Was macht Parallel Issue Resolver?
Bearbeite einen Stapel von GitHub-Issues gleichzeitig, jedes isoliert in einem eigenen Git-Worktree, und führe dann jedes über einen eigenen Pull Request zusammen. Fünf Phasen – Planen → Implementieren → Reviewen → Beheben → Zusammenführen.
Die grundlegende Regel: Ein Issue ist genau dann geschlossen, wenn GitHub seinen PR als MERGED meldet. Nicht bei einem lokalen Merge, nicht bei einem grünen Testlauf in einem Worktree, nicht auf die Aussage eines Sub-Agenten hin. Jedes Schließen enthält einen Kommentar, der beschreibt, was tatsächlich implementiert wurde.
Die Arbeit gelangt auf dieselbe Weise zu main wie bei einem Menschen: Branch → PR → CI → Squash-Merge. Nichts wird zusammengeführt, was CI nicht gesehen hat.
Schnellstart
Der Benutzer sagt: "Löse #12 #15 #18 parallel."
- Preflight:
bash <skill-verzeichnis>/scripts/preflight.sh– muss mit Exit-Code 0 beendet werden, bevor du etwas startest. Es gibt keinen separaten Einrichtungsschritt; es konfiguriert das Repository selbst beim ersten Durchlauf. - Planen: Lese jedes Issue, erstelle einen Abhängigkeitsgraphen, wähle die Issues aus, die jetzt ausgeführt werden können, ohne zu kollidieren.
- Implementieren: Ein Sub-Agent pro blockierungsfreiem Issue mit
isolation: "worktree", alle in einer einzigen Nachricht gestartet, damit sie parallel laufen. Jeder implementiert, committet, pusht, eröffnet einen PR und schreibt eine Übergabe. - Reviewen: Ein separater Reviewer-Sub-Agent pro Issue – niemals der Autor – liest den Diff gegen das Issue und gibt
approveoderchanges-requestedzurück. - Beheben: Sende blockierende Ergebnisse an den ursprünglichen Implementierer zurück, dann erneutes Review. Maximal zwei Runden.
- Zusammenführen: Für jedes genehmigte Issue
bash <skill-verzeichnis>/scripts/land.sh <issue> <branch> <kommentar-datei>– eines nach dem anderen. - Wiederholen, wenn noch neu freigegebene Issues vorhanden sind.
Lies REFERENCE.md für die Mechanik, Befehlserkennung und Stolperfallen vor dem ersten Durchlauf.
Phase 0 – Preflight
Führe dies vor jedem Stapel aus. Es ist der einzige Einrichtungsbefehl im Skill:
bash <skill-verzeichnis>/scripts/preflight.sh # --fix hinzufügen, um sichere Überreste zu entfernen
Es richtet alles ein, was noch nicht konfiguriert ist – .worktreeinclude, damit git-ignorierte .env-/Secret-Dateien in jeden Worktree kopiert werden, Ignorierregeln, worktree.baseRef: "head" – und überprüft dann, ob die Ausführung tatsächlich erfolgreich sein wird: erforderliche Tools vorhanden, Baum sauber, gh authentifiziert, Basis mit dem Origin synchron, CI löst bei pull_request aus, und keine übriggebliebenen agent/issue-*-Branches oder verwaisten Worktrees, die kollidieren würden.
Die Einrichtung ist idempotent und gibt nur dann eine Ausgabe, wenn sie etwas ändert, sodass es ab dem zweiten Durchlauf rein eine Überprüfung ist. Es schreibt keine getrackte Datei – Ignorierregeln gehen in .git/info/exclude, sodass der Skill niemals einen Diff im Repository hinterlässt.
Wenn es mit einem Fehler beendet wird, stoppe und behebe – starte keine Agenten. Melde dem Benutzer, was gefunden wurde.
Erfasse den Basis-Branch: git branch --show-current → BASE. Alle PRs zielen auf BASE.
Phase 1 – Planen (Orchestrator, inline)
Für jedes Issue: gh issue view <id> --json number,title,body,labels,state,comments. Wenn ein Issue auf ein übergeordnetes PRD/Epic verweist, lies auch das.
Überspringe jedes Issue, das bereits CLOSED ist oder das bereits einen offenen PR hat (gh pr list --search "<id> in:body") – sage dies, anstatt Arbeit zu duplizieren.
Erstelle einen Abhängigkeitsgraphen. Issue B wird von A blockiert, wenn eines gilt:
- B benötigt Code/Infrastruktur, die A einführt.
- B und A ändern sich überschneidende Dateien/Module → gleichzeitige Änderungen würden kollidieren.
- B hängt von einer API-Form oder Entscheidung ab, die A festlegt.
Ein Issue ist blockierungsfrei, wenn es keine blockierenden Abhängigkeiten von den anderen Issues in diesem Stapel hat. Nur blockierungsfreie Issues laufen in dieser Runde. Wenn jedes Issue blockiert ist, führe nur das mit den schwächsten Abhängigkeiten aus, um den Zyklus zu durchbrechen.
Weise jedem einen deterministischen Branch zu: agent/issue-<id>. Teile dem Benutzer den Stapelplan vor dem Starten mit – welche Issues jetzt laufen, welche warten und warum.
Phase 2 – Implementieren (parallele Sub-Agenten)
Für jedes blockierungsfreie Issue starte einen Sub-Agenten über das Agent-Tool mit isolation: "worktree". Setze alle Starts in eine Nachricht, damit sie parallel laufen.
- Sub-Agent-Typ:
general-purpose(benötigt Bearbeitung + Bash). - Benenne ihn
impl-<id>– du benötigst den Namen, um Review-Ergebnisse in Phase 4 an ihn zurückzusenden, wobei sein Kontext erhalten bleibt. - Prompt: der Inhalt von prompts/implement.md mit
{{ISSUE_ID}},{{BRANCH}}(=agent/issue-<id>),{{BASE}}und{{STATE_DIR}}(absoluter Pfad zu<repo>/.claude/pir) ausgefüllt.
Jeder Sub-Agent implementiert, bereinigt seinen eigenen Diff, pusht, eröffnet einen PR und schreibt zwei Übergabedateien in {{STATE_DIR}}. Die Dateien sind der dauerhafte Datensatz – sie überstehen Kontextverdichtung, die RESULT-Zeile nicht. Siehe REFERENCE.md.
Phase 3 – Unabhängiges Review (parallele Sub-Agenten)
Der implementierende Agent überprüft seine eigene Arbeit nicht. Für jedes Issue, das als complete mit einem offenen PR zurückkam, starte einen separaten Reviewer – wieder alle in einer Nachricht.
- Sub-Agent-Typ:
general-purpose. Benenne ihnreview-<id>. - Kein
isolation: "worktree"– das Review ist schreibgeschützt und arbeitet mitgit diff {{BASE}}...{{BRANCH}}aus dem Basis-Checkout. Kein Worktree zum Erstellen oder Bereinigen. - Prompt: prompts/review.md mit
{{ISSUE_ID}},{{BRANCH}},{{BASE}},{{PR}},{{STATE_DIR}}ausgefüllt.
Der Reviewer schreibt {{STATE_DIR}}/issue-<id>.review.json mit einem Urteil von approve oder changes-requested sowie Ergebnissen. Er bearbeitet, pusht, merged oder kommentiert niemals – er berichtet, du entscheidest.
Veröffentliche das Urteil im PR, damit die Begründung dort festgehalten ist, wo ein Mensch sie suchen würde:
github pr comment <PR> --body "$(jq -r '**Automatisiertes Review: .verdict**\n\n.summary' .claude/pir/issue-<id>.review.json)"
Phase 4 – Behebungsrunde (nur für changes-requested)
Sende die blockierenden Ergebnisse an den ursprünglichen Implementierer zurück, der den Code noch im Kontext hat:
NachrichtSenden → an: "impl-<id>"
Unabhängiges Review von PR # hat blockierende(s) Problem(e) gefunden. Behebe nur diese, führe die Überprüfungen erneut aus, pushe in denselben Branch und aktualisiere deine Übergabe-
.md, damit sie dem endgültigen Zustand entspricht.<das
blocking-Array, wörtlich>Wenn du glaubst, dass ein Ergebnis falsch ist, erkläre warum, anstatt Code zu ändern, den du für korrekt hältst.
Führe dann Phase 3 für dieses Issue erneut aus (ein neuer review-<id>-Agent – Runde 2).
Begrenze auf zwei Review-Runden. Wenn ein Issue nach Runde 2 immer noch changes-requested ist, stoppe: lasse den PR und das Issue offen und teile dem Benutzer mit, was ungelöst ist, zusammen mit den Ergebnissen des Reviewers. Drei Runden bedeuten, dass das Issue zu vage spezifiziert ist oder die Meinungsverschiedenheit einen Menschen erfordert, und weitere Runden verbrennen Tokens, ohne zu einer Einigung zu führen.
Wenn der Implementierer ein Ergebnis zurückweist, anstatt es zu beheben, lies beide Argumente und entscheide selbst. Gib es nicht einfach zurück – so entstehen Schleifen.
Phase 5 – Zusammenführen (Orchestrator, vom BASE-Checkout)
Führe Issues eines nach dem anderen, seriell zusammen – niemals parallel. Jeder Merge ändert BASE, was den nächsten PR veralten lassen kann; land.sh rebased, wenn GitHub einen Konflikt meldet, und das funktioniert nur gegen eine bereits aktualisierte Basis.
Für jedes Issue, dessen Übergabe status: "complete" und dessen Review-Urteil approve ist:
bash <skill-verzeichnis>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md
Das Skript erledigt den gesamten Rest in der einzig korrekten Reihenfolge: Überprüfung des Review-Urteils → Freigabe des Worktrees → Rebase bei Konflikten → Warten auf grünes CI → Squash-Merge → Überprüfen, ob GitHub MERGED meldet → Schließen des Issues mit dem Übergabekommentar → Fast-Forward von BASE → Löschen des Branches → Bereinigen der Worktrees.
Es weigert sich, etwas ohne ein approve-Urteil auf der Festplatte zusammenzuführen, sodass das Review ein Gate ist, nicht eine Gewohnheit. PIR_SKIP_REVIEW=1 überschreibt dies – wenn du das verwendest, sage es laut, denn es entfernt die einzige Prüfung, die CI nicht durchführen kann.
Verzweige anhand des Exit-Codes:
| Code | Bedeutung | Was du tust |
|---|---|---|
0 | Zusammengeführt, geschlossen, bereinigt | Fahre mit dem nächsten Issue fort |
2 | Vorbedingung fehlgeschlagen | Behebe und führe erneut aus; erzwinge nichts |
3 | Rebase-Konflikt, den ein Skript nicht lösen kann | Löse manuell in diesem Branch, pushe, führe land.sh erneut aus |
4 | CI fehlgeschlagen oder Zeitüberschreitung | Lies den fehlgeschlagenen Check, behebe im Branch, pushe, führe land.sh erneut aus |
5 | Merge/Schließen-Problem | Überprüfe den PR – er könnte gemerged sein, während das Issue noch offen ist |
Alles außer 0 lässt den PR und das Issue absichtlich offen. Melde diese dem Benutzer mit dem PR-Link; wiederhole nicht blind.
Dann zurück zu Phase 1, wenn noch blockierte Issues vorhanden sind.
Phase 6 – Bericht
Teile dem Benutzer pro Issue mit: zusammengeführt (PR # + Link), warum offen gelassen oder warum übersprungen. Füge bei allem, was nach zwei Review-Runden offen bleibt, die ungelösten blockierenden Ergebnisse des Reviewers bei. Beharre nicht darauf, dass ein Issue erledigt ist, ohne die gemergte PR-Nummer.
Anforderungen
Läuft in Claude Code: es nutzt Sub-Agenten mit isolation: "worktree", NachrichtSenden und .worktreeinclude. Installiere mit npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver oder kopiere dieses Verzeichnis nach ~/.claude/skills/ oder in ein .claude/skills/ eines Repositories. Es gibt keine pro-Repository-Einrichtung, keine zu bearbeitende Konfiguration und keine zu korrigierenden Pfade.
Was es auf dem Rechner benötigt: git, gh (authentifiziert) und jq. Der Preflight überprüft alle drei und nennt alle, die fehlen.
Was es vom Repository benötigt: einen GitHub-Remote und CI, das Checks bei Pull Requests meldet. Der Preflight warnt, wenn kein solches CI gefunden wird. Du kannst trotzdem mit PIR_REQUIRE_CI=0 ausführen, was PRs ohne CI-Gate zusammenführt. Sage es laut, wenn du das tust, denn es entfernt die wichtigste Sicherheitseigenschaft des Skills.
Was es nicht mit dem Repository tun wird: keine getrackte Datei ändern. Ignorierregeln werden in .git/info/exclude geschrieben, sodass die Einrichtung keinen Diff hinterlässt und nichts in einen Commit gelangen kann.
Skripte werden als bash <pfad> aufgerufen, sodass ein verlorenes Ausführungsbit während des Kopierens nichts kaputtmacht.
Sicherheit & Schutzmechanismen
- Niemals
git pushzu BASE, und niemals--forceauf etwas außer dem eigenen Branch des Agenten (--force-with-lease, nur innerhalb desland.sh-Rebases). - Niemals
git add -A/git add .– stelle nur explizite Pfade bereit. - Niemals
Closes #N/Fixes #Nin einen PR-Text setzen. Das würde GitHub veranlassen, das Issue beim Merge stillschweigend zu schließen, ohne Kommentar darüber, was getan wurde. VerwendeRefs #N; das Schließen ist explizit, durch einen verifizierten Merge abgesichert und enthält immer die Zusammenfassung. - Niemals mit
--adminmergen und niemals einen roten Check überspringen. - Ein Sub-Agent pro Issue, der nur an seinem Issue arbeitet.
- Wenn der Preflight fehlschlägt, stoppe und informiere den Benutzer. Wenn der Baum schmutzig ist, stoppe – Worktrees verzweigen von HEAD.