av/facts

Was ist facts?

av/facts ist ein Workflow und Spezifikationsformat zur Verwaltung eines Projekts als Liste von atomaren Claims in einer .facts-Datei. Jede Zeile ist eine kurze, strukturierte Aussage darüber, was zutreffen sollte, und kann optional einen Shell-Befehl enthalten, den die Maschine ausführt, um den Claim zu verifizieren.

Der Kernzweck ist es, einem Agenten und Ihrem Team zu ermöglichen, Projektanforderungen lesbar und überprüfbar zu halten: Sie schreiben grobe Wahrheiten, verfeinern sie zu präzisen Specs und implementieren sowie verifizieren sie dann. Mit facts check sehen Sie, welche Claims bestehen, fehlschlagen oder manuelle Aufmerksamkeit brauchen.

Wichtige Funktionen

• Atomare „Fact“-Spezifikationsformat (.facts): Schreiben Sie pro Zeile einen Claim als einfachen String, organisiert mit Markdown-Überschriften nach Domäne.
• Lifecycle-Tagging für Fortschrittsverfolgung: Verwenden Sie @draft, @spec und @implemented (plus beliebige benutzerdefinierte Tags), um den Status jedes Claims in der Pipeline anzuzeigen.
• Befehlsbasierte Verifikation: Für Facts mit command führt facts check den Befehl aus und hält den Claim für wahr, wenn der Befehl mit Exit-Code 0 endet.
• Automatisierte Verifikation und Statusgruppierung: facts check lintet Dateien, führt jeden Befehl aus und gruppiert Ergebnisse (z. B. grüner Pass, roter Fail, gelber Manual); es endet mit non-zero, wenn etwas fehlschlägt.
• CI-freundliche Exit-Codes und Filterung: Filtern Sie Checks nach Tag-Ausdrücken (z. B. --tags "mvp and not blocked"), um Teilmengen Ihrer Spec zu verifizieren.
• Agent-gesteuerte Übergänge und Implementierung gegen die Spec: Ein Agent liest die Fact-Tabelle, nimmt @spec-Facts auf, baut sie, führt facts check aus und tagt bestehende Facts als @implemented, während die Spec sich selbst aktualisiert.

So verwenden Sie facts

1. Installieren Sie das CLI/Agent-Tooling (das Projekt bietet mehrere Installationsoptionen, inklusive Rust-Binary und npx-Befehl wie unten beschrieben).
   • Beispiel: npx skills add av/facts
   • Fordern Sie den Agenten dann auf, Init facts auszuführen (z. B. „Init facts“), um Ihren Stack zu erkennen und eine initiale .facts-Datei zu erstellen.
2. Erstellen oder bearbeiten Sie Ihre .facts-Datei im dokumentierten Format:
   • Fügen Sie Überschriften zur Organisation nach Domäne hinzu (z. B. # auth, # data).
   • Fügen Sie pro Zeile einen Claim hinzu.
   • Taggen Sie jeden Fact mit Lifecycle-Stufen wie @draft, @spec oder @implemented.
   • Für verifizierbare Claims fügen Sie einen command hinzu, der mit 0 endet, wenn der Claim zutrifft.
3. Führen Sie Verifikation aus: Nutzen Sie facts check, um alle Facts zu linten und zu verifizieren (oder --tags zur Begrenzung). Prüfen Sie, welche bestanden, fehlschlugen oder manuelle Arbeit brauchen.
4. Iterieren Sie mit dem Agenten: Schreiben Sie grobe Ideen als @draft, verfeinern Sie sie zu @spec, lassen Sie den Agenten dann @spec-Facts implementieren und taggen Sie sie nach facts check-Bestand als @implemented.

Anwendungsfälle

• Projekt-Spec-Validierung nach Änderungen: Halten Sie eine lebende Checkliste dessen, was zutreffen muss, und führen Sie facts check nach Edits aus, um schnell zu sehen, was noch hält.
• Anforderungen in ausführbare Checks umwandeln: Konvertieren Sie „muss zutreffen“-Aussagen (wie Auth-Verhalten oder Datenhandhabungsregeln) in Facts mit befehlsbasierter Verifikation.
• Work-in-Progress mit Fact-Lifecycle managen: Nutzen Sie @draft → @spec → @implemented, um Fortschritt zu kommunizieren und sicherzustellen, dass jeder Claim entweder implementiert/verifiziert oder klar zur Verfeinerung markiert ist.
• Automatisierte Codebase-Entdeckung und Klassifikation: Verwenden Sie die facts-discover-Skill, um die Codebase zu scannen und Facts nach Lifecycle-Stufe zu klassifizieren, inklusive Hinzufügen fehlender Wahrheiten.
• Implementieren gegen eine Spec: Nutzen Sie den facts-implement-Flow, bei dem der Agent @spec-Facts liest, Code baut, mit facts check verifiziert und Tags aktualisiert.

FAQ

Ist facts nur ein Dokumentationsformat, oder verifiziert es Claims wirklich? Es kann beides: Facts ohne Commands können vom Agenten gegen die Codebase verifiziert werden, Facts mit command werden durch Ausführung des Befehls und Prüfung auf Exit-Code 0 verifiziert.

Was macht facts check? Es lintet Dateien, führt jeden angegebenen Befehl aus, gruppiert Ergebnisse nach Status (pass/fail/manual) und endet mit non-zero, wenn etwas fehlschlägt.

Wie werden Facts organisiert und verfolgt? Facts leben in einer .facts-Datei im Markdown/YAML-kompatiblen Format, mit Überschriften zur Domänenorganisation und Tags (inkl. @draft, @spec, @implemented) zur Verfolgung des Lifecycle-Status.

Kann ich nur Teile meines Projekts prüfen? Ja. facts check unterstützt Tag-Filterung via --tags mit booleschen Ausdrücken.

Alternativen

• Test-Suites (Unit/Integration-Tests): Traditionelle Tests verifizieren Verhalten, aber eine .facts-Checklist betont lesbare atomare Claims und einen Lifecycle/Status-Pipeline, nicht nur automatisierte Pass/Fail.
• Statische Dokumentation + Code-Review: Docs erfassen Anforderungen, sind aber meist nicht direkt ausführbar; facts verknüpft Claims mit Verifikation via facts check.
• Spezifikationstools mit Requirements-Traceability: Tools, die Anforderungen mit Implementierung verknüpfen, bieten Traceability, aber facts nutzt speziell ein zeilenweises Claim-Format mit optionaler Befehlsausführung und tagbasierten Lifecycle-Übergängen.