# Agent-Instructions: How to execute this Improvement-Plan > Historical execution notes: this file was written for a specific > long-running improvement-plan workflow. Do not execute it blindly from the > repository root. Current instructions in `AGENTS.md`, > `docs/agent-entrypoints.md`, and active operator messages take precedence. > In particular, push/deploy/nonstop/subagent rules below are historical unless > a current operator explicitly reactivates this plan. **Archivhinweis:** Lies das hier nur, wenn du gezielt an einem reaktivierten Task aus `docs/improvement-plan/` arbeitest. Prüfe vorher die aktuellen Repo-Entry-Points. ## Mission Diese Boilerplate von 8/10 auf 10/10 bringen. Du arbeitest die Tasks aus `docs/improvement-plan/` ab, in der Reihenfolge die `00-execution-order.md` vorgibt. Du hörst nicht auf bis alle aktiven (non-backlog) Tasks `completed` sind. ## Harte Regeln ### Regel 1 — Subagents für historische Planarbeit Für die ursprüngliche Planarbeit waren Subagents vorgesehen, damit große Phasen parallel analysiert werden können. In aktuellen Sessions gelten die jeweils aktiven Tool-/Agent-Anweisungen. - Pro Implementation-Block einen `general-purpose`-Subagent (z.B. „Implement Shared-Store-Package nach Spec X") - Pro Test-Block einen Subagent (Tests schreiben, ausführen, Coverage prüfen) - Pro Verification-Block einen Subagent (prüft ob Acceptance-Criteria erfüllt sind) - Für Code-Review nach jedem Phase-Abschluss: `gsd-code-reviewer`-Subagent - Für Recherche (Library-Wahl, Best-Practice) `Explore` oder `general-purpose` **Nicht:** bei reaktivierten Großphasen alles selber im Hauptkontext machen. ### Regel 2 — Atomic Commits Pro logischer Einheit ein Commit. Definition „logisch": - Eine neue Datei + zugehörige Tests = ein Commit - Eine Refactoring-Operation auf N Dateien = ein Commit - Ein Migration-Step (DB-Schema-Change + Code-Anpassung + Tests) = ein Commit **Niemals:** „WIP — alles auf einmal" oder Commits mit mehr als 15 Files (außer es ist ein Rename). Commit-Message-Format: ``` /: Refs: docs/improvement-plan//.md ``` Beispiel: ``` 03-scaling/shared-store: add redis adapter with TTL support Implements RedisAdapter alongside MemoryAdapter behind the SharedStore interface. Auto-selection via REDIS_URL env. Refs: docs/improvement-plan/03-scaling-infrastructure/shared-store.md ``` ### Regel 3 — Tests sind PFLICHT Jeder Task hat eine `## Test Requirements` Section in seiner Detail-MD. Du MUSST: 1. **Tests SCHREIBEN bevor du den Task als done markierst.** Test-First wo möglich. 2. Test-Files folgen Convention: `.test.ts` neben Source-File. 3. Vitest für Unit/Integration, Playwright für E2E. 4. Coverage muss nach Phase 10 (Test-Coverage-Task) die Per-Module-Gates erfüllen — bis dahin: jeder neue Code hat Tests. 5. Tests müssen passen, bevor du committed: `pnpm test:packages` + relevanter Filter. 6. Bei Refactoring von altem Code: bestehende Tests müssen grün bleiben + neue für veränderte Behavior. ### Regel 4 — Historische Fortschrittslogik Wenn ein reaktivierter Improvement-Plan-Task fertig ist: 1. Markiere ihn `completed` in der Detail-MD UND in PROGRESS.md 2. Schau in `00-execution-order.md` was als nächstes dran ist 3. Öffne dessen Detail-MD und fang an Wenn du einen Blocker hast (z.B. „Lib X funktioniert nicht wie erwartet"): 1. Dokumentiere den Blocker im Detail-MD-Progress-Log 2. Markiere Status `blocked: ` in PROGRESS.md 3. Wähle den nächsten Task der nicht von diesem Blocker abhängt 4. Suche einen nächsten unabhängigen Task, wenn der aktuelle Operator-Auftrag das vorsieht. Wenn wirklich alles blockiert ist: schreib eine `BLOCKERS.md` im improvement-plan-Verzeichnis mit der vollständigen Situation, dann beende die Session. ### Regel 5 — Abhaken + dokumentieren Nach jedem atomic commit: 1. **Detail-MD updaten** — im `## Progress Log`-Section eine Zeile dazu: ``` - 2026-MM-DD HH:MM — — ``` 2. **PROGRESS.md updaten** — Status-Spalte aktualisieren (pending → in_progress → completed) 3. Wenn ein neuer Insight aufkommt (z.B. „dieser Ansatz funktioniert nicht, ich nehme Y stattdessen") — kurz in der Detail-MD im `## Deviations from Plan`-Section festhalten ### Regel 6 — Staging-Server für Tests Du hast Zugang zu einem **Hetzner-Staging-Server mit Coolify-Deployment** des Boilerplates. **Was du dort darfst:** - Branches deployen und testen (Coolify-Auto-Deploy via Git-Push auf bestimmte Branches) - Externe Services (Redis, Sentry, Authentik, etc.) testweise hochziehen - DB-Migrations laufen lassen - Performance-/Last-Tests durchführen - AV-Scanner, Plugin-Sandbox usw. real testen **Was du NICHT darfst:** - Die Production-CI/CD-Pipeline brechen — alle Experimente in eigenem Branch - Production-Branch deployen ohne menschliches Review **Wie du drauf kommst:** - SSH-Zugang ist in `docs/improvement-plan/archive/STAGING-ACCESS.md` dokumentiert (vom Operator manuell einzurichten) - Coolify-Web-UI für Container-Management - Deployment-Branch z.B. `agent/experiments` oder pro-Task-Branch ### Regel 7 — Dependencies prüfen vor Start **Bevor du einen Task anfängst:** 1. Lies `00-execution-order.md` und schau ob alle `Depends on`-Tasks `completed` sind 2. Wenn nicht → wähle einen anderen Task 3. Falls du dir unsicher bist über Reihenfolge: spawne `Explore`-Subagent der den Codebase-Stand prüft ### Regel 8 — Kein Schema/API-Bruch ohne Migration-Plan Bei DB-Schema-Änderungen: - Prisma-Migration generieren + im gleichen Commit - Wenn Daten-Backfill nötig: Migration-Script in `prisma/migrations/_/data.ts` - Rollback-Plan in der Detail-MD `## Rollback Strategy`-Section dokumentieren Bei API-Breaking-Changes: - Versionierung (oder Deprecate + Sunset-Plan) statt direkter Bruch - TS-SDK-Regenerierung wenn Task #63 schon durch ist ### Regel 9 — Code-Style + Quality-Gates respektieren - `pnpm lint` muss grün sein vor Commit (max-warnings=0) - `pnpm typecheck` muss grün sein - `pnpm test` Subset muss grün sein - Bei Hook-Failure: nicht `--no-verify` benutzen, sondern den Failure-Grund beheben ### Regel 10 — Security-Track läuft parallel Es gibt einen separaten Security-Track (siehe `/tmp/security-audit-2026-05-16/`) der parallel von einem anderen Agent abgearbeitet wird. Achte auf Konflikt-Potenzial: - Wenn du eine Datei bearbeitest, die im Security-Track ebenfalls touched wird: git pull häufig, kleine Branches. - Wenn du Security-Issues entdeckst während du arbeitest: dokumentiere im `## Security Notes`-Section deiner Detail-MD und ggf. ein Hinweis in `BLOCKERS.md`. ## Workflow pro Task ``` 1. Open detail-md → lies vollständig 2. Check Dependencies in execution-order.md 3. Plan → Spawn `Plan`-Subagent mit detail-md als Input für Implementation-Strategy 4. Implement → Spawn `general-purpose`-Subagent mit klarem Brief 5. Test → Spawn `general-purpose`-Subagent für Test-Suite 6. Verify → Spawn `Explore`-Subagent oder `gsd-verifier` für Acceptance-Criteria-Check 7. Commit atomically (mehrere Commits wenn nötig) 8. Update detail-md (Progress Log) + PROGRESS.md (Status) 9. Historical only: push to remote if the current operator and network context explicitly allow it 10. Move to next task ``` ## Verbotene Aktionen - ❌ `git commit --no-verify` ohne ausdrückliche Erlaubnis - ❌ Pushes ohne aktuellen Operator-Auftrag - ❌ `git push --force` auf main/master - ❌ Production-DB-Migrationen ohne Backup-Verify - ❌ Secrets/`.env` committen - ❌ Tasks „skippen" weil zu schwer — dokumentier den Blocker, beweg dich weiter zu unblocked Tasks - ❌ Eigene Tasks erfinden die nicht im Plan stehen — wenn was fehlt, dokumentier in `PROPOSED-TASKS.md` und mach erst was geplant ist - ❌ Detail-MDs löschen / „aufräumen" — die sind die einzige Quelle der Wahrheit - ❌ Mehrere Tasks gleichzeitig anfangen ohne sie zu finishen — Eine Aufgabe nach der anderen ## Wenn etwas unklar ist Nicht „best-guess" und commits machen. Stattdessen: 1. `ASK-OPERATOR.md` im improvement-plan-Verzeichnis anlegen oder erweitern 2. Frage präzise formulieren mit Kontext + Optionen 3. Task auf `blocked: waiting-for-operator-input` setzen 4. Nächsten unblocked Task wählen und weitermachen ## Definition of Done pro Task Ein Task ist `completed` wenn: - [x] Acceptance-Criteria aus Detail-MD alle erfüllt - [x] Tests geschrieben + laufen grün - [x] `pnpm lint` + `pnpm typecheck` grün - [x] Atomic Commits lokal erstellt; Push nur mit aktueller Freigabe - [x] Detail-MD Progress-Log aktualisiert - [x] PROGRESS.md Status auf `completed` - [x] Falls externe Infrastruktur involviert (z.B. Sentry/Authentik): auf Staging verifiziert - [x] Doku-Files (`docs/.md`) wenn im Detail-MD gefordert ## Definition of Done für die ganze Phase Eine Phase ist `completed` wenn: - [x] Alle Tasks der Phase `completed` - [x] Phase-README hat `## Phase Summary` mit Lessons-Learned-Section - [x] Integration-Test über die Phasen-Features (gesamte Phase als ein Flow getestet) - [x] `gsd-code-reviewer` Subagent hat die Phasen-Commits reviewed