The Loop
Read prd.json ? Pick highest-priority task (passes: false) ? Implement ? Run checks ? Commit ? Update prd.json ? Repeat
Each iteration gets fresh context. No accumulated cruft. One task per loop.
prd.json Format
{
"project": "TaskApp",
"branchName": "ralph/task-status",
"userStories": [
{
"id": "US-001",
"title": "Add status field to tasks table",
"acceptanceCriteria": [
"Add status column: 'pending'|'in_progress'|'done'",
"Migration runs successfully",
"Typecheck passes"
],
"priority": 1,
"passes": false
},
{
"id": "US-002",
"title": "Display status badge on task cards",
"acceptanceCriteria": [
"Colored badge: gray=pending, blue=in_progress, green=done",
"Typecheck passes"
],
"priority": 2,
"passes": false
}
]
}Story Sizing
Each story must fit in one context window. If you can't describe the change in 2-3 sentences, split it.
| Right-sized | Too big (split these) |
|---|---|
| Add a DB column + migration | "Build the dashboard" |
| Add a UI component to existing page | "Add authentication" |
| Add a filter dropdown | "Refactor the API" |
Order by dependency: schema ? backend ? UI ? aggregation views.
Acceptance Criteria
Must be verifiable by the agent, not vague.
// Good
"Add status column with default 'pending'"
"Filter dropdown has options: All, Active, Completed"
"Typecheck passes"
// Bad
"Works correctly"
"Good UX"
"Handles edge cases"Always include "Typecheck passes" as the final criterion.
Progress Log
## Codebase Patterns ? top of progress.txt, reusable across iterations
- Use sql template for aggregations
- Always use IF NOT EXISTS for migrations
## 2026-03-15 - US-001 ? appended after each iteration
- Added status column to tasks table
- Files: db/migrations/004_status.sql, src/schema.ts
- Learning: drizzle needs explicit push after generatePatterns go at the top. Future iterations read them first.
Tradeoffs
- Pro: Fresh context every loop prevents degradation over long features
- Pro: Each commit is verified and passing before moving on
- Con: Overhead per iteration (re-reading specs, context loading)
- Con: Cross-cutting changes that touch many files are awkward to split
Ralph works with any spec source: BMAD, GSD, or your own format. All it needs is a structured task list with clear acceptance criteria.