Skip to content

amElnagdy/delegate-skills / skills/warp-delegate

warp-delegate

Verified

Delegate a coding task to the Warp Agent CLI (`oz`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Warp - phrasings like "have Warp implement X", "delegate this to the Warp CLI", "run it through Warp", "use oz to implement/fix/refactor" - or wants to run a queue of coding tasks through Warp while staying the reviewer. DO NOT USE for tasks small enough to do inline, when the user wants the code written directly without delegating, or for the interactive `warp` TUI (this skill drives the headless `oz agent run`, not the terminal app).

references/dispatch-and-poll.md

View on GitHub
# Dispatch and poll

The relay is the only Warp-specific machinery in this skill. It launches `oz agent run`, captures
the event stream, and writes one result file the orchestrator can read.

## What the relay runs

```text
oz agent run --output-format ndjson --cwd <cd> [--model …] [--profile …] [--name …]
             [--conversation …] [--skill …] [--mcp … …] [--no-snapshot] --prompt <brief>
```

`--output-format ndjson` makes Warp emit one JSON object per line, so a long run reports progress
instead of buffering to the end. The workspace is pinned twice: the child process's cwd and Warp's
own `--cwd`.

## Flags

| Flag | Effect |
| --- | --- |
| `--brief <file>` | Path to the brief. Omit to read it from stdin. |
| `--cd <dir>` | Working root (default: current directory). Also passed as Warp's `--cwd`. |
| `--lane <name>` | Resolve dials from a `delegate-setup` fleet lane. Explicit flags win. |
| `--model <id>` | Warp model id from `oz model list`. Letters, digits, and `. _ : / -` only. |
| `--profile <id>` | Warp agent profile. |
| `--name <label>` | Labels the run in Warp's own run list. |
| `--conversation <id>` | Continue an existing Warp conversation. Send a delta brief only. |
| `--skill <spec>` | Warp skill as the base prompt: `name`, `repo:name`, or `org/repo:name`. |
| `--mcp <spec>` | MCP config path or inline JSON. Repeatable. |
| `--no-snapshot` | Forward Warp's `--no-snapshot` so no end-of-run workspace snapshot is uploaded. |
| `--timeout <dur>` | Relay watchdog, h/m/s (default `30m`). Warp has no timeout flag of its own. |
| `--out-dir <dir>` | Artifact directory (default: a fresh dir under the system temp dir). |

Values for `--model`, `--profile`, and `--conversation` are token-validated. `--skill`, `--mcp`, and
`--name` accept freer text but must not start with `-`, which `oz` would read as another flag.

## Artifacts

Written to `--out-dir`:

- `brief.txt` — exactly what was sent.
- `events.jsonl` — the raw ndjson stream, byte for byte. The fallback whenever a parsed field looks
  wrong.
- `final.txt` — the assembled report, when one was captured.
- `stderr.txt` — everything Warp wrote to stderr.
- `result.json` — the structured result, written atomically via a temp file and rename, so a polling
  reader never sees a half-written file.

## `result.json`

Schema id `delegate-relay.result.v1`. Synthetic example:

```json
{
  "schema": "delegate-relay.result.v1",
  "tool": "oz",
  "status": "completed",
  "exitCode": 0,
  "signal": null,
  "ozVersion": "Oz v0.0000.00.00.00.00.stable_01",
  "workdir": "/path/to/repo",
  "model": null,
  "profile": null,
  "snapshotDisabled": false,
  "resumed": false,
  "runId": "00000000-0000-0000-0000-000000000000",
  "runUrl": "https://oz.warp.dev/runs/00000000-0000-0000-0000-000000000000",
  "conversationId": null,
  "finalMessage": "Changed src/export/csv.ts …",
  "touchedFiles": [" M src/export/csv.ts", "?? src/export/csv.test.ts"],
  "startedAt": "2026-01-01T00:00:00.000Z",
  "finishedAt": "2026-01-01T00:04:12.000Z"
}
```

Field notes:

- **`status`** — `completed`, `failed`, `timeout`, `aborted`, or `warp_unavailable`.
- **`touchedFiles`** — `git status --porcelain` lines. `null` when git cannot report (not a
  repository, git missing); `[]` when the tree is genuinely clean. `[]` and `null` mean different
  things — do not collapse them.
- **`runId` / `runUrl`** — from Warp's `run_started` system event. `runUrl` opens the run in Warp.
- **`conversationId`** — the handle to pass back as `--conversation` for rework. Present only when
  Warp emitted it on the stream.
- **`finalMessage`** — Warp's own report. Assembled from the text-bearing events in the stream; see
  the caveat below.
- **`stderrTail`** — last 20 stderr lines, included on every non-clean outcome.

### What `finalMessage` actually contains

Confirmed against a live edit run on oz 0.2026.05.27. The stream carries:

| Event | Meaning |
| --- | --- |
| `{"type":"system","event_type":"run_started","run_id":…,"run_url":…}` | Run registered. |
| `{"type":"system","event_type":"conversation_started","conversation_id":…}` | The `--conversation` handle. Re-emitted on a resumed run carrying the *same* id, so `conversationId` stays stable across a rework chain. |
| `{"type":"agent","text":…}` | Agent output. **This is what `finalMessage` is built from.** |
| `{"type":"agent_reasoning","text":…}` | Private reasoning. Same shape, deliberately **excluded**. |
| `{"type":"tool_call"\|"tool_result"\|"tool_error",…}` | Tool traffic. No `text` field. |

Two consequences:

- **`finalMessage` is the whole narration, not just the closing report.** Warp emits no distinct
  final-message event, so every `agent` chunk is concatenated — including running commentary like
  "Now let me run both gates." This is why the brief must specify a report contract: `FILES:` /
  `GATES:` / `NOTES:` at the end gives you a stable anchor to read instead of parsing prose.
- **`agent_reasoning` must stay excluded.** It carries a `text` field of exactly the same shape, so
  matching on `text` alone splices the model's reasoning into the report.

Past those two rules the extraction stays tolerant — it also accepts `agent_output`, `content`, and
a nested `message.content` — so a renamed output event still reports rather than yielding an empty
`finalMessage`. If one ever does come back empty on a successful run, `events.jsonl` holds the raw
stream and `collectText` is the one place to correct.

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | Warp exited 0 and reported no stream error. |
| `1` | Generic failure, or a stream-reported agent error even when `oz` exited 0. |
| `2` | Usage error — bad flag, bad `--timeout`, missing or empty brief. **No result file is written.** |
| `124` | The bounded `oz --version` preflight timed out; Warp was never dispatched. |
| `127` | `oz` is not on PATH. A result file **is** written, with `status: "warp_unavailable"`. |
| `128 + n` | The child died on signal *n*; `signal` records which. |

## Polling

The relay blocks until the run ends. Background it and poll for `result.json`:

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo \
  --out-dir /tmp/warp-run-1 &
until [ -f /tmp/warp-run-1/result.json ]; do sleep 5; done
```

Completion means the process exited **and** `result.json` exists. Do not infer completion from
stdout going quiet — a long tool call looks identical to a finished run.

## Timeouts and aborts

`oz` has no timeout flag, so the watchdog is the relay's. When `--timeout` expires the relay kills
the whole process group (SIGTERM, then SIGKILL after 10s) and writes `status: "timeout"`.

If the relay itself is killed, it still writes `status: "aborted"`, forwards the kill to `oz`, and
re-snapshots `touchedFiles` after a 2-second grace window so files flushed during shutdown are
recorded. On Windows the process tree is felled with `taskkill /t /f`; Windows delivers no catchable
SIGTERM, so the aborted path cannot be driven there.

**A timed-out or aborted run leaves a partially edited tree.** Inspect `git status` and `git diff`
before re-dispatching. If the state is incoherent, discard it against the recorded baseline rather
than stashing — a bare `git stash` leaves behind every file the run created. See
[review-and-land.md](review-and-land.md#rework-through-a-conversation).

## Failure recovery

| Symptom | What it means | Do |
| --- | --- | --- |
| `warp_unavailable`, exit 127 | `oz` is not on PATH | Install the Warp Agent CLI; check `oz --version`. |
| stderr `subscribe to a Warp plan, or bring your own inference` | Authenticated, but the account has no AI quota. Warp logs it as `QuotaLimit` / "lack of AI quota". `oz` shares the Warp app's account, plan, and credits, so this is a credit condition, not a CLI-only gate | Check `oz whoami` names the account holding the plan - if not, `oz logout && oz login`. Otherwise confirm its AI credits are not spent, or store your own provider key: `warp --set-provider-api-key <openai\|anthropic\|google\|grok>` (or `/api-keys` in the TUI). Bring-your-own-key needs no paid plan. Warp's log is at `~/Library/Logs/oz/warp.log` on macOS. |
| `Device not configured` | The `warp` TUI was launched, not `oz` | Use `oz`; the TUI cannot be relayed. |
| exit 2, no result file | Usage error | Read the relay's stderr line; fix the flag. |
| `status: "timeout"` | The watchdog fired | Raise `--timeout`, or split the brief. |
| Empty `finalMessage`, exit 0 | Text extraction missed the event shape | Read `events.jsonl`; see the caveat above. |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall