Skip to main content
skill CX Codex

loop-architect — Claude Code skill: design agent loops before execution

loop-architect is a Claude Code skill that guides iterative workflow design, from goal refinement and verification criteria to reviewer selection and termination guards.

MIT ★ 141 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add fabricioctelles/skills --skill loop-architect -a claude-code
Open on GitHub

What loop-architect does

loop-architect conducts a seven-stage interview: clarifies your goal, sets typed verification rules, picks a host model and reviewers, configures termination and observability. Each stage is critiqued against built-in rubrics—vague goals are pushed toward outcome and definition of done, weak verification toward programmatic checks or judge verdicts.

Emits loop.yaml, loop.resolved.json, LOOP.md, RUN_IN_SESSION.md, and run-loop.py. The loop can run immediately inside the session via /goal, as a subagent pipeline with native review gates, or later via the Python runner. If the council includes models from other vendors, the skill explicitly states what context leaves your machine, which CLI handles it, and what redaction globs apply.

What it helps with

  • design a self-review loop with explicit exit criteria
  • assemble a multi-model council with judge verdicts and cross-vendor context isolation
  • configure iteration guards—max steps, progress signals, revision caps per gate
  • export a loop spec for scheduled runs, CI pipelines, or external execution
  • route outputs through multiple reviewers before a loop starts execution

Example prompts for the agent

  • Design a loop to draft and review a report: agent writes, second model judges against a rubric, loop terminates when score exceeds threshold
  • Build a self-review loop capped at 5 iterations where each cycle validates output against a programmatic checklist
  • Create a multi-model council: Claude plans, Gemini judges code changes, loop ends when approval gate passes

How to install loop-architect

1Skills CLI (Vercel)

npx skills add fabricioctelles/skills --skill loop-architect -a claude-code

2Manually: put the files in place

~/.claude/skills/loop-architect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/loop-architect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about loop-architect

How do I install loop-architect in Claude Code?

Run npx skills add fabricioctelles/skills --skill loop-architect -a claude-code, then open ~/.claude/skills/loop-architect/SKILL.md.

What does loop-architect do?

It coaches you through seven stages of loop design—goal, verification, host model, council, control guards, confirmation—then outputs loop.yaml and a Python runner. You can execute via /goal, a subagent pipeline, or the runner script.

How is loop-architect different from /goal?

/goal executes a self-checking loop on your current model. loop-architect first helps you design the loop correctly—with typed verification, cross-model reviewers, and termination guards—then offers three ways to run it.

Source text

SKILL.md · MIT
---
name: loop-architect
description: >
  Design well-structured agent loops with best-practice coaching and cross-model
  review gates before you run them. Use when the user wants to design, build, or
  set up an agent loop, iterative agent workflow, self-review loop, LLM-as-judge
  loop, multi-model council, reviewer/judge gate, or goal-driven looping process.
  Guides goal refinement, typed verification criteria, reviewer/judge selection,
  privacy boundaries, termination guards, and observability, then emits a
  RUN_IN_SESSION.md handoff prompt plus portable loop.yaml, loop.resolved.json,
  LOOP.md, and run-loop.py.
metadata:
  author: https://ft.ia.br
  version: "1.2"
  date: 2026-10-14
  repository: https://github.com/fabricioctelles/skills
  license: MIT
  original_project: https://github.com/ksimback/looper
  original_author: Kevin Simback (@ksimback)
  attribution: >
    Reinterpretation of Looper (MIT License) by Kevin Simback, adapted for
    Kiro CLI with native /goal, subagent, and review loop integration.
  category: code-scaffolding-and-templates
---

# Loop Architect

A loop design coach for Kiro CLI. Interviews you, critiques your design against
built-in best-practice rubrics, wires in cross-model reviewers or judges, shows
the loop as an ASCII flow preview, and writes portable artifacts you can run
immediately with `/goal` or later with the Python runner.

> Based on [Looper](https://github.com/ksimback/looper) by Kevin Simback, MIT License.
> Adapted for Kiro CLI by ft.ia.br.

## Why This Exists

Kiro CLI ships `/goal` (autonomous loop with self-verification) and subagents
(parallel pipelines with review loops). These **execute** a loop. Loop Architect
helps you **design** one worth executing — with a coached goal, typed
verification, a cross-model gate, and explicit termination guards.

| | `/goal` | Subagent pipeline | **Loop Architect** |
|---|---|---|---|
| Layer | execution | execution | **design (pre-flight)** |
| Coaches your goal | no | no | **yes** |
| Typed verification | no | no | **yes (programmatic / judge / human)** |
| Reviewer model | same model | configurable | **different model, by default** |
| Portable artifact | no | no | **loop.yaml + resolved spec** |
| Runs the loop | **yes** | **yes** | **yes, via handoff** |

## Workflow

1. Resolve the target path from the user. Default: `./loop-architect-output`. If
   the target contains an existing `loop.yaml`, treat as edit/resume.

2. Load the relevant rubric only when entering that stage:
   - Goal stage: `references/goal-rubric.md`
   - Verification stage: `references/verification-rubric.md`
   - Council stage: `references/council-rubric.md`
   - Control stage: `references/control-rubric.md`
   - Model detection: `references/model-detection.md`

3. Interview in seven stages: goal, verification, host model, council,
   gates/control, confirmation flow preview, emit/run option. In the control
   stage, cover execution boundary, isolation, no-progress signals, state, and
   run logging.

4. Critique each stage before accepting it. Prefer concrete alternatives over
   vague warnings. Push weak goals toward outcome, scope, context, and done
   state. Push weak verification toward programmatic checks first, then judge
   rubrics, then human signoff.

5. Keep reviewer and judge roles distinct. A reviewer writes notes. A judge
   returns a structured verdict. `revise_until_clean` must name a judge member
   or `human` as `verdict_source`.

6. Require multiple termination guards: `max_iterations`, a revision cap on
   each gate, a no-progress stop, and either a budget cap or an explicit human
   stop point.

7. Before any cross-vendor council member is selected, state what context will
   leave the user's machine, which CLI receives it, which redaction globs apply,
   and that both execution paths require first-send consent.

8. Show an ASCII flow preview and ask for confirmation before final emission.

9. Emit these files into the target:
   - `loop.yaml`
   - `loop.resolved.json`
   - `LOOP.md`
   - `RUN_IN_SESSION.md`
   - `run-loop.py`
   - `loop-workspace/`
   - `README.md`

10. After writing `loop.yaml`, compile it:
    ```bash
    python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile \
      <target>/loop.yaml \
      --out <target>/loop.resolved.json \
      --render <target>/LOOP.md \
      --session-prompt <target>/RUN_IN_SESSION.md
    ```

11. Ask whether the user wants to run the loop now. If yes:
    - **Easy path**: Follow `RUN_IN_SESSION.md` directly, or suggest a `/goal`
      one-liner derived from the `definition_of_done`.
    - **Subagent path**: If the council uses a model with `review_loop`
      capability, offer to execute via a subagent pipeline with native review
      loops.
    - **External path**: Explain that `run-loop.py` is available for running
      later or outside the session.

## Execution Paths

### Path 1: `/goal` (simplest)

When the loop is straightforward and the host is the current Kiro session:

```
/goal --max 12 <definition_of_done from loop.yaml>
```

This uses Kiro's native self-verification loop. No cross-model review, but
fast and zero-config.

### Path 2: Subagent review pipeline (recommended)

When a cross-model reviewer is needed and the host has `subagent` capability:

```
Implement the loop following RUN_IN_SESSION.md. Use a subagent as reviewer
with trigger "NEEDS_CHANGES" and max 3 iterations per gate.
```

This leverages Kiro's native `loop_to` mechanism for the plan and delivery
gates.

### Path 3: External Python runner (advanced)

```bash
python3 ./loop-architect-output/run-loop.py
```

For scheduled runs, CI integration, or when you need strict budget enforcement.

## File Rules

- Write argv arrays, never shell command strings, for all model invocations.
- Do not write API keys, tokens, or credentials into any emitted file.
- Default redaction globs: `.env`, `.env.*`, `secrets/**`, `**/*.key`.
- Keep `loop.yaml` human-readable and commented.
- Keep `RUN_IN_SESSION.md` as the default/easy execution handoff.
- Copy `templates/run-loop.py` exactly unless the user asks to edit it.

## Helper Scripts

Detect model CLIs:
```bash
python3 ~/.kiro/skills/loop-architect/scripts/looper.py detect-models --write
```

Register a custom CLI:
```bash
python3 ~/.kiro/skills/loop-architect/scripts/looper.py register-model <id> \
  --invoke kiro-cli chat --trust-all-tools -p --authed
```

Compile and render:
```bash
python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile <target>/loop.yaml \
  --out <target>/loop.resolved.json \
  --render <target>/LOOP.md \
  --session-prompt <target>/RUN_IN_SESSION.md
```

## Confirmation Flow Preview

```text
+--------------------------------+
| 1. Goal + context              |
|    read sources                |
+--------------------------------+
              |
              v
+--------------------------------+
| 2. Draft plan.md               |
|    state -> state.json         |
+--------------------------------+
              |
              v
+--------------------------------+
| 3. Plan gate                   |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise <= 3 -> step 2
  | pass
              v
+--------------------------------+
| 4. Write delivery-N.md         |
|    log -> run-log.md           |
+--------------------------------+
              |
              v
+--------------------------------+
| 5. Delivery gate               |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise <= 3 -> step 4
  | pass
              v
+--------------------------------+
| 6. Final output                |
|    all gates clean             |
+--------------------------------+

Stops: pass gates | max 12 iterations | no progress x2 | budget 30m, $5.0
```

## Emit Checklist

- The goal has a clear outcome, scope boundary, context sources, and done state.
- Verification criteria are typed as `programmatic`, `judge`, or `human`.
- At least one criterion is not purely vibe-based.
- Each `revise_until_clean` gate has a valid `verdict_source`.
- Every external invocation is an argv array with a timeout.
- Cross-vendor egress is scoped, redacted, and consent-gated.
- `loop_control` has iteration, revision, no-progress, and budget caps.
- Execution boundary and isolation are explicit.
- Observability names a `run-log.md` and `state.json` path.
- Compiled artifacts (`loop.resolved.json`, `LOOP.md`, `RUN_IN_SESSION.md`)
  pass validation before handoff.

© https://ft.ia.br · MIT · fabricioctelles/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set46

The whole set →
human-ai human-ai reworks English prose to remove canned AI wording and stiff structure while keeping the source facts, meaning, and authorial voice. CX Codex +1 ★ 141repo stars design-md-validator design-md-validator is a Claude Code skill that checks DESIGN.md against Google's specification with the @google/design.md CLI linter. It flags broken token references and computes WCAG contrast ratios. CX Codex +1 ★ 141repo stars humanizar humanizar is a Claude Code skill that drafts and edits Brazilian Portuguese text with natural cadence while preserving the author's facts and voice. CX Codex +1 ★ 141repo stars agent-plugin-eval agent-plugin-eval audits Agent Plugin repositories against the specification, scores them, and compares two targets. Use it for release reviews and conformance checks. CX Codex +1 ★ 141repo stars astro-sites-manager astro-sites-manager is a Claude Code skill for setting up and updating Astro v7 projects, configuring background dev servers for AI workflows, and querying the astro-docs MCP server. CX Codex +1 ★ 141repo stars ralph-loop-kiro-specs The ralph-loop-kiro-specs skill runs kiro-cli in a loop, handling one Kiro spec task per iteration. Use it to automate implementation and check each task against its exit criteria. CX Codex +1 ★ 141repo stars security-specialist security-specialist runs security audits on codebases, builds threat models, validates exploits, and exports HTML reports. Helpful for testing repositories and pull requests for reproducible flaws. CX Codex +1 ★ 141repo stars human-ai The human-ai skill edits English prose to remove AI-like phrasing and stiff structure while keeping the writer’s meaning, facts, and voice intact. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open