autonomous-loop

What this skill does

# 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

| 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:**
- [ ] 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

| 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:**
- [ ] 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

| 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

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

| 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 subage