@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/src/commands/fd-done.md

@@ -0,0 +1,196 @@
+---
+description: Mark the current feature as complete — validates readiness, finalizes state, refreshes codebase mapping
+argument-hint: [--skip-verify] [--phase=N]
+---
+
+# Done
+
+Close the current feature or phase: validate completion readiness, mark it done, update all shared state, and refresh the codebase mapping so later commands start from a current understanding of the code.
+
+**Input:** $ARGUMENTS — optional `--skip-verify` to allow closing without a prior `/fd-verify` run; optional `--phase=N` to target a specific phase
+
+## 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.
+
+Evaluate all of the following. Collect every failure — do not stop at the first:
+
+| 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:
+
+```
+❌ Cannot mark done — completion requirements not met:
+
+  - [ ] <reason 1>
+  - [ ] <reason 2>
+
+Fix these issues, then run /fd-done again.
+```
+
+Do NOT update any state when validation fails.
+
+**Verify check:**
+
+If `status != "verified"` and `--skip-verify` was NOT passed:
+- Warn: `"⚠️  /fd-verify has not been run for this phase. Run /fd-verify first, or pass --skip-verify to close without it."`
+- Do NOT block — this is a warning, not a hard blocker (unless there are other hard blockers above)
+
+If `--skip-verify` is passed:
+- Log: `"[fd-done] --skip-verify passed — closing without /fd-verify"`
+
+## Step 2: Collect Completion Evidence
+
+Gather files changed in this feature:
+
+```bash
+git diff --name-only HEAD
+```
+
+Also check:
+
+```bash
+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 current codegraph state:
+
+```
+codegraph action=status
+```
+
+**If mapping is fresh** (indexed, `freshnessStatus: fresh`, and 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 the error, set `mappingFreshnessStatus: stale`, continue — do not abort completion
+
+## 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 directly into STATE.md:
+
+```
+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 from whatever it currently is to `completed`
+- Preserve all other phases unchanged
+
+Only do this if the ROADMAP.md already tracks phases explicitly.
+
+## Step 7: Report Completion
+
+Print final summary:
+
+```
+════════════════════════════════════════════════════════════
+✅ DONE  — Phase <N> marked complete
+════════════════════════════════════════════════════════════
+
+  Completed at:      <timestamp>
+  Prior status:      <status>
+  Steps complete:    <N>
+  Changed files:     <N files>
+
+  Verification:      ✅ verified  |  ⚠️ skipped
+  Codebase mapping:  ✅ refreshed  |  ℹ️ reused (already fresh)
+
+  Artifact:          .planning/phases/phase-<N>/DONE.md
+  State:             .planning/STATE.md  ← status: complete
+
+────────────────────────────────────────────────────────────
+Next: /fd-status  |  /fd-new-feature  |  /fd-deploy-check
+════════════════════════════════════════════════════════════
+```
+
+## 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.

package/src/commands/fd-execute.md

@@ -9,14 +9,43 @@ Implement the current phase's plan using the full FlowDeck TDD agent pipeline.
 
 **Input:** $ARGUMENTS — optional `--phase=N` to target a specific phase, `--override` to bypass guards
 
-## Pre-flight
+## Pre-flight: Research Gate
 
-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.
+**Before reading PLAN.md or touching any code**, re-verify the execution context.
 
-## TDD Cycle Per Step
+Research scope: `execute`
+
+**CodeGraph Intelligence Check (first):**
+
+```
+codegraph action=check
+```
+
+- If codegraph indexed and fresh: use `codegraph_context` and `codegraph_impact` to understand affected file scope before each implementation step
+  - Log: "codegraph available — impact analysis will use code intelligence"
+- If codegraph absent or stale after a prior execution run: consider running `/fd-map-codebase --incremental` to rebuild the index before proceeding
+
+**Standard pre-flight (always):**
+
+1. Read `.planning/STATE.md` — verify plan_confirmed, current phase, freshness
+2. Read `.codebase/CODEBASE_INDEX.md` if available — check for any file changes since plan was written
+3. Read `.codebase/CODEGRAPH.md` if available — check codegraph index freshness
+4. Check for any `research_execute` evidence in STATE.md from prior research passes
+5. If design-first is required, verify design handoff is complete before proceeding
+
+If existing research is fresh (summaryVersion matches, state fresh within 5 min):
+- Reuse the persisted research evidence
+- Log: "Research skipped — fresh evidence reused from prior pass"
+- Proceed to Guard Check
+
+If research is stale or missing:
+- Run fresh research pass using available MCP and filesystem tools
+- Persist results to STATE.md for future reuse
+- Log which sources were consulted and what evidence was gathered
+
+> **MCP integration:** When implementation requires external library knowledge, invoke configured MCP tools as part of the research pass.
+
+### Step 1: Guard Check
 
 Each plan step follows the TDD cycle:
 
@@ -126,6 +155,14 @@ tdd:
   stage: behavior  # Ready for next step
 ```
 
+After each step that changes source files, refresh the codegraph index so impact analysis stays current for subsequent steps:
+
+```
+codegraph action=refresh agent=fd-execute
+```
+
+If refresh fails, log a warning but do not block execution — codegraph auto-syncs via file watcher when the MCP server is running.
+
 ### Step 13: Loop or Complete
 
 If more steps pending:

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

@@ -25,14 +25,42 @@ BEHAVIOR → RED → GREEN → REFACTOR → complete
                      Only if GREEN
 ```
 
-## Pre-flight
+## Pre-flight: Research Gate
 
-1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
-2. Parse `--scope` from arguments (default: entire codebase).
-3. Read `.codebase/ARCHITECTURE.md` if available — pass as context.
-4. Check `.codebase/FAILURES.json` for prior failures matching the bug description.
+**Before investigating the bug**, inspect the failure path and relevant codebase area.
 
-## Process
+Research scope: `fix-bug`
+
+**CodeGraph Intelligence Check (first):**
+
+```
+codegraph action=check
+```
+
+- If codegraph indexed: use `codegraph_context` to map the bug area, `codegraph_callers`/`codegraph_callees` to trace the execution path, `codegraph_impact` to identify affected files — before opening any file
+  - Log: "codegraph available — using code intelligence for bug investigation"
+- If absent: fall back to ARCHITECTURE.md + direct source reads
+
+**Standard pre-flight (always):**
+
+1. Read `.planning/STATE.md` — current phase, freshness
+2. Read `.codebase/FAILURES.json` — check for prior similar failures matching the bug description
+3. Read `.codebase/ARCHITECTURE.md` if available — codebase structure
+4. Read `.codebase/CODEGRAPH.md` if available — codegraph index freshness
+5. Check for any `research_fix-bug` evidence in STATE.md from prior research passes
+6. Check recent changes via `git log --oneline -10` on relevant files
+
+If existing research is fresh (summaryVersion matches, state fresh within 5 min):
+- Reuse the persisted research evidence
+- Log: "Research skipped — fresh evidence reused from prior pass"
+- Proceed to Explore & Research
+
+If research is stale or missing:
+- Run fresh research pass using available MCP and filesystem tools
+- Persist results to STATE.md for future reuse
+- Log which sources were consulted and what evidence was gathered
+
+> **MCP integration:** When the bug involves external APIs or libraries, invoke configured MCP tools (websearch, docs MCP) to research known failure modes.
 
 ### Steps 1-2: Explore & Research
 
@@ -99,6 +127,14 @@ Append entry to `.codebase/FAILURES.json`:
 }
 ```
 
+After recording, refresh the codegraph index so later stages and agents work against the updated codebase:
+
+```
+codegraph action=refresh agent=fd-fix-bug
+```
+
+If refresh fails, log a warning but do not block — codegraph auto-syncs via file watcher when the MCP server is running.
+
 ## Error Handling
 
 - **GUARD VIOLATION**: If implementation agent attempts to skip RED or GREEN phase, block and return to correct phase
@@ -118,3 +154,4 @@ Append entry to `.codebase/FAILURES.json`:
 ## Completion
 
 Report: root cause, fix applied, regression test location, reviewer sign-off.
+Next step: run `/fd-verify`.

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

@@ -1,30 +1,82 @@
 ---
-description: Analyze codebase and generate .codebase/ documentation — STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS
-argument-hint: [--incremental]
+description: Analyze codebase and generate .codebase/ documentation — STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS. Uses codegraph as primary code intelligence layer.
+argument-hint: [--incremental] [--force]
 ---
 
 # Map Codebase
 
 Analyze the current codebase and generate comprehensive documentation under `.codebase/`.
+Uses `codegraph` as the primary code intelligence layer for accurate, symbol-level understanding.
 
-**Input:** $ARGUMENTS (pass `--incremental` to only process changed files)
+**Input:** $ARGUMENTS (pass `--incremental` to only update changed files, `--force` to skip existing-index confirmation)
 
 ## Pre-flight
 
-Check if `.codebase/` directory already exists. If present, warn and require confirmation to overwrite.
+### Step 0: Check codegraph Installation
 
-## Process
+Use the `codegraph` tool to check the current state:
+
+```
+codegraph action=check
+```
+
+Log the result:
+- **If installed and indexed**: "codegraph ready — index is [fresh/stale]"
+- **If installed but not indexed**: "codegraph installed, index not built — will initialize"
+- **If not installed**: "codegraph not installed — will auto-install"
+
+### Step 1: Auto-Install codegraph if Missing
+
+If `codegraph` is not installed:
+
+```
+codegraph action=install
+```
+
+Log clearly:
+- If install succeeded: "codegraph installed successfully"
+- If already installed (skipped): "codegraph already installed — skipping"
+- If install failed: report the error and remediation steps; abort
+
+> **Diagnostics**: Log install output verbatim for troubleshooting.
+
+### Step 2: Initialize or Refresh codegraph Index
+
+If `.codegraph/` does not exist or `--force` was passed:
 
-### Step 1: Check Existing
+```
+codegraph action=init agent=fd-map-codebase
+```
+
+If `.codegraph/` exists and `--incremental` was passed:
+- Check if changed since last index
+- If stale: run `codegraph action=refresh agent=fd-map-codebase`
+- If fresh: log "codegraph index is fresh — reusing existing mapping"
+
+Log:
+- Whether this was a full build or incremental update
+- Number of changed files detected
+- The git revision fingerprinted
+
+If init/refresh fails:
+- Log the error and diagnostic output
+- Fall back to mapper agents only (proceed to Step 3 without codegraph)
+- Note in summary that codegraph was unavailable
+
+### Step 3: Check Existing .codebase/ Docs
+
+Check if `.codebase/` documentation directory already exists.
 
-If `.codebase/` directory already exists:
+If present and `--force` is not set:
 ```
-Warning: .codebase/ already exists. Running /map-codebase will overwrite existing docs.
+Warning: .codebase/ already exists. Running /fd-map-codebase will overwrite existing docs.
 Continue? (y/n)
 ```
-If user declines, abort. If user confirms, proceed.
+If user declines, abort. If user confirms or `--force` was passed, proceed.
 
-### Step 2: Initialize Worktrees
+## Process
+
+### Step 4: Initialize Worktrees
 
 D-04: Each mapper runs in its own isolated worktree to prevent conflicts.
 Create worktrees:
@@ -35,9 +87,10 @@ Create worktrees:
 - `flowdeck-mapper-testing`
 - `flowdeck-mapper-concerns`
 
-### Step 3: Invoke Mappers
+### Step 5: Invoke Mappers with codegraph Context
+
+Spawn 6 @mapper agents in parallel. Each mapper receives the codegraph status:
 
-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)
@@ -45,40 +98,67 @@ Spawn 6 @mapper agents in parallel:
 - @mapper → TESTING.md (test strategy, coverage, frameworks)
 - @mapper → CONCERNS.md (known issues, technical debt, risks)
 
+**codegraph instructions for mappers:**
+
+If `.codegraph/` exists, each mapper **must** use codegraph MCP tools first:
+
+| Task | Tool |
+|------|------|
+| Map a module / feature area | `codegraph_context` |
+| Find a symbol by name | `codegraph_search` |
+| Trace call paths | `codegraph_trace` |
+| Check callers/callees | `codegraph_callers` / `codegraph_callees` |
+| Impact of a change | `codegraph_impact` |
+| Read a symbol's source | `codegraph_node` |
+| Survey related symbols | `codegraph_explore` |
+
+Fall back to direct file reads only when codegraph doesn't cover a specific detail.
+
 Each mapper:
-- Reads source files directly (no guessing)
+- Reads from codegraph first, files only when necessary
 - Outputs factual analysis only
 - Writes to assigned .codebase/ doc file
 
-### Step 4: Wait for Completion
+### Step 6: 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
+### Step 7: Cleanup
 
 Remove all worktrees regardless of outcome (cleanup happens after all agents complete).
 
-### Step 6: Verify
+### Step 8: 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).
+If `--incremental`: only update files where the underlying source has changed since the last map (check `.codebase/CODEGRAPH.md` lastIndexedAt timestamp).
 
-### Step 7: Write Timestamp
+### Step 9: Write Timestamp and Update State
 
-Write timestamp to `.codebase/last_mapped`.
+1. Write timestamp to `.codebase/last_mapped`.
+2. Update the `codegraph` tool state:
+   ```
+   codegraph action=status
+   ```
+   Log whether codegraph MCP tools are available for subsequent commands.
 
 ## Output
 
-Report summary: files created/updated, key findings per category.
+Report summary:
+- codegraph: installed ✅/❌, indexed ✅/❌, full/incremental build
+- files created/updated per mapper agent
+- key findings per category
+- Next: codegraph MCP tools are now available to /fd-discuss, /fd-plan, /fd-execute, /fd-fix-bug
 
 ## Error Handling
 
 D-03: Fail fast with clear error
+- If codegraph install fails: log diagnostics, fall back to mapper-only mode (no codegraph MCP)
+- If codegraph init fails: log diagnostics, fall back to mapper-only mode
 - 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

@@ -25,7 +25,7 @@ Before running this flow:
 2. All `path` values in the registry resolve to actual directories on disk
 3. A description of the intended change is available (from `/fd-discuss` or passed directly)
 
-If the registry is empty or not set up, run `/multi-repo --add` first.
+If the registry is empty or not set up, run `/fd-multi-repo --add` first.
 
 ## Behavior
 

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

@@ -11,9 +11,19 @@ Initialize a new feature and guide through the full FlowDeck feature workflow.
 
 ## Pre-flight
 
-1. Check `.planning/` exists — if not, error: "Run /fd-new-project first."
-2. Read `.planning/STATE.md` to determine the current phase number N.
-3. Create `.planning/phases/phase-<N>/` directory if it does not exist.
+1. Check `.codebase/` exists — if not, error:
+   > "Codebase mapping is required before starting a feature. Run `/fd-map-codebase` first to index the codebase."
+
+2. If `.planning/` does not exist, initialize it now:
+   - Create `.planning/` directory.
+   - Create `.planning/STATE.md` with default initial state (phase 1, status: ready).
+   - Create `.planning/config.json` with default settings:
+     ```json
+     { "model_profile": "balanced", "tdd_enforced": true, "approval_required": false, "default_agent": "orchestrator" }
+     ```
+
+3. Read `.planning/STATE.md` to determine the current phase number N (default: 1 if not set).
+4. Create `.planning/phases/phase-<N>/` directory if it does not exist.
 
 ## Process
 
@@ -73,7 +83,6 @@ Next steps (in order):
 
 ## Error Handling
 
-- If `.planning/` not found: error "Run /fd-new-project first."
-- If STATE.md not found: error "Project not initialized. Run /fd-new-project first."
+- If `.codebase/` not found: error "Codebase mapping is required first. Run `/fd-map-codebase` to index the codebase."
 - No partial state saved on error.
 

package/src/commands/fd-plan.md

@@ -1,5 +1,5 @@
 ---
-description: Create detailed implementation plan from DISCUSS.md decisions — save PLAN.md, update STATE.md, require CONFIRM before execution
+description: Create detailed implementation plan from DISCUSS.md decisions — research-first, save PLAN.md, update STATE.md, require CONFIRM before execution
 argument-hint: [--phase=N] [--yes]
 ---
 
@@ -11,6 +11,43 @@ Create a detailed implementation plan from confirmed DISCUSS.md decisions.
 
 ## Process
 
+### Step 0: Research Gate
+
+**Before producing any plan**, gather implementation context from the repository.
+
+Research scope: `plan`
+
+**CodeGraph Intelligence Check (first):**
+
+```
+codegraph action=check
+```
+
+- If codegraph is installed and indexed: use `codegraph_context`, `codegraph_explore`, `codegraph_impact` for architecture and affected-file analysis instead of direct file reads
+  - Log: "codegraph available — using code intelligence for research gate"
+- If codegraph is absent or stale: fall back to standard research pass
+
+**Standard research pass (always):**
+
+1. Read `.planning/STATE.md` — current phase, position, freshness
+2. Read `.planning/phases/phase-<N>/DISCUSS.md` — D-XX decisions to trace
+3. Read `.codebase/ARCHITECTURE.md` if available — codebase structure
+4. Read `.codebase/CODEBASE_INDEX.md` if available — recent changes and volatility signals
+5. Read `.codebase/CODEGRAPH.md` if available — codegraph index freshness metadata
+6. Check for any `research_plan` evidence in STATE.md from prior research passes
+
+If existing research is fresh (summaryVersion matches, state fresh within 5 min):
+- Reuse the persisted research evidence
+- Log: "Research skipped — fresh evidence reused from prior pass"
+- Proceed to Step 1
+
+If research is stale or missing:
+- Run fresh research pass using available MCP and filesystem tools
+- Persist results to STATE.md for future reuse
+- Log which sources were consulted and what evidence was gathered
+
+> **MCP integration:** When library, API, or external knowledge is needed, invoke configured MCP tools (websearch, docs MCP, code search MCP) as part of the research pass.
+
 ### Step 1: Guard Check
 
 D-06: Verify DISCUSS.md exists and is confirmed.