Patterns
The architectural decisions behind this workspace, stated as patterns: the problem each solves, the shape of the solution, why it beats the obvious alternative, and what it costs. The file conventions are Claude Code's; the patterns travel to any agent runtime.
Read this when you want the why. META_ARCHITECTURE.md is the what (the structural map), and ADOPTION.md is the how (where to start). Each pattern ends with a pointer to the sample files that implement it, so every claim here is inspectable. Under that pointer a generated line counts the published teardowns that found the pattern fully present, and links the learn module that practises it.
- 01Pure roles, composed with project factsRun security review across five projects and you end up with five near-identical 500-line prompts that drift apart the moment one is edited.
- 02Classify-then-act, not ask-then-waitAn autonomous background agent has two failure modes: it nags for input on everything, or it acts confidently on tasks it doesn't understand.
- 03Make silent failure loud (the dead-man's switch)A scheduled task that stops firing fails silently.
- 04Tier by mechanical impact, not by toneA system that auto-applies its own findings needs a line between "apply automatically" and "ask a human first."
- 05Memory points, it doesn't mirrorAgent memory that copies your source documents goes stale the moment a source changes, then quietly contradicts it.
- 06Credentials live in one place, never in filesA secret written to a file leaks: into git history, into a backup, into an agent's context window, into a screenshot.
- 07A cheap hook beats a careful agentAn agent that has misread the task can overwrite your .env, delete a record, or force-push.
- 08Audit the workspace like a fitness functionA workspace degrades while the ecosystem around it improves.
- 09Context is a budget, not a constantEverything auto-loaded into a session — instruction files, the memory index, skill descriptions, hook strings — costs tokens on every turn, in every session.
- 10A skill is editable weights — never adopt a self-edit without a gateInstruction files are the part of the system that most invites quiet self-improvement.
- 11A scaffold is a hypothesis — gate it behind a measurable signalThe tempting way to make an agent smarter is to keep adding to the layer around it: another skill, another always-loaded directive, another reasoning rule, another self-critique pass.
- 12Loop selection: not everything should be a loopGive an agent real capability and the tempting response is to automate everything: put a loop on every recurring task, "remove yourself as the bottleneck."
- 13Challenge half-formed ideas with a different lensEvery tool that critiques an agent's work assumes a finished artifact: a draft to red-team, a decision to rank, a result to verify.
- 14Delegation is a queue you fill, not work the agent findsA background project-manager agent that finds its own work has to guess what you meant by it.
- 15Price the lane before you migrate itToken consumption climbs even after efficiency work, because every saving gets reinvested in more agent work — Jevons, applied to your own subscription.
- 16A claim carries its provenance, or it is a guessAn agent writes a paragraph in which "the config sets X", "the docs recommend Y" and "this is probably Z" are typographically identical.
- 17One canonical copy, and pointers from everywhere elseThe same rule ends up written in three places: the user-global instructions, the workspace instructions, and a project file.
- 18Position is price — a token costs more the earlier you add itA team optimising context cost measures how large the context is and stops there.
How they compose
These are not independent. The credential law and the file-protection hook are the same instinct (keep damage out of durable surfaces) applied at two layers. The roles library and memory hygiene are the same instinct (one source of truth, referenced rather than copied) applied in two domains. Classify-then-act, tier-by-impact, the skill-as-weights gate, and loop-selection are the same instinct (route by consequence, not by confidence) applied to incoming tasks, to audit findings, to the agent's edits of its own instructions, and to the choice of what gets automated at all — the edit-your-own-instructions case is the riskiest, because the thing being changed is the controlling text itself, and loop-selection is the instinct turned upstream: it asks which work should reach an autonomous loop before any of the other gates get a say. And the context budget is the audit's instinct (notice drift before it bites) pointed at the one resource every other pattern spends. The scaffold-as-hypothesis gate is that same audit instinct again, pointed inward at the workspace's own additions: the self-edit gate (Pattern 10) certifies a change to the instructions, and the reasoning-regression suite certifies a change to the capability layer — both refuse to adopt on the strength of how good the change sounds. Pattern 13 turns the same gate on a critic for unfinished thinking, and adds the twist the offline checks miss: an always-on aid erases its own control group, so it holds out a slice of live firings the way Pattern 11 holds out a case set.
Pattern 15 is Pattern 9's budget instinct meeting Pattern 11's trial discipline at the model ladder: measure the lane, register the hypothesis, and let the same instrument that motivated the change adjudicate it. Pattern 14 is that same route-by-consequence family turned on the coordinator itself, and it is the one place where the answer came back negative. The classify-then-act loop of Pattern 2 ran here for months and was retired, because discovery left authorization ambiguous and the unattended runtime failed silently. What replaced it moves authorization to the human, and the question channel onto the board the human already reads.
Pattern 16 is the audit instinct compressed to a single sentence. Where Pattern 8 measures the workspace periodically and Pattern 11 gates an addition on evidence, Pattern 16 asks the same question of every load-bearing claim at the moment it is written: what is this standing on, and would the reader be able to tell if the answer were nothing. It pairs with Pattern 5 the way a citation pairs with a library: 5 keeps the source of truth singular and pointed-at, while 16 makes each individual assertion say which source it came from and how far it is from one. The two failure modes it addresses are the same failure at different distances: memory that quietly contradicts its source, and a sentence that quietly contradicts the file it claims to describe.
Pattern 17 completes a family that runs through 5, 9 and 16. Pattern 5 keeps memory pointing rather than mirroring; 17 does the same for the instruction surface, where the cost is paid on every session rather than every recall. Pattern 9 measures what that surface costs; 17 removes the part of the cost that buys nothing, because a duplicated rule spends context twice and can contradict itself. And 16 is the same discipline at sentence scale: cite where a claim comes from rather than restating it from memory. The through-line is one idea at four sizes: a fact should exist once, be referenced from everywhere it applies, and carry a visible route back to its source.
Pattern 18 prices what Pattern 9 budgets. Where 9 says context is finite and spent deliberately, 18 says the same token costs differently by when it is spent, because a stateless transcript is re-read on every step, so its levers move a read's position rather than deleting it. It closes a loop with 1 and 8: reading in a subagent — the isolation the roles library uses to keep a caller's context clean — is one of its levers, and the audit instinct of Pattern 8 supplies the meter without which position cost stays invisible.
Adopt them when you feel the friction each one removes. Not before.