ralph-dev

Ralph-dev

English | 中文

Autonomous development workflow plugin for Claude Code that transforms natural language requirements into structured, testable code through a 5-phase process.

Overview

Ralph-dev automates software development workflows by:

• Breaking down requirements into atomic, testable tasks
• Implementing each task with fresh agent context for TDD enforcement
• Auto-detecting project language and framework (12+ languages supported)
• Managing state and progress through a CLI-driven task system
• Automatically healing errors through WebSearch-based investigation
• Creating git commits and pull requests for code review

Quick Start

# Step 1: Install CLI globally
npm install -g ralph-dev

# Step 2: Add plugin marketplace
/plugin marketplace add mylukin/ralph-dev

# Step 3: Install plugin
/plugin install ralph-dev

# Step 4: Initialize project (installs workflow rules)
ralph-dev init

# Step 5: Start your first task
/ralph-dev "Build a REST API for user authentication"

Ralph-dev will guide you through:

1. Clarifying questions with structured multiple-choice answers
2. Task breakdown approval (review atomic tasks before implementation)
3. Autonomous implementation with TDD workflow
4. Automated pull request creation

Key Features

Interactive Clarification

Structured Q&A eliminates requirement ambiguity through multiple-choice questions about tech stack, architecture, and deployment.

Autonomous Task Breakdown

Decomposes requirements into atomic tasks stored as markdown files with YAML frontmatter, enabling:

• Dependency tracking between tasks
• Granular progress monitoring
• Human-readable task descriptions
• Version control integration

Multi-Language Support

Auto-detects and configures verification commands for:

• JavaScript/TypeScript - Node.js, Next.js, React, Vue, Angular
• Python - Django, Flask, FastAPI
• Go, Rust, Java, Ruby, PHP, C#, Swift, Kotlin, Scala, C++

Self-Healing Implementation

When tasks fail, automatically:

• Investigates errors using WebSearch
• Applies fixes based on research
• Re-runs verification commands
• Retries up to 5 times before escalating (circuit breaker pattern)

Safety Features

Inspired by Superpowers:

1. Gitignore Verification - Automatically ensures .ralph-dev/ is gitignored before creating files
2. Baseline Test Verification - Confirms all tests pass before starting implementation
3. Auto-Cleanup - Removes temporary files after delivery while preserving documentation

Two-Stage Code Review

Before creating PRs:

1. Spec Compliance - Validates acceptance criteria are met
2. Code Quality - Runs type-check, lint, and tests

Architecture

5-Phase Workflow

CLARIFY → BREAKDOWN → IMPLEMENT ⇄ HEAL → DELIVER

Phase 1: CLARIFY

• Skill: skills/phase-1-clarify/
• Asks structured questions about requirements
• Generates Product Requirements Document (PRD)
• Output: .ralph-dev/prd.md

Phase 2: BREAKDOWN

• Skill: skills/phase-2-breakdown/
• Parses PRD into atomic tasks (<30 min each)
• Creates modular task files with dependency tracking
• Output: .ralph-dev/tasks/*.md + tasks/index.json

Phase 3: IMPLEMENT

• Skill: skills/phase-3-implement/
• Spawns fresh agent context per task for TDD enforcement
• Manages task lifecycle (pending → in_progress → completed/failed)
• Automatically invokes Phase 4 on failure

Phase 4: HEAL

• Skill: skills/phase-4-heal/
• Triggered when Phase 3 tasks fail
• Uses WebSearch to research error solutions
• Applies fixes and re-runs verification
• Max 5 retry attempts per error (circuit breaker)

Phase 5: DELIVER

• Skill: skills/phase-5-deliver/
• Runs language-specific quality gates
• Two-stage code review process
• Creates git commit and pull request

Directory Structure