Orchestrate Grok Build CLI for headless code implementation

Orchestrates delegating well-specified implementation tasks to xAI's Grok Build CLI running headlessly: the coding assistant plans, writes self-contained task specs, dispatches them to Grok Build, reviews every diff, and owns the final result, while Grok itself is the fast, cheap executor. Full CLI details and verified behaviors live in references/cli.md.

Use it when delegating a well-specified implementation task to Grok Build headlessly, when executing a Markdown implementation plan task-by-task with a diff review after each task, or when the user says "use grok," "grok build," "have grok implement," or "send to grok." Delegate to Grok: plan tasks with clear acceptance criteria, boilerplate/scaffolding/CRUD, mechanical refactors, test writing from clear specs, and UI components from mockups or specs. Keep with the orchestrator instead: ambiguous requirements and architecture decisions, deep cross-file debugging, security-sensitive code, anything touching production infrastructure, and any task where writing the spec is basically equivalent to doing the work - when in doubt, keep it with the orchestrator. Before every dispatch, show the user the exact task specification that will be sent to xAI, the target worktree, and the permission mode, and get explicit approval to disclose that text and let Grok edit the scoped worktree; never include secrets, proprietary source, customer data, or credentials in a task specification, and never run grok update, --always-approve, or a destructive recovery command without separate, explicit approval.

Session preflight runs once before the first dispatch: grok update --check --json (tell the user if updateAvailable is true, and only run grok update after explicit approval, confirming with grok --version), then grok models (if it errors or reports logged out, stop and ask the user to run grok login). The default per-task loop is sequential: write a self-contained task spec to a temp directory outside the target repo (Grok has zero conversation context, so no one-liner prompts, ever); ensure clean state with no uncommitted source changes so the post-run diff is exactly Grok's work; then dispatch:

grok --prompt-file <task-file> \
  --output-format json \
  --always-approve \
  --max-turns 30 \
  --cwd <repo>

parsing the JSON output and saving sessionId (--always-approve is required for headless runs, since --permission-mode acceptEdits silently cancels edits with no interactive approver, and should only be used after explicit approval for that exact scoped worktree; add --check for a high-stakes task so Grok self-verifies first, at roughly double the latency). The review gate is non-negotiable: read the diff yourself, run the acceptance commands from the spec, commit with a clear message on pass, and on failure ask the user before any fix-up or reset - never run git checkout -- . or git clean -fd automatically. The task spec itself follows a fixed template with Task, Context, Files, Task description, Constraints, and Acceptance criteria sections. Default model is grok-4.5, with -m grok-composer-2.5-fast reserved for trivial mechanical tasks only.

Executing a Markdown implementation plan dispatches one plan task at a time in order, checking off the plan's task checkboxes (- [ ] to - [x]) as each task lands and passes the review gate; only when a plan explicitly marks tasks independent does parallel dispatch apply, using --worktree=<task-slug> per task, running concurrently, then reviewing and merging one worktree at a time through the same review gate - merge conflicts usually eat the savings, so sequential remains the preferred default. Failure handling: a cancelled, empty, or diff-less result usually means a missing --always-approve, retry with it; a CLI error or timeout gets one retry, then the orchestrator does the task itself and notes the fallback; an expired auth means stop and ask the user to run grok login; two exhausted fix-up rounds mean preserving the diff and asking the user for a recovery decision; and a dirty tree at dispatch time is refused outright, requiring a commit or stash first. As a third-party service, Grok should never receive secrets, proprietary material, personal data, or customer data, and --always-approve must stay limited to a clean, explicitly approved worktree and never substitute for the orchestrator's own review - the skill does not authorize installations, updates, commits, pushes, deployments, or destructive cleanup on its own.

Coding orchestrators and developers who want to hand well-scoped implementation tasks to a fast, cheap headless executor while keeping architecture decisions, security-sensitive code, and final diff review firmly with a human or the orchestrating agent.