| name | autonomous-loop |
| description | Use when running Ralph-style iterative autonomous development. Triggers on /ralph or /loop commands, when autonomous iterative development is needed, when a project has specs and an implementation plan ready for iterative execution, or when deterministic context loading with subagent delegation and dual-condition exit gates is required. Orchestrates PLANNING, BUILDING, and STATUS cycles. |
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.
Planning mode produces NO implementation code. It is analysis and planning ONLY.
Steps
- 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
- 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
- Synthesis — Deploy a synthesis subagent via the
Agent tool (with model="opus") to synthesize findings and prioritize incomplete work
- Plan Refresh — Update
IMPLEMENTATION_PLAN.md as organized, prioritized bullet list
Planning Mode Constraints
| Constraint | Rationale |
|---|
| Verify ALL assumptions through code search | Never assume something is absent |
Treat src/lib as authoritative standard library | Consolidate, do not duplicate |
| Output is a prioritized task list | Not code, not designs — tasks only |
| Identify missing specs | Specs gaps are blockers, not things to guess about |
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:
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
- Study — Read specs and current IMPLEMENTATION_PLAN.md
- Select — Choose the most important remaining task
- Search — Find existing code patterns (do NOT assume implementations are missing)
- Implement — Write complete, production-quality code (no placeholders, no stubs)
- Test — Run tests immediately after implementation
- Update — Refresh IMPLEMENTATION_PLAN.md with findings and progress
- Commit — Descriptive conventional commit message with rationale
Task Selection Decision Table
| Condition | Which Task to Select |
|---|
| Blocker exists for other tasks | Select the blocker task |
| Test failures exist | Select task that fixes the failure |
| All tasks independent | Select highest priority task |
| Multiple tasks at same priority | Select the one with clearest spec |
| Spec is missing for top task | Run PLANNING mode to identify gap |
Subagent Rules During Building
| Resource | Budget | Rationale |
|---|
| Read/search subagents | Up to 500 parallel Sonnet | Fast context gathering |
| Build subagent | Only 1 Sonnet at a time | Serialize builds to detect failures |
| Main context | 40-60% utilization | The "smart zone" — enough room to think |
Building Mode Constraints
| Constraint | Rationale |
|---|
| No placeholders or stubs | Every line of code is production-quality |
| Search before implementing | Code may already exist elsewhere |
| Run tests immediately | Backpressure catches errors early |
| Update plan after every task | Keep plan current with reality |
| Commit after every task | Small atomic commits, easy to revert |
STOP — Do NOT proceed to Phase 3 until:
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
| Check | Condition | Result |
|---|
| Tasks remaining? | IMPLEMENTATION_PLAN.md has unchecked items | Continue loop |
| Tests passing? | Full test suite passes | Required for exit |
| Errors in iteration? | Clean execution, no unresolved exceptions | Required for exit |
| Meaningful work remains? | No TODOs, no incomplete features | Required for exit |
Loop Decision
| Status | Tasks Remaining | Tests | Action |
|---|
| IN_PROGRESS | Yes | Any | Loop back to Phase 1 or 2 |
| IN_PROGRESS | No | FAILING | Loop — fix failures first |
| BLOCKED | Any | Any | Report blocker, wait for input |
| COMPLETE | No | PASSING | Evaluate exit gate |
Exit Conditions — Dual-Condition Gate
Both conditions must be true simultaneously to exit the loop:
| Condition | Threshold | Verification |
|---|
| Completion indicators | >= 2 recent occurrences of "done" language | Heuristic detection in output |
| Explicit EXIT_SIGNAL | EXIT_SIGNAL: true in status block | Intentional declaration |
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
| Completion Language | EXIT_SIGNAL | Action |
|---|
| < 2 occurrences | false | Continue loop |
| >= 2 occurrences | false | Continue — may be casual language |
| < 2 occurrences | true | Continue — signal without evidence |
| >= 2 occurrences | true | EXIT the loop |
Context Efficiency
| Resource | Budget | Strategy |
|---|
| Main context | 40-60% of window | Keep focused; delegate heavy lifting |
| Read subagents | Up to 500 parallel | Searching, file reading, pattern matching |
| Build subagents | 1 at a time | Implementation, test execution |
| Token format | Markdown over JSON | ~30% more efficient |
Steering Mechanisms
Upstream Steering (Shaping Inputs)
| Mechanism | Purpose |
|---|
| First ~5,000 tokens for detailed specs | Front-load specification context |
| Identical files each iteration | Deterministic context loading |
| Existing code patterns as guides | Generate consistent code |
Downstream Steering (Validation Gates)
| Gate | What It Catches |
|---|
| Tests | Invalid implementations |
| Builds | Compilation errors |
| Linters | Style inconsistencies |
| Typecheckers | Contract violations |
| LLM-as-judge | Subjective quality issues |
State Persistence
The only persistent state between iterations is the file system:
| File | Purpose | Managed By |
|---|
IMPLEMENTATION_PLAN.md | Task list and progress | Planning and Building modes |
specs/*.md | Specification files | spec-writing skill |
AGENTS.md | Operational notes and learnings | Building mode |
| Source code + tests | The actual implementation | Building mode |
IMPLEMENTATION_PLAN.md is disposable — it can be regenerated from specs at any time by running a planning iteration.
Anti-Patterns / Common Mistakes
| Anti-Pattern | Why It Fails | Correct Approach |
|---|
| Multiple tasks per iteration | Context switching, unclear progress | ONE task per loop |
| Assuming code is missing | May exist elsewhere, leads to duplication | Always search first |
| Skipping tests after implementation | Bugs accumulate, no backpressure | Run tests IMMEDIATELY |
| Modifying plan only during planning | Plan drifts from reality | Update during BOTH planning and building |
| Keeping stale plans | Tasks based on outdated assumptions | Regenerate liberally — planning is cheap |
| Manual context management | Main context overflows | Trust subagent delegation |
| Exiting without dual-condition | Premature exit, work incomplete | Both conditions must be true |
| Not committing after each task | Large changesets, hard to revert | Commit every iteration |
| Placeholder or stub code | Incomplete implementations accumulate | Production-quality code only |
| Skipping STATUS CHECK | No exit evaluation, loop runs forever | Every iteration ends with status |
Anti-Rationalization Guards
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.
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
| Task Pattern | Dispatch To | When |
|---|
| Independent file reads across codebase | Agent tool with subagent_type="Explore" | When loop iteration needs context from multiple areas |
| Test execution during build phase | Bash tool with run_in_background=true | When tests can validate work without blocking progress |
| Code review between iterations | Agent tool dispatching code-reviewer agent | After completing a build iteration, before next planning |
Follow the dispatching-parallel-agents skill protocol when dispatching.
Integration Points
| Skill | Relationship | When |
|---|
ralph-status | Per-iteration — produces status blocks | Phase 3: STATUS CHECK |
circuit-breaker | Safety net — monitors loop health | Halts on stagnation |
spec-writing | Upstream — creates specs consumed by planning | Before loop starts |
acceptance-testing | Validation — validates behavioral outcomes | During building mode |
resilient-execution | Per-task — retry on failure | When task implementation fails |
task-management | Tracking — tracks individual tasks | Within iterations |
llm-as-judge | Quality — evaluates subjective criteria | Downstream steering |
verification-before-completion | Final gate — verifies completion claim | Before EXIT_SIGNAL: true |
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.
