Agent Loop Quickstart

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

First time using AIWG? Begin with Install, Connect, and Verify. This guide assumes AIWG is already installed, `all` is deployed for your provider, and the agent-owned context regeneration procedure has connected the agent to this project.

Get started with iterative AI task execution in 5 minutes.

Before You Start: Is Ralph Right for This Task?

Ralph is a power tool. Before invoking it, ask yourself:

Question	If NO
Is my task well-defined with clear requirements?	Document requirements first
Can I write a command that verifies success?	Ralph can't help with subjective goals
Do I have tests/linting to validate correctness?	Add verification first
Is this implementation work, not exploration?	Use Discovery Track for research

The token-burning trap: Ralph excels at HOW to implement but thrashes on WHAT to build. If you don't have clear requirements, Ralph will hallucinate features, contradict itself, and burn tokens producing junk.

Safe to proceed? Read on. Unsure? See When to Use Ralph first.

---

What is Ralph?

Ralph (from the "iterative agent loop methodology") executes AI tasks in a loop until completion criteria are met:

1. Execute your task 2. Verify if completion criteria are met 3. Learn from failures 4. Iterate until success (or limits reached)

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

Installation

Use AIWG to complete this documented outcome: Installation
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

Your First Agent Loop

Example 1: Fix Failing Tests

/ralph "Fix all failing tests" the completion option "npm test passes"

Ralph will: 1. Run your tests to see what's failing 2. Analyze and fix the issues 3. Run tests again 4. Repeat until all tests pass (or max iterations reached)

Example 2: Fix TypeScript Errors

/ralph "Fix all TypeScript errors" the completion option "npx tsc --noEmit passes"

Example 3: Improve Test Coverage

/ralph "Add tests to reach 80% coverage" the completion option "coverage report shows >80%"

Example 4: Fix Lint Errors

/ralph "Fix all ESLint errors" the completion option "npm run lint passes"

Interactive Mode

Not sure about completion criteria? Use interactive mode:

/ralph the interactive option

Ralph will ask you:

• What task should I execute?
• How do I verify it's complete?
• Any files I should avoid?
• Other constraints?

Natural Language

You can also trigger Ralph with natural language:

• "ralph this: fix all the lint errors"
• "keep trying until the tests pass"
• "loop until coverage is above 80%"
• "ralph it" (after describing a task)

Monitoring Progress

Check Status

/ralph-status

Shows current iteration, progress, and learnings.

Check Detailed History

/ralph-status the verbose option

Shows full iteration history.

Managing Loops

Abort If Stuck

/ralph-abort

Stops the loop, keeps all changes.

Abort and Revert

/ralph-abort the revert option

Stops the loop and reverts all changes.

Resume After Interruption

/ralph-resume

Continues from the last checkpoint.

Resume with More Iterations

/ralph-resume the max-iterations option 20

Key Options

Option	Default	Description
the completion option	Required	Verification command/criteria
the max-iterations option	10	Safety limit on attempts
the timeout option	60	Maximum minutes
the interactive option	false	Ask clarifying questions
the no-commit option	false	Disable auto-commits
the branch option	none	Create feature branch

Best Practices

1. Be Specific

# Good
/ralph "Fix auth module tests" the completion option "npm test -- auth"

# Too vague
/ralph "Fix tests" the completion option "npm test passes"

2. Use Verifiable Criteria

# Good - can verify with command
the completion option "npm test passes"
the completion option "npx tsc --noEmit exits with code 0"

# Bad - subjective
the completion option "code looks good"

3. Set Reasonable Limits

• Simple fixes: 5-10 iterations
• Migrations: 15-20 iterations
• Complex tasks: 20-30 iterations

4. Let Git Track Progress

Ralph auto-commits each iteration by default, creating a clear history:

ralph: iteration 1 - initial attempt
ralph: iteration 2 - fixed auth test
ralph: iteration 3 - fixed edge case

Output Files

Ralph stores state and reports in `.aiwg/ralph/`:

.aiwg/ralph/
├── current-loop.json        # Current loop state
├── iterations/              # Individual iteration details
│   ├── iteration-1.json
│   └── iteration-2.json
└── completion-2025-01-15.md # Completion report

Next Steps

• Read When to Use Ralph to understand Ralph's sweet spot
• Read Best Practices for effective prompt engineering
• See Examples for common patterns
• Check Troubleshooting if you get stuck

Quick Reference

# Start a loop
/ralph "task" the completion option "criteria"

# Interactive start
/ralph the interactive option

# Check status
/ralph-status

# Resume interrupted loop
/ralph-resume

# Abort loop
/ralph-abort