docs: create roadmap (6 phases)

gsd-framework/.planning/REQUIREMENTS.md

@@ -89,4 +89,4 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 ---
 *Requirements defined: 2026-03-10*
-*Last updated: 2026-03-10 after initial definition*
+*Last updated: 2026-03-10 after roadmap creation*

gsd-framework/.planning/ROADMAP.md

@@ -0,0 +1,138 @@
+# Roadmap: Pikachu Match
+
+## Overview
+
+Build a minimal, playable tile-matching puzzle game where players connect matching Pokemon tiles using paths with 3 or fewer straight lines. The journey starts with project foundation and game loop, builds up through grid rendering and input handling, implements the core path-finding algorithm, adds game state management and win/lose detection, ensures solvable boards with shuffle recovery, and finishes with visual polish for a smooth player experience.
+
+## 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: Core Foundation** - Project setup, game loop, event system, and basic types
+- [ ] **Phase 2: Grid and Input** - Rendered game board with clickable tiles
+- [ ] **Phase 3: Core Matching Mechanics** - Path-finding algorithm and tile matching
+- [ ] **Phase 4: Game State Management** - Win/lose detection and score tracking
+- [ ] **Phase 5: Board Generation and Recovery** - Solvable boards and shuffle feature
+- [ ] **Phase 6: Polish and UX** - Animations, mobile touch, and responsive design
+
+## Phase Details
+
+### Phase 1: Core Foundation
+**Goal**: Establish the project structure and fundamental architecture patterns that all other components build upon
+**Depends on**: Nothing (first phase)
+**Requirements**: CORE-01
+**Success Criteria** (what must be TRUE):
+  1. Developer can run `npm run dev` and see a blank Canvas with a colored background
+  2. Game loop runs at 60fps using requestAnimationFrame with delta time tracking
+  3. Event system allows components to subscribe to and emit typed events
+  4. Basic Tile model exists with properties for id, type, position, and cleared state
+**Plans**: TBD
+
+Plans:
+- [ ] 01-01: Project scaffolding with Vite + TypeScript + Canvas
+- [ ] 01-02: Game loop with delta time and event emitter
+- [ ] 01-03: Tile model and game configuration constants
+
+### Phase 2: Grid and Input
+**Goal**: Players can see a grid of Pokemon tiles and interact with them via mouse and touch
+**Depends on**: Phase 1
+**Requirements**: CORE-02, CORE-03
+**Success Criteria** (what must be TRUE):
+  1. Player sees a grid of colorful tiles arranged in rows and columns on screen
+  2. Player can click or tap a tile to select it (tile shows visual highlight)
+  3. Player can click or tap a second tile to attempt a match (both tiles highlighted)
+  4. Grid scales appropriately for different screen sizes (desktop and mobile)
+**Plans**: TBD
+
+Plans:
+- [ ] 02-01: Grid manager with 2D tile array and coordinate system
+- [ ] 02-02: Canvas renderer for drawing tiles and grid
+- [ ] 02-03: Input handler for mouse and touch events
+
+### Phase 3: Core Matching Mechanics
+**Goal**: Players can match and clear tiles by connecting them with valid paths (3 or fewer straight lines)
+**Depends on**: Phase 2
+**Requirements**: CORE-04, CORE-05, CORE-06, CORE-07, BOARD-02
+**Success Criteria** (what must be TRUE):
+  1. Two matching tiles disappear when connected by a valid path (0, 1, or 2 turns)
+  2. Match fails with visual feedback when tiles do not match or path requires more than 2 turns
+  3. Player sees score increase immediately after successful match
+  4. Cleared tiles become empty space that allows paths to pass through
+  5. Player can continue matching remaining tiles after each successful match
+**Plans**: TBD
+
+Plans:
+- [ ] 03-01: Path-finding algorithm with 3-line constraint
+- [ ] 03-02: Match engine and scoring system
+- [ ] 03-03: Visual feedback for matches (success and failure)
+
+### Phase 4: Game State Management
+**Goal**: Game detects and responds to win condition and no-moves state appropriately
+**Depends on**: Phase 3
+**Requirements**: CORE-08, CORE-09
+**Success Criteria** (what must be TRUE):
+  1. Player sees win message when all tiles are cleared from the board
+  2. Game detects when no valid moves remain and notifies the player
+  3. Game state machine handles transitions between idle, selected, matching, and game over states
+  4. Player can restart the game after win or game over
+**Plans**: TBD
+
+Plans:
+- [ ] 04-01: State machine with game states and transitions
+- [ ] 04-02: Win/lose detection and game over handling
+- [ ] 04-03: Move detector for no-moves state
+
+### Phase 5: Board Generation and Recovery
+**Goal**: Game generates solvable boards and provides shuffle when stuck
+**Depends on**: Phase 4
+**Requirements**: BOARD-01
+**Success Criteria** (what must be TRUE):
+  1. New game starts with a board that is guaranteed to be solvable
+  2. Player can trigger shuffle when no moves are available
+  3. Shuffle redistributes remaining tiles while preserving pairs
+  4. Player sees shuffle button or prompt when stuck with no valid moves
+**Plans**: TBD
+
+Plans:
+- [ ] 05-01: Board generation with solvability validation
+- [ ] 05-02: Shuffle utility for redistributing tiles
+- [ ] 05-03: No-moves prompt and shuffle trigger
+
+### Phase 6: Polish and UX
+**Goal**: Game feels smooth and responsive with satisfying visual feedback on all devices
+**Depends on**: Phase 5
+**Requirements**: UX-01, UX-02, UX-03
+**Success Criteria** (what must be TRUE):
+  1. Matched tiles animate smoothly before disappearing (scale, fade, or similar effect)
+  2. Game responds accurately to touch input on mobile devices without lag
+  3. Grid layout adapts responsively to phone and desktop screen sizes
+  4. Connection path is drawn visually when a match succeeds
+**Plans**: TBD
+
+Plans:
+- [ ] 06-01: Tile match animations and visual effects
+- [ ] 06-02: Connection path visualization
+- [ ] 06-03: Mobile touch optimization
+- [ ] 06-04: Responsive grid layout refinements
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Core Foundation | 0/3 | Not started | - |
+| 2. Grid and Input | 0/3 | Not started | - |
+| 3. Core Matching Mechanics | 0/3 | Not started | - |
+| 4. Game State Management | 0/3 | Not started | - |
+| 5. Board Generation and Recovery | 0/3 | Not started | - |
+| 6. Polish and UX | 0/4 | Not started | - |
+
+---
+*Roadmap created: 2026-03-10*
+*Granularity: standard*

gsd-framework/.planning/STATE.md

@@ -0,0 +1,63 @@
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-03-10)
+
+**Core value:** The satisfying "aha!" moment when you spot a valid connection and clear a pair — the core matching loop must feel smooth and rewarding.
+**Current focus:** Phase 1: Core Foundation
+
+## Current Position
+
+Phase: 1 of 6 (Core Foundation)
+Plan: 0 of 3 in current phase
+Status: Ready to plan
+Last activity: 2026-03-10 — Roadmap created, project initialized
+
+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:
+
+- [Init]: Web browser first, no backend, single level for v1
+
+### Pending Todos
+
+[From .planning/todos/pending/ — ideas captured during sessions]
+
+None yet.
+
+### Blockers/Concerns
+
+[Issues that affect future work]
+
+None yet.
+
+## Session Continuity
+
+Last session: 2026-03-10
+Stopped at: Roadmap created, ready to plan Phase 1
+Resume file: None