# 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](#1-konzept-coder-und-judge)
2. [Vorbereitung](#2-vorbereitung)
3. [Server starten und stoppen](#3-server-starten-und-stoppen)
4. [Neues Projekt anlegen](#4-neues-projekt-anlegen)
5. [Manueller Workflow: /coder → /judge → /fix → /shipit](#5-manueller-workflow)
6. [Automatischer Workflow: /optimize](#6-automatischer-workflow-optimize) (inkl. [Interactive-Modus](#interactive-modus))
7. [Kleine Änderungen: /patch und /quick_check](#7-kleine-änderungen-patch-und-quick_check)
8. [Dokumentation generieren: /update_doku](#8-dokumentation-generieren-update_doku)
9. [Versionsverwaltung: /version](#9-versionsverwaltung-version)
10. [TASK.md verstehen und nutzen](#10-taskmd-verstehen-und-nutzen)
11. [Typische Anwendungsfälle](#11-typische-anwendungsfälle)
12. [Fehlermeldungen und Lösungen](#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

```bash
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

```bash
./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`:

```bash
cd ~/MeinProjekt
pi
```

---

## 3. Server starten und stoppen

### GPU-Zuordnung

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

```bash
./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:
```bash
nvidia-smi --query-gpu=index,name,memory.used,memory.free --format=csv
```

### Server starten

```bash
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

```bash
./stop-coding-server.sh
```

### Status prüfen

```bash
./status-coding-server.sh
```

### Alternativer Modellpfad

Falls die GGUF-Datei an einem anderen Ort liegt:

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

### Anderes Modell für die Schleife

Ohne weitere Angabe arbeiten Coder und Judge mit `strata/qwen3.8-flash-next-iq3_s` (Strata, Port 9090). Das Modell
liest auch Bilder (`"input": ["text", "image"]` in `models.json`): Screenshots, die pi mit dem `read`-Werkzeug
öffnet, erreichen das Modell. Ist das
Modell entladen, lädt Strata es bei der ersten Anfrage und gibt vorher GPU 1 und 2 frei; die Bereitschaftsprüfung
wartet darauf bis zu 3 Minuten. Eingerichtet ist das in `~/nvme2n1p7_home/strata-betrieb` (dort
BEDIENUNGSANLEITUNG, „GPUs teilen“). Ein anderes Modell aus `models.json` setzt die Umgebungsvariable
`PI_CODER_MODEL` beim Start von pi, als `<provider>/<id>`, z. B. der llama.cpp-Server auf Port 8001:

```bash
PI_CODER_MODEL=llama-cpp-single/coding_model pi
```

`--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:

```bash
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](#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:
```markdown
# 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
```

```markdown
# 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

```bash
# 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

```bash
# 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

```bash
/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

```bash
# 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

```bash
# 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

```bash
# 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

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

### Schrittweise mit manuellem Review

```bash
/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

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

### Schrittweise Features hinzufügen mit --interactive

```bash
# 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:**
```bash
# 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:
   ```bash
   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:
   ```bash
   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:
   ```bash
   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:**
```bash
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:
```bash
cd <pfad>
pi
```