Hook-enforced discipline for LLM coding agents. Seven rules that prevent the common failure modes: runaway token burn, concurrent-agent file conflicts, unverified "I fixed it" claims, and convention drift.
LLM coding agents have predictable failure modes. Unleashed, they:
- Burn tokens re-exploring code they could index once
- Execute destructive operations without verification gates
- Spawn parallel agents that conflict on shared files
- Generate code that does not compile or fails tests
- Produce output that looks plausible but is wrong
The fix is not a better model. The fix is discipline applied at the dispatch boundary, enforced by hooks at tool-call time.
Every implementation agent runs in a dedicated git worktree with its own filesystem. Agents cannot write to the main branch. Merge only happens after verification passes.
Why: parallel agents corrupt each other's edits. Worktrees force physical separation.
Never dispatch more than 2 implementation agents simultaneously.
Why: a human supervisor cannot review more than 2 concurrent threads of agent work. Past 2, burn outpaces review.
Implementation agents: 15 tool calls maximum. Research agents: 5 tool calls maximum.
Why: past 15 calls on a single task, the agent is either stuck or duplicating work. Hard cap forces escalation.
Implementation agents: 20,000 output tokens. Research agents: 10,000.
Why: runaway verbosity signals agent confusion. Cap forces concision.
No agent dispatches without a TOML plan describing what it must produce and how output will be verified.
Why: "build a feature" without acceptance criteria produces unverifiable output. The plan converts agent output into something testable.
Every agent output passes a mandatory gate before merge:
- Compile or type-check passes
- Test plan assertions pass
- Visual capture if UI (optional, domain-specific)
Why: verification is non-negotiable. Agent self-reported success is not evidence.
Two distinct steps. A code-reviewer validates the diff against plan and conventions. Then the verification gate runs. Both must pass.
Why: review catches convention drift. Verification catches correctness. Both required, neither sufficient.
Never agent what you already know. If the current session has the answer, use it. Do not dispatch for re-discovery.
Log violations. Every agent dispatch that fails a gate writes to an audit log. Review weekly. Patterns signal where discipline is drifting.
Budget lives in hooks, not in prompts. Telling an agent "do not use more than 15 tool calls" does not work. Hooks that abort at call 16 do.
Three hook scripts and one shared library for Claude Code users. Hooks operate on tool-call stdin.
hooks/budget-cap.sh: Rule 3 tool-call budgethooks/worktree-guard.sh: Rule 1 worktree isolationhooks/toml-gate.sh: Rule 5 TOML plan mandatorylib/hook-lib.sh: shared stdin parser and JSON output helpers
See examples/claude-code-setup.md for Claude Code integration.
- The parallel dispatch burn: multi-agent orchestrations spawn 7+ concurrent agents. Concurrency cap of 2 stops this.
- The self-reported success: agent says "I fixed it." Verification gate requires compile and test evidence, not narration.
- The convention drift: agent writes code that works but violates project style. Review step catches it before merge.
- The silent token burn: agent retries the same failing approach 5 times. Tool call cap stops the loop and escalates.
LLM coding workflows where:
- Multiple agents work in parallel
- Agents touch production or shared code
- Output quality matters more than speed
- Token cost is non-trivial
Not worth the overhead for single-prompt code generation, exploratory notebooks, or throwaway prototypes.
MIT. Adopt freely.