6.7 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | |||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| quick | 260329-ua1 | execute | 1 |
|
true |
|
Purpose: Make the project approachable for English-speaking developers browsing the repo. Output: README.md at project root
<execution_context> @$HOME/.claude/get-shit-done/workflows/execute-plan.md @$HOME/.claude/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @CLAUDE.md @package.json Task 1: Create README.md with full open-source documentation README.md Create README.md at project root in English. Structure it with these sections:Header area:
- Project name "Zauberwald" with a one-line tagline: "A magical typing tutor that teaches touch typing through an AI-generated enchanted forest"
- Short paragraph explaining the concept: a web app for teaching a 7-year-old child touch typing via QWERTZ keyboard, combining structured typing exercises with a dynamically growing AI-generated forest world. Curiosity-driven, not score-driven.
- Screenshot placeholder:
<!--  -->
Features section (bullet list):
- 10-finger touch typing with QWERTZ (DE/CH) on-screen keyboard with color-coded finger zones
- 3-phase micro-lessons: Discover, Practice, Build Words (90-120 seconds each)
- AI-generated forest rewards (Gemini API) — new forest elements appear after each lesson
- 4 companion characters (Fee Lila, Einhorn Stella, Fuchs Finn, Eule Elsa) with AI-generated dialogue
- Adaptive tempo that adjusts to the child's speed
- No visible scores, timers, or error counters — progress shown only through the growing forest
- Parent dashboard (Ctrl+Shift+E + code) with statistics, export/import, settings
- Audio feedback (key sounds, rewards) and optional speech output
- Offline-capable with IndexedDB storage (images cached as blobs)
- Watercolor pastel art style with gentle animations
Tech Stack section:
- Vanilla TypeScript (no framework)
- Vite 6.x (build tool)
- Biome (linting)
- Vitest (testing)
- Gemini API (text: gemini-2.5-flash, images: gemini-3.1-flash-image-preview)
- IndexedDB for client-side persistence
- Web Audio API + Web Speech API
Prerequisites:
- Node.js 18+
- npm
- Google Gemini API key (for AI features; app works with fallbacks without it)
Getting Started:
git clone <repo-url>
cd zauberwald
npm install
cp public/config.example.json public/config.json
# Edit public/config.json and add your Gemini API key
npm run dev
Then open http://localhost:5173
Available Scripts (table format from package.json):
npm run dev— Start dev server (--host 0.0.0.0)npm run build— Type-check and build for productionnpm run preview— Preview production build (port 4173)npm test— Run testsnpm run lint— Lint with Biomenpm run lint:fix— Lint and auto-fixnpm run generate-assets— Pre-generate companion character assets via Gemini
Project Structure (tree showing key directories):
src/
api/ — Gemini API client and config loader
audio/ — Sound effects and speech synthesis
companion/ — Character definitions, AI dialogue, fallbacks
forest/ — Forest scene rendering and reward logic
game/ — Keyboard, levels, typing engine, word lists
storage/ — IndexedDB persistence layer
ui/ — Screen management and parent dashboard
styles/ — CSS (single main.css with custom properties)
assets/ — Companion avatars, character sheets, fallback SVGs
types.ts — Shared type definitions
main.ts — App entry point
app.ts — App initialization and routing
public/
config.json — Runtime config (API keys, not committed)
scripts/
generate-assets.ts — Pre-generate character images
How It Works section: Explain the core loop in 2-3 paragraphs:
- The child picks a companion and starts a level. Each level introduces new keys on the home row (levels 1-6 in MVP).
- A micro-lesson has 3 phases: Discover (see new keys light up), Practice (type prompted letters with adaptive timing), Build Words (type simple words using learned keys).
- After completing a lesson, the forest grows: the app generates a new forest element image via Gemini API (or uses SVG fallbacks). The child is motivated to continue because they want to see what appears next in their forest — not because of points or stars.
Configuration section:
- Copy
public/config.example.jsontopublic/config.json - Add your Gemini API key
- Note: The app works without an API key using built-in fallback texts and SVG images
- Note: The API key is stored client-side — this is acceptable for private/single-user use
Deployment section:
npm run build
# Serve the dist/ directory with any static file server
# For VPS preview:
npm run preview # serves on 0.0.0.0:4173
Contributing section: "Contributions are welcome! Please open an issue first to discuss what you would like to change."
License section: "This project is not yet licensed. Please contact the author for usage terms." (Note: Do NOT create a LICENSE file, just mention status in README.)
Use clean markdown formatting. No emojis. Keep language concise and professional. test -f README.md && wc -l README.md | awk '{if ($1 >= 80) print "PASS: " $1 " lines"; else print "FAIL: only " $1 " lines"}' README.md exists at project root with all specified sections, content is in English, at least 80 lines, accurate to the actual codebase
- README.md exists at project root - Content is in English - All sections present: features, tech stack, prerequisites, getting started, scripts, project structure, how it works, configuration, deployment, contributing, license - File paths and commands match actual project structure<success_criteria> README.md is complete, accurate, and follows open-source conventions. A developer unfamiliar with the project can understand what it does, set it up, and run it. </success_criteria>
After completion, create `.planning/quick/260329-ua1-readme-md-erstellen-english-open-source-/260329-ua1-SUMMARY.md`