agy-crew 0.0.0-stage → 0.9.2

package/opencode-skills/agy-crew-accounts/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: agy-crew-accounts
+description: Manage the agy account pool - list accounts, read quota and cooldown state, import, enable, disable, remove, and guide interactive sign-in. Use when the user asks "which agy accounts are available", "add an agy account", "agy quota", "why is the agy account cooling down", or "remove/disable an agy account". This is an operations skill for the pool; the persona skills select accounts automatically.
+---
+
+<!-- Generated from skills/accounts/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy accounts
+
+Inspect and manage the pool of agy accounts that background jobs run on. Pool state is global per user (`~/.agy-crew/pool.json`, overridable with `AGY_CREW_HOME`), not per repository.
+
+This file lives at `<plugin-root>/opencode-skills/agy-crew-accounts/SKILL.md`:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" accounts <subcommand> [args]
+```
+
+> [!IMPORTANT]
+> Run this command **unsandboxed**, like every companion command. Details: `../agy-crew-jobs/references/troubleshooting.md`.
+
+## Live and pool accounts
+
+- **live** is the user's own agy login. It is never part of the pool: `auto` never picks it, it never lends credentials and never borrows. It runs only when explicitly requested (`--account live`) or when the pool has no enabled account, so an empty pool behaves exactly as before.
+- **Pool accounts** are named, private agy logins stored under `~/.agy-crew/accounts/<name>/home`. Runs pick one automatically; the user does not need to name it.
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `accounts list [--json]` | Every account with its state, last use and cached quota summary, plus a line for live. Start here. |
+| `accounts quota [<name>...] [--refresh] [--json]` | Cached quota snapshots and cooldowns. `--refresh` queries Google's Cloud Code service and updates the snapshots; it is the only subcommand that uses the network. |
+| `accounts import <name> --home <dir>` | Copy the token (and `settings.json`) from an existing HOME-shaped directory, for example an agy-cli-manager account. |
+| `accounts enable <name>` / `accounts disable <name>` | Put an account into or out of automatic selection. |
+| `accounts cooldown clear <name> [--family <f>]` | Drop a recorded quota cooldown. Use it only when the user says the quota is back. |
+| `accounts remove <name> [--yes]` | Delete an account. Without `--yes` it only prints what would be deleted. |
+| `accounts login <name>` | Interactive sign-in. **Do not run this yourself**, see below. |
+
+Add `--json` when you need to parse the output; otherwise read the table.
+
+## Adding an account
+
+`accounts login <name>` opens a browser sign-in and waits for the user to exit agy. It cannot work from a background or sandboxed command. Tell the user to run this in their own terminal:
+
+```bash
+agy-crew accounts login <name>
+```
+
+If the `agy-crew` command is not on their PATH, give them the full `node "<skill-dir>/../../companion/agy-companion.mjs" accounts login <name>` line instead. Then run `accounts list` to confirm the account shows as ready. Names are lowercase letters, digits, `.`, `_` and `-`; `live` and `auto` are reserved. The same Google account cannot be added twice. To refresh an expired sign-in, the user runs the same login command for the existing name.
+
+If the user already has accounts elsewhere, offer `accounts import` instead of a new sign-in; it copies files and needs no browser.
+
+## Reading the state
+
+| State in `list` | Meaning | Action |
+| --- | --- | --- |
+| `ready` | Idle and usable | None. |
+| `busy n` | `n` runs hold it | Normal. A new `auto` run prefers an idle account. |
+| `cooling <family> until <t>` | That model family hit its quota; other families still work | Wait until `<t>`, use another model family or account. Do not clear the cooldown on your own. |
+| `needs login` | agy rejected the credential | Tell the user to run `agy-crew accounts login <name>`. Never retry. |
+| `disabled` | Excluded from selection | `enable` only if the user asks. |
+
+Cooldowns are per account and per model family (for example `gemini-3.8-flash`, whatever the effort suffix). Quota snapshots show the short-window and weekly remaining fraction per quota pool; they are cached, so `quota --refresh` is needed for current numbers. Refresh only when the user asks about current quota or a run failed with a quota error, not for routine checks.
+
+## Choosing an account for a run
+
+Run commands accept `--account auto|live|<name>` (default `auto`, or the `AGY_CREW_ACCOUNT` environment variable):
+
+- `auto` picks an idle ready account, then the one with the most known quota left. With no enabled pool account it uses live.
+- `<name>` forces that account; it fails when the account is unknown, disabled, cooling or needs login.
+- `live` forces the user's own login.
+
+A conversation stays bound to the account that created it; continuing it with a different explicit `--account` is refused. Quota handling during runs is described in `../agy-crew-jobs/SKILL.md`.
+
+## Rules
+
+- `remove` is destructive: it deletes the account's stored login, its conversations become unusable, and re-adding needs a new sign-in. Run it without `--yes` first, show the user what would be deleted, ask with `AskUserQuestion`, and add `--yes` only after an explicit yes. `remove`, `login` and re-login refuse while the account is in use.
+- Never read or print token files under `~/.agy-crew/accounts/`.
+- Do not create, import or remove accounts unprompted. Report the pool state and let the user decide.
+- Quote companion errors exactly and add a concise diagnosis. Exit 0 is success, 1 is an error.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-ask/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: agy-crew-ask
+description: Ask Google's Antigravity CLI (agy staffer, fast Gemini) a cheap one-shot question - the fast zero-tool mode and the post-install smoke test. Use when the user says /agy-crew-ask, "ask agy", "quick second opinion from agy", or right after installing to verify the plugin works.
+---
+
+<!-- Generated from skills/ask/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy ask
+
+The quick mode: one question in, one answer out, ~3 seconds on the default `gemini-3.8-flash-low`. Zero tools by design (restricted profile, question-only prompt), so it needs no setup and works on a fresh install — run it first as the smoke test: `ask --prompt "reply with OK"`.
+
+ask is the only persona that runs in the foreground: the call blocks and the answer comes back on stdout. staffer, researcher, reviewer, and implementer instead return a background job id (see the jobs skill, `../agy-crew-jobs/SKILL.md`).
+
+## Locating the companion
+
+This skill file lives at `<plugin-root>/opencode-skills/agy-crew-ask/SKILL.md`; resolve the companion path relative to this skill directory:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" ask [flags] --prompt "question"
+```
+
+Pass the user's question verbatim via `--prompt`; use `--prompt-file <path>` or `--stdin` for a long question.
+
+> [!IMPORTANT]
+> Run this command **unsandboxed** — agy needs a localhost port and its OAuth token file, which harness sandboxes hide. In Codex, request escalated permissions for the command. Details: `../agy-crew-jobs/references/troubleshooting.md`.
+
+## Flags (all optional)
+
+- `--prompt <text>` / `--prompt-file <path>` / `--stdin` — the question, from exactly one of these three sources. Use file/stdin for a long question.
+- `--continue` — reuse the last ask conversation; `--conversation <id>` targets a specific one.
+- `--model <id>` or `--effort low|medium|high` — default model is `gemini-3.8-flash-low`.
+- `--timeout <dur>` — default 2m.
+
+ask is always restricted (it is tool-free, so there is nothing to unrestrict); `--unrestricted` is ignored with a note on stderr. That is fixed for ask alone — the tool-using personas default to unrestricted, where `--restricted` is an opt-in hardening flag. Execution style is likewise fixed per mode and no flag changes it.
+
+## Rules
+
+- Pass the user's question through verbatim and return the answer verbatim. The `[agy-crew]` telemetry line arrives on stderr and is metadata for you, the calling agent — do not show it to the user; mention the follow-up ability in natural language when relevant, and give model/duration/token numbers only if asked.
+- If the answer says "not sure", relay it as-is; do not silently substitute your own answer.
+- Exit 5 means a resumable response timeout: explain it and ask whether the user wants to continue with the suggested timeout or stop. Continue only after explicit user confirmation, using the recorded conversation and configuration. For other companion errors, quote the error and add a concise diagnosis. Full failure protocol: `../agy-crew-jobs/SKILL.md`.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-implementer/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: agy-crew-implementer
+description: Delegate a coding task to Google's Antigravity CLI (agy staffer, fast Gemini), which edits the working tree directly and can perform explicitly requested Git delivery. Use when the user says /agy-crew-implementer, "have agy fix/build X", or wants to hand a well-scoped coding task to the agy staffer instead of doing it in the host model.
+---
+
+<!-- Generated from skills/implementer/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy implementer
+
+Hand a coding task to the agy staffer. agy edits the real working tree under its unrestricted permission profile; the companion is a thin launcher and job collector. Pass the user's requested delivery through in the task text instead of doing Git work yourself.
+
+## Locating the companion
+
+This skill file lives at `<plugin-root>/opencode-skills/agy-crew-implementer/SKILL.md`; resolve the companion path relative to this skill directory:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" implement [flags] --prompt "task description"
+```
+
+Pass the user's task description verbatim via `--prompt`; use `--prompt-file <path>` or `--stdin` for long text.
+
+> [!IMPORTANT]
+> Run this command **unsandboxed** — agy needs a localhost port and its OAuth token file, which harness sandboxes hide. In Codex, request escalated permissions for the command. Details: `../agy-crew-jobs/references/troubleshooting.md`. (The companion passes `--dangerously-skip-permissions` to agy in this mode — that is the unrestricted profile working as designed.)
+
+## Workspace and delivery
+
+- Inside a git repository, dirty workspaces are allowed. When `git status --porcelain` is not clean, the companion injects a bounded pre-run status summary into the implement prompt so agy treats those paths as user-owned context.
+- Outside a git repository the companion warns that agy's edits cannot be reviewed or rolled back via git, and proceeds. Relay that warning; there is no diff to fall back on.
+- By default, agy leaves a working-tree diff. If the user explicitly asks for a commit, push, or PR, include that request verbatim in the task text and let agy do that exact Git delivery.
+- After the run, surface agy's summary and the current workspace state. Do not add your own commit/PR step unless the user separately asks you to do it.
+
+## Collecting the result
+
+The command returns a job id. Read `../agy-crew-jobs/SKILL.md` for result collection and recovery: dispatch, wait for the final result, then validate as needed. Do not proactively observe progress, read logs or inspect intermediate artifacts while running. Observe only when the user explicitly asks for progress; diagnose a failure or a result requiring intervention under the jobs protocol.
+
+## Flags (all optional)
+
+- `--restricted` / `--unrestricted` — permission profile. implement defaults to unrestricted, so it works out of the box with no setup. `--restricted` is the opt-in hardening path: agy may then only use allowlisted tools, so it can usually only propose rather than edit, and it needs the setup flow's evidence-gathering allowlist to be useful.
+- `--continue` (or `--conversation <id>`), `--model <id>` / `--effort low|medium|high` (default `gemini-3.8-flash-high`), `--timeout <dur>` (default 60m, maximum 120m hard execution limit), `--account auto|live|<name>` (default `auto`, the pool; see `../agy-crew-accounts/SKILL.md`).
+- `--prompt <text>` / `--prompt-file <path>` / `--stdin` — the task, from exactly one of these three sources. Use file/stdin for long prompts.
+
+## Rules
+
+- Do not pre-implement, extend, or "clean up" agy's changes without user confirmation.
+- Return agy's summary verbatim before presenting the diff.
+- Pass the user's explicit authorizations through to the task string verbatim. The prompt template default-denies costly or irreversible side effects; that default opens only when the request itself asks for the operation — so keep "open a draft PR", "run the e2e tests", or "call the staging API" in the prompt instead of trimming it.
+- Never commit agy's changes yourself unless the user explicitly asks you, the host agent, to do it.
+- For errors and recovery, follow `../agy-crew-jobs/SKILL.md`.
+
+For an existing conversation, `--continue` / `--conversation <id>` inherit its recorded model and permission profile unless explicitly overridden. The unrestricted defaults above apply to new tasks.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-jobs/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: agy-crew-jobs
+description: Manage agy staffer background jobs - collect results, check status, cancel, follow-up conversation, and setup. Use when an agy job needs collecting, when the user asks "is the agy job done", "show agy's result", "cancel the agy job", "continue the agy conversation", or "set up agy". This is the orchestrator's skill; the persona skills (staffer/researcher/reviewer/implementer) point here.
+---
+
+<!-- Generated from skills/jobs/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy jobs
+
+Manage background staffer/research/review/implement jobs. State is per repository in `.agy-crew/`. Only ask runs synchronously.
+
+This file lives at `<plugin-root>/opencode-skills/agy-crew-jobs/SKILL.md`:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" <command> [args]
+```
+
+## Collect the result
+
+Default flow: prepare the prompt → dispatch → wait for the final result → validate as needed. While a job is running, do not proactively call `observe`/`status`, read logs or inspect intermediate artifacts. Do not query progress for routine updates or create sleep/observe loops. Observe only when the user explicitly asks for progress; diagnose after receiving a failure or a result requiring intervention.
+
+1. Keep the returned job id. Start `wait <id> --timeout 10m` in the background, using the same unsandboxed context as launch. Use a separate wait for each job; never wait for several jobs serially in one shell.
+2. For **wait**, branch on the exit code:
+
+| Code | Meaning | Next action |
+| --- | --- | --- |
+| 0 | Invocation ended; response text delivered | Assess whether it satisfies the task. Review attached diagnostics; inspect further only as needed. |
+| 2 | Still running; wait soft-expired | Wait again for the same job. The attached snapshot is not a request to inspect progress or intervene. |
+| 3 | Error or crash | Read the error and recovery information below. |
+| 4 | Canceled | Complete any already-authorized follow-up; otherwise report cancellation. |
+| 5 | Attention: resumable timeout | Inspect partial workspace changes; ask whether to continue with the suggested timeout or stop. Continue only after explicit user confirmation. |
+| 1 | Invalid command or other command error | Quote the error and correct the named problem. |
+
+`done` describes invocation and response delivery, not task acceptance. Preserve agy-cli response text and diagnostics; a nonempty response may only acknowledge launched background work. Successful calls with warnings include a bounded log tail on stderr and a full-log pointer. The orchestrator assesses the response and artifacts, uses `observe` or diagnostics if the returned result needs investigation, and decides whether to propose continuation. Keep the recovery confirmation rules below; do not infer timeout from response wording or add routine progress polling.
+
+When the user explicitly asks for progress, use `observe <id>` and answer from that snapshot, keeping any pending wait open. An already returned snapshot may answer the question; do not duplicate it or turn one question into recurring observation.
+
+Collecting a pending wait command is necessary result collection, not active observation. Host collectors (for example, Codex `write_stdin`) return that command's output; an outer `functions.wait` resumes a yielded `functions.exec` call. They do not independently read AGY progress. Prefer background completion delivery; if host collection requires polling, use a long supported blocking wait rather than short empty polls or sleep loops. Keep the same pending command until it returns; only restart `wait` for the same job after exit 2.
+
+A wait expires without stopping the worker. Cancel only when the task calls for stopping; silence or soft expiry alone is not a reason. For a user-requested progress answer or diagnosis after failure/required intervention, read a bounded `details` excerpt only if the returned information leaves a specific question unanswered. Never inspect logs or intermediate artifacts for routine reassurance.
+
+When using lead, let the lead assess and synthesize the results. For direct persona invocations, deliver short results verbatim; summarize long results with their file path. Keep quoted verdicts, numbers and errors exact. For implement, also report the workspace state and inspect changes with `git diff`; verify any Git delivery that the user explicitly requested.
+
+Follow through to a result unless the user asked only to launch. If the host cannot deliver background command results, use the longest practical wait within its tool-call limit (bare `wait` defaults to 100s). The host controls when the model receives a tool result; this plugin cannot schedule a future model invocation by itself.
+
+## Other commands
+
+| Command | Purpose |
+| --- | --- |
+| `observe [id]` | On an explicit user progress request, or for diagnosis after failure/required intervention: bounded JSON with progress or terminal metadata and recovery pointers. Never returns report text. |
+| `status [id]` | List jobs or show one job's state and log tail. |
+| `result [id]` | Reprint stored output; default to the latest finished job. |
+| `cancel <id>` | Stop that job's execution. Interrupting wait does not cancel it. |
+| `continue --job <id> --prompt "..."` | Resume the job's conversation with its original mode/model/profile; create a linked new job. |
+| `continue --prompt "..."` | Continue the latest conversation; `--conversation <id>` selects a known older one. |
+| `restart <id>` | Start the original task/configuration again without its conversation; create a linked new job. |
+| `setup [--apply] [--restrict <modes\|none>]` | Optional permission setup; read `references/setup.md` first. |
+
+Wait/observe default to the latest job. Observe uses the same status exit codes, but exit 0 means **finished, not full result delivered**. Collect the existing wait session, or use `result <id>` if none is pending; do not start another wait or expect observe to consume the pending session. Failed/canceled/attention observations provide bounded recovery metadata; wait/result deliver the full report. A continued ask remains synchronous. `result` also returns exit 5 for attention (its legacy exit behavior for other terminal states is unchanged).
+
+Continuation and restart may be invoked from the root or any subdirectory of the same worktree; execution returns to the original cwd. Generic `continue` fails for an unrecorded conversation ID. It does not search other worktrees or infer configuration from an unrelated conversation. For continuation, explicit model/profile flags override the inherited values.
+
+`status`, `result` and `observe` show the account that ran the job. A conversation stays bound to that account: `continue` reuses it, and a conflicting explicit `--account` is refused. `restart` starts a fresh conversation, so it selects an account again. Account management itself is in `../agy-crew-accounts/SKILL.md`.
+
+Cancel records a request first and returns success only after the worker has stored the cancellation report and published `canceled`. A crashed job keeps its crash diagnostics. A cancellation error requires inspection; it does not mean execution has stopped.
+
+## Follow-up instructions
+
+Use `continue --job <id>` to target an existing AGY conversation. It starts a new invocation once the current execution has stopped. While that job is still running, the companion refuses the follow-up with exit 1, reporting the job ID and status; nothing is queued. Decide whether to wait or cancel.
+
+- **Finished:** continue directly with the next assignment or revision.
+- **Running, feedback can wait:** collect the current result, then continue.
+- **Running, direction must change now:** cancel the active job, confirm termination, then continue with the updated brief. An already-authorized change of direction does not require another confirmation solely for this sequence.
+
+Include relevant decisions made in the host conversation, what changed, and what the worker should do next. After interruption, reconcile partial artifacts before repeating work: cancellation does not roll back edits, and the conversation may not contain the last interrupted step. If no usable conversation exists, start a fresh task with the updated brief and retained work. Timeout recovery still follows the rules below.
+
+## Quota and account failures
+
+With a pool configured, the companion handles quota inside the run: it records a cooldown for that account and model family, and either fails over to another account (when no conversation existed yet) or borrows an idle account's credential to continue the same conversation. Nothing for you to do when the job still finishes `done`.
+
+- **`quota_exhausted`** (status `attention`, exit 5, when a conversation exists; otherwise `error`) means no account could continue. The result and `observe` include `retry_at`. Report it, keep the job id, and offer `continue --job <id> --prompt "..."` after `retry_at`, or sooner once `accounts list` shows another account idle (a credential loan is then used automatically). Ask before continuing, as with a timeout. Never loop retries and never clear a cooldown yourself. Without a conversation, a new run with `--account auto`, `--account live` or another model family is the alternative; propose it to the user.
+- **`needs login`** (an authentication failure on a pool account) is not retried. Tell the user to run `agy-crew accounts login <name>` in their own terminal; it opens a browser, so you must not run it.
+- An unknown, disabled or cooling explicit `--account <name>` fails before launch with the reason; use `auto` or another account.
+
+## Progress and recovery
+
+Progress contains up to five recent tool calls, input/output excerpts, and the latest response text. Timestamps, incomplete text and truncation are labeled. It is a snapshot, not a judgment of useful progress. Reads do not consume history or reset deadlines. Payload limits and file layout are in `../../docs/REFERENCE.md`.
+
+The worker has a separate hard limit: default 60m, configurable with launch `--timeout` up to 120m. AGY receives the same response timeout; the worker independently enforces the overall budget, including initialization. At that limit it stops execution. If response text has already arrived, it delivers that text with a warning for the orchestrator to assess; otherwise it reports `hard_timeout`, the last snapshot, logs, known conversation ID and original configuration. Before recovery, inspect `git status` and `git diff` so partial changes are accounted for. Prefer `continue --job` when a conversation exists; otherwise use `restart`. Each creates a fresh 60m budget unless `--timeout` is specified, and preserves the old terminal record. Restart refreshes workspace context; older specifications explicitly label historical snapshots and append current context. An empty response at either the AGY response deadline or worker hard limit becomes `attention` (exit 5) when a conversation ID is known, otherwise `error`. The response-timeout classifier accepts explicit TIMEOUT statuses and AGY's exact `ERROR` / `timeout waiting for response` payload; unrelated tool/network/auth/quota errors keep their own failure path. The report includes pre-run/current workspace status, original configuration and an exact continuation command with a doubled timeout capped at 120m for background jobs. At that ceiling, offer a narrower task. Ask the user whether to continue or stop and inspect; do not automatically retry, restart or continue after a timeout. Run the proposed recovery only after explicit user confirmation. A wait soft expiry is still exit 2 and requires no new execution.
+
+Warning-free success removes intermediate stream/snapshot files after results are stored. Errors, cancellation, hard timeout and warning results retain them; results, logs and conversation metadata remain available. Older jobs may have no progress files.
+
+Quote errors and add a concise diagnosis. For sandbox/permission errors or an apparent crash without a result, check that collection uses the same unsandboxed context as launch; see `references/troubleshooting.md`. For restricted empty responses, relay the companion's permission guidance. Do not switch repositories to bypass a precondition.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-jobs/references/setup.md

@@ -0,0 +1,41 @@
+<!-- Generated from skills/jobs/references/setup.md; run npm run generate:opencode. Do not edit here. -->
+
+# setup — optional hardening for restricted runs
+
+staffer, research, review, and implement default to unrestricted and work with no setup. Run setup only when the user wants restricted runs — per call (`--restricted`) or by default in this repository. Restricted runs keep AGY's permission engine active (ask is tool-free and needs no command rules).
+
+## Flow
+
+**Step 1 — status + dry run.** Shows the current per-repo policy, the allow/deny rules state, and the plan without writing anything:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" setup
+```
+
+If it reports the agy CLI itself is missing, stop and relay its install guidance — do not attempt to install agy yourself.
+
+**Step 2 — per-repo policy.** Ask the user with `AskUserQuestion` (multiSelect over `staffer`, `research`, `review`, `implement`, plus a "None — keep the defaults (Recommended)" option): which modes should default to the **restricted** profile in this repository? Make clear this is a per-repo, per-machine preference (`.agy-crew/config.json`, git-ignored, not shared with the team), that a `--restricted`/`--unrestricted` flag on a call still overrides it, and that it is a run policy, not a security boundary — untrusted input still calls for an isolated checkout. Then apply their answer:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" setup --restrict review,research   # their selection
+node "<skill-dir>/../../companion/agy-companion.mjs" setup --restrict none              # if they chose none
+```
+
+If they chose none AND the step-1 output shows the allow/deny rules already installed, you are done — skip to the final report.
+
+**Step 3 — allow/deny rules.** If any mode is restricted (by policy or because the user wants `--restricted` runs) and rules are missing, present the step-1 dry-run output in full: which rules would be added, to which file, and that the file is backed up first. Be explicit about two things before asking for confirmation:
+
+- **Scope is global.** The rules go into agy's global settings file, so they apply to every project on this machine, not just this repository.
+- **AGY owns rule enforcement.** Setup allows broad `git`/`gh` commands and adds five deny prefixes: `git push`, `git reset --hard`, `git clean`, `gh pr merge`, and `gh release delete`. AGY evaluates deny before ask before allow. This avoids maintaining every task's allowed subcommands, but does not cover other command forms, scripts or APIs and is not a read-only boundary. Existing allow/deny/ask rules are preserved; adding broad grants to an earlier narrow setup is visible in the dry run. A denied operation remains denied even if the task requests it; changing policy requires an explicit settings change.
+
+Then use `AskUserQuestion` exactly once: `Apply the allow/deny rules (Recommended)` / `Skip for now`.
+
+**Step 4 — only if the user chose apply:**
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" setup --apply
+```
+
+## Final report
+
+Tell the user what is now in effect: the per-repo policy (if any) and where to change it later (`setup --restrict ...` / `setup --restrict none`), whether the allow/deny rules were applied (including the backup path), and the caveats: prefix matching, global scope, the headless caveat that some agy tools ignore allow-rules entirely so a restricted run can still come back empty, and the honest note that agy's project-scoped settings path is undocumented and unverified — so only the global file is edited. Security-sensitive users can scope permissions to a single project themselves, but do not guess a path for them.

package/opencode-skills/agy-crew-jobs/references/troubleshooting.md

@@ -0,0 +1,35 @@
+<!-- Generated from skills/jobs/references/troubleshooting.md; run npm run generate:opencode. Do not edit here. -->
+
+# Troubleshooting agy runs
+
+## The harness command sandbox (`operation not permitted`)
+
+agy cannot run inside a harness command sandbox (e.g. Codex workspace-write): it binds a localhost port for its internal language server and reads its OAuth token file, which sandbox secret-protection hides. No writable_roots/network_access knob fixes the hidden token — the run dies with `operation not permitted` on `~/.gemini/...` or on binding `127.0.0.1`, or with a bogus "authentication failed".
+
+Fix: run the companion command **unsandboxed**. In Codex, request escalated permissions for the command or have the user grant the workspace full access. Do not retry the command as-is; the sandbox will block it the same way every time.
+
+## False crash reports across permission or sandbox contexts
+
+If a background job was started unsandboxed but a management command (`wait`, `status`, `result`) is later run from a sandboxed or different permission context, the collector process may not see the running worker process. Because the liveness check fails and no result file has been written yet, the command reports the job as `crashed` with no stored result.
+
+Fix: run job management commands (`wait`, `status`, `result`, `cancel`) in the same unsandboxed permission context as the job start. Rerunning `wait`/`status`/`result` from the unsandboxed context sees the live worker PID and resumes waiting or reporting normal running status.
+
+## Empty response with status SUCCESS
+
+The fail-closed signature of a restricted run: headless agy auto-denies every unlisted tool call, so agy finishes "successfully" with nothing to say. The companion's error message carries the exact guidance — run `setup` once to install the evidence-gathering allowlist (see `setup.md`), or pass `--unrestricted` explicitly when authorized (continuations inherit the previous profile; new tool-using tasks default to unrestricted). Note that some agy tools ignore allow-rules in headless mode entirely, so even a complete allowlist cannot make them work; those need an unrestricted run. An empty response from an *unrestricted* run is not a permission issue — report it.
+
+## done_with_warnings (error status, response text)
+
+When agy reports an error but response text came back, the companion delivers the response anyway: exit 0, response on stdout, warning on stderr (retained in the job log and included as a bounded tail during background result collection). Assess the response against the task and review the diagnostics before deciding whether more work is needed. An empty response at a deadline with a known conversation instead needs attention (exit 5); other empty responses remain failures.
+
+## Quota exhausted and needs login (account pool)
+
+`reason=quota_exhausted` with a `retry_at` means the account (and any idle account that could lend a credential) hit its quota for that model family. Failover and credential loans have already been tried inside the run, so do not retry in a loop. Offer `continue --job <id>` after `retry_at`, or when `accounts list` shows an idle account; with no conversation, offer a new run with another `--account` or model family. `accounts quota --refresh` shows current numbers when the user wants them.
+
+An authentication failure on a pool account marks it `needs login` and is never retried. The user must run `agy-crew accounts login <name>` in their own terminal (browser sign-in); do not run it yourself. Live authentication failures still mean running `agy` interactively once.
+
+## Retry rules
+
+- Do not retry with different flags unless the error message itself names the exact flag.
+- For a timeout, inspect the retained result and workspace. Exit 5 means the conversation is resumable: ask the user whether to continue with the suggested timeout or stop, and recover only after explicit confirmation. Background `--timeout` defaults to 60m and accepts at most 120m; increase it only below that ceiling, otherwise narrow the task. A known conversation ID lets `continue` resume with its recorded configuration. A response already received before the hard deadline is delivered with a warning, so do not restart a completed job merely because cleanup timed out.
+- Model-id errors fail pre-flight with the valid ids in the message (`agy models` lists them); expired auth means running `agy` interactively once to re-login (for a pool account, `agy-crew accounts login <name>`).

package/opencode-skills/agy-crew-lead/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: agy-crew-lead
+description: Orchestrate an ongoing task with AGY while the current agent owns key decisions, review, and delivery. Use when the user invokes /agy-crew-lead or asks you to coordinate a task using AGY.
+---
+
+<!-- Generated from skills/lead/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy lead
+
+Task orchestration with AGY. You are the lead in the current harness. With an argument, work on that task; otherwise apply this guidance to the active task. Extend it across the session only when the user asks.
+
+## Working with AGY
+
+1. **Frame the assignment.** Orient just enough to state the outcome and completion criteria. Discovery itself can be delegated when the right next step is unclear; unknown interfaces or implementation choices need not be settled before discovery starts. Supply relevant background, constraints, settled decisions, and existing authorizations in the brief without expanding their scope. AGY sees its brief and its conversation, not the host's intervening discussion.
+2. **Default to delegating substantive work.** Use AGY to advance the task while you own user communication, cross-task decisions, acceptance, integration, and delivery. Handle work directly when it is small or existing context makes handoff and review more expensive. Make routine orchestration choices within the user's existing authorization. Stay within the requested scope and stage: discussing a proposal does not authorize implementing it.
+3. **Choose persona and worker scope by outcome.** Default to `staffer`; choose a specialist when the user requests it or its guidance materially improves the assignment (`researcher` for a source-backed survey, `reviewer` for independent critique, `implementer` for a scoped code change with verification). Reserve `ask` for installation smoke tests or explicit testing; do not route ordinary work to it. Keep related context together and choose worker count by useful independent outcomes. Implementation normally includes necessary verification in the same assignment; avoid splitting one change into implement, test, and review handoffs. Before parallel assignments that share interfaces, naming, or approach, settle those decisions and include them in each affected brief. Each background job takes an idle pool account, so useful parallelism is about the number of ready accounts: check `accounts list` (see `../agy-crew-accounts/SKILL.md`) before fanning out, and size the batch to it. With an empty pool every job runs on the live login, so serial work is wiser. Workers that edit files in parallel need separate git worktrees, each launched from its own worktree, because job state and continuation are per worktree; otherwise run editing assignments one at a time and parallelize only reads.
+4. **Wait by default.** After dispatch, wait for the result through `jobs`. Parallel host work should be an already-identified independent task worth handling directly. Idle time is not a reason to open another investigation into the same problem; avoid duplicating delegated work or delivering conclusions that depend on unavailable worker results.
+5. **Require an assessable result.** Specify the artifacts and evidence needed for acceptance. For example: research findings with sources and uncertainties; actual implementation changes with verification results, consequential choices, and remaining issues; or review findings with locations, triggering conditions, evidence, and impact, plus coverage limits even when no issues are found. Adapt these requirements to the task. The worker may analyze and recommend; you retain final judgment.
+6. **Assess, then decide the next step.** Read every result against completion criteria and check for conflicting assumptions or interfaces across workers. Inspect relevant diffs and verification for edits; make targeted checks of consequential claims as needed without repeating the whole investigation. Turn substantive gaps into focused follow-ups, continuing the existing conversation when its context helps and supplying new user decisions. Use a fresh conversation for an independent opinion or different context. Handle short, specific checks directly; take over when another handoff is unlikely to help. Integrate the results, disclose material omissions, and complete the requested delivery when the task is satisfied. Add review rounds only when they resolve meaningful uncertainty.
+
+## Dispatch and follow through
+
+Read `../agy-crew-jobs/SKILL.md` for result collection, cancellation, continuation, and recovery. This skill lives at `<plugin-root>/opencode-skills/agy-crew-lead/SKILL.md`. Write the brief to a temporary file and call the shared companion:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" staffer --prompt-file "<brief-path>"
+```
+
+For a specialist, replace `staffer` with `research`, `review`, or `implement`. When requesting code review, use the review-brief guidance in `../agy-crew-reviewer/references/code-review.md`. Modes retain their existing model and permission defaults; honor user overrides. Run unsandboxed as described in `../agy-crew-jobs/references/troubleshooting.md` (escalated execution in Codex).
+
+Keep each returned job ID with its assignment and collect the result through jobs. Prefer `continue --job <id>` for follow-ups; the companion refuses it while that job is still running. Let useful running work finish when feedback can wait; for an immediate change, follow jobs' cancel, confirm termination, then continue sequence. Account for partial work after interruption and follow the existing timeout recovery rules.
+
+In this workflow you compose briefs and synthesize results. The persona skills' thin-shell and verbatim-delivery instructions apply to direct persona invocations. Preserve exact quotes, figures, errors, and evidence references when integrating results. The lead skill uses existing companion modes; it adds no scheduler.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-researcher/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agy-crew-researcher
+description: Delegate a deep research or survey task to Google's Antigravity CLI (agy staffer, fast Gemini). Use when the user says /agy-crew-researcher, "ask agy to research", "have the agy staffer survey X", or wants a second, independent deep-dive on a topic or codebase without spending the host model's quota.
+---
+
+<!-- Generated from skills/researcher/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy researcher
+
+Delegate a research task to the agy staffer via the shared companion script. You are a thin shell: build the command, run it, return agy's report verbatim.
+
+## Locating the companion
+
+This skill file lives at `<plugin-root>/opencode-skills/agy-crew-researcher/SKILL.md`; resolve the companion path relative to this skill directory:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" research [flags] --prompt "what to research"
+```
+
+Pass the user's research topic verbatim via `--prompt`; use `--prompt-file <path>` or `--stdin` for a long brief.
+
+> [!IMPORTANT]
+> Run this command **unsandboxed** — agy needs a localhost port and its OAuth token file, which harness sandboxes hide. In Codex, request escalated permissions for the command. Details: `../agy-crew-jobs/references/troubleshooting.md`.
+
+## Collecting the result
+
+The command returns a job id. Read `../agy-crew-jobs/SKILL.md` for result collection and recovery: dispatch, wait for the final result, then validate as needed. Do not proactively observe progress, read logs or inspect intermediate artifacts while running. Observe only when the user explicitly asks for progress; diagnose a failure or a result requiring intervention under the jobs protocol.
+
+## Flags (all optional)
+
+- `--continue` — reuse the last research conversation (quota-friendly, served largely from cache); `--conversation <id>` targets a specific one.
+- `--model <id>` or `--effort low|medium|high` — default model is `gemini-3.8-flash-high`.
+- `--restricted` / `--unrestricted` — permission profile. research defaults to unrestricted, so it works out of the box with no setup. `--restricted` is the opt-in hardening path: agy runs without `--dangerously-skip-permissions` and may only use allowlisted tools, so it needs the setup flow's evidence-gathering allowlist to be useful — and some native agy tools ignore allow-rules headless, so restricted runs can still come back empty.
+- `--prompt <text>` / `--prompt-file <path>` / `--stdin` — the task, from exactly one of these three sources. Use file/stdin for long prompts.
+- `--timeout <dur>` — default 60m, maximum 120m hard execution limit.
+- `--account auto|live|<name>` — which agy account runs the task (default `auto`, the pool). See `../agy-crew-accounts/SKILL.md`.
+
+## Rules
+
+- Do not do the research yourself and do not re-verify agy's findings.
+- Return the companion stdout verbatim. The `[agy-crew]` telemetry line goes to stderr (and into `jobs/<id>.log` for background runs) — it is metadata for you, the calling agent, not something to show the user.
+- Pass the user's explicit authorizations through to the task string verbatim. The prompt template default-denies costly or irreversible side effects (commits/pushes, deleting files outside the workspace, side-effectful network calls, commands that burn paid API quota); that default opens only when the request itself asks for the operation — so keep "run the e2e tests" or "call the staging API" in the prompt instead of trimming it.
+- If a `--restricted` run reports an empty response due to denied permissions, relay the companion's guidance: run the setup flow once (see `../agy-crew-jobs/references/setup.md`), or drop `--restricted`.
+- For errors and recovery, follow `../agy-crew-jobs/SKILL.md`.
+
+For an existing conversation, `--continue` / `--conversation <id>` inherit its recorded model and permission profile unless explicitly overridden. The unrestricted defaults above apply to new tasks.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-reviewer/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: agy-crew-reviewer
+description: Get a second-opinion review from Google's Antigravity CLI (agy staffer, fast Gemini) - of code (a diff, PR, working tree) or of a decision, plan, or design. Use when the user says /agy-crew-reviewer, "have agy review this", "second opinion on my diff/PR/plan", or after finishing work and wanting an independent verifier that does not share the host model's blind spots.
+---
+
+<!-- Generated from skills/reviewer/SKILL.md; run npm run generate:opencode. Do not edit here. -->
+
+# agy reviewer
+
+Run a second-opinion review through the agy staffer. You are a thin shell: compose the task, run the companion, return agy's review verbatim. Never fix the issues it finds.
+
+The companion's template contributes only the reviewer stance, evidence discipline, and guardrails. Everything flavor-specific travels in the task string you compose — so pick the flavor first:
+
+- **Code review** — the subject is code: a PR, a branch/ref, the working tree, a patch file, specific files. Read `references/code-review.md` and compose the task per it (evidence gathering, review axes, severity-ranked output). `--json` belongs to this flavor only.
+- **General review** — the subject is a decision, plan, design, document, or set of claims. Read `references/general-review.md` and compose the task per it (multi-angle challenge). No fixed output format: state the deliverable's shape in the task if the user needs a specific one.
+
+## Locating the companion
+
+This skill file lives at `<plugin-root>/opencode-skills/agy-crew-reviewer/SKILL.md`; resolve the companion path relative to this skill directory:
+
+```bash
+node "<skill-dir>/../../companion/agy-companion.mjs" review [flags] --prompt "what to review"
+```
+
+Pass the review subject verbatim via `--prompt`; use `--prompt-file <path>` or `--stdin` for long text, which a composed task usually needs.
+
+> [!IMPORTANT]
+> Run this command **unsandboxed** — agy needs a localhost port and its OAuth token file, which harness sandboxes hide. In Codex, request escalated permissions for the command. Details: `../agy-crew-jobs/references/troubleshooting.md`.
+
+## The review subject is the prompt
+
+review is prompt-based: the user's request plus the flavor's framing is the task string. Do not gather diffs, write patch files, or translate the request into flags — agy collects the evidence itself. If the subject is ambiguous, agy reports the ambiguity instead of guessing; relay that and let the user sharpen the request. A task string is required; review with no subject exits with an error.
+
+## Collecting the result
+
+The command returns a job id. Read `../agy-crew-jobs/SKILL.md` for result collection and recovery: dispatch, wait for the final result, then validate as needed. Do not proactively observe progress, read logs or inspect intermediate artifacts while running. Observe only when the user explicitly asks for progress; diagnose a failure or a result requiring intervention under the jobs protocol.
+
+## Flags (all optional)
+
+- `--json` — schema-enforced JSON findings (verdict/summary/findings/could_not_verify) instead of markdown. Code-review flavor only, and only when the user asks for machine-readable output.
+- `--restricted` / `--unrestricted` — permission profile. review defaults to unrestricted, so it works out of the box and can run tests or reproduce a bug when the request asks for it. `--restricted` is the opt-in hardening path: agy may then only use allowlisted tools, so it needs the setup flow's evidence-gathering allowlist to be useful — and some native agy tools ignore allow-rules headless, so restricted runs can still come back empty.
+- `--model <id>` / `--effort low|medium|high` (default `gemini-3.8-flash-medium`), `--continue` (or `--conversation <id>`), `--timeout <dur>` (default 60m, maximum 120m hard execution limit), `--account auto|live|<name>` (default `auto`, the pool; see `../agy-crew-accounts/SKILL.md`).
+- `--prompt <text>` / `--prompt-file <path>` / `--stdin` — the task, from exactly one of these three sources. Use file/stdin for long prompts (a composed task with the flavor framing usually is one).
+
+## Reviewing untrusted content
+
+An unrestricted review of code from an untrusted author (a PR from a stranger, a patch from an unknown source) means prompt injection in that content could run arbitrary commands. For those reviews, consider `--restricted` (it may fail closed, and some native tools ignore allow-rules) or run the review in an isolated checkout.
+
+## Rules
+
+- Return the companion stdout verbatim — no commentary, no fixes, no softening of findings.
+- Pass the user's explicit authorizations through to the task string verbatim. The prompt template default-denies costly or irreversible side effects (commits/pushes, deleting files outside the workspace, side-effectful network calls, commands that burn paid API quota); that default opens only when the request itself asks for the operation — so keep "run the e2e tests" or "call the staging API" in the prompt instead of trimming it.
+- Empty responses from a `--restricted` run: relay the companion's guidance (run the setup flow once, or drop `--restricted`).
+- For errors and recovery, follow `../agy-crew-jobs/SKILL.md`.
+
+For an existing conversation, `--continue` / `--conversation <id>` inherit its recorded model and permission profile unless explicitly overridden. The unrestricted defaults above apply to new tasks.
+
+## Host compatibility
+
+When this skill or its referenced instructions require a tool that the current environment does not provide, use available capabilities to achieve an equivalent result. Adapt only the tool-specific execution method; preserve the task goal, authorization requirements, explicit confirmation steps, result delivery, and stopping conditions.
+
+If an equivalent result cannot be achieved, or you cannot establish that an alternative is equivalent, explain the missing capability and its impact, and ask the user for help. Do not silently skip requirements or bypass the environment's restrictions.

package/opencode-skills/agy-crew-reviewer/references/code-review.md

@@ -0,0 +1,46 @@
+<!-- Generated from skills/reviewer/references/code-review.md; run npm run generate:opencode. Do not edit here. -->
+
+# Composing a code-review task
+
+Read this when the review subject is code: a PR, a branch or ref, the working tree, a patch file, or specific files. The companion's template carries only the reviewer stance and guardrails; the code-review contract below travels in the task string. Compose the task as the user's request, verbatim, followed by this contract — adjusted only where the request explicitly overrides it. A composed task is usually long: pass it with `--prompt-file` or `--stdin` rather than `--prompt` (the three are the only task sources, and exactly one per call).
+
+The standards and spec-alignment axes are adapted from `code-review` in [mattpocock/skills](https://github.com/mattpocock/skills) (MIT).
+
+## The contract to append to the task
+
+### Gathering the evidence
+
+No diff is inlined. Identify the review subject from the request, then fetch the evidence yourself with the tools you have:
+
+- A pull request → `gh pr view <num>` for title, description, and discussion, then `gh pr diff <num>` for the change.
+- A git ref or branch → `git diff <ref>` for the change and `git log --oneline <ref>..HEAD` for the commit trail.
+- The current working tree → `git status` plus `git diff` and `git diff --staged`.
+- A patch or diff file → read the file at the given path.
+- Specific files or a directory → read them directly.
+
+Read surrounding source files wherever the diff alone is ambiguous — the review is about the code the change lands in, not just the changed lines.
+
+### Review axes
+
+Cover each axis; drop one only when the diff plainly has none of that surface, and say in the report that you dropped it:
+
+- **correctness** — does the code do what it claims: logic, edge cases, error and retry paths, concurrency, resource lifetimes, and tests that only appear to test something.
+- **standards** — does it follow *this* repo's conventions, documented (lint config, CONTRIBUTING, CLAUDE.md / AGENTS.md) and observed (how neighbouring modules do it). Establish the convention from the repo before judging, and cite the file that establishes it — a convention you cannot cite is a preference, not a finding.
+- **spec alignment** — does it do what the originating issue, ticket, or request actually asked: requirements left unmet, cases silently dropped, scope added on its own.
+- **security** — untrusted input reaching a sink, authz checks missing or in the wrong layer, secrets and logging, injection, unsafe defaults.
+
+### Findings
+
+- **Rank by severity**: `critical` (data loss, security, corruption), `high` (incorrect behavior on realistic input), `medium` (bug in edge case, resource leak), `low` (robustness, maintainability), `nit` (style). Report in that order.
+- **Every finding needs `file:line`** (or `file:hunk` if line numbers are unavailable) plus a one-line title and a concrete explanation of the failure mode — what input or sequence triggers it.
+- **Check what the change touches, not just what it shows**: callers of changed functions, invariants the change might break, error paths, and concurrency.
+
+### Output format
+
+- `## Verdict` — one of: approve / request changes / comment, with one sentence of justification.
+- `## Findings` — severity-ranked list as specified above. If none: say so explicitly and state what was checked.
+- `## What I could not verify` — mandatory. Evidence that could not be fetched, tests that could not run, callers not seen, assumptions made.
+
+## --json
+
+`--json` makes the companion enforce a findings schema (verdict / summary / findings with severity, file, line, title, detail / could_not_verify) instead of markdown. Opt-in only, when the user wants machine-readable output; it matches the output format above, so no extra task text is needed for it.