Loop Goal

loop-goal

Discipline for running long tasks without losing progress or polluting context.

A long-running task — one that repeats, or one that runs until done — has three failure modes that quietly ruin it:

• Progress is lost when conversation context is compacted.
• Context is polluted by accumulated tool output across iterations.
• The loop never ends because no exit condition was written down.

This skill turns the three fixes into rules you MUST follow, instead of habits you might forget halfway through a long run.

Step 1 — Detect the mode

Decide LOOP or GOAL before anything else.

| Mode | Signals | End condition | |------|---------|---------------| | LOOP | time-driven, recurring — "every N…" / "每隔…", "keep monitoring" / "持续监控", an interval given, /loop | none intrinsic — you MUST write one | | GOAL | result-driven, run-until-done — "turn all tests green" / "把所有测试修绿", "until X" / "直到 X 为止" | a completion criterion already exists |

State the detected mode out loud, then proceed.

Step 2 — The checkpoint file

.loopgoal/state.json is the single recoverable source of truth. Git commits hold history. Copy the skeleton from templates/state.json.

{
  "mode": "goal",
  "objective": "one line — what this task achieves",
  "exit_condition": "the explicit, testable condition that ends the task",
  "status": "in_progress",
  "iteration": 0,
  "phases": [{"name": "...", "status": "todo"}],
  "current": {"focus": "...", "next_action": "...", "blockers": ""},
  "decisions": [],
  "verify_cmd": "command that checks the current state is real",
  "updated_at": "2026-05-17T15:00:00"
}

decisions[] is not optional bookkeeping — it is the field context compaction is most likely to silently drop. Record tradeoffs there as you make them.

The six rules

Follow all six. They are rigid — do not adapt them away.

• R1 — Init. Before starting, create .loopgoal/state.json from the

template and write exit_condition explicitly. If you cannot state the exit condition, stop and ask the user — a loop without one never ends.

• R2 — Context isolation. Run each unit of work — a LOOP iteration

or a GOAL phase — in a fresh subagent via the Agent tool. The subagent reads the checkpoint, advances one step, writes the checkpoint, and returns a one-line summary. This is equivalent to clearing context every iteration: the main session stays a thin coordinator and never accumulates.

• Exception: if a single iteration is genuinely lightweight — no

file reads, no long command output (e.g. one curl for a status code) — run it in the main session directly. Subagent overhead is not worth it for trivial work.

• R3 — Checkpoint order. At every safe point, in this exact order:

1. write .loopgoal/state.json
2. git commit
3. then continue, or schedule the next iteration

Never reorder. The file must be current before the commit, and both before you move on — so a context loss right after still recovers.

• R4 — Resume. At the start of every iteration/step: read

.loopgoal/state.json, run verify_cmd, and reconcile it against reality. The file is "what I last believed", not fact. If they disagree, reality wins — fix the file first, then proceed.

• R5 — Decision log. The moment you make a meaningful tradeoff,

append it to decisions[] with its reason. Do not rely on conversation memory to carry decisions across iterations.

• R6 — Exit. When exit_condition is met: set status to done,

write the file, commit, and stop scheduling. If you hit a blocker you cannot resolve: set status to blocked, record it in current.blockers, and stop to ask the user. Never spin silently.

LOOP-specific

• A safe point is each iteration. Iterations must be idempotent:

read file → advance one step → write file. Never depend on "I remember what I did last round."

• A fixed-interval loop (cron / /loop 5m) does not stop itself.

Its exit_condition MUST also be written into the loop prompt, or it runs forever.

• A dynamic loop (ScheduleWakeup, self-paced) ends naturally: when

exit_condition is met, simply do not schedule the next wakeup.

GOAL-specific

• A goal has no natural boundary. You MUST carve safe points

manually: after each completed sub-goal, and before any irreversible operation (bulk writes, long jobs, commits to shared branches).

• verify_cmd is mandatory — a goal is defined by a checkable end

state, so there must be a command that checks it.

• Break the goal into phases[] up front. Each phase is one R2 unit of

work.

Optional companions

These improve results but are NOT required — this skill is fully self-contained:

• superpowers:subagent-driven-development — a heavier per-task

subagent + review workflow, compatible with R2.

• /loop, /schedule — harness mechanisms for actually scheduling the

iterations this skill disciplines.

Source & license

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

• Author: lgqyhm2010
• Source: lgqyhm2010/loop-goal
• License: MIT

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