Documentazione ARchetipo

Quick start

Con un comando npm installa la CLI di ARchetipo a livello globale.

npm install -g @techreloaded/archetipo

# verifica installazione e versione
archetipo version

Inizializza un progetto

Dopo l'installazione globale, prima di usare ARchetipo in un progetto devi inizializzarlo nella sua directory:

$ cd il-mio-progetto
$ archetipo init

# oppure in modo non interattivo:
$ archetipo init --tool claude --connector file

Cosa fa archetipo init

• Copia le skill ARchetipo nella directory del tool AI selezionato, ad esempio .claude/skills/ o .gemini/skills/.
• Crea .archetipo/config.yaml con il connector scelto (file di default).
• Crea .archetipo/shared-runtime.md con le regole runtime del progetto.
• Può essere eseguito in modo interattivo (archetipo init) o non interattivo con flag come --tool, --connector e --yes.

Glossario

Concetti di base che ricorrono in tutta la documentazione e nelle skill.

Termine	Significato
PRD	Product Requirements Document: definisce cosa costruire, per chi e perché. È il punto di partenza della pipeline.
Backlog	Lista ordinata di user story da implementare, ciascuna con priorità, stima e stato (TODO -> PLANNED -> IN PROGRESS -> REVIEW -> DONE).
User story	Unità atomica di requisito dal punto di vista dell'utente: "Come <persona> voglio <azione> così che <beneficio>".
Epic	Raggruppamento di user story correlate con un obiettivo condiviso. Ogni story appartiene a un epic.
Planning	Documento tecnico per una singola story con soluzione, task ordinati, dipendenze e strategia di test. Salvato dal file connector in .archetipo/plans/US-XXX-plan.yaml.
Acceptance criteria	Condizioni verificabili che definiscono quando una story può considerarsi completata.
Connector	Modalità di persistenza degli artefatti del progetto: file system locale tramite CLI ARchetipo oppure GitHub Projects v2 + Issues.

Come usarlo

Il workflow

Dopo l'installazione, segui questo flusso nel tuo AI coding agent. Ogni slash-command invoca una skill che produce artefatti persistenti e alimenta la fase successiva.

ARchetipo implementa la metodologia Spec-Driven Development: la specifica è il contratto, e il ciclo spec -> plan -> implement si ripete per ogni slice di valore fino a completare il prodotto.

STEP 01 · DISCOVERY: definisci il prodotto

Comando: /archetipo-inception

Discovery e definizione del prodotto. Guida la fase di discovery con un team virtuale. Raccoglie obiettivi, scope e ipotesi di business, produce il PRD.

• Prerequisito: nessuno
• Team: Andrea, Costanza, Leonardo, Livia, Emanuele
• Output: docs/PRD.md

STEP 02 · OPZIONALE: crea concept visivi

Comando: /archetipo-design

Mockup e prototipi UI. Produce mockup HTML/CSS isolati in docs/mockups/ senza toccare il codice applicativo. Usati come riferimento visivo da archetipo-implement.

• Prerequisito: nessuno
• Team: Livia
• Output: docs/mockups/

STEP 03 · BACKLOG: genera il backlog iniziale

Comando: /archetipo-spec

Creazione ed estensione del backlog. Converte il PRD in backlog oppure aggiunge nuove story INVEST-compliant a uno esistente, con domande sfidanti di qualità. Auto-rileva la modalità.

• Prerequisito: PRD esistente
• Team: Andrea, Emanuele
• Output: .archetipo/backlog.yaml

STEP 04 · PLANNING: pianifica una storia

Comando: /archetipo-plan US-001

Piano tecnico di implementazione. Trasforma una story TODO in piano tecnico con soluzione, task ordinati, dipendenze e strategia di test, inclusi e2e con video recording.

• Prerequisito: story già presente nel backlog
• Team: Emanuele, Leonardo, Ugo, Mina
• Output: .archetipo/plans/US-001-plan.yaml

STEP 05 · CODE: implementa il codice

Comando: /archetipo-implement US-001

Scrittura di codice e test. Esegue il piano tecnico: scrive codice, test unit/integration/e2e, effettua code review automatica e porta la story verso REVIEW.

• Prerequisito: planning file, story PLANNED
• Team: Ugo, Mina, Cesare
• Output: codice, test, review notes

Auto-detect della lingua

Ogni skill adotta automaticamente la lingua della conversazione. Scrivi in italiano, ricevi artefatti in italiano. Scrivi in inglese, ricevi artefatti in inglese.

Stati workflow

Le storie transitano tra stati standardizzati. Le transizioni automatiche avvengono durante il loop; il passaggio finale a DONE è sempre manuale.

Stato	Significato	Transizione
TODO	Storia nel backlog, non ancora lavorata	auto, da spec
PLANNED	Pianificazione tecnica completata	auto, da plan
IN PROGRESS	Implementazione in corso	auto, da implement
REVIEW	Code review e test passati, pronta per approvazione umana	auto, fine implement
DONE	Storia accettata e rilasciata	manuale

Da dove parto?

Guida rapida per scegliere la skill giusta in base alla fase del tuo progetto. Segui le domande in ordine.

Domanda	Se la risposta è no	Se la risposta è sì
Hai già un PRD?	Usa /archetipo-inception.	Continua.
Vuoi concept visivi prima dello sviluppo?	Salta design per ora.	Usa /archetipo-design.
Hai già un backlog di story?	Usa /archetipo-spec.	Continua.
Le story sono già pianificate?	Usa /archetipo-plan US-001 su una story TODO.	Continua.
Una story è pronta da implementare?	Pianificala prima.	Usa /archetipo-implement US-001.

CLI e comandi disponibili

ARchetipo usa una CLI scritta in Go, archetipo, che implementa le operazioni di configurazione e persistenza degli artefatti.

Nell'uso normale di ARchetipo, interagisci con le skill /archetipo-* e sono loro a invocare autonomamente i comandi necessari in base allo stato del progetto. La CLI legge .archetipo/config.yaml dal repository per conoscere la configurazione corrente.

Gli unici comandi che ha davvero senso usare manualmente nella pratica quotidiana sono questi:

archetipo init

Installa ARchetipo nel repository corrente: copia le skill nel tool AI selezionato e crea .archetipo/config.yaml più .archetipo/shared-runtime.md.

archetipo init

# oppure in modo non interattivo
archetipo init --tool claude --connector file

archetipo view

Avvia la visualizzazione locale del backlog in forma Kanban. È particolarmente utile con il connector file, perché legge e mostra gli artefatti salvati sotto .archetipo/.

archetipo view

archetipo version

Mostra la versione della CLI installata. È utile subito dopo npm install -g @techreloaded/archetipo per verificare che l'installazione sia andata a buon fine e controllare quale release stai usando.

archetipo version

Tutti gli altri sub-comandi della CLI esistono soprattutto come superficie tecnica usata internamente dalle skill per leggere backlog, salvare piani, aggiornare stati e completare task.

Connector

ARchetipo non lega il workflow a un unico sistema di storage. Lavora su un set stabile di artefatti di progetto e usa un connector per decidere dove questi artefatti vengono letti, salvati e aggiornati. Così il metodo resta identico anche se cambi supporto: repo locale quando vuoi lavorare in autonomia, GitHub quando vuoi tracking condiviso e board cloud.

In pratica, le skill ragionano sempre sugli stessi concetti — PRD, backlog, spec, piani, task, mockup — mentre il connector traduce queste operazioni nel sistema di persistenza configurato in .archetipo/config.yaml.

Gli artefatti di ARchetipo

Artefatto	Che cos'è	A cosa serve
PRD	Documento di visione e requisiti di alto livello.	Allinea obiettivi, personas, scope e vincoli prima di costruire il backlog.
Backlog	Vista ordinata delle spec da realizzare.	Rende visibili priorità, stato di avanzamento ed epic del progetto.
Spec	Scheda strutturata di una specifica con titolo, corpo, acceptance criteria, priorità e stato.	È l'unità di lavoro che attraversa il ciclo spec -> plan -> implement.
Piano tecnico	Traduzione implementativa di una spec: soluzione, task ordinati, dipendenze e strategia di test.	Guida l'implementazione senza lasciare ambiguità operative all'agente.
Task	Passi eseguibili che compongono un piano tecnico.	Permettono di monitorare il lavoro in modo granulare e verificabile.
Mockup	Concept UI isolati dal codice applicativo.	Forniscono un riferimento visivo per la fase di implementazione.

Come lavora un connector

• La skill legge .archetipo/config.yaml per sapere quale connector è attivo.
• ARchetipo invoca gli stessi comandi CLI, indipendentemente dal connector scelto.
• Il connector traduce le operazioni di lettura e scrittura nel sistema corretto: file locali oppure GitHub.

Risultato: puoi cambiare dove vivono i tuoi artefatti senza riscrivere skill, prompt o processo di prodotto.

Dove vivono gli artefatti

Artefatto	Connector file	Connector github
PRD	docs/PRD.md	docs/PRD.md
Backlog	.archetipo/backlog.yaml	Issue sulla board GitHub Projects v2
Spec	.archetipo/specs/US-XXX.yaml	Issue padre con corpo della story e metadati di board
Piano tecnico	.archetipo/plans/US-XXX-plan.yaml	Aggiunto al body della issue padre
Task	Nel piano YAML della spec	Sub-issue collegate alla story
Mockup	docs/mockups/	docs/mockups/
Board e stati	Board locale via archetipo view	GitHub Projects v2 con campi custom

Connector file

È il connector di default. Tiene backlog, spec e piani nel repository, senza autenticazione e con piena versionabilità. È ideale per lavoro individuale, sperimentazione rapida e contesti offline. La board locale di archetipo view legge questi artefatti e li rende navigabili in forma Kanban.

Connector GitHub

Porta il workflow su GitHub Projects v2 e GitHub Issues. È pensato per team che vogliono visibilità condivisa, stati di avanzamento sul board e task eseguibili come sub-issue, lasciando comunque il PRD e i mockup come file nel repo.

Estendibilità. Oggi i connector integrati sono file e github, ma l'architettura è pensata per poter aggiungere in futuro altri target come Linear, Jira o Trello.

Configurazione

.archetipo/config.yaml definisce connector, percorsi e stati di workflow. Se il file manca, la CLI usa la configurazione di default; se alcune chiavi sono assenti, completa automaticamente i valori mancanti con i default ufficiali.

connector: file   # file | github

# percorsi condivisi da tutti i connector
paths:
  prd: docs/PRD.md
  mockups: docs/mockups/
  test_results: docs/test-results/

workflow:
  statuses:
    todo: TODO
    planned: PLANNED
    in_progress: IN PROGRESS
    review: REVIEW
    done: DONE   # nessuna skill porta automaticamente una spec a DONE

# usato solo quando connector == file
file:
  backlog: .archetipo/backlog.yaml
  planning: .archetipo/plans/

# usato solo quando connector == github
github:
  # owner: auto-detected from repo
  # project_number: auto-detected from repo

• connector seleziona il backend di persistenza: file oppure github.
• paths definisce i percorsi condivisi da tutti i connector: PRD, mockup e risultati dei test.
• file contiene i percorsi specifici del connector locale: backlog e planning.
• workflow.statuses permette di mappare le etichette di stato usate dal progetto; i valori mancanti vengono riempiti con i default.
• github contiene override opzionali del connector GitHub; owner e project_number vengono auto-rilevati se lasciati vuoti.
• I vecchi campi paths.backlog e paths.planning non sono più validi: vanno migrati rispettivamente in file.backlog e file.planning.

Filosofia

Il team è una lente, non un costume

Ogni persona applica un angolo di analisi. Il brief è conciso e serve a rendere visibile il processo.

Contesto lean

Le skill leggono solo ciò che serve, nell'ordine: shared-runtime -> config -> comandi CLI -> template. I file grandi si leggono chirurgicamente.

Output persistenti

Ogni fase produce artefatti che vivono nel repo o nel sistema connector. Il prossimo comando parte da lì.

Autonomia responsabile

Le skill si fermano solo davanti a blocker reali: dipendenze esterne o ambiguità sul contratto. Adattamenti locali e fix meccanici non richiedono conferma.

Tool e connector agnostici

Cambiare AI agent o sistema di tracking non deve riscrivere il processo.

FAQ

Serve sempre il PRD per iniziare?

Per costruire un backlog solido sì: il PRD è il punto di partenza ideale. Se non esiste ancora, usa archetipo-inception per crearlo prima di passare a archetipo-spec.

Posso aggiungere story senza rifare tutto il backlog?

Sì. archetipo-spec distingue tra generazione iniziale ed estensione: se il backlog esiste, aggiunge o raffina story senza ripartire da zero.

I mockup prodotti da design finiscono nel codice applicativo?

No. archetipo-design produce file isolati in docs/mockups/ usati solo come riferimento visivo da archetipo-implement, che li legge prima di scrivere l'interfaccia reale.

Posso usare ARchetipo su un progetto già esistente?

Sì. archetipo-spec in modalità extend-backlog aggiunge storie a un backlog esistente. archetipo-plan e archetipo-implement lavorano su qualsiasi storia presente, indipendentemente da come è stata creata.

Cosa succede se il mio AI tool non supporta i subagent?

Le skill principali funzionano lo stesso, in modalità in-context.

Troubleshooting

La skill non trova il PRD

Verifica che paths.prd in .archetipo/config.yaml punti al file corretto. Il valore di default è docs/PRD.md.

Il connector GitHub non transiziona le issue

Controlla che gh sia autenticato (gh auth status) e che il token abbia gli scope repo e project. Le transizioni di stato avvengono tramite GraphQL sui campi custom del Project.

Gli artefatti sono nella lingua sbagliata

Le skill rilevano la lingua dall’ultimo messaggio utente. Se il contesto è misto, invia un messaggio esplicito nella lingua desiderata prima di invocare la skill.

Beta Test

ARchetipo è in beta: abbiamo preparato una pagina con documentazione tecnica, repository GitHub, server Discord e prove consigliate per aiutarci a migliorare il workflow su progetti, agenti AI e contesti reali. Se vuoi partecipare, trovi risorse, canali di feedback e checklist operative nella pagina Beta ARchetipo.

Licenza

MIT © techreloaded. Fork, modifiche e contributi benvenuti: apri una PR o una discussion sul repository.

Per segnalare bug, proporre feature o chiedere supporto, apri una issue sul repository GitHub o entra nelle Discussions.