version: "1.0.0" name: loop description: 'Use when the user wants to design, scaffold, or choose an agentic LOOP that repeats one task until a check passes — iterate-until-green automation, a long-running unattended build, or picking which loop engine fits — landing as a written .context/loops/ loop-spec (goal + verifiable stop condition + guardrails + chosen engine) before the loop runs. Fires on "design a loop for X", "set up a loop to keep building until tests pass", "make a loop that iterates until green", "loop until the build is clean", "which loop should I use". Not for: one-shot multi-agent fan-out across N different targets, which repeats nothing (/aidex:workflow); executing an existing loop right now (hand off to the ralph-loop plugin, /loop, or /goal); one-off tasks with no stop condition; planning multi-step work without a loop (/aidex:plan); ecosystem audits (/aidex:aidex); project-state audits (/aidex:audit).' argument-hint: "[design [slug] | new <slug> | run <slug>]" disable-model-invocation: false allowed-tools: Bash Read Write Edit Glob Grep Agent model-policy: per-stage

Loop — Design Agentic Loops

Help the user design and specify an agentic loop before running it, capture it as a .context/loops/ loop-spec, then hand off execution to an existing engine. This skill does not implement a loop runner — three mature engines already exist (/goal, /loop, the ralph-loop plugin) plus headless claude -p. The value here is the decision, the spec, and the guardrails.

See references/01-loop-engines.md for the engine matrix and guardrails, and references/02-loop-spec-conventions.md for the artifact format.

Default autonomy

On run start, apply Mode A autonomy automatically — do not wait for the user to grant it. Questions live in the initial alignment moment only; after that the run proceeds start-to-finish per the shared canon (deny/pre-authorized/mandated/autonomous). See "Run doctrine" below for how this applies once a loop is running.

Sub-actions

Dispatch by first argument:

Dispatch logic

bash "${CLAUDE_SKILL_DIR}/scripts/new-loop-spec.sh" "$@"

• new <slug> → new-loop-spec.sh new <slug>
• design [slug] → run the interview below, then new-loop-spec.sh new <slug> and fill it in
• run <slug> → no script; read the spec and follow run below
• no args → list specs (ls .context/loops/*.md) and show this help

design — the interview

Borrow the Socratic, one-question-at-a-time style. Walk the user through references/01-loop-engines.md §"Adoption steps". Do not skip step 0 or step 1 — they decide whether a loop is even appropriate.

No interactive channel (claude -p, cron): do not attempt the interview — take each step's recommended default and record the defaulting in the loop-spec. Steps 0 and 1 are the exception: a loop with no verifiable gate has no defensible default, so say so in the spec and stop rather than guess one. autonomy-conventions.md § When there is no interactive channel.

1. Loop-suitability (step 0). Is there a check the machine can run to say

pass/fail? If no verifiable gate exists, stop: this is interactive work, not a loop. Say so plainly.

1. The gate (step 1). What is the verifiable stop condition? (tests pass /

exit 0 / type-check clean / lint clean / screenshot diff / a verifier subagent). Pin it down concretely — this becomes the spec's stop condition. A per-iteration "tests pass" means the SELECTED suite, never the full one (affected-tests.sh --command): a loop pays its stop condition on every iteration, so a full suite there is the largest repeated cost a loop can carry. The full suite belongs once, at the loop's end, which is its integration boundary (decision/2026-08-24-full-suite-gate-moves-from-commit-to-integration).

1. Shape. Greenfield or existing code? One task or many? Must it run with the

machine off? Budget ceiling?

1. Engine. First cut: ask what the user is handing off — the verification

check, the stop condition, the trigger, or the whole prompt (see the reference §"First cut"). Then use the decision matrix to pick: /goal · /loop · ralph-loop · claude -p while-loop · Routines (/schedule) · Channels · Workflow — or, for proactive loops, a composed stack (/schedule + /goal + Workflow) recorded as engine: routine+goal+workflow. Recommend one, name the runner-up, say why.

1. Autonomy surface (step 1.5). Resolve the permission borders so the loop runs

unattended. Walk references/01-loop-engines.md §"Step 1.5". Use Claude Code's native allow/ask/deny — do NOT enumerate an allowlist. Pin three things: (a) any loop-specific deny beyond the base destructive config; (b) the pre-authorized ops that may run without asking; (c) the always-ask set (defaults: push/publish/deploy/release, plus integrating a branch into the trunk — merging the trunk INTO the loop's branch stays autonomous; NOT commit, deps, or additive migrations, which are autonomous; a destructive migration stays gated). Everything else safe + additive is autonomous: proceed, verify the assumption, log it. This is the lever that stops the loop from interrupting the user. (ADR decision/2026-06-19-loop-autonomy-surface-native-permissions.md.)

1. Isolation surface. Decide whether the loop needs its own git worktree so it does

not trample your other work or shared state. Check whether .context/worktrees/00-index.md exists in the target project: if not, invoke worktree bootstrap first. Then record the worktree command (worktree.sh new <slug> --branch <branch>; a loop that runs migrations or mutates the DB unattended is the strongest case for the full stack, never --no-infra) in the spec's Guardrails → isolation line exactly as today. Entry stays opt-in (user / project CLAUDE.md authorizes).

1. Scaffold. Run new-loop-spec.sh new <slug>, then fill every section of the

generated spec from the answers. Leave nothing as a placeholder. If a spec with that slug already exists (new-loop-spec.sh refuses to overwrite), refine the existing spec in place from the interview answers instead of re-scaffolding.

run

1. Read .context/loops/<date>-<slug>.md.
2. Confirm the stop condition and guardrails are still accurate.
3. Emit the engine command from the spec's Run command field. Do not invent a

new loop — dispatch to the chosen engine:

• goal → /goal "<condition> … or stop after N turns"
• loop → /loop <interval> <prompt-or-command>
• ralph → /ralph-loop "<prompt>" --completion-promise "DONE" --max-iterations N
• claude-p → the while one-liner over claude -p with scoped --allowedTools
• routine → /schedule …

1. Only execute it if the user explicitly asks you to start the loop now;

otherwise print the command for them to run.

Run doctrine — autonomy during the run

Once a spec's Autonomy surface is declared, the loop runs to its stop condition or turn cap without interrupting the user:

• Do not pause for anything outside the declared ask-set. Routine, safe,

additive work proceeds — including an unforeseen, non-breaking architectural micro-decision that falls under your authorship.

• Pause only for the deny set (blocked outright) and the ask set

(push/publish/deploy/release, merging the loop's branch into the trunk — not the trunk into the branch — plus any the spec declared). Commit, deps, and additive migrations are not in the ask-set — outward publication and trunk integration are.

• Proceed + log, don't halt: on a safe additive decision, the burden is to

verify the assumption is correct (investigate, don't guess) and surface or log what you decided — not to stop. You may investigate, read the DB, and take a backup without asking when it gives confidence to continue.

• **Ambiguous consent point not in the declared ask-set → consult the

durability-arbiter, do not deadlock.** Read `../conventions/agents/durability-arbiter.md`, pass it to the Agent tool (model: sonnet, effort: high, read-only) with the situation + the spec's autonomy surface + proof, and follow its verdict; batch any ASK to the end. If it errors, apply the rule above and proceed — never block on it. model-policy: per-stage — that pin is the policy: the gate's depth is set here, not inherited from the loop asking to be judged.

This is the loop's instance of the shared autonomy canon — full decision rule, the commit-is-not-gated policy, and the durability-arbiter in autonomy-conventions.md.

Self-check

Validate the artifact you just wrote and fix any violation before closing:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/validate.py --type loops

If the project carries a ratchet baseline (.context/.validate-baseline.json), a non-zero exit means you introduced a NEW violation — fix it before closing.

Boundaries

Related

• ralph-loop (plugin) — one of the run targets; loop scaffolds the

methodology (specs, back pressure, disposable plan) the plugin does not ship.

• plan — for multi-phase work that is not a loop.
• conventions — owns the shared .context/ documentation canon.