- Einfache Jobs: Research, Codebase-Exploration, Dokumentations-Zusammenfassung — Aufgaben ohne Code-Änderungen oder Schema-Migrationen.
- Komplexe Jobs (Code-Änderungen, Tests, Migrationen, Deployments): vom Haupt-Agent selbst ausführen.
- Wenn der User sagt "keine Sub-Agents verwenden": daran halten, keine Ausnahmen.
- Sub-Agents haben in der Vergangenheit Code geschrieben der nicht gegen Produktion verifiziert wurde, Schema-Drifts verursacht und nicht getestet hat. Qualitätssicherung bleibt beim Haupt-Agent.
Der Agent MUSS vor jeder Implementierung das bestehende System analysieren:
1.**Backend lesen:** Welche Models, Routes, Services, Plugins, Contracts, Hooks, ARQ-Jobs existieren bereits für den betroffenen Bereich? Der Agent greppt und liest die relevanten Dateien BEVOR er Code schreibt.
2.**Frontend lesen:** Welche Pages, Components, Stores, Hooks, API-Clients, Block-Typen, Sidebar-Tabs existieren bereits für den betroffenen Bereich? Der Agent greppt und liest die relevanten Dateien BEVOR er Code schreibt.
3.**Datenbank lesen:** Welche Tabellen, Foreign Keys, RLS-Policies, Migrationen existieren bereits? Der Agent prüft `alembic/versions/` und die Produktions-DB BEVOR er neue Migrationen schreibt.
4.**Plugin-System lesen:** Welche Contracts, Manifests, Search Provider, Tools, Hooks existieren bereits in den betroffenen Plugins? Der Agent liest `plugin.py`, `contracts.py`, `manifest.py` BEVOR er neue Plugins oder Erweiterungen baut.
### 0.2 Pflicht zum Aufbau auf bestehendem Code
Der Agent MUSS auf bestehendem Code aufbauen. Es ist VERBOTEN:
- ❌ Parallele Systeme zu bauen die vorhandene Funktionalität duplizieren (z.B. ein separates Workstream-System wenn das `kommunikation` Plugin schon Conversations, Messages, Blocks, WebSocket hat)
- ❌ Neue Frontend-Pages zu bauen wenn vorhandene Pages die Funktion aufnehmen können (z.B. Dashboard, Communication, AgentDashboard, Workflows, Wiki, Settings)
- ❌ Neue Sidebars oder Panels zu bauen wenn die AISidebar (5 Tabs) oder MessageSidebar die Funktion aufnehmen können
- ❌ Neue Stores zu bauen wenn vorhandene Stores (commStore, uiStore, authStore, etc.) die Funktion aufnehmen können
- ❌ Neue API-Clients zu bauen wenn vorhandene API-Clients (api/comm.ts, api/ai.ts, api/automation.ts, etc.) die Funktion abdecken können
- ❌ Neue Block-Typen zu bauen wenn vorhandene Block-Typen (action_card, contact_card, miniapp, etc.) die Funktion abdecken können
- ❌ Dataclasses zu schreiben wenn echte SQLAlchemy Models + FastAPI Routes die richtige Lösung sind
- ❌ Mock-Tests zu schreiben wenn echte Integration-Tests mit der Test-DB möglich sind
- ❌ Module zu bauen die 0 Referenzen aus Routes/Plugins haben (unverbundener Code)
- ❌ Tasks als "done" zu markieren ohne echte Verifizierung (curl gegen echte API, grep-Beweis für Import-Verbindungen, tsc clean, Backend import OK)
### 0.3 Pflicht zur Verbindung
Jeder neue Code MUSS mit dem bestehenden System verbunden werden:
- **Backend:** Neue Module müssen in `app/main.py` oder in Plugin `routes.py` registriert werden. Neue Models müssen in `alembic/versions/` migriert werden. Neue Tools müssen im `tool_registry` registriert werden. Neue Hooks müssen in `plugin.py on_activate` registriert werden. Neue ARQ-Jobs müssen in `worker.py` registriert werden.
- **Frontend:** Neue Components müssen in vorhandene Pages integriert werden (nicht als neue Page). Neue API-Calls müssen vorhandene API-Clients nutzen oder erweitern. Neue Block-Typen müssen im `BlockRenderer.tsx` registriert werden. Neue Sidebar-Tabs müssen in der `AISidebar.tsx` registriert werden.
- **Verifizierung:** Der Agent beweist mit grep dass neue Module importiert/referenziert werden. Der Agent beweist mit curl/pytest dass die API funktioniert. Der Agent markiert nichts als "done" ohne diese Beweise.
### 0.4 Referenz-Architektur (was existiert und genutzt werden MUSS)
-`review` — Task implementiert, wartet auf Review/Tests
-`done` — Task hat Definition of Done (DoD) erfüllt
**Der Agent MUSS `PROGRESS.md` bei jedem Status-Wechsel aktualisieren.** Kein Task-Wechsel ohne PROGRESS.md-Update.
### Forgejo Issues & Milestones
- **Pro Phase (A-J):** Ein Forgejo Milestone (z.B. "Phase A — Stabilität", "Phase B — System-Konsolidierung")
- **Pro Task:** Ein Forgejo Issue mit Label `task` + Milestone der jeweiligen Phase
- **Pro Bug:** Ein Forgejo Issue mit Label `bug` + Priorität (`critical`, `high`, `medium`, `low`)
- **Pro Feature-Request:** Ein Forgejo Issue mit Label `enhancement`
**Der Agent MUSS für jeden Task ein Forgejo Issue erstellen** und die Issue-Nummer in `PROGRESS.md` eintragen.
### Commit-Messages
- Commit-Messages enthalten die Task-ID: `feat(B-LLM): zentraler LLM Client implementiert`
- Bug-Fixes referenzieren das Issue: `fix(#123): Redis-Connection-Leak behoben`
-`fixes #123` oder `closes #123` im Commit schließt das Issue automatisch
### Definition of Done (DoD)
Ein Task gilt erst als **DONE** wenn alle 8 DoD-Kriterien erfüllt sind (siehe `PLATFORM_ROADMAP.md`). Ein Task ohne Test ist NICHT done. Der Agent darf keinen Task als `done` markieren ohne DoD erfüllt zu haben.
### Phase-Gate-Review
Eine Phase gilt erst als **ABGESCHLOSSEN** wenn alle 7 Phase-Gate-Kriterien erfüllt sind (siehe `PLATFORM_ROADMAP.md`). Der Agent darf nicht zur nächsten Phase übergehen ohne Phase-Gate-Review bestanden zu haben.
## 10. Tracking-Ein-Datei-Regel (bindend seit 2026-08-27)
- **PROGRESS.md ist die einzige Source of Truth** fuer Status und offene Punkte. Keine weiteren parallelen Tracking-Dateien (test-bugs.md/fix-plan-v3 sind in docs/archive/ historisiert).
- Ein Finding wird nur eingetragen mit **tagesaktueller Live-Messung** (Befehl + Zaehler). 'Scanner sagt' oder Plan-Text allein reicht nie.
- Tests duerfen nur zusammen mit Pflegeanspruch entstehen: UI-Aenderung zieht Test-Nachzug im selben Commit nach sich. Geister-Tests (Importziel geloescht) werden sofort geloescht.
- Playwright-e2e bleibt dem eigenen Runner vorbehalten (vite.config exclude), kein Vitest-Collection.
