@dv.nghiem/flowdeck 0.2.4 → 0.3.0

package/docs/parallel-execution.md

@@ -1,255 +0,0 @@
-# Parallel Execution
-
-FlowDeck can coordinate multiple agents working simultaneously on independent tasks. This is managed by the `@parallel-coordinator` agent using a wave-based execution model.
-
----
-
-## When to Use Parallel Execution
-
-Parallel execution pays off when:
-
-- A feature decomposes into clearly independent tracks (research, implementation, documentation)
-- The codebase has well-separated modules with distinct file ownership
-- Review and security audit need to happen simultaneously (they always can)
-- Estimated total work exceeds 30 minutes
-
-## When NOT to Use It
-
-Avoid parallel execution when:
-
-- Total estimated work is under 30 minutes — coordination overhead outweighs the gain
-- File ownership is unclear — parallel agents editing the same files produce merge conflicts
-- Task B depends directly on task A's output — sequential is correct here, not parallel
-
----
-
-## The WAVE TABLE
-
-When `@parallel-coordinator` plans work, it produces a WAVE TABLE that maps each wave to its agents, and records any inter-wave dependencies:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  WAVE TABLE — [Feature Name]                                 ║
-╠══════════════════════════════════════════════════════════════╣
-║  Wave 1 (parallel)  │ @researcher + @code-explorer          ║
-║  Wave 2 (serial)    │ @architect                             ║
-║  Wave 3 (parallel)  │ @coder + @tester                      ║
-║  Wave 4 (parallel)  │ @reviewer + @security-auditor         ║
-╠══════════════════════════════════════════════════════════════╣
-║  Dependency lock:   │ Wave 3 blocked on Wave 2 output        ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-The dependency lock line explicitly documents which wave gates are in effect. `@parallel-coordinator` enforces these locks — Wave 3 will not begin until Wave 2 output is confirmed available.
-
----
-
-## Standard 4-Wave Pattern
-
-### Wave 1 — Research (always parallel)
-
-**Agents:** `@researcher` + `@code-explorer`
-
-These two agents run simultaneously because neither depends on the other's output.
-
-- **`@researcher`** — gathers external context: API documentation, library docs, relevant RFCs, prior art, and best practices for the problem domain
-- **`@code-explorer`** — maps the existing codebase: which patterns are in use, which modules will be affected, which conventions must be followed
-
-Both results feed into Wave 2 as inputs. `@architect` should not begin until both are complete.
-
----
-
-### Wave 2 — Design (always serial)
-
-**Agent:** `@architect`
-
-Wave 2 is intentionally serial. Architecture decisions are the foundation everything else builds on — running `@coder` before `@architect` is done produces code that must be thrown away.
-
-`@architect` consumes Wave 1 outputs and produces:
-
-- **Interface contracts** — function signatures, type definitions, API shapes
-- **Data models** — schemas, entity relationships, persistence strategy
-- **ADRs (Architecture Decision Records)** — the key decisions made and the alternatives rejected, with rationale
-
-Wave 2 output is written to `.planning/phases/*/ARCH.md` and is the authoritative specification for Wave 3.
-
----
-
-### Wave 3 — Execution (usually parallel)
-
-**Agents:** `@coder` + `@tester`
-
-`@coder` and `@tester` can run in parallel because both work from the same Wave 2 interface contracts — neither needs to see the other's actual implementation.
-
-- **`@coder`** — implements the interfaces and data models specified by `@architect`. Works top-down from contracts, not bottom-up from intuition.
-- **`@tester`** — writes tests against the same Wave 2 interface contracts. Because tests are written to the contract (not the implementation), they are valid before `@coder` finishes.
-
-When Wave 3 completes, tests should be passing against the new implementation. If they are not, `@coder` and `@tester` reconcile before Wave 4 begins.
-
-> **Note:** Wave 3 is marked "usually parallel" because some features have sequential implementation requirements — for example, a migration that must run before the new code can be tested. `@parallel-coordinator` identifies these cases from the Wave 2 output and adjusts accordingly.
-
----
-
-### Wave 4 — Verification (always parallel)
-
-**Agents:** `@reviewer` + `@security-auditor`
-
-Both agents review the same codebase snapshot but look for different issues — they can always run in parallel.
-
-- **`@reviewer`** — checks code quality, logic correctness, error handling completeness, naming, and adherence to the project's coding standards
-- **`@security-auditor`** — runs through the OWASP checklist, checks authentication and authorization logic, scans for injection vulnerabilities, and verifies that no secrets are present in the diff
-
-Wave 4 produces a joint findings report. Findings are classified as:
-
-| Severity | Meaning |
-|----------|---------|
-| **Critical** | Must be resolved before the code is merged |
-| **Major** | Should be resolved; skipping requires explicit justification |
-| **Minor** | Suggestions; no blocking requirement |
-
-If Critical findings exist, the flow returns to Wave 3 (`@coder`) for remediation before re-entering Wave 4.
-
----
-
-## Triggering Parallel Execution
-
-### Automatic (via `/fd-new-feature`)
-
-```
-/fd-new-feature "payment integration with Stripe"
-```
-
-The `@orchestrator` estimates scope for every `/fd-new-feature` call. If the feature exceeds approximately 30 minutes of estimated work, `@orchestrator` automatically hands off to `@parallel-coordinator`, which builds the WAVE TABLE and begins Wave 1.
-
-You do not need to specify parallel execution — it is selected based on scope.
-
-### Manual (direct invocation)
-
-For work that does not go through `/fd-new-feature`, invoke `@parallel-coordinator` directly:
-
-```
-@parallel-coordinator I need to implement the notification system.
-Track 1: email notifications via SendGrid
-Track 2: push notifications via Firebase FCM
-Track 3: SMS notifications via Twilio
-```
-
-`@parallel-coordinator` will:
-1. Identify which tracks are fully independent
-2. Build a WAVE TABLE appropriate for the work
-3. Manage agent dispatch, output collection, and inter-wave handoffs
-
----
-
-## Merge Protocol
-
-After parallel waves complete, `@parallel-coordinator` classifies the combined output by conflict type:
-
-- **Additive** — each agent touched different files and different modules. These are merged automatically with no manual review required.
-- **Structural** — agents touched the same module but made compatible changes (e.g., both added new functions to the same file). `@parallel-coordinator` merges and flags the overlapping area for `@reviewer`.
-- **Contradictory** — agents produced conflicting design decisions (e.g., `@coder` implemented a REST interface while `@tester` assumed a message queue). These are escalated to `@architect` for resolution before any merge occurs.
-
-The merge classification is written to `.planning/phases/*/MERGE.md` so the resolution is traceable.
-
----
-
-## Using the `run-parallel` Tool
-
-The `run-parallel` plugin tool is available in all FlowDeck sessions. It provides lower-level control over parallel dispatch when you want to coordinate agents yourself without going through `@parallel-coordinator`:
-
-```
-Use the run-parallel tool to execute @researcher and @code-explorer simultaneously
-on the topic of rate-limiting strategies for REST APIs.
-```
-
-```
-Use the run-parallel tool to run @reviewer on src/payments/ and 
-@security-auditor on src/payments/ at the same time, then combine their findings.
-```
-
-`run-parallel` is best used when:
-- You have exactly two independent tasks and do not need full WAVE TABLE management
-- You want to parallelize review and audit on a specific directory after manual edits
-- You are running a one-off investigation, not a full feature pipeline
-
-For full feature work, prefer `/fd-new-feature` or direct `@parallel-coordinator` invocation over the `run-parallel` tool.
-
----
-
-## Using the `delegate` Tool
-
-The `delegate` tool runs a single agent in an isolated child session and returns its output. Use it when you need a focused sub-task completed by a specific agent without disrupting the current session context:
-
-```
-Use the delegate tool to ask @security-auditor to review src/auth/login.ts
-and report back any vulnerabilities found.
-```
-
-```
-Use the delegate tool with context "existing schema: ..." to ask @architect to
-propose a migration plan.
-```
-
-`delegate` supports an optional `context` field — any string prepended to the agent's prompt. This is useful for passing output from a prior step without polluting the current conversation.
-
----
-
-## Using the `run-pipeline` Tool
-
-The `run-pipeline` tool chains agents sequentially: each step's output becomes part of the next step's input. This is the right tool when tasks must happen in order and each depends on the previous result:
-
-```
-Use the run-pipeline tool with steps:
-  1. agent: planner, prompt: "Analyze the codebase and produce an implementation plan for the auth refactor"
-  2. agent: coder, prompt: "Implement the plan"
-  3. agent: reviewer, prompt: "Review the implementation for correctness and security"
-```
-
-Key behaviors:
-- Each step gets its own fresh child session (no hidden state accumulates between steps)
-- The previous step's text output is automatically prepended to the next step's prompt
-- Set `abort_on_failure: false` to continue the pipeline even if a step fails
-- Provide `initial_context` to seed the first step with prior information
-
----
-
-## Implementation Notes
-
-All three dispatch tools (`run-parallel`, `delegate`, `run-pipeline`) create real OpenCode child sessions via `client.session.create` and `client.session.prompt`. They:
-
-- Use `parentID` to link child sessions to the current session
-- Check both transport-level errors (`response.error`) and agent-level errors (`response.data.info.error`)
-- Register an abort listener on the parent context so child sessions are cancelled if the parent aborts
-- Return structured JSON with per-task/step results including `session_id`, `success`, and `duration_ms`
-
----
-
-## 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/src/commands/fd-analyze-change.md

@@ -1,57 +0,0 @@
----
-description: Pre-change analysis — runs impact radar, blast radius, regression prediction, test gaps, volatility, and reviewer routing in one report
-argument-hint: [change description]
----
-
-# Analyze Change
-
-Run a comprehensive pre-change analysis combining all intelligence tools into a single report.
-
-**Input:** $ARGUMENTS — description of the proposed change
-
-## Steps
-
-Run all analyses in parallel:
-
-1. **Impact Radar** — which files/APIs/tests are affected (see `/fd-impact-radar`)
-2. **Blast Radius** — downstream consequences and hidden couplings (see `/fd-blast-radius`)
-3. **Regression Predict** — most likely regression categories (see `/fd-regression-predict`)
-4. **Test Gap** — coverage gaps to fill before implementing (see `/fd-test-gap`)
-5. **Volatility** — check `.codebase/VOLATILITY.json` for hotspot scores on affected files
-6. **Review Route** — who should review this change (see `/fd-review-route`)
-
-## Consolidated Report
-
-```
-════════════════════════════════════════════════════
-PRE-CHANGE ANALYSIS: "$ARGUMENTS"
-════════════════════════════════════════════════════
-
-IMPACT (<N> files affected)
-  - <top 5 affected files with reason>
-
-BLAST RADIUS (risk: <low|medium|high>)
-  - <key downstream risks>
-
-REGRESSIONS (top 3 risks)
-  🔴 <category> — <reason>
-  🟠 <category> — <reason>
-
-TEST GAPS (<N> gaps found)
-  - CRITICAL: <gap>
-  - HIGH: <gap>
-
-VOLATILITY
-  Hot zones touched: <list or "none">
-
-REVIEW ROUTING
-  → <reviewer type> (<reason>)
-
-────────────────────────────────────────────────────
-RECOMMENDATION: <proceed | add tests first | redesign | review required>
-
-Next steps:
-  1. <most important action>
-  2. <second action>
-════════════════════════════════════════════════════
-```

package/src/commands/fd-approve.md

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

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

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

package/src/commands/fd-dashboard.md

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

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

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

package/src/commands/fd-guarded-edit.md

@@ -1,69 +0,0 @@
----
-description: Edit gate — decides auto-approve / require-confirmation / require-review / block based on policy, trust score, volatility, and arch constraints
-argument-hint: [change description or file path]
----
-
-# Guarded Edit
-
-Evaluate a proposed edit against all safety gates before allowing it to proceed.
-
-**Input:** $ARGUMENTS — description or file path of the proposed edit
-
-## Gates (evaluated in order)
-
-### Gate 1 — Policy Check
-
-Read `.planning/config.json` for active policies:
-- `approval_required`: if true, all edits need explicit approval
-- `volatility_threshold`: edits touching files above this score need confirmation
-
-### Gate 2 — Volatility Check
-
-Check `.codebase/VOLATILITY.json` for the files in `$ARGUMENTS`.
-- Score ≥ 0.8 → REQUIRE REVIEW
-- Score ≥ 0.6 → REQUIRE CONFIRMATION
-- Score < 0.6 → proceed
-
-### Gate 3 — Architecture Constraints
-
-Read `.codebase/ARCHITECTURE.md` and check if the edit:
-- Crosses defined service boundaries
-- Modifies public API contracts
-- Touches security-critical paths (auth, payments, PII)
-
-### Gate 4 — Trust Score
-
-Check `.codebase/FAILURES.json` for prior failures in the same path.
-- 3+ prior failures in this area → REQUIRE REVIEW
-- 1-2 prior failures → REQUIRE CONFIRMATION
-
-## Decision Matrix
-
-| Condition | Decision |
-|-----------|----------|
-| Any BLOCK signal | ❌ BLOCK |
-| REQUIRE REVIEW signal | 👁️ REQUIRE REVIEW |
-| REQUIRE CONFIRMATION signal | ⚠️ REQUIRE CONFIRMATION |
-| All gates pass | ✅ AUTO-APPROVE |
-
-## Report
-
-```
-════════════════════════════════════
-GUARDED EDIT GATE
-════════════════════════════════════
-Edit: <summary>
-
-Gate 1 — Policy:      <pass|flag>
-Gate 2 — Volatility:  <score> → <pass|confirm|review>
-Gate 3 — Arch:        <pass|flag>
-Gate 4 — Trust:       <failures count> → <pass|confirm|review>
-
-DECISION: AUTO-APPROVE / CONFIRM / REVIEW / BLOCK
-
-<if BLOCK or REVIEW: explain what needs to happen first>
-════════════════════════════════════
-```
-
-If BLOCK: do not proceed with the edit. Explain what must change first.
-If CONFIRM: present to user and wait for explicit "yes" before proceeding.

package/src/commands/fd-impact-radar.md

@@ -1,51 +0,0 @@
----
-description: Change Impact Radar — predict which files, modules, APIs, tests, and DB paths are affected before editing anything
-argument-hint: [change description]
----
-
-# Impact Radar
-
-Predict the blast area of a proposed change before any code is written.
-
-**Input:** $ARGUMENTS — description of the proposed change
-
-## Steps
-
-Run three agents in parallel:
-
-- **@researcher**: Trace dependency graph from the paths mentioned in `$ARGUMENTS`; find all files that import or are imported by those modules; map 2 levels deep
-
-- **@architect**: Identify API contracts and service boundaries at risk; flag any public interfaces that would change; check for DB schema impacts
-
-- **@tester**: Find test files that cover the affected paths; identify which tests would need updating; spot gaps (changed files with no tests)
-
-## Report
-
-```
-════════════════════════════════════════════
-CHANGE IMPACT RADAR
-════════════════════════════════════════════
-Change: <summary of $ARGUMENTS>
-Risk score: <low|medium|high>
-
-Affected Files (<N>):
-  - <file> (<reason>)
-
-API Contracts at Risk:
-  - <interface/endpoint> — <risk>
-
-Tests to Update (<N>):
-  - <test file>
-
-Test Gaps (<N> files with no tests):
-  - <file>
-
-DB / Schema Impact:
-  - <none | description>
-
-Recommendation:
-  <proceed with caution | review required | block>
-════════════════════════════════════════════
-```
-
-If no impact found: "No significant impact detected. Proceed with standard review."