Track HiveGrid Cloud planning reference
This commit is contained in:
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
|
||||
Reference in new issue
Block a user