@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/commands/fd-quick.md

@@ -1,35 +1,149 @@
----
-description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
-argument-hint: [task description]
----
-
-# Quick Task
-
-Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
-
-## Agent Selection Matrix
-
-| Task Type | Agent |
-|-----------|-------|
-| Backend code | @backend-coder |
-| Frontend code | @frontend-coder |
-| DevOps/infra code | @devops |
-| Explore/understand | @code-explorer |
-| Review code | @reviewer |
-| Security review | @security-auditor |
-| Design/architecture | @architect |
-| Write tests | @tester |
-| Documentation | @doc-updater |
-| Research | @researcher |
-| Debug | @debug-specialist |
-| Performance | @performance-optimizer |
-| Build error | @build-error-resolver |
+# /fd-quick
+
+**Purpose:** Focused autonomous task execution with automatic agent and workflow selection.
+
+## Usage
+
+/fd-quick [task description]
+
+## What Happens
+
+The command explores the codebase first, classifies the task, selects the appropriate workflow, and runs the full stage sequence end-to-end with minimal user input.
+
+### Step 0: Autonomous Preflight Exploration
+
+Before asking anything, invoke `@code-explorer` to inspect:
+1. Repository structure — `.planning/STATE.md`, `.planning/PROJECT.md`, `AGENTS.md`
+2. Available commands — enumerate `src/commands/*.md` filenames
+3. Available agents — enumerate `src/agents/*.ts` filenames
+4. Available skills — enumerate `src/skills/` directory names
+5. Workflow config — read `flowdeck.json` (governance, models)
+6. Tech stack — read `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+7. Implementation patterns — inspect `src/` top-level directories
+8. Prior decisions — check `.planning/phases/*/DISCUSS.md` files
+9. Relevant files — find source files matching keywords in the task description
+
+Store exploration snapshot in STATE.md under `quick_run.preflightExploration`.
+
+### Question Suppression Rule
+
+A question may only be forwarded to `@supervisor` if:
+1. It cannot be answered by the exploration evidence
+2. It has not already been asked in the current session
+3. It is required to safely select the correct workflow
+
+### Step 1: Classify the Task
+
+Use both text-signal matching and preflight exploration evidence via `classifyTaskWithContext()`.
+
+| Task Type | Strong Signal Keywords | Stage Sequence |
+|-----------|------------------------|----------------|
+| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause | `discuss → fix-bug → verify` |
+| **ui-feature** | landing page, dashboard, admin panel, app screen, wireframe, design system, ux flow | `discuss → design → plan → execute → verify` |
+| **docs** | docs, documentation, readme, api docs, usage guide | `discuss → write-docs → verify` |
+| **simple** | rename, move file, typo, update constant, bump version, one-liner | `execute → verify` |
+| **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
+| **ambiguous** | (short, vague, only after exploration cannot resolve) | *(clarify via supervisor)* |
+
+**Bug signals dominate**: if the description contains "fix", "bug", "error", "crash", "exception", "broken", or "regression", classify as `bugfix` even if it also mentions UI elements.
+
+### Step 2: Supervisor-Gated Clarification (only when exploration cannot resolve)
+
+If classification is `ambiguous` AND exploration evidence did not resolve it:
+1. Invoke `@supervisor` with the partial task description and preflight exploration snapshot
+2. `@supervisor` asks ONE clarifying question
+3. Wait for the answer
+4. Re-classify using combined description + answer
+
+### Step 3: Confirm Stage Sequence
+
+Present the classification and planned stage sequence before proceeding:
+```
+Task classified as: <task type>
+Stage sequence:     <stage-1> → <stage-2> → ... → <stage-N>
+Requires design:    <yes / no>
+Requires TDD:       <yes / no>
+Evidence used:      <N> 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.
+```
+
+Proceed automatically — do not wait for additional input unless approval is explicitly required.
+
+### Step 4: Execute Stage Sequence Autonomously
+
+For each stage in sequence:
+
+1. **Announce stage start**
+2. **Supervisor preflight review** — pass `taskDescription`, `currentPhase`, `prerequisitesMet`, `designApprovalPresent`, `regressionTestPresent`
+3. **Handle supervisor decision:**
+   - `approve` — proceed immediately
+   - `revise` — resolve listed required changes then re-run stage
+   - `block` — stop, report why, update `quick_run.outcome = blocked`
+   - `escalate` — pause, present reason to user, request explicit approval
+4. **Execute the stage** using its existing command with full context
+5. **Stage completion check** — invoke `@supervisor` (post-stage) to confirm valid output
+6. **Update STATE.md** with completed stages and supervisor decisions
+7. **Proceed to next stage**
+
+**Stage → Command Mapping:**
+
+| Stage | Command | Key Behavior |
+|-------|---------|--------------|
+| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Questions already answered by evidence are skipped. Saves `DISCUSS.md`. |
+| `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
+| `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
+| `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. |
+| `fix-bug` | `/fd-fix-bug` | TDD bugfix: explore → RED regression test → GREEN fix → REFACTOR → record in FAILURES.json. |
+| `write-docs` | `/fd-write-docs` | Explore APIs → `@writer` drafts → `@reviewer` accuracy check → finalize. |
+| `verify` | `/fd-verify` | Full verification: tests + code review + security scan + deploy check. Reports verdict. |
+
+### Step 5: Completion
+
+When all stages complete:
+1. Update STATE.md with `outcome: complete`
+2. Present final summary
+
+### Block / Failure Handling
+
+If execution cannot continue at any stage:
+1. Update STATE.md: `quick_run.outcome = blocked`
+2. Report blocked stage, reason, what's needed, and how to resume
+
+## Workflow Discipline (Non-Negotiable)
+
+- **Design-first**: `ui-feature` tasks MUST complete the `design` stage before `execute` can begin
+- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR
+- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM
+- **Regression test**: `fix-bug` requires a failing regression test before implementation
+- **Verify**: All workflows end with `/fd-verify`
+
+## Output / State
+
+All routing and execution progress recorded in `.planning/STATE.md` under `quick_run` key.
 
 ## Examples
 
+**Run a feature through full workflow:**
+```
+/fd-quick "Add user profile page with avatar upload"
+```
+
+**Fix a bug autonomously:**
+```
+/fd-quick "Fix the login timeout error that happens randomly"
 ```
-/fd-quick find where session validation happens
-/fd-quick add rate limiting to the API
+
+**Start a documentation task:**
 ```
+/fd-quick "Generate API documentation for the payment module"
+```
+
+## Related Commands
 
-**Note:** Use for small tasks only (~15 min). For larger work, use `/fd-new-feature`.
+- `/fd-discuss` — explore a topic manually
+- `/fd-plan` — plan manually
+- `/fd-execute` — execute manually
+- `/fd-status` — inspect current state and progress
+- `/fd-resume` — reload context after a session break

package/docs/commands/fd-reflect.md

@@ -1,23 +1,91 @@
----
-description: Post-session reflection and skill capture — analyse artifacts, propose improvements, capture session patterns
-argument-hint: [--mode=reflect,learn]
----
+# /fd-reflect
 
-# Reflect
+**Purpose:** Post-session reflection and skill capture — analyze session artifacts, propose improvements to FlowDeck's knowledge base, and optionally capture reusable skills from patterns discovered during the session.
 
-Post-session reflection to analyse artifacts and propose improvements, or capture learnings as reusable skills.
+## Usage
 
-## Modes
+/fd-reflect [--mode=reflect,learn]
 
-### Reflect (default)
-Analyzes session artifacts, proposes skills/policies/workflow changes.
+## What Happens
 
-### Learn (`--mode=learn`)
-Captures a repeatable pattern as a reusable FlowDeck skill.
+### Reflect Mode (default)
+
+1. **Gather artifacts.** Call the `reflect` tool to collect session artifacts and generate reflection context.
+
+2. **Analyze the session.**
+   - Which tools were called most often? Any redundant calls?
+   - Which decisions were made? Do they reveal a repeatable pattern?
+   - Were there failures? What caused them?
+   - What knowledge was absent and had to be worked out from scratch?
+
+3. **Produce improvement proposals.**
+   - **New skill** → call `create-skill` to capture it in `src/skills/`
+   - **Policy** → propose a new entry in `.codebase/POLICIES.json` for user review
+   - **Workflow change** → note it clearly for user to decide
+
+4. **Execute skill creation** for any new skills identified.
+
+5. **Final report.** Provide:
+   - What was captured (new skills created)
+   - What requires human review (policy proposals, workflow changes)
+   - 3-5 bullet summary of the session's most impactful learnings
+
+### Learn Mode (`--mode=learn`)
+
+1. **Identify worth capturing.** Look for:
+   - Novel problems requiring non-obvious solutions
+   - Patterns that needed human guidance to resolve
+   - Workflows or sequences that would save time if remembered
+   - Pitfalls that were hit and corrected
+
+   If nothing significant was found, reply: "No new patterns to capture from this session." and stop.
+
+2. **Draft the skill.** Structure as:
+   - `## When to Activate` — concrete triggers (e.g., "when X file pattern exists", "when user asks about Y")
+   - `## Steps` — ordered, concrete steps to apply the skill
+   - `## Examples` — at least one short concrete example
+   - `## Pitfalls` — common mistakes to avoid
+
+3. **Choose a name.** Use `$ARGUMENTS` if provided as skill name; otherwise derive a kebab-case name from the pattern.
+
+4. **Write the skill** using the `create-skill` tool with:
+   - `name`: kebab-case identifier
+   - `description`: one sentence summary
+   - `content`: full Markdown body
+   - `tags`: 2-4 relevant tags
+
+5. **Report** what was captured, why it is useful, and remind the user to restart OpenCode to activate it.
+
+## Output / State
+
+Files created (Learn mode):
+- `src/skills/<name>.md` — new skill file
+
+Files modified (Reflect mode):
+- `.codebase/POLICIES.json` — proposed policy entries (user review needed)
 
 ## Examples
 
 ```
 /fd-reflect
-/fd-reflect --mode=learn auth-pattern
-```
+```
+
+Run post-session reflection and produce improvement proposals.
+
+```
+/fd-reflect --mode=learn
+```
+
+Capture the most significant pattern from this session as a reusable skill.
+
+```
+/fd-reflect --mode=learn api-error-handling
+```
+
+Capture the session pattern as a skill named "api-error-handling".
+
+## Related Commands
+
+- `/fd-map-codebase` — map the codebase before starting a feature
+- `/fd-execute` — run implementation (reflection happens after)
+- `/fd-checkpoint` — save state before ending a session

package/docs/commands/fd-resume.md

@@ -1,10 +1,67 @@
----
-description: Resume from last checkpoint — reloads STATE.md and PLAN.md context
----
-Run the FlowDeck resume workflow to reload project context and continue from where you stopped.
+# /fd-resume
 
-## What Next?
+**Purpose:** Reload STATE.md, PLAN.md, and DISCUSS.md to continue an interrupted session — brief the user, PAUSE for confirmation, then resume from where work stopped.
 
-1. **Continue feature work** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`
+## Usage
+
+/fd-resume [--yes]
+
+## What Happens
+
+1. **Pre-flight check.**
+   - Verify `.planning/STATE.md` exists — error if not ("No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature.")
+
+2. **Read and parse STATE.md.** Extract phase, status, last_updated, plan_confirmed.
+
+3. **Read PLAN.md** (`.planning/phases/phase-<N>/PLAN.md`) if it exists — show preview (first 20 lines).
+
+4. **Read DISCUSS.md** (`.planning/phases/phase-<N>/DISCUSS.md`) if it exists — show decision count.
+
+5. **Present session summary:**
+
+```
+═══════════════════════════════════════════════
+RESUMING SESSION
+═══════════════════════════════════════════════
+Phase: <N>  |  Status: <status>
+Last updated: <timestamp>
+Plan confirmed: <yes/no>
+Decisions: <X> from DISCUSS.md
+
+Plan preview:
+<first 10 lines of PLAN.md>
+───────────────────────────────────────────────
+Type CONFIRM to resume execution from this point.
+═══════════════════════════════════════════════
+```
+
+6. **PAUSE for confirmation** (unless `--yes` is passed). Wait for user to type CONFIRM.
+
+7. **After confirmation:**
+   - If `plan_confirmed: true` and PLAN.md has uncompleted steps → proceed with implementation
+   - If no plan exists → suggest running `/fd-plan`
+   - Brief the user on what the next step is before starting
+
+## Output / State
+
+No new files created. Resumes from existing STATE.md and PLAN.md.
+
+## Examples
+
+```
+/fd-resume
+```
+
+Show session summary and wait for CONFIRM before resuming.
+
+```
+/fd-resume --yes
+```
+
+Skip confirmation and immediately resume from the last checkpoint.
+
+## Related Commands
+
+- `/fd-checkpoint` — save a checkpoint before closing a session
+- `/fd-plan` — create a plan if no PLAN.md exists to resume
+- `/fd-execute` — continue implementation (auto-triggered after CONFIRM)

package/docs/commands/fd-status.md

@@ -1,31 +1,99 @@
----
-description: View project status — combined status, roadmap, workspace overview, and progress
-argument-hint: [--roadmap | --workspace | --phase=N]
----
+# /fd-status
 
-# Status
+**Purpose:** View project progress, roadmap phase statuses, and workspace overview — combined status display with optional detailed flags.
 
-View project status combining progress, roadmap, and workspace overview.
+## Usage
 
-## Modes
+/fd-status [--roadmap | --workspace | --phase=N]
+
+## What Happens
 
 ### Default (no flags)
-Show current phase status summary from STATE.md.
+
+Reads `.planning/STATE.md` and displays:
+```
+Phase: <N>  |  Status: <status>  |  Updated: <timestamp>
+────────────────────────────────────────────────────────────
+Plan: <X> steps (<Y> complete)
+Plan confirmed: <yes/no>
+```
 
 ### Roadmap (`--roadmap`)
-Display project roadmap with phase statuses.
+
+Reads `.planning/ROADMAP.md` and `.planning/STATE.md` and displays:
+```
+═══════════════════════════════════════
+PROJECT ROADMAP
+═══════════════════════════════════════
+  ✅ Phase 1: <name> — completed
+  🔄 Phase 2: <name> — in progress  ← current
+  ⏳ Phase 3: <name> — planned
+═══════════════════════════════════════
+```
 
 ### Workspace (`--workspace`)
-Display overview of all registered repositories.
+
+Reads `.planning/config.json` for registered repositories and each repo's STATE.md, displaying:
+```
+════════════════════════════════════════════════════
+WORKSPACE OVERVIEW
+════════════════════════════════════════════════════
+  frontend   — Phase 2 | in_progress  | Plan: ✅ | Updated: <time>
+  backend    — Phase 3 | completed    | Plan: ✅ | Updated: <time>
+  shared     — Phase 1 | planned      | Plan: ❌ | Updated: <time>
+────────────────────────────────────────────────────
+Total: 3 repos | 1 in progress | 1 completed | 1 planned
+════════════════════════════════════════════════════
+```
 
 ### Phase Detail (`--phase=N`)
-Show detailed progress for a specific phase.
+
+Reads the specific phase's STATE.md and PLAN.md (if exists) and displays:
+```
+Phase <N> Detail
+Status: <status>
+Plan file: <path>
+Plan confirmed: <yes/no>
+
+Steps:
+  ✅ Step 1: <name> — completed
+  🔄 Step 2: <name> — in progress
+  ⬜ Step 3: <name> — pending
+  ⬜ Step 4: <name> — pending
+```
+
+## Output / State
+
+No files modified. Read-only display command.
 
 ## Examples
 
 ```
 /fd-status
+```
+
+Show current phase summary.
+
+```
 /fd-status --roadmap
+```
+
+Show full project roadmap with all phase statuses.
+
+```
 /fd-status --workspace
+```
+
+Show overview of all registered repositories in the workspace.
+
+```
 /fd-status --phase=2
-```
+```
+
+Show detailed progress for phase 2.
+
+## Related Commands
+
+- `/fd-map-codebase` — map the codebase (required before starting a feature)
+- `/fd-execute` — advance phase status by implementing steps
+- `/fd-verify` — update phase status to `verified` after full pipeline pass

package/docs/commands/fd-suggest.md

@@ -0,0 +1,114 @@
+# /fd-suggest
+
+**Purpose:** Analyze the codebase and suggest high-value feature opportunities with implementation guidance.
+
+## Usage
+
+/fd-suggest [--category=TYPE] [--limit=N]
+
+## Arguments
+
+- `--category=TYPE` (optional) — focus on specific type: `tools`, `hooks`, `agents`, or `skills`
+- `--limit=N` (optional) — number of suggestions to return (default: 5)
+
+## What Happens
+
+### Step 1: Detect Environment
+
+Check if `.planning/` directory exists:
+- If it exists: Use current project context, analyze within existing architecture
+- If not: This is a standalone analysis, scan the codebase root
+
+### Step 2: Run Analysis Tools
+
+Execute tools to gather insight data:
+
+1. **Volatility Map** — `volatility-map` tool to find high-change areas (instability signals)
+2. **Decision Trace** — `decision-trace` tool to find incomplete or TODO decisions
+3. **Failure Replay** — `failure-replay` tool to find recurring failure patterns
+4. **Codebase State** — `codebase-state` tool to get overall project structure
+
+### Step 3: Scan for Gaps
+
+Analyze the codebase structure to identify gaps:
+
+- **Tools** — Are all tool categories covered? (planning, state, execution, analysis)
+- **Hooks** — Are lifecycle hooks comprehensive?
+- **Agents** — Are agent types sufficient for common tasks?
+- **Skills** — Are there skill coverage gaps for major frameworks?
+
+### Step 4: Generate Suggestions
+
+For each valid suggestion (up to --limit), produce:
+```
+## Suggestion N: [Feature Name]
+
+**Category:** tools|hooks|agents|skills
+**Impact:** HIGH|MEDIUM|LOW
+**Complexity:** HIGH|MEDIUM|LOW
+
+### Problem Statement
+[What issue this solves, with evidence from analysis]
+
+### Proposed Solution
+[Brief description of the approach]
+
+### Implementation Steps
+1. [Step with TDD approach - write test first]
+2. [Step referencing existing patterns]
+3. [Step with integration points]
+
+### Files Affected
+- `src/tools/xxx.ts` or `src/hooks/xxx.ts` or `src/agents/xxx.ts`
+- `src/skills/xxx/SKILL.md` (if applicable)
+- `docs/xxx.md` (if applicable)
+
+### Integration
+- How this connects to existing FlowDeck tools/agents
+- Any new dependencies or configuration needed
+```
+
+### Step 5: Rank and Present
+
+Sort suggestions by impact/complexity ratio (highest first).
+
+## Output / State
+
+```
+# Feature Suggestions
+
+Found N suggestions ranked by impact:
+
+[Suggestions 1-N]
+
+---
+Run /fd-discuss [topic] to start a discussion on any suggestion.
+```
+
+## Examples
+
+**Get 5 feature suggestions (default):**
+```
+/fd-suggest
+```
+
+**Get 10 suggestions:**
+```
+/fd-suggest --limit=10
+```
+
+**Focus on tool gaps only:**
+```
+/fd-suggest --category=tools
+```
+
+**Find agent-related opportunities:**
+```
+/fd-suggest --category=agents
+```
+
+## Related Commands
+
+- `/fd-discuss` — explore any suggestion in depth
+- `/fd-plan` — plan implementation of a selected suggestion
+- `/fd-translate-intent` — convert a vague request into concrete options

package/docs/commands/fd-translate-intent.md

@@ -1,17 +1,77 @@
----
-description: Intent-to-Change Translator — convert vague requests into 3–5 concrete, ranked implementation options with tradeoffs
-argument-hint: [vague intent, e.g. "make checkout faster"]
----
+# /fd-translate-intent
 
-# Translate Intent
+**Purpose:** Convert vague requests into ranked concrete implementation options with tradeoffs.
 
-Convert a vague or high-level request into concrete ranked implementation options with tradeoffs.
+## Usage
+
+/fd-translate-intent [vague intent, e.g. "make checkout faster"]
+
+## What Happens
+
+Run two agents in parallel:
+
+- **@architect**: Decomposes the input into 3-5 concrete implementation options. For each option provides:
+  - **Name**: short label
+  - **Description**: what exactly would be changed
+  - **Files affected**: list of files/modules that would change
+  - **Effort**: S (hours) / M (days) / L (week+)
+  - **Risk**: low / medium / high
+  - **Tradeoffs**: pros and cons
+
+- **@researcher**: For each option, fetches relevant codebase context — finds existing patterns, prior art, and constraints that apply
+
+## Output / State
+
+Report format:
+```
+════════════════════════════════════════════
+INTENT TRANSLATION: "$ARGUMENTS"
+════════════════════════════════════════════
+
+Option 1 (Recommended): <name>
+  Description: <what changes>
+  Files: <list>
+  Effort: <S|M|L> | Risk: <low|med|high>
+  Pros: <pros>
+  Cons: <cons>
+
+Option 2: <name>
+  ...
+
+Option 3: <name>
+  ...
+
+────────────────────────────────────────────
+Clarifying Questions:
+  1. <question about unclear aspect>
+  2. <question>
+
+Assumptions Made:
+  - <assumption>
+════════════════════════════════════════════
+```
+
+The command presents all options and asks: "Which option would you like to proceed with?"
 
 ## Examples
 
+**Convert a vague request:**
+```
+/fd-translate-intent "make checkout faster"
 ```
-/fd-translate-intent make checkout faster
-/fd-translate-intent improve auth security
+
+**Translate a high-level request:**
 ```
+/fd-translate-intent "improve auth security"
+```
+
+**Clarify a feature direction:**
+```
+/fd-translate-intent "add mobile support"
+```
+
+## Related Commands
 
-Returns 3-5 options with description, files affected, effort, risk, and tradeoffs.
+- `/fd-discuss` — explore the problem space before translating intent
+- `/fd-plan` — plan the selected implementation option
+- `/fd-execute` — execute the chosen implementation