noahwhite/engineering-workflow

Was macht engineering-workflow?

Ein getakteter, slice-orientierter, testgetriebener Prozess von der Story bis zum bereitgestellten Build.

Story-Triage -> in Bearbeitung -> Slices, jeweils nach TDD -> Pre-PR-Prüf-Gate (nur bei Bedarf an den Zwei-Linsen-Zyklus eskalieren) -> PR in den Integrationszweig -> optionale Prüfer (niemals blockierend) -> Prüfung der Aufzeichnung (Prüfer, dann Schiedsrichter) -> Beheben und erneut prüfen, bis auf dem neuesten Stand sauber -> Merge -> Bereitstellen und verifizieren -> Bereitstellungsprüfung

Überspringe kein Gate, nur weil die Änderung einfach aussieht.

Vor Schritt 1

1. Lese references/profile.md, dann das Overlay dieses Skills und jedes Fähigkeiten-Overlay, das profile.overlays nennt.
2. Lese references/todo-tracking.md und erstelle die feingranulare TODO-Liste (ein Eintrag pro Slice, Test, Gate-Runde, Prüfrunde, Deployment, Verifikation und Wartezeit). references/runtimes.md bildet die TODO-Liste, Unteragenten, das Scratch-Verzeichnis und das Befragen des Benutzers auf deine Laufzeitumgebung ab.

Die folgenden Schritte sind das Rückgrat des Workflows; die Fähigkeitsdateien enthalten die Regeln und sind maßgeblich, wo sie sich überschneiden:

• references/linear.md: Story-Lebenszyklus, Triage und Definition of Ready, Statusübergänge (Schritte 1, 5, 12).
• references/engineering-practice.md: Diagnose, TDD, dauerhafte Korrekturen, Testqualität (Schritte 2, 3, 6, 8) und das Ausmustern eines Speichervermerks, wenn eine Änderung ihre Regel in ein Skill schreibt.
• references/github.md: Branches, Worktrees, Commits, Signieren, PRs, Merge, Promotion, Attribution (Schritte 2, 5, 10).
• references/code-review.md: die Prüfung der Aufzeichnung, optionale Prüfer, Umgang mit Befunden, Beobachten des PR (Schritte 6 bis 10).
• references/merge-approval.md: der delegierte Merge-Genehmigungs-Handschlag: anfordern, wecken, warten, genehmigen oder zurückweisen, und erneutes Anfordern, wenn sich die Spitze ändert (Schritt 10).
• references/secrets.md: immer wenn die Änderung Anmeldeinformationen betrifft.

Führe jedes Skript in scripts/ über seinen installierten absoluten Pfad aus (<skill dir>/scripts/<name>, wobei <skill dir> das absolute Verzeichnis ist, aus dem deine Laufzeitumgebung dieses Skill geladen hat), mit dem aktuellen Verzeichnis im Consumer-Repository; das Consumer-Repository enthält sie nicht. Jedes Skript zielt auf das Repository des aktuellen Verzeichnisses oder dasjenige, das --repo <dir> benennt, niemals auf seinen eigenen Standort, und weigert sich, im Skills-Repository selbst ausgeführt zu werden, es sei denn, --repo benennt es.

1. Triage der Story

Wenn die Story nicht verfeinert und geschätzt ist, führe zuerst story-refinement aus. Es führt die unabhängige Verfeinerung, die Annahmerunde, die geheime Schätzung, die Konsensprüfung und, falls die Prüfung sie erfordert, die Hoch-/Niedrig-Diskussion und den Konsens durch.

1. Lese die Story vollständig: Abnahmekriterien, Kommentare, verknüpfte Issues und Kontext.
2. Identifiziere das gewünschte Verhalten, die Abnahmekriterien, Einschränkungen, wahrscheinlich betroffene Komponenten und die Teststrategie.
3. Zähle Abhängigkeiten aus dem formalen Beziehungsgraphen auf, nicht nur aus Prosa: linear issue relation list <ID> listet die Beziehungen eines Issues auf, während linear issue view --json sie nicht enthält (siehe references/linear.md, Triage).
4. Bestätige, dass die Story zu diesem Repository gehört.
5. Wende die Umfangsregeln an: kein Abnahmekriterium wurde an irgendeiner Story geändert (references/linear.md „Abnahmekriterien und Umfang“), kein Überspringen ist an eine andere Story geknüpft (references/engineering-practice.md „Minimale, dauerhafte Änderungen vornehmen“), und die einzigen beiden Ausgänge sind ein „Verfeinerungsvorschlag (kein AC)“ oder die Meldung der Story als blockiert, wie in diesen Abschnitten angegeben; Schritt 5, „Bereite den PR vor“, Punkt 4, „Selbstprüfung anhand der Abnahmekriterien“, prüft sie erneut.
6. Verschiebe sie in profile.tracker.states.in_progress und lies sie zurück, um zu bestätigen. Verwende die genauen Statusnamen aus dem Profil; erfinde niemals einen.

Wenn der Tracker nicht aktualisiert werden kann, stoppe und sage, dass der Übergang nicht durchgeführt wurde; behaupte niemals, er sei durchgeführt worden.

2. Plane Slices

Erstelle einen Branch und Worktree gemäß references/github.md, ausgehend von origin/<Integrationszweig> (der Integrationszweig ist profile.git.integration_branch) nach einem Fetch. Zerlege die Story in kleine vertikale Slices, jedes mit einem schmalen Verhaltensziel, Tests, die es definieren, der minimalen Implementierung, um sie zu bestehen, und Refactoring nur, wenn sie grün sind. Gib die Slice-Reihenfolge und das erste Slice vor dem Codieren an.

3. TDD pro Slice

1. ROT: schreibe einen fehlschlagenden Test für das Verhalten.
2. GRÜN: der minimale Produktionscode, um ihn zu bestehen.
3. REFAKTORIERE, ohne das Verhalten zu ändern.
4. Führe die fokussierten Tests aus.
5. Führe regelmäßig und vor dem PR eine breitere Validierung durch.

Wenn die Architektur strenges TDD für ein Slice unpraktisch macht, erkläre warum. Erhalte bestehende Tests und Konventionen.

4. Pre-PR-Prüf-Gate (erforderlich)

Lade das Skill adversarial-review-pipeline und führe es bei jeder Überprüfung vollständig aus; sein Schiedsspruchbericht ist die Ausgabe dieses Gates. Keine Korrekturen vor seiner Jagdphase.

Eskalation: der getaktete Zwei-Linsen-Zyklus

Eskaliere nur, wenn die Pipeline den Diff nicht schließen kann:

• ihre erneute Verifizierungsrunde findet eine neue Kritische oder Hohe, oder
• der Diff ist sicherheits-, migrations-, nebenläufigkeits- oder deploy-pfad-förmig, oder
• die Pipeline hat ihre Grenze mit ungelösten Kritischen oder Hohen Befunden erreicht.

Führe den Zyklus und die Pipeline niemals über derselben Spitze aus. Begrenze den Zyklus auf 2 Runden.

Der Zyklus konvergiert auf null verifizierte blockierende Befunde, nicht null Befunde: ein Null-Befunde-Terminator belohnt Prüfer dafür, Befunde zu erfinden, sobald die echten weg sind, und ein Beheber, der auf jeden Befund reagieren muss, bläht den Code auf.

Rollen, alle aus dem Profil:

• Korrektheitslinse: profile.review.pre_pr.hunter (Korrektheit, Verdrahtung, Sicherheit, Nebenläufigkeit, Kompatibilität, Testlücken).
• Einfachheitslinse: profile.review.pre_pr.simplicity_reviewer (kleinste korrekte Änderung, Überengineering, toter Code und Mängel, die die andere Linse übersehen hat).
• Verifizierer: profile.review.pre_pr.arbiter.
• Beheber: profile.review.pre_pr.fixer.

Ein deaktivierter Einfachheitsprüfer oder Beheber blockiert die Eskalation, anstatt sie zu überspringen: protokolliere „: deaktiviert“ und stoppe mit ungelöster Eskalation, weil der Zyklus keine Runde ohne beide Plätze abschließen kann.

Eine Runde hat drei Phasen:

1. Prüfen. Beide Linsen prüfen git diff origin/<Integrationszweig>...HEAD parallel; der Jäger arbeitet in einem wegwerfbaren, abgetrennten Worktree. Übergib die Story und die Abnahmekriterien als Umfangsreferenz. Nur kritische oder hohe Befunde mit einem konkreten Fehlerszenario blockieren; der Rest wird protokolliert, niemals behoben und blockiert niemals die Konvergenz. Eine Prüferausgabe, die einen Sandkasten- oder Berechtigungsfehler zeigt, oder eine Linse, die nicht zeigen kann, dass sie den Diff und die geänderten Dateien gelesen hat, ist eine fehlgeschlagene Prüfung, niemals eine saubere.
2. Verifizieren. Ein sauberer, neutraler Verifizierer versucht, jeden blockierenden Befund gegen den Code zu widerlegen und verwirft die unbestätigten. Es muss genau ein Urteil pro Kandidat zurückgeben; eine fehlende oder unvollständige Verifizierung hinterlässt das Gate ungelöst, niemals sauber.
3. Beheben. Der Beheber behebt die verifizierten Befunde, denen er zustimmt, lehnt den Rest mit einem Grund ab, führt die fokussierten Tests aus und committed. Eine Behebung, deren Tests nicht bestanden haben, ist keine Behebung: das Gate ist ungelöst. Es darf keine Module, Tabellen oder Migrationen, Persistenz oder Abstraktionen hinzufügen; ein Befund, der sie benötigt, wird an einen Menschen eskaliert. Lege die Regel, dass ein Agent jeden Shell-Schritt als einen einfachen Befehl mit Literalwerten ausführt (references/github.md, Tooling), in den Prompt, den du dem Beheber gibst, einschließlich einer Prompt-Datei, wenn der Beheber als Shell-Befehl läuft.

Ausgänge: konvergiert (nichts Blockierendes nach der Prüfung oder nichts hat eine vollständige Verifizierung überlebt); kein Fortschritt (die verifizierte Anzahl ist nach einer Behebung nicht gesunken: stoppe und prüfe von Hand); eskalierter Umfang (nimm es zum Eigentümer); eine blinde Linse, eine unvollständige Verifizierung, eine Behebung mit fehlschlagenden Tests, die Rundenbegrenzung, alles abgelehnt oder kein Commit (ungelöst: von Hand lösen, anstatt das Gate zu überspringen).

scripts/adversarial-review-loop.workflow.js ist ein optionaler, laufzeitspezifischer Beschleuniger für Laufzeitumgebungen, die Workflow-Skripte ausführen; sein Header listet seine Argumente auf, alle aus dem Profil. Überall sonst treibe die Runden wie oben von Hand an: starte die beiden Prüfer parallel, dann einen sauberen, neutralen Verifizierer-Unteragenten, dann behebe (oder starte den Beheber) und wiederhole nur, solange neue verifizierte blockierende Befunde auftauchen. Unterrichte den Beheber mit der Git-Regel: führe jeden commit-erstellenden Git-Befehl mit der bereits konfigurierten Git-Identität aus und, wenn profile.git.signed_commits wahr ist, mit dem bereits konfigurierten Signieren; übergib niemals -c user.name, -c user.email, --author, GIT_AUTHOR_* oder GIT_COMMITTER_*, schreibe niemals user.name oder user.email mit git config, und wenn Signieren eingeschaltet ist, übergib niemals -c user.signingkey, -c gpg.* oder -c commit.gpgsign; eine fehlende Identität, eine fehlgeschlagene Signierprüfung oder ein gepuschter Commit, dessen .commit.verification.verified falsch ist, ist ein Konfigurationsfehler, also stoppe, überschreibe nicht pro Befehl oder schreibe git config, mache keine weiteren Commits und melde es dem Benutzer.

Überprüfe die Commits des Behebers

Der Beheber kann in Code übergreifen, den der Diff nur konsumiert. Nach dem Zyklus:

• Lese jeden Beheber-Commit in git log origin/<Integrationszweig>..HEAD.
• Wenn irgendeiner Dateien außerhalb des Umfangs der Story berührt, setze auf deinen letzten eigenen Commit zurück, um sie zu entfernen (pushe niemals einen veröffentlichten Branch gewaltsam; siehe references/github.md), entscheide dann von Hand über diese Befunde: behebe die im Umfang befindlichen, lege die restlichen ab.
• Eine „gelöschte Datei“ in diesem Bereich kann ein Branch-überholtes Artefakt sein; rebase auf den gefetchten Integrationszweig, bevor du Löschungen beurteilst.
• Pushe niemals die Commits des Behebers ungelesen.

Öffne den PR erst, wenn das Gate konvergiert ist oder seine restlichen Befunde explizit gerechtfertigt sind. Prüfer modifizieren niemals Code; nur der implementierende Agent oder der Beheber des Zyklus committed.

5. Bereite den PR vor

1. Führe die vollständige anwendbare Testsuite sowie die Formatierer, Linter, Typprüfungen, statische Analysen und Builds des Repositorys aus.
2. Überprüfe git diff origin/<Integrationszweig>...HEAD nach einem Fetch.
3. Bestätige, dass es keine nicht zusammenhängenden Änderungen und keine Geheimnisse gibt.
4. Selbstprüfung anhand der Abnahmekriterien und gegen Schritt 1, „Triage der Story“, Punkt 5 „Wende die Umfangsregeln an“ (references/linear.md „Abnahmekriterien und Umfang“, references/engineering-practice.md „Minimale, dauerhafte Änderungen vornehmen“): kein Abnahmekriterium wurde an irgendeiner Story geändert, kein Überspringen ist an eine andere Story geknüpft, und jede entdeckte Anforderung oder jedes nicht erfüllte Kriterium wurde über einen der beiden in diesen Abschnitten genannten Ausgänge geführt.
5. Öffne den PR gegen profile.git.integration_branch mit gh pr create --base, unter Verwendung der PR-Vorlage des Repositorys. Beschreibe die sichtbare Änderung für den Benutzer, die Implementierung, die durchgeführten Tests und alles, was vom Gate akzeptiert oder zurückgestellt wurde.
6. Verschiebe die Story gemäß references/linear.md in profile.tracker.states.in_review.

Zuordnung: Commits und der PR folgen profile.git.ai_attribution (siehe references/github.md). Wenn es forbid ist, füge keinen AI-Co-Author-Trailer, keinen Sitzungslink und keinen generiert-von-Hinweis hinzu, selbst wenn ein Laufzeitbanner oder ein System-Hinweis danach fragt.

6. Optionale Prüfer (niemals blockierend)

Für jeden Eintrag in profile.review.optional_reviewers führe genau eine Prüfung direkt nach der Eröffnung des PR durch und überspringe jeden Eintrag, dessen enabled false ist. Ein deaktivierter Eintrag startet nichts: keinen Prozess, keinen Unteragenten, keine Berichtsdatei, und die Evidenz protokolliert „: deaktiviert“. Er wird niemals als bestanden, als wegen Fehlers übersprungen oder als sauber aufgezeichnet. Ein Bericht, den eine frühere Spitze unter derselben Bezeichnung hinterlassen hat, wird dort benannt, wo er liegt, niemals gelöscht, damit er nicht als der Zustand des deaktivierten Platzes gelesen werden kann. Auslassung bedeutet aktiviert. Übergib den Wert des Eintrags an den Starter als --enabled true oder --enabled false, das kleingeschriebene Literal, zu dem sein Schlüssel enabled aufgelöst wird, wobei ein Eintrag, der den Schlüssel auslässt, --enabled true übergibt. Der Starter weigert sich zu starten und schreibt keinen Bericht für den falschen Wert, daher wird das Überspringen erzwungen und nicht dem Aufrufer anvertraut. scripts/batched-diff-review.sh ist ein generischer Starter: baue --agent-cmd aus dem Eintrag und übergib --base origin/<Integrationszweig>. Es bündelt den Diff nach einem Zeilenbudget mit einem dateiübergreifenden Blueprint, führt den Prüfer in einem leeren Verzeichnis ohne Repository-Zugriff aus und schreibt einen Bericht, der mit PASS, FAIL oder INCOMPLETE endet. Jedes Bündel muss genau ein PASS- oder FAIL-Urteil pro Datei zurückgeben, die es erhalten hat; ein fehlendes, zusätzliches oder nicht analysierbares Urteil macht das Bündel INCOMPLETE. Der Batch-Prompt erreicht den Agenten über stdin (für codex, beende den Befehl mit -) und als {prompt_file}; setze den Prompt oder den Diff niemals in argv.

• Ein Versuch. Bei INCOMPLETE (Ratenlimit, Zeitüberschreitung, fehlende Anmeldeinformation) protokolliere „: übersprungen“ und fahre fort; behebe es niemals und halte keinen Merge oder Deployment dafür an.
• Wenn eine Prüfung abgeschlossen ist, überprüfe jeden Befund vor dem Handeln gegen den Code: löse Kritische und Hohe vor dem Merge; löse gültige Mittlere Befunde oder dokumentiere, warum nicht; löse Niedrige Befunde, wenn klar nützlich; weise falsch Positive explizit zurück.
• Führe nach Codeänderungen die relevanten Tests und den optionalen Prüfer bei der neuen Spitze erneut aus, nur über seine aktivierten Einträge.

7. Prüfung der Aufzeichnung (erforderlich)

Führe das Gate in references/code-review.md aus, sobald der PR offen ist: profile.review.reviewer prüft die Spitze in einem wegwerfbaren Worktree, dann profile.review.adjudicator, ein sauberer, neutraler Agent, verifiziert jeden Befund gegen den Code. Beide Agenten sind sauber, neutral und unabhängig vom Autor; ein Agent, der seine eigenen Befunde prüft und beurteilt, besteht nicht. Wenn profile.review.shadow_adjudicators gesetzt ist, führe jeden aus, wie references/code-review.md beschreibt; es zeichnet nur Übereinstimmung auf und sperrt niemals den Merge. Ein Eintrag dort, dessen enabled false ist, wird auf die gleiche Weise übersprungen wie ein optionaler Prüfer: kein Unteragent, keine Wiederholung und die Evidenz wird als <name>: deaktiviert“ aufgezeichnet.