Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,191 @@
# 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:
- [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/<feature>.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