@dv.nghiem/flowdeck 0.3.8 → 0.4.0

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).

package/docs/concepts/intelligence.md

@@ -0,0 +1,145 @@
+# Intelligence
+
+FlowDeck's intelligence layer evaluates every change before it is applied. It scores edit safety, tracks file change history, reproduces prior failures, predicts regressions, and enforces workflow discipline through phase gating. All intelligence services run as hooks on every tool execution — no additional commands needed.
+
+---
+
+## Patch Trust Score
+
+Before any `edit` tool call is applied, the **patch trust scorer** evaluates the edit and assigns a trust score from 0.0 (dangerous) to 1.0 (safe).
+
+The score is computed from:
+
+| Factor | Weight | What it measures |
+|--------|--------|-----------------|
+| File volatility | 25% | Historical change frequency from `.codebase/VOLATILITY.json` |
+| Edit scope | 20% | Lines changed vs. file total — large rewrites score lower |
+| Context window pressure | 15% | Remaining context space — edits under pressure score lower |
+| Agent history | 20% | Historical failure rate of the calling agent on this file |
+| Rule compliance | 20% | Does the edit violate project rules from `.flowdeck/rules/` |
+
+**Threshold behavior:**
+
+- Score >= 0.8 — edit applied automatically
+- Score 0.5–0.8 — user notified; edit applied with confirmation prompt
+- Score < 0.5 — edit blocked; user must resolve concerns or override explicitly
+
+The `@policy-enforcer` agent is invoked automatically when the score is below threshold. The score is logged in the tool span metadata.
+
+---
+
+## Volatility Map
+
+The **volatility map** tracks change frequency per file over the session and across sessions. It is maintained by the `volatility-map` tool and stored in `.codebase/VOLATILITY.json`.
+
+```json
+{
+  "src/auth/login.ts": {
+    "changeCount": 7,
+    "lastChanged": "2026-05-26T09:30:00Z",
+    "avgRevisionsPerSession": 3.2,
+    "risk": "high"
+  },
+  "src/config/default.ts": {
+    "changeCount": 1,
+    "lastChanged": "2026-05-25T14:00:00Z",
+    "avgRevisionsPerSession": 0.4,
+    "risk": "low"
+  }
+}
+```
+
+Files with high volatility:
+
+- Receive lower Patch Trust Scores automatically
+- Trigger `@risk-analyst` review before large refactors
+- Are flagged in the Workflow Scorecard under `context_preserved` if they change frequently within a single session
+
+The volatility map is rebuilt on first session start and incrementally updated on each `edit` tool call.
+
+---
+
+## Failure Replay
+
+When a task fails (test failure, build error, runtime crash), the **failure replay** service can reproduce the failure in isolation to generate a clean diagnostic trace.
+
+Invoked by the `@debugger` agent via the `failure-replay` tool:
+
+1. The tool reads the original error context from the failed span in `AGENT_SPANS.jsonl`
+2. It re-runs the minimal subset of the task that caused the failure
+3. The trace is written to `.codebase/FAILURE_REPLAY.jsonl`:
+
+```json
+{
+  "replay_id": "fr-001",
+  "original_span": "s1a2b3c",
+  "task": "Run user authentication tests",
+  "reproduced": true,
+  "root_cause": "Missing mock for auth service in test environment",
+  "trace": [
+    "Step 1: npm test src/auth/login.test.ts",
+    "Error: Cannot read property 'validate' of undefined",
+    "Step 2: Mock auth service — result: test passes"
+  ],
+  "fix_suggestion": "Add mock for auth service in login.test.ts line 42"
+}
+```
+
+Replays are deterministic — the same failure will reproduce the same trace. This prevents "heisenbugs" that only appear in full runs.
+
+---
+
+## Regression Prediction
+
+Before a plan is executed, the **regression predictor** evaluates the planned changes against the volatility map and historical failure data to predict which tasks are likely to break tests.
+
+The predictor runs as a pre-execution check in `/fd-execute`:
+
+1. For each task in the plan, look up every file the task will modify in `VOLATILITY.json`
+2. Cross-reference with historical failure data in `SCORECARDS.jsonl` — if similar changes broke tests before, flag the task
+3. Assign a regression probability score (0.0–1.0) per task and per wave
+
+**Output appended to PLAN.md:**
+
+```markdown
+## Regression Predictions
+
+| Task | Files | Regression Probability | Flag |
+|------|-------|----------------------|------|
+| 1a: Write user model | src/models/user.ts | 0.15 | low |
+| 1b: Refactor auth service | src/auth/login.ts | 0.72 | high — historically fragile |
+| 2a: Integration tests | src/auth/*.test.ts | 0.31 | medium |
+```
+
+Tasks flagged `high` are presented to the user before `CONFIRM` in `/fd-plan`. The user may choose to skip, refactor, or add additional test coverage before proceeding.
+
+---
+
+## Phase Gating
+
+Phase gating enforces workflow discipline by blocking entry into a phase unless the prerequisites from the previous phase are satisfied.
+
+| Transition | Gate |
+|------------|------|
+| `/fd-new-feature` → `/fd-discuss` | `DISCUSS.md` must exist and have at least 3 Q&A entries |
+| `/fd-discuss` → `/fd-plan` | `DISCUSS.md` must have a risk summary section |
+| `/fd-plan` → `/fd-execute` | User must type `CONFIRM`; no blockers in regression predictions |
+| `/fd-execute` → `/fd-verify` | All plan tasks must be marked `done` or `skipped` |
+
+If a gate check fails, the command exits with a descriptive error listing the missing prerequisites. The user resolves them before retrying.
+
+Phase gating is implemented by the `guard-rails` hook running in `tool.execute.before` — it intercepts command invocations and validates prerequisites before the command logic runs.
+
+---
+
+## Intelligence Tool Summary
+
+| Tool / Hook | Service | Purpose |
+|-------------|---------|---------|
+| `patch-trust` hook | Patch Trust Score | Score edits before application |
+| `volatility-map` tool + hook | Volatility Map | Track per-file change frequency |
+| `failure-replay` tool | Failure Replay | Reproduce and trace prior failures |
+| Regression predictor (in `/fd-plan`) | Regression Prediction | Score planned changes for breakage risk |
+| `guard-rails` hook | Phase Gating | Enforce workflow discipline at phase boundaries |
+| `policy-engine` tool | Rule Compliance | Evaluate edits against project rules |
+| `hash-edit` tool | Edit Hashing | Content-address edits for deduplication |