Il core loop

DWP definisce un piccolo insieme di operazioni che portano un piano da un obiettivo a lavoro completato e revisionabile: create → execute → refine → resume → status, con verify come verifica di conformità che conferma il risultato. Insieme formano il ciclo che un agente segue per tutta la vita di un piano. Gli agenti eseguono un’attività alla volta, validando ogni passo prima di proseguire.

Questo ciclo è la forma operativa dello spec-driven development. Il piano è la specifica rispetto a cui un agente esegue, ogni attività porta con sé criteri di accettazione espliciti e il passo di validazione è il gate che trasforma una dichiarazione di completamento nella sua prova. Poiché il piano e il suo log dei progressi vivono nel repository, il ciclo è ripristinabile tra sessioni e agenti.

Le operazioni

Il ciclo principale di DWP: cinque operazioni portano un piano dall’obiettivo al lavoro completato, con Verificare come porta di conformità.

La skill metodologica delega l’intento a nove sotto-skill specializzate: sei operazioni centrali di esecuzione, due assistenti del ciclo di vita e un motore di authoring:

create — Genera un nuovo piano da un obiettivo. L’agente analizza l’obiettivo, lo scompone in attività sequenziali e scrive i file del piano. In modalità guidata, l’agente materializza direttamente un piano Lite — una proposta compatta e già eseguibile —, che lo sviluppatore può mantenere, promuovere a un piano Full, modificare o annullare; in modalità trust, l’agente materializza direttamente la rappresentazione scelta (Lite o Full) senza richiedere conferme. L’analisi dei requisiti e il controllo di qualità del piano vengono eseguiti in entrambe le modalità.
execute — Esegue il piano attività per attività in modo sequenziale. L’agente aggiorna il log dei progressi, esegue i validation gate e committa dopo ogni attività. In modalità trust, l’esecuzione prosegue in modo autonomo senza pause tra le attività.
refine — Modifica un piano esistente (aggiungere, modificare, dividere o riordinare attività, o promuovere un piano Lite a Full). Le prove già convalidate vengono rigorosamente preservate e l’indebolimento non confermato dei criteri è vietato.
resume — Continua un piano interrotto. L’agente legge il journal in solo accodamento e i file delle attività per ricostruire lo stato, poi prosegue dalla prima attività incompleta senza ripetere il lavoro completato.
status — Riferisce sui progressi senza eseguire (rigorosamente in sola lettura). L’agente riassume le attività completate, in corso e in sospeso e non cambia nulla.
verify — Verifica la conformità senza cambiare nulla (rigorosamente in sola lettura). L’agente riferisce se il repository soddisfa lo standard AI-first e se le attività hanno criteri espliciti e validation gate.
onboard — Ispeziona il repository di destinazione per ricavare tramite ragionamento — mai tramite copia-incolla — un AGENTS.md adattato, una gerarchia docs/, documentazione dei moduli e il kit .agents/ con symlink.
upgrade — Controlla i rilasci a monte, richiede il consenso esplicito dello sviluppatore prima del download, installa tag stabili fissati e concilia gli adattamenti locali senza toccare i piani .dwp/ esistenti.
author — Crea ed evolve skill, agenti o comandi slash locali del repository per coprire flussi ricorrenti reali, e mantiene sincronizzato il catalogo .agents/docs/.

La directory di output `.dwp/`

Tutti gli artefatti DWP vivono in una directory .dwp/ esclusa da git nella radice del repository. Tenere il workspace fuori dal controllo di versione significa che lo stato di lavoro di un piano non inquina mai la storia del progetto. Le configurazioni degli addon a livello di repository sono registrate in .dwp/config.json (dwp-config/v1), mentre i piani risiedono in directory numerate piatte:

.dwp/
├── config.json
└── plans/
    └── PLAN_001_<slug>/
        ├── manifest.json
        ├── contract.json
        ├── journal.ndjson
        ├── state.json
        ├── README.md
        ├── PROGRESS.md
        ├── 1.task_<slug>.md
        ├── 2.task_<slug>.md
        └── analysis_results/

L’anatomia in dieci sezioni di un’attività

File di task

01 Titolo
02 Contesto
03 Da leggere prima di iniziare
04 Obiettivo
05 Superficie interessata
06 Istruzioni
07 Criteri di accettazione
08 Output
09 Validazione
10 Checklist di esecuzione e Registro di completamento

Ogni file di task segue le stesse dieci sezioni ordinate definite dallo skill installato, garantendo che ogni unità di lavoro sia autonoma e revisionabile.

Ogni file di attività segue le dieci sezioni normative presentate sopra, nell’ordine definito dalla skill installata.

Goal — un paragrafo che dichiara cosa l’attività realizza.
Context — contesto, link e il perché questa attività esiste.
Superficie toccata: ciò che l’attività modifica e la classe di rischio che seleziona la sua validazione.
Steps — azioni ordinate e concrete da svolgere.
Acceptance criteria — una checklist di condizioni che definiscono il completamento.
Validation — comandi o test da eseguire per verificare il lavoro.
Files — percorsi che ci si aspetta vengano creati o modificati.
Dependencies — altre attività o prerequisiti esterni.
Risks — cosa potrebbe andare storto e le relative mitigazioni.
Completion & Log — un marcatore di stato più note cronologiche.

Validazione, completamento e ripresa

La validazione è parte dell’attività, non un ripensamento: ogni attività indica i comandi o i test che ne provano il completamento e l’agente li esegue prima di segnare il completamento. I test sono di prima classe qui — un’attività che aggiunge nuove funzionalità o modifica il comportamento deve aggiungere o aggiornare test automatizzati per quel comportamento ed eseguire il controllo completo di qualità del codice del repository (test più lint e type-check), non limitarsi a confermare che la build riesce; i test esistenti devono restare verdi, aggiornati al comportamento previsto anziché saltati. La sicurezza è di prima classe allo stesso modo — qualsiasi attività che tocchi l’autenticazione, la gestione dell’input, i segreti, la superficie di rete o le dipendenze porta con sé le aspettative di sicurezza di quella modifica nei propri criteri di accettazione e mantiene ogni commit privo di segreti, e ogni piano si chiude con il Final Review — il passaggio di sicurezza sull’intero insieme di modifiche, la validazione completa sullo stato finale e la riconciliazione delle decisioni sulle skill. Il completamento è registrato con un marcatore di stato esplicito ([ ] non iniziata, [~] in corso, [x] completata, [!] bloccata) nella sezione Completion & Log. La ripresa si basa su questi marcatori e sul log dei progressi — un agente può ricostruire esattamente dove il piano si è fermato e proseguire dalla prima attività incompleta senza rifare il lavoro già concluso.

v6 e v7: la stessa metodologia, una struttura più rigorosa

Lo standard DWP attuale è 7.0.0, implementato dalla linea di skill 7.x. Quel pacchetto usa v7 per ogni nuovo piano per impostazione predefinita; una richiesta esplicita di v6 materializza comunque un piano v6. I piani v1, v2, v5 e v6 esistenti mantengono la generazione registrata e non vengono mai migrati silenziosamente; il passaggio di un piano v5 a v6 richiede una richiesta di migrazione esplicita.

v6 mantiene la stessa metodologia piano → attività → gate di validazione → completamento, i comandi slash e la posizione .dwp/plans/. Rende più rigorosa la struttura ingegneristica con un contratto, un journal, manifest di contesto per attività, uno scheduler e il rifiuto di una allowlist vuota. v7 mantiene questo livello di registrazione e aggiunge un marcatore di task opzionale parallel_safe, un evento del journal delegation per il lavoro delimitato affidato a un altro agente e il registro degli addon .dwp/config.json; senza alcun addon di delega abilitato, ogni piano viene comunque eseguito in sequenza nella sessione corrente. La decisione architetturale è GO; la non inferiorità empirica dei risultati degli agenti non è stata misurata.