Runs locally · no LLM · no API keys

AI agents are brilliant and blind.

They write code without your project’s rules. speclaw gives them the laws, the map, and the loop that makes the laws hold.

npx @esneiderbravo/speclaw@latest init
View on GitHub

You pick which agents to wire; Claude Code also gets enforcement hooks. See it work

acme-api — speclaw initreal output
npx @esneiderbravo/speclaw@latest init --yes --agents claude╭────────╮│ ────── │   s p e c l a w│ ────   │   where specs become law│ ─────  ││ ▇▇▇▇▇▇ │╰────────╯ ◇ Setting up acme-api✓ Foundation — LAWS.md + 8 standards + CLAUDE.md/AGENTS.md✓ Lawbook workflow — cortex · explore · draft · build · sync · archive✓ Role agents — explorer · planner · implementer · reviewer · tester · archiver✓ Lawbook workspace — lawbook/ ◇ Configuring agents✓ Claude Code — symlinks + MCP ◇ Indexing your code with Compass✓ 2 files · 1 nodes · 2 edges · 1 embeddings ◇ You're set — one last stepHealth check:   speclaw doctor
speclaw 2.0.6 in a two-file sample repo. Long prompt omitted.
9canonical MCP tools
<15 mshook check at p99, with 50 laws
0LLM calls, API keys, or telemetry

Everything speclaw loads into an agent's context has a committed ceiling of 16k tokens, checked by its tests. Spec Kit's commands alone sit around 18.6k.

Built on
  • Model Context Protocol
  • Node.js 22
  • TypeScript
  • tree-sitterWASM
  • SQLite FTS5
  • GitHub Actions
  • SARIF 2.1.0
  • npm provenance
  • Pythonindexed
  • JavaScriptindexed
01

The problem

Why “law”

An agent can skip a guideline. A law blocks the edit.

A request

# CLAUDE.md

Never edit generated files.

Run the standards before you commit.

Ignoredthe edit lands anyway

A request. An agent can ignore a rule in CLAUDE.md.

A law

PreToolUse · Edit · db/schema.generated.ts

lawbook/laws/generated-files.md

deny: generated files are written by the generator

Deniedcited: LAWS.md#generated-files

A law. The hook denies the edit and cites the law. Agents without hooks get the same law as a rule in their own format.

If a rule must hold every time, make it a hook rather than a prompt instruction.

— Claude Code, Hooks
02

The modules

The suite

Four modules hold the laws in place. Team and Tools handle who owns the specs and which extra packs you add.

01

Foundation

Holds your project rules: LAWS.md and the standards it links to. speclaw turns them into agent hooks, rules for each agent, and checks you can run in CI.

  • In Claude Code, a hook checks each Write and Edit before it lands
  • speclaw.lock pins your rule files by SHA-256
  • speclaw verify --ci gates pull requests and reports SARIF
02

Compass

Indexes every function, class, call and import in your Python, JavaScript and TypeScript into a graph on your machine. Agents ask it for the code they need and skip reading whole files.

  • Hybrid search: BM25, lexical vectors and name match
  • explore shows a symbol with its callers, callees, blast radius and tests
  • In Claude Code it refreshes at session start and after every edit
03

Lawbook

Gives every non-trivial change its own folder with a spec, tasks and test reports. How much paperwork a change needs depends on how much code it touches.

  • draft → build → sync → archive
  • Ceremony levels 0–3, proposed from how much of the graph a change touches; HTTP routes count as public API
  • Archive waits for every task, the reports, synced specs and PASS verdicts
04

Cortex

One brain does the critical path, as fast as one agent alone. A hook ships the finished work, and extra agents run only in parallel.

  • A Stop hook sizes the change from its diff, runs the gates on the tests it reaches that are not already green, and archives level-0 work
  • Specced features run explorer → planner → implementer → reviewer → tester → archiver
  • State lives in harness.json; after 3 reworks it asks you
05

Team

You say once, in config, who owns the specs for each capability. speclaw writes that into CODEOWNERS for you.

  • Owners live in lawbook/config.yaml
  • speclaw owners --write keeps a managed CODEOWNERS block
  • It covers the specs and the standards, not your source paths
06

Tools

A catalog of optional packs. speclaw installs none of them unless you ask.

  • list-packs shows the catalog
  • add-pack installs one pack
  • The catalog ships empty in 2.0
03

How it works

From one command to enforced law

Six steps, each leaving files you can read and commit.

  1. Init

    One command scaffolds your constitution, eight standards, the Lawbook workflow and six role agents, links them into .agents/ (or the agents you pick), and indexes your code.

    • LAWS.md
    • docs/standards/
    • ai-specs/
    • .agents/
    • .speclaw/index.db
  2. Fill

    init prints one prompt. Your agent reads the repo and writes your real rules into LAWS.md and the standards.

    • LAWS.md
    • docs/standards/*.md
  3. Compile

    Laws become Claude Code hooks, rules in each agent's own format, and a local lockfile that pins them.

    • .claude/settings.json
    • .mdc rules
    • speclaw.lock
  4. Work

    Each change runs through Lawbook at the ceremony it needs. One agent does the work, reading code through Compass, and a hook ships it with speclaw ship.

    • lawbook/changes/
    • harness.json
    • speclaw ship
  5. Enforce

    In Claude Code a hook denies a violating edit before it lands. Add the speclaw Action and every pull request verifies the laws and reports SARIF.

    • speclaw check
    • speclaw verify --ci
    • speclaw.sarif
  6. Archive

    A change archives only with every task done, reports written, specs synced and the verdicts its level needs. Its anchors are sealed, so later drift is caught.

    • lawbook/specs/
    • lawbook/anchors/
04

Live

One brain. Many agents.

One brain does the work, as fast as one agent alone, and a hook ships it. A feature that needs a spec goes to six roles in turn, and the brain takes each result back before it calls the next.

  1. 01explorerReads the codebase through Compass. Writes nothing.
  2. 02plannerDrafts the change and picks its ceremony level.
  3. 03implementerWorks through the tasks in source and tests.
  4. 04reviewerReads the branch diff once and records PASS or FAIL.
  5. 05testerRuns the gates, verifies by hand, writes the reports.
  6. 06archiverSyncs the specs and archives the change.

state lives in harness.json · the archive lands in the same PR · review happens on the PR · after 3 reworks it asks you

05

Agents

Every agent, in its own format

speclaw compiles one set of laws into each tool’s own format. Claude Code also gets a hook that stops the edit itself.

AgentWhat speclaw writesBefore the edit
Any agent.agents/ · skills, commands, agents, rules · .mcp.json · the defaultRules + CI
Claude Code.mcp.json · skills, commands, agents · path-scoped rules · hooksHook
Cursor.cursor/mcp.json · skills, commands, agents · .mdc rulesRules + CI
Codex.codex/mcp.json · skills, commands, agentsRules + CI
Windsurf.windsurf/mcp.json · skills, commands, agentsRules + CI
AGENTS.mdThe laws, nested where a package livesRules + CI
GitHub Copilot.github/instructions/*.instructions.mdRules + CI
CodeRabbit.coderabbit.yaml path instructionsRules + CI

init sets up .agents/ alone; add another agent with --agents or speclaw agent add cursor. Agents without hooks get the laws as rules in their own format, and speclaw verify --ci checks the dependency and graph laws for all of them.

06

Trust

What runs on your machine

Six things you can check for yourself, true of every speclaw command.

  • No LLM, no API keys

    speclaw never calls a model and stores no credentials. The reasoning stays with the agent you already use.

  • No telemetry

    Nothing to opt out of. Run speclaw telemetry status and it tells you the same.

  • Network only for updates

    A version check against the npm registry, at most once a day, and speclaw update fetching the new release it runs. NO_UPDATE_NOTIFIER=1 and --no-self-update turn them off.

  • Fails open

    A missing or broken manifest never blocks your work: the hook allows the edit. Your own hooks and files are left alone.

  • Rule files are pinned

    A local speclaw.lock pins rule files by SHA-256, and a scanner checks them for hidden text, instruction overrides and exfiltration. An edit made outside speclaw keeps its locked digest and gets a warning until you accept it, and accepting needs a terminal, never an agent.

  • Signed releases

    Published with npm Trusted Publishing and SLSA provenance. Check it with npm audit signatures.

Before you install

Does speclaw call an LLM?Cortex

No. It runs no model and needs no API key. Cortex does not spawn agents either: it keeps the state of a change, a hook ships the work, and your agent spawns any roles.

Which agents get enforcement hooks?Foundation

Claude Code, where a hook checks each edit before it lands. Cursor, Codex, Windsurf, Copilot, CodeRabbit and any AGENTS.md reader get the laws as rules in their own format, and speclaw verify --ci checks them on every pull request you wire it into.

What does Compass index?Compass

Python, JavaScript and TypeScript, parsed with tree-sitter into a local SQLite graph of symbols, calls and imports. Search fuses BM25, lexical vectors and name match. Nothing is downloaded. In Claude Code, hooks refresh the index when a session starts and re-index each file the agent edits.

What do I commit?Foundation

Only your content: LAWS.md, CLAUDE.md, AGENTS.md, docs/ and lawbook/. init gitignores the rest: the index (.speclaw/), the generated workflow (ai-specs/), speclaw.lock, .agents/ and any agent folder or MCP file it creates. Teammates run speclaw init after cloning.

How do I upgrade?Foundation

Run speclaw update. It upgrades itself to the latest release first, refreshes the files speclaw manages, never edits your LAWS.md or standards, and prints one prompt for anything worth reviewing. --no-self-update keeps the installed version.

How much context does it cost?Foundation

Everything it loads has a committed ceiling of 16k tokens. speclaw budget measures your repo, and --minimal cuts the MCP surface to 7 tools.

07

The author

Who builds speclaw

One engineer writes and maintains speclaw in the open, under the MIT license.

Portrait of Esneider Bravo

Esneider Bravo

Senior Backend Engineer

Santa Marta, Colombia

  • Python
  • FastAPI
  • AWS

Get started

Install speclaw

Run one command in the repo you already have.

npx @esneiderbravo/speclaw@latest init
View on GitHub

If you’d rather have a global binary: npm i -g @esneiderbravo/speclaw. Requires Node.js 22.16 or newer.

Commands you will use

speclaw doctor
FoundationChecks the install: Node, SQLite FTS5, hooks, lock and index
speclaw quick fix-typo
LawbookA level-0 change for a one-line fix
speclaw ship <name>
CortexGates once, writes the report, archives level-0 work
speclaw cortex brief --change <name>
CortexWhere a change stands and which role is next
speclaw agent add cursor
FoundationConfigures another agent next to .agents/
speclaw laws accept <path>
FoundationAccepts a rule file edited outside speclaw into the lock
speclaw verify --ci
FoundationThe CI gate: exit codes 0–4 and SARIF 2.1.0
speclaw drift
LawbookCode that changed under a sealed spec
speclaw budget
FoundationWhat your agents load on every session
speclaw visualize
CompassYour code graph as a local HTML page