581 lines
20 KiB
Markdown
581 lines
20 KiB
Markdown
# 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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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**:
|
|
|
|
```markdown
|
|
# 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*
|