Autonomous Loop

Autonomous Loop

Overview

The autonomous loop implements Ralph's iterative development methodology. Each iteration loads identical context (PROMPT + AGENTS files), executes one focused task, reports structured status, and persists state to disk for the next iteration. The loop continues until the dual-condition exit gate is satisfied. The core innovation is that deterministic conditions allow Claude to autonomously plan, build, and iterate toward quality without human intervention in the loop.

Announce at start: "I'm starting the autonomous loop. Loading context and beginning PLANNING mode."

Trigger Conditions

• /ralph or /loop command invoked
• Project has specs and is ready for iterative autonomous development
• Multi-task implementation that benefits from autonomous iteration
• User requests autonomous execution without per-task approval

---

Architecture

+--------------------------------------------------+
|                 AUTONOMOUS LOOP                    |
|                                                    |
|  +----------+    +----------+    +-----------+    |
|  | PLANNING |---→| BUILDING |---→|  STATUS   |    |
|  |   MODE   |    |   MODE   |    |  CHECK    |    |
|  +----------+    +----------+    +-----+-----+    |
|       ^                               |           |
|       |            +-----------+      |           |
|       +------------|  EXIT GATE|←-----+           |
|                    |  (dual)   |                   |
|                    +-----+-----+                   |
|                          |                         |
|                    PASS: EXIT                      |
|                    FAIL: LOOP                      |
+--------------------------------------------------+

---

Phase 1: PLANNING MODE (Gap Analysis)

Goal: Analyze specs against implementation to identify and prioritize remaining work.

<HARD-GATE> Planning mode produces NO implementation code. It is analysis and planning ONLY. </HARD-GATE>

Steps

1. Knowledge Gathering — Deploy up to 250 parallel subagents via the Agent tool (with subagent_type="Explore" and model="sonnet") to study specs, existing implementation plans, and utility libraries 2. Code Analysis — Deploy up to 500 parallel subagents via the Agent tool (with subagent_type="Explore") to study src/* against specs/*, identifying gaps between specification and implementation 3. Synthesis — Deploy a synthesis subagent via the Agent tool (with model="opus") to synthesize findings and prioritize incomplete work 4. Plan Refresh — Update IMPLEMENTATION_PLAN.md as organized, prioritized bullet list

Planning Mode Constraints

Planning Mode Output

IMPLEMENTATION_PLAN.md updated:
- [x] Completed tasks (checked off)
- [ ] Remaining task 1 (highest priority)
- [ ] Remaining task 2
- [ ] Remaining task 3
...
Missing specs identified: [list or "none"]

STOP — Do NOT proceed to Phase 2 until:

• [ ] All specs have been read and analyzed
• [ ] Code has been compared against specs
• [ ] IMPLEMENTATION_PLAN.md is updated with prioritized tasks
• [ ] Missing specs are identified (if any)

---

Phase 2: BUILDING MODE (Implementation)

Goal: Select and complete exactly ONE task per iteration.

"ONE Task Per Loop" Principle

Each iteration selects and completes exactly one task from IMPLEMENTATION_PLAN.md. This reduces context switching, enables clear progress measurement, and makes debugging easier.

Steps

1. Study — Read specs and current IMPLEMENTATION_PLAN.md 2. Select — Choose the most important remaining task 3. Search — Find existing code patterns (do NOT assume implementations are missing) 4. Implement — Write complete, production-quality code (no placeholders, no stubs) 5. Test — Run tests immediately after implementation 6. Update — Refresh IMPLEMENTATION_PLAN.md with findings and progress 7. Commit — Descriptive conventional commit message with rationale

Task Selection Decision Table

Subagent Rules During Building

Building Mode Constraints

STOP — Do NOT proceed to Phase 3 until:

• [ ] Task is fully implemented (no stubs)
• [ ] Tests have been run
• [ ] IMPLEMENTATION_PLAN.md is updated
• [ ] Changes are committed

---

Phase 3: STATUS CHECK

Goal: Produce a RALPH_STATUS block and evaluate exit conditions.

After each BUILD iteration, invoke the ralph-status skill to produce a structured status block.

Exit Evaluation

Loop Decision

---

Exit Conditions — Dual-Condition Gate

<HARD-GATE> Both conditions must be true simultaneously to exit the loop: </HARD-GATE>

EXIT_SIGNAL May Only Be true When ALL Of:

• IMPLEMENTATION_PLAN.md has no remaining tasks
• All tests pass
• No errors in latest iteration
• No meaningful work remains

This prevents false positives where completion language appears while productive work continues.

Exit Decision Table

---

Context Efficiency

---

Steering Mechanisms

Upstream Steering (Shaping Inputs)

Downstream Steering (Validation Gates)

---

State Persistence

The only persistent state between iterations is the file system:

IMPLEMENTATION_PLAN.md is disposable — it can be regenerated from specs at any time by running a planning iteration.

---

Anti-Patterns / Common Mistakes

---

Anti-Rationalization Guards

<HARD-GATE> Do NOT exit the loop without the dual-condition gate passing. Do NOT implement more than one task per iteration. Do NOT write placeholder or stub code. Do NOT skip the STATUS CHECK. </HARD-GATE>

If you catch yourself thinking:

• "I can do two quick tasks in this iteration..." — No. ONE task per loop.
• "The plan is probably fine, skip planning mode..." — Verify. Plans drift.
• "Tests can wait until the next iteration..." — Run tests NOW. Backpressure is essential.
• "Everything is done, I can exit..." — Check the dual-condition gate. Both must be true.

---

Subagent Dispatch Opportunities

Follow the dispatching-parallel-agents skill protocol when dispatching.

---

Integration Points

---

Concrete Examples

Example: Planning Mode Output

IMPLEMENTATION_PLAN.md:
- [x] Set up project structure
- [x] Implement core data types
- [ ] Implement user authentication (P0 — blocks 3 other tasks)
- [ ] Add API rate limiting (P1)
- [ ] Implement webhook handlers (P1)
- [ ] Add monitoring and logging (P2)

Missing specs: Rate limiting spec needs error response format defined.

Example: Building Mode Iteration

Task selected: Implement user authentication
Searched: Found existing password hashing in src/lib/crypto.ts
Implemented: src/auth/service.ts, src/auth/middleware.ts
Tests: 8 passing, 0 failing
Committed: feat(auth): implement JWT-based user authentication

Updated IMPLEMENTATION_PLAN.md:
- [x] Implement user authentication

Example: Status Block

---RALPH_STATUS---
STATUS: IN_PROGRESS
TASKS_COMPLETED_THIS_LOOP: 1
FILES_MODIFIED: 4
TESTS_STATUS: PASSING
WORK_TYPE: IMPLEMENTATION
EXIT_SIGNAL: false
RECOMMENDATION: Next: implement API rate limiting (P1)
---END_RALPH_STATUS---

---

Skill Type

RIGID — Follow this process exactly. The determinism of the loop depends on consistent execution. ONE task per loop. Status block every iteration. Dual-condition exit gate. No exceptions.