docs(01): create phase 1 plan — 5 plans across 4 waves

2026-03-29 10:55:52 +02:00
parent 70c73f404c
commit 9624323c9b
6 changed files with 1960 additions and 2 deletions
@@ -0,0 +1,341 @@
+---
+phase: 01-grundger-st-tippmechanik
+plan: 02
+type: execute
+wave: 2
+depends_on: ["01-01"]
+files_modified:
+  - src/app.ts
+  - src/ui/screens.ts
+  - src/companion/characters.ts
+  - index.html
+autonomous: true
+requirements:
+  - FNDN-05
+  - ONBD-01
+  - ONBD-02
+  - ONBD-03
+  - ONBD-04
+
+must_haves:
+  truths:
+    - "App startet und zeigt den Willkommens-Screen"
+    - "4 Begleitfigur-Karten sind klickbar und zeigen Emoji + Name"
+    - "DE/CH Layout-Toggle ist waehlbar"
+    - "Nach Auswahl + Los gehts wechselt die App zur Wald-Uebersicht"
+    - "Nach Browser-Reload bleibt die Auswahl erhalten und Willkommens-Screen wird uebersprungen"
+  artifacts:
+    - path: "src/app.ts"
+      provides: "Screen management and routing"
+      exports: ["showScreen", "initApp"]
+    - path: "src/ui/screens.ts"
+      provides: "Welcome screen logic and companion selection"
+      exports: ["initWelcomeScreen"]
+    - path: "src/companion/characters.ts"
+      provides: "Companion definitions (name, emoji, personality)"
+      exports: ["companions", "CompanionDefinition"]
+  key_links:
+    - from: "src/app.ts"
+      to: "src/storage/db.ts"
+      via: "checks progress on init to skip welcome"
+      pattern: "getProgress"
+    - from: "src/ui/screens.ts"
+      to: "src/storage/db.ts"
+      via: "saves companion + layout choice"
+      pattern: "saveProgress"
+    - from: "src/main.ts"
+      to: "src/app.ts"
+      via: "calls initApp() on DOMContentLoaded"
+      pattern: "initApp"
+---
+
+<objective>
+Implement screen management (CSS fade transitions between 5 screens) and the complete onboarding flow: companion selection, layout selection, persistence, and navigation to forest.
+
+Purpose: The user must be able to start the app, choose a companion and layout, and reach the forest overview. This is the entry point for all subsequent gameplay.
+Output: Working welcome-to-forest flow with IndexedDB persistence.
+</objective>
+
+<execution_context>
+@$HOME/.claude/get-shit-done/workflows/execute-plan.md
+@$HOME/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/phases/01-grundger-st-tippmechanik/01-CONTEXT.md
+@.planning/phases/01-grundger-st-tippmechanik/01-01-SUMMARY.md
+@SPEC.md (sections 5.2, 7.1, 7.2)
+
+<interfaces>
+From src/types.ts:
+```typescript
+export type CompanionType = 'fee' | 'einhorn' | 'fuchs' | 'eule';
+export type KeyboardLayout = 'de' | 'ch';
+export type ScreenName = 'welcome' | 'forest' | 'lesson' | 'reward' | 'parent';
+export interface Progress {
+  id: 1;
+  currentLevel: number;
+  completedLevels: number[];
+  totalSessions: number;
+  sessionDates: string[];
+  selectedCharacter: CompanionType;
+  selectedLayout: KeyboardLayout;
+}
+```
+
+From src/storage/db.ts:
+```typescript
+export function openDB(): Promise<IDBDatabase>;
+export async function getProgress(db: IDBDatabase): Promise<Progress | null>;
+export async function saveProgress(db: IDBDatabase, progress: Progress): Promise<void>;
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Screen management + companion definitions</name>
+  <files>
+    src/app.ts, src/companion/characters.ts
+  </files>
+  <read_first>
+    src/types.ts
+    src/storage/db.ts
+    src/styles/main.css
+    index.html
+    SPEC.md (section 5.2 for companion definitions, section 7.1 for screen list)
+  </read_first>
+  <action>
+    1. Create src/companion/characters.ts with companion definitions (per D-05, emoji placeholders):
+    ```typescript
+    import type { CompanionType } from '../types';
+
+    export interface CompanionDefinition {
+      type: CompanionType;
+      name: string;
+      emoji: string;
+      personality: string;
+    }
+
+    export const companions: CompanionDefinition[] = [
+      { type: 'fee', name: 'Lila', emoji: '🧚', personality: 'Sanft, ermutigend, ein bisschen vertraeumt' },
+      { type: 'einhorn', name: 'Stella', emoji: '🦄', personality: 'Froehlich, enthusiastisch, feiert jeden kleinen Erfolg' },
+      { type: 'fuchs', name: 'Finn', emoji: '🦊', personality: 'Ruhig, weise, humorvoll' },
+      { type: 'eule', name: 'Elsa', emoji: '🦉', personality: 'Geduldig, warm, grossmuetterlich' },
+    ];
+    ```
+
+    2. Create src/app.ts with screen management (per D-01):
+    ```typescript
+    import type { ScreenName } from './types';
+    import { openDB, getProgress } from './storage/db';
+    import { initWelcomeScreen } from './ui/screens';
+
+    let db: IDBDatabase;
+
+    export function showScreen(name: ScreenName): void {
+      document.querySelectorAll('.screen').forEach(el => {
+        el.classList.remove('screen--active');
+      });
+      const target = document.getElementById(`screen-${name}`);
+      if (target) {
+        target.classList.add('screen--active');
+      }
+    }
+
+    export function getDB(): IDBDatabase {
+      return db;
+    }
+
+    export async function initApp(): Promise<void> {
+      db = await openDB();
+      const progress = await getProgress(db);
+      if (progress && progress.selectedCharacter) {
+        // Returning user — skip welcome, go to forest
+        showScreen('forest');
+      } else {
+        // First time — show welcome
+        initWelcomeScreen(db, showScreen);
+        showScreen('welcome');
+      }
+    }
+    ```
+
+    3. Update src/main.ts to call initApp:
+    ```typescript
+    import './styles/main.css';
+    import { initApp } from './app';
+    document.addEventListener('DOMContentLoaded', initApp);
+    ```
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/zauberwald && npx tsc --noEmit</automated>
+  </verify>
+  <acceptance_criteria>
+    - src/companion/characters.ts exports `companions` array with 4 entries (fee, einhorn, fuchs, eule)
+    - src/companion/characters.ts contains emoji strings: '🧚', '🦄', '🦊', '🦉'
+    - src/app.ts exports `showScreen` and `initApp`
+    - src/app.ts imports from `./storage/db` and `./ui/screens`
+    - src/app.ts contains logic: if progress exists -> showScreen('forest'), else showScreen('welcome')
+    - src/main.ts contains `import { initApp } from './app'` and `initApp`
+    - `npx tsc --noEmit` exits 0
+  </acceptance_criteria>
+  <done>Screen transitions work via CSS class toggling, companion data defined, app routes to welcome or forest based on saved progress</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Welcome screen UI + onboarding flow</name>
+  <files>
+    src/ui/screens.ts, index.html, src/styles/main.css
+  </files>
+  <read_first>
+    src/app.ts
+    src/companion/characters.ts
+    src/types.ts
+    src/storage/db.ts
+    src/styles/main.css
+    index.html
+  </read_first>
+  <action>
+    1. Update index.html — populate the welcome screen section with:
+    ```html
+    <section id="screen-welcome" class="screen screen--active">
+      <div class="welcome">
+        <h1>Willkommen im Zauberwald!</h1>
+        <p class="welcome__subtitle">Waehle deine Begleitfigur:</p>
+        <div class="welcome__companions" id="companion-grid">
+          <!-- Filled dynamically by screens.ts -->
+        </div>
+        <p class="welcome__layout-label">Tastatur-Layout:</p>
+        <div class="welcome__layout-toggle" id="layout-toggle">
+          <button class="layout-btn layout-btn--active" data-layout="de">DE</button>
+          <button class="layout-btn" data-layout="ch">CH</button>
+        </div>
+        <button class="welcome__start-btn" id="start-btn" disabled>Los geht's!</button>
+      </div>
+    </section>
+    ```
+    Keep the other 4 screen sections empty (just the section tag).
+
+    2. Create src/ui/screens.ts:
+    ```typescript
+    import type { CompanionType, KeyboardLayout, ScreenName, Progress } from '../types';
+    import { companions } from '../companion/characters';
+    import { saveProgress } from '../storage/db';
+
+    export function initWelcomeScreen(
+      db: IDBDatabase,
+      navigateTo: (screen: ScreenName) => void
+    ): void {
+      let selectedCompanion: CompanionType | null = null;
+      let selectedLayout: KeyboardLayout = 'de';
+
+      const grid = document.getElementById('companion-grid')!;
+      const startBtn = document.getElementById('start-btn') as HTMLButtonElement;
+      const layoutToggle = document.getElementById('layout-toggle')!;
+
+      // Render companion cards
+      companions.forEach(c => {
+        const card = document.createElement('button');
+        card.className = 'companion-card';
+        card.dataset.companion = c.type;
+        card.innerHTML = `
+          <span class="companion-card__emoji">${c.emoji}</span>
+          <span class="companion-card__name">${c.name}</span>
+        `;
+        card.addEventListener('click', () => {
+          grid.querySelectorAll('.companion-card').forEach(el =>
+            el.classList.remove('companion-card--selected')
+          );
+          card.classList.add('companion-card--selected');
+          selectedCompanion = c.type;
+          startBtn.disabled = false;
+        });
+        grid.appendChild(card);
+      });
+
+      // Layout toggle
+      layoutToggle.addEventListener('click', (e) => {
+        const btn = (e.target as HTMLElement).closest('.layout-btn') as HTMLButtonElement | null;
+        if (!btn) return;
+        layoutToggle.querySelectorAll('.layout-btn').forEach(el =>
+          el.classList.remove('layout-btn--active')
+        );
+        btn.classList.add('layout-btn--active');
+        selectedLayout = btn.dataset.layout as KeyboardLayout;
+      });
+
+      // Start button
+      startBtn.addEventListener('click', async () => {
+        if (!selectedCompanion) return;
+        const progress: Progress = {
+          id: 1,
+          currentLevel: 1,
+          completedLevels: [],
+          totalSessions: 0,
+          sessionDates: [],
+          selectedCharacter: selectedCompanion,
+          selectedLayout: selectedLayout,
+        };
+        await saveProgress(db, progress);
+        navigateTo('forest');
+      });
+    }
+    ```
+
+    3. Add CSS for welcome screen in src/styles/main.css:
+    - `.welcome` — centered flex column, padding 2rem, max-width 600px, margin auto
+    - `.welcome h1` — font-family Quicksand, font-size 2rem, color var(--text-dark)
+    - `.welcome__companions` / `#companion-grid` — display grid, grid-template-columns repeat(2, 1fr), gap 1rem
+    - `.companion-card` — background white, border 3px solid transparent, border-radius 16px, padding 1.5rem, cursor pointer, transition border-color 0.2s, text-align center, display flex, flex-direction column, align-items center, gap 0.5rem
+    - `.companion-card:hover` — border-color var(--accent-gold)
+    - `.companion-card--selected` — border-color var(--accent-green), background var(--bg-forest)
+    - `.companion-card__emoji` — font-size 3rem
+    - `.companion-card__name` — font-family Quicksand, font-weight 600, font-size 1.2rem, color var(--text-dark)
+    - `.layout-btn` — padding 0.5rem 1.5rem, border-radius 8px, border 2px solid var(--text-light), background white, cursor pointer, font-family Nunito, font-size 1rem
+    - `.layout-btn--active` — background var(--accent-green), color white, border-color var(--accent-green)
+    - `.welcome__start-btn` — margin-top 1.5rem, padding 1rem 3rem, border-radius 12px, background var(--accent-green), color white, border none, font-family Quicksand, font-weight 700, font-size 1.3rem, cursor pointer, opacity 1, transition opacity 0.2s
+    - `.welcome__start-btn:disabled` — opacity 0.4, cursor not-allowed
+    - `.welcome__layout-toggle` — display flex, gap 0.5rem, margin-top 0.5rem
+  </action>
+  <verify>
+    <automated>cd /home/dev/workspace/zauberwald && npx tsc --noEmit && npm run dev -- --strictPort 2>&1 &amp; sleep 3 && curl -s http://localhost:5173 | grep -q "companion-grid" && kill %1 && echo "PASS"</automated>
+  </verify>
+  <acceptance_criteria>
+    - index.html contains `id="companion-grid"` and `id="start-btn"` and `id="layout-toggle"`
+    - index.html contains `data-layout="de"` and `data-layout="ch"`
+    - src/ui/screens.ts exports `initWelcomeScreen`
+    - src/ui/screens.ts contains `saveProgress(db, progress)` call
+    - src/ui/screens.ts contains `navigateTo('forest')` after save
+    - src/ui/screens.ts creates 4 companion cards with `.companion-card` class
+    - src/styles/main.css contains `.companion-card`, `.companion-card--selected`, `.welcome__start-btn`
+    - src/styles/main.css contains `.layout-btn--active`
+    - `npx tsc --noEmit` exits 0
+    - Welcome screen renders 4 companion cards and DE/CH toggle in browser
+  </acceptance_criteria>
+  <done>Welcome screen shows 4 emoji companion cards, DE/CH layout toggle, and "Los geht's" button. Selecting companion enables start. Clicking start saves to IndexedDB and navigates to forest screen. On reload, app skips welcome and shows forest directly.</done>
+</task>
+
+</tasks>
+
+<verification>
+- App loads and shows welcome screen with 4 companion cards
+- Clicking a companion highlights it and enables "Los geht's"
+- DE/CH toggle switches active state
+- Clicking "Los geht's" transitions to forest screen (empty for now)
+- Refreshing the page skips welcome and shows forest directly
+- Clearing IndexedDB and refreshing shows welcome again
+</verification>
+
+<success_criteria>
+- Complete onboarding flow: select companion + layout, start, persist, skip on return
+- Screen transitions use CSS fade (opacity transition)
+- All companion data matches spec section 5.2 names
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/01-grundger-st-tippmechanik/01-02-SUMMARY.md`
+</output>