italiadatacenter/add-on/AgentPlatform/sts-spec-driven/SKILL.md

name, description

name

description

sts-spec-driven

STS Lab Srl — Spec-Driven Reader. Legge e SCRIVE la documentazione spec-driven di un progetto (cartella docs/ con PROJECT_MEMORY, REQUIREMENTS REQ-*, specifiche SPEC-*, task T-*, decisioni D-*, difetti DIF-*, TRACEABILITY, TODO, DECISIONS, CHANGELOG, DEVELOPMENT_LOG). Lettura: trasforma la documentazione in un brief di implementazione prima del codice e chiude il ciclo dopo. Scrittura: se il progetto non ha documentazione la crea da zero facendo scegliere fra layout strutturato (00-INDEX + 01-product…08-project) e piatto, con modelli, intervista e controllo di coerenza; aggiunge nuove spec, requisiti e decisioni a una documentazione esistente. Usala all'inizio di ogni sessione di sviluppo, quando l'utente cita un ID (REQ-, SPEC-, T-, D-, DIF-), chiede di implementare una spec o un task, chiede «leggi la documentazione», «da dove riprendo», «che stato ha il progetto», «crea la documentazione», «imposta lo spec driven», «scrivi la spec di …», «nuovo progetto», o quando si inizia a sviluppare in un progetto senza docs/.

Spec-Driven Reader — STS Lab Srl

STS Lab Srl · Skill proprietaria per lo sviluppo software guidato da specifiche. © 2026 STS Lab Srl — tutti i diritti riservati.

Nei progetti STS Lab la documentazione precede il codice e ne è il contratto:

REQ-xxx  cosa deve fare il prodotto          (REQUIREMENTS)
   ▼
SPEC-xxx come lo fa: API, dati, regole,      (03-specs/ o documenti di modulo)
   │     errori, criteri di accettazione
   ▼
T-xxx    unità di lavoro implementabile      (TODO)
   ▼
codice + test
   ▼
TRACEABILITY  chiude il cerchio: ogni REQ ha spec, task e test che passano

Ogni scelta strutturale è una decisione numerata D-xxx; ogni difetto noto è un DIF-xx. Questa skill serve a scrivere quella catena quando manca, a leggerla bene prima di toccare il codice, e a richiuderla dopo.

Quale modalità

Situazione	Modalità	Dove
Il progetto non ha documentazione spec-driven (o l'utente chiede di crearla)	Scrittura	§A qui sotto + references/scrittura.md
C'è solo lo scheletro, con molti DA COMPILARE	Scrittura (completamento)	idem, dallo step in corso
Serve una spec, un requisito o una decisione nuovi	Scrittura (aggiunta)	references/scrittura.md §6
La documentazione c'è e si deve sviluppare	Lettura	§1–§8

---

0. Strumento: scripts/spec_index.py

Libreria standard Python 3.8+. Usalo prima di aprire i file grandi: DECISIONS e DEVELOPMENT_LOG possono superare le 3–6 000 righe e non vanno mai letti interi.

S=~/.claude/skills/sts-spec-driven/scripts/spec_index.py
# lettura (non scrive nulla)
python $S overview <docs>                 # layout, documenti chiave, stato delle spec, segnaposto
python $S context  <docs> SPEC-004        # definizione + ID collegati + TODO + TRACEABILITY
python $S find     <docs> D-014           # dove è definito e chi lo cita
python $S check    <docs>                 # coerenza: orfani, requisiti scoperti, derive di stato
python $S next-id  <docs> SPEC|D|DIF|T|REQ [--area AUT] [--spec SPEC-004] [--prefisso W]
# scrittura (non sovrascrive mai un file esistente)
python $S scaffold <docs> --layout strutturato|piatto --progetto "Nome"
python $S new-spec <docs> --titolo "Titolo" [--prefisso W  (solo layout piatto)]

Su Windows da PowerShell il ~ non viene espanso: usa $HOME\.claude\skills\sts-spec-driven\scripts\spec_index.py (oppure lancialo dal tool Bash, dove ~ funziona).

• Per una SPEC, context stampa l'indice delle sezioni con i numeri di riga: leggi poi solo le sezioni che servono con Read offset/limit.
• check esce con codice 1 se trova problemi; riporta all'utente cosa ha trovato.

Se Python non c'è, ripiega su Grep con il pattern REQ-[A-Z]+-\d+|SPEC-\d{3}|T-[A-Z]{0,2}\d+|D-\d{3}|DIF-\d+ e copia a mano i modelli da templates/.

---

A. Scrittura — creare la documentazione

Procedura completa in references/scrittura.md. In sintesi:

1. Verifica che non esista già (§1). Se esiste solo in parte, non ricrearla: completala.
2. Fai scegliere il layout all'utente con AskUserQuestion, mettendo per primo con «(Consigliato)» quello adatto — Strutturato per progetti con più moduli, integrazioni, riscritture, committente esterno; Piatto per progetti piccoli, prototipi, un solo modulo. Chiedi anche dove crearla (default docs/ alla radice del repository).
3. Crea lo scheletro con scaffold. I modelli stanno in templates/strutturato/, templates/piatto/, templates/spec.md, templates/modulo.md.
4. Raccogli le informazioni: prima leggi README, manifest, codice; poi intervista l'utente (al massimo 4 domande per giro, solo ciò che manca). Se c'è codice senza documenti, ricostruisci i requisiti dal codice come tipo P con Origine file:funzione.
5. Scrivi nell'ordine degli step (visione → requisiti → architettura → spec → contratto e dati → devops → qualità e backlog), con un riepilogo e la conferma dell'utente a fine step.
6. Nuove spec con new-spec: numerazione, blocco di task e lettera dei criteri sono automatici. Nascono sempre «da approvare».
7. Chiudi con check e riporta l'esito.

Regole che non si derogano:

• Non inventare: ciò che non è noto resta DA COMPILARE o diventa una domanda.
• Mai approvare da solo: una spec diventa Approvata solo dopo un sì esplicito dell'utente (procedura in scrittura.md §5).
• Mai sovrascrivere documenti esistenti; i contenuti sparsi si spostano nei documenti giusti, con l'accordo dell'utente.

---

1. Trovare la documentazione

Cerca nell'ordine: docs/, src/docs/, */src/docs/, documentation/. Una cartella è spec-driven se contiene almeno PROJECT_MEMORY.md o 00-INDEX.md più uno fra DECISIONS.md, TODO.md, REQUIREMENTS.md. Leggi anche CLAUDE.md/README.md alla radice del repository: possono indicare la cartella o regole locali.

Se non la trovi, non scrivere codice: di' all'utente che il progetto non ha documentazione spec-driven e proponi di crearla (§A). Se l'utente preferisce procedere senza, rispetta la scelta e annotala nella risposta.

Due layout ricorrenti (dettagli in references/layout.md):

Layout	Riconoscimento	Esempio
Strutturato	cartelle 01-product/ … 08-project/, 00-INDEX.md, 03-specs/SPEC-xxx-*.md	KadeonCad_v2/docs
Piatto	tutti i .md in una cartella, specifiche come documenti di modulo (CAD_MODULE.md, whatsapp/DESIGN.md)	Kadeon/kadeon/src/docs

---

2. Lettura di inizio sessione (sempre, prima del codice)

1. overview con lo script.
2. PROJECT_MEMORY.md — per intero. Contiene ciò che non è deducibile dal codice e che, se dimenticato, fa ripetere errori: vincoli non negoziabili, azioni pendenti di sicurezza, «le cose da non dimenticare mai». Tienile presenti per tutta la sessione.
3. 00-INDEX.md (layout strutturato) — tabella degli step, stato dell'implementazione e i riquadri > **Titolo (data):** in testa: sono le novità più recenti, in ordine inverso.
4. Indice di DECISIONS.md — solo la tabella iniziale; le singole decisioni si leggono quando servono.
5. TODO.md — sezione «fuori sequenza / prima di tutto» e la fase corrente.

Non leggere CHANGELOG, DEVELOPMENT_LOG, openapi.yaml per intero: si interrogano per ID o data.

---

3. Prima di implementare: il cancello

Rispondi a queste domande prima di scrivere una riga. Se una risposta è «no», fermati e dillo all'utente.

#	Domanda	Dove si verifica	Se «no»
1	Il lavoro richiesto corrisponde a un T-xxx?	TODO, sezione Task della spec	Proponi il task e la spec di appartenenza
2	Il task appartiene a una SPEC-xxx in stato Approvata?	riga Stato: della spec, 00-INDEX	Non implementare: segnala lo stato (da approvare, 🟡) e chiedi
3	Le dipendenze del task (colonna Dipende da) sono ✅?	TODO, tabella task della spec	Segnala l'ordine corretto
4	Nessuna decisione D-xxx accettata lo vieta o lo vincola diversamente?	DECISIONS (per ID), PROJECT_MEMORY	Cita la decisione; una deviazione richiede una nuova D-xxx
5	Se tocca un requisito di parità (tipo P) cambia il comportamento?	REQUIREMENTS, colonna Tipo	È una decisione di prodotto: serve una D-xxx
6	Contratto API e schema dati sono già scritti?	openapi.yaml / API.md, DATABASE.md	Si scrive prima il contratto (contract-first)

Eccezione legittima: richiesta esplicita dell'utente di procedere comunque. In quel caso procedi, ma registra la deviazione (vedi §6) — è ciò che i progetti chiamano «inversione» e che va lasciata scritta.

---

4. Leggere una spec

Struttura tipica di una SPEC-xxx (le sezioni possono variare):

1. Intestazione: Stato, versione, data, requisiti coperti, decisione di riferimento.
2. Contesto e obiettivo — il perché; spesso contiene un dato misurato che giustifica la scelta.
3. «Cosa cambia rispetto a ciò che è già scritto» — elenco dei punti fermi che la spec modifica.
4. Regole / algoritmo in forma normativa: le parole in grassetto e i «non» sono vincoli.
5. Contratto API: rotta, ingresso, uscita, tabella degli esiti con codici HTTP.
6. Errori.
7. Criteri di accettazione (D1…D12, P1…P24, …): ognuno diventa almeno un test.
8. Task con dipendenze.

Regole di lettura:

• Leggi la spec intera quando la implementi; usa l'indice di context per le altre.
• I paragrafi «è una decisione, non una dimenticanza» descrivono comportamenti voluti che sembrano bug: non «correggerli».
• Sezioni con suffisso bis/ter (es. §5.3bis) sono aggiunte successive: leggile, spesso modificano la regola base.
• Per ogni REQ- citato leggi la riga in REQUIREMENTS: colonna Tipo (P parità / C correzione / N nuovo) e Origine (per i P la fonte di verità è il codice della versione precedente indicato lì).
• Per ogni D- citata leggi solo la sezione ## D-xxx (Contesto → Decisione → Alternative → Conseguenze). Una decisione Superata da D-yyy non vale più: segui D-yyy.
• Il glossario (GLOSSARY.md) fissa i termini: usa gli stessi nomi nel codice e nei messaggi.

---

5. Il brief di implementazione

Prima di scrivere codice, presenta all'utente un brief compatto con il modello in references/brief-template.md: obiettivo, stato della spec, requisiti, regole normative, contratto, criteri di accettazione → test, task e dipendenze, decisioni vincolanti, file di codice probabilmente toccati, incoerenze trovate.

Per un task piccolo il brief può stare in poche righe; non saltare mai le sezioni criteri e incoerenze.

---

6. Dopo l'implementazione: chiudere il ciclo

Aggiorna la documentazione nella stessa modifica del codice, seguendo references/chiusura-ciclo.md. In sintesi:

Documento	Cosa scrivere	Quando
TODO	stato del task (⬜ → 🟡 → ✅)	✅ solo con test passanti
TRACEABILITY	stato della riga REQ, criteri coperti	quando il test passa, non quando il codice è scritto
spec	nuove sezioni bis, criteri e task aggiunti	se la regola cambia o si estende
DECISIONS	nuova D-xxx (mai modificarne una vecchia: la si supera)	ogni scelta strutturale o deviazione
CHANGELOG	cosa cambia per chi usa il prodotto	ogni modifica visibile
DEVELOPMENT_LOG	cosa si è scoperto e perché si è deciso così	scoperte, tentativi respinti, misure
PROJECT_MEMORY	solo ciò che, dimenticato, fa ripetere un errore	raramente
00-INDEX	riquadro > **Titolo (data):** in testa + date «Ultimo aggiornamento»	ogni consegna rilevante

Riporta sempre il numero di test eseguiti e il loro esito reale (es. «backend 614 (+3)»). Non dichiarare ✅ ciò che non è stato verificato: scrivi 🟡 e cosa manca.

---

7. Incoerenze e fonti di verità

La documentazione viva va in deriva: indici non aggiornati, totali vecchi, spec marcata «da approvare» ma task già ✅, ID citati e mai definiti (l'overview li elenca). Quando le trovi:

1. Non correggere in silenzio e non sceglierne una a caso. Elencale nel brief.
2. Applica la gerarchia delle fonti di verità dichiarata dal progetto. Default:
   • contratto API → openapi.yaml (non API.md, non il codice);
   • requisiti di parità → codice della versione precedente citato in Origine;
   • stato «verificato» → test eseguiti (non la TRACEABILITY);
   • decisioni → l'ultima D-xxx accettata che non è superata;
   • stato di una spec → la sua riga Stato:; in assenza, l'indice.
3. Se l'incoerenza blocca il lavoro, chiedi all'utente; altrimenti prosegui e proponi la correzione documentale insieme alla consegna.

---

8. Cose da non fare

• Implementare da una spec da approvare o da un'idea non scritta, senza dirlo.
• «Modernizzare» ciò che un requisito di parità o una decisione congela.
• Rinumerare o riusare un ID: gli ID sono immutabili; quelli eliminati si barrano (~~T-005~~).
• Cancellare una decisione o una voce di diario: si superano o si annotano.
• Leggere per intero file da migliaia di righe quando basta una sezione.
• Copiare segreti trovati nella documentazione in risposte, log o commit.

---

_{STS Lab Srl · Spec-Driven Reader v1.1 (lettura + scrittura) · 2026-10-16 · uso interno e per i clienti STS Lab Srl}