av/facts

Cos'è facts?

av/facts è un workflow e un formato di specifica per gestire un progetto come elenco di claim atomici in un file .facts. Ogni riga è un'affermazione breve e strutturata su ciò che deve essere vero, e può includere opzionalmente un comando shell che la macchina esegue per verificarla.

Lo scopo principale è consentire a un agente e al tuo team di mantenere i requisiti del progetto leggibili e verificabili: scrivi verità approssimative, raffinale in specifiche precise, quindi implementale e verificale. Puoi eseguire facts check per vedere quali claim passano, falliscono o richiedono attenzione manuale.

Caratteristiche Principali

• Formato di specifica “fact” atomica (.facts): Scrivi un claim per riga come stringhe semplici, organizzate con intestazioni Markdown per dominio.
• Tagging del ciclo di vita per il tracciamento dei progressi: Usa @draft, @spec e @implemented (più tag personalizzati) per mostrare lo stato di ogni claim nel suo flusso.
• Verifica supportata da comandi: Per i fact con un command, facts check esegue il comando e considera il claim vero se esce con 0.
• Verifica automatizzata e raggruppamento per stato: facts check linta i file, esegue ogni comando e raggruppa i risultati (es. verde pass, rosso fail, giallo manuale); esce con codice non-zero se qualcosa fallisce.
• Codici di uscita e filtraggio CI-friendly: Filtra i check per espressioni di tag (es. --tags "mvp and not blocked") per verificare sottoinsiemi della specifica.
• Transizioni gestite dall'agente e implementazione contro la specifica: Un agente legge il foglio dei fact, raccoglie i fact @spec, li costruisce, esegue facts check e tagga i fact passati come @implemented mentre la specifica si aggiorna da sola.

Come Usare facts

1. Installa il tooling CLI/agente (il progetto offre più opzioni di installazione, inclusi un binario Rust e un comando npx come descritto sotto).
   • Esempio: npx skills add av/facts
   • Poi chiedi all'agente di eseguire Init facts (es. “Init facts”) per rilevare lo stack e creare un file .facts iniziale.
2. Crea o modifica il tuo file .facts usando il formato documentato:
   • Aggiungi intestazioni per organizzare per dominio (es. # auth, # data).
   • Aggiungi un claim per riga.
   • Tagga ogni fact con etichette di stadio del ciclo di vita come @draft, @spec o @implemented.
   • Per claim verificabili, includi un command che esce con 0 quando il claim è valido.
3. Esegui la verifica: usa facts check per lintare e verificare tutti i fact (o usa --tags per limitare i check). Rivedi quali sono passati, falliti o richiedono lavoro manuale.
4. Itera con l'agente: scrivi idee approssimative come @draft, raffinale in @spec, poi lascia che l'agente implementi i fact @spec e li tagghi come @implemented dopo che passano facts check.

Casi d'Uso

• Validazione specifica del progetto dopo cambiamenti: Mantieni una checklist viva di ciò che deve essere vero e esegui facts check dopo le modifiche per vedere rapidamente cosa è ancora valido.
• Trasformare requisiti in check eseguibili: Converti affermazioni “deve essere vero” (come comportamenti di autenticazione o regole di gestione dati) in fact con verifica basata su comandi.
• Gestire work-in-progress con ciclo di vita dei fact: Usa @draft → @spec → @implemented per comunicare i progressi e assicurare che ogni claim sia implementato e verificato o chiaramente marcato per raffinamento.
• Scoperta e classificazione automatizzata del codebase: Usa la skill facts-discover per scansionare il codebase e classificare i fact per stadio del ciclo di vita, inclusa l'aggiunta di verità mancanti.
• Implementare contro una specifica: Usa il flow facts-implement dove l'agente legge i fact @spec, costruisce il codice, lo verifica con facts check e aggiorna i tag.

FAQ

facts è solo un formato di documentazione, o verifica davvero i claim? Può fare entrambe: i fact senza comandi possono essere verificati dall'agente contro il codebase, mentre i fact con un command sono verificati eseguendo il comando e controllando l'exit code 0.

Cosa fa facts check? Linta i file, esegue ogni comando fornito, raggruppa i risultati per stato (pass/fail/manuale) ed esce con codice non-zero se qualcosa fallisce.

Come sono organizzati e tracciati i fact? I fact vivono in un file .facts scritto in struttura compatibile Markdown/YAML, con intestazioni per organizzazione per dominio e tag (inclusi @draft, @spec, @implemented) per tracciare lo stato del ciclo di vita.

Posso verificare solo una parte del mio progetto? Sì. facts check supporta il filtraggio per tag tramite --tags con espressioni booleane.

Alternative

• Suite di test (test unitari/integrazione): I test tradizionali verificano comportamenti, ma una checklist .facts enfatizza claim atomici leggibili dall'uomo e un pipeline di ciclo di vita/stato, non solo pass/fail automatizzato.
• Documentazione statica + code review: I documenti catturano requisiti, ma di solito non sono direttamente eseguibili; facts lega i claim alla verifica tramite facts check.
• Tool di specifica con tracciabilità dei requisiti: Tool che collegano requisiti all'implementazione possono fornire tracciabilità, ma facts usa specificamente un formato claim riga per riga con esecuzione opzionale di comandi e transizioni di ciclo di vita basate su tag.