diff --git a/.agents/skills/zoo-code-integration/SKILL.md b/.agents/skills/zoo-code-integration/SKILL.md new file mode 100644 index 0000000..96122d6 --- /dev/null +++ b/.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 +``` diff --git a/.github/workflows/bench.yml b/.github/workflows/bench.yml index 87ccc62..58a8361 100644 --- a/.github/workflows/bench.yml +++ b/.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: diff --git a/.roo/global-settings.copy-to-zoo-code.json b/.roo/global-settings.copy-to-zoo-code.json new file mode 100644 index 0000000..2412572 --- /dev/null +++ b/.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" + } +} diff --git a/.roo/mcp.json b/.roo/mcp.json new file mode 100644 index 0000000..a959620 --- /dev/null +++ b/.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" + } + } + } +} diff --git a/.roo/modes.local.json b/.roo/modes.local.json new file mode 100644 index 0000000..e8c9381 --- /dev/null +++ b/.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." + } + ] +} diff --git a/.roo/specsmith-rules.md b/.roo/specsmith-rules.md new file mode 100644 index 0000000..4a80a8f --- /dev/null +++ b/.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 diff --git a/docs/site/zoo-code-roo.md b/docs/site/zoo-code-roo.md new file mode 100644 index 0000000..43f3112 --- /dev/null +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 414965f..d10d926 100644 --- a/mkdocs.yml +++ b/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