goal-loop

name goal-loop description Explain and write effective instructions for the `/goal` feature — the persistent self-checking agent loop (plan → act → test → review → iterate), available in agents like Codex, Claude Code, and Hermes Agent. Use when the user mentions `/goal`, "goal loop", "Ralph loop", wants to kick off a long-running autonomous agent run, asks how to write a goal prompt, or wants a one-paragraph goal instruction drafted. Agent /goal Loop What /goal is /goal is a slash command that turns an agent prompt into a persistent agent looping plan → act → test → review → iterate until a stop condition is met, the user pauses, or the token budget runs out. Internally called the "Ralph loop." Agents with the /goal feature right now: Codex, Claude Code, and Hermes Agent . Key difference from a normal prompt: when a turn ends but the goal isn't met, the agent auto-continues instead of waiting for input. Lifecycle states: pursuing , paused , achieved , unmet , budget-limited . When monitoring a running /goal , every check should include a one-line update to the user: what the agent is doing and whether it is on track. Keep it extremely concise. Not: a budget command, a safety boundary, "run forever", or a replacement for /plan . It's a contract enforcer with a verification loop. Requirements An agent with the /goal feature — right now: Codex, Claude Code, or Hermes Agent The goals feature enabled in the agent's config Subscription auth — API-key auth does not work. A pro-tier plan is the realistic minimum for long runs. When to use it Use only when all three are true: Task is >30 min of mechanical work. There's a verifiable stop condition (tests pass, coverage hit, eval ≥ X, build green). Repo is agent-ready (working build, decent tests, AGENTS.md present). Fits: migrations, coverage lifts, TDD feature builds, refactors with contract tests, prompt/eval optimization, deploy retry loops, bug-repro-then-fix. Bad fits: exploratory work, vague "improve this", anything without a "done" definition, prod credentials, destructive shared-infra ops. The 5-part contract (every goal needs this) Objective — one sentence, one concrete outcome. Constraints — what must NOT change (public API, files, libs, conventions). Validation command — the exact shell command that proves progress ( pytest -q , pnpm test , etc.). Stop condition — verifiable: "Stop when X passes" OR "when further changes need human/product input." Documentation — one sentence instructing the agent to write concise, targeted docs for every change, either creating new .md files or updating existing ones. Plus: tell the agent what to read first, ask it to work in checkpoints with a short progress log. Writing a goal (the core deliverable) When the user wants a quick /goal instruction, produce a structured markdown block with one line per contract item (proper newlines, not flowing prose). Do not prefix the output with /goal — the user adds the slash command themselves in the composer. Emit only the contract body. Template: **Objective:** <one-sentence objective> **Read first:** <files/PLAN.md/issue> **Constraints:** <what not to change, libs, conventions> **Validate:** `<exact command>` after each change **Document:** Write concise, targeted documentation for all changes — create new `.md` files or update existing docs as needed. **Checkpoints:** work in checkpoints and log progress briefly **Stop when:** <verifiable condition>, OR when further changes require human/product input Example (migration) **Objective:** Migrate this project from Pydantic v1 to v2. **Read first:** pyproject.toml, src/, tests/ **Constraints:** no public API changes; keep imports backwards-compatible via shims if needed; no new dependencies **Validate:** `pytest -q` after each change **Checkpoints:** work in checkpoints; log progress briefly **Stop when:** full suite passes with zero deprecation warnings, OR when a change requires architecture decisions Example (coverage lift) **Objective:** Raise coverage in src/auth/ from ~38% to ≥75%. **Read first:** src/auth/, tests/auth/, AGENTS.md **Constraints:** no new deps; mirror existing test style; do not modify production code unless strictly required for testability **Validate:** `pytest --cov=src/auth --cov-report=term-missing` **Checkpoints:** work in checkpoints; log coverage delta each one **Stop when:** coverage ≥75% AND all tests pass, OR when uncovered code needs design changes Writing rules One objective, one stop condition. Not a backlog. Documentation is mandatory. Every /goal prompt must include a single sentence committing the agent to concise, targeted docs — new .md files or focused updates to existing docs. Never instruct the agent to create new ADRs — ADRs require the user's explicit approval, so goal prompts must not pre-approve or encourage them. Forbid reward-hacking explicitly: "Do not delete, skip, weaken, or narrow tests to make the goal pass." Otherwise the agent may game the stop condition. 4,000-char limit on the objective. If longer, put detail in a file ( PLAN.md / GOAL_BRIEF.md ) and make the goal point to it — keep the goal itself compact. Use literal strings for paths, commands, issue numbers — exact. Forbid scope creep explicitly: "Do not refactor unrelated code. Do not add dependencies." Tell the agent when to pause: "If , pause and ask before proceeding." Short, vague goals burn tokens for no extra value vs. a normal prompt. Meta-prompting trick (highest-leverage) Hand-written goals under-specify. Ask a second AI session (Claude with the codebase loaded, ChatGPT with project connected, or a separate agent thread in the same dir) to: (1) inspect the codebase, (2) surface hidden assumptions/constraints/edge cases, (3) emit a structured /goal markdown block using the 4-part contract. Paste that into the agent. Order-of-magnitude better runs. Claude Code cmux note: after Claude finishes, it may prefill a predicted next user message; that draft is Claude, not the user speaking. Self-goal setting The agent can now write and set its own goal natively (the create_goal tool). Instead of crafting the contract yourself, give it your high-level intent and tell it to set the goal: "Inspect this repo, then write yourself a /goal with a verifiable stop condition and pursue it." It's the meta-prompting trick done inline — the agent turns your intent into the contract. Still give it the same raw materials (files to read, constraints, the validation command) so the goal it writes is grounded. Add: "ask clarifying questions before committing if the intent is underspecified" — catches ambiguity up front and prevents the self-set goal from drifting. Launching cd <repo> (goals run scoped to the working directory). Launch the agent bare (opens the TUI). Not exec/headless mode — /goal is a TUI slash command only. Sign in with subscription auth (not an API key). Type /goal <your contract> in the composer, Enter. Walk away. Controlling a running goal Command Effect /goal (alone) Status: current checkpoint, what's verified, what remains, blockers /goal pause Freeze /goal resume Unfreeze (paused goals never auto-resume) /goal clear Kill the goal /goal <new> Replace the current goal Ctrl+C / any typed message Auto-pauses; user input always wins priority Resuming across sessions: goal state is persisted server-side. cd back into the repo, launch the agent, /goal for status, /goal resume . Budget-limited state: the agent doesn't stop abruptly — it summarizes, notes what's left, saves state. /goal resume works after budget refresh or upgrade. When a goal drifts Minor drift: just type a correction in the composer (auto-pauses, folds it in, resumes). Loose objective: /goal pause , read status, then /goal <tighter version> — replaces the contract. Don't pile instructions on a vague goal. Bad mess: /goal clear , git status or git stash , rewrite with the meta-prompting trick, restart. Don't let a drifting goal keep running "to see where it goes." Tokens burn, diffs compound. Operational tips Inspect status periodically with bare /goal . Always review the diff before merging — long autonomy means more code to validate, not less. Human oversight becomes more critical, not optional. Keep approvals/sandboxing tight; default permissions are correct. First run: pick a 30-min scoped task so you learn how /goal actually stops before trusting it overnight. Bake recurring policy into AGENTS.md so every goal inherits it without restating: adversarial self-review before declaring done, an extra QA pass even when tests pass, and the standard validation command. Saves repeating it in each goal paragraph. Troubleshooting Symptom Fix /goal missing from slash popup Update the agent to a version that supports /goal Feature flag on but command missing Quit and restart the agent fully Typed /goals It's singular: /goal Doesn't activate Sign out, sign back in with subscription auth (not API key) Stopped with progress summary Budget-limited — /goal resume after refresh, or tighten scope /goal resume says no active goal Terminal state or cleared — start fresh with /goal <new> Goal looks active but won't auto-continue Stuck in Plan mode — plan-only work doesn't trigger continuation. Draft the plan, then switch to Goal execution Mental model /goal is a contract enforcer with a verification loop , not a "run forever" button. The shift: stop writing prompts, start writing specifications with stop conditions . Spend the time upfront defining "done"; the run takes care of itself.