@dv.nghiem/flowdeck 0.2.3 → 0.3.0

package/docs/configuration.md

@@ -268,6 +268,8 @@ These are enabled by default. If you have API keys (e.g., `CONTEXT7_API_KEY`, `E
 | `XDG_CONFIG_HOME` | `~/.config` | Standard XDG base directory; used to resolve `OPENCODE_CONFIG_DIR` when not explicitly set |
 | `FLOWDECK_CONTEXT_LIMIT` | `200000` | Token limit used by the Context Window Monitor to warn when context usage exceeds 70% |
 | `FLOWDECK_DISABLE_MCP` | (empty) | Comma-separated list of remote MCPs to disable. Valid options: `context7`, `websearch`, `grep_app` |
+| `FLOWDECK_ORCHESTRATOR_GUARD` | `off` | Enable the orchestrator guard hook. When `on`, the orchestrator session cannot use write/bash tools directly and must delegate all implementation work. |
+| `TELEMETRY_ENABLED` | `false` | Enable telemetry events from hooks. When `true`, events are written to `.codebase/TELEMETRY.jsonl`. |
 
 ---
 
@@ -278,7 +280,6 @@ When the `@dv.nghiem/flowdeck` plugin is loaded, six tools become available to e
 | `planning-state` | Read and write `.planning/` state files (`STATE.md`, `PLAN.md`, `DISCUSS.md`, `config.json`). Used by every agent that needs project context. |
 | `codebase-state` | Read `.codebase/` documentation files generated by `@mapper`. Gives agents access to `STACK.md`, `ARCHITECTURE.md`, and `CONVENTIONS.md`. |
 | `workspace-state` | Read workspace and multi-repo metadata. Returns the current project config, sub-repo list, and active phase. |
-| `run-parallel` | Fan out a set of independent agent tasks simultaneously. Used by `@parallel-coordinator` to execute wave tasks concurrently. |
 | `run-pipeline` | Execute a sequence of agent tasks in strict order, passing each step's output as input to the next. Used by `@orchestrator` for ordered workflows. |
 | `delegate` | Invoke a specific named agent with a given prompt and context. The core primitive used by orchestration agents to hand off work. |
 | `hash-edit` | Reliable file editing with content verification. Takes target content and its expected hash to prevent edits on stale versions. |

package/docs/index.md

@@ -1,6 +1,6 @@
 # FlowDeck Documentation
 
-FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates 29 specialist agents through a four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
+FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
 
 ---
 
@@ -18,12 +18,13 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Agents](agents.md) | All 29 agents — names, roles, models, and when to invoke each one |
-| [Skills](skills.md) | All 24 skills — what each skill does and example prompts that activate it |
-| [Commands](commands.md) | All 27 slash commands — syntax, arguments, and what each command triggers |
-| [Workflows](workflows.md) | All 15 built-in workflows — flow diagrams, inputs, outputs, and agent involvement |
+| [Agents](agents.md) | All specialist agents — names, roles, models, and when to invoke each one |
+| [Skills](skills.md) | Reusable skill patterns for common tasks |
+| [Commands](commands.md) | All 18 slash commands — syntax, arguments, and what each command triggers |
+| [Workflows](workflows.md) | Built-in workflows for common scenarios |
 | [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
-| [Intelligence Features](intelligence.md) | 15 AI-safety features: impact radar, patch trust, blast radius, decision trace, and more |
+| [Intelligence Features](intelligence.md) | AI-safety features for pre-change analysis and risk assessment |
+| [Memory System](memory.md) | Persistent memory — recall past sessions, tool executions, and context across sessions |
 
 ---
 
@@ -31,7 +32,6 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Parallel Execution](parallel-execution.md) | How FlowDeck fans out independent tasks across multiple agents simultaneously |
 | [Multi-Repo](multi-repo.md) | Coordinating changes across two or more repositories in a single session |
 | [Notifications](notifications.md) | Desktop and system alerts for long-running task completion |
 
@@ -50,26 +50,20 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Command | What it does |
 |---------|--------------|
-| `/fd-new-project <name>` | Initialize `.planning/` directory structure for a new project |
-| `/fd-discuss <phase>` | Run structured requirements Q&A with `@discusser` |
-| `/fd-plan <phase>` | Generate a wave-structured `PLAN.md` (requires `CONFIRMED` to execute) |
-| `/fd-new-feature "<description>"` | Execute full feature workflow via `@orchestrator` |
-| `/fd-review-code [staged\|branch]` | Parallel review by `@reviewer`, `@security-auditor`, `@tester` |
+| `/fd-new-project <name>` | Initialize project with planning structure and default config |
+| `/fd-discuss <topic>` | Run structured requirements Q&A to capture decisions |
+| `/fd-plan [--phase=N]` | Generate implementation plan from decisions (requires CONFIRM) |
+| `/fd-new-feature "<description>"` | Execute full feature workflow with TDD discipline |
 | `/fd-fix-bug "<description>"` | Diagnose and fix a bug with regression test |
+| `/fd-deploy-check [--check=deploy,review,analysis]` | Pre-deploy checks, code review, or pre-change analysis |
+| `/fd-status [--roadmap\|--workspace\|--phase=N]` | Combined status, roadmap, and workspace view |
 | `/fd-checkpoint` | Save current state — safe to close the session after this |
-| `/fd-resume` | Reload `STATE.md` and `PLAN.md` context in a new session |
-| `/fd-progress` | Print current state, active plan, and recent results |
-| `/fd-map-codebase` | Generate `.codebase/` documentation from source analysis |
-| `/fd-roadmap` | View or update phase statuses and milestones |
-| `/fd-dashboard` | Open the project dashboard with phase progress and blockers |
-| `/fd-deploy-check` | Run pre-deployment checks and produce a go/no-go verdict |
-| `/fd-write-docs` | Generate or update project documentation |
-| `/fd-multi-repo` | Coordinate a change across multiple registered repositories |
-| `/fd-settings` | View or update FlowDeck model assignments and configuration |
-| `/fd-impact-radar` | Predict affected files/APIs/tests before editing |
-| `/fd-blast-radius` | Show downstream consequences and hidden dependencies of a change |
-| `/fd-translate-intent` | Convert vague request into ranked concrete implementation options |
-| `/fd-volatility-map` | Show unstable code zones by churn and hotfix frequency |
-| `/fd-regression-predict` | Estimate likely regression categories before making a change |
-| `/fd-test-gap` | Identify weakly-tested areas in a proposed change |
-| `/fd-review-route` | Route risky patches to security, backend, infra, or domain reviewers |
+| `/fd-resume [--yes]` | Reload STATE.md and PLAN.md to continue interrupted session |
+| `/fd-reflect [--mode=reflect,learn]` | Post-session reflection or capture skill from session |
+| `/fd-map-codebase [--incremental]` | Generate `.codebase/` documentation |
+| `/fd-write-docs [--scope=path]` | Generate documentation from public APIs |
+| `/fd-multi-repo <list\|add\|remove\|status>` | Manage multi-repo configuration |
+| `/fd-translate-intent "<vague request>"` | Convert vague request into ranked implementation options |
+| `/fd-ask "<question>"` | Route question to specialist agent |
+| `/fd-quick "<task>"` | Quick focused task with automatic agent selection |
+| `/fd-doctor` | Check FlowDeck installation and environment health |

package/docs/memory.md

@@ -0,0 +1,69 @@
+# Memory System
+
+FlowDeck includes a persistent memory system that stores tool executions, assistant messages, and session summaries. This helps agents recall what was worked on in previous sessions.
+
+## How It Works
+
+Memory is automatically captured during sessions:
+
+1. **Session Start** — Session is registered with project directory
+2. **Tool Execution** — Every tool call (Read, Write, Edit, Bash, etc.) is stored
+3. **Assistant Messages** — Agent responses are captured
+4. **Session Compact/Summary** — End-of-session summaries are stored
+
+## Storage
+
+- **Location**: `~/.flowdeck-memory/memory.db`
+- **Format**: SQLite database (using `bun:sqlite`)
+- **Tables**:
+  - `sessions` — Session metadata (project, directory, timestamps)
+  - `observations` — Tool executions and messages
+  - `summaries` — Session summaries
+
+## Using Memory
+
+### Search Tool
+
+Use the `memory-search` tool to query past observations:
+
+```
+tool: memory-search
+args: { query: "authentication", limit: 5 }
+```
+
+**Arguments:**
+- `query` (optional) — Search text for tool names, inputs, and outputs
+- `session_id` (optional) — Retrieve all observations from a specific session
+- `limit` (optional) — Max results (default: 10)
+
+### Example Queries
+
+```javascript
+// Search for specific work
+tool: memory-search
+args: { query: "Redis cache" }
+
+// Get recent sessions
+tool: memory-search
+args: { limit: 10 }
+
+// Get all observations from a session
+tool: memory-search
+args: { session_id: "abc-123" }
+```
+
+## Context Injection
+
+When a new session starts in the same directory, FlowDeck can optionally inject relevant context from previous sessions. This helps maintain continuity across sessions.
+
+## Privacy
+
+- Memory is stored per-user at `~/.flowdeck-memory/`
+- Each project directory has its own session tracking
+- Use session.delete event to remove specific sessions
+
+## Configuration
+
+No configuration required — memory is enabled by default.
+
+To disable memory tracking for a project, you would need to modify the session tracking hooks in the FlowDeck plugin configuration.

package/docs/quick-start.md

@@ -123,7 +123,7 @@ Once the plan is confirmed, start implementation:
 3. **Wave 3** — `@tester` writes and runs tests against the completed implementation
 4. **Wave 4** — `@reviewer` reviews the full changeset
 
-You see progress updates as each wave completes. Independent tasks within a wave run simultaneously via the `run-parallel` tool.
+You see progress updates as each wave completes. Independent tasks within a wave run simultaneously via OpenCode's multi-agent capabilities.
 
 ---
 

package/docs/workflows.md

@@ -1,14 +1,14 @@
-# FlowDeck Workflows
+# Command Architecture
 
-Workflows define how agents collaborate in multi-step sequences. They live in `flowdeck/workflows/` as reference documents — agents read and follow them, but you don't invoke workflows directly. Commands trigger them.
+FlowDeck commands are the single entry point for all operations. Each command embeds its workflow steps directly — no separate workflow files are needed.
 
-## How Workflows Work
+## How Commands Work
 
 1. You run a command (e.g., `/fd-plan`)
-2. The command's plugin handler injects workflow context into the session
-3. The AI reads the workflow steps and delegates to the named agents in order
-4. Each step's output becomes context for the next step
-5. The workflow may pause for user confirmation before irreversible actions
+2. The command template is loaded with its embedded workflow steps
+3. The AI follows the step-by-step process defined in the command
+4. Each step may spawn agents or perform actions
+5. The command may pause for user confirmation before irreversible actions
 
 ## The Core FlowDeck Cycle
 
@@ -32,345 +32,97 @@ Each step gates the next. `/fd-plan` will not proceed without a confirmed `DISCU
 
 ---
 
-## Workflow Reference Table
+## Command Reference
 
-| Workflow file | Triggered by | Agents involved |
-|--------------|-------------|----------------|
-| `discuss-flow.md` | `/fd-discuss` | `@orchestrator`, `@discusser` |
-| `plan-flow.md` | `/fd-plan` | `@orchestrator`, `@planner`, `@plan-checker` |
-| `plan-phase.md` | `/fd-plan-phase [N]` | `@planner`, `@plan-checker`, `@orchestrator` |
-| `execute-flow.md` | `/fd-new-feature` | `@orchestrator`, `@coder`, `@reviewer` |
-| `execute-phase.md` | `/execute-phase [N]` | `@orchestrator`, `@orchestrator` |
-| `fix-bug-flow.md` | `/fd-fix-bug` | `@orchestrator`, `@debug-specialist`, `@researcher`, `@tester`, `@coder`, `@reviewer` |
-| `debug-flow.md` | `/debug` | `@debug-specialist`, `@tester`, `@coder` |
-| `review-code-flow.md` | `/fd-review-code` | `@orchestrator`, `@parallel-coordinator`, `@reviewer`, `@researcher`, `@tester` |
-| `deploy-check-flow.md` | `/fd-deploy-check` | `@parallel-coordinator`, `@orchestrator`, `@security-auditor`, `@tester`, `@reviewer` |
-| `refactor-flow.md` | `/refactor` | `@tester`, `@mapper`, `@refactor-guide`, `@coder`, `@orchestrator` |
-| `write-docs-flow.md` | `/fd-write-docs` | `@code-explorer`, `@writer`, `@reviewer`, `@doc-updater` |
-| `map-codebase-flow.md` | `/fd-map-codebase` | `@orchestrator`, `@mapper` (×6 in parallel) |
-| `parallel-execution-flow.md` | Triggered by `@parallel-coordinator` | `@parallel-coordinator`, `@researcher`, `@code-explorer`, `@architect`, `@coder`, `@tester`, `@reviewer`, `@security-auditor` |
-| `multi-repo-flow.md` | `/fd-multi-repo` | `@multi-repo-coordinator`, `@architect`, `@coder`, `@tester`, `@reviewer` |
+| Command | Purpose | Key Agents |
+|---------|---------|------------|
+| `/fd-new-project` | Bootstrap a new project | @orchestrator |
+| `/fd-map-codebase` | Analyse and index the codebase | @mapper (×6 parallel) |
+| `/fd-settings` | Configure FlowDeck settings | @orchestrator |
+| `/fd-discuss` | Pre-planning discussion | @discusser |
+| `/fd-plan` | Generate a phase plan | @planner, @plan-checker |
+| `/fd-roadmap` | View / update project roadmap | @orchestrator |
+| `/fd-dashboard` | Visual progress dashboard | — |
+| `/fd-ask` | Smart agent dispatch | various |
+| `/fd-new-feature` | Implement a new feature | @coder, @tester, @reviewer |
+| `/fd-fix-bug` | Fix a bug with TDD | @debug-specialist, @tester, @coder |
+| `/fd-review-code` | Code review | @reviewer, @researcher, @tester |
+| `/fd-write-docs` | Generate documentation | @writer, @reviewer |
+| `/fd-deploy-check` | Pre-deploy safety check | @tester, @security-auditor, @reviewer |
+| `/fd-progress` | View project progress | — |
+| `/fd-checkpoint` | Save a session checkpoint | — |
+| `/fd-resume` | Resume from checkpoint | — |
+| `/fd-multi-repo` | Multi-repo orchestration | @multi-repo-coordinator, @architect |
 
 ---
 
-## Detailed Workflow Descriptions
+## Analysis Commands
 
-### discuss-flow
+These umbrella commands combine multiple analysis modules:
 
-**Triggered by:** `/fd-discuss`
-
-The discuss flow drives the requirements extraction phase. It starts by loading `PROJECT.md` and `STATE.md` to understand the current phase and any decisions already made. The `@orchestrator` extracts the current phase number, then spawns `@discusser` with that context so it avoids re-asking about settled decisions.
-
-The `@discusser` asks one question per turn, records every decision as `D-XX` with its rationale, and detects conflicts between new answers and existing decisions before proceeding. The Q&A loop continues until all required topics are covered. When complete, all decisions are written to `.planning/phases/phase-N/DISCUSS.md`.
-
-Before the file is marked confirmed, `@orchestrator` presents a summary of all decisions to the user and requires explicit confirmation. Nothing in DISCUSS.md is treated as locked until the user confirms.
-
-**Steps:**
-1. `@orchestrator` — Load `PROJECT.md` and `STATE.md`
-2. `@orchestrator` — Extract current phase number
-3. `@discusser` — Q&A loop, one question per turn
-4. `@discusser` — Record decisions with D-XX numbering
-5. `@discusser` — Save to `.planning/phases/phase-N/DISCUSS.md`
-6. `@orchestrator` — Present summary; require user confirmation
-
-**Workflow format:**
-```yaml
----
-name: discuss-flow
-description: "Orchestrates discuss phase (context load → @discusser Q&A → pause → decisions → save)"
-triggers:
-  - /fd-discuss
-steps:
-  - name: load_context
-    agent: "@orchestrator"
-    priority: first
-    action: Load PROJECT.md and current phase STATE.md
-  - name: determine_phase
-    agent: "@orchestrator"
-    action: Extract current phase number from STATE.md
-  - name: invoke_discusser
-    agent: "@discusser"
-    action: Spawn @discusser agent with project context
-  - name: qa_loop
-    agent: "@discusser"
-    action: Discusser asks one question at a time; user responds; repeat until all topics covered
-  - name: save_decisions
-    agent: "@discusser"
-    action: Write all decisions to .planning/phases/phase-N/DISCUSS.md with D-XX numbering
-  - name: confirm_discuss
-    agent: "@orchestrator"
-    action: Present summary to user; require explicit confirmation before marking DISCUSS.md as confirmed
----
-```
-
----
-
-### plan-flow
-
-**Triggered by:** `/fd-plan`
-
-The plan flow creates an execution-ready `PLAN.md` from the decisions in a confirmed `DISCUSS.md`. It starts with a guard check — if `DISCUSS.md` does not exist or is not confirmed, execution stops and the user is directed to run `/fd-discuss` first.
-
-After loading context (`PROJECT.md`, `STATE.md`, `DISCUSS.md`), `@planner` creates a wave-structured `PLAN.md` where every task traces back to a `D-XX` decision. The draft plan is then handed to `@plan-checker`, which scores it for completeness, feasibility, and testability.
-
-A FAIL verdict from `@plan-checker` returns the plan to `@planner` for revision. A PASS (or PASS_WITH_NOTES) causes `@orchestrator` to present the plan to the user. Execution **pauses here** — the plan is not saved until the user explicitly confirms it. After confirmation, the plan is saved to `.planning/phases/phase-N/PLAN.md` and `STATE.md` is updated.
-
-**Steps:**
-1. `@orchestrator` — Guard check: verify `DISCUSS.md` exists and is confirmed
-2. `@orchestrator` — Load `PROJECT.md`, `STATE.md`, `DISCUSS.md`
-3. `@planner` — Create `PLAN.md` with tasks traced to D-XX decisions
-4. `@plan-checker` — Verify completeness, feasibility, testability; return PASS or FAIL
-5. `@orchestrator` — Present draft plan for user review
-6. `@orchestrator` — **PAUSE** — wait for explicit user CONFIRM before saving
-7. `@orchestrator` — Save confirmed `PLAN.md` to `.planning/phases/phase-N/`
-8. `@orchestrator` — Update `STATE.md` with plan file path
-
----
-
-### plan-phase
-
-**Triggered by:** `/fd-plan-phase [N]`
-
-A focused sub-flow for creating a plan for a specific numbered phase. Unlike `plan-flow`, which drives the full `/fd-plan` command, `plan-phase` is a targeted invocation that takes a phase number as an argument and operates only on that phase's scope.
-
-`@planner` is spawned with the phase's `REQUIREMENTS.md` (or `DISCUSS.md`), `ROADMAP.md`, and `PROJECT.md`. It produces `.planning/phases/phase-N/PLAN.md`. `@plan-checker` then reviews the plan and returns PASS or FAIL with specific recommendations. Results are presented by `@orchestrator`.
-
-**Steps:**
-1. `@planner` — Create `PLAN.md` for the specified phase
-2. `@plan-checker` — Score plan: completeness, feasibility, testability
-3. `@orchestrator` — Present PASS/FAIL verdict and recommendations
+| Command | Purpose | Flags |
+|---------|---------|-------|
+| `/fd-analyze-change` | Combined impact analysis | `--impact`, `--blast-radius`, `--regression`, `--test-gap`, `--volatility` |
+| `/fd-guarded-edit` | Edit gate decision | auto/confirm/review/block |
+| `/fd-evaluate-risk` | Standalone risk assessment | — |
+| `/fd-translate-intent` | Intent to concrete options | `assumptions`, `recommended_option` |
 
 ---
 
-### execute-flow
-
-**Triggered by:** `/fd-new-feature`
-
-The execute flow drives full feature delivery. A guard check verifies that `.planning/` and `.codebase/` exist and that `PLAN.md` is confirmed — if any check fails, execution stops with a specific message directing the user to the missing prerequisite.
+## Command Structure
 
-`@orchestrator` loads the active `PLAN.md` and identifies the first incomplete step. If steps are independent, `@coder` agents run in parallel via `@parallel-coordinator`. After each step, `@reviewer` reviews the completed work. `@orchestrator` marks the step complete in `STATE.md`, then advances to the next step. When all steps are complete, `STATE.md` is updated to the `review` phase.
+Each command file (`src/commands/fd-*.md`) contains:
 
-**Steps:**
-1. `@orchestrator` — Guard check: verify `.planning/`, `.codebase/`, plan confirmed
-2. `@orchestrator` — Load active `PLAN.md`; identify first incomplete step
-3. `@coder` — Execute step (parallel if steps are independent)
-4. `@reviewer` — Review completed work
-5. `@orchestrator` — Mark step complete; advance to next step
-6. `@orchestrator` — Loop until all steps complete; update phase to `review`
+1. **Frontmatter** — description and argument hint
+2. **Purpose** — what the command does
+3. **Input** — how to invoke it
+4. **Process** — step-by-step workflow embedded directly
+5. **Guards** — transition rules and blocking conditions
+6. **Error Handling** — fail-fast rules
 
+Example structure:
+```markdown
 ---
-
-### execute-phase
-
-**Triggered by:** `/execute-phase [N]`
-
-A targeted sub-flow for executing a single numbered phase plan. Before delegating, `@orchestrator` verifies that `.planning/`, `.codebase/`, and `.planning/phases/phase-N/PLAN.md` all exist and that the plan has the `confirmed` status flag.
-
-`@orchestrator` is spawned with `STATE.md`, `PLAN.md`, and `PROJECT.md`. It executes tasks in wave order, committing each atomically. After each task it checkpoints state via the planning-state tool. Deviations from the plan are documented in a `## Deviations` section of `PLAN.md`. After all tasks complete, `@orchestrator` writes `SUMMARY.md` and `@orchestrator` marks the phase complete in `STATE.md` and `ROADMAP.md`.
-
-**Steps:**
-1. `@orchestrator` — Verify prerequisites: `.planning/`, `.codebase/`, `PLAN.md` confirmed
-2. `@orchestrator` — Load `PLAN.md`, `STATE.md`, `PROJECT.md`
-3. `@orchestrator` — Execute tasks in wave order; atomic commit per task
-4. `@orchestrator` — Checkpoint state after each task
-5. `@orchestrator` — Write `SUMMARY.md`
-6. `@orchestrator` — Mark phase complete in `STATE.md` and `ROADMAP.md`
-
----
-
-### fix-bug-flow
-
-**Triggered by:** `/fd-fix-bug`
-
-A systematic bug fix workflow that guarantees a regression test exists before any fix is applied. `@orchestrator` loads `STATE.md`, `ARCHITECTURE.md`, and `CONVENTIONS.md` to give all agents the project context they need.
-
-`@debug-specialist` reproduces the bug with a minimal case, documenting expected vs actual behavior. `@researcher` assists with root cause investigation by tracing the stack and reading related code. `@tester` writes a failing regression test that reproduces the exact failure — this test must fail before any fix is written. `@coder` then fixes the root cause (not the symptom) with the minimum change that makes the regression test pass. `@reviewer` checks the fix for quality and security regressions. Finally, `@tester` runs the full test suite to confirm everything is green.
-
-**Steps:**
-1. `@orchestrator` — Load `STATE.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`
-2. `@debug-specialist` — Reproduce bug; document inputs and expected vs actual
-3. `@researcher` — Trace stack; identify root cause candidates
-4. `@tester` — Write failing regression test
-5. `@coder` — Fix root cause; minimum change to make regression test pass
-6. `@reviewer` — Review fix for quality and security regressions
-7. `@tester` — Run full suite; confirm regression test and all others pass
-8. `@orchestrator` — Update `STATE.md` with fix summary
-
+description: Brief description
+argument-hint: [args]
 ---
 
-### debug-flow
-
-**Triggered by:** `/debug`
+# Command Name
 
-A lighter debugging workflow focused on systematic diagnosis without the full bug-fix lifecycle. Where `fix-bug-flow` orchestrates a complete team, `debug-flow` keeps `@debug-specialist` in the lead throughout.
-
-`@debug-specialist` establishes a minimal reproduction case, reads the full stack trace from top to bottom, and traces the execution path backward to identify root cause. `@tester` then writes a failing regression test for the exact failure — not a general test, but one that fails for the specific reason `@debug-specialist` identified. `@coder` applies the minimal fix, and `@tester` verifies by running the regression test plus the full suite.
-
-The cardinal rule of this workflow: never suppress an error to make a test pass. Fix the root cause.
-
-**Steps:**
-1. `@debug-specialist` — Establish minimal reproduction case
-2. `@debug-specialist` — Trace execution path; identify root cause
-3. `@tester` — Write failing regression test for the specific failure
-4. `@coder` — Fix root cause with minimal change
-5. `@tester` — Run regression test + full suite to confirm
-
----
+**Input:** $ARGUMENTS
 
-### review-code-flow
+## Process
 
-**Triggered by:** `/fd-review-code`
+### Step 1: Context Load
+...
 
-A parallel code review workflow that combines quality review, security checking, and test coverage verification simultaneously. `@orchestrator` determines the review scope — either from changed files (git diff) or an explicit scope argument.
+### Step 2: Execute
+...
 
-`@parallel-coordinator` spawns three agents simultaneously: `@reviewer` checks for security vulnerabilities (injection, exposed secrets, missing auth) and code quality issues; `@researcher` provides best-practice context for any flagged areas; `@tester` verifies that changed code has adequate test coverage. All three run in parallel and report independently. `@orchestrator` then aggregates the findings into a unified report sorted by severity: CRITICAL → HIGH → MEDIUM → PASS.
+## Guards
 
-**Steps:**
-1. `@orchestrator` — Identify review scope (changed files or explicit argument)
-2. `@parallel-coordinator` — Spawn in parallel:
-   - `@reviewer` — security vulnerabilities and code quality
-   - `@researcher` — best-practice context for flagged areas
-   - `@tester` — test coverage for changed code
-3. `@orchestrator` — Aggregate all findings by severity into unified report
-
----
-
-### deploy-check-flow
-
-**Triggered by:** `/fd-deploy-check`
-
-A comprehensive pre-deployment check suite that runs four independent checks simultaneously and produces a single GO/NO-GO decision. Any CRITICAL or HIGH finding from any check produces NO-GO.
-
-`@parallel-coordinator` launches all four checks at once: the full test suite (all tests pass, no unexplained skips), a security scan via `@security-auditor` (OWASP Top 10 on changed files), a CVE audit on dependencies, and a clean build verification. `@orchestrator` waits for all four to complete, aggregates the results, and produces the final GO or NO-GO verdict. A NO-GO includes a specific list of required fixes before the deployment can be retried.
-
-**Steps:**
-1. `@parallel-coordinator` — Run simultaneously:
-   - Full test suite
-   - Security scan (`@security-auditor`)
-   - CVE dependency audit
-   - Build verification
-2. `@orchestrator` — Aggregate all results
-3. `@orchestrator` — Produce GO/NO-GO decision; list required fixes if NO-GO
-
----
-
-### refactor-flow
-
-**Triggered by:** `/refactor`
-
-A disciplined safe-refactoring workflow where the test suite must be green before the first line of code changes, and must stay green after every single transformation. No feature additions are permitted during a refactoring session.
-
-`@tester` runs the suite and confirms it is green. If it is not green, the workflow stops — tests must be fixed before refactoring begins. `@mapper` reads the codebase and identifies refactoring candidates (large files, duplication, high complexity). `@refactor-guide` produces a list of specific transforms ordered from lowest to highest risk. `@coder` applies one transform, then `@tester` verifies the suite is still green. `@orchestrator` commits each transform separately with a `refactor:` prefix message. The loop repeats until all planned transforms are complete.
-
-**Steps:**
-1. `@tester` — Run suite; confirm green before any changes
-2. `@mapper` — Identify refactoring candidates
-3. `@refactor-guide` — List transforms in low-to-high risk order
-4. Loop:
-   - `@coder` — Apply one transform
-   - `@tester` — Verify suite still green; if broken, undo
-   - `@orchestrator` — Commit with `refactor:` message
-
----
-
-### write-docs-flow
-
-**Triggered by:** `/fd-write-docs`
-
-A documentation workflow that prioritizes accuracy over speed — every piece of documentation is verified against the actual code before it is finalized. The flow starts with exploration rather than writing.
-
-`@code-explorer` maps all exported functions, classes, and types in the target scope, identifying public API entry points and key workflows. `@writer` uses that structural map to draft documentation covering API reference, examples, and usage patterns — it reads every source file it documents. `@reviewer` then checks the draft for accuracy against actual code behavior (not plausible-sounding descriptions, actual behavior). `@writer` incorporates reviewer feedback, and `@doc-updater` writes the final output to the appropriate location and ensures no stale references remain.
-
-**Steps:**
-1. `@code-explorer` — Map exports, public APIs, and key workflows in scope
-2. `@writer` — Draft documentation from code exploration output
-3. `@reviewer` — Accuracy check against actual code behavior
-4. `@writer` — Revise based on review feedback
-5. `@doc-updater` — Write final docs to appropriate location; remove stale references
-
----
-
-### map-codebase-flow
-
-**Triggered by:** `/fd-map-codebase`
-
-Produces the six `.codebase/` documentation files in parallel using six `@mapper` instances, each assigned to one output file. Before running, `@orchestrator` checks whether `.codebase/` already exists and requires user confirmation before overwriting.
-
-`@orchestrator` creates individual worktrees for each mapper instance to prevent file conflicts, then spawns all six `@mapper` agents simultaneously. Each mapper reads source files directly and writes only its assigned file: `STACK.md`, `ARCHITECTURE.md`, `STRUCTURE.md`, `CONVENTIONS.md`, `TESTING.md`, or `CONCERNS.md`. `@orchestrator` waits for all six to complete, then verifies each file exists and contains non-empty content. Worktrees are cleaned up regardless of success or failure.
-
-**Steps:**
-1. `@orchestrator` — Check if `.codebase/` exists; warn and require confirmation if present
-2. `@orchestrator` — Create worktrees for each mapper instance
-3. `@mapper` ×6 — Run in parallel, each writing its assigned `.codebase/` file
-4. `@orchestrator` — Wait for all mappers to complete
-5. `@orchestrator` — Clean up worktrees
-6. `@orchestrator` — Verify all six files exist with non-empty content
-
-**Output files:**
-
-| File | Contents |
-|------|---------|
-| `.codebase/STACK.md` | Tech stack with exact pinned versions |
-| `.codebase/ARCHITECTURE.md` | Component diagram and data flow |
-| `.codebase/STRUCTURE.md` | Directory layout with purpose of each directory |
-| `.codebase/CONVENTIONS.md` | Naming and coding patterns with file:line examples |
-| `.codebase/TESTING.md` | Test frameworks, patterns, and file organization |
-| `.codebase/CONCERNS.md` | All TODO, FIXME, and HACK markers found by grep |
-
----
-
-### parallel-execution-flow
-
-**Triggered by:** `@parallel-coordinator` (invoked from execute-flow or directly)
-
-The parallel execution flow maximizes agent throughput by running independent workstreams simultaneously in waves. It is not triggered by a user command directly — it is invoked when `@orchestrator` or `@execute-flow` determines that parallel execution is appropriate for a plan.
-
-`@parallel-coordinator` reads the active `PLAN.md`, identifies all tasks, and classifies each as blocking (must complete before something else) or independent (can run simultaneously). It then groups tasks into waves and emits a WAVE TABLE before delegating any agents.
-
-The standard wave structure: Wave 1 runs `@researcher` and `@code-explorer` simultaneously (discovery); Wave 2 runs `@architect` alone (design, serial, gates Wave 3); Wave 3 runs `@coder` and `@tester` simultaneously (implementation from `@architect`'s contracts); Wave 4 runs `@reviewer` and `@security-auditor` simultaneously (validation). When Wave 3 tracks converge, `@parallel-coordinator` runs a merge protocol to detect and resolve any overlapping file changes.
-
-**Steps:**
-1. `@parallel-coordinator` — Read `PLAN.md`; classify tasks as blocking or independent
-2. `@parallel-coordinator` — Group into waves; emit WAVE TABLE
-3. Wave 1 (parallel): `@researcher` + `@code-explorer`
-4. Wave 2 (serial): `@architect` (design from Wave 1 output)
-5. Wave 3 (parallel): `@coder` + `@tester` (from `@architect` contracts)
-6. `@parallel-coordinator` — Merge Wave 3 outputs; resolve conflicts
-7. Wave 4 (parallel): `@reviewer` + `@security-auditor`
-
-**WAVE TABLE format:**
-```
-╔══════════════════════════════════════════════════════════════╗
-║  WAVE TABLE — [Job Title]                                    ║
-╠══════════════════════════════════════════════════════════════╣
-║  Wave 1 (parallel)  │ @researcher + @code-explorer          ║
-║  Wave 2 (serial)    │ @architect                             ║
-║  Wave 3 (parallel)  │ @coder + @tester                      ║
-║  Wave 4 (parallel)  │ @reviewer + @security-auditor         ║
-╠══════════════════════════════════════════════════════════════╣
-║  Est. sequential:   │ 8h                                     ║
-║  Est. parallel:     │ 4.5h                                   ║
-║  Dependency locks:  │ Wave 3 blocked on Wave 2 output        ║
-╚══════════════════════════════════════════════════════════════╝
+| Transition | Guard | If Violated |
+|-----------|-------|-------------|
+| A → B | condition | block |
 ```
 
 ---
 
-### multi-repo-flow
-
-**Triggered by:** `/fd-multi-repo`
-
-Orchestrates a feature or fix that spans multiple repositories in a microservice architecture. Ensures changes propagate in the correct dependency order, API contracts are agreed before implementation, and integration is verified end-to-end before any service ships to production.
-
-`@multi-repo-coordinator` reads the sub-repo registry from `.planning/config.json`, verifies all repository paths exist, and loads each service's tech stack. It then builds a dependency graph — which services call which — and classifies the change as breaking or non-breaking. `@architect` writes the contract-first change specification and a per-repo CHANGE PLAN ordered by the dependency graph. `@coder` and `@tester` implement and test changes in each repo in the correct order (upstream before downstream). After all repos are implemented, `@tester` and `@reviewer` run cross-repo integration verification and sign off on each repo before any service is deployed.
+## Agent Configuration
 
-**Steps:**
-1. `@multi-repo-coordinator` — Read `.planning/config.json`; verify repo paths; load stacks
-2. `@multi-repo-coordinator` + `@architect` — Build dependency graph; classify change
-3. `@architect` — Write contract-first change spec and ordered per-repo CHANGE PLAN
-4. `@coder` + `@tester` — Implement and test in dependency order (upstream first)
-5. `@tester` + `@reviewer` — Cross-repo integration tests; sign off per repo
+| Agent | Purpose |
+|-------|---------|
+| @orchestrator | Coordinates multi-step workflows |
+| @planner | Creates implementation plans |
+| @coder | Implements code changes |
+| @tester | Writes and runs tests |
+| @reviewer | Reviews code quality |
+| @researcher | Investigates and provides context |
+| @security-auditor | Security vulnerability scanning |
+| @architect | System design and patterns |
+| @writer | Documentation generation |
+| @mapper | Codebase analysis |
 
 ---
 
-← [Back to Index](index.md)
+← [Back to Index](index.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,6 @@
     "src/commands",
     "src/rules",
     "src/skills",
-    "src/workflows",
     "docs",
     "postinstall.mjs"
   ],