@dv.nghiem/flowdeck 0.3.8 → 0.4.0

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

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