Building a subagent fleet for my persistent agent environment

A subagent in my NanoClaw agent fleet is one Markdown file: a description that routes work to it and an output format that is all its caller ever sees. Two things carry it. Everything else has a safe default.

My persistent agent environment has a fleet of subagents: planner, general, fact-checker, refuter, and verifier; planner is the worked example in this note. In my setup, an agent that owns the goal spawns each subagent for one task, and I write each subagent definition: frontmatter plus a system prompt in one file that the harness loads and the orchestrator calls. Take planner, which turns a goal into an executable plan. It shows what is load-bearing in every subagent definition, and how little that is.

The description routes it

The description is how a caller decides to hand work to this subagent. So planner's description says what it does (split a goal into units, decide what runs in parallel, assign each to a subagent), what to hand it (a spec with success criteria, a task description, and the agent's goal), and when: before anything that takes several subagent calls or fills a recurring slot, when "what should I actually run, and in what order" is the hard part. The routing that matters most is simple: use it for a job big enough to need a plan.

The output format is all the caller sees

The final message is data the caller executes. planner spawns no subagents of its own. Its whole output is the plan. So the output format is the most important thing in the subagent definition:

## Goal / ## Success criteria   (measurable, each check can fail)
## Plan
### Phase 1  [parallel: N units | sequential]
- [ ] <unit> -> `<agent>` | inline (`<skill>`)   returns: <one line>
## Fan-out   (mermaid: orchestrator + one node per unit)
## Assembly / Done-condition / Schedule / State / Risks

The system prompt opens by saying so ("your final message is the return value your caller reads, the plan itself, no preamble") and the rest of the prompt just serves it.

One job, isolated

planner has one job: planning. Running the plan belongs to the caller. It routes every unit to a sibling (general, fact-checker, refuter, verifier). That division is the point, and half of it is context isolation: planning happens in planner's own context, so the caller spends its context executing while planner makes the decisions. The findings land in the caller's context, where the deliverable gets built, and each subagent keeps its own isolated context.

Everything else inherits

Two things carry the subagent. Everything else has a safe default, and you override only where it pays off. planner is one of the few that does: its model is pinned up to Opus because a bad plan is the most expensive thing a run can produce. Most of the roster omits the field and inherits the group's tier. It uses a denylist on the built-in host tool server, granting access to every tool its group connects to and blocking message sending and config changes.

The bottom line

Decide what work to route to a subagent and what it returns, and you have defined the subagent. This is the shape the spec leaves for later. The spec says why an agent exists, and the subagent definition describes how to build each subagent. Both run on the fleet that sits behind one gateway. Same instinct as the verification gate: define the contract first, then let the subagent fill it.