| name | siae-subagent-development |
| description | Use when dispatching parallel implementer subagents from a validated plan in the current session (vs siae-executing-plans for separate session). Trigger: /forge-implement, implementa il piano, dispatcha task, lancia implementer, subagent, controller-subagent, orchestrazione implementazione.
|
SIAE Subagent Development — Orchestratore Implementazione
╔══════════════════════════════════════════════════════════════════╗
║ ███████╗██╗ █████╗ ███████╗ ██████╗ ███████╗██╗ ██╗ ║
║ ██╔════╝██║██╔══██╗██╔════╝ ██╔══██╗██╔════╝██║ ██║ ║
║ ███████╗██║███████║█████╗ ██║ ██║█████╗ ██║ ██║ ║
║ ╚════██║██║██╔══██║██╔══╝ ██║ ██║██╔══╝ ╚██╗ ██╔╝ ║
║ ███████║██║██║ ██║███████╗ ██████╔╝███████╗ ╚████╔╝ ║
║ ╚══════╝╚═╝╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚══════╝ ╚═══╝ ║
║ 🔨 DevForge · SUBAGENT DEVELOPMENT ║
║ "Il codice si forgia. Il developer cresce." ║
╚══════════════════════════════════════════════════════════════════╝
Tipo: Rigid | Fase SDLC: 4. Implementation (orchestrazione)
LA LEGGE DI FERRO
OGNI TASK VIENE IMPLEMENTATO DA UN SUBAGENT FRESCO, REVISIONATO DA DUE REVIEWER INDIPENDENTI
Nessun task viene dichiarato completo senza:
- Implementazione da subagent con contesto fresco
- Review di conformita' alla specifica (spec-reviewer)
- Review di qualita' del codice (code-quality-reviewer)
Stai per implementare codice direttamente invece di dispatchare un subagent?
FERMATI. Ogni task va implementato da un subagent fresco — nessuna eccezione.
Stai per dichiarare un task completo senza PASS da entrambi i reviewer?
FERMATI. Nessun completamento senza spec-review + code-quality-review.
"Posso implementare io, conosco il codice" = bias accumulato = bug invisibili.
"La review e' eccessiva per questo task" = i bug peggiori vengono dai task "semplici".
Orchestrator Boundary:
L'orchestratore NON implementa codice, NON fa review di codice, NON modifica file
di produzione. Ruolo esclusivo: caricare task, dispatchare subagent, raccogliere
risultati, aggiornare stato piano.
"Posso farlo io velocemente" = bias accumulato = il motivo per cui esistono i subagent.
📊 Dai repo itsiae: Il 28% dei task implementati da subagent senza spec-review conteneva drift rispetto al design doc originale.
Fonte: analisi dei repository GitHub dell'org itsiae.
Quando si Applica
Prerequisiti obbligatori:
- Un piano implementativo esiste in
docs/plans/ (prodotto da siae-brainstorming)
- Il piano contiene task indipendenti o ordinabili
- Siamo nella stessa sessione di lavoro
NON usare quando:
- Il task e' singolo e semplice (usa le skill standard)
- Non esiste un piano implementativo (prima
siae-brainstorming)
- I task sono troppo interdipendenti per essere parallelizzati
Processo di Orchestrazione
Step 1 — Carica il Piano
🟢 SICURO
- Identifica il design doc piu' recente in
docs/plans/
- Estrai la lista dei task dal piano
- Determina l'ordine di esecuzione (rispetta le dipendenze)
- Presenta il piano all'utente per conferma
Detect formato piano:
- Cerca directory in
docs/plans/ che contiene overview.md
→ se trovata: formato split. Leggi overview.md per lista task.
- Se non trovata: cerca file
*-plan.md in docs/plans/
→ formato legacy monolitico. Procedi come prima.
# Formato split
Piano: docs/plans/<topic>/overview.md
Task: docs/plans/<topic>/task-01-*.md ... task-NN-*.md
# Formato legacy
Piano: docs/plans/<topic>-plan.md (file unico)
Output:
PIANO DI IMPLEMENTAZIONE:
Design doc: docs/plans/YYYY-MM-DD-<topic>-design.md
Task totali: N
Ordine: [lista ordinata dei task]
Inizializza Accumulated Discoveries:
Crea un blocco vuoto che verra' popolato durante l'esecuzione:
ACCUMULATED DISCOVERIES:
(nessuna — primo task)
Questo blocco si azzera ogni volta che viene caricato un nuovo piano.
Non persiste tra sessioni o tra piani diversi.
Step 2 — Per Ogni Task: Dispatch Implementer
Costruisci la card come MARKDOWN TABLE direttamente nella risposta testuale.
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-subagent-development |
|---|
🤖 Task: <nome task dal piano> · 📋 Piano: docs/plans/<file>.md |
| ▼ Azione |
1. 🚀 Dispatch subagent implementer → docs/plans/<file>.md |
| 💡 Perche': Subagent con contesto fresco modifichera file reali |
| 🚫 Se NO: Il task non viene implementato, piano resta in attesa |
Per ogni task nel piano, lancia un subagent implementer con il prompt definito
in implementer-prompt.md.
Il subagent implementer:
- Riceve il testo completo del task + contesto del progetto
- Chiede chiarimenti se necessario (risposta dall'orchestratore)
- Implementa seguendo
REQUIRED SUB-SKILL: siae-tdd (RED-GREEN-REFACTOR)
- Esegue self-review con checklist
- Produce un report di completamento
Contesto del subagent: fresco. Nessun bagaglio dalla sessione corrente.
Questo previene bias e assunzioni accumulate.
Contesto arricchito: oltre al task description e al contesto progetto,
inietta nel prompt del subagent il blocco accumulated discoveries:
**Discoveries dai task precedenti (usale, non riscoprirle):**
{accumulated_discoveries}
Per il primo task il blocco e' vuoto. Per i task successivi contiene
le scoperte accumulate dai task precedenti.
Contesto per il subagent (formato split):
Il subagent riceve SOLO:
overview.md — per contesto generale (goal, architettura, stack)task-NN-<nome>.md — il task specifico da implementare- Accumulated discoveries (se presenti)
NON passare gli altri file task. Il subagent non ha bisogno di leggere task
che non gli competono → risparmio token significativo.
Contesto per il subagent (formato legacy):
Estrai dal file monolitico la sezione del task corrente e passala al subagent
insieme all'header del piano.
Step 2b — GATE: Valuta Complessita' Task per Review Scaling
Prima di lanciare i reviewer, valuta la complessita' del task corrente.
| Complessita' | Segnali | Review |
|---|
| Bassa | config, rename, typo, 1-2 file, nessuna logica nuova | Solo code-quality-reviewer (spec-review elidibile con conferma utente) |
| Media | CRUD, refactoring, 3-5 file, logica moderata | Entrambi i reviewer (default, non elidibile) |
| Alta | Feature nuova, cross-module, integrazione, migrazione | Entrambi i reviewer (non elidibile) |
Regole GATE:
- Per complessita' bassa, CHIEDI all'utente: "Task '{nome}' e' a bassa complessita' (N file, nessuna logica nuova). Review completa (spec + code-quality) o ridotta (solo code-quality)?"
- Per complessita' media/alta, procedi con entrambi i reviewer senza chiedere
- L'utente decide SEMPRE — l'orchestratore non salta mai autonomamente
- Code-quality-reviewer non e' MAI elidibile (anche su task banali)
- Se in dubbio sulla complessita', tratta come media (entrambi i reviewer)
Step 3 — Dispatch Spec-Reviewer
🟢 SICURO
Dopo che l'implementer dichiara il task completato, lancia un subagent spec-reviewer
con il prompt definito in spec-reviewer-prompt.md.
Il subagent spec-reviewer (formato split):
- Riceve SOLO
task-NN-<nome>.md (Goal + criteri di accettazione, gia'
self-contained) + overview.md per contesto goal/architettura + la lista
dei file modificati — NON design.md per intero: stesso scoping
dell'implementer (Step 2), stesso risparmio token. Per formato legacy:
estrai la sezione del task corrente come per l'implementer.
- Applica il DISTRUST PATTERN: "L'implementer ha finito sospettosamente in fretta"
- Verifica conformita': requisiti implementati, test presenti, YAGNI
- Produce verdetto PASS/FAIL
Se FAIL:
- L'orchestratore comunica le discrepanze all'implementer
- L'implementer fixa
- Re-dispatch del spec-reviewer
- Max 2 iterazioni, poi escalation all'utente
Step 4 — Dispatch Code-Quality-Reviewer
🟢 SICURO
Dopo il PASS del spec-reviewer, lancia un subagent code-quality-reviewer
con il prompt definito in code-quality-reviewer-prompt.md.
Il subagent code-quality-reviewer:
- Riceve i file modificati dal task
- Esegue review a 6 punti SIAE (standard, security, test, architettura, quality, doc)
- Produce report con severity (CRITICAL / MAJOR / MINOR / INFO)
- Produce verdetto (APPROVED / CHANGES REQUESTED / BLOCKED)
Se CHANGES REQUESTED o BLOCKED:
- L'orchestratore comunica le issue all'implementer
- L'implementer fixa
- Re-dispatch del code-quality-reviewer
- Max 2 iterazioni, poi escalation all'utente
Step 5 — Mark Task Complete
🟢 SICURO
Dopo il PASS di entrambi i reviewer:
Aggiorna il piano:
- Apri
docs/plans/<filename>.md
- Aggiorna il marker del task — dual format:
- Formato marker:
[PENDING] → [DONE] (o [BLOCKED])
- Formato checkbox:
- [ ] Task description → - [x] Task description
- Rileva quale formato usa il piano e aggiorna di conseguenza
- Se il subagent ha fallito dopo 2 retry:
[PENDING] → [BLOCKED] — motivo del fallimento
- Committa:
git add docs/plans/<filename>.md
git commit -m "docs(plans): mark task N as DONE in <piano>"
Aggiorna Accumulated Discoveries:
Dopo che l'implementer produce il report, estrai la sezione Project Discoveries.
Se contiene discoveries (non solo "nessuna"), aggiungile al blocco accumulato:
ACCUMULATED DISCOVERIES:
- [Task 1] Drizzle ORM wrappa PostgresError dentro DrizzleQueryError
- [Task 2] Il config loader ignora .env.local in test environment
- [Task 3] (nessuna nuova discovery)
Ogni discovery e' prefissata con [Task N] per tracciabilita'.
REQUIRED SUB-SKILL: siae-verification
Esegui il protocollo di verifica completo (IDENTIFICA-ESEGUI-LEGGI-VERIFICA-AFFERMA)
prima di dichiarare il task completato.
Step 5b — Plan Completion Gate
Prima della final review, verifica lo stato completo del piano:
grep -c "\[PENDING\]" docs/plans/<filename>.md
grep -c "\[BLOCKED\]" docs/plans/<filename>.md
grep -c "\[DONE\]" docs/plans/<filename>.md
Se PENDING > 0 o BLOCKED > 0: STOP. Non procedere alla final review.
🔴 PIANO INCOMPLETO
Stato: X [DONE] / Y [PENDING] / Z [BLOCKED]
Opzioni:
1. Dispatcha subagent per i task [PENDING] rimanenti
2. Chiedi all'utente se i [BLOCKED] vanno risolti o rimossi
3. Solo quando tutti [DONE] → procedi con Step 6
Se tutti [DONE]: procedi con Step 5c.
Step 5c — Fresh-Eyes Review (Cross-Task)
🟢 SICURO
Dopo che tutti i task sono [DONE], lancia un subagent fresh-eyes-reviewer
con il prompt definito in fresh-eyes-reviewer-prompt.md.
Il subagent fresh-eyes-reviewer:
- Risolve la base con
devforge_resolve_pr_base() (lib/pr-base-resolver.sh — non assume origin/main: usa la PR aperta se esiste, altrimenti merge-base contro il default branch reale) e usa git diff $PARENT_BRANCH...HEAD -- ':(top,exclude)docs/*.md' per TUTTI i cambiamenti di codice (i .md sotto docs/ sono esclusi: piano e design sono gia' input della review). Se il diff e' grande, prima git diff --stat $PARENT_BRANCH...HEAD -- ':(top,exclude)docs/*.md', poi i file uno a uno on-demand.
- Si concentra SOLO su problemi cross-task (6 categorie)
- NON ri-revisa problemi per-task (gia' approvati da spec + quality reviewer)
- Produce report con issue count + ready to merge assessment
Se issue trovate:
- L'orchestratore comunica le issue all'implementer appropriato
- L'implementer fixa
- Re-dispatch del fresh-eyes-reviewer
- Max 2 iterazioni, poi escalation all'utente
Se zero issue: procedi con Step 6 (Final Review).
Step 6 — Final Review Complessiva
Costruisci la card come MARKDOWN TABLE direttamente nella risposta testuale.
| 🟡 MEDIO (reversibile) — 🔨 DevForge · siae-subagent-development |
|---|
🧪 Suite: Test suite completa progetto · ✅ Task completati: N/N |
| ▼ Azione |
1. ▶️ Esecuzione test suite finale → tests/ |
| 💡 Perche': Verifica integrazione post-implementazione |
| 🚫 Se NO: Completamento dichiarato senza verifica test suite |
Dopo che tutti i task sono completati:
- Verifica che l'intero piano sia coperto (nessun task dimenticato)
- Esegui test suite completa del progetto
- Verifica che non ci siano conflitti tra i task implementati
- Produce report finale
Output:
IMPLEMENTAZIONE COMPLETATA:
Piano: docs/plans/YYYY-MM-DD-<topic>-plan.md
Task totali: N
Task [DONE]: N/N
Task [BLOCKED]: 0
Task [PENDING]: 0
Review PASS: N/N spec + N/N quality
Test suite: [risultato]
Verdetto: COMPLETO (tutti [DONE])
Limiti Operativi
| Vincolo | Limite | Se superato |
|---|
| Tentativi max per step | 2 | Fermati. Chiedi all'utente prima di riprovare. |
| Step totali dell'orchestrazione | 4 | Se ne servono di piu', il piano ha troppi task per sessione. |
| Output max per analisi | 300 righe | Sintetizza. L'utente non legge wall-of-text. |
Tabella Anti-Razionalizzazione
| Pensiero | Realta' |
|---|
| "Posso implementare tutto io senza subagent" | I subagent freschi non hanno bias accumulati. Usali. |
| "La review e' eccessiva per questo task" | Ogni task merita review. I bug peggiori vengono dai task "semplici". |
| "Posso saltare il spec-review se il codice e' ok" | Il codice puo' essere perfetto e non corrispondere alla specifica. |
| "Il code-review e' ridondante dopo il spec-review" | Spec e quality sono ortogonali. Uno verifica il "cosa", l'altro il "come". |
| "Ho gia' fatto self-review" | Il self-review ha bias di conferma. Serve un reviewer esterno. |
| "Troppi round di review rallentano" | I bug in produzione rallentano di piu'. 2 review sono un investimento. |
| "Il task e' troppo piccolo per un subagent" | Contesto fresco = meno errori. Anche per task piccoli. |
| "Conosco gia' la codebase, non serve contesto fresco" | La familiarita' genera cecita'. Il contesto fresco trova bug invisibili. |
| "Questo task e' banale, posso implementarlo io" | L'orchestratore non implementa. Mai. Dispatcha un subagent. |
| "La review spec non serve per un rename" | Chiedi all'utente. Non decidere tu. GATE scaling. |
Classificazione Rischio Operazioni
| Operazione | Livello | Card |
|---|
| Lettura piano implementativo | 🟢 Sicuro | No |
| Analisi dipendenze task | 🟢 Sicuro | No |
| Dispatch subagent implementer | 🟡 Medio | Si |
| Dispatch subagent spec-reviewer | 🟢 Sicuro | No |
| Dispatch subagent code-quality-reviewer | 🟢 Sicuro | No |
| Dispatch subagent fresh-eyes-reviewer | 🟢 Sicuro | No |
| Esecuzione test suite finale | 🟡 Medio | Si |
| Report di completamento | 🟢 Sicuro | No |
Permission Denied Handling
Se Agent tool viene negato (dispatch subagent):
- Presenta il prompt completo del subagent come output testuale, racchiuso in
un fenced code block
```text per facilitare il copy-paste senza
rendering markdown.
- Suggerisci all'utente di aprire una sessione Claude Code separata
(
cd <project-path> + claude) e incollare il blocco completo come
primo messaggio della nuova sessione.
- NON inventare slash command (es.
/forge-execute esiste,
/forge-spec-review no). Per execution piano usa /forge-execute docs/plans/<topic>/overview.md. Per review post-impl usa la trigger
sentence della skill (siae-spec-review non esiste come slash command —
il subagent viene dispatchato dall'orchestratore).
- Fornisci istruzioni per ogni tipo di subagent:
- Implementer: "Apri una nuova sessione nella directory del progetto e
digita
/forge-execute docs/plans/<topic>/overview.md. Il piano
contiene il task da eseguire."
- Spec-reviewer: "Dopo l'implementazione, apri una nuova sessione e
incolla il blocco prompt sotto (NON è uno slash command)."
- Code-quality-reviewer: "Dopo la spec-review, apri una nuova sessione
e incolla il blocco prompt sotto (NON è uno slash command)."
Se Bash viene negato (test suite finale — Step 6):
- Fornisci i comandi test esatti per esecuzione manuale
- Chiedi all'utente di eseguire e riportare l'output
Fasi completabili senza permessi: Step 1 (Read piano), analisi dipendenze, generazione prompt
Fasi che richiedono permessi: Step 2-4 (Agent per subagent), Step 5-6 (Bash per test)
Se i permessi sono negati:
- Completa l'analisi del piano e la generazione dei prompt
- Presenta i prompt come istruzioni per sessioni separate
- NON entrare in loop di retry su tool negato
- NON dichiarare completamento per fasi non eseguite
Vincoli
- SEMPRE usare subagent freschi — mai implementare direttamente
- SEMPRE 2 stadi di review per ogni task (spec + quality)
- MAX 2 iterazioni fix-review per stadio, poi escalation
- REQUIRED SUB-SKILL: siae-tdd per ogni subagent implementer
- REQUIRED SUB-SKILL: siae-verification prima di dichiarare qualsiasi task completato
- PRE-FLIGHT OBBLIGATORIA per dispatch implementer e test suite
- NON modificare file se non attraverso subagent
- NON dichiarare completamento senza verdetto PASS da entrambi i reviewer
- REQUIRED fresh-eyes review dopo completamento tutti i task — nessuna eccezione
Risorse Aggiuntive
