|
| 1 | +# Warp Terminal Integration |
| 2 | + |
| 3 | +specsmith v0.12.0 ships native integration with [Warp](https://www.warp.dev) terminal at two levels: |
| 4 | + |
| 5 | +1. **MCP governance server** — Warp/Oz (and any MCP client) can call governance commands as structured tool calls without shell roundtrips. |
| 6 | +2. **Repository workflows** — seven `Ctrl+Shift+R`-searchable workflows appear automatically when you open this repo in Warp. |
| 7 | + |
| 8 | +--- |
| 9 | + |
| 10 | +## Native MCP Server Setup |
| 11 | + |
| 12 | +### What it does |
| 13 | + |
| 14 | +`specsmith mcp serve` starts a zero-dependency MCP server (JSON-RPC 2.0, protocol pin 2024-11-05) over stdio. Once configured in Warp, Oz can call any of six governance tools natively — getting back structured JSON, not terminal output. |
| 15 | + |
| 16 | +### One-time setup |
| 17 | + |
| 18 | +**Step 1:** Get the config snippet: |
| 19 | + |
| 20 | +```bash |
| 21 | +specsmith mcp install-warp |
| 22 | +``` |
| 23 | + |
| 24 | +Output: |
| 25 | +```json |
| 26 | +{ |
| 27 | + "specsmith-governance": { |
| 28 | + "command": "specsmith", |
| 29 | + "args": ["mcp", "serve", "--project-dir", "/path/to/your/project"] |
| 30 | + } |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +**Step 2:** Open **Warp → Settings → Agents → MCP servers** and paste the JSON. |
| 35 | + |
| 36 | +After saving, Warp/Oz will show `specsmith-governance` as an available tool server. Oz will call governance commands automatically when they are relevant to the task. |
| 37 | + |
| 38 | +### Using with oz agent run (inline) |
| 39 | + |
| 40 | +For one-off cloud agent runs, pass the config inline: |
| 41 | + |
| 42 | +```bash |
| 43 | +oz agent run \ |
| 44 | + --mcp '{"specsmith-governance": {"command": "specsmith", "args": ["mcp", "serve"]}}' \ |
| 45 | + --prompt "check governance health, run a preflight for my next change, and report what phase we are in" |
| 46 | +``` |
| 47 | + |
| 48 | +--- |
| 49 | + |
| 50 | +## MCP Tools Reference |
| 51 | + |
| 52 | +| Tool | Description | Required inputs | Returns | |
| 53 | +|---|---|---|---| |
| 54 | +| `governance_audit` | Run the full governance audit | `project_dir` (optional) | `healthy`, `passed`, `failed`, `checks[]` | |
| 55 | +| `governance_checkpoint` | Emit GOVERNANCE ANCHOR snapshot | `project_dir` (optional) | `anchor`, `phase`, `health`, `req_count`, `test_count`, `esdb_chain_valid`, `recent_work_items` | |
| 56 | +| `governance_preflight` | Preflight a proposed change | `intent` (required), `project_dir` | `decision`, `work_item_id`, `instruction` | |
| 57 | +| `governance_phase` | Current AEE phase + readiness | `project_dir` (optional) | `phase`, `label`, `pct`, `failing_checks` | |
| 58 | +| `governance_req_list` | List all requirements | `project_dir`, `status_filter` | `total`, `covered`, `reqs[]` | |
| 59 | +| `governance_trace_seal` | Seal a milestone or decision | `seal_type`, `description`, `project_dir` | `sealed`, `seal_id`, `entry_hash` | |
| 60 | + |
| 61 | +### governance_audit |
| 62 | + |
| 63 | +Returns a complete governance health picture. Oz uses this to decide whether to proceed with a change. |
| 64 | + |
| 65 | +```json |
| 66 | +{ |
| 67 | + "healthy": true, |
| 68 | + "passed": 27, |
| 69 | + "failed": 0, |
| 70 | + "fixable": 0, |
| 71 | + "suppressed": 0, |
| 72 | + "checks": [ |
| 73 | + {"name": "file-exists:AGENTS.md", "passed": true, "message": "Required file AGENTS.md exists"}, |
| 74 | + ... |
| 75 | + ] |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +### governance_checkpoint |
| 80 | + |
| 81 | +Emits the GOVERNANCE ANCHOR — include this verbatim in any context summary. Oz calls this automatically every 8–10 turns via the `specsmith-session-governance` skill. |
| 82 | + |
| 83 | +```json |
| 84 | +{ |
| 85 | + "anchor": "SPECSMITH-ANCHOR-2026-06-01T20:00:00Z", |
| 86 | + "project": "specsmith", |
| 87 | + "phase": "release", |
| 88 | + "phase_label": "🚀 Release", |
| 89 | + "phase_pct": 100, |
| 90 | + "health": "clean", |
| 91 | + "req_count": 321, |
| 92 | + "test_count": 325, |
| 93 | + "esdb_chain_valid": true, |
| 94 | + "recent_work_items": ["WI-7320B3C9"] |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### governance_preflight |
| 99 | + |
| 100 | +Gate every code change through this. Returns `accepted` + `work_item_id` to proceed, or `needs_clarification` with an instruction to refine the intent. |
| 101 | + |
| 102 | +```json |
| 103 | +{ |
| 104 | + "decision": "accepted", |
| 105 | + "work_item_id": "WI-7320B3C9", |
| 106 | + "instruction": "Change request matched existing governance scope. Proceed under Specsmith verification.", |
| 107 | + "intent": "change" |
| 108 | +} |
| 109 | +``` |
| 110 | + |
| 111 | +### governance_phase |
| 112 | + |
| 113 | +Tells Oz what phase the project is in and what checks are failing. |
| 114 | + |
| 115 | +```json |
| 116 | +{ |
| 117 | + "phase": "release", |
| 118 | + "label": "🚀 Release", |
| 119 | + "pct": 75, |
| 120 | + "description": "CHANGELOG updated, release tag created, compliance report filed.", |
| 121 | + "failing_checks": ["Trace vault has seals"] |
| 122 | +} |
| 123 | +``` |
| 124 | + |
| 125 | +### governance_req_list |
| 126 | + |
| 127 | +List requirements, optionally filtered by status (`planned`, `implemented`, `partial`, `deprecated`). |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + "total": 321, |
| 132 | + "covered": 321, |
| 133 | + "reqs": [ |
| 134 | + {"id": "REQ-363", "title": "specsmith mcp serve: native stdio MCP server...", "status": "implemented", "covered": true}, |
| 135 | + ... |
| 136 | + ] |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +### governance_trace_seal |
| 141 | + |
| 142 | +Seal types: `decision`, `milestone`, `audit-gate`, `logic-knot`, `stress-test`, `epistemic`. |
| 143 | + |
| 144 | +```json |
| 145 | +{ |
| 146 | + "sealed": true, |
| 147 | + "seal_id": "SEAL-0001", |
| 148 | + "seal_type": "milestone", |
| 149 | + "description": "v0.12.0 released — native MCP governance server", |
| 150 | + "timestamp": "2026-06-01T20:00:00+00:00", |
| 151 | + "entry_hash": "a3f9b2c1..." |
| 152 | +} |
| 153 | +``` |
| 154 | + |
| 155 | +--- |
| 156 | + |
| 157 | +## Repository Workflows (Ctrl+Shift+R) |
| 158 | + |
| 159 | +Opening the specsmith repo in Warp automatically makes seven governance workflows available via `Ctrl+Shift+R` search. |
| 160 | + |
| 161 | +| Workflow name | What it runs | When to use | |
| 162 | +|---|---|---| |
| 163 | +| specsmith — Session Start | kill → migrate → audit → sync → checkpoint | Start of every session | |
| 164 | +| specsmith — Audit | `specsmith audit` | Check governance health | |
| 165 | +| specsmith — Checkpoint | `specsmith checkpoint` | Every 8–10 turns, or before a context summary | |
| 166 | +| specsmith — Preflight | `specsmith preflight "{{intent}}" --json` | Before any code change | |
| 167 | +| specsmith — Save | `specsmith save` | After completing a feature or fix | |
| 168 | +| specsmith — Phase Status | `specsmith phase show` | See current AEE phase + failing checks | |
| 169 | +| specsmith — Session End | `specsmith save && specsmith kill-session` | End of every session | |
| 170 | + |
| 171 | +### Session workflow |
| 172 | + |
| 173 | +``` |
| 174 | +1. Ctrl+Shift+R → "specsmith session start" → Enter |
| 175 | + (runs: kill → migrate → audit → sync → checkpoint) |
| 176 | +
|
| 177 | +2. Make your changes, using Preflight before each one |
| 178 | +
|
| 179 | +3. Ctrl+Shift+R → "specsmith save" → Enter |
| 180 | +
|
| 181 | +4. At end of day: Ctrl+Shift+R → "specsmith session end" → Enter |
| 182 | +``` |
| 183 | + |
| 184 | +--- |
| 185 | + |
| 186 | +## Skill Auto-Discovery |
| 187 | + |
| 188 | +The specsmith repo ships five governance skills in `.agents/skills/`. Warp/Oz auto-discovers these and loads them at session start: |
| 189 | + |
| 190 | +| Skill | Purpose | |
| 191 | +|---|---| |
| 192 | +| `specsmith` | Master CLI reference — session workflow, commands, audit codes | |
| 193 | +| `specsmith-audit` | Running audits and interpreting results | |
| 194 | +| `specsmith-save` | When and how to run `specsmith save` | |
| 195 | +| `specsmith-session-governance` | Drift prevention, heartbeat every 8–10 turns, preflight gate | |
| 196 | +| `release-pilot` | Gitflow release-cut workflow | |
| 197 | + |
| 198 | +The `specsmith-session-governance` skill is the most important for AI sessions — it instructs Oz to enforce the preflight gate before every code change and emit a checkpoint every 8–10 turns automatically. |
| 199 | + |
| 200 | +--- |
| 201 | + |
| 202 | +## Troubleshooting |
| 203 | + |
| 204 | +**`specsmith mcp serve` not found in Warp MCP servers list** |
| 205 | + |
| 206 | +Ensure specsmith is installed via pipx (not pip): |
| 207 | +```bash |
| 208 | +pipx install specsmith |
| 209 | +which specsmith # should point to ~/.local/bin/specsmith or ~/pipx/venvs/... |
| 210 | +``` |
| 211 | + |
| 212 | +**MCP tool call returns an error** |
| 213 | + |
| 214 | +Run `specsmith audit` manually to check governance health. Some tools (like `governance_req_list`) require `.specsmith/requirements.json` to exist — run `specsmith sync` first. |
| 215 | + |
| 216 | +**Checkpoint returns `phase: "unknown"`** |
| 217 | + |
| 218 | +The project directory needs a `docs/SPECSMITH.yml` or `scaffold.yml` file. Run `specsmith init` or `specsmith import` to set up governance. |
| 219 | + |
| 220 | +**`governance_trace_seal` fails** |
| 221 | + |
| 222 | +The `.specsmith/` directory must exist. Run `specsmith sync` first. |
0 commit comments