Skip to content

02-understanding-ralph-files.md

Latest commit

 

History

History
245 lines (191 loc) · 9.24 KB

02-understanding-ralph-files.md

File metadata and controls

245 lines (191 loc) · 9.24 KB

Understanding Ralph Files

After running ralph-enable, ralph-import, or ralph-setup, you'll have a .ralph/ directory with several files. This guide explains what each file does and whether you need to edit it.

File Reference Table

File Auto-Generated? Who Writes It Who Reads It You Should...
.ralph/PROMPT.md Yes (with smart defaults) You customize it Ralph reads every loop Review and customize project goals
.ralph/fix_plan.md Yes (can import tasks) You + Ralph updates Ralph reads and updates Add/modify specific tasks
.ralph/AGENT.md Yes (detects build commands) Ralph maintains Ralph reads for build/test Rarely edit (auto-maintained)
.ralph/specs/ Empty directory created You add files when needed Ralph reads for context Add when PROMPT.md isn't detailed enough
.ralph/specs/stdlib/ Empty directory created You add reusable patterns Ralph reads for conventions Add shared patterns and conventions
.ralphrc Yes (project-aware) Usually leave as-is Ralph reads at startup Rarely edit (sensible defaults)
.ralph/logs/ Created automatically Ralph writes logs You review for debugging Don't edit (read-only)
.ralph/status.json Created at runtime Ralph updates Monitoring tools Don't edit (read-only)

The Core Files

PROMPT.md - Your Project Vision

Purpose: High-level instructions that Ralph reads at the start of every loop.

What to include:

  • Project description and goals
  • Key principles or constraints
  • Technology stack and frameworks
  • Quality standards

What NOT to include:

  • Step-by-step implementation tasks (use fix_plan.md)
  • Detailed API specifications (use specs/)
  • Build commands (use AGENT.md)

Example:

## Context
You are Ralph, building a REST API for a bookstore inventory system.

## Key Principles
- Use FastAPI with async database operations
- Follow REST conventions strictly
- Every endpoint needs tests
- Document all API endpoints with OpenAPI

fix_plan.md - Your Task List

Purpose: Prioritized checklist of tasks Ralph works through.

Key characteristics:

  • Ralph checks off [x] items as it completes them
  • Ralph may add new tasks it discovers
  • You can add, reorder, or remove tasks anytime
  • More specific tasks = better results

Good task structure:

## Priority 1: Foundation
- [ ] Create database models for Book and Author
- [ ] Set up SQLAlchemy with async support
- [ ] Create Alembic migration for initial schema

## Priority 2: API Endpoints
- [ ] POST /books - create a new book
- [ ] GET /books - list all books with pagination
- [ ] GET /books/{id} - get single book with author details

Bad task structure:

- [ ] Make the API work
- [ ] Add features
- [ ] Fix bugs

specs/ - Detailed Specifications

Purpose: When PROMPT.md isn't enough detail for a feature.

When to use specs/:

  • Complex features needing detailed requirements
  • API contracts that must be followed exactly
  • Data models with specific validation rules
  • External system integrations

When NOT to use specs/:

  • Simple CRUD operations
  • Features already well-explained in PROMPT.md
  • General coding standards (put in PROMPT.md)

Example structure:

.ralph/specs/
├── api-contracts.md      # OpenAPI-style endpoint definitions
├── data-models.md        # Entity relationships and validations
└── third-party-auth.md   # OAuth integration requirements

specs/stdlib/ - Standard Library Patterns

Purpose: Reusable patterns and conventions for your project.

What belongs here:

  • Error handling patterns
  • Logging conventions
  • Common utility functions specifications
  • Testing patterns
  • Code style decisions

Example:

# Error Handling Standard

All API errors must return:
{
  "error": {
    "code": "BOOK_NOT_FOUND",
    "message": "No book with ID 123 exists",
    "details": {}
  }
}

Use HTTPException with these codes:
- 400: Validation errors
- 404: Resource not found
- 409: Conflict (duplicate)
- 500: Internal errors (log full trace)

AGENT.md - Build Instructions

Purpose: How to build, test, and run the project.

Who maintains it: Primarily Ralph, as it discovers build commands.

When you might edit:

  • Setting initial build commands for a complex project
  • Adding environment setup steps
  • Documenting deployment commands

.ralphrc - Project Configuration

Purpose: Project-specific Ralph settings.

Default contents (usually fine as-is):

PROJECT_NAME="my-project"
PROJECT_TYPE="typescript"
MAX_CALLS_PER_HOUR=100
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

When to edit:

  • Restricting tool permissions for security
  • Adjusting rate limits
  • Changing session timeout

File Relationships

┌─────────────────────────────────────────────────────────────┐
│                         PROMPT.md                           │
│            (High-level goals and principles)                │
│                              │                              │
│                              ▼                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                      specs/                          │   │
│  │         (Detailed requirements when needed)          │   │
│  │                                                      │   │
│  │  specs/api.md ──────▶ Informs fix_plan.md tasks     │   │
│  │  specs/stdlib/ ─────▶ Conventions Ralph follows     │   │
│  └─────────────────────────────────────────────────────┘   │
│                              │                              │
│                              ▼                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    fix_plan.md                       │   │
│  │          (Concrete tasks Ralph executes)             │   │
│  │                                                      │   │
│  │  [ ] Task 1 ◄────── Ralph checks off when done      │   │
│  │  [x] Task 2                                         │   │
│  │  [ ] Task 3 ◄────── Ralph adds discovered tasks     │   │
│  └─────────────────────────────────────────────────────┘   │
│                              │                              │
│                              ▼                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                     AGENT.md                         │   │
│  │        (How to build/test - auto-maintained)         │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

Common Scenarios

Scenario 1: Simple feature addition

Just edit fix_plan.md:

- [ ] Add a /health endpoint that returns {"status": "ok"}

Scenario 2: Complex feature with specific requirements

Add a spec file first, then tasks:

  1. Create .ralph/specs/search-feature.md:
# Search Feature Specification

## Requirements
- Full-text search on book titles and descriptions
- Must support:
  - Exact phrase matching: "lord of the rings"
  - Boolean operators: fantasy AND epic
  - Fuzzy matching for typos
  1. Then add to fix_plan.md:
- [ ] Implement search per specs/search-feature.md

Scenario 3: Establishing team conventions

Add to specs/stdlib/:

# Logging Conventions

All service methods must log:
- Entry with parameters (DEBUG level)
- Exit with result summary (DEBUG level)
- Errors with full context (ERROR level)

Tips for Success

  1. Start simple - Begin with just PROMPT.md and fix_plan.md. Add specs/ only when needed.

  2. Be specific - Vague requirements produce vague results. "Add user auth" is worse than "Add JWT authentication with /login and /logout endpoints".

  3. Let fix_plan.md evolve - Ralph will add tasks it discovers. Review periodically and reprioritize.

  4. Don't over-specify - If Claude can figure it out from context, you don't need to specify it.

  5. Review logs - When something goes wrong, .ralph/logs/ tells you what Ralph was thinking.