grok-delegate

Use when delegating Grok task nodes via native CLI (-p, -r, worktrees, leader) from Codex/OpenCode waves. NOT for harness sync or wrappers.

grok-delegate1353 wordsMITv1.3.0Repo-owned

grok-delegate

Use when delegating Grok task nodes via native CLI (-p, -r, worktrees, leader) from Codex/OpenCode waves. NOT for harness sync or wrappers.

Quick Start

Install:

npx skills add github:wyattowalsh/agents --skill grok-delegate -y -g --agent antigravity --agent claude-code --agent codex --agent crush --agent cursor --agent gemini-cli --agent github-copilot --agent grok --agent opencode

Use: /grok-delegate

Works with Claude Code, Gemini CLI, OpenCode, and other agentskills.io-compatible agents.

What It Does

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

Modes

$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\
`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

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.

Classification Gate

Step — Use when the parent harness owns a multi-node graph and at least one node should run on Grok Build via native CLI.
Step — Use when a gate failed and the parent needs -r <sessionId> tune passes on an existing ledger row.
Step — Tier-T — use trivial 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). Parent keeps synthesis.
Step — Do not use for Grok config/MCP sync, skill installs, or nested Grok-in-Grok orchestration.
Step — Do not use for multi-node graphs, overlapping file writers, or unbounded parent work better done in-session.
Step — 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).
Dispatch one bounded node:

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

`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	Bounded trivial leaf offload via single `grok -p` after fast preflight
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

When To Use

Parent dispatches independent Grok nodes via bash (Pattern A/E).
Tier-T bounded leaf offload when preflight passes.
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).
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

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

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

Public Metadata
General

Field	Value
Source Type	`repo-owned`
Display Source	`github:wyattowalsh/agents`
Source Kind	`repo`
Installability	portable command
Review State	reviewed
Target Agents	`antigravity`, `claude-code`, `codex`, `crush`, `cursor`, `gemini-cli`, `github-copilot`, `grok`, `opencode`

Field	Value
Name	`grok-delegate`
License	MIT
Version	1.3.0
Author	wyattowalsh

Full SKILL.md

---
name: grok-delegate
description: >-
  Use when delegating Grok task nodes via native CLI (-p, -r, worktrees, leader)
  from Codex/OpenCode waves. NOT for harness sync or wrappers.
license: MIT
metadata:
  author: wyattowalsh
  version: "1.3.0"
user-invocable: true
---

# 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`](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** — use `trivial` 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). Parent keeps synthesis.
4. **Do not use** for Grok config/MCP sync, skill installs, or nested Grok-in-Grok orchestration.
5. **Do not use** for multi-node graphs, overlapping file writers, or unbounded parent work better done in-session.
6. **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`](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. Dispatch one bounded node:

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

### `wave <0|1|2>`

1. Load [references/command-templates.md](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](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](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](references/session-ledger.md).
2. Require N terminal ledger rows before opening the next parent gate.

### `patterns`

1. Load [references/graph-patterns.md](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** | Bounded trivial leaf offload via single `grok -p` after fast preflight |
| **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 when preflight passes.
- 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).
- 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

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](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](references/output-json.md). Append ledger row per [references/session-ledger.md](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](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](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.

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

Download from GitHub

Resources

Skill CatalogBrowse custom and external skills.

CLI ReferenceInstall and manage skills.

agentskills.ioThe open ecosystem for cross-agent skills.

View source on GitHub

Custom

External

grok-delegate

Quick Start

What It Does

Modes

Critical Rules

Classification Gate

Operator Contract

`preflight`

`auth`

`trivial`

`wave <0\|1\|2>`

`tune`

`leader`

`ledger`

`patterns`

(empty)

Canonical Vocabulary

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

Resources

Surfaces

Reference

Popular Tags

grok-delegate

Quick Start

What It Does

Modes

Critical Rules

Classification Gate

Operator Contract

preflight

auth

trivial

wave &lt;0\|1\|2&gt;

tune

leader

ledger

patterns

(empty)

Canonical Vocabulary

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

Resources

Surfaces

Reference

Popular Tags

`preflight`

`auth`

`trivial`

`wave <0\|1\|2>`

`tune`

`leader`

`ledger`

`patterns`