speclaw: Instructions file for Codex

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 — Foundation, Compass, Lawbook, Cortex; 100% local
• Organization: Esneider Bravo · open source (MIT)
• Stack: TypeScript (ESM) on Node.js ≥22.16 · MCP server + Clack CLI · tree-sitter (WASM) · node:sqlite · Zod

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_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; Claude Code sessions refresh an existing index at start), or the target isn't indexed code (stylesheets, config, logs). Cheat sheet: docs/compass.md.
3. Cortex, always — one brain on the critical path (One brain. Many agents.). Branch <type>/<slug>, locate with Compass, implement the change and its test yourself, run the tests that cover it, finish. The Stop hook (speclaw ship-on-stop) — or speclaw ship <change> --summary "<what and why>" as your last step on agents without hooks — sizes the change from its diff, names the artifacts that level owes while you edit (the why, tasks, delta specs, proposal/design; write them in the same turn), runs the gates once, writes the report from their real output, and archives level-0 work. Commit with a message whose body says why. Review happens on the PR and never blocks the agent. Add agents only to run three or more large, independent parts in parallel. Details: the cortex skill and docs/standards/lawbook.md.
4. The quality gates run once before anything is declared done — by the Stop hook where there is one, scoped to the tests the diff reaches (run only those yourself: speclaw affected-tests --file <path>; the full suite runs in CI), else by you or speclaw ship — see docs/standards/testing-standards.md:
   • Tests: npm run build && npm test
   • Lint / type-check: npm run check && npm run build
5. Respect the conventions — branches <type>/<short-slug>, commits 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 and role agents. ai-specs/ is the canonical home for skills, commands, rules, and agents; agents read them through the symlinks in .agents/ (plus an IDE folder only for an agent added explicitly).
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. Planner questions always go to the human.