Loop Architect

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 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.

1. 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

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

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

1. Emit these files into the target:

• loop.yaml
• loop.resolved.json
• LOOP.md
• RUN_IN_SESSION.md
• run-loop.py
• loop-workspace/
• README.md

1. After writing loop.yaml, compile it:

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

1. 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 

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)

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:

python3 ~/.kiro/skills/loop-architect/scripts/looper.py detect-models --write

Register a custom CLI:

python3 ~/.kiro/skills/loop-architect/scripts/looper.py register-model  \
  --invoke kiro-cli chat --trust-all-tools -p --authed

Compile and render:

python3 ~/.kiro/skills/loop-architect/scripts/looper.py compile /loop.yaml \
  --out /loop.resolved.json \
  --render /LOOP.md \
  --session-prompt /RUN_IN_SESSION.md

Confirmation Flow Preview

+--------------------------------+
| 1. Goal + context              |
|    read sources                |
+--------------------------------+
              |
              v
+--------------------------------+
| 2. Draft plan.md               |
|    state -> state.json         |
+--------------------------------+
              |
              v
+--------------------------------+
| 3. Plan gate                   |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise  step 2
  | pass
              v
+--------------------------------+
| 4. Write delivery-N.md         |
|    log -> run-log.md           |
+--------------------------------+
              |
              v
+--------------------------------+
| 5. Delivery gate               |
|    verdict: reviewer-1         |
+--------------------------------+
  | needs work -> revise  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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fabricioctelles
• Source: fabricioctelles/skills
• License: Apache-2.0
• Homepage: https://skill.dev.br

Install and usage instructions live in the source repository linked above.