Grok Delegate

Grok Delegate

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

Dispatch

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

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

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

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.