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

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.

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, and where the agent is least confident — 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 delegation is opaque until it ends, and the three states you most need to distinguish — working, stuck, and dead — look identical from outside. Checkpoints are also what make recovery possible when it dies mid-flight (see the salvage-subagent-transcript skill); an agent with no progress trail leaves you nothing but its workspace diff to reconstruct from. Keep each checkpoint short — a few lines, not a narration; the distilled-return rule (§0.5) applies here too.

3a. Which gates to run (the acceptance checks)

Gates are declared in the host's gate manifest — see the project-gates skill for the schema (categories: always / logic / safety-specific; triggers; commands). Here, the rule for using them:

• Always-gates run every delegation. Run logic / safety-specific gates whose trigger matches what the change touched — pick what the task touches; don't run all by reflex, and don't skip a matching one.
• Gate truth is the command's tool output, never the agent's prose (§0.2): observe the exit status yourself before treating a gate as passed.

4. Orchestration patterns

• Single delegate — spec → run → inspect the diff (bound the expected size) → run the §3a gates the task touched → commit.
• Parallel fan-out — independent tasks in one batch (background). Cap concurrency (a handful at a time, ~3–5). If they write, give each an isolated workspace (a git worktree, a separate clone, or your harness's isolation mode), then join: merge each one, and re-run the always-gate on the unified tree before committing (per-workspace green ≠ integrated green).
• Pipeline — produce → verify per item, no barrier, when stages don't need the whole set.
• **Panel /

Content truncated.