[!TIP] One command. Detects your agents and wires only those. Paste npx @esneiderbravo/speclaw@latest init — speclaw detects Claude Code, Cursor, Codex, Windsurf, and generic AGENTS.md surfaces, scaffolds the constitution + lawbook, indexes your code, and registers the local MCP server — only for the agents you pick. This one-liner is a stable contract (see CONTRIBUTING.md); do not invent alternate install commands in directories or newsletters.

  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.

  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

| Module | What it does | | :-- | :-- | | Foundation | The project's constitution: LAWS.md binding granular standards under docs/standards/, plus CLAUDE.md / AGENTS.md. Enforced via agent hooks (speclaw check), deterministic graph laws (speclaw verify / laws verify), multidialect compile (laws compile), and committed speclaw.lock digests + injection scan (laws lock / accept / scan). | | Compass | Local code graph (tree-sitter → node:sqlite): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema 10. No LLM — lives in .speclaw/ (gitignored). | | Lawbook | Spec-driven workflow with adaptive ceremony (levels 0–3), bugfix changes + lawbook_investigate, EARS linting, requirement coverage, and sealed drift anchors. Loop: explore → draft → build → sync → archive. | | Team | Declare team.owners in lawbook/config.yaml; speclaw owners --write compiles a managed trailing block in .github/CODEOWNERS (GitHub: last match wins). Doctor checks the posture. CLI-only — no MCP tool. | | Tools | Opt-in packs of skills and subagents (currently the dev-agents). |

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

| | Tokens | | :-- | --: | | speclaw budget (always-on) | ~13.7k (8 MCP tools · ceiling 14.0k) | | Spec Kit commands alone | ~18.6k (spec-kit#1401) |

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

| Step | What happens | | :-- | :-- | | explore | Think an idea through before committing to it — should we do this, and how. Writes nothing. | | draft | Propose a ceremony level (0–3) from graph signals, confirm it, then scaffold only what that level needs under lawbook/changes/<name>/. | | build | Implement the tasks in order, keeping code and spec in agreement, and record test results under reports/. | | sync | Reconcile the delta specs against what was actually built, then promote them into the canonical lawbook/specs/. | | archive | Reconcile, then validate, promote, and move the change to lawbook/changes/archive/ — in the same PR. Gated on tasks, reports, synced specs, and coverage. |

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

| Level | When | Artifacts | | :-- | :-- | :-- | | 0 | One-liner / typo / docs-only | speclaw quick → record.md + reports/ | | 1 | Small fix with a delta | record.md + tasks.md + ≥1 delta + reports/ | | 2 | Normal feature | proposal.md + tasks + deltas + reports/ (design.md optional) | | 3 | Full ceremony | proposal + design + tasks + deltas + reports/ | | bug | Regression / RCA | speclaw lawbook draft --bug → bugfix.md + investigate first |

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.

[!NOTE] Delta specs are normative and testable. Requirements use SHALL/MUST under ### Requirement: headers (EARS-friendly), each with #### Scenario: blocks. lawbook_validate checks structure; speclaw coverage tracks req~…~N → impl/test via // Covers: comments.

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 a context-coverage log feeds speclaw doctor.

  Philosophy — why "laws"?

[!NOTE] A guideline is a suggestion. A law is enforced. The most common failure mode of AI coding agents isn't lack of capability — it's working without the project's tacit knowledge: the rules the team actually lives by. speclaw makes that knowledge explicit, executable, and binding, and gives agents a local map (Compass) and a disciplined workflow (Lawbook) to act on it — without burning tokens.

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

| Exit | Meaning | | :-- | :-- | | 0 | No findings at or above --fail-on (default error) | | 1 | At least one finding at or above --fail-on (including strict integrity / scan errors) | | 2 | Usage error (unknown --fail-on / --format) | | 3 | Environment (shallow clone under --ci, or an unwritable --sarif/--json path) | | 4 | At least one law was skipped, and --strict-engines was set |

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