Rules & Governance
Headbox is not only a CLI. It is a set of rules that apply to a workspace: instruction packs a project installs à la carte, artifacts with access rules that decide who may write to them, and one block emitted into every agent file so six tools cannot drift apart. The CLI is how you operate it; this is what it operates on.
Since v0.8.0, the rules stopped asking nicely
The original model relied on an agent choosing to read its instructions. headbox install-hooks changes
that: a deterministic adherence layer with hooks, mechanical counters and an @import stub, so the
harness enforces the rules rather than the agent remembering them. headbox refresh re-emits the managed
blocks from headbox-main.md, which is the propagation path: change a rule once, refresh, and every
vendor file is rewritten.
Plugins
Modular instruction packs. A project installs only the ones it needs. All 24 are parsed from plugins/REGISTRY.md and their own file headers: the same registry the CLI validates against.
Why 24 is a verified number, not a claim
Three independent sources agree: 24 rows in plugins/REGISTRY.md, 24 files present on disk, and the CLI's own headbox validate printing OK: 24 plugins checked. No plugin is registered-but-missing or present-but-unregistered.
The Full Set
Each card carries the plugin's real registry row. Version, type, dependencies and starter artifacts, plus the vendor compatibility line from its own file header. Team marks the five plugins the CLI counts as team plugins.
Artifacts
The files Headbox governs. Each one has an access rule that decides whether you may edit it directly, only append through a command, or must file a proposal. This list is captured from live headbox artifacts output.
Governed Files
The access rule is the interesting part: proposal-required artifacts cannot be edited directly at all: the CLI routes you to headbox propose. Append-through-command artifacts are append-only so history cannot be quietly rewritten.
Vendor Targets
Headbox writes the same instruction block into every agent file it finds, so each tool gets identical rules. These 6 candidates are parsed directly from vendorFiles().
The code and the README disagree: the code wins
The README's vendor table lists seven agents including Antigravity. vendorFiles() ships six candidates, and the string antigravity does not appear anywhere in cli/headbox.js. We render what the code does and flag the seventh rather than quietly showing either number.
Implemented
Detected by vendorFiles(), which filters the candidate list to files that actually exist in the target. AGENTS.md is the vendor-neutral baseline every install carries; CLAUDE.md is added explicitly because Claude Code will not read anything else.
AGENTS.md
CLAUDE.md
GEMINI.md
.cursorrules
.github/copilot-instructions.md
.windsurfrules
Documented, Not Implemented
Present in the docs, absent from the binary. Shown because a reader comparing this page to the README deserves to know which one is true.