15 A small operating playbook

The method works best when the disciplined path is the easiest path, and easiest is something you build. Prepare the repository once. Then run every change through one loop, at whatever weight the change deserves.

15.1 Prepare the repository

Before you assign several agents, put seven things in place.

15.1.1 A document map

Name the sources of truth for product behavior, architecture, active plans, invariants, compatibility, and scars. State which source wins when they disagree.

15.1.2 An invariant suite

List the properties the project cannot casually violate, and give each one a named executable check when practical. Write them in domain language: byte preservation, caret-line stability, route reachability, checkpoint equivalence, label clearance.

15.1.3 A complete command-line path

An agent should be able to build, test, lint, collect logs, capture diagnostics, regenerate documentation, prepare releases, and inspect the live result without hitting a step that only works in a GUI.

15.1.4 Fast local gates

Pin the formatters and linters. Keep targeted checks quick and the full suite reliable. A slow or opaque gate invites bypass.

15.1.5 Branch rules

Decide the worktree, commit, rebase, merge, issue, and documentation protocol once. Reuse it instead of renegotiating mechanics in every conversation.

15.1.6 A scar file

Record the bug classes behind your standing rules. Keep it short enough that a new agent will actually read it.

15.1.7 A completion harness

Define what done means for a delegated unit and encode it where the agent cannot argue with it: passing gates, a required review pass, an updated contract surface, a verified release. Agents stop at bounded units and hand the work back. Delegation grants permission to continue; only the harness makes continuing the default.

15.2 Run the change loop

15.2.1 Reproduce

Use the real binary at the current revision. Save the input, the command, the trace, or the artifact.

15.2.2 Name the semantic decision

A small fix gets a paragraph. A larger change gets a design. Either way, identify the canonical state, the failure behavior, the compatibility rule, and the proof.

15.2.3 Attack the design

Assign independent review lenses. Look for unreachable states, data loss, migration traps, platform differences, and weak test oracles.

15.2.4 Implement in isolation

One branch or worktree per coherent decision. Keep unrelated judgment out of the diff.

15.2.5 Add the ratchet

Write the named regression check, then revert, tamper, or mutate to prove it detects the old behavior. Use an independent oracle when one exists.

15.2.6 Review the code and the proof

Ask fresh reviewers to refute both. Require concrete code references and failing cases, and validate their findings before acting on them.

15.2.7 Repair or reject

Every accepted finding gets a fix and evidence. Every rejected finding gets a technical reason. Every deferred finding states what is missing.

15.2.8 Integrate one change

Refresh against current main, rerun the branch checks, merge, and run the full suite on the merged tree.

15.2.9 Sweep the contract surface

Update the docs, examples, site, editor integration, embedded agent instructions, migrations, issue state, and release notes that belong to the change.

15.2.10 Verify the published result

Check the built artifact, the release assets, the install path, and the live surface. Confirm that the whole required CI graph concluded green, not one workflow: a release job can publish happily while a required check sits red. A green workflow is not the thing users receive.

15.2.11 Preserve the lesson

If the work exposed a reusable failure mode, add the smallest durable test, tool, or scar note that prevents rediscovery.

15.3 Use evidence bundles instead of done

A completion report should contain handles another person or agent can inspect:

• behavior changed;
• root cause;
• old behavior reproduction;
• regression proof;
• deliberate red run or known-bad probe result;
• review findings accepted and rejected;
• commands and revision tested;
• integrated-tree result;
• documentation and release state;
• remaining uncertainty;
• new scar or standing rule.

The bundle does not need to be long. It needs to make every important claim rerunnable.

15.4 Keep the human decision surface small

The agent should not ask permission for routine mechanics the repository already covers. It should stop for choices that change product meaning, compatibility, acceptable loss, or scope.

A good checkpoint presents:

• the fork;
• the evidence for each branch;
• the cost of reversal;
• the recommended choice and why;
• the one fact only the human can supply.

Once you make the choice, execution resumes without repeated approval.

Audit the checkpoints themselves occasionally. A gate whose answer is predetermined by standing policy cannot change the work; remove it rather than respect it. Keep the gates where disagreement is possible and would matter.

15.5 Know when not to use the full loop

A typo in prose does not need a five-reviewer panel. A safe dependency pin may need only the build, the tests, and the generated artifacts. Let the process follow the risk.

Use the full loop when the change touches canonical state, persistence, malformed input, migrations, security, data loss, public contracts, or a proof system. Use a smaller loop when the behavior is local and the existing invariants already cover it.

The method should reduce uncertainty, not manufacture paperwork.