# Worklog für Agenten

Dieses Dokument existiert, weil Michael es angeordnet hat (#10509, 08.10.2026):
*„Das Worklog-Feature existiert schon Wochen lang. Aber ihr überseht es. Nimm
einen Task auf, dass die Doku und der initiale Prompt in Synapse um das
Worklog-Feature erweitert wird, dass es bloß nicht untergeht und jeder
weiß."* — Wenn du als Agent diese Seite liest, gehört das Worklog ab sofort
zu deinem Standard-Repertoire.

## Warum das Worklog?

Agenten sterben oft: Kontext-Limit, Sandbox-Wipe, Cron-Neustart. Was dabei
regelmäßig verloren geht, ist nicht das Wissen (dafür ist `/memory` da),
sondern die **Arbeits-Historie**: Was wurde an diesem Task schon probiert?
Welcher Commit ist gepusht, welcher nicht? Wer wartet auf wen? Genau dafür
ist das Worklog da — append-only, pro Task, abfragbar. Ein neuer Run liest
`GET /worklog/:task_id` und weiß in Sekunden, wo sein Vorgänger stehen blieb.

Die zweite Zielgruppe ist Michael: Das Worklog ist DIE alleininge Quelle für
die Fleet-Arbeits-Historie. Ohne Worklog-Eintrag existiert deine Arbeit für
die Fleet-Übersicht offiziell nicht.

## Die Pflichtregel

**Push-first, nicht push-last.** Zu JEDEM Meilenstein ein Eintrag:

- Fix-Commit gepusht
- MR erstellt, Verdict gefallen, Merge geschehen
- Pipeline-Status (insbesondere FAILED mit Ursache)
- Eskalation, Übergabe, Takeover
- CRIT/HIGH-Funde
- Kontext-Nähte (vor dem Kontext-Ende ein `summary`-Eintrag)

Ein Eintrag kostet einen Einzeiler:

```
GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt&agent=Janus
```

## Die kinds und wann du sie nutzt

| kind | Moment |
| --- | --- |
| `start` | Task geclaimt — Beweis, dass du übernommen hast |
| `progress` | jeder Meilenstein (siehe Pflichtregel) |
| `note` | Entscheidungen, Kontext, Beobachtungen |
| `error` | Fehler MIT dem, was du versucht hast |
| `summary` | Phase/Session abgeschlossen, bevor der Kontext knapp wird |
| `close` | Task fertig — letzter Eintrag, Status wird `completed` |

## Initialer Prompt (Baustein für Agent-Setups)

Kopiere diesen Block in den Start-/Cron-Prompt neuer Agent-Instanzen. Er ist
bewusst kurz gehalten, damit er in jedem Template Platz hat:

```text
WORKLOG-PFLICHT (Michael #8882/#10509, bindend): Zu JEDEM Meilenstein deiner
Arbeit pushe einen Eintrag nach Synapse /worklog — nicht erst am Sessionende:
- Taskübernahme:    kind=start
- Fix-Commit/MR/Verdict/Merge/Pipeline-Status: kind=progress
- Fehler (mit Fix-Versuch): kind=error
- Kontext-Naht (vor Kontextende): kind=summary
- Abschluss: kind=close (oder POST /worklog/:task_id/close)
Einzeiler: GET /worklog/push?task_id=<task>&kind=<kind>&content=<kurz>&agent=<dein-name>
Die Fleet-Task-Convention steht in GET /script/fleet-worklog-tasks-spec.
Die API-Referenz: docs/content/de/api/worklog.md (im synapse-Repo).
```

Fleet-Agents, die denselben Mind-Namen wiederverwenden, setzen `agent` auf
ihren Namen (`Janus`, `Minerva`, `Elara`, …) — so sind die Einträge je Agent
zählbar.

## Für Humans

Die Worklog-Übersicht liest sich am besten im Markdown-Format:
`GET /worklog/<task_id>?format=md` oder die Task-Liste
`GET /worklog/list?status=active`. Gesamthistorie:
`GET /worklog?limit=50`.