ralph-vibe/ralph-implementation-instructions.md

# Ralph PRD Generator: Implementation Instructions

## Overview

You will use the Ralph Method to build the Ralph PRD Generator itself. This is bootstrapping - using the technique to build the tool that automates the technique.

**Time estimate**: 2-4 hours setup, 8-16 hours autonomous Ralph execution
**Cost estimate**: $150-300 in API costs

---

## Prerequisites

Before starting, ensure you have:

- [ ] Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
- [ ] Ralph Wiggum plugin installed (instructions below)
- [ ] Claude API key with sufficient credits (~$300 recommended)
- [ ] Perplexity API key (for testing the app, not for building it)
- [ ] Node.js 20+ installed
- [ ] Git installed
- [ ] jq installed (required by Ralph plugin on some systems)

---

## Step 1: Create Project Directory

```bash
mkdir ralph-vibe
cd ralph-vibe
git init
```

---

## Step 2: Download the Specification Files

From the Claude conversation, download:

1. `ralph-prd-generator-spec.md` → save as `ralph-vibe/PROMPT.md`
2. `ralph-method-framework.md` → save as `ralph-vibe/docs/framework.md`
3. `ralph-method-step-by-step-guide.md` → save as `ralph-vibe/docs/guide.md`

```bash
mkdir -p docs
# Then manually save the downloaded files to these locations
```

---

## Step 3: Create Supporting Files

Run each of these commands in your terminal:

### 3.1 Create prd.json

```bash
cat > prd.json << 'ENDJSON'
{
  "project": "ralph-prd-generator",
  "version": "1.0.0",
  "features": [
    {
      "id": "config-management",
      "phase": 1,
      "name": "API Key Management",
      "description": "Store and retrieve API keys securely",
      "priority": 1,
      "passes": false,
      "acceptance": "ralph-vibe init stores keys and ralph-vibe new fails gracefully without keys"
    },
    {
      "id": "cli-framework",
      "phase": 1,
      "name": "CLI Framework",
      "description": "Commander.js setup with all commands stubbed",
      "priority": 2,
      "passes": false,
      "acceptance": "ralph-vibe --help shows all commands, ralph-vibe init/new/validate/research exist"
    },
    {
      "id": "claude-client",
      "phase": 2,
      "name": "Claude API Client",
      "description": "Anthropic SDK integration with retry logic",
      "priority": 1,
      "passes": false,
      "acceptance": "Can send prompt to Claude and receive response, retries on failure"
    },
    {
      "id": "perplexity-client",
      "phase": 2,
      "name": "Perplexity API Client",
      "description": "Perplexity REST API integration",
      "priority": 2,
      "passes": false,
      "acceptance": "Can search Perplexity and parse response with sources"
    },
    {
      "id": "architecture-classification",
      "phase": 2,
      "name": "Architecture Classification",
      "description": "Claude prompt for classifying app type",
      "priority": 3,
      "passes": false,
      "acceptance": "Given idea text, returns valid Architecture JSON"
    },
    {
      "id": "research-queries",
      "phase": 2,
      "name": "Research Query Generation",
      "description": "Generate Perplexity queries from architecture",
      "priority": 4,
      "passes": false,
      "acceptance": "Given architecture, generates 4-6 relevant search queries"
    },
    {
      "id": "spec-generation",
      "phase": 3,
      "name": "Specification Generation",
      "description": "Generate features, data models, interfaces from idea plus research",
      "priority": 1,
      "passes": false,
      "acceptance": "Produces valid Specification object with all required fields"
    },
    {
      "id": "prd-generation",
      "phase": 3,
      "name": "PRD Generation",
      "description": "Generate PROMPT.md, prd.json, GUIDE.md",
      "priority": 2,
      "passes": false,
      "acceptance": "Generated PROMPT.md contains all required sections and promise tags"
    },
    {
      "id": "scaffold-generation",
      "phase": 3,
      "name": "Project Scaffold",
      "description": "Create directory structure and all files",
      "priority": 3,
      "passes": false,
      "acceptance": "ralph-vibe new test-app creates complete directory with all files"
    },
    {
      "id": "interactive-flow",
      "phase": 3,
      "name": "Interactive Prompts",
      "description": "Inquirer.js prompts for user confirmation",
      "priority": 4,
      "passes": false,
      "acceptance": "User can confirm or modify architecture classification interactively"
    },
    {
      "id": "validation-command",
      "phase": 4,
      "name": "Validate Command",
      "description": "Validate existing PROMPT.md files",
      "priority": 1,
      "passes": false,
      "acceptance": "ralph-vibe validate ./PROMPT.md reports issues or confirms valid"
    },
    {
      "id": "research-command",
      "phase": 4,
      "name": "Standalone Research",
      "description": "Research a topic without full generation",
      "priority": 2,
      "passes": false,
      "acceptance": "ralph-vibe research topic outputs formatted research"
    },
    {
      "id": "dry-run",
      "phase": 4,
      "name": "Dry Run Mode",
      "description": "Show what would be generated without writing",
      "priority": 3,
      "passes": false,
      "acceptance": "The --dry-run flag shows output without creating files"
    },
    {
      "id": "documentation",
      "phase": 4,
      "name": "Documentation",
      "description": "README, help text, examples",
      "priority": 4,
      "passes": false,
      "acceptance": "README.md covers all commands, examples directory exists"
    },
    {
      "id": "packaging",
      "phase": 4,
      "name": "npm Packaging",
      "description": "Package ready for npm publish",
      "priority": 5,
      "passes": false,
      "acceptance": "npm pack succeeds, npm publish --dry-run succeeds"
    }
  ]
}
ENDJSON
```

### 3.2 Create progress.txt

```bash
cat > progress.txt << 'ENDFILE'
# Progress Log - Ralph PRD Generator
# Format: [TIMESTAMP] [ITERATION] [STATUS] - [DETAILS]
# Agent: Append only, never modify previous entries

---

ENDFILE
```

### 3.3 Create CLAUDE.md

```bash
cat > CLAUDE.md << 'ENDFILE'
# Claude Code Configuration

## Project Context

This is the Ralph PRD Generator - a CLI tool that generates Ralph Method project scaffolds.

Read PROMPT.md for full requirements.
Read prd.json for feature tracking.
Append progress to progress.txt after each significant change.

## Key Files

- PROMPT.md: Full specification - this is your primary reference
- prd.json: Feature tracking with acceptance criteria
- progress.txt: Append-only progress log
- docs/framework.md: Ralph Method framework reference
- docs/guide.md: Step-by-step guide reference

## Tech Stack

- TypeScript with strict mode
- Node.js 20+
- Commander.js for CLI
- Inquirer.js for prompts
- Anthropic SDK for Claude
- Native fetch for Perplexity
- Vitest for testing
- tsup for building

## Working Rules

1. Always run tests before committing
2. Never commit failing code
3. Update prd.json when features complete by setting passes to true
4. Use conventional commit messages
5. Make reasonable decisions - do not ask questions

## Commands

- Build: npm run build
- Test: npm run test
- Lint: npm run lint
- All: npm run build && npm run test && npm run lint
- Dev: npm run dev

## Directory Structure

src/
  index.ts           # CLI entry point
  commands/          # Command handlers
    init.ts
    new.ts
    validate.ts
    research.ts
  clients/           # API clients
    claude.ts
    perplexity.ts
  generators/        # Generation logic
    architecture.ts
    specification.ts
    prd.ts
    scaffold.ts
  prompts/           # Prompt templates
    templates.ts
  types/             # TypeScript types
    index.ts
  utils/             # Utilities
    config.ts
    files.ts
    logger.ts

## API Keys for Testing

During development, use environment variables:
- CLAUDE_API_KEY
- PERPLEXITY_API_KEY

Never commit real keys. Use .env.local which is gitignored.
ENDFILE
```

### 3.4 Create .gitignore

```bash
cat > .gitignore << 'ENDFILE'
node_modules/
dist/
.env
.env.local
*.log
coverage/
.DS_Store
*.tgz
RALPH_TASK.md
phase*-prompt.txt
ENDFILE
```

### 3.5 Create package.json

```bash
cat > package.json << 'ENDJSON'
{
  "name": "ralph-vibe",
  "version": "0.1.0",
  "description": "Generate Ralph Method project scaffolds with AI-powered research",
  "type": "module",
  "bin": {
    "ralph-vibe": "./dist/index.js"
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm --dts",
    "dev": "tsup src/index.ts --format esm --watch",
    "test": "vitest run",
    "test:watch": "vitest",
    "lint": "eslint src --ext .ts",
    "typecheck": "tsc --noEmit",
    "prepublishOnly": "npm run build && npm run test && npm run lint"
  },
  "keywords": ["cli", "ai", "claude", "vibe-coding", "ralph-method"],
  "author": "",
  "license": "MIT",
  "engines": {
    "node": ">=20.0.0"
  }
}
ENDJSON
```

---

## Step 4: Create Phase Prompt Files

Create separate files for each phase prompt. This avoids shell escaping issues entirely.

### 4.1 Phase 1 Prompt

```bash
cat > phase1-prompt.txt << 'ENDPROMPT'
Execute Phase 1 - Foundation from PROMPT.md.

You are building the Ralph PRD Generator CLI tool.

Read PROMPT.md for full specification.
Read prd.json for feature tracking.
Read CLAUDE.md for project configuration.

Phase 1 tasks:
1. Set up TypeScript project with all dependencies
2. Configure tsup, vitest, eslint
3. Implement CLI framework with Commander.js
4. Implement config management for API key storage
5. Create basic project structure
6. Write tests for config and CLI

For each feature:
1. Write tests first
2. Implement the feature
3. Run: npm run build && npm run test && npm run lint
4. If all pass, update prd.json by setting passes to true for completed features
5. Commit with descriptive message
6. Append progress to progress.txt

When ALL Phase 1 features in prd.json have passes set to true:
Output <promise>PHASE_1_COMPLETE</promise>

If blocked after 10 attempts on same issue:
Document in progress.txt and output <promise>PHASE_1_BLOCKED</promise>
ENDPROMPT
```

### 4.2 Phase 2 Prompt

```bash
cat > phase2-prompt.txt << 'ENDPROMPT'
Execute Phase 2 - Core API Integration from PROMPT.md.

Phase 1 is complete. Now implement Phase 2.

Read PROMPT.md for API specifications.
Read prd.json for Phase 2 features.

Phase 2 tasks:
1. Claude API client with Anthropic SDK
2. Perplexity API client with fetch
3. Architecture classification prompt and parser
4. Research query generation
5. Tests for all API clients

API Integration notes:
- Use environment variables for API keys during testing
- Implement retry logic with 3 attempts and exponential backoff
- Handle rate limits gracefully
- Parse JSON responses safely

For each feature:
1. Write tests first using mocked API calls
2. Implement the feature
3. Verify: npm run build && npm run test && npm run lint
4. Update prd.json when feature passes
5. Commit and log progress

When ALL Phase 2 features pass:
Output <promise>PHASE_2_COMPLETE</promise>

If blocked:
Output <promise>PHASE_2_BLOCKED</promise>
ENDPROMPT
```

### 4.3 Phase 3 Prompt

```bash
cat > phase3-prompt.txt << 'ENDPROMPT'
Execute Phase 3 - Generation Pipeline from PROMPT.md.

Phases 1-2 complete. Now implement the core generation pipeline.

Phase 3 tasks:
1. Specification generation from idea plus research
2. PRD generation including PROMPT.md, prd.json, GUIDE.md
3. Project scaffold creation
4. Interactive prompts with Inquirer.js
5. Full pipeline integration from idea to scaffold

Key requirements:
- Generated PROMPT.md must follow Ralph Method structure
- Generated files must be app-type aware for web, desktop, CLI, and other types
- prd.json must have all features with passes set to false
- GUIDE.md must be personalized to the project
- User must be able to confirm or override classifications

Test with a sample idea:
A CLI tool that converts markdown to PDF with syntax highlighting

When ALL Phase 3 features pass:
Output <promise>PHASE_3_COMPLETE</promise>

If blocked:
Output <promise>PHASE_3_BLOCKED</promise>
ENDPROMPT
```

### 4.4 Phase 4 Prompt

```bash
cat > phase4-prompt.txt << 'ENDPROMPT'
Execute Phase 4 - Polish from PROMPT.md.

Phases 1-3 complete. Final polish and packaging.

Phase 4 tasks:
1. Validate command to check existing PROMPT.md files
2. Standalone research command
3. Dry-run mode with --dry-run flag
4. Comprehensive documentation in README.md
5. npm packaging with npm pack and npm publish --dry-run
6. Examples directory with sample outputs

Documentation must include:
- Installation instructions
- All commands with examples
- Environment variable configuration
- Troubleshooting section

When ALL Phase 4 features pass AND all completion criteria from PROMPT.md are met:
Output <promise>PROJECT_COMPLETE</promise>

If blocked:
Output <promise>PHASE_4_BLOCKED</promise>
ENDPROMPT
```

---

## Step 5: Initial Commit

```bash
git add .
git commit -m "Initial Ralph scaffold for ralph-vibe"
```

---

## Step 6: Install Ralph Wiggum Plugin

Open Claude Code:

```bash
claude
```

Inside Claude Code, run:

```
/plugin marketplace add anthropics/claude-code
/plugin install ralph-wiggum@claude-plugins-official
```

---

## Step 7: Execute Phase 1

**Option A: Using the Ralph Plugin**

In Claude Code:

```
/ralph-wiggum:ralph-loop "$(cat phase1-prompt.txt)" --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"
```

**Option B: Using Raw Bash Loop**

If the plugin has issues, use this instead in your terminal:

```bash
MAX=30
for i in $(seq 1 $MAX); do
  echo "=== Iteration $i of $MAX ==="
  cat phase1-prompt.txt | claude --print
  
  # Check for completion
  if grep -rq "PHASE_1_COMPLETE" . 2>/dev/null; then
    echo "Phase 1 complete at iteration $i"
    break
  fi
  
  # Check for blocked
  if grep -rq "PHASE_1_BLOCKED" . 2>/dev/null; then
    echo "Phase 1 blocked. Check progress.txt"
    break
  fi
  
  # Commit progress
  git add -A
  git diff --cached --quiet || git commit -m "Ralph Phase 1 iteration $i"
done
```

### Verify Phase 1

```bash
npm run build
npm run test
./dist/index.js --help
# Should show help text with init, new, validate, research commands
```

---

## Step 8: Execute Phase 2

**Option A: Plugin**
```
/ralph-wiggum:ralph-loop "$(cat phase2-prompt.txt)" --max-iterations 40 --completion-promise "PHASE_2_COMPLETE"
```

**Option B: Bash Loop**
```bash
MAX=40
for i in $(seq 1 $MAX); do
  echo "=== Iteration $i of $MAX ==="
  cat phase2-prompt.txt | claude --print
  if grep -rq "PHASE_2_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
  if grep -rq "PHASE_2_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
  git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 2 iteration $i"
done
```

---

## Step 9: Execute Phase 3

**Option A: Plugin**
```
/ralph-wiggum:ralph-loop "$(cat phase3-prompt.txt)" --max-iterations 50 --completion-promise "PHASE_3_COMPLETE"
```

**Option B: Bash Loop**
```bash
MAX=50
for i in $(seq 1 $MAX); do
  echo "=== Iteration $i of $MAX ==="
  cat phase3-prompt.txt | claude --print
  if grep -rq "PHASE_3_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
  if grep -rq "PHASE_3_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
  git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 3 iteration $i"
done
```

---

## Step 10: Execute Phase 4

**Option A: Plugin**
```
/ralph-wiggum:ralph-loop "$(cat phase4-prompt.txt)" --max-iterations 30 --completion-promise "PROJECT_COMPLETE"
```

**Option B: Bash Loop**
```bash
MAX=30
for i in $(seq 1 $MAX); do
  echo "=== Iteration $i of $MAX ==="
  cat phase4-prompt.txt | claude --print
  if grep -rq "PROJECT_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
  if grep -rq "PHASE_4_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
  git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 4 iteration $i"
done
```

---

## Step 11: Final Verification

```bash
# Build and test
npm run build
npm run test
npm run lint

# Set up API keys for testing
export CLAUDE_API_KEY="your-key"
export PERPLEXITY_API_KEY="your-key"

# Test initialization
./dist/index.js init

# Test with a real idea
echo "A CLI tool that converts markdown to PDF with syntax highlighting" > test-idea.txt
./dist/index.js new test-project --idea-file ./test-idea.txt

# Check output
ls -la test-project/
cat test-project/PROMPT.md
cat test-project/GUIDE.md

# Validate the generated PRD
./dist/index.js validate ./test-project/PROMPT.md

# Test research command
./dist/index.js research "Tauri 2.0 best practices 2026"
```

---

## Step 12: Git Cleanup

```bash
# See all commits
git log --oneline

# Optional: squash into logical commits
git rebase -i HEAD~N

# Suggested structure:
# feat: Phase 1 - CLI foundation and config
# feat: Phase 2 - Claude and Perplexity integration
# feat: Phase 3 - Generation pipeline
# feat: Phase 4 - Polish and packaging
```

---

## Step 13: Publish

```bash
npm run prepublishOnly
npm publish
```

---

## Overnight Batch Run

To run all phases unattended:

```bash
cat > run-all.sh << 'ENDSCRIPT'
#!/bin/bash
set -e

LOG="build-$(date +%Y%m%d-%H%M).log"
echo "Starting build: $(date)" | tee "$LOG"

run_phase() {
  local phase=$1
  local max=$2
  local complete=$3
  local blocked=$4
  
  echo "=== Phase $phase ===" | tee -a "$LOG"
  
  for i in $(seq 1 $max); do
    echo "--- Iteration $i of $max ---" | tee -a "$LOG"
    cat "phase${phase}-prompt.txt" | claude --print 2>&1 | tee -a "$LOG"
    
    if grep -rq "$complete" . 2>/dev/null; then
      echo "Phase $phase complete" | tee -a "$LOG"
      git add -A && git commit -m "Phase $phase complete" --allow-empty
      return 0
    fi
    
    if grep -rq "$blocked" . 2>/dev/null; then
      echo "Phase $phase blocked" | tee -a "$LOG"
      return 1
    fi
    
    git add -A && git diff --cached --quiet || git commit -m "Ralph Phase $phase iteration $i"
  done
  
  echo "Phase $phase max iterations reached" | tee -a "$LOG"
  return 1
}

run_phase 1 30 "PHASE_1_COMPLETE" "PHASE_1_BLOCKED"
run_phase 2 40 "PHASE_2_COMPLETE" "PHASE_2_BLOCKED"
run_phase 3 50 "PHASE_3_COMPLETE" "PHASE_3_BLOCKED"
run_phase 4 30 "PROJECT_COMPLETE" "PHASE_4_BLOCKED"

echo "Build complete: $(date)" | tee -a "$LOG"
ENDSCRIPT

chmod +x run-all.sh
nohup ./run-all.sh > overnight.log 2>&1 &
echo "Running in background. Check overnight.log for progress."
```

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Plugin shell errors | Use the bash loop method instead |
| Completion not detected | Check that promise tags are output without the angle brackets being escaped |
| API rate limits | Add sleep 2 between iterations in the bash loop |
| Tests fail on API calls | Ensure all API calls are mocked in tests |
| TypeScript errors | Run npm run typecheck to see all errors |
| Phase blocked | Check progress.txt, fix manually, restart phase |

---

## Summary Checklist

- [ ] Created ralph-vibe directory
- [ ] Downloaded and placed PROMPT.md
- [ ] Created prd.json
- [ ] Created progress.txt
- [ ] Created CLAUDE.md
- [ ] Created .gitignore
- [ ] Created package.json
- [ ] Created phase1-prompt.txt
- [ ] Created phase2-prompt.txt
- [ ] Created phase3-prompt.txt
- [ ] Created phase4-prompt.txt
- [ ] Initial git commit
- [ ] Installed Ralph plugin or using bash loop
- [ ] Phase 1 complete - ralph-vibe --help works
- [ ] Phase 2 complete - API clients work
- [ ] Phase 3 complete - ralph-vibe new works
- [ ] Phase 4 complete - all features work
- [ ] Final verification passed
- [ ] Published to npm

---

*Implementation Guide Version: 2.0*
*Shell-safe prompts using file-based approach*