---
title: "Workflow: Set Up New Ralph Loop"
description: "<required_reading> **Read these reference files NOW:** 1. references/ralph-fundamentals.md 2. references/project-structure.md 3. references/prompt-design.md </required_reading>"
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/setup-new-loop
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:46:42.307Z
license: CC-BY-4.0
attribution: "Workflow: Set Up New Ralph Loop — Claudary (https://claudary.paisolsolutions.com/skills/setup-new-loop)"
---

# 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>

## Overview

# 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:

```bash
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`:

```markdown
# 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

```bash
chmod +x loop.sh
```

**Docker mode:** Also make loop-docker.sh executable:
```bash
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>

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/setup-new-loop) · https://claudary.paisolsolutions.com