Skip to content
← Tutti i capitoli

Capitolo 03

Template di piani e attività

Un Deep Work Plan è una directory di file Markdown. La forma di quella directory — e di ciascun file al suo interno — è ciò che rende un piano revisionabile sia dalle persone sia dagli agenti.

Struttura del piano

Un piano è una directory sotto .dwp/plans/ denominata PLAN_001_<slug>/. Contiene:

  • manifest.json — l’identità del piano e il puntatore al suo contratto attivo, scritto per primo durante la materializzazione.
  • contract.json — contratto di specifica e ambito del piano.
  • journal.ndjson — giornale degli eventi a sola aggiunta.
  • state.json — uno snapshot proiettato dal journal, mai modificato a mano.
  • README.md — panoramica del piano: obiettivo, tabella delle attività e stato.
  • PROGRESS.md — log di esecuzione cronologico leggibile dall’uomo.
  • <n>.task_<slug>.md — file di specifica in dieci sezioni per ciascuna attività.
  • analysis_results/ — directory per artefatti di analisi, report e log dei gate.

Il pacchetto 7.x attuale crea i piani v7 per impostazione predefinita, con 2–5 parole nello slug come per v6. Il flusso v5 conservato utilizza 2–4 parole (poiché il relativo schema congelato conta l’ID numerico come una parola). I nuovi piani ricevono ID numerici crescenti con almeno tre cifre (ad esempio PLAN_001_add_payment_webhooks/). Le directory non numerate esistenti PLAN_<slug>/ restano leggibili e non vengono mai rinominate; nessun piano esistente viene migrato implicitamente. Se esistono piani numerati, latest punta al piano con l’ID numerico più alto.

Struttura del file di attività

Ogni file di attività è denominato <n>.task_<slug>.md e segue le dieci sezioni normative definite dalla skill installata (per i dettagli anatomici si veda Il core loop). Ogni attività si riancora all’obiettivo del piano prima di agire, il che impedisce a un agente di andare alla deriva su un orizzonte lungo, di più ore.

Il Final Review

Ogni piano deve concludersi con esattamente un’attività obbligatoria: il Final Review. Chiude il piano in cinque passaggi rigorosamente ordinati — i controlli di sicurezza e i validation gate non vengono in alcun caso indeboliti:

  1. Passaggio di sicurezza — verificare tutto ciò che il piano ha modificato per individuare segreti, rischi di injection e nuove superfici di attacco, mantenere aggiornato docs/SECURITY.md ed eseguire la review locale richiesta di AI Diff Reviewer sull’intero ambito del piano (un reviewer mancante viene registrato come rilievo local reviewer not installed, mai ignorato silenziosamente). Un rilievo critico blocca il completamento.
  2. Validazione dello stato finale — le suite complete di test, lint e controllo tipi del repository vengono eseguite e superate sullo stato finale. Eventuali correzioni durante la revisione invalidano i risultati correlati e richiedono una nuova esecuzione.
  3. Riconciliazione delle skill — verificare che ogni attività abbia registrato la propria disposizione locale delle skill e riconciliare i candidati in analysis_results/SKILLS_CANDIDATES.md.
  4. Riconciliazione della documentazione — allineare la superficie toccata di ogni attività che modifica il comportamento con i documenti (docs/TESTING_GUIDE.md, architettura, AGENTS.md) che registrano tale funzionalità.
  5. Completamento — i registri del piano concordano (elenco delle attività, log di avanzamento e, nei piani v6 e v7, snapshot e ricevuta derivati dal journal); segnalare deliverable, prove e limitazioni, e proporre l’Executive Report una sola volta.

Convenzioni di README e PROGRESS

Il README.md del piano deve contenere un titolo (# Deep Work Plan: <name>), una dichiarazione discorsiva dell’obiettivo, una sezione facoltativa sul materiale di origine, una tabella delle attività (numero, nome dell’attività, casella di stato) e una riga di stato del piano nella forma <n>/<total> tasks complete.

PROGRESS.md è un log di esecuzione a sola aggiunta. Ogni voce registra un timestamp ISO 8601, il numero e il nome dell’attività, cosa è stato fatto e qualsiasi deviazione o motivo di salto. Poiché non fa che crescere, è una cronologia affidabile di come il piano si è effettivamente svolto.

Intestazioni e riferimenti incrociati

Tutte le intestazioni usano lo stile a frase (sentence case) e i documenti evitano il linguaggio di marketing e i punti esclamativi. Queste convenzioni mantengono i piani coerenti tra gli agenti e nel tempo.