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.