@dv.nghiem/flowdeck 0.2.3 → 0.2.4

package/dist/services/telemetry.d.ts

@@ -18,7 +18,7 @@ export interface TelemetryEvent {
     meta?: Record<string, unknown>;
 }
 export declare function telemetryPath(dir: string): string;
-export declare function appendEvent(dir: string, partial: Omit<TelemetryEvent, "id" | "ts">): TelemetryEvent;
+export declare function appendEvent(dir: string, partial: Omit<TelemetryEvent, "id" | "ts">): TelemetryEvent | null;
 export declare function readEvents(dir: string, limit?: number): TelemetryEvent[];
 export declare function getRunEvents(dir: string, run_id: string): TelemetryEvent[];
 export interface CommandSummary {

package/dist/services/telemetry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/services/telemetry.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,aAAa,GACb,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,cAAc,CAAA;AAElB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,cAAc,CAWnG;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,cAAc,EAAE,CAUrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAE1E;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,SAAM,GAAG,cAAc,EAAE,CAuBxE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,cAAc,EAAE,CAI/E"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/services/telemetry.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,kBAAkB,GAC1B,eAAe,GACf,aAAa,GACb,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,cAAc,CAAA;AAElB,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,EAAE,EAAE,MAAM,CAAA;IACV,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,kBAAkB,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,CAAC,EAAE,IAAI,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,cAAc,GAAG,IAAI,CAa1G;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,cAAc,EAAE,CAUrE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,cAAc,EAAE,CAE1E;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,SAAM,GAAG,cAAc,EAAE,CAuBxE;AAED,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,cAAc,EAAE,CAI/E"}

package/dist/tools/run-parallel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-parallel.d.ts","sourceRoot":"","sources":["../../src/tools/run-parallel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAkBtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA8G5E"}
+{"version":3,"file":"run-parallel.d.ts","sourceRoot":"","sources":["../../src/tools/run-parallel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAsBtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAiK5E"}

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 `run-parallel` and hooks. When `true`, events are written to `.codebase/TELEMETRY.jsonl`. |
 
 ---
 

package/docs/parallel-execution.md

@@ -224,4 +224,32 @@ All three dispatch tools (`run-parallel`, `delegate`, `run-pipeline`) create rea
 
 ---
 
+## Telemetry & Monitoring
+
+The `run-parallel` tool emits structured telemetry events for observability:
+
+| Event | When |
+|-------|------|
+| `agent.dispatch` | Child session created for a task |
+| `agent.complete` | Task finished (success or error) |
+
+Events are appended to `.codebase/TELEMETRY.jsonl` and include:
+- `session_id` / `run_id` — session tracking
+- `agent` — which agent ran
+- `duration_ms` — wall time
+- `status` — `ok` or `error`
+- `meta` — child session ID, task index, output length, error details
+
+Additionally, `run-parallel` writes `.codebase/parallel-progress.json` at completion with aggregate stats.
+
+**To enable telemetry**, set the environment variable:
+
+```bash
+TELEMETRY_ENABLED=true
+```
+
+When enabled, events are written to `.codebase/TELEMETRY.jsonl`. The progress file is always written regardless of this setting.
+
+---
+
 ← [Back to Index](index.md)

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.2.4",
   "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"
   ],

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

@@ -5,54 +5,89 @@ argument-hint: [--env=staging|production]
 
 # Deploy Check
 
-Run a comprehensive pre-deploy validation to produce a go/no-go decision.
+Run a comprehensive pre-deployment check suite before releasing to production.
 
 **Input:** $ARGUMENTS — optional `--env=staging|production` (default: staging)
 
-## Parallel Checks
+## Process
 
-Run three checks simultaneously:
+### Step 1: Parallel Checks
 
-### Check 1 — Test Suite (@tester)
-- Run full test suite
-- Check TDD coverage meets threshold (default: 80%)
-- Report: tests passed/failed, coverage %, any flaky tests
+Launch four checks simultaneously:
 
-### Check 2 — Code Review (@reviewer)
+**Check A: Test Suite (@tester)**
+```bash
+npm test
+```
+All tests must pass. No failures, no skips without justification.
+
+**Check B: Security Scan**
+
+Spawn `@security-auditor` to check:
+- No hardcoded secrets in changed files
+- Input validation at trust boundaries
+- Auth/authz on all protected routes
+- No CRITICAL or HIGH vulnerabilities
+
+**Check C: Dependency CVE Audit**
+```bash
+npm audit --audit-level=high
+```
+No HIGH or CRITICAL CVEs unaddressed.
+
+**Check D: Build Verification**
+```bash
+npm run build
+```
+Build must succeed with zero errors.
+
+**Check E: Code Review (@reviewer)** — parallel with above
 - 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
+### Step 2: Aggregate Results
 
-## Go/No-Go Decision
+```
+## Pre-Deployment Check
 
-**@orchestrator** aggregates results:
+| Check | Status | Details |
+|-------|--------|---------|
+| Tests | ✅ PASS / ❌ FAIL | N/N passed |
+| Security | ✅ PASS / ❌ FAIL | [findings] |
+| CVE Audit | ✅ PASS / ❌ FAIL | [vulnerabilities] |
+| Build | ✅ PASS / ❌ FAIL | [errors] |
+```
 
-| 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) |
+### Step 3: Go/No-Go Decision
 
-## Report
+**🚀 GO** — all checks pass, proceed with deployment.
 
+**🛑 NO-GO** — one or more checks failed:
 ```
-════════════════════════════════════════════
-DEPLOY CHECK — <env>
-════════════════════════════════════════════
-Tests:    <passed>/<total> | Coverage: <X>%
-Security: <N> critical, <M> high
-CVEs:     <N> high, <M> medium
-
-DECISION: GO / NO-GO / CONDITIONAL
-════════════════════════════════════════════
+Verdict: NO-GO
+
+Required fixes before deploy:
+- [ ] [fix 1]
+- [ ] [fix 2]
+
+Run /deploy-check again after fixing.
 ```
 
-For NO-GO: list blocking issues with fix suggestions.
-For CONDITIONAL: list what requires override approval.
+## No-go conditions (automatic)
+
+Any of these → automatic NO-GO:
+- Test failures
+- CRITICAL security vulnerability
+- HIGH/CRITICAL CVE unpatched
+- Build error
+
+## Agent Configuration
+
+| Agent | Purpose |
+|-------|---------|
+| @tester | Run test suite |
+| @security-auditor | Security vulnerability scan |
+| @researcher | CVE research and context |
+| @reviewer | Code quality review |