Core workflows: orchestrate, self-diagnose, review, and tear down¶
Agy-Squad runs four connected workflows across Antigravity Desktop (IDE) and the Antigravity CLI (agy) on Linux, macOS, and Windows:
- Task-proportional orchestration (
squad_planner/agy-squad plan,dispatch_squad/agy-squad dispatch, andagy-squad(collect,bundle-init,fingerprint,inspect,digest,bundle,verify,finalize,prune,verdict) backed bymcp/handoffs.mjs) - Recursive harness self-diagnosis (
self-diagnosis) - Governed PR, non-diff, and Day-1 launch reviews under Standard v1.5.0 (
pr-review,full-review, andday-one-review) - Three-scope evidence retention and deterministic scratch teardown
For the canonical definition of every role, Task-Spec vs. Execution-Modifier skill composition, MCP/CLI surface map, and the 4-check runtime closure gate, see Roles, skill workflows, and runtime closure.
1. Orchestrate proportional specialist or lead cohorts¶
Agy-Squad structures each cohort run into four ordered stages: Pre-Flight Intake, Working Cohort, Independent Integrity Audit, and Acceptance Bundling.
Phase 0: Pre-flight intake interview¶
Before compiling manifests or launching workers, the primary agent runs an interactive intake check via ask_question (or a multiple-choice prompt) to lock the operator choices below when unspecified:
| Decision | Options | Governing control |
|---|---|---|
| Topology | Ask neutrally (no default bias): Flat (specialists report to parent/coordinator), Layered (all_l1 leads in dispatch_squad or domain coordinators in /swarm), or single-squad run |
squad_planner (omit squadId for all squads), dispatch_squad (all_l1 / <squadId>), or diagnose.mjs --print-dispatch all_specialists |
| Workspace isolation | inherit (shared coordinator root for read-only or disjoint scopeFiles), share (shared-storage copy), or branch (isolated clone) |
squad_planner (workspaceIsolation, /swarm only; subagent requires inherit) |
| Teardown and provenance | Full retention (--keep-reports, preserving scratch/agy-squad/) or automatic atomic teardown (--teardown) |
agy-squad prune / agy-squad finalize --prune and diagnose.mjs |
| Model | Coordinator active model (default: omit model/--model) or explicit user-selected model ID (swarm{action: "models"}) |
squad_planner (model, knownModels) and swarm{action: "status"} |
| Integrity rigor | Independent flat integrity auditor (audit-<id> on /swarm, integrity_auditor via slot; emits CLEAN or INTEGRITY VIOLATION) or --allow-unaudited opt-out |
agy-squad bundle / agy-squad finalize and mcp/verdicts.mjs |
| Instruction self-containment | Explicit file paths, objectives, and criteria in every brief; unanchored codes (such as H4 or D2) are rejected |
mcp/briefs.mjs |
Stage 1: Working cohort execution¶
- Compile the stage: For Antigravity native
/swarm,squad_planner(agy-squad plan) compilesswarmAddpayloads and a parent-authoredprovenanceScaffold(omitsquadIdto compile all manifest squads). Forinvoke_subagent,dispatch_squad(agy-squad dispatch) builds direct working specialists (squadId: "<id>"), squad leads (squadId: "all_l1"), or self-diagnosisall_specialistsviadiagnose.mjs --print-dispatch all_specialists(docs/tools.md). - Inject brief invariants:
mcp/briefs.mjsadds alignment rules, flattery penalties, and transcript query rules to every compiled brief so the operator does not repeat boilerplate across squads. - Query transcripts in batches: Squad leads and reviewers inspect child sessions with single-pass batch CLI calls (
agy-context transcript query --id <id> --summaryoragy-context transcript read --id <id> --last-turns 10). Iterative 1-to-2-step transcript polling is prohibited. - Write to workspace report slots:
dispatch_squadsetsTypeName: "self"andWorkspace: "inherit"so each specialist writes directly toscratch/agy-squad/.../specialist-<N>/report.md. - Send a
<= 500byte receipt (Pointer-Over-Wire): Each child posts one single-line receipt (READY,PARTIAL, orNO_REPORT) under500UTF-8 bytes throughsend_message, waking its parent via Reactive Wakeup without pasting full reports into parent context. - Run the Squad Lead Patrol Gate: The squad lead checks leaf traces against primary source files and test output, rejects guessed or sycophantic claims (
Subagent Alignment Policy), and writeslead/report.mdwithContent Verdict: PASS,FAIL, orBLOCKEDon its own line (bareVerdict:is accepted only as a legacy alias).
Stage 2: Independent integrity auditor¶
Run the integrity auditor after working squads finish and before acceptance. For Antigravity native /swarm runs, follow .agents/skills/swarm-governance/SKILL.md.
- Dispatch or spawn the flat auditor: On
/swarm, add flataudit-<id>(squad-integrity_auditor/specialist-1/report.mdfor single-squad manifests, flat or layered, orsquad-integrity_auditor-<targetSquad>/specialist-1/report.mdfor multi-squad manifests, flat or layered). Oninvoke_subagent, calldispatch_squadwithsquadId: "integrity_auditor:<targetSquad>"(orintegrity_auditorfor single-squad manifests). Legacyadversarial_l1,adversarial_flat, andadversarial_reviewstages have been removed. - Audit execution traces: The auditor runs single-pass batch CLI queries (
agy-context transcript list --parent <id> --lineage,agy-context transcript query --id <id> --summary, oragy-context transcript read --id <id> --last-turns 10, or verifies a coordinatoragy-context transcript export --parent <id> --sanitized --out scratch/...index) to confirm that specialists executed real tools instead of guessing from memory, avoided sycophantic filler, and had their claims checked by the squad lead. - Emit an audit verdict with Evidence Digest: Run
agy-squad digest <record.json>(oragy-squad bundle-init --digest) first so the auditor recordsTarget Squad: <targetSquad>,Evidence Digest: <64-hex>, and strictlyIntegrity Verdict: CLEANorIntegrity Verdict: INTEGRITY VIOLATION(never a contentPASS).
Stage 3: Acceptance and cryptographic bundling¶
- Enforce the dual-verdict gate:
agy-squad finalize <record.json> [--prune](oragy-squad bundle <record.json>) requiresContent Verdict: PASSonlead/report.md,Evidence Digest: <64-hex>, andIntegrity Verdict: CLEANfor every auditor slot matchingTarget Squadviamcp/verdicts.mjs. AnyINTEGRITY VIOLATION, stale digest, hedged verdict, or missing audit blocks bundling unless--allow-unauditedis passed (auditPolicy: "required"vs"unaudited-explicit"). - Record and verify SHA-256 digests:
mcp/handoffs.mjshashes all citedverifiedFiles, specialist reports, and everyintegrityAudit/integrityAuditsreport intolead/report.sources.json.agy-squad finalize <record.json> [--prune [--keep-reports]]runsinspect -> bundle -> verify(+ optional prune) in one call, while granularagy-squad verify <report.sources.json>enforces the persistedauditPolicyalongside archived Markdown and digest matches, andagy-squad prune <report.sources.json> <accepted-sha256> [--keep-reports]safely removes matching loose specialist reports.
2. Diagnose and optimize the harness (self-diagnosis)¶
The self-diagnosis skill uses Agy-Squad's staged dispatch and handoff contracts to audit the repository itself. The workflow requires operator supervision and makes no autonomous code changes.
Run the zero-subagent profiler¶
From the repository root, run diagnose.mjs to check skill frontmatter, relative links, byte/token budgets, dispatch_squad and squad_planner compilation, handoff pipeline canaries, and the v1.5.0 review ledger schema:
# Markdown diagnostic report:
node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdown
# JSON output for scripts and CI:
node .agents/skills/self-diagnosis/scripts/diagnose.mjs
# Validate a specific PR review ledger under docs/reviews/:
node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
--ledger docs/reviews/rebuild-wsl-dispatch-review-r2.md
Compile and run targeted diagnostic cohorts¶
For deeper audits, .agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json defines three diagnostic squads (skill_and_pr_review_audit, runtime_and_contract_diagnosis, and token_and_execution_optimization):
# Primary (/swarm coordinator plan, Flat or Layered, inherit workspace for read-only audit):
node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
--print-plan [--mode swarm] [--workspace-isolation inherit]
# Or compile invoke_subagent stages via dispatch_squad (flat squad or all_l1 leads):
node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
--print-dispatch skill_and_pr_review_audit --parent-id <parent-conversation-id>
node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
--print-dispatch all_l1 --parent-id <parent-conversation-id>
Every diagnostic pass follows one fixed sequence:
run zero-subagent profiler -> launch cohort -> reconcile & bundle reports -> transcribe 1-ID-per-row into docs/reviews/<slug>.md -> run diagnose.mjs --teardown -> remediate -> re-verify with the same specialists -> terminate subagents
3. Review pull requests to the v1.5.0 standard¶
The pr-review skill, full-review skill, day-one-review skill, and PR Review Standard v1.5.0 define the repository review contract:
| Standard section | Requirement |
|---|---|
| Section 1: Commit and session provenance | Pin base/head SHAs, dirty working-tree deltas, CI run IDs, and an append-only Session Provenance table (Session # | Operator Conversation ID | Parent Session | Date | Base..Head + Working-Tree State | Skill / Topology Invoked). |
| Sections 2 and 3: Architecture-before-runtime trace | Trace normative architecture docs or ADRs (when present in the target repository) to public contracts, source code, and tests before evaluating runtime behavior. |
| Section 4: Eleven review categories | Map every changed file to one primary category across ARCH, DOC, SKILL, MCP, RUN, SVC, DB, SCRIPT, TEST, DEP, and SEC (4.11 security, trust boundaries, and vulnerabilities). |
Sections 7, 8, and 9: 1 ID = 1 Row durability |
Give every distinct P0 through P3 finding its own row (range/umbrella IDs fail diagnose.mjs) with one of six statuses: Open (Pre-Remediation), Closed, Residual (Open), Closed (Post-Remediation), Deferred / Won't Fix, or Closed (By Design) / Informational. Record post-remediation residuals in Section 8 and /self-diagnosis cohort provenance plus bundle SHA-256 digests in Section 9. |
diagnose.mjs and npm test enforce pr-review locally in the repository (not as a GitHub branch-protection rule).
[!WARNING]
diagnose.mjsstatus (HEALTHY, finding counts) reflects the structure and contents of the target review ledger, which the author of a change usually writes. It checks that the ledger is well-formed and internally consistent. It does not independently re-review the code. TreatHEALTHYas evidence that the process was followed, not as an independent review. An independent reviewer's findings take precedence over a self-authored ledger's counts.
4. Three-scope evidence retention and teardown contract¶
Agy-Squad separates native worker cleanup from report bundling and ledger-gated scratch deletion across three scopes:
| Lifecycle scope | Governing tool | What is cleaned up | What is retained and gated |
|---|---|---|---|
1. Native /swarm planning and workspace |
agy-squad plan (squad_planner) + Antigravity /swarm |
Native /swarm owns worker lifecycles and kill cleanup (workspace: "share" / "branch" worktrees); agy-squad creates no temporary .agents/plugins/, .agents/agents/, or run-<uuid>/ directories (the legacy agy-squad run PTY launcher is retired) |
Preserves workspace-relative specialist/lead reports and parent-authored provenanceScaffold under scratch/agy-squad/squad-<id>/ (or custom reportRoot) |
| 2. Handoff and integrity bundle | agy-squad (finalize, bundle, verify, prune) |
prune (or finalize --prune) deletes loose specialist-<N>/report.md files only after bundle and verify succeed (unless --keep-reports or retainReports: true is set) |
Preserves lead/report.md (Content Verdict: PASS), lead/report.sources.json (SHA-256 digests of all inputs and specialist reports), and verified integrityAudit evidence (Integrity Verdict: CLEAN) |
| 3. Self-diagnosis wave | diagnose.mjs --teardown |
Removes scratch/agy-squad/squad-<id> and empty scratch/ parent directories |
Refuses deletion (unless --force is passed) until lead/report.sources.json verifies and the target docs/reviews/<slug>.md ledger is schema-valid, newer than the bundle, and records the cohort's findings |
To tear down completed self-diagnosis cohorts after updating the target review ledger:
node .agents/skills/self-diagnosis/scripts/diagnose.mjs --teardown all \
--ledger docs/reviews/<target-review-slug>.md
After --teardown succeeds and no open blocking findings remain, stop spawned subagents via manage_subagents(Action='kill', ConversationIds=[...]) (or /agents in the CLI) or swarm{action: "kill", name} for /swarm workers, then confirm child processes have exited (Stopping agents).