its-consulting/ralph-claude-code
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add ralph-import command for PRD conversion using Claude Code

Browse source 
🚀 New Feature: ralph-import
- Converts existing PRDs/specs to Ralph format using Claude Code intelligence
- Supports multiple formats: Markdown, text, JSON, Word docs, PDFs
- Creates complete Ralph project with PROMPT.md, @fix_plan.md, specs/
- Leverages Claude Code for intelligent requirement parsing and conversion

🔧 Implementation:
- ralph_import.sh: Core conversion script with Claude Code integration
- Global installation: ralph-import command available system-wide
- Smart conversion prompt that extracts goals, priorities, and technical specs
- Auto-generates proper Ralph project structure from any source format

📚 Enhanced Documentation:
- New "Importing Existing Requirements" section in README
- Option A (import PRD) vs Option B (manual setup) in Quick Start
- Comprehensive format support and usage examples
- Command reference updated with ralph-import

🎯 Benefits:
- Eliminates manual conversion from PRDs to Ralph format
- Leverages Claude Code's intelligence for requirement interpretation
- Dramatically reduces onboarding friction for existing projects
- Maintains all original requirement context while making it actionable

Sample PRD included for testing and demonstration purposes.
This commit is contained in:
frankbria 2025-08-27 10:01:57 -07:00
parent 05146b1c30
commit 76a80220da
4 changed files with 415 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

70
README.md
View file

@ -48,17 +48,33 @@ This adds `ralph`, `ralph-monitor`, and `ralph-setup` commands to your PATH.
For each new project you want Ralph to work on:
#### Option A: Import Existing PRD/Specifications
```bash
# 1. Create a new Ralph-managed project (run anywhere)
# Convert existing PRD/specs to Ralph format (recommended)
ralph-import my-requirements.md my-project
cd my-project
# Review and adjust the generated files:
# - PROMPT.md (Ralph instructions)
# - @fix_plan.md (task priorities)
# - specs/requirements.md (technical specs)
# Start autonomous development
ralph --monitor
```
#### Option B: Manual Project Setup
```bash
# Create blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project
# 2. Configure your project requirements
# Configure your project requirements manually
# Edit PROMPT.md with your project goals
# Edit specs/ with detailed specifications
# Edit @fix_plan.md with initial priorities
# 3. Start autonomous development
# Start autonomous development
ralph --monitor
```
@ -93,6 +109,45 @@ Ralph automatically stops when it detects:
- 🧪 Too many test-focused loops (indicating feature completeness)
- 📋 Strong completion indicators in responses
## 📄 Importing Existing Requirements
Ralph can convert existing PRDs, specifications, or requirement documents into the proper Ralph format using Claude Code.
### Supported Formats
- **Markdown** (.md) - Product requirements, technical specs
- **Text files** (.txt) - Plain text requirements
- **JSON** (.json) - Structured requirement data
- **Word documents** (.docx) - Business requirements
- **PDFs** (.pdf) - Design documents, specifications
- **Any text-based format** - Ralph will intelligently parse the content
### Usage Examples
```bash
# Convert a markdown PRD
ralph-import product-requirements.md my-app
# Convert a text specification
ralph-import requirements.txt webapp
# Convert a JSON API spec
ralph-import api-spec.json backend-service
# Let Ralph auto-name the project from filename
ralph-import design-doc.pdf
```
### What Gets Generated
Ralph-import creates a complete project with:
- **PROMPT.md** - Converted into Ralph development instructions
- **@fix_plan.md** - Requirements broken down into prioritized tasks
- **specs/requirements.md** - Technical specifications extracted from your document
- **Standard Ralph structure** - All necessary directories and template files
The conversion is intelligent and preserves your original requirements while making them actionable for autonomous development.
## 🛠️ Configuration
### Rate Limiting
@ -269,10 +324,11 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
### Project Commands (Per Project)
```bash
ralph-setup project-name # Create new Ralph project
ralph --monitor # Start with integrated monitoring
ralph --status # Check current loop status
ralph-monitor # Manual monitoring dashboard
ralph-setup project-name # Create new Ralph project
ralph-import prd.md project # Convert PRD/specs to Ralph project
ralph --monitor # Start with integrated monitoring
ralph --status # Check current loop status
ralph-monitor # Manual monitoring dashboard
```
### tmux Session Management

18
install.sh
View file

@ -118,16 +118,31 @@ EOF
RALPH_HOME="$HOME/.ralph"
exec "$RALPH_HOME/setup.sh" "$@"
EOF
# Create ralph-import command
cat > "$INSTALL_DIR/ralph-import" << 'EOF'
#!/bin/bash
# Ralph PRD Import - Global Command
RALPH_HOME="$HOME/.ralph"
exec "$RALPH_HOME/ralph_import.sh" "$@"
EOF
# Copy actual script files to Ralph home with modifications for global operation
cp "$SCRIPT_DIR/ralph_monitor.sh" "$RALPH_HOME/"
# Copy PRD import script to Ralph home
cp "$SCRIPT_DIR/ralph_import.sh" "$RALPH_HOME/"
# Make all commands executable
chmod +x "$INSTALL_DIR/ralph"
chmod +x "$INSTALL_DIR/ralph-monitor"
chmod +x "$INSTALL_DIR/ralph-setup"
chmod +x "$INSTALL_DIR/ralph-import"
chmod +x "$RALPH_HOME/ralph_monitor.sh"
chmod +x "$RALPH_HOME/ralph_import.sh"
log "SUCCESS" "Ralph scripts installed to $INSTALL_DIR"
}
@ -232,6 +247,7 @@ main() {
echo " ralph --monitor # Start Ralph with integrated monitoring"
echo " ralph --help # Show Ralph options"
echo " ralph-setup my-project # Create new Ralph project"
echo " ralph-import prd.md # Convert PRD to Ralph project"
echo " ralph-monitor # Manual monitoring dashboard"
echo ""
echo "Quick start:"
@ -253,7 +269,7 @@ case "${1:-install}" in
;;
uninstall)
log "INFO" "Uninstalling Ralph for Claude Code..."
rm -f "$INSTALL_DIR/ralph" "$INSTALL_DIR/ralph-monitor" "$INSTALL_DIR/ralph-setup"
rm -f "$INSTALL_DIR/ralph" "$INSTALL_DIR/ralph-monitor" "$INSTALL_DIR/ralph-setup" "$INSTALL_DIR/ralph-import"
rm -rf "$RALPH_HOME"
log "SUCCESS" "Ralph for Claude Code uninstalled"
;;

273
ralph_import.sh Executable file
View file

@ -0,0 +1,273 @@
#!/bin/bash
# Ralph Import - Convert PRDs to Ralph format using Claude Code
set -e
# Configuration
CLAUDE_CODE_CMD="npx @anthropic/claude-code"
# Colors
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
log() {
local level=$1
local message=$2
local color=""
case $level in
"INFO") color=$BLUE ;;
"WARN") color=$YELLOW ;;
"ERROR") color=$RED ;;
"SUCCESS") color=$GREEN ;;
esac
echo -e "${color}[$(date '+%H:%M:%S')] [$level] $message${NC}"
}
show_help() {
cat << HELPEOF
Ralph Import - Convert PRDs to Ralph Format
Usage: $0 <source-file> [project-name]
Arguments:
source-file Path to your PRD/specification file (any format)
project-name Name for the new Ralph project (optional, defaults to filename)
Examples:
$0 my-app-prd.md
$0 requirements.txt my-awesome-app
$0 project-spec.json
$0 design-doc.docx webapp
Supported formats:
- Markdown (.md)
- Text files (.txt)
- JSON (.json)
- Word documents (.docx)
- PDFs (.pdf)
- Any text-based format
The command will:
1. Create a new Ralph project
2. Use Claude Code to intelligently convert your PRD into:
- PROMPT.md (Ralph instructions)
- @fix_plan.md (prioritized tasks)
- specs/ (technical specifications)
HELPEOF
}
# Check dependencies
check_dependencies() {
if ! command -v ralph-setup &> /dev/null; then
log "ERROR" "Ralph not installed. Run ./install.sh first"
exit 1
fi
if ! npx @anthropic/claude-code --version &> /dev/null 2>&1; then
log "WARN" "Claude Code CLI not found. It will be downloaded when first used."
fi
}
# Convert PRD using Claude Code
convert_prd() {
local source_file=$1
local project_name=$2
log "INFO" "Converting PRD to Ralph format using Claude Code..."
# Create conversion prompt
cat > .ralph_conversion_prompt.md << 'PROMPTEOF'
# PRD to Ralph Conversion Task
You are tasked with converting a Product Requirements Document (PRD) or specification into Ralph for Claude Code format.
## Input Analysis
Analyze the provided specification file and extract:
- Project goals and objectives
- Core features and requirements
- Technical constraints and preferences
- Priority levels and phases
- Success criteria
## Required Outputs
Create these files in the current directory:
### 1. PROMPT.md
Transform the PRD into Ralph development instructions:
```markdown
# Ralph Development Instructions
## Context
You are Ralph, an autonomous AI development agent working on a [PROJECT NAME] project.
## Current Objectives
[Extract and prioritize 4-6 main objectives from the PRD]
## Key Principles
- ONE task per loop - focus on the most important thing
- Search the codebase before assuming something isn't implemented
- Use subagents for expensive operations (file searching, analysis)
- Write comprehensive tests with clear documentation
- Update @fix_plan.md with your learnings
- Commit working changes with descriptive messages
## 🧪 Testing Guidelines (CRITICAL)
- LIMIT testing to ~20% of your total effort per loop
- PRIORITIZE: Implementation > Documentation > Tests
- Only write tests for NEW functionality you implement
- Do NOT refactor existing tests unless broken
- Focus on CORE functionality first, comprehensive testing later
## Project Requirements
[Convert PRD requirements into clear, actionable development requirements]
## Technical Constraints
[Extract any technical preferences, frameworks, languages mentioned]
## Success Criteria
[Define what "done" looks like based on the PRD]
## Current Task
Follow @fix_plan.md and choose the most important item to implement next.
```
### 2. @fix_plan.md
Convert requirements into a prioritized task list:
```markdown
# Ralph Fix Plan
## High Priority
[Extract and convert critical features into actionable tasks]
## Medium Priority
[Secondary features and enhancements]
## Low Priority
[Nice-to-have features and optimizations]
## Completed
- [x] Project initialization
## Notes
[Any important context from the original PRD]
```
### 3. specs/requirements.md
Create detailed technical specifications:
```markdown
# Technical Specifications
[Convert PRD into detailed technical requirements including:]
- System architecture requirements
- Data models and structures
- API specifications
- User interface requirements
- Performance requirements
- Security considerations
- Integration requirements
[Preserve all technical details from the original PRD]
```
## Instructions
1. Read and analyze the attached specification file
2. Create the three files above with content derived from the PRD
3. Ensure all requirements are captured and properly prioritized
4. Make the PROMPT.md actionable for autonomous development
5. Structure @fix_plan.md with clear, implementable tasks
PROMPTEOF
# Run Claude Code with the source file and prompt
if $CLAUDE_CODE_CMD < .ralph_conversion_prompt.md; then
log "SUCCESS" "PRD conversion completed"
# Clean up temp file
rm -f .ralph_conversion_prompt.md
# Verify files were created
local missing_files=()
if [[ ! -f "PROMPT.md" ]]; then missing_files+=("PROMPT.md"); fi
if [[ ! -f "@fix_plan.md" ]]; then missing_files+=("@fix_plan.md"); fi
if [[ ! -f "specs/requirements.md" ]]; then missing_files+=("specs/requirements.md"); fi
if [[ ${#missing_files[@]} -ne 0 ]]; then
log "WARN" "Some files were not created: ${missing_files[*]}"
log "INFO" "You may need to create these files manually or run the conversion again"
fi
else
log "ERROR" "PRD conversion failed"
rm -f .ralph_conversion_prompt.md
exit 1
fi
}
# Main function
main() {
local source_file="$1"
local project_name="$2"
# Validate arguments
if [[ -z "$source_file" ]]; then
log "ERROR" "Source file is required"
show_help
exit 1
fi
if [[ ! -f "$source_file" ]]; then
log "ERROR" "Source file does not exist: $source_file"
exit 1
fi
# Default project name from filename
if [[ -z "$project_name" ]]; then
project_name=$(basename "$source_file" | sed 's/\.[^.]*$//')
fi
log "INFO" "Converting PRD: $source_file"
log "INFO" "Project name: $project_name"
check_dependencies
# Create project directory
log "INFO" "Creating Ralph project: $project_name"
ralph-setup "$project_name"
cd "$project_name"
# Copy source file to project
cp "../$source_file" .
# Run conversion
convert_prd "$source_file" "$project_name"
log "SUCCESS" "🎉 PRD imported successfully!"
echo ""
echo "Next steps:"
echo " 1. Review and edit the generated files:"
echo " - PROMPT.md (Ralph instructions)"
echo " - @fix_plan.md (task priorities)"
echo " - specs/requirements.md (technical specs)"
echo " 2. Start autonomous development:"
echo " ralph --monitor"
echo ""
echo "Project created in: $(pwd)"
}
# Handle command line arguments
case "${1:-}" in
-h|--help|"")
show_help
exit 0
;;
*)
main "$@"
;;
esac

62
sample-prd.md Normal file
View file

@ -0,0 +1,62 @@
# Task Management Web App - Product Requirements Document
## Overview
Build a modern task management web application similar to Todoist/Asana for small teams and individuals.
## Core Features
### User Management
- User registration and authentication
- User profiles with avatars
- Team/workspace creation and management
### Task Management
- Create, edit, and delete tasks
- Task prioritization (High, Medium, Low)
- Due dates and reminders
- Task categories/projects
- Task assignment to team members
- Comments and attachments on tasks
### Organization
- Project-based organization
- Kanban board view
- List view with filtering and sorting
- Calendar view for due dates
- Dashboard with overview metrics
## Technical Requirements
### Frontend
- React.js with TypeScript
- Modern UI with responsive design
- Real-time updates for collaborative features
- PWA capabilities for mobile use
### Backend
- Node.js with Express
- PostgreSQL database
- RESTful API design
- WebSocket for real-time features
- JWT authentication
### Infrastructure
- Docker containerization
- Environment-based configuration
- Automated testing (unit and integration)
- CI/CD pipeline ready
## Success Criteria
- Users can create and manage tasks efficiently
- Team collaboration features work seamlessly
- App loads quickly (<2s initial load)
- Mobile-responsive design works on all devices
- 95%+ uptime once deployed
## Priority
1. **Phase 1**: Basic task CRUD, user auth, simple UI
2. **Phase 2**: Team features, real-time updates, advanced views
3. **Phase 3**: Notifications, mobile PWA, advanced filtering
## Timeline
Target MVP completion in 4-6 weeks of development.