amElnagdy/delegate-skills / skills/copilot-delegate
copilot-delegate
VerifiedDelegate a coding task to the GitHub Copilot CLI (`copilot`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to delegate implementation work to Copilot - phrasings like "have Copilot implement X", "delegate this to copilot", "run it through Copilot CLI", or "use copilot to implement/fix/refactor" - or wants to run a queue of coding tasks through Copilot 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 | 7.0 KB |
| references/dispatch-and-poll.md | markdown | 7.9 KB |
| references/multi-task-queues.md | markdown | 2.2 KB |
| references/review-and-land.md | markdown | 3.6 KB |
| references/writing-the-brief.md | markdown | 6.2 KB |
| scripts/relay.mjs | script | 30.8 KB |
references/dispatch-and-poll.md
View on GitHub# Dispatch and poll
`scripts/relay.mjs` wraps copilot's headless JSONL mode, captures its event stream, and writes
a `result.json`. Run one command, then read one file.
## Before the first run
```bash
command -v copilot
copilot version
```
Install `copilot` (`npm install -g @github/copilot`; the CLI requires Node 22+, the relay itself
runs on Node 18+); on Windows it installs as an npm `.cmd` shim
(the relay launches it with `shell:true`). Authenticate with `copilot login` or set
`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`. A headless run that is not authenticated
fails with `status: "failed"` (exit 1).
## Dispatching
```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
```
`<skill-dir>` is the installed folder containing this skill's `SKILL.md`.
| Flag | Effect |
| --- | --- |
| `--brief <file>` | Brief path. Omit it to read the brief from stdin. |
| `--cd <dir>` | Working root and child process cwd (default: current directory). |
| `--lane <name>` | Fleet lane from `delegate-setup` config. Applies that lane's dials; fails if the lane's `implementer` is not this relay. Explicit dial flags win. |
| `--model <name>` | Copilot model (default: copilot's own default, `auto`). Token-validated: letters, digits, `. _ : / -`. |
| `--effort <level>` | Reasoning effort (`low`\|`medium`\|`high`\|`xhigh`\|`max`). Rejected before dispatch if unknown. |
| `--read-only` | Read-only plan mode (`--mode plan`); works without `--allow-all-tools`. Mutually exclusive with `--allow-all-tools`. |
| `--allow-all-tools` | Full tool autonomy. Without this, headless tool calls are auto-denied and the relay reports `status: "failed"`. Mutually exclusive with `--read-only`. |
| `--resume-last` | Resume the most recent session (`--continue`). |
| `--session <id>` | Resume a specific session (`--resume=<id>`). Mutually exclusive with `--resume-last`. |
| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). Copilot has no timeout flag. |
| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
| `-h`, `--help` | Print the relay's header help. |
The child cwd pins the workspace. The relay does not pass copilot's `--add-dir`.
## Artifacts and result fields
Artifacts live outside the repo by default, so they do not appear in `touchedFiles`; an
`--out-dir` inside the worktree can make the artifacts appear there:
- `brief.txt` — the exact brief.
- `events.jsonl` — raw copilot stdout events (every JSONL event copilot emitted).
- `final.txt` — the last non-ephemeral `assistant.message` content; absent if none was emitted.
- `stderr.txt` — complete stderr.
- `result.json` — the stable `delegate-relay.result.v1` contract.
`result.json` fields:
- `schema`, `tool` (`"copilot"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `copilot_unavailable`), `exitCode`, and `signal` (`null` unless the child died on a signal).
- `workdir`, `model`, `effort`, `readOnly`, `allowAllTools`, `resumed`, `copilotVersion`,
`startedAt`, and `finishedAt`.
- `sessionId` — parsed from the `result` event's `sessionId` field; available for resume.
- `finalMessage` — text of the last non-ephemeral `assistant.message` event.
- `touchedFiles` — `git status --porcelain` lines for the **final working tree under `--cd` only**,
not an attribution of copilot's edits: anything already dirty before dispatch shows up too.
Dispatch from a clean tree when you want the list to read as "what copilot changed". `null` means
git could not report; `[]` means git ran and the tree is clean.
- `briefPath`, nullable `finalPath`, `eventsPath`, and `stderrPath`. `finalPath` is `null` when
copilot emitted no non-ephemeral assistant message and `final.txt` was not created.
- `stderrTail` — the last 20 non-empty stderr lines on any run that did not complete (`failed`,
`timeout`, `aborted`).
- `error` — present on denial failures (with the CLI's own denial message plus a hint to pass
`--allow-all-tools`), preflight failures, when the relay watchdog fires (`timeout`), and on an
`aborted` run.
## Waiting for completion
The relay blocks. Use the orchestrator's background-command facility, or background it in a shell
and poll for `result.json`. The run is done only when the process exits and the file contains a
`status`. The result file is written atomically, so a partial read is impossible.
A pre-run usage error exits 2 and writes no result. A missing `copilot` exits 127 and writes
`status: "copilot_unavailable"`.
## When a run misbehaves
- **`status: "copilot_unavailable"` (exit 127):** copilot is not on PATH. Install it, authenticate,
and re-dispatch.
- **`status: "failed"` with a denial error:** copilot auto-denied a tool call in headless mode.
The error message includes the CLI's own denial text and a hint to pass `--allow-all-tools`.
Re-dispatch with `--allow-all-tools` to grant full tool permissions.
- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
causes: an unknown `--model`, expired credentials, or a provider error.
- **`status: "failed"` with an `error` mentioning `version preflight`:** the bounded
`copilot version` probe failed or hung, so copilot was never dispatched. Check the install
(`copilot version` yourself).
- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
closed terminal) and forwarded the kill to copilot. The result is written before the relay exits;
inspect the working tree before re-dispatching.
- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
`copilot did not finish within --timeout <dur>; killed by the relay watchdog`. Increase
`--timeout` or split the task.
- **Empty `finalMessage`:** inspect `touchedFiles` and the diff. Add a
`<structured_output_contract>` to the next brief to require a closing report.
## Recovering lost work
`events.jsonl` in the run directory records every JSONL event the implementer streamed. If finished
work is lost — the run killed late, or the working tree damaged afterward — read the event log
before re-dispatching: it identifies which files and tool commands were involved, which scopes
what needs redoing.
## What the relay runs
The launch is equivalent to:
```bash
copilot --output-format json --no-color --stream off \
[--mode plan] [--allow-all-tools] \
[--continue | --resume=<id>] \
[--model <name>] [--effort <level>] \
-p @<brief.txt>
```
The child process cwd pins the workspace. Only token-validated model/effort/session values and
fixed text reach the `shell:true` launch on native Windows; the brief is delivered via `-p @<file>`
(the CLI's @-prefixed file prompt channel), with the brief path quoted for the shell on Windows.
On resume (`--continue` / `--resume=<id>`) the relay wraps the reference in a fixed directive —
`Execute the instructions in the referenced file, then report what you did. Do not just summarize
the file: @<file>` — because a bare `@<file>` reference in a resumed session is echoed back instead
of executed (verified on copilot 1.0.78). The directive is relay-authored fixed text, so no user
content ever reaches the shell-quoted value on Windows. Fresh runs deliver the bare `@<file>`,
which copilot executes correctly.
Before dispatch the relay runs a bounded `copilot version` preflight (10s cap) so a
hung or crashing CLI fails fast and explicitly instead of hanging the run.
Copilot's JSONL events include ephemeral events (mcp status, skills_loaded, etc.) which the relay
skips, `assistant.message` events whose `data.content` becomes `finalMessage`, and a final
`result` event carrying `sessionId` and `usage.codeChanges`. Tool execution events with
`success: false` and `error.code: "denied"` trigger the denial-detection path.
## The commit boundary
The relay never commits. Copilot edits the working tree; the orchestrator reviews, re-runs the
gates, and commits. See [review-and-land.md](review-and-land.md).
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 |