speclaw

<div align="center"> <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/speclaw-banner.png" width="820" alt="speclaw — where specs become law"> <br/>

<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=00707f&labelColor=131313&style=flat-square&label=npm" alt="npm"></a>  <a href="https://github.com/esneiderbravo/speclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esneiderbravo/speclaw/ci.yml?branch=main&label=CI&labelColor=131313&style=flat-square&color=00707f" alt="CI"></a>  <a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-00707f?labelColor=131313&style=flat-square" alt="npm provenance"></a>  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-00707f?labelColor=131313&style=flat-square" alt="MIT"></a>  <img src="https://img.shields.io/badge/node-%E2%89%A522.16-00707f?labelColor=131313&style=flat-square" alt="Node >= 22.16">  <img src="https://img.shields.io/badge/v2.0-00707f?labelColor=131313&style=flat-square" alt="v2.0">

<br/><br/>

<p align="center"> <b>AI agents are brilliant and blind</b> — brilliant at writing code, blind to <i>your</i> project's rules. <b>speclaw 2.0</b> hands them what they're missing: the codebase's <b>written laws</b> (Foundation), a <b>local map</b> (Compass), a <b>spec-driven lawbook</b>, and <b>Cortex</b> — <i>One brain. Many agents.</i> — the multi-agent loop that plans, builds, reviews, and archives every non-trivial change. Plus the <b>gates</b> that make those laws hold in the editor, in CI, and in the PR. <br/> One command. No cloud, no LLM, no API keys — <b>everything runs on your machine.</b> </p> <img src="https://img.shields.io/badge/100%25_local-00707f?labelColor=131313&style=flat-square" alt="100% local"> &nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-00707f?labelColor=131313&style=flat-square" alt="no LLM"> &nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-00707f?labelColor=131313&style=flat-square" alt="CLI + MCP"> &nbsp;<img src="https://img.shields.io/badge/9_canonical_tools-00707f?labelColor=131313&style=flat-square" alt="9 tools"> &nbsp;<img src="https://img.shields.io/badge/Cortex-One_brain._Many_agents.-00707f?labelColor=131313&style=flat-square" alt="Cortex"> &nbsp;<img src="https://img.shields.io/badge/any_agent-00707f?labelColor=131313&style=flat-square" alt="any agent"> </div> <br/>

[!TIP] One command. Detects your agents and wires only those. Paste npx @esneiderbravo/speclaw@latest init — speclaw detects Claude Code, Cursor, Codex, Windsurf, and generic AGENTS.md surfaces, scaffolds the constitution + lawbook + Cortex roles, indexes your code, and registers the local MCP server (nine tools including cortex) — only for the agents you pick. This one-liner is a stable contract (see CONTRIBUTING.md); do not invent alternate install commands in directories or newsletters.

<br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  Quick start

npx @esneiderbravo/speclaw@latest init

<p align="center"> <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-quickstart.png" width="800" alt="speclaw init"> </p>

Prefer a global install for repeated CLI use?

npm i -g @esneiderbravo/speclaw
speclaw init

The speclaw command is then available everywhere — run speclaw index, speclaw doctor, speclaw verify, speclaw owners --write, or speclaw lawbook … directly.

init will:

1. Ask which agents you use (Claude Code, Cursor, Codex, Windsurf, …) — and configure only those. Add more later; nothing is forced on you.
2. Write the foundation (constitution + standards) and the lawbook workflow, compile your blocking laws into agent hooks, and create a committed speclaw.lock baseline for rule-file integrity.
3. Index your code with a live progress bar and a summary of what it found.
4. Register the speclaw MCP server in each chosen agent's config (nine canonical tools; use --minimal to omit setup/lifecycle tools).
5. Print a prompt to paste into your agent so it fills the constitution with your project's real architecture and conventions.

When something breaks, run speclaw doctor --json and paste it into an issue (required on bug reports). Output is redacted by default.

<br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  Verify a release (provenance)

Every npm publish is signed via Trusted Publishing (OIDC) and carries a SLSA provenance attestation tied to this repository and workflow. That proves where the tarball was built — not that its contents are benign. Pair it with your own review and with speclaw.lock digests on rule files (see Verify in CI).

npm audit signatures
# After downloading the tarball from the registry:
gh attestation verify <tarball> --owner esneiderbravo

<br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  It looks like this

<p align="center"> <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-init.png" width="800" alt="speclaw init — terminal output"> </p> <p align="center"><i>Cyan steps, green checks, a live progress bar — themed with the speclaw palette.</i></p> <br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  The suite — six modules

| Module | What it does | | :-- | :-- | | Foundation | The project's constitution: LAWS.md binding granular standards under docs/standards/, plus CLAUDE.md / AGENTS.md. Enforced via agent hooks (speclaw check), deterministic graph laws (speclaw verify / laws verify), multidialect compile (laws compile), and committed speclaw.lock digests + injection scan (laws lock / accept / scan). | | Compass | Local code graph (tree-sitter → node:sqlite): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema 12 (type-reference callers). Refreshed silently at every Claude Code session start once built. No LLM — lives in .speclaw/ (gitignored). | | Lawbook | Spec-driven workflow with adaptive ceremony (levels 0–3), EARS linting, requirement coverage, sealed drift anchors, bugfix + lawbook_investigate. Artifacts under lawbook/. | | Cortex | One brain. Many agents. The multi-agent loop: durable harness.json, MCP tool cortex (status/start/advance/rework/brief), CLI speclaw cortex, skill /lawbook/cortex. Dispatches explorer → planner → implementer → reviewer → tester → archiver. | | Team | Declare team.owners in lawbook/config.yaml; speclaw owners --write compiles a managed trailing block in .github/CODEOWNERS (GitHub: last match wins). Doctor checks the posture. CLI-only — no MCP tool. | | Tools | Opt-in pack catalog (empty by default). Role agents (explorer/planner/implementer/reviewer/tester/archiver) ship with Lawbook + Cortex. |

Compass is inspired by CodeGraph and the Lawbook module by OpenSpec — both MIT. speclaw reimplements the ideas as its own code and gives full credit; see ATTRIBUTION.md.

<br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  Context cost

speclaw publishes and gates its own always-on context cost. Measured with a deterministic offline estimator (speclaw/estimate-v1, about ±8% vs Anthropic's tokenizer on this corpus — not a BPE dependency):

| | Tokens | | :-- | --: | | speclaw budget (always-on) | ~13.7k (9 MCP tools · ceiling 14.6k) | | Spec Kit commands alone | ~18.6k (spec-kit#1401) |

speclaw budget          # human table
speclaw budget --json   # machine-readable; used by the suite gate
speclaw coverage        # requirement → impl → test coverage (TAP / table)
speclaw drift           # sealed spec ↔ code drift (default --fail-on semantic)
speclaw owners --write  # team.owners → .github/CODEOWNERS
speclaw init --minimal  # omit setup/lifecycle MCP tools from registration

Raising a number in committed token-budget.json is a reviewable PR. Optional calibration (never CI): npm run budget:calibrate with ANTHROPIC_API_KEY. MCP servers cannot mark tools defer_loading — savings come from shorter definitions, omitted registration (--minimal), and JIT skill steps.

<br/>

<img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">  Cortex — One brain. Many agents.

The biggest risk with AI agents isn't capability — it's one session doing everything: explore, code, "review," test, and archive with no durable state and no role boundaries. Cortex is speclaw's answer: a coordinator brain that dispatches specialized roles through a durable harness. Lawbook holds the specs; Cortex runs the loop. Cheat sheet: docs/cortex.md.

<p align="center"> <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/cortex-loop.png" width="800" alt="Cortex — One brain. Many agents."> </p>

| Role | Stage | Owns | | :-- | :-- | :-- | | explorer | exploring | Compass-first investigation; writes nothing under lawbook/ / src/ | | planner | planning | Ceremony level + change artifacts; questions always go to the human | | implementer | implementing | Code + tests; stops at hand-off (no final gates, no archive) | | reviewer | reviewing | reports/review.md PASS/FAIL; no code patches (skipped at level 0) | | tester | testing | Quality gates, manual verification, discipline reports | | archiver | archiving | Sync + lawbook_change action archive in the same PR |

State lives in lawbook/changes/<name>/harness.json. Archive is gated on harness verdicts (test PASS; review PASS when level ≥ 1) plus tasks, reports, sync, and coverage. Max 3 reworks; then the coordinator asks you.

<p align="center"> <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-cortex.png" width="800" alt="speclaw cortex brief"> </p>

Drive it three ways — same engine:

• In your agent — /lawbook/cortex (coordinator) plus per-role skills
• MCP — canonical tool cortex (status / start / advance / rework / brief)
• CLI — speclaw cortex …

Lawbook — the specs Cortex runs

Lawbook is the artifact layer: adaptive ceremony (levels 0–3), EARS linting, requirement coverage, sealed drift anchors, bugfix + investigate.

| Level | When | Artifacts | | :-- | :-- | :-- | | 0 | One-liner / typo / docs-only | speclaw quick → record.md + reports/ | | 1 | Small fix with a delta | record.md + tasks.md + ≥1 delta + reports/ | | 2 | Normal feature | proposal.md + tasks + deltas + reports/ (design.md optional) | | 3 | Full ceremony | proposal + design + tasks + deltas + reports/ | | bug | Regression / RCA | speclaw lawbook draft --bug → bugfix.md + investigate first |

[!NOTE] Delta specs are normative and testable. Requirements use SHALL/MUST under ### Requirement: headers (EARS-friendly), each with #### Scenario: blocks. lawbook_change action validate checks structure; speclaw coverage tra