@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/commands/fd-ask.md

@@ -1,51 +1,83 @@
----
-description: Smart dispatch — routes a free-form task to the appropriate specialized agent without requiring a workflow
-argument-hint: "--task '<description>'"
----
+# /fd-ask
 
-Route a free-form task to the best specialized agent automatically.
+**Purpose:** Smart agent dispatch — routes a focused question to the appropriate specialist.
 
-**What this does:**
-1. Parses your task description using keyword scoring
-2. Picks the best-fit agent from 12 specialists
-3. Runs the Impact Radar if the task involves change analysis
-4. Dispatches the task directly — no workflow, no STATE.md required
+## Usage
 
-**Routing table:**
+/fd-ask [question]
 
-| Keywords | Agent |
-|---|---|
-| design, architecture, component | `@architect` |
-| impact, blast radius, affected | `@researcher` + radar |
-| security, vulnerability, CVE | `@security-auditor` |
-| performance, bottleneck, slow | `@performance-optimizer` |
-| debug, error, crash, exception | `@debug-specialist` |
-| test, coverage, spec, TDD | `@tester` |
-| refactor, cleanup, simplify | `@backend-coder` / `@frontend-coder` / `@devops` |
-| document, docs, README | `@writer` |
-| explain, query, find, explore | `@code-explorer` |
-| deploy, release, migration | `@devops` |
-| plan, roadmap, breakdown | `@planner` |
-| (anything else) | `@orchestrator` |
+## Arguments
 
-**Examples:**
+- `question` — the question to route to a specialist agent
 
+## What Happens
+
+Analyze the question to determine the best specialist from this routing table:
+
+| Keywords / Topic | Agent |
+|-----------------|-------|
+| ui, ux, wireframe, landing page, dashboard, admin panel, app screen, design system | **@design** |
+| design, architecture, structure, system, component, API | **@architect** |
+| security, auth, vulnerability, token, permission, injection | **@security-auditor** |
+| performance, speed, slow, optimize, latency, cache, memory | **@performance** |
+| impact, change, affect, downstream, dependency, blast | **@researcher** (impact mode) |
+| test, coverage, regression, tdd, gap | **@tester** |
+| bug, error, crash, debug, trace | **@debug-specialist** |
+| general / unclear | **@orchestrator** |
+
+Once the specialist is identified:
+1. Delegate the question to that specialist with full context
+2. Include `.codebase/ARCHITECTURE.md` if available and relevant
+3. Include `.planning/STATE.md` phase context if relevant
+4. Return the specialist's answer directly
+
+## Output / State
+
+Present the answer clearly with:
+- Which specialist answered
+- The answer (no padding, no ceremony)
+- Any follow-up suggestions if the question opens further threads
+
+## Examples
+
+**Ask an architecture question:**
+```
+/fd-ask "What is the best way to structure a new API endpoint?"
+```
+Routes to: @architect
+
+**Ask a security question:**
 ```
-/fd-ask --task "system design for a real-time notification service"
-/fd-ask --task "explain how the payment flow works"
-/fd-ask --task "is there a security issue with the rate limiter"
-/fd-ask --task "why is the login endpoint slow"
-/fd-ask --task "what files are affected if I change the auth module"
-/fd-ask --task "write tests for the checkout service"
-/fd-ask --agent security-auditor --task "review the JWT implementation"
+/fd-ask "How should we handle token expiration securely?"
 ```
+Routes to: @security-auditor
 
-**Override routing:** Use `--agent` to force a specific agent.
+**Ask about performance:**
+```
+/fd-ask "Why is the login page slow on mobile?"
+```
+Routes to: @performance
+
+**Ask about a bug:**
+```
+/fd-ask "Why does the session timeout error appear randomly?"
+```
+Routes to: @debug-specialist
 
-## What Next?
+**Ask about test coverage:**
+```
+/fd-ask "What parts of the auth module are not tested?"
+```
+Routes to: @tester
+
+**Ask about UI design:**
+```
+/fd-ask "Should the dashboard use tabs or a sidebar for navigation?"
+```
+Routes to: @design
 
-After `/fd-ask` completes, you can go deeper:
+## Related Commands
 
-1. **Full workflow** → `/fd-fix-bug`, `/fd-new-feature`, `/fd-verify`
-2. **Detailed planning** → `/fd-discuss`, `/fd-plan`
-3. **Another question** → `/fd-ask --task '...'`
+- `/fd-discuss` — structured exploration of a topic with multiple questions
+- `/fd-suggest` — get feature recommendations
+- `/fd-translate-intent` — convert a vague request into concrete options

package/docs/commands/fd-checkpoint.md

@@ -1,10 +1,65 @@
----
-description: Save current state to STATE.md — safe to close session after this
----
-Run the FlowDeck checkpoint command to save the current project state.
+# /fd-checkpoint
 
-## What Next?
+**Purpose:** Force-save mid-session checkpoint to STATE.md and write a CHECKPOINT.md summary — safe to close the session and resume later with `/fd-resume`.
 
-1. **Continue working** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`
+## Usage
+
+/fd-checkpoint
+
+## What Happens
+
+1. **Pre-flight check.**
+   - Verify `.planning/STATE.md` exists — error if not found ("No active project to checkpoint.")
+
+2. **Read current STATE.md.** Parse phase, status, steps_complete, and other tracked fields.
+
+3. **Update STATE.md.**
+   - Set `last_updated` to current timestamp
+   - Ensure `status` reflects current state accurately
+   - Scan `.planning/phases/phase-<N>/PLAN.md` for completed steps and update `steps_complete` if tracked
+
+4. **Write CHECKPOINT.md.** Creates `.planning/phases/phase-<N>/CHECKPOINT.md`:
+
+```markdown
+# Checkpoint
+
+**Saved:** <timestamp>
+**Phase:** <N>
+**Status:** <status>
+**Plan confirmed:** <yes/no>
+
+## What was done
+
+<brief summary of recent changes in this session>
+
+## What's next
+
+<next uncompleted step from PLAN.md, or "No plan active">
+```
+
+5. **Report.** Present checkpoint summary including phase, status, file path, and the `/fd-resume` command.
+
+## Output / State
+
+Files created:
+- `.planning/phases/phase-<N>/CHECKPOINT.md`
+
+STATE.md updates:
+```yaml
+last_updated: "<timestamp>"
+status: <current status>
+steps_complete: [1, 2, ...]   # if tracked in PLAN.md
+```
+
+## Examples
+
+```
+/fd-checkpoint
+```
+
+Save a checkpoint for the current session. Safe to close afterward.
+
+## Related Commands
+
+- `/fd-resume` — reload the checkpointed state and continue
+- `/fd-map-codebase` — map the codebase (required before starting a feature)

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

@@ -1,11 +1,168 @@
----
-description: Pre-deploy check — parallel tester + reviewer + CVE scan — orchestrator go/no-go decision
----
-Run the FlowDeck deploy-check workflow before deploying to production.
+# /fd-deploy-check
 
-## What Next?
+**Purpose:** Pre-deploy safety check with test, security, and build verification.
 
-1. **Fix blocking issues** → `/fd-fix-bug [issue]`
-2. **Create deployment checkpoint** → `/fd-checkpoint`
-3. **Review code again** → `/fd-verify`
-4. **View project roadmap** → `/fd-roadmap`
+## Usage
+
+/fd-deploy-check [--env=staging|production] [--check=deploy,review,analysis] [--scope=path]
+
+## Arguments
+
+- `--env=staging|production` (optional) — target environment
+- `--check=deploy|review|analysis` (optional) — type of check to run
+  - `deploy` (default): full pre-deployment suite
+  - `review`: parallel reviewer + researcher + tester on changed files
+  - `analysis`: comprehensive pre-change analysis
+- `--scope=path` (optional) — limit scope to specific files or directories
+
+## What Happens
+
+### Deploy Check (`--check=deploy` or default)
+
+**Step 1: Parallel Checks**
+
+Launch four checks simultaneously:
+
+- **Check A: Test Suite (@tester)** — runs `npm test`. All tests must pass.
+- **Check B: Security Scan (@security-auditor)** — checks for hardcoded secrets, input validation at trust boundaries, auth/authz on protected routes, no CRITICAL/HIGH vulnerabilities.
+- **Check C: Dependency CVE Audit** — runs `npm audit --audit-level=high`. No HIGH/CRITICAL CVEs unaddressed.
+- **Check D: Build Verification** — runs `npm run build`. Build must succeed with zero errors.
+- **Check E: Code Review (@reviewer)** (parallel) — security review, quality review, TDD discipline check.
+
+**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. Report required fixes.
+
+### Code Review (`--check=review`)
+
+**Step 4-5: Scope and Parallel Review**
+
+Determine scope (files changed since last commit or provided scope). Spawn three agents in parallel:
+- **@reviewer** — security, quality, conventions review
+- **@researcher** — best practices lookup, vulnerability context
+- **@tester** — coverage check, untested paths, run existing tests
+
+**Step 6: Aggregate Review Results**
+
+```
+## Code Review: <scope>
+
+### 🔴 CRITICAL (block merge)
+- [finding with file:line and fix]
+
+### 🟠 HIGH (strongly recommend fix)
+- [finding]
+
+### 🟡 MEDIUM (consider fixing)
+- [finding]
+
+### 🟢 LOW (optional)
+- [finding]
+
+### Coverage
+- Changed files: N%
+- Untested paths: [list]
+
+### Verdict: PASS | FAIL | PASS_WITH_NOTES
+```
+
+### Pre-Change Analysis (`--check=analysis`)
+
+**Step 7: 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
+
+```
+════════════════════════════════════════════════════
+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>
+════════════════════════════════════════════════════
+```
+
+## No-Go Conditions
+
+Automatic NO-GO if any of:
+- Test failures
+- CRITICAL security vulnerability
+- HIGH/CRITICAL CVE unpatched
+- Build error
+
+## Output / State
+
+For deploy: aggregated check results with GO/NO-GO verdict.
+For review: findings by severity with verdict.
+For analysis: consolidated analysis report with recommendations.
+
+## Examples
+
+**Full pre-deployment check:**
+```
+/fd-deploy-check
+```
+
+**Code review on specific scope:**
+```
+/fd-deploy-check --check=review --scope=src/auth
+```
+
+**Pre-change analysis:**
+```
+/fd-deploy-check --check=analysis --scope=src/api
+```
+
+**Target staging environment:**
+```
+/fd-deploy-check --env=staging
+```
+
+## Related Commands
+
+- `/fd-verify` — full verification suite
+- `/fd-fix-bug` — fix issues found during check
+- `/fd-status` — review current project state

package/docs/commands/fd-design.md

@@ -0,0 +1,101 @@
+# /fd-design
+
+**Purpose:** Design-first workflow for UI-heavy features, including draft, review, and design system modes.
+
+## Usage
+
+/fd-design [--mode=draft|review|system] [task-description] [--override]
+
+## Arguments
+
+- `--mode=draft|review|system` (optional) — workflow mode, default: `draft`
+- `task-description` — description of the design task
+- `--override` (optional) — bypass design approval requirement (logged explicitly)
+
+## What Happens
+
+### Mode: draft
+
+Use when creating or updating UI before implementation.
+
+**Required Stages:**
+1. discovery
+2. UX planning
+3. wireframe/layout planning
+4. visual system definition
+5. design approval
+6. implementation handoff
+
+**Process:**
+1. Classify task as UI-heavy (landing page, dashboard, admin panel, app screen, website/app UX)
+2. Delegate to `@design` agent for structured artifacts
+3. Persist outputs in planning state under `design_artifact`
+4. Mark:
+   - `requires_design_first: true`
+   - `design_stage: handoff_complete`
+   - `design_approved: true` only when approval criteria are met
+5. Record any bypass with explicit `design_override_reason`
+
+### Mode: review
+
+Use to review implemented UI against approved design artifact.
+
+**Process:**
+1. Load approved design artifact and changed UI files
+2. Delegate to `@design` with `design-audit` + `responsive-review`
+3. Report:
+   - design mismatches
+   - hierarchy/spacing issues
+   - CTA flow weaknesses
+   - responsive/accessibility concerns
+   - missing empty/error/loading/success states
+
+### Mode: system
+
+Use to generate or update design tokens and component behavior rules.
+
+**Process:**
+1. Delegate to `@design` with `design-system-definition`
+2. Generate/update token guidance and component rules
+3. Save summary in planning state `design_artifact.design_tokens_guidance`
+
+## Enforcement Notes
+
+- UI-heavy tasks must complete design approval before `/fd-execute`, unless `--override` is explicitly provided and logged
+- Backend-only/infrastructure-only tasks skip this command
+
+## Output / State
+
+- `design_artifact` persisted in planning state
+- `requires_design_first: true` set in STATE.md
+- `design_stage: handoff_complete` when draft complete
+- `design_approved: true` when approval criteria met
+
+## Examples
+
+**Draft a new UI:**
+```
+/fd-design "Create a user profile page with avatar upload and bio editing"
+```
+
+**Review implemented UI against design:**
+```
+/fd-design --mode=review
+```
+
+**Generate design system tokens:**
+```
+/fd-design --mode=system
+```
+
+**Bypass design (with explicit logging):**
+```
+/fd-design "Quick UI change" --override
+```
+
+## Related Commands
+
+- `/fd-execute` — implementation (must wait for design approval for UI-heavy tasks)
+- `/fd-discuss` — explore design requirements before starting
+- `/fd-plan` — plan the implementation after design is approved
+- `/fd-quick` — run full workflow including design for UI-heavy tasks

package/docs/commands/fd-discuss.md

@@ -1,28 +1,95 @@
----
-description: Start a structured requirements discussion using FlowDeck. Extracts decisions and saves to .planning/phases/phase-N/DISCUSS.md
-argument-hint: "[phase-number]"
----
+# /fd-discuss
 
-Load the FlowDeck discuss workflow for the current (or specified) phase.
+**Purpose:** Structured pre-planning Q&A to capture decisions about scope, constraints, acceptance criteria, risks, and UI classification — saves decisions to DISCUSS.md with D-XX numbering.
 
-**What this does:**
-1. Reads `.planning/STATE.md` to determine the current phase
-2. Scouts the codebase for relevant context (existing patterns, affected files)
-3. Surfaces key decisions that need to be made for this phase
-4. Guides you through answering them via conversation
-5. Saves decisions to `.planning/phases/phase-N/DISCUSS.md`
+## Usage
 
-**Output:** A DISCUSS.md file with locked decisions that guide the planner and coder.
+/fd-discuss [topic]
 
-**Next step after this:** Run `/fd-plan` to create the implementation plan.
+## What Happens
 
-## What Next?
+1. **Pre-flight checks.**
+   - Verify `.planning/STATE.md` exists (error: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature.")
+   - Read current phase N from STATE.md
+   - Create `.planning/phases/phase-<N>/` directory if needed
 
-After discussion completes, choose your next step:
+2. **CodeGraph intelligence check.**
+   - Run `codegraph action=check`
+   - If indexed and fresh: use `codegraph_context`, `codegraph_search`, `codegraph_explore` for preflight exploration
+   - If stale or unavailable: fall back to `@code-explorer` for codebase exploration
+   - Log which mode is active
 
-1. **Create implementation plan** → `/fd-plan [phase-number]`
-2. **Continue discussion** → `/fd-discuss [phase-number]`
-3. **Review existing work** → `/fd-verify`
-4. **Check project dashboard** → `/fd-dashboard`
+3. **Autonomous codebase exploration (before any questions).**
+   - Inspect PROJECT.md, STATE.md, prior DISCUSS.md files, tech stack manifests, src/ structure, and AGENTS.md/rules
+   - Skip questions whose answers are already determinable from the codebase
+   - Apply question guard: suppress any question answered by existing evidence
 
-Type the number or the command to proceed.
+4. **Invoke @discusser agent.**
+   - Agent receives project context, current phase, and full preflight exploration findings
+   - Asks one question per turn using the RecommendedQuestion format
+   - Each question is validated with `parseQuestionBlocks()` and `validateRecommendedQuestion()` before presentation
+
+5. **Q&A loop.**
+   - Questions presented one at a time covering: Scope, Constraints, Acceptance Criteria, Risks, UI Classification
+   - Each answer is assigned a D-XX decision number and recorded with topic, choice, and rationale
+   - Conflicts with prior decisions are flagged
+   - Loop continues until all topics covered or user says to stop early
+
+6. **Write DISCUSS.md.**
+   - Saves to `.planning/phases/phase-<N>/DISCUSS.md`
+   - Includes D-XX numbered decisions, suppressed questions (with evidence source), open questions, and next steps
+   - If UI-heavy, suggests `/fd-design --mode=draft` before `/fd-execute`
+
+## Output / State
+
+File created:
+- `.planning/phases/phase-<N>/DISCUSS.md`
+
+DISCUSS.md structure:
+```markdown
+# Discussion: <topic>
+
+**Phase:** <N>
+**Date:** <timestamp>
+**Topic:** <topic>
+
+## Preflight Evidence Used
+- Tech stack: <detected>
+- Questions suppressed by evidence: <N>
+
+## Decisions
+D-01: [Topic] — [Decision] ([Rationale])
+...
+
+## Answered Recommendations
+RQ-01: [question] | User choice: [answer] | Rationale: [why]
+
+## Suppressed Questions
+"<question>" → answered by: <evidence source>
+
+## Open Questions
+- <unresolved items>
+
+## Next Steps
+- Run /fd-plan to create implementation plan
+```
+
+## Examples
+
+```
+/fd-discuss user authentication
+```
+
+Runs a structured discussion on "user authentication", exploring scope, constraints, acceptance criteria, risks, and UI classification.
+
+```
+/fd-discuss
+```
+
+Runs a discussion with no pre-selected topic.
+
+## Related Commands
+
+- `/fd-new-feature` — define the feature before discussing
+- `/fd-plan` — create implementation plan from DISCUSS.md decisions
+- `/fd-design` — draft UI designs if the feature is UI-heavy