r10m - Ralph Wiggum (e10d Edition)

Autonomous software development agent that iteratively implements user stories from a plan using OpenCode.

What It Does

r10m reads a plan.md file containing user stories and implements them one at a time using OpenCode. It:

• Works through stories in order
• Runs quality checks (lint, typecheck, tests)
• Commits changes to git
• Tracks progress in real-time (displays in OpenCode's plans pane)
• Verifies UI features in the browser
• Continues until all stories are complete or max iterations reached

Installation

# Clone or download this repo
cd r10m

# Run install script
./install.sh

# Reload your shell (or restart terminal)
source ~/.bashrc  # or source ~/.zshrc

This installs:

• r10m CLI to ~/.local/bin/
• riom alias (identical to r10m)
• Skills to ~/.config/opencode/skill/
• plan.md.example template to ~/.local/share/r10m/ (for manual plan creation)

Quick Start

# In your project directory
# Option 1: Generate PRD and auto-convert to plan.md
r10m create-prd "add user auth" # Generate PRD and convert to plan.md

# Option 2: Create plan.md manually
cp ~/.local/share/r10m/plan.md.example .
# Edit plan.md with your stories

# Start implementation
r10m run                       # Run with default 10 iterations
r10m run 5                     # Run with 5 iterations

# Check progress
r10m status

CLI Commands

Command	Description
r10m init	Initialize project with plan.md template
r10m run [n]	Run implementation (default: 10 iterations)
r10m status	Show progress from plan.md
r10m create-prd <desc>	Generate PRD using opencode prd skill
r10m convert-prd	Convert PRD to plan.md

plan.md Format

# Plan: My Project

## Project Description
Brief description of the feature

## Stories

- [ ] US-001: Story Title
  - As a [user], I want [feature] so that [benefit]
  - **Acceptance Criteria:**
    - [ ] Criterion 1
    - [ ] Criterion 2
    - [ ] Typecheck passes

- [ ] US-002: Another Story
  - As a [user], I want [feature] so that [benefit]
  - **Acceptance Criteria:**
    - [ ] Criterion 1
    - [ ] Verify in browser using webapp-testing skill
    - [ ] Typecheck passes

Key Concepts

Fresh Instance Per Story

Each iteration spawns a fresh OpenCode instance with clean context. Memory persists via:

• Git commits
• plan.md (checkboxes)
• progress.txt (learnings and context)

Story Selection

r10m always works on the first story where all checkboxes are unchecked (- [ ]).

Quality Gates

Before committing, r10m ensures:

• All acceptance criteria checkboxes are checked
• Typecheck passes (if applicable)
• Linting passes (if applicable)
• Tests pass (if applicable)
• Browser verification for UI stories

Progress Tracking

• plan.md checkboxes update as stories complete
• OpenCode's plans pane automatically displays plan.md
• r10m status shows progress summary

Skills

prd

Generate markdown PRDs from feature descriptions.

r10m-plan-creator

Convert markdown PRDs to plan.md format with checkbox tracking for r10m.

Configuration

Environment variables:

• MAX_ITERATIONS - Maximum iterations before stopping (default: 10)

Requirements

• OpenCode CLI
• Git

License

MIT

Credits

Inspired by the original Ralph project, reimplemented for e10d with OpenCode.