@dv.nghiem/flowdeck 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,6 +17,7 @@
   "files": [
     "dist",
     "bin",
+    "src/commands",
     "src/rules",
     "src/skills",
     "src/workflows",

package/src/commands/fd-analyze-change.md

@@ -0,0 +1,57 @@
+---
+description: Pre-change analysis — runs impact radar, blast radius, regression prediction, test gaps, volatility, and reviewer routing in one report
+argument-hint: [change description]
+---
+
+# Analyze Change
+
+Run a comprehensive pre-change analysis combining all intelligence tools into a single report.
+
+**Input:** $ARGUMENTS — description of the proposed change
+
+## Steps
+
+Run all analyses in parallel:
+
+1. **Impact Radar** — which files/APIs/tests are affected (see `/fd-impact-radar`)
+2. **Blast Radius** — downstream consequences and hidden couplings (see `/fd-blast-radius`)
+3. **Regression Predict** — most likely regression categories (see `/fd-regression-predict`)
+4. **Test Gap** — coverage gaps to fill before implementing (see `/fd-test-gap`)
+5. **Volatility** — check `.codebase/VOLATILITY.json` for hotspot scores on affected files
+6. **Review Route** — who should review this change (see `/fd-review-route`)
+
+## Consolidated 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>
+════════════════════════════════════════════════════
+```

package/src/commands/fd-approve.md

@@ -0,0 +1,64 @@
+---
+description: Manage approval requests — list pending approvals, approve or reject a request by ID
+argument-hint: [list | approve <id> | reject <id> [reason]]
+---
+
+# Approve
+
+Manage approval requests for guarded changes.
+
+**Input:** $ARGUMENTS
+
+## Behavior
+
+### List Pending (`list` or no arguments)
+
+Read `.planning/approvals.json`. Display all pending approval requests:
+
+```
+════════════════════════════════════════
+PENDING APPROVALS
+════════════════════════════════════════
+ID       | Change                    | Risk  | Requested
+---------|---------------------------|-------|----------
+APR-001  | Edit auth middleware       | HIGH  | <time>
+APR-002  | Update DB migration       | MED   | <time>
+════════════════════════════════════════
+Use: /fd-approve approve <ID>  or  /fd-approve reject <ID> [reason]
+```
+
+If no pending approvals: "No pending approvals."
+
+### Approve (`approve <ID>`)
+
+1. Read `.planning/approvals.json`
+2. Find approval with matching ID
+3. Update status to `approved`, set `approved_at` timestamp
+4. Write updated file
+5. Report: "APR-XXX approved. Change may proceed."
+
+### Reject (`reject <ID> [reason]`)
+
+1. Find approval with matching ID
+2. Update status to `rejected`, set `rejected_at` and `reason`
+3. Report: "APR-XXX rejected. Reason: <reason>."
+
+## Approval File Format
+
+`.planning/approvals.json`:
+```json
+{
+  "approvals": [
+    {
+      "id": "APR-001",
+      "change": "<description>",
+      "risk_score": 0.8,
+      "requested_at": "<timestamp>",
+      "status": "pending|approved|rejected",
+      "approved_at": null,
+      "rejected_at": null,
+      "reason": null
+    }
+  ]
+}
+```

package/src/commands/fd-ask.md

@@ -0,0 +1,39 @@
+---
+description: Ask a specialist agent a focused question — routes to architect, security, performance, or impact analyst
+argument-hint: [question]
+---
+
+# Ask
+
+Route a focused question to the most appropriate specialist agent.
+
+**Input:** $ARGUMENTS — your question
+
+## Routing
+
+Analyze `$ARGUMENTS` to determine the best specialist:
+
+| Keywords / Topic | Agent |
+|-----------------|-------|
+| 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** |
+
+## Process
+
+1. Identify the best specialist from the table above.
+2. Delegate `$ARGUMENTS` to that specialist with full context:
+   - Include `.codebase/ARCHITECTURE.md` if available and relevant
+   - Include `.planning/STATE.md` phase context if relevant
+3. Return the specialist's answer directly.
+
+## Output
+
+Present the answer clearly with:
+- Which specialist answered
+- The answer (no padding, no ceremony)
+- Any follow-up suggestions if the question opens further threads

package/src/commands/fd-blast-radius.md

@@ -0,0 +1,49 @@
+---
+description: Blast Radius Preview — show downstream consequences of a proposed change including hidden dependencies and fragile integration points
+argument-hint: [change description] [--depth=N]
+---
+
+# Blast Radius
+
+Map the full downstream blast radius of a proposed change.
+
+**Input:** $ARGUMENTS — description or file path of the proposed change. Optional `--depth=N` (default: 3).
+
+## Steps
+
+Run two agents in parallel:
+
+- **@architect**: Trace dependency graph to depth `--depth` (default 3 levels); flag integration points, event listeners, shared state, and service-to-service calls that would be affected
+
+- **@researcher**: Identify hidden couplings — shared config values, environment variables, database tables, message queue topics, and implicit conventions that the changed code relies on
+
+## Report
+
+```
+════════════════════════════════════════════
+BLAST RADIUS PREVIEW
+════════════════════════════════════════════
+Change: <summary>
+Depth: <N> levels
+
+Direct Impact (depth 1):
+  - <file/module> — <relationship>
+
+Indirect Impact (depth 2-3):
+  - <file/module> — <chain>
+
+Hidden Couplings:
+  - <coupling type>: <description>
+
+Fragile Integration Points:
+  - <point> — <why fragile>
+
+Risk Assessment:
+  Score: <0-10>
+  Level: <low|medium|high|critical>
+  
+  <1-2 sentence summary of the biggest risks>
+
+Recommended: <proceed | add tests | get review | redesign>
+════════════════════════════════════════════
+```

package/src/commands/fd-checkpoint.md

@@ -0,0 +1,46 @@
+---
+description: Force-save current state to STATE.md — safe to close session
+---
+
+# Checkpoint
+
+Save the current session state so work can be safely resumed later.
+
+## Steps
+
+1. Check `.planning/STATE.md` exists — if not, error: "No active project to checkpoint."
+
+2. Read current STATE.md content.
+
+3. Update STATE.md:
+   - Set `last_updated` to current timestamp
+   - Ensure `status` reflects current state accurately
+
+4. If `.planning/phases/phase-<N>/PLAN.md` exists, scan for completed steps and update STATE.md's `steps_complete` if tracked.
+
+5. Write a brief checkpoint summary to `.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">
+```
+
+6. Report:
+```
+✅ Checkpoint saved
+   Phase: <N> | Status: <status>
+   File: .planning/phases/phase-<N>/CHECKPOINT.md
+   Safe to close session. Resume with /fd-resume.
+```

package/src/commands/fd-dashboard.md

@@ -0,0 +1,57 @@
+---
+description: Open project dashboard in browser — displays phase progress, milestones, and blockers
+argument-hint: [--port=N]
+---
+
+# Dashboard
+
+Open the FlowDeck project dashboard.
+
+**Input:** $ARGUMENTS — optional `--port=N` (default: 3847)
+
+## Steps
+
+1. Check `.planning/STATE.md` exists — if not, error: "No active project. Run /fd-new-project first."
+
+2. Read project state from:
+   - `.planning/STATE.md` — current phase, status, progress
+   - `.planning/ROADMAP.md` — all phases and completion status
+   - `.planning/phases/phase-*/PLAN.md` — step completion per phase
+
+3. Try to start the dashboard server if not running:
+   ```bash
+   npx @dv.nghiem/flowdeck-dashboard --port <port> &
+   ```
+   Or if the package is installed, run:
+   ```bash
+   flowdeck-dashboard --port <port> &
+   ```
+
+4. If server cannot start, display a text-based dashboard instead:
+
+```
+════════════════════════════════════════════
+FLOWDECK DASHBOARD
+════════════════════════════════════════════
+Project: <name from PROJECT.md>
+Updated: <last_updated>
+
+ROADMAP
+  ✅ Phase 1: Setup           — completed
+  🔄 Phase 2: Core Feature    — in progress (3/7 steps)
+  ⏳ Phase 3: Polish          — planned
+
+CURRENT PHASE (2): Core Feature
+  ✅ Step 1: Set up database schema
+  ✅ Step 2: Create API endpoints
+  ✅ Step 3: Add authentication
+  ⬜ Step 4: Write tests
+  ⬜ Step 5: Write documentation
+
+BLOCKERS
+  - (none)
+════════════════════════════════════════════
+Run /fd-progress for detailed state view.
+```
+
+5. If server starts: report the URL: "Dashboard running at http://localhost:<port>"

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

@@ -0,0 +1,58 @@
+---
+description: Parallel tester + reviewer + researcher CVE check — orchestrator go/no-go deploy decision
+argument-hint: [--env=staging|production]
+---
+
+# Deploy Check
+
+Run a comprehensive pre-deploy validation to produce a go/no-go decision.
+
+**Input:** $ARGUMENTS — optional `--env=staging|production` (default: staging)
+
+## Parallel Checks
+
+Run three checks simultaneously:
+
+### Check 1 — Test Suite (@tester)
+- Run full test suite
+- Check TDD coverage meets threshold (default: 80%)
+- Report: tests passed/failed, coverage %, any flaky tests
+
+### Check 2 — Code Review (@reviewer)
+- 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
+
+## Go/No-Go Decision
+
+**@orchestrator** aggregates results:
+
+| 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) |
+
+## Report
+
+```
+════════════════════════════════════════════
+DEPLOY CHECK — <env>
+════════════════════════════════════════════
+Tests:    <passed>/<total> | Coverage: <X>%
+Security: <N> critical, <M> high
+CVEs:     <N> high, <M> medium
+
+DECISION: GO / NO-GO / CONDITIONAL
+════════════════════════════════════════════
+```
+
+For NO-GO: list blocking issues with fix suggestions.
+For CONDITIONAL: list what requires override approval.

package/src/commands/fd-discuss.md

@@ -0,0 +1,61 @@
+---
+description: Extract requirements via structured Q&A — saves decisions to .planning/phases/phase-N/DISCUSS.md with D-XX numbering
+argument-hint: [topic]
+---
+
+# Discuss
+
+Run a structured requirements discussion session and capture decisions.
+
+**Input:** $ARGUMENTS (optional topic to focus the discussion)
+
+## Pre-flight
+
+1. Check `.planning/STATE.md` exists — if not, return error: "Run /fd-new-project first."
+2. Read current phase from STATE.md.
+3. Create `.planning/phases/phase-<N>/` directory if it does not exist.
+
+## Discussion Process
+
+Act as `@discusser` — a requirements analyst. Ask the user focused questions about the topic: **$ARGUMENTS**
+
+Structure the discussion:
+
+1. **Scope** — What exactly needs to be built/changed? What is out of scope?
+2. **Constraints** — Technical constraints, deadlines, dependencies?
+3. **Acceptance criteria** — How will we know it's done?
+4. **Risks** — What could go wrong? Any known issues?
+
+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
+# Discussion: <topic>
+
+**Phase:** <N>
+**Date:** <timestamp>
+**Topic:** <topic>
+
+## Decisions
+
+D-01: <decision>
+D-02: <decision>
+...
+
+## Open Questions
+
+- <any unresolved items>
+
+## Next Steps
+
+- Run /fd-plan to create implementation plan from these decisions
+```
+
+## Completion
+
+Report: decisions captured, file path, and suggest running `/fd-plan`.

package/src/commands/fd-doctor.md

@@ -0,0 +1,37 @@
+---
+description: Check FlowDeck installation and environment health
+---
+
+# Doctor
+
+Run environment health checks and report status.
+
+## Checks
+
+1. **OpenCode CLI** — run `opencode --version`. Report version if found, warn if not found.
+
+2. **FlowDeck plugin registration** — read `~/.config/opencode/opencode.json` (or `$OPENCODE_CONFIG_DIR/opencode.json`). Check that `@dv.nghiem/flowdeck` is in the `plugin` array.
+
+3. **Workspace state** — check if `.planning/STATE.md` exists in the current directory. Warn (non-fatal) if missing.
+
+4. **Codebase map** — check if `.codebase/ARCHITECTURE.md` exists. Note if missing (suggest `/fd-map-codebase`).
+
+5. **Planning phases** — if STATE.md exists, parse the current phase and check that `.planning/phases/phase-N/` directory exists.
+
+## Output Format
+
+```
+# 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!
+```
+
+Use `[x]` for pass, `[ ]` for failure (blocks healthy), `[!]` for warning (non-blocking).
+
+Report `✅ Environment looks healthy!` if no failures, otherwise `❌ Some issues found.`

package/src/commands/fd-evaluate-risk.md

@@ -0,0 +1,62 @@
+---
+description: Risk assessment — estimates change risk, confidence, likely regressions, and whether approval is needed before proceeding
+argument-hint: [change description]
+---
+
+# Evaluate Risk
+
+Produce a risk assessment for a proposed change.
+
+**Input:** $ARGUMENTS — description of the proposed change
+
+## Steps
+
+Run two agents in parallel:
+
+- **@researcher**: Map `$ARGUMENTS` to affected paths and modules; check `.codebase/VOLATILITY.json` for hotspot scores; check `.codebase/FAILURES.json` for prior failures; identify external dependencies touched
+
+- **@reviewer**: Validate the risk assessment — verify risk level is calibrated correctly given the scope; flag any under-estimated risks; check if approval is warranted by active policies in `.planning/config.json`
+
+## Risk Dimensions
+
+| Dimension | Weight | Assessment |
+|-----------|--------|------------|
+| Volatility | 30% | hotspot score of affected files |
+| Blast radius | 25% | number of downstream dependents |
+| Prior failures | 25% | recurrences in FAILURES.json |
+| External deps | 20% | third-party APIs or services involved |
+
+## Approval Logic
+
+Approval required if:
+- `approval_required: true` in config
+- Overall risk score ≥ `volatility_threshold` (default 0.7)
+- Any touched file has 3+ prior failures
+
+## Report
+
+```
+════════════════════════════════════════════
+RISK ASSESSMENT
+════════════════════════════════════════════
+Change: <summary>
+
+Risk Score: <0.0–1.0> (<low|medium|high|critical>)
+Confidence: <high|medium|low>
+
+Breakdown:
+  Volatility:    <score> (<rationale>)
+  Blast radius:  <score> (<N downstream>)
+  Prior failures: <score> (<N failures>)
+  External deps: <score> (<list or none>)
+
+Likely Regressions:
+  - <category>: <reason>
+
+Approval Required: <yes|no>
+  <if yes: reason and who should approve>
+
+Recommendation:
+  <proceed | add tests | get review | redesign>
+════════════════════════════════════════════
+```

package/src/commands/fd-fix-bug.md

@@ -0,0 +1,93 @@
+---
+description: TDD bug fix — explore → research → RED test → GREEN fix → REFACTOR → reviewer → record in FAILURES.json
+argument-hint: [bug description] [--scope=path]
+---
+
+# Fix Bug
+
+Fix a bug using the TDD red-green-refactor discipline.
+
+**Input:** $ARGUMENTS — description of the bug. Optional `--scope=<path>` to limit search scope.
+
+## Pre-flight
+
+1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+2. Parse `--scope` from arguments (default: entire codebase).
+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
+```
+
+### 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
+
+### Step 3: Define Behaviors
+
+Write acceptance cases describing the fix (what should happen after the bug is fixed).
+
+### Step 4: 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
+
+Confirm test fails. If it passes, the bug may already be fixed or the test is wrong.
+
+### Step 6: 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.**
+
+### Step 8: REFACTOR
+
+Clean up the implementation. Run tests again to confirm they still pass.
+
+### Steps 9-10: Full Suite
+
+Run the full test suite. All tests must pass.
+
+### Step 11: Review
+
+- **@reviewer**: Confirm fix is correct, no regressions, TDD discipline followed
+
+### Step 12: 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>"
+}
+```
+
+## Completion
+
+Report: root cause, fix applied, regression test location, reviewer sign-off.