Agy-Squad¶
Agy-Squad is a subagent planning, self-diagnosis, and review harness for Antigravity Desktop (IDE) and the Antigravity CLI (agy) across Linux, macOS, and Windows.
squad_planner and dispatch_squad assign scoped tasks to specialist or lead cohorts, cap Pointer-Over-Wire receipts at 500 UTF-8 bytes, and pair with the agy-squad CLI (mcp/handoffs.mjs) to verify SHA-256 input and report digests. During live Desktop IDE runs, Agy-Context-Saver (>= 2.0.1, 2.0.4+ recommended) rewrites shell commands through rtk >= 1.1.0 (rtk hook antigravity), enforces 5-tier transcript access governance, and applies Reactive Wakeup backoff.
Start here¶
- Getting started (Linux, macOS & Windows): Host and companion compatibility matrix,
npxinstall,PATH& IDE reload guidance, Uninstall & Rollback, and CLI commands (setup,status,plan,dispatch,collect,bundle-init,verdict,fingerprint,inspect,digest,bundle,verify,finalize,prune). - Core workflows: Task-proportional delegation, recursive
self-diagnosis, the eleven-categorypr-reviewStandard v1.5.0, coldday-one-review, and the 3-scope evidence-retention and teardown contract. - Roles, skill workflows, and runtime closure: Single canonical definition of every role, Task-Spec vs. Execution-Modifier skill composition (
swarm-governance,pr-review,full-review,day-one-review,self-diagnosis), and the 4-check runtime closure checklist. - Concepts and terminology: Definitions for stages (
all_l1vs.<squadId>vs.integrity_auditor/audit-<id>),squad_planner, report slots,Pointer-Over-Wirereceipts, SHA-256 bundles, Reactive Wakeup, andRTK. - Manifest and tool contract: Schema and CLI flags for
squad_planner(plan),dispatch_squad(dispatch),agy-squad, andmcp/handoffs.mjs(library module). - Benchmarks: Canonical metric tables, per-agent telemetry, and reproduction guide for the November 15, 2026 matched-
High/swarmretest and November 8, 2026 Phase 1 baseline against Antigravity/teamwork.
Core capabilities¶
- Proportional
/swarmplanning and subagent dispatch:squad_planner(/swarmdefault with explicitmodelpinning,readOnly-aware scope-overlap checks, and transcript-safeprovenanceScaffold) anddispatch_squad(invoke_subagent) route worker evidence toscratch/agy-squad/.../report.mdand return a single-line<= 500BREADYreceipt. Ask the user upfront whenFlatvsLayeredtopology is unspecified. - Maintainer harness self-diagnosis (
/self-diagnosis): Inside anAgy-Squadsource checkout,node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdownruns a zero-subagent health and token-budget check, or builds targeted audit cohorts (--print-planor--print-dispatch) for operator-supervised inspection. - Repository review standards (
/pr-review,/full-review, &/day-one-review, v1.5.0): Reviewers apply commit and session provenance, architecture-before-runtime tracing, eleven mandatory categories (ARCH,DOC,SKILL,MCP,RUN,SVC,DB,SCRIPT,TEST,DEP,SEC), and1 ID = 1 Rowstructured reports (in chat, Antigravity artifacts,scratch/day-one-review/for Day-1 reviews, ordocs/reviews/when requested or already adopted). - Governed evidence retention and teardown:
agy-squadverifies SHA-256 source and report digests before pruning loose specialist reports (finalize --pruneorbundle+verify+prune), binds flat integrity auditCLEANverdicts (audit-<id>on/swarm,integrity_auditor[:<id>]via slot), and gatesdiagnose.mjs --teardownon a verified bundle and updateddocs/reviews/ledger.
How Agy-Squad extends native /swarm¶
Agy-Squad configures Antigravity's native /swarm runtime rather than replacing it, adding non-overlapping scopes, file-backed report slots, and independent integrity auditing on top of the built-in shared board (see Roles, skill workflows, and runtime closure):
Companion integration: Agy-Context-Saver¶
Agy-Squad and Agy-Context-Saver remain separate packages that interact across four execution stages:
| Stage | Owner | Mechanism and tools |
|---|---|---|
| 1. Cohort planning and compilation | Agy-Squad |
squad_planner and dispatch_squad assign scoped briefs, report slots (scratch/agy-squad/...), and <= 500 B Pointer-Over-Wire receipts (TypeName: "self", Workspace: "inherit" for invoke_subagent; explicit model pinning and share/branch isolation for /swarm). |
| 2. Subagent execution governance | Agy-Context-Saver (>= 2.0.1, 2.0.4+ recommended) |
Inside Desktop IDE sessions, Agy-Context-Saver's PreToolUse hook delegates child run_command rewrites to rtk >= 1.1.0 (rtk hook antigravity), bounds workspace read_file slices (<= 150 lines), and applies backoff on manage_task and schedule. |
| 3. Cryptographic bundling and pruning | Agy-Squad |
agy-squad (plan -> dispatch -> collect -> bundle-init -> verdict -> finalize [--prune], or granular fingerprint -> inspect -> digest -> verdict --integrity -> bundle -> verify -> prune [--keep-reports]) validates single-line verdicts, binds integrityAudit digests (CLEAN + Target Squad), writes report.sources.json, and optionally removes loose reports. |
| 4. Session and transcript forensics | Agy-Context-Saver (>= 2.0.1, 2.0.4+ recommended) |
The agy-context CLI (agy-context status, agy-context setup, agy-context transcript read|query|step|health|list|export|access) inspects parent or child conversationId records without reading .system_generated/ directly, enforcing [agy-transcript-access: allow|deny] directives per worker. |
Run agy-context setup once on a new host so the rtk >= 1.1.0 binary and agy-context CLI shim are active before launching live workers.
Recorded comparison vs. Antigravity /teamwork¶
On November 15, 2026, a matched-effort sequential retest (Gemini 4 Hydrogen (High) on all parents and child workers) compared native /swarm (Agy-Squad + Agy-Context-Saver 2.0.1, rtk 1.1.0) against /teamwork [skip-interview] on the six-defect event-relay fixture (benchmarks.md). Both arms caught all six planted defect categories (6 / 6):
- Runtime and steps (end-to-end parent + all workers): Agy-Squad
/swarmfinished in6m 30s(390s) vs.22m 41s(1,361s,3.49xfaster) and executed178vs.655combined transcript steps (72.8%fewer steps;90vs.636child-only steps). - Context, transcript size, and wakeups: Combined raw transcripts totaled
336.8 KB(183.6 KBchild-only) vs.801.8 KB(773.7 KBchild-only) (58.0%smaller overall,76.3%smaller child-only), and parent wakeup payloads totaled1,629 Bvs.18,322 B(91.1%fewer parent bytes). - Verification and evidence quality: Agy-Squad found
21unique defects (10 P1,11 P2) backed by SHA-256 bundle4c28db49...and an independentaudit-ab-auditCLEANverdict, whereas/teamworkfound16defects (8 P1,8 P2) and itsVictory Auditorapproved Sentinel-fabricated snippets that the parent session had to catch and fix in Steps 11–17.
See Benchmarks for the complete November 15 matched-High per-agent table, the historical November 8, 2026 Phase 1 baseline (6m 15s vs. 26m 19s, 148.2 KB vs. 817.4 KB subagent-only), unit definitions, and reproduction steps.