Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• TESTING.md
• CLAUDE.md
• README.md
• IMPLEMENTATION_PLAN.md
• create_files.sh
• templates/AGENT.md
• tests/helpers/fixtures.bash

This guide provides a comprehensive overview of how to contribute to the Ralph for Claude Code project. It covers everything from setting up your development environment to submitting pull requests, ensuring that all contributions align with the project's established patterns and quality standards. Following these guidelines helps maintain code quality, consistency, and a clear development history.

Every contribution, from fixing typos to implementing major features, is valued. For a high-level overview of the project, please see the README.md. For technical specifications, refer to CLAUDE.md.

Sources: CONTRIBUTING.md:3-6

Getting Started

Prerequisites

Before you begin, ensure the following tools are installed on your system:

• Bash 4.0+: For script execution.
• jq: For JSON processing.
• git: For version control.
• tmux: Recommended for running the monitor.
• Node.js 18+: For running the test suite via npm.

Sources: CONTRIBUTING.md:15-22

Setup and Installation

1. Fork the repository on GitHub, then clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/ralph-claude-code.git
   cd ralph-claude-code
   

   Sources: CONTRIBUTING.md:25-28

2. Install the BATS testing framework and its dependencies:

   npm install
   

   Sources: CONTRIBUTING.md:31-32

3. Verify your setup by running the full test suite. All tests must pass.

   npm test
   

   Sources: CONTRIBUTING.md:38-39

Project Structure

The repository is organized into several key directories containing scripts, libraries, templates, and tests.

ralph-claude-code/
├── ralph_loop.sh        # Main loop script
├── ralph_monitor.sh     # Live monitoring dashboard
├── setup.sh             # Project initialization
├── ralph_import.sh      # PRD import tool
├── install.sh           # Global installation script
├── lib/                 # Modular library components
│   ├── circuit_breaker.sh
│   ├── response_analyzer.sh
│   └── date_utils.sh
├── templates/           # Project templates
├── tests/               # Test suite
│   ├── unit/            # Unit tests
│   ├── integration/     # Integration tests
│   ├── e2e/             # End-to-end tests
│   └── helpers/         # Test utilities
└── docs/                # Documentation

Sources: CONTRIBUTING.md:44-63

Development Workflow

Contributions should follow a structured workflow involving feature branches, conventional commits, and pull requests. Never work directly on the main branch.

Sources: CONTRIBUTING.md:67-69

Branch Naming Conventions

Create a new branch from main for each feature or fix. The branch name should follow a specific format based on the type of change.

Branch Type	Format	Example
New features	feature/<feature-name>	feature/log-rotation
Bug fixes	fix/<issue-name>	fix/rate-limit-reset
Documentation	docs/<doc-update>	docs/api-reference
Tests	test/<test-area>	test/circuit-breaker
Refactoring	refactor/<area>	refactor/response-analyzer

Sources: CONTRIBUTING.md:72-79, templates/AGENT.md:63-64

Commit Message Format

This project uses Conventional Commits to maintain a clear and structured commit history. Each commit message must adhere to this format.

<type>(<scope>): <description>

[optional body]

[optional footer]

The following table details the allowed commit types:

Type	Description	Example
feat	A new feature	feat(loop): add dry-run mode
fix	A bug fix	fix(monitor): correct refresh rate
docs	Documentation only changes	docs(readme): update installation steps
test	Adding or updating tests	test(setup): add template validation tests
refactor	A code change that neither fixes a bug nor adds a feature	refactor(analyzer): simplify error detection
chore	Build process or auxiliary tool changes	chore(deps): update bats-assert

Sources: CONTRIBUTING.md:86-108, templates/AGENT.md:55-58

Contribution Flow

The overall contribution workflow is a standard fork-and-pull model.

This diagram illustrates the standard contribution workflow from forking the repository to merging a pull request.

Code Style Guidelines

All scripts must follow consistent Bash conventions to ensure readability and maintainability.

Sources: CONTRIBUTING.md:139-140

Bash Best Practices

A standard script file has a defined structure including shebang, description, dependencies, constants, helper functions, and a main entry point.

Element	Convention	Example
Functions	snake_case	get_circuit_state()
Local variables	snake_case	local loop_count=0
Constants	UPPER_SNAKE_CASE	MAX_CALLS_PER_HOUR
File names	snake_case.sh	circuit_breaker.sh
Control files	@ prefix	@fix_plan.md

Sources: CONTRIBUTING.md:163-170

Functions should be documented to explain their purpose, parameters, and return values.

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

Sources: CONTRIBUTING.md:173-185

Error handling is critical. Scripts must validate inputs and use appropriate exit codes (0 for success, 1 for general error, 2 for invalid usage).

Sources: CONTRIBUTING.md:188-195

Testing Requirements

All new features must include tests. This is a non-negotiable quality standard. The test suite uses the BATS (Bash Automated Testing System) framework.

Sources: CONTRIBUTING.md:213-214, TESTING.md:4-5

Mandatory Testing Standards

Requirement	Standard	Enforcement
Test Pass Rate	100%	Mandatory - CI blocks merge on any failure.
Test Coverage	85%	Aspirational - Informational only due to kcov limitations.

The 100% test pass rate is the primary quality gate.

Sources: CONTRIBUTING.md:216-220, TESTING.md:154-159

Test Organization

Tests are organized by category into unit, integration, and e2e directories.

tests/
├── unit/                       # Fast, isolated tests
│   ├── test_cli_parsing.bats   # CLI argument tests
│   ├── test_json_parsing.bats  # JSON output parsing
│   └── ...
├── integration/                # Multi-component tests
│   ├── test_loop_execution.bats
│   └── ...
├── e2e/                        # End-to-end workflows
└── helpers/
    └── test_helper.bash        # Shared test utilities

Sources: CONTRIBUTING.md:226-238, TESTING.md:48-64

Running Tests

The following npm scripts are available to run the test suite.

Command	Purpose	When to Use
npm test	Run all tests (unit + integration)	Before committing, before creating a PR.
npm run test:unit	Run unit tests only	During development for fast feedback.
npm run test:integration	Run integration tests only	When testing interactions between components.
bats tests/unit/test_file.bats	Run a single test file	When debugging a specific set of tests.

Sources: CONTRIBUTING.md:240-246, TESTING.md:29-46

Writing Tests

Tests are written in .bats files. Each test should be isolated and have a descriptive name. The setup() function runs before each test to create an isolated environment, and teardown() runs after to clean up.

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

load '../helpers/test_helper'

# Setup runs before each test
setup() {
    source "$(dirname "$BATS_TEST_FILENAME")/../helpers/test_helper.bash"
    export TEST_TEMP_DIR="$(mktemp -d /tmp/ralph-test.XXXXXX)"
    cd "$TEST_TEMP_DIR"
    # ... initialize test state
}

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

@test "can_make_call returns success when under limit" {
    echo "50" > ".call_count"
    export MAX_CALLS_PER_HOUR=100

    run can_make_call
    assert_success
}

Sources: CONTRIBUTING.md:251-281

The test suite provides several helper functions in tests/helpers/test_helper.bash and fixture generators in tests/helpers/fixtures.bash to simplify test creation.

Available Test Helpers:

• assert_success: Checks for exit code 0.
• assert_failure: Checks for a non-zero exit code.
• assert_equal: Compares two values.
• assert_output: Checks command output.
• assert_file_exists: Verifies a file exists.
• create_mock_prompt: Creates a test PROMPT.md.
• create_sample_fix_plan: Creates a test @fix_plan.md.

Sources: CONTRIBUTING.md:289-298, TESTING.md:188-206, tests/helpers/fixtures.bash

Pull Request Process

Before Creating a PR

Ensure your contribution is ready by running through this checklist:

• All tests pass locally (npm test).
• New code is accompanied by appropriate tests.
• Commits follow the conventional format.
• Documentation is updated if needed.
• No debug code or secrets are committed.

Sources: CONTRIBUTING.md:302-309

Creating the PR

When opening a Pull Request on GitHub, the title must follow the conventional commit format. The description should use the provided template to summarize the changes, detail the test plan, and link to any related issues.

## Summary

Brief description of what this PR does (1-3 bullet points).

- Adds dry-run mode to preview loop execution
- Includes new CLI flag `--dry-run`
- Logs actions without making actual changes

## Test Plan

- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] Manual testing completed

## Related Issues

Fixes #123
Related to #456

Sources: CONTRIBUTING.md:315-344

After creating the PR, wait for the CI/CD pipeline to complete and address any feedback from code reviewers.

Quality Standards

All contributions must meet the project's quality standards, which are enforced through automated checks and manual review.

Quality Gates

The CI/CD pipeline enforces several quality gates that all PRs must pass before they can be merged.

Gate	Requirement	Enforcement
Unit Tests	100% pass	Blocks merge
Integration Tests	100% pass	Blocks merge
Conventional Commits	Required	Manual review
Documentation	Updated	Manual review

Sources: CONTRIBUTING.md:382-389

Feature Completion Checklist

A feature is considered complete only after verifying the following items:

• All tests pass (100% pass rate).
• All changes are committed with conventional commit messages.
• All commits are pushed to the remote repository.
• The CI/CD pipeline passes.
• CLAUDE.md and README.md are updated if user-facing changes were made.
• Breaking changes are documented.

Sources: CONTRIBUTING.md:401-412, templates/AGENT.md:91-106

Community Guidelines

Priority Contribution Areas

The project is actively seeking help in several high-priority areas. You can find a detailed roadmap in IMPLEMENTATION_PLAN.md.

1. Test Implementation: Expand test coverage, especially for tmux integration and E2E workflows.
2. Feature Development: Implement features like log rotation, dry-run mode, and a .ralphrc config file.
3. Documentation: Create tutorials, troubleshooting guides, and usage examples.
4. Real-World Testing: Use Ralph on your own projects and report bugs or edge cases.

Sources: CONTRIBUTING.md:418-435, IMPLEMENTATION_PLAN.md:21-48

Communication

For major changes, open an issue to discuss the proposal first. For questions, review the documentation before opening an issue. All communication should be respectful and professional.

Sources: CONTRIBUTING.md:437-448

Thank you for contributing to Ralph! Your efforts help make autonomous AI development more accessible.

Sources: CONTRIBUTING.md:459-460