Grok Delegate

Cross-harness orchestration of Grok Build native CLI only. Parent harness owns the macro graph; Grok executes micro nodes.

Dispatch

$ARGUMENTS	Action
(empty)	Show pre-flight, wave taxonomy, critical rules, and reference index
`preflight`	Run `scripts/preflight.sh` ; stop on `fail` checks
`auth`	Run fast auth checks; show `references/auth.md` remediation
`trivial`	Show Tier-T eligibility and single-node `grok -p` template
`wave <0\|1\|2>`	Show command templates for scout / build / verify waves
`tune`	Show session resume / delta prompt loop
`leader`	Show leader pool lifecycle
`ledger`	Show session ledger schema
`patterns`	Show orchestrator Pattern A–F → Grok flag mapping

Classification Gate

Use when the parent harness owns a multi-node graph and at least one node should run on Grok Build via native CLI.
Use when a gate failed and the parent needs
```
-r <sessionId>
```
tune passes on an existing ledger row.
Tier-T default — use
```
trivial
```
by default when fast preflight
```
ok
```
,
```
grok-auth-expiry
```
is
```
ok
```
, and the leaf is bounded (≤3 reads OR ≤1 file ≤80 LOC; no destructive/prod/git-push/secrets; no unresolved user-pivotal or subtask-pivotal uncertainty). Parent keeps synthesis.
Tier-T failure fallback — if the first native
```
grok -p
```
Tier-T dispatch fails for a parent work item, stop Tier-T for that item and continue locally.
Do not use for Grok config/MCP sync, skill installs, or nested Grok-in-Grok orchestration.
Do not use Tier-T for multi-node graphs, overlapping file writers, or unbounded parent work better done in-session; use
```
wave
```
/
```
patterns
```
for valid multi-node Grok graphs.
Malformed dispatch —
```
wave
```
without
```
0|1|2
```
is invalid; show valid tiers or the empty-args gallery. Never invent a default wave.

Operator Contract

preflight

Run
```
bash scripts/preflight.sh
```
from any cwd (bundled
```
doctor.py
```
; optional
```
--cwd
```
for target repo).
Stop fleet dispatch when JSON
```
ok
```
is false or any
```
grok-auth-*
```
/
```
grok-binary
```
check is
```
fail
```
.
Treat
```
warn
```
as advisory; any
```
grok-auth-expiry
```
```
fail
```
(expired, missing, or malformed
```
expires_at
```
) blocks fleet dispatch and Tier-T offload.

auth

Run
```
preflight.sh
```
; inspect
```
grok-auth-*
```
checks in JSON output.
Load
```
references/auth.md
```
for OAuth-primary remediation (
```
grok login
```
).

Optional deep smoke:

bash scripts/auth_verify.sh --cwd <target>

trivial

Confirm Tier-T eligibility (Classification Gate item 3).
Run fast preflight; require
```
ok: true
```
and
```
grok-auth-expiry: ok
```
(OAuth healthy).
For the one-file edit form, the parent must run normal branch and dirty-worktree safety checks before dispatch. Confirm the target file does not overlap unrelated dirty work and keep the parent responsible for review, synthesis, and validation.
Dispatch one bounded node:

bash

grok --no-auto-update \
  -p "<bounded self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 10

If the native dispatch fails, record the failure, stop Tier-T for the current parent work item, and continue locally.

wave <0|1|2>

Load references/command-templates.md for the requested tier.
Assign distinct
```
-w w<wave>-<role>-<n>
```
names and non-overlapping file ownership for wave 1.
State the parent gate that must pass before the next wave.

tune

Load references/session-ledger.md and resume with
```
-r <sessionId>
```
.
Prefix delta prompts with
```
Tune:
```
; cap
```
parent_tune_count
```
at 3 per
```
node_id
```
.
Never default
```
--always-approve
```
.

leader

Load references/leader-lifecycle.md.
Start one leader per cwd pool; kill orphans with
```
grok leader kill
```
after graph completion.

ledger

Load references/session-ledger.md.
Require N terminal ledger rows before opening the next parent gate.

patterns

Load references/graph-patterns.md and map to
```
/orchestrator
```
Pattern A–F.
Keep parent accounting: N dispatched nodes = N resolved before synthesis.

(empty)

Show pre-flight, wave taxonomy, critical rules, and the reference index.
Run the Classification Gate on the current parent request before dispatching nodes.

Canonical Vocabulary

Term	Meaning
parent harness	Codex, OpenCode, Claude, or Cursor session owning the macro DAG
Tier-T	Default bounded trivial leaf offload via single `grok -p` after fast preflight and `grok-auth-expiry: ok`
node	One `grok` subprocess invocation for a graph task
wave	Staged batch of nodes (0 scout, 1 build, 2 verify)
gate	Parent checkpoint before the next wave
tune	`-r <sessionId> -p "Tune: ..."` delta on an existing node
ledger	`grok-delegate-ledger.jsonl` tracking `sessionId` per node
worktree	`-w w<wave>-<role>-<n>` git isolation per parallel builder
leader pool	Shared `grok agent leader` backend for dense graphs

Critical Rules

Native CLI only — no
```
bin/gk
```
, MCP control server, or custom headless wrapper scripts.
Pre-flight mandatory — run
```
scripts/preflight.sh
```
before fleet dispatch or Tier-T offload.
OAuth primary —
```
grok login
```
default; API key only on explicit user request.
Parent owns the graph — Grok depth is 1; parallelize siblings via parent bash, not nested Grok orchestration.
Never default
--always-approve
for cross-harness delegation.
Always
--no-auto-update
and explicit
--cwd
on automation paths.
Accounting — N dispatched nodes = N terminal ledger rows before the next gate.
One writer per worktree — non-overlapping file ownership across parallel wave 1 nodes.

When to use

Parent dispatches independent Grok nodes via bash (Pattern A/E).
Tier-T bounded leaf offload by default when fast preflight and
```
grok-auth-expiry
```
pass.
Tune-in-place after gate failure:
```
-r <sessionId>
```
.
Parallel builders with
```
-w
```
worktrees or hypothesis
```
--best-of-n
```
.

When NOT to use

Multi-node graphs or overlapping writers (use waves, not Tier-T).
Destructive, production, git-push, secret-reading, or broad implementation work.
Grok config/MCP sync —
```
/harness-master
```
.
Skill installs — Skills CLI dry-run preview only (no live
```
--apply
```
unless maintainer requests).
Nested Grok-in-Grok graphs beyond platform depth 1.

Pre-flight

Authoritative procedure: Operator Contract →

preflight

auth

above.

bash

bash skills/grok-delegate/scripts/preflight.sh

Inspect target repo:

cd <target-repo> && grok inspect --json

(

grok inspect

has no

--cwd

flag).

Three-tier model

Parent —
```
/orchestrator
```
or OpenCode Ensemble owns waves and gates.
This skill — templates, ledger, safety, recovery.
Grok CLI —
```
-p
```
,
```
-r
```
, worktrees, leader, optional
```
grok agent stdio
```
.

Wave taxonomy

Wave	Purpose	Typical `--agent`	`--max-turns`
0 scout	Read-only exploration	`researcher`	8
1 build	Implementation	repo agent	25
2 verify	Tests, review	`code-reviewer`	10
tune	Delta on session	inherit	10
hypothesis	Competing theories	`researcher`	12

Templates: references/command-templates.md.

Single node

bash

grok --no-auto-update \
  -p "<self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 25 \
  --agent "<agent-name>"

Parse JSON per references/output-json.md. Append ledger row per references/session-ledger.md.

Tune loop

bash

grok --no-auto-update \
  -r "<sessionId>" \
  -p "Tune: <delta only>" \
  --cwd "<same cwd>" \
  --output-format json \
  --max-turns 10

Cap

parent_tune_count

at 3 per

node_id

Parallel wave dispatch

Dispatch N independent bash subprocesses in one parent message. Each node gets unique

-w w<wave>-<role>-<n>

and non-overlapping ownership. See references/concurrency.md.

Leader pool

bash

grok agent leader --no-exit-on-disconnect --no-auto-update

Clients attach with

grok agent --leader

. Details: references/leader-lifecycle.md.

Recovery ladder

Node fail → one retry; else ledger
```
failed
```
.
JSON parse fail →
```
--output-format plain
```
triage.
Leader dead →
```
grok leader list
```
; restart pool.
Auth fail →
```
grok login
```
; re-run preflight; stop fleet until
```
grok-auth-*
```
checks pass.

Completion criteria

Pre-flight doctor JSON
```
ok: true
```
Every dispatched node has terminal ledger status
Parent gate passed or explicit user abort recorded
Orphan leaders killed:
```
grok leader kill
```

Validation

check.py

runs skill validation, eval validation, audit, doctor smoke, and

parse_grok_json

smoke.

bash

uv run python skills/grok-delegate/scripts/check.py
uv run pytest tests/test_grok_delegate_*.py -q
uv run python skills/skill-creator/scripts/audit.py skills/grok-delegate
uv run python skills/skill-creator/scripts/package.py skills/grok-delegate --dry-run

Reference index

File	Content
wave-dag.md	Wave gates on bash dispatch
graph-patterns.md	Orchestrator A–F + Tier-T mapping
command-templates.md	Copy-paste invocations
output-json.md	Headless JSON fields
session-ledger.md	Ledger schema
agent-map.md	Repo agents → `--agent`
concurrency.md	Budgets, naming
leader-lifecycle.md	Leader start/stop
acp-driver.md	Official ACP stdio excerpt
safety-permissions.md	Permission matrix
auth.md	OAuth-primary auth and remediation
doctor-output.md	Bundled doctor JSON

Official docs: https://docs.x.ai/build/cli/headless-scripting

Scope boundaries

IS for: native Grok CLI delegation, wave templates, Tier-T trivial offload, session tune loops, parallel worktree dispatch, leader pool policy.

NOT for: Grok config sync, custom wrappers, MCP servers, or live

skills sync --apply

unless the maintainer requests it.

grok-delegate

NPX Install

Tags

SKILL.md Content

Grok Delegate

Dispatch

Classification Gate

Operator Contract

`preflight`

`auth`

`trivial`

`wave <0|1|2>`

`tune`

`leader`

`ledger`

`patterns`

(empty)

Canonical Vocabulary

Critical Rules

When to use

When NOT to use

Pre-flight

Three-tier model

Wave taxonomy

Single node

Tune loop

Parallel wave dispatch

Leader pool

Recovery ladder

Completion criteria

Validation

Reference index

Scope boundaries