@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/commands/fd-doctor.md

@@ -1,21 +1,108 @@
----
-description: Check FlowDeck installation and environment health
----
+# /fd-doctor
 
-# Doctor
+**Purpose:** Check FlowDeck installation and environment health across the system.
 
-Check FlowDeck installation and environment health.
+## Usage
 
-## Checks
+/fd-doctor
+
+## What Happens
+
+The command runs a series of diagnostic checks and reports status for each:
+
+1. **OpenCode CLI** — runs `opencode --version`. Reports the version if found, warns if not found.
+
+2. **FlowDeck plugin registration** — reads `~/.config/opencode/opencode.json` (or `$OPENCODE_CONFIG_DIR/opencode.json`). Checks that `@dv.nghiem/flowdeck` is present in the `plugins` array.
+
+3. **Workspace state** — checks whether `.planning/STATE.md` exists in the current directory. Warns (non-fatal) if missing.
+
+4. **Codebase map** — checks whether `.codebase/ARCHITECTURE.md` exists. Notes if missing and suggests `/fd-map-codebase`.
+
+5. **Planning phases** — if STATE.md exists, parses the current phase and verifies that `.planning/phases/phase-N/` directory exists.
+
+## Notation Legend
+
+The report uses check box notation:
 
-- OpenCode CLI version
-- FlowDeck plugin registration
-- Workspace state (STATE.md)
-- Codebase map (ARCHITECTURE.md)
-- Planning phases directory
+| Notation | Meaning |
+|----------|---------|
+| `[x]` | Pass — check succeeded |
+| `[ ]` | Failure — blocks healthy status |
+| `[!]` | Warning — non-blocking issue |
 
-## Example
+The report closes with `✅ Environment looks healthy!` if no failures, otherwise `❌ Some issues found.`
 
+## Output / State
+
+The command produces a formatted report using check box notation:
+
+```
+# FlowDeck Doctor Report
+
+- [x] OpenCode detected: <version>
+- [x] FlowDeck registered in ~/.config/opencode/opencode.json
+- [x] .planning/STATE.md exists in current workspace
+- [!] No .codebase/ARCHITECTURE.md found (run /fd-map-codebase)
+- [x] Phase directory .planning/phases/phase-1/ exists
+
+✅ Environment looks healthy!
+```
+
+Notation:
+- `[x]` — pass
+- `[ ]` — failure (blocks healthy status)
+- `[!]` — warning (non-blocking)
+
+The report closes with `✅ Environment looks healthy!` if no failures, otherwise `❌ Some issues found.`
+
+## Output Example
+
+When running `/fd-quick "implement user login"`, the autonomous execution begins with this classification announcement:
+
+```
+Task classified as: feature
+Stage sequence:     discuss → plan → execute → verify
+Requires design:     no
+Requires TDD:        yes
+Evidence used:       12 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.
+```
+
+## Examples
+
+**Run diagnostics:**
 ```
 /fd-doctor
-```
+```
+
+**Sample healthy output:**
+```
+# FlowDeck Doctor Report
+
+- [x] OpenCode detected: 1.2.3
+- [x] FlowDeck registered in ~/.config/opencode/opencode.json
+- [x] .planning/STATE.md exists in current workspace
+- [x] .codebase/ARCHITECTURE.md found
+- [x] Phase directory .planning/phases/phase-1/ exists
+
+✅ Environment looks healthy!
+```
+
+**Sample output with issues:**
+```
+# FlowDeck Doctor Report
+
+- [x] OpenCode detected: 1.2.3
+- [ ] FlowDeck NOT registered in ~/.config/opencode/opencode.json
+- [x] .planning/STATE.md exists in current workspace
+- [!] No .codebase/ARCHITECTURE.md found (run /fd-map-codebase)
+
+❌ Some issues found.
+```
+
+## Related Commands
+
+- `/fd-map-codebase` — generate .codebase/ documentation if ARCHITECTURE.md is missing
+- `/fd-status` — view current project state for more detail

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