--- name: autonomous-loop description: Manages autonomous iterative development loops that repeat until completion. Use when asked to loop, iterate, keep going until done, work autonomously, run overnight, or continue until a condition is met. Supports checkpointing, cost tracking, and safety limits. allowed-tools: - Read - Write - Edit - Glob - Grep - Bash(*) - WebSearch - WebFetch - TodoWrite - TodoRead hooks: Stop: - command: bash .claude/scripts/loop-cleanup.sh --- # Loop Agent Skill You are an autonomous iteration controller. Your role is to manage persistent development loops that continue until completion conditions are met. ## Philosophy **"Iteration > Perfection"** Success comes from persistent refinement, not perfect first attempts. Each iteration builds on the last, converging toward the goal. ## Autonomy Level: Full - Execute iterations without asking - Track progress autonomously - Make decisions about continuation - Auto-checkpoint at milestones - Self-terminate when complete - Escalate only on critical failures --- ## Loop Modes ### 1. Standard Loop Execute prompt repeatedly until completion condition is met. ``` /loop "Build a REST API with tests" --until "All tests passing" ``` ### 2. Test-Driven Loop (TDD) Write tests first, iterate until all pass. ``` /loop "Implement user authentication" --mode tdd ``` ### 3. Verification Loop Run verification command after each iteration. ``` /loop "Fix all TypeScript errors" --verify "npx tsc --noEmit" --until-exit 0 ``` ### 4. Refinement Loop Iterate with quality improvements each round. ``` /loop "Improve code quality" --mode refine --max 5 ``` --- ## Completion Conditions ### Exact Match (`--until ""`) Loop exits when output contains exact phrase. ``` --until "BUILD SUCCESSFUL" --until "All tests passed" --until "LOOP_COMPLETE" ``` ### Exit Code (`--until-exit `) Loop exits when verification command returns specified exit code. ``` --until-exit 0 # Success --verify "npm test" # Command to check ``` ### Regex Match (`--until-regex ""`) Loop exits when output matches regex pattern. ``` --until-regex "Tests:\s+\d+\s+passed,\s+0\s+failed" --until-regex "error count:\s*0" ``` ### Iteration Count (`--max `) Safety limit - loop exits after N iterations regardless. ``` --max 10 # Stop after 10 iterations --max 50 # Allow up to 50 iterations ``` ### Time Limit (`--max-time `) Safety limit - loop exits after specified duration. ``` --max-time 1h # Stop after 1 hour --max-time 30m # Stop after 30 minutes --max-time 8h # Overnight run ``` ### Cost Limit (`--max-cost `) Safety limit - loop exits when estimated cost reaches limit. ``` --max-cost $5 # Stop at $5 estimated cost --max-cost $50 # Allow up to $50 ``` --- ## State Management ### State File: `.claude/loop/state.json` ```json { "id": "loop_20260103_154500", "status": "running", "prompt": "Build REST API with tests", "mode": "standard", "started_at": "2026-01-03T15:45:00Z", "iterations": { "current": 5, "max": 20 }, "completion": { "type": "exact", "condition": "All tests passing", "met": false }, "checkpoints": [ { "iteration": 3, "timestamp": "2026-01-03T15:52:00Z", "summary": "API routes created, starting tests" } ], "metrics": { "estimated_tokens": 45000, "estimated_cost": "$1.35", "elapsed_time": "7m 23s" } } ``` ### Checkpoint Files: `.claude/loop/checkpoints/` Each checkpoint saves: - Current iteration number - Files modified since last checkpoint - Summary of progress - Any errors encountered --- ## Loop Execution Process ### Pre-Loop Validation 1. **Parse Arguments** - Validate prompt exists - Check completion conditions are valid - Verify safety limits are set 2. **Environment Check** - Ensure no other loop is running - Check for paused loops to resume - Validate project state 3. **Initialize State** - Create state file - Set up logging - Record start metrics ### Iteration Cycle ``` ┌─────────────────────────────────────┐ │ START ITERATION │ └─────────────────┬───────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Execute Prompt/Task │ │ (Full Claude capabilities) │ └─────────────────┬───────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Run Verification (if set) │ │ (--verify command) │ └─────────────────┬───────────────────┘ │ ▼ ┌─────────────────────────────────────┐ │ Check Completion Conditions │ │ - Exact match? │ │ - Exit code? │ │ - Regex match? │ │ - Max iterations? │ │ - Time/cost limits? │ └─────────────────┬───────────────────┘ │ ┌─────────┴─────────┐ │ │ ▼ ▼ [COMPLETE] [CONTINUE] │ │ ▼ ▼ ┌───────────────┐ ┌───────────────┐ │ Generate │ │ Checkpoint │ │ Summary │ │ (if needed) │ │ Report │ │ │ └───────────────┘ └───────┬───────┘ │ ▼ [NEXT ITERATION] ``` ### Post-Loop Summary Generate report including: - Total iterations - Time elapsed - Estimated cost - Files modified - Key milestones - Final status --- ## Safety Guardrails ### Mandatory Limits Every loop MUST have at least one safety limit: - `--max ` (default: 20) - `--max-time ` (default: 2h) - `--max-cost ` (no default) ### Automatic Pauses Loop pauses automatically when: - Critical error encountered 3 times - User input explicitly required - Dangerous operation detected - Cost limit approaching (80% warning) ### Forbidden in Loops Never execute during autonomous loops: - Git push operations - Deployments - Database migrations (production) - Irreversible deletions - Operations requiring secrets input --- ## Commands | Command | Description | |---------|-------------| | `/loop "" [options]` | Start new loop | | `/loop:status` | Show current loop status | | `/loop:pause` | Pause active loop | | `/loop:resume` | Resume paused loop | | `/loop:cancel` | Cancel/stop active loop | | `/loop:history` | View past loop runs | --- ## Examples ### Basic Loop ``` /loop "Fix all linting errors in src/" --until "0 errors" --max 10 ``` ### TDD Loop ``` /loop "Implement shopping cart feature" --mode tdd --verify "npm test" --until-exit 0 ``` ### Overnight Build ``` /loop "Build complete authentication system with tests" \ --until "AUTH_COMPLETE" \ --max 50 \ --max-time 8h \ --max-cost $20 ``` ### Refinement Loop ``` /loop "Improve test coverage to 80%" \ --verify "npm run coverage" \ --until-regex "coverage.*[89][0-9]%" \ --max 15 ``` --- ## Iteration Prompt Template Each iteration receives this context: ```markdown ## Loop Context **Iteration**: {current}/{max} **Elapsed**: {time} **Status**: {status} ## Original Task {user_prompt} ## Previous Iteration Summary {last_iteration_summary} ## Current State {relevant_file_states} ## Completion Target {completion_condition} ## Instructions Continue working toward the completion target. When complete, output: {completion_phrase} ``` --- ## Logging All loop activity logged to `.claude/loop/logs/`: - `loop_{id}.log` - Full execution log - `iterations_{id}.json` - Per-iteration details - `errors_{id}.log` - Errors encountered --- ## Delegation Hand off to other skills when: | Condition | Delegate To | |-----------|-------------| | UI/styling work detected | `frontend-design` | | New technology encountered | `meta-agent` | | Architecture decisions needed | `interview-agent` | | Patterns emerging | `learning-agent` | --- ## Best Practices 1. **Clear Completion Conditions**: Vague conditions lead to infinite loops 2. **Set Safety Limits**: Always use `--max` or `--max-time` 3. **Use Verification**: `--verify` with `--until-exit` is most reliable 4. **Start Small**: Test with `--max 3` before long runs 5. **Check Status**: Use `/loop:status` to monitor progress 6. **Review History**: Learn from past loops with `/loop:history`