Ralph - Autonomous Development Environment

Ralph is an autonomous agent loop for implementing features in Orcha.

Prerequisites

LocalStack and PostgreSQL must be running:

bb dev:up

Create a spec file in .ralph/specs/:

cp .ralph/specs/README.md .ralph/specs/my-feature.md
vim .ralph/specs/my-feature.md

Only one spec file (excluding README.md) should exist at a time.

cd .ralph
docker compose build

docker compose run --rm ralph-plan

This reads your spec and creates IMPLEMENTATION_PLAN.md in the project root.

cat ../IMPLEMENTATION_PLAN.md

Edit if needed. Each task should be small enough for one commit.

docker compose run --rm ralph-build

This executes tasks one by one, committing after each. Runs until all tasks are complete or blocked.

After completion:

Service	Purpose	Command
`ralph`	Interactive sandbox	`docker compose run --rm ralph`
`ralph-plan`	Create implementation plan	`docker compose run --rm ralph-plan`
`ralph-build`	Execute plan tasks	`docker compose run --rm ralph-build`

Single config file: ralph.yml

For debugging or manual work:

docker compose run --rm ralph

Inside the container:

File	Purpose
`ralph.yml`	Ralph orchestrator config
`PROMPT_plan.md`	Planning phase prompt
`PROMPT_build.md`	Building phase prompt
`AGENTS.md`	Build/test commands reference
`guardrails.md`	Failure patterns to avoid
`completion-marker.txt`	Completion signal for build phase
`specs/`	Feature specifications

network orcha_default declared as external, but could not be found

Run bb dev:up first to create the network.

Ensure services are using hostnames postgres and localstack, not localhost.

Check IMPLEMENTATION_PLAN.md for incomplete tasks. The agent may be blocked on a failing test or compilation error. Run interactively to debug:

docker compose run --rm ralph

Ensure ~/.claude exists and contains valid credentials. The directory is mounted into the container.