Outfitter documentation

Synced from outfitter/docs/documentation/README.md. The repository is the source of truth.

Outfitter lays out conventions for iterating on and sharing agent configuration — agent profiles, skills, and loadouts. Start by setting up your configuration, then learn how to share it across projects and your organization and run it in CI or on a cluster. Each page keeps to one concept and links onward when you need the next one, so nothing here has to be read up front.

To understand AI Outfitter and how its projects fit together, read How AI Outfitter fits together. To assess and onboard your own organization, start with Onboard an organization with an SDLC report — one engineer runs the maturity assessment, then creates the org .agents repository with the baseline report as its first commit.

Climb the ramp (runbooks)

One runbook 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. Every runbook ends in a check you run rather than a judgement you make — the first three against the signals an SDLC assessment reports, the last against the cluster directly.

Share one catalog — one pinned catalog the organization shares, instead of per-laptop configuration. (→ delegated)
Run it without your laptop — an event triggers the workflow, its output lands through review, and the session is captured. (→ automated)
Give the agent a residence — a named, assignable agent with an account and somewhere to live. (→ governed)
Continuously deployed Kubernetes agents with Actions — a merge to the catalog moves the fleet, with no stored cluster credential. (deepens governed)

Start (you)

Getting started — install, first run, default agent.
First-time CLI agent users — new to agent CLIs entirely.
Switching to Outfitter — adopt from an existing agent-CLI setup.
Porting a Claude Code setup — ~/.claude into ~/.agents/ with symlinks back.

Understand (the model)

Concepts — resolve → compose → adapt; layers and precedence.
Agents — the agents/<id>/agent.md resource and its loadout — what you run.
Agent profiles — why an agent and its loadout is the profile.
Skills — capability packages with progressive disclosure, references, and routing.
Personas — one portable Markdown file per persona; append at launch or paste anywhere.
Subagents and delegation — the four delegation boundaries, from in-session helpers to Kubernetes Jobs.
Settings — scopes, schema, and the flat settings.local.yml override file.
Tasks — placeholder for a separate upcoming RFC.

Catalogs — publish and consume shareable .agents payloads; standalone and colocated layouts.
Conventions — place a resource once, specialize downward, never copy.
Local dotagents development — a personal standalone .agents repo that trickles upstream.
Iterating on an agent — the edit-run-inspect loop.
Best practices — few agents, many skills.

Automate (surfaces)

The same composition runs on every surface; only the trigger changes.

Running an agent in GitHub Actions — headless runs on any workflow trigger.
Channels — add external event sources that wake a resident agent only when work arrives.
Container images — run the published Debian-based image persistently or extend it with apt.
Recurring runs — loops three ways: the local loop extension, Actions cron, cluster schedules.
Cost estimation — one workload profile and model-cost line across local, Actions, and Kubernetes runs.
In-cluster agents — resident agents, CronJobs, and subagent Jobs via Link Operator.
Hooks — harness hook wiring, launcher-scope system observers, and the protocol gap.
Dump — deterministic, self-contained .agents/ dumps.
State persistence
Adapter support matrix

Use cases (stories)

Each use case is a worked story — a problem, the composition that answers it, and the payoff — with links back to the concepts it uses.

Shared conventions without duplication — one conventional-commits rule for every user, org, and project; zero copies.
Flaky-test post-mortems in CI — an on-failure step that classifies flake vs. regression and comments with evidence.
Grafana alert investigations in-cluster — a webhook turns each firing alert into one bounded investigation Job.
Self-improving skills — a weekly loop that proposes skill edits and ships only measured improvements.
Resident agents: a researcher wiki — a long-lived agent that turns an email inbox into a compounding, reviewable knowledge base.
Persona reviews — author one persona file, run it through the shared reviewer, paste the same file into any web agent.
Organization catalog — publish shared org resources and defaults through an owner/.outfitter control repository.
Engineering catalog — package engineering agents and skills for repeatable workflows.