Ralph Init

Ralph Init

Initialize a project with the Ralph workflow for autonomous AI-driven development.

The Ralph Workflow

Ralph is Geoffrey Huntley's loop-based autonomous development methodology.

Three Phases:

1. Define - Write specs for topics of concern (specs/*.md)
2. Plan - Gap analysis: compare specs vs code → IMPLEMENTATION_PLAN.md
3. Build - Implement one task per loop, commit, repeat

Core Principles:

• Context is everything - Fresh context each iteration, subagents preserve main context
• Backpressure steers quality - Tests/typechecks/lints reject invalid work
• Let Ralph Ralph - Trust self-correction through iteration, plans are disposable

Reference: Ralph Playbook

Project Structure

IMPORTANT: Workflow files ALWAYS at project root. Specs in specs/ at root.

project/
├── loop.sh                    # Ralph loop script (runs from here)
├── PROMPT_plan.md             # Planning mode prompt
├── PROMPT_build.md            # Building mode prompt
├── IMPLEMENTATION_PLAN.md     # Task list (generated/updated by Ralph)
├── AGENTS.md                  # Operational guide (~60 lines max, brief!)
├── specs/                     # Specifications directory
│   ├── README.md              # Lookup table: spec → code
│   └── [topic].md             # One spec per topic of concern
└── src/                       # Source code
    └── lib/                   # Shared utilities & components

Why root? The loop runs from project root. PROMPTs reference specs/* and @IMPLEMENTATION_PLAN.md. Everything must be accessible from root.

AGENTS.md must stay brief: Operational commands only. No status updates, no progress notes. Those go in IMPLEMENTATION_PLAN.md. A bloated AGENTS.md pollutes every loop's context.

Step 1: Gather Project Info

Ask the user:

1. Project name - Name for AGENTS.md header
2. Specs location - Where will specs live? (default: specs/)
3. Source location - Where is source code? (default: src)
4. Project goal - One sentence describing what success looks like
5. Key commands - Build, test, typecheck, lint commands (can leave as placeholders)

Step 2: Copy Templates

Templates location: ~/.agents/skills/ralph-init/templates/

CRITICAL: Copy templates VERBATIM. Do NOT improvise. The numbered rules (99999, 999999, etc.) are intentional.

Step 3: Create specs/README.md

The specs README is a lookup table linking specs to code. Follow the Loom pattern:

# [Project] Specifications

[One-line description]

## [Category Name]

| Spec | Code | Purpose |
|------|------|---------|
| [spec-name.md](./spec-name.md) | [dir/](../src/dir/) | Brief purpose |

Keep it clean:

• No workflow documentation (that's in PROMPT files)
• No verbose explanations
• Just specs linked to code they affect
• Group by logical category if many specs

Step 4: Make Executable

chmod +x loop.sh

Step 5: Summary

Ralph initialized!

Created at project root:
  loop.sh                 - Run with ./loop.sh or ./loop.sh plan
  PROMPT_plan.md          - Planning mode (gap analysis)
  PROMPT_build.md         - Building mode (implementation)
  AGENTS.md               - Operational guide (keep brief!)
  IMPLEMENTATION_PLAN.md  - Task list
  specs/README.md         - Spec index

Usage:
  1. Write specs in specs/
  2. ./loop.sh plan       # Generate implementation plan
  3. Review plan
  4. ./loop.sh            # Start building

Template Placeholders