---
title: "Project Structure"
description: "Required files and directory layout for a Ralph loop."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/project-structure-3
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:37:09.039Z
license: CC-BY-4.0
attribution: "Project Structure — Claudary (https://claudary.paisolsolutions.com/skills/project-structure-3)"
---

# Project Structure
Required files and directory layout for a Ralph loop.

## Overview

# 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:**
```bash
#!/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:
```bash
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>

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/project-structure-3) · https://claudary.paisolsolutions.com