@dv.nghiem/flowdeck 0.3.3 → 0.3.5

package/docs/configuration.md

@@ -147,9 +147,9 @@ Each FlowDeck project stores its settings in `.planning/config.json`. This file
 
 ---
 
-## flowdeck.json (Agent Model Overrides)
+## flowdeck.json (Agent and Governance Config)
 
-The `flowdeck.json` file lets you assign specific AI models to individual FlowDeck agents. This is useful when you want the `@planner` to use a more capable model while lighter agents like `@tester` use a faster, cheaper one.
+The `flowdeck.json` file controls two things: per-agent model overrides and the governance layer. **No model is hardcoded** — if an agent is not listed, it uses whatever model is currently selected in OpenCode.
 
 ### Locations
 
@@ -160,7 +160,7 @@ The `flowdeck.json` file lets you assign specific AI models to individual FlowDe
 
 Project config takes precedence over global config.
 
-### Schema
+### Full schema
 
 ```json
 {
@@ -168,61 +168,91 @@ Project config takes precedence over global config.
     "<agent-name>": {
       "model": "<provider>/<model-id>"
     }
+  },
+  "designFirst": {
+    "enabled": true,
+    "enforcement": "strict",
+    "requireApprovalBeforeImplementation": true,
+    "modelOverrides": {
+      "design": "anthropic/claude-sonnet-4"
+    },
+    "defaultSkillsByTaskType": {
+      "landing-page": ["landing-page-design", "wireframe-planning", "design-system-definition", "frontend-handoff"]
+    }
+  },
+  "governance": {
+    "validator": {
+      "mode": "advisory"
+    },
+    "delegationBudget": {
+      "maxToolCalls": 200,
+      "maxDelegatedAgents": 30,
+      "maxRetries": 10,
+      "maxDepth": 8,
+      "maxSameStepRetries": 3
+    },
+    "deadlockDetection": {
+      "enabled": true,
+      "bounceThreshold": 3,
+      "stageStallMinutes": 30,
+      "autoStop": false
+    },
+    "scorecard": {
+      "enabled": true
+    }
   }
 }
 ```
 
-### Supported Agents
-
-| Agent | Default Model | Override Example |
-|-------|--------------|-----------------|
-| `@architect` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@build-error-resolver` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@code-explorer` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-| `@coder` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@debug-specialist` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@discusser` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@doc-updater` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@orchestrator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@plan-checker` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@planner` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@mapper` | `gemini-2.5-flash` | `google/gemini-2.5-flash` |
-| `@multi-repo-coordinator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@orchestrator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@parallel-coordinator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@performance-optimizer` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@planner` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@refactor-guide` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@researcher` | `gpt-4o` | `openai/gpt-4o` |
-| `@reviewer` | `gemini-2.5-flash` | `google/gemini-2.5-flash` |
-| `@security-auditor` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@task-splitter` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@tester` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-| `@writer` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-
-### Example
+### Agent model overrides
+
+All agents default to the model currently selected in OpenCode. Only list agents you want to override:
 
 ```json
 {
   "agents": {
-    "planner": {
-      "model": "anthropic/claude-opus-4-5"
-    },
-    "orchestrator": {
-      "model": "anthropic/claude-sonnet-4-5"
-    },
-    "tester": {
-      "model": "anthropic/claude-haiku-4-5"
-    }
+    "planner":      { "model": "anthropic/claude-opus-4" },
+    "orchestrator": { "model": "anthropic/claude-sonnet-4" },
+    "tester":       { "model": "openai/gpt-4o-mini" },
+    "reviewer":     { "model": "google/gemini-2.5-flash" }
   }
 }
 ```
 
-### Notes
-
-- If an agent is not listed in `agents`, it uses the model currently selected in OpenCode.
-- Only list agents you want to override — omitted agents inherit the session default.
-- Model strings must match the format `provider/model-id` (e.g., `anthropic/claude-sonnet-4-5`).
+Model strings must use the format `provider/model-id`. Common examples:
+
+| Provider | Example model string |
+|----------|---------------------|
+| Anthropic | `anthropic/claude-opus-4`, `anthropic/claude-sonnet-4`, `anthropic/claude-haiku-4` |
+| OpenAI | `openai/gpt-4o`, `openai/gpt-4o-mini` |
+| Google | `google/gemini-2.5-flash`, `google/gemini-2.5-pro` |
+| GitHub Copilot | `github-copilot/sonnet-4.6` |
+| Minimax | `minimax/minimax-m2.7-highspeed` |
+
+Agents with no entry in `agents` inherit the session model selected in OpenCode's model picker.
+
+### Governance config
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `governance.validator.mode` | `"advisory"` | `"off"` — disabled; `"advisory"` — warn but never block; `"strict"` — block on contract violations |
+| `governance.delegationBudget.maxToolCalls` | `200` | Total tool calls allowed per workflow run before escalation |
+| `governance.delegationBudget.maxDelegatedAgents` | `30` | Maximum number of sub-agent delegations per run |
+| `governance.delegationBudget.maxRetries` | `10` | Total retries allowed across all steps |
+| `governance.delegationBudget.maxDepth` | `8` | Maximum delegation nesting depth |
+| `governance.delegationBudget.maxSameStepRetries` | `3` | Retries allowed on a single failing step before escalation |
+| `governance.deadlockDetection.enabled` | `true` | Enable deadlock and loop detection |
+| `governance.deadlockDetection.bounceThreshold` | `3` | Agent-pair invocations before bounce is flagged |
+| `governance.deadlockDetection.stageStallMinutes` | `30` | Minutes without stage progress before stall is flagged |
+| `governance.deadlockDetection.autoStop` | `false` | Stop automatically on detection; `false` emits warning only |
+| `governance.scorecard.enabled` | `true` | Generate a quality scorecard after every run |
+
+### Design-first defaults
+
+- `designFirst.enabled`: defaults to `true`
+- `designFirst.enforcement`: defaults to `strict` (`advisory` supported)
+- `designFirst.requireApprovalBeforeImplementation`: defaults to `true`
+- UI-heavy tasks are blocked from implementation until design handoff is approved, unless explicit override is recorded.
 
 ---
 

package/docs/design-first-workflow.md

@@ -0,0 +1,94 @@
+# Design-First Workflow
+
+FlowDeck enforces a design-first path for UI-heavy tasks by default.
+
+## Trigger Conditions
+
+Design-first is triggered when tasks mention user-facing work such as:
+- landing page
+- dashboard
+- admin panel
+- website redesign
+- onboarding UX
+- app screen/mobile UI
+
+Backend-only or infra-only tasks skip design-first.
+
+## Workflow
+
+```text
+task intake
+→ task classification
+→ design discovery
+→ UX structure
+→ wireframe/layout planning
+→ visual system definition
+→ design review/approval
+→ implementation handoff
+→ frontend implementation
+→ QA/review
+```
+
+## Commands
+
+- `/fd-design --mode=draft`: produce design artifact and handoff
+- `/fd-design --mode=review`: compare implementation to approved design artifact
+- `/fd-design --mode=system`: create/update token and component consistency guidance
+
+## Design Artifact Schema
+
+Each design run should persist:
+- `task_type`
+- `user_goals`
+- `target_audience`
+- `core_user_flows`
+- `page_map_or_screen_map`
+- `section_structure`
+- `layout_plan`
+- `component_list`
+- `state_list`
+- `responsive_behavior_notes`
+- `visual_direction`
+- `design_tokens_guidance`
+- `accessibility_notes`
+- `implementation_handoff_checklist`
+- `approval_status`
+
+## Example: Landing Page
+
+```yaml
+task_type: landing-page
+user_goals:
+  - understand value in <10 seconds
+  - complete signup CTA
+core_user_flows:
+  - hero -> social-proof -> pricing -> CTA
+layout_plan:
+  - hero_section: headline, subheadline, primary_cta, secondary_cta
+  - proof_section: logos, testimonials
+  - pricing_section: tier_cards, comparison_table
+state_list: [loading, empty, error, success]
+approval_status: approved
+```
+
+## Example: App Screen Redesign
+
+```yaml
+task_type: app-screen
+target_audience:
+  - returning mobile users
+core_user_flows:
+  - home -> quick-action -> detail -> completion
+section_structure:
+  - top_nav
+  - summary_cards
+  - task_list
+  - persistent_action_bar
+responsive_behavior_notes:
+  - compact_nav_on_small_screens
+  - collapse_secondary_panels_under_768
+design_tokens_guidance:
+  - spacing_scale: [4, 8, 12, 16, 24, 32]
+  - text_scale: [12, 14, 16, 20, 24]
+approval_status: approved
+```

package/docs/feature-integration-architecture.md

@@ -11,7 +11,7 @@ This layer adds 8 capabilities behind the existing command architecture without
 | Capability | Implementation | Data File |
 |---|---|---|
 | Patch Trust Engine | `src/hooks/patch-trust.ts` | `.codebase/DECISIONS.jsonl` |
-| Adaptive Model Router | `src/services/model-router.ts` | `.codebase/MODEL_ROUTER.json` |
+| Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
 | Approval-Aware Execution | `src/services/approval-manager.ts` + `src/hooks/approval-hook.ts` | `.codebase/APPROVALS.json` |
 | Workflow Replay + Diff | `src/services/run-trace.ts` | `.codebase/RUNS.jsonl` |
 | Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
@@ -63,27 +63,6 @@ isSensitivePath(filePath) → boolean
 
 **Approval TTL:** 30 minutes. Sensitive path patterns: auth, payment, secrets, migrations, infra, production config.
 
-### model-router.ts
-Routes task types to the best available model.
-
-```typescript
-routeModel(dir, task_type, risk_score?) → RoutedModel
-buildAgentConfig(dir, agents) → AgentConfig[]
-getRouterConfig(dir) → ModelRouterConfig
-```
-
-**Default routing:**
-| Task | Primary | High-Risk Override |
-|---|---|---|
-| planning | claude-sonnet-4-5 | — |
-| implementation | claude-opus-4-5 | claude-opus-4-5 |
-| debugging | claude-sonnet-4-5 | claude-opus-4-5 |
-| review | gemini-2.5-flash | — |
-| testing | claude-haiku-4-5 | — |
-| security | claude-opus-4-5 | claude-opus-4-5 |
-
-Override by creating `.codebase/MODEL_ROUTER.json` with `{ "task_type": { "primary": "model-name" } }`.
-
 ### agent-performance.ts
 Tracks success rates, costs, and durations per agent+model+task combination.
 
@@ -94,7 +73,7 @@ getBestAgentForTask(dir, task_type) → AgentRecommendation | null
 getAgentLeaderboard(dir) → AgentRecommendation[]
 ```
 
-Requires ≥ 3 runs per combination before making routing recommendations.
+Requires ≥ 3 runs per combination before making routing recommendations. Model is tracked from the actual call — no hardcoded model list.
 
 ---
 
@@ -122,7 +101,6 @@ Emits `tool.call` events for all tool invocations. Lightweight — never blocks.
 
 ### /fd-new-feature
 - Calls `startTrace()` on entry → `run_id` included in config
-- Calls `buildAgentConfig()` from model-router → no hardcoded models
 - Emits `command.start` telemetry event with risk score and phase
 
 ### /fd-fix-bug
@@ -175,12 +153,7 @@ The dashboard at `http://localhost:<port>` now includes:
 
 ### AGENT_PERF.json
 ```json
-{"entries":[{"agent":"coder","model":"claude-opus-4-5","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
-```
-
-### MODEL_ROUTER.json (optional override)
-```json
-{"implementation":{"primary":"claude-sonnet-4-5","temperature":0.2},"review":{"primary":"claude-haiku-4-5"}}
+{"entries":[{"agent":"backend-coder","model":"<user-configured>","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
 ```
 
 ---
@@ -189,7 +162,6 @@ The dashboard at `http://localhost:<port>` now includes:
 
 No new required config. Optional per-repo overrides:
 
-- `.codebase/MODEL_ROUTER.json` — override model routing per task type
 - `.codebase/POLICIES.json` — runtime policy rules (existing, enhanced)
 - `.codebase/CONSTRAINTS.md` — architectural constraints (existing)
 

package/docs/index.md

@@ -1,6 +1,6 @@
 # FlowDeck Documentation
 
-FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
+FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a gated workflow — discuss, plan, design (UI-heavy), execute, review — with persistent state stored in your project's `.planning/` directory.
 
 ---
 
@@ -18,12 +18,14 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Agents](agents.md) | All specialist agents — names, roles, models, and when to invoke each one |
+| [Agents](agents.md) | All specialist agents — names, roles, and when to invoke each one |
 | [Skills](skills.md) | Reusable skill patterns for common tasks |
 | [Commands](commands.md) | All 18 slash commands — syntax, arguments, and what each command triggers |
 | [Workflows](workflows.md) | Built-in workflows for common scenarios |
+| [Design-First Workflow](design-first-workflow.md) | UI-heavy workflow gates from design discovery to implementation handoff |
 | [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
 | [Intelligence Features](intelligence.md) | AI-safety features for pre-change analysis and risk assessment |
+| [Governance Layer](configuration.md#governance-config) | Agent contracts, validator, trace graph, budget, deadlock detection, and scorecards |
 | [Memory System](memory.md) | Persistent memory — recall past sessions, tool executions, and context across sessions |
 
 ---
@@ -53,6 +55,7 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 | `/fd-new-project <name>` | Initialize project with planning structure and default config |
 | `/fd-discuss <topic>` | Run structured requirements Q&A to capture decisions |
 | `/fd-plan [--phase=N]` | Generate implementation plan from decisions (requires CONFIRM) |
+| `/fd-design [--mode=draft\|review\|system]` | Run design-first planning and UI fidelity review for UI-heavy tasks |
 | `/fd-new-feature "<description>"` | Execute full feature workflow with TDD discipline |
 | `/fd-fix-bug "<description>"` | Diagnose and fix a bug with regression test |
 | `/fd-deploy-check [--check=deploy,review,analysis]` | Pre-deploy checks, code review, or pre-change analysis |

package/docs/installation.md

@@ -20,7 +20,7 @@ If OpenCode is not yet installed, follow the [OpenCode installation guide](https
 
 ## Method 1: curl (recommended)
 
-The install script downloads the latest release, copies all agents, skills, commands, and workflows to `~/.config/opencode/`, and registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json`.
+The install script registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json` and sets `orchestrator` as default agent when missing.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh | bash
@@ -29,11 +29,9 @@ curl -fsSL https://raw.githubusercontent.com/DVNghiem/flowdeck/main/install.sh |
 What the script does:
 
 1. Detects your config directory (`$OPENCODE_CONFIG_DIR` or `~/.config/opencode`)
-2. Copies `agents/*.md` → `~/.config/opencode/agent/` (markdown agents for OpenCode compatibility)
-3. Compiles TypeScript agents from `src/agents/` → `dist/agents/` (for plugin-based loading)
-4. Copies `skills/*/` → `~/.config/opencode/skills/`
-5. Registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json`
-6. Sets `orchestrator` as the default agent
+2. Creates the config directory if needed
+3. Registers `@dv.nghiem/flowdeck` as a plugin in `opencode.json` if not present
+4. Sets `orchestrator` as the default agent if not already configured
 
 ---
 
@@ -59,18 +57,9 @@ Steps explained:
 
 ## Verification
 
-After any install method, run these commands to confirm everything landed correctly:
+After any install method, run these commands to confirm registration:
 
 ```bash
-# Should print 23 or more
-ls ~/.config/opencode/agent/ | grep -c "\.md"
-
-# Should list 24 or more directories
-ls ~/.config/opencode/skills/
-
-# Should list 16 or more files
-ls ~/.config/opencode/command/
-
 # Should print @dv.nghiem/flowdeck
 cat ~/.config/opencode/opencode.json | grep flowdeck
 ```
@@ -81,7 +70,7 @@ Expected output for the last command:
 "@dv.nghiem/flowdeck"
 ```
 
-If any count is lower than expected, re-run the install command. If the `opencode.json` line is missing, the plugin will not load — add it manually (see [Configuration](configuration.md)).
+If the `opencode.json` line is missing, the plugin will not load — add it manually (see [Configuration](configuration.md)).
 
 ---
 

package/docs/intelligence.md

@@ -8,19 +8,19 @@ FlowDeck's intelligence layer adds safety-first AI editing, persistent architect
 
 | Feature | Command / Hook | Storage |
 |---------|---------------|---------|
-| Change Impact Radar | `/fd-impact-radar` | VOLATILITY.json, MEMORY.json |
+| Change Impact Radar | Integrated analysis workflow | VOLATILITY.json, MEMORY.json |
 | Patch Trust Score | Hook (automatic) | VOLATILITY.json, FAILURES.json |
-| Blast Radius Preview | `/fd-blast-radius` | MEMORY.json, FAILURES.json |
+| Blast Radius Preview | Integrated analysis workflow | MEMORY.json, FAILURES.json |
 | Repo Memory Graph | `repo-memory` tool | `.codebase/MEMORY.json` |
 | Failure Replay Engine | `failure-replay` tool | `.codebase/FAILURES.json` |
 | Safe Execution Modes | Hook (automatic) | `.planning/config.json` |
-| Test Gap Detector | `/fd-test-gap` | VOLATILITY.json |
+| Test Gap Detector | Integrated analysis workflow | VOLATILITY.json |
 | Architectural Constraint Guard | Hook (automatic) | `.codebase/CONSTRAINTS.md` |
 | Intent-to-Change Translator | `/fd-translate-intent` | — |
 | Confidence-Aware Planning | Skill | — |
-| Codebase Volatility Map | `/fd-volatility-map`, `volatility-map` tool | `.codebase/VOLATILITY.json` |
-| Human Review Routing | `/fd-review-route` | VOLATILITY.json, FAILURES.json |
-| Regression Prediction | `/fd-regression-predict` | — |
+| Codebase Volatility Map | `volatility-map` tool | `.codebase/VOLATILITY.json` |
+| Human Review Routing | Integrated analysis workflow | VOLATILITY.json, FAILURES.json |
+| Regression Prediction | Integrated analysis workflow | — |
 | Decision Trace | `decision-trace` tool + hook | `.codebase/DECISIONS.jsonl` |
 | Self-Healing Policies | `policy-engine` tool | `.codebase/POLICIES.json` |
 
@@ -28,14 +28,11 @@ FlowDeck's intelligence layer adds safety-first AI editing, persistent architect
 
 ## Slash Commands
 
-### `/fd-impact-radar`
+### Change Impact Radar
 
 Predicts which files, modules, APIs, tests, and database paths are likely to be affected before the AI edits anything.
 
-```
-/fd-impact-radar --change "refactor auth token handling" --scope all
-/fd-impact-radar --change "drop users table" --json
-```
+Use `/fd-suggest` or `/fd-translate-intent` when you need pre-change analysis with impact context.
 
 **Arguments:**
 - `--change` — describe the proposed change (free text)
@@ -46,13 +43,11 @@ Predicts which files, modules, APIs, tests, and database paths are likely to be
 
 ---
 
-### `/fd-blast-radius`
+### Blast Radius Preview
 
 Shows the likely downstream consequences of a proposed change — hidden dependencies, fragile integration points, and predicted test breakages.
 
-```
-/fd-blast-radius --change "delete legacy session table" --depth 3
-```
+Use `/fd-suggest` for broad risk discovery and `/fd-deploy-check` before release changes.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -78,14 +73,11 @@ Converts a vague request like "make checkout faster" into concrete, ranked imple
 
 ---
 
-### `/fd-volatility-map`
+### Volatility Map
 
 Displays the Codebase Volatility Map — highlights unstable zones based on churn, hotfix frequency, and unresolved TODO clusters.
 
-```
-/fd-volatility-map
-/fd-volatility-map --threshold volatile --limit 10
-```
+Use the `volatility-map` tool directly from delegated agents for incremental updates.
 
 **Arguments:**
 - `--threshold` — minimum stability level to show: `stable`, `moderate`, `volatile` (default), `critical`
@@ -96,13 +88,11 @@ Displays the Codebase Volatility Map — highlights unstable zones based on chur
 
 ---
 
-### `/fd-regression-predict`
+### Regression Prediction
 
 Estimates the most likely regression categories for a change — performance, auth, schema, UI states, async flows, etc.
 
-```
-/fd-regression-predict --change "add webhook retry logic" --categories all
-```
+FlowDeck derives regression risk from historical failures plus volatility data during analysis-oriented workflows.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -111,14 +101,11 @@ Estimates the most likely regression categories for a change — performance, au
 
 ---
 
-### `/fd-test-gap`
+### Test Gap Detector
 
 Identifies which areas of a proposed change are weakly covered by tests, and suggests the minimum high-value tests to add first.
 
-```
-/fd-test-gap --change "add payment webhook handler"
-/fd-test-gap --change "update user schema" --scope unit
-```
+Use `/fd-verify` and `/fd-deploy-check` for current test-gap surfacing in production workflows.
 
 **Arguments:**
 - `--change` — describe the proposed change
@@ -127,13 +114,11 @@ Identifies which areas of a proposed change are weakly covered by tests, and sug
 
 ---
 
-### `/fd-review-route`
+### Human Review Routing
 
 Routes risky patches to the right reviewer type — security, backend, infra, domain-owner, frontend, data, or devops — based on the file paths and change description.
 
-```
-/fd-review-route --files "src/auth/token.ts,src/api/routes.ts" --change "new JWT rotation logic"
-```
+Routing to reviewer profiles is integrated into verification and deployment checks.
 
 **Arguments:**
 - `--files` — comma-separated file paths being changed
@@ -267,12 +252,103 @@ Manages `.codebase/POLICIES.json` — self-healing editing rules that update aft
 | `VOLATILITY.json` | JSON | Per-file churn and stability metrics |
 | `POLICIES.json` | JSON | Self-healing editing rule set |
 | `CONSTRAINTS.md` | Markdown | Forbidden path list for Arch Constraint Guard |
+| `AGENT_SPANS.jsonl` | Newline-delimited JSON | Inter-agent trace graph (governance) |
+| `BUDGETS.json` | JSON | Per-run delegation budget state (governance) |
+| `DEADLOCK_SIGNALS.jsonl` | Newline-delimited JSON | Detected loops and deadlocks (governance) |
+| `SCORECARDS.jsonl` | Newline-delimited JSON | 10-dimension workflow quality scores (governance) |
 
 > **Tip:** All `.codebase/` files should be committed to version control so the intelligence layer improves over time.
 
 ---
 
-## Skills
+## Governance Layer
+
+The governance layer makes multi-agent execution trustworthy and debuggable. It runs automatically as internal runtime services — no commands or manual wiring needed.
+
+### Agent Contracts
+
+Every major agent has an explicit contract defining:
+
+- **Allowed tools** — tools the agent may invoke
+- **Forbidden actions** — things the agent must never do (e.g. `@reviewer` may not write files)
+- **Required inputs** — what context must be present before the agent runs
+- **Escalation conditions** — when to surface to human review
+- **Success criteria** — what a good output looks like
+
+Contracts are defined in `src/services/agent-contract-registry.ts` and cover: orchestrator, planner, plan-checker, design, backend-coder, frontend-coder, devops, tester, reviewer, security-auditor, researcher, architect, writer, and doc-updater.
+
+### Agent Validator
+
+Before and after each agent invocation, the validator checks the execution context against the agent's contract. Configure the enforcement mode in `flowdeck.json`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `off` | Validation disabled |
+| `advisory` | Validate and warn; never block execution (default) |
+| `strict` | Block on contract violations of severity `block` |
+
+Violations are emitted as `contract.violation` telemetry events and attached to the agent span.
+
+### Inter-Agent Trace Graph
+
+Every delegation opens a **span** in the trace graph. Spans record:
+
+- Invoker → agent direction
+- Trace ID and parent span ID (causal chain)
+- Tools used and outputs
+- Contract violations attached to the span
+- Latency and delegation depth
+
+Spans are stored in `.codebase/AGENT_SPANS.jsonl`. The trace graph is dashboard-ready and can be rendered as a timeline, causality graph, or per-agent drilldown.
+
+### Delegation Budget
+
+Each workflow run has a budget tracked in `.codebase/BUDGETS.json`:
+
+| Limit | Default | Config key |
+|-------|---------|------------|
+| Max tool calls | 200 | `governance.delegationBudget.maxToolCalls` |
+| Max delegated agents | 30 | `governance.delegationBudget.maxDelegatedAgents` |
+| Max retries (total) | 10 | `governance.delegationBudget.maxRetries` |
+| Max delegation depth | 8 | `governance.delegationBudget.maxDepth` |
+| Max retries per step | 3 | `governance.delegationBudget.maxSameStepRetries` |
+
+When a limit is exceeded the system escalates to human review or (if `autoStop: true`) stops safely and summarises what was completed.
+
+### Deadlock and Loop Detector
+
+The detector runs four independent pattern checks after each agent invocation:
+
+| Pattern | Trigger |
+|---------|---------|
+| `agent_bounce` | Same agent pair invoked ≥ N times without resolution |
+| `step_retry_loop` | Same stage retried beyond the per-step limit |
+| `circular_delegation` | DFS detects a cycle in the delegation graph — always triggers `auto_stop` |
+| `stage_stall` | Workflow stage makes no progress within the stall window |
+
+Signals are written to `.codebase/DEADLOCK_SIGNALS.jsonl`. Duplicate signals for the same trace and pattern are suppressed. A recovery action recommendation is attached to each signal.
+
+### Workflow Scorecard
+
+After every completed or failed run, a scorecard is generated and appended to `.codebase/SCORECARDS.jsonl`. Ten dimensions are scored and combined into a weighted 0–100 score:
+
+| Dimension | Weight |
+|-----------|--------|
+| Stage compliance | 15% |
+| TDD compliance | 15% |
+| Design-first compliance | 10% |
+| Approval compliance | 10% |
+| Review quality | 10% |
+| Handoff quality | 10% |
+| Budget efficiency | 10% |
+| Tool reliability | 10% |
+| Policy compliance | 5% |
+| Override frequency | 5% |
+
+Scorecards support trend analysis over time. Use `getScorecardTrend(dir, command)` and `computeAverageScore(dir)` from `src/services/workflow-scorecard.ts` to query them programmatically.
+
+---
+
 
 Each intelligence feature also has a corresponding skill that gives the OpenCode agent detailed workflow instructions. Skills are installed automatically by `install.sh`.
 

package/docs/multi-repo.md

@@ -180,7 +180,7 @@ The `multi-repo-flow` workflow orchestrates the full end-to-end process:
 1. **Analyze** — `@code-explorer` runs in each registered repo and builds a combined dependency graph
 2. **Classify** — `@multi-repo-coordinator` identifies which changes are breaking vs non-breaking and determines service change order
 3. **Plan** — produces a CHANGE PLAN per repo in dependency order
-4. **Execute** — `@coder` is invoked per repo in order; `@tester` runs per repo in parallel with `@coder` (using that repo's test suite)
+4. **Execute** — role-routed implementation agent (`@backend-coder`/`@frontend-coder`/`@devops`) is invoked per repo in order; `@tester` runs per repo in parallel with the selected implementation agent (using that repo's test suite)
 5. **Verify** — `@reviewer` and `@security-auditor` run per repo after implementation; integration tests are run across the full service mesh in staging before any production rollout
 
 Each step produces output files in `.planning/fd-multi-repo/` so the entire process is auditable.

package/docs/optimization-baseline.md

@@ -0,0 +1,21 @@
+# FlowDeck Optimization Baseline
+
+Captured on 2026-05-07 before deep optimization implementation.
+
+## Dispatch Baseline
+
+- Command: `bun test src/tools/agent-dispatch.test.ts`
+- Result: 8 passing, 0 failing
+- Suite runtime (bun): 135ms
+- Wall clock runtime: 0.17s
+
+## Observability Baseline
+
+- `.codebase/` does not exist yet in a clean repo checkout.
+- Telemetry hooks emitted `status: "ok"` for all tool completions and did not classify failures.
+- Session/run IDs defaulted to `session-0` and `run-0` when runtime env variables were not set.
+
+## Routing and Cost Baseline
+
+- Dispatch tools did not call model routing or agent performance tracking.
+- `src/services/model-router.ts` and `src/services/agent-performance.ts` were present but not wired into `delegate`/`run-pipeline`.