Subagents

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

A subagent is a protocol agent projected into the harness’s native delegation mechanism, so a run can hand focused work to a separate context. You declare subagents in an agent’s loadout — the subagents field of its agent.md frontmatter or config.json — not in any settings map.

---
name: engineer
subagents: [code-reviewer, explorer]
---

Each slug resolves to an agents/<id>/ definition across layers like any other resource. At launch the adapter projects the selected definitions into the harness’s subagent surface:

• Claude Code — materialized into the harness’s agents directory so they are invocable as native subagents.
• Pi — registered through Pi’s subagent extension mechanism.

See the adapter support matrix for current coverage.

The four delegation boundaries

Delegation is one concept — an agent hands a unit of work to another agent identity — with four boundaries it can cross. The composition being delegated to is ordinary .agents resources in every case; what changes is where the delegate runs and how it reports back.

Boundary	Mechanism	Reports back via	Use when
In-run	Harness-native subagents (Claude Code’s agents directory, Pi’s subagent extension), declared in the leader’s subagents loadout	Inline, same session	Exploration, review, parallelizable work needing a fresh context now
CI-backed	A GitHub Actions run: dispatch a workflow that does the work, or assignment-as-trigger — assign the issue/PR to a machine account whose events start the workflow (runs on hosted or self-hosted runners)	A comment or PR from the run; optionally a session-transcript artifact (adapter-dependent)	Work that should run asynchronously with its own token scope and an auditable trail
Cluster-backed	A Kubernetes subagent Job in the delegating agent’s namespace, sharing its service account and quota (in-cluster agents)	The tracking issue/PR, or the delegating agent’s next tick	Cluster-local work; one bounded Job per delegated unit or per incoming event
Peer agent	Notify or assign a persistent resident agent — its notifications channel is the intake	Wherever the peer works: the issue, the PR, the thread	Standing responsibilities owned by an always-on identity rather than one-off runs

A leader’s loadout declares in-run delegates as subagents; the other three boundaries are reached through the tools the leader already has (dispatching a workflow, assigning an issue, filing work where a peer listens). Keep each delegate bounded — one job, clear inputs, a defined deliverable back to the caller.

Delegation patterns

Two patterns recur on top of the boundaries:

• Adversarial review. Delegate critique to a differently composed identity than the author — a different model, persona, or loadout, often a machine account, so the review carries no author bias and a visibly separate identity. The personas convention supplies the reviewer shape; the CI-backed boundary supplies the separate identity and audit trail.
• Singleton coordinator. Invert the fan-out: you always talk to one persistent agent (a machine account listening to its GitHub notifications), which keeps a bounded, prioritized queue and always chooses what to work on next. Everything else — CI runs, cluster Jobs, in-run subagents — is its delegation target. The human interface stays one conversation; concurrency lives below it. “Assign the PR to the agent” becomes the entire UX.

When to give an agent subagents

• One focused agent — a single agent doing the work directly. Prefer this default; delegation adds latency and context loss.
• One leader managing subagents — a coordinating agent that delegates exploration, review, or parallelizable work.

Authoring guidance

• Give each subagent a crisp description — the leader uses it to decide when to delegate.
• Keep subagents bounded: one job, clear inputs, a defined deliverable.
• Don’t duplicate skill procedures into subagent definitions; a subagent can select and use skills through its own loadout like any agent.