pi_coder/BEDIENUNGSANLEITUNG.md

Bedienungsanleitung: pi_coder

pi_coder ist ein Werkzeug, das zwei lokale KI-Modelle 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:

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

Judge (Port 8002): Überprüft den Code mit dem Blick eines skeptischen Senior-Entwicklers. Prüft Korrektheit, Robustheit, Randfälle, Sicherheit und Produktionsreife. Gibt ein Urteil:

• PASS — Code ist in Ordnung
• PASS WITH CONCERNS — grundsätzlich akzeptabel, aber mit Anmerkungen
• FAIL — enthält Blocker, die behoben werden müssen

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-servers.sh

Ausgabe bei Erfolg:

[*] Starte beide Server parallel ...
[✓] Coder (:8001) bereit
[✓] Judge (:8002) bereit

Dauer: 1–3 Minuten (Modell wird in GPU-VRAM geladen).

Status prüfen

./status.sh

=== LLaMA-Server Status ===
qwen36-27b-coder (Port 8001): Container=RUNNING  HTTP=OK
qwen36-27b-judge (Port 8002): 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

Beide starten (empfohlen)

./start-servers.sh

Einzelnen Server neu starten

Z.B. wenn nur der Coder-Server abgestürzt ist:

./start-coder.sh

Beide stoppen

./stop-servers.sh

Alternativer Modellpfad

Falls die GGUF-Datei an einem anderen Ort liegt:

HF_HOME=/mnt/daten/huggingface ./start-servers.sh

---

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:

Urteil: PASS WITH CONCERNS

Blocker: keine

Major:
- Stoppwortliste ist hardcoded; große Projekte erwarten --stopwords-file Option

Minor:
- Keine --version Flag
- Fehlermeldung bei nicht-existenter Datei gibt keinen Exit-Code 1 zurück

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

Produktionsrisiken:
- Bei sehr großen Dateien (>1 GB) wird alles in den RAM geladen

Konkrete Fix-Aufträge:
1. exit(1) bei FileNotFoundError
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]

• --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.

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 prüft...
  → Urteil: FAIL (2 Blocker)
Phase 3: Runde 1/2: Coder fixt...
Phase 4: Runde 2/2: Judge prüft...
  → Urteil: PASS WITH CONCERNS
✓ PASS WITH CONCERNS nach Runde 2
Finale ShipIt-Prüfung... (nur bei PASS WITH CONCERNS)
  → SHIP
[Dialog: Version → v0.1.0 (empfohlen)]

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

Während des Ablaufs zeigt die Statuszeile immer die aktuelle Aktivität: Coder implementiert… → Editiere src/main.rs… → Git-Commit… → Judge reviewt (Runde 1/2)…

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

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 genau dieselben Blocker auftreten, bricht /optimize ab:

⚠ Derselbe Blocker tritt erneut auf – Schleife abgebrochen. Bitte manuell prüfen.

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 drei 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

/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

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

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

"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-servers.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 qwen36-27b-coder | tail -50
   # Suche nach: "CUDA out of memory" oder "failed to allocate"
   

   → Kontext reduzieren: -c 32768 statt -c 131072

2. GPU nicht verfügbar:

   nvidia-smi   # GPUs sichtbar?
   docker run --gpus '"device=1,2"' --rm nvidia/cuda:12.0-base nvidia-smi
   

3. Port bereits belegt:

   ss -tlnp | grep 800[12]
   docker ps -a   # alter Container noch vorhanden?
   ./stop-servers.sh
   ./start-servers.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 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

Server läuft, aber pi wechselt nicht das Modell

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

Lösung:

cd ~/pi_coder
./install.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