Manifest and tool contract¶
Agy-Squad exposes two MCP tools (dispatch_squad in mcp/dispatch.mjs and squad_planner in mcp/planner.mjs) alongside the offline governance CLI (bin/agy-squad.mjs, backed by mcp/briefs.mjs, mcp/handoffs.mjs, and mcp/verdicts.mjs).
dispatch_squad (mcp/dispatch.mjs)¶
dispatch_squad is the invoke_subagent compiler and returns a JSON object with a native Subagents array. Each call compiles one stage.
| Argument | Purpose |
|---|---|
squadId |
Required. Use all_l1 for working leads, integrity_auditor (or integrity_auditor:<targetSquad>) for the canonical flat independent integrity auditor, or a squad ID for that squad's specialists. Legacy adversarial_l1 / adversarial_flat / adversarial_review stages were removed in PR #5. |
manifestPath |
Optional. A relative or absolute path inside the configured workspace. Symlinks must also resolve inside the workspace. |
workspace |
Optional. Active repository directory path; overrides MCP initialize roots, AGY_SQUAD_WORKSPACE, and server cwd when running from a global plugin install. |
mcp/index.js captures MCP initialize workspace roots (workspaceFolders/rootUri/rootPath) as the session default and passes args.workspace, that initialize root, AGY_SQUAD_WORKSPACE, or process.cwd() into mcp/dispatch.mjs and mcp/planner.mjs. With no explicit manifestPath, dispatch_squad searches for task-01-manifest.json, swarm-manifest.json, .scratch/swarm-manifest.json, and suite-manifest.json in that order and loads the first valid squad manifest. agy-squad setup installs the plugin into ~/.gemini/config/plugins/agy-squad (auto-discovering skills/ and mcp_config.json, while sweeping any duplicate global agy-squad MCP entry).
squad_planner (mcp/planner.mjs & agy-squad plan)¶
squad_planner pairs Agy-Squad governance with Antigravity native /swarm (executionMode: "swarm", default) or invoke_subagent (executionMode: "subagent"), replacing the retired agy-squad run PTY launcher. Provide exactly one of manifestPath, manifest (inline { squads }), or task (plus optional scopeFiles, roles, readOnly, roleScopes), alongside optional workspace (active repository root when MCP cwd differs from your repo), squadId (omit to plan all squads; all_l1 is valid only in dispatch_squad/agy-squad dispatch), topology (flat | layered), executionMode, model, workspaceIsolation (inherit | share | branch), includeIntegrityAuditor, reportRoot, knownModels, occupiedWorkerNames, boardSince, and boardSeqs. It imposes zero topology default bias (topology.defaultBias: "none (ask user if unspecified)").
- Explicit model pinning and provenance: Under
executionMode: "swarm",mcp/planner.mjscompilesswarmAddentries with explicitmodelpinning and instructs live verification viaswarm{action: "status"}. UnderexecutionMode: "subagent",invoke_subagentaccepts onlyinherit,flash,flash_lite, orpro;modelProvenancestates when a requested model ID cannot be pinned or inspected per child (agy-context transcript readandmanage_subagentsdo not expose child model IDs). - Writable
scopeFilesoverlap checks:mcp/planner.mjspartitions overlapping writablescopeFilesintotopology.siblingOverlaps(concurrent sibling collisions, emitted aswarnings[]underworkspaceIsolation: "inherit") andtopology.leadSpecialistOverlaps(sequential same-squad lead-vs-specialist overlaps, emitted asnotes[]), while keeping the combinedtopology.scopeOverlapslist (scopeOverlapComparison: "canonical-when-present-else-lexical") and exempting read-only audit squads (integrity_auditor*) and explicit booleanreadOnly: truespecs. Note:readOnly: trueis overlap-check planning metadata only (not enforced inside compiled worker briefs or host permissions). - Transcript-safe
provenanceScaffoldandbundleRecordTemplates: Generates a parent-authored provenance scaffold recording worker names, report slots, and model expectations without copying raw.system_generated/transcripts intoscratch/, plus pre-populatedbundleRecordTemplates(includingintegrityAuditSlots) foragy-squad digestandagy-squad bundle.
[!NOTE]
mcp/index.jsvalidates JSON-RPC 2.0 request IDs (typeof id === "string"orNumber.isSafeInteger(id); otherwise-32600), decodes stdio payloads with fatal UTF-8 (-32700on invalid UTF-8), drains stdout cleanly on stdin EOF, returns JSON-RPC-32602(Invalid params) for malformedtools/callparams, unknown tool names, or non-objectparams.arguments, and returns{ isError: true }inside tool results for schema, workspace, or manifest validation errors (MCP-002).
Manifest (mcp/briefs.mjs & mcp/dispatch.mjs)¶
{
"squads": {
"storage": {
"lead": {
"role": "Storage Lead",
"objective": "Summarize the storage review",
"scopeFiles": ["src/storage.js"]
},
"specialists": [
{
"role": "WAL Reviewer",
"objective": "Review the write-ahead log",
"scopeFiles": ["src/wal.js"]
}
]
}
}
}
Manifest structure rules¶
- Single-squad validation: Compiling one working squad validates its specialists and its own
lead(when defined) without rebuilding unrelated sibling squads. - Custom roles vs. custom manifests: Use
task+roles(plus optionalreadOnly: true/--read-onlyor per-roleroleScopes/--role-scope <role=path>) for fast multi-role flat cohorts; switch to inlinemanifestormanifestPathwhen workers need custom per-workerobjective/instructions, per-workermodel, domainleads, or multiple parallel squads (omitsquadIdinsquad_plannerto compile all squads). Passingroles,scopeFiles,readOnly, orroleScopesalongsidemanifest/manifestPathis rejected. - Aliases and reserved IDs:
childrenis an alias forspecialists(a squad cannot define both). You can place lead fields directly on the squad object instead of underlead, as long as you do not mix both forms.all_l1and retiredadversarial_*keys cannot be used as squad IDs insidesquads. Exactintegrity_auditorandintegrity_auditor-<targetSquad>keys are permitted only as optional flat integrity auditor overrides (filtered out of working squads); malformed or case-variantintegrity_auditor*keys (such asintegrity_auditor_custom,INTEGRITY_AUDITOR, orintegrity_auditor-) are rejected. - Canonical casing: Agent fields in
mcp/briefs.mjsplusreadOnlyinmcp/planner.mjsaccept camelCase and non-conflicting PascalCase aliases compared structurally withutil.isDeepStrictEqual(for example, identicalscopeFilesarrays in both cases pass cleanly; conflicting values throw). - Planner & wire limits: There is no hardcoded cap on squad count or specialists per squad, but code enforces
MAX_SWARM_NAME_LENGTH = 24chars (deduplicated with-2,-3, ...; passoccupiedWorkerNamesacross multi-call/swarmadditions),squad-<encodeURIComponent(id)>directory names<= 255UTF-8 bytes,reportPath()slot length headroom soPARTIAL <path> —plusSWARM_MENTION_RESERVE_BYTES = 26andMIN_OBSERVATION_BYTES = 16stays<= 500UTF-8 bytes, andMAX_STDIO_PAYLOAD_BYTES = 10 MiBdefault (AGY_MAX_STDIO_PAYLOAD_BYTES) onmcp/index.js. See Scaling swarms, custom role configurations, and limits.
Agent field contract¶
| Field | Requirement | Rules and defaults |
|---|---|---|
objective |
Required | Plain task statement for the worker or lead. |
scopeFiles |
Required (>= 1) |
Workspace-relative files or directories without trailing / ("." and "docs" are valid; "docs/", absolute paths, \ separators, . or .. segments, and newlines are rejected by mcp/briefs.mjs). |
role, instructions, expectedDeliverable |
Optional | Optional role label, custom guidance, and deliverable description. |
readOnly |
Optional | Boolean (ReadOnly alias supported). Exempts read-only specialists or leads from squad_planner writable scopeFiles overlap checks (planning metadata only). |
typeName |
Optional | Defaults to self. Disallowed read-only or sandboxed presets (research, browser, image-generator) are rejected. |
model |
Optional | Defaults to inherit in dispatch_squad (only inherit, flash_lite, flash, or pro pin directly under dispatch_squad; any other explicit ID defaults to inherit with a warnings[] advisory recommending squad_planner under executionMode: "swarm"). |
workspace |
Optional | Manifest agent workspace must be inherit in both dispatch_squad and squad_planner (configure /swarm copy isolation via top-level workspaceIsolation). |
Stages and Pointer-Over-Wire¶
- Plan and record launch metadata: Call
squad_planner(MCP/swarmprimary flow; omitsquadIdto compile all working squads with optionaltopology,workspaceIsolation,boardSince, andboardSeqs) ordispatch_squad(invoke_subagentfallback viaall_l1or a squad ID). Review the compiled payload, pass each entry verbatim, and record the operator, shared workspace, acceptance criteria, report slots,<cohortBaseSeq>cursor, and native child IDs from launch receipts. - Write workspace report slots: Each worker writes one evidence report at
scratch/agy-squad/squad-<encoded-id>/lead/report.mdorspecialist-N/report.md(or under customreportRoot). Pre-create unused slots before launch, use fresh squad IDs on retries, include source locations or command outputs with exit codes, and preserve contradictions or gaps. - Send
<= 500byte receipts: Each child posts one single-line receipt of at most500UTF-8 bytes:READY <report-path> — <concrete observation>,PARTIAL <report-path> — <observation and blocker>, orNO_REPORT — <reason>. The parent matches each sender to its assigned slot, ignores exact duplicates, and inspects conflicts. - Yield for Reactive Wakeup: Wait via Reactive Wakeup, then inspect
/agents(orswarm{action: "status"}) at the evidence checkpoint (10 minutes by default, longer when work requires it). Extend work showing progress, allow for approval waits, and redirect or stop work stuck on identical output. Record agent termination and command cleanup separately. - Enforce the Squad Lead Patrol Gate: After workers finish or stop, the parent or squad lead audits execution traces, rejects ungrounded or sycophantic reports (
FAILorPARTIAL), and checks material claims against final files (Subagent Alignment Policy: guessing from memory is prohibited; every claim cites an executed tool or primary source line). The lead records its verdict (Content Verdict: PASS,FAIL, orBLOCKED; bareVerdict:is accepted only as a legacy alias) and verified file hashes, rechecking changed inputs. - Run the Independent Integrity Auditor (
audit-<id>/integrity_auditor): After working squads finish and before acceptance, run the flat integrity auditor: - Canonical Flat Integrity Auditor: On
/swarm, spawnaudit-<id>(scratch/agy-squad/squad-integrity_auditor/specialist-1/report.mdfor single-squad manifests, flat or layered, orscratch/agy-squad/squad-integrity_auditor-<targetSquad>/specialist-1/report.mdfor multi-squad manifests, flat or layered) viasquad_planner. Oninvoke_subagent, calldispatch_squad({ squadId: "integrity_auditor:<targetSquad>" })(orintegrity_auditorfor single-squad manifests). Computeagy-squad digest <record.json>(oragy-squad bundle-init --digest) first so each auditor recordsTarget Squad: <targetSquad>,Evidence Digest: <64-hex>, and strictlyIntegrity Verdict: CLEANorIntegrity Verdict: INTEGRITY VIOLATION(never a contentPASS). Legacyadversarial_l1,adversarial_flat, andadversarial_reviewauto-discovery have been removed. - Acceptance gate:
agy-squad bundle <record.json>(andagy-squad finalize <record.json>) enforcesrequireIntegrityAudit: trueby default (pass--allow-unauditedorrequireIntegrityAudit: falseto opt out).bundleReportsinmcp/handoffs.mjshashes all matching integrity audit reports (integrityAudits+integrityAudit), persistsschemaVersion: 2andauditPolicy("required"|"unaudited-explicit"), and guards against silent overwrites (--replace/--predecessor <sha256>).verifyenforces the persistedauditPolicyand confirms matchingEvidence Digest,Target Squad,Integrity Verdict: CLEAN, andverifiedFilesdigests.
File scope in a brief describes the worker's assigned target paths; host-level write enforcement remains controlled by Antigravity permissions and workspace isolation.
Governance CLI & report cleanup (agy-squad, mcp/handoffs.mjs, mcp/verdicts.mjs)¶
Run agy-squad <command> from the shared workspace root (inside a local Agy-Squad source checkout, you may also run node bin/agy-squad.mjs <command>; run agy-squad help [<command>] or agy-squad <command> --help for focused flags and examples; mcp/handoffs.mjs is the underlying JS library module whose standalone CLI entrypoint was removed in PR #5). Leading ./ workspace-relative paths (for example, ./docs/tools.md) and Windows \ relative paths on win32 (for example, .\scratch\record.json) are normalized uniformly at the CLI boundary across downstream verbs (plan, bundle-init, fingerprint, inspect, digest, bundle, verify, finalize, prune, verdict, and collect), while internal JSON/API contracts keep canonical POSIX / paths. Flat and task plans also emit workers[i].synthesisSlot pointing to the coordinator-authored lead/report.md path. Bundling and pruning support both default (scratch/agy-squad/squad-<id>/) and custom reportRoot layouts.
CLI subcommands¶
| Command | Purpose and inputs |
|---|---|
setup [--check] |
Installs or synchronizes the native plugin, 4 skills (pr-review, full-review, self-diagnosis, swarm-governance), plugin mcp_config.json, and agy-squad CLI shims (install is an alias; --check runs read-only preflight validation). |
status [--json] |
Checks live plugin link, skills, docs, canonical plugin MCP registration, CLI shim, and non-fatal companion agy-context (>= 2.0.1) / rtk (>= 1.1.0) availability. |
uninstall [--restore-backups] |
Removes the plugin link, MCP registration, CLI shims, and stale schema caches; --restore-backups restores prior backups. |
restore-backups |
Restores pre-install configuration backups (mcp_config.json.agy-squad.bak / config.json.agy-squad.bak, with read-only fallback on legacy .bak files). |
dispatch (--squad <id> \| <id>) [--manifest <path>] |
Exposes dispatch_squad (mcp/dispatch.mjs) for invoke_subagent cohorts (all_l1, <squadId>, or integrity_auditor[:<target>]). |
plan (--manifest <path> \| "<task>") [options] |
Exposes squad_planner (mcp/planner.mjs) from the CLI (--board-since, --board-seq, --occupied-worker, etc.). In swarm mode, bundle templates use each swarm member name as assignments[].conversationId and handoffs[].sender. |
collect (--plan <plan.json> \| --record <record.json> \| --squad <id>) --from <worktree-dir>... |
Safely collects non-empty specialist/lead/auditor report slots from /swarm share or branch worktrees into the coordinator workspace before bundle and kill, rejecting symlink escapes and inter-worktree conflicts (--workspace, --report-root, --overwrite, --dry-run, --strict, --allow-empty). |
bundle-init --plan <plan.json> [options] [<verified-file>...] |
Generates a pre-filled bundle-record.json from squad_planner output and provenanceScaffold (supports --provenance, --squad, --workspace, --report-root, --verdict, --file, --id-map, --handoffs, --handoff, --allow-unaudited, --allow-non-passing, --allow-partial, --digest, --out, --replace). |
verdict [--integrity] <report.md> |
Calls mcp/verdicts.mjs (parseContentVerdict or parseIntegrityVerdict) to parse a strict single-line Content Verdict: PASS\|FAIL\|BLOCKED (legacy alias Verdict: ...), or Integrity Verdict: CLEAN\|INTEGRITY VIOLATION with --integrity, rejecting hedged or conflicting lines. |
fingerprint <file...> |
Maps workspace-relative file paths to SHA-256 digests for verifiedFiles. Capture hashes before and after checks on final work inputs. |
inspect <record.json> |
Checks the recorded cohort against native messages and readable reports (workspace, ordered assignments with conversationId and report, and handoffs with native sender and exact message). |
digest <record.json> [--allow-non-passing] [--allow-partial] |
Computes the deterministic 64-hex Evidence Digest binding squadId, verifiedFiles, lead/report.md, and specialist reports before audit-<id> signs CLEAN (opt-in --allow-non-passing / --allow-partial for non-PASS or PARTIAL/NO_REPORT failure bundles). |
bundle <record.json> [--allow-unaudited] [--allow-non-passing] [--allow-partial] [--replace] [--predecessor <sha256>] |
Requires squadId, synthesizer verdict: "PASS" (unless --allow-non-passing for FAIL/BLOCKED), verifiedFiles hashes, unambiguous matching verdict in lead/report.md, and matching Evidence Digest: <64-hex> + Integrity Verdict: CLEAN across all matching auditor slots (unless --allow-unaudited). Writes v2 lead/report.sources.json and requires --replace or --predecessor <sha256> to overwrite a different existing bundle. |
verify <report.sources.json> [--prune [--keep-reports]] |
Enforces persisted auditPolicy, archived Markdown verdicts, every integrityAudit / integrityAudits digest and Evidence Digest, verifiedFiles hashes, and any remaining loose reports (and optionally prunes loose reports in the same process when --prune is passed). |
finalize <record.json> [--allow-unaudited] [--allow-non-passing] [--allow-partial] [--replace] [--predecessor <sha256>] [--prune [--keep-reports]] |
Ergonomic one-step wrapper that runs inspect -> bundle -> verify (plus optional --prune [--keep-reports]) deterministically and emits { inspected, bundled, verified, pruned } JSON while keeping every granular subcommand intact. |
prune <report.sources.json> <accepted-sha256> [--keep-reports] |
Safely unlinks only verified loose specialist reports (re-verifying inode identity and SHA-256) after bundle and verify pass, unless --keep-reports or retainReports: true is set. |
help [<command>] |
Print top-level CLI usage or focused help for a specific subcommand (equivalent to --help / <command> --help). |
Bundle record and handoffs schemas¶
agy-squad bundle-init --plan <plan.json> ... generates a <bundle-record.json> pre-populated from bundleRecordTemplates.<squadId>, provenanceScaffold, and fingerprinted verifiedFiles. Pass specialist receipts via --handoffs <handoffs.json> (a JSON array of { sender, message } objects) or repeatable --handoff "<sender>=<message>" flags.
--handoffs <handoffs.json> schema (mcp/handoffs.mjs):
[
{
"sender": "storage-wal-reviewer",
"message": "@storage-lead READY scratch/agy-squad/squad-storage/specialist-1/report.md — src/storage.js:42 fsync guard verified (npm test exit 0)"
}
]
Each entry requires nonempty sender (matching assignments[].conversationId, which is the compiled workerName in /swarm mode) and a single-line <= 500 UTF-8 byte message using the literal U+2014 em-dash (—) separator (READY <slot> — <observation>, PARTIAL <slot> — <observation>, or NO_REPORT — <reason>, with optional leading @mention prefixes).
<bundle-record.json> schema (inspect, digest, bundle, finalize):
{
"squadId": "storage",
"workspace": "/absolute/path/to/your-repo",
"reportRoot": "scratch/agy-squad",
"verdict": "PASS",
"verifiedFiles": {
"src/storage.js": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"assignments": [
{
"conversationId": "storage-wal-reviewer",
"report": "scratch/agy-squad/squad-storage/specialist-1/report.md"
}
],
"handoffs": [
{
"sender": "storage-wal-reviewer",
"message": "@storage-lead READY scratch/agy-squad/squad-storage/specialist-1/report.md — src/storage.js:42 fsync guard verified (npm test exit 0)"
}
],
"requireIntegrityAudit": true,
"integrityAuditSlots": [
"scratch/agy-squad/squad-integrity_auditor/specialist-1/report.md"
]
}
Optional boolean flags allowNonPassing: true and allowPartial: true mirror --allow-non-passing and --allow-partial. All workspace paths inside JSON records must use canonical POSIX / separators.
agy-squad flags reference¶
| Flag | Applies to | Behavior |
|---|---|---|
--check / -c |
setup, install |
Run read-only preflight check without writing files (cannot pair with --restore-backups or --uninstall). |
--restore-backups |
uninstall |
Restore backed-up configuration files after removing Agy-Squad entries. |
--json |
status |
Emit machine-readable installation and companion status JSON. |
--manifest <path> |
plan, dispatch |
Load squads from a workspace manifest file (mutually exclusive with positional <task> in plan). |
--squad <id> |
plan, dispatch, collect, bundle-init |
Target a specific squad ID. |
--topology flat\|layered |
plan |
Override multi-squad compilation topology (flat strips leads; layered requires leads). |
--mode swarm\|subagent |
plan |
Select native /swarm (swarm, default) or invoke_subagent (subagent). |
--model <id> |
plan |
Pin a model ID for workers (under swarm mode, marks models unverified unless listed via --known-model). |
--known-model <id> |
plan |
Repeatable. Supplies allowed model IDs from swarm{action: "models"}; pinned models outside the list are rejected. |
--occupied-worker <name> |
plan |
Repeatable. Reserves pre-existing /swarm roster names (occupiedWorkerNames) when adding cohorts to an active board. |
--board-since <seq> / --board-seq <seq> |
plan |
Scope working lead/specialists read_board directives via boardSince (non-negative integer cursor) and integrity auditor directives via repeatable boardSeqs message sequence IDs. |
--workspace-isolation inherit\|share\|branch |
plan |
Choose Antigravity /swarm worker workspace mode (inherit, share, or branch). |
--scope <path> |
plan |
Repeatable. Workspace-relative scope paths for task-based planning. |
--role <title> |
plan |
Repeatable. Specialist role titles for task-based planning. |
--read-only |
plan |
Mark inline task specialists readOnly: true to exempt them from writable overlap warnings. |
--role-scope <role=path> |
plan |
Repeatable. Assign per-role workspace-relative scopeFiles for inline task planning (roleScopes). |
--no-integrity |
plan |
Omit the integrity_auditor plan stage and set requireIntegrityAudit: false in bundleRecordTemplates. |
--report-root <path> |
plan, collect, bundle-init |
Custom workspace-relative root for report slots instead of scratch/agy-squad. |
--plan <path> / --record <path> |
collect, bundle-init |
Supply squad_planner JSON output (--plan) or a bundle record (--record in collect). |
--from <worktree-dir> / --workspace <dir> |
collect, bundle-init |
Repeatable source worktree directories (--from in collect) and optional target coordinator root (--workspace). |
--overwrite / --dry-run / --strict / --allow-empty |
collect |
Overwrite differing coordinator slots, preview copies without writing, fail on missing slots, or allow zero found slots. |
--provenance <path> / --verdict <v> / --file <path> |
bundle-init |
Merge external provenance entries, supply an explicit verdict (PASS\|FAIL\|BLOCKED), and add repeatable verified file inputs. |
--id-map <worker=id> / --handoffs <json> / --handoff <sender=msg> |
bundle-init |
Map worker names to runtime IDs and inject handoff receipts from JSON or inline sender=message pairs. |
--digest |
bundle-init |
Compute and output evidenceDigest alongside the initialized record (requires --handoffs or --handoff; --out optional). |
--out <path> |
bundle-init |
Write the initialized <record.json> to disk instead of printing only to stdout. |
--integrity |
verdict |
Parse Integrity Verdict: CLEAN\|INTEGRITY VIOLATION instead of a content verdict. |
--allow-unaudited |
bundle, finalize, bundle-init |
Opt out of the default requireIntegrityAudit: true gate. |
--allow-non-passing |
digest, bundle, finalize, bundle-init |
Allow archiving/digesting a FAIL or BLOCKED cohort (allowNonPassing: true). |
--allow-partial |
digest, bundle, finalize, bundle-init |
Allow archiving/digesting cohorts containing PARTIAL or NO_REPORT specialist slots (allowPartial: true). |
--replace |
bundle, finalize, bundle-init |
Allow overwriting an existing lead/report.sources.json bundle or --out record file. |
--predecessor <sha256> |
bundle, finalize |
Require the existing lead/report.sources.json bundle's SHA-256 to match <sha256> before overwriting. |
--prune / --keep-reports |
verify, finalize, prune |
--prune (on verify or finalize) prunes verified loose specialist-<N>/report.md files in the same process; --keep-reports retains loose reports after verification passes. |