The decision records¶
Each design decision of this kit is an architecture decision record, an ADR. An ADR is a short file that gives the context of a decision, the decision, and its consequences. I keep them in the repository so that a contributor can read the reason for a rule without access to a private tracker. A code comment gives its reason inline, or it cites an ADR.
The ADRs are in docs/adr/. They record decisions about the whole kit, so they sit in the documentation and not inside one skill. The site does not build them as pages. This page is the index, and each entry links to the file on GitHub. A test fails when an ADR exists that this page does not list, so the index cannot fall behind.
The index¶
- ADR 0001: Effort follows the model: a rendered Claude Code agent has no
effortkey unless the declaration sets one, because the effort comes with the model. - ADR 0002: The OpenCode push guard stays narrow: the OpenCode specialist keeps two push denies, and the renderer does not widen them to a pattern that would also match other commands.
- ADR 0003: The caller can override the OpenCode model column:
renderandvalidatetake flags that change the OpenCode column of the tier table, andbootstraptakes none. - ADR 0004: Gate commands are per repository: the global verifier guard list does not grow. A repository names its own gates, and they are the only extra commands its verifier may run.
- ADR 0005: The Claude Code guards read the hook input with python3: both guards read the command with
python3, so they need nojqand they fail closed. - ADR 0006: A load-time block is one plain command: each block of a context skill that Claude Code runs at load time is one plain command. No Claude Code documentation states the rule. The ADR records the measurements: Claude Code 2.1.283 on 2026-09-26, with each of the
--permission-modevaluesdefault(manual),acceptEditsandauto. - ADR 0007: The engine runs each agent from a sealed agent, outside the tree under review: each session of a
delegate runstarts from a copy of the agent that the engine makes at the start of the run, outside each tree, and not from the project agent of the tree. The ADR names the five measured options and the reason for the choice, and it records that the project settings and the projectCLAUDE.mdare dropped on purpose. The measurements are on Claude Code 2.1.287 and OpenCode 1.15.10. - ADR 0008: The run index is derived from the journals: each run writes a record of itself to the run index, a list that each host can read. The journal stays the record of the run, and a failed write of the index changes nothing in the run.
- ADR 0009: The journal has one projection: the run state: the engine and each view decide the state of a run and of its tickets from one fold of the journal, the run state. A second record of the state on the disk, and a fold in each view, are rejected.
How to read an ADR¶
Each ADR opens with a status, a date and the part of the kit that it applies to. The date matters. A harness fact in an ADR is true on the day I measured it, and a new version of the harness can change it. When a decision depends on such a fact, the ADR names the version and the date.
Some ADRs set limits that come up again in the enforcement model and its limits. ADR 0002, ADR 0005 and ADR 0007 do.
How to add an ADR¶
Write the next number, a short name, and the sections Context, Decision and Consequences. Then add the ADR to the index above. The test names the ADR that is missing from the index.