Ralph PRD Generator

A CLI tool that generates Ralph Method project scaffolds with AI-powered research and specification generation.

Features

• Idea Classification: Uses Claude to analyze your app idea and classify its architecture
• Research Integration: Uses Perplexity to research best practices for your tech stack
• Specification Generation: Generates detailed features, data models, and interface contracts
• PRD Generation: Creates complete Ralph Method files (PROMPT.md, prd.json, GUIDE.md)
• Project Scaffolding: Sets up a complete project directory with all documentation
• Validation: Validates existing PROMPT.md files for Ralph compatibility
• Standalone Research: Research any topic using Perplexity AI

Installation

Clone and build locally:

git clone <repo-url>
cd ralph-gen
npm install
npm run build
npm link

Or run directly:

./dist/index.js --help

Quick Start

1. Configure API keys:

   ralph-vibe init
   

2. Create a new project:

   ralph-vibe new my-app
   

3. Follow the interactive prompts to describe your idea and review the generated scaffold.

Commands

ralph-vibe init

Configure API keys for Claude and Perplexity.

ralph-vibe init
ralph-vibe init --claude-key sk-ant-xxx
ralph-vibe init --perplexity-key pplx-xxx
ralph-vibe init --reset  # Clear existing configuration

Options:

Option	Description
--claude-key <key>	Set Claude API key directly
--perplexity-key <key>	Set Perplexity API key directly
--reset	Clear existing configuration

Keys are stored in ~/.ralph-generator/config.json with file permissions set to 600.

ralph-vibe new <project-name>

Create a new Ralph Method project.

ralph-vibe new my-app
ralph-vibe new my-app --idea-file ./idea.txt
ralph-vibe new my-app --skip-research
ralph-vibe new my-app --skip-confirm
ralph-vibe new my-app --dry-run

Options:

Option	Description
--idea-file <path>	Read idea from file instead of interactive prompt
--output-dir <path>	Output directory (default: current directory)
--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

Generated Structure:

my-app/
├── PROMPT.md           # Main Ralph prompt
├── prd.json            # Feature tracking
├── progress.txt        # Progress log
├── GUIDE.md            # Personalized step-by-step guide
├── CLAUDE.md           # Claude Code configuration
├── README.md           # Project README
├── docs/
│   ├── idea-dump.md    # Original idea
│   ├── architecture.md # Architecture decisions
│   ├── features.md     # Feature specifications
│   ├── tech-stack.md   # Tech stack details
│   ├── data-models.md  # Data model specs
│   ├── interfaces.md   # Interface contracts
│   └── research-notes.md # Research findings
├── agent_docs/
│   ├── tech_stack.md   # Tech stack context
│   ├── code_patterns.md # Coding patterns
│   └── testing.md      # Testing guide
├── src/                # Source directory
└── .gitignore

ralph-vibe validate <path>

Validate an existing PROMPT.md file for Ralph compatibility.

ralph-vibe validate ./PROMPT.md
ralph-vibe validate ./my-app/PROMPT.md

Checks for:

• Required sections (Objective, Application Type, Tech Stack, Completion Criteria)
• Promise tags for Ralph loop integration
• Ambiguous language (should, might, could, etc.)
• Verification commands in completion criteria

Exit codes:

• 0 - Valid PROMPT.md
• 1 - Issues found

ralph-vibe research <topic>

Research a topic using Perplexity AI.

ralph-vibe research "Node.js best practices 2026"
ralph-vibe research "React testing strategies" -o research.md
ralph-vibe research "Tauri 2.0 file handling" --verbose

Options:

Option	Description
-o, --output <path>	Save results to a file
--verbose	Show detailed progress

Environment Variables

API keys can be set via environment variables (overrides config file):

export CLAUDE_API_KEY=sk-ant-xxx
export PERPLEXITY_API_KEY=pplx-xxx

Configuration

Configuration is stored in ~/.ralph-generator/config.json:

{
  "claudeApiKey": "sk-ant-xxx",
  "perplexityApiKey": "pplx-xxx"
}

File permissions are set to 600 (user read/write only) for security.

Using Generated Projects

After generating a project:

cd my-app
# Read PROMPT.md for full requirements
# Follow GUIDE.md for step-by-step instructions
# Or start a Ralph loop:
/ralph-wiggum:ralph-loop "$(cat PROMPT.md)" --max-iterations 50 --completion-promise "PROJECT_COMPLETE"

Troubleshooting

"Claude API key not found"

Run ralph-vibe init to configure your API key, or set the CLAUDE_API_KEY environment variable.

"Perplexity API key not found"

Run ralph-vibe init to configure your Perplexity key, or use --skip-research to skip the research phase.

"Invalid API key"

Verify your API key is correct:

• Claude: https://console.anthropic.com/
• Perplexity: https://www.perplexity.ai/settings/api

"Idea must be at least 50 characters"

Provide a more detailed description of your app idea. Include:

• What the app does
• Who it's for
• Key features

Rate Limiting

The tool automatically retries on rate limits with exponential backoff. If you encounter persistent rate limits, wait a few minutes before trying again.

Development

# Clone the repository
git clone https://github.com/your-username/ralph-vibe.git
cd ralph-vibe

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Lint
npm run lint

# Run in development mode
npm run dev

Tech Stack

• Language: TypeScript (strict mode)
• Runtime: Node.js 20+
• CLI Framework: Commander.js
• Prompts: Inquirer.js
• Spinners: ora
• Colors: chalk
• AI: Anthropic SDK, Perplexity API
• Testing: Vitest
• Build: tsup

License

MIT