# Specloop

> Run a bounded SPEC → BUILD → REVIEW → REPAIR workflow until verified or blocked. Explicit invocation only: `$specloop` in Codex or `/specloop` in Claude Code.

- Skill: `ivankuprin/specloop` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ivankuprin/specloop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ivankuprin/specloop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: ivankuprin (https://skillmd.com/u/ivankuprin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ivankuprin/specloop

---


# SpecLoop

Deliver the change through `DISCOVER → SPEC → BUILD → REVIEW → REPAIR`, repeating only while measurable progress is possible.

## Rules

- User, repository, host, and safety instructions override this skill.
- The approved spec is authoritative. Never weaken it, tests, or required checks to obtain PASS.
- Keep scope minimal; preserve unrelated behavior and user changes.
- Use current project state and observed results as evidence. Never present partial work as PASS.
- Do not commit, push, merge, deploy, publish, or perform destructive/external mutations without explicit authorization.

## Mode and record

Work autonomously and make conservative non-material assumptions. Ask only when a missing decision changes behavior, scope, safety, data handling, or requires an irreversible/external action. Pause before BUILD when the user requests approval.

Default record: `specs/<task-slug>.md` with `SPEC`, `EVIDENCE`, `REVIEW`, and `LOOP` sections. After each phase or repair, persist the phase, spec and project-state fingerprints, baseline revision, cumulative repair count, per-finding attempts/outcomes, and check results.

On resume, compare the spec, relevant project state, and check plan with the record. Invalidate affected evidence/reviews and rerun stale checks. Keep repair limits cumulative across sessions.

Strict mode uses separate spec, evidence, review, and loop files. Its fingerprints cover the spec, baseline, relevant working-tree diff, and required-check plan. Strict PASS requires an independent reviewer context; if unavailable or unpermitted, return BLOCKED.

## Loop

1. **DISCOVER:** locate the root; inspect applicable instructions, code, manifests, CI/tests, version-control state, and existing changes. Derive commands from evidence. Mark checks required or optional and map requirements to verification.
2. **SPEC:** reuse a matching spec or record the objective, current/desired behavior, scope, assumptions, stable IDs, edge/failure behavior, acceptance criteria, check plan, and done criteria. Save before BUILD. Material behavior changes require approval and invalidate review.
3. **BUILD:** make the smallest coherent change satisfying the spec. Add meaningful tests when practical, run affected checks, and record requirement-to-change evidence and uncertainty.
4. **REVIEW:** inspect the spec, actual diff, evidence, and results from disk. PASS requires the complete required gate on the current state, even without repair. Mark every requirement and criterion `PASS`, `FAIL`, or `BLOCKED`; for non-PASS items record a stable ID, evidence, remedy, and closing verification. Outside strict mode, use independent review when available; otherwise label self-review honestly.
5. **REPAIR:** fix unresolved findings and direct consequences, add useful regression coverage, rerun affected checks, and repeat the complete review. Close findings only after verification; rerun the full gate whenever changes make it stale.

## Gates and stopping

After each review, return `SPECLOOP PASS` first if every requirement, criterion, and required check passes, evidence is complete, and no blocker, correctness/safety finding, known regression, or unapproved scope change remains.

Otherwise repair while budget remains. Return `SPECLOOP BLOCKED` for unavailable material decisions/spec changes, authorization, credentials/infrastructure, or required checks; conflicting requirements; oscillation; a finding unresolved after two attempts without progress; or unresolved findings after three repairs. Report completed work, evidence, uncertainty, and the exact next action.

The final response must start with exactly `SPECLOOP PASS` or `SPECLOOP BLOCKED` and include the record path, cumulative repair count, reviewer isolation, and required-check results.