grok-delegate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Grok Delegate

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

仅针对Grok Build原生CLI的跨工具编排。父工具负责宏图管理；Grok执行微节点任务。

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

参数	操作
（空）	显示预检信息、wave分类体系、关键规则及参考索引
`preflight`	运行 `scripts/preflight.sh` ；若检查失败则终止
`auth`	执行快速身份验证检查；展示 `references/auth.md` 中的修复方案
`trivial`	展示Tier-T资格条件及单节点 `grok -p` 模板
`wave <0\|1\|2>`	展示侦察/构建/验证wave的命令模板
`tune`	展示会话恢复/增量提示循环流程
`leader`	展示领导者池生命周期
`ledger`	展示会话账本 schema
`patterns`	展示编排器Pattern A–F到Grok参数的映射关系

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.

适用场景：父工具管理多节点图，且至少一个节点需通过原生CLI在Grok Build上运行。
适用场景：准入检查失败，父工具需对现有账本记录执行
```
-r <sessionId>
```
调优操作。
Tier-T默认规则：当快速预检通过、
```
grok-auth-expiry
```
状态正常，且叶节点为受限任务（≤3次读取操作或 ≤1个文件且代码行数≤80；无破坏性/生产环境/git推送/敏感信息操作；无未解决的用户关键或子任务关键不确定性）时，默认使用
```
trivial
```
模式。父工具保留合成权限。
Tier-T失败回退：若父工作项首次原生
```
grok -p
```
Tier-T调度失败，则终止该工作项的Tier-T流程，转为本地执行。
禁用场景：Grok配置/MCP同步、skill安装或嵌套Grok-in-Grok编排。
Tier-T禁用场景：多节点图、重叠文件写入操作，或更适合在会话内完成的无界父工作任务；针对有效的多节点Grok图，使用
```
wave
```
/
```
patterns
```
模式。
格式错误调度：
```
wave
```
命令未指定
```
0|1|2
```
参数时无效；展示有效层级或空参数下的选项列表。不得自行默认wave层级。

Operator Contract

操作协议

preflight

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.

从任意工作目录运行
```
bash scripts/preflight.sh
```
（内置
```
doctor.py
```
；可通过
```
--cwd
```
指定目标仓库）。
当JSON输出中
```
ok
```
为false，或任何
```
grok-auth-*
```
/
```
grok-binary
```
检查失败时，终止集群调度。
将
```
warn
```
视为建议信息；任何
```
grok-auth-expiry
```
失败（过期、缺失或格式错误的
```
expires_at
```
）将阻止集群调度和Tier-T任务卸载。

auth

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>

运行
```
preflight.sh
```
；检查JSON输出中的
```
grok-auth-*
```
项。
加载
```
references/auth.md
```
获取基于OAuth的修复方案（
```
grok login
```
）。

可选深度验证：

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

。

trivial

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.

确认Tier-T资格（分类准入规则第3条）。
执行快速预检；要求
```
ok: true
```
且
```
grok-auth-expiry: ok
```
（OAuth状态正常）。
对于单文件编辑任务，父工具在调度前必须执行常规分支和工作区脏文件安全检查。确认目标文件未与无关脏文件重叠，并由父工具负责审核、合成和验证。
调度一个受限节点：

bash

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

若原生调度失败，记录失败信息，终止当前父工作项的Tier-T流程，转为本地执行。

wave <0|1|2>

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.

加载references/command-templates.md获取对应层级的内容。
为wave 1分配唯一的
```
-w w<wave>-<role>-<n>
```
名称，并确保文件所有权不重叠。
说明进入下一wave前必须通过的父工具准入检查。

tune

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
```
.

加载references/session-ledger.md，通过
```
-r <sessionId>
```
恢复会话。
增量提示前缀添加
```
Tune:
```
；每个
```
node_id
```
的
```
parent_tune_count
```
上限为3次。
不得默认启用
```
--always-approve
```
。

leader

leader

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

加载references/leader-lifecycle.md。
每个工作目录池启动一个领导者；图任务完成后，通过
```
grok leader kill
```
终止孤立的领导者进程。

ledger

ledger

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

加载references/session-ledger.md。
开启下一个父工具准入检查前，需确保存在N条终端账本记录。

patterns

patterns

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

加载references/graph-patterns.md，映射到
```
/orchestrator
```
的Pattern A–F。
父工具需记录：调度的节点数 = 合成前已解决的节点数。

(empty)

（空参数）

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

展示预检信息、wave分类体系、关键规则及参考索引。
调度节点前，对当前父工具请求执行分类准入检查。

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

术语	含义
parent harness	负责宏DAG的Codex、OpenCode、Claude或Cursor会话
Tier-T	快速预检通过且 `grok-auth-expiry: ok` 后，通过单次 `grok -p` 默认卸载受限简单叶节点的模式
node	针对图任务的一次 `grok` 子进程调用
wave	分阶段的节点批次（0侦察、1构建、2验证）
gate	进入下一wave前的父工具检查点
tune	对现有节点执行 `-r <sessionId> -p "Tune: ..."` 增量操作
ledger	跟踪每个节点 `sessionId` 的 `grok-delegate-ledger.jsonl` 文件
worktree	每个并行构建器的 `-w w<wave>-<role>-<n>` git隔离环境
leader pool	用于密集图任务的共享 `grok agent leader` 后端

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.

仅使用原生CLI — 禁止使用
```
bin/gk
```
、MCP控制服务器或自定义无头包装脚本。
必须执行预检 — 集群调度或Tier-T任务卸载前，需运行
```
scripts/preflight.sh
```
。
优先使用OAuth — 默认使用
```
grok login
```
；仅在用户明确请求时使用API密钥。
父工具管理图 — Grok深度为1；通过父工具的bash脚本并行处理兄弟节点，而非嵌套Grok编排。
跨工具委托时不得默认启用
--always-approve
。
自动化路径中必须使用
--no-auto-update
和显式
--cwd
。
记录规则 — 调度的节点数 = 进入下一个准入检查前的终端账本记录数。
每个工作树仅一个写入者 — 并行wave 1节点间的文件所有权不得重叠。

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
```
.

父工具通过bash调度独立的Grok节点（Pattern A/E）。
快速预检和
```
grok-auth-expiry
```
通过时，默认使用Tier-T卸载受限叶节点。
准入检查失败后原地调优：
```
-r <sessionId>
```
。
使用
```
-w
```
工作树或假设性
```
--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.

多节点图或重叠写入操作（使用wave模式，而非Tier-T）。
破坏性、生产环境、git推送、读取敏感信息或大范围实现工作。
Grok配置/MCP同步 — 使用
```
/harness-master
```
。
Skill安装 — 仅使用Skills CLI干运行预览（除非维护者请求，否则不得执行实时
```
--apply
```
）。
平台深度超过1的嵌套Grok-in-Grok图。

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).

权威流程：操作协议 → 上述

preflight

auth

部分。

bash

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

检查目标仓库：

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

（

grok inspect

无

--cwd

参数）。

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
```
.

父工具 —
```
/orchestrator
```
或OpenCode Ensemble负责wave和准入检查。
本skill — 模板、账本、安全、恢复。
Grok CLI —
```
-p
```
、
```
-r
```
、工作树、领导者、可选
```
grok agent stdio
```
。

Wave taxonomy

Wave分类体系

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.

Wave	用途	典型 `--agent`	`--max-turns`
0 scout	只读探索	`researcher`	8
1 build	实现开发	repo agent	25
2 verify	测试、评审	`code-reviewer`	10
tune	会话增量调优	继承	10
hypothesis	竞争性方案验证	`researcher`	12

模板：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.

bash

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

根据references/output-json.md解析JSON。根据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

bash

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

每个

node_id

的

parent_tune_count

上限为3次。

Parallel wave dispatch

并行Wave调度

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.

在一条父工具消息中调度N个独立的bash子进程。每个节点分配唯一的

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

，且文件所有权不重叠。详情见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.

bash

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

客户端通过

grok agent --leader

连接。详情：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.

节点失败 → 重试一次；否则标记账本为
```
failed
```
。
JSON解析失败 → 使用
```
--output-format plain
```
进行诊断。
领导者进程终止 → 执行
```
grok leader list
```
；重启池。
身份验证失败 → 执行
```
grok login
```
；重新运行预检；集群调度需等待
```
grok-auth-*
```
检查通过后方可恢复。

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

预检诊断JSON输出
```
ok: true
```
所有调度节点均有终端账本状态
父工具准入检查通过，或已记录用户明确终止操作
孤立领导者已被终止：
```
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

check.py

执行skill验证、评估验证、审计、诊断预检和

parse_grok_json

预检。

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

文件	内容
wave-dag.md	bash调度中的Wave准入检查
graph-patterns.md	编排器A–F + Tier-T映射关系
command-templates.md	可直接复制的调用命令
output-json.md	无头模式JSON字段说明
session-ledger.md	账本schema
agent-map.md	仓库代理 → `--agent` 映射
concurrency.md	预算、命名规则
leader-lifecycle.md	领导者进程启动/终止
acp-driver.md	官方ACP标准输入输出摘录
safety-permissions.md	权限矩阵
auth.md	基于OAuth的身份验证及修复方案
doctor-output.md	内置诊断工具JSON输出示例

官方文档：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 CLI委托、wave模板、Tier-T简单任务卸载、会话调优循环、并行工作树调度、领导者池策略。

禁用范围：Grok配置同步、自定义包装器、MCP服务器，或实时

skills sync --apply

（除非维护者请求）。