Agent orchestration: delegare a sub-agent senza perdere il filo

Quando GSD spawna un sub-agent per fare ricerca, planning, execution o verification, sta facendo una cosa apparentemente semplice ma con conseguenze importanti: delega un pezzo di lavoro a un'istanza Claude separata, che ha context window pulito e non vede la conversazione principale. Questa è la differenza fra "Claude che fa tutto in un thread" e "Claude che orchestra agent specializzati".

Disclaimer di indipendenza: non sono affiliato a qrx né ad Anthropic. Tutto quanto segue è esperienza diretta su circa 250 spawn di sub-agent sul mio portfolio brownfield nelle 19 fasi GSD eseguite.

Perché delegare a sub-agent

Tre ragioni concrete:

1. Context isolation. Una sessione tipica con planner Opus legge 200+ file (CONTEXT, RESEARCH, UI-SPEC, AI-SPEC, REQUIREMENTS, STATE, codebase maps). Se questo tracking avvenisse nella conversazione principale, dopo due-tre fasi il context window sarebbe saturo. Spawnare il planner come sub-agent isolato mantiene la conversazione principale leggera.
2. Parallelism. Sub-agent indipendenti possono girare contemporaneamente. Wave 2 di Phase 20 ha spawnato backend executor + frontend executor in parallelo: 40 ore di lavoro stimato compresse in ~3-4 ore wall-clock.
3. Specializzazione. Sub-agent come gsd-planner, gsd-plan-checker, gsd-executor hanno prompt ottimizzati per il loro task. Un singolo "general-purpose" agent sarebbe meno efficace su ognuno dei task specifici.

Anatomia dello spawn

Lo spawn avviene via tool Agent di Claude Code. Esempio illustrativo del pattern usato da /gsd-plan-phase:

Agent(
  description="Plan Phase 20",
  subagent_type="gsd-planner",
  model="opus",
  prompt="...prompt completo con context, files_to_read,
          istruzioni specifiche, output expected..."
)

I parametri chiave:

• description: stringa breve per logging/UI.
• subagent_type: tipo di agent (deve esistere in ~/.claude/agents/<name>.md con prompt template).
• model: opus / sonnet / haiku. Choice impatta cost + capabilities.
• prompt: il messaggio che il sub-agent riceve come primo input. Deve includere tutto il context necessario perché il sub-agent non vede nulla altro.

Opzionale: run_in_background: true per spawn asincrono (l'agent principale procede mentre il sub-agent lavora, notifica al completamento).

Il prompt è tutto

Il sub-agent ha context isolato: vede solo cosa gli scrivi nel prompt. Un prompt incompleto produce sub-agent che chiede chiarimenti (impossibile risposta - è isolato) o che ipotizza male.

Pattern best per prompt sub-agent:

1. Objective chiaro: una frase che dice cosa il sub-agent deve produrre.
2. Files_to_read espliciti: lista di path che il sub-agent deve leggere prima di iniziare. Senza questa lista, sub-agent non sa quali file aprire.
3. Decisioni LOCKED: tutte le decisioni già prese (in CONTEXT, AI-SPEC, UI-SPEC) sintetizzate inline nel prompt. Anche se sono in files_to_read, ribadirle inline evita che sub-agent le ignori.
4. Output expected: formato dell'output che il sub-agent deve produrre (es. "End with ## PLANNING COMPLETE followed by ...").
5. Vincoli: cosa NON fare (es. "Do not spawn other sub-agent", "Do not modify CONTEXT.md").

Esempio reale: spawn researcher per Phase 20

Riassunto del prompt che ho dato al researcher di Phase 20 (sintesi):

Objective: ricerca tecnica su 16 macro-aree
  (framework upstream Superpowers/GSD, schema.org 2026, Mermaid CLI,
  Apache POI/OpenPDF, Wikidata, Buttondown, i18n bulk, ecc.)

Files_to_read:
  - .planning/phases/20-.../20-CONTEXT.md (PRIMARY)
  - .planning/phases/20-.../20-AI-SPEC.md
  - .planning/phases/20-.../20-UI-SPEC.md
  - .planning/REQUIREMENTS.md
  - .planning/STATE.md
  - CLAUDE.md (project root)

Decisioni LOCKED (sintesi inline):
  - D-PG-1: Hub + 2 sub-pages (NOT hub-only)
  - D-18: Code samples HEAVY
  - D-22: AI Citations Q&A blocks
  - ... [resto delle 27 D-XX]

Output expected:
  - 20-RESEARCH.md con 16 sezioni + Validation Architecture
  - End with ## RESEARCH COMPLETE
  - OR end with ## RESEARCH BLOCKED + blocker

Risultato: il researcher è andato in timeout dopo 67 minuti senza output. Ho dovuto scrivere RESEARCH.md manualmente (vedi sezione Recovery da timeout più sotto). Lezione: il prompt era troppo ambizioso (16 macro-aree). Mitigation: avrei dovuto splittare in 2-3 research separate, ognuna su 5-6 aree.

Recovery da timeout sub-agent

Sub-agent hanno tempo limite (tipicamente 60+ minuti). Task troppo grandi vanno in timeout senza output finalizzato. Workflow recovery:

1. Verifica disk: anche se il sub-agent è timed-out, potrebbe aver scritto file parzialmente. ls sull'output path per verificare.
2. SendMessage al sub-agent (se ancora vivo, dipende runtime): chiedere "concludi immediatamente con quanto raccolto".
3. Fallback manuale: scrivere l'output direttamente come orchestrator, basandosi su context disponibile + knowledge base interna.
4. Re-spawn con scope ridotto: nuova spawn con prompt più stretto (es. ricerca solo 5 aree invece di 16).

Sul portfolio ho usato fallback manuale per Phase 20 RESEARCH.md (986 righe scritte direttamente in 30 min vs il timeout di 67 min del sub-agent). Token saving + output focalizzato sono stati il guadagno.

Pattern: wave-based parallel spawn

Quando più sub-agent devono girare in parallelo (es. Wave 2 di Phase 20 con backend + frontend executor), il pattern è:

1. Verifica che file_modified dei plan paralleli siano disjoint.
2. Spawn N sub-agent contemporaneamente (tool Agent in parallelo).
3. Ognuno ha output_file diverso (no race su scrittura).
4. Attendi completamento di tutti (notifiche async).
5. Verifica output di ognuno + commit batch.

Speedup misurato sul portfolio: 3-5x rispetto a sequenziale. Costo: complexity in orchestration (devi tracciare N notifiche), e risk di race se file_modified hanno overlap nascosto (es. blog-manifest.json modificato da entrambi i plan paralleli).

Choice del model: Opus, Sonnet, Haiku

Sub-agent può girare su Opus, Sonnet o Haiku. Decision matrix sul portfolio:

• Opus 4.7: planner, plan-checker, architect - task che richiedono deep reasoning su tradeoff complessi. Cost: ~5x Sonnet.
• Sonnet 4.6: researcher, ui-researcher, executor - task di scrittura tecnica + esecuzione disciplinata. Best balance cost/quality.
• Haiku 4.5: batch lookup, doc parsing, simple verification - task ripetitivi su contenuto semplice. ~3x cost saving vs Sonnet.

Cost optimization concreto: una fase con 8 plan executor su Sonnet (€~5 totale token cost) vs su Opus (€~25) = €20 saving per phase. Su 19 phase l'anno = €380 saving senza degradazione qualità.

Anti-pattern: sub-agent recursion

La tentazione: sub-agent A spawna sub-agent B che spawna sub-agent C. Problema: ogni livello aggiunge tempo + token + complessità debug. Se C timeout, sai dove perdi context? Sub-agent recursion è quasi sempre indicazione che task andrebbe splittato a livello orchestrator, non delegato in cascata.

GSD design impone: orchestrator (la conversazione principale) spawn sub-agent direttamente, sempre flat structure. Mai recursion. Wave-based parallel è il pattern preferito per scaling.

Sub-agent isolation con worktree

Per task che modificano file (executor, refactor agent), c'è un'opzione avanzata: isolation: "worktree". Crea un git worktree temporaneo, sub-agent lavora isolato lì, cleanup automatico se no changes, altrimenti returns path + branch.

Vantaggio: N executor paralleli su stessa codebase senza race file. Non sovrascrivono file altrui perché ognuno ha il suo worktree.

Caveat: git stash non funziona in worktree perché refs/stash è shared. Pattern alternativo: git checkout -- <file> per cleanup. Lezione imparata male: la prima volta che ho usato worktree ho fatto git stash e pull ha tirato dentro WIP da sibling worktree. Frastornante.

Output parsing

Sub-agent restituiscono testo libero. Per orchestrator parsing, convention output marker in coda al messaggio:

• ## RESEARCH COMPLETE + summary 3-5 righe.
• ## PLANNING COMPLETE + N plans + waves + estimate.
• ## GOAL_MET (plan-checker success).
• ## BLOCKER (plan-checker found issues).
• ## EXECUTION BLOCKED (executor stopped).

Orchestrator parsing pattern: cerca marker, ramifica logica. Senza marker convenzionali, orchestrator deve interpretare output naturale - fragile, soggetto a misparsing.

Sessione tipica: orchestrazione di una fase

/gsd-plan-phase 21 tipica spawn questi sub-agent:

1. Researcher (Sonnet, ~30 min, ~50k token).
2. Pattern-mapper (Sonnet, ~15 min, ~25k token) - opzionale.
3. Planner (Opus, ~30-40 min, ~100k token).
4. Plan-checker (Sonnet, ~10 min, ~30k token).
5. Optional iter 2: planner revision (Opus, ~20 min, ~80k token).

Totale: 4-5 sub-agent, ~90-120 min total wall-clock (sequenziale), ~200-280k token consumati. Cost: ~€3-5 per phase planning.

Cosa ho imparato scrivendo questo articolo

La cosa più importante: il prompt è il contratto. Sub-agent è isolato; tutto quello che non scrivi nel prompt non esiste per lui. Tendenza naturale è scrivere prompt brevi ("plan the phase"); risultato sono sub-agent che improvvisano. Prompt dettagliati (300-500 righe per planner) producono output di qualità ma richiedono effort upfront.

Secondo insight: model choice ha impatto subtle ma cumulativo. Per mesi ho usato Opus per tutto. Quando ho switched executor a Sonnet (con planner restato su Opus), qualità executor è leggermente calata su task complessi ma cost è dimezzato. Net effect su 19 phase: budget mensile ridotto del 40% senza perdita visibile in output.

Anti-pattern evitati

• Prompt minimi a sub-agent. Sub-agent non sa cosa non gli dici. Prompt dettagliati pagano.
• Recursion sub-agent. Mai. Splitta a livello orchestrator, mai delegare ricorsivamente.
• Spawn senza output marker convention. Parsing output naturale è fragile. Marker espliciti (## STATUS) salvano il orchestrator.

Una storia ricevuta che vale la pena condividere

Sezione segnaposto. Se hai integrato sub-agent in workflow complessi (positivi o disastri di recursion), scrivimi a federico@federicocalo.dev.

← Cluster precedente: Plan-checker Prossimo cluster: Wave-based parallel execution →