🤠 Ralph SpecKit

Autonomous AI coding loop for Spec-Driven Development

Run your AI agent in a loop: read tasks → implement → verify → commit → repeat.

---

Table of Contents

• 🎯 Why Ralph?
• 📦 Installation
• 🚀 Quick Start
• ✨ Features
• 🤖 Supported Agents
• ⚙️ Configuration
• 📚 Documentation
• 🙏 Credits
• 📄 License

🎯 Why Ralph?

Ralph automates the iterative development process for SpecKit projects. Each iteration:

1. Reads context — tasks.md, progress.txt, project docs
2. Picks ONE task — First uncompleted item with all dependencies met
3. Implements — Follows project patterns, runs quality checks
4. Verifies — Tests pass, lint pass, build succeeds
5. Commits — Saves work with descriptive message
6. Updates progress — Marks task complete, logs learnings
7. Repeats — Until <promise>COMPLETE</promise>

📦 Installation

Option 1: Install Script (Recommended)

curl -sSL https://raw.githubusercontent.com/merllinsbeard/ralph-speckit/main/install.sh | bash

Option 2: Manual Download

curl -sLO https://raw.githubusercontent.com/merllinsbeard/ralph-speckit/main/ralph.sh
curl -sLO https://raw.githubusercontent.com/merllinsbeard/ralph-speckit/main/ralph-prompt.md
chmod +x ralph.sh

🚀 Quick Start

# Copy to your SpecKit project
./install.sh

# Run in HITL mode (human-in-the-loop)
./ralph.sh --iterations 1 --verbose

# Or run in AFK mode (autonomous)
./ralph.sh --iterations 10

✨ Features

Feature	Description
SpecKit Native	Reads specs/<branch>/tasks.md automatically
Smart Task Selection	Picks first uncompleted task with dependencies met
Progress Tracking	Updates tasks.md checkboxes, appends to progress.txt
Quality Gates	Runs tests, lint, typecheck before committing
Completion Signal	Stops when <promise>COMPLETE</promise> detected
Multi-Agent	Supports Claude Code, OpenCode, or custom CLIs

🤖 Supported Agents

Agent	Support	Notes
Claude Code	✅	Default
OpenCode	✅	Set --agent opencode
Custom	✅	Set RALPH_CUSTOM_AGENT_CMD

⚙️ Configuration

Set via environment variables or .env file:

# Agent selection
RALPH_AGENT=claude          # claude | opencode | custom
RALPH_ITERATIONS=1          # Number of iterations
RALPH_PROMPT=ralph-prompt.md

# Custom agent (for RALPH_AGENT=custom)
RALPH_CUSTOM_AGENT_CMD="my-cli --print"

📚 Documentation

• SpecKit Integration — How Ralph works with GitHub SpecKit
• Architecture — Loop flow, completion signal
• Examples — Working SpecKit task example

🙏 Credits

Inspired by ghuntley.com/ralph and GitHub SpecKit.

📄 License

MIT