In breve: i repository “vivi” — pieni di AGENTS.md, PLAN.md, ARCHITECTURE.md — si sporcano in fretta: il contesto smette di raccontare cosa il codice fa davvero. Repo Forge è il workflow in tre passi (Seed → Scan → Keeper) che ho costruito per tenerli allineati nel tempo.
Evitare il repository drift
Nel precedente articolo Intent Source parlavo di una cosa che negli ultimi tempi mi capita sempre più spesso: apro un repository e, prima ancora del codice, mi ritrovo a guardare file come AGENTS.md, PLAN.md, ARCHITECTURE.md o BACKLOG.md.
L’idea era abbastanza semplice: forse il repository non sta più contenendo solo codice.
Però mentre lavoravo su questa roba mi sono accorto di un problema molto meno filosofico e molto più pratico.
All’inizio quei file sono quasi sempre ordinati.
Poi il progetto parte davvero.
Si aggiunge una feature, si cambia direzione, si scopre che una scelta fatta all’inizio non funziona più così bene. Il backlog cambia, l’architettura cambia, qualche decisione rimane in testa invece di finire in un documento.
Niente di drammatico.
- un AGENTS.md che descrive un progetto vecchio;
- piani che non corrispondono più al lavoro reale;
- decisioni architetturali prese ma mai scritte;
- documentazione corretta… tre settimane fa.
Il problema non è creare il repository. Quello ormai è quasi la parte facile. Il problema è mantenere allineato il contesto.
Da qui nasce Repo Forge
Repo Forge è nato per risolvere esattamente questa cosa.
Non è una singola skill ma un piccolo workflow diviso in tre parti:
Seed → Scan → Keeper
Seed
Genera struttura, documentazione, backlog, piani, ADR e file di contesto. In pratica prepara il terreno.
Scan
Guarda cosa c’è dentro, identifica strutture mancanti e prova a capire se il progetto è ancora coerente oppure se ha iniziato a divergere.
Keeper
Serve a riallineare documenti, piani e contesto per evitare che il repository inizi lentamente a raccontare una storia diversa dal codice che contiene.
Una cosa che mi ha colpito
Mentre costruivo queste skill mi sono accorto che stavo trattando il repository in un modo leggermente diverso da prima.
Non più come una cartella di file.