wardrobe

A harness-agnostic capability system for LLM agents. Any agent that can read files and run shell commands equips a domain capsule — a role prompt, tool recipes, curated files, and optional real capabilities (MCP servers, skills, plugins) — from this plain file tree, does its work, and leaves the tree untouched. The wardrobe is a read-only registry: agents equip from it, never write back to it. Capsules are curated by maintainers through ordinary git pull requests.

Everything is Markdown + YAML frontmatter + git + one Python script (bin/reindex). There is no server, no daemon, no orchestrator process, and no harness-specific configuration in the core.

The core is harness-agnostic, but Claude Code is the only supported harness for now. It has the one shipped adapter, adapters/claude-code/. Any other harness would need its own adapter built on the same shell-out contract — bin/reindex capabilities <domain> → JSON manifest → materialize into a project — and none has been written yet.

INDEX.md is the agent entrypoint — read live, at runtime, by an operating agent starting a task: how to pick a capsule, the four-rule constitution, and the generated table of every capsule with its context cost in tokens. It is not where a human starts; this README is. Setup and day-to-day management happen through skills/ — see Operator skills below.

---

Specialization lives in equippable capsules, not in pre-assigned specialist agents — and there is no orchestrator. An arriving agent reads the INDEX table's frontmatter signals (when-to-use, token cost, status flags) and assigns itself. This follows the pressure-field coordination result (arXiv:2601.08129): across 1,350 trials, agents self-assigning from shared quality signals on a common artifact solved 48.5% of tasks, versus 11.1% for conversation-based coordination and 1.5% for hierarchical control. The orchestrator's costs are structural — management calls displace work, managers fixate on the hardest region and block progress everywhere, decisions serialize; message load scales O(n²)/O(n log n) against O(1) for reading shared state. Dedicated orchestrators and pre-assigned domain agents were patches for weak models: a model that is a universal actor (broad pretraining), follows natural-language capability descriptions (no enumerated action space), and recognizes quality zero-shot (it judges its own fit from written signals) makes the router pure overhead — and a pre-assigned specialist is a pre-assigned blind spot.

The design follows from that. Coordination happens through committed artifact state — the capsule table, its frontmatter, git history — never messages. Equipping is cheap and reversible, so one agent re-equips between phases instead of a fleet of specialists holding context they mostly do not need: the token column in INDEX is a budget contract that bin/reindex equip resolves exactly. Delegation stays the exception, per minimal-rule swarm findings (arXiv:2603.28990) — an agent that cannot add value abstains rather than coordinating.

The registry is read-only at runtime for a reason: an equipping agent's job is to do the task, not to maintain the wardrobe. It materializes a capsule's capabilities into its own workspace, works there, and leaves the registry byte-for-byte unchanged. What a capsule contains — its role wording, tool recipes, permissions, and capability declarations — changes only the way any reviewed code changes: a maintainer opens a pull request, and the git hook revalidates every capsule before the commit lands. An agent that hits a problem with a capsule reports it to the maintainer; it never edits the registry to route around the problem.

---

Setup

Requires Python 3 (stdlib only). tiktoken is optional — installed, token counts are exact for the o200k tokenizer; otherwise a chars/4 approximation is used and labeled as such.

git clone <this-repo> wardrobe && cd wardrobe
cp _system/hooks/pre-commit .git/hooks/ && chmod +x .git/hooks/pre-commit
python3 -m pip install --user tiktoken   # optional; then run bin/reindex once
bin/reindex --check                      # validate: silence + exit 0 is healthy
python3 -m pytest tests/ -q              # contract tests for scripts and hooks

The pre-commit hook is load-bearing: it runs bin/reindex --check, which validates every capsule and commons file and refuses any commit that would leave the registry invalid. History stays append-only — recovery adds commits, it never rewrites them.

Wire your agents to it. Paste the one-paragraph snippet from _system/bootstrap.md into whatever instruction layer your harness reads (project instructions file, system prompt, spawn prompts). That single pointer — read INDEX.md first and follow it — is the entire integration surface; the wardrobe stays harness-agnostic because nothing else is required.

Setup itself is one of the operator skills below, not a one-off manual sequence — the commands above are what wardrobe-setup runs.

For agents: before any task, read INDEX.md and follow its "How to use" steps. Decide your equip from frontmatter alone; run bin/reindex equip <domain> [--budget N] and load exactly the files it lists. Confirm every env var in the capsule's permissions.env exists — a missing one means stop and report, never improvise secrets. Do the work in your own workspace and leave the registry unchanged.

Operator skills — how setup and management actually happen

Setup and day-to-day repo management are not manual procedures a human executes by hand; they are skills/ — self-contained operator procedures an agent (e.g. Claude Code) invokes directly, the same dispatcher pattern domain capsules use for task work:

• wardrobe-setup — get a checkout, install the hook, wire an agent's instruction layer to INDEX.md.
• wardrobe-add-capsule — create a domain capsule from the template, fill it in, index it, and commit it.
• wardrobe-delete-capsule — remove a capsule cleanly and reindex.
• wardrobe-connect — materialize a capsule's declared capabilities into a real project, and detach them again.

A human operates this repo by directing an agent to run the relevant skill — "set up the wardrobe here," "add a capsule for X," "connect that domain's capabilities" — or, lacking an agent, by opening the SKILL.md file directly and following it as plain instructions; each one is written to stand alone. This is the other half of resolving the entrypoint question above: INDEX.md is what an agent reads mid-task to pick and equip a capsule; skills/ is what an agent (or a human reading along) runs to set the repo up or change its shape in the first place.

Daily use — equip and work

Every task, every agent:

1. Read the INDEX capsule table; pick the domain whose when to use matches; respect when not to use redirects; check the token cost fits.
2. bin/reindex equip <domain> [--budget N] → load exactly that bundle (capsule manifest, required files, then recommended files while budget allows).
3. If the capsule declares capabilities, materialize them into your own workspace with a harness adapter (for Claude Code, adapters/claude-code/apply <domain> --target-dir <your-project>); the adapter refuses to write into this registry.
4. Confirm every permissions.env var is present — a missing one means stop and report, never improvise secrets.
5. Work as role.md prescribes with the recipes in tools.md, in your own workspace. Leave the registry unchanged. If a capsule is wrong or incomplete, report it to the maintainer rather than editing it.

Managing capsules

Capsules are curated through ordinary git review — there is no runtime mutation path.

• Add a domain: copy _system/templates/capsule/ to capsules/<domain>/, fill the frontmatter, write role.md / tools.md (and any files/ or capabilities/), run bin/reindex to validate and write the token count, then commit. Full procedure: skills/wardrobe-add-capsule.
• Remove a domain: git rm -r capsules/<domain>, run bin/reindex, and commit — history keeps the removed capsule recoverable from any prior sha. Full procedure: skills/wardrobe-delete-capsule.
• Edit a domain: change the files, run bin/reindex (it rewrites the token count and regenerates the INDEX table), and commit. The pre-commit hook revalidates before the commit lands.

Wiring real capability

A capsule's capabilities: block (optional) declares real MCP servers, Claude-Code-style skills, and plugins — not prose about them. bin/reindex capabilities <domain> resolves the block to a JSON manifest; a harness adapter turns that manifest into something a project can actually use. Claude Code is the only harness with a shipped adapter — everything below is adapters/claude-code/; another harness reimplements it against the same bin/reindex capabilities contract.

adapters/claude-code/apply  <domain> --target-dir <project>   # .mcp.json entries + skills
adapters/claude-code/remove <domain> --target-dir <project>   # detaches exactly what apply wrote

generate-agent combines one or more capsules into a single Claude Code subagent definition (remove-agent deletes it). It writes each declared MCP server into the target project's .mcp.json under a <domain>-<server> key and references that key from the agent file's mcpServers: as a bare string — never an inline map. That routing is what makes a credentialed server work: Claude Code interpolates ${VAR} placeholders when it reads .mcp.json, but not from an inline subagent map, so a descriptor whose env uses ${TOKEN} resolves to the real secret from the environment (declared in the capsule's permissions.env) and the registry never holds it. New .mcp.json servers apply on the next session start, exactly like apply.

bin/reindex validates each MCP descriptor's shape at commit time — a stdio server needs a nonempty command; a remote one needs type in {sse, http} plus a url; args must be a list and env/headers string maps — so a malformed descriptor is rejected in git review, not when a client first tries to connect. A complete, copyable wiring (the official @modelcontextprotocol/server-everything) lives in the capabilities authoring doc, _system/templates/capsule/capabilities/README.md, and tests/test_smoke_capability.py exercises that same path end to end.

Every adapter verb refuses to write into the wardrobe registry itself — you always materialize into your own project workspace, never back into the read-only tree. The adapter shells out to bin/reindex capabilities and parses its JSON stdout; it never imports the wardrobe's own scripts, which is what keeps the core harness-agnostic even though the adapter necessarily is not. Full procedure: skills/wardrobe-connect.

Scope & limitations

Honest boundaries, not defects:

• Claude Code only, for now. The core is harness-agnostic, but adapters/claude-code/ is the sole shipped adapter. Another harness needs its own adapter on the bin/reindex capabilities contract.
• Plugins are printed, never installed. There is no safe generic install primitive to script against yet, so wiring a plugin stays a manual step.
• Scale is reasoned, not load-tested. The read-only registry has no shared runtime state to contend on, so hundreds of agents equipping concurrently should not interfere — but that has not been benchmarked at that scale.
• Skills symlink with absolute paths by default. Fine on a normal checkout; untested on Windows or across container boundaries where an absolute path may not resolve. Pass --copy to materialize real directories instead.

Layout

Path	Purpose
INDEX.md	Agent entrypoint: usage flow, constitution, capsule table
capsules/<domain>/	One capsule per domain (capsule.md, role.md, tools.md, files/, capabilities/)
commons/	Cross-domain shared files
_system/	Delegation, recovery docs, capsule templates, bootstrap snippet
_system/bootstrap.md	The one-paragraph snippet that points any agent harness at INDEX.md
_system/hooks/	Canonical git hook (pre-commit capsule validation)
bin/reindex	Validate frontmatter, count tokens, regenerate the INDEX table, resolve equip bundles and capability manifests
adapters/claude-code/	apply/remove/generate-agent/remove-agent: materialize a domain's capabilities into (or out of) a real project
ledger/transcripts/	Local task transcripts (gitignored)
tests/	Contract tests for the script, hook, and adapter
skills/	Operator skills (SKILL.md each): setup, add/delete a domain capsule, connect capabilities
TODOS.md	Known follow-ups: additional harness adapters, plugin install, scale load-test, cross-platform skills

Recovery

Nothing rewrites history; recovery adds commits or restores from existing state. Undo a bad commit with git revert; restore a deleted file from any sha with git checkout <sha> -- <path>; reinstall the pre-commit hook from _system/hooks/. Full recipes: _system/recovery.md.

References

• Pressure-field coordination — self-assignment via shared quality signals beats hierarchical and conversational orchestration: arXiv:2601.08129
• Minimal-rule swarms; abstention over coordination chatter: arXiv:2603.28990