Ralph Engineering Workflow

The Ralph engineering workflow executes tasks through a structured agent pipeline. Each task follows the same sequence: research, code, verify, review.

Task Execution Flow

For each task from TASKS.md:

1. Find task - Locate first unchecked - [ ] item
2. Research - Use researcher agent to gather context
3. Code - Use coder agent to implement + write tests
4. Verify - Use verifier agent to run all checks
5. Review - Use reviewer agent to assess quality
6. Complete - Mark [x] in TASKS.md, append to PROGRESS.md

Cleanup Phase

A dedicated Cleanup phase runs after all feature phases and before Final Verification. It contains a single triage task that reads ALL of PROGRESS.md, identifies every unaddressed item (failures, blocks, reviewer caveats, deferred work), and creates individual fix tasks in TASKS.md. Each fix task goes through the full agent sequence (researcher → coder → verifier → reviewer). One triage pass only — remaining issues are caught by Final Verification. See references/context-files.md for format and examples.

Agent Sequence

researcher → coder → verifier → reviewer

Each agent receives context from the previous. The session orchestrates the handoff.

File Locations

All Ralph files live in .ralph/:

File	Purpose
ARCHITECTURE.md	Technical approach (services, schema, APIs, components)
TASKS.md	Tasks with checkboxes at task level (- [ ] Task 1.1:), NOT on steps
VERIFICATION.md	How to verify (test commands, env setup, feature flags)
PROGRESS.md	Learnings and results from each iteration
CONFIG.md	Branch description and isolation mode (worktree vs branch)
screenshots/	Visual proof from manual testing (tracked)
logs/	Flat session logs: {timestamp}-{branch}-{task}.jsonl (gitignored)

For context file formats (loaded each iteration), see references/context-files.md.

Task Granularity

When creating TASKS.md (via /ralph:plan-deep), you'll be asked to choose task granularity:

Granularity	Description	Best For
Small	Smallest chunks of verifiable work. Each task is highly focused (e.g., "Create schema", "Add endpoints", "Write tests" as separate tasks)	Catching issues early, maintaining steady progress, clear milestones
Medium (Recommended)	Balanced task sizes. Each task covers a complete feature component (e.g., "Implement auth service with tests")	Good balance between granularity and task count
Large	Fewer, larger tasks. Each task covers significant functionality (e.g., "Implement complete authentication system")	Less overhead, fewer tasks to track

Medium granularity is recommended because:

• Each task covers a complete feature component, reducing overhead
• Good balance between progress tracking and task count
• Fewer context switches between tasks
• Still granular enough to isolate issues and resume after interruptions

See references/context-files.md for concrete examples of the same feature at different granularities.

Branch Naming

Format: ralph/yyyymmdd-hhmm-short-description

Examples:

• ralph/20260126-1430-user-auth
• ralph/20260127-0915-payment-flow

Branch creation depends on the isolation mode chosen during planning (stored in .ralph/CONFIG.md):

• Branch mode: Branch is created by /ralph:run before execution starts. Planning docs are written on the current branch and carry over when the ralph branch is created.
• Worktree mode: A worktree is created during planning via EnterWorktree. Planning docs are written directly in the worktree. /ralph:run detects the worktree and skips branch creation.

# Branch creation (used by /ralph:run in branch mode)
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git checkout $DEFAULT_BRANCH && git pull
git checkout -b ralph/$(date +%Y%m%d-%H%M)-short-description

Tracking Progress Remotely

Generate a compare URL to view all commits made during a Ralph run. Display this URL whenever showing status or confirming execution start.

REPO_URL=$(git remote get-url origin | sed 's/\.git$//' | sed 's/git@github.com:/https:\/\/github.com\//')
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
echo "${REPO_URL}/compare/${DEFAULT_BRANCH}...${CURRENT_BRANCH}"

Example: https://github.com/org/repo/compare/main...ralph/20260128-1123-feature

Task Completion Criteria

A task is complete ONLY when BOTH conditions are met:

1. Verifier reports all checks PASS
2. Reviewer assessment is APPROVED

NEEDS_WORK is NOT complete. Implement all reviewer feedback immediately and re-verify until APPROVED.

Test failures are NOT complete. Fix all failures immediately and re-verify until passing.

Only BLOCKED (fundamental architectural issues) defers to next iteration.

Session Instructions

When spawned by the Ralph orchestrator:

1. Read .ralph/TASKS.md and find first - [ ] task
2. Read .ralph/ARCHITECTURE.md for context
3. Read .ralph/VERIFICATION.md for check commands
4. Read last 50 lines of .ralph/PROGRESS.md for learnings
5. Execute agent sequence: researcher → coder → verifier → reviewer
6. If all checks pass and review APPROVED:
   • Mark task [x] in TASKS.md
   • Append iteration report to PROGRESS.md
7. If checks fail: fix NOW and re-verify until passing
8. If review returns NEEDS_WORK: implement ALL feedback NOW and re-verify until APPROVED
9. If review returns BLOCKED: keep task [ ], append details to PROGRESS.md

Commit Modes

Mode	Behavior
no-commit	Leave changes uncommitted
commit	Commit on success
commit-push	Commit and push on success (default)

Commit message format: "Ralph: Task X.Y - [task name]"

Testing Types — The Agent Does ALL of Them

There is no human in the loop. Every check in VERIFICATION.md — automated or manual — is performed by the agent. If the environment isn't ready, the agent sets it up. If a service isn't running, the agent starts it.

Type	Purpose	Agent Action
Unit tests	Test isolated functions	Run test commands
Integration tests	Test components together	Start services (Docker, DB) if needed, then run tests
E2E tests (automated)	Scripted regression tests	Start the app, run E2E suite
Manual testing (FE)	Visual/UX verification	Open browser with Playwright (installed locally), navigate, interact, screenshot
Manual testing (BE)	API endpoint verification	Curl endpoints, verify responses, test error cases
Linting	Code style/errors	Run linter
Type checking	Static type verification	Run type checker
Feature flags	Gate feature availability	Enable flags locally, mock if needed

For detailed guidance on each testing type, see references/testing-types.md. For Playwright installation and usage, see references/playwright.md.

E2E tests ≠ Manual testing. E2E tests prove code runs; manual testing proves it looks/works right. When E2E is required, manual browser testing with screenshots is also required.

Screenshots

During manual testing with Playwright, capture screenshots as visual proof:

Location: .ralph/screenshots/ (tracked in git)

Naming: iteration-{NNN}-{description}.png

When to capture: Key states, before/after actions, error states, final success.

Environment Validation

Before starting Ralph execution, validate AND fix the environment so all verification steps can run:

1. Parse VERIFICATION.md for test commands
2. For each test suite, run ONE existing test to verify runner works. If it doesn't, install dependencies / fix config until it does.
3. For URLs/endpoints listed, verify they're reachable. If they're not, start the services yourself.
4. If manual verification requires browser, check Playwright is installed. If not, install it (see references/playwright.md).
5. If feature flags mentioned, verify required flags are enabled locally. If not, enable or mock them.
6. Report what works, what was fixed, and what's still broken

The goal is a working environment, not just a report. Fix problems, don't just list them.

Use the ralph-validator agent to perform this check.