gsd-ralph

GSD-Ralph

Plan interactively. Execute autonomously.

A Claude Code plugin that bridges structured project planning with Ralph Loop autonomous execution. Plan your phases during the day, let Ralph build them overnight.

What It Does

GSD-Ralph combines two proven workflows:

1. GSD-style planning — Break work into phases with clear plans, success criteria, and file lists
2. Ralph Loop execution — Autonomously execute all phases without human input, with state tracking and decision logging

Commands

Command	Description
/gsd-ralph:plan	Plan project phases interactively
/gsd-ralph:handoff	Generate RALPH-OVERNIGHT.md from existing plans
/gsd-ralph:execute	Start autonomous execution of planned phases
/gsd-ralph:resume	Resume execution after interruption
/gsd-ralph:status	Check project progress and next action

Typical Workflow

1. /gsd-ralph:plan          # Plan your phases (interactive)
2. /gsd-ralph:handoff       # Generate overnight handoff
3. /gsd-ralph:execute       # Start autonomous execution
4. ... Ralph works overnight ...
5. /gsd-ralph:status        # Check what happened
6. git push                 # Push when satisfied

Installation

As a Claude Code plugin (recommended)

# Clone into your dev-tools
git clone https://github.com/smaluhn/gsd-ralph.git ~/git/dev-tools/gsd-ralph

# Install as local plugin in Claude Code
# (Plugin installation via Claude Code CLI)

Manual (copy commands)

cp commands/*.md ~/.claude/commands/gsd-ralph/
cp hooks/* ~/.claude/hooks/

Project Structure

gsd-ralph/
├── .claude-plugin/
│   └── plugin.json           # Plugin manifest
├── commands/
│   ├── plan.md               # Interactive planning
│   ├── handoff.md            # Generate overnight handoff
│   ├── execute.md            # Autonomous execution
│   ├── resume.md             # Resume interrupted execution
│   └── status.md             # Progress dashboard
├── hooks/
│   ├── hooks.json            # Hook event config
│   └── ralph-stop-hook.sh    # Loop continuation hook
├── scripts/
│   ├── start-loop.sh         # Initialize loop state
│   └── stop-loop.sh          # Stop loop
├── templates/
│   ├── ralph-overnight.md    # Handoff document template
│   ├── state.md              # State tracker template
│   ├── plan.md               # Phase plan template
│   └── summary.md            # Phase summary template
└── README.md

How It Works

Planning Phase (Interactive)

/gsd-ralph:plan guides you through:

• Project context gathering
• Phase breakdown with goals and success criteria
• Detailed plan creation for each phase

Handoff Phase

/gsd-ralph:handoff generates .planning/RALPH-OVERNIGHT.md containing:

• Full project context
• Phase execution scope
• Hard rules for autonomous mode (no user interaction, no git push)
• Completion promise for loop termination

Execution Phase (Autonomous)

/gsd-ralph:execute runs without human input:

• Reads plans sequentially
• Executes tasks from each PLAN.md
• Commits after each phase
• Updates STATE.md continuously
• Logs decisions in DECISIONS.md
• Outputs completion promise when done

The Stop Hook

The stop hook (ralph-stop-hook.sh) prevents Claude from exiting mid-execution. When Claude tries to stop:

1. Hook checks if loop is active via .planning/gsd-ralph-loop.local.md
2. If active, increments iteration and re-feeds the execution prompt
3. If max iterations reached or loop inactive, allows exit

State Files

During execution, these files track progress:

File	Purpose
.planning/STATE.md	Phase completion status
.planning/RALPH-OVERNIGHT.md	Execution instructions
.planning/DECISIONS.md	Decisions made during autonomous execution
.planning/EXECUTION-LOG.md	Post-execution summary
.planning/gsd-ralph-loop.local.md	Loop iteration state
.planning/phases/{N}-{name}/{N}-PLAN.md	Phase plans
.planning/phases/{N}-{name}/{N}-SUMMARY.md	Phase execution summaries

License

MIT