pi_coder_2/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung: pi_coder

pi_coder ist ein Werkzeug, das ein lokales KI-Modell abwechselnd als Coder und Judge einsetzt, um Software automatisch zu schreiben, zu prüfen und zu verbessern — alles gesteuert über einfache Slash-Kommandos in der pi-Agent-Oberfläche.

---

Inhaltsverzeichnis

1. Konzept: Coder und Judge
2. Vorbereitung
3. Server starten und stoppen
4. Neues Projekt anlegen
5. Manueller Workflow: /coder → /judge → /fix → /shipit
6. Automatischer Workflow: /optimize (inkl. Interactive-Modus)
7. Kleine Änderungen: /patch und /quick_check
8. Dokumentation generieren: /update_doku
9. Versionsverwaltung: /version
10. TASK.md verstehen und nutzen
11. Typische Anwendungsfälle
12. Fehlermeldungen und Lösungen

---

1. Konzept: Coder und Judge

pi_coder verwendet zwei Rollen — bedient von einem einzigen Modell, das je nach Aufgabe eine andere Persona annimmt:

Coder-Persona: Schreibt und repariert Code. Liest die Aufgabe aus TASK.md, implementiert sie, führt Tests aus und erstellt Git-Commits.

Judge-Persona: Überprüft den Code mit dem Blick eines skeptischen Senior-Entwicklers. Prüft Korrektheit, Robustheit, Randfälle, Sicherheit und Produktionsreife. Maßstab für das Urteil sind TASK.md und, falls vorhanden, SPEC.md:

• PASS — alle Anforderungen erfüllt, Tests grün, kein Blocker und kein Major
• PASS WITH CONCERNS — alle Anforderungen erfüllt, aber mindestens ein Major: ein konkretes Risiko im geforderten Einsatz, mit Reproduktion (wird wie FAIL behandelt, außer du verwendest --approve-concerns)
• FAIL — eine Anforderung fehlt, Tests schlagen fehl oder ein reproduzierbarer Fehler im geforderten Verhalten

Härtung über die Anforderungen hinaus, Skalierung, Stil und Wünsche schreibt der Judge unter „Hinweise“. Sie ändern das Urteil nicht, und der Coder bearbeitet sie bei /fix nicht. Ein Major ohne Reproduktion gilt als Hinweis. Ohne diese Regeln urteilte der Judge mit Strata am 15.10.2026 in keiner Aufgabe PASS.

Die Umschaltung zwischen den Rollen erfolgt über unterschiedliche System-Prompts, die die Extension automatisch vor jeder Inference einsetzt. Es läuft kein zweiter Server.

Der Grundgedanke: Coder und Judge haben keine „Höflichkeitsschranke" zueinander — der Judge kritisiert direkt und konkret, der Coder repariert ohne Widerspruch.

---

2. Vorbereitung

Server starten

cd ~/pi_coder
./start-coding-server.sh

Ausgabe bei Erfolg:

[*] Verwende HF_HOME = /home/.../huggingface
[*] GPU device = 1
[✓] Single-Server (:8001) bereit

Dauer: bis zu 5 Minuten (Modell wird in GPU-VRAM geladen; neuere llama.cpp-Versionen prüfen beim Start die VRAM-Verfügbarkeit, was zusätzliche Zeit kostet).

Status prüfen

./status-coding-server.sh

=== LLaMA-Server Status ===
coding_model (Port 8001): Container=RUNNING  HTTP=OK

pi agent öffnen

pi agent im Projektverzeichnis starten — das ist das Verzeichnis, in dem dein Code liegt, nicht ~/pi_coder:

cd ~/MeinProjekt
pi

---

3. Server starten und stoppen

GPU-Zuordnung

Der Server läuft standardmäßig auf GPU 1 (überschreibbar):

./start-coding-server.sh           # GPU 1 (Standard)
GPU_DEVICE=0 ./start-coding-server.sh   # GPU 0

Auf einem System mit mehreren GPUs empfiehlt es sich, GPU 0 (Display) freizuhalten und GPU 1 für den KI-Server zu verwenden.

Wichtig: Andere GPU-Prozesse (z. B. TTS-Dienste, Ollama) auf der verwendeten GPU können VRAM belegen und dazu führen, dass der Server nicht startet. Im Zweifel prüfen:

nvidia-smi --query-gpu=index,name,memory.used,memory.free --format=csv

Server starten

cd ~/pi_coder
./start-coding-server.sh

Erwartete Ausgabe:

[*] Verwende HF_HOME = /home/.../huggingface
[*] GPU device = 1
[✓] Single-Server (:8001) bereit

Dauer: bis zu 5 Minuten. Danach ist das Modell im VRAM und sofort antwortbereit.

Server stoppen

./stop-coding-server.sh

Status prüfen

./status-coding-server.sh

Alternativer Modellpfad

Falls die GGUF-Datei an einem anderen Ort liegt:

HF_HOME=/mnt/daten/huggingface ./start-coding-server.sh

Anderes Modell für die Schleife

Ohne weitere Angabe arbeiten Coder und Judge mit llama-cpp-single/coding_model (Port 8001). Ein anderes Modell aus models.json setzt die Umgebungsvariable PI_CODER_MODEL beim Start von pi, als <provider>/<id>:

PI_CODER_MODEL=strata/qwen3.8-flash-next-iq3_s \
  pi --provider strata --model qwen3.8-flash-next-iq3_s

--provider/--model machen das Modell auch für freie Eingaben zum Standard dieses Laufs; die globalen Einstellungen bleiben unverändert. Die Bereitschaftsprüfung fragt den Endpunkt aus baseUrl des Modells ab. Der Provider strata (lokaler Strata-Server auf 127.0.0.1:9090) steht in models.json; den Server startet man außerhalb dieses Repos.

---

4. Neues Projekt anlegen

Kommando

/new_project <pfad>

Beispiel

/new_project ~/Python_Programs/mein_tool

Was passiert:

• Verzeichnis ~/Python_Programs/mein_tool wird angelegt
• git init wird ausgeführt
• .gitignore wird mit Standardeinträgen angelegt und committed

Wichtig: pi agent wechselt nicht automatisch in das neue Verzeichnis — die Session bleibt im aktuellen Verzeichnis. Nach dem Anlegen:

cd ~/Python_Programs/mein_tool
pi

Dann kannst du /coder oder /optimize mit dem neuen Projekt verwenden.

---

5. Manueller Workflow

Der manuelle Workflow gibt dir volle Kontrolle über jeden Schritt.

Schritt 1: /coder — Aufgabe übergeben

/coder <auftrag>

Der Coder:

1. Legt TASK.md im aktuellen Verzeichnis an (oder hängt an bestehende an)
2. Liest TASK.md und implementiert den Auftrag
3. Führt Tests oder Build-Checks aus
4. Erstellt einen Git-Commit

Beispiel:

/coder Schreibe ein Python-Kommandozeilenprogramm 'textcount'. Es soll eine Textdatei als Argument nehmen und folgendes ausgeben: Anzahl Zeichen, Wörter, Zeilen und die 5 häufigsten Wörter (ohne Stoppwörter).

Typische Ausgabe des Coders:

Implementierung abgeschlossen.
- src/textcount.py erstellt (Hauptprogramm)
- tests/test_textcount.py erstellt (Unit-Tests)
- requirements.txt angelegt (keine externen Abhängigkeiten)
- Alle 8 Tests bestanden
- Commit: feat: implement textcount CLI tool
Risiken: Stoppwortliste nur Deutsch/Englisch, keine Konfigurations-Option.

Schritt 2: /judge — Code überprüfen lassen

/judge

Optionaler Fokus:

/judge Besonderes Augenmerk auf Fehlerbehandlung und Edge Cases

Der Judge:

1. Liest TASK.md und prüft ob alle Anforderungen umgesetzt sind
2. Analysiert git show HEAD
3. Führt Tests aus
4. Gibt ein strukturiertes Urteil aus

Beispiel-Ausgabe PASS WITH CONCERNS:

Urteil: PASS WITH CONCERNS

Blocker: keine

Major:
- Nicht-existente Datei: Traceback statt Meldung und Exit-Code 2 (TASK.md verlangt Exit 2).
  Reproduktion: python3 textcount.py fehlt.txt; echo $?  → Traceback, Exit 1

Minor:
- Fehlermeldung nennt den Dateinamen nicht

Fehlende Tests:
- Test für leere Datei fehlt
- Test für Datei mit nur Leerzeichen fehlt

Hinweise (ändern das Urteil nicht):
- Bei sehr großen Dateien (>1 GB) wird alles in den RAM geladen
- Keine --version Flag

Konkrete Fix-Aufträge:
1. FileNotFoundError abfangen, Meldung mit Dateiname, exit(2)
2. Test für leere Eingabedatei

Beispiel-Ausgabe FAIL:

Urteil: FAIL

Blocker:
- textcount.py importiert 'collections.Counter' aber das ist nicht installiert
  (Counter ist stdlib, aber der Import-Fehler tritt bei Python < 3.9 auf)
- ./textcount.py existiert nicht — tests/test_textcount.py schlägt komplett fehl

Major: ...

Schritt 3: /fix — Kritik beheben

/fix

Optionaler Hinweis:

/fix Den Major-Punkt mit der Stoppwortliste kannst du weglassen, das ist kein Produktionsprojekt

Der Coder arbeitet die Judge-Kritik ab (Blocker zuerst, dann Major, dann Minor) und erstellt einen neuen Commit.

Schritt 4: /shipit — Finale Freigabe

/shipit

Der Judge gibt ein finales Urteil:

• SHIP — bereit für Produktion
• NO-SHIP — noch Probleme offen

Beispiel:

Urteil: SHIP

Letzte Blocker: keine

Restrisiken:
- Kein Streaming für sehr große Dateien (dokumentiert in README)

Empfohlene Sofortmaßnahmen: keine

---

6. Automatischer Workflow: /optimize

/optimize führt den gesamten Coder→Judge→Fix-Zyklus automatisch durch.

Syntax

/optimize <auftrag> [--rounds N] [--with-doku] [--continue] [--interactive]
          [--no-tests] [--approve-concerns] [--test-cmd "cmd"] [--test-timeout N]

• --rounds N — maximale Anzahl Runden (Standard: 2)
• --with-doku — nach SHIP automatisch /update_doku ausführen
• --continue — überspringt die Implementierungsphase und startet direkt mit dem Judge→Fix-Zyklus ab dem aktuellen Code-Stand. Nützlich wenn man bereits manuell /coder, /judge und /fix durchgeführt hat und den Rest automatisieren möchte.
• --interactive — pausiert nach erstem PASS für einen menschlichen Checkpoint. Details: siehe Interactive-Modus weiter unten.
• --no-tests — überspringt die automatische Test-Erkennung. Sinnvoll wenn keine Test-Suite vorhanden ist oder Tests über externe Infrastruktur laufen.
• --approve-concerns — behandelt „PASS WITH CONCERNS" wie „PASS": kein ShipIt-Call, direktes SHIP. Standardmäßig löst PASS WITH CONCERNS immer einen Coder-Fix aus.
• --test-cmd "befehl" — überschreibt die automatische Test-Erkennung mit einem eigenen Befehl (z.B. --test-cmd "pytest tests/ -x").
• --test-timeout N — maximale Laufzeit pro Test-Befehl in Sekunden (Standard: 120).

PASS WITH CONCERNS — wichtig

Ohne --approve-concerns gilt PASS WITH CONCERNS wie FAIL — der Coder bekommt einen Fix-Auftrag und der Loop geht weiter. Erst sauberes PASS beendet die Schleife. Mit --approve-concerns gilt PASS WITH CONCERNS als bestanden.

Beispiel: einfacher Auftrag

/optimize Schreibe ein Rust-Programm 'genpw' das sichere Passwörter generiert. Optionen: --length N (Standard 16), --count N (Standard 1), --no-symbols, --no-numbers.

Was im Hintergrund passiert:

Phase 1: Coder implementiert...
Phase 2: Runde 1/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: FAIL (2 Blocker)
Phase 3: Runde 1/2: Coder fixt...
Phase 4: Runde 2/2: Judge — TASK.md + letzter Commit + Tests...
  → Urteil: PASS
✓ PASS nach Runde 2 → SHIP
[Dialog: Version → v0.1.0 (empfohlen)]

Bei PASS WITH CONCERNS (ohne --approve-concerns):

  → Urteil: PASS WITH CONCERNS (Major: fehlendes --help)
Phase 3: Runde 2/2: Coder fixt Concerns...
Phase 4: Runde 3/3: Judge...
  → Urteil: PASS
✓ PASS → SHIP

Bei klarem PASS entfällt die ShipIt-Runde — es wird direkt SHIP ausgelöst.

Während des Ablaufs zeigt die Statuszeile die aktuelle Phase — mit laufendem Timer:

◉ Coder implementiert: Login-Flow mit JWT [01:23]
◉○ Runde 1/2: Judge — TASK.md + letzter Commit + Tests [00:47]
●◉ Runde 1/2: Coder fixt — fehlendes Null-Check [01:05]
●● ✓ PASS nach Runde 2/2 — SHIP
🚀 SHIP – produktionsreif

Steht der Timer still, hängt der Prozess — dann /cancel verwenden.

Beispiel: mehr Runden

/optimize Implementiere einen vollständigen REST-API-Client für die GitHub API in Python mit Rate-Limiting, Retry-Logic und Caching --rounds 5

Beispiel: mit automatischer Dokumentation

/optimize Schreibe ein Go-Tool 'logfilter' das Logdateien nach Regex-Muster filtert --with-doku

Nach SHIP werden automatisch ausgeführt:

1. Code-Kommentare einfügen
2. README.md schreiben
3. BEDIENUNGSANLEITUNG.md schreiben
4. LICENCE.md anlegen (falls noch nicht vorhanden)

Vom manuellen Workflow in den automatischen wechseln

Du hast bereits /coder, /judge und /fix manuell durchgeführt und möchtest den Rest automatisch ablaufen lassen:

/optimize --continue

/optimize --continue --rounds 5

/optimize --continue --with-doku

Die Implementierungsphase wird übersprungen — der Judge prüft sofort den aktuellen Stand und der Fix-Zyklus läuft automatisch bis PASS oder max. N Runden.

Loop-Erkennung

Wenn zweimal hintereinander dieselbe Beanstandung auftritt, bricht /optimize ab:

⚠ Schleife: Gleicher Blocker zweimal – manuelle Intervention nötig

Verglichen wird der Blocker-Abschnitt des Judges. Steht dort nur „Keine“, werden stattdessen die Major-Punkte verglichen; fehlen beide Abschnitte, der ganze Judge-Text. Zwei Runden mit „Blocker: Keine“, aber verschiedenen Major-Punkten sind also keine Schleife.

In diesem Fall: /judge manuell ausführen, Blocker lesen, mit /fix manuell eingreifen.

Max. Runden ohne PASS

⚠ 2 Runden durchlaufen ohne PASS. Bitte manuell prüfen.

Dann: /judge und /fix manuell für gezielte Eingriffe. Mit --rounds N kann die Grenze hochgesetzt werden, z.B. --rounds 5 für komplexe Aufgaben.

Interactive-Modus

Mit --interactive pausiert /optimize nach dem ersten PASS und wartet auf menschliches Feedback — bevor das abschließende SHIP ausgelöst wird.

/optimize Implementiere Feature X --interactive

Typischer Ablauf:

Phase 1: Coder implementiert...
Phase 2: Judge prüft...
  → Urteil: PASS
⏸ PASS erreicht. Weitere Features? /continue "Zusatzauftrag" — oder /continue zum Shippern.

Jetzt hast du drei Optionen:

Option A: Direkt shippern

/continue

→ ShipIt wird gestartet, Version-Dialog erscheint.

Option B: Zusatzauftrag hinzufügen

/continue "Füge außerdem eine --verbose Option hinzu"

→ Coder implementiert den Zusatz, dann läuft der Judge-Loop erneut an. → Nach erneutem PASS erscheint der Checkpoint wieder — du kannst beliebig viele Iterationen anhängen, bevor du mit /continue zum SHIP gehst.

Option C: Abbrechen

/cancel

→ Loop wird abgebrochen, kein SHIP.

Timeout: Wenn du 30 Minuten lang nichts eingibst, bricht /optimize automatisch ab.

Wann ist --interactive sinnvoll?

• Wenn der Auftrag aus mehreren voneinander abhängigen Features besteht
• Wenn du nach jeder fertigen Stufe entscheiden möchtest, ob du weitermachst
• Wenn du sicherstellen willst, dass nichts unbeabsichtigt committed wird

---

7. Kleine Änderungen: /patch und /quick_check

Für minimale Korrekturen — kein voller Review-Zyklus, keine TASK.md-Änderungen.

/patch — kleine Änderung umsetzen

/patch <beschreibung der änderung>

Der Coder ändert ausschließlich das Beschriebene, prüft ob es noch kompiliert/startet und erstellt einen Commit.

Beispiele:

/patch Mindestpasswortlänge von 4 auf 8 Zeichen erhöhen

/patch Fehlermeldung bei ungültigem Argument von stderr auf stdout umleiten

/patch Versionsnummer in Cargo.toml von 0.1.0 auf 0.2.0 erhöhen

/patch Die Funktion parse_args() soll bei fehlendem --input-Argument eine sinnvolle Hilfsnachricht ausgeben statt zu paniken

/quick_check — Änderung schnell prüfen lassen

/quick_check [was geprüft werden soll]

Der Judge schaut sich git show HEAD an und gibt nur OK oder PROBLEM zurück.

Beispiele:

/quick_check

/quick_check Prüfe ob die Mindestlängen-Änderung korrekt umgesetzt ist und keine Randfälle fehlen

Typische Ausgaben:

Urteil: OK

Die Änderung in src/main.rs Zeile 47 ist korrekt. Mindestlänge wird jetzt
sowohl bei --length als auch im Standardfall geprüft.

Urteil: PROBLEM

src/lib.rs Zeile 23: Der neue Mindestwert von 8 wird nur bei --length geprüft,
nicht beim Standardwert (16). Wenn jemand --length 6 übergibt, schlägt die
Validierung korrekt fehl, aber der Standardfall ist nicht abgedeckt.
Fix: Validierung in die Funktion generate_password() verschieben statt in parse_args().

Typischer /patch + /quick_check Workflow

/patch Timeout bei HTTP-Requests von 30 auf 10 Sekunden setzen

(Coder ändert, committet)

/quick_check Prüfe ob der Timeout auch bei Retry-Versuchen korrekt gilt

(Judge gibt OK oder zeigt konkretes Problem)

---

8. Dokumentation generieren: /update_doku

Nach Abschluss der Entwicklung (nach /shipit oder /optimize) erstellt /update_doku vier Dinge automatisch:

1. Code-Kommentare — erklärt das WARUM in den Quelldateien (Deutsch)
2. README.md — Entwicklerperspektive: Installation, Build, Verwendung
3. BEDIENUNGSANLEITUNG.md — Endnutzerperspektive: einfach, ohne Jargon
4. LICENCE.md — proprietäre Lizenz mit aktuellem Jahr und Inhaber aus git config user.name (wird nur angelegt wenn noch keine LICENCE.md vorhanden ist — existierende Lizenzen werden nie überschrieben)

/update_doku

Inkrementelles Update

/update_doku merkt sich via Git-Tags welche Dateien seit dem letzten Lauf geändert wurden. Nur geänderte Quelldateien werden neu kommentiert — unveränderte bleiben unangetastet.

Code-Kommentare: keine Änderungen seit letztem Lauf – übersprungen.
README.md: 2 Datei(en) geändert – wird geprüft
BEDIENUNGSANLEITUNG.md: 2 Datei(en) geändert – wird geprüft
LICENCE.md: bereits vorhanden – übersprungen.

Zusammen mit /optimize

/optimize Implementiere Feature X --with-doku

Führt nach SHIP automatisch /update_doku aus.

---

9. Versionsverwaltung: /version

pi_coder verwaltet Versionsnummern im SemVer-Format (vMAJOR.MINOR.PATCH) automatisch — basierend auf den Commit-Messages des generierten Codes.

Wie Commit-Messages die Version bestimmen

Der Coder verwendet standardmäßig das Conventional-Commits-Format:

Commit-Prefix	Beispiel	Bump-Typ
feat!: oder BREAKING CHANGE	feat!: API komplett überarbeitet	major (v1.0.0 → v2.0.0)
feat:	feat: CSV-Export hinzugefügt	minor (v1.0.0 → v1.1.0)
fix:, chore:, andere	fix: Crash bei leerer Datei	patch (v1.0.0 → v1.0.1)

Automatisch nach SHIP

Nach einem erfolgreichen SHIP-Verdikt in /optimize oder /shipit erscheint automatisch ein Dialog:

┌─ Version ──────────────────────────────────────────────┐
│ Aktuelle Version: v1.2.3. Commits seit letztem Tag:    │
│ minor-Bump erkannt.                                     │
│                                                         │
│  patch → v1.2.4                                         │
│  minor → v1.3.0  (empfohlen)                           │
│  major → v2.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘

Du kannst den empfohlenen Wert bestätigen oder manuell einen anderen wählen.

Manuell aufrufen

/version

Nützlich wenn du den Tag nachträglich setzen möchtest oder nach manuellen Commits.

Was passiert nach der Auswahl

1. Die Versionsnummer wird in die Projekt-Manifest-Datei geschrieben (falls vorhanden):
   • package.json → npm version --no-git-tag-version X.Y.Z
   • Cargo.toml → version = "X.Y.Z" in [package]
   • pyproject.toml → version = "X.Y.Z" in [project]
   • VERSION → Dateiinhalt vX.Y.Z
2. Commit: chore: bump version to vX.Y.Z
3. Git-Tag: vX.Y.Z wird gesetzt

Wenn keine der genannten Dateien vorhanden ist, wird nur der Git-Tag gesetzt.

Erstes Mal — kein Tag vorhanden

┌─ Version ──────────────────────────────────────────────┐
│ Noch kein Versions-Tag vorhanden.                       │
│                                                         │
│  patch → v0.0.1                                         │
│  minor → v0.1.0  (empfohlen)                           │
│  major → v1.0.0                                         │
│  Überspringen                                           │
└─────────────────────────────────────────────────────────┘

Empfehlung: v0.1.0 für ein frisches, funktionierendes Projekt; v1.0.0 wenn es sofort produktionsreif ist.

---

10. TASK.md verstehen und nutzen

TASK.md ist die persistente Aufgabenbeschreibung im Projektverzeichnis. Sie wird von allen Kommandos als Referenz gelesen.

Erstellt von /coder und /optimize

Beim ersten /coder-Aufruf:

# Aufgabe

Schreibe ein Python-Kommandozeilenprogramm 'textcount'...

## Erstellt
2026-05-19T14:30:00.000Z

## Status
- [ ] Implementierung
- [x] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)

Zusatzauftrag hinzufügen

Wenn du später /coder mit einer neuen Aufgabe aufrufst, wird TASK.md erweitert statt überschrieben:

/coder Füge zusätzlich eine --csv-Option hinzu, die das Ergebnis als CSV ausgibt

# Aufgabe

[...ursprüngliche Aufgabe...]

---

## Zusatzauftrag

2026-05-19T15:45:00.000Z

Füge zusätzlich eine --csv-Option hinzu...

## Status
- [ ] Implementierung
- [ ] Review bestanden (PASS)
- [ ] Produktionsreif (SHIP)

Status-Checkboxen

Die Checkboxen werden automatisch abgehakt:

• [x] Implementierung — nach erfolgreichem /coder oder Phase 1 von /optimize
• [x] Review bestanden (PASS) — nach PASS durch /judge oder in /optimize
• [x] Produktionsreif (SHIP) — nach SHIP durch /shipit oder /update_doku

---

11. Typische Anwendungsfälle

Neues Rust-Programm von Null

# 1. Verzeichnis anlegen
/new_project ~/Rust_Programs/mein_tool

# 2. Terminal: in Verzeichnis wechseln und pi neu starten
# cd ~/Rust_Programs/mein_tool && pi

# 3. In pi: vollautomatisch implementieren + dokumentieren
/optimize Schreibe ein Rust-CLI-Tool 'csvfilter' das CSV-Dateien zeilenweise filtert. Optionen: --column NAME, --value WERT, --regex. Ausgabe auf stdout. --with-doku

Bestehendes Projekt verbessern

# In pi, im Projektverzeichnis:
/coder Refaktoriere die Datenbankschicht: ersetze das raw-SQL durch sqlx mit typsicheren Queries. Alle Tests müssen danach noch laufen.
/judge
/fix
/shipit

Schnelle Bugfixes

/patch Die Funktion split_csv() schlägt bei Feldern mit eingebetteten Kommas fehl (RFC 4180 nicht implementiert)
/quick_check

Repo ohne Test-Suite oder mit externer CI

# Test-Erkennung überspringen — Judge bewertet nur den Code
/optimize "Implementiere Feature X" --no-tests

# Externe Test-Suite explizit angeben
/optimize "Implementiere Feature X" --test-cmd "make integration-test"

Schneller Loop ohne ShipIt-Runde

# Für Projekte wo "PASS WITH CONCERNS" ausreicht:
/optimize "Kleines Refactoring" --approve-concerns

# Kombination: kein Test, PASS WITH CONCERNS akzeptieren, 1 Runde
/optimize "Typo-Fix in Fehlermeldungen" --rounds 1 --no-tests --approve-concerns

Versionsnummer nach der Entwicklung setzen

# Nach SHIP: Dialog erscheint automatisch
/optimize Neues Feature X --rounds 2
# → SHIP → Dialog → "minor → v1.1.0" wählen → Tag gesetzt

# Oder manuell:
/version

Kommentarlosen Legacy-Code dokumentieren

# Nur Kommentare und Dokumentation, kein Code ändern:
/update_doku

Schrittweise mit manuellem Review

/coder Implementiere OAuth2-Login mit GitHub
# → Code lesen, verstehen
/judge Besonderes Augenmerk auf Token-Speicherung und CSRF-Schutz
# → Judge-Bericht lesen
/fix Ignoriere den Minor-Punkt mit der Logging-Verbosität, das ist Absicht
/shipit

Experiment: mehrere Runden explizit

/optimize Schreibe einen vollständigen Markdown-Parser mit AST in Python --rounds 5

Schrittweise Features hinzufügen mit --interactive

# Erst Grundgerüst implementieren und PASS abwarten:
/optimize Schreibe ein CLI-Tool 'filewatch' das Dateiänderungen überwacht --interactive

# Nach PASS erscheint: ⏸ PASS – warte auf /continue…

# Option A: Genug, direkt shippern:
/continue

# Option B: Weiteres Feature anhängen:
/continue "Füge außerdem einen --filter GLOB-Parameter hinzu"
# → Coder implementiert, Judge prüft erneut, PASS → Checkpoint wieder aktiv

# Nochmal erweitern:
/continue "Füge --output-log DATEI hinzu um Änderungen zu protokollieren"

# Fertig → shippern:
/continue

---

12. Fehlermeldungen und Lösungen

"Urteil unklar: … Judge-Urteil nicht erkennbar"

Ursache: In der Judge-Antwort steht keine Zeile „Urteil: PASS | PASS WITH CONCERNS | FAIL“. Markdown dazwischen wird erkannt (## Urteil: **PASS**, **Urteil:** FAIL); fehlt das Wort ganz, gilt die Runde als nicht bestanden.

Lösung: Antwort im Chat lesen, dann /judge erneut oder /fix mit der Kritik.

"Modell-Datei nicht gefunden"

[!] Modell-Datei nicht gefunden: /home/.../models/qwen3/Qwen3.6-27B-Uncensored-...gguf

Ursache: Die GGUF-Datei liegt nicht am erwarteten Ort.

Lösung:

# Pfad prüfen:
ls $HF_HOME/models/qwen3/

# Oder mit explizitem Pfad starten:
HF_HOME=/korrekter/pfad ./start-coding-server.sh

Server startet nicht / HTTP nicht erreichbar

[!] HTTP-Server wurde nicht rechtzeitig erreichbar.

Ursachen und Lösungen:

1. Zu wenig VRAM — Container bricht beim Laden ab:

   docker logs coding_model | tail -50
   # Suche nach: "CUDA out of memory" oder "failed to allocate"
   

   → Kontext reduzieren: -c 65536 statt -c 262144 in start-coding-server.sh

2. GPU nicht verfügbar:

   nvidia-smi   # GPU sichtbar?
   # GPU 1 testen:
   docker run --gpus '"device=1"' --rm nvidia/cuda:12.0-base nvidia-smi
   # Andere GPU testen:
   GPU_DEVICE=0 ./start-coding-server.sh
   

3. Port 8001 bereits belegt:

   ss -tlnp | grep 8001
   docker ps -a   # alter Container noch vorhanden?
   ./stop-coding-server.sh
   ./start-coding-server.sh
   

"Agent is already processing a prompt"

Ursache: Ein Kommando wurde aufgerufen während pi agent noch auf eine Antwort wartet.

Lösung: Warten bis die aktuelle Antwort fertig ist, dann das Kommando wiederholen. Bei /optimize passiert das automatisch — der interne Mechanismus wartet auf idle.

"edits[n] ... oldText must match exactly"

Ursache: Der interne pi-agent-Edit-Mechanismus hat beim Anwenden mehrerer Änderungen an derselben Datei versagt.

Was pi_coder dagegen tut: Ein tool_call-Hook in der Extension sortiert Mehrfach-Edits automatisch von hinten nach vorne (Bottom-up-Reordering), sodass frühere Edits spätere Positionen nicht verschieben. Zusätzlich steht das apply_patch-Tool bereit, das GNU patch -p1 mit Fuzzy-Matching nutzt.

Falls es trotzdem auftritt: Das Modell manuell anweisen:

Lies die Datei neu ein und wende die Änderungen als unified diff mit apply_patch an.

"N Runden ohne PASS" / Loop-Erkennung schlägt an

⚠ Derselbe Blocker tritt erneut auf – Schleife abgebrochen.

Ursache: Der Coder kann einen bestimmten Blocker oder Concern nicht beheben — z.B. weil die Aufgabe einen Widerspruch enthält oder ein externes System fehlt.

Lösung: Manuell eingreifen:

/judge  ← Judge-Bericht lesen

Dann den Blocker analysieren und entweder:

• /fix Ignoriere Blocker X, das ist nicht Teil dieser Aufgabe
• Den Code selbst anpassen und dann /fix aufrufen
• Die Aufgabe in TASK.md präzisieren
• Bei komplexen Aufgaben mit mehr Runden wiederholen: /optimize --continue --rounds 5

Falls der Judge wiederholt Concerns findet, die du akzeptierst:

/optimize --continue --approve-concerns

Server läuft, aber pi wechselt nicht das Modell

Ursache: models.json oder settings.json wurde nach einer Änderung nicht neu deployt.

Lösung:

cd ~/pi_coder
./deploy-pi-config.sh
# Dann /reload in pi agent

"Neues Projekt" wechselt nicht das Verzeichnis

Das ist gewollt — pi-Sessions sind an ihr Startverzeichnis gebunden. Nach /new_project <pfad> im Terminal:

cd <pfad>
pi