The Standard · Adopters · GitHub ↗

Agent-Instruction House Standard

How to structure agent-instruction files across a set of repos: one source of truth, an in-repo fix log, written anti-drift rules, and a self-healing session hook.

Apply this to any repo an AI agent (Claude Code, Codex, Cursor, Gemini) works in.

1. One source of truth

A repo has one canonical instruction file: AGENTS.md. It holds everything an agent (or human) needs to work on the repo: architecture pointer, build/test commands, conventions, gotchas, ship rules.

CLAUDE.md is one line, an include:

@AGENTS.md

Why: AGENTS.md is the cross-harness convention (Codex, Cursor, Gemini, Agent Skills all read it). Claude Code reads CLAUDE.md, so the include points it at the same canonical file. Never maintain the same content in two files. That is the failure mode this prevents (a large monolithic instruction file drifted because there was no single source).

Accepted alternative: a symlink

A CLAUDE.md symlink → AGENTS.md is equally compliant and in some ways stronger: any tool that opens CLAUDE.md gets the full canonical content with zero drift, no @import support required (a CLAUDE.md -> AGENTS.md symlink, git mode 120000). Leave such repos as-is.

Tradeoff: symlinks don’t survive some Windows checkouts / zip exports, where the @AGENTS.md text include is more portable. Pick per repo; both satisfy one-source-of-truth. Do not convert a working symlink to an include just for uniformity; it is a lateral move.

If a repo genuinely needs Claude-only nuance, put the @AGENTS.md line first, then the small Claude-specific addendum below it. This should be rare.

Accepted exception: a deliberate two-file split

A repo may keep CLAUDE.md and AGENTS.md as complementary files (not duplicates) when the content genuinely divides by audience, e.g. AGENTS.md = install + operating protocol + routing (cross-harness onboarding), CLAUDE.md = architecture reference / key files / test layout. This is compliant as long as the two never hold the same content and a ## Keep in sync rule covers any overlap. The anti-pattern is duplication, not two files.

Scoped instruction files (subdirectories)

The root AGENTS.md doesn’t have to carry everything. Context that belongs to one part of the repo can live there, so it loads only when an agent actually works there:

• A subdirectory AGENTS.md for a folder with its own live conventions, constraints, or locked decisions (a package in a monorepo, a deploy dir). Harnesses that read nested instruction files load it on top of the root; open it with “Apply the root AGENTS.md first, then this” so precedence is written down. The one-source rule applies at every level — if the harness wants a folder CLAUDE.md too, it’s a symlink or include, never a copy.
• Path-scoped rules where the harness supports them (a rules file with a paths: glob), so a guardrail loads only when matching files are touched.

Two disciplines keep scoped files from becoming the drift problem they solve: a folder file holds only what the root doesn’t (zero duplication), and it pins decisions and constraints, not structure — file trees and stack lists are derivable from ls and rot fast (§3). A folder of static reference files needs no instruction file at all.

For the wider doc set an AGENTS.md routes to (runbooks, design docs, system notes), make discovery mechanical: open every doc with a dense summary in its first few lines, so an agent can head across the folder and pick the right file instead of loading them all. Note the convention in AGENTS.md — both so agents rely on it when searching and so they keep the summary true when they edit the doc.

AGENTS.md skeleton

# <Repo>: Agent Guide

One-sentence description of what this repo is.

## Architecture
Where the code lives, the 3 to 5 things you must understand before editing.

## Commands
Build / dev / test commands. The ones you actually run.

## Conventions
House style, naming, patterns to follow, orphaned code NOT to recreate.

## Gotchas
The traps. (See docs/solutions/ for the full fix log.)

## Before shipping
Tests, lint, build, whatever the ship gate is.

## Keep in sync
<see section 3>

Keep AGENTS.md scannable. Anything that is a specific past incident goes in docs/solutions/, not inline. That keeps AGENTS.md from growing without bound.

Write hard rules with their exceptions attached: “never commit secrets, except .env.example” survives contact with edge cases; a bare NEVER gets ignored the first time an edge case makes it wrong.

What good context covers: the four S’s

Instruction-file content comes in four layers — Syntax, Service, System, Strategy. Each builds on the one below; skipping a layer produces slop regardless of model quality:

• Syntax — coding standards, linters, import conventions, what test files look like. Models know generic syntax; they need your conventions, or every session adds patterns nobody chose.
• Service — how this repo is organized, deployed, and what domain it owns; how other services interact with it. Without Service context an agent builds in isolation, duplicating what already exists.
• System — cross-repo architecture and the tools the org already uses. Agents without System context build by default; with it, they integrate by default.
• Strategy — the business context that breaks ties when there is no technical right answer (runway, roadmap, what’s strategic vs. routine).

A minimal AGENTS.md covers Syntax and Service. System often lives in a shared org-level file the repo points to. Strategy is frequently private config — but each layer should exist in writing somewhere an agent can read, because this hierarchy is exactly the implicit knowledge senior engineers carry, made explicit and machine-readable.

One name per concept (domain language)

Content drift has a twin: naming drift — one concept accruing synonyms (“issue”, “ticket”, “task item”) until an agent builds around the wrong one. Where a repo’s domain has terms worth defending, give AGENTS.md (or a file it points to) a short domain-language block:

• Canonical term — one name per concept, one-line definition.
• Avoid-list — the synonyms not to use, named explicitly, so the rule is checkable (“issue tracker; avoid: backlog manager, backlog backend”).
• Resolved ambiguities — when a word turns out to mean two things, record the resolution, not just the confusion (§2’s compile move, applied to vocabulary).

Keep it to terms that actually get confused. A glossary of the obvious is an inventory, and inventories rot (§3).

Name the current layer when the codebase has strata

Naming drift has a structural twin. A repo maintained by a succession of leads accumulates strata: each lead built in the idiom they understood, and because nobody had enough context to migrate the previous one, the old idiom survives underneath. The result is a codebase where two files solve the same problem in two shapes, both load-bearing, neither wrong. This is most common in small teams on complex domains — permissions, billing, identity — where the work is permanently valuable but rarely the quarter’s priority, so nothing ever forces the layers to compact.

Strata break the instruction “write code consistent with the surrounding code”, because surrounding is ambiguous by construction. An agent that copies the nearest pattern picks a layer at random, and a harness that ships all day picks a new one every session — which is how the repo gains a stratum per contributor instead of per lead.

Where a repo has strata, AGENTS.md (or a file it points to) says so plainly:

• The current layer — the idiom new code is written in, with one pointer to a file that exemplifies it. “Copy this file’s shape” beats a paragraph describing it.
• Frozen layers — older idioms that still run and must keep running. Name them, name where they live, and say the rule: extend in place if you must touch them, never seed new code from them.
• Layers being migrated — the ones with a live destination, and what the destination is. A migration nobody is running is a frozen layer; label it as one rather than aspirationally.

Left unwritten, this knowledge lives only with whoever has been there longest, and it decays exactly the way §11 describes — except here the cost isn’t a lost runbook, it’s a repo that gains a layer every time someone new starts shipping.

Finding the strata when nobody can name them

The block above assumes someone can enumerate the layers. Often nobody can — the person who could is exactly the person who left, which is the condition that produced the strata in the first place. So the layers have to be recovered from evidence, and the repo carries plenty: strata are visible as clusters of files that solve the same problem in different shapes, and those clusters correlate with periods of history.

The recovery is a §11 discovery pass narrowed to one question — what idioms are live here? — and it is read-only:

• Start from divergence, not from history. Pick a handful of concerns the repo handles repeatedly (how a request is validated, how errors surface, how a module reaches the database, how tests are structured) and collect how each is done across the tree. Concerns with exactly one shape are not strata and cost nothing further. Concerns with two or three competing shapes are the candidates; everything below is about those.
• Date the shapes, then read the seam. For each competing shape, find when its files were introduced and when the shape last got new files rather than edits. A shape that stopped acquiring new files at some point and only receives maintenance edits since is a frozen layer. A shape still gaining new files is live. Two shapes both gaining new files is the finding that matters most: the repo is actively growing in two directions, and nobody decided which one wins.
• Take conversions as the migration signal. Where a file moved from one shape to another, the direction of that change is the intended destination, and the count of remaining unconverted files is how far it got. A conversion that happened a few times long ago and stopped is a stalled migration — record it as a frozen layer with a note that a destination was once attempted, not as a migration in flight.
• Ask about intent; never infer it. Evidence establishes what the layers are and which are still growing. It cannot establish which one is meant to win — that is a decision, not a fact, and inferring it from file counts or recency is how the wrong layer gets enshrined as canonical. Present the candidates and let a human pick. Where nobody will decide, say so in AGENTS.md explicitly (“two live shapes, no ruling”) — an honest ambiguity an agent can escalate on beats a confident wrong answer it will build on.
• Verify each layer before writing it down. Every claim about a layer names real files that a reader can open, and the exemplar pointer for the current layer must be a file that actually exhibits the idiom end to end. This is §11’s ground-truth rule: a wrong strata map is worse than none, because it is trusted, and it will be copied.

The output is the block above, plus a fix-log entry (§2) recording how the strata arose where that is knowable — the entry is the why, and the AGENTS.md block is the compiled rule. Re-run the pass when a migration finishes or a new shape starts appearing, not on a schedule; strata change on the timescale of leads, not sprints.

Scoring compliance: a maturity level, not a point total

Compliance is checkable (adopt --check), and the score is deliberately shaped as a maturity level, not a raw count of passing checks. A repo with a rich AGENTS.md, a fix log, and a sync block but no secret hygiene is not “almost compliant” — it is one clear rung below a repo that also keeps secrets out of history, because the missing piece is a floor, not one point among many. Levels gate on the shape of the harness:

• L0 unharnessed — no canonical AGENTS.md; agents relearn the repo every session.
• L1 documented — a substantive AGENTS.md exists.
• L2 structured — L1 plus the single-source include (§1), a fix log (§2), and a written sync block (§3).
• L3 safe — L2 plus version control and secret hygiene (a .gitignore that keeps .env out of history). The secret floor is what separates the top level.

A point total lets 80% of beautiful docs mask a dangerous gap; a level makes the gap the headline. The gate (--check exit 0) is reaching the top level, not collecting the most points.

The check IDs are a contract. Each check has a stable identifier (STD-01 … STD-06); an ID never changes meaning, and the --json output only gains fields, never renames them — so a CI pipeline gating on the score never silently misreads a new version.

What the check does not measure. A deterministic scan can confirm a file exists, parses, and matches a pattern — never that its contents are true. A stale rule scores like a fresh one; an AGENTS.md full of wrong commands passes the presence check; a fix log of outdated entries still counts as a fix log. A high score means the infrastructure for reliable agent work is in place — it is necessary, not sufficient, and that is the honest ceiling of any automated check. Keeping the contents true is the §2 “compile, don’t retrieve” discipline, which no scanner can do for you.

2. docs/solutions/: the fix log

A committed, queryable record of past bugs, fixes, and hard-won patterns. The in-repo, shared version of per-machine agent memory: every agent and human that opens the repo sees it.

One fix per file. Filename: docs/solutions/<area>-<short-slug>.md.

Required frontmatter:

---
module: <which part of the codebase, e.g. "booking", "auth", "build">
tags: [<keywords for search>]
problem_type: bug | gotcha | pattern | workflow
date: YYYY-MM-DD
---

## Problem
What went wrong / what's confusing.

## Cause
Why it happens (the root cause, not the symptom).

## Fix
What to do. Concrete, copy-pasteable where possible.

When a repo already grows an inline “Corrections Log” or “Things Claude Has Learned” section, migrate those entries into docs/solutions/ one file each and leave a one-line pointer in AGENTS.md.

The slop list

Not every entry is a bug. Recurring slop — agent output that compiles, passes the cheap checks, and looks plausible but is subtly wrong — gets logged the same way (problem_type: pattern), one category per file. The categories that show up everywhere:

1. Plausible but wrong — right types, wrong answer at the edge cases.
2. Over-engineered — three abstractions for a ten-line problem.
3. Convention-blind — generic good code that ignores this repo’s patterns.
4. Hallucinated APIs — methods that don’t exist, or were renamed two versions ago, inside otherwise-legitimate code.
5. Defensive slop — error handling that hides failures instead of preventing them; null checks for values that can’t be null.
6. Cargo-cult patterns — retries, caches, async wrappers where they don’t fit.

Capture a category once and it becomes context that prevents it forever. The slop list is the institutional memory of how agents fail on this codebase — and the review lens for §10’s contract check.

Compile, don’t retrieve

A fix log only pays off if entries get read into AGENTS.md and each other, not just accumulated as files an agent might grep. Retrieval re-derives an answer from raw entries on every session and compounds nothing; compilation folds an entry’s implication into the standing instructions once, so every future session starts from the compiled result instead of re-discovering it. Concretely: when a fix-log entry reveals a rule an agent should follow by default (not just a past incident to know about), promote that rule into AGENTS.md’s Gotchas or Conventions section — don’t leave it as something only found by searching docs/solutions/. The entry stays as the record of why; the rule it produced belongs in the file agents read every session.

Prose is the floor of compilation, not the ceiling. When a logged pattern is mechanically checkable, promote it past AGENTS.md into a linter or pre-commit hook — one that fixes the problem (--fix), or at minimum blocks it, never one that only flags it. A rule enforced by a hook cannot be skimmed past, and it frees the instruction file’s budget for rules that need judgment. The same goes for workflows: a multi-step incantation agents keep re-deriving (how to kick off a review, how to run one targeted test) gets compiled into a small script in the repo’s bin/, pointed to from AGENTS.md.

Add entries one at a time. Write a fix-log entry right after the incident, while the cause is fresh. The highest-signal trigger is a human correcting the agent on something the instructions should have prevented: log it and promote the rule in the same session, not in a later documentation pass. Cross-link each entry to related entries and to the AGENTS.md rule it feeds (§3’s “Keep in sync” is the place to declare that link if it’s easy to miss). Do not batch-import a backlog of old incidents in one pass — a bulk import produces isolated files with no cross-links and no promoted rules, which is a pile, not a compiled fix log.

Gate the commit, don’t trust the habit

Promoting a rule into a hook (above) only bites if the hook actually runs before the commit lands. The reliable shape is a review marker: a review step (a /code-review, a reviewer agent, a lint pass) writes a marker file on pass, and a PreToolUse hook blocks git commit until the marker exists. The difference from a convention is that the agent cannot skip it — an unreviewed commit is refused, not merely frowned upon.

Make the marker session-scoped (keyed by repo + agent session id), so parallel agent sessions in the same checkout don’t clear each other’s gate, and so the requirement resets per session rather than leaking across unrelated work. Scope the strictness to the diff: require only a light review for most changes, and a deeper one (a data-migration reviewer, a security pass) only when the staged paths match the sensitive set — a blanket heavy gate on every commit gets disabled within a week. Keep a single documented bypass for genuine exceptions (an env flag, --no-verify); a gate with no escape hatch gets ripped out instead of bypassed. templates/hooks/scripts/review-gate.sh is a copy-in implementation.

Ratchet debt down; don’t gate on an absolute

Some rules can’t be enforced as a hard line without failing on day one. “No source file over 500 lines” is unachievable in a repo that already has fifty such files, so the rule never ships. Ratchet instead: snapshot the current count of the thing you want less of (files over N lines, TODOs, suppressions, any-casts) into a committed baseline, and fail CI only when a metric goes up. Existing debt is grandfathered; new debt is blocked; lowering the baseline is a deliberate commit, so the number only moves in the good direction — never silently. This turns an aspiration a repo can’t meet today into a gate it can adopt today and tighten over time. templates/hooks/scripts/ratchet.sh is a language-agnostic implementation; edit its metric list for the repo.

Record the decision before the change, not only the fix after

The fix log (above) captures what broke and why — after the fact. Its forward-looking twin is a short decision record written before a significant change: what’s being decided, why, and the alternatives rejected. Keep it lightweight — a few paragraphs in docs/adr/NNNN-slug.md — and, exactly like the fix log, bound it with an explicit skip-list so it doesn’t become ceremony. Require it for: new features, architectural changes, new external integrations, changes spanning many modules, or a new cross-cutting pattern. Do not require it for: bug fixes, single-file refactors, doc-only changes, or test additions. The rule earns its keep precisely because it says loudly when it does not apply — an unbounded “write an ADR for everything” is the drift, not the discipline.

3. Anti-drift sync contracts

When two files must agree, say so in writing. Drop a ## Keep in sync block into AGENTS.md:

## Keep in sync
- Add an env var → document it in `CONFIGURATION.md` (or `.env.example`).
- Add a CLI flag / route → update the relevant section here and the README example.
- Change <file A> → update <file B> (and the test that pins them, if any).

List only the pairs that actually drift in this repo. The rule exists because prose inventories rot: a hand-kept “Inventory (legacy)” file-list drifts from the codebase until it is removed. Prefer “read the directory” over a hand-kept list; where a list is unavoidable, pin it with a sync rule or a test.

4. Self-healing SessionStart hook

Only for repos with config that fails silently (an .env with secrets, a required output dir). A SessionStart hook fixes the common problems before they bite instead of after.

hooks/hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"${CLAUDE_PLUGIN_ROOT:-.}/hooks/scripts/check-config.sh\""
          }
        ]
      }
    ]
  }
}

The script (template in templates/hooks/scripts/check-config.sh) does two generically-useful things, both cross-platform-guarded:

• Ensure required dirs exist (mkdir -p the output/cache dir).
• Auto-chmod 600 a loose-permission .env and warn, so a world-readable secrets file gets locked down at session start.

Adapt the env-file path and dir per repo. Skip the hook entirely where there’s no silent-failure config to heal. Do not add ceremony for its own sake.

5. Commit authorship

Commits in any repo under this standard must be authored by one of a small, explicit set of sanctioned identities. No stray author (a work email, a machine default, a bot) should ever land in history. Pick your allowed identities and list them, e.g.:

• you <you@example.com>
• you-alt <you-alt@example.com>

Before committing, verify the local identity resolves to one of them:

git config user.name && git config user.email

If it doesn’t, set it per-repo (git config user.email you@example.com). Do not commit under a different identity and fix it later. An agent committing on your behalf uses whichever sanctioned identity the repo is already configured for; if unset, fall back to a documented default.

Co-author trailers (Co-Authored-By:) for the agent are fine and don’t count as the commit author.

Agent-authorship disclosure

Separate from whose identity a commit carries is whether the work was agent-generated at all — and that must never be invisible. Disclosure is continuous, not a one-time note:

• Every agent-authored commit carries an Assisted-by: (or Co-Authored-By:) trailer naming the agent and whether it acted autonomously or under direct human supervision. A human git identity on the commit does not exempt it — the trailer states agent involvement regardless of whose name is on the author line.
• Agents disclose their own identity in PR and issue comments they post, and restate it each round — a disclosure in the PR body does not cover commits or comments added later in review.
• No fake-review theater. Do not reply “done” or push a fix within seconds of a review comment without disclosing that the response was agent-generated. An inhumanly fast turnaround is itself a signal of automation, not something to paper over with “reviewed and tested by me.”

Multi-account hosting. If your repos live under more than one GitHub (or GitLab) account, remember the hosting account is separate from commit identity, and CLIs like gh keep only one account active at a time. Working in a repo owned by a non-default account without switching first (gh auth switch --user <account>) makes reads/pushes hit the wrong account, which returns a bare 404 / repository not found, a silent “wrong active account,” not a missing repo. Note the required account at the top of that repo’s AGENTS.md and switch before any gh/push operation.

6. Commit + push flow: default to the main branch

Default: commit straight to the default branch (main/master) and push it. For solo / small-team repos, a feature branch + PR for routine work just adds ceremony and leaves stale branches behind (see the anti-pattern below). Complete the loop: commit and git push origin <default>, so the work is actually on the remote, not parked on a local branch waiting for a second ask.

Branch + PR only when the change is risky. Open a branch instead of committing to main when the change is any of:

• a schema/data migration or anything that can corrupt or lose data,
• a large or wide-reaching refactor touching many files or core modules,
• hard to revert (irreversible, or a one-way door), or
• likely to break the build / leave main undeployable if it lands half-done.

For those, branch off the default, push the branch, and open a PR so main stays green. Everything else goes straight to main. The user can always override in either direction (“just commit it”, “put it on a branch”); when they do, that wins for that change.

Anti-pattern: branch-per-trivial-change

Do not create a feature/add-x branch for a routine, low-risk edit (docs, a diagram, a copy tweak, a one-line fix) and then merge it yourself moments later. The branch adds no review value on a solo repo, and if it’s fast-forwarded or rebased into main the leftover branch lingers on the remote showing a misleading “Compare & pull request” banner. Commit low-risk work directly to main; reserve branches for the risky cases above. If a redundant branch does get created, delete it (remote + local) once its content is on main.

7. Deploy-account hygiene (multi-account setups)

If you deploy across more than one account on a host (Vercel, Netlify, Fly, Cloudflare, etc.), the CLI usually keeps one account logged in at a time, and the account that owns a deployment is independent of the git remote owner. Deploying under the wrong account fails (“Could not retrieve Project Settings”) or, worse, deploys to the wrong project.

Rules for any agent about to deploy:

1. Never run a bare deploy command. Run an account-check first that compares the current CLI login against the account this repo requires, and only then deploy. A tiny deploy-check wrapper that reads the required account from the repo’s AGENTS.md and diffs it against the active login pays for itself.
2. Never infer the account from the git remote. Read the > **Deploy:** line in AGENTS.md, or cross-check the linked project’s org id against a maintained account→repo map.
3. The deploy link is not always at the repo root. Some projects link the deploy config from a subdirectory. If the root has none, find the real one (find . -path '*/.vercel/project.json', adjust per host) and run deploy commands from that directory, otherwise the CLI silently uses whatever account is logged in.
4. Prefer stored tokens over interactive login. A per-account token (e.g. from the OS keychain / a secrets manager) lets deploys run headless with --token and avoids flipping the global CLI session to the wrong account. The fix for a wrong-account error is the correct account’s token, not a bare login that mutates global state.

If the account-check reports a mismatch, stop and switch accounts. Do not guess your way through auth.

Keep the concrete account↔︎repo map (emails, org ids, domains) in a private file or a secrets manager, not in this public standard. This section is the policy; your account list is config.

8. Model routing (multi-model setups)

If more than one model or agent CLI is available, keep a small ranking table of the models you use, scored on three axes: cost, intelligence (how hard a problem it can be handed unsupervised), and taste (UI/UX, code quality, API design, copy). The table is config — keep it private and current. This section is the policy for using it.

• Defaults, not limits. The agent has standing permission to escalate: if a cheaper model’s output doesn’t meet the bar, rerun the work with a smarter model without asking. Judge the output, not the price tag — escalating costs less than shipping mediocre work.
• Tie-break order. For anything that ships: intelligence > taste > cost. Cost is a tie-breaker only.
• Route by task. Bulk/mechanical work (clear-spec implementation, migrations, data analysis) → the cheapest capable model. Anything user-facing (UI, copy, API design) → a high-taste model. Reviews of plans and implementations → the strongest models available, ideally including a second model from a different vendor as an independent perspective.
• Dial reasoning effort, don’t drop to a weaker model. A strong model at a lower reasoning setting is often both smarter and cheaper than a smaller model at full effort — a model that isn’t capable enough just burns tokens failing. Prefer turning the effort dial down on a capable model over routing to a weaker one. And avoid “max fan-out” modes that spawn sub-agents recursively at top effort: the multiplier, not the per-call price, is what empties a budget.
• Cross-vendor via CLI wrapper. When a harness’s subagent/model parameter only takes its own vendor’s models, reach the other vendor through its CLI: spawn a thin wrapper agent whose only job is to write a self-contained prompt, run the other CLI non-interactively (read-only sandbox for reviews), and return just the result. Prefer token-efficient CLIs over MCP servers for this — measure a tool’s agent ergonomics before adopting it.
• The orchestrator is the scarcest resource. In an orchestrator/worker setup, the top model plans, decomposes, and synthesizes — it does not burn its own budget or context on execution. Pin role subagents with one-line charters: a strong-reasoning worker for architecture and hard debugging (“think thoroughly, return a concise conclusion the orchestrator can act on”) and a cheap fast worker for mechanical edits (“execute efficiently”). Protect the orchestrator’s own provider more conservatively than the workers’: a worker failure reroutes; an orchestrator budget failure strands the whole session.
• A second vendor is a peer, not a rubber stamp. Treat a strong different-vendor agent as a peer senior engineer with a different perspective — delegate whole problems to it, not just review passes.
• Watch quota, not just cost. On subscription plans the binding constraint isn’t per-token price, it’s the remaining pool in each vendor’s quota — a cheap-per-token model is useless when its subscription is dry. Route against live quota %, not a static price list: stack subscriptions across vendors so each has its own pool, keep the premium model’s remaining budget for the high-taste work nothing else does as well, and pace usage against each plan’s reset window (aggressive where resets are generous, rationed where they aren’t). Because routing is config (the private ranking table above), swapping the default when a pool runs out is a one-line change, not a code edit.
• High-stakes decisions: consult blind, then synthesize. Task two strong models (ideally different vendors) on the same problem in parallel without showing either the other’s answer, then synthesize the best of both. Blind parallel consultation avoids anchoring; a sequential second opinion inherits the first answer’s frame.

A worked, harness-specific setup for all of this is in examples/orchestration-workflow.md.

9. Delegation and long-running work

Rules for work that spans subagents, background jobs, or hours. The theme: files are the state, context is scarce, and the user is not a polling target.

• Files over context. A delegated worker whose output may be long writes its findings to a file and returns a TL;DR plus the path. Returning a long report inline defeats the delegation — the bytes land back in the parent’s context anyway. Same for logs, diffs, and review transcripts: store them, summarize, link.
• Verification first. Every delegated prompt starts by checking repo state and its own assumptions before editing. A goal-shaped task loops plan → act → test → self-review until green, and returns a converged result, never a draft.
• Reviews gate; absence is not approval. Review risky work before it lands — and an adversarial pass that challenges the design (assumptions, tradeoffs, failure modes), not just the code, is worth as much as a plain one. A missing or stalled review is inconclusive, not clean. Save review verdicts durably (never only in /tmp), and turn reviewer misses into regression tests. When a review catches a new class of bug, sweep the rest of the codebase for more instances of that class: one catch, one class, one sweep.
• Continue, don’t confirm. Once scope is approved, keep working until the queue drains or a real blocker appears — never poll the user with “shall I continue?” prompts. Stop only for permissions, destructive or irreversible actions without a plan default, or genuine product choices. Record non-blocking uncertainty in a file and proceed with the plan default. The queue itself must be readable by any agent — a committed TODOS.md or a tracker reachable by CLI, never a list that lives only in chat memory.
• Quiet is not dead. Don’t declare a long-running job failed from one stale signal (a silent log, a missing PID). Reconcile several — process identity, status file, output mtime, dirty tree — before discarding work. After a context reset, resume from state files, not from chat memory.
• Long work leaves a worksheet. A session that spans hours or could die midway keeps a running trace — goal, plan, what’s done, what’s next, open questions — as a file committed with the work, not scratch notes in /tmp. The bar is the handoff test: a fresh agent handed only the worksheet could finish the job. Committing it alongside the code ties the trace to the history, so “why is it like this?” has an answer months later. But the worksheet is the fresh-start path, and any rewritten summary is lossy — when the same task merely changes harness (a usage limit hit, a second opinion from another vendor), transfer the session transcript itself instead; converters exist, and a raw transcript preserves far more of the session’s concrete facts than a hand-written handoff.
• Commit hygiene under parallelism. With parallel workers in flight, the coordinator never runs a bare git commit -a — commit with explicit pathspecs so one commit can’t bundle another worker’s work-in-progress. One commit per completed chunk.
• Isolation under parallelism. Every concurrent agent gets its own git worktree and its own branch — never two agents in one working directory. And cap concurrency at what the operator can actually review, not what the machine can run: worktrees solve collisions and checkers solve verification, but nothing solves operator overload; review bandwidth is the ceiling.
• Autonomy is bounded by verification, not generation. Hand a loop only as much autonomy as you can cheaply and reliably verify — no further. Generation is wide and near-free; verification is the narrow neck, and it is where the one resource that doesn’t scale (human attention) gets spent. So making the agent generate faster doesn’t relieve the bottleneck, it deepens the pile in front of it — the problem is never too many changes, it’s too many unverified ones. The practical dial: a loop earns more autonomy only when a cheap, unfakeable check (a type gate, a property test, a rubric-driven review) can green-light its output without a person. Where no such check exists, the loop stays small and a human stays in it — which is the same “review bandwidth is the ceiling” limit, read as a budget you spend deliberately rather than a wall you hit by accident.
• An unattended shift runs inside written bounds. Before a loop runs with nobody watching, it gets a declared blast radius, a wall-clock or token runtime limit, a consecutive-failure threshold, and a circuit breaker — and it ends at a deterministic boundary (tests green, queue drained, budget hit), never because the model says it’s finished. Autonomy rarely explodes; it quietly drifts, and the usual causes are a stale verifier, a missing stop condition, and an operator who stopped reviewing. End the shift with the full ship gate — tests, lint, everything — run once more over all the loop touched, so the human returns to a verified tree, not merely a quiet one.
• An uncalibrated checker is worse than none. When the verifier is itself a model — a rubric-driven reviewer, an LLM judging output quality — it starts as an unvalidated instrument, and shipping behind one buys false confidence rather than safety. Calibrate before trusting it at scale: assemble a small labeled set (50–100 cases is enough) that includes the failures, not just the passes — a checker that has only ever seen good work can’t demonstrate discernment — then run the checker against it, measure how often it agrees with the human label, and analyze every disagreement. Sharpen the rubric until agreement is high, and re-run the loop; a checker that can’t reach it has an ambiguous rubric, which is the real bug. If a rule can’t be applied consistently by two humans, a model won’t apply it consistently either — and when the humans themselves disagree on a label, stop and settle that before automating anything on top of it. Keep the labeled set in the repo so recalibration is a re-run, not a re-derivation.
• One checker, one dimension. A single reviewer prompt scoring correctness and security and style is undebuggable — when it fails you can’t tell which criterion misfired, and sharpening one dimension silently drags the others. Split into a few narrow checkers that each target one dimension and score it plainly (pass/fail unless a gradient genuinely carries signal). A handful of well-calibrated checkers beats a couple dozen noisy ones, so add a dimension only when a real failure demands it. This is §1’s rule about monolithic instruction files, applied to verification.
• Verifiers decay; audit them. Verification debt is real: outputs still compile while quality slides, until weak work passes review. Recalibrate the checker continuously — feed reviewer misses back as regression tests (above), re-run the calibration set when failure modes shift (above), refresh review criteria as the codebase changes, and spot-check what the verifier passes. Audit the test suite the same way: periodically hunt false-confidence tests — tests that pass without exercising what they claim to (asserting against the mock, an over-broad try/catch, testing the fixture) — and fix them; they are the stalest verifier of all.
• Green tests are not comprehension; watch the debt nobody can see. A loop can ship correct-looking, passing code indefinitely while no human ever reads it — and the bill comes due the first time a subtle bug surfaces in a module nobody understands, where tracing it takes weeks instead of hours because there’s no mental model to start from. This is comprehension debt, and it’s distinct from the verification debt above: the checks genuinely pass, the code genuinely works, yet the team has lost the ability to reason about its own system. Tests-green is a floor, not understanding. Bound the debt deliberately: keep the loops that run fully unread confined to cheap, reversible, low-blast-radius work (a nightly lint-fixer, a small dependency bump), and require a human to actually read and hold the design for anything expensive to undo — auth, billing, data model, cross-cutting architecture. The point isn’t to read every diff; it’s to never let the code a human must be able to debug drift into code no human has seen.
• Blocked workers escalate, never bypass. A worker that hits a sandbox, permission, or write block reports it and stops. Workarounds — alternate APIs, out-of-path writes, git plumbing — are the coordinator’s call, made in the open.

10. Guardrails and recovery

Rules for keeping autonomous work safe when things go wrong — and for deciding, in writing, when a human takes over.

• Failures get a ladder, never silence. Detect errors actively: validate tool output, check exit codes and API errors, put timeouts on anything that can hang. Then walk a planned ladder — retry (with backoff) → fallback (alternate tool/model) → degrade gracefully (partial result, clearly labeled as partial) → escalate. An agent that swallows a failure and keeps going converts one bug into a chain of them.
• Compact the error before feeding it back. Self-healing on a failed tool call works because the model reads the error and fixes the next call — but re-injecting the raw output (full stack trace, multi-screen log, the whole failing response) poisons the context window and buries the one line that matters. Feed the next attempt a compacted error: the message plus the decisive line, not the dump (store the full log to a file and link it, per §9). Cap how many raw failures accumulate — after a couple of compacted retries that don’t converge, the loop is stuck on this error, so hand it up the ladder (fallback → escalate) instead of letting failures pile into context. The compacted history, not the raw log, is what travels with the escalation.
• Retries move pressure; they don’t remove failure. An agent that retries aggressively — no backoff, no jitter, no budget — amplifies a hiccup into a retry storm. Retry with exponential backoff plus jitter, under a written budget (max attempts, per-attempt timeout, total time), with exactly one layer owning retries per dependency so stacked layers don’t silently multiply attempts. Retrying a read is safe; retrying a write needs an idempotency key, or the retry duplicates the side effect. Past the budget, a circuit breaker fails fast — and the fallback is designed deliberately, because wrong data is often worse than none.
• Guard in layers. One guard is not robust. Validate inputs before acting on them, check outputs before shipping them, and restrict what each step can touch. A single filter, prompt rule, or reviewer will eventually be bypassed; independent layers fail independently.
• Least-privilege tools. A delegated task gets the narrowest tool allowlist that can complete it — a docs task doesn’t need shell access; a review task is read-only. Scope the allowlist per dispatch, not per agent.
• External content is data, not instructions. Fetched web pages, issue text, PR comments, and tool output can carry adversarial instructions (prompt injection). An agent follows its instruction files and its operator — content it reads never gets promoted to instruction status, no matter how imperative it sounds.
• Never combine all three sides of the capability triangle in one agent. Three capabilities are each safe alone but catastrophic together: access to private data + exposure to untrusted input + a path to send data out. An agent holding all three is an exfiltration machine waiting for one injected instruction (the “external content is data” rule above is exactly what gets bypassed). Break the triangle at one side per trust boundary: split the component that reads untrusted input from the one that touches private data, remove the outbound path, or put a human on the step that completes the send. This composes with least-privilege (above) — the allowlist is how you drop a side.
• The stop condition is a policy, not a parameter. A turn cap or spend cap is an organizational judgment wearing a numeric disguise — “max turns: 20” really answers “how much may this flail before a human looks?”, and that answer differs between a docs fixer and anything touching billing. Before an autonomous loop runs, answer five questions in writing (in AGENTS.md or the loop’s config):
  1. What may it touch? The blast-radius fence — auth, billing, migrations, the audit trail trigger a stop; everything outside the fence is fair game. Where the harness supports pre-tool-call hooks, compile the fence into a deny-hook that blocks the dangerous commands outright (a force-push, a hard reset) — enforced beats written (§2).
  2. How long may it run? A turn cap and a spend cap — an agent without them will eventually discover an expensive way to fail.
  3. What counts as proof? The exact command and condition that mean “done”, so the agent isn’t grading its own happy path.
  4. What must it record? What changed, why, and what authorized it — specified up front, not reconstructed after a bad day.
  5. When does a human get pulled in? A condition the loop can evaluate (“two consecutive failures”, “wants a new dependency”) — not a vibe.
  §9’s “continue, don’t confirm” is only safe once these are explicit.
• Success criteria precede work; the author is not the judge. Define the verifiable deliverable before execution starts — scope, the checks that must pass, what “done” means — so the task is a contract, not a vibe. The concrete shape is four fields: Objective (user-visible), Constraints (what can’t change), Validation method (a command + condition, not “looks right”), and Escalation protocol (when to stop and ask) — a copy-in template is in templates/docs/EXAMPLE-acceptance-criteria.md. And never let the model that produced the work be the sole judge of whether it met the bar: a producer grading itself struggles to notice it went in the wrong direction, and self-reported completion is a claim, not a result — “done” is what the compiler, the tests, and an independent checker say. And “the tests” means the change exercised the way a user actually hits it — run the app, drive the flow end to end — not only the unit tests written alongside the change, which encode the author’s own assumptions. Route the gate through a test, an independent reviewer, or a different model (§8, §9). Review the output against the contract — “did it satisfy the contract, and did it add anything beyond it?” — not the diff line by line; line-by-line reading is how slop (§2) slips through while the reviewer feels thorough.
• Derive the checks from observed failures, not imagined ones. Criteria invented in a vacuum measure what you guessed would break, and pass while the failure users actually hit goes unmeasured — a generic “is this good?” gate scoring well is the classic false green. So before writing the gate, look at the real output: run the thing on a batch of realistic inputs and read the results — not the summary, the actual outputs and traces — then group the mistakes you find and write one check per recurring group. Prefer the cheap deterministic check wherever a failure admits one (does it parse, does it compile, does it match the schema, is the required line present); reserve model-judged rubrics for what genuinely needs judgment, and human review for the high-stakes and the tie-breaks. That ordering is also a cost ladder — cheapest filter first, most expensive attention last. Keep the checks tied to failures that keep recurring, and let new failure modes add new checks as they appear; a check nobody can trace to a real defect is upkeep you’re paying for nothing.
• Where nothing compiles, reconcile against a second source. Every check above assumes an exit code: a type gate, a failing test, a schema mismatch. Point a harness at analysis instead — an incident trend, a cost breakdown, a usage query pulled through some MCP — and that whole apparatus is gone. There is no compiler for a number, and the failure mode is not an error but a plausible answer computed over the wrong population: a query that silently covers half the rows because the filter depends on a field nobody fills in, returning real arithmetic over an unrepresentative slice. It reads as fact, formats beautifully, and is wrong in a direction nobody can see from the output. Reasoning built on top of it inherits the error at full confidence, and a quarter of work can be spent solving a problem that never existed. So for analysis that will be reasoned on top of, the verification is reconciliation: state the population before stating the finding — what the query counted, what it excluded, and why — then check that population against an independent source that was never part of the pipeline (the raw channel the alerts fired into, a second system’s totals, a hand count of one slice). Reconcile before the conclusion is drawn, not after it’s been acted on; a number that survived a cross-check is evidence, and one that hasn’t is still a draft. Disagreement between the two sources is the finding — chase it before proceeding, because it is the only signal you get that the pipeline is measuring the wrong thing. Surprise gets the same treatment: an analysis that contradicts what someone close to the domain believed is not automatically the correction, it is the trigger to reconcile.
• Play and production are separate activities; don’t run them in one pass. Learning a new harness, model, or tool is genuinely valuable and mostly happens by failing at things — which is exactly why it must not happen inside load-bearing work. Mixed together, the experiment inherits production’s stakes and production inherits the experiment’s error rate, and the outcome is worse at both: the learning is timid because the blast radius is real, and the shipped work carries failures nobody budgeted for. It also erodes the quality bar, because “it’s a new tool, we’re still figuring it out” becomes a standing excuse attached to real deliverables. So bound the experiment deliberately — a scratch repo, a throwaway branch, a task nothing depends on, an explicit block of time — and let it fail freely. A technique graduates into production work once it clears the same gates as anything else (§10’s checks, §9’s reviews), not because it seemed to go well in the experiment.
• Change one variable at a time. When tuning a loop that isn’t performing — prompt, model, tool definitions, runtime config — vary exactly one and hold the rest fixed, against an unchanged set of checks. Change two and a wash reads as “no effect” when it was really one win cancelling one regression, and you learn nothing about either. Fix the model and vary the prompt, then fix the prompt and vary the model, then vary the serving config last. The corollary: don’t tune the work and its checker in the same pass — a checker edited to accommodate failing output has stopped being a measurement.
• Scrutiny scales with novelty. Agents are strongest where prior art is dense and fail confidently where it’s thin — an agent that visibly struggles is the signal you’ve left remix territory, and its plausible-sounding output deserves the hardest verification precisely there. Easy is a smell: when the work felt effortless, check what the effortlessness bought before trusting it.

11. Knowledge succession (skill libraries)

AGENTS.md (§1) and the fix log (§2) cover a repo’s day-to-day operating knowledge. Some repos also carry knowledge that lives only in one person’s head — the debugging instincts, the settled arguments, the unwritten rules nobody documented because the senior engineer just knew them. When that knowledge needs to survive the person, or needs to run on a cheaper model than the one that holds it today, generalize it into a skill library (.claude/skills/<name>/SKILL.md or the harness-equivalent path) instead of letting it stay tacit.

A skill library is a compiled artifact in the same sense as §2’s “compile, don’t retrieve”: it is the settled output of someone’s tacit judgment, written once so a reader gets the answer directly instead of re-deriving it from raw history, Slack threads, or trial and error. A library that just links out to source material without stating the settled rule has not actually succeeded the knowledge — it has relocated the retrieval step.

• Discover before you write. Read the repo like an incoming engineer first — history, docs, tests, CI, the trail of reverted or abandoned attempts — then ask a small, bounded number of questions for what the repo genuinely cannot tell you (the hardest live problem, the unwritten discipline rules, who the audience is and what they don’t know). Fold the answers into the library; don’t author from assumption.
• One skill, one topic — no duplicate homes for a fact. Split a library by concern (architecture, debugging, config, domain reference, validation discipline, the hardest live problem as its own guided runbook) rather than one sprawling file. Each skill states when not to use it and which sibling to use instead, so a loader doesn’t have to guess.
• The description is the routing contract. A skill’s frontmatter description is all a loader sees before deciding to read it. State what the skill does, when to use it (the trigger phrases someone would actually say), and what distinguishes it from siblings — and never summarize the workflow itself, or the loader follows the summary and skips the body. Debug accordingly: a skill that doesn’t fire has a description problem; a skill that fires and produces the wrong output has a body problem.
• Invocation is a cost decision. A model-invocable skill’s description sits in the context window every session (context load); a skill invocable only by name costs nothing there, but the human becomes the index that must remember it exists (cognitive load). Choose model-invocation only when the agent — or a sibling skill — must reach it unprompted. When by-name skills multiply past what a person can remember, add one router skill that names the others and says when to reach for each.
• Lean body, deep references. Keep the skill file short enough to load cheaply; move rarely-needed detail into reference files linked one level deep (no chains), each with an explicit “read this when …” trigger. Push anything deterministic into a script the skill invokes rather than prose the model re-derives. Don’t re-teach what the model already knows — every paragraph must carry knowledge specific to this repo or this person.
• Test the trigger, not just the content. Before calling a skill done, pose the task in the words a user would use, without naming the skill, and check it fires — then pose a neighboring task and check it doesn’t. A library whose skills only load when invoked by name has failed at succession: the person who knew which file to open is exactly who’s gone.
• Ground truth only. Every command, flag, path, and claim gets verified against the repo before it’s written down — a wrong runbook is worse than no runbook, because it’s trusted. Unproven or open items stay explicitly labeled as such; nothing in the library may contradict AGENTS.md or route around this standard’s ship gates.
• Provenance and re-verification. Date-stamp anything that can drift (config defaults, flag lists, tool versions) and give each skill a one-line command that re-checks it. A skill without a re-verification path decays into the exact stale-instruction problem §1 exists to prevent.
• Write-scope discipline. A skill-authoring pass writes only inside the skills directory; it doesn’t mutate the rest of the repo. Keep the authoring and review passes separate — author, then have an independent pass check facts, check for contradictions between skills or with AGENTS.md, and check that a zero-context reader could actually follow each one.

This is expensive relative to a normal AGENTS.md update, so reserve it for knowledge that is genuinely at risk of being lost or that must run on a materially cheaper model than the one that holds it — not as the default way to document a repo.

Common rationalizations

The standard fails one skipped step at a time, and every skip arrives wearing a plausible excuse. These are the recurring ones, each with why it doesn’t hold. An agent about to act on an excuse from the left column should treat that as the signal to stop and follow the section on the right instead.

Migration recipe (monolithic CLAUDE.md → standard)

1. Back up the current CLAUDE.md (scratchpad copy; git init + commit first if the repo isn’t under git).
2. Rename/move the content into AGENTS.md (if AGENTS.md exists as a stub, merge into it; if it’s a duplicate, the content is already there).
3. Replace CLAUDE.md with the single line @AGENTS.md.
4. Extract any inline “corrections / lessons / gotchas log” into docs/solutions/*.md with frontmatter; leave a pointer in AGENTS.md.
5. Add a ## Keep in sync block for this repo’s drift-prone file pairs.
6. Add the SessionStart hook only if the repo has silent-failure config.
7. Verify: head -2 CLAUDE.md shows the include; diff AGENTS.md against the backup to confirm zero content loss (relocation only); git diff is reviewable.