HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/AGENT-INSTRUCTIONS.md

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:

<phase>/<task-id>: <short description>

<longer body if needed>

Refs: docs/improvement-plan/<phase>/<task-file>.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: <source>.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: <reason> 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 — <commit-sha-short> — <kurzbeschreibung>
   

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/<timestamp>_<name>/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:

• Acceptance-Criteria aus Detail-MD alle erfüllt
• Tests geschrieben + laufen grün
• pnpm lint + pnpm typecheck grün
• Atomic Commits lokal erstellt; Push nur mit aktueller Freigabe
• Detail-MD Progress-Log aktualisiert
• PROGRESS.md Status auf completed
• Falls externe Infrastruktur involviert (z.B. Sentry/Authentik): auf Staging verifiziert
• Doku-Files (docs/<feature>.md) wenn im Detail-MD gefordert

Definition of Done für die ganze Phase

Eine Phase ist completed wenn:

• Alle Tasks der Phase completed
• Phase-README hat ## Phase Summary mit Lessons-Learned-Section
• Integration-Test über die Phasen-Features (gesamte Phase als ein Flow getestet)
• gsd-code-reviewer Subagent hat die Phasen-Commits reviewed