Roles, skill workflows, and runtime closure¶
This page is the single repository reference for Agy-Squad skill composition, MCP/CLI tool boundaries, roles, cross-role handoff flows, and the runtime closure checklist. Other docs and skill files (.agents/skills/*/SKILL.md) link here instead of repeating role graphs.
Skill composition & tool surface map¶
| Dimension | Choice / Surface | Canonical Scope & Usage |
|---|---|---|
| Task Spec (what to inspect) | pr-review, full-review, day-one-review, self-diagnosis |
Use pr-review for branch/PR diffs, full-review for non-diff evidence & direction decisions, day-one-review for raw, unguided cold first-time-user launch reviews and iterative remediation (no /swarm by default; flat category /swarm opt-in only), and self-diagnosis for Agy-Squad health & optimization. |
| Execution Modifier (how teams run) | swarm-governance |
Pair with any Task Spec on /swarm or multi-agent teams (opt-in only for day-one-review). Governs slot receipts (<= 500 B), flat audit-<id>, agy-squad proof bundles, and 4-check closure. |
| Topology rule (no default bias) | Flat vs Layered vs single-agent |
Neither topology is forced by default; ask the user once if unspecified. squad_planner reports neutral tradeoffs via topology.defaultBias: "none (ask user if unspecified)". |
/swarm planner |
squad_planner / agy-squad plan |
Default planner for /swarm (swarmAdd, readOnly: true overlap exemptions, provenanceScaffold). Supports all manifest squads when squadId is omitted (all_l1 is invalid here). |
invoke_subagent compiler |
dispatch_squad / agy-squad dispatch |
Explicit invoke_subagent stage compiler (all_l1 leads, <squadId> specialists, or integrity_auditor[:<target>] slot; legacy adversarial_* modes removed). |
| Verification library | mcp/handoffs.mjs |
Library imported by agy-squad (collect, bundle-init, fingerprint, inspect, digest, bundle, verify, finalize, prune); standalone CLI removed, so always invoke agy-squad (or node bin/agy-squad.mjs inside a local checkout). |
1. Canonical role inventory¶
Agy-Squad runs inside Google Antigravity's native /swarm runtime without replacing it, structuring roles, file scopes, board receipts, and dual-gate verification on top of the shared board:
| Role | Active in | Verdict or primary output | Authority and boundary |
|---|---|---|---|
| Operator / Primary Agent | All workflows | Compiles plans, delivers structured reviews (in chat, artifacts, or opt-in docs/reviews/), runs finalize/bundle/--teardown, stops agents |
Owns user intake, final reporting, and teardown; never fabricates specialist evidence |
Coordinator (/swarm) |
swarm-governance |
Briefs workers on the shared board (post_message), writes lead/report.md in flat mode, runs agy-squad |
Owns single-squad orchestration and worker kill cleanup; never delegates coordination to monitor or narrator |
| Working Lead | swarm-governance (layered), self-diagnosis (all_l1) |
Content Verdict: PASS \| FAIL \| BLOCKED (legacy alias Verdict: ...) |
Reviews specialist slot reports against cited files/tests and re-checks after integrity CLEAN; never audits its own integrity |
| Specialist | swarm-governance, self-diagnosis, pr-review, full-review, day-one-review |
Writes specialist-<N>/report.md + <= 500 B receipt (READY, PARTIAL, NO_REPORT) |
Inspects assigned scopeFiles via executed tools/commands (Subagent Alignment Policy); never guesses from memory |
| Flat Integrity Auditor | All skills (/swarm: audit-<id>, slot: integrity_auditor:<id>) |
Target Squad: <id> and Integrity Verdict: CLEAN \| INTEGRITY VIOLATION |
Independent flat peer auditing tool traces (agy-context transcript list --parent <id> --lineage, query --id <id> --summary, or read --id <id> --last-turns 10 with [agy-transcript-access: allow], or coordinator export --parent <id> --sanitized --out scratch/... index), scope isolation, and SHA-256 hashes; fails closed with INTEGRITY VIOLATION if execution traces are unavailable and cannot approve content (PASS) |
| Review Lead / Responsible Reviewer | pr-review, full-review, day-one-review |
APPROVE \| REQUEST_CHANGES, PASS \| FAIL \| BLOCKED, or 4-tier Day-1 Ship Verdict (SHIP NOW \| SHIP WITH MINOR POLISH \| FIX BEFORE RELEASE \| HOLD BEFORE PUBLIC RELEASE) (+ Section 7 Direction decision when requested) |
Evaluates repository architecture contracts and ADRs (when present), 11 review categories (ARCH..DEP, SEC), and 1 ID = 1 Row review ledgers; issues provisional verdict before audit and final verdict only after CLEAN |
| Implementer / Author | pr-review, day-one-review, self-diagnosis remediation |
Code, test, or doc changes at a new commit/revision | Fixes recorded findings separately from review acceptance (day-one-review auto-fixes P0-P3 and pauses only on Section 8 residuals, defaulting to a single worker for heavy indexers/daemons); resumes only interrupted subagents cleanly on interruption and re-checks fixes |
Monitor (swarm_monitor) |
Antigravity native /swarm |
@coordinator [stall] or @<member> [stall] alerts when all members stop moving |
Runs a */3 daemon cron (schedule with IsDaemon: true) and checks read_board; never receives task briefs, edits files, or touches verdicts |
| Narrator | Antigravity native /swarm |
Maintains the user-facing Swarm UI overview | Summarizes board progress for the Swarm UI; never edits files, briefs workers, or touches verdicts |
2. Role workflows by skill¶
Every multi-agent workflow separates content evaluation from integrity auditing: a provisional content verdict runs before the flat integrity auditor checks execution authenticity, and acceptance requires the lead or reviewer to re-check final artifacts after Integrity Verdict: CLEAN (see Review roles).
Each built-in skill has its own dedicated guide under Skills:
| Skill | Kind | Dedicated guide |
|---|---|---|
pr-review |
Task Spec | PR & branch review (Standard v1.5.0) |
full-review |
Task Spec | Non-diff audits, evidence triage & direction decisions |
day-one-review |
Task Spec | Cold first-time-user launch audit & remediation |
swarm-governance |
Execution Modifier | Native /swarm orchestration, receipts & SHA-256 bundling |
self-diagnosis |
Task Spec (maintainer-only) | Agy-Squad harness profiler & optimization cohorts |
3. Runtime closure checklist and hook boundary¶
Running agy-squad finalize, agy-squad bundle, and agy-squad verify confirms file integrity (SHA-256) for a coordinator-assembled record; those CLI commands do not query live Antigravity agents, timers, or child OS processes. Every coordinator or operator must execute this 4-check closure checklist before reporting completion:
Four-check runtime closure gate (active checklist)¶
swarm{action: "status"}(native/swarm): Confirm every non-coordinator member showsstate: "killed",killed: true.- Monitor retirement rule: Native
/swarminstructions leavemonitor(or anymonitor-*worker) alive waiting up to 3 minutes on a*/3daemon cron after[done](swarm_monitorgoes dormant only on its next cron tick). UnderAgy-Squadgoverned runs, explicitly callswarm{action: "kill", name: "monitor"}(or the active monitor's exact roster name fromswarm{action: "status"}) once[done]is posted so no background cron lingers. manage_subagents(Action='list'): Confirm0 active subagent(s): [].manage_task(Action='list'): ConfirmNo background tasks are currently running.(catches any lingeringscheduledaemon cron or timer).- Child commands (Stopping agents): Confirm any dev servers, builds, or watchers started by agents exited cleanly.
Current hook boundary and propagation behavior¶
- Current live hook coverage: Global
~/.gemini/config/hooks.jsoncurrently limits itsPreToolUsematcher to file, shell, and task tools (run_command,view_file,read_file,manage_task,schedule, etc.), so liveswarm,post_message, and agent exit events remain governed by the active closure checklist above. - CLI hook propagation findings (
agy 1.5.9CLI, 2026-11-16): Controlled probes onagy 1.5.9CLI ("matcher": "*") confirmed that workspace.agents/hooks.jsonand global~/.gemini/config/hooks.jsonpropagateSessionStart,PreInvocation,PreToolUse,PostToolUse, andStopto bothinvoke_subagentchildren and/swarmworkers (withPreToolUsedenyblockinginvoke_subagentand workerpost_message), whereas pluginhooks.jsondoes not fire inside/swarmworkers. ReusableAgy-Squad.agents/hooks.jsonenforcement gates and Desktop IDE verification remain pending before removing the advisory closure checklist.
4. Scaling swarms, custom role configurations, and limits¶
You can request larger swarms or arbitrary custom role layouts in any session; Agy-Squad imposes no hardcoded cap on squad count or workers per squad (mcp/planner.mjs, mcp/dispatch.mjs). Choose the configuration surface that matches how differentiated each worker needs to be:
Ways to configure larger swarms and custom roles¶
- Quick custom roles on an ad-hoc task (
task+roles): Pass an arbitrary non-emptyroleslist (--role "<title>"repeatable on CLI, orroles: [...]insquad_planner), such as["Security Reviewer", "Performance Auditor", "Test Verifier", "Docs Checker"], with optionalreadOnly: true(--read-only) and per-roleroleScopes(--role-scope <role=path>, repeatable).deriveTaskSquads(mcp/planner.mjs) compiles onespecialist-<N>per role undertask_squad, falling back toscopeFiles(["."]by default) for roles withoutroleScopesand pairing withaudit-task_squad. Use this for flat cohorts where custom per-worker objectives or per-worker models are unnecessary. - Custom manifests (
manifestinline object ormanifestPathfile): Define any number of named squads undersquads.<id>, each with a customspecialistsarray (role, tailoredobjective, dedicatedscopeFiles, optionalinstructions, optionalexpectedDeliverable, optionalreadOnly: true, optionalmodel, andtypeName: "self"or a custom writable subagent) plus an optionallead(or inline lead fields). OmitsquadIdinsquad_plannerto launch all squads in one/swarmwave, override structure withtopology: "flat"(strips leads) or"layered"(requires leads), or customizeintegrity_auditorwith multiple audit specialists (mcp/dispatch.mjs). - Note:
roles,scopeFiles,readOnly, androleScopescannot be passed alongsidemanifestormanifestPath; place per-role overrides inside the manifest itself. - Multi-wave scaling on an active board (
occupiedWorkerNames) & native sharding: When adding a second squad or helper cohort to a running/swarmboard, pass existing roster names viaoccupiedWorkerNames(--occupied-worker) soallocateWorkerNameavoids name collisions. Native/swarmalso supportstasks(sharded<name>-1..-<len(tasks)>),n(homogeneous copies),fork: "<member>", andmonitor(swarm_monitor), though every governed worker bundled withagy-squadstill needs an explicitspecialist-<N>/report.mdslot.
Hard code limits vs. host & practical limits¶
| Boundary | Exact limit or rule | Governing source |
|---|---|---|
| Squads & workers per cohort | Hard minimum: >= 1 working squad and >= 1 specialist per squad; no hardcoded maximum count |
mcp/dispatch.mjs, mcp/planner.mjs |
| Swarm member name length | Hard ceiling: 24 characters (MAX_SWARM_NAME_LENGTH = 24); lowercased [a-z0-9-]+ slugs deduplicated via -2, -3, ... suffixes |
mcp/planner.mjs |
| Squad ID & directory name | Must match /^[A-Za-z0-9_.-]*[A-Za-z0-9_-]$/ (no trailing ., excluding ., .., __proto__, constructor, prototype, all_l1, adversarial_*, integrity_auditor*); squad-<encodeURIComponent(id)> must be <= 255 UTF-8 bytes |
mcp/verdicts.mjs, mcp/handoffs.mjs |
| Board receipt & path headroom | Hard ceiling: single line, <= 500 UTF-8 bytes (messageLimit = 500); reportPath() also reserves 26 bytes (SWARM_MENTION_RESERVE_BYTES = 26 for @<24-char-name>) so PARTIAL <path> — fits |
mcp/handoffs.mjs |
| MCP stdio payload size | Hard ceiling: 10 MiB (10 * 1024 * 1024 bytes default, configurable via positive integer AGY_MAX_STDIO_PAYLOAD_BYTES) |
mcp/index.js |
| Models & worker types | executionMode: "swarm" pins arbitrary model IDs (optionally validated against knownModels); executionMode: "subagent" only accepts inherit, flash_lite, flash, pro; built-ins research, browser, image-generator are rejected; manifest agent workspace must be inherit |
mcp/briefs.mjs, mcp/planner.mjs |
| Workspace isolation | share and branch require executionMode: "swarm" (subagent allows inherit only); concurrent editors must avoid inherit overlaps or split scopeFiles |
mcp/planner.mjs |
| Shared board broadcast & UI scaling | Host / practical limit: Antigravity attaches one append-only board (board: "local") per conversation and disables channel partitioning when swarm omits action: "channel". Every board post is ingested by all active workers (quadratic token growth), and Antigravity's built-in /swarm guidance suggests splitting areas above ~8 workers; start a fresh conversation per major wave to keep boards responsive |
Concepts: shared swarm board |
| Model quota & rate limits | Host limit: Running many workers pinned to one model shares host quota; check swarm{action: "models"} upfront and switch waiting workers with swarm{action: "model"} on quota exhaustion |
Tools contract |