@dv.nghiem/flowdeck 0.3.8 → 0.4.0

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`)

package/docs/commands/fd-quick.md

@@ -1,35 +1,149 @@
----
-description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
-argument-hint: [task description]
----
-
-# Quick Task
-
-Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
-
-## Agent Selection Matrix
-
-| Task Type | Agent |
-|-----------|-------|
-| Backend code | @backend-coder |
-| Frontend code | @frontend-coder |
-| DevOps/infra code | @devops |
-| Explore/understand | @code-explorer |
-| Review code | @reviewer |
-| Security review | @security-auditor |
-| Design/architecture | @architect |
-| Write tests | @tester |
-| Documentation | @doc-updater |
-| Research | @researcher |
-| Debug | @debug-specialist |
-| Performance | @performance-optimizer |
-| Build error | @build-error-resolver |
+# /fd-quick
+
+**Purpose:** Focused autonomous task execution with automatic agent and workflow selection.
+
+## Usage
+
+/fd-quick [task description]
+
+## What Happens
+
+The command explores the codebase first, classifies the task, selects the appropriate workflow, and runs the full stage sequence end-to-end with minimal user input.
+
+### Step 0: Autonomous Preflight Exploration
+
+Before asking anything, invoke `@code-explorer` to inspect:
+1. Repository structure — `.planning/STATE.md`, `.planning/PROJECT.md`, `AGENTS.md`
+2. Available commands — enumerate `src/commands/*.md` filenames
+3. Available agents — enumerate `src/agents/*.ts` filenames
+4. Available skills — enumerate `src/skills/` directory names
+5. Workflow config — read `flowdeck.json` (governance, models)
+6. Tech stack — read `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+7. Implementation patterns — inspect `src/` top-level directories
+8. Prior decisions — check `.planning/phases/*/DISCUSS.md` files
+9. Relevant files — find source files matching keywords in the task description
+
+Store exploration snapshot in STATE.md under `quick_run.preflightExploration`.
+
+### Question Suppression Rule
+
+A question may only be forwarded to `@supervisor` if:
+1. It cannot be answered by the exploration evidence
+2. It has not already been asked in the current session
+3. It is required to safely select the correct workflow
+
+### Step 1: Classify the Task
+
+Use both text-signal matching and preflight exploration evidence via `classifyTaskWithContext()`.
+
+| Task Type | Strong Signal Keywords | Stage Sequence |
+|-----------|------------------------|----------------|
+| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause | `discuss → fix-bug → verify` |
+| **ui-feature** | landing page, dashboard, admin panel, app screen, wireframe, design system, ux flow | `discuss → design → plan → execute → verify` |
+| **docs** | docs, documentation, readme, api docs, usage guide | `discuss → write-docs → verify` |
+| **simple** | rename, move file, typo, update constant, bump version, one-liner | `execute → verify` |
+| **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
+| **ambiguous** | (short, vague, only after exploration cannot resolve) | *(clarify via supervisor)* |
+
+**Bug signals dominate**: if the description contains "fix", "bug", "error", "crash", "exception", "broken", or "regression", classify as `bugfix` even if it also mentions UI elements.
+
+### Step 2: Supervisor-Gated Clarification (only when exploration cannot resolve)
+
+If classification is `ambiguous` AND exploration evidence did not resolve it:
+1. Invoke `@supervisor` with the partial task description and preflight exploration snapshot
+2. `@supervisor` asks ONE clarifying question
+3. Wait for the answer
+4. Re-classify using combined description + answer
+
+### Step 3: Confirm Stage Sequence
+
+Present the classification and planned stage sequence before proceeding:
+```
+Task classified as: <task type>
+Stage sequence:     <stage-1> → <stage-2> → ... → <stage-N>
+Requires design:    <yes / no>
+Requires TDD:       <yes / no>
+Evidence used:      <N> items from preflight exploration
+
+Running /fd-quick autonomously. I will proceed through each stage and pause only
+if I need approval, encounter a blocker, or complete the full sequence.
+```
+
+Proceed automatically — do not wait for additional input unless approval is explicitly required.
+
+### Step 4: Execute Stage Sequence Autonomously
+
+For each stage in sequence:
+
+1. **Announce stage start**
+2. **Supervisor preflight review** — pass `taskDescription`, `currentPhase`, `prerequisitesMet`, `designApprovalPresent`, `regressionTestPresent`
+3. **Handle supervisor decision:**
+   - `approve` — proceed immediately
+   - `revise` — resolve listed required changes then re-run stage
+   - `block` — stop, report why, update `quick_run.outcome = blocked`
+   - `escalate` — pause, present reason to user, request explicit approval
+4. **Execute the stage** using its existing command with full context
+5. **Stage completion check** — invoke `@supervisor` (post-stage) to confirm valid output
+6. **Update STATE.md** with completed stages and supervisor decisions
+7. **Proceed to next stage**
+
+**Stage → Command Mapping:**
+
+| Stage | Command | Key Behavior |
+|-------|---------|--------------|
+| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Questions already answered by evidence are skipped. Saves `DISCUSS.md`. |
+| `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
+| `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
+| `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. |
+| `fix-bug` | `/fd-fix-bug` | TDD bugfix: explore → RED regression test → GREEN fix → REFACTOR → record in FAILURES.json. |
+| `write-docs` | `/fd-write-docs` | Explore APIs → `@writer` drafts → `@reviewer` accuracy check → finalize. |
+| `verify` | `/fd-verify` | Full verification: tests + code review + security scan + deploy check. Reports verdict. |
+
+### Step 5: Completion
+
+When all stages complete:
+1. Update STATE.md with `outcome: complete`
+2. Present final summary
+
+### Block / Failure Handling
+
+If execution cannot continue at any stage:
+1. Update STATE.md: `quick_run.outcome = blocked`
+2. Report blocked stage, reason, what's needed, and how to resume
+
+## Workflow Discipline (Non-Negotiable)
+
+- **Design-first**: `ui-feature` tasks MUST complete the `design` stage before `execute` can begin
+- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR
+- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM
+- **Regression test**: `fix-bug` requires a failing regression test before implementation
+- **Verify**: All workflows end with `/fd-verify`
+
+## Output / State
+
+All routing and execution progress recorded in `.planning/STATE.md` under `quick_run` key.
 
 ## Examples
 
+**Run a feature through full workflow:**
+```
+/fd-quick "Add user profile page with avatar upload"
+```
+
+**Fix a bug autonomously:**
+```
+/fd-quick "Fix the login timeout error that happens randomly"
 ```
-/fd-quick find where session validation happens
-/fd-quick add rate limiting to the API
+
+**Start a documentation task:**
 ```
+/fd-quick "Generate API documentation for the payment module"
+```
+
+## Related Commands
 
-**Note:** Use for small tasks only (~15 min). For larger work, use `/fd-new-feature`.
+- `/fd-discuss` — explore a topic manually
+- `/fd-plan` — plan manually
+- `/fd-execute` — execute manually
+- `/fd-status` — inspect current state and progress
+- `/fd-resume` — reload context after a session break