Initial Ralph scaffold for ralph-vibe

2026-01-10 11:59:27 +00:00
commit 688cfe57ed
9 changed files with 3469 additions and 0 deletions
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -0,0 +1,961 @@
+# Ralph Method: Step-by-Step Implementation Guide
+
+## From Idea to Deployed App Using 100% Vibe Coding
+
+This guide walks you through the exact steps to go from "I have an app idea" to "Claude Code built it for me overnight."
+
+---
+
+## Overview: The 7 Stages
+
+| Stage | What You Do | Output |
+|-------|-------------|--------|
+| 1 | Dump your idea | Raw idea document |
+| 2 | Expand into full spec | Structured requirements |
+| 3 | Convert to machine PRD | PROMPT.md + prd.json |
+| 4 | Set up project scaffold | Ready-to-run directory |
+| 5 | Execute Phase 1 (Foundation) | Working skeleton |
+| 6 | Execute remaining phases | Complete application |
+| 7 | Review and polish | Production-ready code |
+
+**Total human effort**: 1-3 hours of prompting and setup
+**Total Ralph effort**: Hours to days of autonomous coding
+
+---
+
+## Stage 1: Idea Dump (15-30 minutes)
+
+### Step 1.1: Brain Dump
+
+Open any text editor or chat with Claude/ChatGPT. Write everything in your head about the app. Don't organize, just dump.
+
+**Prompt to use:**
+
+```
+I have an app idea. I'm going to brain dump everything about it. 
+Don't respond until I say "DONE". Just acknowledge each message.
+
+[Then type everything: features, users, problems it solves, tech preferences, 
+things you've seen in other apps you like, random thoughts, everything]
+
+DONE
+```
+
+### Step 1.2: Initial Structuring
+
+After your dump, use this prompt:
+
+```
+Now organize what I described into these categories:
+
+1. PROBLEM: What problem does this solve? Who has this problem?
+2. SOLUTION: What is the app and how does it solve the problem?
+3. USERS: Who are the primary users? What are their goals?
+4. CORE FEATURES: What are the absolute must-have features for v1?
+5. NICE-TO-HAVE: What features can wait for v2?
+6. TECH PREFERENCES: Any specific technologies I mentioned or prefer?
+7. CONSTRAINTS: Any limitations, requirements, or non-negotiables?
+8. SIMILAR APPS: What existing apps is this similar to?
+
+Output as a structured document I can save.
+```
+
+### Step 1.3: Save Output
+
+Save the response as `docs/idea-dump.md` in a new folder for your project.
+
+**Checkpoint**: You should have a rough but organized document describing your app.
+
+---
+
+## Stage 2: Expand to Full Specification (30-60 minutes)
+
+### Step 2.1: Architecture Classification
+
+First, let the LLM identify what type of application this is:
+
+```
+Based on my app idea, classify this project:
+
+1. APPLICATION TYPE: What kind of application is this?
+   - Web application (frontend + backend)
+   - Web frontend only (static/SPA)
+   - Backend API only
+   - Desktop application (Electron, Tauri, native)
+   - CLI tool
+   - Mobile app (native, React Native, Flutter)
+   - Library/package
+   - Script/automation
+   - Game
+   - Other (specify)
+
+2. INTERFACE TYPES NEEDED: Based on the app type, what interfaces are relevant?
+   - REST API (web backends, mobile backends)
+   - GraphQL API (complex data relationships)
+   - IPC channels (desktop apps with multi-process)
+   - Module interfaces (libraries, internal boundaries)
+   - CLI arguments/flags (command-line tools)
+   - File formats (apps that save/load data)
+   - WebSocket/real-time (chat, live updates)
+   - System integrations (OS APIs, hardware, file system)
+   - Plugin architecture (extensible apps)
+   - None/minimal (simple scripts)
+
+3. DATA PERSISTENCE: How will data be stored?
+   - Remote database (PostgreSQL, MySQL, MongoDB)
+   - Local database (SQLite, LevelDB)
+   - File-based (JSON, YAML, custom format)
+   - In-memory only
+   - Cloud storage (S3, etc.)
+   - No persistence needed
+
+4. DEPLOYMENT MODEL:
+   - Cloud hosted (Vercel, AWS, GCP, etc.)
+   - Self-hosted server
+   - Desktop installer (Windows, macOS, Linux)
+   - Package registry (npm, PyPI, crates.io)
+   - App store (mobile)
+   - No deployment (local script)
+
+Output your classification with brief justification for each choice.
+```
+
+### Step 2.2: Feature Decomposition
+
+Take your structured idea and expand each feature:
+
+```
+For each CORE FEATURE in my idea document, break it down into:
+
+1. User Story: "As a [user], I want to [action] so that [benefit]"
+2. Acceptance Criteria: Specific, testable conditions that prove it works
+3. Data Required: What data/models does this feature need?
+4. Interface Points: Based on the app type identified, what interfaces does this feature need?
+   - For web apps: API endpoints
+   - For desktop apps: IPC handlers or module functions
+   - For CLI tools: commands/subcommands and flags
+   - For libraries: public API functions/classes
+5. UI/UX Components: What user-facing elements are needed (if applicable)?
+
+Be specific and concrete. Each acceptance criterion must be binary (pass/fail).
+```
+
+### Step 2.3: Technical Decisions
+
+Get explicit about the tech stack:
+
+```
+Based on my app requirements and the architecture classification, recommend a tech stack.
+
+Consider:
+- Application type: [from Step 2.1]
+- My preferences: [your preferences, e.g., "TypeScript", "Python", "whatever is fastest", or "none"]
+- Deployment target: [from Step 2.1, or your preference]
+- Data persistence: [from Step 2.1]
+
+For each technology choice, provide:
+1. The specific technology/framework
+2. Why it fits this project and architecture
+3. The exact versions to use (current stable)
+4. Any critical dependencies or companion tools
+
+Also identify:
+- Build tools needed
+- Testing framework appropriate for this app type
+- Linting/formatting tools
+- CI/CD approach (if applicable)
+
+Output as a tech-stack.md file.
+```
+
+### Step 2.4: Data Model Design
+
+```
+Based on the features and persistence model identified, design the data structures:
+
+For each model/entity:
+1. Name
+2. Fields with types
+3. Relationships to other models
+4. Validation rules
+5. Example data
+
+Adapt the format to the persistence type:
+- For databases: include indexes, constraints, migrations approach
+- For file-based: include file format specification, versioning strategy
+- For in-memory: include initialization and state management approach
+
+Output as a data specification.
+```
+
+### Step 2.5: Interface Contract
+
+```
+Based on the interface types identified in Step 2.1, design the contracts:
+
+FOR REST/GraphQL APIs:
+- Method and path (e.g., POST /api/users)
+- Request/response schemas
+- Authentication requirements
+- Error responses
+
+FOR DESKTOP IPC:
+- Channel names
+- Message types and payloads
+- Direction (main→renderer, renderer→main, bidirectional)
+
+FOR CLI TOOLS:
+- Commands and subcommands
+- Flags and arguments with types
+- Input/output formats
+- Exit codes
+
+FOR LIBRARIES:
+- Public functions/classes/types
+- Parameters and return types
+- Error handling approach
+- Usage examples
+
+FOR FILE FORMATS:
+- Schema/structure specification
+- Versioning approach
+- Migration between versions
+
+Design only the interface types relevant to this application.
+Group by feature area. Output as an interface specification.
+```
+
+### Step 2.6: Save Everything
+
+You should now have:
+- `docs/idea-dump.md` (from Stage 1)
+- `docs/architecture.md` (app type, interfaces, persistence, deployment)
+- `docs/features.md` (feature breakdown with acceptance criteria)
+- `docs/tech-stack.md` (technologies with versions)
+- `docs/data-models.md` (data structures)
+- `docs/interfaces.md` (API/IPC/CLI/library contracts as applicable)
+
+**Checkpoint**: You have a complete human-readable specification tailored to your app type.
+
+---
+
+## Stage 3: Convert to Machine PRD (30-45 minutes)
+
+### Step 3.1: Create PROMPT.md
+
+This is the master file Ralph will read. Use this prompt:
+
+```
+Convert my specification documents into a PROMPT.md file for an AI coding agent.
+
+Context from my architecture classification:
+- Application type: [from Step 2.1]
+- Interface types: [from Step 2.1]
+- Persistence model: [from Step 2.1]
+- Deployment model: [from Step 2.1]
+
+Requirements for the PROMPT.md:
+1. Single file that contains everything the agent needs
+2. Tailored to the specific application type (not generic web app assumptions)
+3. Clear completion criteria with exact commands to verify
+4. Phased approach appropriate to this app type:
+   - Web apps: Foundation → Core → Integration → Polish
+   - Desktop apps: Foundation → Core UI → System Integration → Packaging
+   - CLI tools: Foundation → Commands → I/O Handling → Distribution
+   - Libraries: Foundation → Core API → Documentation → Publishing
+   - Adapt as needed for other types
+5. Binary pass/fail acceptance criteria for every feature
+6. Interface specifications appropriate to the app type
+7. Explicit constraints and safety rules
+8. Promise tags for completion signals
+
+Use this structure:
+
+# Project: [Name]
+
+## Objective
+[One sentence]
+
+## Application Type
+[Classification from Step 2.1]
+
+## Tech Stack
+[Exact versions]
+
+## Completion Criteria
+[Numbered list of verification commands appropriate to this app type]
+
+## Phase 1: Foundation
+[Setup tasks with acceptance criteria]
+
+## Phase 2: Core [Features/UI/Commands/API - varies by app type]
+[Each feature with binary acceptance]
+
+## Phase 3: [Integration/System/I/O - varies by app type]
+[External services, system integration, etc.]
+
+## Phase 4: [Polish/Packaging/Publishing - varies by app type]
+[Docs, distribution, optimization]
+
+## Constraints
+[Hard rules]
+
+## Abort Conditions
+[When to stop and signal]
+
+## Working Process
+[Step-by-step instructions for each iteration]
+
+Include the promise tags:
+- <promise>PROJECT_COMPLETE</promise> for full completion
+- <promise>PHASE_N_COMPLETE</promise> for phase completion
+- <promise>ABORT_BLOCKED</promise> for blocking issues
+
+Here are my spec documents:
+[Paste all your docs including architecture.md]
+```
+
+### Step 3.2: Create prd.json
+
+For granular progress tracking:
+
+```
+Create a prd.json file that tracks each feature as a separate item.
+
+Format:
+{
+  "project": "MyApp",
+  "features": [
+    {
+      "id": "unique-id",
+      "phase": 1,
+      "name": "Feature Name",
+      "description": "What it does",
+      "priority": 1,
+      "passes": false,
+      "acceptance": "Exact command or condition that proves completion",
+      "dependencies": ["other-feature-ids"]
+    }
+  ]
+}
+
+Order by phase, then by priority within phase.
+Include all features from my specification.
+Set all "passes" to false initially.
+```
+
+### Step 3.3: Create progress.txt Template
+
+Create an empty file with header:
+
+```
+# Progress Log
+# Format: [TIMESTAMP] [ITERATION] [STATUS] - [DETAILS]
+# Agent: Append only, never modify previous entries
+
+---
+
+```
+
+### Step 3.4: Validate Your PRD
+
+Final check prompt:
+
+```
+Review this PROMPT.md for an AI coding agent. Check for:
+
+1. AMBIGUITY: Any requirements that aren't binary pass/fail?
+2. MISSING COMMANDS: Every verification must have an exact command
+3. DEPENDENCIES: Are phases ordered correctly?
+4. COMPLETENESS: Can an agent build this without asking questions?
+5. SAFETY: Are there guardrails against destructive actions?
+
+List any issues found and suggest fixes.
+
+[Paste your PROMPT.md]
+```
+
+Fix any issues identified.
+
+**Checkpoint**: You have `PROMPT.md`, `prd.json`, and `progress.txt` ready.
+
+---
+
+## Stage 4: Project Scaffold Setup (15-30 minutes)
+
+### Step 4.1: Create Directory Structure
+
+Run these commands:
+
+```bash
+# Create project directory
+mkdir my-app && cd my-app
+
+# Initialize git (CRITICAL - Ralph uses git for memory)
+git init
+
+# Create core Ralph files
+touch PROMPT.md
+touch prd.json
+touch progress.txt
+
+# Create documentation directory
+mkdir -p docs
+
+# Create agent context directory (optional but recommended)
+mkdir -p agent_docs
+touch agent_docs/tech_stack.md
+touch agent_docs/code_patterns.md
+touch agent_docs/testing.md
+
+# Create Claude Code config (optional)
+touch CLAUDE.md
+```
+
+### Step 4.2: Populate Files
+
+Copy your generated content:
+- Paste PROMPT.md content
+- Paste prd.json content
+- Paste progress.txt template
+- Copy spec docs to `docs/`
+
+### Step 4.3: Create .gitignore
+
+```bash
+cat > .gitignore << 'EOF'
+node_modules/
+.env
+.env.local
+*.log
+dist/
+build/
+coverage/
+.DS_Store
+__pycache__/
+*.pyc
+.venv/
+EOF
+```
+
+### Step 4.4: Create CLAUDE.md (Optional but Recommended)
+
+This file gives Claude Code persistent instructions:
+
+```bash
+cat > CLAUDE.md << 'EOF'
+# Claude Code Instructions
+
+## Project Context
+Read PROMPT.md for full requirements.
+Read prd.json for feature tracking.
+Append progress to progress.txt after each significant change.
+
+## Working Rules
+1. Always run tests before committing
+2. Never commit failing code
+3. Update prd.json when features complete
+4. Use conventional commit messages
+5. Ask no questions - make reasonable decisions
+
+## Commands
+- Build: npm run build
+- Test: npm run test
+- Lint: npm run lint
+- All: npm run build && npm run test && npm run lint
+EOF
+```
+
+### Step 4.5: Initial Commit
+
+```bash
+git add .
+git commit -m "Initial project setup with Ralph configuration"
+```
+
+**Checkpoint**: Your project directory is ready for Ralph.
+
+---
+
+## Stage 5: Execute Phase 1 - Foundation (1-3 hours automated)
+
+### Step 5.1: Install Ralph Plugin
+
+In Claude Code:
+
+```
+/plugin marketplace add anthropics/claude-code
+/plugin install ralph-wiggum@claude-plugins-official
+```
+
+### Step 5.2: Start Phase 1 Loop
+
+```
+/ralph-wiggum:ralph-loop "Execute Phase 1 (Foundation) from PROMPT.md.
+
+Read PROMPT.md for full context.
+Read prd.json for feature tracking.
+
+Work on Phase 1 items only. For each item:
+1. Write tests first
+2. Implement the feature
+3. Verify tests pass
+4. Update prd.json (set passes=true)
+5. Commit with descriptive message
+6. Append progress to progress.txt
+
+Run verification after each feature:
+npm run build && npm run test && npm run lint
+
+When ALL Phase 1 features in prd.json have passes=true:
+Output <promise>PHASE_1_COMPLETE</promise>
+
+If blocked after 10 attempts on same feature:
+Document in progress.txt and output <promise>PHASE_1_BLOCKED</promise>" --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"
+```
+
+### Step 5.3: Monitor (Optional)
+
+While Ralph runs, you can monitor:
+
+```bash
+# Watch progress
+tail -f progress.txt
+
+# Watch git commits
+watch -n 10 'git log --oneline -10'
+
+# Check test status
+watch -n 30 'npm test 2>&1 | tail -20'
+```
+
+### Step 5.4: Handle Completion
+
+**If PHASE_1_COMPLETE:**
+```bash
+# Review what was built
+git log --oneline
+npm run test
+npm run build
+
+# Continue to Phase 2
+```
+
+**If PHASE_1_BLOCKED:**
+```bash
+# Check what blocked
+cat progress.txt | tail -50
+
+# Review the issue
+# Manually fix or adjust PROMPT.md
+# Restart Phase 1 with updated prompt
+```
+
+**Checkpoint**: Foundation is complete. You have a working project skeleton.
+
+---
+
+## Stage 6: Execute Remaining Phases (2-8 hours automated per phase)
+
+### Step 6.1: Phase 2 - Core Features
+
+```
+/ralph-wiggum:ralph-loop "Execute Phase 2 (Core Features) from PROMPT.md.
+
+Phase 1 is complete. Now implement Phase 2 features.
+
+Read PROMPT.md for requirements.
+Read prd.json for feature list and status.
+
+For each Phase 2 feature:
+1. Check dependencies are met (Phase 1 complete)
+2. Write comprehensive tests
+3. Implement feature
+4. Verify all tests pass
+5. Update prd.json
+6. Commit
+7. Log to progress.txt
+
+Verification command:
+npm run build && npm run test && npm run lint
+
+When ALL Phase 2 features pass:
+Output <promise>PHASE_2_COMPLETE</promise>
+
+If blocked: <promise>PHASE_2_BLOCKED</promise>" --max-iterations 50 --completion-promise "PHASE_2_COMPLETE"
+```
+
+### Step 6.2: Phase 3 - Integration
+
+```
+/ralph-wiggum:ralph-loop "Execute Phase 3 (Integration) from PROMPT.md.
+
+Phases 1-2 complete. Now implement Phase 3.
+
+Focus on:
+- External service integrations
+- Authentication/Authorization
+- Error handling
+- Logging
+
+For external services, use mocks in tests.
+Document any API keys needed in .env.example.
+
+When ALL Phase 3 features pass:
+Output <promise>PHASE_3_COMPLETE</promise>" --max-iterations 40 --completion-promise "PHASE_3_COMPLETE"
+```
+
+### Step 6.3: Phase 4 - Polish
+
+```
+/ralph-wiggum:ralph-loop "Execute Phase 4 (Polish) from PROMPT.md.
+
+Phases 1-3 complete. Final polish.
+
+Tasks:
+- Complete README.md with setup instructions
+- Add API documentation
+- Handle edge cases
+- Add input validation
+- Improve error messages
+- Add any missing tests (target >80% coverage)
+
+When done and all PROMPT.md completion criteria met:
+Output <promise>PROJECT_COMPLETE</promise>" --max-iterations 30 --completion-promise "PROJECT_COMPLETE"
+```
+
+### Step 6.4: Overnight Batch (Alternative)
+
+If you want all phases to run overnight:
+
+```bash
+#!/bin/bash
+# run-all-phases.sh
+
+echo "Starting full build: $(date)"
+
+# Phase 1
+claude -p '/ralph-wiggum:ralph-loop "Execute Phase 1..." --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"'
+
+# Phase 2
+claude -p '/ralph-wiggum:ralph-loop "Execute Phase 2..." --max-iterations 50 --completion-promise "PHASE_2_COMPLETE"'
+
+# Phase 3
+claude -p '/ralph-wiggum:ralph-loop "Execute Phase 3..." --max-iterations 40 --completion-promise "PHASE_3_COMPLETE"'
+
+# Phase 4
+claude -p '/ralph-wiggum:ralph-loop "Execute Phase 4..." --max-iterations 30 --completion-promise "PROJECT_COMPLETE"'
+
+echo "Build complete: $(date)"
+```
+
+Run before bed:
+```bash
+chmod +x run-all-phases.sh
+nohup ./run-all-phases.sh > build.log 2>&1 &
+```
+
+**Checkpoint**: All phases complete. Full application built.
+
+---
+
+## Stage 7: Review and Polish (1-2 hours manual)
+
+### Step 7.1: Full Verification
+
+```bash
+# Run all checks
+npm run build
+npm run test
+npm run lint
+
+# Check coverage
+npm run test -- --coverage
+
+# Start the app and test manually
+npm run dev
+```
+
+### Step 7.2: Code Review
+
+Review key files:
+
+```bash
+# See all files created
+find . -name "*.ts" -o -name "*.js" -o -name "*.tsx" | head -50
+
+# Review main entry point
+cat src/index.ts  # or equivalent
+
+# Review a core feature
+cat src/services/[main-service].ts
+
+# Check test quality
+cat tests/[main-test].test.ts
+```
+
+### Step 7.3: Git Cleanup
+
+```bash
+# See all Ralph commits
+git log --oneline
+
+# Optional: squash into logical commits
+git rebase -i HEAD~[number]
+
+# Or create a clean branch
+git checkout -b release/v1
+git merge --squash main
+git commit -m "v1.0.0 - Initial release"
+```
+
+### Step 7.4: Documentation Check
+
+Verify README.md contains:
+- [ ] Project description
+- [ ] Prerequisites
+- [ ] Installation steps
+- [ ] Environment setup (.env.example)
+- [ ] Running locally
+- [ ] Running tests
+- [ ] API documentation (or link to it)
+- [ ] Deployment instructions
+
+### Step 7.5: Security Scan
+
+```bash
+# Check for secrets
+git log -p | grep -i "password\|secret\|key\|token" | head -20
+
+# Run security audit
+npm audit  # or equivalent for your stack
+```
+
+### Step 7.6: Final Fixes
+
+If you find issues, you can run targeted Ralph loops:
+
+```
+/ralph-wiggum:ralph-loop "Fix the following issues:
+1. [Issue 1]
+2. [Issue 2]
+
+Run tests after each fix. Commit when green.
+Output <promise>FIXES_COMPLETE</promise> when done." --max-iterations 10 --completion-promise "FIXES_COMPLETE"
+```
+
+**Checkpoint**: Production-ready application.
+
+---
+
+## Quick Reference: Commands Cheat Sheet
+
+### Setup
+```bash
+mkdir my-app && cd my-app
+git init
+touch PROMPT.md prd.json progress.txt
+```
+
+### Ralph Plugin
+```
+/plugin install ralph-wiggum@claude-plugins-official
+/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N --completion-promise "TEXT"
+/ralph-wiggum:cancel-ralph
+```
+
+### Monitoring
+```bash
+tail -f progress.txt
+watch -n 10 'git log --oneline -5'
+```
+
+### Recovery
+```bash
+/ralph-wiggum:cancel-ralph
+git log --oneline -10
+git reset --hard HEAD~N
+```
+
+---
+
+## Quick Reference: Time Estimates
+
+| Stage | Human Time | Ralph Time |
+|-------|-----------|------------|
+| 1. Idea Dump | 15-30 min | - |
+| 2. Expand Spec | 30-60 min | - |
+| 3. Convert to PRD | 30-45 min | - |
+| 4. Setup Scaffold | 15-30 min | - |
+| 5. Phase 1 | 5 min | 1-3 hours |
+| 6. Phases 2-4 | 15 min | 3-12 hours |
+| 7. Review | 1-2 hours | - |
+| **Total Human** | **3-5 hours** | - |
+| **Total Ralph** | - | **4-15 hours** |
+
+---
+
+## Quick Reference: Prompts Library
+
+### Brain Dump Prompt
+```
+I have an app idea. I'm going to brain dump everything about it.
+Don't respond until I say "DONE". Just acknowledge each message.
+```
+
+### Structuring Prompt
+```
+Organize what I described into: PROBLEM, SOLUTION, USERS, CORE FEATURES, 
+NICE-TO-HAVE, TECH PREFERENCES, CONSTRAINTS, SIMILAR APPS.
+```
+
+### Feature Breakdown Prompt
+```
+For each feature, provide: User Story, Acceptance Criteria, Data Required,
+API Endpoints, UI Components. Make acceptance criteria binary pass/fail.
+```
+
+### Tech Stack Prompt
+```
+Recommend a tech stack with exact versions. Consider [preferences].
+Justify each choice.
+```
+
+### PROMPT.md Generation Prompt
+```
+Convert my specification into a PROMPT.md for an AI coding agent with:
+phased approach, binary acceptance criteria, promise tags, and safety rules.
+```
+
+### Phase Execution Prompt
+```
+Execute Phase N from PROMPT.md. Read prd.json for tracking.
+Write tests first, implement, verify, update prd.json, commit, log progress.
+Output <promise>PHASE_N_COMPLETE</promise> when done.
+```
+
+---
+
+## Troubleshooting Quick Fixes
+
+| Problem | Solution |
+|---------|----------|
+| Ralph stops early | Check completion promise text matches exactly |
+| Tests keep failing | Add "never commit failing code" to prompt |
+| Wrong direction | Add specific constraints to PROMPT.md |
+| Context too large | Break into smaller phases |
+| Costs too high | Reduce --max-iterations, use phases |
+| Loop infinite | Always set --max-iterations |
+
+---
+
+## Example: Complete Workflow
+
+**Idea**: "A todo app with user accounts and team sharing"
+
+**Stage 1 Output** (5 minutes):
+```
+PROBLEM: People need to manage tasks, existing apps are too complex
+SOLUTION: Simple todo app with team sharing
+USERS: Individuals, small teams
+CORE FEATURES: Create todos, mark complete, share lists, user accounts
+NICE-TO-HAVE: Due dates, labels, mobile app
+TECH: TypeScript, prefer simple
+```
+
+**Stage 2 Output** (20 minutes):
+- Architecture classification:
+  - App type: Web application (frontend + backend)
+  - Interfaces: REST API, WebSocket (for real-time sync)
+  - Persistence: Remote database (PostgreSQL)
+  - Deployment: Cloud hosted (Vercel + Railway)
+- 4 core features broken into 12 acceptance criteria
+- Tech stack: Node.js, Express, PostgreSQL, Prisma, Jest, React, Vite
+- 5 data models: User, Team, List, Todo, TeamMember
+- 15 API endpoints specified
+
+**Stage 3 Output** (15 minutes):
+- PROMPT.md: 200 lines with all phases (web app structure)
+- prd.json: 12 features with acceptance criteria
+
+**Stage 4** (10 minutes):
+- Directory created, files populated, initial commit
+
+**Stage 5-6** (overnight):
+- Phase 1: 45 minutes, 8 iterations
+- Phase 2: 3 hours, 24 iterations  
+- Phase 3: 2 hours, 18 iterations
+- Phase 4: 1 hour, 12 iterations
+- Total cost: ~$85
+
+**Stage 7** (1 hour):
+- All tests pass
+- 84% coverage
+- 3 minor fixes needed
+- README complete
+- Ready to deploy
+
+**Total human time**: ~2 hours
+**Total elapsed time**: ~10 hours (mostly overnight)
+**Total cost**: ~$90
+
+---
+
+## Example: Desktop App Workflow
+
+**Idea**: "A markdown note-taking app with local storage and vim keybindings"
+
+**Stage 1 Output** (5 minutes):
+```
+PROBLEM: Existing note apps are bloated or cloud-dependent
+SOLUTION: Fast local markdown editor with vim motions
+USERS: Developers, writers who know vim
+CORE FEATURES: Create/edit notes, vim keybindings, local file storage, search
+NICE-TO-HAVE: Plugins, sync, mobile companion
+TECH: Prefer Rust or TypeScript, must be fast
+```
+
+**Stage 2 Output** (25 minutes):
+- Architecture classification:
+  - App type: Desktop application (Tauri)
+  - Interfaces: IPC channels (Rust backend ↔ React frontend), File formats (markdown + metadata JSON)
+  - Persistence: File-based (markdown files in user directory)
+  - Deployment: Desktop installer (Windows, macOS, Linux)
+- 4 core features broken into 10 acceptance criteria
+- Tech stack: Tauri 2.0, Rust, React, TypeScript, CodeMirror 6, Vitest
+- 3 data structures: Note (file), NoteMetadata (index), AppConfig
+- 8 IPC channels specified, file format documented
+
+**Stage 3 Output** (15 minutes):
+- PROMPT.md: 180 lines with desktop-appropriate phases:
+  - Phase 1: Foundation (Tauri setup, file system, config)
+  - Phase 2: Core UI (editor, vim bindings, note list)
+  - Phase 3: System Integration (file watching, search indexing)
+  - Phase 4: Packaging (installers, auto-update, icons)
+- prd.json: 10 features tracked
+
+**Stage 4** (10 minutes):
+- Tauri project initialized, files populated, initial commit
+
+**Stage 5-6** (overnight):
+- Phase 1: 30 minutes, 6 iterations
+- Phase 2: 4 hours, 32 iterations (vim bindings complex)
+- Phase 3: 2 hours, 16 iterations
+- Phase 4: 1.5 hours, 14 iterations
+- Total cost: ~$120
+
+**Stage 7** (1.5 hours):
+- All tests pass
+- App launches on all 3 platforms
+- Vim bindings verified manually
+- Installers build successfully
+
+**Total human time**: ~2.5 hours
+**Total elapsed time**: ~11 hours
+**Total cost**: ~$130
+
+---
+
+*Guide version: 1.0*
+*Works with: Claude Code + Ralph Wiggum plugin*
+*Last updated: January 2026*