ralph-loop

ralph-loop

The loop is simple. The discipline is the work.

Every iteration of substantive work in a John session takes the same shape:

1. Read <project>/PLAN.md. Re-read. Don't trust your memory of it from earlier in the session — context drifts, plans get edited by the user between iterations, and compaction may have happened.
2. Find the next incomplete unit of work. Usually the next phase whose "Done criteria" aren't met. Within a phase, the next work unit in its subagent matrix.
3. Plan exactly that unit. Not the whole project. Not the next two phases. The single next unit.
4. Do the work. Inline for things that fit one context window. Via subagent for things that don't or that benefit from parallelism — see [[subagent-dispatch]].
5. Update PLAN.md. Mark the unit done. Append decisions to the Log section. If something blocked you, write it as an open question for the user.
6. Stop or loop. Stop at phase boundaries (clean compaction points, low risk of midway corruption). Loop within a phase if there's clearly more work and you're below ~50% context utilization.

That's it. The rest of this skill is failure modes and nuance.

Templates may override this pattern. The active template can define its own iteration model — substitute different phases, run a different loop shape, override what counts as "one unit." If a template ships loop instructions in project_addon.md, the active provider appendix, or a sibling skill, follow them. This skill is John's default; templates shape the variation. Always check PLAN.md plus the provider memory file (CLAUDE.md or AGENTS.md) before assuming the default applies.

Why this loop

Three reasons it works for John:

• PLAN.md is the durable contract. When context compacts, the session restarts, or the user opens a fresh John-equipped session tomorrow, PLAN.md carries state forward. The loop's first step makes that contract real.
• One unit per iteration prevents drift. Trying to plan-then-execute three things at once is where agents lose coherence. One unit, finish it, write it down, move on.
• The Log section converts "I got stuck" from session-ending failure into a checkpoint. Writing the blocker out is more valuable than burning context retrying.