Verifiable run-until-done objectives for Grok Build /goal. Patterns, a verifier, and the goal-audit CLI.
The canonical essay — why one-shot prompts fail and what goals fix.
Most agent sessions end when the model sounds done. Tests might fail. Migration might be half-finished. The chat moved on.
That gap — between “looks done” and actually done — is where agent productivity goes to die. You re-prompt. You re-explain context. You trust a summary you cannot verify.
Goal engineering closes the gap with four ideas:
GOAL.md) that survives compactionPrompt = one turn, one answer
Loop = recurring discovery on a cadence
Goal = run until done (or blocked / paused)
Prompts are fine for spikes. Loops are fine for triage. Goals are for finish.
Loop engineering discovers work; goals complete it.
Humans set intent:
/goal Migrate auth to v2. Done when tests pass and no legacy imports.
Agents report without spamming chat:
update_goal(message: "12/18 auth tests passing")
update_goal(completed: true, message: "Verifier PASS")
The objective persists across turns until completed, blocked, or cleared.
Not every repo should run unattended goals on day one.
| Level | Posture |
|---|---|
| G0 | Ad hoc prompts |
| G1 | Human approves milestones |
| G2 | Verifier gates completion |
| G3 | Unattended with budget + run log |
Measure yours:
npx @cobusgreyling/goal-audit . --suggest
Six production patterns cover most finish work: tests green, migrate module, implement feature, fix bug, refactor safely, coverage target.
Each ships an example /goal line, verifier strategy, and GOAL.md fields.
The most common failure is not bad code — it is a mega-goal. See mega-goal-failure. Split with goal-scoper before /goal.
| Layer | Question |
|---|---|
| Context engineering | What does the model see? |
| Harness engineering | How does one run execute safely? |
| Goal engineering | How do we run until verifiably done? |
| Loop engineering | What keeps work discovered? |
| Fleet engineering | How do many agents coordinate? |
npx @cobusgreyling/goal-init . --pattern tests-green --tool grok
npx @cobusgreyling/goal-audit . --suggest
Then in Grok Build:
/goal Read GOAL.md. Fix failing tests. goal-verifier before completed: true.
Walk through a full replay: golden path.
Goal engineering is replacing one-shot prompts with verifiable, run-until-done objectives. This repo is the canonical reference for Grok Build /goal — patterns, skills, CLIs, and honest stories.