spec-driven-devlopment/spec-as-source

Workflow di spec-driven development costruito su OpenSpec, con enforcement meccanico per lo spec-as-source sopra di esso.

OpenSpec porta un progetto a spec-anchored (propose → apply → archive, con openspec/specs/<capability>/spec.md come specifica canonica), ma non verifica nulla da solo. Questo plugin aggiunge una schema OpenSpec custom (spec-as-source) e gli strumenti che rendono la spec un vincolo strutturale: ownership dei file, verifica dei test, workflow CI, e le skill che li orchestrano.

Installazione

# prerequisito: CLI OpenSpec
npm install -g @fission-ai/openspec

# nel tuo progetto
tessl install spec-driven-devlopment/spec-as-source

Richiede: openspec CLI, git, e un test runner (pytest / vitest / jest / cargo / go).

Cosa installa

Rule (sempre attive)

Skill — prima di scrivere codice (on-demand)

Skill — workflow OpenSpec (on-demand, genericizzate cross-agente)

Skill — enforcement spec-as-source (on-demand)

Skill — continuità di sessione (on-demand)

Docs

docs/policy.md — la policy in chiaro: perché esiste, come funziona, il ciclo di vita completo, il gap di migrazione da v1.x.

Uso tipico

# 1. una tantum: installa schema OpenSpec + infrastruttura di enforcement
Use spec-as-source-setup.
Use handoff.    # opzionale: installa anche l'hook PreCompact (Workflow E)

# 2. per ogni nuova feature
Use requirement-gathering.    # se la richiesta è vaga: chiarisce scope ed edge case
Use openspec-propose.         # o openspec-explore se l'idea non è ancora chiara
Use spec-writer.               # se serve scrivere/correggere una spec a mano
Use openspec-apply-change.     # implementa tasks.md
Use spec-verify.                # verifica targets/test/drift contro la spec
Use work-review.                 # review requisito-per-requisito prima di dire "fatto"
Use openspec-archive-change.     # chiude il change, unisce le spec

# 3. manutenzione occasionale
Use spec-ci-sync.    # dopo aver cambiato stack o aggiunto test
Use spec-rebuild.     # per dimostrare che le spec bastano a ricostruire il codice

# 4. quando la sessione si allunga
Use handoff.    # salva lo stato prima che il contesto rischi allucinazioni

Cosa crea spec-as-source-setup nel progetto:

openspec/schemas/spec-as-source/     # schema OpenSpec custom con targets + [@test]
scripts/check-spec-links.sh          # ogni [@test] punta a un file esistente
scripts/check-target-ownership.sh    # un target non cambia senza la sua spec
scripts/build-spec-manifest.py       # mappa spec → requisiti → target → test
scripts/verify.sh                    # esegue i tre script + test suite
.pre-commit-config.yaml              # gli stessi check in locale
.github/workflows/spec-verification.yml  # gli stessi check in CI

I 5 controlli di spec-verify

I primi 4 girano anche in CI (meccanici); il quinto è una review qualitativa che solo un agente può fare:

Il controllo #2 è il cuore dello spec-as-source: è ciò che OpenSpec da solo non ha. Il controllo #5 è il cuore di work-review: prova che spec e codice dicano davvero la stessa cosa, non solo che i link tra loro siano formalmente a posto.

Aggiornamento

tessl update spec-driven-devlopment/spec-as-source
# poi RIAVVIA Claude Code: le skill si caricano all'avvio della sessione

Se tessl update non vede il plugin, non è registrato in tessl.json: installalo prima con tessl install spec-driven-devlopment/spec-as-source.

Convenzioni delle spec

Perché gli script funzionino, ogni openspec/specs/<capability>/spec.md deve avere:

---
targets:
  - src/percorso/file.py      # i file che questa capability possiede
---

# <Capability> Specification

## Purpose
...

## Requirements

### Requirement: <nome del requisito>
Descrizione normativa (SHALL/MUST).

**Verified by**: [@test] tests/percorso/test_file.py

#### Scenario: <nome scenario>
- **WHEN** ...
- **THEN** ...

• frontmatter con targets (dichiarazione di proprietà), prima del titolo;
• requisiti con nome libero nell'header ### Requirement: <nome> (formato OpenSpec, non più ID REQ-*);
• ogni requisito con una riga **Verified by**: [@test] <path> dopo la frase normativa, mai come prima riga del blocco.

Una spec appena creata da openspec archive per una capability nuova parte senza frontmatter (lo scheletro di OpenSpec non ne genera uno): non è una violazione finché non viene modificata in modo non banale, momento in cui deve guadagnarsi un targets:.

Migrazione da v1.x

Le versioni precedenti alla 2.0.0 imponevano un formato di spec diverso e fatto in casa: file flat in specs/<nome>.spec.md con header REQ-<AREA>-<NNN>. Non esiste una skill di migrazione automatica. Spostare un progetto v1.x a questa versione richiede di ricreare manualmente ogni spec sotto openspec/specs/<capability>/spec.md seguendo la nuova convenzione frontmatter + **Verified by**, e aggiornare i percorsi [@test] di conseguenza.

Autore

Costruito da Giuseppe Di Canosa. Workspace spec-driven-devlopment.