subagent-framework

Subagent framework — delegate work, keep the judgment

How to delegate to subagents and measure whether it worked — getting the leverage of parallel, cheaper agents without letting unverified output into the tree, and without orchestration overhead exceeding the work saved.

Parameterized skill — resolve these slots from the host repo (its CLAUDE.md):

• Gates — declared in the host's gate manifest per the project-gates skill (e.g. .agents/gates.yaml): categories (always / logic / safety-specific), triggers, and commands. Run the always-gates plus those whose trigger matches the change (§3a).
• Delegation log path (its format lives in reference.md → Logging).

Companion skills: independent-expert-review (the review-panel pattern — now its own skill) and the host repo's own conventions skills. Deeper rubric — scorecard, two-tier logging, tooling map — is in reference.md.

0. Principles

1. The main loop owns the outcome. A subagent's output is a proposal, done only after the main loop observes the gate pass.
2. Gate truth comes from tool output, never the agent's prose. A subagent may claim "check 0, tests pass" while the run failed or never happened. Re-run the gate yourself and read the exit status.
3. Right-size the ceremony. Match panel size, scorecard depth, and adversarial-verify to the stakes. The cheapest sufficient process wins.
4. Delegate the work, keep the judgment. Hand off scoped/mechanical/parallel work; keep design, architecture, ambiguity, and final synthesis in the main loop.
5. Spec in, distilled result out. Precise contract (§3); compact structured return so the main loop's context isn't flooded (never read raw agent transcripts into context).
6. Don't build in the main loop — delegate the build. Writing and editing code, mechanical sweeps, and breadth work go to a worker by default (§1). The main loop designs, decomposes, verifies, and commits — it does not type the implementation. This doesn't soften §0.4 — design, architecture, ambiguity, and synthesis stay in the main loop; execution leaves it. Building in the main loop is the exception, and there are exactly two: small stuff (§1a) and delegation that has repeatedly failed (§1b).

Standing rule (validated in practice): delegating to a cheaper/faster model is worth it, but on a strict division of labour — the worker does breadth + execution; the orchestrator keeps design + verification. Every delegation that holds to that split lands cleanly. The failure mode is the inverse — letting a subagent make the design calls or self-certify its own gates. Delegate for breadth and for execution; never delegate the architecture or the gate.

1. When to delegate (default: delegate — see §0.6)

The default is delegate. The question isn't "is this worth delegating?" — it's "does this hit one of the two exceptions below?" The matrix sorts what the worker gets versus what the orchestrator keeps; it is not licence to keep the implementation in the main loop.

1a. Exception 1 — small stuff

• Just do it in the main loop when the task is < ~15 min / < ~100 lines of straightforward change — the contract-writing + logging + verification overhead exceeds the saving. Exception: delegate anyway if parallelism is the goal (N independent items at once).
• Single worker for a bounded task above that line.
• Parallel fan-out / panel only when work is genuinely independent or needs multiple perspectives (see the independent-expert-review skill).

1b. Exception 2 — delegation has repeatedly failed

When delegation keeps failing on a task, the main loop builds it itself. The bar is two distinct failed attempts, not one bad round:

1. Attempt 1 exhausts the §4 repair cap (1 round for < ~1 h tasks, 2 for larger).
2. Before re-delegating, suspect your own contract. A worker that drifts or stalls is usually an under-specified §3 hand-off — missing step outline, unstated design call, scope too wide. That's an orchestrator bug; fix the spec (or split the task) and re-delegate once.
3. If that re-scoped attempt also fails, take it over. Run the salvage decision first — harvest the workspace diff, or discard it — per the salvage-subagent-transcript skill; never merge an unsalvaged workspace blind. Then build from the failure evidence: the failing gate output is now your spec.

Log the fallback in the delegation log with the reason. Repeated fallbacks on the same kind of task are the signal that matters: that task type needs a better contract, a stronger worker tier, or it isn't delegatable (§6) — one-off fallbacks are noise, a pattern is a fix.

2. Roles & model selection

Never let the model default. A sub-agent spawned without an explicit model inherits the session's model, so a session running your strongest tier silently runs every mechanical pass on it too. That is the wrong default in the expensive direction, and it is invisible — nothing in the output says which model ran. State the tier on every delegation.

The rule is the mapping, not the names — a consumer on Anthropic models reads that as Opus / Sonnet / Haiku.

This table is asserted, not measured. The delegation log is what can falsify it — record tier · task class · outcome per delegation and read the pattern by class, with an occasional deliberate downshift so the mapping can move down and not only up. See reference.md → Tier fit.

Pick by role, then map the role to whatever model tier fits your provider:

• Orchestrator — the main loop. Owns design, decomposition, synthesis, and the gate. Use your strongest model; delegate to it only for a genuinely hard sub-problem.
• Worker — the default for delegated coding & structured review. A capable mid-tier model; does breadth and spec'd execution.
• Extractor — trivial deterministic work only (collect a file list, grep-and-summarize, extract symbol names, a pure rename sweep). A cheap/fast model. Never a write task without a following gate — the repair cost of a bad extractor write is high.
• Agent type & access: a read-only search agent for read-only fan-out; a general/implementation agent for review/implementation. Declare the access scope (read-only / propose / write:<globs> / write) per the agent-access skill — least-privilege by default. Worktree isolation only when multiple agents write in parallel (it costs setup time + disk each — not free).

3. The task contract (every delegation states these)

1. Role/goal — one line.

2. Scope — exact files/dirs in/out (exclude generated/vendored code).

3. Context — design intent (link the plan), project conventions, the skill(s) to consult.

4. Constraints — the sub-agent's access scope + isolation per the agent-access skill (read-only / propose / write:<globs> / write; inline vs sub-agent), resolved against .agents/access.yaml; plus any explicit don't-touch. Name what other agents are holding: if a sibling delegation is writing files this one might reach for, list them and require this agent to stop and report rather than edit outside its own set. Silence here is how two agents clobber one file.

5. Acceptance checks — what "done" means (§3a).

6. Output format — compact structured return; "your final message IS the deliverable." Fixed schema for reviews. Report worse-than-expected first: the return leads with what came out weaker than hoped, what couldn't be verified, where the agent is least confident, and an explicit skip list with reasons — a justified skip is a better outcome than silent partial compliance — before the accomplishments. An agent that falsifies its own draft is working correctly, not failing; a uniformly positive report is a smell, not a success.

7. Budget/parallelism — background? batch? worktree?

8. Step outline (the orchestrator's job). For any non-trivial task, design and hand over an ordered, numbered step plan — not just a goal. The orchestrator owns the decomposition and the hard design calls (resolve ambiguous/idiomatic choices before delegating); the worker executes. A goal-only prompt makes the agent re-derive design under-context and drift. Outlining steps is also where you catch that a task should be split or kept.

9. Progress checkpoints — required for anything long-running or multi-step. Have the agent emit a short status at defined points (per completed step, or per milestone in the §8 outline): what's done, what's in flight, what's blocked. Write it where you can read it without interrupting the agent — a log file, a task update, a scratch note — not only in the final return.

   Without checkpoints a long deleg

Content truncated.