zcode-delegate

# ZCode Delegate

You are the **orchestrator**. This skill lets you hand a bounded coding task to a separate
**implementer** — the Z.AI ZCode CLI — then review what it produced and land it yourself. You write
the brief and own the judgment; ZCode does the typing; you verify and commit.

Nothing here is specific to one orchestrating agent. The loop needs only the ability to run a shell
command and read a file. (It is designed for and run on Claude Code; treat other orchestrators as
designed-for, not yet proven.)

## When NOT to use this

- The task is small enough to just do inline — delegation overhead is not worth it.
- ZCode is not installed, or its CLI has no model provider configured.
- You want to write the code yourself, or you only need a review.

## Prerequisites (check once)

1. **ZCode is installed.** The CLI ships **inside the desktop app** — it is not on PATH and not on
   npm. The relay resolves it in this order: `--zcode-path <file>` or `ZCODE_CLI` first, then PATH,
   then the installed app bundle. On Linux the app is an AppImage with no fixed install path, so
   the flag or the environment variable is required there — the relay guesses nothing.
2. **A model provider is configured for the CLI**, with a key it can actually reach. Being signed
   into the desktop app is *not* enough — see below.
3. You are in (or will point `--cd` at) the target git repository.

The relay records the CLI version and how it was resolved into `result.json`, so a surprising
install is visible after the fact.

## Authenticating the headless CLI

**Signing into the ZCode desktop app does not authenticate the CLI this relay drives.** The CLI
keeps its own config at `~/.zcode/cli/config.json`, separate from the desktop app's, and nothing
bridges the two. `zcode login` is the intended path, but where it fails with `OAuth response is
not valid JSON` the way in is a Z.AI API key.

Two pieces are needed, and they are separate:

1. **The provider block** must exist in `~/.zcode/cli/config.json`. It defines the provider, its
   endpoint and its models — the environment cannot supply this:

   ```jsonc
   {
     "provider": {
       "zai": {
         "kind": "anthropic",
         "options": { "apiKeyRequired": true, "baseURL": "https://api.z.ai/api/anthropic" },
         "models": { "glm-5.1": { "name": "GLM-5.1" } }
       }
     },
     "model": { "main": "zai/glm-5.1" }
   }
   ```

2. **The key** can live either in `provider.zai.options.apiKey` in that file, or in the
   environment as any one of `ZAI_API_KEY`, `ZCODE_API_KEY`, or `ANTHROPIC_API_KEY`. Prefer the
   environment — it keeps the secret off disk.

If a run fails with `Model provider is missing an API key: <provider>`, the provider block resolved
but no key was found: set one of those variables and re-run.

## Autonomy — read this before dispatching

ZCode's own term is **mode**. It has four values; only two are usable headlessly.

| mode | Behaviour |
| --- | --- |
| `yolo` | **Writes.** ZCode's own default for `--prompt`, and this relay's write-capable default. |
| `plan` | **Refuses edits.** What `--read-only` selects. |
| `build` | **Rejected by this relay.** No permission client exists headlessly, so tools are blocked and the run exits 0 having done nothing. |
| `edit` | Rejected for the same reason. |

Two limits stated plainly, because ZCode cannot enforce them:

- **`plan` mode refused edits in testing, but the relay does not treat that as a guarantee.** It
  takes a Git fingerprint before the run and reports a tri-state `readOnlyViolation` afterwards.
  Confirm `touchedFiles` came back empty rather than assuming no edits.
- **ZCode has no `--allowed-tools`.** Only the `--disallowed-tools` denylist exists, and it *is*
  genuinely enforced. An explicit allowlisted tool surface is therefore impossible here — do not
  assume one.

## The loop

Run these five steps per task. Steps 1, 4, and 5 are your judgment; 2 and 3 are mechanical.

### 1. Write the brief

ZCode sees **only** what you send — no repo memory, no chat history. Everything the task needs goes
in the brief: the goal, the current state, what to change, what to leave untouched, the project's
**actual** gate commands (discover them from the repo's CLAUDE.md/AGENTS.md/Makefile — do not
assume), and a report contract. Tell ZCode it will **not** commit. One task per brief. The relay
delivers the brief as an attached file, so the command line no longer bounds its length — the
model's context window still does. Full guidance and a template:
[references/writing-the-brief.md](references/writing-the-brief.md).

### 2. Dispatch

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# read-only (review/diagnosis, no edits):   add --read-only
# continue a specific session:              add --session <sess_...>  (from result.json; send only the delta brief)
# continue the latest session for --cd:     add --resume-last
# withhold tools (denylist):                add --disallowed-tools "Write,Edit,Bash"
# point at the CLI explicitly:              add --zcode-path /path/to/zcode.cjs
# hard time limit (watchdog):               add --timeout 2h  (default: off)
# see all options:                          node .../relay.mjs --help
```

(`<skill-dir>` is this skill's installed directory — the folder containing this `SKILL.md`.)

The relay writes its artifacts to a temp dir, so the repo under review stays clean. It **never
commits** — see step 5. Mechanics, flags, and the `result.json` shape:
[references/dispatch-and-poll.md](references/dispatch-and-poll.md).

### 3. Wait for completion

The relay blocks until ZCode finishes, so back it with whatever your orchestrator offers:

- **Claude Code:** run the Bash call with `run_in_background: true`; you are notified on completion.
- **Plain shell / other agents:** foreground for short tasks, or background it and poll the result
  file. The run is done when `result.json` exists with a `status`. A pre-run usage error exits 2