aimasteracc/harness-kit/subagent-brief

subagent-brief — Brief sub-agents so they don't silently fail

Purpose

The single most common way multi-agent setups break: a lead spawns a sub-agent and assumes it can wait for messages, coordinate with siblings, or call tools it doesn't actually have. Sub-agents are usually stateless one-shot workers — no inbox, no ability to wait, often without the coordination tools the prompt assumed. A brief that ignores this produces an agent that aborts cleanly or runs on stale assumptions. This skill writes a brief that works.

How to run

1. Clarify the job: what this one agent must produce, and what it needs to start.
2. Resolve coordination to a bus, not to messaging. Inter-agent state goes through a

shared medium the lead controls (memory keys, files, a scratch dir) — never "wait for a message from another agent."

1. Write the brief using the template. Every brief MUST include a degraded-mode paragraph.
2. State the spawn rule to the lead: parallelize only genuinely independent work; spawn

dependent agents only after the lead has verified upstream outputs exist.

The brief template

ROLE: <one-line role, e.g. "API contract extractor">
 
DEGRADED MODE (read first): If your expected coordination tools (messaging, task-update,
swarm/hive tools) are missing or error, do NOT abort. Read your inputs directly from the
paths/keys below, do the work, and write your outputs to the specified destinations. Then end.
 
INPUTS (read these exact sources):
- <file path / memory key / dir> — <what it contains>
- ...
 
TASK:
- <the concrete deliverable, with any constraints / format>
 
OUTPUTS (write exactly here, then stop):
- <destination path / memory key> — <shape of what you write, e.g. JSON schema>
 
DONE = <observable condition the lead can verify, e.g. "file exists and parses as JSON">
Do NOT wait for messages. Do NOT depend on sibling agents. If a needed input is missing,
write a `<dest>.blocked` note explaining what's missing, and stop.

Spawn rules (give these to the lead)

• Parallelize only independent work — siblings with no dependency between them.
• Chain dependents through the lead. Lead spawns A → verifies A's output exists → spawns B

with A's output path in its brief. Never tell B to "wait for A."

• Name every agent so the lead can address it; sub-agents can't address each other.
• After spawning, the lead verifies outputs before the next phase — the bus is the source

of truth, not a message that may never arrive.

Anti-patterns (these silently fail — never write them into a brief)

• "Wait for a message from X before starting." (No mechanism to wait → it aborts or runs open-loop.)
• "Send your findings to <other agent>." (Peers can't receive.)
• "Coordinate with the other agents to divide the work." (No peer channel exists.)
• Spawning N interdependent agents in one batch expecting them to chain via messages.

Notes

• The degraded-mode paragraph is mandatory. It's what converts a fragile assumption into a

worker that finishes regardless of which coordination tools happen to be present.