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

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

Or run directly:

```bash
./dist/index.js --help
```

## Quick Start

1. **Configure API keys**:
   ```bash
   ralph-vibe init
   ```

2. **Create a new project**:
   ```bash
   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.

```bash
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.

```bash
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.

```bash
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.

```bash
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):

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

## Configuration

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

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

```bash
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

```bash
# 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