@dv.nghiem/flowdeck 0.3.9 → 0.4.0

package/docs/commands/fd-map-codebase.md

@@ -1,27 +1,91 @@
----
-description: Map the codebase structure into .codebase/ files for AI context
-argument-hint: "[--full] [--update]"
----
+# /fd-map-codebase
 
-Analyze and document the codebase for AI agent context.
+**Purpose:** Analyze and index the codebase into structured `.codebase/` documentation files.
 
-**What this does:**
-1. Scans the project structure (entry points, modules, dependencies)
-2. Identifies key files, patterns, and conventions
-3. Writes structured summaries to `.codebase/`:
-   - `ARCHITECTURE.md` — high-level system design
-   - `CONVENTIONS.md` — naming, style, and patterns used in this project
-   - `DEPENDENCIES.md` — external packages and what they're used for
-   - `INDEX.md` — file-by-file inventory
+## Usage
 
-**Flags:**
-- `--full` — Deep scan (reads every file, slower but thorough)
-- `--update` — Refresh existing `.codebase/` files with recent changes
+/fd-map-codebase [--incremental] [--force]
 
-**Why this matters:** Agents use `.codebase/` for context instead of re-scanning on every task.
+## Arguments
 
-## What Next?
+- `--incremental` — only update files where the underlying source has changed since the last mapping
+- `--force` — skip the existing-index confirmation prompt and rebuild from scratch
 
-1. **Start discussion** → `/fd-discuss`
-2. **Write documentation** → `/fd-write-docs`
-3. **View dashboard** → `/fd-dashboard`
+## What Happens
+
+### Pre-flight
+
+1. Check codegraph installation using `codegraph action=check`.
+2. Log the result: installed and indexed, installed but not indexed, or not installed.
+3. Auto-install codegraph if missing (`codegraph action=install`).
+4. Initialize or refresh the codegraph index (`codegraph action=init` or `codegraph action=refresh`).
+
+### Process
+
+1. Check if `.codebase/` documentation directory already exists. If it does and `--force` is not set, prompt for confirmation before overwriting.
+2. Initialize 6 isolated worktrees for parallel mapper agents:
+   - `flowdeck-mapper-stack`
+   - `flowdeck-mapper-arch`
+   - `flowdeck-mapper-structure`
+   - `flowdeck-mapper-conventions`
+   - `flowdeck-mapper-testing`
+   - `flowdeck-mapper-concerns`
+3. Spawn 6 `@mapper` agents in parallel, each producing one documentation file:
+   - `@mapper` → `.codebase/STACK.md` — tech stack, dependencies, versions
+   - `@mapper` → `.codebase/ARCHITECTURE.md` — system design, components, data flow
+   - `@mapper` → `.codebase/STRUCTURE.md` — file organization, directory layout
+   - `@mapper` → `.codebase/CONVENTIONS.md` — coding standards, naming, patterns
+   - `@mapper` → `.codebase/TESTING.md` — test strategy, coverage, frameworks
+   - `@mapper` → `.codebase/CONCERNS.md` — known issues, technical debt, risks
+
+Each mapper uses codegraph MCP tools for symbol-level analysis, falling back to direct file reads when codegraph does not cover a specific detail.
+
+### Cleanup
+
+Remove all worktrees regardless of outcome after agents complete.
+
+### Verify
+
+Check that all 6 doc files exist and contain non-empty content.
+
+### Finalize
+
+1. Write timestamp to `.codebase/last_mapped`.
+2. Update codegraph state with `codegraph action=status`.
+
+## Output / State
+
+Files created in `.codebase/`:
+- `STACK.md` — technology stack and dependencies
+- `ARCHITECTURE.md` — system architecture and component relationships
+- `STRUCTURE.md` — directory layout and file organization
+- `CONVENTIONS.md` — coding standards and patterns
+- `TESTING.md` — test coverage and frameworks
+- `CONCERNS.md` — technical debt and known risks
+- `last_mapped` — timestamp file
+- `CODEGRAPH.md` — codegraph index status
+
+Report includes: codegraph install/index status, files created per mapper, key findings per category.
+
+## Examples
+
+**Full codebase mapping:**
+```
+/fd-map-codebase
+```
+
+**Incremental update (only changed files):**
+```
+/fd-map-codebase --incremental
+```
+
+**Force rebuild (skip confirmation):**
+```
+/fd-map-codebase --force
+```
+
+## Related Commands
+
+- `/fd-doctor` — check environment health including codegraph status
+- `/fd-discuss` — uses codegraph for code intelligence during discussions
+- `/fd-plan` — uses codegraph for impact analysis during planning

package/docs/commands/fd-multi-repo.md

@@ -1,63 +1,178 @@
----
-description: Initialize or manage multi-repo configuration for microservice architecture. Adds, lists, checks status of, or removes repos from .planning/config.json.
-argument-hint: "[--add <path> <role> | --list | --status | --remove <name>]"
----
+# /fd-multi-repo
 
-Manage the multi-repo registry in `.planning/config.json`.
+**Purpose:** Multi-repo orchestration for coordinated changes across a microservice architecture.
 
-**With no arguments:** show the current list of registered repos from `sub_repos`.
+## Usage
 
-**Arguments:**
+/fd-multi-repo [list | add <path> [name] | remove <name> | status]
 
-`--add <path> <role>` — Register a new repo. `path` is relative to the root repo's parent directory. `role` must be one of: `upstream-api`, `downstream-consumer`, `shared-lib`, `gateway`, `worker`. Prompts for `name`, `tech_stack`, and `owner_team` if not inferred.
+## Arguments
 
-`--list` — Print all registered repos as a table: name, path, role, tech_stack, owner_team.
+- `list` — display all registered repositories
+- `add <path> [name]` — add a repository to the registry
+- `remove <name>` — remove a repository from the registry
+- `status` — show status of all registered repositories
 
-`--status` — For each registered repo, check if the path resolves on disk, report the current git branch, and show whether a `.planning/` directory exists in that repo.
+## What Happens
 
-`--remove <name>` — Remove a repo from the registry by name. Does not delete the repo on disk.
+### List (or no arguments)
 
-**What this does:**
+Read `.planning/config.json` → `repos` array. Display:
+```
+════════════════════════════════════
+MULTI-REPO REGISTRY
+════════════════════════════════════
+  user-service     ../user-service     upstream-api         node+typescript
+  order-service    ../order-service    downstream-consumer  node+typescript
+  shared-types     ../shared-types     shared-lib           node+typescript
+  api-gateway      ../api-gateway      gateway              nginx+lua
+
+Path check: all 4 repos resolved ✅
+```
+
+### Add (`add <path> [name]`)
+
+1. Verify `<path>` exists and has a `.planning/STATE.md`
+2. Derive `name` from directory basename if not provided
+3. Add to `.planning/config.json` → `repos` array
+4. Report: "Added '<name>' at <path>."
+
+### Remove (`remove <name>`)
+
+Remove matching repo from registry. Report: "Removed '<name>'."
+
+### Status (`status`)
+
+For each registered repo, read its STATE.md and display:
+```
+════════════════════════════════════
+WORKSPACE STATUS
+════════════════════════════════════
+  frontend  — Phase 2 | in_progress | Updated: <time>
+  backend   — Phase 3 | completed   | Updated: <time>
+  shared    — Phase 1 | planned     | Updated: <time>
+════════════════════════════════════
+Overall: 1 in progress, 1 complete, 1 planned
+```
+
+### Execution Flow (for coordinated feature/fix)
+
+**Step 1: Analyze Repos**
+
+`@multi-repo-coordinator` reads `.planning/config.json` and produces a registry summary. If any path fails to resolve, the flow stops here with a clear error.
+
+**Step 2: Identify Dependencies**
+
+`@multi-repo-coordinator` and `@architect` work together to:
+1. Build the dependency graph from service roles and actual API references
+2. Classify the change as breaking or non-breaking for each affected service
+3. Produce the ordered change list
+
+If circular dependency is detected, the flow stops and reports the cycle.
+
+**Step 3: Plan Changes**
+
+`@architect` produces the cross-repo CHANGE PLAN using contract-first development:
+1. Write the new API contract or type definition before any implementation starts
+2. Confirm the contract covers all required changes without scope creep
+3. Produce a per-repo task list ordered by the dependency graph
+
+**Step 4: Execute Per Repo**
+
+Changes execute in dependency order. For each repo:
+1. Implementation agent implements the changes
+2. `@tester` writes and runs tests for that repo's changes
+3. No downstream repo starts until upstream repo's changes pass tests
+
+For non-breaking changes, implementation and testing run in parallel. For breaking changes, `@tester` must verify upstream before downstream implementation starts.
+
+If a repo fails, that repo and all downstream repos are paused. Upstream repos that completed are not rolled back.
 
-1. Reads `.planning/config.json`; creates the file with an empty `sub_repos: []` array if it does not exist
-2. For `--add`: resolves the path, infers `name` from the directory name if not provided, writes the new entry to `sub_repos`
-3. For `--list`: formats the `sub_repos` array as a readable table
-4. For `--status`: walks each entry, checks `path` existence, runs `git -C <resolved_path> branch --show-current`
-5. For `--remove`: removes the matching entry by `name`, writes back to config.json
+**Step 5: Verify Integration**
 
-**Example output (no args):**
+After all per-repo changes complete, `@tester` and `@reviewer` run cross-repo verification:
+- `@tester` (integration): runs end-to-end integration tests covering the full change path
+- `@reviewer` (cross-repo): reviews all changed files across all repos for contract adherence
 
+Both run in parallel. Integration test failures block the production rollout.
+
+**Rollout After Integration Pass**
+
+Once integration is verified in staging, deploy in dependency order:
+```
+1. shared-types  →  publish to package registry (semver minor)
+2. user-service  →  canary (5% traffic, 15 min) → stage ✅ → prod
+3. order-service →  canary (after user-service prod) → stage ✅ → prod
+4. api-gateway   →  canary (after order-service prod) → stage ✅ → prod
+```
+
+## Conflict Handling
+
+If a conflict is detected during Step 2 or Step 3, the flow pauses:
 ```
-Multi-Repo Registry (.planning/config.json)
+FLOW PAUSED — Conflict Requires Resolution
+
+  Service A (user-service): removing `legacyUserId` from response
+  Service B (order-service PR #47): new consumer of `legacyUserId`
+  Classification: Breaking API collision
+
+  Resolution options:
+    A. Versioned endpoint: keep /v1/users (with legacyUserId) + add /v2/users (without)
+    B. Coordinate: block order-service PR #47 until user-service migration is complete
+    C. Reverse: defer the user-service removal until order-service removes its dependency
+
+  Owner teams: platform (user-service), commerce (order-service)
+  Decision required before this flow can continue.
+```
+
+The flow does not auto-resolve conflicts. It surfaces them clearly, names the options, and waits for human direction.
 
-  Name                 Path                   Role                  Stack             Team
-  ───────────────────  ─────────────────────  ────────────────────  ────────────────  ────────
-  user-service         ../user-service        upstream-api          node+typescript   platform
-  order-service        ../order-service       downstream-consumer   node+typescript   commerce
-  shared-types         ../shared-types        shared-lib            node+typescript   platform
-  api-gateway          ../api-gateway         gateway               nginx+lua         infra
+## Error Handling
 
-4 repos registered. Run /fd-multi-repo --status to check path health.
+| Condition | Action |
+|-----------|--------|
+| Registry path not found on disk | Stop at Step 1; report which path failed |
+| Circular dependency in graph | Stop at Step 2; show the cycle |
+| Contract review rejected | Stop at Step 3; rework contract before proceeding |
+| Repo's tests fail | Pause that repo and all dependents; upstream remains deployed |
+| Integration test fails | Block production rollout; report which test failed |
+| Conflict detected | Pause flow; surface options; wait for human decision |
+
+## Output / State
+
+- `.planning/config.json` updated with repo registry
+- Per-repo state tracked across phases
+- Cross-repo integration verified
+
+## Examples
+
+**List all registered repos:**
+```
+/fd-multi-repo list
 ```
 
-**Example output (--status):**
+**Add a repo:**
+```
+/fd-multi-repo add ../user-service
+```
 
+**Add a repo with custom name:**
+```
+/fd-multi-repo add ../order-service order-service
 ```
-Multi-Repo Status
 
-  Name              Path               Exists   Branch            .planning/
-  ────────────────  ─────────────────  ───────  ────────────────  ──────────
-  user-service      ../user-service    ✅        main              ✅
-  order-service     ../order-service   ✅        feature/checkout  ❌
-  shared-types      ../shared-types    ✅        main              ❌
-  api-gateway       ../api-gateway     ❌        —                 —
+**Remove a repo:**
+```
+/fd-multi-repo remove shared-types
+```
 
-Warning: api-gateway path does not exist on disk.
-Warning: order-service and shared-types have no .planning/ — cross-repo planning context unavailable.
+**Check status across all repos:**
+```
+/fd-multi-repo status
 ```
 
-**What Next?**
+## Related Commands
 
-- `/fd-discuss` — discuss a change that spans multiple repos before planning it
-- `/fd-new-feature` — plan and execute a feature; use with multi-repo context loaded
-- `/fd-dashboard` — view progress across all registered repos
+- `/fd-new-feature` — start a new feature in a single repo
+- `/fd-status` — view current state across repos
+- `/fd-deploy-check` — run pre-deployment checks across all affected repos

package/docs/commands/fd-new-feature.md

@@ -1,25 +1,69 @@
----
-description: Execute feature implementation workflow — orchestrator + role-routed implementation/researcher + reviewer + tester
-argument-hint: "[feature-description]"
----
+# /fd-new-feature
 
-Execute a new feature using FlowDeck's multi-agent workflow.
+**Purpose:** Define a new feature, initialize feature context in the current phase directory, and guide the user through the discuss-plan-execute-verify workflow.
 
-**What this does:**
-1. If a confirmed PLAN.md exists: delegates each step to `@backend-coder`, `@frontend-coder`, or `@devops` based on scope
-2. If no plan: first runs discuss → plan → confirm, then executes
-3. Runs `@researcher` in parallel for any external APIs or docs needed
-4. Runs `@reviewer` after each significant step to catch issues early
-5. Runs `@tester` to write and run tests for implemented code
-6. Updates STATE.md after each step
+## Usage
 
-**Phase gate:** Requires `plan_confirmed = true` in STATE.md before execution begins.
+/fd-new-feature [feature name or description]
 
-**Parallel execution:** Independent steps are delegated simultaneously to maximize speed.
+## What Happens
 
-## What Next?
+1. **Pre-flight checks.**
+   - Verify `.planning/` exists (error if not found)
+   - Read `STATE.md` to determine current phase number N
 
-1. **Review the code** → `/fd-verify`
-2. **Write documentation** → `/fd-write-docs`
-3. **Deploy check** → `/fd-deploy-check`
-4. **Start next feature** → `/fd-new-feature [description]`
+2. **Capture feature description.**
+   - If no arguments provided, ask the user to describe the feature
+   - Use the provided description as the feature name/summary
+
+3. **Initialize feature context.**
+   - Create `.planning/phases/phase-<N>/FEATURE.md` with phase, timestamp, status (defined), description, and placeholder fields for acceptance criteria and out-of-scope
+
+4. **Update STATE.md.**
+   - Set `feature` to the feature name
+   - Set `status` to `defined`
+   - Set `last_action` to record the feature initialization
+
+5. **Present next steps.** Report the created file and the ordered workflow:
+
+```
+Next steps (in order):
+  1. /fd-discuss          — capture requirements, scope, and acceptance criteria
+  2. /fd-plan             — create implementation plan from discussion decisions
+  3. /fd-execute          — run TDD pipeline to implement the plan
+  4. /fd-verify           — run full test + review + deploy-check pipeline
+```
+
+## Output / State
+
+File created:
+- `.planning/phases/phase-<N>/FEATURE.md`
+
+STATE.md updates:
+```yaml
+phase: <N>
+status: defined
+feature: <feature name>
+last_action: "Feature defined: <feature name>"
+```
+
+## Examples
+
+```
+/fd-new-feature user authentication
+```
+
+Initializes a feature "user authentication" in the current phase and creates `FEATURE.md`.
+
+```
+/fd-new-feature
+```
+
+Prompts for a feature description if no arguments are given.
+
+## Related Commands
+
+- `/fd-discuss` — capture requirements and decisions for this feature
+- `/fd-plan` — create implementation plan from discuss decisions
+- `/fd-execute` — run TDD pipeline to implement the feature
+- `/fd-verify` — run full verification after implementation

package/docs/commands/fd-plan.md

@@ -1,33 +1,86 @@
----
-description: Create a detailed implementation plan from requirements — saves PLAN.md, requires confirmation before execution
-argument-hint: "[phase-number]"
----
-
-Create a step-by-step implementation plan for the current (or specified) phase.
-
-**What this does:**
-1. Reads `.planning/phases/phase-N/DISCUSS.md` for locked decisions
-2. Reads `.codebase/ARCHITECTURE.md` for system context (if mapped)
-3. Breaks the feature into ordered, atomic steps
-4. Identifies dependencies between steps
-5. Saves to `.planning/phases/phase-N/PLAN.md`
-6. Asks for your confirmation before marking phase as `execute`-ready
-
-**Plan format:**
+# /fd-plan
+
+**Purpose:** Create a detailed implementation plan from confirmed DISCUSS.md decisions — research-first, saves PLAN.md, updates STATE.md, and requires CONFIRM before saving.
+
+## Usage
+
+/fd-plan [--phase=N] [--yes]
+
+## What Happens
+
+1. **Research gate (before writing any plan).**
+   - CodeGraph intelligence check (`codegraph action=check`)
+   - If indexed and fresh: use `codegraph_context`, `codegraph_explore`, `codegraph_impact`
+   - If unavailable: standard research pass reading STATE.md, DISCUSS.md, ARCHITECTURE.md, CODEBASE_INDEX.md
+   - Reuse persisted research if fresh (within 5 minutes), otherwise run fresh pass and persist results
+   - Invoke configured MCP tools for library/API/external knowledge as needed
+
+2. **Guard check — D-06 compliance.**
+   - Verify DISCUSS.md exists — error if not found
+   - Verify DISCUSS.md is confirmed — error if not yet confirmed
+   - Abort with clear remediation in both cases
+
+3. **Load context.**
+   - Read PROJECT.md, STATE.md, and the current phase's DISCUSS.md
+
+4. **Draft plan.**
+   - Tasks trace to D-XX decisions from DISCUSS.md
+   - Each task includes `<action>` referencing relevant D-XX decisions
+   - Wave assignments for parallel execution
+   - File dependencies between tasks
+
+5. **Validate plan.**
+   - All requirements from ROADMAP.md for the current phase addressed
+   - All D-XX decisions from DISCUSS.md traced in tasks
+   - No tasks contradict prior decisions
+   - Return to Step 4 to revise if validation fails
+
+6. **Review plan.** Present draft to user showing tasks, D-XX traces, wave structure, and file dependencies.
+
+7. **PAUSE for CONFIRM.**
+   - Present: "Ready to save PLAN.md? Type CONFIRM to save, or describe changes needed."
+   - If user types CONFIRM → proceed to Step 8
+   - If user requests changes → return to Step 4 with feedback
+
+8. **Save PLAN.md** to `.planning/phases/phase-<N>/PLAN.md` and commit with message `docs(phase-N): save confirmed plan`
+
+9. **Update STATE.md.**
+   - Set `plan_file` to the saved path
+   - Set `plan_confirmed: true`
+   - Set `last_action: "Plan confirmed"`
+   - If UI-heavy task: set `requires_design_first: true` and `design_stage: pending`
+   - Suggest `/fd-design --mode=draft` if design-first is required
+
+## Output / State
+
+File created:
+- `.planning/phases/phase-<N>/PLAN.md`
+
+STATE.md updates:
+```yaml
+plan_file: ".planning/phases/phase-<N>/PLAN.md"
+plan_confirmed: true
+last_action: "Plan confirmed"
+requires_design_first: true   # if UI-heavy
+design_stage: pending          # if UI-heavy
 ```
-## Phase N: [Name]
-### Step 1: [Action] — [file path]
-### Step 2: [Action] — [file path]
-...
+
+## Examples
+
+```
+/fd-plan
 ```
 
-**Next step:** Run `/fd-new-feature` to execute the confirmed plan.
+Creates a plan for the current phase using confirmed DISCUSS.md decisions.
+
+```
+/fd-plan --phase=2 --yes
+```
 
-## What Next?
+Creates a plan for phase 2 and skips the confirmation pause.
 
-After plan is confirmed, choose your next step:
+## Related Commands
 
-1. **Start feature implementation** → `/fd-new-feature [description]`
-2. **Revisit discussion** → `/fd-discuss [phase-number]`
-3. **View progress** → `/fd-progress`
-4. **Check dashboard** → `/fd-dashboard`
+- `/fd-discuss` — capture decisions before planning
+- `/fd-execute` — run TDD pipeline to implement the plan
+- `/fd-design` — draft UI designs if the feature is UI-heavy (required before execute if `requires_design_first: true`)