Concepts

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

How an outfitter launch goes from configuration files to a running agent:

flowchart LR
  settings[Settings] --> sources[Sources]
  sources --> layers[".agents layers"]
  layers --> resolver[Resolver]
  resolver --> composed["Composed agent"]
  composed --> adapter[Adapter]
  adapter --> harness[Harness]

Settings tell Outfitter where .agents resources come from; sources supply protocol resource trees; the resolver merges the layered trees into one effective resource set; the selected agent composes its loadout — skills, subagents, model, and so on — from that set by slug; and an adapter projects the composed agent into harness-specific files, flags, and environment variables before launching the harness (pi, Claude Code, or Codex CLI).

The `.agents` protocol

Outfitter stores and exchanges all agent configuration in the vendor-neutral Dotagents .agents protocol (pinned at revision 502a9d5). Outfitter does not define its own authored configuration format: a .agents/ tree is useful without Outfitter, and any existing .agents/ tree is usable by Outfitter without conversion.

.agents/
  agents.md            # shared operating context
  system-prompt.md     # base system prompt
  mcp.json             # MCP server configuration
  models.json          # model configuration
  agents/<id>/agent.md # agent definitions (+ optional config.json)
  agents/<id>/skills/  # skills private to one agent (also knowledge/, commands/)
  agents/<id>/mcp.json # per-agent MCP config (discovered; projection deferred, #183)
  agents/<id>/hooks/   # reserved namespace (not yet resolved)
  skills/<id>/...      # Agent Skills packages
  tasks/<id>/task.md   # named execution contracts
  knowledge/...        # reference documents
  commands/...         # slash commands

Resources

The protocol resources Outfitter resolves and composes:

Agent — a definition at agents/<id>/agent.md (plus optional config.json) describing an identity and its loadout: the skills, subagents, MCP servers, extensions, plugins, model, thinking level, and tools it runs with. The agent is what you run. See Agents.
Skill — a capability package under catalog-wide skills/<id>/ or agent-local agents/<agent-id>/skills/<id>/, with instructions, references, scripts, and assets. See Skills.
Knowledge and commands — reference documents and slash commands shared across runs.

Tasks — tasks/<id>/task.md execution contracts, structured inputs, and baking — are the subject of a separate upcoming RFC and are not part of this end state. See Tasks.

Profiles, personas, and subagents

Three related terms, none of which is a settings key or a separate file format:

A profile is just an agent and its loadout. “The engineer profile” is the engineer agent with everything it composes. There is no profile.yml and no profiles: map — the loadout lives on the agent.
A persona is a convention, not a resource: one portable, committed Markdown document per persona — docs/personas/platform-lead.md for a project’s own readers, or ~/.agents/personas/platform-lead.md for a reader who outlives one repository — appended at launch to a shared review agent, or pasted into any tool as stakeholder context. Swapping the file swaps the persona.
A subagent is an agent projected into the harness’s native delegation mechanism, selected in another agent’s subagents loadout. A leader agent delegates to local coding-harness subagents or to issue- and action-backed subagents.

The same agent definition can be run directly or selected as a subagent elsewhere; its loadout decides what it composes.

Layers

Resources resolve across layers, following the protocol’s overlay semantics:

<project>/.agents/ — the workspace layer, committed with a project.
~/.agents/ — the global layer for one developer.
Remote sources — pinned .agents payloads from catalog repositories, in configured order.

Resources merge by ID: a workspace skills/wiki/ overrides a global or remote skills/wiki/. Agent-local skills merge by owner and ID, so agents/actions/skills/debug/ is distinct from agents/reviewer/skills/debug/; the selected agent’s local winner takes precedence over catalog-wide skills/debug/. JSON files such as mcp.json and models.json follow the protocol’s JSON merge behavior. Standalone .agents repositories — where the repository root is the payload — are the primary way to develop and share layers; see Catalogs and Local development.

Settings scopes

Outfitter’s own settings live inside the .agents tree as settings.yml, with a flat, gitignored settings.local.yml beside it for personal machine-local overrides:

~/.agents/settings.yml — user defaults, plus optional ~/.agents/settings.local.yml.
<project>/.agents/settings.yml — committed project settings.
<project>/.agents/settings.local.yml — personal, uncommitted overrides for that project. This flat file replaces the old nested project-local directory scope.

Settings declare the default agent and harness, resource sources, and launch behavior — not resource selection, which lives on the agent. Removing the settings files leaves a pure protocol tree. See Settings.

One resolver

Listing, validation, running, and dumping all share one resolver. What outfitter list shows is what outfitter run launches and what outfitter dump writes. See Dump.

Adapters

An adapter projects composed resources into one agent CLI’s native configuration — files, command-line flags, and environment variables. Pi is the primary and most complete adapter; Claude Code and Codex CLI adapters are supported with gaps. When an adapter cannot honor part of a composition it warns to stderr, or fails when --strict is set. See the adapter support matrix.

State persistence

Agents write state during a run — auth, native settings, plugins, sessions. Each adapter declares the state paths it understands and how writes are handled (symlink, discard, warn, error, or prompt), so useful state survives future runs. See State persistence.

Layer precedence

When several layers define the same resource ID or setting, higher layers win:

Project-local settings (<project>/.agents/settings.local.yml)
Project (<project>/.agents/)
User (~/.agents/, with settings.local.yml above settings.yml)
Cached remote sources (in configured source order)
Built-in defaults