Ralph - Autonomous Agent Skill

Ralph is an autonomous agent skill that breaks complex projects into user stories and executes them step by step. It's designed to work with command-line AI systems that have skills installed.

How Ralph Works

When you tell your AI "use Ralph" to work on a project:

1. •Your AI reads this SKILL.md to understand what Ralph does
2. •Your AI analyzes your project structure (files, code, data, references)
3. •Your AI checks what skills it has available
4. •Your AI generates a PRD (Project Requirements Document) with:
   • •User stories for each part of the work
   • •contextMap showing what files each story needs
   • •requiredSkills describing what capabilities are needed
5. •Your AI shows you the PRD - you confirm it looks right
6. •Your AI runs Ralph with the generated PRD
7. •Ralph executes all user stories automatically

The Workflow

User: "Use Ralph to write my paper"
  ↓
AI reads SKILL.md
  ↓
AI analyzes: Code/, Data/, References/ folders
  ↓
AI checks: "I have Quarto Authoring and Quarto skills"
  ↓
AI generates PRD automatically
  ↓
AI shows you: "Here's what I'm going to do..."
  
  You confirm: "Looks good!" or "Wait, fix XXX first"
  ↓
AI runs: ralph.mjs create --prd generated_prd.json --start
  ↓
Ralph executes all tasks
  ↓
Done! You have your paper

What Ralph Does

Ralph executes projects step by step by:

1. •Reading the PRD that describes the work
2. •Processing each user story in priority order
3. •Reading referenced files (code, docs, data)
4. •Doing the actual work (writing, coding, analyzing, etc.)
5. •Using your AI's skills when needed for special tasks
6. •Tracking progress and handling errors

The PRD (Generated by Your AI)

Your AI will generate a PRD with this structure:

{
  "description": "Project description",
  "taskType": "code|content|research|data|devops|testing|orchestrator",
  "requiredSkills": ["Capability description 1", "Capability description 2"],
  "contextMap": {
    "story_id": {
      "references": ["files to read"],
      "code_files": ["code to understand"],
      "experiments": ["data and results"]
    }
  },
  "userStories": [
    {
      "id": "US001",
      "title": "What to do",
      "acceptanceCriteria": ["specific criteria"],
      "priority": 1,
      "passes": false
    }
  ]
}

Key fields:

• •taskType - What kind of work (code, content, research, data, devops, testing, orchestrator)
• •requiredSkills - Capabilities needed (AI matches these to its available skills)
• •contextMap - What files each story needs to read
• •userStories - The actual work broken into pieces

For AI Systems: How to Use Ralph

Your AI should follow the AI Workflow guide in docs/AI_WORKFLOW.md:

1. •Analyze the project - Scan files and structure
2. •Check available skills - See what's installed
3. •Generate the PRD - Create user stories, contextMap, requiredSkills
4. •Show to user - Display PRD and ask for confirmation
5. •Run Ralph - Execute after user approves
6. •Monitor - Watch logs and provide feedback

PRD Generation Guide: See docs/PRD_GENERATOR.md for detailed step-by-step instructions.

Basic CLI Commands

# Create and start a session
ralph.mjs create --prd path/to/prd.json --start

# Monitor progress
ralph.mjs logs <session-id> --follow

# Pause if needed
ralph.mjs pause <session-id> --reason "Waiting for feedback"

# Resume after adjustments
ralph.mjs resume <session-id> --guidance "Here's what to fix..."

# Check status
ralph.mjs status <session-id>

# Abort if necessary
ralph.mjs abort <session-id>

For full CLI reference: ralph.mjs --help

Example: MCM Paper Writing

See examples/mcm-paper/ for a complete example showing:

• •Project structure with Code/, Data/, References/
• •Generated PRD with contextMap
• •How user confirms and Ralph executes

Key Insight

Ralph doesn't require users to manually write PRDs. Instead:

• •Your AI analyzes the actual project
• •Your AI generates an intelligent PRD
• •User confirms the plan
• •Ralph executes automatically

This makes Ralph adaptive to different projects without manual setup.