subagents

name	subagents
description	Spawn subagents and dynamic workflows well — size each task to the context window (~33% of 1M target) and pick the right model tier. Use whenever delegating work to subagents, launching a Workflow, or deciding how to split a task across agents.

Subagents and Dynamic Workflows

The orchestrator delegates execution and keeps its own context lean. The two decisions that make delegation work are how big to make each subagent's task and which model runs it. Getting the size right matters more than anything else: it is the difference between coherent, trustworthy work and hallucinated, low-quality work.

This skill is self-improving. When you discover a better sizing heuristic or a new calibration point, update it.

The context budget: aim for ~33% of the 1M window

• Fable, Opus, and Sonnet all have 1,000,000-token context windows. So ~33% ≈ 330k tokens.
• These models begin degrading around 25–33% window fill. Past ~33%, distrust the output — that is where hallucinations, silently-dropped requirements, and quality regressions appear. Do not trust results from a context much fuller than a third.
• Design each task to LAND near 33% by the time it finishes — not to blow past it. The target is the end state of a healthy task, not a ceiling you race toward.
• Soft rule, not hard: if an agent is genuinely near the end of its task when it crosses 33%, let it finish — interrupting or compacting mid-task is worse than mild degradation at the finish line. What you must avoid is an agent still doing substantive work at 50%+.

Sizing: the tradeoff to balance

• Too small → over-parallelization. Many agents each holding a partial view produce fragmented, less coherent work with integration seams, duplicated context loading, and coordination overhead.
• Too big → the context overflows past ~33%, performance degrades, and either the quality drops (hallucinations, missed requirements) or the agent dies mid-task with its work wasted.
• Right-sized = one coherent deliverable an agent can hold entirely in a healthy (<~33%) context, including all the reading and gate-iteration the task requires.

Estimate a task's token cost BEFORE you spawn

Add up the big consumers:

• Startup: the agent's system prompt + your task prompt + any skills it loads. A rich task prompt plus 3–4 skills is easily 20–60k tokens before it does any work.
• Reading: each file ≈ characters/4 tokens. Design docs, research digests, and broad source-tree reading add up fast — a large design doc plus a digest can be 30–60k on its own.
• Iteration (usually the silent killer): every tool result accumulates and is replayed into context on later turns. Gate runs (lint/tsc/test/build), git diff, and test/build logs each land in full. A build-until-green loop can add 100k+.
• Output: cumulative generated tokens (code + reasoning) count too, though the input side normally dominates.

If the honest sum lands well past ~330k, the task is too big — split it or scope it down before spawning.

Empirical calibration (this repo — keep this section growing)

• A full feature-lane build from scratch (migration + business layer + routes + tests + gate-until-green) does not fit one healthy agent: first-attempt lane agents reached ~33% (330–337k) and were still mid-build. Lesson: split a lane into coherent sub-slices, or plan an explicit checkpoint/resume, rather than asking one agent to build the whole thing.
• A resuming agent — fresh context, pointed at the on-disk state plus the design doc — finishing the remainder of a lane sat at only ~23–24% (~232–244k) partway through. Much healthier, because it skips re-deriving the entire design from sources.
• Implication for feature work: prefer design (1 agent) → build coherent sub-slices (parallel, one module/layer each) → exhaustive review (fan-out) over "one agent builds the entire lane."
• A foundation-lane build (new test harness + a 36-entry coverage manifest + gates + draft PR, ~1.1k added lines) finished healthy at ~251k (25%). Sibling gap-fill lanes (one seed section + manifest entries + browser verification each) averaged ~187k, and a read-only design investigation over ~4k lines of sources landed at ~172k — all comfortably single-agent sizes.
• A settled-pattern feature split into two dependent slices landed both healthy: the data slice (2 migrations + prod seed + business layer + MCP + 31 tests, ~1.5k lines) at ~229k (23%), the UI/display/dev-seed/docs slice at ~319k (32%) — the second finished fine but had no headroom left; a third concern would have broken it. The follow-up 10-finding fix pass (one UI interaction redesign, a 3-path authorization fix, test strengthening, a seed refactor, plus a database reseed) also fit one agent at ~326k (33%).
• Browser verification passes are cheap: a 9-flow E2E run landed at ~165k and a 6-check targeted re-check at ~121k. A two-platform mobile verification (build wiring, both devices, Maestro suite, new flow) consumed ~398k over 3h — past the healthy line. Codified since: the mobile-verification skill now prescribes a shared bring-up followed by one verification agent per platform.
• A 5-dimension review with per-finding adversarial verification (5 Sonnet finders + 12 verifiers) totaled ~1.47M tokens across 17 agents and produced 12 findings, 10 of which survived and were real — including a critical race a single reviewer had no lens to catch. The per-finding verify stage rejected 2 plausible-but-wrong findings; keep it.
• An urgent test-determinism fix lane (empirical diagnosis, seed + spec fixes, simulated-condition proofs, a full E2E suite run, draft PR) landed at , and a (a seed re-anchor plus three new journey specs with death-simulation proofs) at — comfortable single-agent sizes.

Measure a live or finished agent's context

Transcripts record per-turn token usage. Extract just the numbers — never read the JSONL wholesale (it overflows your own window). The last turn's input_tokens + cache_creation_input_tokens + cache_read_input_tokens is that agent's current context occupancy:

python3 - <<'PY'
import json, os
WINDOW = 1_000_000
FILES = {"<agent-id>": "<label>"}  # fill in ids → labels
for aid, label in FILES.items():
    f = f"/path/to/tasks/{aid}.output"
    if not os.path.exists(f): print(f"{label}: no transcript"); continue
    last = peak = out = turns = 0
    for line in open(f):
        try: o = json.loads(line)
        except: continue
        m = o.get("message"); u = m.get("usage") if isinstance(m, dict) else None
        u = u or (o.get("usage") if isinstance(o.get("usage"), dict) else None)
        if not u: continue
        ctx = u.get("input_tokens",0)+u.get("cache_creation_input_tokens",0)+u.get("cache_read_input_tokens",0)
        if ctx: last, peak, turns = ctx, max(peak,ctx), turns+1
        out += u.get("output_tokens",0)
    print(f"{label}: turns={turns} last={last:,} ({100*last/WINDOW:.0f}%) peak={peak:,} out={out:,}")
PY

Use it to watch a long-running agent's trajectory. If one is approaching ~33% while still far from done, decide deliberately: let it finish (if nearly there) or have it checkpoint its state to disk and hand off to a fresh agent.

Shrink a task's footprint

• Point the agent at specific docs and sections, not "read everything."
• Have agents return distilled conclusions, not raw file contents — the summary is the deliverable, not the transcript.
• Split along natural seams (by module, by layer, by review dimension) — but not so finely that coherence breaks. Cohesive or dependent work stays in one agent.
• Use pipeline()/parallel() for genuinely independent units; keep dependent work sequential in one agent.
• Resume interrupted work with a fresh agent + a summary and the on-disk state, not by replaying a giant transcript.
• Keep the orchestrator's own context lean: delegate, store durable state in the scratchpad ledger, and don't read what a subagent can read for you.

Model selection

Tier names are version-agnostic: fable, opus, and sonnet are Claude Code model aliases that always resolve to the current model of each family — never pin a specific version in this skill.

Match the tier to the work:

• Fable — reserved for the highest-judgment work only: the main orchestrator session, architecture, UX/UI design, the hardest coding tasks and problems, and final QA — the last pre-merge audit of a lane, judging with real discernment whether the work truly meets our quality bar. Work is never merged on a lower tier's word alone.
• Opus — the default workhorse for everything below that bar: regular feature builds and implementation, fix passes, design-doc drafting within a settled architecture, code review with ≤5 subagents, and agent-browser end-to-end manual testing.
• Sonnet — code review with ≥5 subagents (multi-dimension adversarial reviews) and similar wide fan-out work.

Design work splits across the tiers by how much invention it demands. Invention-type design — a new pattern, a new architecture, a shape nothing in the repo prefigures — always runs on Fable. Design that applies a settled pattern to a new surface, where drafting is mostly grounded investigation, sits on the edge: make a fresh judgment call each time between Fable designing directly and Opus drafting for Fable to personally adjudicate against the primary sources. Neither arrangement is pre-approved for the edge — the call is part of the work.

When a tier is unavailable (a weekly or rate limit), substitute the nearest capable tier and record the substitution in the ledger. (Standing example: when Fable's weekly limit is reached, Fable-tier work runs on Opus at xhigh until tokens return.)

Reasoning effort

Pair every model with a fixed reasoning effort — always:

• Opus → xhigh.
• Sonnet → xhigh.
• Fable → high.

(When a tier is substituted for another, the effort follows the model actually running: Opus standing in for Fable still runs at xhigh.)

How to set it:

• Dynamic workflows (agent()): pass effort on every call alongside model — e.g. agent(prompt, { model: 'sonnet', effort: 'xhigh', schema, ... }). Omitting effort inherits the session effort, which is not guaranteed to match this rule, so always set it explicitly.
• The Agent tool: it has no per-call effort parameter — a directly-spawned subagent inherits the current session's reasoning effort. You cannot raise a single Agent-tool spawn to xhigh in isolation. To guarantee a required effort, either launch that agent from a workflow (where effort is settable) or run the whole session at the target effort. Call out this limitation whenever it bites (e.g. a directly-spawned agent-browser Opus run that you want at xhigh).