amElnagdy/delegate-skills

Pi Delegate

Du bist der Orchestrator. Delegiere eine klar abgegrenzte Programmieraufgabe an einen separaten Implementierer – das Pi-Coding-Agent-CLI – überprüfe dann, was es produziert hat, und merge selbst. Du schreibst die Aufgabenbeschreibung und trägst die Verantwortung für die Beurteilung; der Implementierer nimmt Änderungen in seiner eigenen Sitzung vor; du überprüfst und comittest.

Der Ablauf benötigt nur einen Shell-Befehl und Dateizugriff, sodass jeder vergleichbare Orchestrator ihn ausführen kann.

Wann NICHT zu verwenden

• Die Aufgabe ist klein genug, um inline erledigt zu werden; der Delegationsaufwand lohnt sich nicht.
• Das pi CLI ist nicht installiert oder authentifiziert.
• Du benötigst einen sandboxed Implementierer. Pi hat keine Sandbox und keine Berechtigungsmodi; --read-only schränkt die Werkzeugoberfläche ein, aber ein schreibfähiger Lauf führt ohne Rückfragen aus.

Voraussetzungen (einmal prüfen)

1. Installiere pi mit npm install -g @earendil-works/pi-coding-agent.
2. Authentifiziere: /login innerhalb von pi für einen Abo-Anbieter oder eine API-Key-Umgebungsvariable / die pi-Auth-Datei für einen API-Key-Anbieter.
3. Bestätige, dass pi --version erfolgreich ist.
4. Arbeite im Ziel-Git-Repository oder verwende --cd, um darauf zu verweisen.

Modell auswählen (optional)

Lasse --model weg, um die konfigurierte Standardeinstellung von pi zu verwenden. Um ein anderes Modell auszuwählen, wähle aus pi --list-models und übergib eine explizite ID oder ein Muster wie <provider>/<model-id> oder sonnet:high. Das Relay akzeptiert nur Buchstaben, Ziffern und . _ : / - (der Wert erreicht eine Shell unter Windows), daher werden Glob-Muster mit * nicht weitergeleitet.

Der Ablauf

Führe diese fünf Schritte pro Aufgabe aus. Die Schritte 1, 4 und 5 erfordern Urteilsvermögen; 2 und 3 sind mechanisch.

1. Die Aufgabenbeschreibung schreiben

Pi sieht nur den von dir gesendeten Text plus das, was es im Arbeitsbereich inspizieren kann – kein Chatverlauf oder gemeinsamer Kontext. Füge das Ziel, den aktuellen Zustand, was geändert werden soll, was unberührt bleiben soll, die tatsächlichen Gates des Projekts und einen Berichtsvertrag hinzu. Sage pi, dass es nicht committen soll. Behalte eine Aufgabe pro Beschreibung bei. Pi lädt automatisch die Kontextdateien AGENTS.md/CLAUDE.md aus dem Arbeitsbereich und dessen übergeordneten Verzeichnissen, sodass Repo-Anweisungen ohne Einbettung ankommen. Siehe references/writing-the-brief.md.

2. Absenden

Verwende das mitgelieferte Relay. Es leitet die Aufgabenbeschreibung an pi --mode json auf stdin weiter, erfasst den JSON-Ereignisstrom und schreibt result.json. (<skill-dir> ist das installierte Verzeichnis, das diese SKILL.md enthält.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# Modell auswählen:                          add --model <id from pi --list-models>
# Anbieter auswählen:                        add --provider <name>
# Read-only-Lauf (Überprüfung/Diagnose):     add --read-only
# Projekt-.pi-Ressourcen vertrauen:          add --approve
# Letzte Sitzung fortsetzen:                 add --resume-last  (nur Delta-Beschreibung)
# Bestimmte Sitzung fortsetzen:              add --session <id> (nur Delta-Beschreibung)
# Harte Zeitbegrenzung (Watchdog):           add --timeout 2h  (die 30min Standard eignet sich für kurze Läufe; Implementierungsbeschreibungen benötigen routinemäßig 1-2h)
# Alle Optionen anzeigen:                    node .../relay.mjs --help

Das Arbeitsverzeichnis des Kindprozesses fixiert den Workspace. Das Relay schreibt Artefakte standardmäßig unter das temporäre Systemverzeichnis und comittet nie. Siehe references/dispatch-and-poll.md.

3. Auf Fertigstellung warten

Das Relay blockiert, bis pi fertig ist. Führe es mit der Hintergrundbefehl-Funktion des Orchestrators aus oder lasse es im Hintergrund der Shell laufen und warte auf result.json. Ein vor dem Lauf auftretender Nutzungsfehler beendet sich mit Exit-Code 2 und schreibt kein Ergebnis; ein fehlendes pi beendet sich mit Exit-Code 127 und schreibt status: "pi_unavailable".

Vertraue dem Prozessstatus und dem Arbeitsbaum mehr als einer Fortschrittsanzeige. Fertigstellung bedeutet, dass der Prozess beendet wurde und result.json existiert. Der vollständige Bericht von pi ist das Feld finalMessage in result.json (wird auch im Volltext auf stdout zwischen den Berichtsmarkierungen ausgegeben).

4. Überprüfen – vertraue nicht dem Selbstbericht

Behandle die abschließende Nachricht von pi und die Gate-Behauptungen als Behauptungen:

• Führe die Gates des Projekts selbst aus.
• Lies den Diff gegen die Aufgabenbeschreibung, beginnend mit touchedFiles.
• Führe relevante Guard-Skills aus, falls installiert.
• Führe Round-Trip-Migrationen durch und suche nach hängenden Referenzen nach Entfernungen oder Umbenennungen.

Siehe references/review-and-land.md.

5. Commit

Der Implementierer bearbeitet den Arbeitsbaum; der Orchestrator comittet. Committe nur, nachdem die Gates bestanden wurden und der Diff stimmt. Wenn Nacharbeit erforderlich ist, sende eine Delta-Beschreibung mit --resume-last oder --session <id> und überprüfe erneut.

Autonomie und Berechtigungen

Pi hat keine Sandbox und keine Berechtigungsmodi. Ein standardmäßiger headless Lauf liest, schreibt, bearbeitet und führt Shell-Befehle ohne Rückfragen aus – die Kontrollen sind:

1. --read-only schränkt die aufrufbaren Werkzeuge von pi auf --tools read,grep,find,ls über integrierte, Erweiterungs- und benutzerdefinierte Werkzeuge ein. Installierter Erweiterungscode läuft weiterhin mit den Host-Berechtigungen des Benutzers.
2. Das Relay übergibt standardmäßig --no-approve, sodass Projekt-.pi-Einstellungen, Erweiterungen und Skills nicht vertrauenswürdig bleiben. --approve ist die explizite Opt-in für ein Repository, dem der Benutzer vertraut.
3. touchedFiles und der Diff sind die Aufzeichnung dessen, was geändert wurde. Überprüfe sie nach jedem Lauf.

Autorisierungsmodell

Delegation ist etwas, in das der Mensch explizit einwilligt. Sobald er dies getan hat („diese Warteschlange ausführen“, „fortfahren“), ist das Committen von verifizierten, gate-bestandenen Arbeiten der vereinbarte Vertrag. Zwei Grenzen bleiben bestehen: Oberfläche, nicht absorbieren (berichte über Designentscheidungen von pi, vertretbare, aber nicht angeforderte Abweichungen und nicht blockierende Kleinigkeiten) und bei Scope-Änderungen anhalten (wenn die korrekte Fertigstellung über die Aufgabenbeschreibung hinausgeht, frage nach, anstatt das Mandat zu erweitern). Siehe references/review-and-land.md.

Referenzen

• references/writing-the-brief.md – Struktur, Berichtsvertrag, echte Gates, stdin-Zustellung und Delta-Beschreibungen.
• references/dispatch-and-poll.md – Flags, Artefakte, result.json, Polling und Fehlerbehebung.
• references/review-and-land.md – Überprüfungsliste, Commit-Grenze und Nacharbeit durch pi-Sitzungen.
• references/multi-task-queues.md – Sequenzielle Warteschlangen, Constraint-Übertragung, Fortschrittsverfolgung und der finale Kohärenzdurchlauf.