CEO Ralph

I'm Claude, but you can call me CEO Ralph, now get coding Codex!

Spec-driven development for Claude Code. Task-by-task execution with fresh context per task.

Codex MCP + Spec-Driven Development = Sensational

Quick Start | Commands | How It Works | Troubleshooting

What is this?

CEO Ralph is a Claude Code plugin that turns your vague feature ideas into structured specs, then executes them task-by-task. Like having a tiny product team in your terminal.

You: "Add user authentication"
Ralph: *creates discovery.md, tasks.md*
Ralph: *executes each task with fresh context*
Ralph: "I'm helping!"

Why "Ralph"?

Named after the Ralph agentic loop pattern and everyone's favorite Springfield student. Ralph doesn't overthink. Ralph just does the next task. Be like Ralph.

Requirements

Codex MCP is required for task execution. Configure it once:

/ceo-ralph:setup

Codex MCP provides the execution loop. CEO Ralph provides the spec-driven workflow on top.

Installation

From Marketplace

# Configure Codex MCP
/ceo-ralph:setup

# Add the marketplace
/plugin marketplace add DUTSTECH/ceoralph

# Install the plugin
/plugin install ceo-ralph@dutstech-ceoralph

# Restart Claude Code

From GitHub

# Configure Codex MCP
/ceo-ralph:setup

/plugin install https://github.com/DUTSTECH/ceoralph

Local Development

# Configure Codex MCP
/ceo-ralph:setup

git clone https://github.com/DUTSTECH/ceoralph.git
cd ceoralph
claude --plugin-dir $(pwd)

Quick Start

# The smart way (auto-detects resume or new)
/ceo-ralph:start user-auth Add JWT authentication

# Quick mode (skip spec phases, auto-generate everything)
/ceo-ralph:start "Add user auth" --quick

# The step-by-step way
/ceo-ralph:new user-auth Add JWT authentication
/ceo-ralph:discovery
/ceo-ralph:plan
/ceo-ralph:implement

Commands

How It Works

        "I want a feature!"
               |
               v
    +---------------------+
    |     Discovery       |  <- Research + requirements
    +---------------------+
               |
               v
    +---------------------+
    |       Plan          |  <- Design summary + tasks
    +---------------------+
               |
               v
    +---------------------+
    |     Execution       |  <- Task-by-task with fresh context
    +---------------------+
               |
               v
          "I did it!"

The Agents

Each phase uses a specialized sub-agent:

Task Execution Workflow

Tasks follow a 4-phase structure:

1. Make It Work - POC validation, skip tests initially
2. Refactoring - Clean up the code
3. Testing - Unit, integration, e2e tests
4. Quality Gates - Lint, types, CI checks

Lightweight Governance

CEO Ralph uses a simple Principles + References model:

• Define non-negotiable Principles (P-1, P-2...) in discovery.md
• Every task references relevant Principles alongside FR/AC and design

Project Structure

ceoralph/
├── .claude-plugin/
│   └── marketplace.json
├── agents/             # Sub-agent definitions
├── commands/           # Slash commands
├── hooks/              # Stop watcher
├── templates/          # Spec templates
└── schemas/            # Validation schemas

Your Specs

Specs live in ./specs/ in your project:

./specs/
├── .current-spec           # Active spec name
└── my-feature/
    ├── .ralph-state.json   # Loop state (deleted on completion)
    ├── .progress.md        # Progress tracking
    ├── discovery.md
    └── tasks.md

Notes

CEO Ralph follows the specum workflow while delegating all task execution to Codex MCP.

Troubleshooting

"Codex MCP not configured"? Run /ceo-ralph:setup and restart Claude Code.

Task keeps failing? After max iterations, the loop stops. Check .progress.md for errors. Fix manually, then /ceo-ralph:implement to resume.

Want to start over? /ceo-ralph:cancel cleans up state. Then start fresh.

Resume existing spec? Just /ceo-ralph:start - it auto-detects and continues where you left off.

More issues? See the full Troubleshooting Guide.

Contributing

PRs welcome! This project is friendly to first-time contributors.

1. Fork it
2. Create your feature branch (git checkout -b feature/amazing)
3. Commit your changes
4. Push to the branch
5. Open a PR

Credits

• Ralph agentic loop pattern by Geoffrey Huntley
• Smart Ralph
• Claude Delegator
• Built for Claude Code
• Inspired by every developer who wished their AI could just figure out the whole feature