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](#1-konzept-coder-und-judge)
2. [Vorbereitung](#2-vorbereitung) (Modell wählen, Einrichten, pi aktualisieren)
3. [Alternative: llama.cpp-Server (:8001)](#3-alternative-llamacpp-server-8001)
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. [Schneller entwickeln](#schneller-entwickeln), [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. [Werkzeuge für pi: MCP-Server](#11-werkzeuge-für-pi-mcp-server)
12. [Web-Anwendungen testen](#12-web-anwendungen-testen)
13. [Typische Anwendungsfälle](#13-typische-anwendungsfälle)
14. [Fehlermeldungen und Lösungen](#14-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.

Judge und Freigabeprüfung berichten kurz: keine Tabelle bestandener Prüfungen, Blocker und Major vollständig mit
Fundstelle, Minor, fehlende Tests und Hinweise höchstens 5 Punkte je Abschnitt. Grund: Lange Berichte kosten
Rechenzeit und bleiben im Kontext jeder weiteren Runde (Messung im Repo `strata-betrieb`, FUNKTIONSWEISE).

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

### Modell wählen

Coder und Judge sind **ein** Modell. Standard ist `strata/qwen3.8-flash-next-iq3_s`, der lokale Strata-Server auf
`127.0.0.1:9090`. Seinen Betrieb (Start, GPU-Freigabe, Entladen nach 10 Minuten, Bilder) beschreibt
`~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md`. Ist das Modell entladen, lädt Strata es bei der ersten
Anfrage; die Bereitschaftsprüfung der Extension wartet darauf bis zu 3 Minuten.

Ein anderes Modell aus `models.json` setzt die Umgebungsvariable `PI_CODER_MODEL=<provider>/<id>` beim Start von pi,
z. B. der llama.cpp-Server aus [Kapitel 3](#3-alternative-llamacpp-server-8001):

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

Freie Eingaben (ohne Slash-Befehl) nutzen pis eigenes Standardmodell aus `~/.pi/agent/settings.json`.
`--provider`/`--model` ändern es für einen Lauf, ohne die globalen Einstellungen anzufassen:

```bash
pi --provider strata --model qwen3.8-flash-next-iq3_s
```

**Bilder** (Screenshots, `read` auf PNG/JPG, Browser-Screenshots) erreichen nur Modelle, die in `models.json`
`"input": ["text", "image"]` haben. Strata ist so eingetragen. Bei anderen Modellen meldet pi „Current model does not
support images“ und lässt das Bild weg.

### Einrichten

Einmalig und nach Änderungen an `models.json` oder `settings.json`:

```bash
cd ~/pi_coder_v2
./deploy-pi-config.sh
```

Das Skript **verlinkt** `pi-coding-extension.ts` und `mcp.json` nach `~/.pi/agent/`. Änderungen im Repo gelten
damit ab dem nächsten pi-Start (oder `/reload`), auch noch nicht committete, und `pi mcp add` schreibt direkt ins
Repo. `models.json` wird kopiert, aus `settings.json` nur die Liste `packages` übernommen. Eine abweichende alte
Datei sichert das Skript vorher als `.bak`.

### pi öffnen

pi im Projektordner starten, also dort, wo der Code liegt, nicht in `~/pi_coder_v2`:

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

### pi aktualisieren

`pi update` ersetzt pis Programmdateien. Ein pi, das dabei läuft, findet danach Teile seines eigenen Codes nicht mehr,
und jede Modellanfrage scheitert (siehe [Fehlermeldungen](#cannot-find-module--chunks-nach-pi-update)). Deshalb
nur aktualisieren, wenn kein pi läuft, oder alle laufenden pi danach neu starten.

---

## 3. Alternative: llama.cpp-Server (:8001)

Nur nötig, wenn Coder und Judge statt Strata das Modell `llama-cpp-single/coding_model` nutzen sollen: Qwen3.6-27B
IQ4_XS im Docker-Container `coding_model` auf einer GPU. Danach pi mit `PI_CODER_MODEL=llama-cpp-single/coding_model`
starten (siehe [Modell wählen](#modell-wählen)).

### 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_v2
./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
```

---

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

### Schneller entwickeln

Eine lange Sitzung an einem Tauri-Projekt mit Strata dauerte 12 Stunden, davon rund 9 Stunden Warten auf den
nächsten Befehl (Messung: `~/nvme2n1p7_home/strata-betrieb/FUNKTIONSWEISE.md`, „Messwerte“). Was schneller macht, nach
Wirkung:

1. **Eine Schleife statt einzelner Befehle.** Für einen weiteren Auftrag am selben Projekt
   `/optimize --continue "Zusatzauftrag …" --rounds 5 --test-cmd "…"` statt `/judge`, `/fix` und `/shipit` von Hand.
   Die Schleife geht ohne Pause von Prüfung zu Reparatur.
2. **Neue pi-Sitzung je Auftrag** (pi neu starten). Der Kontext beginnt klein; in der gemessenen Sitzung lag der
   Prompt im Median bei 126 000 Tokens. Was pi wissen muss, steht in `TASK.md` und in Git.
3. **Teure Builds erst zur Freigabe.** Im Auftrag z. B.: „In den Fix-Runden nur `cargo test` und `npm run build`;
   `npx tauri build` erst bei der Freigabe.“
4. **Kurze Berichte** sind Standard (siehe [Konzept](#1-konzept-coder-und-judge)).
5. Ein schnelleres Cloud-Modell (`PI_CODER_MODEL=openrouter/…`) ist die letzte Stufe: kostet Geld, und der Code geht
   nach außen.

### 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. Werkzeuge für pi: MCP-Server

Eingetragen in `mcp.json` dieses Repos, nach `~/.pi/agent/mcp.json` verlinkt (`pi mcp list` zeigt den Zustand). Sie
gelten in jeder pi-Sitzung, auch in der Coder/Judge-Schleife:

| Server | Version | Zweck |
|---|---|---|
| `playwright` | `@playwright/mcp@0.0.83` | Web-Apps in einem headless Chrome bedienen (siehe [Kapitel 12](#12-web-anwendungen-testen)) |
| `context7` | `@upstash/context7-mcp@4.1.1` | aktuelle Doku von Bibliotheken nachschlagen (`resolve-library-id`, `query-docs`), damit das Modell keine veralteten APIs erfindet; Anfragen gehen an `context7.com` |

**codemode:** pi beschreibt MCP-Werkzeuge dem Modell nicht einzeln. Das Modell schreibt ein kurzes JavaScript, das sie
aufruft (`tools.mcp__context7__query_docs(...)`). Beide Server zusammen kosten so nur rund 870 Prompt-Tokens.

**Context7 benutzen:** im Auftrag den Server und die Bibliothek mit Version nennen, ein Thema je Frage, z. B.:

```
Schlage mit context7 in der aktuellen Doku von Tauri 2 nach: Wie sende ich aus einem Rust-Command
Fortschritts-Events an das Frontend? Kurzes Beispiel für beide Seiten, nenne die Bibliotheks-ID.
```

In `/optimize`-Aufträgen hilft der Satz „Schlage unklare APIs mit context7 nach, bevor du sie benutzt.“

**API-Key:** `mcp.json` enthält nur den Verweis `"CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"`. Der Key selbst gehört in
die Umgebung, z. B. `export CONTEXT7_API_KEY=…` in `~/.bashrc`. Fehlt die Variable, startet pi den Server **nicht**
(`pi mcp list`: `context7: failed`, „Failed to resolve … env "CONTEXT7_API_KEY"“). Steht der `export` in `~/.bashrc`
nach der Abfrage auf interaktive Shells, gilt das für Skripte, Cron und Dienste. Prüfen, ob der Key beim Server
ankommt (zeigt nur die Länge):
`tr '\0' '\n' < /proc/$(pgrep -f context7-mcp | head -1)/environ | grep '^CONTEXT7_API_KEY=' | cut -d= -f2- | wc -c`.
Den Einrichtungsassistenten `npx ctx7 setup` nicht benutzen: Er schreibt den Key im Klartext in die Konfiguration.

**Weitere Server** nur bei Bedarf, z. B. Serena (Code-Navigation über Language Server, lohnt bei großen Projekten)
oder ein Forgejo-Server (Issues, Pull Requests). Unnötig sind Dateisystem-, Git- oder Fetch-Server: Das können
`bash`, `read` und `research_web` schon. Versionen fest wählen, nur eine Version, die mindestens zwei Wochen alt ist.

---

## 12. Web-Anwendungen testen

pi testet Web-Apps über den MCP-Server `playwright` in einem **headless** Chrome (der installierte, `--browser chrome`),
nie über Klicks auf dem Desktop. Die Seite kommt als Text (Accessibility-Baum) beim Modell an; dafür reicht jedes
Textmodell. Für die Optik kann pi Screenshots machen; die sieht nur ein bildfähiges Modell (siehe
[Modell wählen](#modell-wählen)).

```bash
pi --provider strata --model qwen3.8-flash-next-iq3_s
# dann z. B.: Teste http://127.0.0.1:5173/ mit den Browser-Werkzeugen: fülle das Formular aus, sende es ab
#             und nenne das Ergebnis wörtlich. Mach danach einen Screenshot und prüfe das Layout.
```

**Für Projekte** ist eine Playwright-Testsuite verlässlicher: reproduzierbar, auch in CI. Im Auftrag an `/optimize`:
„Schreibe Playwright-E2E-Tests (`@playwright/test`, headless, `channel: 'chrome'`, `webServer` startet die App).“ und
`--test-cmd "npm test && npx playwright test" --test-timeout 900`. `channel: 'chrome'` nutzt den installierten Chrome,
`npx playwright install` ist dann nicht nötig.

Inhalte prüft man über Snapshot oder Testsuite; Screenshots kosten Zeit und sind ungenauer. Messwerte mit Strata und
die Einrichtung anderer Agenten (Hermes, OpenCode): `~/nvme2n1p7_home/strata-betrieb/BEDIENUNGSANLEITUNG.md`,
„Web-Anwendungen testen“.

---

## 13. 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
```

---

## 14. 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
   ```

### "Cannot find module … chunks" nach pi update

```
Cannot find module '…/pi-coding-agent/dist/bundle/chunks/openai-completions-….js'
```

**Ursache:** pi wurde aktualisiert (`pi update`), während diese pi-Sitzung lief. Jede Modellanfrage scheitert sofort;
`/optimize` läuft dann mit leeren Antworten durch, ohne zu arbeiten.

**Lösung:** pi beenden und neu starten, dann den Befehl wiederholen (bei `/optimize` mit `--continue`).

### pi -p hängt in Skripten

**Ursache:** `pi -p "…"` liest zusätzlich stdin, wenn das kein Terminal ist, und wartet auf dessen Ende.

**Lösung:** `pi … -p "…" </dev/null`.

### "Current model does not support images"

**Ursache:** Das gewählte Modell ist in `models.json` nicht als bildfähig eingetragen; pi lässt das Bild weg.

**Lösung:** Ein bildfähiges Modell wählen, z. B. Strata (siehe [Modell wählen](#modell-wählen)).

### "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_v2
./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
```