amElnagdy/delegate-skills / skills/zcode-delegate
zcode-delegate
VerifiedDelegate a coding task to the Z.AI ZCode CLI as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to ZCode — phrasings like "have ZCode do X", "delegate this to ZCode", "run it through ZCode", or "use ZCode to implement/fix/refactor" — or to run a queue of coding tasks through ZCode while staying the reviewer. DO NOT USE for tasks small enough to do inline, or when the user wants the code written directly without delegating.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.4 KB |
| references/dispatch-and-poll.md | markdown | 6.4 KB |
| references/multi-task-queues.md | markdown | 3.5 KB |
| references/review-and-land.md | markdown | 4.0 KB |
| references/writing-the-brief.md | markdown | 4.9 KB |
| scripts/relay.mjs | script | 47.3 KB |
references/dispatch-and-poll.md
View on GitHub# Dispatch and poll
The relay wraps the ZCode CLI so your job is "run a command, read a file."
```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
cat brief.txt | node "<skill-dir>/scripts/relay.mjs" --cd /path/to/repo
```
## How the relay finds ZCode
ZCode does not install a `zcode` binary on PATH and does not publish one to npm — the CLI ships
inside the desktop app. The relay resolves it in this order, first hit wins:
1. `zcode` on **PATH** — if you made a shim or alias, this is used.
2. **`--zcode-path <file>`**, else the **`ZCODE_CLI`** environment variable.
3. The installed **app bundle**: `%LOCALAPPDATA%\Programs\ZCode\resources\glm\zcode.cjs` on Windows,
`/Applications/ZCode.app/…` (and `~/Applications/…`) on macOS. Linux ships an AppImage with no
fixed install path, so there is nothing to auto-discover there — use option 1 or 2.
A resolved `.cjs` bundle is launched under `node`. `result.json` records which route was used in
`zcodeSource` (`path` / `flag` / `env` / `bundle`), so a surprising install is visible after the run.
If no CLI is found — including when you name one explicitly that does not exist — the relay exits
**127** and still writes a `result.json` with `status: "zcode_unavailable"`.
## Options
| Flag | Effect |
| --- | --- |
| `--brief <file>` | Path to the brief. Omitted → read from stdin. |
| `--cd <dir>` | Working root for ZCode (default: current directory). |
| `--lane <name>` | Fleet lane from `delegate-setup` config. Explicit flags win over lane dials. |
| `--mode <mode>` | ZCode's `--mode`. **Only `plan` and `yolo` are accepted** (see below). Default `yolo`. |
| `--read-only` | Shortcut for `--mode plan` (review/diagnosis, no edits). |
| `--disallowed-tools <list>` | Comma/space-separated denylist, e.g. `"Write,Edit,Bash"`. Enforced by ZCode. |
| `--session <id>` | Continue a specific session by `sess_…` id from a prior `result.json`. |
| `--resume-last` | Continue the latest session **for `--cd`**. Mutually exclusive with `--session`. |
| `--zcode-path <file>` | Point at the CLI explicitly. |
| `--timeout <dur>` | Relay-side watchdog (default: off). `30m`, `2h`. ZCode has no timeout flag of its own. |
| `--out-dir <dir>` | Where to write run artifacts (default: a fresh dir under the system temp dir). |
| `-h, --help` | Show help. |
### Why `build` and `edit` are rejected
ZCode documents four modes. Headless runs have no permission client, so under `build` or `edit` the
Write and Bash tools are blocked and the run **exits 0 having changed nothing**, with a report
explaining that tool permissions were denied. That is a success status for a run that did no work,
so the relay refuses those modes up front with a usage error (exit 2) rather than letting them look
like a completed task. Use `--mode yolo` to write, or `--read-only` for plan mode.
## The `result.json` contract
Speaks `delegate-relay.result.v1`.
| Field | Meaning |
| --- | --- |
| `status` | `completed` \| `failed` \| `timeout` \| `aborted` \| `zcode_unavailable` |
| `exitCode` | ZCode's own exit code, or the relay's mapping for a killed run |
| `signal` | The signal that killed the child, or `null` |
| `finalMessage` | ZCode's final report (its `response` field) |
| `sessionId` | The `sess_…` id — pass to `--session` to continue this exact session |
| `touchedFiles` | Git porcelain paths. `[]` when the tree is clean, `null` when git cannot report. |
| `mode` | The ZCode mode the run actually used |
| `readOnlyViolation` | Tri-state. `false` = the tripwire saw no change on a plan run, `true` = it did, `null` = unknown or not applicable |
| `usage` | ZCode's token accounting (input, output, total, cache reads) |
| `contextWindow` | From ZCode's `projection` |
| `zcodeVersion`, `zcodeSource` | Which CLI ran, and how it was found |
| `briefPath`, `outputPath`, `finalPath` | Run artifacts on disk |
Exit codes: a pre-run usage error (bad args, empty brief, a rejected `--mode`) exits **2** and writes
**no** result file. A CLI that cannot be found exits **127** and *does* write one. Otherwise the exit
code mirrors ZCode's, and a run killed by the watchdog reports `timeout`.
An orchestrator that polls for the file must therefore also check the exit code — a non-zero exit
with no file is a usage error, not a crashed run.
## Backgrounding
- **Claude Code:** run the Bash call with `run_in_background: true`.
- **bash/zsh (incl. Git Bash/WSL):** `… &`, then poll for `result.json`.
- **PowerShell:** `Start-Job`. **cmd:** `start /b`.
The run is finished when `result.json` exists with a `status` *and* the process has exited.
## Reading the output
ZCode's `--json` prints a single JSON document at the end rather than a stream of events, and the
relay parses it tolerantly: the bundled AI SDK sometimes prints a warning banner on stdout ahead of
the JSON, so leading non-JSON lines are skipped. The raw stdout is preserved at `outputPath` and the
final report at `finalPath`, so nothing is lost if parsing degrades.
If the document cannot be parsed at all:
- with exit 0, the run is still `completed`, `finalMessage` falls back to the raw stdout, and a
`parseWarning` field is set — read `outputPath` yourself.
- with a non-zero exit, the run is `failed` and `stderrTail` carries the last lines of stderr.
## When a run misbehaves
- **`status: "timeout"`** — the watchdog fired. The whole ZCode process tree was killed. Inspect the
working tree before re-dispatching; a killed run can leave partial edits.
- **`status: "aborted"`** — the relay itself was killed and forwarded the kill. Same advice.
- **`status: "zcode_unavailable"`** — no CLI found. Check the three resolution routes above.
- **Exit 1 with `Session not found`** — the `--session` id does not exist. Session ids are
`sess_`-prefixed; copy them from a prior `result.json`, not from memory.
- **`completed` but `touchedFiles` is empty on a write run** — read `finalMessage`. ZCode may have
reported that it could not proceed. That is a real outcome, not a relay bug.
- **`(no final message captured)` on a resumed plan-mode run** — ZCode has been observed returning
`"response": ""` while doing substantial work (658 output tokens across 602 events in one measured
run). The relay reports what ZCode sent, so an empty report here is the CLI's, not a parse failure:
`parseWarning` will be absent and `usage` non-zero. Read `outputPath` and the working tree rather
than concluding nothing happened.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |