grok-delegate

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

1. Use when the parent harness owns a multi-node graph and at least one node should run on Grok Build via native CLI.
2. Use when a gate failed and the parent needs -r <sessionId> tune passes on an existing ledger row.
3. 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.
4. 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.
5. Do not use for Grok config/MCP sync, skill installs, or nested Grok-in-Grok orchestration.
6. 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.
7. 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

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

auth

1. Run preflight.sh; inspect grok-auth-* checks in JSON output.
2. Load references/auth.md for OAuth-primary remediation (grok login).
3. Optional deep smoke: bash scripts/auth_verify.sh --cwd <target>.

trivial

1. Confirm Tier-T eligibility (Classification Gate item 3).
2. Run fast preflight; require ok: true and grok-auth-expiry: ok (OAuth healthy).
3. 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.
4. Dispatch one bounded node:

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

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

wave <0|1|2>

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

tune

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

leader

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

ledger

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

patterns

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

(empty)

1. Show pre-flight, wave taxonomy, critical rules, and the reference index.
2. 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

1. Native CLI only — no bin/gk, MCP control server, or custom headless wrapper scripts.
2. Pre-flight mandatory — run scripts/preflight.sh before fleet dispatch or Tier-T offload.
3. OAuth primary — grok login default; API key only on explicit user request.
4. Parent owns the graph — Grok depth is 1; parallelize siblings via parent bash, not nested Grok orchestration.
5. Never default --always-approve for cross-harness delegation.
6. Always --no-auto-update and explicit --cwd on automation paths.
7. Accounting — N dispatched nodes = N terminal ledger rows before the next gate.
8. 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 skills/grok-delegate/scripts/preflight.sh

Inspect target repo: cd <target-repo> && grok inspect --json (grok inspect has no --cwd flag).

Three-tier model

1. Parent — /orchestrator or OpenCode Ensemble owns waves and gates.
2. This skill — templates, ledger, safety, recovery.
3. 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

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

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

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

Clients attach with grok agent --leader. Details: references/leader-lifecycle.md.

Recovery ladder

1. Node fail → one retry; else ledger failed.
2. JSON parse fail → --output-format plain triage.
3. Leader dead → grok leader list; restart pool.
4. 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.

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.