version: "1.0.1" name: start description: Start autonomous iteration loop OR explain how Loop works. Triggers on "loop", "keep going", "don't stop", "continue until done", "until tests pass", "implement full feature", "fix all problems", "make better", "what is loop", "how does loop work", "loop help", or any persistence pattern. Executes multi-step tasks without stopping until complete or limits reached. model: opus allowed-tools: Bash, Read

Loop

Autonomous iteration that continues until spec is satisfied or limits reached.

Before You Start (Required Checklist)

□ Score the spec (use rubric below) □ Determine shape (Tool ≥8, Colleague 5-7, Intent <5) □ Classify reversibility (see below) □ Extract success criteria from spec (explicit list) □ Decompose into concrete steps □ Create task with state schema □ Write .loop/state.json with criteria array □ Announce: [LOOP] Starting | Shape: X | Workflow: [A/B/C] | Steps: N | Budget: $Y

If any checkbox is unclear, STOP and clarify before proceeding.

Reversibility Classification

See fit-decision.md for full delegation scoring.

SHAPE.md Integration

If .loop/shape/SHAPE.md exists (generated by /hope:shape), extract:

1. criteria: → Add to criteriaStatus initialization
2. mustNot: → Add as circuit breaker triggers
3. verification: → Map to verification types per criterion

{
  "criteriaStatus": {
    "tests pass": {"met": false, "verification": "execution output"},
    "API returns 200": {"met": false, "verification": "execution output"},
    "UI renders": {"met": false, "verification": "observation"}
  }
}

mustNot Circuit Breaker: If any mustNot condition becomes true during execution → pause immediately.

Exit Blocked: If any criterion has verification: "assumption", exit_signal cannot be true.

Spec Clarity Rubric (Inline)

Score on 5 dimensions (0-2 each, max 10):

Decision:

• ≥8: Tool-shaped — execute silently, report on completion
• 5-7: Colleague-shaped — check in after each iteration
• <5: Run /hope:intent first

Workflow Type Detection

After scoring spec, detect workflow type from content:

Update announcement to include workflow: [LOOP] Starting | Shape: X | Workflow: [A/B/C] | Steps: N

Reference hope/skills/soul for workflow details.

Confirmation Gates by Shape

Tool-Shaped (≥8)

Execute autonomously. No confirmation gates.

[LOOP] Starting | Shape: Tool (9/10) | Workflow: A | Steps: 5
... executes all steps without pausing ...
<loop-complete>

Colleague-Shaped (5-7)

Pause at three checkpoints:

[LOOP] Starting | Shape: Colleague (6/10) | Workflow: B | Steps: 4
 
G1: Decomposed into 4 steps:
1. Identify failing test
2. Add instrumentation
3. Fix root cause
4. Verify fix
Proceed? [Y/n]

Skip gates: User says "proceed without confirmation" to run uninterrupted.

Intent-Required (<5)

Block and route to /hope:intent before proceeding.

State File Schema (CRITICAL)

Transparency: Loop writes .loop/state.json to track progress.

On loop start, disclose: "Writing state to .loop/state.json. Delete after session? [Y/n]"

Cleanup: State files auto-delete on /loop cancel unless user opts to keep.

Write .loop/state.json at loop start and update after EVERY iteration:

{
  "spec": "original user request verbatim",
  "criteria": ["tests pass", "all routes refactored", "no lint errors"],
  "criteriaStatus": {
    "tests pass": false,
    "all routes refactored": false,
    "no lint errors": true
  },
  "exit_signal": false,
  "steps": ["step1", "step2", "step3"],
  "completedSteps": ["step1"],
  "remainingSteps": ["step2", "step3"],
  "iteration": 2,
  "status": "in_progress",
  "circuitBreaker": {
    "stuckCount": 0,
    "lastUnmet": "tests pass"
  }
}

The stop hook reads this file to decide whether to continue.

Dual-Condition Exit (CRITICAL)

The stop hook requires BOTH conditions to stop:

1. All `criteriaStatus` values are `true`
2. `exit_signal` is `true`

If either condition is false, the loop continues.

Why Dual-Condition?

Prevents premature stops. Claude must:

1. Actually verify each criterion (tests pass, lint clean, etc.)
2. Explicitly signal completion intent

Iteration Protocol

1. TaskGet → Retrieve current state
2. Read .loop/state.json if exists (recovery case)
3. Announce → [LOOP] Iteration N/max | Cost: $X | Step: [name]
4. Execute → Do ONE logical unit of work
5. Verify → Run verification commands for affected criteria
6. Update state → Write .loop/state.json with updated criteriaStatus
7. Check circuit breaker → Increment stuckCount if same criteria unmet
8. Output status block → ---LOOP_STATUS--- (required)
9. TaskUpdate → Save to Tasks API (backup)

Status Block (REQUIRED)

After EACH iteration, output this exact format:

---LOOP_STATUS---
EXIT_SIGNAL: false
CRITERIA: {"tests pass": false, "lint clean": true}
STUCK_COUNT: 0
NEXT: Fix failing tests
---END_STATUS---

Rules:

• EXIT_SIGNAL: true ONLY when ALL criteria verified true
• CRITERIA must match criteriaStatus in state file
• STUCK_COUNT increments when same criteria remain unmet
• NEXT describes the next action

State Update Protocol

After each iteration:

1. Run verification commands for criteria you worked on
2. Update `criteriaStatus` based on actual verification results
3. Check for stuck state:

• If same criteria unmet as last iteration, increment circuitBreaker.stuckCount
• If different criteria unmet, reset stuckCount to 0

1. Set `exit_signal`:

• true ONLY if ALL criteriaStatus values are true
• false otherwise

1. Write updated state to .loop/state.json
2. Output status block

Circuit Breakers

The stop hook checks circuitBreaker.stuckCount >= 5 and returns {ok: true} to stop.

Announcements

Before Each Iteration

[LOOP] Iteration N/max | Cost: $X/$budget | Step: [current step]

After Each Iteration

[LOOP] ✓ [step name] complete | Progress: N/total | Next: [next step]

On Completion

<loop-complete>
All success criteria satisfied:
- [criterion 1]: ✓
- [criterion 2]: ✓
- [criterion 3]: ✓
</loop-complete>

Output <loop-complete> ONLY after:

1. All criteriaStatus values are true
2. exit_signal set to true in state file

Quality Footer Required: After <loop-complete>, include a verdict box:

╭─ 🟢 SHIP ──────────────────────────╮
│ Verified: [execution output/observation/measurement] │
│ Checklist: N/N criteria verified    │
│ Subjective: ~X% · Type 2A/2B · Npt  │
├────────────────────────────────────┤
│ ↳ Alt: [alternative approach]       │
│ ↳ Risk: [key assumption]            │
╰────────────────────────────────────╯

Map loop outcomes to verdicts:

• 🟢 SHIP: All criteria verified with execution output/observation/measurement
• 🟡 MONITOR: Criteria passed but verification was code review only
• 🔴 RESEARCH: Any criterion verified by assumption only

See quality-footer.md for format details.

On Pause

[LOOP] ⏸ Paused: [reason]
Progress: N steps complete, M remaining
Resume: /loop continue

Commands

Cost Controls

Principle: Pause, don't kill. User can always continue.

Example

User: "loop - refactor all API routes to use validation middleware"

[LOOP] Starting | Shape: Colleague (7/10) | Steps: 4 | Budget: $25
 
Spec scoring:
- Outcome: 2 (clear refactor)
- Scope: 2 (API routes)
- Constraints: 1 (middleware implied)
- Success: 1 (implicit: works)
- Done: 1 (implicit: all routes)
Total: 7/10 → Colleague-shaped
 
[LOOP] Iteration 1/10 | Cost: $0.50/$25 | Step: Refactor /api/users
... work happens ...
[LOOP] ✓ /api/users complete | Progress: 1/4 | Next: /api/auth
 
---LOOP_STATUS---
EXIT_SIGNAL: false
CRITERIA: {"/api/users refactored": true, "/api/auth refactored": false, "tests pass": false}
STUCK_COUNT: 0
NEXT: Refactor /api/auth
---END_STATUS---
 
Continue? [Y/n]

On completion:

---LOOP_STATUS---
EXIT_SIGNAL: true
CRITERIA: {"/api/users refactored": true, "/api/auth refactored": true, "tests pass": true}
STUCK_COUNT: 0
NEXT: none
---END_STATUS---
 
<loop-complete>
All success criteria satisfied:
- /api/users refactored: ✓
- /api/auth refactored: ✓
- /api/products refactored: ✓
- /api/orders refactored: ✓
- All tests pass: ✓
</loop-complete>

Boundary

Loop executes, never decides.

• User controls what gets built — loop executes the spec, doesn't expand it
• User controls persistence — state files disclosed, cleanup offered
• User controls continuation — pause is always honored, "cancel" is immediate

Loop must not do work the user should learn. If same pattern repeats 3+ times, suggest: "This is a learnable pattern. Want the steps to run yourself?"

References

• references/loop-mechanics.md — Command-based stop hook, state schema, circuit breaker
• references/spec-rubric.md — Scoring examples
• references/cost-controls.md — Override syntax, continuation
• references/headless.md — CI/CD integration
• references/prd-mode.md — PRD execution mode for pre-decomposed tasks