Workflow: Set Up New Ralph Loop

<required_reading> Read these reference files NOW:

1. references/ralph-fundamentals.md
2. references/project-structure.md
3. references/prompt-design.md </required_reading>

<process> ## Step 1: Confirm Directory

Ask the user: "Which directory should I set up Ralph in? (provide absolute path, or I'll use current working directory)"

Wait for response. If no path provided, use current working directory from environment.

Step 2: Verify Directory Safety

Check if directory already has Ralph setup:

• Look for loop.sh, PROMPT_plan.md, PROMPT_build.md, or IMPLEMENTATION_PLAN.md
• If found, ask: "This directory appears to have Ralph files already. Overwrite? (yes/no)"
• If no, exit workflow

Step 3: Security Warning

Display to user before proceeding:

⚠️  SECURITY NOTICE

Ralph runs with --dangerously-skip-permissions, meaning it executes
commands without confirmation. This is powerful but risky.

RECOMMENDED: Run Ralph in Docker for isolation.
- Limits filesystem access to project directory
- Prevents accidental system modifications
- Sandboxes network and process execution

NON-DOCKER: Run at your own risk.
- Full access to your system as your user
- Can modify any files you can modify
- Only use in trusted, isolated environments

Step 4: Gather Project Context

Ask the user 2-4 questions using AskUserQuestion:

Question 1 (Required): "What programming language/framework is this project using?"

• Options based on common stacks (Node.js/TypeScript, Python, Go, Rust, etc.)
• This determines test commands and backpressure mechanisms

Question 2 (Required): "What kind of backpressure should Ralph use?"

• Option 1: Tests only - Unit/integration tests must pass
• Option 2: Tests + type checking - Tests and type checker (TypeScript, mypy, etc.)
• Option 3: Full validation - Tests, type checking, linting, builds
• Option 4: Custom commands - I'll specify validation commands

Question 3 (Conditional): If custom commands selected: "What validation commands should Ralph run?"

• Free text input for custom commands

Question 4 (Optional): "Do you already have specification files?"

• Yes, in specs/ directory
• Yes, but elsewhere (I'll specify)
• No, I'll create them as I go
• No, help me create initial specs

Question 5 (Required): "Run Ralph in Docker for isolation?"

• Option 1: Yes, Docker mode (Recommended) - Isolated container, safer execution, requires OAuth token setup
• Option 2: No, run directly - Faster but runs with full host access. Use at your own risk.

If Docker mode selected, check for OAuth token:

1. Check $CLAUDE_CODE_OAUTH_TOKEN env var
2. Check ~/.claude-oauth-token file
3. If neither found, instruct user: "Run claude setup-token and save to ~/.claude-oauth-token"

Step 5: Create Directory Structure

Create the following structure in target directory:

mkdir -p specs src

Essential files:

• loop.sh - Main orchestration script (from templates/loop.sh)
• PROMPT_plan.md - Planning mode instructions (from templates/PROMPT_plan.md)
• PROMPT_build.md - Building mode instructions (from templates/PROMPT_build.md)
• AGENTS.md - Operational learnings (initially empty or minimal)
• IMPLEMENTATION_PLAN.md - Task list (initially empty, generated by planning mode)

Docker mode additional files (if selected):

• Dockerfile - Container definition (from templates/Dockerfile)
• loop-docker.sh - Docker-wrapped loop script (from templates/loop-docker.sh)

Directories:

• specs/ - Requirement documents (one per topic of concern)
• src/ - Application source code

Step 6: Generate Loop Script

Use templates/loop.sh and customize:

• Set Claude model (default: opus for reasoning, can use sonnet for speed)
• Configure CLI flags based on user preferences
• Add validation commands based on backpressure choice

Step 7: Generate Planning Prompt

Use templates/PROMPT_plan.md and customize:

• Adjust subagent counts based on project size
• Reference appropriate source directories
• Include project-specific context if provided

Step 8: Generate Building Prompt

Use templates/PROMPT_build.md and customize:

• Set validation commands based on backpressure choice
• Configure subagent limits
• Add project-specific build/test instructions

Step 9: Initialize AGENTS.md

Create minimal AGENTS.md:

# Operational Learnings

This file contains project-specific guidance that Ralph has learned through observation.

Start minimal. Add entries only when Ralph exhibits repeated failures or needs specific guidance.

## Build/Test Commands

[To be filled as needed]

## Known Patterns

[To be filled as needed]

## Constraints

[To be filled as needed]

Step 10: Make Loop Executable

chmod +x loop.sh

Docker mode: Also make loop-docker.sh executable:

chmod +x loop-docker.sh

Step 11: Provide Usage Instructions

Display to user:

Ralph loop initialized in [directory]!

NEXT STEPS:

1. Create specification files in specs/:
   - One file per topic of concern
   - Use "one sentence without 'and'" test for scope
   - Example: specs/authentication.md, specs/color-extraction.md

2. Start planning mode:
   ./loop.sh plan

   This will:
   - Study your specs
   - Analyze existing code
   - Generate IMPLEMENTATION_PLAN.md
   - Exit when plan is complete

3. Start building mode:
   ./loop.sh

   This will:
   - Pick most important task from plan
   - Implement it
   - Run validation ([validation_commands])
   - Commit changes
   - Loop until stopped (Ctrl+C)

4. Limit iterations (optional):
   ./loop.sh 20        # Build mode, 20 tasks max
   ./loop.sh plan 5    # Plan mode, 5 iterations

IMPORTANT:
- Your role: Sit on the loop, not in it
- Watch for failure patterns
- Update AGENTS.md with learnings
- Regenerate plan if Ralph goes off track
- Use Ctrl+C to stop the loop anytime

SECURITY:
- Loop runs with --dangerously-skip-permissions
- Only run in trusted environments
- Use Docker mode for isolation: ./loop-docker.sh
- Minimum viable access to APIs and secrets

DOCKER MODE (if enabled):
- First run: ./loop-docker.sh --build-image
- Then: ./loop-docker.sh plan
- Then: ./loop-docker.sh
- Requires: ~/.claude-oauth-token or CLAUDE_CODE_OAUTH_TOKEN env var
- Get token: claude setup-token

FILES:
- loop.sh              - Main orchestration script
- loop-docker.sh       - Docker-wrapped loop (if Docker mode)
- Dockerfile           - Container definition (if Docker mode)
- PROMPT_plan.md       - Planning mode instructions
- PROMPT_build.md      - Building mode instructions
- AGENTS.md            - Operational learnings (update as needed)
- IMPLEMENTATION_PLAN.md  - Generated task list
- specs/               - Your requirement documents
- src/                 - Your application code

Need help? Check references/operational-learnings.md for guidance on:
- Writing effective specs
- Tuning prompts
- Adding backpressure
- Debugging loops

Step 12: Offer Spec Creation Help

Ask using AskUserQuestion: "Would you like help creating initial specification files?"

Options:

1. Yes, help me create specs - I'll guide you through defining requirements
2. No, I'll create them myself - I understand the spec structure
3. Show me an example spec - I want to see what a good spec looks like

If option 1 selected, route to workflow: create-initial-specs.md (create this workflow) If option 3 selected, display example from references/spec-examples.md (create this reference) </process>

<success_criteria> This workflow is complete when:

• Directory structure created with all required files
• loop.sh executable and customized for project
• PROMPT_plan.md generated with appropriate settings
• PROMPT_build.md generated with validation commands
• AGENTS.md initialized (empty or minimal)
• Usage instructions displayed to user
• User knows next steps (create specs, run loop)
• User offered help with spec creation </success_criteria>