# Agent Hierarchy

Designs orchestrator-and-subagent hierarchies for a repository, splitting agents by...

- Repository: https://github.com/cbrock84/headcount (2554 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-18
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add cbrock84/headcount --skill agent-hierarchy -g -a claude-code -y`
Codex: `npx skills add cbrock84/headcount --skill agent-hierarchy -g -a codex -y`
Cursor: `npx skills add cbrock84/headcount --skill agent-hierarchy -g -a cursor -y`
Gemini CLI: `npx skills add cbrock84/headcount --skill agent-hierarchy -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add cbrock84/headcount`

## Description

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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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.

The rest: https://github.com/cbrock84/headcount/blob/HEAD/plugins/executive/skills/agent-hierarchy/SKILL.md