Initial Ralph scaffold for ralph-vibe
This commit is contained in:
Debian
10
.gitignore
vendored
Normal file
10
.gitignore
vendored
Normal file
@@ -0,0 +1,10 @@
|
|||||||
|
node_modules/
|
||||||
|
dist/
|
||||||
|
.env
|
||||||
|
.env.local
|
||||||
|
*.log
|
||||||
|
coverage/
|
||||||
|
.DS_Store
|
||||||
|
*.tgz
|
||||||
|
RALPH_TASK.md
|
||||||
|
phase*-prompt.txt
|
||||||
78
CLAUDE.md
Normal file
78
CLAUDE.md
Normal file
@@ -0,0 +1,78 @@
|
|||||||
|
# Claude Code Configuration
|
||||||
|
|
||||||
|
## Project Context
|
||||||
|
|
||||||
|
This is the Ralph PRD Generator - a CLI tool that generates Ralph Method project scaffolds.
|
||||||
|
|
||||||
|
Read PROMPT.md for full requirements.
|
||||||
|
Read prd.json for feature tracking.
|
||||||
|
Append progress to progress.txt after each significant change.
|
||||||
|
|
||||||
|
## Key Files
|
||||||
|
|
||||||
|
- PROMPT.md: Full specification - this is your primary reference
|
||||||
|
- prd.json: Feature tracking with acceptance criteria
|
||||||
|
- progress.txt: Append-only progress log
|
||||||
|
- docs/framework.md: Ralph Method framework reference
|
||||||
|
- docs/guide.md: Step-by-step guide reference
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- TypeScript with strict mode
|
||||||
|
- Node.js 20+
|
||||||
|
- Commander.js for CLI
|
||||||
|
- Inquirer.js for prompts
|
||||||
|
- Anthropic SDK for Claude
|
||||||
|
- Native fetch for Perplexity
|
||||||
|
- Vitest for testing
|
||||||
|
- tsup for building
|
||||||
|
|
||||||
|
## Working Rules
|
||||||
|
|
||||||
|
1. Always run tests before committing
|
||||||
|
2. Never commit failing code
|
||||||
|
3. Update prd.json when features complete by setting passes to true
|
||||||
|
4. Use conventional commit messages
|
||||||
|
5. Make reasonable decisions - do not ask questions
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
- Build: npm run build
|
||||||
|
- Test: npm run test
|
||||||
|
- Lint: npm run lint
|
||||||
|
- All: npm run build && npm run test && npm run lint
|
||||||
|
- Dev: npm run dev
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
src/
|
||||||
|
index.ts # CLI entry point
|
||||||
|
commands/ # Command handlers
|
||||||
|
init.ts
|
||||||
|
new.ts
|
||||||
|
validate.ts
|
||||||
|
research.ts
|
||||||
|
clients/ # API clients
|
||||||
|
claude.ts
|
||||||
|
perplexity.ts
|
||||||
|
generators/ # Generation logic
|
||||||
|
architecture.ts
|
||||||
|
specification.ts
|
||||||
|
prd.ts
|
||||||
|
scaffold.ts
|
||||||
|
prompts/ # Prompt templates
|
||||||
|
templates.ts
|
||||||
|
types/ # TypeScript types
|
||||||
|
index.ts
|
||||||
|
utils/ # Utilities
|
||||||
|
config.ts
|
||||||
|
files.ts
|
||||||
|
logger.ts
|
||||||
|
|
||||||
|
## API Keys for Testing
|
||||||
|
|
||||||
|
During development, use environment variables:
|
||||||
|
- CLAUDE_API_KEY
|
||||||
|
- PERPLEXITY_API_KEY
|
||||||
|
|
||||||
|
Never commit real keys. Use .env.local which is gitignored.
|
||||||
580
PROMPT.md
Normal file
580
PROMPT.md
Normal file
@@ -0,0 +1,580 @@
|
|||||||
|
# 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*
|
||||||
881
docs/framework.md
Normal file
881
docs/framework.md
Normal file
@@ -0,0 +1,881 @@
|
|||||||
|
# The Ralph Method: Comprehensive Framework for 100% Vibe-Coded Greenfield Projects
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
|
||||||
|
The Ralph Method is an iterative AI development methodology that runs autonomous coding agents in persistent loops until task completion. Named after Ralph Wiggum from The Simpsons—perpetually confused but never stopping—it embodies the philosophy: **"Better to fail predictably than succeed unpredictably."**
|
||||||
|
|
||||||
|
Core principle: Iteration beats perfection. The agent sees previous work via git history and modified files, learns from it, and iteratively improves.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 1: Philosophy and Prerequisites
|
||||||
|
|
||||||
|
### The Ralph Mindset
|
||||||
|
|
||||||
|
- **Deterministically bad in an undeterministic world**: Failures are predictable and informative
|
||||||
|
- **Operator skill matters**: Success depends on writing good prompts, not just having a good model
|
||||||
|
- **LLMs are mirrors of operator skill**: The quality of output reflects the quality of input
|
||||||
|
- **Faith in eventual consistency**: Ralph will test you. Each failure tunes the system like a guitar
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
1. **Claude Code** installed and configured
|
||||||
|
2. **Git** initialized in project directory
|
||||||
|
3. **jq** installed (required dependency on Windows/Git Bash)
|
||||||
|
4. **Clear success criteria** for your project
|
||||||
|
5. **Cost awareness**: Opus 4.5 burns $15-75/hour on large contexts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 2: PRD Structure for Ralph Consumption
|
||||||
|
|
||||||
|
Traditional PRDs must be converted to machine-parseable format. Create `PROMPT.md` in your project root.
|
||||||
|
|
||||||
|
### PRD Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Project: [NAME]
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
[One sentence describing the end state]
|
||||||
|
|
||||||
|
## Application Type
|
||||||
|
[Web app | Desktop app | CLI tool | Library | Mobile app | Other]
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
- Interface types: [REST API | GraphQL | IPC | Module boundaries | CLI | File formats]
|
||||||
|
- Persistence: [Remote DB | Local DB | File-based | In-memory | None]
|
||||||
|
- Deployment: [Cloud | Self-hosted | Desktop installer | Package registry | App store]
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
- Language: [X]
|
||||||
|
- Framework: [X]
|
||||||
|
- Database/Storage: [X]
|
||||||
|
- Testing: [X]
|
||||||
|
- CI: [X]
|
||||||
|
|
||||||
|
## Completion Criteria
|
||||||
|
All of the following must be true:
|
||||||
|
1. Build command passes with zero errors
|
||||||
|
2. Test command passes with >80% coverage
|
||||||
|
3. Lint command passes
|
||||||
|
4. All features documented in README.md
|
||||||
|
5. [App-type specific criteria, e.g.:]
|
||||||
|
- Web: Docker compose brings up working stack
|
||||||
|
- Desktop: Installers build for all target platforms
|
||||||
|
- CLI: Binary runs and --help works
|
||||||
|
- Library: Package publishes to registry (dry-run)
|
||||||
|
|
||||||
|
Output `<promise>PROJECT_COMPLETE</promise>` when all criteria met.
|
||||||
|
|
||||||
|
## Phase 1: Foundation
|
||||||
|
- [ ] Initialize project structure
|
||||||
|
- [ ] Set up CI/linting/formatting
|
||||||
|
- [ ] Create data layer (DB schema | file handlers | state management)
|
||||||
|
- [ ] Write failing tests for core models
|
||||||
|
|
||||||
|
## Phase 2: Core [Features | UI | Commands | API]
|
||||||
|
[Adapted to app type]
|
||||||
|
- [ ] Feature A
|
||||||
|
- Acceptance: [binary criterion]
|
||||||
|
- [ ] Feature B
|
||||||
|
- Acceptance: [binary criterion]
|
||||||
|
|
||||||
|
## Phase 3: [Integration | System | I/O]
|
||||||
|
[Adapted to app type:]
|
||||||
|
- Web: External services, auth, error handling
|
||||||
|
- Desktop: System integration, file watching, native APIs
|
||||||
|
- CLI: Input parsing, output formatting, piping support
|
||||||
|
- Library: Edge cases, error handling, type exports
|
||||||
|
|
||||||
|
## Phase 4: [Polish | Packaging | Publishing]
|
||||||
|
[Adapted to app type:]
|
||||||
|
- Web: Documentation, performance, deployment config
|
||||||
|
- Desktop: Installers, auto-update, icons, signing
|
||||||
|
- CLI: Man pages, shell completions, distribution
|
||||||
|
- Library: API docs, examples, changelog, publishing
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
- No external API calls without mocking in tests
|
||||||
|
- All functions must have docstrings/JSDoc
|
||||||
|
- [Language-specific, e.g., No `any` types for TypeScript]
|
||||||
|
- [Additional constraints]
|
||||||
|
|
||||||
|
## Abort Conditions
|
||||||
|
If any of these occur, output `<promise>ABORT_BLOCKED</promise>`:
|
||||||
|
- Cannot resolve circular dependency after 5 attempts
|
||||||
|
- External service unavailable after 3 retries
|
||||||
|
- Architectural issue that requires human decision
|
||||||
|
- After 15 iterations if not fixed, document blocking issues
|
||||||
|
```
|
||||||
|
|
||||||
|
### PRD Conversion Rules
|
||||||
|
|
||||||
|
| Traditional PRD Element | Ralph Format |
|
||||||
|
|------------------------|--------------|
|
||||||
|
| User stories | Concrete acceptance tests |
|
||||||
|
| "Should support X" | Specific test file that must pass |
|
||||||
|
| Architecture diagrams | File structure specification |
|
||||||
|
| "Nice to have" | Remove entirely or move to Phase 4 |
|
||||||
|
| Ambiguous requirements | Binary pass/fail criteria |
|
||||||
|
| Success metrics | Automated verification commands |
|
||||||
|
|
||||||
|
### JSON-Based PRD (Matt Pocock Method)
|
||||||
|
|
||||||
|
For scoping work correctly and preventing context rot:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"project": "MyApp",
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"id": "auth",
|
||||||
|
"description": "JWT authentication system",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "npm run test:auth passes"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "api",
|
||||||
|
"description": "REST API endpoints",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "all endpoints return 200 for valid requests"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Prompt the agent to:
|
||||||
|
1. Pick the highest priority feature with `passes: false`
|
||||||
|
2. Work ONLY on that feature
|
||||||
|
3. Update the passing status when acceptance criteria met
|
||||||
|
4. Commit progress to `progress.txt`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 3: Directory Setup
|
||||||
|
|
||||||
|
### Initial Structure
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir my-project && cd my-project
|
||||||
|
git init
|
||||||
|
|
||||||
|
# Core prompt file
|
||||||
|
cat > PROMPT.md << 'EOF'
|
||||||
|
[Your structured PRD here]
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Progress tracker (critical for context persistence)
|
||||||
|
touch progress.txt
|
||||||
|
|
||||||
|
# Agent context files (optional but recommended)
|
||||||
|
mkdir -p agent_docs
|
||||||
|
touch agent_docs/tech_stack.md
|
||||||
|
touch agent_docs/code_patterns.md
|
||||||
|
touch agent_docs/testing.md
|
||||||
|
|
||||||
|
# Initial commit
|
||||||
|
git add .
|
||||||
|
git commit -m "Initial prompt and structure"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recommended Full Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
my-project/
|
||||||
|
├── PROMPT.md # Main task definition
|
||||||
|
├── progress.txt # Append-only progress log
|
||||||
|
├── prd.json # JSON PRD for feature tracking
|
||||||
|
├── agent_docs/
|
||||||
|
│ ├── tech_stack.md # Tech decisions and rationale
|
||||||
|
│ ├── code_patterns.md # Project conventions
|
||||||
|
│ ├── testing.md # Test strategy
|
||||||
|
│ └── resources.md # External references
|
||||||
|
├── CLAUDE.md # Claude Code specific config
|
||||||
|
├── .cursorrules # Cursor config (if using)
|
||||||
|
├── .gitignore
|
||||||
|
├── README.md
|
||||||
|
└── src/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 4: Execution Methods
|
||||||
|
|
||||||
|
### Method A: Official Ralph Wiggum Plugin (Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install from official plugin marketplace
|
||||||
|
/plugin marketplace add anthropics/claude-code
|
||||||
|
/plugin install ralph-wiggum@claude-plugins-official
|
||||||
|
|
||||||
|
# Basic usage
|
||||||
|
/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N
|
||||||
|
|
||||||
|
# With completion promise
|
||||||
|
/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N --completion-promise "text"
|
||||||
|
|
||||||
|
# Cancel active loop
|
||||||
|
/ralph-wiggum:cancel-ralph
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```bash
|
||||||
|
/ralph-wiggum:ralph-loop "Build the authentication system as specified in PROMPT.md. Output <promise>AUTH_COMPLETE</promise> when all auth tests pass." --max-iterations 30 --completion-promise "AUTH_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Method B: Raw Bash Loop (Universal)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# ralph-loop.sh
|
||||||
|
|
||||||
|
MAX_ITERATIONS=${1:-30}
|
||||||
|
ITERATION=0
|
||||||
|
|
||||||
|
while [ $ITERATION -lt $MAX_ITERATIONS ]; do
|
||||||
|
echo "=== Iteration $((ITERATION + 1)) of $MAX_ITERATIONS ==="
|
||||||
|
|
||||||
|
# Feed prompt to Claude Code
|
||||||
|
cat PROMPT.md | claude --print
|
||||||
|
|
||||||
|
# Check for completion promise
|
||||||
|
if grep -rq "<promise>PROJECT_COMPLETE</promise>" . 2>/dev/null; then
|
||||||
|
echo "Project complete at iteration $((ITERATION + 1))"
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check for abort
|
||||||
|
if grep -rq "<promise>ABORT_BLOCKED</promise>" . 2>/dev/null; then
|
||||||
|
echo "Agent blocked. Check logs."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Auto-commit progress
|
||||||
|
git add -A
|
||||||
|
git diff --cached --quiet || git commit -m "Ralph iteration $((ITERATION + 1))"
|
||||||
|
|
||||||
|
ITERATION=$((ITERATION + 1))
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "Max iterations reached"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Method C: Enhanced Loop with Safety Controls
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
set -e
|
||||||
|
|
||||||
|
MAX_ITERATIONS=${1:-30}
|
||||||
|
FAIL_COUNT=0
|
||||||
|
MAX_CONSECUTIVE_FAILS=5
|
||||||
|
|
||||||
|
for i in $(seq 1 $MAX_ITERATIONS); do
|
||||||
|
echo "=== Iteration $i of $MAX_ITERATIONS ==="
|
||||||
|
echo "Started: $(date)" >> progress.txt
|
||||||
|
|
||||||
|
# Run Claude with timeout (10 minutes per iteration)
|
||||||
|
timeout 600 bash -c 'cat PROMPT.md | claude --print' || {
|
||||||
|
echo "Iteration timed out, continuing..."
|
||||||
|
echo "Iteration $i: TIMEOUT" >> progress.txt
|
||||||
|
}
|
||||||
|
|
||||||
|
# Commit whatever got done
|
||||||
|
git add -A
|
||||||
|
git diff --cached --quiet || git commit -m "Ralph iteration $i"
|
||||||
|
|
||||||
|
# Check completion
|
||||||
|
if grep -rq "<promise>PROJECT_COMPLETE</promise>" .; then
|
||||||
|
echo "Complete at iteration $i"
|
||||||
|
echo "PROJECT COMPLETE at iteration $i" >> progress.txt
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check abort
|
||||||
|
if grep -rq "<promise>ABORT_BLOCKED</promise>" .; then
|
||||||
|
echo "Agent signaled abort"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Verify tests pass (prevents compounding errors)
|
||||||
|
if command -v npm &> /dev/null && [ -f package.json ]; then
|
||||||
|
if ! npm test 2>/dev/null; then
|
||||||
|
FAIL_COUNT=$((FAIL_COUNT + 1))
|
||||||
|
echo "Test failure #$FAIL_COUNT" >> progress.txt
|
||||||
|
if [ $FAIL_COUNT -gt $MAX_CONSECUTIVE_FAILS ]; then
|
||||||
|
echo "Too many consecutive test failures. Stopping."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
FAIL_COUNT=0
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "Iteration $i complete" >> progress.txt
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "Max iterations reached without completion"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Method D: Amp/Sourcegraph Loop
|
||||||
|
|
||||||
|
```bash
|
||||||
|
while :; do cat PROMPT.md | npx --yes @sourcegraph/amp ; done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 5: Prompt Engineering for Ralph
|
||||||
|
|
||||||
|
### Critical Prompt Elements
|
||||||
|
|
||||||
|
1. **Clear Completion Signal**
|
||||||
|
```markdown
|
||||||
|
Output <promise>COMPLETE</promise> when:
|
||||||
|
- All tests pass
|
||||||
|
- Linting passes
|
||||||
|
- Build succeeds
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Atomic Task Scoping**
|
||||||
|
```markdown
|
||||||
|
Work ONLY on the highest-priority incomplete feature.
|
||||||
|
Do NOT proceed to next feature until current feature passes all acceptance criteria.
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Progress Tracking**
|
||||||
|
```markdown
|
||||||
|
After each significant change:
|
||||||
|
1. Commit your work with descriptive message
|
||||||
|
2. Append progress to progress.txt (use verb 'append', do not modify previous entries)
|
||||||
|
3. Run tests to verify state
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **CI Green Requirement**
|
||||||
|
```markdown
|
||||||
|
Each commit MUST pass all tests and type checks.
|
||||||
|
Never commit code that breaks the build.
|
||||||
|
Run `npm run build && npm run test && npm run lint` before every commit.
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Self-Correction Pattern**
|
||||||
|
```markdown
|
||||||
|
If tests fail:
|
||||||
|
1. Read the error message
|
||||||
|
2. Identify root cause
|
||||||
|
3. Implement fix
|
||||||
|
4. Run tests again
|
||||||
|
5. Repeat until green
|
||||||
|
```
|
||||||
|
|
||||||
|
### Prompt Tuning Process
|
||||||
|
|
||||||
|
Geoffrey Huntley's guitar tuning metaphor:
|
||||||
|
|
||||||
|
1. **Start with no guardrails**: Let Ralph build the playground first
|
||||||
|
2. **Add signs when Ralph fails**: When Ralph falls off the slide, add a sign saying "SLIDE DOWN, DON'T JUMP"
|
||||||
|
3. **Iterate on failures**: Each failure teaches you what guardrails to add
|
||||||
|
4. **Eventually get a new Ralph**: Once prompts are tuned, the defects disappear
|
||||||
|
|
||||||
|
### Example: Feature Implementation Prompt
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Task: Implement User Authentication
|
||||||
|
|
||||||
|
Read PROMPT.md for full project context.
|
||||||
|
|
||||||
|
## Current Feature
|
||||||
|
Implement JWT-based user authentication.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
- POST /auth/register - Create new user
|
||||||
|
- POST /auth/login - Return JWT token
|
||||||
|
- GET /auth/me - Return current user (protected)
|
||||||
|
- Password hashing with bcrypt
|
||||||
|
- Token expiration: 24 hours
|
||||||
|
|
||||||
|
## Process
|
||||||
|
1. Write failing tests first (TDD)
|
||||||
|
2. Implement minimal code to pass
|
||||||
|
3. Run tests
|
||||||
|
4. If failing, debug and fix
|
||||||
|
5. Refactor if needed
|
||||||
|
6. Repeat until all green
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
- All tests in tests/auth.test.ts pass
|
||||||
|
- No linter errors
|
||||||
|
- Coverage > 80% for auth module
|
||||||
|
|
||||||
|
## On Completion
|
||||||
|
1. Update prd.json: set auth.passes = true
|
||||||
|
2. Append summary to progress.txt
|
||||||
|
3. Output <promise>AUTH_DONE</promise>
|
||||||
|
|
||||||
|
## If Stuck After 10 Attempts
|
||||||
|
- Document blocking issues in progress.txt
|
||||||
|
- List attempted approaches
|
||||||
|
- Output <promise>AUTH_BLOCKED</promise>
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 6: AFK Ralph vs HOTL Ralph
|
||||||
|
|
||||||
|
### AFK (Away From Keyboard) Ralph
|
||||||
|
|
||||||
|
For overnight/weekend runs on well-defined tasks:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## AFK Mode Instructions
|
||||||
|
|
||||||
|
You are running autonomously. Human will not intervene.
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
1. Never stop to ask questions - make reasonable decisions
|
||||||
|
2. If blocked, try 3 alternative approaches before marking blocked
|
||||||
|
3. Commit frequently (every 5-10 minutes of work)
|
||||||
|
4. Log all decisions to progress.txt
|
||||||
|
5. Prefer reversible decisions over blocking
|
||||||
|
6. If uncertain, implement the simpler option
|
||||||
|
7. Document assumptions made
|
||||||
|
|
||||||
|
Safety:
|
||||||
|
- Never delete data without explicit instruction
|
||||||
|
- Never modify files outside project directory
|
||||||
|
- Never make network requests to production systems
|
||||||
|
- Stop if costs approach $100 in estimated tokens
|
||||||
|
```
|
||||||
|
|
||||||
|
### HOTL (Human On The Loop) Ralph
|
||||||
|
|
||||||
|
For complex tasks requiring occasional judgment:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## HOTL Mode Instructions
|
||||||
|
|
||||||
|
Human is monitoring but not actively directing.
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
1. Work autonomously on implementation details
|
||||||
|
2. Signal for human input on:
|
||||||
|
- Architectural decisions
|
||||||
|
- Security-critical code
|
||||||
|
- External API integrations
|
||||||
|
- Ambiguous requirements
|
||||||
|
3. Use <question>Your question here</question> tags when blocked
|
||||||
|
4. Continue with other work while waiting for response
|
||||||
|
5. Log questions to progress.txt with timestamp
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 7: Advanced Patterns
|
||||||
|
|
||||||
|
### Parallel Development with Git Worktrees
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create isolated worktrees for parallel features
|
||||||
|
git worktree add ../project-auth -b feature/auth
|
||||||
|
git worktree add ../project-api -b feature/api
|
||||||
|
git worktree add ../project-ui -b feature/ui
|
||||||
|
|
||||||
|
# Terminal 1: Auth
|
||||||
|
cd ../project-auth
|
||||||
|
/ralph-wiggum:ralph-loop "Implement authentication..." --max-iterations 30
|
||||||
|
|
||||||
|
# Terminal 2: API (simultaneously)
|
||||||
|
cd ../project-api
|
||||||
|
/ralph-wiggum:ralph-loop "Build REST API..." --max-iterations 30
|
||||||
|
|
||||||
|
# Terminal 3: UI (simultaneously)
|
||||||
|
cd ../project-ui
|
||||||
|
/ralph-wiggum:ralph-loop "Build frontend components..." --max-iterations 30
|
||||||
|
|
||||||
|
# Later: merge completed features
|
||||||
|
git checkout main
|
||||||
|
git merge feature/auth
|
||||||
|
git merge feature/api
|
||||||
|
git merge feature/ui
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Phase Sequential Development
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Phase 1: Data layer
|
||||||
|
/ralph-wiggum:ralph-loop "Phase 1: Build data models and database schema. Output <promise>PHASE1_DONE</promise>" --max-iterations 20 --completion-promise "PHASE1_DONE"
|
||||||
|
|
||||||
|
# Phase 2: Business logic
|
||||||
|
/ralph-wiggum:ralph-loop "Phase 2: Build service layer and business logic. Output <promise>PHASE2_DONE</promise>" --max-iterations 25 --completion-promise "PHASE2_DONE"
|
||||||
|
|
||||||
|
# Phase 3: API
|
||||||
|
/ralph-wiggum:ralph-loop "Phase 3: Build API endpoints. Output <promise>PHASE3_DONE</promise>" --max-iterations 25 --completion-promise "PHASE3_DONE"
|
||||||
|
|
||||||
|
# Phase 4: Frontend
|
||||||
|
/ralph-wiggum:ralph-loop "Phase 4: Build UI. Output <promise>PHASE4_DONE</promise>" --max-iterations 30 --completion-promise "PHASE4_DONE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Overnight Batch Processing
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# overnight-work.sh
|
||||||
|
|
||||||
|
LOG_FILE="overnight-$(date +%Y%m%d).log"
|
||||||
|
|
||||||
|
echo "Starting overnight batch: $(date)" >> $LOG_FILE
|
||||||
|
|
||||||
|
# Project 1
|
||||||
|
cd /path/to/project1
|
||||||
|
echo "Starting project1..." >> $LOG_FILE
|
||||||
|
timeout 14400 bash -c '/ralph-wiggum:ralph-loop "$(cat PROMPT.md)" --max-iterations 50' >> $LOG_FILE 2>&1
|
||||||
|
echo "Project1 finished: $(date)" >> $LOG_FILE
|
||||||
|
|
||||||
|
# Project 2
|
||||||
|
cd /path/to/project2
|
||||||
|
echo "Starting project2..." >> $LOG_FILE
|
||||||
|
timeout 14400 bash -c '/ralph-wiggum:ralph-loop "$(cat PROMPT.md)" --max-iterations 50' >> $LOG_FILE 2>&1
|
||||||
|
echo "Project2 finished: $(date)" >> $LOG_FILE
|
||||||
|
|
||||||
|
echo "Batch complete: $(date)" >> $LOG_FILE
|
||||||
|
|
||||||
|
# Optional: send notification
|
||||||
|
# curl -X POST "https://hooks.slack.com/..." -d '{"text":"Overnight batch complete"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 8: Quality Control and Safety
|
||||||
|
|
||||||
|
### Feedback Loops (Critical)
|
||||||
|
|
||||||
|
1. **Tests**: Every commit must pass all tests
|
||||||
|
2. **Types**: Full type checking on every commit
|
||||||
|
3. **Lint**: Consistent style enforcement
|
||||||
|
4. **Build**: Verify deployability continuously
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Mandatory Verification Sequence
|
||||||
|
|
||||||
|
Before EVERY commit, run:
|
||||||
|
```bash
|
||||||
|
npm run typecheck && npm run lint && npm run test && npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
If ANY command fails:
|
||||||
|
1. Do NOT commit
|
||||||
|
2. Fix the issue
|
||||||
|
3. Re-run verification
|
||||||
|
4. Only commit when all pass
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cost Control
|
||||||
|
|
||||||
|
| Context Size | Approx Cost/Hour | Recommended Max Iterations |
|
||||||
|
|-------------|------------------|---------------------------|
|
||||||
|
| Small (<50k tokens) | $15-25 | 50 |
|
||||||
|
| Medium (50-200k tokens) | $25-50 | 30 |
|
||||||
|
| Large (>200k tokens) | $50-100+ | 20 |
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Set hard limits
|
||||||
|
/ralph-wiggum:ralph-loop "..." --max-iterations 30
|
||||||
|
|
||||||
|
# Monitor during execution
|
||||||
|
# Check ~/.claude/usage.log or equivalent
|
||||||
|
```
|
||||||
|
|
||||||
|
### Safety Guardrails
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Safety Rules
|
||||||
|
|
||||||
|
NEVER:
|
||||||
|
- Delete production data
|
||||||
|
- Modify files outside project directory
|
||||||
|
- Execute commands with sudo
|
||||||
|
- Make requests to production APIs
|
||||||
|
- Store credentials in code
|
||||||
|
- Commit sensitive data to git
|
||||||
|
|
||||||
|
ALWAYS:
|
||||||
|
- Use environment variables for secrets
|
||||||
|
- Mock external services in tests
|
||||||
|
- Operate in sandboxed environment
|
||||||
|
- Maintain ability to rollback via git
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recovery Procedures
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# If Ralph goes off the rails
|
||||||
|
/ralph-wiggum:cancel-ralph
|
||||||
|
|
||||||
|
# Review what happened
|
||||||
|
git log --oneline -20
|
||||||
|
git diff HEAD~5
|
||||||
|
|
||||||
|
# Rollback if needed
|
||||||
|
git reset --hard HEAD~N
|
||||||
|
|
||||||
|
# Clean up any mess
|
||||||
|
git clean -fd
|
||||||
|
|
||||||
|
# Restart with adjusted prompt
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 9: When to Use (and Not Use) Ralph
|
||||||
|
|
||||||
|
### Good For
|
||||||
|
|
||||||
|
- **Greenfield projects** with clear specifications
|
||||||
|
- **Mechanical tasks**: migrations, refactors, test coverage
|
||||||
|
- **Well-defined tasks** with automatic verification
|
||||||
|
- **Batch operations**: lint fixes, dependency updates
|
||||||
|
- **Documentation** generation
|
||||||
|
- **Test writing** with clear acceptance criteria
|
||||||
|
- **Overnight development** while you sleep
|
||||||
|
|
||||||
|
### Not Good For
|
||||||
|
|
||||||
|
- **Ambiguous requirements** without binary success criteria
|
||||||
|
- **Architectural decisions** requiring human judgment
|
||||||
|
- **Security-critical code** needing human review
|
||||||
|
- **Exploratory work** without clear goals
|
||||||
|
- **Production debugging** requiring context
|
||||||
|
- **UX/design decisions** requiring human taste
|
||||||
|
- **Complex integrations** with undocumented APIs
|
||||||
|
|
||||||
|
### Decision Matrix
|
||||||
|
|
||||||
|
| Task Type | Ralph Suitability | Recommended Approach |
|
||||||
|
|-----------|------------------|---------------------|
|
||||||
|
| New API endpoint | High | AFK Ralph |
|
||||||
|
| Database migration | High | AFK Ralph |
|
||||||
|
| Test coverage | High | AFK Ralph |
|
||||||
|
| Security audit | Low | Manual review |
|
||||||
|
| UI polish | Medium | HOTL Ralph |
|
||||||
|
| Performance tuning | Medium | HOTL Ralph |
|
||||||
|
| Architecture design | Low | Manual design + Ralph implementation |
|
||||||
|
| Bug investigation | Low | Manual + targeted Ralph |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 10: Real-World Results
|
||||||
|
|
||||||
|
### Documented Successes
|
||||||
|
|
||||||
|
- **CURSED Programming Language**: 3-month continuous loop, built complete esoteric language
|
||||||
|
- **YC Hackathon**: 6 repositories shipped overnight for $297 in API costs
|
||||||
|
- **$50k Contract**: Delivered complete MVP with Ralph for ~$300 in compute
|
||||||
|
- **Integration Test Optimization**: Reduced runtime from 4 minutes to 2 seconds
|
||||||
|
|
||||||
|
### Cost Expectations
|
||||||
|
|
||||||
|
| Project Complexity | Estimated Cost | Typical Iterations |
|
||||||
|
|-------------------|----------------|-------------------|
|
||||||
|
| Simple CRUD app | $50-100 | 20-30 |
|
||||||
|
| Medium SaaS MVP | $200-500 | 50-100 |
|
||||||
|
| Complex system | $500-2000+ | 100-300 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Part 11: Quick Reference
|
||||||
|
|
||||||
|
### Checklist: Before Starting Ralph
|
||||||
|
|
||||||
|
- [ ] Git initialized
|
||||||
|
- [ ] PROMPT.md created with binary completion criteria
|
||||||
|
- [ ] progress.txt created (empty)
|
||||||
|
- [ ] Test framework configured
|
||||||
|
- [ ] Linting configured
|
||||||
|
- [ ] Build command working
|
||||||
|
- [ ] --max-iterations set appropriately
|
||||||
|
- [ ] Cost limits understood
|
||||||
|
- [ ] Rollback strategy clear
|
||||||
|
|
||||||
|
### Checklist: During Ralph Run
|
||||||
|
|
||||||
|
- [ ] Monitoring progress.txt
|
||||||
|
- [ ] Watching git log
|
||||||
|
- [ ] Checking test results
|
||||||
|
- [ ] Monitoring token usage
|
||||||
|
- [ ] Ready to /cancel-ralph if needed
|
||||||
|
|
||||||
|
### Checklist: After Ralph Run
|
||||||
|
|
||||||
|
- [ ] Review all commits
|
||||||
|
- [ ] Run full test suite
|
||||||
|
- [ ] Review code quality
|
||||||
|
- [ ] Squash/rebase commits if desired
|
||||||
|
- [ ] Document any issues found
|
||||||
|
- [ ] Update PRD with lessons learned
|
||||||
|
|
||||||
|
### Command Reference
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start loop
|
||||||
|
/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N --completion-promise "TEXT"
|
||||||
|
|
||||||
|
# Cancel loop
|
||||||
|
/ralph-wiggum:cancel-ralph
|
||||||
|
|
||||||
|
# Help
|
||||||
|
/ralph-wiggum:help
|
||||||
|
|
||||||
|
# Raw bash alternative
|
||||||
|
while :; do cat PROMPT.md | claude --print ; done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix A: Complete PROMPT.md Template
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Project: [NAME]
|
||||||
|
|
||||||
|
## Context
|
||||||
|
[2-3 sentences about what this project is]
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
- Runtime: Node.js 20 / Python 3.12 / Go 1.22
|
||||||
|
- Framework: Express / FastAPI / Gin
|
||||||
|
- Database: PostgreSQL 16
|
||||||
|
- ORM: Prisma / SQLAlchemy / GORM
|
||||||
|
- Testing: Jest / pytest / go test
|
||||||
|
- Linting: ESLint / ruff / golangci-lint
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── controllers/ # HTTP handlers
|
||||||
|
├── services/ # Business logic
|
||||||
|
├── models/ # Data models
|
||||||
|
├── middleware/ # Auth, logging, etc.
|
||||||
|
├── utils/ # Helpers
|
||||||
|
└── types/ # Type definitions
|
||||||
|
|
||||||
|
tests/
|
||||||
|
├── unit/
|
||||||
|
├── integration/
|
||||||
|
└── e2e/
|
||||||
|
```
|
||||||
|
|
||||||
|
## Completion Criteria
|
||||||
|
All must be true:
|
||||||
|
1. `npm run build` exits 0
|
||||||
|
2. `npm run test` exits 0 with >80% coverage
|
||||||
|
3. `npm run lint` exits 0
|
||||||
|
4. README.md contains API documentation
|
||||||
|
5. All features in prd.json have passes=true
|
||||||
|
|
||||||
|
Output `<promise>PROJECT_COMPLETE</promise>` when ALL criteria met.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
### Phase 1: Foundation (Priority 1)
|
||||||
|
- [ ] Project setup with all dependencies
|
||||||
|
- [ ] Database connection and migrations
|
||||||
|
- [ ] Basic health check endpoint
|
||||||
|
- [ ] Logging middleware
|
||||||
|
- [ ] Error handling middleware
|
||||||
|
|
||||||
|
### Phase 2: Core (Priority 2)
|
||||||
|
- [ ] User model and CRUD
|
||||||
|
- [ ] Authentication (JWT)
|
||||||
|
- [ ] Authorization middleware
|
||||||
|
- [ ] [Feature specific to project]
|
||||||
|
- [ ] [Feature specific to project]
|
||||||
|
|
||||||
|
### Phase 3: Integration (Priority 3)
|
||||||
|
- [ ] [External service]
|
||||||
|
- [ ] Email notifications
|
||||||
|
- [ ] File uploads
|
||||||
|
|
||||||
|
### Phase 4: Polish (Priority 4)
|
||||||
|
- [ ] API documentation
|
||||||
|
- [ ] Rate limiting
|
||||||
|
- [ ] Caching
|
||||||
|
- [ ] Performance optimization
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
- All async operations must have error handling
|
||||||
|
- No hardcoded credentials
|
||||||
|
- All endpoints must validate input
|
||||||
|
- All database operations must use transactions where appropriate
|
||||||
|
- Test coverage minimum 80%
|
||||||
|
- No TypeScript `any` types / Python type hints required
|
||||||
|
|
||||||
|
## Working Process
|
||||||
|
1. Read this file and prd.json
|
||||||
|
2. Select highest priority feature with passes=false
|
||||||
|
3. Write failing tests first
|
||||||
|
4. Implement minimal code to pass
|
||||||
|
5. Verify: `npm run build && npm run test && npm run lint`
|
||||||
|
6. If fail: fix and retry
|
||||||
|
7. If pass: commit with descriptive message
|
||||||
|
8. Append progress to progress.txt
|
||||||
|
9. Update prd.json feature.passes = true
|
||||||
|
10. Repeat until all features complete
|
||||||
|
|
||||||
|
## Abort Conditions
|
||||||
|
Output `<promise>ABORT_BLOCKED</promise>` if:
|
||||||
|
- Circular dependency cannot be resolved after 5 attempts
|
||||||
|
- External API required but unavailable
|
||||||
|
- Fundamental architecture change needed
|
||||||
|
- After 15 iterations on same feature without progress
|
||||||
|
|
||||||
|
Document blocking issue in progress.txt before aborting.
|
||||||
|
|
||||||
|
## Safety
|
||||||
|
- Never modify files outside project directory
|
||||||
|
- Never use sudo
|
||||||
|
- Never store real credentials
|
||||||
|
- Always use .env for configuration
|
||||||
|
- Commit frequently
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Appendix B: Troubleshooting
|
||||||
|
|
||||||
|
### "Claude keeps stopping early"
|
||||||
|
|
||||||
|
**Cause**: Completion promise detected incorrectly or unclear criteria
|
||||||
|
**Fix**: Make completion criteria more specific, use unique promise text
|
||||||
|
|
||||||
|
### "Tests keep failing in loop"
|
||||||
|
|
||||||
|
**Cause**: Breaking changes accumulating
|
||||||
|
**Fix**: Add stronger "CI green" requirement, reduce iteration count, add checkpoint validation
|
||||||
|
|
||||||
|
### "Context getting too large"
|
||||||
|
|
||||||
|
**Cause**: Too much history accumulating
|
||||||
|
**Fix**: Use phases with fresh context each, summarize progress.txt periodically
|
||||||
|
|
||||||
|
### "Ralph taking wrong direction"
|
||||||
|
|
||||||
|
**Cause**: Ambiguous requirements
|
||||||
|
**Fix**: Add explicit constraints, use the "sign next to slide" pattern - add guardrails for specific failure modes
|
||||||
|
|
||||||
|
### "Loop running forever"
|
||||||
|
|
||||||
|
**Cause**: Impossible completion criteria
|
||||||
|
**Fix**: Always set --max-iterations, add abort conditions, monitor manually
|
||||||
|
|
||||||
|
### "Costs spiraling"
|
||||||
|
|
||||||
|
**Cause**: Large context, too many iterations
|
||||||
|
**Fix**: Break into smaller phases, set strict iteration limits, use smaller models for simpler tasks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Framework version: 1.0*
|
||||||
|
*Last updated: January 2026*
|
||||||
|
*Based on techniques by Geoffrey Huntley, Matt Pocock, and the Claude Code community*
|
||||||
961
docs/guide.md
Normal file
961
docs/guide.md
Normal file
@@ -0,0 +1,961 @@
|
|||||||
|
# Ralph Method: Step-by-Step Implementation Guide
|
||||||
|
|
||||||
|
## From Idea to Deployed App Using 100% Vibe Coding
|
||||||
|
|
||||||
|
This guide walks you through the exact steps to go from "I have an app idea" to "Claude Code built it for me overnight."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview: The 7 Stages
|
||||||
|
|
||||||
|
| Stage | What You Do | Output |
|
||||||
|
|-------|-------------|--------|
|
||||||
|
| 1 | Dump your idea | Raw idea document |
|
||||||
|
| 2 | Expand into full spec | Structured requirements |
|
||||||
|
| 3 | Convert to machine PRD | PROMPT.md + prd.json |
|
||||||
|
| 4 | Set up project scaffold | Ready-to-run directory |
|
||||||
|
| 5 | Execute Phase 1 (Foundation) | Working skeleton |
|
||||||
|
| 6 | Execute remaining phases | Complete application |
|
||||||
|
| 7 | Review and polish | Production-ready code |
|
||||||
|
|
||||||
|
**Total human effort**: 1-3 hours of prompting and setup
|
||||||
|
**Total Ralph effort**: Hours to days of autonomous coding
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 1: Idea Dump (15-30 minutes)
|
||||||
|
|
||||||
|
### Step 1.1: Brain Dump
|
||||||
|
|
||||||
|
Open any text editor or chat with Claude/ChatGPT. Write everything in your head about the app. Don't organize, just dump.
|
||||||
|
|
||||||
|
**Prompt to use:**
|
||||||
|
|
||||||
|
```
|
||||||
|
I have an app idea. I'm going to brain dump everything about it.
|
||||||
|
Don't respond until I say "DONE". Just acknowledge each message.
|
||||||
|
|
||||||
|
[Then type everything: features, users, problems it solves, tech preferences,
|
||||||
|
things you've seen in other apps you like, random thoughts, everything]
|
||||||
|
|
||||||
|
DONE
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 1.2: Initial Structuring
|
||||||
|
|
||||||
|
After your dump, use this prompt:
|
||||||
|
|
||||||
|
```
|
||||||
|
Now organize what I described into these categories:
|
||||||
|
|
||||||
|
1. PROBLEM: What problem does this solve? Who has this problem?
|
||||||
|
2. SOLUTION: What is the app and how does it solve the problem?
|
||||||
|
3. USERS: Who are the primary users? What are their goals?
|
||||||
|
4. CORE FEATURES: What are the absolute must-have features for v1?
|
||||||
|
5. NICE-TO-HAVE: What features can wait for v2?
|
||||||
|
6. TECH PREFERENCES: Any specific technologies I mentioned or prefer?
|
||||||
|
7. CONSTRAINTS: Any limitations, requirements, or non-negotiables?
|
||||||
|
8. SIMILAR APPS: What existing apps is this similar to?
|
||||||
|
|
||||||
|
Output as a structured document I can save.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 1.3: Save Output
|
||||||
|
|
||||||
|
Save the response as `docs/idea-dump.md` in a new folder for your project.
|
||||||
|
|
||||||
|
**Checkpoint**: You should have a rough but organized document describing your app.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 2: Expand to Full Specification (30-60 minutes)
|
||||||
|
|
||||||
|
### Step 2.1: Architecture Classification
|
||||||
|
|
||||||
|
First, let the LLM identify what type of application this is:
|
||||||
|
|
||||||
|
```
|
||||||
|
Based on my app idea, classify this project:
|
||||||
|
|
||||||
|
1. APPLICATION TYPE: What kind of application is this?
|
||||||
|
- Web application (frontend + backend)
|
||||||
|
- Web frontend only (static/SPA)
|
||||||
|
- Backend API only
|
||||||
|
- Desktop application (Electron, Tauri, native)
|
||||||
|
- CLI tool
|
||||||
|
- Mobile app (native, React Native, Flutter)
|
||||||
|
- Library/package
|
||||||
|
- Script/automation
|
||||||
|
- Game
|
||||||
|
- Other (specify)
|
||||||
|
|
||||||
|
2. INTERFACE TYPES NEEDED: Based on the app type, what interfaces are relevant?
|
||||||
|
- REST API (web backends, mobile backends)
|
||||||
|
- GraphQL API (complex data relationships)
|
||||||
|
- IPC channels (desktop apps with multi-process)
|
||||||
|
- Module interfaces (libraries, internal boundaries)
|
||||||
|
- CLI arguments/flags (command-line tools)
|
||||||
|
- File formats (apps that save/load data)
|
||||||
|
- WebSocket/real-time (chat, live updates)
|
||||||
|
- System integrations (OS APIs, hardware, file system)
|
||||||
|
- Plugin architecture (extensible apps)
|
||||||
|
- None/minimal (simple scripts)
|
||||||
|
|
||||||
|
3. DATA PERSISTENCE: How will data be stored?
|
||||||
|
- Remote database (PostgreSQL, MySQL, MongoDB)
|
||||||
|
- Local database (SQLite, LevelDB)
|
||||||
|
- File-based (JSON, YAML, custom format)
|
||||||
|
- In-memory only
|
||||||
|
- Cloud storage (S3, etc.)
|
||||||
|
- No persistence needed
|
||||||
|
|
||||||
|
4. DEPLOYMENT MODEL:
|
||||||
|
- Cloud hosted (Vercel, AWS, GCP, etc.)
|
||||||
|
- Self-hosted server
|
||||||
|
- Desktop installer (Windows, macOS, Linux)
|
||||||
|
- Package registry (npm, PyPI, crates.io)
|
||||||
|
- App store (mobile)
|
||||||
|
- No deployment (local script)
|
||||||
|
|
||||||
|
Output your classification with brief justification for each choice.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.2: Feature Decomposition
|
||||||
|
|
||||||
|
Take your structured idea and expand each feature:
|
||||||
|
|
||||||
|
```
|
||||||
|
For each CORE FEATURE in my idea document, break it down into:
|
||||||
|
|
||||||
|
1. User Story: "As a [user], I want to [action] so that [benefit]"
|
||||||
|
2. Acceptance Criteria: Specific, testable conditions that prove it works
|
||||||
|
3. Data Required: What data/models does this feature need?
|
||||||
|
4. Interface Points: Based on the app type identified, what interfaces does this feature need?
|
||||||
|
- For web apps: API endpoints
|
||||||
|
- For desktop apps: IPC handlers or module functions
|
||||||
|
- For CLI tools: commands/subcommands and flags
|
||||||
|
- For libraries: public API functions/classes
|
||||||
|
5. UI/UX Components: What user-facing elements are needed (if applicable)?
|
||||||
|
|
||||||
|
Be specific and concrete. Each acceptance criterion must be binary (pass/fail).
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.3: Technical Decisions
|
||||||
|
|
||||||
|
Get explicit about the tech stack:
|
||||||
|
|
||||||
|
```
|
||||||
|
Based on my app requirements and the architecture classification, recommend a tech stack.
|
||||||
|
|
||||||
|
Consider:
|
||||||
|
- Application type: [from Step 2.1]
|
||||||
|
- My preferences: [your preferences, e.g., "TypeScript", "Python", "whatever is fastest", or "none"]
|
||||||
|
- Deployment target: [from Step 2.1, or your preference]
|
||||||
|
- Data persistence: [from Step 2.1]
|
||||||
|
|
||||||
|
For each technology choice, provide:
|
||||||
|
1. The specific technology/framework
|
||||||
|
2. Why it fits this project and architecture
|
||||||
|
3. The exact versions to use (current stable)
|
||||||
|
4. Any critical dependencies or companion tools
|
||||||
|
|
||||||
|
Also identify:
|
||||||
|
- Build tools needed
|
||||||
|
- Testing framework appropriate for this app type
|
||||||
|
- Linting/formatting tools
|
||||||
|
- CI/CD approach (if applicable)
|
||||||
|
|
||||||
|
Output as a tech-stack.md file.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.4: Data Model Design
|
||||||
|
|
||||||
|
```
|
||||||
|
Based on the features and persistence model identified, design the data structures:
|
||||||
|
|
||||||
|
For each model/entity:
|
||||||
|
1. Name
|
||||||
|
2. Fields with types
|
||||||
|
3. Relationships to other models
|
||||||
|
4. Validation rules
|
||||||
|
5. Example data
|
||||||
|
|
||||||
|
Adapt the format to the persistence type:
|
||||||
|
- For databases: include indexes, constraints, migrations approach
|
||||||
|
- For file-based: include file format specification, versioning strategy
|
||||||
|
- For in-memory: include initialization and state management approach
|
||||||
|
|
||||||
|
Output as a data specification.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.5: Interface Contract
|
||||||
|
|
||||||
|
```
|
||||||
|
Based on the interface types identified in Step 2.1, design the contracts:
|
||||||
|
|
||||||
|
FOR REST/GraphQL APIs:
|
||||||
|
- Method and path (e.g., POST /api/users)
|
||||||
|
- Request/response schemas
|
||||||
|
- Authentication requirements
|
||||||
|
- Error responses
|
||||||
|
|
||||||
|
FOR DESKTOP IPC:
|
||||||
|
- Channel names
|
||||||
|
- Message types and payloads
|
||||||
|
- Direction (main→renderer, renderer→main, bidirectional)
|
||||||
|
|
||||||
|
FOR CLI TOOLS:
|
||||||
|
- Commands and subcommands
|
||||||
|
- Flags and arguments with types
|
||||||
|
- Input/output formats
|
||||||
|
- Exit codes
|
||||||
|
|
||||||
|
FOR LIBRARIES:
|
||||||
|
- Public functions/classes/types
|
||||||
|
- Parameters and return types
|
||||||
|
- Error handling approach
|
||||||
|
- Usage examples
|
||||||
|
|
||||||
|
FOR FILE FORMATS:
|
||||||
|
- Schema/structure specification
|
||||||
|
- Versioning approach
|
||||||
|
- Migration between versions
|
||||||
|
|
||||||
|
Design only the interface types relevant to this application.
|
||||||
|
Group by feature area. Output as an interface specification.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 2.6: Save Everything
|
||||||
|
|
||||||
|
You should now have:
|
||||||
|
- `docs/idea-dump.md` (from Stage 1)
|
||||||
|
- `docs/architecture.md` (app type, interfaces, persistence, deployment)
|
||||||
|
- `docs/features.md` (feature breakdown with acceptance criteria)
|
||||||
|
- `docs/tech-stack.md` (technologies with versions)
|
||||||
|
- `docs/data-models.md` (data structures)
|
||||||
|
- `docs/interfaces.md` (API/IPC/CLI/library contracts as applicable)
|
||||||
|
|
||||||
|
**Checkpoint**: You have a complete human-readable specification tailored to your app type.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 3: Convert to Machine PRD (30-45 minutes)
|
||||||
|
|
||||||
|
### Step 3.1: Create PROMPT.md
|
||||||
|
|
||||||
|
This is the master file Ralph will read. Use this prompt:
|
||||||
|
|
||||||
|
```
|
||||||
|
Convert my specification documents into a PROMPT.md file for an AI coding agent.
|
||||||
|
|
||||||
|
Context from my architecture classification:
|
||||||
|
- Application type: [from Step 2.1]
|
||||||
|
- Interface types: [from Step 2.1]
|
||||||
|
- Persistence model: [from Step 2.1]
|
||||||
|
- Deployment model: [from Step 2.1]
|
||||||
|
|
||||||
|
Requirements for the PROMPT.md:
|
||||||
|
1. Single file that contains everything the agent needs
|
||||||
|
2. Tailored to the specific application type (not generic web app assumptions)
|
||||||
|
3. Clear completion criteria with exact commands to verify
|
||||||
|
4. Phased approach appropriate to this app type:
|
||||||
|
- Web apps: Foundation → Core → Integration → Polish
|
||||||
|
- Desktop apps: Foundation → Core UI → System Integration → Packaging
|
||||||
|
- CLI tools: Foundation → Commands → I/O Handling → Distribution
|
||||||
|
- Libraries: Foundation → Core API → Documentation → Publishing
|
||||||
|
- Adapt as needed for other types
|
||||||
|
5. Binary pass/fail acceptance criteria for every feature
|
||||||
|
6. Interface specifications appropriate to the app type
|
||||||
|
7. Explicit constraints and safety rules
|
||||||
|
8. Promise tags for completion signals
|
||||||
|
|
||||||
|
Use this structure:
|
||||||
|
|
||||||
|
# Project: [Name]
|
||||||
|
|
||||||
|
## Objective
|
||||||
|
[One sentence]
|
||||||
|
|
||||||
|
## Application Type
|
||||||
|
[Classification from Step 2.1]
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
[Exact versions]
|
||||||
|
|
||||||
|
## Completion Criteria
|
||||||
|
[Numbered list of verification commands appropriate to this app type]
|
||||||
|
|
||||||
|
## Phase 1: Foundation
|
||||||
|
[Setup tasks with acceptance criteria]
|
||||||
|
|
||||||
|
## Phase 2: Core [Features/UI/Commands/API - varies by app type]
|
||||||
|
[Each feature with binary acceptance]
|
||||||
|
|
||||||
|
## Phase 3: [Integration/System/I/O - varies by app type]
|
||||||
|
[External services, system integration, etc.]
|
||||||
|
|
||||||
|
## Phase 4: [Polish/Packaging/Publishing - varies by app type]
|
||||||
|
[Docs, distribution, optimization]
|
||||||
|
|
||||||
|
## Constraints
|
||||||
|
[Hard rules]
|
||||||
|
|
||||||
|
## Abort Conditions
|
||||||
|
[When to stop and signal]
|
||||||
|
|
||||||
|
## Working Process
|
||||||
|
[Step-by-step instructions for each iteration]
|
||||||
|
|
||||||
|
Include the promise tags:
|
||||||
|
- <promise>PROJECT_COMPLETE</promise> for full completion
|
||||||
|
- <promise>PHASE_N_COMPLETE</promise> for phase completion
|
||||||
|
- <promise>ABORT_BLOCKED</promise> for blocking issues
|
||||||
|
|
||||||
|
Here are my spec documents:
|
||||||
|
[Paste all your docs including architecture.md]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.2: Create prd.json
|
||||||
|
|
||||||
|
For granular progress tracking:
|
||||||
|
|
||||||
|
```
|
||||||
|
Create a prd.json file that tracks each feature as a separate item.
|
||||||
|
|
||||||
|
Format:
|
||||||
|
{
|
||||||
|
"project": "MyApp",
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"id": "unique-id",
|
||||||
|
"phase": 1,
|
||||||
|
"name": "Feature Name",
|
||||||
|
"description": "What it does",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Exact command or condition that proves completion",
|
||||||
|
"dependencies": ["other-feature-ids"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
||||||
|
Order by phase, then by priority within phase.
|
||||||
|
Include all features from my specification.
|
||||||
|
Set all "passes" to false initially.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.3: Create progress.txt Template
|
||||||
|
|
||||||
|
Create an empty file with header:
|
||||||
|
|
||||||
|
```
|
||||||
|
# Progress Log
|
||||||
|
# Format: [TIMESTAMP] [ITERATION] [STATUS] - [DETAILS]
|
||||||
|
# Agent: Append only, never modify previous entries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 3.4: Validate Your PRD
|
||||||
|
|
||||||
|
Final check prompt:
|
||||||
|
|
||||||
|
```
|
||||||
|
Review this PROMPT.md for an AI coding agent. Check for:
|
||||||
|
|
||||||
|
1. AMBIGUITY: Any requirements that aren't binary pass/fail?
|
||||||
|
2. MISSING COMMANDS: Every verification must have an exact command
|
||||||
|
3. DEPENDENCIES: Are phases ordered correctly?
|
||||||
|
4. COMPLETENESS: Can an agent build this without asking questions?
|
||||||
|
5. SAFETY: Are there guardrails against destructive actions?
|
||||||
|
|
||||||
|
List any issues found and suggest fixes.
|
||||||
|
|
||||||
|
[Paste your PROMPT.md]
|
||||||
|
```
|
||||||
|
|
||||||
|
Fix any issues identified.
|
||||||
|
|
||||||
|
**Checkpoint**: You have `PROMPT.md`, `prd.json`, and `progress.txt` ready.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 4: Project Scaffold Setup (15-30 minutes)
|
||||||
|
|
||||||
|
### Step 4.1: Create Directory Structure
|
||||||
|
|
||||||
|
Run these commands:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create project directory
|
||||||
|
mkdir my-app && cd my-app
|
||||||
|
|
||||||
|
# Initialize git (CRITICAL - Ralph uses git for memory)
|
||||||
|
git init
|
||||||
|
|
||||||
|
# Create core Ralph files
|
||||||
|
touch PROMPT.md
|
||||||
|
touch prd.json
|
||||||
|
touch progress.txt
|
||||||
|
|
||||||
|
# Create documentation directory
|
||||||
|
mkdir -p docs
|
||||||
|
|
||||||
|
# Create agent context directory (optional but recommended)
|
||||||
|
mkdir -p agent_docs
|
||||||
|
touch agent_docs/tech_stack.md
|
||||||
|
touch agent_docs/code_patterns.md
|
||||||
|
touch agent_docs/testing.md
|
||||||
|
|
||||||
|
# Create Claude Code config (optional)
|
||||||
|
touch CLAUDE.md
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4.2: Populate Files
|
||||||
|
|
||||||
|
Copy your generated content:
|
||||||
|
- Paste PROMPT.md content
|
||||||
|
- Paste prd.json content
|
||||||
|
- Paste progress.txt template
|
||||||
|
- Copy spec docs to `docs/`
|
||||||
|
|
||||||
|
### Step 4.3: Create .gitignore
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > .gitignore << 'EOF'
|
||||||
|
node_modules/
|
||||||
|
.env
|
||||||
|
.env.local
|
||||||
|
*.log
|
||||||
|
dist/
|
||||||
|
build/
|
||||||
|
coverage/
|
||||||
|
.DS_Store
|
||||||
|
__pycache__/
|
||||||
|
*.pyc
|
||||||
|
.venv/
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4.4: Create CLAUDE.md (Optional but Recommended)
|
||||||
|
|
||||||
|
This file gives Claude Code persistent instructions:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > CLAUDE.md << 'EOF'
|
||||||
|
# Claude Code Instructions
|
||||||
|
|
||||||
|
## Project Context
|
||||||
|
Read PROMPT.md for full requirements.
|
||||||
|
Read prd.json for feature tracking.
|
||||||
|
Append progress to progress.txt after each significant change.
|
||||||
|
|
||||||
|
## Working Rules
|
||||||
|
1. Always run tests before committing
|
||||||
|
2. Never commit failing code
|
||||||
|
3. Update prd.json when features complete
|
||||||
|
4. Use conventional commit messages
|
||||||
|
5. Ask no questions - make reasonable decisions
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
- Build: npm run build
|
||||||
|
- Test: npm run test
|
||||||
|
- Lint: npm run lint
|
||||||
|
- All: npm run build && npm run test && npm run lint
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4.5: Initial Commit
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
git commit -m "Initial project setup with Ralph configuration"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Checkpoint**: Your project directory is ready for Ralph.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 5: Execute Phase 1 - Foundation (1-3 hours automated)
|
||||||
|
|
||||||
|
### Step 5.1: Install Ralph Plugin
|
||||||
|
|
||||||
|
In Claude Code:
|
||||||
|
|
||||||
|
```
|
||||||
|
/plugin marketplace add anthropics/claude-code
|
||||||
|
/plugin install ralph-wiggum@claude-plugins-official
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5.2: Start Phase 1 Loop
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "Execute Phase 1 (Foundation) from PROMPT.md.
|
||||||
|
|
||||||
|
Read PROMPT.md for full context.
|
||||||
|
Read prd.json for feature tracking.
|
||||||
|
|
||||||
|
Work on Phase 1 items only. For each item:
|
||||||
|
1. Write tests first
|
||||||
|
2. Implement the feature
|
||||||
|
3. Verify tests pass
|
||||||
|
4. Update prd.json (set passes=true)
|
||||||
|
5. Commit with descriptive message
|
||||||
|
6. Append progress to progress.txt
|
||||||
|
|
||||||
|
Run verification after each feature:
|
||||||
|
npm run build && npm run test && npm run lint
|
||||||
|
|
||||||
|
When ALL Phase 1 features in prd.json have passes=true:
|
||||||
|
Output <promise>PHASE_1_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked after 10 attempts on same feature:
|
||||||
|
Document in progress.txt and output <promise>PHASE_1_BLOCKED</promise>" --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5.3: Monitor (Optional)
|
||||||
|
|
||||||
|
While Ralph runs, you can monitor:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Watch progress
|
||||||
|
tail -f progress.txt
|
||||||
|
|
||||||
|
# Watch git commits
|
||||||
|
watch -n 10 'git log --oneline -10'
|
||||||
|
|
||||||
|
# Check test status
|
||||||
|
watch -n 30 'npm test 2>&1 | tail -20'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 5.4: Handle Completion
|
||||||
|
|
||||||
|
**If PHASE_1_COMPLETE:**
|
||||||
|
```bash
|
||||||
|
# Review what was built
|
||||||
|
git log --oneline
|
||||||
|
npm run test
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Continue to Phase 2
|
||||||
|
```
|
||||||
|
|
||||||
|
**If PHASE_1_BLOCKED:**
|
||||||
|
```bash
|
||||||
|
# Check what blocked
|
||||||
|
cat progress.txt | tail -50
|
||||||
|
|
||||||
|
# Review the issue
|
||||||
|
# Manually fix or adjust PROMPT.md
|
||||||
|
# Restart Phase 1 with updated prompt
|
||||||
|
```
|
||||||
|
|
||||||
|
**Checkpoint**: Foundation is complete. You have a working project skeleton.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 6: Execute Remaining Phases (2-8 hours automated per phase)
|
||||||
|
|
||||||
|
### Step 6.1: Phase 2 - Core Features
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "Execute Phase 2 (Core Features) from PROMPT.md.
|
||||||
|
|
||||||
|
Phase 1 is complete. Now implement Phase 2 features.
|
||||||
|
|
||||||
|
Read PROMPT.md for requirements.
|
||||||
|
Read prd.json for feature list and status.
|
||||||
|
|
||||||
|
For each Phase 2 feature:
|
||||||
|
1. Check dependencies are met (Phase 1 complete)
|
||||||
|
2. Write comprehensive tests
|
||||||
|
3. Implement feature
|
||||||
|
4. Verify all tests pass
|
||||||
|
5. Update prd.json
|
||||||
|
6. Commit
|
||||||
|
7. Log to progress.txt
|
||||||
|
|
||||||
|
Verification command:
|
||||||
|
npm run build && npm run test && npm run lint
|
||||||
|
|
||||||
|
When ALL Phase 2 features pass:
|
||||||
|
Output <promise>PHASE_2_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked: <promise>PHASE_2_BLOCKED</promise>" --max-iterations 50 --completion-promise "PHASE_2_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6.2: Phase 3 - Integration
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "Execute Phase 3 (Integration) from PROMPT.md.
|
||||||
|
|
||||||
|
Phases 1-2 complete. Now implement Phase 3.
|
||||||
|
|
||||||
|
Focus on:
|
||||||
|
- External service integrations
|
||||||
|
- Authentication/Authorization
|
||||||
|
- Error handling
|
||||||
|
- Logging
|
||||||
|
|
||||||
|
For external services, use mocks in tests.
|
||||||
|
Document any API keys needed in .env.example.
|
||||||
|
|
||||||
|
When ALL Phase 3 features pass:
|
||||||
|
Output <promise>PHASE_3_COMPLETE</promise>" --max-iterations 40 --completion-promise "PHASE_3_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6.3: Phase 4 - Polish
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "Execute Phase 4 (Polish) from PROMPT.md.
|
||||||
|
|
||||||
|
Phases 1-3 complete. Final polish.
|
||||||
|
|
||||||
|
Tasks:
|
||||||
|
- Complete README.md with setup instructions
|
||||||
|
- Add API documentation
|
||||||
|
- Handle edge cases
|
||||||
|
- Add input validation
|
||||||
|
- Improve error messages
|
||||||
|
- Add any missing tests (target >80% coverage)
|
||||||
|
|
||||||
|
When done and all PROMPT.md completion criteria met:
|
||||||
|
Output <promise>PROJECT_COMPLETE</promise>" --max-iterations 30 --completion-promise "PROJECT_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 6.4: Overnight Batch (Alternative)
|
||||||
|
|
||||||
|
If you want all phases to run overnight:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# run-all-phases.sh
|
||||||
|
|
||||||
|
echo "Starting full build: $(date)"
|
||||||
|
|
||||||
|
# Phase 1
|
||||||
|
claude -p '/ralph-wiggum:ralph-loop "Execute Phase 1..." --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"'
|
||||||
|
|
||||||
|
# Phase 2
|
||||||
|
claude -p '/ralph-wiggum:ralph-loop "Execute Phase 2..." --max-iterations 50 --completion-promise "PHASE_2_COMPLETE"'
|
||||||
|
|
||||||
|
# Phase 3
|
||||||
|
claude -p '/ralph-wiggum:ralph-loop "Execute Phase 3..." --max-iterations 40 --completion-promise "PHASE_3_COMPLETE"'
|
||||||
|
|
||||||
|
# Phase 4
|
||||||
|
claude -p '/ralph-wiggum:ralph-loop "Execute Phase 4..." --max-iterations 30 --completion-promise "PROJECT_COMPLETE"'
|
||||||
|
|
||||||
|
echo "Build complete: $(date)"
|
||||||
|
```
|
||||||
|
|
||||||
|
Run before bed:
|
||||||
|
```bash
|
||||||
|
chmod +x run-all-phases.sh
|
||||||
|
nohup ./run-all-phases.sh > build.log 2>&1 &
|
||||||
|
```
|
||||||
|
|
||||||
|
**Checkpoint**: All phases complete. Full application built.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stage 7: Review and Polish (1-2 hours manual)
|
||||||
|
|
||||||
|
### Step 7.1: Full Verification
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run all checks
|
||||||
|
npm run build
|
||||||
|
npm run test
|
||||||
|
npm run lint
|
||||||
|
|
||||||
|
# Check coverage
|
||||||
|
npm run test -- --coverage
|
||||||
|
|
||||||
|
# Start the app and test manually
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7.2: Code Review
|
||||||
|
|
||||||
|
Review key files:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# See all files created
|
||||||
|
find . -name "*.ts" -o -name "*.js" -o -name "*.tsx" | head -50
|
||||||
|
|
||||||
|
# Review main entry point
|
||||||
|
cat src/index.ts # or equivalent
|
||||||
|
|
||||||
|
# Review a core feature
|
||||||
|
cat src/services/[main-service].ts
|
||||||
|
|
||||||
|
# Check test quality
|
||||||
|
cat tests/[main-test].test.ts
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7.3: Git Cleanup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# See all Ralph commits
|
||||||
|
git log --oneline
|
||||||
|
|
||||||
|
# Optional: squash into logical commits
|
||||||
|
git rebase -i HEAD~[number]
|
||||||
|
|
||||||
|
# Or create a clean branch
|
||||||
|
git checkout -b release/v1
|
||||||
|
git merge --squash main
|
||||||
|
git commit -m "v1.0.0 - Initial release"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7.4: Documentation Check
|
||||||
|
|
||||||
|
Verify README.md contains:
|
||||||
|
- [ ] Project description
|
||||||
|
- [ ] Prerequisites
|
||||||
|
- [ ] Installation steps
|
||||||
|
- [ ] Environment setup (.env.example)
|
||||||
|
- [ ] Running locally
|
||||||
|
- [ ] Running tests
|
||||||
|
- [ ] API documentation (or link to it)
|
||||||
|
- [ ] Deployment instructions
|
||||||
|
|
||||||
|
### Step 7.5: Security Scan
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check for secrets
|
||||||
|
git log -p | grep -i "password\|secret\|key\|token" | head -20
|
||||||
|
|
||||||
|
# Run security audit
|
||||||
|
npm audit # or equivalent for your stack
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 7.6: Final Fixes
|
||||||
|
|
||||||
|
If you find issues, you can run targeted Ralph loops:
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "Fix the following issues:
|
||||||
|
1. [Issue 1]
|
||||||
|
2. [Issue 2]
|
||||||
|
|
||||||
|
Run tests after each fix. Commit when green.
|
||||||
|
Output <promise>FIXES_COMPLETE</promise> when done." --max-iterations 10 --completion-promise "FIXES_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Checkpoint**: Production-ready application.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Commands Cheat Sheet
|
||||||
|
|
||||||
|
### Setup
|
||||||
|
```bash
|
||||||
|
mkdir my-app && cd my-app
|
||||||
|
git init
|
||||||
|
touch PROMPT.md prd.json progress.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ralph Plugin
|
||||||
|
```
|
||||||
|
/plugin install ralph-wiggum@claude-plugins-official
|
||||||
|
/ralph-wiggum:ralph-loop "<prompt>" --max-iterations N --completion-promise "TEXT"
|
||||||
|
/ralph-wiggum:cancel-ralph
|
||||||
|
```
|
||||||
|
|
||||||
|
### Monitoring
|
||||||
|
```bash
|
||||||
|
tail -f progress.txt
|
||||||
|
watch -n 10 'git log --oneline -5'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Recovery
|
||||||
|
```bash
|
||||||
|
/ralph-wiggum:cancel-ralph
|
||||||
|
git log --oneline -10
|
||||||
|
git reset --hard HEAD~N
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Time Estimates
|
||||||
|
|
||||||
|
| Stage | Human Time | Ralph Time |
|
||||||
|
|-------|-----------|------------|
|
||||||
|
| 1. Idea Dump | 15-30 min | - |
|
||||||
|
| 2. Expand Spec | 30-60 min | - |
|
||||||
|
| 3. Convert to PRD | 30-45 min | - |
|
||||||
|
| 4. Setup Scaffold | 15-30 min | - |
|
||||||
|
| 5. Phase 1 | 5 min | 1-3 hours |
|
||||||
|
| 6. Phases 2-4 | 15 min | 3-12 hours |
|
||||||
|
| 7. Review | 1-2 hours | - |
|
||||||
|
| **Total Human** | **3-5 hours** | - |
|
||||||
|
| **Total Ralph** | - | **4-15 hours** |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Prompts Library
|
||||||
|
|
||||||
|
### Brain Dump Prompt
|
||||||
|
```
|
||||||
|
I have an app idea. I'm going to brain dump everything about it.
|
||||||
|
Don't respond until I say "DONE". Just acknowledge each message.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Structuring Prompt
|
||||||
|
```
|
||||||
|
Organize what I described into: PROBLEM, SOLUTION, USERS, CORE FEATURES,
|
||||||
|
NICE-TO-HAVE, TECH PREFERENCES, CONSTRAINTS, SIMILAR APPS.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Feature Breakdown Prompt
|
||||||
|
```
|
||||||
|
For each feature, provide: User Story, Acceptance Criteria, Data Required,
|
||||||
|
API Endpoints, UI Components. Make acceptance criteria binary pass/fail.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tech Stack Prompt
|
||||||
|
```
|
||||||
|
Recommend a tech stack with exact versions. Consider [preferences].
|
||||||
|
Justify each choice.
|
||||||
|
```
|
||||||
|
|
||||||
|
### PROMPT.md Generation Prompt
|
||||||
|
```
|
||||||
|
Convert my specification into a PROMPT.md for an AI coding agent with:
|
||||||
|
phased approach, binary acceptance criteria, promise tags, and safety rules.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase Execution Prompt
|
||||||
|
```
|
||||||
|
Execute Phase N from PROMPT.md. Read prd.json for tracking.
|
||||||
|
Write tests first, implement, verify, update prd.json, commit, log progress.
|
||||||
|
Output <promise>PHASE_N_COMPLETE</promise> when done.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting Quick Fixes
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
|---------|----------|
|
||||||
|
| Ralph stops early | Check completion promise text matches exactly |
|
||||||
|
| Tests keep failing | Add "never commit failing code" to prompt |
|
||||||
|
| Wrong direction | Add specific constraints to PROMPT.md |
|
||||||
|
| Context too large | Break into smaller phases |
|
||||||
|
| Costs too high | Reduce --max-iterations, use phases |
|
||||||
|
| Loop infinite | Always set --max-iterations |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example: Complete Workflow
|
||||||
|
|
||||||
|
**Idea**: "A todo app with user accounts and team sharing"
|
||||||
|
|
||||||
|
**Stage 1 Output** (5 minutes):
|
||||||
|
```
|
||||||
|
PROBLEM: People need to manage tasks, existing apps are too complex
|
||||||
|
SOLUTION: Simple todo app with team sharing
|
||||||
|
USERS: Individuals, small teams
|
||||||
|
CORE FEATURES: Create todos, mark complete, share lists, user accounts
|
||||||
|
NICE-TO-HAVE: Due dates, labels, mobile app
|
||||||
|
TECH: TypeScript, prefer simple
|
||||||
|
```
|
||||||
|
|
||||||
|
**Stage 2 Output** (20 minutes):
|
||||||
|
- Architecture classification:
|
||||||
|
- App type: Web application (frontend + backend)
|
||||||
|
- Interfaces: REST API, WebSocket (for real-time sync)
|
||||||
|
- Persistence: Remote database (PostgreSQL)
|
||||||
|
- Deployment: Cloud hosted (Vercel + Railway)
|
||||||
|
- 4 core features broken into 12 acceptance criteria
|
||||||
|
- Tech stack: Node.js, Express, PostgreSQL, Prisma, Jest, React, Vite
|
||||||
|
- 5 data models: User, Team, List, Todo, TeamMember
|
||||||
|
- 15 API endpoints specified
|
||||||
|
|
||||||
|
**Stage 3 Output** (15 minutes):
|
||||||
|
- PROMPT.md: 200 lines with all phases (web app structure)
|
||||||
|
- prd.json: 12 features with acceptance criteria
|
||||||
|
|
||||||
|
**Stage 4** (10 minutes):
|
||||||
|
- Directory created, files populated, initial commit
|
||||||
|
|
||||||
|
**Stage 5-6** (overnight):
|
||||||
|
- Phase 1: 45 minutes, 8 iterations
|
||||||
|
- Phase 2: 3 hours, 24 iterations
|
||||||
|
- Phase 3: 2 hours, 18 iterations
|
||||||
|
- Phase 4: 1 hour, 12 iterations
|
||||||
|
- Total cost: ~$85
|
||||||
|
|
||||||
|
**Stage 7** (1 hour):
|
||||||
|
- All tests pass
|
||||||
|
- 84% coverage
|
||||||
|
- 3 minor fixes needed
|
||||||
|
- README complete
|
||||||
|
- Ready to deploy
|
||||||
|
|
||||||
|
**Total human time**: ~2 hours
|
||||||
|
**Total elapsed time**: ~10 hours (mostly overnight)
|
||||||
|
**Total cost**: ~$90
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example: Desktop App Workflow
|
||||||
|
|
||||||
|
**Idea**: "A markdown note-taking app with local storage and vim keybindings"
|
||||||
|
|
||||||
|
**Stage 1 Output** (5 minutes):
|
||||||
|
```
|
||||||
|
PROBLEM: Existing note apps are bloated or cloud-dependent
|
||||||
|
SOLUTION: Fast local markdown editor with vim motions
|
||||||
|
USERS: Developers, writers who know vim
|
||||||
|
CORE FEATURES: Create/edit notes, vim keybindings, local file storage, search
|
||||||
|
NICE-TO-HAVE: Plugins, sync, mobile companion
|
||||||
|
TECH: Prefer Rust or TypeScript, must be fast
|
||||||
|
```
|
||||||
|
|
||||||
|
**Stage 2 Output** (25 minutes):
|
||||||
|
- Architecture classification:
|
||||||
|
- App type: Desktop application (Tauri)
|
||||||
|
- Interfaces: IPC channels (Rust backend ↔ React frontend), File formats (markdown + metadata JSON)
|
||||||
|
- Persistence: File-based (markdown files in user directory)
|
||||||
|
- Deployment: Desktop installer (Windows, macOS, Linux)
|
||||||
|
- 4 core features broken into 10 acceptance criteria
|
||||||
|
- Tech stack: Tauri 2.0, Rust, React, TypeScript, CodeMirror 6, Vitest
|
||||||
|
- 3 data structures: Note (file), NoteMetadata (index), AppConfig
|
||||||
|
- 8 IPC channels specified, file format documented
|
||||||
|
|
||||||
|
**Stage 3 Output** (15 minutes):
|
||||||
|
- PROMPT.md: 180 lines with desktop-appropriate phases:
|
||||||
|
- Phase 1: Foundation (Tauri setup, file system, config)
|
||||||
|
- Phase 2: Core UI (editor, vim bindings, note list)
|
||||||
|
- Phase 3: System Integration (file watching, search indexing)
|
||||||
|
- Phase 4: Packaging (installers, auto-update, icons)
|
||||||
|
- prd.json: 10 features tracked
|
||||||
|
|
||||||
|
**Stage 4** (10 minutes):
|
||||||
|
- Tauri project initialized, files populated, initial commit
|
||||||
|
|
||||||
|
**Stage 5-6** (overnight):
|
||||||
|
- Phase 1: 30 minutes, 6 iterations
|
||||||
|
- Phase 2: 4 hours, 32 iterations (vim bindings complex)
|
||||||
|
- Phase 3: 2 hours, 16 iterations
|
||||||
|
- Phase 4: 1.5 hours, 14 iterations
|
||||||
|
- Total cost: ~$120
|
||||||
|
|
||||||
|
**Stage 7** (1.5 hours):
|
||||||
|
- All tests pass
|
||||||
|
- App launches on all 3 platforms
|
||||||
|
- Vim bindings verified manually
|
||||||
|
- Installers build successfully
|
||||||
|
|
||||||
|
**Total human time**: ~2.5 hours
|
||||||
|
**Total elapsed time**: ~11 hours
|
||||||
|
**Total cost**: ~$130
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Guide version: 1.0*
|
||||||
|
*Works with: Claude Code + Ralph Wiggum plugin*
|
||||||
|
*Last updated: January 2026*
|
||||||
24
package.json
Normal file
24
package.json
Normal file
@@ -0,0 +1,24 @@
|
|||||||
|
{
|
||||||
|
"name": "ralph-vibe",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "Generate Ralph Method project scaffolds with AI-powered research",
|
||||||
|
"type": "module",
|
||||||
|
"bin": {
|
||||||
|
"ralph-vibe": "./dist/index.js"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"build": "tsup src/index.ts --format esm --dts",
|
||||||
|
"dev": "tsup src/index.ts --format esm --watch",
|
||||||
|
"test": "vitest run",
|
||||||
|
"test:watch": "vitest",
|
||||||
|
"lint": "eslint src --ext .ts",
|
||||||
|
"typecheck": "tsc --noEmit",
|
||||||
|
"prepublishOnly": "npm run build && npm run test && npm run lint"
|
||||||
|
},
|
||||||
|
"keywords": ["cli", "ai", "claude", "vibe-coding", "ralph-method"],
|
||||||
|
"author": "",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=20.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
141
prd.json
Normal file
141
prd.json
Normal file
@@ -0,0 +1,141 @@
|
|||||||
|
{
|
||||||
|
"project": "ralph-prd-generator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"id": "config-management",
|
||||||
|
"phase": 1,
|
||||||
|
"name": "API Key Management",
|
||||||
|
"description": "Store and retrieve API keys securely",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe init stores keys and ralph-vibe new fails gracefully without keys"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "cli-framework",
|
||||||
|
"phase": 1,
|
||||||
|
"name": "CLI Framework",
|
||||||
|
"description": "Commander.js setup with all commands stubbed",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe --help shows all commands, ralph-vibe init/new/validate/research exist"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "claude-client",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Claude API Client",
|
||||||
|
"description": "Anthropic SDK integration with retry logic",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Can send prompt to Claude and receive response, retries on failure"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "perplexity-client",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Perplexity API Client",
|
||||||
|
"description": "Perplexity REST API integration",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Can search Perplexity and parse response with sources"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "architecture-classification",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Architecture Classification",
|
||||||
|
"description": "Claude prompt for classifying app type",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Given idea text, returns valid Architecture JSON"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "research-queries",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Research Query Generation",
|
||||||
|
"description": "Generate Perplexity queries from architecture",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Given architecture, generates 4-6 relevant search queries"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "spec-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Specification Generation",
|
||||||
|
"description": "Generate features, data models, interfaces from idea plus research",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Produces valid Specification object with all required fields"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "prd-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "PRD Generation",
|
||||||
|
"description": "Generate PROMPT.md, prd.json, GUIDE.md",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Generated PROMPT.md contains all required sections and promise tags"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "scaffold-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Project Scaffold",
|
||||||
|
"description": "Create directory structure and all files",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe new test-app creates complete directory with all files"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "interactive-flow",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Interactive Prompts",
|
||||||
|
"description": "Inquirer.js prompts for user confirmation",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "User can confirm or modify architecture classification interactively"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "validation-command",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Validate Command",
|
||||||
|
"description": "Validate existing PROMPT.md files",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe validate ./PROMPT.md reports issues or confirms valid"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "research-command",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Standalone Research",
|
||||||
|
"description": "Research a topic without full generation",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe research topic outputs formatted research"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "dry-run",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Dry Run Mode",
|
||||||
|
"description": "Show what would be generated without writing",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "The --dry-run flag shows output without creating files"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "documentation",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Documentation",
|
||||||
|
"description": "README, help text, examples",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "README.md covers all commands, examples directory exists"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "packaging",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "npm Packaging",
|
||||||
|
"description": "Package ready for npm publish",
|
||||||
|
"priority": 5,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "npm pack succeeds, npm publish --dry-run succeeds"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
6
progress.txt
Normal file
6
progress.txt
Normal file
@@ -0,0 +1,6 @@
|
|||||||
|
# Progress Log - Ralph PRD Generator
|
||||||
|
# Format: [TIMESTAMP] [ITERATION] [STATUS] - [DETAILS]
|
||||||
|
# Agent: Append only, never modify previous entries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
788
ralph-implementation-instructions.md
Normal file
788
ralph-implementation-instructions.md
Normal file
@@ -0,0 +1,788 @@
|
|||||||
|
# Ralph PRD Generator: Implementation Instructions
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
You will use the Ralph Method to build the Ralph PRD Generator itself. This is bootstrapping - using the technique to build the tool that automates the technique.
|
||||||
|
|
||||||
|
**Time estimate**: 2-4 hours setup, 8-16 hours autonomous Ralph execution
|
||||||
|
**Cost estimate**: $150-300 in API costs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before starting, ensure you have:
|
||||||
|
|
||||||
|
- [ ] Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
|
||||||
|
- [ ] Ralph Wiggum plugin installed (instructions below)
|
||||||
|
- [ ] Claude API key with sufficient credits (~$300 recommended)
|
||||||
|
- [ ] Perplexity API key (for testing the app, not for building it)
|
||||||
|
- [ ] Node.js 20+ installed
|
||||||
|
- [ ] Git installed
|
||||||
|
- [ ] jq installed (required by Ralph plugin on some systems)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 1: Create Project Directory
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir ralph-vibe
|
||||||
|
cd ralph-vibe
|
||||||
|
git init
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 2: Download the Specification Files
|
||||||
|
|
||||||
|
From the Claude conversation, download:
|
||||||
|
|
||||||
|
1. `ralph-prd-generator-spec.md` → save as `ralph-vibe/PROMPT.md`
|
||||||
|
2. `ralph-method-framework.md` → save as `ralph-vibe/docs/framework.md`
|
||||||
|
3. `ralph-method-step-by-step-guide.md` → save as `ralph-vibe/docs/guide.md`
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p docs
|
||||||
|
# Then manually save the downloaded files to these locations
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Create Supporting Files
|
||||||
|
|
||||||
|
Run each of these commands in your terminal:
|
||||||
|
|
||||||
|
### 3.1 Create prd.json
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > prd.json << 'ENDJSON'
|
||||||
|
{
|
||||||
|
"project": "ralph-prd-generator",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"features": [
|
||||||
|
{
|
||||||
|
"id": "config-management",
|
||||||
|
"phase": 1,
|
||||||
|
"name": "API Key Management",
|
||||||
|
"description": "Store and retrieve API keys securely",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe init stores keys and ralph-vibe new fails gracefully without keys"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "cli-framework",
|
||||||
|
"phase": 1,
|
||||||
|
"name": "CLI Framework",
|
||||||
|
"description": "Commander.js setup with all commands stubbed",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe --help shows all commands, ralph-vibe init/new/validate/research exist"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "claude-client",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Claude API Client",
|
||||||
|
"description": "Anthropic SDK integration with retry logic",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Can send prompt to Claude and receive response, retries on failure"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "perplexity-client",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Perplexity API Client",
|
||||||
|
"description": "Perplexity REST API integration",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Can search Perplexity and parse response with sources"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "architecture-classification",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Architecture Classification",
|
||||||
|
"description": "Claude prompt for classifying app type",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Given idea text, returns valid Architecture JSON"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "research-queries",
|
||||||
|
"phase": 2,
|
||||||
|
"name": "Research Query Generation",
|
||||||
|
"description": "Generate Perplexity queries from architecture",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Given architecture, generates 4-6 relevant search queries"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "spec-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Specification Generation",
|
||||||
|
"description": "Generate features, data models, interfaces from idea plus research",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Produces valid Specification object with all required fields"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "prd-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "PRD Generation",
|
||||||
|
"description": "Generate PROMPT.md, prd.json, GUIDE.md",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "Generated PROMPT.md contains all required sections and promise tags"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "scaffold-generation",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Project Scaffold",
|
||||||
|
"description": "Create directory structure and all files",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe new test-app creates complete directory with all files"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "interactive-flow",
|
||||||
|
"phase": 3,
|
||||||
|
"name": "Interactive Prompts",
|
||||||
|
"description": "Inquirer.js prompts for user confirmation",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "User can confirm or modify architecture classification interactively"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "validation-command",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Validate Command",
|
||||||
|
"description": "Validate existing PROMPT.md files",
|
||||||
|
"priority": 1,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe validate ./PROMPT.md reports issues or confirms valid"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "research-command",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Standalone Research",
|
||||||
|
"description": "Research a topic without full generation",
|
||||||
|
"priority": 2,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "ralph-vibe research topic outputs formatted research"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "dry-run",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Dry Run Mode",
|
||||||
|
"description": "Show what would be generated without writing",
|
||||||
|
"priority": 3,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "The --dry-run flag shows output without creating files"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "documentation",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "Documentation",
|
||||||
|
"description": "README, help text, examples",
|
||||||
|
"priority": 4,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "README.md covers all commands, examples directory exists"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"id": "packaging",
|
||||||
|
"phase": 4,
|
||||||
|
"name": "npm Packaging",
|
||||||
|
"description": "Package ready for npm publish",
|
||||||
|
"priority": 5,
|
||||||
|
"passes": false,
|
||||||
|
"acceptance": "npm pack succeeds, npm publish --dry-run succeeds"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
ENDJSON
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.2 Create progress.txt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > progress.txt << 'ENDFILE'
|
||||||
|
# Progress Log - Ralph PRD Generator
|
||||||
|
# Format: [TIMESTAMP] [ITERATION] [STATUS] - [DETAILS]
|
||||||
|
# Agent: Append only, never modify previous entries
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
ENDFILE
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.3 Create CLAUDE.md
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > CLAUDE.md << 'ENDFILE'
|
||||||
|
# Claude Code Configuration
|
||||||
|
|
||||||
|
## Project Context
|
||||||
|
|
||||||
|
This is the Ralph PRD Generator - a CLI tool that generates Ralph Method project scaffolds.
|
||||||
|
|
||||||
|
Read PROMPT.md for full requirements.
|
||||||
|
Read prd.json for feature tracking.
|
||||||
|
Append progress to progress.txt after each significant change.
|
||||||
|
|
||||||
|
## Key Files
|
||||||
|
|
||||||
|
- PROMPT.md: Full specification - this is your primary reference
|
||||||
|
- prd.json: Feature tracking with acceptance criteria
|
||||||
|
- progress.txt: Append-only progress log
|
||||||
|
- docs/framework.md: Ralph Method framework reference
|
||||||
|
- docs/guide.md: Step-by-step guide reference
|
||||||
|
|
||||||
|
## Tech Stack
|
||||||
|
|
||||||
|
- TypeScript with strict mode
|
||||||
|
- Node.js 20+
|
||||||
|
- Commander.js for CLI
|
||||||
|
- Inquirer.js for prompts
|
||||||
|
- Anthropic SDK for Claude
|
||||||
|
- Native fetch for Perplexity
|
||||||
|
- Vitest for testing
|
||||||
|
- tsup for building
|
||||||
|
|
||||||
|
## Working Rules
|
||||||
|
|
||||||
|
1. Always run tests before committing
|
||||||
|
2. Never commit failing code
|
||||||
|
3. Update prd.json when features complete by setting passes to true
|
||||||
|
4. Use conventional commit messages
|
||||||
|
5. Make reasonable decisions - do not ask questions
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
- Build: npm run build
|
||||||
|
- Test: npm run test
|
||||||
|
- Lint: npm run lint
|
||||||
|
- All: npm run build && npm run test && npm run lint
|
||||||
|
- Dev: npm run dev
|
||||||
|
|
||||||
|
## Directory Structure
|
||||||
|
|
||||||
|
src/
|
||||||
|
index.ts # CLI entry point
|
||||||
|
commands/ # Command handlers
|
||||||
|
init.ts
|
||||||
|
new.ts
|
||||||
|
validate.ts
|
||||||
|
research.ts
|
||||||
|
clients/ # API clients
|
||||||
|
claude.ts
|
||||||
|
perplexity.ts
|
||||||
|
generators/ # Generation logic
|
||||||
|
architecture.ts
|
||||||
|
specification.ts
|
||||||
|
prd.ts
|
||||||
|
scaffold.ts
|
||||||
|
prompts/ # Prompt templates
|
||||||
|
templates.ts
|
||||||
|
types/ # TypeScript types
|
||||||
|
index.ts
|
||||||
|
utils/ # Utilities
|
||||||
|
config.ts
|
||||||
|
files.ts
|
||||||
|
logger.ts
|
||||||
|
|
||||||
|
## API Keys for Testing
|
||||||
|
|
||||||
|
During development, use environment variables:
|
||||||
|
- CLAUDE_API_KEY
|
||||||
|
- PERPLEXITY_API_KEY
|
||||||
|
|
||||||
|
Never commit real keys. Use .env.local which is gitignored.
|
||||||
|
ENDFILE
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.4 Create .gitignore
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > .gitignore << 'ENDFILE'
|
||||||
|
node_modules/
|
||||||
|
dist/
|
||||||
|
.env
|
||||||
|
.env.local
|
||||||
|
*.log
|
||||||
|
coverage/
|
||||||
|
.DS_Store
|
||||||
|
*.tgz
|
||||||
|
RALPH_TASK.md
|
||||||
|
phase*-prompt.txt
|
||||||
|
ENDFILE
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3.5 Create package.json
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > package.json << 'ENDJSON'
|
||||||
|
{
|
||||||
|
"name": "ralph-vibe",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"description": "Generate Ralph Method project scaffolds with AI-powered research",
|
||||||
|
"type": "module",
|
||||||
|
"bin": {
|
||||||
|
"ralph-vibe": "./dist/index.js"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"build": "tsup src/index.ts --format esm --dts",
|
||||||
|
"dev": "tsup src/index.ts --format esm --watch",
|
||||||
|
"test": "vitest run",
|
||||||
|
"test:watch": "vitest",
|
||||||
|
"lint": "eslint src --ext .ts",
|
||||||
|
"typecheck": "tsc --noEmit",
|
||||||
|
"prepublishOnly": "npm run build && npm run test && npm run lint"
|
||||||
|
},
|
||||||
|
"keywords": ["cli", "ai", "claude", "vibe-coding", "ralph-method"],
|
||||||
|
"author": "",
|
||||||
|
"license": "MIT",
|
||||||
|
"engines": {
|
||||||
|
"node": ">=20.0.0"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
ENDJSON
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Create Phase Prompt Files
|
||||||
|
|
||||||
|
Create separate files for each phase prompt. This avoids shell escaping issues entirely.
|
||||||
|
|
||||||
|
### 4.1 Phase 1 Prompt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > phase1-prompt.txt << 'ENDPROMPT'
|
||||||
|
Execute Phase 1 - Foundation from PROMPT.md.
|
||||||
|
|
||||||
|
You are building the Ralph PRD Generator CLI tool.
|
||||||
|
|
||||||
|
Read PROMPT.md for full specification.
|
||||||
|
Read prd.json for feature tracking.
|
||||||
|
Read CLAUDE.md for project configuration.
|
||||||
|
|
||||||
|
Phase 1 tasks:
|
||||||
|
1. Set up TypeScript project with all dependencies
|
||||||
|
2. Configure tsup, vitest, eslint
|
||||||
|
3. Implement CLI framework with Commander.js
|
||||||
|
4. Implement config management for API key storage
|
||||||
|
5. Create basic project structure
|
||||||
|
6. Write tests for config and CLI
|
||||||
|
|
||||||
|
For each feature:
|
||||||
|
1. Write tests first
|
||||||
|
2. Implement the feature
|
||||||
|
3. Run: npm run build && npm run test && npm run lint
|
||||||
|
4. If all pass, update prd.json by setting passes to true for completed features
|
||||||
|
5. Commit with descriptive message
|
||||||
|
6. Append progress to progress.txt
|
||||||
|
|
||||||
|
When ALL Phase 1 features in prd.json have passes set to true:
|
||||||
|
Output <promise>PHASE_1_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked after 10 attempts on same issue:
|
||||||
|
Document in progress.txt and output <promise>PHASE_1_BLOCKED</promise>
|
||||||
|
ENDPROMPT
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 Phase 2 Prompt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > phase2-prompt.txt << 'ENDPROMPT'
|
||||||
|
Execute Phase 2 - Core API Integration from PROMPT.md.
|
||||||
|
|
||||||
|
Phase 1 is complete. Now implement Phase 2.
|
||||||
|
|
||||||
|
Read PROMPT.md for API specifications.
|
||||||
|
Read prd.json for Phase 2 features.
|
||||||
|
|
||||||
|
Phase 2 tasks:
|
||||||
|
1. Claude API client with Anthropic SDK
|
||||||
|
2. Perplexity API client with fetch
|
||||||
|
3. Architecture classification prompt and parser
|
||||||
|
4. Research query generation
|
||||||
|
5. Tests for all API clients
|
||||||
|
|
||||||
|
API Integration notes:
|
||||||
|
- Use environment variables for API keys during testing
|
||||||
|
- Implement retry logic with 3 attempts and exponential backoff
|
||||||
|
- Handle rate limits gracefully
|
||||||
|
- Parse JSON responses safely
|
||||||
|
|
||||||
|
For each feature:
|
||||||
|
1. Write tests first using mocked API calls
|
||||||
|
2. Implement the feature
|
||||||
|
3. Verify: npm run build && npm run test && npm run lint
|
||||||
|
4. Update prd.json when feature passes
|
||||||
|
5. Commit and log progress
|
||||||
|
|
||||||
|
When ALL Phase 2 features pass:
|
||||||
|
Output <promise>PHASE_2_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked:
|
||||||
|
Output <promise>PHASE_2_BLOCKED</promise>
|
||||||
|
ENDPROMPT
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.3 Phase 3 Prompt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > phase3-prompt.txt << 'ENDPROMPT'
|
||||||
|
Execute Phase 3 - Generation Pipeline from PROMPT.md.
|
||||||
|
|
||||||
|
Phases 1-2 complete. Now implement the core generation pipeline.
|
||||||
|
|
||||||
|
Phase 3 tasks:
|
||||||
|
1. Specification generation from idea plus research
|
||||||
|
2. PRD generation including PROMPT.md, prd.json, GUIDE.md
|
||||||
|
3. Project scaffold creation
|
||||||
|
4. Interactive prompts with Inquirer.js
|
||||||
|
5. Full pipeline integration from idea to scaffold
|
||||||
|
|
||||||
|
Key requirements:
|
||||||
|
- Generated PROMPT.md must follow Ralph Method structure
|
||||||
|
- Generated files must be app-type aware for web, desktop, CLI, and other types
|
||||||
|
- prd.json must have all features with passes set to false
|
||||||
|
- GUIDE.md must be personalized to the project
|
||||||
|
- User must be able to confirm or override classifications
|
||||||
|
|
||||||
|
Test with a sample idea:
|
||||||
|
A CLI tool that converts markdown to PDF with syntax highlighting
|
||||||
|
|
||||||
|
When ALL Phase 3 features pass:
|
||||||
|
Output <promise>PHASE_3_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked:
|
||||||
|
Output <promise>PHASE_3_BLOCKED</promise>
|
||||||
|
ENDPROMPT
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 Phase 4 Prompt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > phase4-prompt.txt << 'ENDPROMPT'
|
||||||
|
Execute Phase 4 - Polish from PROMPT.md.
|
||||||
|
|
||||||
|
Phases 1-3 complete. Final polish and packaging.
|
||||||
|
|
||||||
|
Phase 4 tasks:
|
||||||
|
1. Validate command to check existing PROMPT.md files
|
||||||
|
2. Standalone research command
|
||||||
|
3. Dry-run mode with --dry-run flag
|
||||||
|
4. Comprehensive documentation in README.md
|
||||||
|
5. npm packaging with npm pack and npm publish --dry-run
|
||||||
|
6. Examples directory with sample outputs
|
||||||
|
|
||||||
|
Documentation must include:
|
||||||
|
- Installation instructions
|
||||||
|
- All commands with examples
|
||||||
|
- Environment variable configuration
|
||||||
|
- Troubleshooting section
|
||||||
|
|
||||||
|
When ALL Phase 4 features pass AND all completion criteria from PROMPT.md are met:
|
||||||
|
Output <promise>PROJECT_COMPLETE</promise>
|
||||||
|
|
||||||
|
If blocked:
|
||||||
|
Output <promise>PHASE_4_BLOCKED</promise>
|
||||||
|
ENDPROMPT
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 5: Initial Commit
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add .
|
||||||
|
git commit -m "Initial Ralph scaffold for ralph-vibe"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 6: Install Ralph Wiggum Plugin
|
||||||
|
|
||||||
|
Open Claude Code:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
claude
|
||||||
|
```
|
||||||
|
|
||||||
|
Inside Claude Code, run:
|
||||||
|
|
||||||
|
```
|
||||||
|
/plugin marketplace add anthropics/claude-code
|
||||||
|
/plugin install ralph-wiggum@claude-plugins-official
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 7: Execute Phase 1
|
||||||
|
|
||||||
|
**Option A: Using the Ralph Plugin**
|
||||||
|
|
||||||
|
In Claude Code:
|
||||||
|
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "$(cat phase1-prompt.txt)" --max-iterations 30 --completion-promise "PHASE_1_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Using Raw Bash Loop**
|
||||||
|
|
||||||
|
If the plugin has issues, use this instead in your terminal:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
MAX=30
|
||||||
|
for i in $(seq 1 $MAX); do
|
||||||
|
echo "=== Iteration $i of $MAX ==="
|
||||||
|
cat phase1-prompt.txt | claude --print
|
||||||
|
|
||||||
|
# Check for completion
|
||||||
|
if grep -rq "PHASE_1_COMPLETE" . 2>/dev/null; then
|
||||||
|
echo "Phase 1 complete at iteration $i"
|
||||||
|
break
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check for blocked
|
||||||
|
if grep -rq "PHASE_1_BLOCKED" . 2>/dev/null; then
|
||||||
|
echo "Phase 1 blocked. Check progress.txt"
|
||||||
|
break
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Commit progress
|
||||||
|
git add -A
|
||||||
|
git diff --cached --quiet || git commit -m "Ralph Phase 1 iteration $i"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
### Verify Phase 1
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
npm run test
|
||||||
|
./dist/index.js --help
|
||||||
|
# Should show help text with init, new, validate, research commands
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 8: Execute Phase 2
|
||||||
|
|
||||||
|
**Option A: Plugin**
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "$(cat phase2-prompt.txt)" --max-iterations 40 --completion-promise "PHASE_2_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Bash Loop**
|
||||||
|
```bash
|
||||||
|
MAX=40
|
||||||
|
for i in $(seq 1 $MAX); do
|
||||||
|
echo "=== Iteration $i of $MAX ==="
|
||||||
|
cat phase2-prompt.txt | claude --print
|
||||||
|
if grep -rq "PHASE_2_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
|
||||||
|
if grep -rq "PHASE_2_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
|
||||||
|
git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 2 iteration $i"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 9: Execute Phase 3
|
||||||
|
|
||||||
|
**Option A: Plugin**
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "$(cat phase3-prompt.txt)" --max-iterations 50 --completion-promise "PHASE_3_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Bash Loop**
|
||||||
|
```bash
|
||||||
|
MAX=50
|
||||||
|
for i in $(seq 1 $MAX); do
|
||||||
|
echo "=== Iteration $i of $MAX ==="
|
||||||
|
cat phase3-prompt.txt | claude --print
|
||||||
|
if grep -rq "PHASE_3_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
|
||||||
|
if grep -rq "PHASE_3_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
|
||||||
|
git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 3 iteration $i"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 10: Execute Phase 4
|
||||||
|
|
||||||
|
**Option A: Plugin**
|
||||||
|
```
|
||||||
|
/ralph-wiggum:ralph-loop "$(cat phase4-prompt.txt)" --max-iterations 30 --completion-promise "PROJECT_COMPLETE"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Option B: Bash Loop**
|
||||||
|
```bash
|
||||||
|
MAX=30
|
||||||
|
for i in $(seq 1 $MAX); do
|
||||||
|
echo "=== Iteration $i of $MAX ==="
|
||||||
|
cat phase4-prompt.txt | claude --print
|
||||||
|
if grep -rq "PROJECT_COMPLETE" . 2>/dev/null; then echo "Done"; break; fi
|
||||||
|
if grep -rq "PHASE_4_BLOCKED" . 2>/dev/null; then echo "Blocked"; break; fi
|
||||||
|
git add -A && git diff --cached --quiet || git commit -m "Ralph Phase 4 iteration $i"
|
||||||
|
done
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 11: Final Verification
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Build and test
|
||||||
|
npm run build
|
||||||
|
npm run test
|
||||||
|
npm run lint
|
||||||
|
|
||||||
|
# Set up API keys for testing
|
||||||
|
export CLAUDE_API_KEY="your-key"
|
||||||
|
export PERPLEXITY_API_KEY="your-key"
|
||||||
|
|
||||||
|
# Test initialization
|
||||||
|
./dist/index.js init
|
||||||
|
|
||||||
|
# Test with a real idea
|
||||||
|
echo "A CLI tool that converts markdown to PDF with syntax highlighting" > test-idea.txt
|
||||||
|
./dist/index.js new test-project --idea-file ./test-idea.txt
|
||||||
|
|
||||||
|
# Check output
|
||||||
|
ls -la test-project/
|
||||||
|
cat test-project/PROMPT.md
|
||||||
|
cat test-project/GUIDE.md
|
||||||
|
|
||||||
|
# Validate the generated PRD
|
||||||
|
./dist/index.js validate ./test-project/PROMPT.md
|
||||||
|
|
||||||
|
# Test research command
|
||||||
|
./dist/index.js research "Tauri 2.0 best practices 2026"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 12: Git Cleanup
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# See all commits
|
||||||
|
git log --oneline
|
||||||
|
|
||||||
|
# Optional: squash into logical commits
|
||||||
|
git rebase -i HEAD~N
|
||||||
|
|
||||||
|
# Suggested structure:
|
||||||
|
# feat: Phase 1 - CLI foundation and config
|
||||||
|
# feat: Phase 2 - Claude and Perplexity integration
|
||||||
|
# feat: Phase 3 - Generation pipeline
|
||||||
|
# feat: Phase 4 - Polish and packaging
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 13: Publish
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run prepublishOnly
|
||||||
|
npm publish
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overnight Batch Run
|
||||||
|
|
||||||
|
To run all phases unattended:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cat > run-all.sh << 'ENDSCRIPT'
|
||||||
|
#!/bin/bash
|
||||||
|
set -e
|
||||||
|
|
||||||
|
LOG="build-$(date +%Y%m%d-%H%M).log"
|
||||||
|
echo "Starting build: $(date)" | tee "$LOG"
|
||||||
|
|
||||||
|
run_phase() {
|
||||||
|
local phase=$1
|
||||||
|
local max=$2
|
||||||
|
local complete=$3
|
||||||
|
local blocked=$4
|
||||||
|
|
||||||
|
echo "=== Phase $phase ===" | tee -a "$LOG"
|
||||||
|
|
||||||
|
for i in $(seq 1 $max); do
|
||||||
|
echo "--- Iteration $i of $max ---" | tee -a "$LOG"
|
||||||
|
cat "phase${phase}-prompt.txt" | claude --print 2>&1 | tee -a "$LOG"
|
||||||
|
|
||||||
|
if grep -rq "$complete" . 2>/dev/null; then
|
||||||
|
echo "Phase $phase complete" | tee -a "$LOG"
|
||||||
|
git add -A && git commit -m "Phase $phase complete" --allow-empty
|
||||||
|
return 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
if grep -rq "$blocked" . 2>/dev/null; then
|
||||||
|
echo "Phase $phase blocked" | tee -a "$LOG"
|
||||||
|
return 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
git add -A && git diff --cached --quiet || git commit -m "Ralph Phase $phase iteration $i"
|
||||||
|
done
|
||||||
|
|
||||||
|
echo "Phase $phase max iterations reached" | tee -a "$LOG"
|
||||||
|
return 1
|
||||||
|
}
|
||||||
|
|
||||||
|
run_phase 1 30 "PHASE_1_COMPLETE" "PHASE_1_BLOCKED"
|
||||||
|
run_phase 2 40 "PHASE_2_COMPLETE" "PHASE_2_BLOCKED"
|
||||||
|
run_phase 3 50 "PHASE_3_COMPLETE" "PHASE_3_BLOCKED"
|
||||||
|
run_phase 4 30 "PROJECT_COMPLETE" "PHASE_4_BLOCKED"
|
||||||
|
|
||||||
|
echo "Build complete: $(date)" | tee -a "$LOG"
|
||||||
|
ENDSCRIPT
|
||||||
|
|
||||||
|
chmod +x run-all.sh
|
||||||
|
nohup ./run-all.sh > overnight.log 2>&1 &
|
||||||
|
echo "Running in background. Check overnight.log for progress."
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
| Problem | Solution |
|
||||||
|
|---------|----------|
|
||||||
|
| Plugin shell errors | Use the bash loop method instead |
|
||||||
|
| Completion not detected | Check that promise tags are output without the angle brackets being escaped |
|
||||||
|
| API rate limits | Add sleep 2 between iterations in the bash loop |
|
||||||
|
| Tests fail on API calls | Ensure all API calls are mocked in tests |
|
||||||
|
| TypeScript errors | Run npm run typecheck to see all errors |
|
||||||
|
| Phase blocked | Check progress.txt, fix manually, restart phase |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Summary Checklist
|
||||||
|
|
||||||
|
- [ ] Created ralph-vibe directory
|
||||||
|
- [ ] Downloaded and placed PROMPT.md
|
||||||
|
- [ ] Created prd.json
|
||||||
|
- [ ] Created progress.txt
|
||||||
|
- [ ] Created CLAUDE.md
|
||||||
|
- [ ] Created .gitignore
|
||||||
|
- [ ] Created package.json
|
||||||
|
- [ ] Created phase1-prompt.txt
|
||||||
|
- [ ] Created phase2-prompt.txt
|
||||||
|
- [ ] Created phase3-prompt.txt
|
||||||
|
- [ ] Created phase4-prompt.txt
|
||||||
|
- [ ] Initial git commit
|
||||||
|
- [ ] Installed Ralph plugin or using bash loop
|
||||||
|
- [ ] Phase 1 complete - ralph-vibe --help works
|
||||||
|
- [ ] Phase 2 complete - API clients work
|
||||||
|
- [ ] Phase 3 complete - ralph-vibe new works
|
||||||
|
- [ ] Phase 4 complete - all features work
|
||||||
|
- [ ] Final verification passed
|
||||||
|
- [ ] Published to npm
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*Implementation Guide Version: 2.0*
|
||||||
|
*Shell-safe prompts using file-based approach*
|
||||||
Reference in New Issue
Block a user