Skip to content
Skills Library
AI & agents · Automation

loop

/loop

Bounded foreground repetition for the current session. Creates a loop contract, runs or coordinates an action plus verifier up to a declared attempt limit, and records evidence under .planning/loops/. Use for repeat-until-pass work that is too small for daemon and not time-based scheduling.

Repository
Citadel ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Bounded foreground repetition for the current session. Creates a loop contract, runs or coordinates an action plus verifier up to a declared attempt limit, and records evidence under .planning/loops/. Use for repeat-until-pass work that is too small for daemon and not time-based scheduling.

Original author description

Bounded foreground repetition for the current session. Creates a loop contract, runs or coordinates an action plus verifier up to a declared attempt limit, and records evidence under .planning/loops/. Use for repeat-until-pass work that is too small for daemon and not time-based scheduling.

How it works

  1. Orientation
  2. Commands
  3. Protocol
  4. Fringe Cases
  5. Contextual Gates
  6. Quality Gates
  7. Exit Protocol
Original SKILL.md headings · 170 lines, 802 words
SKILL.md preview
---
name: loop
license: MIT
description: >-
  Bounded foreground repetition for the current session. Creates a loop
  contract, runs or coordinates an action plus verifier up to a declared attempt
  limit, and records evidence under .planning/loops/. Use for repeat-until-pass
  work that is too small for daemon and not time-based scheduling.
user-invocable: true
auto-trigger: false
trigger_keywords:
  - loop
  - repeat until
  - until tests pass
  - until lint passes
  - max attempts
  - retry until
last-updated: 2026-06-09
---

# /loop -- Bounded Foreground Loop

## Orientation

**Use when:** the user wants a visible repeat-until-pass cycle inside the
current session, such as "loop until lint passes" or "try this up to three
times and stop if tests still fail."

**Don't use when:** the work should run unattended across sessions (`/daemon`),
on a clock (`/schedule`), on file changes (`/watch`), or as a metric-driven
optimization experiment (`/experiment`).

## Commands

| Command | Behavior |
|---|---|
| `/loop status` | Show all known Citadel loops with active/stopped grouping. |
| `/loop inspect {id}` | Show one loop's contract, verifier, budget, runs, and stop reason. |
| `/loop templates` | List built-in loop templates. |
| `/loop plan --template {name}` | Create a loop contract from a template. |
| `/loop run "{action}" --verify "{command}" --max {N}` | Run a bounded foreground loop. |
| `/loop stop {id}` | Mark a loop stopped. |

## Protocol

### Step 1: Classify the loop

Determine which kind of loop the user requested:

| User intent | Route |
|---|---|
| Repeat within this active session | `/loop` |
| Continue campaign across sessions | `/daemon` |
| Run on a schedule | `/schedule` |
| Watch PR checks/reviews | `/pr-watch` |
| Watch files or marker comments | `/watch` |
| Optimize a numeric metric | `/experiment` |

If another route is clearly better, say so and route there.

### Step 2: Require a verifier

A `/loop run` must have an explicit verifier. Explicit means the user supplied
`--verify "<command>"` or an equally concrete verifier command in plain language.
Do not infer a verifier from words like "lint", "test", "until it works", or
"fix until passing." If the verifier is missing, ask for it before executing and
do not run `loop-runner.js`, shell commands, or manual repair steps.

Accept examples like:

```text
--verify "npm run lint"
--verify "npm run test"
--verify "node scripts/operating-proof.js --write"
```

If missing, respond in this shape:

```text
/loop needs an explicit verifier before it can run. Please provide one, for example:
--verify "npm run lint"

I will not run the loop until the verifier is explicit.
```

### Step 3: Create the contract

For status, inspect, templates, and stop commands, run:

```bash
node .citadel/scripts/loops.js <command>
```

For template planning:

```bash
node .citadel/scripts/loops.js plan --template <name> --write
```

For foreground execution:

```bash
node .citadel/scripts/loop-runner.js --action "<action>" --verify "<verifier>" --max-attempts <N> --write
```

If `.citadel/scripts/` is not present and this is the Citadel harness repo
itself, use `node scripts/loops.js` or `node scripts/loop-runner.js` instead.

The runner writes a contract under `.planning/loops/{id}.json`, appends each
attempt, and stops with a shared stop status.

### Step 4: Stop on the first terminal condition

Stop when any of these are true:

- verifier passes
- attempt limit is reached
- the action fails in a way that needs human review
- the requested action would cross a safety or approval boundary
- the user asks to stop

Never silently continue beyond the declared attempt limit.

### Step 5: Report the outcome

Summarize:

- loop id
- status
- attempts used
- verifier
- runner command, including `--verify` and `--max-attempts`
- state path
- next action if stopped before success

## Fringe Cases

**If `.planning/` does not exist:** create `.planning/loops/` before writing
loop state. If writing fails, output the contract inline and tell the user
setup is needed.

**No verifier:** ask for one. Do not infer a destructive or expensive verifier.

**Action is an agent command, not a shell command:** run the action manually as
the agent for each attempt, then record the loop with `node scripts/loops.js
register` or use the loop contract as the state artifact. Do not pass slash
commands to the shell runner.

**Verifier keeps failing with the same cause:** stop at the attempt limit and
report `attempt-limit` with the latest evidence.

**User asks for unattended looping:** route to `/daemon` or `/schedule`, not
`/loop`.

## Contextual Gates

**Disclosure:** "Running foreground loop: action `{action}`, verifier
`{verifier}`, max attempts `{N}`."

**Reversibility:** amber -- the loop may run user-provided shell commands and
modify files; inspect the diff or loop-owned artifacts to revert.

**Trust gates:**
- Any: require verifier and attempt cap.
- Familiar: may execute shell action/verifier after disclosing the contract.
- Risky commands: require normal tool approval boundaries before running.

## Quality Gates

- A loop contract exists under `.planning/loops/` unless the filesystem blocks it.
- The verifier is explicit.
- The attempt limit is explicit and >= 1.
- The final status uses the shared loop vocabulary from `docs/LOOP_CONTRACT.md`.
- The final answer includes the loop id and state path.

## Exit Protocol

```
---HANDOFF---
- Loop: {id}
- Status: {status}
- Attempts: {used}/{max}
- Verifier: {command}
- Runner: node .citadel/scripts/loop-runner.js --action "{action}" --verify "{command}" --max-attempts {max} --write
- State: .planning/loops/{id}.json
- Next: {next action or "none"}
---
```
Files in this package (3)
  • SKILL.md 6 KB
  • __benchmarks__/foreground-verify.md 1 KB
  • __benchmarks__/missing-verifier.md 1 KB

Versions

RepositoryScoreLicence
This page · SethGammon/Citadel100MIT
mickeyyaya/evolve-loop100Apache-2.0
relai-ai/agent-eval-loop100Apache-2.0
alirezarezvani/claude-skills100MIT
x-cmd/x-cmd100Apache-2.0
in-the-loop-labs/pair-review100Apache-2.0
railly/skills100MIT
slogsdon/loop-and-gate-foundation100MIT
Mineru98/skills-store100MIT

Database snapshot: 13.11.2026 · package version cb6fce270566 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90goal-loop
    Run a task as a goal loop. Write a contract (goals, exit criteria, checks, budget), work, verify with an independent agent, repeat on FAIL until PASS or budget. Use for "goal loop", "verify until done", or exit criteria plus a verifier.
  • 86loop-tick
    Run one tick of a loop from docs/loops/<name>.yaml. Use when a schedule, the night tick or the human asks to advance a loop.
  • 100iloop
    In-session iterative loop — keeps Claude running in the current session until a task is done. Unlike /loop (which spawns background workers), /iloop stays in the current session and re-prompts each iteration via Stop hook. Use for: 'keep fixing until tests pass', 'iterate until…
  • 96generate-agentic-loop
    Design or implement bounded, self-correcting agent execution loops with verification, resource limits, and recoverable state. Use when a user asks to build or improve an agent loop or its execution harness.
  • 100loopy
    Discover, find, compare, audit, repair, adapt, craft, run, debrief, save, and prepare repeatable AI-agent loops for publication. Use when a user asks to analyze code or coding threads for recurring work, find a published loop, interview them to turn a goal into a bounded loop,…
  • 90cmd-session-commit
    Capture learnings from the current coding session and update AGENTS.md. Use when the user asks to close the loop, run session-commit, record best practices, or update agent instructions based on recent work.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.