amElnagdy/delegate-skills / skills/omp-delegate
omp-delegate
VerifiedDelegate a coding task to Oh My Pi (`omp`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to delegate implementation work to Oh My Pi / omp - phrasings like "have omp implement X", "delegate this to oh my pi", "run it through omp", "use oh-my-pi to implement/fix/refactor" - or wants to run a queue of coding tasks through omp 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 when they mean the original Pi CLI (`pi`) — that is pi-delegate.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.9 KB |
| references/dispatch-and-poll.md | markdown | 8.8 KB |
| references/multi-task-queues.md | markdown | 2.3 KB |
| references/review-and-land.md | markdown | 4.6 KB |
| references/writing-the-brief.md | markdown | 6.7 KB |
| scripts/relay.mjs | script | 32.1 KB |
references/dispatch-and-poll.md
View on GitHub# Dispatch and poll
`scripts/relay.mjs` wraps omp's non-interactive JSON print mode, captures its event stream, and
writes a `result.json`. Run one command, then read one file.
## Before the first run
```bash
command -v omp
omp --version
omp models # list models this install can run; then pass one id as --model
# omp models --json # machine-readable catalog
# omp models find sonnet
```
Do **not** run `omp --list-models`. That flag is a hard error.
Install with `bun install -g @oh-my-pi/pi-coding-agent`. Authenticate with `/login` inside omp
(subscription providers) or an API-key environment variable; omp stores credentials in `~/.omp/`.
## 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. A lane `effort` value becomes `--thinking`. |
| `--provider <name>` | omp `--provider` (default: omp's own default). Token-validated. |
| `--model <pattern>` | omp `--model` id or fuzzy pattern (default: omp's own default). Token-validated: letters, digits, `. _ : / -`. Pick the value from `omp models`, not from memory. |
| `--thinking <level>` | omp `--thinking`: `off`, `auto`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
| `--session <id>` | Resume a specific omp session (`--session` / `--resume`); send only the delta brief. A value is required — bare `--resume` would open omp's picker and hang. |
| `--resume-last` | Continue the most recent omp session for this cwd (`omp --continue`); send only the delta brief. |
| `--read-only` | Restrict omp to `--tools read,grep,glob`. |
| `--approve` | Load project-local `.omp` extensions, skills, and rules. The default passes `--no-extensions --no-skills --no-rules`. |
| `--timeout <dur>` | Relay watchdog (default: `30m`; h/m/s strings). The relay does not forward omp's `--max-time`. |
| `--out-dir <dir>` | Artifact directory (default: a fresh directory under the system temp dir). |
| `-h`, `--help` | Print the relay's header help. |
`--session` and `--resume-last` are mutually exclusive. The child cwd pins the workspace; omp's
`--cwd` is not passed. omp has no sandbox, so reachability is simply the filesystem.
A run without `--read-only` can write and execute anything the user account can: the relay passes
`--yolo` so print mode does not stall on tool approval. `--read-only` removes write/edit/bash (and
the rest of omp's default tool surface) from the callable tools; installed extension code still
runs with the user's host permissions when `--approve` is set.
The relay never forwards `--api-key`.
## 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 omp stdout events (the session header, then every agent event).
- `final.txt` - assistant text joined with a blank line between chunks; absent if none was emitted.
- `stderr.txt` - complete stderr.
- `result.json` - the stable `delegate-relay.result.v1` contract.
`result.json` fields:
- `schema`, `tool` (`"omp"`), `status` (`completed` | `failed` | `timeout` | `aborted` | `omp_unavailable`), `exitCode`, and
`signal` (`null` unless the child died on a signal).
- `workdir`, requested `provider`/`model`/`thinking`, `projectTrusted`, `readOnly`, `yolo`, `resumed`, `ompVersion`,
`sessionId`, `startedAt`, and `finishedAt`.
- `actualProvider`, `actualModel`, `usage`, and `stopReason` from omp's final assistant event.
- `briefPath`, `finalPath`, `eventsPath`, and `stderrPath`.
- `sessionId` - parsed from the JSON stream's `session` header. Resume with `--session <id>`.
Note: `--continue` may mint a new session id for the continued run; the result always reports
the id of the run that just happened.
- `finalMessage` - assistant text parts joined with `"\n\n"`; tool calls and tool results are
excluded.
- `touchedFiles` - `git status --porcelain` lines for the **final working tree under `--cd` only**,
not an attribution of omp's edits: anything already dirty before dispatch shows up too. Dispatch
from a clean tree when you want the list to read as "what omp changed". `null` means git could
not report; `[]` means git ran and the tree is clean.
- `stderrTail` - the last 20 non-empty stderr lines on any run that did not complete (`failed`,
`timeout`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`.
- `error` - present for launch failures, preflight failures, when the relay watchdog fires
(`timeout`), and on an `aborted` run.
omp's stream carries thinking and message-update events the relay archives but does not parse.
## 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 `omp` exits 127 and writes
`status: "omp_unavailable"`.
## When a run misbehaves
- **`status: "omp_unavailable"` (exit 127):** install omp (`bun install -g @oh-my-pi/pi-coding-agent`),
authenticate, and re-dispatch.
- **`status: "failed"`:** read `stderrTail`, `stderrPath`, and the tail of `events.jsonl`. Common
causes: an unknown `--model`, an expired login, or a provider error.
A final assistant event with `stopReason: "error"` or `"aborted"` is failed even if omp exits zero.
- **`status: "failed"` with an `error` mentioning `version preflight`:** the bounded `omp --version`
probe failed or hung, so omp was never dispatched. Check the install (`omp --version` yourself).
- **`status: "aborted"`:** the relay itself was killed (its parent's timeout, a stopped task, a
closed terminal) and forwarded the kill to omp. The result is written before the relay exits;
inspect the working tree before re-dispatching. On native Windows a hard kill of the relay is
uncatchable (Node supports no `SIGTERM` handler there), so this status may never get written -
a relay process that is gone without a `result.json` is an aborted run; inspect the working
tree and `events.jsonl` directly.
- **`status: "failed"` with `signal: "SIGKILL"`:** the host killed the process, commonly through
the OOM killer or a supervisor timeout. This is not an omp error; check host memory and
re-dispatch, or split the task into smaller briefs.
- **`status: "timeout"`:** the `--timeout` watchdog killed the run; `error` reads
`omp did not finish within --timeout <dur>; killed by the relay watchdog`. Increase `--timeout`
or split the task. On POSIX the relay sends SIGTERM to the process group, waits 10 seconds,
then sends SIGKILL if needed; on Windows there is no escalation phase — the whole process tree
is felled immediately with `taskkill /pid <pid> /t /f`.
- **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 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. Tool execution events carry the write/edit arguments, but treat any
reconstruction as unverified until it matches a working-tree diff — when the tree still holds the
work, preserve the tree rather than replaying the log.
## What the relay runs
The launch is equivalent to:
```bash
cat brief.txt | omp --mode json [--provider <name>] [--model <pattern>] [--thinking <level>] \
[--session <id> | --continue] [--yolo] \
[--no-extensions --no-skills --no-rules] [--tools read,grep,glob]
```
`--yolo` is omitted on `--read-only`. The three `--no-*` flags are omitted when `--approve` is
set.
The brief rides stdin, so it is not visible in the host process list and no argv size cap
applies. `omp` is a native binary (bun / install script / Homebrew), so the relay never launches
it through a shell. Before dispatch the relay runs a bounded `omp --version` preflight (10s cap)
so a hung or crashing CLI fails fast and explicitly instead of hanging the run.
## The commit boundary
The relay never commits. omp 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 |