Quick Start

Run a bounded task loop and inspect its verification result

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](../../getting-started/install-connect-verify.md). This guide assumes AIWG is connected to the target project and your provider session can read the deployed context.

Use an iterative loop for one bounded task with a measurable completion check.

Before You Start: Is Al Right for This Task?

Al 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 or evidence check that verifies success?	Define a reviewable result first
Do I have tests/linting to validate correctness?	Add verification first
Is this implementation work, not exploration?	Use Discovery Track for research

Al works best when the "what" is already clear. If requirements are still open, start with intake, discovery, or a short planning pass before launching a loop.

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

What is Al?

Al (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.

Enable If Needed

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

Skip this when the complete setup path already made the addon available in your provider session.

Your First Agent Loop

Example 1: Fix Failing Tests

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

Al 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, a configured limit is reached, or it needs your input

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

Al 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 Al 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. Decide How Git Should Track Progress

If auto-commit is enabled for your loop, each iteration creates a clear history:

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

Output Files

Al 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 Al to understand Al's sweet spot
Read Best Practices for effective prompt engineering
See Examples for common patterns
Check Troubleshooting if you get stuck

Success is a completion report in `.aiwg/ralph/`, the verification evidence named in the completion option, and a clear statement of any remaining blocker.

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