ralph-vibe/PROMPT.md

Project: Ralph PRD Generator

Objective

A CLI/TUI application that takes a user's app idea and generates a complete, tailored Ralph Method project scaffold with research-backed best practices, ready for autonomous vibe coding.

---

Application Type

CLI tool with optional TUI (terminal user interface)

Architecture

• Interface types: CLI commands, interactive prompts, file output
• Persistence: File-based (output project folder), optional config file (~/.ralph-generator/config.json)
• Deployment: Package registry (npm) + standalone binary

Tech Stack

• Language: TypeScript
• Runtime: Node.js 20+
• CLI Framework: Commander.js or oclif
• TUI: Inquirer.js for prompts, ora for spinners, chalk for colors
• API Clients: Anthropic SDK, Perplexity API (REST)
• Testing: Vitest
• Build: tsup (for CLI bundling)
• Distribution: npm package + pkg for standalone binaries

---

User Flow

┌─────────────────────────────────────────────────────────────────────┐
│                         USER JOURNEY                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  1. SETUP (one-time)                                                │
│     $ ralph-gen init                                                │
│     → Prompts for Claude API key                                    │
│     → Prompts for Perplexity API key                                │
│     → Saves to ~/.ralph-generator/config.json                       │
│                                                                      │
│  2. START NEW PROJECT                                               │
│     $ ralph-gen new my-app                                          │
│     → Creates ./my-app directory                                    │
│     → Enters interactive mode                                       │
│                                                                      │
│  3. BRAIN DUMP                                                      │
│     "Describe your app idea (press Enter twice to finish):"        │
│     → User types freeform description                               │
│     → Can also pass --idea-file ./idea.txt                         │
│                                                                      │
│  4. CLASSIFICATION (Claude)                                         │
│     → Claude analyzes idea                                          │
│     → Determines: app type, interfaces, persistence, deployment    │
│     → User confirms or adjusts                                      │
│                                                                      │
│  5. RESEARCH (Perplexity)                                           │
│     → Queries best practices for identified stack                   │
│     → Queries common pitfalls                                       │
│     → Queries current library recommendations                       │
│     → Queries testing approaches for this app type                  │
│     → Saves findings to docs/research-notes.md                     │
│                                                                      │
│  6. SPECIFICATION (Claude)                                          │
│     → Generates feature breakdown with acceptance criteria          │
│     → Generates data model specification                            │
│     → Generates interface contracts (API/IPC/CLI as appropriate)   │
│     → Incorporates Perplexity research findings                    │
│                                                                      │
│  7. PRD GENERATION (Claude)                                         │
│     → Generates PROMPT.md tailored to app type                     │
│     → Generates prd.json with all features                         │
│     → Generates progress.txt initialized                           │
│     → Generates GUIDE.md - personalized step-by-step               │
│                                                                      │
│  8. SCAFFOLD                                                        │
│     → Creates project directory structure                           │
│     → Writes all generated files                                    │
│     → Initializes git                                               │
│     → Makes initial commit                                          │
│                                                                      │
│  9. OUTPUT                                                          │
│     ./my-app/                                                       │
│     ├── PROMPT.md           # Main Ralph prompt                    │
│     ├── prd.json            # Feature tracking                     │
│     ├── progress.txt        # Progress log                         │
│     ├── GUIDE.md            # Personalized step-by-step            │
│     ├── CLAUDE.md           # Claude Code config                   │
│     ├── docs/                                                       │
│     │   ├── idea-dump.md                                           │
│     │   ├── architecture.md                                        │
│     │   ├── features.md                                            │
│     │   ├── tech-stack.md                                          │
│     │   ├── data-models.md                                         │
│     │   ├── interfaces.md                                          │
│     │   └── research-notes.md                                      │
│     ├── agent_docs/                                                 │
│     │   ├── tech_stack.md                                          │
│     │   ├── code_patterns.md                                       │
│     │   └── testing.md                                             │
│     ├── .gitignore                                                  │
│     └── README.md           # Generated setup instructions         │
│                                                                      │
│  10. NEXT STEPS                                                     │
│      "Your project is ready! Next steps:"                          │
│      "  cd my-app"                                                  │
│      "  Open in Claude Code"                                        │
│      "  Follow GUIDE.md or run:"                                   │
│      "  /ralph-wiggum:ralph-loop \"$(cat PROMPT.md)\" ..."        │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

---

Commands

ralph-gen init

Configure API keys.

Options:
  --claude-key <key>      Set Claude API key directly
  --perplexity-key <key>  Set Perplexity API key directly
  --reset                 Clear existing configuration

ralph-gen new <project-name>

Create a new project.

Options:
  --idea-file <path>      Read idea from file instead of interactive
  --output-dir <path>     Output directory (default: ./<project-name>)
  --skip-research         Skip Perplexity research phase
  --skip-confirm          Don't ask for confirmation at each stage
  --verbose               Show detailed progress
  --dry-run               Show what would be generated without writing files

ralph-gen research <topic>

Standalone research command.

$ ralph-gen research "Tauri 2.0 best practices"
→ Outputs research findings to stdout or file

ralph-gen validate <path>

Validate an existing PROMPT.md file.

$ ralph-gen validate ./my-app/PROMPT.md
→ Checks for ambiguity, missing commands, etc.
→ Suggests improvements

---

Core Features

Feature 1: API Key Management

Description: Securely store and retrieve API keys for Claude and Perplexity.

Acceptance Criteria:

• Keys stored in ~/.ralph-generator/config.json
• File permissions set to 600 (user read/write only)
• Keys can be overridden via environment variables (CLAUDE_API_KEY, PERPLEXITY_API_KEY)
• init command validates keys work before saving
• Clear error messages if keys invalid or missing

Feature 2: Idea Input

Description: Accept freeform app idea from user.

Acceptance Criteria:

• Interactive multiline input with clear instructions
• File input via --idea-file flag
• Minimum 50 characters required
• Saves raw input to docs/idea-dump.md

Feature 3: Architecture Classification

Description: Use Claude to classify the app type and determine appropriate architecture.

Acceptance Criteria:

• Correctly identifies: Web app, Desktop app, CLI, Library, Mobile, Script
• Determines appropriate interface types for the app type
• Determines persistence model
• Determines deployment model
• User can confirm or override each classification
• Saves classification to docs/architecture.md

Feature 4: Best Practices Research

Description: Use Perplexity to research current best practices for the identified stack.

Acceptance Criteria:

• Queries constructed based on app type and tech stack
• Minimum 4 research queries executed:
  1. "[stack] best practices [year]"
  2. "[stack] common mistakes pitfalls"
  3. "[stack] recommended libraries [year]"
  4. "[stack] testing approach"
• Results parsed and formatted
• Saved to docs/research-notes.md
• Research findings passed to Claude for PRD generation

Research Query Templates:

For Web Apps (Node.js + Express):
- "Node.js Express project structure best practices 2026"
- "Express.js common security mistakes to avoid"
- "Node.js backend recommended libraries 2026 authentication database"
- "Node.js Express testing Jest Vitest comparison 2026"

For Desktop Apps (Tauri):
- "Tauri 2.0 project structure best practices"
- "Tauri Rust TypeScript common mistakes"
- "Tauri recommended plugins file handling"
- "Tauri application testing approaches"

For CLI Tools:
- "[language] CLI tool best practices argument parsing"
- "CLI tool UX common mistakes"
- "[language] CLI framework comparison 2026"
- "CLI tool testing strategies"

Feature 5: Specification Generation

Description: Use Claude to generate detailed specifications from the idea and research.

Acceptance Criteria:

• Generates feature breakdown with user stories and acceptance criteria
• Generates data model specification appropriate to persistence type
• Generates interface contracts appropriate to app type
• Incorporates findings from Perplexity research
• All acceptance criteria are binary (pass/fail)
• Saves to respective files in docs/

Feature 6: PRD Generation

Description: Use Claude to generate the complete PROMPT.md and supporting files.

Acceptance Criteria:

• PROMPT.md follows Ralph Method framework structure
• Phases appropriate to app type (not generic web app template)
• Includes all completion criteria with exact verification commands
• Includes promise tags for Ralph loop
• prd.json includes all features with passes: false
• progress.txt initialized with header

Feature 7: Personalized Guide Generation

Description: Generate a step-by-step GUIDE.md tailored to this specific project.

Acceptance Criteria:

• Guide reflects the specific app type and tech stack
• Includes exact commands for this project (not generic npm commands)
• References the specific phases from PROMPT.md
• Includes time estimates based on complexity
• Includes cost estimates based on feature count

Feature 8: Project Scaffold

Description: Create the complete project directory structure.

Acceptance Criteria:

• Creates all directories and files
• Initializes git repository
• Creates appropriate .gitignore for the tech stack
• Makes initial commit with message "Initial Ralph scaffold"
• Sets correct file permissions

Feature 9: Validation

Description: Validate existing PROMPT.md files for Ralph compatibility.

Acceptance Criteria:

• Detects ambiguous requirements (non-binary criteria)
• Detects missing verification commands
• Detects missing promise tags
• Detects phase dependency issues
• Outputs specific suggestions for fixes
• Exit code 0 if valid, 1 if issues found

---

Technical Specifications

Claude API Integration

interface ClaudeClient {
  analyze(prompt: string): Promise<string>;
  generateSpec(idea: string, architecture: Architecture, research: Research): Promise<Specification>;
  generatePRD(spec: Specification): Promise<PRDOutput>;
  validate(prompt: string): Promise<ValidationResult>;
}

// Use Claude claude-sonnet-4-20250514 for speed/cost balance
// Use Claude claude-opus-4-20250514 for complex analysis if user opts in

Perplexity API Integration

interface PerplexityClient {
  search(query: string): Promise<SearchResult>;
  researchStack(stack: TechStack): Promise<Research>;
}

interface SearchResult {
  answer: string;
  sources: Source[];
  citations: string[];
}

// Use sonar-pro model for comprehensive research
// Rate limit: respect API limits, add retry logic

Data Types

interface Architecture {
  appType: 'web' | 'desktop' | 'cli' | 'library' | 'mobile' | 'script' | 'other';
  interfaces: InterfaceType[];
  persistence: PersistenceType;
  deployment: DeploymentType;
}

interface Specification {
  features: Feature[];
  dataModels: DataModel[];
  interfaces: InterfaceContract[];
  techStack: TechStack;
}

interface PRDOutput {
  promptMd: string;
  prdJson: PRDJson;
  progressTxt: string;
  guideMd: string;
  claudeMd: string;
}

Error Handling

• API failures: Retry 3 times with exponential backoff
• Invalid keys: Clear error message with instructions to run init
• Rate limits: Wait and retry with user notification
• Network errors: Offer to save progress and resume later

---

Completion Criteria

1. npm run build exits 0
2. npm run test exits 0 with >80% coverage
3. npm run lint exits 0
4. ralph-gen --help displays all commands
5. ralph-gen init successfully stores and validates keys
6. ralph-gen new test-app --idea-file ./test-idea.txt generates complete scaffold
7. Generated PROMPT.md passes ralph-gen validate
8. All generated files are syntactically valid (JSON parses, Markdown renders)
9. README.md documents all commands and options
10. Package publishes to npm successfully (dry-run)

Output <promise>PROJECT_COMPLETE</promise> when all criteria met.

---

Phase 1: Foundation

• Project setup with TypeScript, tsup, vitest
• CLI framework with Commander.js
• Config file management (~/.ralph-generator/)
• API key storage with validation
• Basic error handling framework
• Logging with verbosity levels

Acceptance: ralph-gen init works, ralph-gen --help displays commands

Phase 2: Core API Integration

• Claude API client with retry logic
• Perplexity API client with retry logic
• Architecture classification prompt
• Research query generation
• Specification generation prompt
• PRD generation prompt

Acceptance: Can classify an idea and research a tech stack

Phase 3: Generation Pipeline

• Full pipeline: idea → classification → research → spec → PRD
• PROMPT.md generation with app-type awareness
• prd.json generation
• GUIDE.md generation (personalized)
• All supporting files generation
• Interactive confirmation at each stage

Acceptance: ralph-gen new test-app produces complete valid scaffold

Phase 4: Polish

• Validation command
• Standalone research command
• Dry-run mode
• Resume capability (save/load progress)
• Comprehensive error messages
• Documentation
• npm packaging
• Standalone binary build (pkg)

Acceptance: All completion criteria met, package ready to publish

---

Constraints

• All API calls must have timeout and retry logic
• API keys must never be logged or included in error messages
• All file writes must be atomic (write to temp, then rename)
• Must work offline for validation command (no API needed)
• Must handle Ctrl+C gracefully at any point
• Generated files must be valid (JSON parseable, Markdown renderable)

Abort Conditions

Output <promise>ABORT_BLOCKED</promise> if:

• Cannot authenticate with either API after configuration
• API response format changes breaking parsing
• File system permissions prevent writing to output directory

---

Appendix: Prompt Templates

Architecture Classification Prompt

Analyze this app idea and classify its architecture:

<idea>
{user_idea}
</idea>

Determine:

1. APPLICATION TYPE (choose one):
   - web: Frontend + backend web application
   - desktop: Native or Electron/Tauri desktop application
   - cli: Command-line tool
   - library: Reusable package/module
   - mobile: iOS/Android application
   - script: Automation/utility script
   - other: Specify

2. INTERFACE TYPES (choose all that apply):
   - rest_api: RESTful HTTP endpoints
   - graphql: GraphQL API
   - ipc: Inter-process communication (desktop)
   - module: Internal module boundaries (library)
   - cli_args: Command-line arguments/flags
   - file_format: Custom file format handling
   - websocket: Real-time communication
   - grpc: gRPC services

3. PERSISTENCE (choose one):
   - remote_db: Cloud/remote database (PostgreSQL, MySQL, MongoDB)
   - local_db: Local database (SQLite, LevelDB)
   - file_based: File system storage
   - in_memory: No persistence
   - cloud_storage: Object storage (S3, etc.)

4. DEPLOYMENT (choose one):
   - cloud: Cloud platform (Vercel, AWS, GCP, etc.)
   - self_hosted: Self-managed server
   - desktop_installer: Native installers
   - package_registry: npm, PyPI, crates.io, etc.
   - app_store: Mobile app stores
   - none: No deployment (local script)

Output as JSON:
{
  "appType": "...",
  "appTypeReason": "...",
  "interfaces": ["..."],
  "interfacesReason": "...",
  "persistence": "...",
  "persistenceReason": "...",
  "deployment": "...",
  "deploymentReason": "...",
  "suggestedTechStack": {
    "language": "...",
    "framework": "...",
    "reasoning": "..."
  }
}

Research Query Generation

Based on this architecture classification, generate Perplexity search queries
to research current best practices:

<architecture>
{architecture_json}
</architecture>

Generate 4-6 search queries that will find:
1. Project structure and architecture best practices for this stack
2. Common mistakes and pitfalls to avoid
3. Recommended libraries and tools (current year)
4. Testing approaches and frameworks
5. (If applicable) Security considerations
6. (If applicable) Performance optimization

Format as JSON array of query strings. Make queries specific and current-year focused.

---

Appendix: Sample Output

For idea: "A CLI tool that converts markdown to PDF with syntax highlighting"

Generated PROMPT.md excerpt:

# Project: md2pdf

## Objective
CLI tool that converts markdown files to styled PDFs with syntax highlighting for code blocks.

## Application Type
CLI tool

## Architecture
- Interface types: CLI arguments
- Persistence: None (stateless transformation)
- Deployment: Package registry (npm) + standalone binary

## Tech Stack
- Language: TypeScript
- Runtime: Node.js 20
- CLI: Commander.js
- PDF: puppeteer + marked
- Syntax Highlighting: shiki
- Testing: Vitest
- Build: tsup + pkg

## Completion Criteria
1. `npm run build` exits 0
2. `npm run test` exits 0 with >80% coverage
3. `echo "# Test" | md2pdf > test.pdf` produces valid PDF
4. `md2pdf --help` shows all options
5. `md2pdf input.md -o output.pdf` works
6. Code blocks render with syntax highlighting
...

---

PRD Version: 1.0 Target: Claude Code + Ralph Method