/ai-loop

name: ai-loop
description: Runs a bounded spec-build-review development loop with explicit scope, stop conditions, and human approval gates for risky or ambiguous work.
category: workflow
risk: safe
source: community
date_added: "2026-06-27"
tags: [agent-workflow, specification, implementation, review, verification, feedback-loop]
tools: [claude, cursor, codex, gemini]

AI-Loop Skill

Overview

The `ai-loop` skill structures a bounded development cycle for agentic workflows. By dividing the process into distinct planning (Spec), implementation (Build), and validation (Review) phases, it helps an agent build and correct scoped code changes while keeping requirements, risk gates, and stop conditions explicit.

When to Use This Skill

• Use when you need a feature built from scratch or heavily modified, and you want the agent to handle the lifecycle (specification, implementation, and verification) inside one clearly bounded workflow.
• Use when working with isolated components, modules, or features that have well-defined scopes and constraints.
• Use when the user asks for a complete development pass but the work still has clear success criteria, a reasonable verification path, and no unresolved safety or product decisions.

How It Works

This skill executes a controlled development loop composed of three phases: Spec, Build, and Review. When invoked, the agent moves through those phases until the scoped requirements pass verification, a stop condition is reached, or human approval is needed.

Before starting, define:

• The maximum number of build-review iterations.
• The verification commands or manual checks that count as evidence.
• The actions that require explicit approval, such as destructive commands, production changes, external service writes, or broad architectural pivots.

Phase 1: Spec (Planning)

1. Reuse the current request, accepted plan and existing artifacts. Ask only for essential missing scope or acceptance criteria; do not repeat answered questions. 2. **Do not start building yet.** 3. When you have enough information, use the existing specification or, when needed, save a scoped new one at `specs/<feature-name>.md` without overwriting user work. 4. The spec must include:

• The objective
• The exact requirements
• Edge cases to handle
• A concrete definition of done that someone could check the build against
• The iteration budget, verification commands, and approval gates.

Phase 2: Build (Implementation)

1. Read the spec you just created in `specs/<feature-name>.md`. 2. Build exactly what it describes. 3. **Do not add features**, do not refactor unrelated code, and do not invent requirements that aren't in the spec. 4. Focus strictly on fulfilling the spec. List which spec requirements you covered so the review step can check them.

Phase 3: Review (Verification)

1. Compare your implementation against `specs/<feature-name>.md`. 2. Go requirement by requirement and verify if it was met. List every gap, bug, or missing piece, naming the exact spec item each one fails. 3. If anything fails and the iteration budget is not exhausted, write the specific fixes needed and **loop back to Phase 2 (Build)** to address them. 4. Use the agreed iteration/resource limits and scope. Ask for material product or consequential authorization decisions that are not already resolved; routine repairs within the accepted outcome need no new checkpoint. Continue independent work when a dependent check is unavailable. 5. Only pass the build and conclude the skill execution when every requirement in the spec is fully met and the declared verification evidence has passed.

Examples

Example 1: Creating a Basic Statistics Helper

**User:** > I want to add a utility for calculating basic statistics (mean, median, mode) of an array of numbers.

**Agent (Phase 1 - Spec):** > I can help with that. To get started, what programming language should this statistics calculator be implemented in? Also, how should empty arrays or invalid inputs be handled?

**User:** > JavaScript. If the array is empty, return null. If there are non-numbers, ignore them.

**Agent (Phase 1 - Spec):** > Thank you. I have created the specification file at `specs/stats-calculator.md` with the requirements we discussed. Now, I will start implementing it.

**Agent (Phase 2 - Build):** > *(Creates `stats_calculator.js` and implements `mean`, `median`, and `mode` matching the spec exactly)* > I have finished implementing the calculator. I will now verify the implementation.

**Agent (Phase 3 - Review):** > Checking implementation against `specs/stats-calculator.md`: > - Requirement: mean calculation -> PASS > - Requirement: median calculation -> PASS > - Requirement: mode calculation -> PASS > - Requirement: empty array returns null -> PASS > - Requirement: non-numbers are ignored -> FAIL (I noticed `mode` doesn't filter out non-numbers). > > I will now loop back to Phase 2 to fix the `mode` function.

**Agent (Phase 2 - Build Loop-Back):** > *(Fixes `mode` to filter out non-numbers)* > I have updated the implementation. Let's re-verify.

**Agent (Phase 3 - Review):** > - Requirement: mode filters non-numbers -> PASS > > All requirements passed! The statistics calculator is complete and verified.

Best Practices

• ✅ Do ask clarifying questions one at a time to avoid overwhelming the user during the planning phase.
• ✅ Do document edge cases explicitly in `specs/<feature-name>.md` before writing any code.
• ✅ Do stick strictly to the approved specification during the build phase.
• ✅ Do cap the loop with a small iteration budget and report exactly what remains if the budget is exhausted.
• ✅ Do pause for explicit approval before destructive, production, credentialed, or externally visible actions.
• ❌ Don't implement extra features or perform unrelated refactorings that aren't specified.
• ❌ Don't skip the review phase or pass it without verifying every single requirement.