agy-native

# agy-native

Drive the AgentOps loop on the **Antigravity image** (AGY): the `agy` CLI backed by the brain/knowledge store at `~/.gemini/antigravity-cli/`. This is the third harness alongside the Claude image and the Codex image — same loop laws, AGY-native primitives. **Invoke `agy`, never rebuild it.**

## Overview / When to Use

AGY is Google's Antigravity agent harness exposed as a local CLI (`~/.local/bin/agy`). It speaks the Claude-style packaging shape (plugins, skills, subagents, hooks, MCP) and a **portable `SKILL.md`** — AGY reads skills from `~/.gemini/skills/` directly, so the AgentOps corpus already loads on it. Use this skill when you need the claim->work->validate->close->persist loop running on AGY (driving Gemini, or Claude/GPT models *through* AGY — `agy models` exposes Gemini 3.5/3.1, Claude Sonnet/Opus 4.6, GPT-OSS), as a parallel or fallback to the Claude/Codex images.

**AGY ≠ gemini-cli.** The retired `gemini` CLI lane (`gemini -p`, `gemini skills`, `gemini extensions`, `--approval-mode`, `--worktree`) is gone. Everything here is an AGY affordance; §"Distribution" + the reference file name each AGY equivalent for an old gemini habit.

Verified primitives on this host (`agy --help`, `agy plugin help`, `agy models`):
- **Headless run:** `agy -p "<prompt>"` / `agy --print` (one-shot, prints, exits; `--print-timeout` default 5m). `-c`/`--continue` resumes the most recent conversation; `--conversation <id>` resumes by ID.
- **Plugins:** `agy plugin {list,import,install,uninstall,enable,disable,validate,link}`. `import [gemini|claude]` pulls existing plugin trees in. `install <target>` reads a `plugin.json` (supports `plugin@marketplace`).
- **Permissions:** `--dangerously-skip-permissions` auto-approves tool calls (loop/headless lane); `--sandbox` restricts the terminal.
- **Workspace scope:** `--add-dir <dir>` (repeatable) scopes which repos a run can touch (AGY's write-isolation primitive — it scopes by directory, not by spawning worktrees).
- **Brain/knowledge:** durable agent memory + user-facing artifacts under `~/.gemini/antigravity-cli/{brain,knowledge}/` (per-conversation dirs; `*.md` + `*.md.metadata.json` with `{summary, updatedAt, userFacing}`).

### Folded triggers (ag-s43tg wave 1): the four AGY sibling lanes route here

- **`agy-mcp-plugins` → the Distribution lane.** Use when wiring MCP servers and AgentOps plugin bundles
  into the AGY image with least-privilege access, rollback evidence, and validation hooks — the
  §"Distribution" layer below (plugin trees, `agy plugin link/install`, validate → apply → list →
  record-rollback) owns that mutation protocol.
- **`agy-project-worktree-permissions` → the isolation rules.** Use when proving AGY project/worktree
  isolation with scoped --add-dir permissions, role permission tiers, and `dcg` guardrails — Rules 4–6
  below (non-overlapping `--add-dir` scopes, permission matched to role, the `dcg` BeforeTool hook)
  are that contract, with evidence persisted per Rule 3.
- **`agy-rules-workflows` (triggers: AGY rules, agy-loop, AGY schedule) → Phase 2 law packaging.** Use
  when installing AGY rules, workflow, goal, and schedule controls for AgentOps loop law — the
  `agy-control-plane` plugin tree in Phase 2 (`rules/` + `workflows/` + `hooks.json`) is where the
  agy-loop law lands; schedules drive Phase 5.
- **`agy-sidecar-scheduled-tick` → the Phase 5 recurring driver.** Use when running a
  recurring AGY sidecar loop tick with agentapi evidence capture — Phase 5's tick lane (AGY
  scheduled task, or an external timer / Claude `CronCreate` calling `agy --print`) is that driver.

## ⚠️ Critical Constraints

- **Rule 1 — Never `claude -p` for workers (LAW 0).** AGY runs on Gemini OAuth (and proxied Claude/GPT). Drive AGY workers with `agy --print` or `agy -i`, Codex with `codex exec`, Claude only via NTM panes / subagents. **Why:** `claude -p` bills the API per-token, not the Max sub; the overnight factory burned API this exact way (banned).
- **Rule 2 — author != judge, always two contexts.** The subagent that closes a bead must NOT be the one that validates it. Spawn the judge as a separate async subagent with a clean context (or a separate `agy --print` invocation; **never** `-c`/`--continue` across roles — it shares context). **Why:** a self-grading worker is a flatterer; independent verdict is the membrane (control-plane LEARNINGS: a tie-break quorum caught a false-FAIL).
- **Rule 3 — evidence-gated close.** A bead closes only against a persisted verdict artifact (a `brain/*.md` with `userFacing:true` or a committed repo file), never against chat text alone. **Why:** agents are ephemeral; the system carries state. Consume an agent's *published compression*, never its live session.
- **Rule 4 — worktree / `--add-dir` isolation.** Concurrent author and judge get isolated worktrees or non-overlapping `--add-dir` scopes. No two roles edit the same file. **Why:** prevents swarm races and clobbered work.
- **Rule 5 — `dcg` guard stays on.** `~/.gemini/settings.json` wires a `BeforeTool` hook on `run_shell_command` to `dcg`. Do not remove it even under `--dangerously-skip-permissions`. **Why:** it blocks destructive commands the auto-approve flag would otherwise let through.
- **Rule 6 — match permission to role.** Author = `--dangerously-skip-permissions` with a **tight** `--add-dir`; judge = **default** (no auto-approve) with a read-mostly scope; full-auto only inside `--sandbox`. **Why:** auto-approve is a blast-radius choice — a validator that can edit is a false-close path.
- **Rule 7 — operator-side; invoke-never-rebuild.** This drives the flywheel harness. Do NOT write under `~/dev/agentops`, do NOT git push agentops, do NOT treat AGY as something to re-author. **Why:** AGY is Emanuel's substrate (ACFS doctrine) — own a thin adapter, not the tool.

## Distribution — exposing skills/plugins to AGY

AGY discovers capability through three layers (weight ascending): a **portable `SKILL.md`** under `~/.gemini/