goralphy/CLAUDE.md

# goralphy

## Projekt
Autonomer Go Coding-Agent ähnlich wie Ralphy.
Nutzt lokale LLMs via OpenAI-kompatibler API (Docker AI, Port 12434).
Die lokalen LLMs sind klein und laufen auf einem Rechner mit 16GB RAM –
daher ist die Planung und Task-Aufteilung in atomare Schritte besonders wichtig.

Das Projekt unterstützt mehrere spezialisierte Agenten die zusammenarbeiten:
- **Planner-Agent**: Zerlegt PRD.md in atomare, ausführbare Tasks
- **Code-Agent**: Führt Tasks aus, schreibt Code, dokumentiert
- **Test-Agent**: Führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent
- **Research-Agent**: Recherchiert Fragen basierend auf konfigurierbaren Quellen
  (GitHub, Google, Reddit, StackOverflow)

Jeder Agent dokumentiert Erkenntnisse in `.agent-session.md` damit Fortschritte
nachvollziehbar sind und Agenten voneinander lernen können.

---

## Aktueller Implementierungsstand

### Fertig ✅
- `main.go` – Flag-Parsing, Modell-Auswahl via /v1/models API
- `agent/loop.go` – Worker-Loop mit Tool Calling + XML-Fallback Parser
- `agent/tools.go` – ToolExecutor: write_file, read_file, list_files (rekursiv), task_complete
- `agent/logger.go` – Verbose-Logging mit --verbose Flag
- `agent/session.go` – Session-Persistenz in .agent-session.md
- `prd/parser.go` – PRD.md Checkbox-Parser + MarkTaskComplete

### In Arbeit 🔄
- `agent/planner.go` – Planner-Agent (Grundgerüst vorhanden, noch nicht in loop.go integriert)

### Geplant 📋
- `agent/code.go` – Code-Agent
- `agent/test.go` – Test-Agent
- `agent/research.go` – Research-Agent

---

## Architektur

### Dateien
- `main.go` – Einstiegspunkt, Flag-Parsing, Modell-Auswahl
- `agent/loop.go` – Haupt-Loop, koordiniert alle Agenten
- `agent/tools.go` – Tool-Executor (Filesystem-Operationen)
- `agent/logger.go` – Strukturiertes Logging
- `agent/session.go` – Session-Persistenz
- `agent/planner.go` – Planner-Agent
- `agent/code.go` – Code-Agent (geplant)
- `agent/test.go` – Test-Agent (geplant)
- `agent/research.go` – Research-Agent (geplant)
- `prd/parser.go` – PRD.md Parser

---

## Agent Interface

Jeder Agent implementiert dieses Interface:

```go
type Agent interface {
    Run(task Task) (Result, error)
    Name() string
}

type Task struct {
    ID          int
    Title       string
    Description string
    OriginTask  string
}

type Result struct {
    Success  bool
    Output   string
    Findings string // wird in .agent-session.md dokumentiert
}
```

Jeder Agent bekommt:
- Einen `*openai.Client` für LLM-Calls
- Einen `*ToolExecutor` für Filesystem-Zugriff
- Einen `*Logger` für strukturiertes Logging
- Einen `*Session` für Persistenz

---

## Wichtige Konventionen

- **Go Modulname**: `llm-agent`
- **LLM Endpoint**: `http://127.0.0.1:12434/v1`
- **Default Modell**: `docker.io/ai/qwen3-coder:latest`
- **Arbeitsverzeichnis**: `./output` (per `--workdir` Flag)
- **PRD-Datei**: `PRD.md` (per `--prd` Flag)
- **Session-Datei**: `{workdir}/.agent-session.md`
- **Pfade**: immer relativ zum workdir, niemals absolut
- **Kontext**: frischer Kontext pro Task (kein Context-Bloat)
- **Fehlerbehandlung**: maxRetries=3 mit exponential Backoff

---

## Bekannte Probleme & Workarounds

| Problem | Workaround |
|---|---|
| Modell nutzt XML-Format statt JSON Tool Calling | XML-Fallback Parser in `loop.go` (`parseXMLToolCalls`) |
| Kleine Modelle (3B) halten sich nicht an Formate | Mindestens 7B Modell empfohlen |
| `go run` zeigt auf `/tmp` | `os.Getwd()` statt `os.Executable()` |
| LLM schreibt absoluten Pfad | `sanitizePath()` extrahiert relativen Teil |
| `TASK_COMPLETE` ohne Arbeit in Turn 0 | Guard in `runTask()` – prüft ob Tool-Call stattfand |
| API Timeout bei großen Modellen | `context.WithTimeout` auf 5 Minuten |

---

## Commands

```bash
# Bauen
go build -o llm-agent .

# Starten
go run main.go --workdir output --prd PRD.md
go run main.go --workdir output --prd PRD.md --verbose
go run main.go --workdir output --prd PRD.md --verbose --model docker.io/ai/qwen3-coder:latest

# Tests
go test ./...
go test -v ./agent/...
go test -cover ./agent/...
```

---

## Vorgehensweise für Claude Code

1. Verfeinere Agent-Interface und Basis-Architektur
2. Integriere `planner.go` in `loop.go`
3. Implementiere `code.go` (Code-Agent)
4. Teste Code-Agent mit einfachen Tasks
5. Implementiere `test.go` (Test-Agent)
6. Verbinde Code-Agent und Test-Agent in Feedback-Loop
7. Implementiere `research.go` (Research-Agent)

---

## Spätere Erweiterungen

- **Vektor-Datenbank**: Speicherung von Agenten-Erkenntnissen und Code-Snippets
  für Wiederverwendbarkeit und Lernen zwischen Sessions
- **Git-Integration**: Automatische Commits pro Task, Steuerung via Pull Requests,
  Zusammenarbeit mehrerer Agenten auf separaten Branches
- **Discord-Integration**: Echtzeit-Monitoring und Interaktion mit Agenten
  über Discord Chat
- **Streaming**: LLM-Antworten Wort für Wort ausgeben statt auf einmal warten

---

## Session-Format (.agent-session.md)

```markdown
# Agent Session

Started: 2026-03-04 20:00:00
Model: docker.io/ai/qwen3-coder:latest
PRD: output/PRD.md

## Plan

###  Erstelle go.mod[1]
Origin: Projektstruktur anlegen
Description: Erstelle go.mod mit Modulname llm-agent...

## Tasks

### ✅ Erstelle go.mod
Status: complete
Started: 2026-03-04 20:00:01
Completed: 2026-03-04 20:00:45

### ❌ Erstelle main.go
Status: failed
Attempts: 3
Error: maximale Turns (10) erreicht ohne task_complete

### ⏳ Erstelle README.md
Status: pending
```

---

## Tool-Übersicht

## Tool-Übersicht

| Tool | Parameter | Beschreibung |
|---|---|---|
| `write_file` | `path`, `content` | Datei schreiben, Verzeichnisse werden automatisch erstellt |
| `read_file` | `path` | Dateiinhalt lesen |
| `list_files` | `path`, `recursive?` | Verzeichnis auflisten, optional rekursiv |
| `delete_file` | `path` | Datei löschen |
| `move_file` | `from`, `to` | Datei verschieben oder umbenennen |
| `run_command` | `command`, `args[]`, `workdir?` | Beliebigen Shell-Befehl ausführen (z.B. `go build`, `go test`) |
| `run_tests` | `path?`, `flags[]?` | `go test ./...` ausführen, gibt Ergebnis und Fehler zurück |
| `git_command` | `args[]` | Beliebigen git-Befehl ausführen (z.B. `["commit", "-m", "msg"]`) |
| `git_status` | – | `git status` – zeigt geänderte Dateien |
| `git_diff` | `path?` | `git diff` – zeigt Änderungen |
| `git_commit` | `message`, `files[]?` | Dateien stagen und committen |
| `git_log` | `limit?` | Letzte Commits anzeigen |
| `web_search` | `query`, `sources[]?` | Websuche, optionale Quellen: `github`, `stackoverflow`, `reddit`, `google` |
| `fetch_url` | `url` | Inhalt einer URL abrufen und als Text zurückgeben |
| `task_complete` | `summary?` | Task als erledigt markieren, optionale Zusammenfassung |
| `task_failed` | `reason` | Task explizit als fehlgeschlagen markieren mit Begründung |

---

## Sicherheitsregeln

| Tool | Einschränkung |
|---|---|
| `write_file`, `delete_file`, `move_file` | Nur innerhalb `workdir` |
| `run_command` | Konfigurierbare Whitelist erlaubter Befehle |
| `git_command` | Nur im Projekt-Root, kein `git push` ohne Bestätigung |
| `web_search`, `fetch_url` | Optional deaktivierbar per Flag `--no-network` |

---

## Implementierung