speclaw AGENTS.md

AGENTS.md — speclaw

Operating contract for every AI agent (Claude Code, Cursor, Codex, or any other) working in this repository. These rules are STRICT and non-negotiable. Claude-specific notes: CLAUDE.md. The law: LAWS.md.

Project

• What it is: a self-contained MCP suite + CLI that turns any repo into a spec-driven, agent-ready project — its own constitution (Foundation), local code graph (Compass), and spec-driven workflow (Lawbook). 100% local: no LLM, no cloud, no API keys.
• Organization: Esneider Bravo · open source (MIT)
• Stack: TypeScript (ES2022, ESM, Node16 resolution) on Node.js ≥22.16 · MCP server (@modelcontextprotocol/sdk) + Clack CLI · tree-sitter (WASM) parsing · node:sqlite code graph · Zod schemas. No frontend, no service, no LLM.

Mandatory operating rules

1. Read LAWS.md first. It is the constitution; it binds the standards below. Open the standard that governs your change before making it. Conflicts resolve in favor of the standard; amendments go through a spec change, never silent deviation.
2. Compass first, always — for any code question call compass_explore / compass_find / compass_explore before any grep/sed/cat/Read, including files you already know by name. Fall back to manual file tools only after Compass returns nothing useful, the graph is missing (compass_index first), or the target isn't indexed code (stylesheets, config, logs). compass_impact is grouped by module (format: flat escape hatch); prefer compass_affected_tests / speclaw affected-tests --from-diff over the full suite. compass_hotspots / speclaw hotspots ranks activity × AST health (default 90 days); compass_coupling / speclaw coupling reports Jaccard strength, in_graph, and isTestPair. Schema 9 (embedding_cache, Merkle dir_hashes, node_metrics) — reindex with speclaw index after a schema bump (8→9 migrates embeddings). Cheat sheet: docs/compass.md.
3. Follow the lawbook workflow for every non-trivial change; archive within the same PR. Artifact volume follows the confirmed ceremony level in change.json (0=quick … 3=full); missing change.json is level 3. Propose, set, or promote with lawbook_level / speclaw lawbook level; level 0 via speclaw quick. Bugs: speclaw lawbook draft --bug, bugfix.md (repro + regression + prevention), changeType: bug; RCA first with lawbook_investigate / the investigate skill. Feature ceremony unchanged; security-withheld mode is not shipped. Rules: docs/standards/lawbook.md. Coverage: speclaw coverage / lawbook_coverage (ids like req~name~1, // Covers: comments). Drift: speclaw drift / lawbook_drift (committed lawbook/anchors/*.json, dual body/norm hashes).
4. Run the quality gates yourself before declaring anything done — see docs/standards/testing-standards.md:
   • Lint + format: npm run check (Prettier --check + ESLint); npm run format to fix
   • Type-check + compile: npm run build (strict tsc + asset copy)
   • Tests: no unit-test runner yet — the gates above are the compile-time gates; add node:test coverage with new behavior, and verify runtime by exercising the CLI (e.g. node dist/cli/index.js …).
5. Respect the conventions — branches <type>/<short-slug> (no ticket prefix), Conventional Commits (type(scope): imperative summary, English, lowercase), code that reads like its neighbors. See docs/standards/base-standards.md and docs/standards/conventions.md.
6. Use the skills. ai-specs/ is the canonical home for skills, commands, and subagents, mirrored to each IDE directory via symlinks.
7. Ask before irreversible or outward-facing actions — destructive commands; writing to a real data store (DB rows or files with real user data, including for tests — verify against an isolated/throwaway store); publishing reviews/tickets/comments.