Skip to content

Latest commit

 

History

History
357 lines (254 loc) · 8.36 KB

INDEX.md

File metadata and controls

357 lines (254 loc) · 8.36 KB

Ralphing Documentation Index

Complete documentation for Ralphing - Autonomous AI Coding Loop

Quick Links

Document Description
README.md START HERE - Complete user guide and reference
SETUP.md Installation and configuration guide
EXAMPLES.md Visual examples and output samples
PRD.md Sample Product Requirements Document

Document Overview

📘 README.md

Main documentation and user guide

Contents:

  • Features overview
  • Prerequisites and requirements
  • Installation instructions
  • Quick start guide
  • Complete usage reference
  • All command-line options
  • PRD format specifications
  • Advanced features
  • Troubleshooting
  • Best practices

Who should read: Everyone using Ralphing

🔧 SETUP.md

Installation and setup guide

Contents:

  • System requirements
  • Step-by-step installation for macOS/Linux
  • AI engine setup (Claude Code, OpenCode, Cursor, Codex)
  • Project initialization
  • Verification steps
  • Troubleshooting common installation issues
  • Advanced configuration

Who should read: First-time users, anyone having installation issues

📊 EXAMPLES.md

Visual output examples

Contents:

  • Sequential mode output samples
  • Parallel mode output samples
  • Branch-per-task examples
  • Status indicator reference
  • Error handling examples
  • 30-second update samples
  • Conflict resolution examples
  • Completion summaries

Who should read: Anyone wanting to understand what Ralphing's output looks like

📋 PRD.md

Sample Product Requirements Document

A complete example PRD for building an e-commerce application with:

  • 12 phases
  • 70+ tasks
  • Realistic project structure
  • Proper task formatting
  • Success criteria
  • Technical stack

Who should read: Anyone creating their first PRD

Example Files

📂 examples/

Sample scripts and configurations to get started quickly.

File Description
run-sequential.sh Basic sequential mode example
run-parallel.sh Parallel mode with 3 agents
run-with-prs.sh Branch-per-task with PR creation
run-fast-prototype.sh Fast mode for rapid prototyping
run-yaml-parallel.sh YAML tasks with parallel groups
tasks.yaml Sample YAML task file with groups
simple-prd.md Minimal test PRD (4 phases)
sample-progress.txt Example progress log output

Getting Started Path

For New Users

  1. Read: README.md - Overview and features
  2. Setup: SETUP.md - Install dependencies
  3. Test: Run ./ralphing.sh --version to verify
  4. Try: Copy examples/simple-prd.md to test project
  5. Run: ./ralphing.sh --verbose --max-iterations 1
  6. Learn: EXAMPLES.md - Understand output
  7. Build: Create your own PRD using PRD.md as template

For Experienced Users

  1. Quick Setup: SETUP.md - Installation
  2. Reference: README.md - Command options
  3. Examples: examples/ - Copy and modify scripts

File Structure

ralphing_docs/
├── INDEX.md              # This file - documentation index
├── README.md             # Complete user guide (START HERE)
├── SETUP.md              # Installation and setup
├── EXAMPLES.md           # Visual output examples
├── PRD.md                # Sample PRD for e-commerce app
├── ralphing.sh             # The Ralphing script (v3.1.0)
└── examples/             # Sample scripts and files
    ├── run-sequential.sh       # Sequential mode example
    ├── run-parallel.sh         # Parallel mode example
    ├── run-with-prs.sh         # Branch-per-task + PRs
    ├── run-fast-prototype.sh   # Fast prototyping mode
    ├── run-yaml-parallel.sh    # YAML with parallel groups
    ├── tasks.yaml              # Sample YAML task file
    ├── simple-prd.md           # Minimal test PRD
    └── sample-progress.txt     # Example progress log

Common Tasks

Installing Ralphing

→ See SETUP.md

Sections:

  • System Requirements
  • Installation Steps (macOS/Linux)
  • AI Engine Setup
  • Verification

Running First Task

→ See README.md - Quick Start

Quick commands:

# Create test PRD
cp ralphing_docs/examples/simple-prd.md PRD.md

# Run first iteration
./ralphing.sh --verbose --max-iterations 1

Understanding Output

→ See EXAMPLES.md

Sections:

  • Sequential Mode Output
  • Parallel Mode Output
  • Status Indicators
  • 30-Second Updates

Creating a PRD

→ See PRD.md for template

→ See README.md - PRD Formats for specifications

Format:

# Product Requirements Document

## Phase 1: Setup

- [ ] Task 1 description
- [ ] Task 2 description

## Phase 2: Features

- [ ] Task 3 description

Running in Parallel

→ See README.md - Execution Modes

→ See examples/run-parallel.sh

Command:

./ralphing.sh --parallel --max-parallel 3 --verbose

Branch-per-Task Workflow

→ See README.md - Git Branch Management

→ See examples/run-with-prs.sh

Command:

./ralphing.sh --branch-per-task --create-pr --base-branch main

Troubleshooting

→ See SETUP.md - Troubleshooting

→ See README.md - Troubleshooting

Common issues:

  • AI engine not found
  • jq not installed
  • Tasks not being marked complete
  • API rate limits
  • Git conflicts

Feature Reference

Colorful Status Indicators (v3.1.0)

→ See EXAMPLES.md - Status Indicators

Features:

  • Rotating colored ⏺ indicators (6 colors)
  • Per-agent indicators in parallel mode
  • Real-time step detection
  • Elapsed time display

30-Second Status Updates (v3.1.0)

→ See EXAMPLES.md - 30-Second Status Updates

Shows:

  • Recent AI activity (tools, files, commands)
  • Current step
  • Per-agent status (parallel mode)
  • Elapsed time

Reliable Task Completion (v3.1.0)

→ See README.md - How It Works

Improvements:

  • Script always marks tasks complete
  • Doesn't rely on AI to update PRD
  • Verification with fallback
  • Handles special characters

Parallel Execution

→ See README.md - Parallel Mode

→ See EXAMPLES.md - Parallel Mode

Features:

  • Isolated git worktrees per agent
  • Concurrent task execution
  • Per-agent status indicators
  • Automatic branch merging
  • Interactive conflict resolution

AI Engine Support

Engine Documentation Setup Guide
Claude Code (default) README.md SETUP.md - Claude Code
OpenCode README.md SETUP.md - OpenCode
Cursor README.md SETUP.md - Cursor
Codex README.md SETUP.md - Codex

Version History

v3.1.0 (Current)

  • ✨ Colorful blinking status indicators
  • ✨ 30-second detailed status updates
  • ✨ Reliable task completion tracking
  • ✨ Per-agent indicators in parallel mode
  • 🐛 Fixed PRD tasks not being marked complete
  • 🐛 Improved stuck agent detection

v3.0.0

  • Parallel execution mode
  • Git worktree isolation
  • Conflict resolution menu
  • Branch-per-task workflow
  • PR creation support

v2.0.0

  • Multiple AI engine support
  • YAML task file format
  • GitHub issues integration
  • Token tracking

v1.0.0

  • Initial release
  • Sequential execution
  • Markdown PRD format
  • Claude Code integration

Contributing

Found an issue or want to contribute?

  1. Report bugs: Create an issue with --verbose output
  2. Request features: Describe use case and expected behavior
  3. Submit PRs: Fork, create feature branch, submit PR

License

MIT License - See LICENSE file

Support

  • Documentation: You're reading it!
  • Examples: See examples/ directory
  • Issues: Report at GitHub Issues
  • Updates: Check README.md for latest version

Last Updated: January 2026 Version: 3.1.0 Author: Arsalan Amin