Appendix A — For Agents — Home for Deranged Scientists

Reference, not flow. The Coda was the closing statement. This appendix exists so agents can find the rules without re-reading the prose — and so humans can skim the whole spine in one screen when they want to.

You are an agent, and a human engineer has loaded this playbook as context because they want you to work the way it describes. It does not matter which model you are or which harness is running you — the rules below are model-invariant, and §2 maps the harness-specific names (read "CLAUDE.md" as your instructions file, "settings.json" as your harness config). This appendix is your index: every rule from chapters §1 through §16, stripped to imperatives, each with a one-sentence reason and a link back to the full section. Skim the rules here; jump to the section when a rule needs context you don't have. One overriding instruction: if anything in this appendix conflicts with the project's instructions file, with a skill the user tells you to run, or with a direct instruction from the user, the user wins — always. The rest of the file is for the human reading over your shoulder; you can skim it, but the rules live here.

§1 Mental models · full section

Brief the agent like a smart colleague who just walked into the room. — Every prompt is a cold start; a self-contained briefing prevents invented answers.
Delegate the task, not the understanding. — Synthesis is the engineer's job; handing the agent a riddle is where work falls apart.
The agent is good at breadth and consistency. It is bad at judgment under ambiguity. — Use it for search, refactor, fan-out; make trade-off calls yourself.
Agent-authored domain content is a plausible first draft of the world, not the world. — Wordlists, heuristics, and personas encode the author's vocabulary; only real data and the human's world knowledge close the gap.

§2 The model and the harness · full section

The disciplines are model-invariant. Only the calibration moves. — A model upgrade widens the qualifiers (step size, delegable judgment); it never retires verification, retros, or trust boundaries. A better model fails less often and more convincingly.
Pick the model tier by the shape of the work, not the size of the diff. — Gates can judge mechanics, so mechanics go cheap; nothing but the model judges voice, so voice goes expensive.
The harness is a dependency: map its layers, keep the knowledge portable. — File knowledge by layer (instructions file, memory, skills, hooks, permissions), not by filename; prefer repo-portable homes (AGENTS.md, docs/, retros) so a harness swap loses nothing.
Trust harness claims the way you trust "tests pass": with evidence. — Edit tools mis-report, CLIs truncate secrets, CI providers have billing disputes; verify with an independent read, and keep a manual fallback for every automated rail.

§3 The workspace · full section

Your pipeline is a precondition, not a feature. — Every discipline in this playbook assumes CI catches mechanical failures quickly and deploys are automated; a flaky pipeline inverts the loop and drags the human into the mechanics layer. You are done when the pipeline is boring. And every automated rail needs a rehearsed manual fallback — automation you can't bypass is a dependency you can't survive.
The instructions file is for facts that don't change. Memory is for facts that do. — Stable facts in a stable layer stay correct; moving facts in memory can be corrected next turn.
Skills are for procedures. The instructions file is for facts. — Skills get executed on purpose; notes get absorbed as ambient noise and ignored under pressure.
Hooks make automation non-negotiable. — Anything the agent is asked to "remember to do" will fail silently at least once; hooks take the choice out of the loop.
The harness config configures the harness. The instructions file configures the agent. They are different layers. — "Can't" is enforced by the tool; "should" is enforced by politeness.

§4 The first conversation · full section

Bootstrap with the smallest context that contains the answer. — Token budget is attention budget; three load-bearing files beat eighty skimmed ones.
Correct drift in message 2, not message 50. — Early corrections are nearly free; late ones mean rewriting ten turns built on top of the drift. The highest-leverage corrections are conceptual reframings — correct the frame in one sentence now, or the code in one release later.
If the agent doesn't know something, tell it. Don't let it guess. — Hallucination is most likely when the agent is confidently filling a gap.
Make the agent tell you what it thinks you're building — then grill it. — The agent's model of the product is a guess until you've heard it recited and corrected it out loud; the value proposition is not derivable from a type definition.

§5 The loop · full section

Explore before you plan. The plan is not the codebase. — Run the greps, check the migration state, dispatch the survey agent; ten minutes of reading reality deletes an hour of planning against a memory of it, and exploration finds the bugs nobody filed.
Run the whole loop. Skip a step out loud or pay for it silently. — Each step (explore, brainstorm, plan, TDD, verify, commit, retro) catches a different class of failure.
Brainstorm before planning. Plan before code. — Out of order, the bounds are hallucinated; a plan that feels obvious hasn't been pressure-tested. The brainstorm can amortize across cycles when the upfront thinking was rigorous.
Frequent commits are not optional. — Bisecting agent bugs only works if commits are small enough to bisect against. Precondition: a pipeline fast enough to support the cadence.
Retros feed the next loop. — Without them, the loop has no memory and each release starts from zero.
Cycles nest. Each level needs a theme, a boundary, and all three phases. — Task-level, release-level, and project-level loops all take the same shape; cycles without themes get named by date and forgotten.

§6 Memory hygiene · full section

Memory has four types. Use the right one or it rots. — User facts, feedback, state, and pointers have different staleness profiles; mixing them produces a junk drawer.
Stale memory is worse than no memory. — No memory makes the agent ask; stale memory makes it act confidently on last quarter's facts.
A belief you've never probed is a hypothesis, not a memory. — Memory and instructions files amplify whatever they're given, true or not; attach the command that proves each infrastructure belief, and run it.
Save the why, not just the rule. — A rule without its reason becomes unfollowable dogma the moment the world moves on.
Don't memorize what the code already says. — Anything one grep away will drift out from under a memory note the moment a file is renamed.
File your neighbor's scars, keyed to the trigger that will make them yours. — A sibling project's bug plus a named trigger (the dependency bump, the platform migration) is your cheapest future fix; fleets learn through cross-repo memory.

§7 Skills as institutional knowledge · full section

Skills are procedures with discipline. Instructions-file notes are facts you hope get followed. — If a thing must happen reliably, it needs a host other than the agent's attention.
Rigid skills exist for a reason. Don't adapt the discipline away. — Rigid skills feel like overkill in exactly the moments they're needed most.
Write a skill after the third correction. — The third correction is the moment "I keep saying this" becomes "the system should enforce this."
Ship the cheap defense now; schedule the clean refactor for a quiet phase. — The warning comment buys the time; the maintenance cycle spends it; skipping either half is how seams become incidents. Rigor budgets are per-audience — debug tooling may take documented shortcuts user-facing code can't.

§8 Verification before completion · full section

"Tests pass" is not "feature works." Verify the feature. — Suites can be green while the feature is broken because no test exercised the wire. Check what each assertion would tolerate — a test guarding a weaker property than the invariant is theater in miniature.
Evidence before assertions. Always. — Prose without paste is hallucination; evidence of the wrong claim is theater.
Ask: would these tests pass if the change were reverted? — If yes, they don't test the change; rename what they actually pin and verify in the layer being fixed.
Verify in the environment that matters. — If local doesn't run what CI runs, local green is a lie. Test with the rudest client you support; verify what was fetched, not what rendered.
When a value crosses a layer boundary, verify the wire, not the fixture. — Some delivery properties are structurally invisible to unit tests; the manual wire-level integration task is mandatory plan content, not extra credit.
Health checks must check health — and observability must be observed. — A check that can't detect a downed dependency is a status check cosplaying as one; an unobserved error tracker is a prop. Fire a test flare through it.

§9 Trust boundaries · full section

Match the action to its blast radius. Confirm before crossing the line. — Blast radius is set by recovery time, not by command length. Reversibility has a time axis: deploy the conservative setting first and calendar the escalation on hard-to-put-back levers.
Authorization is scoped, not blanket. — Every yes is for one action; it is not a standing permission slip for the next risky thing.
When the agent hits an obstacle, it must investigate, not delete. — Unexpected files and orphan containers usually represent in-progress work; if you can't show where you looked, you didn't look. Mirror clause: investigation depth follows blast radius — a zero-impact tooling mystery gets a note and a ticket, not a session.
Secrets never transit the transcript. — The session log is a copy of everything that touches it; pipe secrets, verify their properties not their values, and rotate anything that leaked.
Before touching a non-negotiable, write down what would change your mind. — File the challenge as a pre-registered experiment: measurable bar, full cost accounting, no conclusion before evidence.

§10 Diagnosis — build the lab · full section

Build the diagnostic surface before the fix. — When a bug class recurs, ship the instrument (persisted traces, replay playground, exportable diagnostics) first; then the fixes land in batches and you watch them land instead of inferring it.
The ticket's diagnosis is a hypothesis. Read the trace before believing the issue. — Fixes designed from the ticket's framing are beautiful solutions to problems that may not exist; the trace is the only witness that was there.
A fixed bug's class is a search query, not a closed ticket. — The siblings are one layer up or down; hunt them by grep while the failure mode is fresh, or pay a full diagnosis per sibling later.
Exploration mode is not production mode. — Stateful rules that are correct in the real flow misbehave against a playground's frozen state; bypass them in the lab with an explicit flag, never in production.
When the runner wedges, suspect the runner. — Failures in files you didn't touch, at speeds that make no sense, are the tooling talking; try the cache clear and the config change before debugging your code, and don't over-investigate a mystery with zero blast radius.

§11 Failure modes & recovery · full section

Agent went off the rails: stop, open a fresh conversation, and write a self-contained briefing (§4) — steering a context-starved conversation only gives new ways to be wrong.
Agent produced slop: add explicit YAGNI constraints and promote them into memory or a skill (§6, §7) — without a rail, every prompt drifts toward gold-plating.
Agent can't be trusted with anything important: install evidence-before-assertions discipline hard (§8) — you can't out-discipline a missing rail; build the rail.
Agent loops on the same wrong fix: stop touching code, dump raw state, diagnose the real failure (§8, §10) — when the second fix fails the same way, the root cause is misdiagnosed; if the class recurs, build the lab.
Agent confidently lies about state: reject any success claim not accompanied by verification command plus output (§8) — this is the failure that looks like progress and rots underneath.
Partnership architecture is wrong: the agents are good but the result is bad — change the shape of the collaboration, not the prompts (§13). Fix the topology, not the discipline.
The workspace lies about state: everyone agrees on a fact that was never true — probe the load-bearing beliefs with commands (§6, §15); written context is an amplifier, not a witness.

Closing note: every agent failure has a human-side twin — skipped brainstorm, skipped retro, accepted-prose-as-evidence, note-instead-of-skill, claim-written-without-probe. Look for the shortcut you took upstream before you tune the prompt. The antecedent is almost always cheaper to fix than the symptom.

§12 The rescue protocol · full section

In the next hour: pick one small scoped task, run the full loop on it, stop using the agent for anything you can't verify in 5 minutes, and audit memory files with a bias toward deletion — re-calibrate the muscle before optimizing it.
In the next day: run the brainstorming skill before every task for a full day, write one feedback memory from last week's corrections, run an honest retro, and read §8 out loud — stabilize by reinstalling the disciplines that got skipped.
In the next week: promote two repeated corrections into real skills, add one hook that enforces a non-negotiable, reconcile the instructions file against memory, and ship one thing end-to-end with pasted evidence — move pain from prompts into the harness.

§13 Parallel agents & worktrees · full section

Fan out only when tasks are independent. — Group by file overlap, not issue priority. Interface-first design makes conflicts impossible by construction.
Designate merge points explicitly; update them last. — Shared touchpoints (config, main, integration tests) belong to a single post-parallel pass. Phase one is fan-out; phase two is the merge-point pass — which ends with reading the diff against the commit message, because the controller owns the history's truthfulness.
Worktrees are workspaces, not stashes — and they are not a coordination strategy. — Worktrees isolate filesystem, not git state. Use file-boundary parallelism inside a single worktree; never worktree-per-agent.
Subagents protect your context window; they don't hide work from you. — Dispatch when the output is small but the process is large. Accountability is yours; "reading" delegates to automated gates when the pipeline is trustworthy.
Review delegated work in two stages, with reviewers who don't trust the implementer. — A spec-compliance pass (asks the revert question) and a code-quality pass (hunts the wrong-someday class), neither fed the implementer's self-report. Nobody grades their own homework.
Isolate even the "read-only" agents. — "Report-only" is a job description, not a sandbox; audit fleets run package managers and dirty shared trees. Give the fleet its own copy of the world.

§14 Plan quality · full section

A plan with placeholders is a wish list. — If you can't fill in the step right now, you can't implement it right now. A known-failing test deferred to "future work" is a TODO, not TDD.
Each step is one action, two to five minutes long. — Small steps surface complexity before the agent buries it. The time budget is a proxy for small blame radius; when architecture provides that for free, steps can be larger.
The plan must cover the spec — and match the codebase. — Walk every spec section and name the task that implements it; then walk the plan's nouns (files, fields, functions) against the tree. Cross-system ordering is part of the spec.
Predict the failing output before you run it. — Write the expected red (exception, message, counts) into each TDD step; a match is a drift detector reporting all-clear, a mismatch is the cheapest warning you'll ever get.
Descope explicitly. Name what's out, and name why. — Every plan gets a "descoped" section with named reasons; every change gets a "things we deliberately didn't do" list, because restraint that isn't written down will be undone by the next helpful editor.

§15 Audits · full section

Schedule audits on purpose. — Whole defect categories generate no bug reports; the only way they're found is someone deciding to look. The audit is its own themed cycle with its own retro.
Claims must be downstream of code, not upstream. — Aspirational policy text is a liability for exactly as long as it's unimplemented; when the PRD and the code disagree, fix the one a user can verify.
The debt is in the seams. Diff what you wrote down against what's true. — A parallel report-only fleet (docs, security, debt, devops) enumerates the record-vs-reality gap in minutes; the rot itemizes faster than it accumulates if you measure it at all.
Probe the gate. A protection you've never tested is a protection you don't have. — Branch rules, backups, alarms, and rate limits look identical present or absent until the day they matter; rattle every gate on a schedule and attach the probe to the belief.

§16 The retro habit · full section

Write retros in voice, not in bullet points. — A dry changelog is forgotten in a week; a story with a nickname is rediscoverable in two years by instinct.
Retros are how the loop learns. — A retro is mandatory at the end of every release, even small ones; an honest paragraph beats a dishonest page. Paired with §8: verification catches the failure; retros convert it into a rule.
Write a retro at the end of every themed cycle, and right after every surprise. — Scheduled retros catch slow lessons; surprise retros catch fast ones. Don't retro on calendar intervals divorced from the work.
A retro has an anatomy. Use it as a scaffold, not a template. — Five parts: mission, execution narrative, numbers, what we learned, what's next. Scale each to what the cycle produced; the scaffold is what frees the voice.
A retro has three audiences: you next month, your team, and the agent next time. — End every retro with one extractable "what we'd do differently" sentence — the story is for humans, the explicit lesson is for everyone including the agent that hasn't read the story yet.
The retro unit is the arc, not the tag — and when a retro was wrong, write the reversal down. — Same-day patches consolidate into one story (the consolidation must actually happen), and a retro that praised a mistake gets corrected out loud: "we got it wrong, here's what we did instead, and here's the principle."