speclaw

         

  Quick start

npx @esneiderbravo/speclaw@latest init

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.

Related MCP server: Graph

  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

  It looks like this

  The suite — six 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.

  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):

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.

  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.

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.

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.

The workspace is committed under lawbook/: specs/, changes/ (with harness.json per active change), changes/archive/, anchors/, and config.yaml.

  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, Cortex, 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, docs/cortex.md, the lawbook/ workspace, and speclaw.lock (rule digests at the repo root). speclaw's regenerable workflow content is local, not committed: only ai-specs/ (skills, commands, rules, role agents, and its .speclaw.json manifest) is gitignored, because init/update reconstruct it from the package. So after cloning a speclaw project, run speclaw init (or speclaw update) to regenerate ai-specs/ locally. Optional team.owners in lawbook/config.yaml compiles into a managed block at the end of .github/CODEOWNERS via speclaw owners --write.

Enforcement artifacts. For agents that support hooks, speclaw merges its law hooks into that agent's settings by identity — it never touches hooks you added yourself. The same merge adds one SessionStart command hook that silently refreshes an existing Compass index when a session starts (speclaw session-start; it skips when no index exists, never downloads or contacts the registry, and always exits 0), and one separate PostToolUse command hook for Write|Edit|MultiEdit|NotebookEdit that hands each edited file to speclaw reindex-file, which re-indexes it in a detached background process (silent, always exit 0; PageRank and the compact map catch up on the next full run). The PostToolUse and PostToolUseFailure hooks on Bash watch test runs: a failing npm test / pytest / go test / … points the agent at lawbook_investigate with the failing output as stackTrace (once per failure signature). The compiled law manifest lives in .speclaw/laws-manifest.json (gitignored) and is adapted to the target tree on init/update — speclaw's own architecture laws are seeded only when those paths exist, and the cycle law follows apps/*/src, packages/*/src, or src/ rather than copying src/modules/** from this package. A context-coverage log 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. Digests in speclaw.lock catch silent edits to the rule files themselves (the Rules File Backdoor).

  Verify in CI

speclaw verify evaluates your deps and graph laws against the local Compass index, and — when speclaw.lock is present — compares digests of managed rule files and scans them (plus skill packs) for known injection patterns. It is deterministic: no model, no API key, no network.

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

Create or refresh the committed lockfile (repo root, never under .speclaw/):

speclaw laws lock
speclaw laws scan
speclaw laws accept AGENTS.md   # interactive TTY only — never via MCP
speclaw laws lock --force       # list drifted files, confirm, re-baseline — interactive TTY only

speclaw laws scan (text or --json) exits 1 when speclaw.lock cannot be read or a finding has severity error. On an unreadable lock it names the lock error (lockError in the JSON) and still reports every injection finding.

A lock refresh (init, update, laws compile, laws lock) never launders an edit: a strict file (CLAUDE.md, AGENTS.md, compiled rules) that drifted from the lock outside speclaw keeps its locked digest, and the command warns run speclaw laws accept <path>, so verify keeps failing until a human accepts it. Clean strict files, new strict files, and advisory files (LAWS.md, docs/standards/*) are refreshed freely, and stale accepted[] entries are pruned — an accepted[] entry lasts until the next refresh rewrites that file, after which the audit trail lives in git history. laws lock --force lists each drifted file with its locked and on-disk digests, asks for confirmation (default No), then re-baselines them and records an accepted[] entry for each (--note adds the reason); without a TTY, when declined, or when any file or digest changed while the prompt was open, it exits 1 and leaves the lock untouched. A speclaw.lock that exists but cannot be read (merge-conflict markers, a newer lockfileVersion, or valid JSON with the wrong structure) is never rebuilt: every refresh leaves it byte-identical and reports the error, and the CLI (including laws accept) exits non-zero until it is repaired (or deleted and re-created with laws lock).

Limits (honest): digests catch any edit; the scanner catches known payload shapes after Unicode normalization — not LLM-grade semantic injection. Digest acceptance is a human gate (laws accept on a TTY). There is no Sigstore signing of the lock in this release. Regenerable IDE mirrors (e.g. .cursor/rules → ai-specs/) are not pinned as strict committed files.

On GitHub:

- uses: esneiderbravo/speclaw@v2

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. Pair with speclaw owners + Require review from Code Owners when you declare team.owners.

  Staying up to date

speclaw checks for new releases in the background (at most once a day) and nudges you when one lands. To bring a project up to date (never runs npm install -g):

speclaw update

update upgrades itself: when npm reports a newer release during the run, it re-executes as npx -y @esneiderbravo/speclaw@<latest> update with the same flags (also in CI), so the latest release applies its own migrations, and exits with that run's code. It migrates with the installed binary instead when you opt out (--no-self-update or SPECLAW_NO_SELF_UPDATE=1), when the registry is unreachable (a cached version only), or when npx cannot be started; it then prints how to upgrade the binary yourself (npm i -g @esneiderbravo/speclaw@latest). init only advises — prefer npx @esneiderbravo/speclaw@latest init.

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

• Managed files (skills/commands/rules under ai-specs/) are refreshed. Pass --backup to keep a <file>.bak before overwrite.

• Personalized files (CLAUDE.md, AGENTS.md, LAWS.md, docs/standards/*, docs/compass.md, lawbook/config.yaml) are never auto-edited — update prints a prompt for the agent you're using.

• speclaw.lock and the CODEOWNERS owners block are refreshed when configured (a drifted strict file keeps its locked digest — see laws accept above).

• Agent MCP entry — init, agent add, and update pin it to the installed version (npx -y @esneiderbravo/speclaw@<version> mcp); update re-pins the stock entry and keeps a custom one (e.g. a local node path).

• speclaw update --check — report version status only; do not re-run or migrate.

• speclaw update --no-self-update — migrate with the installed binary.

• speclaw update --migrate-only — silent no-op alias of the default (compat).

• NO_UPDATE_NOTIFIER=1 — silence the reminder.

• speclaw <command> --help (or -h) — that command's usage; runs nothing.

  Requirements

• Node.js ≥ 22.16 — uses built-in node:sqlite (FTS5 for hybrid find).

• 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 2.0 · where specs become law