Project Structure

Required files and directory layout for a Ralph loop.

<essential_files>

Essential Files

loop.sh

Main orchestration script that runs the loop.

Minimal implementation:

#!/bin/bash
while :; do cat PROMPT.md | claude ; done

Production implementation:

• Mode switching (plan vs build)
• Iteration limits
• CLI flag configuration
• Error handling

Located at project root.

PROMPT_plan.md

Instructions for planning mode. Tells Claude to:

• Study specs and existing code
• Perform gap analysis
• Generate/update IMPLEMENTATION_PLAN.md
• NOT implement anything

Located at project root.

PROMPT_build.md

Instructions for building mode. Tells Claude to:

• Read the implementation plan
• Select most important task
• Search existing code
• Implement functionality
• Run validation
• Update plan
• Commit changes

Located at project root.

IMPLEMENTATION_PLAN.md

The persistent task list that survives across iterations.

Generated by: Planning mode Updated by: Building mode (marks tasks complete, adds findings) Format: Markdown with prioritized list

This is the ONLY state that persists between loop iterations. Everything else is fresh context.

Initially empty. Created by first planning mode run.

AGENTS.md

Operational learnings specific to this project.

Purpose: Capture patterns Ralph needs to know Updated by: You (the observer) Format: Markdown with sections

Start minimal (even empty). Add guidance only when Ralph exhibits repeated failures or needs project-specific context.

Common sections:

• Build/Test Commands
• Known Patterns
• Discovered Constraints
• Learned Best Practices

Located at project root. </essential_files>

<directory_structure>

Directory Structure

project-root/
├── loop.sh                    # Orchestration script (executable)
├── PROMPT_plan.md             # Planning mode instructions
├── PROMPT_build.md            # Building mode instructions
├── AGENTS.md                  # Operational learnings (starts minimal)
├── IMPLEMENTATION_PLAN.md     # Task list (generated by planning)
├── specs/                     # Requirement documents
│   ├── topic-1.md
│   ├── topic-2.md
│   └── ...
└── src/                       # Application source code
    ├── lib/                   # Shared utilities
    └── ...

specs/ Directory

Requirement documents following "one sentence without 'and'" principle.

One file per topic of concern:

• ✓ specs/authentication.md - Describes auth requirements
• ✓ specs/color-extraction.md - Describes color analysis requirements
• ✗ specs/user-system.md - Too broad (auth AND profiles AND billing)

Format:

• Markdown
• Clear requirements
• Examples where helpful
• Acceptance criteria
• NOT implementation details (that's Ralph's job)

src/ Directory

Application source code. Structure depends on language/framework.

Common pattern:

src/
├── lib/              # Shared utilities
├── components/       # Reusable components
├── features/         # Feature-specific code
└── tests/           # Test files

Ralph learns patterns from existing code in src/. Consistent structure helps Ralph maintain consistency. </directory_structure>

<optional_directories>

Optional Directories

.git/

Version control. Ralph commits after each task.

Required for:

• Tracking changes
• Reverting mistakes
• Reviewing what Ralph did

Initialize before starting loop:

git init
git add .
git commit -m "Initial commit"

tests/

Test files for validation backpressure.

Location: Depends on language/framework

• JavaScript/TypeScript: Often src/__tests__/ or tests/
• Python: Often tests/ at root
• Go: Test files alongside source (*_test.go)

Ralph needs runnable tests to create backpressure. If no tests exist, Ralph has no feedback mechanism.

.github/ or .gitlab/

CI/CD configuration (optional).

Ralph can update these, but they're not core to the loop mechanism. </optional_directories>

<file_loading_order>

File Loading Order

Each loop iteration loads files in this order:

1. PROMPT.md (or mode-specific variant)

   • First ~5,000 tokens
   • Sets the objective

2. AGENTS.md

   • Project-specific learnings
   • Patterns Ralph needs to know

3. IMPLEMENTATION_PLAN.md

   • Current task list
   • What's done, what's pending

4. specs/

   • Requirement documents
   • Loaded via subagents (parallel)

5. src/

   • Existing code (as needed)
   • Loaded via subagents (parallel)

Total context budget: ~176K usable tokens from 200K window.

Optimize by:

• Keeping PROMPT.md tight
• Keeping AGENTS.md minimal
• Using parallel subagents for reading
• One task per iteration (focused context) </file_loading_order>

<topic_of_concern_scope>

Topic of Concern Scope

Test: Can you describe the topic in one sentence without "and"?

Good examples:

• "Authentication handles user login and session management" → Split into:

  • authentication.md - User login with credentials
  • session-management.md - Session lifecycle and validation

• "Color extraction analyzes images for dominant colors" → Keep as one:

  • color-extraction.md - Single topic, no conjunction needed

Why this matters:

• Each spec file should have clear, focused requirements
• Ralph works better with well-scoped tasks
• Easier to validate completion
• Simpler to update when requirements change

If unsure:

• Start with separate files
• Merge later if topics are truly coupled
• Bias toward focused specs </topic_of_concern_scope>

<minimal_viable_structure>

Minimal Viable Structure

Absolute minimum to start a Ralph loop:

project-root/
├── loop.sh                    # Minimal bash loop
├── PROMPT_build.md            # Building instructions
├── IMPLEMENTATION_PLAN.md     # Empty initially
└── src/                       # Your code

You can skip:

• PROMPT_plan.md - Write plan manually
• AGENTS.md - Start with empty file
• specs/ - Embed requirements in PROMPT_build.md

But you should have:

• Version control (git)
• Tests (for backpressure)
• Clear requirements (somewhere)

Recommended: Use full structure. The overhead is minimal, and you'll want it as the loop runs. </minimal_viable_structure>