@dv.nghiem/flowdeck 0.2.2 → 0.2.4

package/src/commands/fd-plan.md

@@ -5,75 +5,97 @@ argument-hint: [--phase=N] [--yes]
 
 # Plan
 
-Create a detailed implementation plan from confirmed discussion decisions.
+Create a detailed implementation plan from confirmed DISCUSS.md decisions.
 
 **Input:** $ARGUMENTS (optional `--phase=N` to target a specific phase, `--yes` to skip confirmation)
 
-## Pre-flight
+## Process
 
-1. Check `.planning/STATE.md` exists — if not, return error: "Run /fd-new-project first."
-2. Determine phase: use `--phase=N` from arguments, or read current phase from STATE.md.
-3. Check `.planning/phases/phase-<N>/DISCUSS.md` exists — if not, return error: "Run /fd-discuss first."
+### Step 1: Guard Check
 
-## Confirmation Gate
+D-06: Verify DISCUSS.md exists and is confirmed.
 
-Unless `--yes` is passed or STATE.md already has `plan_confirmed: true`:
-
-Show a preview of the DISCUSS.md decisions found and ask:
+If no DISCUSS.md found:
+```
+Error: DISCUSS.md not found. Run /discuss [topic] first.
+```
 
+If DISCUSS.md exists but not confirmed:
+```
+Error: DISCUSS.md not yet confirmed. Complete the discuss phase first.
 ```
-═══════════════════════════════════════════
-PLAN PHASE <N> — AWAITING CONFIRMATION
-═══════════════════════════════════════════
 
-Found <X> decisions in DISCUSS.md:
-<preview of D-XX lines>
+Abort with clear error message in both cases.
 
-Type CONFIRM to save PLAN.md and enable execution.
-═══════════════════════════════════════════
-```
+### Step 2: Load Context
 
-**PAUSE** — wait for user to type CONFIRM before proceeding.
+Read:
+- `.codebase/PROJECT.md` (project context)
+- `.planning/STATE.md` (current phase and position)
+- `.planning/phases/phase-<N>/DISCUSS.md` (D-XX decisions to trace in plan)
 
-## Plan Generation
+### Step 3: Draft Plan
 
-After confirmation:
+Create PLAN.md with:
+- Tasks that 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
 
-1. Read all `D-XX: <decision>` lines from DISCUSS.md.
-2. Generate `.planning/phases/phase-<N>/PLAN.md`:
+### Step 4: Validate Plan
 
-```markdown
-# Implementation Plan
+Verify:
+- All requirements from ROADMAP.md for current phase are addressed
+- All D-XX decisions from DISCUSS.md are traced in plan tasks
+- No tasks that contradict prior decisions
 
-**Phase:** <N>
-**Created:** <timestamp>
-**Source:** DISCUSS.md (<X> decisions)
+If validation fails, return to Step 3 to revise.
 
-## Decisions
+### Step 5: Review Plan
 
-- D-01: <decision>
-- D-02: <decision>
+Present draft plan to user:
+- Show all tasks and their D-XX decision traces
+- Show wave structure
+- Show file dependencies
 
-## Steps
+### Step 6: PAUSE CONFIRM
 
-- [ ] Step 1: <concrete implementation step traced to decision>
-- [ ] Step 2: <concrete implementation step>
-- [ ] Step 3: <concrete implementation step>
+D-06: "PAUSE — wait for user CONFIRM before saving"
 
-## Acceptance Criteria
+Present:
+```
+Ready to save PLAN.md?
+Type CONFIRM to save, or describe changes needed.
+```
 
-- [ ] <criterion from DISCUSS.md>
-- [ ] <criterion from DISCUSS.md>
+If user types CONFIRM, proceed to Step 7.
+If user requests changes, return to Step 3 with feedback.
 
-## Status
+### Step 7: Save Plan
 
-CONFIRMED
-```
+Save PLAN.md to `.planning/phases/phase-<N>/PLAN.md`.
+Commit with message: `docs(phase-N): save confirmed plan`
+
+### Step 8: Update State
+
+Update STATE.md:
+- Set plan_file to path of saved PLAN.md
+- Set plan_confirmed: true
+- Update last_action to "Plan confirmed"
+
+## D-06 Compliance
+
+- Requires confirmed DISCUSS.md before proceeding
+- Aborts with clear error if DISCUSS.md not confirmed
+- Creates PLAN.md tracing D-XX decisions
+- Pauses for user CONFIRM before saving
+
+## Error Handling
 
-3. Update `.planning/STATE.md`:
-   - Set `plan_confirmed: true`
-   - Set `confirmed_at: <timestamp>`
-   - Set `status: in_progress`
+D-03: Fail fast with clear error
+- If guard check fails: abort with clear error and remediation
+- If plan validation fails: show what's missing
+- No partial plan saved on error
 
 ## Completion
 

package/src/commands/fd-review-code.md

@@ -5,58 +5,92 @@ argument-hint: [--scope=path | --focus=security,quality,tdd]
 
 # Review Code
 
-Run a comprehensive parallel code review.
+Run a comprehensive parallel code review before merging or deploying.
 
 **Input:** $ARGUMENTS — optional `--scope=<path>` and `--focus=<areas>`
 
-## Steps
+## Process
 
-1. Determine scope: use `--scope` if provided, else review uncommitted changes (`git diff --name-only HEAD`).
-2. If no changes found, report: "Nothing to review."
+### Step 1: Identify Scope
 
-## Parallel Review
+If `/review-code [scope]` provided: review files matching scope.
+If no scope: review all files changed since last commit.
 
-Run three reviewers in parallel:
+```bash
+git diff --name-only HEAD~1
+```
+
+If no changes found, report: "Nothing to review."
+
+### Step 2: Parallel Review
 
-- **@reviewer**: Quality, security, convention compliance, TDD discipline
-  - CRITICAL: hardcoded secrets, SQL injection, XSS, auth gaps
-  - HIGH: logic errors, missing error handling, unsafe casts
-  - MEDIUM: functions >50 lines, nesting >4 deep, missing tests
-  - LOW: naming nits, missing comments on public APIs
+Spawn three agents simultaneously:
 
-- **@researcher**: API contracts, edge cases, hidden dependencies, integration risks
+**@reviewer**
+- Security: secrets, injection, auth, XSS
+- Quality: function size, nesting, error handling
+- Conventions: naming, import style, patterns
 
-- **@tester**: Test coverage, missing test cases, test quality, regression risks
+**@researcher**
+- Look up best practices for flagged patterns
+- Check if flagged patterns are known vulnerabilities
+- Provide context for MEDIUM findings
 
-## Report
+**@tester**
+- Check coverage for changed files
+- Identify untested paths
+- Run existing tests
 
-Aggregate findings into:
+### Step 3: Aggregate Results
+
+Merge all findings by severity:
 
 ```
-════════════════════════════════════════════
-CODE REVIEW REPORT
-════════════════════════════════════════════
-Files reviewed: <N>
+## Code Review: <scope>
+
+### 🔴 CRITICAL (block merge)
+- [finding with file:line and fix]
 
-CRITICAL (<count>)
-  - <file>:<line> — <issue>
+### 🟠 HIGH (strongly recommend fix)
+- [finding]
 
-HIGH (<count>)
-  - <file>:<line> — <issue>
+### 🟡 MEDIUM (consider fixing)
+- [finding]
 
-MEDIUM (<count>)
-  - <file>:<line> — <issue>
+### 🟢 LOW (optional)
+- [finding]
 
-LOW (<count>)
-  - <file>:<line> — <issue>
+### Coverage
+- Changed files: N%
+- Untested paths: [list]
 
-Test Coverage: <findings>
-────────────────────────────────────────────
-Verdict: PASS / NEEDS CHANGES / BLOCK
-════════════════════════════════════════════
+### Verdict: PASS | FAIL | PASS_WITH_NOTES
 ```
 
-**Verdict rules:**
-- CRITICAL issues → BLOCK
-- HIGH issues → NEEDS CHANGES
-- Only MEDIUM/LOW → PASS with comments
+### Step 4: Decision
+
+- **CRITICAL found** → Block. Fix before merge.
+- **HIGH found** → Strongly recommend fix. Document if proceeding anyway.
+- **MEDIUM/LOW** → Document. Proceed.
+- **PASS** → Ready to merge.
+
+## Agent Configuration
+
+| Agent | Model | Purpose |
+|-------|-------|---------|
+| @reviewer | google/gemini-2.5-flash | Security and quality |
+| @researcher | anthropic/claude-sonnet-4-5 | Context and best practices |
+| @tester | anthropic/claude-sonnet-4-5 | Coverage analysis |
+
+## Severity Classification
+
+| Severity | Meaning | Action |
+|----------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Output
+
+Report: files reviewed, findings by severity, coverage, verdict.

package/src/commands/fd-write-docs.md

@@ -5,46 +5,78 @@ argument-hint: [--scope=path | --format=api,guide,readme]
 
 # Write Docs
 
-Generate documentation for the codebase or a specific scope.
+Generate accurate, up-to-date documentation from the codebase.
 
 **Input:** $ARGUMENTS — optional `--scope=<path>` and `--format=<type>`
 
 Supported formats: `api` (API reference), `guide` (usage guide), `readme` (README)  
 Default: all formats
 
-## Pipeline
+## Process
 
-### Phase 1 — Explore
+### Step 1: Explore APIs
 
-- **@researcher**: Find all public APIs, exported functions, classes, types, and their signatures
-- **@code-explorer**: Identify existing documentation, JSDoc comments, README sections
+Spawn `@mapper` to:
+- Find all exported functions, classes, and types
+- Identify public API entry points
+- Map key workflows and integration points
 
-### Phase 2 — Draft
+```bash
+# Find exports
+grep -rn "export " src/ --include="*.ts"
+# Find public interfaces
+grep -rn "export interface\|export type\|export class" src/ --include="*.ts"
+```
 
-- **@writer**: Draft documentation based on the exploration findings
-  - API docs: function signatures, parameters, return types, examples
-  - Guides: usage examples, step-by-step instructions
-  - README: project overview, install, quickstart, API summary
+### Step 2: Draft Documentation
 
-### Phase 3 — Review
+Spawn `@writer` to produce:
 
-- **@reviewer**: Check accuracy — verify all documented APIs exist and signatures are correct
-  - Flag any documentation that contradicts the implementation
-  - Flag missing documentation for public APIs
+**API Reference**
+```markdown
+## functionName(param: Type): ReturnType
 
-### Phase 4 — Finalize
+Description of what the function does.
 
-- **@writer**: Apply reviewer corrections, finalize and write documentation files
+**Parameters:**
+- `param` (Type) — description
 
-## Output Files
+**Returns:** description
 
-Based on `--format`:
-- `api` → writes or updates `docs/API.md`
-- `guide` → writes or updates `docs/GUIDE.md`
-- `readme` → updates `README.md`
+**Example:**
+\`\`\`typescript
+const result = functionName(value);
+\`\`\`
+```
 
-If `--scope` is set, documentation applies only to files within that path.
+**Usage Guide**
+- Step-by-step workflow with examples
+- Common patterns and best practices
+- Configuration options
 
-## Completion
+**Troubleshooting**
+- Common errors and their solutions
+
+### Step 3: Review for Accuracy
+
+Spawn `@reviewer` to verify:
+- Every documented function/method actually exists
+- Parameter types match the actual signatures
+- Examples are syntactically correct
+- No outdated API references
+
+### Step 4: Finalize
+
+Writer incorporates feedback and writes final docs to:
+- `README.md` — project overview and quick start
+- `docs/API.md` — complete API reference
+- `docs/USER_GUIDE.md` — detailed usage guide
+
+## Output
+
+Updated documentation files with:
+- Accurate function signatures
+- Working code examples
+- Clear explanations of behavior
 
 Report: files written/updated, public APIs documented, any gaps found.

package/src/workflows/debug-flow.md

@@ -1,119 +0,0 @@
----
-name: debug-flow
-description: "Systematic debugging: reproduce → trace → write failing test → fix root cause → verify. Never suppress errors."
-triggers:
-  - /debug
-steps:
-  - name: reproduce
-    agent: "@debug-specialist"
-    action: Establish minimal reproduction case with expected vs actual behavior
-  - name: trace
-    agent: "@debug-specialist"
-    action: Debug-specialist traces execution path and identifies root cause
-  - name: write_test
-    agent: "@tester"
-    action: Tester writes failing regression test for the exact failure
-  - name: fix
-    agent: "@coder"
-    action: Coder fixes root cause with minimal change
-  - name: verify
-    agent: "@tester"
-    action: Run regression test + full suite to confirm fix
----
-
-# Debug Flow
-
-## Purpose
-
-Diagnose and fix unexpected behavior systematically. Prevents symptom-fixing and ensures reproducibility.
-
-## Rules
-
-- Never suppress an error to make a test pass
-- Fix the root cause, not the symptom
-- Always write a regression test before fixing
-- Read stack traces completely — never half-read
-
-## Process
-
-### Step 1: Reproduce
-
-Document the bug precisely:
-```
-Bug: [one-line description]
-Steps to reproduce:
-  1. ...
-  2. ...
-Expected: [what should happen]
-Actual: [what does happen]
-Stack trace: [if available]
-```
-
-Confirm you can reproduce it consistently before proceeding.
-
-### Step 2: Trace
-
-Spawn `@debug-specialist` to:
-
-1. Read the complete stack trace
-2. Identify the failing function and line
-3. Trace inputs backward to find where bad data enters
-4. Check recent changes: `git log --oneline -10 -- <file>`
-5. Identify root cause (not symptom)
-
-Common root causes:
-| Symptom | Look for |
-|---------|---------|
-| null/undefined error | Missing boundary check |
-| Wrong value | Type coercion, missing validation |
-| Race condition | Missing await, shared mutable state |
-| Auth failure | Missing middleware, wrong scope check |
-| Infinite loop | Missing base case, wrong termination |
-
-### Step 3: Write Failing Test
-
-Spawn `@tester` to write a regression test:
-- Must FAIL on current code (RED)
-- Tests the exact scenario from Step 1
-- Isolated from other tests
-
-```typescript
-test('should [expected] when [condition from bug report]', () => {
-  // Arrange: set up the exact failing scenario
-  // Act: call the failing code
-  // Assert: verify expected behavior
-});
-```
-
-### Step 4: Fix
-
-Spawn `@coder` to:
-- Fix the root cause identified in Step 2
-- Minimum change to make the regression test pass
-- Do NOT touch unrelated code
-
-If the fix requires more than 20 lines: STOP, reassess scope.
-
-### Step 5: Verify
-
-```bash
-# Regression test must pass
-npm test -- --grep "regression test name"
-
-# Full suite must still pass
-npm test
-```
-
-If any unrelated test breaks: the fix has unintended side effects. Investigate before proceeding.
-
-## Output
-
-```
-## Debug Complete
-
-Bug: [description]
-Root cause: [specific cause]
-Fix: [what changed, file:line]
-Regression test: [test name] ✅ PASS
-Suite: ✅ N/N tests passing
-```

package/src/workflows/deploy-check-flow.md

@@ -1,98 +0,0 @@
----
-name: deploy-check-flow
-description: "Pre-deployment checks: parallel tests + security scan + CVE audit + build verification → go/no-go decision"
-triggers:
-  - /deploy-check
-steps:
-  - name: parallel_checks
-    agent: "@parallel-coordinator"
-    action: Run tests, security scan, CVE audit, and build in parallel
-  - name: aggregate
-    agent: "@orchestrator"
-    action: Aggregate all results into a unified report
-  - name: decision
-    agent: "@orchestrator"
-    action: Produce explicit go/no-go decision with required fixes if no-go
----
-
-# Deploy Check Flow
-
-## Purpose
-
-Run a comprehensive pre-deployment check suite before releasing to production.
-
-## Process
-
-### Step 1: Parallel Checks
-
-Launch four checks simultaneously:
-
-**Check A: Test Suite**
-```bash
-npm test
-```
-All tests must pass. No failures, no skips without justification.
-
-**Check B: Security Scan**
-
-Spawn `@security-auditor` to check:
-- No hardcoded secrets in changed files
-- Input validation at trust boundaries
-- Auth/authz on all protected routes
-- No CRITICAL or HIGH vulnerabilities
-
-**Check C: Dependency CVE Audit**
-```bash
-npm audit --audit-level=high
-```
-No HIGH or CRITICAL CVEs unaddressed.
-
-**Check D: Build Verification**
-```bash
-npm run build
-```
-Build must succeed with zero errors.
-
-### Step 2: Aggregate Results
-
-```
-## Pre-Deployment Check
-
-| Check | Status | Details |
-|-------|--------|---------|
-| Tests | ✅ PASS / ❌ FAIL | N/N passed |
-| Security | ✅ PASS / ❌ FAIL | [findings] |
-| CVE Audit | ✅ PASS / ❌ FAIL | [vulnerabilities] |
-| Build | ✅ PASS / ❌ FAIL | [errors] |
-```
-
-### Step 3: Decision
-
-**🚀 GO** — all checks pass, proceed with deployment.
-
-**🛑 NO-GO** — one or more checks failed:
-```
-Verdict: NO-GO
-
-Required fixes before deploy:
-- [ ] [fix 1]
-- [ ] [fix 2]
-
-Run /deploy-check again after fixing.
-```
-
-## No-go conditions (automatic)
-
-Any of these → automatic NO-GO:
-- Test failures
-- CRITICAL security vulnerability
-- HIGH/CRITICAL CVE unpatched
-- Build error
-
-## Agent configuration
-
-| Agent | Purpose |
-|-------|---------|
-| @tester | Run test suite |
-| @security-auditor | Security vulnerability scan |
-| @researcher | CVE research and context |

package/src/workflows/discuss-flow.md

@@ -1,97 +0,0 @@
----
-name: discuss-flow
-description: "Orchestrates discuss phase (context load → @discusser Q&A → pause → decisions → save)"
-triggers:
-  - /discuss
-steps:
-  - name: load_context
-    agent: "@orchestrator"
-    priority: first
-    action: Load PROJECT.md and current phase STATE.md
-  - name: determine_phase
-    agent: "@orchestrator"
-    action: Extract current phase number from STATE.md
-  - name: invoke_discusser
-    agent: "@discusser"
-    action: Spawn @discusser agent with project context
-  - name: qa_loop
-    agent: "@discusser"
-    action: Discusser asks one question at a time; user responds; repeat until all topics covered
-  - name: save_decisions
-    agent: "@discusser"
-    action: Write all decisions to .planning/phases/phase-N/DISCUSS.md with D-XX numbering
-  - name: confirm_discuss
-    agent: "@orchestrator"
-    action: Present summary to user; require explicit confirmation before marking DISCUSS.md as confirmed
----
-
-# Discuss Flow
-
-## Purpose
-
-Extract project requirements and decisions via structured Q&A with the @discusser agent.
-
-## Process
-
-### 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.
-
-### Step 5: Save Decisions
-
-Save all decisions to `.planning/phases/phase-N/DISCUSS.md`:
-```
-D-01: [Topic] — [Decision] ([Rationale])
-D-02: [Topic] — [Decision] ([Rationale])
-...
-```
-
-### Step 6: Confirm Discuss
-
-Present summary of decisions to user.
-Ask for explicit confirmation: "CONFIRMED" to proceed or "REVISION NEEDED" to revisit.
-
-If user confirms:
-- Update STATE.md to mark DISCUSS.md as confirmed
-- Proceed to plan phase
-
-If user requests revision:
-- Return to Step 4 (Q&A loop) for the specified topics
-
-## 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)
-
-## 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