Skip to content

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:

Native Antigravity /swarm vs. Agy-Squad roles and configuration additions

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

Skill role workflows and dual-verdict closure flow

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)

  1. swarm{action: "status"} (native /swarm): Confirm every non-coordinator member shows state: "killed", killed: true.
  2. Monitor retirement rule: Native /swarm instructions leave monitor (or any monitor-* worker) alive waiting up to 3 minutes on a */3 daemon cron after [done] (swarm_monitor goes dormant only on its next cron tick). Under Agy-Squad governed runs, explicitly call swarm{action: "kill", name: "monitor"} (or the active monitor's exact roster name from swarm{action: "status"}) once [done] is posted so no background cron lingers.
  3. manage_subagents(Action='list'): Confirm 0 active subagent(s): [].
  4. manage_task(Action='list'): Confirm No background tasks are currently running. (catches any lingering schedule daemon cron or timer).
  5. 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.json currently limits its PreToolUse matcher to file, shell, and task tools (run_command, view_file, read_file, manage_task, schedule, etc.), so live swarm, post_message, and agent exit events remain governed by the active closure checklist above.
  • CLI hook propagation findings (agy 1.5.9 CLI, 2026-11-16): Controlled probes on agy 1.5.9 CLI ("matcher": "*") confirmed that workspace .agents/hooks.json and global ~/.gemini/config/hooks.json propagate SessionStart, PreInvocation, PreToolUse, PostToolUse, and Stop to both invoke_subagent children and /swarm workers (with PreToolUse deny blocking invoke_subagent and worker post_message), whereas plugin hooks.json does not fire inside /swarm workers. Reusable Agy-Squad .agents/hooks.json enforcement 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

  1. Quick custom roles on an ad-hoc task (task + roles): Pass an arbitrary non-empty roles list (--role "<title>" repeatable on CLI, or roles: [...] in squad_planner), such as ["Security Reviewer", "Performance Auditor", "Test Verifier", "Docs Checker"], with optional readOnly: true (--read-only) and per-role roleScopes (--role-scope <role=path>, repeatable). deriveTaskSquads (mcp/planner.mjs) compiles one specialist-<N> per role under task_squad, falling back to scopeFiles (["."] by default) for roles without roleScopes and pairing with audit-task_squad. Use this for flat cohorts where custom per-worker objectives or per-worker models are unnecessary.
  2. Custom manifests (manifest inline object or manifestPath file): Define any number of named squads under squads.<id>, each with a custom specialists array (role, tailored objective, dedicated scopeFiles, optional instructions, optional expectedDeliverable, optional readOnly: true, optional model, and typeName: "self" or a custom writable subagent) plus an optional lead (or inline lead fields). Omit squadId in squad_planner to launch all squads in one /swarm wave, override structure with topology: "flat" (strips leads) or "layered" (requires leads), or customize integrity_auditor with multiple audit specialists (mcp/dispatch.mjs).
  3. Note: roles, scopeFiles, readOnly, and roleScopes cannot be passed alongside manifest or manifestPath; place per-role overrides inside the manifest itself.
  4. Multi-wave scaling on an active board (occupiedWorkerNames) & native sharding: When adding a second squad or helper cohort to a running /swarm board, pass existing roster names via occupiedWorkerNames (--occupied-worker) so allocateWorkerName avoids name collisions. Native /swarm also supports tasks (sharded <name>-1..-<len(tasks)>), n (homogeneous copies), fork: "<member>", and monitor (swarm_monitor), though every governed worker bundled with agy-squad still needs an explicit specialist-<N>/report.md slot.

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