Add Zoo/Roo MCP governance integration

.agents/skills/zoo-code-integration/SKILL.md

@@ -0,0 +1,102 @@
+# Zoo Code — Specsmith Governance Integration
+
+Use this skill when working in Zoo Code or Roo Code on a Specsmith-governed repository.
+
+## Goal
+
+Make Zoo/Roo behave like a governed local engineering agent, not an unconstrained chat assistant.
+
+The required pattern is:
+
+```text
+Architect plans
+Coder edits
+Debug/Tool runs and parses commands
+Reviewer critiques
+Specsmith preflight/verify/trace gates the work
+```
+
+The model that writes a patch must not be the only model that approves it.
+
+## Required local project files
+
+Project-local Zoo/Roo integration lives in `.roo/`:
+
+- `.roo/mcp.json` — repo-local MCP server registration for `specsmith-governance`
+- `.roo/specsmith-rules.md` — mandatory agent protocol for Zoo/Roo
+- `.roo/modes.local.json` — project-local reference mode definitions
+- `.roo/global-settings.copy-to-zoo-code.json` — copyable global Zoo Code/OpenAI-compatible provider settings
+
+Only `.roo/mcp.json` and `.roo/specsmith-rules.md` are intended to be active project files. Global provider/model settings must be copied into Zoo Code global settings by the operator.
+
+## Session start
+
+1. Read `AGENTS.md` and `.roo/specsmith-rules.md`.
+2. Call the MCP tool `governance_checkpoint`.
+3. Call `governance_phase` and `governance_req_list` before changing code.
+4. Summarize the current phase, failing checks, relevant requirements, and permitted scope.
+
+## Before any code change
+
+Call `governance_preflight` with one sentence describing the intended change.
+
+Do not edit files unless the decision is `accepted`.
+
+If the decision is `needs_clarification`, ask a narrow question or reduce the change scope.
+
+If the decision is `rejected`, stop and report why.
+
+## During implementation
+
+Follow role separation:
+
+- Architect mode may plan and inspect but should not directly edit production code.
+- Code mode may edit only within the accepted preflight scope.
+- Debug/Tool mode should run safe commands and parse outputs; it should not make large edits.
+- Review mode should read diffs, requirements, and tests; it should not rewrite the patch unless explicitly promoted.
+
+Prefer small diffs. Ground API, register, binding, and build-system claims in actual repository files or command output.
+
+## Verification
+
+After edits:
+
+1. Run the relevant tests/build checks.
+2. Capture command output.
+3. Run `specsmith verify` or use MCP governance tools when available.
+4. Call `governance_trace_seal` for meaningful milestones, accepted reviews, or release gates.
+
+## Embedded/firmware discipline
+
+Never invent SDK, HAL, register, device-tree, or build-system APIs.
+
+For Zephyr/devicetree-style work, ground claims in:
+
+- `bindings/*.yaml`
+- board DTS/DTSI files
+- generated devicetree output
+- exact build errors
+
+For C/firmware work, ground claims in:
+
+- headers
+- vendor SDK files
+- compiler output
+- tests or reproducible logs
+
+## Local model routing
+
+When using a LiteLLM/vLLM local pool, route by task:
+
+| Task | Model role |
+|---|---|
+| repo planning, architecture, ambiguous debugging | `architect` |
+| implementation, tests, refactors | `editor` |
+| shell commands, build logs, JSON/YAML, quick summaries | `tool-fast` |
+| adversarial review, regression risk, final critique | `reviewer` |
+
+Use the LiteLLM router endpoint when available:
+
+```text
+http://localhost:4000/v1
+```

.github/workflows/bench.yml

@@ -147,7 +147,7 @@ jobs:
     outputs:
       matrix: ${{ steps.gen.outputs.matrix }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - uses: actions/setup-python@v6
         with:

.roo/global-settings.copy-to-zoo-code.json

@@ -0,0 +1,33 @@
+{
+  "note": "Copy these provider/model ideas into Zoo Code global settings. This file is a project reference only; Zoo Code global settings are not automatically loaded from this repository.",
+  "provider": {
+    "name": "ChronoCortex Local Agent Pool",
+    "type": "openai-compatible",
+    "baseUrl": "http://localhost:4000/v1",
+    "apiKeyEnv": "LITELLM_MASTER_KEY"
+  },
+  "models": {
+    "architect": {
+      "id": "architect",
+      "useFor": ["architecture", "repo planning", "ambiguous debugging", "risk review"]
+    },
+    "editor": {
+      "id": "editor",
+      "useFor": ["implementation", "tests", "refactors", "code edits"]
+    },
+    "toolFast": {
+      "id": "tool-fast",
+      "useFor": ["shell planning", "build logs", "JSON/YAML", "quick summaries"]
+    },
+    "reviewer": {
+      "id": "reviewer",
+      "useFor": ["diff review", "regression risk", "adversarial critique"]
+    }
+  },
+  "recommendedModeMapping": {
+    "Specsmith Architect": "architect",
+    "Specsmith Code": "editor",
+    "Specsmith Debug / Tool": "tool-fast",
+    "Specsmith Review": "reviewer"
+  }
+}

.roo/mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "specsmith-governance": {
+      "command": "specsmith",
+      "args": ["mcp", "serve", "--project-dir", "."],
+      "env": {
+        "SPECSMITH_ALLOW_NON_PIPX": "1",
+        "SPECSMITH_NO_AUTO_UPDATE": "1",
+        "SPECSMITH_PYPI_CHECKED": "1"
+      }
+    }
+  }
+}

.roo/modes.local.json

@@ -0,0 +1,33 @@
+{
+  "note": "Project-local reference for Zoo Code / Roo Code modes. Use this as the canonical role mapping for this repository. Some clients require custom modes to be copied into global/user settings.",
+  "modes": [
+    {
+      "slug": "specsmith-architect",
+      "name": "Specsmith Architect",
+      "role": "architect",
+      "model": "architect",
+      "description": "Plan, inspect, and reason about requirements and architecture. Do not directly edit production code unless explicitly promoted."
+    },
+    {
+      "slug": "specsmith-code",
+      "name": "Specsmith Code",
+      "role": "code",
+      "model": "editor",
+      "description": "Implement accepted preflight tasks with small diffs and tests. Do not approve your own patch."
+    },
+    {
+      "slug": "specsmith-debug",
+      "name": "Specsmith Debug / Tool",
+      "role": "debug",
+      "model": "tool-fast",
+      "description": "Generate safe commands, parse build logs, inspect outputs, and summarize failures. Avoid large edits."
+    },
+    {
+      "slug": "specsmith-review",
+      "name": "Specsmith Review",
+      "role": "ask",
+      "model": "reviewer",
+      "description": "Review diffs against requirements, tests, and prior decisions. Prefer adversarial critique over rewriting."
+    }
+  ]
+}

.roo/specsmith-rules.md

@@ -0,0 +1,64 @@
+# Specsmith Rules for Zoo Code / Roo Code
+
+This repository uses Specsmith governance. Follow these rules for all agentic work in Zoo Code or Roo Code.
+
+## Mandatory protocol
+
+1. Read `AGENTS.md` and this file before changing code.
+2. Use the `specsmith-governance` MCP server from `.roo/mcp.json`.
+3. Call `governance_checkpoint` at session start and every 8-10 turns.
+4. Call `governance_preflight` before any code edit.
+5. Do not edit files unless preflight returns `accepted`.
+6. Run tests/build checks after edits.
+7. Run verification before reporting success.
+8. Seal meaningful decisions with `governance_trace_seal`.
+
+## Role separation
+
+Use separate modes/models for separate jobs:
+
+| Work | Preferred mode | Preferred local model role |
+|---|---|---|
+| requirements, architecture, plans | Architect | `architect` |
+| implementation and tests | Code | `editor` |
+| command generation and log parsing | Debug / Tool | `tool-fast` |
+| adversarial diff review | Review | `reviewer` |
+
+The model that writes a patch must not be the only model that approves it.
+
+## Scope control
+
+Keep changes inside the accepted preflight scope.
+
+Do not perform these actions unless the user explicitly asks and preflight accepts:
+
+- dependency upgrades
+- public API changes
+- file tree deletions
+- generated code rewrites over 200 lines
+- git push or release actions
+- secret, credential, or `.env` edits
+
+## Grounding rules
+
+Do not invent APIs, flags, registers, CLI options, package names, or configuration keys.
+
+Ground technical claims in one of:
+
+- repository files
+- generated outputs
+- test/build logs
+- official vendor/project docs already present in the workspace
+
+For firmware, Zephyr, RTL, FPGA, or low-level systems work, cite exact headers, bindings, source files, generated files, or build output before editing.
+
+## Completion report
+
+Every completed task should report:
+
+- accepted preflight work item id, when available
+- files changed
+- tests/builds run
+- reviewer findings
+- remaining risks
+- follow-up work, if any

docs/site/zoo-code-roo.md

@@ -0,0 +1,99 @@
+# Zoo Code / Roo Code Integration
+
+Specsmith integrates with Zoo Code / Roo Code through a repo-local `.roo/` directory and the Specsmith MCP governance server.
+
+## What belongs in the repository
+
+Project-local integration files:
+
+| File | Purpose |
+|---|---|
+| `.roo/mcp.json` | Registers the `specsmith-governance` MCP server for this repo. |
+| `.roo/specsmith-rules.md` | Mandatory rules for governed Zoo/Roo sessions. |
+| `.roo/modes.local.json` | Reference mode-to-model mapping for this project. |
+| `.roo/global-settings.copy-to-zoo-code.json` | Copyable global provider/model settings for Zoo Code. |
+
+Zoo Code global settings are not automatically loaded from a repository. Keep copyable global settings in the project as a reference, then copy them into Zoo Code global/user settings manually.
+
+## MCP setup
+
+The repo-local MCP config should look like this:
+
+```json
+{
+  "mcpServers": {
+    "specsmith-governance": {
+      "command": "specsmith",
+      "args": ["mcp", "serve", "--project-dir", "."],
+      "env": {
+        "SPECSMITH_ALLOW_NON_PIPX": "1",
+        "SPECSMITH_NO_AUTO_UPDATE": "1",
+        "SPECSMITH_PYPI_CHECKED": "1"
+      }
+    }
+  }
+}
+```
+
+The MCP server exposes governance tools such as:
+
+- `governance_checkpoint`
+- `governance_phase`
+- `governance_req_list`
+- `governance_preflight`
+- `governance_audit`
+- `governance_trace_seal`
+
+## Required agent flow
+
+Every Zoo/Roo session should follow this sequence:
+
+```text
+read AGENTS.md + .roo/specsmith-rules.md
+call governance_checkpoint
+call governance_phase
+call governance_req_list
+call governance_preflight before edits
+edit only within accepted scope
+run tests/build checks
+run verification
+seal meaningful decisions
+```
+
+Do not edit files unless `governance_preflight` returns `accepted`.
+
+## Local model routing
+
+When a local LiteLLM/vLLM pool is available, use the router endpoint:
+
+```text
+Base URL: http://localhost:4000/v1
+API key:  $LITELLM_MASTER_KEY
+```
+
+Recommended role mapping:
+
+| Zoo/Roo mode | Model |
+|---|---|
+| Specsmith Architect | `architect` |
+| Specsmith Code | `editor` |
+| Specsmith Debug / Tool | `tool-fast` |
+| Specsmith Review | `reviewer` |
+
+The model that writes a patch must not be the only model that approves it.
+
+## Operator setup checklist
+
+1. Start the local model router if using local models.
+2. Copy `.roo/global-settings.copy-to-zoo-code.json` into Zoo Code global settings, adapting field names to the current extension version.
+3. Ensure Zoo/Roo sees `.roo/mcp.json` for the active workspace.
+4. Start a session by asking the agent to read `.roo/specsmith-rules.md` and call `governance_checkpoint`.
+5. Run governed tasks using the role split: Architect -> Code -> Debug/Tool -> Review.
+
+## Safe defaults
+
+- Architect mode plans and reads; it should not directly edit production code.
+- Code mode implements accepted preflight tasks.
+- Debug/Tool mode runs safe commands and parses logs.
+- Review mode critiques diffs against requirements, tests, and prior decisions.
+- Specsmith blocks or escalates work when confidence, phase, or scope checks fail.

mkdocs.yml

@@ -52,6 +52,7 @@ nav:
       - Standalone CLI: standalone-cli.md
       - Agent Integrations: agent-integrations.md
       - Warp Integration: warp-integration.md
+      - Zoo Code / Roo Code: zoo-code-roo.md
       - BYOE Endpoints: endpoints.md
       - Kairos Terminal: kairos-terminal.md
     - Skills Index: skills-index.md