@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/docs/commands/fd-done.md

@@ -0,0 +1,215 @@
+# /fd-done
+
+**Purpose:** Mark a feature or phase complete, validate readiness, finalize state, and refresh the codebase mapping.
+
+## Usage
+
+/fd-done [--skip-verify] [--phase=N]
+
+## Arguments
+
+- `--skip-verify` (optional) — allow closing without a prior `/fd-verify` run
+- `--phase=N` (optional) — target a specific phase
+
+## What Happens
+
+### Step 0: Pre-flight
+
+1. Check `.planning/STATE.md` exists. If not: error "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
+2. Read current STATE.md using `planning_state action=read`.
+3. Record: `phase`, `status`, `plan_confirmed`, `blockers`, `steps_complete`, `requires_design_first`, `design_stage`, `design_approved`.
+
+### Step 1: Completion Readiness Validation
+
+Before marking done, verify the workflow is in a finishable state.
+
+| Check | Pass condition |
+|-------|---------------|
+| Plan confirmed | `plan_confirmed: true` |
+| Not already done | `status != "complete"` |
+| Work has started | `status != "planned"` OR `steps_complete` is non-empty |
+| No active blockers | `blockers` list is empty or contains only `"none"` |
+| Design gate (if required) | `requires_design_first: false` OR `design_stage: handoff_complete` AND `design_approved: true` OR `design_override: true` |
+
+If any check fails, stop and report all failures. Do NOT update any state when validation fails.
+
+**Verify check:**
+- If `status != "verified"` and `--skip-verify` was NOT passed: warn that `/fd-verify` has not been run
+- If `--skip-verify` is passed: log that verification was skipped
+
+### Step 2: Collect Completion Evidence
+
+Gather files changed in this feature:
+```bash
+git diff --name-only HEAD
+git diff --name-only HEAD~1..HEAD 2>/dev/null || echo "(no commits yet)"
+```
+
+Record `changedFiles[]` for the summary artifact.
+
+### Step 3: Codebase Mapping — Refresh or Reuse
+
+Check codegraph state: `codegraph action=status`
+
+- **If mapping is fresh** (indexed, `freshnessStatus: fresh`, no changed files since last index):
+  - Log: "[fd-done] Codebase mapping is current — skipping remap"
+  - Record: `mappingRefreshed: false`, `mappingFreshnessStatus: fresh`
+
+- **If mapping is stale, absent, or changed files exist since last index:**
+  - Log: "[fd-done] Refreshing codebase mapping..."
+  - Run: `codegraph action=refresh agent=fd-done`
+  - Record result: `mappingRefreshed: true`, `mappingFreshnessStatus: fresh|stale`
+  - If refresh fails: log error, set `mappingFreshnessStatus: stale`, continue — do not abort
+
+### Step 4: Mark Feature Complete
+
+Update STATE.md:
+```
+planning_state action=update updates={
+  status: "complete",
+  last_action: "Phase <N> marked done via /fd-done",
+  next_action: "Run /fd-status to review project state, or /fd-new-feature to start the next phase"
+}
+```
+
+Additional fields to upsert:
+```
+completed_at: "<ISO timestamp>"
+completed_by: "fd-done"
+verify_skipped: <true|false>
+mapping_refreshed_at_done: "<ISO timestamp if refreshed, else skipped>"
+mapping_freshness_at_done: "<fresh|stale|skipped>"
+```
+
+### Step 5: Write Completion Artifact
+
+Write `.planning/phases/phase-<N>/DONE.md`:
+```markdown
+# Phase <N> — Done
+
+**Completed:** <ISO timestamp>
+**Completed by:** fd-done
+**Prior status:** <status before this run>
+**Steps complete:** <list>
+
+## Verification
+
+✅ /fd-verify ran — all checks passed before closing
+  — OR —
+⚠️  /fd-verify not run — skipped by user (--skip-verify)
+  — OR —
+⚠️  /fd-verify not run — consider running before deploying
+
+## Codebase Mapping
+
+✅ Codebase mapping refreshed (status: fresh)
+  — OR —
+ℹ️  Codebase mapping reused — already fresh (status: fresh)
+  — OR —
+⚠️  Codebase mapping refresh failed (status: stale)
+
+## Changed Files
+
+- <file 1>
+- <file 2>
+...
+
+## Next Steps
+
+- Run `/fd-status` to see the full project state
+- Run `/fd-new-feature` or increment the phase to start the next feature
+- Run `/fd-deploy-check` if preparing for production deployment
+```
+
+### Step 6: Update ROADMAP.md (if present)
+
+If `.planning/ROADMAP.md` exists:
+- Find the entry for Phase N
+- Update its status to `completed`
+- Preserve all other phases unchanged
+
+### Step 7: Report Completion
+
+Print final summary with completion timestamp, prior status, steps complete, changed files count, verification status, and mapping freshness.
+
+## Error Handling
+
+- STATE.md not found → error with remediation ("No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature.")
+- Completion validation fails → list all failures, do not update state
+- Mapping refresh fails → log error, continue with `mappingFreshnessStatus: stale`
+- DONE.md write fails → log error, do not fail overall — state is already updated
+- ROADMAP.md update fails → log error, do not fail overall
+
+No partial state writes. Either the validation passes and full state is written, or nothing is written.
+
+## Output / State
+
+- `.planning/STATE.md` — status set to `complete`
+- `.planning/phases/phase-<N>/DONE.md` — completion artifact written
+- `.planning/ROADMAP.md` — phase marked as completed (if exists)
+- Codebase mapping refreshed (if needed)
+
+### DONE.md Artifact Format
+
+The completion artifact at `.planning/phases/phase-<N>/DONE.md` uses this structure:
+
+```markdown
+# Phase <N> — Done
+
+**Completed:** <ISO timestamp>
+**Completed by:** fd-done
+**Prior status:** <status before this run>
+**Steps complete:** <list>
+
+## Verification
+
+✅ /fd-verify ran — all checks passed before closing
+  — OR —
+⚠️  /fd-verify not run — skipped by user (--skip-verify)
+  — OR —
+⚠️  /fd-verify not run — consider running before deploying
+
+## Codebase Mapping
+
+✅ Codebase mapping refreshed (status: fresh)
+  — OR —
+ℹ️  Codebase mapping reused — already fresh (status: fresh)
+  — OR —
+⚠️  Codebase mapping refresh failed (status: stale)
+
+## Changed Files
+
+- <file 1>
+- <file 2>
+...
+
+## Next Steps
+
+- Run `/fd-status` to see the full project state
+- Run `/fd-new-feature` or increment the phase to start the next feature
+- Run `/fd-deploy-check` if preparing for production deployment
+```
+
+## Examples
+
+**Mark current phase complete:**
+```
+/fd-done
+```
+
+**Mark specific phase complete:**
+```
+/fd-done --phase=2
+```
+
+**Close without prior verification:**
+```
+/fd-done --skip-verify
+```
+
+## Related Commands
+
+- `/fd-status` — review the completed project state
+- `/fd-new-feature` — start the next feature
+- `/fd-deploy-check` — pre-deployment checks after completing a phase
+- `/fd-verify` — full verification before marking done (recommended)

package/docs/commands/fd-execute.md

@@ -0,0 +1,104 @@
+# /fd-execute
+
+**Purpose:** Implement the current phase's plan using TDD discipline and a parallel agent pipeline — delegates to specialist agents via orchestrator, cycles through RED-GREEN-REFACTOR per step, and updates STATE.md throughout.
+
+## Usage
+
+/fd-execute [--phase=N] [--override]
+
+## What Happens
+
+1. **Research gate (before touching any code).**
+   - CodeGraph intelligence check (`codegraph action=check`)
+   - If indexed and fresh: use `codegraph_context` and `codegraph_impact`
+   - Standard pre-flight: verify STATE.md freshness, check CODEBASE_INDEX.md for changes since plan was written
+   - Reuse persisted research if fresh; run fresh pass and persist if stale
+   - Verify design handoff is complete if `requires_design_first: true`
+
+2. **Guard check.**
+   - Verify `.planning/` and `.codebase/` exist
+   - Verify `plan_confirmed: true` in STATE.md
+   - Verify PLAN.md exists in current phase directory
+   - If `requires_design_first: true`: require `design_stage: handoff_complete` and `design_approved: true` (or `--override` with logged reason)
+   - Initialize TDD state (`stage: behavior`, `cycle: 1`)
+
+3. **Load PLAN.md.** Parse tasks and identify which steps are already complete.
+
+4. **TDD cycle per step** (repeat for each incomplete step):
+
+   a. **Define behaviors** — spawn `@orchestrator` to generate behavior checklist from the step
+   
+   b. **RED** — spawn `@tester` to write failing tests (tests MUST fail before implementation)
+   
+   c. **Confirm RED** — run failing tests; block until tests fail
+   
+   d. **GREEN** — spawn appropriate implementation agent (`@backend-coder`, `@frontend-coder`, or `@devops`) to write minimum code to pass the failing tests
+   
+   e. **Confirm GREEN** — run tests; block until they pass; return to (d) if they fail
+   
+   f. **REFACTOR** — clean up code (only if GREEN); block if not GREEN
+   
+   g. **Verify** — run full test suite; revert refactoring if any test fails
+   
+   h. **Review step** — spawn `@reviewer` to check quality, security, TDD discipline, >= 80% test coverage
+   
+   i. **Update STATE.md** — mark step complete, increment TDD cycle
+   
+   j. **Refresh codegraph index** — run `codegraph action=refresh agent=fd-execute` after each source change
+
+5. **Wave-based execution.** Wave 1 steps execute first; Wave 2 after Wave 1; Wave 3 after Wave 2. No intra-wave dependencies.
+
+6. **Complete phase.**
+   - Update phase status to `complete` in STATE.md
+   - Update ROADMAP.md progress
+   - Present completion summary
+
+## Output / State
+
+STATE.md per-step update:
+```yaml
+steps_complete: [1, 2]
+steps_pending: [3, 4, 5]
+last_action: "Step 2 TDD complete: [behavior] (RED→GREEN→REFACTOR)"
+tdd:
+  stage: behavior
+  cycle: 2
+  behaviors_completed: 2
+```
+
+STATE.md on full phase completion:
+```yaml
+status: complete
+last_action: "Phase N TDD complete — all steps finished"
+tdd:
+  stage: complete
+  cycles_used: N
+  behaviors_completed: M
+```
+
+## Examples
+
+```
+/fd-execute
+```
+
+Run the TDD pipeline for all steps in the current phase's PLAN.md.
+
+```
+/fd-execute --phase=2
+```
+
+Execute phase 2's plan instead of the current phase.
+
+```
+/fd-execute --override
+```
+
+Override design-first requirement (with logged reason). Use sparingly.
+
+## Related Commands
+
+- `/fd-plan` — create the plan before executing
+- `/fd-verify` — run full verification after execution
+- `/fd-resume` — reload state and continue if execution was interrupted
+- `/fd-checkpoint` — save checkpoint before a long execution session

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

@@ -1,24 +1,144 @@
----
-description: Debug and fix a bug — scope analysis, mini-plan, implementation-agent fix, regression test, reviewer confirmation
-argument-hint: "[bug description or issue number]"
----
-
-Systematically debug and fix a bug using FlowDeck's structured approach.
-
-**What this does:**
-1. Reads `.codebase/` for architecture context
-2. Delegates to `@debug-specialist` to locate the root cause
-3. Creates a mini-plan (fix + regression test)
-4. Delegates fix to `@backend-coder`, `@frontend-coder`, or `@devops` based on scope
-5. Delegates regression test writing to `@tester`
-6. Verifies the fix via `@reviewer`
-7. Writes a brief post-mortem to `.planning/bugs/`
-
-**Root cause first:** Does not implement a fix until root cause is confirmed — no symptom masking.
-
-## What Next?
-
-1. **Run code review** → `/fd-verify`
-2. **Check for more bugs** → `/fd-fix-bug [next-issue]`
-3. **Update documentation** → `/fd-write-docs`
-4. **Deploy check** → `/fd-deploy-check`
+# /fd-fix-bug
+
+**Purpose:** Diagnose, fix, and verify a bug using TDD-based workflow with regression test.
+
+## Usage
+
+```
+/fd-fix-bug [bug description] [--scope=path]
+```
+
+**Note:** `bug description` is required. `--scope=path` is optional.
+
+## Arguments
+
+- `bug description` — description of the bug or reproduction steps
+- `--scope=path` (optional) — limit search scope to a specific path
+
+## What Happens
+
+The workflow enforces the TDD cycle with guards at each transition:
+
+```
+BEHAVIOR → RED → GREEN → REFACTOR → complete
+   ↑______________|         |
+   (loop if needed)         |
+                     Only if GREEN
+```
+
+### Pre-flight: Research Gate
+
+Before investigating the bug, inspect relevant context:
+
+1. Check codegraph availability (`codegraph action=check`). If indexed, use `codegraph_context`, `codegraph_callers`, `codegraph_callees`, and `codegraph_impact` for symbol-level understanding.
+2. Read `.planning/STATE.md` — current phase, freshness.
+3. Read `.codebase/FAILURES.json` — check for prior similar failures.
+4. Read `.codebase/ARCHITECTURE.md` and `.codebase/CODEGRAPH.md` if available.
+5. Check `research_fix-bug` evidence in STATE.md from prior research passes.
+6. Check recent changes via `git log --oneline -10` on relevant files.
+
+If research is fresh (within 5 minutes), reuse it and log: "Research skipped — fresh evidence reused from prior pass."
+
+### Steps 1-2: Explore and Research
+
+- **@researcher** investigates bug scope, traces root cause via ARCHITECTURE.md and source files.
+- **@researcher** identifies all affected components and prior similar failures from FAILURES.json.
+- Reproduce the bug with minimal case; document inputs and expected vs actual behavior.
+
+### Step 3: Define Behaviors
+
+Write acceptance cases describing what should happen after the bug is fixed.
+
+### Step 4: Isolate Root Cause
+
+- 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** writes 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 6: GREEN — Implement Fix
+
+- Implementation agent (`@backend-coder`, `@frontend-coder`, or `@devops`) implements the minimum code change that makes the regression test pass.
+- Do not refactor yet.
+
+**GUARD: Do NOT proceed if test does not pass GREEN.**
+
+### Step 7: REFACTOR
+
+Clean up the implementation. Run tests again to confirm they still pass.
+
+### Steps 8-9: Full Suite and Review
+
+- Run the full test suite. All tests must pass.
+- **@reviewer** confirms fix is correct, no regressions, TDD discipline followed.
+
+### Step 10: Record
+
+Append entry to `.codebase/FAILURES.json`:
+```json
+{
+  "id": "F-<N>",
+  "type": "bug",
+  "description": "<bug description>",
+  "affected_paths": ["<files changed>"],
+  "root_cause": "<root cause>",
+  "fix_applied": "<fix summary>",
+  "regression_test": "<test file path>",
+  "resolved_at": "<timestamp>"
+}
+```
+
+Refresh the codegraph index after recording:
+```
+codegraph action=refresh agent=fd-fix-bug
+```
+
+## 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 |
+
+## Error Handling
+
+- **GUARD VIOLATION**: If implementation agent 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.
+
+## Output / State
+
+- Root cause identified
+- Fix applied to affected files
+- Regression test created at `<test file path>`
+- Reviewer sign-off received
+- Entry appended to `.codebase/FAILURES.json`
+- Codegraph index refreshed
+
+## Examples
+
+**Fix a bug with description:**
+```
+/fd-fix-bug "Login fails when password contains special characters"
+```
+
+**Fix a bug scoped to a specific path:**
+```
+/fd-fix-bug "Session timeout error" --scope=src/auth
+```
+
+## Related Commands
+
+- `/fd-verify` — run full verification suite after fix
+- `/fd-discuss` — investigate before filing a bug report
+- `/fd-deploy-check` — run pre-deployment checks after fix is complete

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