diff --git a/README.md b/README.md index 2195a0d..7bb99d9 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/install.sh b/install.sh index 42e575d..d6a3049 100755 --- a/install.sh +++ b/install.sh @@ -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" ;; diff --git a/ralph_import.sh b/ralph_import.sh new file mode 100755 index 0000000..f6ac4ea --- /dev/null +++ b/ralph_import.sh @@ -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 [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 \ No newline at end of file diff --git a/sample-prd.md b/sample-prd.md new file mode 100644 index 0000000..b93eab3 --- /dev/null +++ b/sample-prd.md @@ -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. \ No newline at end of file