speclaw

   

  Quick start

Install speclaw globally (once), then run init in your project root:

npm i -g @esneiderbravo/speclaw
speclaw init

The speclaw command is now available everywhere — run speclaw index, speclaw visualize, or speclaw lawbook … directly in any project.

init will:

1. Ask which agents you use (Claude Code, Cursor, Codex, …) — and configure only those. Add more later; nothing is forced on you.

2. Write the foundation (constitution + standards) and the lawbook workflow, and compile your blocking laws into agent hooks for the agents that support them.

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.

5. Print a prompt to paste into your agent so it fills the constitution with your project's real architecture and conventions.

Prefer not to install globally? A one-off npx @esneiderbravo/speclaw init works too (also pnpm dlx / yarn dlx) — but installing globally means you can run the speclaw commands directly afterwards.

Related MCP server: Graph

  It looks like this

  The suite — four modules

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.

  The spec-driven workflow (Lawbook)

Lawbook is speclaw's answer to the biggest risk with AI agents: code that drifts from intent. The intent is written first, the code is made to match it, and the spec is promoted to the project's canonical record — so nothing non-trivial lands without a spec change. It's a loop of five steps:

   ┌─────────┐    ┌───────┐    ┌───────┐    ┌──────┐    ┌─────────┐
   │ explore │ ─▶ │ draft │ ─▶ │ build │ ─▶ │ sync │ ─▶ │ archive │
   └─────────┘    └───────┘    └───────┘    └──────┘    └─────────┘

Every draft writes four artifacts under lawbook/changes/<name>/ — none optional:

Plus a reports/ folder — scaffolded at draft, filled at build with one report per discipline (backend.md, frontend.md, …) recording the real unit/integration/e2e results. Evidence of testing travels with the change, and lawbook_archive refuses to archive without it.

Three ways to drive it — same engine, no external CLI:

• In your agent — the /lawbook:explore, /lawbook:draft, /lawbook:build, /lawbook:sync, /lawbook:archive commands (installed as skills).

• MCP tools — lawbook_init, lawbook_validate, lawbook_sync, lawbook_archive, lawbook_list.

• CLI — speclaw lawbook init | list | validate | sync | archive.

The workspace is committed under lawbook/: specs/ (canonical), changes/ (in-flight), changes/archive/ (shipped), and config.yaml (the mandatory task steps every change must include). The standards themselves are amended the same way — through a spec change reviewed by a human.

  Two ways to use it

speclaw meets you where you are. Everything works through the CLI — so no one is blocked by MCP setup — and the same capabilities are exposed as MCP tools for a smoother, integrated experience once configured. An agent without MCP can still use Compass and the lawbook engine by calling the CLI from its shell.

  What lands in your project

Committed vs. local. Your personalized source is committed — LAWS.md, CLAUDE.md, AGENTS.md, docs/standards/*, docs/compass.md, and the lawbook/ workspace. speclaw's regenerable workflow content is local, not committed: only ai-specs/ (skills, commands, rules, agent packs, and its .speclaw.json manifest) is gitignored, because init/update reconstruct it from the package — like a dependency. So after cloning a speclaw project, run speclaw init (or speclaw update) to regenerate ai-specs/ locally, which the agent IDE symlinks point into. If a project committed ai-specs/ before this behavior existed, init/update print the exact git rm -r --cached ai-specs command to stop tracking it (they never touch your git index themselves). The agent directories (.claude/, .cursor/, …) are left to you — commit your own skills and commands there if you want to.

Enforcement artifacts. For agents that support hooks, speclaw merges its law hooks into that agent's settings (e.g. .claude/settings.json) by identity — it never touches hooks you added yourself. The compiled law manifest lives in .speclaw/laws-manifest.json (gitignored, regenerated on init/update), and a context-coverage log in .speclaw/context-log.jsonl feeds speclaw doctor.

  Philosophy — why "laws"?

This is why "enforced" is literal, not a metaphor. Anthropic's own guidance puts it plainly:

"An instruction like 'never edit .env' in CLAUDE.md or a skill is a request, not a guarantee. A PreToolUse hook that blocks the edit is enforcement. If a rule must hold every time, make it a hook rather than a prompt instruction." — Claude Code — Hooks

So speclaw init compiles your blocking laws into agent hooks: a law marked bloqueo is denied at the keystroke (PreToolUse), citing the law's id, text, and source. speclaw check --dry-run --path <file> previews what would block, and speclaw doctor reports how many of your laws actually reached the agent's context. Agents without hooks (Cursor, Codex) enforce the same laws in CI via speclaw verify.

  Verify in CI

speclaw verify evaluates your deps and graph laws against the local Compass index. It is deterministic: no model, no API key, no network.

speclaw verify --ci --sarif speclaw.sarif --json speclaw.json

On GitHub:

- uses: esneiderbravo/speclaw@v1

init / update write .github/workflows/speclaw.yml only when that path is missing — they never overwrite your CI. Make the check required in branch protection yourself; speclaw does not.

  Staying up to date

speclaw checks for new releases in the background (at most once a day) and nudges you when one lands. To upgrade:

speclaw update

update upgrades the global package and brings the current project up to date without a re-init, splitting files by who owns them:

• Managed files (speclaw's workflow machinery — the skills, commands, rules, and agent packs under ai-specs/) are refreshed to the new version, so improvements actually reach your project. They live locally (gitignored, see What lands in your project) and are reconstructed from the package. If you edited one locally, update reports the overwrite; pass --backup to keep a <file>.bak (itself gitignored) before it is refreshed.

• Personalized files (your constitution and standards — CLAUDE.md, AGENTS.md, LAWS.md, docs/standards/*, docs/compass.md, lawbook/config.yaml) are never auto-edited. When a release changes their speclaw-authored content, update prints a prompt for the agent you're using to apply the change while preserving your project's specifics.

• speclaw update --check — report whether an update exists, change nothing.

• NO_UPDATE_NOTIFIER=1 — silence the reminder.

  Requirements

• Node.js ≥ 22 — uses the built-in node:sqlite.

• No native builds, no services, no API keys, no LLM download. Tree-sitter parsers ship as WASM; the vector store is local.

MIT  ·  built on ideas from OpenSpec &  CodeGraph  ·  see ATTRIBUTION.md

speclaw · where specs become law