### Integration Test Example: Project Setup

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Integration tests for the `setup.sh` script, verifying project directory creation, structure, and Git repository initialization.

```bash
#!/usr/bin/env bats
# Integration tests for setup.sh project initialization

load '../helpers/test_helper'
load '../helpers/fixtures'

SETUP_SCRIPT="${BATS_TEST_DIRNAME}/../../setup.sh"

setup() {
    export TEST_TEMP_DIR="$(mktemp -d)"
    export HOME="$TEST_TEMP_DIR/home"
    mkdir -p "$HOME/.ralph/templates"

    # Copy real templates for integration testing
    cp -r "${BATS_TEST_DIRNAME}/../../templates/"* "$HOME/.ralph/templates/"

    cd "$TEST_TEMP_DIR"
}

teardown() {
    cd /
    rm -rf "$TEST_TEMP_DIR"
}

@test "setup.sh creates project directory with correct structure" {
    run bash "$SETUP_SCRIPT" "test-project"

    assert_success
    assert_dir_exists "$TEST_TEMP_DIR/test-project"
    assert_dir_exists "$TEST_TEMP_DIR/test-project/specs"
    assert_dir_exists "$TEST_TEMP_DIR/test-project/src"
    assert_dir_exists "$TEST_TEMP_DIR/test-project/logs"
}

@test "setup.sh initializes git repository" {
    bash "$SETUP_SCRIPT" "test-project"

    cd "$TEST_TEMP_DIR/test-project"
    [[ -d ".git" ]]

    run git log --oneline -1
    assert_success
    [[ "$output" == *"Initial commit"* ]]
}
```

--------------------------------

### Setup and Teardown Mocks

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Install and remove mock implementations using `setup_mocks` and `teardown_mocks`. Ensure mocks are sourced before use.

```bash
setup() {
    source ".../helpers/mocks.bash"
    setup_mocks  # Install all mocks
}

teardown() {
    teardown_mocks  # Remove all mocks
}
```

--------------------------------

### Start Development Server

Source: https://github.com/frankbria/ralph-claude-code/blob/main/templates/AGENT.md

Launch a local development server for real-time updates and testing during development.

```bash
npm run dev
```

```bash
cargo run
```

--------------------------------

### Copy Project Directory

Source: https://github.com/frankbria/ralph-claude-code/blob/main/examples/rest-api/README.md

Use this command to copy the example directory to a new location for your project. Ensure you are in the parent directory of 'examples'.

```bash
cp -r examples/rest-api ~/my-bookstore-api
cd ~/my-bookstore-api
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/frankbria/ralph-claude-code/blob/main/templates/AGENT.md

Use these commands to install project dependencies based on the programming language. Ensure you have the correct package manager installed.

```bash
npm install
```

```bash
pip install -r requirements.txt
```

```bash
cargo build
```

--------------------------------

### Install Ralph Globally

Source: https://context7.com/frankbria/ralph-claude-code/llms.txt

Installs Ralph globally on your system by cloning the repository and running the install script. Verify the installation using `ralph --help` and uninstall with `./uninstall.sh`.

```bash
# One-time global installation
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

# Verify installation
ralph --help

# Uninstall completely
./uninstall.sh
# Or without the repo:
curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Installs all necessary development dependencies for the project, including testing frameworks like bats.

```bash
npm install
```

--------------------------------

### Fork, Clone, and Install Ralph

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Steps to fork the Ralph repository, clone it locally, install dependencies, and run tests.

```bash
git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
cd ralph-claude-code
npm install
npm test
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Install the BATS testing framework and other project dependencies using npm. Verify that BATS is installed correctly.

```bash
npm install

./node_modules/.bin/bats --version
```

--------------------------------

### Task Management: Just Right Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

Provides an example of a well-scoped task that represents a meaningful unit of work for a single development iteration.

```markdown
- [ ] Create auth routes with POST /login and POST /logout endpoints
- [ ] Add JWT token generation and validation middleware
- [ ] Create refresh token endpoint POST /auth/refresh

```

--------------------------------

### Initialize Git and Python Environment

Source: https://github.com/frankbria/ralph-claude-code/blob/main/examples/rest-api/README.md

Initialize a Git repository and set up a Python virtual environment. Install necessary dependencies for a FastAPI application.

```bash
git init
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn sqlalchemy pytest
```

--------------------------------

### Install Ralph Globally

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Installs Ralph globally on your system by cloning the repository and running the install script. This adds essential Ralph commands to your PATH.

```bash
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh
```

--------------------------------

### Best Practice: Test Isolation with `setup`

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Demonstrates the best practice of ensuring test isolation by setting up a fresh, unique state for each test, typically using temporary directories.

```bash
setup() {
    export TEST_TEMP_DIR="$(mktemp -d)"  # Fresh directory each test
    cd "$TEST_TEMP_DIR"
}
```

--------------------------------

### Bad PROMPT.md Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

This example demonstrates vague requirements that lack specificity and measurable criteria, leading to ambiguity for the AI.

```markdown
# Project

Make a good API for managing stuff. Use best practices.
Should be fast and work well.

```

--------------------------------

### Bash Function Documentation Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Demonstrates how to document Bash functions, including a description of what the function does, its return values, and fallback behavior.

```bash
# Get current circuit breaker state
# Returns the state as a string: CLOSED, HALF_OPEN, or OPEN
# Falls back to CLOSED if state file doesn't exist
get_circuit_state() {
    if [[ ! -f "$CB_STATE_FILE" ]]; then
        echo "$CB_STATE_CLOSED"
        return
    fi

    jq -r '.state' "$CB_STATE_FILE" 2>/dev/null || echo "$CB_STATE_CLOSED"
}
```

--------------------------------

### Install and Uninstall Ralph CLI

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Commands for installing and uninstalling the Ralph CLI tool. The install script handles global installation, while uninstall scripts or arguments can be used for removal.

```bash
./install.sh              # Install Ralph globally
./uninstall.sh            # Remove Ralph from system (dedicated script)
./install.sh uninstall    # Alternative: Remove Ralph from system
./install.sh --help       # Show installation help
```

--------------------------------

### Good PROMPT.md Example for Ralph

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

This example shows a well-structured PROMPT.md with clear context, technology stack, key principles, data entities, and quality standards, enabling Ralph to understand the project requirements effectively.

```markdown
# Ralph Development Instructions

## Context
You are Ralph, building a REST API for a pet adoption shelter.
The API manages animals, adopters, and adoption records.

## Technology Stack
- Python 3.11+ with FastAPI
- PostgreSQL with SQLAlchemy (async)
- pytest for testing
- Pydantic for validation

## Key Principles
- RESTful endpoints following standard conventions
- All endpoints require authentication except GET /animals
- Soft delete for all entities (is_deleted flag, not actual deletion)
- Pagination on all list endpoints (default 20, max 100)

## Data Entities
- Animal: name, species, breed, age, status (available/adopted/pending)
- Adopter: name, email, phone, approved (boolean)
- Adoption: animal_id, adopter_id, date, status

## Quality Standards
- Every endpoint needs at least one happy-path test
- Input validation with clear error messages
- OpenAPI documentation for all endpoints

```

--------------------------------

### Setup Utilities for Mock Data

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

These utilities help create mock files and environment variables for testing purposes. They are essential for setting up predictable test environments.

```bash
# Provided environment variables (set in setup)
$TEST_TEMP_DIR      # Unique temp directory for this test
$PROMPT_FILE        # "PROMPT.md"
$LOG_DIR            # "logs"
$STATUS_FILE        # "status.json"
$CALL_COUNT_FILE    # ".call_count"
$EXIT_SIGNALS_FILE  # ".exit_signals"

# Mock data creation
create_mock_prompt          # Create sample PROMPT.md
create_mock_fix_plan 5 2    # Create fix_plan.md (5 total, 2 completed)
create_mock_status 1 42 100 # Create status.json (loop 1, 42 calls, 100 max)
create_mock_exit_signals 0 2 0  # Create exit signals (0 test, 2 done, 0 complete)
```

--------------------------------

### Install Ralph Globally (Optional)

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Optionally, install the Ralph project globally for easier access and testing across your system.

```bash
./install.sh
```

--------------------------------

### BATS: Testing File Creation and Content

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Examples for verifying that a command creates a file and that the file contains the expected content.

```bash
@test "command creates file" {
    run my_command
    assert_file_exists "output.txt"
}

@test "file contains expected content" {
    run my_command
    [[ "$(cat output.txt)" == "expected content" ]]
}
```

--------------------------------

### Verify GNU coreutils installation

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Check the installed version of GNU coreutils to confirm that `gtimeout` is available.

```bash
gtimeout --version
```

--------------------------------

### Git Push Command Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Demonstrates how to push a feature branch to the remote repository. Ensure your branch name is descriptive.

```bash
git push origin feature/my-feature
```

--------------------------------

### Bats Test File Structure Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Provides an example of the basic structure for a Bats test file, including the shebang, loading helper modules, and test case definitions.

```bash
#!/usr/bin/env bats
# Unit Tests for Feature X

load '../helpers/test_helper'
```

--------------------------------

### Install tmux on Ubuntu/Debian

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install the tmux terminal multiplexer on Debian-based systems using apt-get.

```bash
sudo apt-get install tmux
```

--------------------------------

### Restricting Tool Permissions .ralphrc Examples

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/CLI_OPTIONS.md

Examples of `ALLOWED_TOOLS` settings in `.ralphrc` for different permission levels, from broad development access to read-only audits.

```bash
# Broad (development): all git subcommands allowed
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"
```

```bash
# Safe (default): specific git subcommands only, no destructive git commands
ALLOWED_TOOLS="Write,Read,Edit,Bash(git add *),Bash(git commit *),Bash(git diff *),Bash(git log *),Bash(git status),Bash(git push *),Bash(npm *),Bash(pytest)"
```

```bash
# Read-only audit
ALLOWED_TOOLS="Read,Grep,Glob"
```

--------------------------------

### Verifying Mock Setup in BATS Tests

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Illustrates how to ensure mocks are correctly set up and functions are exported in BATS tests. This involves calling `setup_mocks` and verifying function types.

```bash
# Verify setup_mocks was called
setup() {
    source "$(dirname "$BATS_TEST_FILENAME")/../helpers/mocks.bash"
    setup_mocks  # Must call this!
}

# Verify function is exported
type git  # Should show "git is a function"
```

--------------------------------

### Install GNU coreutils on macOS

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install GNU coreutils on macOS using Homebrew to provide the `gtimeout` command, which Ralph uses for execution timeouts.

```bash
brew install coreutils
```

--------------------------------

### Start Manual Monitoring

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Launch the Ralph monitor in a separate terminal to observe Ralph's activity.

```bash
ralph-monitor
```

--------------------------------

### Install BATS Testing Framework

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install the BATS (Bash Automated Testing System) framework and its support plugins globally using npm. This is required for running the project's test suite.

```bash
npm install -g bats bats-support bats-assert
```

--------------------------------

### Task Management: Too Small Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

Demonstrates tasks that are too granular, leading to wasted iterations and inefficiency in the development process.

```markdown
- [ ] Create the auth folder
- [ ] Create the auth/__init__.py file
- [ ] Create the auth/routes.py file

```

--------------------------------

### Run Test Suite

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Execute the project's test suite using npm test to verify your setup. A successful run should indicate 100% pass rate.

```bash
npm test
```

--------------------------------

### Local Workstation .ralphrc Configuration

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/CLI_OPTIONS.md

Example `.ralphrc` configuration for a local development environment, setting parameters like call rate limits, timeouts, and session persistence.

```bash
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"
CLAUDE_AUTO_UPDATE=true
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24
```

--------------------------------

### Reproducing CI Environment Locally

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Commands to set up a local environment that matches the CI environment for debugging, including Node.js version, dependency installation, and running tests in the specified order.

```bash
# Match CI environment
nvm use 18
npm ci  # Clean install (not npm install)

# Run tests in CI order
npm run test:unit
npm run test:integration
npm run test:e2e

# Check for environment-specific issues
uname -a  # OS differences
bash --version  # Bash version
```

--------------------------------

### Bash JSON State Management Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Demonstrates safe JSON state management in Bash scripts, including validation before parsing and using `jq` for parsing.

```bash
# Always validate JSON before parsing
if ! jq '.' "$STATE_FILE" > /dev/null 2>&1; then
    echo "Error: Invalid JSON in state file"
    return 1
fi

# Use jq for safe parsing
local state=$(jq -r '.state' "$STATE_FILE" 2>/dev/null || echo "CLOSED")
```

--------------------------------

### Use Custom Prompt File with Ralph

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Specify a custom prompt file to guide Ralph's development instructions. Supports integrated monitoring.

```bash
# Use custom prompt file
ralph --prompt my_custom_instructions.md

# With integrated monitoring
ralph --monitor --prompt my_custom_instructions.md
```

--------------------------------

### Enable Live Streaming Output in Ralph

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Get real-time visibility into Claude Code execution with live streaming. Output is logged to .ralph/live.log.

```bash
# Enable real-time visibility into Claude Code execution
ralph --live

# Combine with monitoring for best experience
ralph --monitor --live

# Live output is written to .ralph/live.log
tail -f .ralph/live.log  # Watch in another terminal
```

--------------------------------

### Unit Test Example: Rate Limiting Logic

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

A unit test for the `can_make_call` function, demonstrating setup and teardown for test isolation and assertions on success and failure conditions.

```bash
#!/usr/bin/env bats
# Unit Tests for Rate Limiting Logic

load '../helpers/test_helper'

setup() {
    source "$(dirname "$BATS_TEST_FILENAME")"/../helpers/test_helper.bash

    export MAX_CALLS_PER_HOUR=100
    export CALL_COUNT_FILE=".call_count"
    export TEST_TEMP_DIR="$(mktemp -d /tmp/ralph-test.XXXXXX)"
    cd "$TEST_TEMP_DIR"

    echo "0" > "$CALL_COUNT_FILE"
}

teardown() {
    cd /
    rm -rf "$TEST_TEMP_DIR"
}

# Define the function being tested (extracted from production code)
can_make_call() {
    local calls_made=0
    [[ -f "$CALL_COUNT_FILE" ]] && calls_made=$(cat "$CALL_COUNT_FILE")
    [[ $calls_made -ge $MAX_CALLS_PER_HOUR ]] && return 1
    return 0
}

@test "can_make_call returns success when under limit" {
    echo "50" > "$CALL_COUNT_FILE"
    run can_make_call
    assert_success
}

@test "can_make_call returns failure when at limit" {
    echo "100" > "$CALL_COUNT_FILE"
    run can_make_call
    assert_failure
}
```

--------------------------------

### Create New Project from Scratch

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Sets up a new, blank Ralph project. Manually configure project requirements by editing the `.ralph/PROMPT.md`, `.ralph/specs/`, and `.ralph/fix_plan.md` files.

```bash
# Create blank Ralph project
ralph-setup my-awesome-project
cd my-awesome-project

# Configure your project requirements manually
# Edit .ralph/PROMPT.md with your project goals
# Edit .ralph/specs/ with detailed specifications
# Edit .ralph/fix_plan.md with initial priorities

# Start autonomous development
ralph --monitor
```

--------------------------------

### Best Practice: Focused Test Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Illustrates the best practice of writing tests that focus on a single behavior, contrasting a good, specific test with a bad, overly broad one.

```bash
# Good: focused test
@test "increment counter increases value by 1" { ... }

# Bad: multiple behaviors
@test "counter increments and respects limit and resets hourly" { ... }
```

--------------------------------

### Create and Initialize Node.js Project

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/01-quick-start.md

Use these bash commands to create a new project directory, navigate into it, initialize a Node.js project with npm, and set up a Git repository.

```bash
mkdir todo-cli
cd todo-cli
npm init -y
git init
```

--------------------------------

### Initialize Git and NPM

Source: https://github.com/frankbria/ralph-claude-code/blob/main/examples/simple-cli-tool/README.md

Initialize a new git repository and npm project in the copied directory.

```bash
git init
npm init -y
```

--------------------------------

### Checking for jq Installation

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Verifies if the `jq` command-line JSON processor is installed. If not, it prints a message and provides installation commands for Ubuntu/Debian and macOS.

```bash
# Check jq is available
which jq || echo "jq not installed"

# Install if missing
# Ubuntu/Debian
sudo apt-get install jq

# macOS
brew install jq
```

--------------------------------

### Install tmux on macOS

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install the tmux terminal multiplexer on macOS using Homebrew.

```bash
brew install tmux
```

--------------------------------

### Create a New Ralph-Managed Project

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CLAUDE.md

Use this command to initialize a new project managed by Ralph. Navigate into the project directory after creation.

```bash
ralph-setup my-project-name
cd my-project-name
```

--------------------------------

### Install tmux on CentOS/RHEL

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install the tmux terminal multiplexer on CentOS/RHEL systems using yum.

```bash
sudo yum install tmux
```

--------------------------------

### Create Sample Ralph Project Files

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Generate sample project files and structures for Ralph projects, including prompt, fix plan, and agent files.

```bash
# Create sample Ralph project files
create_sample_prompt "PROMPT.md"
create_sample_fix_plan "fix_plan.md" 10 3  # 10 tasks, 3 completed
create_sample_agent_md "AGENT.md"

# Create complete project structure
create_test_project "project-name"
# Creates: PROMPT.md, fix_plan.md, AGENT.md, specs/, src/, logs/, etc.
```

--------------------------------

### Bash Script Structure Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Illustrates the recommended structure for Bash scripts, including shebang, description, sourcing dependencies, configuration constants, helper functions, main logic, and execution.

```bash
#!/bin/bash
# Script description
# Purpose and usage notes

# Source dependencies
source "$(dirname "${BASH_SOURCE[0]}")/lib/date_utils.sh"

# Configuration constants (UPPER_CASE)
MAX_CALLS_PER_HOUR=100
CB_NO_PROGRESS_THRESHOLD=3
STATUS_FILE="status.json"

# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'

# Helper functions (snake_case)
helper_function() {
    local param1=$1
    local param2=$2
    # Implementation
}

# Main logic
main() {
    # Entry point
}

# Export functions for reuse
export -f helper_function

# Execute main if run directly
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi
```

--------------------------------

### Customize Ralph Development Instructions

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/01-quick-start.md

Replace the placeholder content in `.ralph/PROMPT.md` to define the context, objectives, and key principles for Ralph's development tasks. This example outlines building a CLI todo app.

```markdown
# Ralph Development Instructions

## Context
You are Ralph, an autonomous AI development agent building a CLI todo application in Node.js.

## Current Objectives
1. Create a command-line todo app with add, list, complete, and delete commands
2. Store todos in a JSON file (~/.todos.json)
3. Use commander.js for argument parsing
4. Include helpful --help output
5. Write unit tests with Jest

## Key Principles
- Keep the code simple and readable
- Use async/await for file operations
- Provide clear error messages
- Follow Node.js best practices
```

--------------------------------

### PROMPT.md Example: Project Vision

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/02-understanding-ralph-files.md

Use this file to define high-level project goals, principles, technology stack, and quality standards. Avoid step-by-step tasks or detailed API specifications here.

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

--------------------------------

### Install Claude Code CLI

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Install the Claude Code CLI globally using npm or use `npx`. Ensure `CLAUDE_CODE_CMD` is set in `.ralphrc` if using `npx`.

```bash
npm install -g @anthropic-ai/claude-code
```

--------------------------------

### Running BATS Tests with Options

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Demonstrates how to run BATS tests with different options for verbose output, TAP format, and timing information. Useful for debugging and analyzing test execution.

```bash
# Verbose output shows each test
bats --verbose-run tests/unit/test_rate_limiting.bats

# TAP format for parsing
bats --tap tests/unit/test_rate_limiting.bats

# Timing information
bats --timing tests/unit/test_rate_limiting.bats
```

--------------------------------

### Conventional Commit Title Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Provides an example of a commit title following the conventional commit format. This format helps in automating changelog generation and semantic versioning.

```markdown
feat(loop): add dry-run mode for testing
```

--------------------------------

### RALPH_STATUS Block Example

Source: https://context7.com/frankbria/ralph-claude-code/llms.txt

An example of the RALPH_STATUS block that Claude must include in its responses. This block provides essential signals for the response analyzer, such as completion status, task counts, and exit intent.

```text
# RALPH_STATUS block that Claude must include in every response:
# ---RALPH_STATUS---
# STATUS: IN_PROGRESS | COMPLETE | BLOCKED
# TASKS_COMPLETED_THIS_LOOP: 3
# FILES_MODIFIED: 7
# TESTS_STATUS: PASSING | FAILING | NOT_RUN
# WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
# EXIT_SIGNAL: false | true
# RECOMMENDATION: Continue with next task from fix_plan.md
# ---END_RALPH_STATUS---
```

--------------------------------

### fix_plan.md Example: Task List

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/02-understanding-ralph-files.md

This file serves as a prioritized checklist for Ralph. You can add, reorder, or remove tasks. Ralph checks off completed items and may add new ones it discovers. Use a clear structure for better results.

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

--------------------------------

### Bash Test Setup and Teardown

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Defines setup and teardown functions for BATS tests, creating and cleaning up an isolated test environment. Ensure these functions are correctly implemented for reliable test execution.

```bash
setup() {
    source "$(dirname "$BATS_TEST_FILENAME")/../helpers/test_helper.bash"

    # Create isolated test environment
    export TEST_TEMP_DIR="$(mktemp -d /tmp/ralph-test.XXXXXX)"
    cd "$TEST_TEMP_DIR"

    # Initialize test state
    echo "0" > ".call_count"
}

# Teardown runs after each test
teardown() {
    cd /
    rm -rf "$TEST_TEMP_DIR"
}
```

--------------------------------

### Best Practice: State Restoration with `teardown`

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Illustrates the best practice of cleaning up and restoring system state after a test runs, including restoring mocked commands and removing temporary files.

```bash
teardown() {
    teardown_mocks  # Restore mocked commands
    cd /
    rm -rf "$TEST_TEMP_DIR"  # Clean up files
}
```

--------------------------------

### Source Initialization Script for Ralph

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/CLI_OPTIONS.md

Source a script before each loop to set up the environment, such as activating a virtualenv or modifying the PATH. Ralph will warn if the file is set but missing and skip sourcing if it does not exist.

```bash
RALPH_SHELL_INIT_FILE=".ralph/init.sh"
```

--------------------------------

### Conventional Commits: Documentation Update

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Example of a commit message for documentation changes, indicating the scope of the update.

```bash
docs(status): update IMPLEMENTATION_STATUS.md with phased structure
```

--------------------------------

### Build Project for Production

Source: https://github.com/frankbria/ralph-claude-code/blob/main/templates/AGENT.md

Generate a production-ready build of your project. Use the release flag for optimized builds in Rust.

```bash
npm run build
```

```bash
cargo build --release
```

--------------------------------

### Start Ralph Autonomous Development Loop

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/01-quick-start.md

Initiate Ralph's autonomous development process by running this command. It opens a tmux session to monitor Ralph's progress, including output and a live dashboard.

```bash
ralph --monitor
```

--------------------------------

### Project Structure Overview

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Understand the standardized directory structure created by Ralph for projects. Key configuration and state files reside in the `.ralph/` subfolder, with source code at the project root.

```text
my-project/
├── .ralph/                 # Ralph configuration and state (hidden folder)
│   ├── PROMPT.md           # Main development instructions for Ralph
│   ├── fix_plan.md        # Prioritized task list
│   ├── AGENT.md           # Build and run instructions
│   ├── specs/              # Project specifications and requirements
│   │   └── stdlib/         # Standard library specifications
│   ├── examples/           # Usage examples and test cases
│   ├── logs/               # Ralph execution logs
│   └── docs/generated/     # Auto-generated documentation
├── .ralphrc                # Ralph configuration file (tool permissions, settings)
└── src/                    # Source code implementation (at project root)

```

--------------------------------

### Conventional Commits: Test Addition

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Example of a commit message for adding or updating tests, specifying the area being tested.

```bash
test(cli): add 27 comprehensive CLI parsing tests
```

--------------------------------

### specs/stdlib Example: Error Responses

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

A specification file defining standard error response formats for project-wide consistency.

```markdown

```

--------------------------------

### Create Sample Status Files

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Generate sample JSON files representing different status states for a running process, such as running, completed, or executing.

```bash
# Create sample status files
create_sample_status_running "status.json"
create_sample_status_completed "status.json"
create_sample_progress_executing "progress.json"
```

--------------------------------

### Task referencing API Specification

Source: https://github.com/frankbria/ralph-claude-code/blob/main/examples/rest-api/README.md

Example of a task in fix_plan.md that references the detailed API specifications located in specs/api.md.

```markdown
- [ ] Implement book endpoints per specs/api.md
```

--------------------------------

### Create Sample PRD Documents

Source: https://github.com/frankbria/ralph-claude-code/blob/main/TESTING.md

Generate sample PRD (Product Requirements Document) files in different formats (Markdown, text, JSON) for testing.

```bash
# Create sample PRD documents
create_sample_prd_md "output.md"    # Markdown PRD
create_sample_prd_txt "output.txt"  # Plain text PRD
create_sample_prd_json "output.json" # JSON PRD
```

--------------------------------

### Conventional Commits: Bug Fix

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Example of a commit message for fixing a bug, specifying the scope and referencing the issue fixed.

```bash
fix(loop): replace non-existent --prompt-file with -p flag
```

--------------------------------

### Manage Ralph Projects with CLI

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Commands for setting up, enabling, and managing Ralph projects. Includes options for converting specifications and enabling Ralph in existing projects.

```bash
ralph-setup project-name     # Create new Ralph project
ralph-enable                 # Enable Ralph in existing project (interactive)
ralph-enable-ci              # Enable Ralph in existing project (non-interactive)
ralph-import prd.md project  # Convert PRD/specs to Ralph project
ralph --monitor              # Start with integrated monitoring
ralph --status               # Check current loop status
ralph --verbose              # Enable detailed progress updates
ralph --timeout 30           # Set 30-minute execution timeout
ralph --calls 50             # Limit to 50 API calls per hour
ralph --reset-session        # Reset session state manually
ralph --live                 # Enable live streaming output
ralph-monitor                # Manual monitoring dashboard
```

--------------------------------

### Conventional Commits: Feature Addition

Source: https://github.com/frankbria/ralph-claude-code/blob/main/CONTRIBUTING.md

Example of a commit message for adding a new feature, following the Conventional Commits format.

```bash
feat(import): add JSON output format support
```

--------------------------------

### Markdown for Specifying Authentication Preferences

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

Provide specific details about the desired authentication method and token management to guide the AI.

```markdown
Use JWT authentication with 1-hour token expiry.
Refresh tokens last 7 days and rotate on use.
```

--------------------------------

### Task Management: Too Big Example

Source: https://github.com/frankbria/ralph-claude-code/blob/main/docs/user-guide/03-writing-requirements.md

Illustrates an overly broad task that is too large for Ralph to effectively begin working on, hindering progress.

```markdown
- [ ] Build the entire authentication system

```

--------------------------------

### Enable Ralph in Existing Project

Source: https://github.com/frankbria/ralph-claude-code/blob/main/README.md

Initializes Ralph in an existing project using an interactive wizard or by specifying a task source. Use `--monitor` to start the autonomous development loop.

```bash
cd my-existing-project
ralph-enable
ralph --monitor
```

```bash
ralph-enable --from beads
ralph-enable --from github --label "sprint-1"
ralph-enable --from prd ./docs/requirements.md
```