agent-hierarchy
Designs orchestrator-and-subagent hierarchies for a repository — splitting agents by exclusive write surface, pairing every producer with an independent auditor, and enforcing the split with a script that runs in CI. Use this whenever the user wants to set up, expand, audit, or fix a multi-agent or subagent structure for a codebase; asks how to divide work between agents; wants agent charters, roles, or a surface map written; or is hitting agents that collide on the same files, review their own work, or drift from their remit. Also use when sizing a roster or deciding whether a new agent is justified.
git clone --depth 1 https://github.com/cbrock84/headcount /tmp/agent-hierarchy && cp -r /tmp/agent-hierarchy/plugins/executive/skills/agent-hierarchy ~/.claude/skills/agent-hierarchySKILL.md
# 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+.
Concentrates marketing and sales effort on a named set of accounts rather than on volume — qualifying whether the model fits your economics at all, building the account list and the buying group inside each, tiering effort against account value, coordinating so the account experiences one campaign rather than several, and measuring account progression instead of leads. Use this to decide whether to run an account-based program, build one, or work out why an existing one produces activity and no pipeline.
Governs models and AI systems in production — intended use, evaluation, monitoring, human oversight, documentation, and the decision to deploy or retire. Use this before deploying a model or AI feature, when defining evaluation criteria, when a model's behavior has drifted, when assessing AI risk or regulatory exposure, or when deciding whether an AI system is fit for a consequential decision.
Produces executive-level research — market sizing, competitor mapping, trend analysis, and strategic intelligence — grounded in cited sources with the confidence in each claim made explicit. Use this to analyze a market or industry, map competitors, evaluate a market-entry or build-versus-buy decision, produce a research brief, or assemble evidence for a decision. Also use when comparing options that need a structured, evidence-based verdict rather than an opinion.
Optimizes for AI assistants and AI-generated answers — being retrievable, being cited, and being represented accurately when a model answers on your behalf. Use this when traffic is shifting from links to AI answers, when a brand is misrepresented or absent in AI responses, when planning content for retrieval rather than ranking, or when deciding how AI search changes an existing SEO program.
Improves visibility and conversion in the App Store and Google Play — metadata, keywords, screenshots, ratings, and the listing experience that turns an impression into an install. Use this to audit or optimize an app listing, plan a launch listing, diagnose poor install conversion, or improve store search visibility.
Protects and restores data — backup coverage and scope, retention, immutability against ransomware, and proving restores actually work. Use this to design a backup regime, verify restores, plan retention, protect backups from ransomware, or recover from data loss.
Runs the planning cycle — annual budget, rolling forecast, consolidation of business unit inputs, and the variance analysis that explains actuals against plan. Use this to build or challenge a budget, run a forecast cycle, consolidate departmental submissions, explain why results diverged from plan, or improve forecast accuracy.
Finds the single constraint currently limiting a business's growth and the highest-leverage moves against it, rather than producing a list of everything that could be improved. Use this when growth has stalled or slowed, when deciding where to spend limited time or budget, when revenue rises but profit does not, when prioritizing growth initiatives, or when a business feels busy without compounding.