AI-Loop Skill
Overview
The ai-loop skill structures a bounded development cycle for agentic workflows. It divides work into three explicit phases — Spec, Build, Review — and loops between Build and Review until every requirement passes verification, a stop condition is reached, or human approval is needed.
Before invoking the loop, the agent must define and record:
- Iteration budget: maximum number of Build→Review cycles (default: 3).
- Verification evidence: the exact commands or manual checks that count as proof.
- Approval gates: any action requiring explicit human sign-off (destructive commands, production changes, external service writes, credential changes, broad architectural pivots).
When to Use
- A feature needs to be built from scratch or heavily modified, and the agent should own the full lifecycle (specification, implementation, verification) inside one bounded workflow.
- The work targets an isolated component, module, or feature with well-defined scope and constraints.
- The user asks for a complete development pass and there are clear success criteria, a reasonable verification path, and no unresolved safety or product decisions.
Do not use for open-ended architectural refactoring, security-sensitive changes, or work where verification depends on unavailable credentials or systems — stop instead.
Prerequisites
- A working directory where
specs/ can be created (PowerShell: New-Item -ItemType Directory -Path specs -Force).
- Verification commands that can actually run in the current environment (tests, linters, type-checkers, build scripts).
- Sufficient user context available during the Spec phase to pin down requirements.
Procedure
0. Pre-Loop Setup
- Confirm the feature name with the user. Use a kebab-case
<feature-name> for file paths.
- Create the specs directory if it does not exist:
New-Item -ItemType Directory -Path specs -Force
- Agree on and record the iteration budget, verification commands, and approval gates before any design discussion.
Phase 1: Spec (Planning)
- Interview the user about the feature. Ask one focused question at a time until the goal, must-have requirements, constraints, and definition of done are clear.
- Do not start building yet.
- Write a detailed specification and save it to
specs/<feature-name>.md.
- The spec must include:
- The objective.
- The exact requirements (numbered or bulleted, individually checkable).
- Edge cases to handle.
- A concrete definition of done that someone could check the build against.
- The iteration budget.
- The verification commands or manual checks.
- The approval gates (destructive ops, production changes, external writes, credential changes, architectural pivots).
Phase 2: Build (Implementation)
- Read the spec at
specs/<feature-name>.md.
- Build exactly what it describes.
- Do not add features. Do not refactor unrelated code. Do not invent requirements not in the spec.
- After implementing, list which spec requirements you covered so the Review phase can check them.
Phase 3: Review (Verification)
- Compare the implementation against
specs/<feature-name>.md.
- Go requirement by requirement and verify whether each was met. List every gap, bug, or missing piece, naming the exact spec item each failure maps to.
- Run the declared verification commands and record their output as evidence.
- If anything fails and the iteration budget is not exhausted, write the specific fixes needed and loop back to Phase 2 (Build).
- Stop and ask for human input when the next fix would:
- Change the spec.
- Exceed the iteration budget.
- Require risky operations (destructive, production, credentialed, externally visible).
- Depend on product decisions not captured in the spec.
- Only conclude the skill when every requirement in the spec is fully met and the declared verification evidence has passed.
Examples
Example: 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 (
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.
Pitfalls
- Problem: Agent tries to build a huge system all at once, leading to an overcomplicated spec and incomplete implementation.
Solution: Keep
ai-loop scope to small, modular features. Break larger systems into multiple independent loops.
- Problem: Spec is vague, causing the Build phase to rely on assumptions.
Solution: Spend extra time in Spec asking targeted questions one at a time. Do not proceed to Build until every requirement is individually checkable.
- Problem: Agent keeps retrying the same failing fix without progress.
Solution: Do not repeat the same fix without new evidence or a changed approach. If the budget is exhausted, stop and report exactly what remains.
- Problem: Agent adds extra features or unrelated refactors during Build.
Solution: Build strictly to the spec. Any addition requires a spec update and re-approval.
- Problem: Review passes without running verification commands.
Solution: Review must execute the declared verification commands and record output. Self-assessment alone is insufficient for critical systems.
- Problem: Hardcoded secrets leak into code or specs.
Solution: Never add secrets, keys, or credentials to code or specs. Use
YOUR_KEY placeholders and environment variables.
Verification
Confirm the loop completed correctly with these checks:
Spec file exists and is complete:
Test-Path specs\<feature-name>.md
Expected output: True
Spec contains all required sections:
Select-String -Path specs\<feature-name>.md -Pattern "objective","requirements","definition of done","iteration budget","verification","approval"
Expected: matches for each pattern.
Run the declared verification commands from the spec (e.g., tests, linters):
npm test
Expected: all tests pass with exit code 0.
Review log covers every numbered requirement:
- Each requirement in
specs/<feature-name>.md has an explicit PASS or FAIL entry.
- Any FAIL was either fixed in a subsequent Build loop-back or escalated to the user with a stop reason.
No unapproved risky actions were taken:
- No destructive commands, production deploys, external writes, or credential changes executed without explicit human approval.
Security & Safety Notes
- Run and test Build-phase code in a safe, sandboxed environment.
- Do not execute arbitrary shell commands provided directly by the user without validating their safety.
- Never add hardcoded secrets, keys, or credentials to code or specifications. Use
YOUR_KEY placeholders.
- Treat production deploys, data migrations, payment flows, credential changes, and external write actions as approval-gated work.
- Stop rather than continue if requirements conflict, tests cannot run, or verification depends on unavailable credentials or systems.
Related Skills
@plan-writing — For writing more detailed implementation plans for larger projects.@ask-questions-if-underspecified — For standard guidelines on interviewing the user.
1---2name: ai-loop3description: Runs a bounded Spec-Build-Review cycle with an iteration budget, recorded verification commands, and human approval gates. Use when an isolated feature needs a full build from scratch or a heavy modification with checkable requirements. Not for open-ended architecture refactors, /goal contracts, or work whose tests depend on missing credentials.4---5
6# AI-Loop Skill
7
8## Overview
9
10The `ai-loop` skill structures a bounded development cycle for agentic workflows. It divides work into three explicit phases — **Spec**, **Build**, **Review** — and loops between Build and Review until every requirement passes verification, a stop condition is reached, or human approval is needed.
11
12Before invoking the loop, the agent must define and record:
13
14- **Iteration budget**: maximum number of Build→Review cycles (default: 3).
15- **Verification evidence**: the exact commands or manual checks that count as proof.
16- **Approval gates**: any action requiring explicit human sign-off (destructive commands, production changes, external service writes, credential changes, broad architectural pivots).
17
18## When to Use
19
20- A feature needs to be built from scratch or heavily modified, and the agent should own the full lifecycle (specification, implementation, verification) inside one bounded workflow.
21- The work targets an isolated component, module, or feature with well-defined scope and constraints.
22- The user asks for a complete development pass and there are clear success criteria, a reasonable verification path, and no unresolved safety or product decisions.
23
24Do **not** use for open-ended architectural refactoring, security-sensitive changes, or work where verification depends on unavailable credentials or systems — stop instead.
25
26## Prerequisites
27
28- A working directory where `specs/` can be created (PowerShell: `New-Item -ItemType Directory -Path specs -Force`).
29- Verification commands that can actually run in the current environment (tests, linters, type-checkers, build scripts).
30- Sufficient user context available during the Spec phase to pin down requirements.
31
32## Procedure
33
34### 0. Pre-Loop Setup
35
361. Confirm the feature name with the user. Use a kebab-case `<feature-name>` for file paths.
372. Create the specs directory if it does not exist:
38 ```powershell
39 New-Item -ItemType Directory -Path specs -Force
40 ```
413. Agree on and record the iteration budget, verification commands, and approval gates before any design discussion.
42
43### Phase 1: Spec (Planning)
44
451. Interview the user about the feature. Ask **one focused question at a time** until the goal, must-have requirements, constraints, and definition of done are clear.
462. **Do not start building yet.**
473. Write a detailed specification and save it to `specs/<feature-name>.md`.
484. The spec must include:
49 - The objective.
50 - The exact requirements (numbered or bulleted, individually checkable).
51 - Edge cases to handle.
52 - A concrete definition of done that someone could check the build against.
53 - The iteration budget.
54 - The verification commands or manual checks.
55 - The approval gates (destructive ops, production changes, external writes, credential changes, architectural pivots).
56
57### Phase 2: Build (Implementation)
58
591. Read the spec at `specs/<feature-name>.md`.
602. Build **exactly** what it describes.
613. **Do not add features.** Do not refactor unrelated code. Do not invent requirements not in the spec.
624. After implementing, list which spec requirements you covered so the Review phase can check them.
63
64### Phase 3: Review (Verification)
65
661. Compare the implementation against `specs/<feature-name>.md`.
672. Go requirement by requirement and verify whether each was met. List every gap, bug, or missing piece, naming the **exact spec item** each failure maps to.
683. Run the declared verification commands and record their output as evidence.
694. If anything fails and the iteration budget is **not exhausted**, write the specific fixes needed and **loop back to Phase 2 (Build)**.
705. **Stop and ask for human input** when the next fix would:
71 - Change the spec.
72 - Exceed the iteration budget.
73 - Require risky operations (destructive, production, credentialed, externally visible).
74 - Depend on product decisions not captured in the spec.
756. Only conclude the skill when **every** requirement in the spec is fully met and the declared verification evidence has passed.
76
77## Examples
78
79### Example: Basic Statistics Helper
80
81**User:**
82> I want to add a utility for calculating basic statistics (mean, median, mode) of an array of numbers.
83
84**Agent (Phase 1 - Spec):**
85> 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?
86
87**User:**
88> JavaScript. If the array is empty, return null. If there are non-numbers, ignore them.
89
90**Agent (Phase 1 - Spec):**
91> Thank you. I have created the specification file at `specs/stats-calculator.md` with the requirements we discussed. Now, I will start implementing it.
92
93**Agent (Phase 2 - Build):**
94> *(Creates `stats_calculator.js` and implements `mean`, `median`, and `mode` matching the spec exactly)*
95> I have finished implementing the calculator. I will now verify the implementation.
96
97**Agent (Phase 3 - Review):**
98> Checking implementation against `specs/stats-calculator.md`:
99> - Requirement: mean calculation -> PASS
100> - Requirement: median calculation -> PASS
101> - Requirement: mode calculation -> PASS
102> - Requirement: empty array returns null -> PASS
103> - Requirement: non-numbers are ignored -> FAIL (`mode` doesn't filter out non-numbers).
104>
105> I will now loop back to Phase 2 to fix the `mode` function.
106
107**Agent (Phase 2 - Build Loop-Back):**
108> *(Fixes `mode` to filter out non-numbers)*
109> I have updated the implementation. Let's re-verify.
110
111**Agent (Phase 3 - Review):**
112> - Requirement: mode filters non-numbers -> PASS
113>
114> All requirements passed! The statistics calculator is complete and verified.
115
116## Pitfalls
117
118- **Problem:** Agent tries to build a huge system all at once, leading to an overcomplicated spec and incomplete implementation.
119 **Solution:** Keep `ai-loop` scope to small, modular features. Break larger systems into multiple independent loops.
120- **Problem:** Spec is vague, causing the Build phase to rely on assumptions.
121 **Solution:** Spend extra time in Spec asking targeted questions one at a time. Do not proceed to Build until every requirement is individually checkable.
122- **Problem:** Agent keeps retrying the same failing fix without progress.
123 **Solution:** Do not repeat the same fix without new evidence or a changed approach. If the budget is exhausted, stop and report exactly what remains.
124- **Problem:** Agent adds extra features or unrelated refactors during Build.
125 **Solution:** Build strictly to the spec. Any addition requires a spec update and re-approval.
126- **Problem:** Review passes without running verification commands.
127 **Solution:** Review must execute the declared verification commands and record output. Self-assessment alone is insufficient for critical systems.
128- **Problem:** Hardcoded secrets leak into code or specs.
129 **Solution:** Never add secrets, keys, or credentials to code or specs. Use `YOUR_KEY` placeholders and environment variables.
130
131## Verification
132
133Confirm the loop completed correctly with these checks:
134
1351. Spec file exists and is complete:
136 ```powershell
137 Test-Path specs\<feature-name>.md
138 ```
139 Expected output: `True`
140
1412. Spec contains all required sections:
142 ```powershell
143 Select-String -Path specs\<feature-name>.md -Pattern "objective","requirements","definition of done","iteration budget","verification","approval"
144 ```
145 Expected: matches for each pattern.
146
1473. Run the declared verification commands from the spec (e.g., tests, linters):
148 ```powershell
149 npm test
150 ```
151 Expected: all tests pass with exit code `0`.
152
1534. Review log covers every numbered requirement:
154 - Each requirement in `specs/<feature-name>.md` has an explicit PASS or FAIL entry.
155 - Any FAIL was either fixed in a subsequent Build loop-back or escalated to the user with a stop reason.
156
1575. No unapproved risky actions were taken:
158 - No destructive commands, production deploys, external writes, or credential changes executed without explicit human approval.
159
160## Security & Safety Notes
161
162- Run and test Build-phase code in a safe, sandboxed environment.
163- Do not execute arbitrary shell commands provided directly by the user without validating their safety.
164- Never add hardcoded secrets, keys, or credentials to code or specifications. Use `YOUR_KEY` placeholders.
165- Treat production deploys, data migrations, payment flows, credential changes, and external write actions as approval-gated work.
166- Stop rather than continue if requirements conflict, tests cannot run, or verification depends on unavailable credentials or systems.
167
168## Related Skills
169
170- `@plan-writing` — For writing more detailed implementation plans for larger projects.
171- `@ask-questions-if-underspecified` — For standard guidelines on interviewing the user.
Kayforkind