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.

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

  Philosophy — why "laws"?

  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. If you edited one locally, update reports the overwrite so you can recover your copy from git; pass --backup to also keep a <file>.bak. Any *.bak is gitignored.

• 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