Outfitter

How AI Outfitter fits together → — the mission, adoption ramp, end-to-end workflow, and relationship between the projects.

Outfitter is the toolchain for .agents: it resolves agent configuration from local and remote .agents trees, composes agents, skills, and knowledge by slug, and launches the result through wrapped agent CLIs like pi, Claude Code, and Codex CLI.

Outfitter does not own a configuration format. Your .agents/ directory is the source of truth — useful without Outfitter, committed and reviewed like any other code.

Why

Your agent setup is configuration: prompts, skills, MCP servers, model choices, permissions. Left alone it lives per tool and per laptop, gets pasted between repos, and drifts. Outfitter treats it like the rest of your infrastructure — layered, composed by slug, pinned by SHA, reviewed through pull requests.

That turns one person's improvement into everyone's default. On Monday a platform engineer writes a grafana-alert-investigate skill in their own ~/.agents tree and uses it at their desk. By Friday it is merged into the org catalog, pinned by SHA, and selected by slug from an agent that also runs on a CI schedule and in the cluster. Nobody else configured anything — their next run composes the new skill, and it costs their context window one line of routing metadata until it activates.

Two conventions do most of that work:

• Iterate on it in your own ~/.agents against real work, then share it by pull request — to the project, your org's catalog, or a community catalog. Everyone composes the shared version back by slug, and anything they need different they override in their own layer instead of copying. See Conventions.

• The same composition runs everywhere work happens: interactively at your desk, in GitHub Actions on any trigger, as recurring loops — locally, on a CI cron, or on a cluster schedule — and as resident or job-based agents in Kubernetes. Surface availability varies by release; each page notes its status.

For the full argument, read the Philosophy.

Quick start

Requires Node 22.19 or newer (the bundled Pi's floor). Older Node installs without error but crashes when Pi starts, so Outfitter refuses to run and prints an upgrade hint instead.

Run without installing:

npx @ai-outfitter/outfitter

Full install:

npm install -g @ai-outfitter/outfitter
outfitter

Pi is bundled and also hosts Outfitter's setup walkthrough. Install other runtime harnesses, such as Claude Code and Codex CLI, separately. For the full walkthrough, see Getting started.

Climb the ramp

Three runbooks, one per rung of the adoption ramp. Each starts where the previous one ended and closes with the one concrete step that begins the next rung. Their success checks are the signals an SDLC assessment reports, so "done" is something you run rather than something you judge.

1. Share one catalog — one pinned catalog the organization shares, instead of per-laptop configuration. → delegated
2. Run it without your laptop — an event triggers the workflow, its output lands through review, and the session is captured. → automated
3. Give the agent a residence — a named, assignable agent with an account and somewhere to live. → governed

Already have a .agents/ directory?

Then you already have Outfitter configuration. Each agent's loadout references your existing skills, subagents, MCP, knowledge, and commands by slug with zero porting:

<!-- .agents/agents/engineer/agent.md -->
---
name: engineer
skills: [wiki, research]
subagents: [code-reviewer]
mcp: [github]
---

# .agents/settings.yml
default_agent: engineer

outfitter setup runs the Pi-native walkthrough on top of .agents: choose a profile from the default Outfitter catalog or import a different .agents catalog, then pick the home/project target and default CLI agent. For a custom profile, write .agents/agents/<id>/agent.md and set default_agent. The default picker is fetched from the immutable ai-outfitter/community-profiles Release Please tag pinned by Outfitter—never from a sibling checkout. Managed porting and persistent harness symlinks are deferred to #187.

The .agents protocol in 30 seconds

.agents/
  agents.md            # shared operating context
  system-prompt.md     # base system prompt
  mcp.json             # MCP servers
  models.json          # model configuration
  agents/<id>/agent.md # identities + loadouts — run directly or as subagents
  skills/<id>/...      # capability packages
  knowledge/           # reference documents
  commands/            # slash commands

Layers merge by ID: <project>/.agents/ over ~/.agents/ over pinned remote catalogs. An agent carries both its identity and its loadout — an agent profile — and is what you run; a persona is one portable Markdown document a shared review agent adopts at launch; a subagent is an agent a run delegates to, across four delegation boundaries from an in-session helper to a Kubernetes Job.

Documentation

The documentation index covers setup, core concepts, organization-wide sharing, automation, and contribution:

• Climb: Share one catalog · Run it without your laptop · Give the agent a residence
• Start: Getting started · First-time CLI agent users · Switching to Outfitter
• Understand: Concepts · Agents · Skills · Personas · Subagents and delegation
• Share: Catalogs · Conventions · Organization catalog · Best practices
• Automate: GitHub Actions · Recurring runs · Cost estimation · In-cluster agents · Hooks · State persistence
• Reference: CLI · Settings · Adapter support matrix · Philosophy

Use cases, story first:

• Shared conventions without duplication
• Flaky-test post-mortems in CI
• Grafana alert investigations in-cluster
• Self-improving skills
• Resident agents: a researcher wiki
• Persona reviews
• Organization catalog
• Engineering catalog

For local development, repository structure, and release workflow details, see Contributing.

License

Outfitter is MIT licensed, except for code in code/enterprise/, which is under the Unsupervised Enterprise license. Production use of that code requires a valid Unsupervised Enterprise license.