Agy delegate

agy Delegate

You are the orchestrator. This skill lets you hand a bounded coding task to agy (the Antigravity CLI) as a background implementer, then review what it produced and land it yourself. You write the brief and own the judgment; agy does the typing; you verify and commit.

Base directory for this skill: the folder containing this SKILL.md — used to locate scripts/relay.mjs below.

When NOT to use this

• The task is small enough to just do inline (delegation overhead not worth it).
• agy is not installed or not authenticated (run agy at the terminal to check).
• You want to write the code yourself.

Prerequisites (check once)

which agy          # must print a path
agy --help         # must succeed

If agy is missing, tell the user to install Antigravity CLI first.

The loop (5 steps per task)

1. Write the brief

agy sees only the text you send — no repo memory, no chat history. Everything the task needs goes in the brief:

• The goal (one clear sentence)
• Current state (what exists, what's broken)
• What to change and what to leave untouched
• The project's actual gate commands (from CLAUDE.md/AGENTS.md/Makefile — do not assume)
• Explicit instruction: "Do NOT commit."
• A report contract: end your response with ## Changes Made listing every file touched and why

Keep one task per brief. Self-contained means a stranger who has never seen the repo can execute it correctly.

Brief template:

## Task
<one-sentence goal>

## Context
<current state — what exists, what's wrong>

## What to change
<specific instructions>

## What NOT to touch
<files/areas that are off limits>

## Gate commands (run these after making changes)
<e.g. npx tsc --noEmit, npm test, etc.>

## Constraints
- Do NOT commit.
- Do NOT change unrelated files.

## Report contract
End your response with:
## Changes Made
- <file>: <why it was changed>

2. Dispatch

Save the brief to a file, then run the relay:

# Basic dispatch (defaults: model=Claude Sonnet 4.6 (Thinking), timeout=30m)
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/brief.txt --cd /path/to/repo

# With a specific model
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/brief.txt --cd /path/to/repo \
  --model "Claude Opus 4.6 (Thinking)"

# With a custom timeout (e.g. for a long refactor)
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/brief.txt --cd /path/to/repo \
  --timeout 60m

# With sandbox mode (restricts terminal commands; does NOT prevent file edits)
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/brief.txt --cd /path/to/repo --sandbox

# Continue most recent agy conversation (send only a delta brief)
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/delta.txt --cd /path/to/repo --continue

# Resume a specific conversation
node "<skill-dir>/scripts/relay.mjs" --brief /tmp/delta.txt --cd /path/to/repo \
  --conversation <id>

<skill-dir> is the directory containing this SKILL.md. The relay streams agy's output live and writes structured artifacts to a temp dir (so the repo stays clean).

Options:

Flag	Default	Description
--model <name>	Claude Sonnet 4.6 (Thinking)	Model to use. Relay defaults to Sonnet for coding quality; override with e.g. "Gemini 3.5 Flash (Medium)" for speed.
--timeout <dur>	30m	How long print mode waits before giving up (Go duration: "30m", "90s", etc.). agy's own default of 5m is too short for real coding tasks.
--sandbox	off	Enable agy's terminal restrictions. NOTE: this restricts terminal commands only — it does NOT prevent file edits. Do not rely on --sandbox for a read-only or no-edits guarantee.
--continue	—	Continue the most recent agy conversation.
--conversation <id>	—	Resume a specific conversation.
--out-dir <dir>	system temp	Where to write run artifacts.

3. Wait for completion

Run the Bash call with run_in_background: true — you will be notified when it finishes.

The run is done when the process exits. The relay writes result.json on every outcome (completed, failed, agy_unavailable). A non-zero exit with no result.json is a usage error.

4. Review — do not trust the self-report

agy's output includes its own summary. Re-verify, don't accept:

• Run the project's gates yourself (the commands from step 1). Never take "tests pass" on faith.
• Read git diff — did agy do what was asked, nothing more and nothing less?
• Check touchedFiles in result.json as your starting point.
• For migration/schema changes, round-trip them; for removals, grep for dangling references.

5. Land it

The relay never commits. After gates pass and the diff looks right:

• Commit the verified work yourself with a clear message.
• If it needs changes, write a delta brief and re-dispatch with --continue (don't restate the whole task).

Available models

agy models

Current options include:

• Gemini 3.5 Flash (Medium) — fast, good for mechanical tasks
• Claude Sonnet 4.6 (Thinking) — best for complex reasoning
• Claude Opus 4.6 (Thinking) — highest quality, slower

Default: the relay uses Claude Sonnet 4.6 (Thinking) for coding quality. Override with --model when speed or cost matters more.

Non-negotiables

• Re-run the gates yourself. agy's self-report is a claim, not evidence.
• The orchestrator commits, never agy. Don't assume agy committed; it didn't.
• One task = one brief = one commit. Split unrelated work into separate runs.
• Surface design decisions. If agy made a defensible-but-unasked choice, report it to the user before landing.
• Stop for scope changes. If correct completion needs going beyond the brief, ask — don't expand.

result.json shape

{
  "schema": "agy-delegate.result.v1",
  "status": "completed | failed | agy_unavailable",
  "exitCode": 0,
  "workdir": "/path/to/repo",
  "model": "Claude Sonnet 4.6 (Thinking)",
  "sandbox": false,
  "resumed": false,
  "agyPath": "/Users/.../.local/bin/agy",
  "startedAt": "...",
  "finishedAt": "...",
  "briefPath": "/tmp/agy-delegate/.../brief.txt",
  "outputPath": "/tmp/agy-delegate/.../output.txt",
  "finalMessage": "<agy's full stdout>",
  "touchedFiles": ["M src/foo.ts", "A src/bar.ts"]
}

touchedFiles comes from git status --porcelain run after agy finishes — it reflects actual working tree changes, not agy's self-report.