Orchestrate Grok Build CLI for headless code implementation

Grok Build Orchestration delegates well-specified implementation tasks to xAI's headless CLI while the orchestrator writes specifications, reviews every diff, and owns the result. Each task receives a self-contained Markdown file because the executor has no conversation context. The specification identifies repository context, conventions, allowed files, the precise change, constraints, and acceptance commands. Task files belong outside the target repository in a scratchpad or operating-system temporary directory.

Sequential dispatch is the default. A Markdown plan runs task by task, with its checkboxes updated after each task passes review. Parallel execution is allowed only when the plan explicitly marks tasks independent; each receives its own worktree, followed by individual review and merge. The skill is Apache-2.0 licensed.

Use it for clear plan tasks, boilerplate, scaffolding, CRUD, mechanical refactors, tests from explicit specifications, or interface components from mockups. Keep ambiguous requirements, architecture decisions, deep debugging across files, security-sensitive code, and production infrastructure with the orchestrator. If writing a specification takes as much work as implementing the task, retain the task locally.

Before every dispatch, show the exact text being sent to xAI, target worktree, and permission mode. Explicit approval must cover both disclosure and scoped editing. Specifications must exclude secrets, proprietary source, customer data, and credentials. Updates, destructive recovery, and unrestricted approval require separate authorization; the skill itself does not authorize installation, deployment, pushes, or cleanup.

Start from a clean source tree. Commit or stash source edits before dispatch so the resulting diff can be attributed to the task. Build artifacts are treated separately from source changes. The preferred one-shot invocation reads a specification file:

grok --prompt-file task.md --output-format json   # preferred: no shell-quoting issues

The returned JSON includes text, stopReason, sessionId, requestId, and thought. Save sessionId for a later fix-up. The top-level prompt command is the one-shot entry point; the agent subcommand runs a server instead.

Inspect the scoped diff, compare it with repository conventions and the specification, then run the acceptance commands. A pass permits the next task through the documented commit workflow. A failure requires permission before a fix-up or reset and preservation of the diff. CLI errors or timeouts get one retry before a manual fallback. Expired authentication stops dispatch; two exhausted fix-up rounds require a recovery decision.

Preflight checks the available update and authenticates through the model listing command. Actual updates require approval, followed by version verification. The default model is grok-4.5; grok-composer-2.5-fast is reserved for trivial mechanical work.

Headless editing requires --always-approve after approval for the exact clean worktree: acceptEdits can cancel edits without an interactive approver. Turn limits constrain execution, optional sandbox profiles restrict access, and --check adds executor verification for high-stakes work before the orchestrator reviews. POSIX and PowerShell support dispatch. Fine-grained allow and deny rules control permissions, --json-schema constrains final output, --cwd selects the repository, and --best-of-n runs several alternatives. Authentication uses subscription OAuth through grok login or logout on macOS, Linux, and Windows. Resume uses the saved session handle and specific feedback without repeating the entire task.