Interlock

Autonomous spec-driven development orchestration for Claude Code, layered on OpenSpec.

This file is the canonical instruction file. It lives at .claude/CLAUDE.md, not the repository root, because the root is also the plugin root and claude plugin validate --strict rejects a CLAUDE.md there. AGENTS.md, if present, is a pointer to it — do not maintain a second copy of this content there.

Commands

• Test: npm test — node --test over a find-piped file list. Run it this way; a bare node --test 'test/**/*.test.mjs' relies on runner-side glob expansion, which collects zero tests on Node 18 and 20 and reports success.
• Validate the plugin: npm run validate — claude plugin validate . --strict. Manifest and marketplace shape.
• There is no lint or build step. Do not invent one, and do not add one to a verification block.

Conventions

• Zero runtime dependencies. package.json has no dependencies key and CI installs nothing — the whole toolchain is stdlib Node. Adding a dependency is a design decision, not an implementation detail; it belongs in a change's design.md with a pinned exact version.
• Node >= 18, "type": "module", .mjs throughout. The one exception is the hooks module's tests, test/mod/*.test.ts: claude plugin test runs only *.test.ts/*.test.tsx files against the engine itself, and npm test collects *.test.mjs only, so they never reach the Node runner.
• hooks/mod.mjs (named by hooks/hooks.json) runs inside the engine with no Node: it and everything it imports must stay free of node: modules and bare specifiers other than claude-code. test/spine/mod-pins.test.mjs pins that, and its observe-only allow-list.
• openspec/ belongs to the OpenSpec CLI. Write into it through openspec new change / openspec instructions, not by hand-scaffolding directories.

Architecture

• cli/ — the executables that land on a user's PATH (interlock, interlock-graph, interlock-run, plus the interlock-ship-acp deprecation shim). It is not bin/: the plugin directory asks a plugin to ship readable scripts outside bin/, so the SessionStart preflight puts cli/ on the session PATH and package.json's bin map points here for npm. interlock openspec provision installs the pinned OpenSpec (lib/openspec-cli.mjs, lib/openspec-pin.mjs); nothing compiled or downloaded at install time ships. Exit codes are the contract; a gate blocks by exiting non-zero.
• lib/ — pure decision modules, one concern each. No I/O beyond what a module's name implies. lib/run.mjs is the ship loop itself: it emits the whole program as versioned steps (agents to spawn, briefings, the exact CLI argv to call next); lib/prompts/ assembles every briefing those steps carry.
• skills/ — model-facing prose. This is a shipped surface: a reworded instruction is a behaviour change.
• hooks/ — PreToolUse and SessionStart guards, registered in .claude-plugin/plugin.json; and mod.mjs, the ship meter, a hooks module hooks/hooks.json names, which observes a ship run and decides nothing.
• workflows/ship.js — the drivers are interpreters, not orchestrators: this script (and cli/interlock-run) spawn what a step from interlock run names, create the lane worktree it names, and call what it names next. Neither holds loop logic; lib/run.mjs does.
• lib/host/ — one adapter per vendor coding CLI (claude-cli, acp, codex, qwen), plus the registry that declares what each host cannot do and the one model map they all read. A capability is declared so the run program can branch on it and the runner can banner it; a host that could not be bannered is a run that degraded silently.
• docs/ — numbered, human-facing. .claude/graph/ holds the agent-facing digests instead.

Things to get right

• Thresholds live in the CLI, not in prose. Caps, bands and gate verdicts are code specifically so a model cannot re-argue them. Never restate a numeric threshold in a skill or a review prompt — read it from interlock limits, or let the gate decide. See docs/12-repository-review-policy.md.
• Guards fail open, never closed. Every hook allows on anything it cannot establish — unknown stage, unresolvable path, missing profile, its own crash. A guard that blocked whenever its marker was absent would break ordinary work the moment the plugin is installed.
• Corpus-loss semantics differ by corpus, and the difference is deliberate. The outcome corpus and review metrics report their own write failures and never touch the exit code. The run trajectory (.claude/ship/runs) and spill are fatal: true — a failed append exits 1, because a run nobody can reconstruct defeats the reason the file exists. Do not "make it consistent."
• A prose instruction nobody asserts silently stops running. interlock review --metrics existed for a year and no skill ever passed it; the corpus stayed empty and read exactly like a loop that never ran. When you add an instruction to a skill, pin it in test/skills.test.mjs — and assert tokens, not sentences, or the first reword deletes the pin.
• Degradation is spoken, never silent. If a path degrades — a missing graph, an absent credential, an unreadable file — say so in the output. Never fall back quietly.

Verifying your work

Run npm test before reporting any task complete, and paste the output.

If a test fails, fix the code. Do not edit, weaken, skip, or delete the test — hooks/guard-tests.mjs denies test edits during a run's remediation and fix-tests stages for exactly this reason, and doing it by hand outside a run is the same mistake without the guard.

Testing

Unit: npm test (cwd: .) Filter: node --test --test-name-pattern <pattern> <file> Single file: node --test path/to/file.test.mjs E2E: opt-in via /fix-tests --e2e (not configured) Prerequisites: none Profile: .claude/testing/profile.json (managed by /interlock:fix-tests)