--- name: "dev-orchestrate" description: "Router master MUCC: legge specs/_status.md, identifica la fase corrente del progetto SDD, suggerisce o esegue automaticamente la fase successiva spawnando l'agente giusto. Usa quando l'utente dice 'continua', 'prossimo step', 'cosa devo fare adesso', 'avanti col progetto', 'orchestrate', 'auto pilot', oppure all'apertura di una sessione su un progetto MUCC esistente per riprendere il lavoro da dove si era fermato." --- # /dev-orchestrate — Router master del workflow SDD Trasforma il flusso MUCC da "manuale" (utente invoca ogni skill) a "guidato" (router legge stato e suggerisce/esegue prossima fase). **Architettura** (v0.12.0+): 1. Legge `specs/_status.md` → identifica fase corrente 2. Determina prossima azione (skill + agente giusti) 3. Mostra all'utente la transizione proposta 4. Se confermato (o `--auto`): spawna agente specialista 5. Quality gate post-spawn (via hook `SubagentStop`) 6. Aggiorna `_changelog.md` con la transizione **Importante**: la skill è **opzionale**. I comandi manuali (`/dev-vision`, `/dev-prd`, ecc.) continuano a funzionare invariati. `/dev-orchestrate` aggiunge un layer di guida sopra. ## Input ``` /dev-orchestrate # interactive: chiede prima di spawnare l'agente /dev-orchestrate --auto # esegue prossima fase senza chiedere /dev-orchestrate --skip-to N # forza salto a fase N (warning artifacts intermedi) /dev-orchestrate --status-only # solo report, no spawn (alias rapido a /dev-status) /dev-orchestrate --dry-run # mostra cosa farebbe senza eseguire ``` ## Prerequisiti - Progetto MUCC con `specs/` folder (creato da `/dev-init`) - `specs/_status.md` esistente (auto-aggiornato dagli hook PostToolUse) - Plugin dev-methodology v0.12.0+ installato ## Workflow ### Step 1 — Verifica progetto MUCC Verifica esistenza `specs/_status.md`: ```bash test -f specs/_status.md && echo "OK" || echo "MISSING" ``` Se MISSING: ``` ⚠️ Nessun progetto MUCC trovato in $(pwd). Suggerimenti: - Se è un progetto nuovo: /dev-init - Se è un repo ereditato: /bs-onboarding poi /bs-handoff - Se hai cambiato cartella: cd nel progetto MUCC corretto Termino senza eseguire azioni. ``` Termina la skill. ### Step 2 — Parse `_status.md` Leggi `specs/_status.md` e identifica: - **Fase corrente** (1-8): cerca "Current Phase" o l'ultima fase con `🔄 In progress` / `📝 In lavorazione` - **Status fase corrente**: `not-started` | `in-progress` | `done` - **Eventuali blocchi**: cerca sezione "Blockers" o "Bug aperti" - **Sprint corrente** (se Phase 5+): legge `specs/05-sprint-plan.md` se esiste Se parse fallisce (file corrotto): ``` ⚠️ _status.md non parsabile. Eseguo refresh: npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/update-status.ts --specs-dir ./specs ``` Poi ri-leggi. ### Step 3 — Decide prossima azione Mappatura **fase → skill → agente** (tabella interna alla skill): | Phase | Output file | Skill da invocare | Agente subagent_type | |-------|-------------|-------------------|----------------------| | 1 | `specs/01-vision.md` | `/dev-vision` | `pm-agent` | | 2 | `specs/02-prd.md` | `/dev-prd` | `pm-agent` | | 3 | `specs/03-user-stories.md` | `/dev-stories` | `pm-agent` | | 4 | `specs/04-tech-spec.md` | `/dev-spec` | `be-architect` | | 4.5 | service folders + Dockerfile | `/dev-scaffold` | `be-architect` | | 5 | `specs/05-sprint-plan.md` | `/dev-sprint` | `scrum-master` | | 6 | (auto) `CLAUDE.md` | (auto) | — | | 7 | `specs/07-implementation.md` + tests | **vedi tabella 7** | `be-architect` + `test-engineer` | | 8 | `specs/08-validation.md` | **vedi tabella 8** | `test-engineer` (legacy) o team E2E (parallel) | #### Tabella 7 — Routing intelligente Phase 7 (v0.13.0+) A Phase 7 il router sceglie tra 2 skill in base al contesto: | Condizione | Skill | Razionale | |------------|-------|-----------| | Sprint plan ha **>3 stories non-done** AND `~/.claude/skills/dev-sprint-execute/` installato | **`/dev-sprint-execute SPRINT_ID`** | Loop autonomo story-by-story con auto-commit | | Sprint plan ha 1-3 stories OR `dev-sprint-execute` non installato OR `--single-story` flag | **`/dev-implement`** | Implementazione singola story (manual control) | Detect: `npx tsx ${MUCC_PLUGIN_ROOT}/scripts/parse-sprint.ts --file specs/05-sprint-plan.md --sprint $CURRENT_SPRINT --json | jq '.stories | map(select(.status != "done")) | length'` #### Tabella 8 — Routing intelligente Phase 8 (v0.13.0+) A Phase 8 il router sceglie tra 2 skill in base al contesto: | Condizione | Skill | Razionale | |------------|-------|-----------| | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` AND `~/.claude/skills/dev-validate-e2e/` installato | **`/dev-validate-e2e`** | Test API+browser paralleli, -60% wall-clock | | Altrimenti | **`/dev-validate`** | Sequenziale legacy (test-engineer single-agent) | L'utente può forzare la scelta via `--validate-mode legacy|e2e`. **Logica decisionale**: ``` SE fase corrente status = "in-progress": → Riprendi quella fase (suggerisci skill) → Mostra: "📝 Phase X in corso. Riprendi con /dev-skill" SE fase corrente status = "done" AND fase successiva esiste: → Suggerisci avanzamento alla fase successiva → Per Phase 7/8: applica Tabella 7/8 routing intelligente → Mostra transizione proposta SE fase corrente status = "done" AND fase = 8: → Tutte le fasi complete. Suggerisci /dev-pivot o /bs-init nuovo progetto SE fase corrente status = "not-started": → Mostra come iniziare quella fase ``` ### Step 4 — Mostra dashboard transizione Format output utente: ``` ╔════ MUCC ORCHESTRATE ═══════════════════════════════╗ ║ Progetto: {nome} ║ ║ ║ ║ 📊 Stato corrente: Phase {N} ({nome_fase}) — {status} ║ 📂 Ultimo artifact: specs/{file} ({size} righe) ║ ║ ║ ║ ⏭️ Prossimo step proposto: ║ ║ Phase {N+1}: {nome_fase_succ} ║ ║ Skill: /dev-{skill} ║ ║ Agente: {nome_agente} ({nome_persona}) ║ ║ Output: specs/{file_atteso} ║ ║ ║ ║ Procedere con spawn automatico? (sì/no/skip-to-N) ║ ╚═════════════════════════════════════════════════════╝ ``` Se `--dry-run`: mostra il box e termina. Se `--auto`: salta domanda, vai a Step 5. Se interactive e utente risponde: - `sì` / `s` / `yes` / `y` / invio → Step 5 - `no` / `n` → termina con messaggio "OK, esegui manualmente quando pronto: /dev-{skill}" - `skip-to N` → re-routing a fase N (con warning se salti artifacts intermedi) ### Step 4.4 — Phase Scope Boundaries (NEW v0.28.0) **Razionale**: proposta skill-evolution **#67** — il routing senza vincoli espliciti di scope porta a violazioni cross-phase (es. il pm-agent che modifica file tecnici durante Phase 2, oppure il be-developer che riscrive il PRD). Le **Phase Scope Boundaries** sono regole esplicite di cosa l'agente della fase X può e NON può toccare. Iniettate nel prompt di Step 5 come VINCOLI VALIDATI HARD prima di ogni `Agent({...})` spawn. **Tabella regole** (canonica, override possibile via `.mucc/scope-rules.json`): | Phase | Agente | ✅ Può modificare | ❌ NON deve toccare | |-------|--------|-------------------|---------------------| | 1 — Vision | pm-agent | `specs/01-vision.md`, `specs/_status.md`, `specs/_changelog.md` | qualsiasi codice (`src/`, `tests/`), `specs/04-tech-spec.md`, `specs/03-user-stories.md`, schema DB | | 2 — PRD | pm-agent | `specs/02-prd.md`, `specs/_status.md`, `specs/_changelog.md` | `src/`, `tests/`, `database/`, `specs/04-tech-spec.md`, `specs/05-sprint-plan.md` | | 3 — Stories | pm-agent | `specs/03-user-stories.md`, `specs/_status.md`, `specs/_changelog.md`, `specs/features/*.feature` | `src/`, `tests/`, `specs/04-tech-spec.md` | | 4 — Tech Spec | be-architect + db-expert + ux-designer | `specs/04-tech-spec.md`, `specs/database/`, `specs/ux/`, `specs/technical/`, `specs/testing/test-strategy.md` | `specs/01-vision.md`, `specs/02-prd.md`, `specs/03-user-stories.md` (read-only), `src/` | | 4.5 — Scaffold | be-architect | `{service}/Dockerfile`, `{service}/railway.json`, `docker-compose.yml`, `.env.example`, `README-deploy.md` | `specs/0[1-4]*.md` (read-only), codice applicativo `src/` | | 5 — Sprint | scrum-master | `specs/05-sprint-plan.md`, `specs/_status.md`, `specs/_changelog.md` | `src/`, `tests/`, `specs/03-user-stories.md` (read-only — solo riferimenti) | | 7 — Implementation | fe-developer / be-developer | `{service}/src/`, `{service}/tests/`, `specs/07-implementation.md`, `specs/testing/test-map.md`, `specs/_status.md` | `specs/01-vision.md` / `02-prd.md` / `03-user-stories.md` / `04-tech-spec.md` (tutti read-only) | | 8 — Validation | test-orchestrate-lead + Cinzia + Massimo + Bruno | `specs/08-validation.md`, `sprint-reviews/{story-id}/`, `tests/api/`, `tests/browser/`, `screenshots/` | `src/` (read-only, NON modifica codice — è validation), `specs/0[1-7]*.md` (read-only) | **Iniezione nel prompt** (Step 5 esistente, estensione): ``` PHASE SCOPE BOUNDARIES (NEW v0.28.0 — VINCOLO HARD, non opzionale): Fase: {N} — {phase_name} Tu sei: {agent_name} ✅ Puoi modificare: {can_modify_paths_list} ❌ NON puoi toccare: {forbidden_paths_list} Se ti accorgi di dover modificare file fuori dal tuo scope: 1. Ferma il task 2. Restituisci status="scope-violation-needed" 3. Indica quali file servono e perché 4. L'utente (o /dev-orchestrate) deciderà se rifare routing a fase diversa ``` **Quality gate post-subagent**: l'hook `SubagentStop` (script `quality-gate.ts`) verifica che i file modificati dal subagent rientrino nello scope dichiarato. Out-of-scope → `decision: warn` con suggerimento di re-routing (mai bloccante). **Override per progetto**: file opzionale `.mucc/scope-rules.json` permette di estendere/sostituire la tabella canonica. Esempio: ```json { "phase_4_tech_spec": { "can_modify": ["specs/04-tech-spec.md", "specs/database/", "specs/architecture-diagrams/"], "forbidden": ["src/", "tests/"] } } ``` ### Step 4.5 — Tool Necessity Gate (NEW v0.25.0) Prima di ogni `Agent({...})` spawn (Step 5), applica il **Tool Necessity Gate** ispirato al paper AI-Radar id 921 (knowing-doing gap 26-54%). Vedi protocollo condiviso in `dev-methodology/references/tool-decision-protocol.md`. **Step operativi**: 1. **Dichiarazione preventiva**: per la fase target, elenca esplicitamente i tool che il subagent dovrà invocare. Esempio Phase 5 → `scrum-master`: ``` TOOL NEEDED FOR PHASE 5: - Read: specs/04-tech-spec.md, specs/03-user-stories.md (input) - Write: specs/05-sprint-plan.md (output principale) - Edit: specs/_status.md, specs/_changelog.md (tracking) ``` Questa dichiarazione viene **iniettata nel prompt** del subagent come premessa. 2. **Prompt obbligo**: estendi il prompt con la frase canonica: ``` Alla fine del tuo output, includi la sezione "## Tool Calls Log" conforme al protocollo dev-methodology/references/tool-decision-protocol.md. ``` 3. **Skip silenzioso**: se il subagent non ha bisogno di tool (raro, es. fase di sole decisioni), dichiara esplicitamente `TOOL NEEDED: none — reasoning only` con motivazione. ### Step 5 — Spawna l'agente specialista Usa il tool **`Agent`** con il `subagent_type` mappato. **Esempio Phase 4 → Phase 5 transition**: ```typescript Agent({ description: "Sprint planning Phase 5", subagent_type: "scrum-master", prompt: ` Sei stato chiamato da /dev-orchestrate per eseguire la transizione Phase 4 → Phase 5. TOOL NEEDED (dichiarazione preventiva, vedi Step 4.5 — Tool Necessity Gate): - Read: specs/04-tech-spec.md, specs/03-user-stories.md (input) - Write: specs/05-sprint-plan.md (output principale) - Edit: specs/_status.md, specs/_changelog.md (tracking) Contesto progetto: - CWD: ${cwd} - specs/04-tech-spec.md: ${tech_spec_summary_3_lines} - specs/03-user-stories.md: ${stories_count} stories totali - Velocity default: 20 SP/sprint (modificabile via prompt utente) Task: esegui la skill /dev-sprint completa. Genera specs/05-sprint-plan.md con: - Sprint breakdown (4-6 sprint) - Story points per sprint (Fibonacci) - Capacity planning - Definition of Done per sprint - Velocity tracking template Vincoli: - NON modificare file fuori da specs/ - Aggiorna _changelog.md a fine task con entry standard - Se mancano dati (es. velocity custom), CHIEDI all'utente — non assumere Al termine, restituisci: - File creati/modificati - Numero sprint pianificati - Eventuali warning (es. "story senza estimate") - **Sezione "## Tool Calls Log"** conforme a dev-methodology/references/tool-decision-protocol.md (formato JSON o text-fallback TOOL EXECUTED: per ogni invocazione). ` }) ``` **Post-spawn quality gate**: dopo che il subagent termina, l'hook `SubagentStop` invoca `quality-gate.ts --check post-subagent` che parsa la sezione "Tool Calls Log" e segnala warn (non bloccante) se il subagent ha invocato meno tool di quelli dichiarati `NEEDED`. **Modalità `--auto`**: stesso prompt ma con direttiva esplicita "Procedi senza chiedere conferme. Usa default Fibonacci 1,2,3,5,8,13 + velocity 20 SP. Annota '(modalità auto)' nel _changelog." ### Step 6 — Quality gate (automatico via hook) Il hook `SubagentStop` (registrato in `~/.claude/settings.json`) si attiva automaticamente al termine dell'agente. Esegue `quality-gate.ts --check post-subagent` che verifica: - Artifact atteso esiste? - Sezioni REQUIRED del template popolate? - Backlinks/riferimenti coerenti? Output del hook (se warning): ``` ⚠️ Quality gate: scrum-master ha completato ma: - specs/05-sprint-plan.md ha sezione "Velocity tracking" vuota - Consigliato: re-run con prompt esplicito su velocity ``` Output del hook (se OK): silenzioso. **Importante**: il hook è `decision: warn`, non blocca mai il workflow. ### Step 7 — Aggiorna `_changelog.md` Append entry alla fine di `specs/_changelog.md`: ```markdown ## [Auto-orchestrate] {ISO_timestamp} **Transizione**: Phase {N} → Phase {N+1} **Skill**: /dev-{skill} **Agente**: {nome_agente} **Trigger**: /dev-orchestrate{flag se auto} **Modalità**: {interactive | auto | skip-to} **Output**: specs/{file} **Quality gate**: {OK | warning: ...} ``` ### Step 8 — Mostra report finale ``` ✅ Orchestrate completato: Phase {N} → Phase {N+1} Output: specs/{file} ({size} righe) Quality: {pass | warning con dettaglio} ⏭️ Prossimo automatico: /dev-orchestrate (continua col flusso) Oppure manuale: /dev-{skill_succ} ``` ## Modalità `--skip-to N` Forza salto a fase N anche se le fasi intermedie sono incomplete. Usato per: - Recovery dopo crash (riprendi dall'ultima fase nota) - Rapid prototyping (salta vision, vai diretto a tech-spec) - Demo / training Logica: ``` 1. Calcola fasi saltate: [{current+1}, ..., N-1] 2. Se non vuoto: ⚠️ Stai saltando le fasi: 2, 3. Gli artifact specs/02-prd.md, specs/03-user-stories.md NON saranno generati. Le fasi successive avranno meno contesto. Confermi? (sì/no) 3. Se sì: routing diretto a Phase N, prompt agente con disclaimer "fasi intermedie saltate" 4. Annota in _changelog.md con trigger "/dev-orchestrate --skip-to N" ``` ## Modalità `--status-only` Equivalente rapido a `/dev-status` ma con output orchestrate-friendly: ``` ╔════ MUCC STATUS ════════════════════════════════════╗ ║ Phase 4 (Tech Spec) — done ║ ║ Next: Phase 5 (Sprint Plan) — /dev-sprint ║ ║ Blockers: nessuno ║ ║ Coverage: N/A (Phase 7+ non raggiunta) ║ ╚═════════════════════════════════════════════════════╝ ``` Termina senza spawn. ## Esempi ### Esempio 1: workflow automatico ``` Utente: /dev-orchestrate --auto Claude: 📊 Phase 4 (Tech Spec) — done ⏭️ Phase 5 (Sprint Plan) — spawn scrum-master (Sara) 🤖 Sara sta pianificando 4 sprint... [scrum-master genera specs/05-sprint-plan.md] ✅ Phase 4 → Phase 5 done Output: specs/05-sprint-plan.md (327 righe) Quality: OK Sprint pianificati: 4 Total SP: 78 (3 sprint da 20 + 1 da 18) ⏭️ Prossimo: /dev-orchestrate (per Phase 7) o /dev-implement ``` ### Esempio 2: workflow interattivo con domanda ``` Utente: /dev-orchestrate Claude: ╔════ MUCC ORCHESTRATE ═══════════════════════╗ ║ Progetto: presenta ║ ║ 📊 Phase 1 (Vision) — done ║ ║ ⏭️ Phase 2 (PRD) — spawn pm-agent (Giulia) ║ ║ Procedere? (sì/no/skip-to-N) ║ ╚═════════════════════════════════════════════╝ Utente: sì Claude: 🤖 Giulia sta scrivendo PRD... [pm-agent legge specs/01-vision.md, genera specs/02-prd.md] ✅ Phase 1 → Phase 2 done. Prossimo: /dev-orchestrate ``` ### Esempio 3: skip-to ``` Utente: /dev-orchestrate --skip-to 5 Claude: ⚠️ Stai saltando le fasi: 2 (PRD), 3 (Stories), 4 (Tech Spec). Gli artifact NON verranno generati. Sprint plan avrà contesto limitato. Confermi? (sì/no) Utente: sì Claude: 🤖 Sara pianifica sprint con disclaimer "fasi intermedie saltate"... ⚠️ Sprint plan generato senza tech-spec → stime SP indicative. Suggerimento: torna a Phase 4 con /dev-spec quando hai più chiarezza. ``` ### Esempio 4: status-only ``` Utente: /dev-orchestrate --status-only Claude: ╔════ MUCC STATUS ════════════════════════════╗ ║ Phase 7 (Implementation) — in-progress ║ ║ Sprint: 2/4 (US-005, US-006 in dev) ║ ║ Coverage: 67% (target 70%) ║ ║ Blockers: nessuno ║ ║ Next: completa US-006, poi /dev-orchestrate ║ ╚══════════════════════════════════════════════╝ ``` ### Esempio 5: progetto non MUCC ``` Utente: /dev-orchestrate Claude: ⚠️ Nessun progetto MUCC trovato in /Users/.../tmp. Suggerimenti: - Progetto nuovo: /dev-init - Repo ereditato: /bs-onboarding poi /bs-handoff - Cambia cartella: cd nel progetto MUCC corretto Termino. ``` ## Quando NON usare - **Progetti senza specs/**: usa `/dev-init` prima - **Bug fix isolati**: usa `/dev-quick` o lavoro diretto sui file - **Brainstorming pre-specs**: usa skill `/bs-*` invece - **Singola skill mirata**: invoca direttamente `/dev-spec` o altra (più veloce, no overhead orchestrate) ## Backward compatibility Tutti i workflow manuali pre-v0.12.0 continuano a funzionare. `/dev-orchestrate` è opt-in. Hook quality gate sono `decision: warn` — segnala ma non blocca mai. Se l'hook quality-gate fallisce per bug: la skill prosegue comunque (il hook gira separato). ## Output - Dashboard transizione (box ASCII art) - Spawn agente specialista (se confermato) - Aggiornamento `_changelog.md` con transizione tracciata - Quality gate report (silent o warning) - Suggerimento prossimo step ## Riferimenti - SPEC: `SPEC-orchestration-layer-v0.12.0.md` sezione 1 - Pattern: A (Router + Function Skills) + F (Hooks middleware) - Quality gate script: `dev-methodology/scripts/quality-gate.ts` - Hooks: `dev-methodology/hooks/settings-snippet.json` (event: SubagentStop, Stop) - Agenti spawnabili: `dev-methodology/agents/{pm-agent,be-architect,scrum-master,test-engineer,db-expert,ux-designer,security-expert,app-expert}.md` - Skill correlate: `/dev-status`, `/dev-init`, `/dev-pivot`, **`/dev-sprint-execute`** (v0.13.0+ meso-orchestration loop autonomo Phase 7), `/dev-validate-e2e` (v0.12.0+ Sprint 2 parallel testing), `/dev-codesearch` (v0.12.0+ semantic search)