EvolveHQ/docflow

bootstrap

Sie installieren (oder rüsten nachträglich ein) ein dokumentationsgesteuertes Konventionenset im aktuellen Repository. Das Ziel ist ein Repository, das sowohl von Menschen als auch von Codierungsagenten anhand einer kleinen Menge kanonischer Dateien gesteuert werden kann. Übernehmen Sie den Mechanismus, der hier beschrieben wird – nichts zu irgendeinem anderen Projekt.

Schritt 1 – Erkennen der Situation

Überprüfen Sie das Repository, bevor Sie Fragen stellen. Verwenden Sie explizite Antworten und Freigaben wieder, die bereits in dieser Sitzung gegeben wurden; ersetzen Sie diese niemals durch Profilstandards oder fragen Sie erneut danach. Fassen Sie vor dem Schreiben den aufgelösten Artefakt-Root, die Tiefe, die Warteschlange, das Gate und die Koordinations-/Integrationsmodi basierend auf diesen Antworten zusammen. Wenn ein Host einen ausgewählten Ordner in eine Sandbox spiegelt, identifizieren Sie den tatsächlichen Zielpfad und wie verifizierte Ausgaben den ausgewählten Ordner erreichen; nennen Sie niemals einen unberührten Zielordner abgeschlossen, nur weil eine temporäre Sandboxkopie bestanden hat.

• Neues Repository (kein Quellcode, keine Dokumentation): Sie erstellen von Grund auf.

• Bestehendes Repository: Sie rüsten nachträglich ein.

  • Lesen Sie alle aktuellen README.md, CONTRIBUTING.md, AGENTS.md, CLAUDE.md, docs/, adr/, .github/, bevor Sie Änderungen vorschlagen.
  • Bewahren Sie vorhandenen Inhalt. Führen Sie zusammen, überschreiben Sie nicht. Wenn vorhandene Konventionen mit den untenstehenden in Konflikt stehen, zeigen Sie den Konflikt in Ihrer Bewertungszusammenfassung auf.
  • Wenn ADRs bereits in einem anderen Format existieren, schlagen Sie einen Migrationsplan vor (Umnummerierung, Behalten, Übersetzen), anstatt einen parallelen Baum zu erstellen.

• Bereits ein Docflow-Repository (enthält AGENTS.md + CONVENTIONS.md + einen ADR-Katalog): Sie fügen zu einer bestehenden Einrichtung hinzu, nicht neu einrüstend. Bauen nicht den Kern neu ein und stellen keine bereits geklärten Fragen erneut – lesen Sie die aufgezeichneten Entscheidungen aus CONVENTIONS.md/AGENTS.md (ADR-Form, Status Lebenszyklus, Artefakt-Root, Multi-Agenten-Modus und welche optionalen Ebenen bereits existieren). Bieten Sie dann an, jede abgewählte optionale Ebene zu aktivieren, die noch fehlt – plan/, _agent/, GLOSSARY.md, domains/ oder die zweite ADR-Form (die Technologievorlage) – und schreiben Sie nur die ausgewählten, durch Zusammenführen, unter dem aufgezeichneten Artefakt-Root, wobei alles andere unberührt bleibt. Stellen Sie nur die Fragen, die die neuen Ebenen benötigen (z. B. die Koordinationsfrage bei der Aktivierung von _agent/ – wo ein einzelner Autor ohne sowohl ein aufgezeichnetes Verifikations-Gate als auch eine Plan-Warteschlange korrekterweise gar kein _agent/ erhält und die Ebene einfach nicht benötigt wird). Dies ist der Einstiegspunkt für das Hinzufügen einer Ebene, die Sie beim ersten Bootstrap zurückgestellt haben. Ein Repository, das noch Koordinationsdateien aus einer früheren Einrichtung enthält, behält diese: Lassen Sie sie an Ort und Stelle und lassen Sie das Audit-Skill das Layout melden.

  Die Aktivierung von GLOSSARY.md schreibt die kanonische Hülle, niemals eine Neuschreibung. Wenn die Ebene ausgewählt ist und die Datei fehlt, schreiben Sie sie aus templates/GLOSSARY.md – die optionale Überschrift und den Prosa, dann die eine Begriff | Definition-Tabelle, die im generierten CONVENTIONS.md §Glossar aufgezeichnet ist. Wenn die Datei bereits existiert, lassen Sie sie unberührt: Die Aktivierung der Ebene fügt nichts hinzu, und add-convention erweitert die vorhandene Datei in der kanonischen Form oder audit bietet eine zugestimmte Migration an.

  Die Aktivierung der zweiten ADR-Form ist ein Schemawechsel, kein Dateikopieren. Es ist die eine zurückgestellte Ebene, die eine bereits aufgezeichnete Entscheidung ändert. Schreiben Sie daher alles in einem Durchgang oder gar nichts: Ersetzen Sie §ADR-Formen in CONVENTIONS.md mit dem Zwei-Formen-Text, fügen Sie die Technologie- Abschnittsreihenfolge und Form-Aufzählungspunkte zu AGENTS.md hinzu, schreiben Sie adr/0000-template-technology.md, und generieren Sie INDEX.md neu mit der Form-Spalte. Vorhandene ADRs behalten ihre Nummern und bleiben Capability- ein fehlendes shape:-Feld bedeutet bereits Capability, also wird kein ADR umgeschrieben und nichts umnummeriert. Die Hälfte des Wechsels strandet das Repository in dem Zustand, den der Schritt-4.5-Abgleich einen Widerspruch nennt: eine Technologievorlage, die ein Einzel-Form-Schema niemals auswählen wird.

  Ein Repository, das bereits die Legacy-Bereichskodierung verwendet, erhält stattdessen das Migrationsangebot. Einige Zwei-Form-Repositories wurden vor der Einführung der Form als deklariertes Feld eingerüstet und kodieren sie in der Nummer: §ADR-Formen zeichnet einen Grenzwert auf (Capability darunter, Technologie ab diesem), und adr/ enthält eine Vorlage, die anders als 0000 nummeriert ist (z. B. adr/0100-template.md). Jedes dieser Signale allein identifiziert es. Ein solches Repository hat keine fehlende Ebene – es hat bereits beide Formen –, bieten Sie daher nicht den Schemawechsel oben an, der es mit zwei konkurrierenden Kodierungen strandet. Bieten Sie die Migration auf das deklarierte Feld an, zu denselben Bedingungen, die das Audit-Skill verwendet:

  • Zeigen Sie zuerst die alt-zu-neu Nummernzuordnung als Trockenlauf: Capability- ADRs behalten ihre Nummern; Technologie-ADRs erhalten die Nummern nach der höchsten Capability-ADR, in ihrer ursprünglichen relativen Reihenfolge. Listen Sie daneben die Referenzen auf, die folgen (depends-on, supersedes / superseded-by, relative adr/NNNN-*.md-Links, INDEX.md, Domain-README.md-Auflistungen, plan/todo/ eigene ADR- Zeilen) und was als Historie bleibt (plan/done/-Fußzeilen, Commit- Nachrichten, Tags).
  • Schreiben Sie nichts ohne eine explizite Bestätigung dieser Zuordnung. Die Ablehnung ist ein gültiges Ergebnis: Das Repository behält die Bereichskodierung und erfüllt weiterhin seine eigenen Regeln.
  • Bei Bestätigung wenden Sie die Migration genau so an, wie der Audit-Skill's Migrationsschritt es festlegt – umnummerieren, shape: auf jedem ADR einstempeln, jede In-Katalog-Referenz umschreiben, die Grenzwert-Vorlage mit adr/0000-template-technology.md ersetzen, §ADR-Formen auf das deklarierte Feld umschreiben und jede Seed-ADR-Ausnahmeklausel entfernen, INDEX.md mit der Form-Spalte neu generieren – und landen Sie es als einen Commit, dessen Nachricht jedes alt-zu-neu-Paar auflistet. Diese Prozedur ist die einzige Wahrheitsquelle; paraphrasieren Sie hier keine zweite Variante davon.
  • Fahren Sie dann normal mit dem Wiederholungslauf für die Ebenen fort, die wirklich fehlen (plan/, _agent/, GLOSSARY.md, domains/).

Geben Sie an, welche Situation in einer Zeile zutrifft, bevor Sie die Bewertungsfragen stellen.

Schritt 2 – Ziellayout

<repo>/
  AGENTS.md              # Harte Regeln für Codierungsagenten – Einstiegspunkt
  CLAUDE.md              # Einzeiler: @AGENTS.md
  README.md              # Menschliche Projektzusammenfassung (vorhanden erhalten)
  CONVENTIONS.md         # Autorenregeln: ADRs, Benennung, Status, Audit, Git
  INDEX.md               # Generierte Tabelle aller ADRs
  GLOSSARY.md            # Gemeinsame Begriffe (optional – siehe Q7)
  adr/
    0000-template.md     # Capability-ADR-Vorlage (immer)
    0000-template-technology.md  # Technologie-ADR-Vorlage (nur bei zwei Formen – siehe Q2)
    NNNN-<kebab-slug>.md # Ein ADR pro Entscheidung, fortlaufende Nummerierung
  domains/<slug>/README.md   # Optional (siehe Q7)
  plan/
    README.md
    todo/NNNN-<slug>.md
    done/<YYYY-MM-DD>-<slug>.md
  _agent/                # Der Agenten-Betriebsvertrag (siehe Q5) – optional
    ROLES.md             # Wer schreibt was (nur mehrere Autoren)
    LOCKS.md             # Der Dateisperr-Mutex (nur gemeinsamer Checkout)
    prompts/autonomous.md  # Wie ein unbeaufsichtigter Lauf sich verhält (nur mit einem
                         #   Verifikations-Gate – Q8 – UND einer Plan-Warteschlange – Q4a)
  federation.md          # Nur Multi-Repo (Q11): Rückverweis dieses Repos
  federation-index.md    # Nur Multi-Repo (Q11): Mitgliederverzeichnis – nur im Heim-Repo

Platzierung. Der Baum oben zeigt die Root-Option. AGENTS.md und CLAUDE.md liegen immer auf Repository-Root; adr/, plan/, _agent/, INDEX.md und CONVENTIONS.md gehen unter den Artefakt-Root, der in Q12 gewählt wurde (Standard .docflow/, z. B. .docflow/adr/, .docflow/plan/).

Erkennung. Werkzeuge lokalisieren den Artefakt-Root ohne zuerst CONVENTIONS.md zu lesen: Ein .docflow/ Verzeichnis auf Repository-Root ist der Root; für jeden anderen Root schreibt Bootstrap eine .docflow Datei auf Repository-Root – ein einzeiliger Zeiger, root: <Pfad> (z. B. root: docs/, root: .). Weder noch vorhanden bedeutet ein Vor-Vertrags-Repository (Werkzeuge durchsuchen docs/, dann den Repository-Root nach einer CONVENTIONS.md, die einen Artefakt-Root nennt) oder kein Docflow-Repository.

_agent/ ist der Agenten-Betriebsvertrag – wer was schreibt, der eine reale Mutex und wie ein unbeaufsichtigter Lauf sich verhält. Es enthält nichts, was Git bereits aufzeichnet: keine doppelte Versandaufzeichnung, kein Dashboard dessen, was in Arbeit ist, keine Momentaufnahme des aktuellen Zustands, keine Übergabe. Welche der drei Dateien oben existieren, folgt vollständig aus Q5, Q8 und Q4a, und ein Repository ohne _agent/-Verzeichnis ist ein gültiges Ergebnis.

Kern vs. optionale Ebenen. Nur der Kern wird immer geschrieben: AGENTS.md, CLAUDE.md, CONVENTIONS.md, adr/0000-template.md und INDEX.md. Ein Repository mit nur diesen ist ein gültiges, leichtgewichtiges Docflow-Repository – ein klassischer ADR-Katalog mit Konventionen. Alles andere ist eine Opt-in-Ebene: die plan/-Warteschlange (Q4a), der _agent/-Vertrag (Q5 + Q8 + Q4a – ein einzelner Autor ohne sowohl ein Verifikations-Gate als auch eine Plan-Warteschlange bekommt nichts davon), GLOSSARY.md und domains/ (Q7). Das Weglassen jeder optionalen Ebene ist ein gültiger Zustand, kein Fehler; ein Lifecycle-Skill, das eine fehlende Ebene benötigt, lehnt sauber ab und nennt, was fehlt.

Für ein Multi-Repo-Produkt (ein Produkt, das sich über mehrere Repositories erstreckt – siehe Q11), erscheinen zwei zusätzliche Dateien: federation.md, ein kleiner Rückverweis, den jedes Mitglieds-Repository trägt, und federation-index.md, die autoritative Mitgliederliste, die nur im Heim-/Gründungs-Repository lebt. Alle Föderations- Artefakte – federation.md, federation-index.md und das abgeleitete Roll-up ROLLUP.md – werden unter dem konfigurierten Artefakt-Root platziert. Ein Standalone-Repository hat keine davon.

Schritt 3 – Zu installierende Konventionen

1. ADRs sind die Quelle der Wahrheit. Eine Entscheidung pro ADR. Aufteilungen werden neue ADRs, die ersetzen; erweitern Sie niemals den Umfang innerhalb eines bestehenden.
2. Bis zu zwei ADR-Formen, durch Feld deklariert. Ein Repository, das die beiden unterscheidet, zeichnet die Unterscheidung im Metadatenfeld shape: jedes ADRs auf (capability oder technology; ein fehlendes Feld bedeutet capability) – niemals in einem Nummernbereich. Jeder ADR erhält die nächste fortlaufende Nummer unabhängig von seiner Form, und jede Form hat ihre eigene Vorlage, beide nummeriert 0000.
   • Capability-ADR (was das System tun muss). Abschnittsreihenfolge: Metadaten → Kontext → Capability-Statement → User Stories / Szenarien → Akzeptanzkriterien → Außerhalb des Rahmens → Offene Fragen → Referenzen → Revisionshistorie → Genehmigungen.
   • Technologie-ADR (wie es gebaut wird). Abschnittsreihenfolge: Metadaten → Kontext → Entscheidung → Begründung → Konsequenzen → Akzeptanzkriterien → Außerhalb des Rahmens → Offene Fragen → Referenzen → Revisionshistorie → Genehmigungen. Begründung muss Alternativen nennen, die in Betracht gezogen wurden, und spezifische Ablehnungsgründe angeben (nicht „einfacher“ / „idiomatischer“).
3. Status-Lebenszyklus: Proposed → Accepted → Implemented → (Superseded | Deprecated). Endzustände von jedem vorherigen Zustand erreichbar. Status steuert die Platzierung im Plan-Ordner: Accepted → plan/todo/, Implemented → plan/done/.
4. Dateinamen: adr/NNNN-kebab-slug.md, nullaufgefüllt 4 Ziffern, fortlaufend, keine reservierten Lücken. Querverweise verwenden relative Pfade.
5. Akzeptanzkriterien sind testbar und nummeriert. Tests bilden sie nach Möglichkeit ab.
6. Audit-Disziplin. Wesentliche ADR-Änderungen fügen eine Zeile in der Revisionshistorie hinzu. Redaktionelle Änderungen (Tippfehler, Formatierung, Link-Korrekturen) sind ausgeschlossen, werden aber im Commit-Kommentar als editorial gekennzeichnet. Die Genehmigungstabelle wird gefüllt, wenn ein ADR auf Accepted gesetzt wird, und aktualisiert bei jeder späteren wesentlichen Revision.
7. INDEX.md wird neu generiert aus ADR-Metadaten nach jeder ADR-Änderung. Als abgeleitet behandeln, nicht manuell bearbeitet.
8. plan/ ist die Arbeitswarteschlange. Wenn Arbeit ausgeliefert wird, werden git mv plan/todo/X plan/done/<datum>-X, alle Statusentfernungen von Plan-Elementen, der Statusfortschritt des zugehörigen ADR und die Neugenerierung von INDEX.md im Abschluss-Commit gruppiert. Bei Direct-to-Main-Integration wird dieser Commit auf den Integrationszweig gepusht und die Fußzeile der verschobenen Datei nennt den HEAD-SHA (und die Bereitstellungs-Artefakt-ID, falls zutreffend). Bei Pull-Request-Integration sind diese Änderungen der letzte Commit auf dem Pull-Request-Zweig, bevor er als bereit markiert wird, die Fußzeile nennt den Pull-Request, und der Merge ist das Abschlussereignis.
9. Koordination ist ein Vertrag, kein Protokoll. _agent/ enthält nur das, was Git Ihnen nicht sagen kann, und jeder Modus (Q5) schreibt genau seine eigenen Dateien vor – nichts anderes wird dort geschrieben. Bei einem gemeinsamen Checkout fügt ein Agent eine Zeile an _agent/LOCKS.md an (<agent-id> | <pfad> | <ISO-8601-Zeitstempel>) vor dem Bearbeiten und entfernt sie beim Commit; dieses Verzeichnis ist der eine echte Mutex, und ein Warteschlangenelement wird auf dem Element selbst beansprucht. Bei getrennten Arbeitsverzeichnissen wird ein Warteschlangenelement durch Pushen von claim/<item-key> – der Name der Warteschlangendatei ohne Erweiterung – plus einem Pull-Request-Entwurf davon beansprucht, wenn die Integration auf Pull-Requests basiert; der Push ist das, was den zweiten Autor ausschließt, und es wird kein Verzeichnis geführt. Bei einem einzelnen Autor gibt es nichts zu serialisieren und nichts zu beanspruchen. Kein Modus führt einen doppelten Versandstatus, ein Dashboard dessen, was in Arbeit ist, oder eine Momentaufnahme des aktuellen Zustands: Git-Historie und plan/done/ sind die Aufzeichnung, und die Live-Zweige und Pull-Requests sind das, was in Arbeit ist.
10. Git-Vertrag. Conventional Commits. Zwingender Rationale:- Fußzeile bei Commits, die einen ADR berühren. Signierte Commits, es sei denn, der Benutzer lehnt ab. Kein Co-Authored-By-Trailer für Agentenarbeit, es sei denn, der Benutzer bittet darum.
11. AGENTS.md ist der Einstiegspunkt für harte Regeln; CLAUDE.md ist der Einzeiler @AGENTS.md für kompatible Agenten, die es lesen.
12. ADRs sind interne Artefakte – niemals benutzersichtbar. ADR-Nummern, ADR-Titel und die Existenz des ADR-Katalogs dürfen NIEMALS in Produktcodepfaden erscheinen, die einen Benutzer erreichen: UI-Strings, API- Antwortkörper, Fehlermeldungen, Protokollzeilen, die an Kunden ausgegeben werden, öffentliche Dokumentation, Versionshinweise, Marketingtexte oder Support- Kommunikation. ADRs sind für Entwickler, nicht für Benutzer. Referenzen SIND erlaubt in: Codekommentaren (// siehe ADR-0012), internen Entwicklerdokumenten, internen Commit-Nachrichten, internem Projektmanagement-Tracking, Build- Skripten und anderen reinen Entwickler-Artefakten.
13. adr/-Verzeichnis mindestens lesbar, plan/todo/ schreibbar. Jeder Agent muss ADRs lesen können, um Kontext zu haben; Plan-Elemente schreiben zu können, um Arbeit aufzunehmen.

Schritt 4 – Ablauf

Schritt 4.1 – Grundlegende Bewertung Schritt 4.2 – Tiefen- und Verhaltensfragen Schritt 4.3 – Artefakt-Root Schritt 4.4 – Vorhandene ADR-Formen Schritt 4.5 – ADR-Form-Konsistenzprüfung Schritt 4.6 – Rollen und Koordination Schritt 4.7 – Zusätzliche optionale Ebenen Schritt 4.8 – Warteschlangen und Gates Schritt 4.9 – Git-Vertrag Schritt 4.10 – Zusätzliche Konfiguration Schritt 4.11 – Multi-Repo-Föderation Schritt 4.12 – Vorlagendateien schreiben Schritt 4.13 – Dateien generieren Schritt 4.14 – Ausgabe und nächste Schritte

Hinweis: Die folgenden Schritte enthalten Eingabeaufforderungen (z. B. [Zusammenfassungsblock], [Bestätigungsblock]), die in der Anwendung durch interaktive Aufforderungen ersetzt werden müssen. Zeigen Sie achtlos generierte Platzhalter nicht im Quellcode an.