@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/src/commands/fd-deploy-check.md

@@ -1,58 +1,213 @@
 ---
-description: Parallel tester + reviewer + researcher CVE check — orchestrator go/no-go deploy decision
-argument-hint: [--env=staging|production]
+description: Pre-deployment checks, code review, and pre-change analysis — all-in-one quality gate
+argument-hint: [--env=staging|production] [--check=deploy,review,analysis] [--scope=path]
 ---
 
 # Deploy Check
 
-Run a comprehensive pre-deploy validation to produce a go/no-go decision.
+Run comprehensive checks before deployment or review code changes.
 
-**Input:** $ARGUMENTS — optional `--env=staging|production` (default: staging)
+**Input:** $ARGUMENTS
 
-## Parallel Checks
+## Check Types
 
-Run three checks simultaneously:
+### Deploy Check (`--check=deploy` or default)
+Run full pre-deployment suite. See Steps 1-3 below.
 
-### Check 1 — Test Suite (@tester)
-- Run full test suite
-- Check TDD coverage meets threshold (default: 80%)
-- Report: tests passed/failed, coverage %, any flaky tests
+### Code Review (`--check=review`)
+Run parallel reviewer + researcher + tester on changed files. See Steps 4-6 below.
 
-### Check 2 — Code Review (@reviewer)
+### Pre-Change Analysis (`--check=analysis`)
+Run comprehensive pre-change analysis. See Step 7 below.
+
+## Common Pre-flight
+
+1. If `--scope` provided: use that path
+2. If no scope with `--check=review`: use files changed since last commit
+3. If no scope with `--check=deploy`: use all changed files since last commit
+
+## Process
+
+### Step 1: Parallel Checks
+
+Launch four checks simultaneously:
+
+**Check A: Test Suite (@tester)**
+```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.
+
+**Check E: Code Review (@reviewer)** — parallel with above
 - Security review: secrets, injection vulnerabilities, auth gaps
 - Quality review: critical bugs, missing error handling
 - TDD discipline: verify new code has tests
 - Report: CRITICAL/HIGH findings only (no nits for deploy check)
 
-### Check 3 — CVE Scan (@researcher)
-- Scan `package.json`, `go.mod`, `Cargo.toml`, `requirements.txt` for known CVEs
-- Check for recently disclosed vulnerabilities in key dependencies
-- Report: any HIGH or CRITICAL CVEs found
+### 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: Go/No-Go 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
+
+### Step 4: Code Review Scope (--check=review)
 
-## Go/No-Go Decision
+If `/deploy-check --check=review [scope]` provided: review files matching scope.
+If no scope: review all files changed since last commit.
 
-**@orchestrator** aggregates results:
+```bash
+git diff --name-only HEAD~1
+```
+
+If no changes found, report: "Nothing to review."
+
+### Step 5: Parallel Review
+
+Spawn three agents simultaneously:
+
+**@reviewer**
+- Security: secrets, injection, auth, XSS
+- Quality: function size, nesting, error handling
+- Conventions: naming, import style, patterns
+
+**@researcher**
+- Look up best practices for flagged patterns
+- Check if flagged patterns are known vulnerabilities
+- Provide context for MEDIUM findings
+
+**@tester**
+- Check coverage for changed files
+- Identify untested paths
+- Run existing tests
+
+### Step 6: Aggregate Review Results
+
+Merge all findings by severity:
+
+```
+## Code Review: <scope>
+
+### 🔴 CRITICAL (block merge)
+- [finding with file:line and fix]
+
+### 🟠 HIGH (strongly recommend fix)
+- [finding]
+
+### 🟡 MEDIUM (consider fixing)
+- [finding]
 
-| Condition | Decision |
-|-----------|----------|
-| All checks pass, zero CRITICAL/HIGH | ✅ GO |
-| Test failures or coverage below threshold | ❌ NO-GO |
-| CRITICAL security issues | ❌ NO-GO |
-| HIGH issues or HIGH CVEs | ⚠️ CONDITIONAL (requires override) |
+### 🟢 LOW (optional)
+- [finding]
 
-## Report
+### Coverage
+- Changed files: N%
+- Untested paths: [list]
 
+### Verdict: PASS | FAIL | PASS_WITH_NOTES
 ```
-════════════════════════════════════════════
-DEPLOY CHECK — <env>
-════════════════════════════════════════════
-Tests:    <passed>/<total> | Coverage: <X>%
-Security: <N> critical, <M> high
-CVEs:     <N> high, <M> medium
 
-DECISION: GO / NO-GO / CONDITIONAL
-════════════════════════════════════════════
+### Step 7: Pre-Change Analysis (--check=analysis)
+
+Run all analyses in parallel:
+
+1. **Impact Radar** — which files/APIs/tests are affected
+2. **Blast Radius** — downstream consequences and hidden couplings
+3. **Regression Predict** — most likely regression categories
+4. **Test Gap** — coverage gaps to fill before implementing
+5. **Volatility** — check hotspot scores on affected files
+6. **Review Route** — who should review this change
+
+## Consolidated Analysis Report
+
+```
+════════════════════════════════════════════════════
+PRE-CHANGE ANALYSIS: "$ARGUMENTS"
+════════════════════════════════════════════════════
+
+IMPACT (<N> files affected)
+  - <top 5 affected files with reason>
+
+BLAST RADIUS (risk: <low|medium|high>)
+  - <key downstream risks>
+
+REGRESSIONS (top 3 risks)
+  🔴 <category> — <reason>
+  🟠 <category> — <reason>
+
+TEST GAPS (<N> gaps found)
+  - CRITICAL: <gap>
+  - HIGH: <gap>
+
+VOLATILITY
+  Hot zones touched: <list or "none">
+
+REVIEW ROUTING
+  → <reviewer type> (<reason>)
+
+────────────────────────────────────────────────────
+RECOMMENDATION: <proceed | add tests first | redesign | review required>
+
+Next steps:
+  1. <most important action>
+  2. <second action>
+════════════════════════════════════════════════════
 ```
 
-For NO-GO: list blocking issues with fix suggestions.
-For CONDITIONAL: list what requires override approval.
+## 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 |

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