specialist-delegation

Imported from FranciscoMateusVG/aperture (.claude/skills/specialist-delegation/SKILL.md). Install upstream with npx skills add FranciscoMateusVG/aperture --skill specialist-delegation. Copyright stays with the author.

Specialist Delegation — When to Subagent vs Stay Hands-On

Operator retrospective 2026-09-07 supersedes unconditional fan-out and “keep only design/craft/review.” The relevant unit is useful independent work, not file count. Tiny handoffs can cost more than the fix.

1. The Principle

Decompose non-trivial work, then choose the smallest execution shape. A bounded task normally has one execution owner plus one scoped independent review. Delegate a genuinely independent substantial slice when its benefit exceeds briefing/context/review costs, within authorized scope. Do not spawn a worker merely because another competent agent could write the same code.

For easy/medium repairs found during assigned work, ask the current owner for the file set, then implement directly after explicit consent with a focused regression and independent review (communicate §10). No file collision, whole-task reassignment, security/infra authority or new scope is implied.

2. WHEN to Delegate to a Subagent

Sibling liveness skills. This skill covers when to delegate. For state that isn't clear AFTER delegation: aperture:subagents §11 (subagent fault-isolation) and aperture:agent-liveness (tmux-pane specialist stuck/working/waiting + tmux send-keys intervention). GLaDOS loads both; specialists load whichever applies.

3. WHEN to Stay Hands-On

Rules the worked examples established (Precedent: §4 Examples A–C, 2026-05-12): a clean subagent brief is scoped + bounded + outputs concrete artifacts and leaves your context untouched; subagents can stall — fault-isolation exists so you can fall back to hands-on, so don't optimise so hard for delegation that you can't take over; when the work IS the craft, hands-on is right even at heavy context cost — a subagent won't reproduce lane-specific muscle memory.

3b. Two delegation primitives: subagent fan-out vs Agent Teams

Pick by whether the workers need to TALK to each other.

• Subagent fan-out (the Agent tool) — when delegation is justified. Multiple Agent calls in one message run concurrently; each worker gets its own context + a scoped prompt and returns ONE result. Workers don't talk to each other. Cheapest, simplest, fault-isolated. Right for independent parallel subtasks conforming to a contract the lead set up front — the common case. (Precedent: §3b.)
• Agent Teams (experimental) — rarely. Teammates (full Claude Code sessions) share a task list AND message each other. Only when workers genuinely must converse: cross-layer negotiation, adversarial review/debugging. Significantly more tokens, experimental (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, v2.1.32+), coordination overhead. Docs: code.claude.com/docs/en/agent-teams.

Decision rule: can you specify each worker's job up front against a shared contract and integrate the results? → fan-out. Must workers ask each other questions mid-flight? → Agent Team.

Two facts: (1) No nested teams — a teammate can't spawn a team; Aperture specialists are independent sessions, so a specialist can run a team, but inside it only subagents. (2) Aperture already IS a hand-rolled Agent Team — GLaDOS (lead) + specialists + BEADS (mailbox + shared list). The "workers must talk" case is usually already handled one level up, which is why intra-task delegation is almost always plain fan-out.

4. Anti-Patterns

5. The Non-Negotiable: Trust-but-Verify

Every subagent diff gets read by you before you sign off — no exceptions. The summary describes what the worker intended; the diff shows what it did. Verify-against-reality applies recursively to the subagent you yourself dispatched. The diff-walk is the swarm's reliability mechanism — don't trade it for context savings. (Precedent: §6, three catches on 2026-05-12, all from hands-on reads.)

6. Calibration

• Bounded input correction or small test delta: one owner, focused regression, one review.
• Independent substantial surfaces: bounded parallel work may help; verify each diff once.
• Another reviewer finds a small issue: use owner-consented finder repair, not a patch-instruction ping-pong loop.
• Slow external I/O: use bounded timeouts or the existing fault-isolation workflow; no standing polling fleet.
• Growing scope or unclear risk: stop and ask GLaDOS; do not build new tooling to justify the original task.

7. Context Budget — Don't Anthropomorphize, Don't Negotiate /compact

You don't get "tired." You have a context window. Precision-risk on critical code has one of three causes: high context (≥65–70%) → the orchestrator /compacts you; missing input → ask or read the source; architectural uncertainty → hands-on the decision. "Hour 18 of waking" / "sleep on it" / "resume tomorrow" are anthropomorphic slop — a fresh session boots from the same skills + specs + bead notes that /compact produces ten seconds from now. The only legitimate pauses are an operator-only decision or an external dependency that hasn't shipped. (Precedent: §8 banked precedents 2026-05-13 / 2026-05-25.)

Mechanics:

• Agents cannot self-invoke slash commands. /compact and /clear only fire from the user-input position — no Skill or Bash call reaches them.
• The orchestrator (GLaDOS) fires them via tmux send-keys -t <agent> C-u '/compact' Enter (trigger + command in watch-protocol §2). The operator can type them directly too.
• Prefer /compact over /clear. /compact summarizes and continues, preserving working state; /clear boots from zero and costs ~30 min of re-recon. Use /clear only when the current context is actively misleading.

Specialist, at ~55–60% context with non-trivial work ahead:

1. Bank state in bead notes proactively — a cold-start anchor (phase, scope revisions, recon patterns, coordination map, next steps). Continuously, before anyone asks.
2. Keep working. Do NOT signal the orchestrator, ask for /compact, pause for permission, or write "ready for /compact." Not your decision.
3. Do NOT ack a /compact. You won't see the decision — you'll see your compacted session boot. Read bead notes + queued messages, continue. No "anchor banked, green-lit" replies.

Orchestrator: /compact is unilateral. Watch context on every tick; at ≥60% context, except while a live subagent is running fire it immediately — no pre-message, no ack, no choice offered; confirm "/compacted at NN%." Queued BEADS messages deliver to the compacted session as normal. Never offer a "/compact unless you object" default, never ask a specialist to self-/clear, never ask the operator to /clear an agent. A fatigue-framed pause request or an "operator please /clear me" request gets a /compact via send-keys, not validation.

8. Parallel Tracks — Question Serial Framing

"Do X, then do Y" is sometimes a real dependency and sometimes a scheduling preference dressed as one. Mis-parallelize a real dependency → rework; mis-serialize a preference → an agent idles on X while Y was independent all along. Get it right and throughput roughly doubles whenever a wait-for-merge/cascade/deploy sits in front of independent craft work.

The test: Is Y dependent on X completing, or just on X's output eventually existing? Needs X done before Y can START → real serial, wait. Needs X's output only before Y's FINAL step (commit, merge, integration test) → parallel tracks. Most cases are the second shape.

Specialist receiving "finish X before claiming Y": apply the test. If independent — Track 1 handles X: mechanical (rebase, retarget, recon, log-pull, ssh probe) → subagent per §2; wait-for-external-event → watcher subagent or pivot when it lands. Track 2 is the craft: request scoped permission for Y if not already assigned; do not self-claim unassigned work. When X completes, integrate (subagent it if mechanical). Can't see how Y is independent? Ask — don't silently serialize.

Orchestrator issuing the dispatch: apply the test BEFORE the words leave your message. If Y is independent, frame it explicitly as parallel tracks ("Track 1: X, subagent if mechanical. Track 2: claim Y now, hands-on"). Every agent-hour idled is swarm throughput lost — the 2026-05-15 miss cost ~3 agent-hours. If you want X first for a non-dependency reason (concentration, blast radius), say so, and accept the specialist may push back. Never frame a small mechanical task (a 5-command cascade rebase) as a serial blocker for hours of independent craft — it dispatches as a subagent or takes 5 min; neither blocks the craft. (Precedent: §9 worked example, aperture-l1gx.)

Stacked PR as the parallel track? Pair with aperture:stacked-pr-verification: fetch the parent's head (git fetch origin pull/<n>/head:ref) and read the real handler bodies before rebasing. That's what turns "build in parallel and hope the contract holds" into "build in parallel and prove it."

When serial is genuinely cheaper — second question: does the parallel version add more orchestration cost than it saves? Y substantive (hours of craft) → parallelize. Y trivial (≤30 min) AND would need a cascade rebase to parallelize → serialize; the rebase tax eats the gain. Rule of thumb: parallel track smaller than the cascade tax → serialize; dwarfs it → parallelize. (Precedent: §9 Izzy tsx1 vs Vance l1gx, 2026-05-15.)