ralph-hero

Ralph Hero

A Claude Code plugin that turns Claude into an autonomous software engineer. Ralph triages issues, researches codebases, writes implementation plans, codes in isolated worktrees, creates PRs, and merges -- all driven by a GitHub Projects V2 board.

The naive hero picks tickets, does their best work, and moves on.

How It Works

Ralph manages GitHub issues through a structured workflow state machine:

Backlog → Research Needed → Research in Progress → Ready for Plan
       → Plan in Progress → Plan in Review → In Progress → In Review → Done

Each transition is enforced by hooks and validated by the MCP server. Issues flow through phases -- triage, research, planning, review, implementation, and merge -- with human checkpoints at plan review and code review.

Autonomous mode (/ralph-hero:hero): Ralph drives an issue tree end-to-end, splitting large tickets, researching each sub-issue, creating plans, and implementing them sequentially.

Interactive mode: Use individual skills like /ralph-hero:plan or /ralph-hero:impl with human-in-the-loop verification at each step.

Team mode (/ralph-hero:team): Spawns parallel specialist agents (analyst, builder, integrator) to process issues concurrently.

Installation

Prerequisites

• Claude Code CLI
• Node.js 18+
• A GitHub Personal Access Token with repo and project scopes

Install the Plugin

claude plugins add cdubiel08/ralph-hero

Configure

Add your GitHub token and project settings to .claude/settings.local.json (gitignored):

{
  "env": {
    "RALPH_HERO_GITHUB_TOKEN": "ghp_your_token_here",
    "RALPH_GH_OWNER": "your-github-username",
    "RALPH_GH_PROJECT_NUMBER": "1"
  }
}

Set Up Your Project Board

/ralph-hero:setup

This creates a GitHub Projects V2 board with the required custom fields: Workflow State, Priority, and Estimate.

Skills

Autonomous Workflow

Run the full pipeline or individual phases:

Skill	Description
/ralph-hero:hero	Drive an issue through the full lifecycle end-to-end
/ralph-hero:team	Multi-agent team with parallel analyst, builder, and integrator workers
/ralph-hero:ralph-triage	Assess backlog issues -- close duplicates, split large tickets, route to research
/ralph-hero:ralph-research	Investigate an issue, create a research document, update issue state
/ralph-hero:ralph-plan	Create an implementation plan from research findings
/ralph-hero:ralph-review	Review and critique plans (interactive or automated)
/ralph-hero:ralph-impl	Implement one phase of an approved plan in an isolated worktree
/ralph-hero:ralph-val	Validate implementation against plan requirements
/ralph-hero:ralph-pr	Push branch and create a pull request
/ralph-hero:ralph-merge	Merge an approved PR, clean up worktree, move issues to Done
/ralph-hero:ralph-split	Decompose M/L/XL issues into XS/S sub-issues

Interactive Workflow

Human-in-the-loop skills for collaborative development:

Skill	Description
/ralph-hero:draft	Quickly capture an idea for later refinement
/ralph-hero:form	Crystallize draft ideas into structured GitHub issues
/ralph-hero:research	Interactive codebase research with parallel sub-agents
/ralph-hero:plan	Create implementation plans through collaborative exploration
/ralph-hero:iterate	Refine or extend an existing plan
/ralph-hero:impl	Implement an approved plan phase-by-phase with manual verification

Project Management

Skill	Description
/ralph-hero:hello	Session briefing -- pipeline status, hygiene warnings, actionable insights
/ralph-hero:status	Pipeline dashboard with health indicators and WIP violations
/ralph-hero:report	Generate and post a project status report to GitHub
/ralph-hero:ralph-hygiene	Identify archive candidates, stale items, and board health issues
/ralph-hero:setup	One-time project board setup with required fields
/ralph-hero:setup-repos	Bootstrap multi-repo portfolio management
/ralph-hero:idea-hunt	Scout GitHub for interesting ideas, trends, and inspiration
/ralph-hero:record-demo	Record an annotated product demo and attach to an issue

MCP Server

The plugin bundles an MCP server (ralph-hero-mcp-server) that provides GitHub Projects V2 tools to Claude Code via the Model Context Protocol.

Tools