@dv.nghiem/flowdeck 0.3.9 → 0.4.1

package/docs/commands/fd-verify.md

@@ -1,18 +1,75 @@
----
-description: Review code quality, security, and conventions — runs parallel @reviewer + @security-auditor agents
-argument-hint: "[file-pattern|dir|stage number]"
----
+# /fd-verify
 
-Run the FlowDeck code review workflow. Reviews can target:
-- **Specific files or directories** — `fd-verify src/services/`
-- **Git staged changes** — `fd-verify staged`
-- **Full project** — `fd-verify`
+**Purpose:** Full verification pipeline after feature implementation — runs tests, code review, security scan, and deploy check; updates STATE.md to `verified` on full pass.
 
-## What Next?
+## Usage
 
-1. **Fix issues found** → `/fd-fix-bug [issue]`
-2. **Create deployment checkpoint** → `/fd-checkpoint`
-3. **Deploy to production** → `/fd-deploy-check`
-4. **View project dashboard** → `/fd-dashboard`
+/fd-verify [--phase=N] [--env=staging|production]
 
-Type the number or command to proceed.
+## What Happens
+
+1. **Pre-flight checks.**
+   - Verify `.planning/` and STATE.md exist
+   - Read current phase N from STATE.md
+   - Warn if `steps_complete` is empty (no steps executed yet)
+
+2. **Gather scope.**
+   - Collect changed files via `git diff --name-only HEAD`
+   - If no changes, use all files in the current phase directory
+   - Run `codegraph action=check` — if available, use `codegraph_impact` on changed files to surface dependent modules not caught by `git diff`
+
+3. **Run four checks in parallel:**
+
+   - **Tests (@tester):** `npm test` — all tests must pass, no failures or unexplained skips
+   
+   - **Code Review (@reviewer):** Review all changed files — security (secrets, injection, auth gaps), quality (critical bugs, error handling, TDD discipline), conventions (naming, patterns, import style), >= 80% test coverage for changed files. If UI-heavy: design fidelity review against approved design artifact
+   
+   - **UI Design Review (@design):** If UI-heavy — compare implemented UI to approved design artifact, report on hierarchy, spacing, CTA flow, responsiveness, accessibility, and missing state coverage. Fail verification on severe design fidelity mismatch
+   
+   - **Security Scan (@security-auditor):** No hardcoded secrets, input validation at trust boundaries, auth/authz on all protected routes, no CRITICAL/HIGH vulnerabilities
+   
+   - **Deploy Check:** `npm audit --audit-level=high` and `npm run build` — no HIGH/CRITICAL CVEs, build must succeed
+
+4. **Aggregate results.** Present consolidated table with pass/fail status for each check.
+
+5. **Go/No-Go decision.**
+
+   **VERIFIED (all checks pass):**
+   - Update STATE.md: `status: verified`, `last_action: "Phase N verified — all checks passed"`, `verified_at: <timestamp>`
+   - Report next steps (deploy, increment phase, etc.)
+
+   **NOT VERIFIED (one or more checks fail):**
+   - List required fixes
+   - Do NOT update STATE.md to verified status
+   - Report suggested next step (run `/fd-execute` for fixes, then `/fd-verify` again)
+
+6. **No-Go conditions (automatic NOT VERIFIED):** test failures, CRITICAL security vulnerability, unpatched HIGH/CRITICAL CVE, build error, CRITICAL code review finding.
+
+## Output / State
+
+STATE.md on verified:
+```yaml
+status: verified
+last_action: "Phase N verified — all checks passed"
+verified_at: "<timestamp>"
+```
+
+## Examples
+
+```
+/fd-verify
+```
+
+Run full verification pipeline for the current phase.
+
+```
+/fd-verify --phase=2 --env=staging
+```
+
+Verify phase 2 and run deploy check against staging environment.
+
+## Related Commands
+
+- `/fd-execute` — implement the feature before verification
+- `/fd-plan` — create the plan that was verified against
+- `/fd-resume` — reload state after making fixes

package/docs/commands/fd-write-docs.md

@@ -1,10 +1,123 @@
----
-description: Write documentation — explore public APIs, writer drafts, reviewer accuracy check
----
-Run the FlowDeck write-docs workflow to generate accurate project documentation.
+# /fd-write-docs
 
-## What Next?
+**Purpose:** Explore APIs and generate accurate, up-to-date documentation from the codebase.
 
-1. **Review documentation** → `/fd-verify staged`
-2. **Deploy check** → `/fd-deploy-check`
-3. **Create checkpoint** → `/fd-checkpoint`
+## Usage
+
+/fd-write-docs [--scope=path] [--format=api,guide,readme]
+
+## Arguments
+
+- `--scope=path` (optional) — limit documentation scope to a specific path
+- `--format=api|guide|readme` (optional) — output format: `api` (API reference), `guide` (usage guide), `readme` (README). Default: all formats
+
+## What Happens
+
+### Step 1: CodeGraph Intelligence Check
+
+Before any file exploration, check if codegraph provides a pre-built symbol index:
+```
+codegraph action=check
+```
+
+- **If codegraph indexed (fresh)**: Use `codegraph_search`, `codegraph_explore`, `codegraph_node` to enumerate exported symbols and API entry points. Log: "codegraph available — using symbol index for API discovery".
+- **If codegraph absent or stale**: Fall through to @mapper-based exploration.
+
+### Step 2: Explore APIs
+
+**If codegraph is available:**
+```
+codegraph_search("export ")           # exported symbols
+codegraph_explore("<scope or src/>")  # survey module structure
+codegraph_context("<key entry points>") # full context per area
+```
+
+**If codegraph is not available:**
+Spawn `@mapper` to:
+- Find all exported functions, classes, and types
+- Identify public API entry points
+- Map key workflows and integration points
+
+Fallback commands:
+```bash
+grep -rn "export " src/ --include="*.ts"
+grep -rn "export interface\|export type\|export class" src/ --include="*.ts"
+```
+
+### Step 3: Draft Documentation
+
+Spawn `@writer` to produce:
+
+**API Reference:**
+```markdown
+## functionName(param: Type): ReturnType
+
+Description of what the function does.
+
+**Parameters:**
+- `param` (Type) — description
+
+**Returns:** description
+
+**Example:**
+\`\`\`typescript
+const result = functionName(value);
+\`\`\`
+```
+
+**Usage Guide:**
+- Step-by-step workflow with examples
+- Common patterns and best practices
+- Configuration options
+
+**Troubleshooting:**
+- Common errors and their solutions
+
+### Step 4: Review for Accuracy
+
+Spawn `@reviewer` to verify:
+- Every documented function/method actually exists
+- Parameter types match the actual signatures
+- Examples are syntactically correct
+- No outdated API references
+
+If codegraph is available: use `codegraph_node` to verify specific function signatures against documentation.
+
+### Step 5: Finalize
+
+Writer incorporates feedback and writes final docs to:
+- `README.md` — project overview and quick start
+- `docs/API.md` — complete API reference
+- `docs/USER_GUIDE.md` — detailed usage guide
+
+## Output / State
+
+Updated documentation files:
+- `README.md` — project overview and quick start
+- `docs/API.md` — complete API reference
+- `docs/USER_GUIDE.md` — detailed usage guide
+
+Report: files written/updated, public APIs documented, any gaps found, codegraph used status.
+
+## Examples
+
+**Generate all documentation formats:**
+```
+/fd-write-docs
+```
+
+**Generate only API reference for a specific scope:**
+```
+/fd-write-docs --scope=src/api --format=api
+```
+
+**Generate README for the project root:**
+```
+/fd-write-docs --format=readme
+```
+
+## Related Commands
+
+- `/fd-map-codebase` — generate the codebase documentation that informs API exploration
+- `/fd-discuss` — explore before writing to understand what matters most
+- `/fd-verify` — validate documentation accuracy after generation

package/docs/concepts/architecture.md

@@ -0,0 +1,163 @@
+# Architecture
+
+FlowDeck is a plugin that runs inside OpenCode. It layers a structured multi-agent orchestration system on top of the base OpenCode runtime, contributing commands, specialist agents, runtime services, and event-driven hooks.
+
+## Layering
+
+```
+OpenCode
+  └── FlowDeck Plugin
+        ├── Commands (CLI entry points)
+        ├── Agents (25 specialists, delegated by orchestrator)
+        ├── Services (governance, intelligence, council)
+        └── Hooks (session-start, compaction, shell-env, etc.)
+```
+
+**OpenCode** provides the underlying runtime: tool execution, file I/O, shell access, MCP integrations, and the conversation UI.
+
+**FlowDeck** adds the workflow layer on top. It does not replace OpenCode's core — it extends it with opinionated orchestration, persistent state, and AI safety services.
+
+## Four Subsystems
+
+### Commands
+
+Commands are the user-facing entry points. They are registered as slash commands in the OpenCode CLI (e.g., `/fd-map-codebase`, `/fd-new-feature`, `/fd-plan`, `/fd-execute`). Each command:
+
+1. Reads current planning or codebase state
+2. Invokes the appropriate specialist agents via the `delegate` or `run-pipeline` tools
+3. Writes results back to `.planning/` state files
+4. Optionally triggers hooks to react to the state change
+
+Commands are implemented as Markdown templates with frontmatter metadata in `src/commands/`. The plugin loader reads them and registers them at startup.
+
+### Agents
+
+FlowDeck ships 25 specialist agents, each responsible for a narrow domain:
+
+| Agent | Role |
+|-------|------|
+| `@orchestrator` | Coordinates the workflow; delegates to specialists |
+| `@architect` | Designs system structure and component boundaries |
+| `@planner` | Breaks features into wave-structured tasks |
+| `@coder` | Implements features; follows TDD discipline |
+| `@tester` | Writes and maintains tests |
+| `@reviewer` | Reviews code quality and style |
+| `@debugger` | Diagnoses and fixes failures |
+| `@risk-analyst` | Identifies technical risk in plans |
+| `@policy-enforcer` | Validates compliance with project rules |
+| `@discusser` | Runs structured pre-planning Q&A |
+| `@designer` | UI/UX design decisions |
+| ... and 15 more | |
+
+The orchestrator is the default agent. All other agents are invoked via the `delegate` tool or `run-pipeline` tool. Every agent inherits the currently active OpenCode model by default; individual agents can be overridden in `flowdeck.json`.
+
+### Services
+
+Services are runtime components that run continuously, not as part of a linear workflow:
+
+- **Governance services** — validate agent contracts, enforce delegation budgets, detect loops, and score workflow quality
+- **Intelligence services** — compute patch trust scores, volatility maps, failure replays, and regression predictions
+- **Council service** — synthesizes consensus from multiple specialized agents via the `council` tool
+
+Services are invoked by hooks (before/after tool execution) or by commands that need on-demand analysis.
+
+### Hooks
+
+Hooks are event handlers registered with OpenCode's plugin API. FlowDeck registers the following hooks:
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| `session.started` | New session begins | Initialize planning state, load config |
+| `session.idle` | Session idle detected | Generate idle summary, auto-learn |
+| `experimental.session.compacting` | Context window near full | Compact session state |
+| `tool.execute.before` | Before any tool runs | Patch trust, guard rails, telemetry, supervisor preflight |
+| `tool.execute.after` | After any tool completes | Telemetry, supervisor post-execution review |
+| `file.edited` | File changed on disk | Track file modifications |
+| `shell.env` | Shell command runs | Inject FlowDeck state into shell |
+| `todo.updated` | Todo list changes | Sync todo state |
+
+## State Flow
+
+State flows through the system in a one-way pipeline:
+
+```
+Commands
+  │  (invoke agents via delegate / run-pipeline)
+  ▼
+Agents
+  │  (produce artifacts, write state)
+  ▼
+Services (governance + intelligence)
+  │  (validate, score, predict — write to .codebase/)
+  ▼
+Hooks
+  │  (react to tool events, trigger re-entry)
+  ▼
+State files
+  ├── .planning/
+  │     STATE.md      — current workflow phase, active feature, checkpoint
+  │     PLAN.md       — wave-structured execution plan
+  │     PROJECT.md    — project overview and constraints
+  │     ROADMAP.md    — feature roadmap
+  │     FEATURE.md    — current feature context
+  │     DISCUSS.md    — pre-planning decisions
+  │     multi-repo/   — multi-repo coordination state
+  └── .codebase/
+        AGENT_SPANS.jsonl    — causal delegation spans
+        BUDGETS.json         — delegation budget consumption
+        DEADLOCK_SIGNALS.jsonl — loop/bounce detections
+        SCORECARDS.jsonl     — per-run quality scores
+        CODEGRAPH.json        — codebase structure index
+        VOLATILITY.json       — change-frequency map
+```
+
+Commands read from and write to `.planning/`. Services write to `.codebase/`. Hooks read both directories and may trigger re-entry into the command pipeline.
+
+## Model-Agnostic Design
+
+FlowDeck makes no model assumptions. Every agent call passes through the active OpenCode model unless overridden per-agent in `flowdeck.json`:
+
+```json
+{
+  "agents": {
+    "planner": { "model": "anthropic/claude-opus-4" },
+    "tester":  { "model": "openai/gpt-4o-mini" }
+  }
+}
+```
+
+Agents not listed inherit the global model. Override at the agent level, not the system level.
+
+## Tool Map
+
+FlowDeck registers these tools for use by agents and commands:
+
+| Tool | Purpose |
+|------|---------|
+| `planning-state` | Read/write `.planning/STATE.md` |
+| `codebase-state` | Read/write `.codebase/` state files |
+| `workspace-state` | Snapshot workspace files and git status |
+| `run-pipeline` | Execute a defined pipeline of agent steps |
+| `delegate` | Invoke a named specialist agent |
+| `council` | Run multiple agents and synthesize consensus |
+| `volatility-map` | Compute change frequency per file |
+| `failure-replay` | Reproduce and trace a prior failure |
+| `decision-trace` | Record and replay decision rationale |
+| `hash-edit` | Compute a content hash for an edit |
+| `policy-engine` | Evaluate agent actions against project rules |
+| `repo-memory` | Persistent memory across sessions |
+| `context-generator` | Generate focused context summaries |
+| `codegraph` | Query codebase structure from indexed graph |
+
+## Plugin Initialization
+
+On startup, the plugin:
+
+1. Reads `flowdeck.json` from the project directory
+2. Registers all slash commands from `src/commands/`
+3. Registers all agents from `src/agents/`
+4. Registers all hooks with the OpenCode plugin API
+5. Registers tools, MCP servers, and skills directories
+6. Sets `default_agent` to `orchestrator` if not already configured
+
+The plugin is passive until a user invokes a FlowDeck command or an OpenCode event triggers a hook.

package/docs/concepts/governance.md

@@ -0,0 +1,242 @@
+# Governance
+
+FlowDeck's governance layer makes multi-agent execution trustworthy and auditable. It consists of six runtime services that run continuously, intercepting agent tool calls, tracking delegation, enforcing budgets, and scoring workflow quality.
+
+Governance is transparent — every service writes its output to a machine-readable file in `.codebase/` so runs can be audited after the fact.
+
+---
+
+## 1. Agent Contract Registry
+
+Every agent type has a **contract**: a declarative specification of what it is allowed to do and what it must not do.
+
+A contract defines:
+
+- **allowed-tools** — the list of tools the agent may call
+- **forbidden-tools** — tools the agent may never call
+- **required-inputs** — fields that must be present in the delegation call
+- **success-criteria** — conditions that must be true after execution
+
+Example contract for `@coder`:
+
+```json
+{
+  "agent": "coder",
+  "allowed-tools": ["read", "edit", "write", "bash", "run-pipeline"],
+  "forbidden-tools": ["delete", "remove", "drop"],
+  "required-inputs": ["prompt", "files"],
+  "success-criteria": [
+    "all edited files pass linter",
+    "no test coverage decrease"
+  ]
+}
+```
+
+Contracts are defined in `src/agents/` as part of each agent's configuration. The registry is consulted by the Agent Validator before and after every agent invocation.
+
+---
+
+## 2. Agent Validator
+
+The Agent Validator checks every agent call against the agent's contract. It operates in three modes:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | No checking — governance overhead is zero |
+| `advisory` | Logs violations; execution continues |
+| `strict` | Throws an error and halts execution on violation |
+
+**Before invocation checks:**
+
+- The agent name resolves to a known contract
+- All `required-inputs` are present in the delegation call
+- No forbidden tools are in the call
+
+**After invocation checks:**
+
+- `success-criteria` conditions are evaluated against the execution result
+- Violations are logged to `.codebase/AGENT_SPANS.jsonl` under the span's metadata
+
+Configuration in `flowdeck.json`:
+
+```json
+{
+  "governance": {
+    "validator": { "mode": "advisory" }
+  }
+}
+```
+
+---
+
+## 3. Inter-Agent Trace Graph
+
+Every delegation — the orchestrator invoking a specialist, or a specialist invoking a sub-agent — is recorded as a **causal span** in `.codebase/AGENT_SPANS.jsonl`.
+
+Each span records:
+
+```json
+{
+  "span_id": "s1a2b3c",
+  "parent_id": "s0a1b2c",
+  "agent": "coder",
+  "tool": "delegate",
+  "prompt": "Implement user authentication",
+  "files": ["src/auth/login.ts"],
+  "started_at": "2026-05-26T10:00:00Z",
+  "finished_at": "2026-05-26T10:05:00Z",
+  "violations": [],
+  "result": "success"
+}
+```
+
+Spans form a tree rooted at the orchestrator. This trace is used by:
+
+- The Deadlock Detector to identify circular delegation
+- The Workflow Scorecard to measure delegation depth
+- Post-session audits to reconstruct exactly what ran
+
+---
+
+## 4. Delegation Budget
+
+Every run has a **delegation budget** — per-run limits that prevent runaway agent chains. Budgets are tracked in `.codebase/BUDGETS.json`.
+
+```json
+{
+  "run_id": "run-2026-05-26-001",
+  "limits": {
+    "maxToolCalls": 200,
+    "maxDepth": 8,
+    "maxSameStepRetries": 3,
+    "maxSubAgentDelegations": 40
+  },
+  "consumed": {
+    "toolCalls": 47,
+    "depth": 3,
+    "sameStepRetries": 1,
+    "subAgentDelegations": 12
+  }
+}
+```
+
+When a budget limit is reached, the agent receives an error and must stop or request user approval to continue.
+
+Configuration:
+
+```json
+{
+  "governance": {
+    "delegationBudget": {
+      "maxToolCalls": 200,
+      "maxDepth": 8,
+      "maxSameStepRetries": 3
+    }
+  }
+}
+```
+
+---
+
+## 5. Deadlock / Loop Detector
+
+The Deadlock Detector monitors spans and budget consumption for patterns that indicate an agent chain is stuck:
+
+| Pattern | Detection |
+|---------|-----------|
+| **Bounce loop** | Same task delegated back to the same agent 3+ times |
+| **Circular delegation** | Span tree contains a cycle (A → B → A) |
+| **Step retry loop** | Same plan step attempted 3+ times without progress |
+| **Stage stall** | No span completion for a configured time threshold |
+
+When a pattern is detected, a signal is written to `.codebase/DEADLOCK_SIGNALS.jsonl`:
+
+```json
+{
+  "signal_id": "dl-001",
+  "type": "bounce_loop",
+  "agent": "coder",
+  "task": "Implement user authentication",
+  "bounce_count": 3,
+  "last_span": "s1a2b3c",
+  "detected_at": "2026-05-26T10:15:00Z",
+  "auto_stop": false
+}
+```
+
+If `auto_stop` is `true` in the config, the orchestrator halts execution. Otherwise, it logs the signal and continues, notifying the user.
+
+Configuration:
+
+```json
+{
+  "governance": {
+    "deadlockDetection": {
+      "enabled": true,
+      "bounceThreshold": 3,
+      "autoStop": false
+    }
+  }
+}
+```
+
+---
+
+## 6. Workflow Scorecard
+
+After each `/fd-verify` run, a 10-dimension quality scorecard is written to `.codebase/SCORECARDS.jsonl`.
+
+| Dimension | Description |
+|-----------|-------------|
+| `tdd_discipline` | Tests written before implementation |
+| `design_first` | Discuss and plan completed before execute |
+| `approval_gated` | Critical steps required explicit CONFIRM |
+| `budget_efficiency` | Tool calls and depth used vs. limits |
+| `conflict_resolved` | Merge conflicts resolved without force |
+| `rule_compliance` | Project rules and contracts respected |
+| `rollback_ready` | Every task had a rollback plan |
+| `context_preserved` | No context loss between phases |
+| `safety_gated` | Phase gating enforced throughout |
+| `governance_traced` | All agent calls have spans |
+
+Each dimension scores 0.0–1.0. The overall score is the weighted average. Scorecards enable post-hoc comparison of runs and identification of process regressions.
+
+---
+
+## Complete Configuration Example
+
+Here is a fully annotated `flowdeck.json` section covering all governance options:
+
+```json
+{
+  "governance": {
+    // Agent Validator — checks agent calls against contracts
+    "validator": {
+      "mode": "advisory"          // "off" | "advisory" | "strict"
+    },
+
+    // Delegation Budget — per-run limits
+    "delegationBudget": {
+      "maxToolCalls": 200,        // total tool calls allowed
+      "maxDepth": 8,              // max delegation chain depth
+      "maxSameStepRetries": 3,    // retries of the same plan step
+      "maxSubAgentDelegations": 40 // sub-agent calls per orchestrator call
+    },
+
+    // Deadlock / Loop Detector
+    "deadlockDetection": {
+      "enabled": true,
+      "bounceThreshold": 3,       // bounces before signal fires
+      "circularThreshold": 2,      // circular spans before signal fires
+      "autoStop": false           // halt execution on first signal
+    },
+
+    // Workflow Scorecard
+    "scorecard": {
+      "enabled": true
+    }
+  }
+}
+```
+
+The governance layer adds measurable overhead only when set to `advisory` or `strict` mode. In `off` mode, no contract checks are performed and no spans are written (though deadlock detection still runs if enabled).