---

name: init-ralph description: Initialize Ralph autonomous coding loop in a project. Use when the user wants to set up Ralph, run /init-ralph, or mentions "ralph" in the context of autonomous AI coding loops. This skill copies Ralph template files and guides the user through a conversation to configure the project goal, tech stack, build commands, and create requirement specs.

Init Ralph

Initialize the Ralph autonomous coding methodology in your project. Ralph runs Claude Code in a continuous loop using file-based state to maintain context across iterations.

Workflow

Phase 1: Copy Template Files

Copy all files from assets/templates/ to the current working directory:

./loop.sh
./PROMPT_plan.md
./PROMPT_build.md
./AGENTS.md
./ARCHITECTURE.md
./IMPLEMENTATION_PLAN.md
./specs/
./.gitignore (append if exists)

Make loop.sh executable: chmod +x loop.sh

Phase 2: Project Configuration Interview

Ask the user these questions to configure Ralph. Use the AskUserQuestion tool when appropriate for quick selections, or conversational questions for open-ended answers.

2.1 Project Basics

1. Project name: "What is your project name?"
2. Project goal: "What is the main goal of this project? (This becomes the ULTIMATE GOAL in PROMPT_plan.md)"
   • Example: "Build a mood board application that helps designers collect and organize visual inspiration"

2.2 Tech Stack & Structure

3. Tech stack: "What tech stack are you using?" (Node.js/TypeScript, Python, Go, Rust, etc.)
4. Source directory: "Where is your source code located?" (default: src/)

2.3 Build Commands (for AGENTS.md)

5. Build command: "What command builds your project?" (e.g., npm run build, cargo build, go build)
6. Test command: "What command runs your tests?" (e.g., npm test, pytest, go test ./...)
7. Typecheck command: "What command runs type checking?" (e.g., npm run typecheck, mypy ., or "none")
8. Lint command: "What command runs linting?" (e.g., npm run lint, ruff check ., or "none")

2.4 Design & Architecture

Always ask these core technical questions:

9. Design principles: "What design principles should we follow?" (e.g., SOLID, DRY, KISS, YAGNI, or describe your own)

10. Testing approach: "What testing approach do you prefer?" (TDD, test-after, integration-first, none)

11. Architecture style: "What architecture style fits this project?" (Clean Architecture, Hexagonal, MVC, Feature-based, Simple/Flat)

Then intelligently select additional questions based on the tech stack and project goal. Consider asking about:

• Database/data access (if project involves persistence): Query builder, ORM, or raw SQL? Repository pattern?
• Validation (if project has user input or API): What library? (Zod, Yup, Joi, etc.)
• Error handling: Result types, exceptions, or simple try/catch?
• API design (if building an API): REST, GraphQL, tRPC?
• State management (if frontend): What approach?
• Authentication (if applicable): What approach?

Finally, always ask:

12. Other technical decisions: "Any other technical decisions, libraries, or patterns you want to enforce?"

Phase 3: Requirements Gathering (Specs Creation)

Guide the user to define their requirements. This creates the specs/*.md files.

3.1 Identify Jobs to Be Done (JTBD)

Ask: "What are the main things users need to accomplish with this project? List the high-level jobs to be done."

Example response: "Users need to upload images, extract color palettes, arrange mood boards, and share with clients"

3.2 Break Down into Topics of Concern

For each JTBD, help break it into topics. Use the "One Sentence Without 'And'" test - if you need "and" to describe it, it's probably multiple topics.

Ask: "Let's break down [JTBD] into specific topics. What are the distinct components or concerns?"

3.3 Create Spec Files

For each topic, ask:

1. "What should [topic] do? What's its purpose?"
2. "What are the acceptance criteria? How do we know it's working?"
3. "Are there any edge cases or constraints to consider?"

Generate specs/<topic-name>.md with this structure:

# [Topic Name]

## Job to Be Done
[What user need does this address]

## Description
[What this component/feature does]

## Acceptance Criteria
- [Criterion 1]
- [Criterion 2]
- ...

## Edge Cases
- [Edge case 1]
- [Edge case 2]

Phase 4: Apply Configuration

After gathering all information:

1. Update PROMPT_plan.md: Replace {{PROJECT_GOAL}} with the user's goal and {{SOURCE_DIR}} with source directory
2. Update PROMPT_build.md: Replace {{SOURCE_DIR}} with source directory
3. Update AGENTS.md: Fill in the build/test/lint commands
4. Create ARCHITECTURE.md: Fill in the design and architecture decisions from Phase 2.4
5. Create specs/*.md: One file per topic of concern

Phase 5: Summary & Next Steps

Display a summary of what was created:

## Ralph Initialized Successfully!

### Files Created:
- loop.sh (executable)
- PROMPT_plan.md (configured with your goal)
- PROMPT_build.md
- AGENTS.md (configured with your commands)
- ARCHITECTURE.md (configured with your technical decisions)
- IMPLEMENTATION_PLAN.md (empty, will be generated)
- specs/
  - [list each spec file created]
- .gitignore (updated)

### Next Steps:

1. **Review the specs**: Check `specs/*.md` files and refine if needed

2. **Run planning mode** to generate the implementation plan:
   ```bash
   ./loop.sh plan

3. Run build mode to start implementing:

   ./loop.sh
   

Useful Commands:

• ./loop.sh plan - Run planning mode (gap analysis, creates IMPLEMENTATION_PLAN.md)
• ./loop.sh plan 5 - Planning mode, max 5 iterations
• ./loop.sh - Run build mode (implements tasks from plan)
• ./loop.sh 20 - Build mode, max 20 iterations
• Ctrl+C - Stop the loop at any time

Tips:

• If Ralph goes off track, regenerate the plan: ./loop.sh plan
• Watch the first few iterations to tune behavior
• Update AGENTS.md with operational learnings as you go

## Handling Existing Ralph Files

If Ralph files already exist in the directory:
1. Warn the user: "Ralph files already exist in this directory."
2. Ask: "Would you like to: (a) Overwrite all files, (b) Only update specs and goal, (c) Abort?"
3. Proceed based on choice

## Template Placeholders

The templates use these placeholders to replace:
- `{{PROJECT_GOAL}}` - The ultimate goal statement (PROMPT_plan.md)
- `{{SOURCE_DIR}}` - Source code directory, default `src` (PROMPT_plan.md, PROMPT_build.md)
- `{{BUILD_COMMANDS}}` - Build instructions (AGENTS.md)
- `{{TEST_COMMAND}}` - Test command (AGENTS.md)
- `{{TYPECHECK_COMMAND}}` - Typecheck command (AGENTS.md)
- `{{LINT_COMMAND}}` - Lint command (AGENTS.md)
- `{{DESIGN_PRINCIPLES}}` - Design principles to follow (ARCHITECTURE.md)
- `{{TESTING_APPROACH}}` - Testing approach (ARCHITECTURE.md)
- `{{ARCHITECTURE_STYLE}}` - Architecture style (ARCHITECTURE.md)
- `{{KEY_LIBRARIES}}` - Key libraries and roles (ARCHITECTURE.md)
- `{{OTHER_TECHNICAL_DECISIONS}}` - Other technical decisions (ARCHITECTURE.md)