ranbot-ai/ai-loop

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. Interview the user about the feature or app they want to build. Ask one focused question at a time until you fully understand the goal, the must-have requirements, the constraints, and what "done" looks like.
2. Do not start building yet.
3. When you have enough information, write a clear, detailed specification and save it to specs/<feature-name>.md.
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. Stop and ask for human input when the next fix would change the spec, exceed the iteration budget, require risky operations, or depend on product decisions not captured in the spec.
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/<