@flydocs/cli 0.6.0-alpha.13 → 0.6.0-alpha.20

package/template/.claude/commands/flydocs-setup.md

@@ -4,7 +4,7 @@ Initial project onboarding — define project context, connect to provider, and
 create an initial backlog. This command handles two scenarios: new projects
 and FlyDocs version updates (including legacy content migration).
 
-Read the active mechanism skill's `SKILL.md` for script calling conventions
+Read the workflow skill's `SKILL.md` for script calling conventions
 before executing any scripts.
 
 Triggers: "setup flydocs", "onboard project", "flydocs init"
@@ -48,7 +48,7 @@ Example:
 
 ```
 Detected: New project setup (cloud tier)
-I'll walk you through project definition, Linear setup, and initial backlog.
+I'll walk you through project definition, provider setup, and initial backlog.
 Ready to begin?
 ```
 
@@ -73,13 +73,99 @@ If the directory exists and contains files:
 5. Offer to add relevant rules to `flydocs/context/project.md` (Standards
    section) or note them for the user to review.
 6. Skip rules that conflict with or duplicate FlyDocs workflow rules (e.g.,
-   skill-led reasoning, mechanism scripts, session management).
+   skill-led reasoning, workflow scripts, session management).
 
 This is agent-guided — review and suggest, let the user confirm. No automated
 merging. If no backup directory exists, skip this phase silently.
 
 ---
 
+## Phase 0c: Topology Detection
+
+Detect the project's physical layout. This affects Phase 1.5 (service
+descriptor generation) and cross-repo context assembly.
+
+**Step 1: Check for workspace config files.**
+
+Look for these in the project root (in order):
+
+- `pnpm-workspace.yaml` → Type 3 (monorepo multi-service)
+- `nx.json` → Type 3
+- `turbo.json` → Type 3
+- `lerna.json` → Type 3
+- `Cargo.toml` with `[workspace]` section → Type 3
+- `go.work` → Type 3
+
+If any found → **Type 3: Monorepo, multi-service**. Record which config file
+was detected.
+
+**Step 2: Check parent directory for sibling repos.**
+
+If no workspace config found, check one directory up from the project root:
+
+- List subdirectories of the parent directory
+- Check which ones contain a `.git` directory
+- If 2+ sibling directories (including this one) have `.git` → **Type 4: Sibling repos**
+- Record the sibling repo directory names
+
+**Step 3: Determine single-app vs monorepo-single.**
+
+If neither workspace config nor sibling repos detected:
+
+- Check if the project has multiple `package.json` files in subdirectories
+  (e.g., `apps/*/package.json`, `packages/*/package.json`)
+- If yes → **Type 2: Monorepo, single app** (monorepo tooling without workspace config)
+- If no → **Type 1: Single repo, single app**
+
+**Step 4: Report and store.**
+
+Tell the user what was detected:
+
+```
+Topology: Monorepo multi-service (Type 3)
+Detected via: pnpm-workspace.yaml
+```
+
+Update `.flydocs/config.json` with the `topology` field:
+
+```json
+{
+  "topology": {
+    "type": 3,
+    "label": "monorepo-multi",
+    "detectedVia": "pnpm-workspace.yaml"
+  }
+}
+```
+
+For Type 4 (sibling repos), also include:
+
+```json
+{
+  "topology": {
+    "type": 4,
+    "label": "sibling-repos",
+    "detectedVia": "parent directory scan",
+    "siblingRepos": ["flydocs-core", "flydocs-app", "flydocs-marketing"]
+  }
+}
+```
+
+For Type 3 with a workspace root different from project root:
+
+```json
+{
+  "topology": {
+    "type": 3,
+    "label": "monorepo-multi",
+    "detectedVia": "turbo.json",
+    "workspaceRoot": "."
+  }
+}
+```
+
+---
+
 ## Phase 1: Project Definition
 
 The goal is to fill every section of `flydocs/context/project.md` with real
@@ -283,6 +369,114 @@ may be useful:
 
 ---
 
+## Phase 1.5: Service Descriptor Generation
+
+Generate `flydocs/context/service.json` — the dual-purpose descriptor that
+provides cross-repo context AND intra-repo orientation. This phase uses the
+topology detected in Phase 0c and stack detected in Phase 1.
+
+Read `.claude/skills/flydocs-context-graph/service-descriptor-schema.md` for
+the full schema reference before proceeding.
+
+**Step 1: Scan for cross-repo export surface.**
+
+Identify what this repo exposes to the outside world:
+
+- **REST/GraphQL APIs** — scan for route definitions, API directories, endpoint
+  patterns. Look in common locations: `src/app/api/`, `src/routes/`,
+  `pages/api/`, `server/routes/`, `api/`.
+- **Published packages** — check `package.json` for `name` field if it looks
+  like a library (`@scope/package` or explicitly `"private": false`).
+- **Events/messages** — check for pub/sub, message queue, or webhook patterns.
+- **gRPC** — check for `.proto` files.
+
+For each API surface found, capture: type, path, description, and methods
+(for REST).
+
+**Step 2: Scan for dependencies on other services.**
+
+Identify what this repo consumes from external services:
+
+- Check environment variables (`.env.example`, `.env.local`) for service URLs,
+  API keys, or connection strings that reference other internal services.
+- Check `package.json` for internal package references (`workspace:*`).
+- Check import patterns for cross-service API clients.
+- Check config files for external service endpoints.
+
+For each dependency, capture: service name, interface type, and description.
+
+**Step 3: Scan for intra-repo structure.**
+
+Help the agent orient within THIS repo:
+
+- **Entry points** — where does request handling or app logic start?
+  - Web frameworks: `src/app/`, `pages/`, `src/routes/`
+  - CLI tools: `src/cli.ts`, `src/index.ts`, `src/main.ts`
+  - Workers: `src/worker/`, `src/jobs/`
+- **Shared types** — where do type definitions live?
+  - `src/types/`, `src/lib/types.ts`, `types/`, `packages/shared/`
+- **Build system** — what builds the project?
+  - Read from `package.json` scripts, config files: turbo, nx, next, vite,
+    tsup, webpack, cargo, go
+- **Packages** (monorepo Type 3 only) — scan workspace packages:
+  - Read `pnpm-workspace.yaml`, `turbo.json`, or `nx.json` for package list
+  - For each package: name, path, one-line purpose
+
+**Step 4: Compose and confirm the descriptor.**
+
+Build the `service.json` from scan results. Show the user the complete
+descriptor and ask for confirmation or corrections:
+
+```
+Service Descriptor for [repo name]:
+
+Purpose: [one-sentence description]
+Stack: [technology list]
+
+APIs exposed:
+  - REST /api/relay/* — Relay API for CLI operations
+  - package @flydocs/cli — npm CLI binary
+
+Dependencies:
+  - plastrlab/flydocs-app (REST /api/relay/*) — cloud tier operations
+
+Structure:
+  - Entry: src/cli.ts
+  - Types: src/lib/types.ts
+  - Build: tsup
+
+Write to flydocs/context/service.json?
+```
+
+**Step 5: Write the descriptor.**
+
+After user approval, write `flydocs/context/service.json` with the confirmed
+content. Use the schema version `1`.
+
+**Step 6: Push to relay (cloud tier only).**
+
+For cloud tier projects, push the descriptor to the relay:
+
+```bash
+python3 .claude/skills/flydocs-context-graph/scripts/push_service.py
+```
+
+This calls `PUT /api/relay/workspace/service` with the descriptor content
+(excluding the `structure` section which is local-only).
+
+**Step 7: Pull workspace composite (cloud tier only).**
+
+After pushing, pull the workspace composite to see sibling descriptors:
+
+```bash
+python3 .claude/skills/flydocs-context-graph/scripts/pull_services.py
+```
+
+This calls `GET /api/relay/workspace/services` and caches the result for
+graph building and prompt hook orientation.
+
+---
+
 ## Phase 2: Provider Setup — Cloud Only
 
 > **Local tier:** Skip this phase entirely. Print: "Local tier — no provider
@@ -306,7 +500,7 @@ Do not proceed until the key is available.
 Query connected providers:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_providers.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py list-integrations
 ```
 
 This returns `[{type, name, connected}]`. Handle based on results:
@@ -320,7 +514,7 @@ This returns `[{type, name, connected}]`. Handle based on results:
 After selection, store the preference:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_provider.py <provider_type>
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-provider <provider_type>
 ```
 
 This stores the provider type on the relay (for routing) and updates
@@ -334,7 +528,7 @@ This stores the provider type on the relay (for routing) and updates
 If `provider.teamId` in config is null, discover available teams:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_teams.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py teams
 ```
 
 Present the teams to the user as a numbered list showing name and key.
@@ -351,7 +545,7 @@ If the user selects **"Create a new team/project"**:
 3. Create via:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/create_team.py --name "Team Name" [--key KEY] [--parent <parent_team_id>]
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-team --name "Team Name" [--key KEY] [--parent <parent_team_id>]
 ```
 
 > The `--parent` flag is Linear-only (sub-teams). Omit for Jira.
@@ -360,7 +554,7 @@ After selection or creation, store the preference on the relay and in local
 config:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_team.py <team_id>
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-team <team_id>
 ```
 
 This stores the team preference server-side (the relay uses it for all
@@ -375,22 +569,35 @@ For Jira, this sets the active Jira project.
 Query existing projects:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_projects.py
+python3 .claude/skills/flydocs-workflow/scripts/projects.py list-projects
 ```
 
 If matching projects exist, let the user select one. Otherwise, offer to
 create a new project:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/create_project.py --name "Project Name"
+python3 .claude/skills/flydocs-workflow/scripts/projects.py create-project --name "Project Name"
+```
+
+**Step 4b: Set active project.**
+
+After selecting or creating a project, store it as the active project:
+
+```bash
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-active-project <project_id>
 ```
 
+This writes `workspace.activeProjects` in `.flydocs/config.json`. All
+subsequent operations (issue listing, captures, milestones, project updates)
+use this to scope work to the active project. This is a critical step —
+without it, product scope filtering and project-update targeting won't work.
+
 **Step 5: Configure labels.**
 
 Fetch available labels from the provider:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_labels.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py labels
 ```
 
 **Auto-detect type mapping:** Scan the returned labels for common names
@@ -412,7 +619,7 @@ available labels as options.
 Store the configuration on the relay:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_labels.py \
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-labels \
   --defaults '["app"]' \
   --type-map '{"feature":["Feature"],"bug":["Bug"],"chore":["Chore"],"idea":["Improvement"]}'
 ```
@@ -425,7 +632,7 @@ user to correct them.
 Map provider workflow states to FlyDocs statuses. Run auto-mapping first:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py --auto
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-status-mapping --auto
 ```
 
 The relay auto-maps by case-insensitive name matching (e.g., "In Progress"
@@ -452,13 +659,13 @@ If the user wants to fix unmapped statuses, fetch available provider states
 and let them map manually:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_statuses.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py statuses
 ```
 
 Then store the corrected mapping:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/set_status_mapping.py \
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py set-status-mapping \
   --mapping '{"BACKLOG":"Backlog","IMPLEMENTING":"In Progress","BLOCKED":"On Hold",...}'
 ```
 
@@ -476,7 +683,7 @@ The setup scripts in Steps 2-7 all POST to the relay — they no longer write
 to local config. After all setup steps complete, pull the canonical config:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/generate_config.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py config
 ```
 
 This calls `GET /config/generate` which returns all server-owned fields
@@ -494,7 +701,7 @@ but don't block — they can fix in the dashboard and re-run later.
 **Step 9: Fetch user identity.**
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/get_me.py
+python3 .claude/skills/flydocs-workflow/scripts/workspace.py get-me
 ```
 
 This calls `GET /auth/me` (no workspace required) and writes
@@ -514,7 +721,7 @@ This enables `--mine` filters and personalizes session output.
 **Step 1: Check existing milestones.**
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_milestones.py
+python3 .claude/skills/flydocs-workflow/scripts/projects.py list-milestones
 ```
 
 **Step 2: If milestones exist** — show them and confirm they'll be used for
@@ -540,7 +747,7 @@ Let the user customize names, descriptions, and target dates.
 For each approved milestone, pass the project ID from Phase 2 Step 3:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/create_milestone.py \
+python3 .claude/skills/flydocs-workflow/scripts/projects.py create-milestone \
   --name "Phase 1: Foundation" --project <project_id> --target-date YYYY-MM-DD
 ```
 
@@ -569,11 +776,11 @@ For each work item, follow the capture procedure from
 `.claude/skills/flydocs-workflow/stages/capture.md`:
 
 - Determine type (feature, bug, chore, idea)
-- Create via the mechanism script (cloud: pass `--project` from Phase 2 for
+- Create via the workflow script (cloud: pass `--project` from Phase 2 for
   Linear; omit `--project` for Jira — issues are scoped to the team/project
   selected in Phase 2 Step 3):
   ```bash
-  python3 .claude/skills/flydocs-{tier}/scripts/create_issue.py \
+  python3 .claude/skills/flydocs-workflow/scripts/issues.py create \
     --title "Issue title" --type feature --priority 3 --estimate 2 \
     --project <project_id>
   ```
@@ -587,7 +794,7 @@ For each work item, follow the capture procedure from
 After creating issues, assign them to milestones:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/assign_milestone.py \
+python3 .claude/skills/flydocs-workflow/scripts/projects.py assign-milestone \
   <issue-ref> <milestone-id>
 ```
 
@@ -599,7 +806,7 @@ based on the issue content.
 **Step 1: Check if backlog is populated.**
 
 ```bash
-python3 .claude/skills/flydocs-{tier}/scripts/list_issues.py --limit 10
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list --limit 10
 ```
 
 If issues exist, skip this phase:
@@ -625,7 +832,7 @@ Only if the user wants to add more.
 List all issues in Backlog status:
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/list_issues.py --status BACKLOG
+python3 .claude/skills/flydocs-workflow/scripts/issues.py list --status BACKLOG
 ```
 
 **Step 2: Set priorities.**
@@ -638,10 +845,10 @@ For each issue, suggest a priority and let the user confirm or adjust:
 - **4 (Low)** — Nice to have, no urgency
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/priority.py <issue-ref> <0-4>
+python3 .claude/skills/flydocs-workflow/scripts/issues.py priority <issue-ref> <0-4>
 ```
 
-Note: Linear uses 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low.
+Note: Priority scale is 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low.
 
 **Step 3: Set estimates.**
 
@@ -654,13 +861,13 @@ For each issue, suggest a t-shirt size estimate:
 - **5** — XL (1+ week, consider breaking down)
 
 ```bash
-python3 .claude/skills/flydocs-cloud/scripts/estimate.py <issue-ref> <1-5>
+python3 .claude/skills/flydocs-workflow/scripts/issues.py estimate <issue-ref> <1-5>
 ```
 
 **Step 4: Identify dependencies.**
 
 Ask about blocking relationships between issues. If any exist, note them
-(Linear handles dependency tracking natively).
+(most providers handle dependency tracking natively).
 
 **Step 5: Recommend implementation order.**
 
@@ -678,7 +885,7 @@ Recommended implementation order:
 
 ## Phase 6: Completion & Onboarding
 
-Summarize what was accomplished and provide a guided onboarding experience.
+Summarize what was accomplished and guide the developer to onboarding.
 
 ### Step 1: Completion summary
 
@@ -690,7 +897,7 @@ Tier: [local / cloud]
 
 ✓ Project context: flydocs/context/project.md
 ✓ Stack detected: [framework list]
-✓ Provider: [Linear connected / Local file-based]      (if applicable)
+✓ Provider: [Connected / Local file-based]              (if applicable)
 ✓ Milestones: [N created]                               (cloud only)
 ✓ Backlog: [N issues captured]
 ✓ Priorities set                                         (cloud only)
@@ -699,9 +906,9 @@ Tier: [local / cloud]
 **Mark setup as complete.**
 
 For **cloud tier**: Setup completion is determined by the relay. The
-`generate_config.py` call in Phase 2 Step 8 already sets `setupComplete`
+`workspace.py config` call in Phase 2 Step 8 already sets `setupComplete`
 based on the relay's validation result. If the relay returns `valid: true`,
-config will have `setupComplete: true`. If not, run `validate_setup.py` to
+config will have `setupComplete: true`. If not, run `workspace.py validate` to
 check what's still missing.
 
 For **local tier**: Update `.flydocs/config.json` to set `setupComplete` to
@@ -711,27 +918,23 @@ For **local tier**: Update `.flydocs/config.json` to set `setupComplete` to
 { "setupComplete": true }
 ```
 
-### Step 2: Quick-start guide
+### Step 2: Direct to /onboard
 
-Present the core workflow commands with brief descriptions:
+Check `.flydocs/config.json` for the `onboardComplete` field. If it is not
+`true`, direct the developer to run `/onboard` for full project orientation:
 
 ```
-Here's how to work with FlyDocs:
+Setup is done! Next step:
 
-Getting started:
-  /start-session        Begin a work session (sets focus, loads context)
-  /activate             Pick your next issue to work on
-  /capture              Capture a new issue or idea anytime
+  Run /onboard to get oriented to the codebase, active work, and available
+  commands. This is especially helpful for new team members joining the project.
+```
 
-During development:
-  /implement            Start implementation on your active issue
-  /status               Check current session and issue status
-  /block                Flag a blocker on the current issue
+If `onboardComplete` is already `true` (developer has onboarded before),
+skip the nudge and go straight to the quick-start reminder:
 
-Wrapping up:
-  /review               Submit work for code review
-  /validate             Run QE validation on completed work
-  /wrap-session         End your session (posts summary, saves progress)
+```
+Setup refreshed. Run /start-session to begin working.
 ```
 
 ### Step 3: Tier-specific notes
@@ -739,7 +942,7 @@ Wrapping up:
 **For cloud tier:**
 
 - Provider project URL (if available from create_project response)
-- For Linear: recommend reviewing milestones in Linear's UI for timeline view
+- Recommend reviewing milestones in your provider's UI for timeline view
 
 **For local tier:**
 
@@ -793,7 +996,7 @@ Docs and updates: https://www.flydocs.ai
 
 Throughout the setup flow:
 
-- **Script failures** — If any mechanism script returns exit code 1, show the
+- **Script failures** — If any workflow script returns exit code 1, show the
   error message from stderr and ask the user how to proceed. Do not retry
   silently.
 - **Missing API key** — For cloud tier, cannot proceed past Phase 2 without
@@ -808,18 +1011,18 @@ Throughout the setup flow:
 
 ## Key Rules
 
-1. **Always read the mechanism skill's `SKILL.md`** before running any script.
-   Script calling conventions may differ between tiers.
+1. **Always read the workflow skill's `SKILL.md`** before running any script.
+   Script calling conventions are documented there.
 2. **All script paths** follow the pattern:
-   `python3 .claude/skills/flydocs-{tier}/scripts/<script>.py`
-   where `{tier}` is read from `.flydocs/config.json`.
+   `python3 .claude/skills/flydocs-workflow/scripts/<dispatcher>.py <subcommand>`
+   The unified client auto-detects tier from `.flydocs/config.json`.
 3. **Never skip user confirmation** on project.md content. This is their
    project definition — they must approve it.
-4. **Never hardcode tier** — always read from config. A project can switch
-   tiers via `flydocs --tier <tier>`.
-5. **Cloud scripts only for cloud tier.** Extended scripts (estimate, priority,
-   milestones, projects) only exist in `flydocs-cloud`. Do not attempt to call
-   them for local tier.
+4. **Never hardcode tier** — the dispatcher scripts auto-detect tier from
+   config. A project can switch tiers via `flydocs --tier <tier>`.
+5. **Cloud-only operations.** Extended operations (estimate, priority,
+   milestones, projects) are cloud-only. The dispatchers will error if called
+   on local tier for unsupported operations.
 6. **Capture procedure** — when creating issues during Phase 4, follow the
    full capture procedure from `.claude/skills/flydocs-workflow/stages/capture.md`.