---
name: run-goal
description: Use when a goal is already approved and must be carried to a verified finish — freeze an outcome plan, judge completion from evidence, and stop when the same gap repeats. Use when an agent would otherwise declare the goal done, rewrite the objective, raise the bar between rounds, or keep going after the same failure.
---

# Run a goal (run-goal)

Carry an already approved goal to a verified finish. `write-goal` settles the objective with the user. This skill starts after that wording is approved. It does not rewrite the objective, and it does not implement host controls.

Token budgets, pause, resume, and clear belong to the host harness. Do not add them here, do not invent a turn cap, and do not tell the user to pause from this skill. If the host already runs an equivalent loop, follow the host and do not duplicate it.

## Roles

Keep these contexts separate. One context does not grade its own work.

| Role | May | May not |
| --- | --- | --- |
| Planner | Read the workspace. Write the plan file once. | Edit product code. Restate the objective as new requirements. |
| Implementer | Change the assigned scope. Produce the evidence the plan names. | Edit acceptance criteria. Mark the plan's checks as passed. Declare the goal complete. |
| Verifier | Read the workspace and the saved evidence. Write a verdict. | Edit product code. Generate the missing evidence. Raise the bar above the frozen plan. |
| Strategist | After repeated non-convergence, name one structural change. | Hand back a longer todo list. Start a second goal. |

The fixer, when findings need a code change, is a separate context from both the implementer and the verifier. Use `adversarial-loops` for that review shape. Two verifiers are the default when the goal can change behavior; one verifier is enough for a read-only research or analysis goal.

## Freeze the plan

The planner writes one plan file and then stops. The objective text stays verbatim. The plan is the only place criteria live.

Sections, in order:

1. **Goal kind** — exactly one of `code-change`, `analysis`, `research`.
2. **Acceptance criteria** — the gating set. Small on purpose. A criterion that does not fit is grouped with a related one or listed under non-goals. Never dropped in silence.
3. **Verification plan** — the procedure both the implementer and the verifier follow. Tag each step `gating` or `evidence`.
4. **Non-goals** — at least one item a reader might otherwise assume is in scope.
5. **Assumed scope** — files, modules, and dependencies the work is expected to touch.
6. **Implementation approach** — `code-change` only. How to keep the change testable. Guidance, not a criterion.
7. **Task checklist** — `code-change` only. Three to eight ordered unchecked boxes. The first unchecked box is the next step. Guidance, not a criterion.
8. **Risks** — only when the objective contradicts itself or the environment cannot produce the named proof. Omit otherwise.

Rules for what goes in the contract:

- State outcomes, not architecture. "The parse-then-normalize transform runs on representative inputs" is a criterion. "Add `parser.py` exporting `normalize(record, opts)`" is not. A verifier that can refute a correct implementation for diverging from a prescribed layout is grading the wrong thing.
- Keep named techniques, artifacts, and environments verbatim. Do not swap a named CI job, remote pipeline, or deployment for an easier local stand-in. If a named bar looks infeasible, keep it and record the conflict under risks.
- A criterion is independently checkable from near its own start. Do not write one holistic gate such as "drive the whole thing through to the end."
- Do not restate the implementation approach or the checklist as criteria.
- `gating` decides pass or fail. `evidence` corroborates. Missing evidence alone does not deny completion once every gating step holds.
- A gating criterion proven only in prose is not proven.

Show the frozen plan to the user once, as a record of what will be judged. Do not open a wording review of the objective. If the user rejects a criterion, the planner revises the plan. The objective text still does not change.

## Execute against the plan

The implementer works the checklist in order and checks a box only after the step's observation holds. Deviations go in one `## Deviations` section, one bullet each, what changed and why. Do not edit existing criteria to match the deviation.

Before handing work to a verifier, the implementer runs the verification plan and saves the proof:

- In-repo tests that drive the shipped code on the real path. No hardcoded expected output, no mock of the unit under test, no re-implementation that the test asserts against.
- Captured command output in a per-goal scratch directory. Never a shared `/tmp` path. Never point `HOME`, package-manager homes, virtualenvs, or caches at scratch. Scratch is deleted when the goal ends. Anything that must outlive the goal is committed in the repo.
- For a visual or interactive deliverable, the proof is the artifact in source, unit tests of the pure logic, and a real launch where the environment can launch it. If the launcher itself fails, save that failure output and fall back to the static and unit checks. Say so in the evidence. A successful readback that returns a blank or partial buffer is the deliverable's output, not an environment failure. Hand-built stand-ins for a launch are not evidence.

## Judge completion

Completion is a verdict, not a sentence the implementer writes. "Done", "stopping here", "I'll check back later", "ready for review", and a self-written `VERDICT: PASS` are not completion. Ignore them and run the verifier.

The verifier is read-only toward the workspace. It reads the plan, the diff, and the saved evidence. It does not create the missing test, rerun the expensive suite to fill a hole, or rewrite the plan. If the evidence is missing, ambiguous, or does not show the observation the plan names, the verdict is not-complete, with the specific gap and where it is.

Verdict fields:

- **result** — `complete` or `not-complete`.
- **gaps** — each unmet gating criterion, with location and one concrete line. Empty only when the result is `complete`.
- **blocking** — `none` when the implementer can fix it, `contradiction` when the objective or plan precludes itself, `unverifiable` when this environment cannot produce the named proof.
- **evidence** — one line citing the saved proof. The implementer's closing prose is not a citation.

`complete` requires every gating criterion to hold and no regression of a criterion that already held. Otherwise `not-complete`.

The bar does not rise between rounds. A gap that was not in the frozen plan is not a gap, unless it is a regression of a criterion that already passed or a cheat. Cheats are always gaps: hardcoded expected output, a test that special-cases its own input, a swallowed error, a deleted or disabled assertion, a stub left behind a TODO, or a narrowed scope that dodges a named requirement.

`blocking: contradiction` or `blocking: unverifiable` stops the loop. Report the conflict and the evidence to the user. Do not open another implementer round to argue with it.

## Stop when it is not converging

Compare each verifier gap set with the previous one.

- The same gaps as the previous round means no progress. Stop and report those gaps. Do not spend another round on them.
- A different gap every round, with no criterion staying fixed, is whack-a-mole. Hand the run to the strategist. The strategist recommends one structural change to the plan or the workflow, not a longer checklist. The implementer applies that one change. If the next round still fails to converge, stop and report.
- A hard external blocker — missing credentials, a down service, a denied permission — is reported on the round it is confirmed, not after a private retry budget.

There is no token budget and no pause command in this skill. Stopping means reporting the remaining gaps, the evidence, and the decision the user has to make. The host decides whether the run is paused, resumed, or cleared.

## What this skill does not do

- It does not draft or tighten the objective. That is `write-goal`.
- It does not set a token budget, a turn cap, or a pause/resume/clear control.
- It does not replace `run-long-task` for a multi-day migration or bulk backlog. Use that skill for work-unit gates, pilots, and shared decision records. Use this skill for the plan, the verdict, and the stop rule inside one goal.
- It does not let the verifier become a second implementer.

## Common mistakes

| Mistake | Better |
| --- | --- |
| Rewriting the objective to make it "more verifiable" | Leave the objective verbatim. Put the check in the plan. |
| Freezing file names, function signatures, or a prescribed layout as criteria | State the observable outcome. Keep layout in the implementation approach. |
| One end-to-end gate for the whole deliverable | Split into criteria that can be checked from their own start. |
| Treating the checklist as the contract | The checklist is the next-step nudge. Criteria are the contract. |
| Accepting "done" or "stopping here" as completion | Run the verifier. Prose is not a verdict. |
| Verifier writes the missing test so the round can pass | Refute and name the missing evidence. The implementer produces it. |
| Adding a new criterion because the last round passed too easily | The frozen plan is the bar. A rising bar is a failed goal, not a stricter one. |
| Retrying after the same gaps come back | Stop and report. Same gaps are no progress. |
| Swapping a named CI or deployment check for a local substitute | Keep the named environment. Record the conflict under risks if it cannot be reached. |
| Saving proof under shared `/tmp`, or pointing `HOME` at scratch | Use the per-goal scratch directory. Commit anything that must survive. |