agent-hierarchy

# Agent hierarchy

A method for standing up an orchestrator → specialist-subagent hierarchy, extracted from a
working implementation of ~24 agents over a 1,500-file monorepo, machine-checked on every PR.

## The whole method in one paragraph

Split agents by **write surface, not by topic**. Two classes only: **builders**, which edit
inside exactly one exclusive surface and never commit, and **reviewers**, which are permanently
read-only and can always run in parallel. The orchestrator — the main chat — is the sole
committer. Write the surface map **before** any charters, keep it in one Markdown file, and
enforce it with a script that runs in CI. Each row also carries an **authority** — `autonomous`,
`proposes`, or `escalates` — which answers the separate question of whether that agent's work may
land without a decision; most rows are `autonomous`, and gating everything makes the gate
meaningless. Producer and auditor are never the same agent. For
each class of fact, exactly one file owns it and everyone else derives.

## Why topic splits fail

"One agent on SEO, one on UI" is the intuitive split and it breaks immediately: both end up
editing `tokens.css`. Neither is wrong, and neither can be held responsible. A surface split
has no such overlap by construction — which is exactly what makes it checkable.

## Order of operations

Do not start writing charters early; the order is the method.

1. **Inventory the real tree** — `git ls-files | sed 's|/[^/]*$||' | sort -u`. Report what is
   actually there before proposing anything.
2. **Propose the roster** — the smallest set where no two agents share a file. Each needs an
   id, a class, a one-line remit, and its exact globs. An agent whose surface cannot be stated
   in globs is not an agent; fold it in.
3. **Write the surface map** — one Markdown file, one row per agent.
4. **Wire the guard** — `scripts/agent-guard.mjs check` proves the map is coherent (no path
   claimed twice, no path unowned); `agent-guard.mjs diff <agent>` proves a given diff obeyed
   it. Both are needed: once the orchestrator commits, the authorship that `diff` checks is
   gone, so it has to run while the work is still attributable.
5. **Write charters last**, in the format in the playbook: why the agent exists, what it must
   never do, the verification its surface implies, and a six-section return contract.

## Rules that carry a failure behind them

- **Producer and auditor are never the same agent.** An agent that reviews its own output
  reliably approves it.
- **The orchestrator is not one of the two classes.** It is the sole committer, and giving it
  a surface makes it a builder that can also merge.
- **One file owns each class of fact.** Everything else derives from it, or the two copies
  diverge and nobody notices which is stale.
- **Never remove a shared-core export because it looks unused.** You cannot see the consumers
  from inside the core. Deprecate, announce, then remove.

## This repository's own log

`docs/DECISION-LOG.md` is the live instance of the decision log described in the playbook. When a
decision is raised, assign it the next number immediately — before it is answered — and give it
lettered options with an explicit recommendation. Never renumber, never reuse a number, and record
resolutions in place rather than deleting them.

## Never

- Add an agent before the surface it will own exists. The map comes first, the agent second.
- Let two agents hold a write claim on the same path. Overlap resolves itself as a race.
- Hand-edit a generated artifact instead of the source it derives from.
- Skip the guard because the change is small. Small changes are how surfaces drift.

## References

- `references/playbook.md` — the full 415-line playbook: surface splitting, the guard, the
  registry, the decision log, anti-patterns with their failure modes, sizing, multi-repo and
  shared-core layouts, the charter format, and a day-one checklist.
- `references/starter-rosters.md` — concrete rosters for a mobile-app portfolio, a game
  portfolio, and a shared core, with producer/auditor pairings.
- `references/bootstrap-prompt.md` — a fill-in-the-blanks prompt for standing this up in a
  fresh session against a target repo.
- `scripts/agent-guard.mjs` — the executable guard. No dependencies, Node 18+.