@dv.nghiem/flowdeck 0.1.0

package/docs/best-practices.md

@@ -0,0 +1,47 @@
+# FlowDeck Best Practices
+
+Maximize the efficiency and safety of your AI-driven development by following these best practices.
+
+---
+
+## 1. Spec-Driven Discipline
+
+**Don't skip the planning phase.** FlowDeck strictly enforces phase gating to prevent agents from writing code before requirements are finalized.
+- Use `/fd-discuss` to capture edge cases and constraints early.
+- Use `/fd-plan` to break complex features into manageable waves.
+- **Tip**: If you must make an emergency edit, run `/fd-settings` to temporarily advance the phase to `execute`, but remember to return to `plan` if you are still designing.
+
+## 2. The Power of the Council
+
+When faced with ambiguity, don't rely on a single agent.
+- Use `/fd-council` for high-level design choices.
+- The synthesis provided by the council often catches security or performance risks that a single "coder" agent might miss.
+
+## 3. Grounding with Hierarchical Context
+
+AI agents perform better when they have clear, localized context.
+- Keep an `AGENTS.md` file in each major directory.
+- Use `context-generator` to keep these files up to date with your current `ROADMAP.md` and `STATE.md`.
+- Include "Forbidden Paths" and "Tech Stack" details to prevent agents from using incompatible libraries.
+
+## 4. Reliable Edits
+
+In multi-agent sessions, files can change rapidly.
+- Encourage your agents to use `fd-hash-edit`.
+- By anchoring edits to specific content hashes, you eliminate the "stale line" problem where an agent overwrites a change made by another agent seconds earlier.
+
+## 5. Failure Replay as a Learning Loop
+
+When a bug is fixed, use the failure replay engine.
+- FlowDeck records failure patterns to suggest new policies.
+- **Tip**: Regularly review `/fd-dashboard` to see recurring failure zones and add them to `.codebase/CONSTRAINTS.md` to prevent future regressions.
+
+## 6. Infrastructure & Environment Health
+
+Before running a heavy implementation wave (e.g., `/fd-new-feature`):
+- Run `/fd-doctor` to ensure all plugins and MCPs are active.
+- Check the **Context Window Monitor** in your session logs. If you are above 80% usage, run a checkpoint and start a fresh session to avoid context truncation.
+
+---
+
+← [Back to Index](index.md)

package/docs/command-migration.md

@@ -0,0 +1,175 @@
+# Command Architecture & Migration Guide
+
+FlowDeck v2 consolidates seven individual analysis commands into four umbrella commands, reducing the top-level command surface while keeping all capabilities. The 15 workflow commands remain as separate top-level slash commands.
+
+---
+
+## Command Map
+
+### Workflow commands (unchanged — 15 total)
+
+These remain as separate top-level commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/fd-new-project` | Bootstrap a new project |
+| `/fd-map-codebase` | Analyse and index the codebase |
+| `/fd-settings` | Configure FlowDeck settings |
+| `/fd-discuss` | Pre-planning discussion with impact radar |
+| `/fd-plan` | Generate a phase plan |
+| `/fd-roadmap` | View / update project roadmap |
+| `/fd-dashboard` | Visual progress dashboard |
+| `/fd-ask` | Smart agent dispatch |
+| `/fd-new-feature` | Implement a new feature |
+| `/fd-fix-bug` | Fix a bug with failure replay |
+| `/fd-review-code` | Code review with impact radar |
+| `/fd-write-docs` | Generate documentation |
+| `/fd-deploy-check` | Pre-deploy safety check |
+| `/fd-progress` | View project progress |
+| `/fd-checkpoint` | Save a session checkpoint |
+| `/fd-resume` | Resume from checkpoint |
+| `/fd-multi-repo` | Multi-repo management |
+
+### Analysis commands — old → new mapping
+
+| Old command | New umbrella command | Flag |
+|-------------|---------------------|------|
+| `/fd-impact-radar` | `/fd-analyze-change` | `--impact` |
+| `/fd-blast-radius` | `/fd-analyze-change` | `--blast-radius` |
+| `/fd-regression-predict` | `/fd-analyze-change` | `--regression` |
+| `/fd-test-gap` | `/fd-analyze-change` | `--test-gap` |
+| `/fd-volatility-map` | `/fd-analyze-change` | `--volatility` |
+| `/fd-review-route` | `/fd-analyze-change` | `--review-route` |
+| `/fd-translate-intent` | `/fd-translate-intent` | *(enhanced, kept as-is)* |
+| *(new)* | `/fd-guarded-edit` | — |
+| *(new)* | `/fd-evaluate-risk` | — |
+
+### New umbrella commands (4 total)
+
+| Command | Replaces / Adds |
+|---------|----------------|
+| `/fd-analyze-change` | Combines 6 analysis commands; `--all` runs all modules |
+| `/fd-guarded-edit` | New — edit gate decision (auto/confirm/review/block) |
+| `/fd-evaluate-risk` | New — standalone risk + regression assessment |
+| `/fd-translate-intent` | Enhanced — adds `assumptions`, `recommended_option`, `clarifying_questions` |
+
+---
+
+## Architecture
+
+### Command layer
+
+Commands are thin entry points that dispatch to agent pipelines or shared utilities. No analysis logic lives inside command files.
+
+```
+User runs: /fd-analyze-change --change "..." --impact --regression
+     ↓
+analyzeChangeCommand.execute()
+     ↓
+  reads: VOLATILITY.json, FAILURES.json, MEMORY.json via shared libs
+  calls: runImpactRadar(), scorePatch()
+     ↓
+  returns: unified config object with agent pipeline + aggregated data
+```
+
+### Agent layer
+
+Agents are modular and reusable across commands:
+
+| Agent | Used by |
+|-------|---------|
+| `architect` | `/fd-analyze-change`, `/fd-translate-intent`, `/fd-plan` |
+| `researcher` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-discuss` |
+| `tester` | `/fd-analyze-change` |
+| `reviewer` | `/fd-analyze-change`, `/fd-evaluate-risk`, `/fd-review-code` |
+| `security-auditor` | `/fd-evaluate-risk` (high/critical risk), `/fd-review-code` |
+| `risk-analyst` | `/fd-evaluate-risk`, `/fd-guarded-edit` |
+| `policy-enforcer` | `/fd-guarded-edit` |
+
+### Plugin hooks
+
+Hooks intercept tool execution and enforce safety policies at the infrastructure layer:
+
+| Hook | Function |
+|------|---------|
+| `tool.execute.before` | `toolGuardHook` — blocks dangerous read/write/bash/edit |
+| `tool.execute.before` | `guardRailsHook` — enforces execution mode (auto/guarded/review-only) |
+| `tool.execute.before` | `patchTrustHook` — scores writes/edits; blocks high-risk without approval |
+| `tool.execute.before` | `decisionTraceHook` — records every edit to DECISIONS.jsonl |
+| `session.started` | `sessionStartHook` — announces FlowDeck, loads context |
+| `command.execute.before` | Command routing — dispatches slash commands |
+
+### Shared libraries
+
+Reusable utilities consumed by multiple commands:
+
+| Module | Exports |
+|--------|---------|
+| `src/lib/impact-radar.ts` | `runImpactRadar()`, `impactRadarSummaryLines()`, `lookupPriorFailures()` |
+| `src/hooks/patch-trust.ts` | `scorePatch()` |
+| `src/hooks/guard-rails.ts` | `resolveExecutionMode()` |
+| `src/hooks/tool-guard.ts` | `checkArchConstraint()`, `isBlocked()` |
+| `src/tools/planning-state-lib.ts` | `statePath()`, `codebaseDir()`, `readPlanningState()`, `timestamp()` |
+
+### Data files (`.codebase/`)
+
+| File | Purpose |
+|------|---------|
+| `MEMORY.json` | Architecture graph — modules, ownership, types |
+| `FAILURES.json` | Failure history — root causes, tags, recurrence counts |
+| `DECISIONS.jsonl` | Append-only edit audit log |
+| `VOLATILITY.json` | Churn metrics — stability ratings per path |
+| `POLICIES.json` | Self-healing policy rules |
+| `CONSTRAINTS.md` | Forbidden paths and architectural boundaries |
+| `ARCHITECTURE.md` | High-level architecture notes (written by `/fd-map-codebase`) |
+| `STACK.md` | Technology stack reference |
+
+---
+
+## Migration Plan
+
+### For existing users
+
+**All old commands still work.** No action required. Old commands were not removed.
+
+**When to migrate:**
+
+| If you used to run | Now prefer |
+|-------------------|-----------|
+| `/fd-impact-radar --change "..."` | `/fd-analyze-change --change "..." --impact` |
+| Multiple analysis commands in sequence | `/fd-analyze-change --change "..." --all` |
+| Manual pre-edit risk assessment | `/fd-evaluate-risk --change "..." --file "..."` |
+| Manually deciding whether to apply a change | `/fd-guarded-edit --file "..." --change "..."` |
+| `/fd-translate-intent --intent "..."` | Same — now returns `assumptions` and `recommended_option` |
+
+### Quick start for new workflows
+
+**Before any significant edit:**
+```bash
+# 1. Translate vague intent to concrete options
+/fd-translate-intent --intent "make checkout faster"
+
+# 2. Full pre-change analysis
+/fd-analyze-change --change "add Redis cache for checkout queries"
+
+# 3. Gate decision for the specific file
+/fd-guarded-edit --file "src/checkout/query.ts" --change "add Redis cache layer"
+```
+
+**In CI/CD pipelines:**
+```bash
+# Risk gate — fail if approval required
+/fd-evaluate-risk --change "<PR description>" --json | jq '.approval_needed'
+
+# Edit gate — fail if block decision
+/fd-guarded-edit --file "<changed file>" --json | jq '.decision == "block"'
+```
+
+---
+
+## Backward compatibility notes
+
+- All 7 original intelligence commands (`/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, `/fd-review-route`, `/fd-translate-intent`) remain registered and functional.
+- Their implementations were not modified (except `/fd-translate-intent` which gained `assumptions`, `recommended_option`, and `clarifying_questions` in its output spec).
+- The new umbrella commands are registered alongside the old ones — no commands were removed.
+- Existing scripts, keybindings, or workflows that call the old commands will continue to work without changes.

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

@@ -0,0 +1,107 @@
+# /fd-analyze-change
+
+**Umbrella analysis command** — runs up to 6 analysis modules in a single pass and produces a consolidated pre-change risk report.
+
+Replaces individual calls to `/fd-impact-radar`, `/fd-blast-radius`, `/fd-regression-predict`, `/fd-test-gap`, `/fd-volatility-map`, and `/fd-review-route`.
+
+---
+
+## Usage
+
+```
+/fd-analyze-change --change "<what's changing>" [flags]
+```
+
+## Arguments
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--change` | string | — | Description of the proposed change |
+| `--scope` | string | `"all"` | Module or file path scope |
+| `--files` | string | — | Comma-separated file paths |
+| `--depth` | number | `2` | Blast radius traversal depth |
+| `--impact` | boolean | false | Run impact radar module |
+| `--blast-radius` | boolean | false | Run blast radius module |
+| `--regression` | boolean | false | Run regression prediction module |
+| `--test-gap` | boolean | false | Run test gap detection module |
+| `--volatility` | boolean | false | Run volatility map module |
+| `--review-route` | boolean | false | Run reviewer routing module |
+| `--all` | boolean | false | Force all modules (default when no module flags given) |
+| `--json` | boolean | false | Return raw JSON instead of table |
+
+**Default behaviour:** If no module flags are specified, all 6 modules run automatically.
+
+---
+
+## Output
+
+```
+════════════════════════════════════════════════════════════════
+fd-analyze-change
+────────────────────────────────────────────────────────────────
+  Change:   update JWT token expiry
+  Scope:    all
+  Modules:  impact-radar, blast-radius, regression-predict, test-gap, volatility-map, review-route
+────────────────────────────────────────────────────────────────
+  ⚠ Affected zones:   src/auth/, src/session/, src/middleware/
+  ⚠ Known failures:   F-023, F-031
+  ≈ Regression cats:  auth, performance, async-flow...
+  ✗ Test gap types:   5 gap patterns checked
+  → Route to:          security, backend
+────────────────────────────────────────────────────────────────
+  ⚠ HIGH RISK: 3 volatile zone(s), 2 known failure(s), 1 fragile pattern(s)
+════════════════════════════════════════════════════════════════
+```
+
+### Top-level fields returned
+
+| Field | Description |
+|-------|-------------|
+| `modules_run` | Which analysis modules were executed |
+| `affected_zones` | Volatile/critical file paths matching the change |
+| `recommended_reviewers` | Reviewer types suggested (security, backend, infra, etc.) |
+| `risk_summary` | Human-readable risk advisory |
+| `risk_score` | Numeric score 0–100 (higher = lower risk) |
+| `config` | Full agent pipeline config dispatched to agents |
+
+---
+
+## Examples
+
+```bash
+# Full analysis before editing auth middleware
+/fd-analyze-change --change "replace JWT with session tokens" --files "src/auth/token.ts"
+
+# Impact + regression only (partial analysis)
+/fd-analyze-change --change "refactor database connection pool" --impact --regression
+
+# JSON output for scripting
+/fd-analyze-change --change "update payment webhook handler" --json
+
+# Deep blast radius (3 levels)
+/fd-analyze-change --change "extract user service" --blast-radius --depth 3
+```
+
+---
+
+## Old commands (still supported)
+
+These individual commands remain available and still work. Use `/fd-analyze-change` for combined analysis:
+
+| Old command | Equivalent flag |
+|-------------|----------------|
+| `/fd-impact-radar` | `--impact` |
+| `/fd-blast-radius` | `--blast-radius` |
+| `/fd-regression-predict` | `--regression` |
+| `/fd-test-gap` | `--test-gap` |
+| `/fd-volatility-map` | `--volatility` |
+| `/fd-review-route` | `--review-route` |
+
+---
+
+## Agents dispatched
+
+- `researcher` — traces dependency graph from changed paths
+- `architect` — maps blast radius to configured depth, flags integration points
+- `tester` — estimates coverage gaps per regression category and test gap types
+- `reviewer` — ranks gaps by risk and confirms routing

package/docs/commands/fd-ask.md

@@ -0,0 +1,51 @@
+---
+description: Smart dispatch — routes a free-form task to the appropriate specialized agent without requiring a workflow
+argument-hint: "--task '<description>'"
+---
+
+Route a free-form task to the best specialized agent automatically.
+
+**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
+
+**Routing table:**
+
+| 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 | `@coder` |
+| document, docs, README | `@writer` |
+| explain, query, find, explore | `@code-explorer` |
+| deploy, release, migration | `@reviewer` |
+| plan, roadmap, breakdown | `@planner` |
+| (anything else) | `@orchestrator` |
+
+**Examples:**
+
+```
+/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"
+```
+
+**Override routing:** Use `--agent` to force a specific agent.
+
+## What Next?
+
+After `/fd-ask` completes, you can go deeper:
+
+1. **Full workflow** → `/fd-fix-bug`, `/fd-new-feature`, `/fd-review-code`
+2. **Detailed planning** → `/fd-discuss`, `/fd-plan`
+3. **Another question** → `/fd-ask --task '...'`

package/docs/commands/fd-checkpoint.md

@@ -0,0 +1,10 @@
+---
+description: Save current state to STATE.md — safe to close session after this
+---
+Run the FlowDeck checkpoint command to save the current project state.
+
+## What Next?
+
+1. **Continue working** → `/fd-new-feature [description]`
+2. **View progress** → `/fd-progress`
+3. **Check dashboard** → `/fd-dashboard`

package/docs/commands/fd-dashboard.md

@@ -0,0 +1,11 @@
+---
+description: Open project dashboard — displays phase progress, milestones, and blockers
+---
+Run the FlowDeck dashboard to view project progress.
+
+## What Next?
+
+1. **Start feature work** → `/fd-new-feature [description]`
+2. **Fix a bug** → `/fd-fix-bug [issue]`
+3. **View roadmap** → `/fd-roadmap`
+4. **Check progress** → `/fd-progress`

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

@@ -0,0 +1,11 @@
+---
+description: Pre-deploy check — parallel tester + reviewer + CVE scan — orchestrator go/no-go decision
+---
+Run the FlowDeck deploy-check workflow before deploying to production.
+
+## What Next?
+
+1. **Fix blocking issues** → `/fd-fix-bug [issue]`
+2. **Create deployment checkpoint** → `/fd-checkpoint`
+3. **Review code again** → `/fd-review-code`
+4. **View project roadmap** → `/fd-roadmap`

package/docs/commands/fd-discuss.md

@@ -0,0 +1,28 @@
+---
+description: Start a structured requirements discussion using FlowDeck. Extracts decisions and saves to .planning/phases/phase-N/DISCUSS.md
+argument-hint: "[phase-number]"
+---
+
+Load the FlowDeck discuss workflow for the current (or specified) phase.
+
+**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`
+
+**Output:** A DISCUSS.md file with locked decisions that guide the planner and coder.
+
+**Next step after this:** Run `/fd-plan` to create the implementation plan.
+
+## What Next?
+
+After discussion completes, choose your next step:
+
+1. **Create implementation plan** → `/fd-plan [phase-number]`
+2. **Continue discussion** → `/fd-discuss [phase-number]`
+3. **Review existing work** → `/fd-review-code`
+4. **Check project dashboard** → `/fd-dashboard`
+
+Type the number or the command to proceed.

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

@@ -0,0 +1,134 @@
+# /fd-evaluate-risk
+
+**Standalone risk assessment command** — estimates change risk, confidence, likely regression categories, and whether human approval is needed before proceeding.
+
+Works with a change description alone (keyword-based) or with a specific file path (trust score + keyword combined).
+
+---
+
+## Usage
+
+```
+/fd-evaluate-risk --change "<description>" [--file "<path>"] [flags]
+```
+
+## Arguments
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--change` | string | — | Plain-language description of the proposed change |
+| `--file` | string | — | Specific file being changed (enables patch trust scoring) |
+| `--volatility` | boolean | true | Include volatile zone count in analysis |
+| `--json` | boolean | false | Return raw JSON instead of table |
+
+At least one of `--change` or `--file` is required.
+
+---
+
+## Risk levels
+
+| Level | Score | Meaning |
+|-------|-------|---------|
+| `low` | 80–100 | Safe to proceed without approval |
+| `medium` | 50–79 | Proceed with care; review recommended |
+| `high` | 25–49 | Approval required; consider safer alternative |
+| `critical` | 0–24 | Approval required; safer alternative strongly recommended |
+
+**Approval is required when:** `risk_score < 60` OR `≥3 regression categories predicted`.
+
+---
+
+## Output
+
+```
+════════════════════════════════════════════════════════════
+fd-evaluate-risk
+────────────────────────────────────────────────────────────
+  Change:      replace JWT with session tokens
+  File:        src/auth/token.ts
+────────────────────────────────────────────────────────────
+  ⚠ Risk level:  HIGH (score: 38/100)
+  Confidence:  72/100 (codebase context coverage)
+  Approval:    REQUIRED
+  Regressions: auth, security, async-flow
+  Hot zones:   src/auth/
+  Signals:     volatile path, auth keyword
+────────────────────────────────────────────────────────────
+  Safer alt:   Consider a feature-flag rollout before swapping auth tokens
+────────────────────────────────────────────────────────────
+  researcher → map to affected paths
+  reviewer   → validate risk + regressions
+  security   → targeted review of high-risk areas
+════════════════════════════════════════════════════════════
+```
+
+### Fields returned
+
+| Field | Description |
+|-------|-------------|
+| `risk_score` | 0–100 (higher = less risky) |
+| `risk_level` | low / medium / high / critical |
+| `confidence` | 0–100 (how much codebase context data exists) |
+| `approval_needed` | boolean — whether human approval is required |
+| `likely_regressions` | predicted regression categories from change keywords |
+| `volatile_zones` | count of volatile/critical zones in the repo |
+| `volatile_matches` | paths that match the change description |
+| `safer_alternative` | suggested safer approach if risk is high/critical |
+| `trust_signals` | risk signals from the patch trust scorer |
+
+---
+
+## Regression categories detected
+
+| Category | Triggered by keywords |
+|----------|----------------------|
+| performance | slow, latency, cache, query, index, bulk, batch, load |
+| auth | auth, token, session, jwt, oauth, permission, rbac, login |
+| schema | schema, migration, column, table, foreign key, constraint |
+| ui-state | state, redux, context, store, hook, render, component |
+| async-flow | async, await, promise, callback, event, queue, worker |
+| api-contract | api, endpoint, route, request, response, payload, version |
+| data-integrity | transaction, rollback, constraint, unique, required, nullable |
+| security | secret, password, encrypt, decrypt, hash, sanitize |
+| config | env, config, setting, flag, feature flag, toggle |
+| i18n | locale, translation, i18n, format, timezone, language |
+
+---
+
+## Confidence score
+
+Confidence reflects how much codebase context data the system has:
+
+| Data source | Points |
+|-------------|--------|
+| `.codebase/ARCHITECTURE.md` exists | +20 |
+| `.codebase/STACK.md` exists | +10 |
+| `.codebase/MEMORY.json` node count | up to +25 |
+| `.codebase/VOLATILITY.json` entries | up to +15 |
+| `.codebase/FAILURES.json` entries | up to +10 |
+| Base | +20 |
+
+Run `/fd-map-codebase` and let FlowDeck index the repo to increase confidence.
+
+---
+
+## Examples
+
+```bash
+# Keyword-based risk estimate
+/fd-evaluate-risk --change "refactor JWT auth to use session tokens"
+
+# File + change (enables patch trust scoring)
+/fd-evaluate-risk --change "update stripe webhook" --file "src/payment/webhook.ts"
+
+# JSON output for CI decision gates
+/fd-evaluate-risk --change "drop users table column" --json
+```
+
+---
+
+## Agents dispatched
+
+- `researcher` — maps change description to affected modules and paths
+- `reviewer` — validates risk level and regression predictions
+- `security-auditor` — targeted review (only when risk is high or critical)

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

@@ -0,0 +1,24 @@
+---
+description: Debug and fix a bug — scope analysis, mini-plan, coder fix, regression test, reviewer confirmation
+argument-hint: "[bug description or issue number]"
+---
+
+Systematically debug and fix a bug using FlowDeck's structured approach.
+
+**What this does:**
+1. Reads `.codebase/` for architecture context
+2. Delegates to `@debug-specialist` to locate the root cause
+3. Creates a mini-plan (fix + regression test)
+4. Delegates fix to `@coder`
+5. Delegates regression test writing to `@tester`
+6. Verifies the fix via `@reviewer`
+7. Writes a brief post-mortem to `.planning/bugs/`
+
+**Root cause first:** Does not implement a fix until root cause is confirmed — no symptom masking.
+
+## What Next?
+
+1. **Run code review** → `/fd-review-code`
+2. **Check for more bugs** → `/fd-fix-bug [next-issue]`
+3. **Update documentation** → `/fd-write-docs`
+4. **Deploy check** → `/fd-deploy-check`