Skip to main content
skill CX Codex

iterative-loop — Claude Code skill: what it does, how to install

iterative-loop runs continuous build-test-fix loops until pass criteria are met. Useful for test-driven feature development, bug fixing, and metric optimization.

MIT 118 installs ★ 533 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill iterative-loop -a claude-code
Open on GitHub

What iterative-loop does

The skill establishes an autonomous development loop. The agent tracks previous attempts through files and git history, applies targeted code updates, runs verification suites, and repeats the routine until success metrics trigger. Built-in guardrails stop the loop after 20 tries or initiate stuck detection when 5 consecutive attempts yield zero progress.

Every run requires git tracking alongside binary pass/fail verification commands, such as exit code 0 from npm test or a strict linter check. Without clear quantitative criteria, the agent cannot evaluate its output and risks exhausting execution limits. The pattern can also link with ruflo hooks to store task memory across passes.

What it helps with

  • automate TDD cycles until test suites pass cleanly
  • increase test coverage to a targeted percentage
  • resolve regressions using a reproducible failure test
  • optimize endpoint latency against benchmark limits

Example prompts for the agent

  • Run a TDD loop for the auth module: write tests, implement logic, and verify with npm test until green, max 15 iterations.
  • Fix the token verification bug: write a failing test, patch the code, and return <promise>BUG_FIXED</promise>.

How to install iterative-loop

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill iterative-loop -a claude-code

2Manually: put the files in place

~/.claude/skills/iterative-loop/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/iterative-loop/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about iterative-loop

How to install iterative-loop in Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill iterative-loop -a claude-code. This installs the definition to ~/.claude/skills/iterative-loop/SKILL.md.

What does the iterative-loop skill do?

It guides the agent through self-correcting development loops, repeating build, test, and repair steps until specific validations pass.

What prerequisites are needed before running the loop?

You need git version control enabled and measurable verification checks with exit codes, such as automated tests, type checks, or linters.

Source text

SKILL.md · MIT
---
name: "iterative-loop"
description: "Runs continuous AI iteration loops that repeat build-test-fix cycles until success criteria are met. Use when building features requiring test-driven refinement, implementing tasks with clear pass/fail criteria, or automating iterative improvement workflows."
---

# Iterative Loop

## Overview

The Iterative Loop skill implements **continuous AI-driven development loops** that persist until completion criteria are met. Inspired by the Ralph Wiggum technique, this approach enables autonomous, self-correcting development cycles where the AI sees its previous work in files and git history, iteratively improving until success.

## Core Philosophy

1. **Iteration > Perfection** - Don't aim for perfect on first try; let the loop refine the work
2. **Failures Are Data** - Each failure provides information to improve the next attempt
3. **Clear Criteria** - Success must be objectively measurable (tests, metrics, validations)
4. **Persistence Wins** - Keep trying until success; the loop handles retry logic automatically

## Prerequisites

- Claude Code with session management
- Clear completion criteria (tests, linting, metrics)
- Version control (git) for tracking iterations

---

## Quick Start

### Basic Iterative Development Pattern

```bash
# Define task with clear completion criteria
TASK="Implement user authentication with JWT.
Success criteria:
- All unit tests pass
- Integration tests pass
- No TypeScript errors
- Security audit passes
Output <promise>COMPLETE</promise> when all criteria met."

# Execute iterative loop (conceptual)
while ! task_complete; do
  claude_execute "$TASK"
  check_completion_criteria
done
```

### AQE v3 Integration Example

```bash
# Using claude-flow hooks for iterative task
npx --no-install ruflo hooks pre-task --description "Implement auth with iteration" --taskId "auth-impl"

# Store iteration state in memory
npx --no-install ruflo memory store \
  --key "iteration-auth" \
  --value '{"iteration": 1, "maxIterations": 20, "criteria": "all tests pass"}' \
  --namespace iterations
```

---

## Step-by-Step Guide

### Step 1: Define Clear Success Criteria

**Essential**: Every iterative task MUST have objectively measurable completion criteria.

**Good Criteria Examples:**
```markdown
✅ All unit tests pass (npm test returns exit code 0)
✅ Coverage > 80% (coverage report shows 80%+)
✅ No TypeScript errors (tsc --noEmit returns 0)
✅ Linting passes (eslint returns 0)
✅ Performance < 100ms (benchmark shows < 100ms)
```

**Bad Criteria Examples:**
```markdown
❌ "Code looks good" (subjective)
❌ "Works properly" (undefined)
❌ "Well-structured" (no measurable check)
```

### Step 2: Structure the Task with Phases

Break complex tasks into incremental phases:

```markdown
## Task: Implement User Authentication

### Phase 1: Data Layer
- Create User model with Prisma schema
- Write migration
- Run tests: `npm test -- --grep "User model"`
- Criteria: Model tests pass

### Phase 2: Service Layer
- Implement AuthService with JWT
- Add token generation/validation
- Run tests: `npm test -- --grep "AuthService"`
- Criteria: Service tests pass

### Phase 3: API Layer
- Create /auth/login endpoint
- Create /auth/register endpoint
- Run tests: `npm test -- --grep "auth API"`
- Criteria: API tests pass

### Phase 4: Integration
- End-to-end authentication flow
- Run tests: `npm test`
- Criteria: ALL tests pass

Output <promise>AUTH_COMPLETE</promise> when Phase 4 passes.
```

### Step 3: Implement Safety Mechanisms

Always include escape conditions:

```markdown
## Safety Rules

1. **Max Iterations**: Stop after 20 attempts
2. **Stuck Detection**: After 5 iterations without progress:
   - Document what's blocking
   - List attempted approaches
   - Suggest alternative strategies
3. **Critical Errors**: Stop immediately if:
   - Database corruption detected
   - Security vulnerability introduced
   - Breaking changes to existing features
```

### Step 4: Execute with Verification

Each iteration should:
1. Make targeted changes
2. Run verification (tests, lint, build)
3. Analyze results
4. Plan next iteration based on feedback

```bash
# Iteration pattern
1. Read previous state (files, git log)
2. Identify remaining work
3. Implement specific change
4. Run verification suite
5. If all pass -> output completion promise
6. If failures -> analyze and continue iteration
```

---

## Iterative Patterns

### Pattern 1: Test-Driven Iteration

```markdown
## TDD Iteration Task

1. Write failing test for [feature]
2. Implement minimal code to pass test
3. Run `npm test`
4. If test fails -> debug and fix implementation
5. If test passes -> check if more tests needed
6. Repeat until all acceptance tests pass
7. Refactor if needed
8. Output <promise>TDD_COMPLETE</promise>
```

### Pattern 2: Bug Fix Iteration

```markdown
## Bug Fix Task

1. Write failing test that reproduces bug
2. Implement fix
3. Run test suite
4. If reproduction test fails -> analyze why fix didn't work
5. If other tests fail -> fix regressions
6. If all tests pass -> output <promise>BUG_FIXED</promise>

Max iterations: 10
After 5 iterations without fix:
- Document root cause analysis
- Suggest alternative approaches
```

### Pattern 3: Coverage Improvement Iteration

```markdown
## Coverage Improvement Task

Target: 80% line coverage

1. Run coverage analysis
2. Identify uncovered code paths
3. Write test for highest-impact uncovered path
4. Run tests with coverage
5. If coverage >= 80% -> output <promise>COVERAGE_ACHIEVED</promise>
6. If coverage < 80% -> continue iteration

Max iterations: 30
Progress check: If coverage doesn't improve for 3 iterations -> analyze blockers
```

### Pattern 4: Performance Optimization Iteration

```markdown
## Performance Optimization Task

Target: Response time < 100ms

1. Run performance benchmark
2. Identify slowest operation
3. Implement optimization
4. Run benchmark again
5. If target met -> output <promise>PERF_TARGET_MET</promise>
6. If not improved -> try different approach

Max iterations: 15
Record metrics each iteration for trend analysis
```

---

## Integration with Claude Flow

### Memory-Enhanced Iteration

```bash
# Store iteration state
npx --no-install ruflo memory store \
  --key "current-iteration" \
  --value '{"task": "auth", "iteration": 5, "lastResult": "2 tests failing"}' \
  --namespace iterations

# Search for similar past iterations
npx --no-install ruflo memory search \
  --query "auth implementation" \
  --namespace iterations

# Learn from successful completions
npx --no-install ruflo hooks post-task \
  --taskId "auth-impl" \
  --success true \
  --quality 0.9
```

### Swarm-Coordinated Iteration

For complex tasks, use multiple agents iterating in parallel:

```bash
# Initialize swarm for parallel iteration
npx --no-install ruflo swarm init --topology mesh --max-agents 5

# Spawn specialized iterators
Task("Iterate on unit tests", "Fix failing unit tests until all pass", "tester")
Task("Iterate on integration", "Fix integration tests until all pass", "tester")
Task("Iterate on performance", "Optimize until benchmarks pass", "performance-engineer")
```

---

## Best Practices

### Prompt Engineering for Iteration

**Include:**
- Explicit completion criteria with verification commands
- Phase-based breakdown for complex tasks
- Safety limits (max iterations)
- Progress tracking instructions
- Stuck detection and recovery procedures

**Example Well-Structured Prompt:**
```markdown
## Task: Implement Feature X

### Success Criteria (ALL must pass):
1. `npm test` exits with code 0
2. `npm run lint` exits with code 0
3. `npm run typecheck` exits with code 0
4. No console.log statements in production code

### Phases:
1. Write failing tests
2. Implement feature
3. Fix any failures
4. Clean up and refactor

### Safety:
- Max iterations: 20
- After 10 iterations: summarize blockers
- Stop if security issues detected

### Completion:
When ALL success criteria pass, output:
<promise>FEATURE_X_COMPLETE</promise>
```

### When to Use Iterative Loops

**Ideal for:**
- Well-defined tasks with measurable success
- Test-driven development
- Bug fixing with reproducible tests
- Coverage improvement
- Performance optimization
- Linting/formatting fixes

**Not ideal for:**
- Tasks requiring human judgment
- Design decisions
- Vague or subjective goals
- One-time operations
- Production debugging without tests

---

## Troubleshooting

### Issue: Infinite Loop / No Progress

**Symptoms**: Same errors repeat without improvement

**Solutions**:
1. Increase specificity in completion criteria
2. Add "stuck detection" with alternative approaches
3. Lower max iterations
4. Break task into smaller phases

### Issue: False Completion

**Symptoms**: Loop ends but task not actually complete

**Solutions**:
1. Add more verification commands
2. Make completion criteria more explicit
3. Add integration tests alongside unit tests

### Issue: Regression in Later Iterations

**Symptoms**: Previously passing tests fail after new changes

**Solutions**:
1. Add regression check step
2. Use git to compare iterations
3. Implement smaller, targeted changes

---

## Related Skills

- [tdd-london-chicago](../tdd-london-chicago/) - TDD approaches for iterative development
- [qe-iterative-loop](../qe-iterative-loop/) - AQE v3 fleet-specific iteration patterns
- [hooks-automation](../hooks-automation/) - Claude Flow hooks for automation

## Resources

- [Ralph Wiggum Technique](https://ghuntley.com/ralph/) - Original methodology
- [Ralph Orchestrator](https://github.com/mikeyobrien/ralph-orchestrator) - Orchestration tools
- [Claude Code Plugins](https://github.com/anthropics/claude-code) - Official plugins

---

**Origin**: Based on Ralph Wiggum plugin from claude-code repository (anthropics/claude-code)
**Adapted for**: Agentic QE v3 with Claude Flow integration

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
qe-learning-optimization qe-learning-optimization optimizes QE agents through transfer learning across test frameworks, Bayesian hyperparameter tuning, and A/B experiments. CX Codex +1 121installs qe-security-compliance qe-security-compliance runs code security audits, dependency vulnerability scans, secret detection, and compliance checks for OWASP and SOC2. CX Codex +1 120installs testability-scoring testability-scoring scores web application testability against 10 principles and produces a report. Use it to check test readiness and find areas that make testing harder. CX Codex +1 119installs test-data-management The test-data-management skill creates test datasets, anonymizes PII, and keeps test records isolated. Use it for unit, integration, performance, and boundary testing. CX Codex +1 118installs shift-left-testing The shift-left-testing skill moves checks earlier in development: validate requirements, write tests before implementation, and run them in CI. Use it when introducing TDD or other early quality practices. CX Codex +1 117installs test-environment-management test-environment-management is a Claude Code skill for setting up test infrastructure and matching it to production. It covers environment setup, parity checks, and test infrastructure costs. CX Codex +1 117installs debug-loop debug-loop — a skill for step-by-step debugging of errors through real commands, not simulations. Forms hypotheses, validates them against live data, identifies root cause, and only then fixes the code. CX Codex +1 117installs shift-right-testing shift-right-testing guides agents through production testing using feature flags, canary rollouts, and chaos experiments. Useful when setting up progressive delivery or tracking SLOs. CX Codex +1 115installs

Project sponsors

Companies that keep this analytics open