@codemcp/workflows-core 4.1.3 → 4.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemcp/workflows-core",
-  "version": "4.1.3",
+  "version": "4.2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",

package/resources/templates/architecture/game-architecture.md

@@ -0,0 +1,250 @@
+# Game Architecture 🏗️
+
+**Game**: [GAME_NAME]  
+**Platform**: [PLATFORM_CHOICE]  
+**Created**: [DATE]
+
+---
+
+## What This Document Is For
+
+This document explains the **BIG PICTURE** of your game:
+
+- What platform we're building on (Scratch? Browser? Python?)
+- What the main building blocks are
+- What each building block is responsible for
+- How they work together
+
+Think of it like planning with LEGO:
+
+- **Platform** = What type of LEGO we're using
+- **Building Blocks** = The main pieces we need
+- **Responsibilities** = What each piece does
+
+**No code, no files - just the big ideas!**
+
+---
+
+## Platform Decision
+
+<!-- LLM: Document the platform choice based on conversation with child -->
+
+**We chose [PLATFORM] because:**
+
+- [REASON_1]
+- [REASON_2]
+- [REASON_3]
+
+**Platform Options We Considered:**
+
+| Platform                       | Best For                   | Pros                                                  | Cons                       |
+| ------------------------------ | -------------------------- | ----------------------------------------------------- | -------------------------- |
+| **Scratch**                    | Total beginners, ages 8-10 | Visual blocks, can't make syntax errors, easy sharing | Less control over graphics |
+| **Browser (HTML5/JavaScript)** | Kids ready for "real" code | Works anywhere, full control, easy to share links     | Need to type carefully     |
+| **Python + Pygame**            | Kids who know Python       | Desktop games, powerful                               | Need to install Python     |
+
+---
+
+## The Big Picture
+
+<!-- LLM: Create a simple ASCII diagram showing main components and their relationships -->
+
+```
+┌─────────────────────────────────┐
+│      GAME MANAGER 🎮            │
+│   (The Boss - Runs Everything)  │
+└─────────────────────────────────┘
+              |
+              |
+    ┌─────────┴─────────┐
+    |                   |
+    v                   v
+┌─────────┐       ┌─────────┐
+│ PLAYER  │       │ ENEMIES │
+│  🧍     │       │  👾     │
+└─────────┘       └─────────┘
+    |                   |
+    └─────────┬─────────┘
+              v
+       ┌──────────────┐
+       │   DISPLAY    │
+       │   (Screen)   │
+       └──────────────┘
+```
+
+**How it works:**
+
+1. **Game Manager** is the boss - it controls everything
+2. **Player** and **Enemies** do their own things
+3. **Display** shows what's happening on screen
+4. Game Manager makes sure they all work together!
+
+---
+
+## Building Blocks
+
+<!-- LLM: For each building block, explain WHAT it does and its responsibilities.
+Keep it conceptual - no code examples, no specific implementation details.
+Focus on helping child understand the PURPOSE and ROLE of each block.
+Use simple analogies they can relate to. -->
+
+### 🎮 Game Manager
+
+The main controller that runs the whole game.
+
+**Responsibilities:**
+
+- Keeps the game running
+- Tells all the other parts when to do their jobs
+- Checks if the player won or lost
+- Keeps track of the score
+
+**Why we need it:**
+Every game needs someone in charge, like a referee in sports or a conductor in an orchestra.
+
+---
+
+### 🧍 Player
+
+The character the player controls in the game.
+
+**Responsibilities:**
+
+- Knows where it is in the game world
+- Remembers its health and score
+- Moves when the player presses keys
+- Checks if it touched something important
+
+**Why we need it:**
+This is YOU in the game! Without it, there's no way to play.
+
+---
+
+### 👾 Enemies
+
+The obstacles or challenges in the game.
+
+**Responsibilities:**
+
+- Knows where they are
+- Moves around in the game world
+- Checks if they touched the player
+- Makes the game challenging
+
+**Why we need it:**
+Games need challenges! Without enemies or obstacles, there's nothing to overcome.
+
+---
+
+### 🎯 [Additional Building Block]
+
+<!-- LLM: Add other building blocks based on the specific game type.
+Common examples:
+- Collectibles (coins, power-ups, items)
+- Projectiles (bullets, arrows, fireballs)
+- Obstacles (walls, platforms, hazards)
+- Level Manager (handles switching between levels)
+- Sound Manager (plays music and sound effects)
+- UI Manager (shows menus, buttons, messages)
+
+Keep each description simple and focused on responsibilities. -->
+
+[Describe building blocks specific to this game]
+
+---
+
+### 🖥️ Display
+
+Shows everything on the screen.
+
+**Responsibilities:**
+
+- Draws the player
+- Draws enemies and other game objects
+- Shows the score and health
+- Displays messages like "Game Over"
+
+**Why we need it:**
+We need to SEE what's happening! The display makes the invisible game visible.
+
+---
+
+## How They Work Together
+
+<!-- LLM: Explain the overall flow in simple terms. Focus on relationships, not implementation. -->
+
+Think of it like a team working together:
+
+**The Game Loop** (what happens over and over, very fast):
+
+1. **Game Manager** wakes everyone up: "Time to do your jobs!"
+2. **Player** checks if keys were pressed and moves
+3. **Enemies** move according to their patterns
+4. **Game Manager** asks: "Did anything touch anything?"
+   - Player hit enemy? → Player takes damage
+   - Player got coin? → Score goes up
+5. **Game Manager** asks **Display**: "Show what changed!"
+6. **Display** redraws everything on screen
+7. **Repeat!** This happens 60 times per second!
+
+**This is like a movie** - it happens so fast your eyes see smooth movement!
+
+---
+
+## Why Separate Into Building Blocks?
+
+Imagine your room:
+
+- **Messy**: Everything in one big pile - hard to find anything
+- **Organized**: Toys in toy box, books on shelf, clothes in closet - easy to find!
+
+**Same with games!**
+
+**All in one piece (BAD):**
+
+- Hard to understand
+- Hard to fix bugs
+- Hard to add new features
+- Confusing for everyone
+
+**Separated into building blocks (GOOD):**
+
+- Each block has ONE clear job
+- Easy to find where something happens
+- Easy to fix: "Enemy not moving? Check the Enemy block!"
+- Easy to add: "Want new enemy types? Make a new Enemy block!"
+
+**Professional game developers ALWAYS organize their games this way!**
+
+---
+
+## Key Decisions
+
+<!-- LLM: Document important architectural decisions in simple terms -->
+
+**Decision 1: [DECISION_TITLE]**
+
+- **What we decided**: [Simple explanation]
+- **Why**: [Reason in terms child understands]
+- **Impact**: [How this helps the game]
+
+**Decision 2: [DECISION_TITLE]**
+
+- **What we decided**: [Simple explanation]
+- **Why**: [Reason in terms child understands]
+- **Impact**: [How this helps the game]
+
+---
+
+## Remember
+
+**This is your game's blueprint!**
+
+- It shows WHO does WHAT
+- Each building block has its own job
+- They work together like a team
+- This is the BIG PICTURE - details come later!
+
+**Next**: Look at the Design document to see HOW to build each block with actual code! 🛠️
+
+Let's build something amazing! 🚀

package/resources/templates/design/game-design.md

@@ -0,0 +1,69 @@
+# Game Design 🛠️
+
+**My Game**: [GAME_NAME]  
+**Platform**: [PLATFORM - from architecture.md]  
+**Date**: [DATE]
+
+---
+
+## What This Document Is For
+
+This document explains **HOW we organize and structure** the code for building the game.
+
+Think of it like a construction plan:
+
+- **Requirements** = What we're building
+- **Architecture** = The main parts and their jobs
+- **Design** (this doc) = How to organize the construction
+
+**No code here - just the plan!** Actual code examples come during implementation.
+
+---
+
+## Core Concepts We'll Use
+
+<!-- LLM INSTRUCTION:
+Explain the 3-4 fundamental coding patterns the child will use repeatedly.
+Keep explanations simple and concrete. Use analogies.
+Platform-specific examples are good.
+
+Typical patterns:
+
+- State (Memory) 🧠
+- Mechanics (Rules) 📏
+- Presentation (Drawing) 🎨
+- The Game Loop 🔄
+
+-->
+
+## Usage of libraries
+
+<!--
+There are many libraries providing e. g. physics or other game specific features. Based on the requirements, pick proper libraries and explain to the child what they do.
+-->
+
+## 🗺️ How Code Is Organized
+
+<!-- LLM INSTRUCTION:
+Show the actual file/sprite structure for this specific game.
+Be concrete - list actual file names or sprite names.
+Explain WHAT goes in each file and WHY.
+
+IMPORTANT:
+- Don't put everything in one file!
+- Keep it object-oriented (one building block = one file)
+- Match the building blocks from architecture.md
+-->
+
+### File Structure for [PLATFORM]
+
+```
+[ACTUAL_FILE_STRUCTURE]
+
+Example for Browser/JavaScript:
+game/
+  ├── game.js       ← Game loop, manages everything
+  ├── player.js     ← Player class (state, mechanics, drawing)
+  ├── enemy.js      ← Enemy class
+  └── main.js       ← Starts the game
+```

package/resources/templates/requirements/game-requirements.md

@@ -0,0 +1,162 @@
+# My Game Plan 🎮
+
+**My Name**: [YOUR_NAME]  
+**Today's Date**: [DATE]  
+**My Game**: [GAME_NAME]
+
+---
+
+## 🎯 Core Game Principle
+
+<!-- LLM INSTRUCTION:
+This section captures the ABSOLUTE MINIMUM game - the simplest possible version that's still fun.
+Think: "What's the ONE thing that makes this game special?"
+Example: For a space shooter: "Player shoots enemies that move toward them"
+Example: For a platformer: "Player jumps over gaps to reach the end"
+Keep it to ONE sentence that describes the core gameplay loop.
+-->
+
+**The Main Idea** (in one sentence):
+
+[CORE_GAME_MECHANIC] - e.g., "A player dodges falling objects and collects coins"
+
+**What Makes It Fun**:
+
+[WHY_IS_THIS_FUN] - e.g., "It's exciting to see how long you can survive!"
+
+**Game Type**: [e.g., Arcade, Platformer, Puzzle, Space Shooter]
+
+---
+
+## 🚀 Version 1: Let's Build This First!
+
+<!-- LLM INSTRUCTION:
+These are the MINIMUM features needed to make the core game principle playable.
+Aim for 3-5 SIMPLE features. Child should be able to build this in 1-2 sessions.
+Each feature should be testable and celebratable when complete.
+Use simple, action-oriented language kids understand.
+-->
+
+**Goal**: Make a playable game with just the basics!
+
+### Must-Have Features:
+
+**1. [FEATURE_1]** 🎮
+
+- Example: "Player can move left and right"
+- Why we need it: So you can control your character!
+
+**2. [FEATURE_2]** 🎯
+
+- Example: "Enemies appear at the top and move down"
+- Why we need it: Something to dodge or shoot!
+
+**3. [FEATURE_3]** ⭐
+
+- Example: "Score goes up when you collect coins"
+- Why we need it: To know how well you're doing!
+
+**4. [FEATURE_4]** 💥
+
+- Example: "Game over when player hits enemy"
+- Why we need it: Games need a win/lose condition!
+
+**5. [FEATURE_5]** 🔄
+
+- Example: "Restart button to play again"
+- Why we need it: So you can try to beat your score!
+
+### ✅ How We Know Version 1 is Done:
+
+- [ ] I can start the game and see my character
+- [ ] I can control my character with the keyboard
+- [ ] [MAIN_THING] works (e.g., "Enemies appear and move")
+- [ ] I can win OR lose the game
+- [ ] I can play again after game over
+
+**When Version 1 is done**: We have a REAL GAME! 🎉
+
+**New features can be added incrementally – just start a new conversation and explain them**
+
+---
+
+## 🚧 Not Building This now (And That's OK!)
+
+<!-- LLM INSTRUCTION:
+Be explicit about what's out of scope to manage expectations.
+Help child understand why some things are too complex for now.
+Always end on a positive note about what they ARE building.
+-->
+
+**Things We're NOT Building** (maybe later!):
+
+- ❌ [OUT_OF_SCOPE_1] - e.g., "Multiplayer" → Too complex! Let's master single-player first
+- ❌ [OUT_OF_SCOPE_2] - e.g., "3D graphics" → 2D is perfect for learning!
+- ❌ [OUT_OF_SCOPE_3] - e.g., "Mobile app" → Browser version is easier to share!
+
+**Why not?** These would take a LONG time and lots of advanced skills. What we're building is already AWESOME! 🌟
+
+---
+
+## 📋 Our Build Order
+
+**Phase 1**: Core Game Principle → Version 1  
+_"Get something playable!"_
+
+**Phase 2**: Add Level 2 Polish  
+_"Make it feel great!"_
+
+**Phase 3**: Add Level 3 Features  
+_"Add variety and depth!"_
+
+---
+
+## 💭 Notes & Ideas
+
+<!-- LLM INSTRUCTION:
+Use this space to capture the child's random ideas, inspirations, or decisions made during development.
+Keep their creativity documented even if ideas don't fit current version.
+-->
+
+**Cool Ideas We Thought Of**:
+
+- [IDEA_1]
+- [IDEA_2]
+- [IDEA_3]
+
+**Games That Inspired Us**:
+
+- [INSPIRATION_1]
+- [INSPIRATION_2]
+
+**Things We Learned**:
+
+- [LEARNING_1]
+- [LEARNING_2]
+
+---
+
+## 🎊 Celebration Log
+
+<!-- LLM INSTRUCTION:
+Document milestones and achievements. This builds confidence and tracks progress.
+Update this as features are completed.
+-->
+
+**What We've Built So Far**:
+
+- [ ] Version 1 Complete! (Date: **\_**) 🎉
+- [ ] Level 2 Complete! (Date: **\_**) 🌟
+- [ ] Level 3 Complete! (Date: **\_**) 🚀
+
+**My Proudest Moments**:
+
+1. [ACHIEVEMENT_1]
+2. [ACHIEVEMENT_2]
+3. [ACHIEVEMENT_3]
+
+---
+
+**Remember**: Every great game developer started exactly where you are now! 🌟
+
+Let's build something awesome together! 🚀

package/resources/workflows/game-beginner.yaml

@@ -0,0 +1,424 @@
+# yaml-language-server: $schema=../../state-machine-schema.json
+---
+name: 'game'
+description: 'Educational game development workflow for children (ages 8-12): Learn to build games step-by-step with guidance, frequent reviews, explanations, and fun!'
+initial_state: 'constitution'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'children'
+  complexity: 'medium'
+  bestFor:
+    - 'Children learning game development'
+    - 'First-time game creators (ages 8-12)'
+    - 'Educational game projects'
+    - 'Learning programming through games'
+  useCases:
+    - 'Building your first video game'
+    - 'Learning game development concepts'
+    - 'Creating simple 2D games'
+  examples:
+    - 'Build a space shooter game'
+    - 'Create a platformer game'
+    - 'Make a simple puzzle game'
+  requiresDocumentation: true
+
+# States with default instructions and transitions
+states:
+  constitution:
+    description: 'Set up project documentation with game development principles'
+    default_instructions: |
+      You are helping a young game developer (ages 8-12) start their game development journey!
+
+      Explain that before we start, we need to set up some documents that help us to remain organized.
+
+      **Step 1: Set Up Project Documentation (REQUIRED)**
+
+      **YOU MUST call the `setup_project_docs()` tool with these parameters:**
+
+      ```
+      setup_project_docs({
+        requirements: "game-requirements",
+        architecture: "game-architecture",
+        design: "game-design"
+      })
+      ```
+
+      This creates three child-friendly documents in `.vibe/docs/`:
+      - `requirements.md` - Game development principles and what we're building
+      - `architecture.md` - Platform choice and code structure
+      - `design.md` - Features and how to implement them
+
+      **These documents are your long-term memory for this project!**
+
+      **Step 2: Explain to the Child**
+
+      After calling setup_project_docs(), explain what just happened:
+
+      "Hi! I'm so excited to help you build your first game! 🎮
+
+      I just created three special helper documents for us. Think of them like a smart notebook
+      that remembers everything we decide while building your game!
+
+      1. **Game Development Principles** - Our rules for making awesome games! Like: Start small,
+         test often, and celebrate every win!
+
+      2. **Game Architecture** - Where we'll write down HOW to build your game (what platform to
+         use, how to organize the code)
+
+      3. **Game Design** - Our plan for WHAT features to create and in what order
+
+      These documents are like our game's memory! Every time we make an important decision,
+      we'll write it down so we never forget. 🧠
+
+      Ready to start dreaming up your game idea?"
+
+      **Step 3: Check Understanding**
+
+      Ask: "Do you understand what these helper documents are for? Any questions before we start?"
+
+      WAIT for the child's response. Answer any questions patiently. Only proceed when they're ready.
+
+      **Important Notes:**
+      - Keep your explanation simple and enthusiastic
+      - Use the analogy of a "smart notebook" or "game's memory"
+      - Don't go into technical details about templates or file structure
+      - Focus on WHY we have these documents (to remember decisions)
+
+    transitions:
+      - trigger: 'docs_ready'
+        to: 'imagine'
+        additional_instructions: |
+          Great! Your project is set up! 🎮
+          Now let's dream up an awesome game idea!
+        transition_reason: 'Project documentation initialized, ready to imagine the game'
+
+  imagine:
+    description: 'Dream phase - describe the game you want to create'
+    default_instructions: |
+      Welcome to game building! 🎮
+
+      **Let the child describe their game idea:**
+
+      Ask questions like:
+      - "What kind of game do you want to make?"
+      - "What does the player do in your game?"
+      - "What makes it fun?"
+      - "What games do you like that are similar?"
+
+      **Apply "Start Small, Dream Big" principle:**
+
+      If they describe something very complex (like "Minecraft" or "Fortnite"):
+      - "That's an AMAZING idea!"
+      - "Big games like that are built in small pieces. What's the ONE most fun thing in your game?"
+      - "Let's build that part first, then add more later!"
+
+      **Document their idea in $REQUIREMENTS_DOC:**
+
+      Update the "Game Requirements" section with:
+      - Game concept and type
+      - Main goal
+      - What makes it fun
+      - Version 1 features (3-5 simple features)
+      - Future ideas (complex features for later)
+
+      **Before transitioning:**
+
+      Summarize back to them:
+      "So you want to build a game where [summarize their idea]. That sounds AWESOME!
+      For Version 1, let's build: [list 3-5 simple features]."
+
+      Ask: "Did I understand your idea correctly? Is there anything else you want to tell me
+      about your game before we figure out HOW to build it?"
+
+      WAIT for confirmation. Adjust if needed. Only proceed when they're happy with the plan.
+
+    transitions:
+      - trigger: 'idea_captured'
+        to: 'architecture'
+        additional_instructions: |
+          Awesome game idea! 🌟
+          Now let's figure out WHERE and HOW we'll build it!
+        transition_reason: 'Game idea documented in requirements, ready for technical planning'
+
+  architecture:
+    description: 'Choose platform and design the technical structure'
+    default_instructions: |
+      Now we need to make technical decisions! Read $REQUIREMENTS_DOC to understand the game concept.
+
+      **Step 1: Platform Choice**
+
+      Ask the child: "Where do you want to play your game?"
+      - "In a web browser?" → HTML5/JavaScript
+      - "As a program on your computer?" → Python/Pygame
+
+      Explain each option simply:
+      - **Browser**: Type code, works anywhere, more control
+      - **Python**: Desktop game, need to know Python
+
+      **Step 2: Design Architecture**
+
+      Update $ARCHITECTURE_DOC with:
+      - Platform decision and why
+      - Main game components (Player, Enemy, Game Manager, etc.)
+      - Simple ASCII diagram showing how components connect
+      - OOP explained simply (classes as blueprints)
+      - File organization for chosen platform
+      - State/Mechanics/Presentation separation
+
+      **Step 3: Set Up Development Environment**
+
+      Based on platform choice, set up quality tools:
+
+      **For HTML5/JavaScript:**
+      - Install ESLint, Prettier, Husky
+      - Configure scripts in package.json
+
+      **For Python:**
+      - Create virtual environment
+      - Install Ruff
+
+      **Step 4: Explain to Child**
+
+      "I just figured out HOW we'll build your game!
+
+      We're using [PLATFORM] because [REASON].
+
+      Your game will have these main parts:
+      - [COMPONENT_1] - like [SIMPLE_ANALOGY]
+      - [COMPONENT_2] - like [SIMPLE_ANALOGY]
+      - [COMPONENT_3] - like [SIMPLE_ANALOGY]
+
+      I also set up helper tools that check your code automatically - like spell-check for code!"
+
+      Ask: "Does that make sense? Do you understand how these pieces will work together?
+      Any questions before we plan out WHAT features to build?"
+
+      WAIT for confirmation.
+
+    transitions:
+      - trigger: 'architecture_complete'
+        to: 'design'
+        additional_instructions: |
+          Great! We know HOW to build it! 🏗️
+          Now let's plan out WHAT features to build and in what order!
+        transition_reason: 'Technical architecture complete, ready for detailed design'
+
+  design:
+    description: 'Plan features and implementation strategy'
+    default_instructions: |
+      Now we create a detailed plan for building the game!
+
+      Read $REQUIREMENTS_DOC and $ARCHITECTURE_DOC to understand what we're building and how.
+
+      **Step 1: Pick Libraries**
+      E. g. physics, platformer engines, etc. based on requirements.
+      Document in $DESIGN_DOC what libraries we'll use and why.
+
+      **Step 2: Update $DESIGN_DOC with detailed Feature Designs** - For each major feature:
+         - What it does (player perspective)
+         - How it works (technical)
+         - State/Mechanics/Presentation breakdown
+         - Edge cases to handle
+
+         **IMPORTANT: Don't code in this phase! Just plan!**
+
+      **Explain to Child:**
+
+      "I made a plan for building your game!
+
+      We'll focus on the very basics first. We captured additional ideas, but for now,
+      we'll build a simple version that works well.
+      After each step, we'll test and play what you built!"
+
+      Ask: "Do you see how we're breaking this into small pieces? Each step is something we can
+      finish and test! Does this make sense? Ready to start coding?"
+
+      WAIT for confirmation.
+
+    transitions:
+      - trigger: 'design_complete'
+        to: 'code'
+        additional_instructions: |
+          Perfect! We have our plan! 🎯
+          We'll be doing this step by step: After each major part we built, we will review it together to make sure you understand everything!
+        transition_reason: 'Detailed design complete, ready to implement'
+
+  code:
+    description: 'Build the game incrementally with frequent reviews'
+    default_instructions: |
+      You are building the game! Follow $DESIGN_DOC for implementation order and $ARCHITECTURE_DOC for structure.
+
+      **IMPORTANT: Build incrementally. Proceed to the review phase after each checked task from the plan**
+
+      **Implementation Strategy:**
+
+      **Build one testable feature at a time**
+
+      **⚠️ CRITICAL: Transition to review phase (proceed_to_phase(review)) after each increment**
+    transitions:
+      - trigger: 'feature_complete'
+        to: 'review'
+        additional_instructions: |
+          Feature complete! Let's review what we just built! 🎉
+        transition_reason: 'Major feature completed, time for incremental review'
+
+      - trigger: 'game_complete'
+        to: 'celebrate'
+        additional_instructions: |
+          The entire game is done! Time to celebrate! 🎊
+        transition_reason: 'All features complete, game is finished'
+
+  review:
+    description: 'Review and understand what was just built'
+    default_instructions: |
+      Time to review the code you just wrote and make sure the child understands it!
+
+      **Step 1: Explain What Was Built**
+
+      Summarize the feature in one sentence:
+      - "We just added player movement!"
+      - "We just made enemies appear and move!"
+      - "We just added collision detection!"
+
+      **Step 2: Show Specific Code Changes**
+
+      Highlight 2-3 key parts of the code and explain each. Encourage the child to open their code editor and follow along.
+
+      Example:
+      "Let me show you the important parts of what we just built:
+
+      1. **Keyboard Listener** - This is like a sensor that detects when you press arrow keys
+         [Show the code]
+
+      2. **Movement Logic** - This changes the player's position when keys are pressed
+         [Show the code]
+
+      3. **Boundary Check** - This keeps the player from going off the screen
+         [Show the code]"
+
+      Use simple analogies:
+      - Event listeners = sensors
+      - Variables = boxes that store information
+      - Functions = recipes that do specific jobs
+      - Classes = blueprints or instruction manuals
+
+      **Step 3: Demonstrate**
+
+      Run the game and show the new feature working:
+      "Let's test it! Try pressing the arrow keys..."
+
+      **Step 4: Celebrate**
+
+      "You just built [FEATURE]! That's a real game programming skill! 🌟"
+
+      **Step 5: Check Understanding**
+
+      Ask: "Do you understand how this works? Want me to explain any part again?"
+
+      WAIT for response. Answer questions.
+
+      **Step 6: Ask About Next Steps**
+
+      "Ready to build the next feature? Or do you need a break?"
+
+      If ready: Transition to 'code' with 'continue_coding' trigger
+      If done: Transition to 'celebrate' with 'game_complete' trigger
+
+    transitions:
+      - trigger: 'continue_coding'
+        to: 'code'
+        additional_instructions: |
+          Great! Let's build the next feature! 🚀
+        transition_reason: 'Child understands current feature, ready to continue'
+        review_perspectives:
+          - perspective: 'quiz-master'
+            prompt: |
+              You are a friendly quiz master helping a child explore and understand their code!
+
+              Ask 2-3 exploratory questions that make them FIND things in the code:
+
+              **Good Questions (make them explore):**
+              - "Can you find the line where we check if the spacebar was pressed? What does it say?"
+              - "Look for the variable that holds the player's score. What's it called?"
+              - "Find the Enemy class - what happens when an enemy reaches the bottom of the screen?"
+              - "Can you spot where we draw the player on the screen? Show me that function!"
+
+              **Bad Questions (too abstract):**
+              - ❌ "What is a variable?"
+              - ❌ "Explain object-oriented programming"
+              - ❌ "What does this function return?"
+
+              **Important:**
+              - Make it a treasure hunt, not a test!
+              - If they can't find it, give hints: "Look in the Player class..."
+              - Celebrate when they find it: "Yes! That's it! 🎉"
+              - The goal is active code exploration, not memorization
+              - Keep it fun and encouraging!
+
+      - trigger: 'game_complete'
+        to: 'celebrate'
+        additional_instructions: |
+          All features are done! Time for the final celebration! 🎊
+        transition_reason: 'All features complete and understood'
+
+  celebrate:
+    description: 'Celebrate the completed game and reflect on learning'
+    default_instructions: |
+      The game is COMPLETE! 🎉🎮🎊
+
+      **Step 1: Play the Complete Game**
+
+      "Let's play your finished game together! You built this!"
+
+      Let them play and enjoy it.
+
+      **Step 2: Celebrate the Achievement**
+
+      Be enthusiastic!
+
+      "You just built a REAL game! You're a game developer now! 🌟
+
+      Think about everything you learned:
+      - How to plan a game
+      - How to organize code (classes, state, mechanics, presentation)
+      - How to make things move on screen
+      - How to detect collisions
+      - How to add scoring and game rules
+
+      That's AMAZING! Many adults don't know how to do this!"
+
+      **Step 3: Reflect**
+
+      Ask:
+      - "What was the hardest part of building this game?"
+      - "What was the most fun part?"
+      - "What are you most proud of?"
+
+      **Step 4: Look Forward**
+
+      "Now that you've built Version 1, what would you want to add next?"
+
+      Review the "Future Ideas" list from $REQUIREMENTS_DOC.
+
+      **Step 5: Document the Achievement**
+
+      Update the plan file with:
+      - Game completion date
+      - What was learned
+      - What the child wants to build next
+      - Any notes for future sessions
+
+      **Step 6: Encourage Next Steps**
+
+      "You can keep building on this game, or start a new one!
+      You now have the skills to make ANY simple game you can imagine!"
+
+      **Congratulations, young game developer! 🚀**
+
+    transitions:
+      - trigger: 'enhance_game'
+        to: 'imagine'
+        additional_instructions: |
+          copy the development plan to a new file. Also move the existing conversation in .vibe to .vibe/archive
+        transition_reason: 'Adding features to existing game'