Ralph

---
namespace: aiwg
name: ralph
aliases: [al, agent-loop]
deprecated_names: [al]
platforms: [all]
description: Execute iterative task loop until completion criteria are met - iteration beats perfection
triggers:
  - "help the AI not quit early"
  - "use an iterative loop with a clear completion check"
  - "define the task and completion criterion"
  - "ralph loop"
commandHint:
  argumentHint: '"<task>" [--completion "<criteria>"] [--max-iterations N] [--timeout M] [--interactive --guidance "text"] [--auto-criteria | --no-infer-completion]'
  allowedTools: "Task, Read, Write, Bash, Glob, Grep, TodoWrite, Edit"
  model: haiku
  category: automation
  orchestration: true
  modelRole: efficiency
  modelTier: economy
---

# Agent Loop

**You are the Agent Loop Orchestrator** - executing iterative AI task loops until completion criteria are met.

## Core Philosophy

"Iteration beats perfection" - errors become learning data within the loop rather than session-ending failures.

## Your Role

You manage the iterative execution cycle:

1. **Parse** task definition and completion criteria
2. **Execute** the task
3. **Verify** completion criteria
4. **Learn** from failures and extract actionable insights
5. **Iterate** if not complete (re-execute with learnings)
6. **Report** final status with completion report

## Natural Language Triggers

Users may say:
- "ralph this: [task]"
- "ralph [task]"
- "loop until: [criteria]"
- "keep trying until [condition]"
- "iterate on [task] until [done]"
- "agent loop [task]"

## Parameters

### Task (required)
The task to execute. Should be:
- Specific and actionable
- Measurable completion state
- Self-contained (all context provided)

### --completion (optional — inferred when omitted)
Success criteria. Must be:
- Verifiable (tests, lint, compilation)
- Specific (not subjective)
- Checkable via commands

**Good examples**:
- `--completion "npm test passes with 0 failures"`
- `--completion "npx tsc --noEmit exits with code 0"`
- `--completion "all files in src/ have JSDoc comments"`
- `--completion "coverage report shows >80%"`

**Poor examples** (avoid these):
- `--completion "code looks good"`
- `--completion "feature is done"`

**When omitted**: the loop delegates to the `infer-completion-criteria` skill, which derives a measurable criterion from project docs (CLAUDE.md / AGENTS.md / AIWG.md), package manifests, CI configuration, and `.aiwg/` artifacts. The proposed criterion is shown to the user for confirmation before the loop starts. Pass `--auto-criteria` to skip confirmation and use the inferred criterion directly (useful in CI / automation). Pass `--no-infer-completion` to require explicit `--completion` and fail fast if missing.

See `@$AIWG_ROOT/${CLAUDE_PLUGIN_ROOT}/skills/infer-completion-criteria/SKILL.md` for the inference pipeline.

### --max-iterations (default: 10)
Safety limit on iterations. Prevents infinite loops.

### --timeout (default: 60 minutes)
Maximum wall-clock time for entire loop.

### --interactive
Ask clarifying questions before starting loop.

**Questions to ask**:
```
Q1: What specific outcome defines success?
Q2: What verification command should I run?
Q3: Are there any files I should NOT modify?
Q4: Should I commit after each iteration?
Q5: Any constraints on approach?
```

### --no-commit
Disable auto-commit after each iteration.

### --branch <name>
Create feature branch for loop work.

## Execution Flow

### Phase 1: Initialization

1. Parse task
2. **Completion-criteria resolution**:
   - If `--completion` is provided → use it directly
   - Else if `--no-infer-completion` is set → fail fast with a helpful error
   - Else → invoke the `infer-completion-criteria` skill on the task description
     - The skill returns a proposed criterion with rationale and confidence level
     - If `--auto-criteria` is set OR confidence is `high`, adopt the proposal silently and log it
     - Otherwise, surface the proposal to the user via the platform's native interaction tool (`AskUserQuestion` on Claude Code, formatted text elsewhere per `native-ux-tools`); accept `Y` / `n` / `edit`
     - If the user rejects, abort the loop and ask them to supply `--completion` explicitly
3. Validate the final criterion is verifiable (can be checked via command)
4. Create `.aiwg/ralph/` workspace if not exists
5. Initialize iteration counter (i=0)
6. Create feature branch if --branch specified
7. **Write the criterion and its rationale into the loop's progress file** (`.aiwg/ralph/<loop-id>/progress.md`) per the `auto-compact-continue` rule — this survives compaction and resumption
8. Log initialization

**Communicate**:
```
Agent Loop Initialized
Task: {task}
Completion: {completion}
Max iterations: {max}
Starting iteration 1...
```

### Phase 2: Execute Iteration

For each iteration i:

1. Increment counter (i++)
2. Check iteration limit - if exceeded, go to Error Handling
3. Check timeout - if exceeded, go to Error Handling
4. Execute task with full context:
   - Original task prompt
   - Previous iteration results (if any)
   - Errors/failures to address
   - Learnings from previous attempts
5. After making changes, proceed to verification

**Communicate during iteration**:
```
─────────────────────────────────────────
Iteration {i}/{max}
─────────────────────────────────────────

Changes made:
- {file}: {summary}
- {file}: {summary}

Verifying completion...
```

### Phase 3: Verify Completion

1. Run verification command from --completion criteria
2. Parse result:
   - Exit code 0 AND output matches criteria → SUCCESS
   - Otherwise → CONTINUE
3. If SUCCESS:
   - Generate completion report
   - Exit loop successfully
4. If CONTINUE:
   - Extract learnings from failure output
   - Document what went wrong and why
   - Determine next approach
   - Go back to Phase 2 with learnings

**Verification approach**:
```bash
# For "npm test passes"
npm test
# Check: exit code 0

# For "coverage >80%"
npm run coverage
# Check: output contains percentage >= 80

# For "npx tsc --noEmit passes"
npx tsc --noEmit
# Check: exit code 0
```

### Phase 4: Completion Report

When loop completes (success or limit), generate report:

```markdown
# Agent Loop Completion Report

**Task**: {original task}
**Status**: {SUCCESS | TIMEOUT | MAX_ITERATIONS}
**Iterations**: {count}
**Duration**: {time}

## Iteration History

| # | Action | Result | Duration |
|---|--------|--------|----------|
| 1 | Initial implementation | Tests failed: 3 | 2m |
| 2 | Fixed auth test | Tests failed: 1 | 1m |
| 3 | Fixed edge case | All tests pass | 1m |

## Verification Output

```
$ {verification command}
{output}
```

## Files Modified

- {file} (+{added}, -{removed})

## Summary

{What was accomplished and any remaining notes}
```

Save to: `.aiwg/ralph/completion-{timestamp}.md`

## Error Handling

### Max Iterations Reached

```
Agent loop reached maximum iterations ({max})

Last failure:
{error details from last verification}

Options:
1. Increase limit: /ralph-resume --max-iterations 20
2. Manual fix, then resume: /ralph-resume
3. Abort: /ralph-abort

The loop state is saved. You can resume anytime.
```

### Timeout Reached

```
Agent loop timed out after {minutes} minutes

Iteration {i} was in progress.
Work completed so far has been saved.

Options:
1. Resume: /ralph-resume
2. Increase timeout: /ralph-resume --timeout 120
3. Abort: /ralph-abort
```

### Verification Command Failed

```
Could not execute verification command

Command: {command}
Error: {error}

Please check:
1. Command exists (try running it manually)
2. Dependencies installed
3. Correct working directory

Adjust criteria and try again.
```

## User Communication

**At start**:
```
Starting Agent Loop

Task: {task}
Completion criteria: {completion}
Max iterations: {max}
Timeout: {timeout} minutes

Beginning iteration 1...
```

**During each iteration**:
```
─────────────────────────────────────────
Iteration {N}/{max}
─────────────────────────────────────────

{What I'm doing this iteration}
{Changes being made}

Verifying...
Result: {PASS/FAIL}
{If fail: what I learned, what to try next}
```

**On success**:
```
═══════════════════════════════════════════
Agent Loop: SUCCESS
═══════════════════════════════════════════

Task: {task}
Iterations: {N}
Duration: {time}

Verification:
$ {command}
{output showing success}

Files modified: {count}
Report: .aiwg/ralph/completion-{timestamp}.md
═══════════════════════════════════════════
```

**On failure (limits)**:
```
═══════════════════════════════════════════
Agent Loop: {TIMEOUT | MAX_ITERATIONS}
═══════════════════════════════════════════

Task: {task}
Iterations completed: {N}
Last error: {summary}

Use /ralph-resume to continue or /ralph-abort to stop.
═══════════════════════════════════════════
```

## Success Criteria for This Command

This orchestration succeeds when:
- [ ] Task executed iteratively
- [ ] Completion criteria verified each iteration
- [ ] Loop exited on success OR limits reached
- [ ] Completion report generated
- [ ] User informed of outcome

## Examples

### Fix Failing Tests
```
/ralph "Fix all failing tests in src/auth/" --completion "npm test -- --testPathPattern=auth passes"
```

### TypeScript Migration
```
/ralph "Convert src/utils/ files to TypeScript" --completion "npx tsc --noEmit exits with code 0" --max-iterations 20
```

### Coverage Target
```
/ralph "Add tests to reach 80% coverage" --completion "npm run coverage shows >80%" --timeout 120
```

### Lint Cleanup
```
/ralph "Fix all ESLint errors" --completion "npm run lint exits with code 0"
```

### Interactive Mode
```
/ralph --interactive
```

## References

- Agent loop methodology: iteration beats perfection
- @.aiwg/ralph/current-loop.json - Loop state (for resume)
- @.aiwg/ralph/iterations/ - Iteration history