Implement Phase 3 & 4: Generation Pipeline and Polish
Phase 3 - Generation Pipeline: - SpecificationGenerator: generates features, data models, interfaces - PRDGenerator: generates PROMPT.md, prd.json, GUIDE.md, CLAUDE.md - ScaffoldGenerator: creates complete project structure with git init - Interactive prompts with Inquirer.js for user confirmation - Full pipeline integration in new command Phase 4 - Polish: - Validate command for PROMPT.md files - Standalone research command using Perplexity - Dry-run mode with --dry-run flag - Comprehensive README.md documentation - Examples directory with sample outputs - npm packaging verified (npm pack, npm publish --dry-run) Bug fixes: - Fix EXDEV error in atomic file writes (use same-dir temp files) - Update Claude model to claude-sonnet-4-5-20250929 All 110 tests passing, all completion criteria met. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Debian
249
README.md
Normal file
249
README.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
npm install -g ralph-vibe
|
||||
```
|
||||
|
||||
Or with npx (no installation required):
|
||||
|
||||
```bash
|
||||
npx ralph-vibe --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
|
||||
Reference in New Issue
Block a user