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.
2. 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).
3. Shape. Greenfield or existing code? One task or many? Must it run with the machine off? Budget ceiling?
4. 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.
5. 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.)
6. 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).
7. 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 …
4. 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 → decide it yourself, do not deadlock. Judge CONTINUE / ASK / STOP against the policy in the ARBITER block of workflow-core.md, using the spec's autonomy surface + proof; batch any ASK to the end. If the policy does not settle it, apply the rule above and proceed — never block on it. model-policy: per-stage: every subagent this skill launches pins its own model and effort rather than inheriting the run's.

This is the loop's instance of the shared autonomy canon — full decision rule, the commit-is-not-gated policy, and the arbiter policy 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.