Goal Engineering

June 30, 2026 · View on GitHub

Goal Engineering — Run until verifiably done

Goal engineering is replacing one-shot prompts with verifiable, run-until-done objectives. You define what "done" means, Grok Build works across turns until the condition holds — and reports progress via /goal and update_goal.

This is the canonical public reference for Grok Build CLI's /goal feature.

→ Interactive showcase + pattern picker
→ Canonical essay · → Golden path (10 min replay)
→ Companion: Loop Engineering (scheduled cadence) · Fleet Engineering (governed populations)

🔄 Loop Engineering v1.5.0 just shipped — loop-sync, loop-constraints, MCP server on npm.
Loops discover work on a cadence. Goals finish bounded tasks. Stack cookbook →

The One-Line Definition

A goal is a single autonomous objective with a verifiable completion condition. Unlike a loop (which fires on a schedule), a goal persists across turns until Grok marks it complete, blocked, or you pause it.

Prompt  = one turn, one answer
Loop    = recurring discovery + triage on a cadence
Goal    = run until done (or blocked / paused)

Quick Start (2 minutes)

# Unified CLI (recommended)
npx @cobusgreyling/goal doctor . --suggest
npx @cobusgreyling/goal init . --pattern tests-green --tool grok

# Or individual packages
npx @cobusgreyling/goal-audit . --suggest
npx @cobusgreyling/goal-init . --pattern tests-green --tool grok --lang python

In Grok Build:

/goal All tests pass — goal-verifier before completed: true

Manage the active goal:

/goal status    # check progress
/goal pause     # pause without clearing
/goal resume    # continue
/goal clear     # end goal mode

Replay a full session: examples/golden-path/SESSION.md

Why Goals Matter
Grok Build API
The Four Primitives
Patterns
Getting Started
Goal vs Loop
Operating & Safety
Tools
CI Integration
Contributing
License

Why Goals Matter

Most agent work fails in the gap between "looks done" and actually done. Goals close that gap:

Persistence — the objective survives compaction and new turns
Progress telemetry — update_goal logs status without spamming the chat
Explicit lifecycle — pause, resume, clear, blocked
Verifiable completion — you define the stop condition up front

Goals pair naturally with loop engineering: loops discover work; goals finish it. See docs/stack-cookbook.md.

Try the stack: morning loop triage → pick top item → /goal until verifier passes:

# Loop side (v1.5.0 — just released)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop-audit . --suggest

# Goal side (this repo)
npx @cobusgreyling/goal init . --pattern fix-bug --tool grok
npx @cobusgreyling/goal doctor . --suggest

Grok Build API

Surface	Purpose
`/goal <objective>`	Set a new autonomous goal
`/goal status`	Show current goal state
`/goal pause` / `resume`	Pause or continue
`/goal clear`	Exit goal mode
`update_goal` tool	Agent reports progress (`message`), completion (`completed: true`), or blockers (`blocked_reason`)

Full reference: docs/api-reference.md

Availability: /goal appears when the goal feature is enabled and update_goal is in the session toolset. No slash command? See examples/no-slash-command/GOAL-only.md.

The Four Primitives

Primitive	Job in a Goal
Objective	One sentence + verifiable done condition
Verifier	Separate check — implementer must not grade its own homework
State	`GOAL.md` or equivalent external memory
Budget	Token/turn caps and kill switches

Detail: docs/primitives.md · Cross-tool matrix: docs/primitives-matrix.md

Anatomy of a Goal

flowchart LR
    A["/goal &lt;objective&gt;"] --> B[Scope + done condition]
    B --> C[(GOAL.md state)]
    C --> D[Implementer turns]
    D --> E[Verifier sub-agent / tests]
    E --> F{Done?}
    F -->|yes| G["update_goal(completed: true)"]
    F -->|blocked| H["update_goal(blocked_reason)"]
    F -->|no| D
    G --> I[/goal clear or new goal/]

Patterns

Pattern	Starter	When to use
Tests Green	`starters/tests-green`	CI red → green with verifier gates
Migrate Module	`starters/migrate-module`	API/module migration + import scan
Implement Feature	`starters/implement-feature`	Scoped feature + acceptance criteria
Fix Bug	`starters/fix-bug`	Repro → fix → regression test
Refactor Safely	`starters/refactor-safely`	Behavior-preserving refactor
Coverage Target	`starters/coverage-target`	Raise coverage to threshold

Unsure? Pattern Picker · When not to use goals: docs/when-not-to-use-goals.md

Getting Started (5 minutes)

npx @cobusgreyling/goal init . --pattern tests-green --tool grok
npx @cobusgreyling/goal estimate --pattern tests-green --level G2
npx @cobusgreyling/goal doctor . --suggest
bash scripts/before-after-demo.sh

In Grok Build:

/goal Read GOAL.md. Implement the scoped objective. Run tests after each meaningful change.
Use update_goal for progress. Do not mark completed until the verifier skill passes.

See starters/minimal-goal/ and docs/goal-design-checklist.md.

Goal vs Loop

	Goal	Loop
Trigger	You set an objective	Schedule (`/loop`) or automation
Duration	Until done / blocked / cleared	Recurring forever (or until cancelled)
Best for	Finish a bounded task	Discover + triage ongoing work
State file	`GOAL.md`	`STATE.md`, `LOOP.md`
Grok command	`/goal`	`/loop` + `scheduler_*`

When to combine: a daily loop triages; when it finds a fixable item, hand off to a goal for run-until-done execution. See docs/goal-vs-loop.md.

Operating & Safety

Operating Goals — day-to-day playbook
Anti-Patterns — design mistakes before production
FAQ & Troubleshooting
Multi-Goal Coordination — parallel goals and loop handoff
Safety — deny lists, human gates, kill switches
Failure Modes — what goes wrong and how to recover
SECURITY.md — vulnerability reporting
GOAL.md — how this reference repo uses goals on itself

Tools

Tool	Command
goal (meta)	`npx @cobusgreyling/goal doctor . --suggest`
goal-audit	`npx @cobusgreyling/goal-audit . --json --min-level G2`
goal-init	`npx @cobusgreyling/goal-init . --pattern tests-green --lang python`
goal-cost	`npx @cobusgreyling/goal-cost --pattern fix-bug`

Meta subcommand	Maps to
`doctor` / `audit`	goal-audit
`init` / `scaffold`	goal-init
`estimate` / `cost`	goal-cost

Scores Goal Readiness (G0–G3) from signals: GOAL.md, skills, verifier, tests, CI, budget, run log freshness.

CI Integration

Gate PRs on minimum readiness:

- uses: cobusgreyling/goal-engineering/.github/actions/goal-audit@main
  with:
    path: .
    min-level: G2

Or: npx @cobusgreyling/goal-audit . --json --min-level G2 (exit 2 if below threshold).

The Stack

Layer	Unit	Question
Context Engineering	One inference	What does the model see?
Harness Engineering	One agent run	How does a single run execute safely?
Goal Engineering	One bounded objective	How do we run until verifiably done?
Loop Engineering	Autonomous system over time	What keeps prompting on a cadence?
Fleet Engineering	Agent populations	How do many agents coordinate at scale?

Contributing

PRs that improve patterns, verifier skills, or CLI heuristics are welcome. See CONTRIBUTING.md, adopters, discussions, and stories/.

License

MIT — see LICENSE.

Made with Grok Build. This repo is the go-to reference for /goal — link here when you teach, blog, or ship goal-driven agent workflows.