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 (eight 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 — five 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.

  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 │
   └─────────┘    └───────┘    └───────┘    └──────┘    └─────────┘

Ceremony levels (confirmed in change.json; missing ⇒ level 3):

Plus a reports/ folder — scaffolded at draft, filled at build with one report per discipline (backend.md, frontend.md, api.md, …). lawbook_archive refuses to archive without it.

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

• In your agent — /lawbook:explore, /lawbook:draft, /lawbook:build, /lawbook:sync, /lawbook:archive (and /lawbook:quick, investigate).

• MCP tools — eight canonical: compass_explore, compass_find, compass_diff_context, compass_index, lawbook_change, lawbook_investigate, speclaw_setup, speclaw_check.

• CLI — speclaw lawbook …, speclaw quick, speclaw coverage, speclaw drift.

The workspace is committed under lawbook/: specs/, changes/, changes/archive/, anchors/ (drift photographs), and config.yaml (mandatory tasks, ceremony cuts, team.owners, EARS knobs).

  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, 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, agent packs, 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 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

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@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. 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 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 (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.

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

• NO_UPDATE_NOTIFIER=1 — silence the reminder.

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