@dv.nghiem/flowdeck 0.2.3 → 0.3.0

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

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

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

@@ -1,105 +0,0 @@
-# /fd-guarded-edit
-
-**Edit gate command** — evaluates a proposed file change before it is applied and returns a binding gate decision.
-
-Combines: patch trust scoring, architectural constraint checking, policy enforcement, volatility analysis, and failure history into a single pass/block decision.
-
----
-
-## Usage
-
-```
-/fd-guarded-edit --file "<path>" --change "<description>" [flags]
-```
-
-## Arguments
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--file` | string | — | File path being changed |
-| `--change` | string | — | Plain-language description of the change |
-| `--dry-run` | boolean | false | Evaluate without recording or side effects |
-| `--json` | boolean | false | Return raw JSON instead of table |
-
-At least one of `--file` or `--change` is required.
-
----
-
-## Gate decisions
-
-| Decision | Meaning |
-|----------|---------|
-| `auto-approve` | Apply — no action needed (trust ≥70, no violations, stable file) |
-| `require-confirmation` | Review the diff carefully, then confirm (volatile file, guarded mode, or prior failures) |
-| `require-review` | Route to human reviewer — do not auto-apply (trust <40 or policy violation) |
-| `block` | Do NOT apply — arch constraint violation or critical policy breach |
-
-### Decision priority (highest first)
-
-1. Arch constraint violated → **block**
-2. Policy violation + trust < 30 → **block**
-3. `review-only` execution mode → **require-review**
-4. Trust < 40 OR any policy violation → **require-review**
-5. `guarded` execution mode OR volatile file OR prior failures → **require-confirmation**
-6. All else → **auto-approve**
-
----
-
-## Output
-
-```
-════════════════════════════════════════════════════════════
-fd-guarded-edit
-────────────────────────────────────────────────────────────
-  File:   src/auth/token.ts
-  Change: replace jwt secret rotation logic
-────────────────────────────────────────────────────────────
-  ⚑ Decision:    REQUIRE-REVIEW
-  Reason:       High risk: trust score 32/100, 0 policy violation(s)
-  Risk score:   32/100 (high-risk)
-  Exec mode:    guarded
-  Prior fails:  F-023, F-031
-────────────────────────────────────────────────────────────
-  → Route to human reviewer before applying — do not auto-apply
-════════════════════════════════════════════════════════════
-```
-
-### Fields returned
-
-| Field | Description |
-|-------|-------------|
-| `decision` | Gate decision string |
-| `reason` | Explanation for the decision |
-| `risk_score` | Patch trust score 0–100 |
-| `execution_mode` | Current repo execution mode (auto/guarded/review-only) |
-| `policy_violations` | Policy rule strings that were triggered |
-| `volatile_files` | Files that matched volatile/critical zones |
-| `prior_failures` | Failure IDs for prior failures on this path |
-| `arch_constraint` | Whether an architectural constraint was violated |
-| `recommended_action` | Plain-language next step |
-
----
-
-## Examples
-
-```bash
-# Check before editing auth token logic
-/fd-guarded-edit --file "src/auth/token.ts" --change "replace secret rotation"
-
-# Dry run (evaluate without recording)
-/fd-guarded-edit --file "src/payment/webhook.ts" --change "update stripe handler" --dry-run
-
-# JSON for CI/CD pipeline integration
-/fd-guarded-edit --file "src/core/engine.ts" --change "patch core engine" --json
-```
-
----
-
-## Data sources read
-
-- `.codebase/POLICIES.json` — active policy rules
-- `.codebase/VOLATILITY.json` — volatile/critical paths
-- `.codebase/FAILURES.json` — unresolved prior failures per path
-- `.codebase/CONSTRAINTS.md` — forbidden path patterns
-- `.planning/config.json` — execution mode setting
-- Patch trust scorer — keyword + volatility scoring

package/docs/commands/fd-progress.md

@@ -1,11 +0,0 @@
----
-description: Display current STATE.md, active PLAN.md, and recent results
----
-Run the FlowDeck progress command to see current project state.
-
-## What Next?
-
-1. **Continue feature work** → `/fd-new-feature [description]`
-2. **Fix a bug** → `/fd-fix-bug [issue]`
-3. **View dashboard** → `/fd-dashboard`
-4. **Check roadmap** → `/fd-roadmap`

package/docs/commands/fd-review-code.md

@@ -1,29 +0,0 @@
----
-description: Parallel code review — reviewer + researcher + tester — aggregates into critical/major/minor report
-argument-hint: "[scope: file, directory, or 'staged']"
----
-
-Run a comprehensive parallel code review.
-
-**What this does:**
-1. Determines scope: staged changes, a file/directory, or the whole PR
-2. Runs `@reviewer` (security, quality, logic), `@researcher` (API correctness), and `@tester` (test coverage) in parallel
-3. Aggregates findings into a single report ranked: CRITICAL → HIGH → MEDIUM → LOW
-4. Proposes fixes for every CRITICAL and HIGH finding
-5. Skips stylistic preferences — only real bugs and security issues
-
-**Output format:**
-```
-## Code Review Report
-### CRITICAL [n]
-- [finding]: [file:line] — [fix]
-### HIGH [n]
-...
-```
-
-## What Next?
-
-1. **Fix critical issues found** → `/fd-fix-bug [issue description]`
-2. **Deploy check** → `/fd-deploy-check`
-3. **Update documentation** → `/fd-write-docs`
-4. **Check project progress** → `/fd-progress`

package/docs/commands/fd-roadmap.md

@@ -1,10 +0,0 @@
----
-description: View or update the project roadmap — shows phase statuses and milestones
----
-Run the FlowDeck roadmap workflow to view or update project phases and milestones.
-
-## What Next?
-
-1. **Start next phase** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`

package/docs/commands/fd-settings.md

@@ -1,10 +0,0 @@
----
-description: View or update FlowDeck settings — model assignments, guard enforcement, workspace mode
----
-Run the FlowDeck settings command to view or modify configuration.
-
-## What Next?
-
-1. **View dashboard** → `/fd-dashboard`
-2. **Check progress** → `/fd-progress`
-3. **Start working** → `/fd-new-feature [description]`

package/docs/parallel-execution.md

@@ -1,227 +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`
-
----
-
-← [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
-    }
-  ]
-}
-```