| name | loop-goal-engineering |
| description | This skill should be used when the user wants to author agentic loops or goal/completion conditions — "write a loop prompt", "loop engineering", "set up a ralph loop", "run Claude overnight", "write a /goal condition", "goal mode", "goal engineering", "stop condition for my agent", "completion criteria", "definition of done for the agent", "long-horizon task setup", "keep the agent working until", "make Codex run until tests pass", "PLANS.md", "harness for a long run", "my agent stops too early", "my agent never finishes", or wants Claude Code /loop, /goal, Stop hooks, or Codex Goal Mode set up well. Covers loop prompt authoring, goal condition design, the four-file long-horizon scaffold, and anti-reward-hacking hardening. For ordinary single-shot prompts, use prompt-engineering instead.
|
Loop & Goal Engineering
Author the artifacts that drive autonomous agent runs: loop prompts (re-run
cold each iteration until a backlog is done), goal conditions (machine- or
evaluator-checkable completion criteria), and the long-horizon file scaffold
that carries state between iterations.
The runtime primitives exist — Claude Code /goal and /loop, Stop hooks,
Codex Goal Mode, bash while-loops. They all assume the human can already write
a good loop prompt or goal condition. That authoring step is this skill's job.
Step 1 — Classify the Deliverable
| User wants | Deliverable | Primary reference |
|---|
| Agent grinds through a backlog / overnight run | Loop prompt (+ scaffold files) | references/loop-patterns.md |
| Agent keeps working until X is true | Goal condition | references/goal-specs.md |
| Multi-hour/multi-day autonomous project | Four-file scaffold + loop prompt + goal | both |
| A check that must gate with zero exceptions | Stop-hook script spec | goal-specs.md §2 |
If the request is really a one-shot prompt with no iteration ("write a prompt
that refactors this file"), hand off to the prompt-engineering skill.
Step 2 — Pick the Harness
Use the harness selection table in references/loop-patterns.md §1. Ask at
most one question if the target runtime is ambiguous (Claude Code vs Codex vs
raw bash loop) — it changes the output format:
- Claude Code
/goal → condition must be provable from the agent's own
transcript output (the evaluator runs no commands itself)
- Codex Goal Mode → Goal / Context / Constraints / Done-when skeleton
- Stop hook → the condition becomes a script with exit codes
- Bash/Ralph loop → full loop prompt + four-file scaffold + safety rails
Step 3 — Draft
Loop prompts: apply the ten rules in loop-patterns.md §2 — one task per
iteration, state in files/git, search-before-assuming, no placeholders,
in-iteration verification, protected tests, idempotency, per-iteration commits,
bounds, one-deliverable scope. Start from the template in §4.
Goal conditions: apply the four-part anatomy in goal-specs.md §1 —
measurable end state, stated proof check, constraints, bound. Use the
skeletons in §2 and the vague-goal rewrite table in §4.
Scaffolds: generate the four files (spec / plan / runbook / status log)
per loop-patterns.md §3, with per-milestone validation commands in the plan.
Step 4 — Lint (mechanism before judgment)
Run the deterministic checker on every drafted goal condition or loop prompt
before delivering it:
PY=$(command -v python3 || command -v python)
"$PY" "${CLAUDE_PLUGIN_ROOT}/scripts/check-goal.py" <draft-file> --json
The script flags: missing named command, vague success adjectives, missing
scope guard, missing bound, and seven of the eight gameability signatures
(G1-G7 in goal-specs.md §3). Fix CRITICAL and WARNING findings, then re-run.
The script exits 1 when findings exist — that's signal, not failure.
Then apply judgment the script can't: G8 (revert-satisfiability — could the
agent pass by reverting to the original state?), whether the check is
semantically sufficient (a passing test suite that doesn't cover the feature
proves nothing), whether the goal is satisfiable at all, and whether two
experts would agree on pass/fail.
Step 5 — Deliver
Same contract as prompt-engineering: a paste-ready block (or file set), one
line stating the target harness and what was optimized, and setup notes only
when genuinely needed (e.g., "save as PLAN.md in repo root", "requires a
Stop hook registered in settings.json").
For loop deliverables, ALWAYS include the safety footer when the run is
unattended: sandbox/worktree advice, credential scope, blast-radius
constraints (loop-patterns.md §5). Never deliver an unbounded loop.
Hard Rules
- NEVER deliver a goal condition without a named command/check, a scope
guard, and a bound. "Tests pass" alone is a documented failure mode.
- NEVER deliver a loop prompt that allows multiple tasks per iteration.
- NEVER let the condition's own success criteria be editable by the agent
(tests, scoring scripts) without an explicit protection constraint.
- NEVER present "goal engineering" as established vocabulary in delivered
artifacts — the vendors' terms are Goal Mode,
/goal conditions, and
"Done when" criteria. (Using the phrase conversationally is fine.)
- For Claude Code
/goal: ALWAYS instruct the agent to show evidence
(command output) in its transcript — the evaluator cannot run commands.
Reference Files
| File | Read when |
|---|
references/loop-patterns.md | Authoring loop prompts, choosing a harness, building the four-file scaffold, unattended-run safety |
references/goal-specs.md | Authoring goal conditions, hardening against reward hacking, vague-goal rewrites |
Related: prompt-engineering skill (single-shot prompts, system prompts,
CLAUDE.md/AGENTS.md), prompt-debugger agent (F8 category diagnoses loop and
goal failures in prompts that already misbehaved).
