loop

name	loop
description	Use when the user asks to loop a workflow, keep doing something until a condition changes, create or use a loops/<loop-name>/LOOP.md definition, or maintain loop state and records across repeated iterations.

Loop Skill

This skill operates the Markdown Loop Protocol. A loop tells the agent how to keep doing a workflow until a condition changes, while tracking state and recording what changed over time.

Operating Principle

A loop has two separate phases:

definition phase
  Create, find, read, or revise LOOP.md.
  Do not create runtime state yet.

activation phase
  After user confirmation, create or resume state.md and record.md.
  Then execute at most one bounded iteration unless the user explicitly asks
  otherwise.

Creating LOOP.md does not start the loop.

A loop is active only after the user confirms:

the loop goal
the trigger or continue condition
the stop condition
the allowed actions
when the agent must ask the user
what state will be tracked
what each iteration will record

If any of these are unclear, ask the user before creating state.md or record.md.

File Responsibilities

A loop package lives at:

loops/<loop-name>/
  LOOP.md
  state.md
  record.md

Each file has a different purpose.

LOOP.md

LOOP.md defines the loop.

It is the exposed loop contract. It should be stable, reviewable, and safe to commit.

It answers:

What is this loop for?
What workflow is this loop for?
When should it continue?
When should it stop?
What actions are allowed?
When must the agent ask the user?
What state must be tracked?
What must be recorded after each iteration?

Do not edit LOOP.md during normal loop execution. If the loop definition needs to change, pause and ask the user.

state.md

state.md stores the current runtime state.

It is local, mutable, and should be gitignored unless the user explicitly wants runtime state committed.

It answers:

Is the loop running, waiting, paused, completed, or stopped?
What is the current focus?
What is the next action?
What blockers exist?
Which continue conditions are currently true?
Which stop conditions are currently true?
What was the last direction check?
What human review is pending?

Update state.md after activation and after each iteration.

record.md

record.md is the append-only runtime history.

It is local, append-only, and should be gitignored unless the user explicitly wants runtime history committed.

record.md is not a universal log format.

Each LOOP.md must define the smallest record shape that preserves what the next iteration needs to know.

Use common activation entries if helpful, but iteration entries should be loop-specific.

It usually answers:

When was the loop activated?
Why did the previous iteration start?
What key signal did the agent see?
What decision or action changed the loop state?
What result matters for the next iteration?
How should the next iteration decide whether to continue, wait, pause, or stop?

Append to record.md after activation and after each iteration.

If the loop paused for a human decision, record the question and the decision.

Do not rewrite previous entries except to fix formatting mistakes explicitly requested by the user.

Determine User Intent

When the user mentions a loop, first determine whether they are asking to:

define
  Create or edit LOOP.md only.

activate
  Start a loop from LOOP.md by creating or resuming state.md and record.md.

resume
  Continue an existing loop with existing state.md and record.md.

iterate
  Run one bounded iteration of an already-active loop. If the loop is paused,
  treat the request as resume.

inspect
  Explain the current loop definition, state, or record.

pause / stop
  Update state.md and append record.md without running another iteration.

If intent is ambiguous, ask.

Do not assume that a request to create a loop means the user wants to activate it immediately.

Find Or Create LOOP.md

When the user asks to loop a workflow:

1. Infer the loop name from the user's request.
2. If the name is ambiguous, ask the user.
3. Look for loops/<loop-name>/LOOP.md exactly.
   - The filename is case-sensitive and must be uppercase `LOOP.md`.
   - Do not search only for lowercase `loop.md`.
   - Do not draft a new loop until this exact uppercase path has been checked.
4. If loops/<loop-name>/LOOP.md exists, read it before proposing execution.
5. If it does not exist, look for the closest bundled example under:
   - skills/loop/examples/<example-name>/LOOP.md
   - skills/loop/examples/extra/<example-name>/LOOP.md
6. Draft a new loops/<loop-name>/LOOP.md from:
   - the user's request
   - the closest example
   - the recommended loop shape
7. Explain the drafted or existing loop using the confirmation shape below.
8. If the loop was newly drafted, ask whether to save it as a definition,
   revise it, activate it, or cancel.
9. Do not create state.md or record.md until activation is confirmed.

If a lowercase loop.md exists but uppercase LOOP.md is missing, pause and ask before renaming, replacing, or drafting a definition.

When creating a new LOOP.md, keep it specific enough to guide continuation, stopping, direction, state tracking, and recording.

Do not create an unbounded autonomous process.

Recommended LOOP.md Shape

Use this shape when creating or revising a loop definition:

# <Name> Loop

## Use For

What workflow is this loop for?

## Purpose

What is this loop trying to keep doing?

## Required Activation Details

Optional. What concrete target, command, artifact, scope, or limit must be
confirmed before activation?

## Direction

What must this loop stay focused on?
What must it avoid drifting into?

## Trigger

What starts the next iteration?

If this depends on time, events, files, reviews, tests, or an external runner,
say so here.

This skill does not create background schedulers. Scheduled or watch-style
loops require an external trigger such as cron, launchd, GitHub Actions, a
manual loop tick, or another approved runner.

Trigger says why this iteration is being considered. Continue When says whether
another iteration is allowed after the trigger.

## Iteration Pattern

Optional. What pattern should each iteration follow?

## Run Policy

Iteration unit:
  What counts as one iteration?

Default activation bound:
  How far should one activation run if the user does not specify otherwise?

Allowed activation bounds:
  What bounds are valid for this loop?

Optional:
  Auto-continue:
    When may the agent continue within the same activation?
  Stop-after-each:
    When should the agent stop after one unit even if continuation is possible?

## Continue When

What conditions allow another iteration?

## Stop When

What conditions require the loop to stop or complete?
Stop conditions override continue conditions.

## Allowed Actions

What may the agent do during one iteration?

## Ask Human When

What conditions require pausing and asking the user?

## State To Track

What variables must state.md preserve between iterations?

## Record Each Iteration

What is the smallest useful record shape for this loop?
What must the next iteration know to avoid repeating work, losing context, or
continuing when it should pause?

Confirmation Before Activation

Before creating state.md, creating record.md, resuming, or running an iteration, summarize the loop for the user.

Use this confirmation shape:

I found / drafted this loop:

Loop:
  <loop name>
Purpose:
  <one sentence>
Trigger:
  <what starts the next iteration>
It will continue when:
  - ...
It will stop when:
  - ...
It may do:
  - ...
It must ask you when:
  - ...
Run policy:
  Iteration unit: ...
  Default activation bound: ...
This activation will run:
  <one item / one gate / up to N items / until queue empty / until blocked>
Activation bound:
  <actual bound>
Stop overrides:
  <Stop When / Ask Human When summary>
It will track in state.md:
  - ...
It will append to record.md:
  - ...
First iteration, if activated:
  - ...

Please choose:
1. Activate and run according to this activation bound.
2. Activate but wait.
3. Create / update LOOP.md only.
4. Revise the loop definition.
5. Cancel.

Do not ask only "confirm?". The user must understand what activation will create and what the first iteration may do.

If the user chooses "create / update LOOP.md only", do not create state.md or record.md.

If the user chooses "revise the loop definition", return to the definition phase. Do not create state.md or record.md.

If the user chooses "activate but wait", create or resume runtime files and append an activation entry, then set Status: waiting without running an iteration.

If the user chooses "activate and run", create or resume runtime files, append an activation entry, and run only within the stated activation bound.

Activation Flow

When activating a loop:

1. Read LOOP.md.
2. Confirm behavior with the user using the confirmation shape above.
3. After confirmation, check gitignore rules.
4. Create state.md if missing.
5. Create record.md if missing.
6. Append an activation entry to record.md.
7. Update state.md.
8. Execute only within the stated activation bound if a trigger or continue
   condition is currently true. Otherwise set Status: waiting.

The agent must not skip confirmation merely because LOOP.md already exists.

Git Rules

Runtime artifacts should be gitignored unless the user explicitly wants them tracked:

/loops/*/state.md
/loops/*/record.md

Before creating state.md or record.md, check whether these paths are gitignored.

If they are not gitignored, tell the user:

This loop will create runtime files:
- loops/<loop-name>/state.md
- loops/<loop-name>/record.md

These usually should not be committed.
Would you like me to add them to .gitignore before activation?

If the user declines, continue only if they explicitly want runtime files to be tracked.

Default state.md Template

Create state.md with this shape when no state exists:

# Loop State

Status: running
Loop:
Current focus:
Next action:
Blockers:
Continue conditions currently true:
Stop conditions currently true:
Last human instruction:
Last direction check:
Pending human review:
Activation bound:
Activation bound progress:
Iteration count:
Updated at:

Allowed statuses:

running
  A bounded iteration may proceed.

waiting
  The loop is active but waiting for an external condition, event, or later tick.

paused
  The loop needs human review or clarification before continuing.

completed
  The loop purpose has been satisfied.

stopped
  The user or policy stopped the loop before completion.

If status is paused, completed, or stopped, do not continue automatically.

Default record.md Template

Create record.md with this shape when no record exists:

# Loop Record

This file is append-only.

Use the record shape defined by this loop's `LOOP.md`.

Each entry should be concise and should include only what the next iteration
needs to understand what happened, what changed, and whether the loop should
continue, pause, stop, or wait.

The activation section uses the standard shape below. Iteration entries should
use the loop-specific shape defined in `LOOP.md`.

## Activation

Loop:
Activated at:
Activated by:
Confirmation:
Initial summary:

If it did not stay within direction, pause the loop and ask the user.

Iteration Flow

For each activation or tick that reaches iteration evaluation:

1. Read LOOP.md.
2. Read state.md.
3. Read the most recent activation entry and recent iteration entries in
   record.md.
4. Check Stop When.
5. If Stop When is true:
   - append one no-action record entry explaining why no action was taken
   - update state.md to completed, stopped, or paused as appropriate
   - do not run checks, tests, edits, tools, or other iteration actions
   - return
6. Check Ask Human When.
7. If Ask Human When is true:
   - append one no-action record entry explaining why human review is needed
   - update state.md to paused
   - ask the user
   - return
8. Check Continue When.
9. If Continue When is false:
   - append one no-action record entry explaining why continuation is not allowed
   - update state.md to waiting, paused, completed, or stopped as appropriate
   - do not execute an iteration action
   - return
10. Check Direction.
11. Check Allowed Actions.
12. If uncertain, append one no-action record entry, update state.md to paused,
    and ask the user.
13. Execute one bounded action.
14. Append one loop-specific record entry.
15. Update state.md.

Stop or pause conditions beat continue conditions.

Before any iteration action, check Stop When and Ask Human When. Stop and pause gates override tests, checks, edits, verification, and all other work. Do not run a verifier, selected check, diagnostic, edit, or task action before honoring an already-true stop or pause condition.

No action is still an outcome. A loop that wakes up and decides not to act must record why.

Continue only when:

state.md status allows continuation
a Continue When condition is true
no Stop When condition is true
the next action is inside Allowed Actions
the next action does not violate Direction
Ask Human When does not require review

Record Timing

After activation, append an activation entry before any iteration action.

Every activation or tick that reaches iteration evaluation must append exactly one record entry before updating state.md, even if no action is taken.

Record a no-action entry when:

Stop When is already true
Ask Human When requires review before action
Continue When is false
the loop is blocked
the loop is waiting for an external trigger
the agent is uncertain and must pause

A no-action entry should say:

why this iteration was considered
whether action was taken
if no action was taken, why
what changed, if anything
whether the loop should wait, pause, stop, complete, or continue later

Do not append record entries for simple inspection, explanation, or definition phase work unless state changes.

Activation Bound

Every activation must be bounded.

The bound does not have to be numeric.

When activating or ticking a loop, read LOOP.md and follow its Run Policy.

If Run Policy is missing, use the safe fallback:

run at most one bounded iteration

A valid activation bound may be:

count-bounded:
  one item, N items, max 3 attempts
condition-bounded:
  until queue empty, until check passes, until delivery accepted
gate-bounded:
  one gate, until blocked, until human decision needed

Do not require a numeric max when the loop has a clear condition-bounded or gate-bounded completion rule.

Never continue without an activation bound.

Stop When and Ask Human When always override Run Policy.

Do not silently spin in a loop.

If the user asks to continue repeatedly in the current session, summarize after each iteration and continue only while:

the loop state is running
the activation bound has not been reached
continue conditions remain true
stop conditions remain false
no human gate is triggered

For scheduled or watch-style loops, do not create your own background scheduler.

A scheduled or watch-style loop should be triggered by:

the user
an external scheduler
an external script
a future loop runner

Pause, Resume, Stop

Pause when:

the next action may be outside Direction
the next action is not clearly allowed
the loop definition needs to change
new permissions are needed
the user needs to decide
the agent is uncertain

When pausing:

1. Append a no-action or pause record entry explaining why human review is needed.
2. Set Status: paused in state.md.
3. Write the blocker or pending question in state.md.
4. Ask the user for a decision.

Resume only after the user resolves the pending question or gives explicit permission.

Before resuming:

1. Record the user decision in record.md.
2. Update state.md.
3. Re-check Continue When and Stop When.

Stop when:

the user stops the loop
the purpose is complete
a Stop When condition is met
continuing would require scope expansion the user does not approve
the activation bound is reached

When stopped or completed:

1. Append a final record entry.
2. Update state.md.
3. Do not run another iteration.

Editing Rules

• Do not edit LOOP.md during normal iterations.
• If LOOP.md needs to change, pause and ask the user.
• state.md may be updated after each iteration.
• record.md must be appended after each activation and iteration.
• Keep entries concise but concrete.
• Prefer exact file paths, review IDs, command outcomes, and explicit user decisions when recording results.

State Update Rule

When updating state.md, replace existing field values. Do not append duplicate fields for the same key.

Bad:

Status: running
Status: waiting

Good:

Status: waiting

The state file should represent the current state, not a history log. History belongs in record.md.

Non-Goals

Do not introduce these unless the user explicitly asks:

run IDs
per-run directories
JSON or YAML schema
CLI tools
internal schedulers
event listeners
multi-loop orchestration
background execution
database state
record archiving or pruning

Do not truncate or delete record.md history unless the user explicitly provides a separate compaction or pruning rule.

The goal is to keep loop operation inspectable:

LOOP.md defines the workflow
state.md holds the current runtime state
record.md preserves what happened over time