Files

Debian 688cfe57ed Initial Ralph scaffold for ralph-vibe

2026-01-10 11:59:27 +00:00

24 KiB

Raw Blame History

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:

# 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

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:

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

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:

# 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:

# Review what was built
git log --oneline
npm run test
npm run build

# Continue to Phase 2

If PHASE_1_BLOCKED:

# 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:

#!/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:

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

# 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:

# 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

# 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

# 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

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

tail -f progress.txt
watch -n 10 'git log --oneline -5'

Recovery

/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"