@dv.nghiem/flowdeck 0.2.3 → 0.2.4

package/src/commands/fd-discuss.md

@@ -15,9 +15,34 @@ Run a structured requirements discussion session and capture decisions.
 2. Read current phase from STATE.md.
 3. Create `.planning/phases/phase-<N>/` directory if it does not exist.
 
-## Discussion Process
+## Process
 
-Act as `@discusser` — a requirements analyst. Ask the user focused questions about the topic: **$ARGUMENTS**
+### Step 1: Load Context
+
+Read `.planning/PROJECT.md` to understand the project vision and goals.
+Read `.planning/STATE.md` to determine the current phase and context.
+
+### Step 2: Determine Phase
+
+Extract the current phase number from STATE.md.
+Decisions will be saved to `.planning/phases/phase-{N}/DISCUSS.md`.
+
+### Step 3: Invoke Discusser
+
+Spawn @discusser agent with:
+- Project context (from PROJECT.md)
+- Current phase number
+- Instructions to ask ONE question per turn
+
+### Step 4: Q&A Loop
+
+The @discusser agent asks one question at a time.
+After each user response:
+- Assign D-XX number to any new decision
+- Record: topic, choice, rationale
+- If response conflicts with previous decision, flag the conflict
+
+Continue until all required topics are covered or user says to stop early.
 
 Structure the discussion:
 
@@ -30,8 +55,6 @@ Ask questions one at a time. Wait for answers before proceeding.
 
 ## Decision Recording
 
-As the user answers, extract decisions and number them `D-01`, `D-02`, etc.
-
 After the discussion, write `.planning/phases/phase-<N>/DISCUSS.md`:
 
 ```markdown
@@ -43,8 +66,8 @@ After the discussion, write `.planning/phases/phase-<N>/DISCUSS.md`:
 
 ## Decisions
 
-D-01: <decision>
-D-02: <decision>
+D-01: [Topic] — [Decision] ([Rationale])
+D-02: [Topic] — [Decision] ([Rationale])
 ...
 
 ## Open Questions
@@ -56,6 +79,21 @@ D-02: <decision>
 - Run /fd-plan to create implementation plan from these decisions
 ```
 
+## D-05 Compliance
+
+- Loads PROJECT.md + current phase STATE.md
+- Invokes @discusser agent
+- Saves decisions with D-XX numbering to DISCUSS.md
+- One question at a time (no compound questions)
+
 ## Completion
 
 Report: decisions captured, file path, and suggest running `/fd-plan`.
+
+## Error Handling
+
+D-03: Fail fast with clear error
+- If PROJECT.md not found: error with "Run /new-project first"
+- If STATE.md not found: error with "Project not initialized"
+- If @discusser fails: error with "Discusser agent unavailable"
+- No partial state saved on error

package/src/commands/fd-fix-bug.md

@@ -9,6 +9,22 @@ Fix a bug using the TDD red-green-refactor discipline.
 
 **Input:** $ARGUMENTS — description of the bug. Optional `--scope=<path>` to limit search scope.
 
+## Prerequisites
+
+- `.planning/` initialized
+- Bug description or reproduction steps available
+
+## TDD Cycle
+
+The workflow enforces the TDD cycle with guards at each transition:
+
+```
+BEHAVIOR → RED → GREEN → REFACTOR → complete
+   ↑______________|         |
+   (loop if needed)         |
+                     Only if GREEN
+```
+
 ## Pre-flight
 
 1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
@@ -16,49 +32,44 @@ Fix a bug using the TDD red-green-refactor discipline.
 3. Read `.codebase/ARCHITECTURE.md` if available — pass as context.
 4. Check `.codebase/FAILURES.json` for prior failures matching the bug description.
 
-## TDD Fix Pipeline (12 steps)
-
-```
-[1-2]  Explore + Research  → isolate root cause
-[3]    Define behaviors    → acceptance cases for the fix
-[4]    RED                 → @tester writes failing regression test
-[5]    Confirm             → test MUST fail before proceeding
-[6]    GREEN               → @coder implements minimum fix
-[7]    Confirm             → test MUST pass before proceeding
-[8]    REFACTOR            → clean up (only if GREEN)
-[9-10] Verify              → full test suite passes
-[11]   Review              → @reviewer confirms + TDD discipline check
-[12]   Record              → log fix + regression test in FAILURES.json
-```
+## Process
 
 ### Steps 1-2: Explore & Research
 
 - **@researcher**: Investigate bug scope, trace root cause via ARCHITECTURE.md and source files
 - **@researcher**: Identify all affected components, list prior similar failures from FAILURES.json
 
+Reproduce the bug with minimal case; document inputs and expected vs actual.
+
 ### Step 3: Define Behaviors
 
 Write acceptance cases describing the fix (what should happen after the bug is fixed).
 
-### Step 4: RED — Write Failing Test
+### Step 4: Isolate Root Cause
+
+Spawn `@researcher` to investigate:
+- Trace the execution path
+- Read stack trace completely
+- Check recent changes: `git log --oneline -20 -- <file>`
+- Identify root cause (not symptom)
+
+### Step 5: RED — Write Failing Test
 
 - **@tester**: Write a regression test that reproduces the bug (it MUST fail right now)
 - Show test output proving it fails
 
 **GUARD: Do NOT proceed if test does not fail RED.**
 
-### Step 5: Confirm RED
+### Step 6: Confirm RED
 
 Confirm test fails. If it passes, the bug may already be fixed or the test is wrong.
 
-### Step 6: GREEN — Implement Fix
+### Step 7: GREEN — Implement Fix
 
 - **@coder**: Implement the minimum code change that makes the regression test pass
 - Do not refactor yet
 
-### Step 7: Confirm GREEN
-
-Run test. It MUST pass. **GUARD: Do NOT proceed if test does not pass GREEN.**
+**GUARD: Do NOT proceed if test does not pass GREEN.**
 
 ### Step 8: REFACTOR
 
@@ -88,6 +99,22 @@ Append entry to `.codebase/FAILURES.json`:
 }
 ```
 
+## Error Handling
+
+- **GUARD VIOLATION**: If coder attempts to skip RED or GREEN phase, block and return to correct phase
+- **Override mechanism**: User can override with `/fd-fix-bug --override` but every override is logged in `override_log`
+- If root cause unclear: spawn `@debug-specialist` for deeper analysis
+- If fix breaks tests: revert, reassess root cause, never suppress error
+
+## Guards Summary
+
+| Transition | Guard | If Violated |
+|-----------|-------|-------------|
+| behavior → red | Test written and fails | Block until test fails |
+| red → green | Test exists and fails | Block until test passes |
+| green → refactor | Tests are green | Block until green |
+| refactor → complete | All tests pass | Block until all pass |
+
 ## Completion
 
 Report: root cause, fix applied, regression test location, reviewer sign-off.

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

@@ -9,28 +9,76 @@ Analyze the current codebase and generate comprehensive documentation under `.co
 
 **Input:** $ARGUMENTS (pass `--incremental` to only process changed files)
 
-## Steps
+## Pre-flight
 
-1. Create `.codebase/` directory if it does not exist.
+Check if `.codebase/` directory already exists. If present, warn and require confirmation to overwrite.
 
-2. Run parallel analysis — delegate to specialist agents:
-   - **@researcher**: Scan package files (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`, etc.) to identify tech stack, frameworks, and dependencies
-   - **@architect**: Analyze directory structure, module boundaries, key entry points, and architectural patterns
-   - **@code-explorer**: Scan source files for naming conventions, code style patterns, import conventions, and anti-patterns
-   - **@tester**: Find test files, identify testing frameworks, coverage configuration, and testing patterns
-   - **@researcher** (second pass): Scan for TODO/FIXME/HACK comments, large files (>500 lines), duplicated code patterns, and security concerns
+## Process
 
-3. Write the following files based on analysis results:
+### Step 1: Check Existing
 
-   - **`.codebase/STACK.md`** — tech stack, frameworks, key dependencies with versions
-   - **`.codebase/ARCHITECTURE.md`** — system design, module boundaries, key flows, data models
-   - **`.codebase/STRUCTURE.md`** — directory layout with explanations of each major directory
-   - **`.codebase/CONVENTIONS.md`** — naming rules, code style, import conventions, patterns to follow
-   - **`.codebase/TESTING.md`** — test frameworks, test patterns, how to run tests, coverage targets
-   - **`.codebase/CONCERNS.md`** — technical debt, risky areas, TODO clusters, large files, security flags
+If `.codebase/` directory already exists:
+```
+Warning: .codebase/ already exists. Running /map-codebase will overwrite existing docs.
+Continue? (y/n)
+```
+If user declines, abort. If user confirms, proceed.
 
-4. If `--incremental`: only update files where the underlying source has changed since the last map (check `.codebase/last_mapped` timestamp).
+### Step 2: Initialize Worktrees
 
-5. Write timestamp to `.codebase/last_mapped`.
+D-04: Each mapper runs in its own isolated worktree to prevent conflicts.
+Create worktrees:
+- `flowdeck-mapper-stack`
+- `flowdeck-mapper-arch`
+- `flowdeck-mapper-structure`
+- `flowdeck-mapper-conventions`
+- `flowdeck-mapper-testing`
+- `flowdeck-mapper-concerns`
 
-6. Report summary: files created/updated, key findings per category.
+### Step 3: Invoke Mappers
+
+Spawn 6 @mapper agents in parallel:
+- @mapper → STACK.md (tech stack, dependencies, versions)
+- @mapper → ARCHITECTURE.md (system design, components, data flow)
+- @mapper → STRUCTURE.md (file organization, directory layout)
+- @mapper → CONVENTIONS.md (coding standards, naming, patterns)
+- @mapper → TESTING.md (test strategy, coverage, frameworks)
+- @mapper → CONCERNS.md (known issues, technical debt, risks)
+
+Each mapper:
+- Reads source files directly (no guessing)
+- Outputs factual analysis only
+- Writes to assigned .codebase/ doc file
+
+### Step 4: Wait for Completion
+
+Wait for all 6 mapper agents to complete. If any fails:
+- Log the failure
+- Continue with remaining mappers
+- Report which docs were not generated
+
+### Step 5: Cleanup
+
+Remove all worktrees regardless of outcome (cleanup happens after all agents complete).
+
+### Step 6: Verify
+
+Check that all 6 .codebase/ doc files exist and contain non-empty content.
+If any are missing or empty, report which ones need regeneration.
+
+If `--incremental`: only update files where the underlying source has changed since the last map (check `.codebase/last_mapped` timestamp).
+
+### Step 7: Write Timestamp
+
+Write timestamp to `.codebase/last_mapped`.
+
+## Output
+
+Report summary: files created/updated, key findings per category.
+
+## Error Handling
+
+D-03: Fail fast with clear error
+- If .codebase/ check fails: show clear error with remediation
+- If worktree creation fails: report which worktree failed
+- Do NOT save partial state on error

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

@@ -1,14 +1,32 @@
 ---
-description: Manage multi-repo registry in .planning/config.json — add, list, status, or remove repos
+description: Cross-repo change orchestration — analyze-repos → identify-dependencies → plan-changes → execute-per-repo → verify-integration
 argument-hint: [list | add <path> [name] | remove <name> | status]
 ---
 
 # Multi-Repo
 
-Manage a multi-repository workspace registry.
+Orchestrates a feature or fix that spans multiple repositories in a microservice architecture.
 
 **Input:** $ARGUMENTS
 
+## When to Use
+
+- A feature requires changes in two or more services
+- An API contract is changing in an upstream service with downstream consumers
+- A shared library is being upgraded with a breaking change
+- You need a coordinated rollout across services
+
+Do not use for single-repo work. Use `/new-feature` instead.
+
+## Prerequisites
+
+Before running this flow:
+1. `.planning/config.json` has a `sub_repos` array with the relevant repos registered
+2. All `path` values in the registry resolve to actual directories on disk
+3. A description of the intended change is available (from `/discuss` or passed directly)
+
+If the registry is empty or not set up, run `/multi-repo --add` first.
+
 ## Behavior
 
 ### List (`list` or no arguments)
@@ -19,10 +37,12 @@ Read `.planning/config.json` → `repos` array. Display:
 ════════════════════════════════════
 MULTI-REPO REGISTRY
 ════════════════════════════════════
-  frontend  — ./packages/frontend  (phase 2, in_progress)
-  backend   — ./packages/backend   (phase 3, completed)
-  shared    — ./packages/shared    (phase 1, planned)
-════════════════════════════════════
+  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]`)
@@ -51,6 +71,110 @@ WORKSPACE STATUS
 Overall: 1 in progress, 1 complete, 1 planned
 ```
 
+## Execution Flow
+
+### 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. The registry must be clean before proceeding.
+
+### Step 2: Identify Dependencies
+
+`@multi-repo-coordinator` and `@architect` work together to:
+
+1. Build the dependency graph from service roles and actual API references (scan client code, package.json, service mesh config)
+2. Classify the requested change as breaking or non-breaking for each affected service
+3. Produce the ordered change list
+
+If any circular dependency is detected, the flow stops and reports the cycle. Circular dependencies cannot be resolved automatically.
+
+### 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 unnecessary 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. `@coder` implements the changes in that repo
+2. `@tester` writes and runs tests for that repo's changes
+3. No downstream repo starts until the upstream repo's changes pass tests
+
+For non-breaking changes, `@coder` and `@tester` for a given repo run in parallel. For breaking changes, `@tester` must verify the upstream before `@coder` starts on any downstream.
+
+If a repo's `@coder` or `@tester` fails, that repo and all downstream repos in the dependency chain are paused. Upstream repos that completed are not rolled back — they remain deployed. The flow resumes once the failing repo is fixed.
+
+### Step 5: Verify Integration
+
+After all per-repo changes are complete, `@tester` and `@reviewer` run cross-repo verification:
+
+**@tester (integration):**
+```
+Task: Run end-to-end integration tests covering the full change path
+Scope: user-service → order-service interaction via the new preferences endpoint
+Test environment: staging (all services deployed to stage)
+```
+
+**@reviewer (cross-repo review):**
+```
+Task: Review all changed files across all repos
+Check: contract adherence, no breaking changes introduced unintentionally,
+       consistent error handling patterns across services
+```
+
+Both run in parallel. Integration tests failing in stage block the production rollout for the entire change set.
+
+## 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
+```
+
+No downstream service enters its canary phase until the upstream service is confirmed stable in production.
+
+## Conflict Handling
+
+If `@multi-repo-coordinator` detects a conflict during Step 2 or Step 3 (two concurrent changes that are incompatible), the flow pauses:
+
+```
+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.
+
+## Error Handling
+
+| 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 and why |
+| Conflict detected | Pause flow; surface options; wait for human decision |
+
 ## Config Format
 
 `.planning/config.json` repos entry:

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

@@ -11,38 +11,181 @@ Implement a new feature using the full FlowDeck agent pipeline.
 
 ## Pre-flight
 
-1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+1. Check `.planning/` exists — if not, error: "Run /fd-new-project first."
 2. Check `plan_confirmed: true` in STATE.md — if not, error: "Confirm plan first with /fd-plan."
 3. Read `.planning/phases/phase-<N>/PLAN.md` to get implementation steps.
 4. Read `.codebase/ARCHITECTURE.md` if it exists — pass as context.
 
-## Execution Pipeline
+## TDD Cycle Per Step
 
-Run the following agent pipeline for feature: **$ARGUMENTS**
+Each plan step follows the TDD cycle:
 
-### Phase 1 — Analysis (parallel)
-- **@researcher**: Trace how $ARGUMENTS touches existing code, find relevant files, identify API contracts at risk
-- **@architect**: Identify architectural boundaries, flag integration points, check for pattern compliance
+```
+BEHAVIOR → RED → GREEN → REFACTOR → next step
+   ↑_________|        |
+   (loop if needed)  Only if GREEN
+```
 
-### Phase 2 — Implementation
-- **@coder**: Implement the feature following PLAN.md steps, CONVENTIONS.md patterns, and TDD discipline
-  - Write failing tests FIRST (RED)
-  - Implement minimum code to pass (GREEN)  
-  - Refactor if needed (REFACTOR)
+## Process
 
-### Phase 3 — Validation (parallel)
-- **@tester**: Run test suite, verify new tests pass, check coverage
-- **@reviewer**: Review implementation for quality, security, and convention compliance
+### Step 1: Guard Check
 
-### Phase 4 — State Update
-- Update `.planning/STATE.md` with completed steps
-- Write summary to `.planning/phases/phase-<N>/RESULT.md`
+Verify prerequisites:
+- `.planning/` directory exists
+- `.codebase/` directory exists
+- `STATE.md` has `plan_confirmed: true`
+- `PLAN.md` exists in current phase directory
 
-## Guard Rails
+Initialize TDD state:
+```yaml
+tdd:
+  stage: behavior
+  cycle: 1
+  behaviors: []
+  regression_test_links: []
+```
 
-- Block if `tdd_enforced: true` and no tests were written
-- Block if any CRITICAL security issues found
-- Require explicit confirmation before overwriting existing public APIs
+### Step 2: Load Plan
+
+Read the active PLAN.md from the current phase directory.
+Parse the tasks list and identify which steps are complete.
+
+### Step 3: Define Behaviors
+
+Spawn `@orchestrator` to generate behavior checklist from PLAN.md:
+- Acceptance cases for each step
+- Edge cases to test
+- Expected behaviors
+
+Store in TDD state.
+
+### Step 4: Identify Next Step
+
+From PLAN.md, find the first step NOT in `steps_complete`.
+Check TDD stage — only proceed if stage is appropriate for the step.
+
+### Step 5: Write Failing Tests (RED)
+
+Spawn `@tester` to write tests for the step's behavior:
+- **Tests MUST fail** before implementation
+- Cover acceptance cases and edge cases
+- Use AAA pattern (Arrange-Act-Assert)
+
+### Step 6: Confirm RED
+
+Run failing tests:
+- **GUARD: Do NOT proceed to Step 7 until tests fail**
+- If tests pass unexpectedly, tests don't correctly describe behavior
+
+### Step 7: Implement Minimum (GREEN)
+
+Spawn `@coder` to implement:
+- **Minimum code** to make failing tests pass
+- No speculative features
+- No over-engineering
+
+### Step 8: Confirm GREEN
+
+Run tests:
+- **GUARD: Do NOT proceed to Step 9 until tests pass**
+- If tests fail, return to Step 7
+
+### Step 9: Refactor (REFACTOR)
+
+Only if GREEN:
+- Clean up code for this step
+- Remove dead code
+- Improve readability
+- **GUARD: Do not refactor if not GREEN**
+
+### Step 10: Verify
+
+Run full test suite:
+- All tests must pass
+- If any fails, revert refactoring
+
+### Step 11: Review Step
+
+Spawn `@reviewer` to check:
+- Code quality, security, conventions
+- TDD discipline followed
+- Test coverage >= 80%
+- No missing or weak tests (flag as major finding)
+
+### Step 12: Update State
+
+Mark step complete via planning-state tool:
+```yaml
+steps_complete: [N, ...]
+last_action: "Step N complete via TDD: [behavior]"
+tdd:
+  stage: behavior  # Ready for next step
+```
+
+### Step 13: Loop or Complete
+
+If more steps pending:
+- Return to Step 3 (define behaviors for next step)
+
+If all steps complete:
+- Update phase status to "complete"
+- Update ROADMAP.md progress
+- Present completion summary
+
+## Wave-Based Execution
+
+WF-03 respects wave structure from PLAN.md:
+- Wave 1 steps execute first (with TDD cycle per step)
+- Wave 2 steps execute after Wave 1 completes
+- Wave 3 steps execute after Wave 2 completes
+- No intra-wave dependencies (parallel execution)
+
+## Guards Summary
+
+| Transition | Guard | If Violated |
+|-----------|-------|-------------|
+| behavior → red | Test written and fails | Block until test fails |
+| red → green | Test exists and fails | Block until test passes |
+| green → refactor | Tests are green | Block until green |
+| refactor → verify | All tests pass | Block until all pass |
+
+## Override Mechanism
+
+User can override with `/fd-new-feature --override`:
+- Every override is logged in `override_log`
+- Surface override in next review
+- Flag in deploy check
+
+## Error Handling
+
+D-03: Fail fast with clear error
+- If guard check fails: abort with clear error and remediation
+- If @coder fails: report failure, offer retry or skip
+- If @reviewer finds critical issues: return to Step 7 for fixes
+- No partial state saved on error
+
+## State Updates
+
+STATE.md updates after each step:
+```yaml
+steps_complete: [1, 2]      # Added after step 2
+steps_pending: [3, 4, 5]   # Removed step 2
+last_action: "Step 2 TDD complete: [behavior] (RED→GREEN→REFACTOR)"
+tdd:
+  stage: behavior
+  cycle: 2
+  behaviors_completed: 2
+```
+
+Full phase completion:
+```yaml
+status: complete
+last_action: "Phase N TDD complete — all steps finished"
+tdd:
+  stage: complete
+  cycles_used: N
+  behaviors_completed: M
+```
 
 ## Completion