Goal Engineering — a compass on a map labeled Define, Plan, Align, Iterate

Grok Build /goal · update_goal · G0→G3 · 6 patterns · goal-audit CLI

Loops discover work. Goals finish it. Companion: Loop Engineering (v1.6.0) · Stack cookbook

· llms.txt

Run until
verifiably done

Goal engineering replaces one-shot prompts with persistent objectives. Grok Build works across turns until the condition holds — and reports progress without flooding your chat.

Golden Path → Read the Essay API Reference Loop Engineering

Try: npx @cobusgreyling/goal-audit . --suggest    /goal All tests pass — goal-verifier before done

"A goal is a bounded objective with a verifiable completion condition — not an open-ended chat, not a cron job."
— Goal Engineering
"Loops discover work. Goals finish it."
— Loop Engineering companion
"The implementer must never grade its own homework."
— Maker / checker split

Grok Build CLI

The /goal API

Slash command for humans. update_goal tool for the agent.

grok build — goal mode
/goal Migrate auth to v2. Done when tests pass and no legacy imports.
/goal status
/goal pause
/goal resume
/goal clear

# Agent telemetry (not chat spam)
update_goal(message: "12/18 auth tests passing")
update_goal(completed: true, message: "Verifier PASS — migration done")
update_goal(blocked_reason: "Need sandbox OAuth credentials")

Full API reference → · Goal vs Loop →

Anatomy

What one goal looks like

Set the objective once. Grok persists until done, blocked, or cleared.

🎯 /goal → 📋 GOAL.md → ⚙️ Implementer → ✓ Verifier → 📡 update_goal → ✅ Done

Building blocks

Four primitives

Every reliable goal run needs these four capabilities.

🎯

Objective

One sentence + done condition

✓

Verifier

Independent completion check

📋

State

GOAL.md survives compaction

🛡

Budget

Turn caps + kill switches

Grok Build /goal Claude /goal Codex /goal

Copy & run

Production patterns

Each pattern includes an example /goal line, verifier strategy, and GOAL.md fields.

Start here

Tests Green

CI red → green with verifier gates. The most common first goal.

Read pattern →
Migration

Migrate Module

API migration with import scan + test lock.

Read pattern →

Implement Feature

Scoped feature with acceptance criteria checklist.

Read pattern →

Fix Bug

Repro → fix → regression test. Handoff from loop triage.

Read pattern →

Refactor Safely

Behavior-preserving refactor with full test lock.

Read pattern →
6
Patterns
G0→G3
Readiness
3
Skills
100
Audit max

2 minutes

Get started

terminal — minimal goal
git clone https://github.com/cobusgreyling/goal-engineering.git
cd your-project
cp -r goal-engineering/starters/minimal-goal/.grok/skills/goal-verifier .grok/skills/
cp goal-engineering/starters/minimal-goal/GOAL.md.example GOAL.md

npx @cobusgreyling/goal-audit . --suggest

# In Grok Build
/goal Read GOAL.md. Work the objective. goal-verifier before completed: true.

Play with it

Pattern Picker & Readiness Simulator

What are you trying to finish?

CI / tests red
Module / API migration
Ship a scoped feature
Fix a specific bug
Safe refactor
Raise test coverage

Goal Readiness Simulator (mirrors goal-audit)

0
/ 100
G0 — Ad hoc — add GOAL.md + verifier

The go-to for Grok Build /goal

Link here when you teach, blog, or ship goal-driven agent workflows.

Star on GitHub Contribute