From cb4306517b297c568f64f3fbdc50434b17663635 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 29 Mar 2026 10:38:42 +0200 Subject: [PATCH] docs: create roadmap (4 phases) --- .planning/REQUIREMENTS.md | 6 +-- .planning/ROADMAP.md | 82 +++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 61 +++++++++++++++++++++++++++++ CLAUDE.md | 58 +++++++++++++++++++++++++++ 4 files changed, 204 insertions(+), 3 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md create mode 100644 CLAUDE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index f6efe59..68edf3d 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -219,10 +219,10 @@ Which phases cover which requirements. Updated during roadmap creation. | PRNT-07 | Phase 4 | Pending | **Coverage:** -- v1 requirements: 63 total -- Mapped to phases: 63 +- v1 requirements: 68 total +- Mapped to phases: 68 - Unmapped: 0 ✓ --- *Requirements defined: 2026-03-29* -*Last updated: 2026-03-29 after initial definition* +*Last updated: 2026-03-29 after roadmap creation (coverage confirmed: 68/68)* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..51ce7c6 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,82 @@ +# Roadmap: Zauberwald + +## Overview + +Vier Phasen bauen die App von der spielbaren Kern-Tippmechanik (ohne API) über die Gemini-Integration und das vollständige Spielerlebnis bis hin zum Polish mit Audio. Nach Phase 4 ist die App bereit zum Testen mit dem Kind. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [ ] **Phase 1: Grundgerüst + Tippmechanik** - Spielbare Tipp-Übung im Browser, komplett ohne API +- [ ] **Phase 2: Gemini-Integration + Asset-Pipeline** - Gemini-API für Text/Bild, generierte Character Assets eingebunden +- [ ] **Phase 3: Komplettes Spielerlebnis** - Alle 3 Übungsphasen verbunden, Wald wächst, Stufen 1–6 spielbar +- [ ] **Phase 4: Polish + Audio** - Animationen, Sounds, Export/Import — bereit fürs Kind + +## Phase Details + +### Phase 1: Grundgerüst + Tippmechanik +**Goal**: Eine spielbare Tipp-Übung im Browser, die ohne API funktioniert +**Depends on**: Nothing (first phase) +**Requirements**: FNDN-01, FNDN-02, FNDN-03, FNDN-04, FNDN-05, ONBD-01, ONBD-02, ONBD-03, ONBD-04, KYBD-01, KYBD-02, KYBD-03, KYBD-04, KYBD-05, TYPE-01, TYPE-02, TYPE-03, TYPE-04, LEVL-01, LEVL-02, LEVL-03, FRST-04, FRST-05, PLSH-06 +**Success Criteria** (what must be TRUE): + 1. Die App startet via `npm run dev` und ist von aussen unter `http://:5173` erreichbar + 2. Begleitfigur und Tastatur-Layout sind wählbar und die Auswahl bleibt nach Browser-Reload erhalten + 3. Stufe 1 (F, J, Leertaste) ist spielbar: Buchstaben erscheinen einzeln, richtiger Tastendruck loest sie auf, falscher Tastendruck tut nichts + 4. Nach 10 richtigen Buchstaben gilt die Uebung als abgeschlossen und Stufe 2 wird freigeschaltet + 5. Die Wald-Uebersicht zeigt den Stufenstatus (locked / current / completed) korrekt an +**Plans**: TBD +**UI hint**: yes + +### Phase 2: Gemini-Integration + Asset-Pipeline +**Goal**: Gemini-API funktioniert fuer Text und Bild, Character Sheets sind generiert und eingebunden +**Depends on**: Phase 1 +**Requirements**: GAPI-01, GAPI-02, GAPI-03, GAPI-04, GAPI-05, GAPI-06, ASST-01, ASST-02, ASST-03, ASST-04, COMP-01, COMP-02, COMP-03, COMP-04 +**Success Criteria** (what must be TRUE): + 1. `npm run generate-assets` generiert alle Character Sheets und Avatare erfolgreich in `src/assets/generated/` + 2. Der Willkommens-Screen zeigt echte generierte Avatare statt Platzhalter + 3. Ein Begruessungstext der Begleitfigur wird generiert (deutsch, max 25 Woerter) oder ein Fallback-Text erscheint wenn kein API-Key vorhanden ist + 4. Ein Waldelement-Bild kann mit Stil-Referenz generiert werden; bei fehlendem API-Key zeigt die App Fallback-Bilder ohne Absturz +**Plans**: TBD + +### Phase 3: Komplettes Spielerlebnis +**Goal**: Alle 3 Uebungsphasen verbunden, Wald waechst visuell, Stufen 1–6 vollstaendig spielbar +**Depends on**: Phase 2 +**Requirements**: TYPE-05, TYPE-06, TYPE-07, LEVL-04, LEVL-05, LEVL-06, FRST-01, FRST-02, FRST-03, RWRD-01, RWRD-02, RWRD-03, RWRD-04, PRNT-01, PRNT-02, PRNT-03, PRNT-04 +**Success Criteria** (what must be TRUE): + 1. Eine komplette Uebungseinheit ist spielbar: Entdecken → Ueben → Woerter → Belohnung → zurueck zum Wald + 2. Nach dem Belohnungs-Screen erscheint ein neues Bild im Wald und bleibt nach Reload erhalten + 3. Alle Stufen 1–6 sind spielbar, jede mit passenden Woertern aus gelernten Buchstaben + 4. Der Elternbereich ist erreichbar (Ctrl+Shift+E + "1234") und zeigt aktuelle Stufe, Einheiten, Uebungstage sowie Einstellungen + 5. Review-Einheiten erscheinen jede 3. Uebung; nach 2× derselben Stufe zeigt die Begleitfigur Ermutigung +**Plans**: TBD +**UI hint**: yes + +### Phase 4: Polish + Audio +**Goal**: Visuell und auditiv angenehmes Erlebnis, bereit zum Testen mit dem Kind +**Depends on**: Phase 3 +**Requirements**: AUDI-01, AUDI-02, AUDI-03, AUDI-04, AUDI-05, PLSH-01, PLSH-02, PLSH-03, PLSH-04, PLSH-05, PRNT-05, PRNT-06, PRNT-07 +**Success Criteria** (what must be TRUE): + 1. Sounds spielen bei richtigem Tastendruck, Belohnung und neuem Waldelement; Mute-Button funktioniert und Zustand bleibt nach Reload + 2. Buchstaben fallen sanft (keine ruckartigen Animationen), Sternenstaub-Animation erscheint bei Erfolg + 3. Sprachausgabe liest Companion-Text vor wenn aktiviert (Web Speech API, Deutsch) + 4. Export und Import funktionieren: Exportieren → Browser-Daten loeschen → Importieren → Fortschritt wiederhergestellt + 5. Keine unbehandelten Exceptions in der Browser-Konsole bei normalem Gebrauch +**Plans**: TBD +**UI hint**: yes + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Grundgerüst + Tippmechanik | 0/? | Not started | - | +| 2. Gemini-Integration + Asset-Pipeline | 0/? | Not started | - | +| 3. Komplettes Spielerlebnis | 0/? | Not started | - | +| 4. Polish + Audio | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..ec9e37c --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,61 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-03-29) + +**Core value:** Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt. +**Current focus:** Phase 1 — Grundgerüst + Tippmechanik + +## Current Position + +Phase: 1 of 4 (Grundgerüst + Tippmechanik) +Plan: 0 of ? in current phase +Status: Ready to plan +Last activity: 2026-03-29 — Roadmap created, all 63 v1 requirements mapped to 4 phases + +Progress: [░░░░░░░░░░] 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: - +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| - | - | - | - | + +**Recent Trend:** +- Last 5 plans: - +- Trend: - + +*Updated after each plan completion* + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- All phases: Vanilla TypeScript + Vite, no framework, DOM-based forest scene +- All phases: Gemini REST via fetch(), key in public/config.json (private use acceptable) +- Phase 2+: Vorab-generierte Character Assets per Build-Script (kein Onboarding-Warten) + +### Pending Todos + +None yet. + +### Blockers/Concerns + +None yet. + +## Session Continuity + +Last session: 2026-03-29 +Stopped at: Roadmap creation complete, ready to plan Phase 1 +Resume file: None diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..5c501df --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,58 @@ + +## Project + +**Zauberwald** + +Zauberwald ist eine Webapplikation, die einem 7-jährigen Kind das 10-Finger-Tastaturschreiben beibringt. Die App verbindet strukturiertes Tipptraining mit einer dynamisch wachsenden, KI-generierten Waldwelt. Fester Übungsrahmen, überraschende Belohnungen — Neugier statt Leistungsdruck. + +**Core Value:** Das Kind übt freiwillig weiter, weil es wissen will, was als Nächstes im Wald erscheint — nicht weil es Punkte sammelt oder Sterne verdient. + +### Constraints + +- **Tech Stack**: Vanilla TypeScript, Vite 6.x, kein Framework. Einzelne main.css mit CSS Custom Properties. Biome für Lint. Vitest für Tests. +- **API**: Gemini REST via fetch(), kein Google SDK. Key im Frontend akzeptabel (private Nutzung). +- **Datenhaltung**: IndexedDB (Bilder als Blobs). Kein Backend, kein Server. +- **Layout**: QWERTZ DE + CH. Unterschiede erst ab Stufe 14+ relevant. +- **Styling**: Pastellfarben, Aquarell-Stil, Quicksand + Nunito Fonts, min. 16px. Sanfte Animationen. +- **VPS-Deployment**: `--host 0.0.0.0`, Port 5173 (dev) / 4173 (preview). Kein HTTPS nötig. + + + +## Technology Stack + +Technology stack not yet documented. Will populate after codebase mapping or first phase. + + + +## Conventions + +Conventions not yet established. Will populate as patterns emerge during development. + + + +## Architecture + +Architecture not yet mapped. Follow existing patterns found in the codebase. + + + +## GSD Workflow Enforcement + +Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync. + +Use these entry points: +- `/gsd:quick` for small fixes, doc updates, and ad-hoc tasks +- `/gsd:debug` for investigation and bug fixing +- `/gsd:execute-phase` for planned phase work + +Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it. + + + + + +## Developer Profile + +> Profile not yet configured. Run `/gsd:profile-user` to generate your developer profile. +> This section is managed by `generate-claude-profile` -- do not edit manually. +