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 →

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)

# 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

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

1. Persistence — the objective survives compaction and new turns
2. Progress telemetry — update_goal logs status without spamming the chat
3. Explicit lifecycle — pause, resume, clear, blocked
4. 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

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.

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

flowchart LR
    A["/goal <objective>"] --> 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/]

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

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.

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 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

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

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).

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

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.