# Onboard (All Agents) One-time orientation to the codebase, workspace, and FlyDocs workflow. Distinct from `/start-session` (daily standup). Run once per project, or re-run after major structural changes. Triggers: "onboard", "get oriented", "new here", "walk me through this project", "set up", "setup" --- ## Step 0: Setup-completion gate (FLY-815) Before orientation, decide whether the project still needs first-time setup. Use `flydocs/context/project.md` content as the authoritative signal — `.flydocs/config.json`'s `setupComplete` is treated as additive metadata only, so existing cloud users whose portal flow never wrote that flag don't get re-routed. - `flydocs/context/project.md` exists AND does NOT contain the placeholder marker `` placeholders with real content for What This Is, Stack, Standards, and Active Priorities. Keep the existing section headers — only replace placeholder bodies. 4. **Generate `flydocs/context/service.json`.** Write a service descriptor (name, purpose, stack, dependencies). For a single repo, one descriptor; for multi-repo, one per child repo. 5. **Optionally seed initial backlog.** Ask the user if they have 3-5 things they want to capture as issues; if yes, run `/capture` for each. Skippable. 6. **Mark setup complete.** Update `.flydocs/config.json` to set `setupComplete: true` (and `onboardComplete: true` once orientation below also runs). In multi-repo, also set `setupComplete: true` in the workspace-root config and the active child repo's config. After step 6, **continue into Step 1** below for orientation. ### Cloud tier — redirect to portal Setup for cloud-tier projects happens in the FlyDocs web portal. Print: ``` Setup happens in the FlyDocs portal. Open https://app.flydocs.ai/[workspaceSlug]/get-started to complete it, then come back here and run /onboard again. ``` Replace `[workspaceSlug]` with the workspace slug from `.flydocs/config.json`'s `workspaceName` (slugified) or the `workspace.slug` field if present. Stop here — do NOT continue to Step 1. After the user finishes the portal Get Started flow and runs `flydocs update`, `project.md` will be populated server-side; their next `/onboard` run will skip this gate and go straight to orientation. --- ## Step 1: Gather Context (one call) Call `session_start`, or run the operation, to gather workspace state deterministically: ```bash flydocs run session.start-context ``` This returns structured JSON with identity, workspace config, active board/project state, last session, and multi-repo info. Use this data for all subsequent steps. **Do NOT read config.json, me.json, or validation-cache.json manually.** Additionally, read project context files for the ecosystem overview (these are content files the script doesn't include): - `flydocs/context/project.md` for each repo (or the current repo) - `.flydocs-workspace.json` for multi-repo purpose/stack/dependencies --- ## Step 2: Welcome Use `identity.name` from the start-context result. This heading is the opening — nothing before it. ``` # Welcome, [First Name]! Let me get you oriented. ``` If `identity.name` is null: `# Welcome!` --- ## Step 3: Your Setup User-friendly workspace context from the start-context result. Never expose config field names or IDs. ``` ## Your Setup **Workspace:** [workspace.name] **Provider:** [Linear/Jira — from provider field or validation-cache] **Tier:** [workspace.tier] ``` **Multi-repo** (when `isMultiRepo` is true): Add: ``` **Structure:** Multi-repo workspace **Repos:** [repos[0].name], [repos[1].name], [repos[2].name] ``` **Single repo:** Omit structure line or show "Single repository". --- ## Step 4: Project Context This is onboard's unique value — the project tour that start-session skips. **Multi-repo:** Use `repos` from start-context for names and purposes. Read `.flydocs-workspace.json` for enriched per-repo stack and dependencies. Read each repo's `flydocs/context/project.md` for detailed context. ``` ## The [Product Name] Ecosystem This workspace contains [N] repos: | Repo | Purpose | Stack | | ---- | ------- | ----- | | [repo] | [purpose from repos or workspace json] | [stack] | [Describe key cross-repo dependencies naturally in 1-2 sentences] ``` Summarize standards and key decisions that span the workspace. **Single repo:** Read `flydocs/context/project.md` and present: ``` ## Project: [Name] [One-line description] **Stack:** [languages, frameworks, tools] ``` **Placeholder project.md:** Offer to help fill it in. Wait for response. --- ## Step 5: Setup Validation (fix interactively if needed) Check `hasActiveProject` from the start-context result. **If `false`:** Guide the user interactively. Do NOT present a config status table or mention field names. ``` ## Getting Connected I don't see an active project selected yet. Let me help set one up: ``` List projects: `flydocs run project.list` Set it: `flydocs run workspace.set-active-project ` For Jira with boards: `flydocs run workspace.list-boards` Do NOT tell the user to edit config.json. **If `true`:** Skip this section entirely. --- ## Step 6: Commands Reference ``` ## FlyDocs Commands **Getting started:** /start-session — Daily standup: see your board and pick up work /activate — Pick your next issue /capture — Log a new issue or idea **During development:** /implement — Start implementation on active issue /status — Check current session and issue status /block — Flag a blocker /attach — Attach to an existing issue **Completing work:** /review — Submit for code review /validate — Run QE validation /close — Close a completed issue /wrap-session — End session and save progress **Project management:** /refine — Triage and refine backlog items /project-update — Post a project status update /knowledge — Capture a decision or knowledge doc **System:** /flydocs-update — Update FlyDocs to latest version /onboard — Re-run this orientation ``` --- ## Step 7: Next Steps Always end with an actionable push. Tailor based on what was found. **Everything set up:** ``` ## Next Steps You're oriented. Run `/start-session` to see your board and start working. ``` **If project.md needs filling (user deferred):** ``` ## Next Steps Run `/start-session` to start working. You can fill in project context later with `/onboard`. ``` **If no active project (user deferred):** ``` ## Next Steps Run `/start-session` — it will help you pick an active project if one isn't set yet. ``` --- ## Step 8: Set Onboard Complete Update `.flydocs/config.json` to set `onboardComplete: true`. This prevents the start-session onboard gate from re-triggering. At workspace root in multi-repo setups, also set `onboardComplete: true` in the workspace-root config (if it exists) AND the active child repo's config. --- ## Key Rules 1. **Orientation, not a dashboard.** Show project context and commands. Do NOT fetch issues or show a sprint/board dashboard — that's start-session's job. 2. **Use start-context for data.** Don't read config files manually. 3. **Conversational, not diagnostic.** Guide — don't report config status. 4. **Never expose config field names.** No `activeProjectId`, `issueLabels`, `repoDefaults`, `topology` in user-facing output. 5. **Fix gaps interactively.** Don't tell users to edit JSON. 6. **Keep it concise.** Summaries, not raw file contents. 7. **Gracefully handle missing data.** Note naturally and move on. $ARGUMENTS