Headcount: The AI Org Chart That Treats File Paths Like Job Descriptions
A deep dive into how `cbrock84/headcount` uses departments, reviewer-class agents, and write-surface enforcement to turn Claude Code into a governable system, not a prompt pile.
Models are noticeably better at holding a line when the line is written down as somebody else's job.
- `headcount` is really about governance, not just agent capability, because it turns authority into filesystem boundaries.
- The repo’s strongest idea is the shift from topic-based roles to machine-enforceable write surfaces.
- Reviewer-class agents matter because they stay read-only, which stops review from collapsing into stealth editing.
- The project argues that future agent tooling needs audit trails and scope control, not just better prompts.
Multi-agent systems fail in boring ways. One agent overwrites another, a reviewer quietly becomes a fixer, and the whole setup drifts from coordination into improvisation. `headcount` is interesting because it attacks those failures with structure, not charisma.
Why Multi-Agent Systems Fail Quietly
The problem is not usually intelligence. It is overlap. Once two agents can touch the same surface, or one agent can review and edit at the same time, you have lost the boundary that makes delegation meaningful.
That line from the README is the thesis in plain English. `headcount` is not trying to make agents smarter in the abstract. It is trying to make responsibility legible enough that the system can enforce it.
The Corporate Metaphor Is the Control Plane
The org chart is not decoration. Departments, reporting lines, and titles are the control plane. The repo uses that metaphor to make Claude Code reason about roles, scope, and escalation the way a real company does.
The idea is basically an “org in a box.” It's meant to help Claude reason through things like organizational structure, roles and responsibilities, headcount planning, hiring, performance, compensation, succession, workforce risk, and the other moving parts involved in building and running a company.
Write Surfaces: The Most Important Idea in the Repo
The key shift is from agent by topic to agent by filesystem boundary. Most multi-agent systems say who does the work. `headcount` says where the work may land. That sounds small until you realize it is the difference between vibe-based coordination and something a machine can check.
That enforcement lives in `agent-guard.mjs`. The guard checks whether a proposed change fits the allowed glob patterns. If it does not, the write is blocked. That turns a social rule into a programmatic one.
Reviewers Are Not Just Another Kind of Agent
`headcount` makes a hard distinction between builders and reviewers. Builders can write within their surface, but they do not get to blur the line between creating and approving. Reviewers are permanently read-only. That is a real governance choice, not a prompt preference.
| System | What it optimizes for | How it assigns responsibility | Failure mode | Why headcount is different |
|---|---|---|---|---|
| Flat skill library | Breadth of capability | By topic or task | Agents overlap and drift | It assigns authority by write surface, not by label |
| General-purpose agent framework | Flexible orchestration | By tool graph or workflow | Too abstract for clear governance | It makes boundaries the primary unit of control |
| Traditional mega-prompt | Fast setup | By a single instruction block | Context bloat and role confusion | It splits authority into installable, auditable departments |
That separation matters because review collapses when a reviewer can also patch the thing they are judging. `headcount` treats that as a design bug, not a clever workflow shortcut.
The Return Contract Makes Outputs Auditable
The `.claude/agents/*.md` files do more than describe personas. They define a return contract. An agent has to report what changed, why it changed, what was verified, what remains undone, what outside help is needed, and what questions are still open.
That sounds bureaucratic until you compare it with the usual agent handoff, which often reads like a confident shrug. The contract makes outputs reviewable by a human and legible to the next agent in the chain.
How the Repo Is Put Together
The structure is intentionally modular. `.claude/agents/` holds the charters. `plugins/` contains installable Claude Code plugins. Each plugin carries its own `skills/` tree, and each skill lives in a `SKILL.md` file. The surrounding scripts and manifests make those boundaries enforceable and portable.
.claude/agents/
executive.md
security.md
finance.md
plugins/
executive/
.claude-plugin/plugin.json
skills/
chief-executive/SKILL.md
agent-hierarchy/SKILL.md
agent-guard.mjs
security/
.claude-plugin/plugin.json
skills/
threat-modeling/SKILL.md
docs/
DECISION-LOG.md
org-chart.mdThat layout is the repo’s second argument. It says the organization itself should be installable. If you only need security, you should not inherit finance, product, or executive context as accidental baggage.
What Headcount Is Really Competing Against
The closest alternatives are flat skill libraries, broad agent frameworks, and monolithic prompts. Those systems can be useful, but they mostly optimize for capability or convenience. `headcount` optimizes for authority, scope, and auditability.
| Model | Strength | Weakness | Takeaway |
|---|---|---|---|
| Flat skills | Easy to add capabilities | No strong boundary model | Good for breadth, weak for governance |
| Agent frameworks | Flexible multi-step orchestration | Can get heavy quickly | Good for workflows, less sharp on responsibility |
| Monolithic prompts | Simple to start | Hard to audit or scale | Good for demos, brittle in practice |
| Headcount | Installable departments with write surfaces | Requires thinking like an org | Good for governed coordination |
That is why the repo feels more like policy-as-code than prompt engineering. It is not just asking an agent to behave. It is deciding what the agent is allowed to change.
The Bigger Bet
The deeper bet here is that agent tooling will eventually need boundaries as much as it needs intelligence. Once systems start acting on real repos, the important question stops being whether the model can write code. It becomes whether the model stayed inside its remit.
`headcount` answers that by borrowing from how organizations already work. It turns jobs into surfaces, review into a class, and coordination into something you can inspect after the fact. That is the real product.
