{"id":53855,"plugin_id":"plugins_6ac84b5ba2ec8191ba087c444a02106c","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-24T13:55:14.800Z","digest":"a4c4608fafcde83d79a95ba90c754c4ce6110d5e6065a9015805e91318bb357c","against":null,"payload":{"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.","included_files":[{"relative_path":"references/bootstrap-prompt.md","size_in_bytes":4940},{"relative_path":"references/playbook.md","size_in_bytes":20261},{"relative_path":"references/starter-rosters.md","size_in_bytes":5110},{"relative_path":"scripts/agent-guard.mjs","size_in_bytes":17301}],"name":"agent-hierarchy","skill_md_contents":"---\nname: agent-hierarchy\ndescription: 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.\n---\n\n# Agent hierarchy\n\nA method for standing up an orchestrator → specialist-subagent hierarchy, extracted from a\nworking implementation of ~24 agents over a 1,500-file monorepo, machine-checked on every PR.\n\n## The whole method in one paragraph\n\nSplit agents by **write surface, not by topic**. Two classes only: **builders**, which edit\ninside exactly one exclusive surface and never commit, and **reviewers**, which are permanently\nread-only and can always run in parallel. The orchestrator — the main chat — is the sole\ncommitter. Write the surface map **before** any charters, keep it in one Markdown file, and\nenforce it with a script that runs in CI. Each row also carries an **authority** — `autonomous`,\n`proposes`, or `escalates` — which answers the separate question of whether that agent's work may\nland without a decision; most rows are `autonomous`, and gating everything makes the gate\nmeaningless. Producer and auditor are never the same agent. For\neach class of fact, exactly one file owns it and everyone else derives.\n\n## Why topic splits fail\n\n\"One agent on SEO, one on UI\" is the intuitive split and it breaks immediately: both end up\nediting `tokens.css`. Neither is wrong, and neither can be held responsible. A surface split\nhas no such overlap by construction — which is exactly what makes it checkable.\n\n## Order of operations\n\nDo not start writing charters early; the order is the method.\n\n1. **Inventory the real tree** — `git ls-files | sed 's|/[^/]*$||' | sort -u`. Report what is\n   actually there before proposing anything.\n2. **Propose the roster** — the smallest set where no two agents share a file. Each needs an\n   id, a class, a one-line remit, and its exact globs. An agent whose surface cannot be stated\n   in globs is not an agent; fold it in.\n3. **Write the surface map** — one Markdown file, one row per agent.\n4. **Wire the guard** — `scripts/agent-guard.mjs check` proves the map is coherent (no path\n   claimed twice, no path unowned); `agent-guard.mjs diff <agent>` proves a given diff obeyed\n   it. Both are needed: once the orchestrator commits, the authorship that `diff` checks is\n   gone, so it has to run while the work is still attributable.\n5. **Write charters last**, in the format in the playbook: why the agent exists, what it must\n   never do, the verification its surface implies, and a six-section return contract.\n\n## Rules that carry a failure behind them\n\n- **Producer and auditor are never the same agent.** An agent that reviews its own output\n  reliably approves it.\n- **The orchestrator is not one of the two classes.** It is the sole committer, and giving it\n  a surface makes it a builder that can also merge.\n- **One file owns each class of fact.** Everything else derives from it, or the two copies\n  diverge and nobody notices which is stale.\n- **Never remove a shared-core export because it looks unused.** You cannot see the consumers\n  from inside the core. Deprecate, announce, then remove.\n\n## This repository's own log\n\n`docs/DECISION-LOG.md` is the live instance of the decision log described in the playbook. When a\ndecision is raised, assign it the next number immediately — before it is answered — and give it\nlettered options with an explicit recommendation. Never renumber, never reuse a number, and record\nresolutions in place rather than deleting them.\n\n## Never\n\n- Add an agent before the surface it will own exists. The map comes first, the agent second.\n- Let two agents hold a write claim on the same path. Overlap resolves itself as a race.\n- Hand-edit a generated artifact instead of the source it derives from.\n- Skip the guard because the change is small. Small changes are how surfaces drift.\n\n## References\n\n- `references/playbook.md` — the full 415-line playbook: surface splitting, the guard, the\n  registry, the decision log, anti-patterns with their failure modes, sizing, multi-repo and\n  shared-core layouts, the charter format, and a day-one checklist.\n- `references/starter-rosters.md` — concrete rosters for a mobile-app portfolio, a game\n  portfolio, and a shared core, with producer/auditor pairings.\n- `references/bootstrap-prompt.md` — a fill-in-the-blanks prompt for standing this up in a\n  fresh session against a target repo.\n- `scripts/agent-guard.mjs` — the executable guard. No dependencies, Node 18+.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}