Skip to content

amElnagdy/delegate-skills / skills/agy-delegate

agy-delegate

Verified

Delegate a coding task to the Google Antigravity CLI (`agy`) as a background implementer, then review its diff and land it yourself. Use this whenever the user wants to hand implementation work to Antigravity or agy - phrasings like "have Antigravity do X", "delegate this to agy", "run it through agy", or "use Antigravity to implement/fix/refactor" - or wants to run a queue of coding tasks through agy 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.

references/dispatch-and-poll.md

View on GitHub
# Dispatch and poll

`scripts/relay.mjs` is the dispatch layer. It wraps `agy --print`, runs the brief in Antigravity,
captures the final response, and writes a structured `result.json`. Your job collapses to: run one
command, then read one file.

## Before the first run: check the binary

```bash
command -v agy
agy help
agy models
```

`agy models` proves the CLI can authenticate and list available model labels. The relay records the
version it can infer from `agy changelog` into `result.json`. Neither command proves that a headless
write will be approved.

## Dispatching

```bash
node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
```

(`<skill-dir>` is wherever this skill is installed - the folder containing its `SKILL.md`.)

Options:

| Flag | Effect |
| --- | --- |
| `--brief <file>` | The brief. Omit it to read the brief from stdin before passing it to `agy --print`. |
| `--cd <dir>` | Working root for Antigravity (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>` | Antigravity model label. Optional; a fresh run can use Antigravity's configured default. |
| `--effort <level>` | Reasoning effort: `low`, `medium`, or `high` (passed as agy's own `--effort`). |
| `--project <id>` | Use an existing Antigravity project. |
| `--new-project` | Force a fresh Antigravity project. This is the default for fresh dispatches. |
| `--resume-last` | Continue the most recent Antigravity conversation; send only the delta brief. |
| `--conversation <id>` | Continue a specific Antigravity conversation; send only the delta brief. |
| `--sandbox` | Enable Antigravity's terminal sandbox for the run. |
| `--read-only` | Run under agy's sandbox with tool approval auto-granted inside it (`--sandbox --dangerously-skip-permissions`); reads and writes are both confined to the workspace — a write appears to succeed to the agent but is overlaid and discarded. Mutually exclusive with `--dangerously-skip-permissions` as a flag (that flag alone, without the sandbox, is full access). |
| `--dangerously-skip-permissions` | Pass Antigravity's permission-bypass flag; mutually exclusive with `--read-only`. Never use this unless the human explicitly accepts it. |
| `--print-timeout <duration>` | Timeout agy itself applies to print mode (default: `30m`). |
| `--timeout <dur>` | Relay-side watchdog (e.g. `30m`); overrides the default of `--print-timeout` plus a 60s grace. On expiry the agy process tree is killed and `result.json` gets `status: "timeout"`. Set it explicitly when agy may hang past its own print timeout. Malformed, zero, and out-of-range durations are rejected; the maximum is `596h31m23s`. |
| `--stall-timeout <dur>` | Opt-in stall watchdog (e.g. `5m`; off by default). If `agy.log` gains no new `streamGenerateContent` line for this long, the agy process tree is killed and `result.json` gets `status: "stalled"`. The clock starts at launch and restarts on every generation call, so it catches a run that lost its stream and only re-runs auth and model-discovery handshakes while the log keeps growing. Set it above the longest tool step you expect: a long test run makes no generation calls. It keys on agy's log format, which agy does not document as stable. Validated like `--timeout`. |
| `--add-dir <dir>` | Add an extra workspace directory. Repeatable; relative paths resolve against `--cd`. Fresh runs always add the `--cd` repo (absolute path) as a workspace dir. Edits inside extra workspaces are not reported in `touchedFiles`. |
| `--out-dir <dir>` | Where artifacts go (default: a fresh dir under the system temp dir). |

Artifacts default to the system temp dir on purpose: the repo under review stays clean, so the
touched-files report shows only Antigravity's edits and nothing of the helper's own.

## The result

`<out-dir>/result.json` is the contract. Fields:

- `schema` - the result-format version (currently `delegate-relay.result.v1`)
- `tool` - `agy`
- `status` - `completed` | `failed` | `timeout` | `stalled` | `aborted` | `agy_unavailable`
- `exitCode` - mirrors Antigravity's exit code; `128` plus the signal number if the child was killed; `127` if `agy` is not on PATH; on a `timeout` or `stalled` run the relay forces a non-zero code even when the child exited `0` after the watchdog's SIGTERM
- `signal` - the signal that killed the child, otherwise `null`
- `agyVersion` - inferred from `agy changelog` when available
- `projectId` / `conversationId` - parsed from the Antigravity log when present
- `finalMessage` - Antigravity's stdout response
- `touchedFiles` - `git status --porcelain` lines in the working root: your review starting point.
  `null` (not `[]`) when git cannot report; `[]` means git ran and the tree is clean
- `readOnlyViolation` - `true` when fingerprints prove a working-tree change, `false` when coverage is complete and proves none, and `null` when fingerprinting was incomplete or the run was not `--read-only`
- `briefPath` / `finalPath` / `logPath` / `stderrPath` - the exact brief, final message, Antigravity
  log, and stderr capture
- `workdir`, `model`, `effort`, `stallTimeout` (the `--stall-timeout` you passed, or `null`), `project` (the `--project` you passed, vs `projectId` parsed from the log),
  `sandbox`, `readOnly`, `dangerouslySkipPermissions`, `resumed` (true for a `--resume-last` or `--conversation`
  run), `startedAt`, `finishedAt`
- `stderrTail` - last ~20 stderr lines; present on every run that did not complete (`failed`, `timeout`, `stalled`, `aborted`), except a launch failure, which reports `failed` with no `stderrTail`; also present when `finalMessage` is empty so diagnostics are not discarded
- `error` - present on a launch failure, `timeout`, `stalled`, `aborted`, headless permission denial, silent no-op, or abandoned background tasks without edits

The helper also prints a summary to stdout and normally exits with Antigravity's exit code. It forces
exit 1 when Antigravity exits 0 after a detected headless permission denial or with neither a final
message nor observable working-tree changes, so a wrapping script can branch on success/failure directly.
It also forces exit 1 for a write-capable run that terminates pending background tasks on exit when
Git fingerprints confirm no working-tree changes, even if `finalMessage` says it is waiting.
If Git cannot fingerprint the directory, that diagnostic alone does not fail a run with a final message. Read `error` and `stderrTail`,
then re-dispatch with a brief requiring synchronous commands and a reply only after they finish
(see [writing-the-brief.md](writing-the-brief.md)).

## Waiting for completion

The helper blocks until Antigravity finishes. Back it with whatever your orchestrator offers:

- **Claude Code:** run the Bash call with `run_in_background: true`; you're notified on completion,
  then read `result.json`.
- **Plain shell / other agents:** foreground for short tasks, or background and poll. A run is done
  when `result.json` exists with a `status`. A pre-run usage error exits with code 2 before writing any
  file, so check the exit code too. A missing `agy` binary exits 127 and writes `result.json` with
  `status: agy_unavailable`.

Trust the working tree and the process state over any progress display. A run is finished when the
process has exited and `result.json` is written.

## When a run misbehaves

- **`status: agy_unavailable` (exit 127):** `agy` is not on PATH. Install the Antigravity CLI and run
  its first-launch setup, then re-dispatch.
- **`status: timeout`:** the relay watchdog killed the run. Inspect `error` to see whether the selected
  limit was explicit `--timeout` or the derived `--print-timeout` plus 60s grace. The working tree may
  hold a half-applied change — inspect it before changing that limit, reducing the brief, or resuming.
- **`status: stalled`:** the `--stall-timeout` watchdog killed a run that stopped making generation
  calls. This usually means agy lost its stream, not that the brief was too large, and the working tree
  often holds nearly finished work. Review it and finish the rest with a short delta brief (e.g.
  `--conversation <id>`) instead of re-dispatching the whole task. If the run was really in a long
  tool step, raise `--stall-timeout` above that step.
- **`status: aborted`:** the relay itself was killed (its parent's timeout, a stopped task, a
  closed terminal) and forwarded the kill to agy. 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 ended the child - commonly the OOM killer
  or a supervisor timeout, not an implementer error. Free up host memory or split the task into
  smaller briefs, then re-dispatch.
- **`status: failed`:** read `result.json`'s `stderrTail`, `stderrPath`, and `logPath` for the cause.
  Common causes: auth lapse, an unknown model label, timeout, or a permission the run needed.
- **Headless write permission denied:** the relay detects Antigravity's `no output produced ...
  auto-denied` stderr sentinel, reports `status: failed`, preserves `stderrTail`, and exits 1.
  Allow-rule matching and location vary by `agy` version and platform — a bare `command(<name>)` rule
  was insufficient on Windows/agy 1.2.5 but did work on macOS/agy 1.2.0 — so measure before assuming;
  see [Permission engine traps](#permission-engine-traps) below before re-dispatching or asking to use
  `--dangerously-skip-permissions`.
- **Empty `finalMessage`:** a run with edits may still be correct - check `touchedFiles`, the diff, and
  the preserved `stderrTail`. With no observable edits, the relay reports `status: failed` rather than
  claiming completion. To get a report next time, add a `<structured_output_contract>` block (see
  [writing-the-brief.md](writing-the-brief.md)).

## What the helper is doing

Under the hood the helper runs roughly:

```bash
agy --new-project --add-dir <repo> --print-timeout 30m --print=<brief>
agy --continue --print-timeout 30m --print=<delta brief>
agy --conversation <id> --print-timeout 30m --print=<delta brief>
```

`agy --print` requires the prompt as a flag argument, so keep briefs focused. The relay still accepts
stdin or `--brief <file>` for your convenience; it reads the text first, then passes it to `agy` as
`--print=<brief>` (the `=` form so a brief that begins with a bare flag like `--help` still runs).
Two consequences of the brief riding the command line: it is visible in the host process list (`ps`),
so on a shared machine keep secrets out of it; and a brief over ~120 KB is rejected up front (the OS
caps a single argument), so have `agy` read large context from the workspace instead of inlining it.

## The commit boundary

The helper never commits - by design, not omission. The robust contract is: Antigravity edits the
working tree, the orchestrator reviews and commits. See [review-and-land.md](review-and-land.md).

## Permission engine traps

When a headless `--print` run needs a permission `agy` cannot prompt for, it is auto-denied. `agy`'s own
error message advises adding an allow-rule under `permissions.allow` in
`~/.gemini/antigravity-cli/settings.json`, e.g. `command(<target>)`. That instruction is incomplete
in measured ways, and what breaks varies by version and platform: following it literally still failed
on a plain, spaceless command like `git status` on the machine that documented these traps (Windows,
agy 1.2.5), while the same bare rule worked on macOS with agy 1.2.0.

### Exact-match rules don't cover real commands (measured on Windows, agy 1.2.5)

`command(<name>)` matches an exact command line, not a prefix. `command(git)` allows only a bare `git`
invocation with zero arguments - not `git status`, not anything a real task actually runs. This is the
first thing to check on *any* denial, before suspecting the Windows bug below: use
`command(regex:git .+)` (or a narrower pattern for a specific subcommand) to match real invocations.
Source: [issue #614 comment](https://github.com/google-antigravity/antigravity-cli/issues/614#issuecomment-5466617752).

Measured on macOS with agy 1.2.0, the opposite held: `command(git)` alone in
`~/.gemini/antigravity-cli/settings.json` allowed a real `git status` through a headless relay
dispatch (the identical brief with no rule was auto-denied). Treat exact-match behavior as version-
and platform-dependent, and test your own denial before assuming either way.

### Executable path splitting (Windows)

The permission engine splits a resolved executable path on whitespace before matching, so a binary
living under a path containing a space is evaluated as its first fragment. `node`, `git` and `npm`
installed under `C:\Program Files\...` are all evaluated as `C:\Program`, and no `command(<name>)` rule
- regex or not - matches any of them this way. This makes `git` the single most common trigger in
practice: it ships under `C:\Program Files\Git\...` by default on Windows, and nearly every delegated
coding brief runs `git status` at least once to check its own work. Measured directly on Windows 10 with
agy 1.1.12: with `command(node)` present in the allow list, a brief whose verification loop ran
`node --check` was auto-denied anyway.

### Which config file agy actually reads

`agy`'s denial message points at `permissions.allow` in `~/.gemini/antigravity-cli/settings.json`.
Verified live on agy 1.2.5 on Windows: that file's `permissions` key was not what took effect - the
CLI's own log reported it as `permissions=<nil>` for that file, while a separate rule added under
`userSettings.globalPermissionGrants.allow` in **`~/.gemini/config/config.json`** was the one that
unblocked a denied `git status` call once written as `command(regex:git .+)`. A rule added to
`antigravity-cli/settings.json` in the exact form `agy`'s own message and error text describe did not
unblock the same call. This may be version- or platform-dependent; re-verify which file actually
applies before relying on this if you're on a different `agy` version, but don't assume the file
`agy` names in its own error is the one to edit.

Measured on macOS with agy 1.2.0, both files' rules took effect in live relay runs:
`command(regex:git .+)` unblocked a denied `git status` from either `antigravity-cli/settings.json`'s
`permissions.allow` or `config.json`'s `userSettings.globalPermissionGrants.allow`. The divergence
between installs is real, so the only reliable rule is the one above: verify which file your install
actually reads before trusting `agy`'s own error text.

### Write file glob error

Upstream issue #614 also reports that a glob in a `write_file` rule - `write_file(C:\path\*)` - raises "globs not supported"
and blocks the agent's actions entirely. Directory rules are recursive already, so the glob is unnecessary as well as harmful.

### Workarounds and caveats

- **Command permissions:** combine the two fixes above - `command(regex:<name> .+)` in
  `~/.gemini/config/config.json`'s `globalPermissionGrants.allow` (verified on agy 1.2.5; on macOS
  with agy 1.2.0 the same regex in `antigravity-cli/settings.json` also unblocked the call) covers both
  the exact-match trap and, since it doesn't depend on matching a resolved executable path, the
  Windows path-splitting bug too. `command(*)` (documented in issue #614) is the broader fallback if a
  targeted regex still doesn't match - it approves all command execution, so treat it the same as
  `--dangerously-skip-permissions` for that run.
- **Directory permissions:** Write directory paths literally without a wildcard, e.g. `write_file(C:\path)`.

If settings allow-rules cannot resolve the denial, ask the human before re-dispatching with `--dangerously-skip-permissions`;
that flag auto-approves every tool permission request and the run must be treated as full access.
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 implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall