agy-squad 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/.agents/skills/full-review/SKILL.md +89 -0
  2. package/.agents/skills/full-review/references/evidence-intake.md +146 -0
  3. package/.agents/skills/full-review/references/report-template.md +216 -0
  4. package/.agents/skills/full-review/references/review-roles.md +91 -0
  5. package/.agents/skills/pr-review/SKILL.md +60 -0
  6. package/.agents/skills/pr-review/references/pr-review-standard.md +163 -0
  7. package/.agents/skills/self-diagnosis/SKILL.md +63 -0
  8. package/.agents/skills/self-diagnosis/references/execution-and-teardown.md +71 -0
  9. package/.agents/skills/self-diagnosis/references/optimization-and-review-rubric.md +61 -0
  10. package/.agents/skills/self-diagnosis/resources/comparative-research-manifest.json +42 -0
  11. package/.agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json +144 -0
  12. package/.agents/skills/self-diagnosis/scripts/diagnose.mjs +1971 -0
  13. package/.agents/skills/swarm-governance/SKILL.md +59 -0
  14. package/.agents/skills/swarm-governance/references/bundling-and-wire-format.md +88 -0
  15. package/.agents/skills/swarm-governance/references/intake-and-planning.md +120 -0
  16. package/.agents/skills/swarm-governance/references/large-swarms.md +39 -0
  17. package/CHANGELOG.md +16 -0
  18. package/LICENSE +21 -0
  19. package/README.md +156 -2
  20. package/bin/agy-squad.mjs +293 -0
  21. package/docs/assets/architecture-overview.svg +39 -0
  22. package/docs/assets/manifest-and-modes.svg +39 -0
  23. package/docs/assets/role-and-verdict-gate.svg +39 -0
  24. package/docs/assets/skill-role-workflows.svg +39 -0
  25. package/docs/assets/swarm-lifecycle.svg +39 -0
  26. package/docs/benchmarks.md +102 -0
  27. package/docs/concepts.md +81 -0
  28. package/docs/core-workflows.md +128 -0
  29. package/docs/getting-started.md +116 -0
  30. package/docs/index.md +47 -0
  31. package/docs/plans/LEDGER.md +24 -0
  32. package/docs/plans/comparative-harness-architecture-retest.md +1174 -0
  33. package/docs/plans/comparative-harness-architecture-teamwork.md +1170 -0
  34. package/docs/plans/comparative-harness-architecture.md +256 -0
  35. package/docs/plans/native-enforcement-ledger.md +126 -0
  36. package/docs/plans/pr3-option-b-fixes.md +803 -0
  37. package/docs/plans/wsl-cli-verification.md +55 -0
  38. package/docs/reviews/post-pr5-governance-review.md +221 -0
  39. package/docs/reviews/pr1-code-review-ledger.md +581 -0
  40. package/docs/reviews/pr1-production-readiness-review.md +764 -0
  41. package/docs/reviews/pr2-documentation-review-ledger.md +380 -0
  42. package/docs/reviews/pr3-squad-alignment-full-review.md +1021 -0
  43. package/docs/reviews/pr4-swarm-governance-pivot-review.md +593 -0
  44. package/docs/reviews/pr5-full-review-direction.md +330 -0
  45. package/docs/reviews/pr5-independent-review.md +266 -0
  46. package/docs/reviews/pr5-layered-swarm-review.md +513 -0
  47. package/docs/reviews/pr5-phase2-swarm-planner-review.md +470 -0
  48. package/docs/reviews/pr5-reconciled-review.md +573 -0
  49. package/docs/reviews/rebuild-wsl-dispatch-review-r2.md +427 -0
  50. package/docs/reviews/rebuild-wsl-dispatch-review.md +552 -0
  51. package/docs/roles-and-workflows.md +115 -0
  52. package/docs/stopping-agents.md +39 -0
  53. package/docs/tools.md +122 -0
  54. package/install.ps1 +5 -0
  55. package/install.sh +4 -0
  56. package/mcp/briefs.mjs +202 -0
  57. package/mcp/dispatch.mjs +280 -0
  58. package/mcp/handoffs.mjs +814 -0
  59. package/mcp/index.js +322 -0
  60. package/mcp/planner.mjs +755 -0
  61. package/mcp/verdicts.mjs +224 -0
  62. package/package.json +57 -4
  63. package/plugin.json +20 -0
  64. package/scripts/install-register.mjs +510 -0
  65. package/scripts/release-preflight.mjs +142 -0
@@ -0,0 +1,102 @@
1
+ # Benchmarks: Agy-Squad vs. Antigravity Teamwork
2
+
3
+ On November 8, 2026, we ran a recorded sequential comparison between **Agy-Squad + Agy-Context-Saver 1.8.1 (`rtk 0.51.0`)** and **Antigravity `/teamwork` (`[skip-interview]` control)** on a two-domain event-relay fixture containing six planted `P1` and `P2` defects ([`benchmarks/teamwork-vs-squad/`](https://github.com/paragon-ux/Agy-Squad/tree/main/benchmarks/teamwork-vs-squad)).
4
+
5
+ ## Canonical recorded comparison (November 8, 2026)
6
+
7
+ Both arms caught all six planted defect categories (`6 / 6`). Agy-Squad + Agy-Context-Saver finished in **`6m 15s` (`375s`) vs. `26m 19s` (`1,579s`, `4.2x` faster)**, used **`64` vs. `645` transcript steps** (`10.1x` fewer steps), generated **`148.2 KB` vs. `817.4 KB` of raw transcripts** (`81.9%` smaller), and sent **`249 B` vs. `4,940 B` into the parent conversation** (`95.0%` fewer parent wakeup bytes).
8
+
9
+ | Metric | Agy-Squad + Agy-Context-Saver (`ab_audit`) | Antigravity `/teamwork` (`[skip-interview]`) | Recorded difference |
10
+ | --- | ---: | ---: | --- |
11
+ | **Planted defect categories caught** | **`6 / 6` (`100%`)** | **`6 / 6` (`100%`)** | Equal category recall (`18` vs. `25` total items reported) |
12
+ | **Active wall-clock time** | **`6m 15s` (`375s`)** | **`26m 19s` (`1,579s`)** | **`4.2x` faster (`76.2%` less time)** |
13
+ | **Time to first specialist delegation** | **`59s`** (`8.5 ms` compile) | **`91s`** (startup phase) | **`1.5x` faster initial delegation** |
14
+ | **Subagents spawned** | **`3`** (`1` lead, `2` specialists) | **`8`** (`teamwork` fleet) | **`2.7x` fewer subagents** |
15
+ | **Total transcript steps (`check_context_health`)** | **`64`** (`32 + 19 + 13`) | **`645`** (`50` to `129` across `8` agents) | **`10.1x` fewer steps (`90.1%` reduction)** |
16
+ | **Total assistant LLM turns** | **`26`** (`11 + 9 + 6`) | **`321`** (`25` to `63` across `8` agents) | **`12.3x` fewer turns (`91.9%` reduction)** |
17
+ | **Total tool calls** | **`32`** (`17 + 9 + 6`) | **`302`** (`24` to `57` across `8` agents) | **`9.4x` fewer tool calls (`89.4%` reduction)** |
18
+ | **Aggregate raw transcript size** | **`148.2 KB`** | **`817.4 KB`** | **`5.5x` smaller (`81.9%` byte reduction)** |
19
+ | **Parent wakeups and injected bytes** | **`1` wakeup (`249 B`)** | **`5` wakeups (`4,940 B`)** | **`19.8x` fewer parent bytes (`95.0%` reduction)** |
20
+ | **Artifact integrity verification** | **`20 ms`** (`handoffs.mjs verify` SHA-256 digests) | No separate SHA-256 source/report bundle check | Cryptographic input and report digest check |
21
+ | **Semantic correctness verification** | Parent/lead direct code and test inspection (`32` lead steps) | `2` dedicated LLM review agents (`reviewer_1` + `auditor_1`, `174` steps, `228.6 KB`) | Direct lead verification vs. separate verifier fleet |
22
+ | **Teardown policy and post-run Git status** | Explicit 3-scope teardown contract at the time of the run (`0` untracked Git files; `scratch/` gitignored; Phase 1, see note below) | No operator-facing teardown CLI documented (`41` untracked files, `207.9 KB` in `.agents/teamwork/`) | Governed lifecycle contract (`L41`) |
23
+
24
+ ## Observed contributors to the difference
25
+
26
+ 1. **Task-proportional topology (`3` agents vs. `8`):** For a two-domain audit (`gateway/` and `worker/`), `dispatch_squad` launches one squad lead and two domain specialists from `manifest.json`. `/teamwork` spawns a wrapper agent, an internal orchestrator, three exploratory agents, a report writer (`worker_report_1`), a reviewer (`reviewer_1`), and a forensic auditor (`auditor_1`).
27
+ 2. **Scoped lead verification and `20 ms` SHA-256 bundling vs. separate LLM review fleet:** In `Agy-Squad`, the squad lead inspects cited source lines directly, writes its synthesis report, and runs `node mcp/handoffs.mjs` (`bundle`, `verify` in `20 ms` producing SHA-256 `418d7ccbade0a14a5b2e165b706adf45275e7b20604df1dfe03c41a012abc945`, and `prune`). Digest verification confirms that cited inputs and reports match their recorded hashes while the lead's code inspection checks semantic correctness. `/teamwork` delegates verification to `reviewer_1` and `auditor_1` (`174` combined steps, `228.6 KB` of transcript).
28
+ 3. **Single-line `Pointer-Over-Wire` receipt (`249 B`) vs. five parent wakeups (`4,940 B`):** `Agy-Squad` keeps intermediate coordination inside the squad and wakes the parent once with a `249`-byte `READY` receipt. `/teamwork` wakes the parent four times with intermediate Sentinel progress updates before sending a `3,218`-byte completion summary.
29
+ 4. **RTK command rewriting and governed teardown ([`L41`](plans/LEDGER.md)):** With `Agy-Context-Saver 1.8.1` (`rtk 0.51.0`) active, `Agy-Squad` specialists read scoped files through `rtk read` and prune loose specialist reports after bundling.
30
+
31
+ ## Recorded session metrics and unit definitions
32
+
33
+ All session counts in `benchmarks/teamwork-vs-squad/results/telemetry.json` come from `agy-context-saver`'s `check_context_health` tool:
34
+
35
+ - **Transcript steps, turns, and tool calls:** Operational counts from `.system_generated/logs/transcript.jsonl` across every spawned subagent in each arm.
36
+ - **Raw transcript size (`148.2 KB` vs. `817.4 KB`) and parent wakeup bytes (`249 B` vs. `4,940 B`):** Measured in decimal kilobytes (`1,000 B`) and UTF-8 message bytes. These measure transcript and parent-inbox volume, not billed API token charges.
37
+ - **Finding adjudication (`6 / 6` categories vs. `18` and `25` total items):** Both arms caught all six planted defect categories (`N1` through `N6`). Total item counts (`18` in Agy-Squad vs. `25` in Teamwork) include sub-defects split out from `N6` (corrupt JSON reset, non-atomic write, off-by-one retry) plus secondary input-validation observations.
38
+
39
+ ## Benchmark fixture and six planted bugs
40
+
41
+ The fixture in `benchmarks/teamwork-vs-squad/fixture/` models a two-stage webhook relay (`gateway/gateway.mjs` and `worker/worker.mjs` + `worker/ledger.mjs`). Its unit tests (`test-gateway.mjs` and `test-worker.mjs`) pass in isolation while leaving six cross-module defects:
42
+
43
+ | ID | Priority | Location | Defect summary | Caught by Agy-Squad | Caught by `/teamwork` |
44
+ | --- | --- | --- | --- | :---: | :---: |
45
+ | `N1` | `P1` | `gateway/gateway.mjs:10` | `crypto.timingSafeEqual` called without buffer length check, throwing uncaught `RangeError` on short or odd-length hex signatures | Yes (`SYN-01`) | Yes (`SEC-01`) |
46
+ | `N2` | `P2` | `gateway/gateway.mjs:25` | `createRateLimiter` resets `bucket.lastRefillMs = nowMs` even when `intervals === 0`, starving token refill under steady sub-second traffic | Yes (`SYN-02`) | Yes (`REL-01`) |
47
+ | `N3` | `P1` | `gateway/gateway.mjs:40` vs. `worker/worker.mjs:4` | Gateway writes `headers['x-idempotency-key']` while worker requires `headers['x-request-id']`, dead-lettering `100%` of gateway envelopes with `MISSING_REQUEST_ID` | Yes (`SYN-03`) | Yes (`CON-01`) |
48
+ | `N4` | `P1` | `gateway/gateway.mjs:43` vs. `worker/worker.mjs:9` | Gateway emits `schemaVersion: "2.0"` while worker rejects anything other than `"1.0"` with `UNSUPPORTED_SCHEMA` | Yes (`SYN-04`) | Yes (`CON-02`) |
49
+ | `N5` | `P1` | `worker/worker.mjs:12` vs. `config.json:3` | Worker compares millisecond timestamp delta `Math.abs(nowMs - event.timestampMs)` against `config.maxSkewSeconds` (`300`) without `* 1000`, shrinking the 5-minute window to `300 ms` | Yes (`SYN-05`) | Yes (`BUG-01`) |
50
+ | `N6` | `P1` | `worker/ledger.mjs:9-21` & `worker/worker.mjs:16-28` | `readLedger` resets corrupt JSON to `[]` (wiping prior entries on non-atomic `writeFileSync`) and `attempt >= maxRetries` on 1-based `attempt` performs `0` retries when `maxRetries = 1` | Yes (`SYN-06`) | Yes (`REL-02` / `BUG-02`) |
51
+
52
+ ## Per-agent telemetry breakdown
53
+
54
+ ### Arm 1: Agy-Squad + Agy-Context-Saver (`3` subagents, `148.2 KB` total)
55
+
56
+ | Role | Conversation ID | Steps | Turns | Tool calls | Busy polls | Raw transcript |
57
+ | --- | --- | ---: | ---: | ---: | ---: | ---: |
58
+ | Event Relay Audit Squad Lead | `f1465008-b194-4217-b103-07bfb98d9454` | `32` | `11` | `17` | `0` | `78.3 KB` |
59
+ | Gateway Security & Rate-Limit Auditor | `5f8a9dd9-42cd-4331-9307-4edd8e02aa54` | `19` | `9` | `9` | `0` | `38.3 KB` |
60
+ | Worker Retry, Ledger & Contract Auditor | `472dbd4c-0f4c-45bf-8b24-ec69923d913f` | `13` | `6` | `6` | `0` | `31.6 KB` |
61
+
62
+ ### Arm 2: Antigravity `/teamwork` control (`8` subagents, `817.4 KB` total)
63
+
64
+ | Role | Conversation ID | Steps | Turns | Tool calls | Busy polls | Raw transcript |
65
+ | --- | --- | ---: | ---: | ---: | ---: | ---: |
66
+ | `teamwork` wrapper | `d00a4261-5d7c-4edd-bb27-8a1f277a5420` | `66` | `33` | `26` | `0` | `59.0 KB` |
67
+ | `teamwork_orchestrator` | `a6772a4a-25d7-411e-bfaf-9d14d0aa63c5` | `129` | `63` | `57` | `0` | `186.2 KB` |
68
+ | `explorer_gateway_1` | `1096662d-2e1e-4945-a512-11c8e077fd98` | `66` | `33` | `32` | `0` | `80.7 KB` |
69
+ | `explorer_worker_1` | `13d812cf-97c2-4372-8622-4ba9fe10e46f` | `84` | `42` | `41` | `0` | `107.2 KB` |
70
+ | `miner_contract_1` | `1d4582c6-d938-46a0-a52f-4f9ced1b8bc2` | `50` | `25` | `24` | `0` | `71.8 KB` |
71
+ | `worker_report_1` | `b67d2e43-bf6e-4981-b70b-8a3ef93e266a` | `76` | `38` | `37` | `0` | `83.9 KB` |
72
+ | `reviewer_1` | `c76fead5-bea3-464d-9865-55fb3f10d205` | `60` | `30` | `29` | `0` | `96.2 KB` |
73
+ | `auditor_1` | `cb702aa1-b3b3-4325-9fe7-1edfdea74ecd` | `114` | `57` | `56` | `0` | `132.4 KB` |
74
+
75
+ ## Documented teardown and evidence retention
76
+
77
+ > [!NOTE]
78
+ > **Historical comparison.** The November 8, 2026 run above used Agy-Squad's Phase 1 launcher (`agy-squad run --launch`, `bin/terminal.py`, `mcp/run-state.mjs`), which PR #5 retired ([`L17`](plans/LEDGER.md)). The run exercised the retained `dispatch_squad` staged compiler, `Pointer-Over-Wire` receipts, and `mcp/handoffs.mjs` (`bundle`/`verify`/`prune`). Managed CLI session cleanup from Phase 1 no longer exists because native `/swarm` owns worker lifecycles and `kill` cleanup. These numbers record the Phase 1 workflow and do not measure the current `squad_planner` + `/swarm` path.
79
+
80
+ After Phase 2, **Agy-Squad's evidence-retention contract (handoff bundle and self-diagnosis scopes)** ([`docs/core-workflows.md`](core-workflows.md)) sits alongside native `/swarm` worker cleanup:
81
+
82
+ 1. **Native `/swarm` worker lifecycle (Antigravity):** Worker spawning, worktree isolation, and `kill` cleanup belong to Antigravity `/swarm`. `agy-squad` writes no temporary plugin or agent-profile registrations.
83
+ 2. **Handoff bundle scope:** `node bin/agy-squad.mjs` enforces `inspect -> bundle -> verify -> prune` (backed by `mcp/handoffs.mjs`; the standalone `node mcp/handoffs.mjs` CLI from Phase 1 has since been retired), recording SHA-256 digests of every input file and specialist report in `lead/report.sources.json` before pruning loose `specialist-N/report.md` files.
84
+ 3. **Self-diagnosis review scope:** `.agents/skills/self-diagnosis/SKILL.md` requires 1-ID-per-row transcription into a durable `docs/reviews/` ledger and bundle digest verification before `diagnose.mjs --teardown` removes `scratch/agy-squad/squad-*` directories and `manage_subagents` terminates child sessions.
85
+
86
+ The recorded `0` vs. `41` (`207.9 KB`) Git-untracked file counts come from `git status` after run completion (Agy-Squad's `.gitignore` excludes `scratch/`).
87
+
88
+ ## Offline check vs. live experiment reproduction
89
+
90
+ ### 1. Offline fixture and ledger consistency check
91
+
92
+ Run the offline verifier from the repository root (also executed by `npm test`):
93
+
94
+ ```bash
95
+ node benchmarks/teamwork-vs-squad/verify-benchmark.mjs
96
+ ```
97
+
98
+ `verify-benchmark.mjs` runs both fixture unit suites, reproduces all six seeded bugs in-process, compiles `all_l1` and `ab_audit` from `benchmarks/teamwork-vs-squad/manifest.json`, and checks the per-agent sums, rubric mappings, and provenance fields in `benchmarks/teamwork-vs-squad/results/telemetry.json`. It does not launch `agy` or replay live conversations.
99
+
100
+ ### 2. Live reproduction protocol and provenance policy
101
+
102
+ See [`benchmarks/teamwork-vs-squad/README.md`](https://github.com/paragon-ux/Agy-Squad/blob/main/benchmarks/teamwork-vs-squad/README.md#experimental-protocol-prompts-and-provenance-policy) for the verbatim audit prompt, arm configuration details (`manifest.json` domain-specialist briefs vs. `/teamwork [skip-interview]`), timing boundaries, and step-by-step live run commands. Session `conversationId` UUIDs in `results/telemetry.json` are local Antigravity conversation identifiers kept for `check_context_health` verification; host paths, usernames, and raw session transcripts were stripped before publication.
@@ -0,0 +1,81 @@
1
+ # Concepts and terminology
2
+
3
+ This guide defines the core terms used across Agy-Squad's CLI, MCP tools, skills, and architecture decision ledger.
4
+
5
+ ## Execution lifecycle
6
+
7
+ ```mermaid
8
+ flowchart LR
9
+ P["Parent Session (agy)"] -->|"1. squad_planner / dispatch_squad"| C["Compiled Stage (Lead, Specialists, or /swarm)"]
10
+ C -->|"2. swarm add / invoke_subagent"| S["Specialists Write report.md Slots"]
11
+ S -->|"3. <= 500B READY Receipt"| L["Lead / Parent + integrity_auditor Verify & Bundle SHA-256"]
12
+ L -->|"4. Ledger Update + --teardown"| D["Durable docs/reviews/ Record"]
13
+ ```
14
+
15
+ ### Role separation and dual-verdict gate
16
+
17
+ ![Role separation and dual-verdict bundle gate](assets/role-and-verdict-gate.svg)
18
+
19
+ Agy-Squad splits content evaluation from execution-integrity auditing. The squad lead (or parent session) inspects cited source files and test runs to issue `Content Verdict: PASS`, `FAIL`, or `BLOCKED` on `lead/report.md`. Separately, an independent flat `integrity_auditor` queries worker transcripts in batch (`summaryOnly=true` / `lastTurns=10`) to issue `Integrity Verdict: CLEAN` or `INTEGRITY VIOLATION`. `node bin/agy-squad.mjs bundle` requires both verdicts before writing `lead/report.sources.json` (unless `--allow-unaudited` is passed). For the single canonical map of every role across all four skills, see [Roles, skill workflows, and runtime closure](roles-and-workflows.md).
20
+
21
+ ## Core orchestration terms
22
+
23
+ ### Parent session
24
+ The top-level Antigravity conversation (started via native `/swarm` or in **Antigravity Desktop (IDE)**; legacy `node bin/agy-squad.mjs run` was retired in Phase 2 per `L17` and `L42`). The parent session owns user approvals, invokes `squad_planner`, `dispatch_squad`, or native `swarm`, receives `<= 500` byte completion receipts, and makes the final acceptance decision.
25
+
26
+ ### Shared swarm board and channel limits
27
+ Antigravity attaches one persistent board to each parent conversation (`board: "local"`). Every `swarm{action: "add"}` call, `post_message`, and retired (`killed: true`) member appends sequentially to that conversation's board history. Running multiple `/swarm` cohorts in the same chat accumulates all prior posts and retired workers in one UI payload, which slows down the Swarm UI pane on open.
28
+
29
+ - **Channels are host-gated, not user-configurable:** Antigravity's built-in `native_swarm` skill documents `swarm{action: "channel"}` conditionally (*"When the `swarm` tool offers the `channel` action..."*). When the host's `swarm` schema exposes only `status`, `models`, `add`, `model`, `kill`, and `title` (`post_message` accepts only `text`, and `read_board` has no `channel` filter), channels are disabled by the host runtime. Neither Antigravity settings nor Agy-Squad config can enable `channel` or `channels`.
30
+ - **Channels partition wakeups, not board databases:** Even on hosts that expose `channel`, `main` remains shared by all members, archived channel history stays readable, and retired workers remain in conversation history.
31
+ - **How to keep boards fast:** Start a fresh Antigravity conversation per major `/swarm` wave when you want a clean Swarm UI board (`#1`), or run repeated follow-up cohorts through `invoke_subagent` (`pr-review` / `self-diagnosis`), which does not append to the `/swarm` board. See [Stopping agents](stopping-agents.md) and [Native enforcement ledger (`NE-07`, `NE-11`)](plans/native-enforcement-ledger.md).
32
+
33
+ ### Squad lead
34
+ An intermediate subagent compiled when `dispatch_squad` (`agy-squad dispatch`) runs with `squadId: "all_l1"` on a manifest defining one or more squads (or a `/swarm` lead in `Layered` mode). Each squad lead inspects its specialists' cited files, writes `scratch/agy-squad/.../lead/report.md` (`Content Verdict: PASS`, `FAIL`, or `BLOCKED`; bare `Verdict:` is accepted only as a legacy alias), pairs with an independent flat integrity auditor (`audit-<id>` on `/swarm`, `integrity_auditor` via slot; emits `Integrity Verdict: CLEAN` or `INTEGRITY VIOLATION`), and bundles SHA-256 digests via `node bin/agy-squad.mjs bundle`.
35
+
36
+ ### Specialist
37
+ A focused worker compiled for a single squad (`squadId: "<id>"`). Under `invoke_subagent`, `dispatch_squad` defaults `typeName` to `"self"` (rejecting `"research"`, `"browser"`, and `"image-generator"`) and enforces `Workspace: "inherit"` so it can inspect its assigned `scopeFiles` and write its evidence report to `scratch/agy-squad/.../specialist-<N>/report.md`. Under `/swarm`, `squad_planner` supports `workspaceIsolation` (`inherit`, `share`, or `branch`) while mapping worker report slots under `scratch/agy-squad/` (or custom `reportRoot`).
38
+
39
+ ### Stage (`all_l1` vs. `<squadId>`)
40
+ A single compilation step returned by `dispatch_squad` (`agy-squad dispatch`) for `invoke_subagent` (in `squad_planner` / `agy-squad plan`, omit `squadId` to compile all squads; `all_l1` is not used in `squad_planner`):
41
+
42
+ - **Direct specialist stage (`squadId: "<id>"`):** Returns the `Subagents` array for that manifest squad (`diagnose.mjs --print-dispatch all_specialists` aggregates all self-diagnosis squads in one CLI call).
43
+ - **Lead stage (`squadId: "all_l1"`):** Returns one lead subagent per squad defined in the manifest (`1` or more squads).
44
+
45
+ ### Manifest
46
+ A JSON file inside the workspace that defines `squads`, each containing an optional `lead` and a required `specialists` array (`role`, `objective`, `scopeFiles`, and optional `instructions`, `expectedDeliverable`, or `model`). When no explicit manifest path is given, `dispatch_squad` searches in order for `task-01-manifest.json`, `swarm-manifest.json`, `.scratch/swarm-manifest.json`, and `suite-manifest.json`. See [Manifest and tool contract](tools.md).
47
+
48
+ ### Report slot
49
+ The deterministic workspace-relative path assigned to each specialist (`scratch/agy-squad/.../specialist-<N>/report.md`) or lead (`scratch/agy-squad/.../lead/report.md`). Writing full evidence to report slots keeps large markdown payloads out of the parent conversation context.
50
+
51
+ ### Pointer-Over-Wire receipt (`<= 500` UTF-8 bytes)
52
+ The single-line message a child sends back to its parent when it finishes (`send_message` for `invoke_subagent`, or `post_message` for `/swarm`):
53
+
54
+ - `READY <report-path> — <concrete observation>`
55
+ - `PARTIAL <report-path> — <reason>`
56
+ - `NO_REPORT — <reason>`
57
+
58
+ `mcp/handoffs.mjs` enforces the `500` UTF-8 byte ceiling and single-line format.
59
+
60
+ ### Evidence bundle (`report.sources.json`)
61
+ A JSON archive written by `node bin/agy-squad.mjs bundle` alongside `lead/report.md`. It records `schemaVersion: 2`, `auditPolicy` (`"required"` or `"unaudited-explicit"`), the SHA-256 digest and archived Markdown snapshot of `lead/report.md` and every `specialist-<N>/report.md`, `integrityAudits` (`path`, `sha256`, `evidenceDigest`, `verdict: "CLEAN"`, `targetSquad`), and every workspace file digest listed in `verifiedFiles`. Running `node bin/agy-squad.mjs verify` validates the persisted `auditPolicy`, checks archived Markdown verdicts and SHA-256 digests against the bundle and final workspace files, and verifies any loose reports that still remain on disk (allowing pruned loose reports to be absent).
62
+
63
+ ## Companion and governance terms
64
+
65
+ ### Reactive Wakeup
66
+ Antigravity's event-driven resumption mechanism: when a background task or subagent calls `send_message` (or finishes), or a `/swarm` worker posts an `@mention`, the parent agent wakes automatically without polling `manage_task(Action='status')` in a loop.
67
+
68
+ ### RTK (`Rust Token Killer`)
69
+ The command-line companion binary (`>= 1.1.0`) provisioned by `Agy-Context-Saver` (`v2.0.1+`). During live subagent and `/swarm` sessions, `Agy-Context-Saver` delegates shell command rewrites to `rtk hook antigravity` (`rtk read`, `rtk grep`, `rtk find`, `rtk git`) and enforces the 3-tier `read_file` slice policy (`<= 150` lines) to keep child transcripts compact.
70
+
71
+ ### Self-diagnosis (`/self-diagnosis`)
72
+ Agy-Squad's harness diagnostic and optimization skill (`.agents/skills/self-diagnosis/SKILL.md`). It provides a zero-subagent local profiler (`diagnose.mjs`) and three targeted specialist cohorts that audit skills, runtime contracts, and token budgets under operator supervision.
73
+
74
+ ### PR Review Standard `v1.4.0` (`/pr-review`)
75
+ The repository's review specification (`.agents/skills/pr-review/SKILL.md` and `.agents/skills/pr-review/references/pr-review-standard.md`). It requires commit and session provenance, architecture-before-runtime tracing, coverage across ten categories (`ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, `DEP`), and `1 ID = 1 Row` finding records in `docs/reviews/`.
76
+
77
+ ### Decision ledger codes (`L1` through `L43`)
78
+ Short identifiers referencing architectural decisions in [`docs/plans/LEDGER.md`](plans/LEDGER.md):
79
+
80
+ - **Active architecture (`L1-L7, L21, L29-L31, L40-L43`):** Define host-enforced boundaries, the 500-byte receipt ceiling, and SHA-256 bundling (`L1, L2`), native stop controls (`L3, L5`), scratch isolation (`L4`), transcript boundaries (`L6`), zero real subagents in automated tests (`L7`), deny-by-default permissions (`L21, L40`), private distribution (`L29`), Zensical docs (`L30`), `Agy-Context-Saver` separation with `dispatch_squad` and `squad_planner` (`L31`), deterministic scratch teardown (`L41`), native `/swarm` governance and the SHA-256 verification CLI (`L42`), and `squad_planner` explicit model pinning, writable `scopeFiles` overlap detection, and `L6`-safe provenance scaffolding (`L43`).
81
+ - **Retired historical IDs (`L8-L12, L16, L17, L18-L20, L22-L24, L28, L35-L39`):** Record earlier Windows/Docker trials, the retired `agy-squad run` CLI PTY launcher (`L17`), and migration steps kept in [`docs/plans/LEDGER.md`](plans/LEDGER.md) for provenance.
@@ -0,0 +1,128 @@
1
+ # Core workflows: orchestrate, self-diagnose, review, and tear down
2
+
3
+ Agy-Squad runs four connected workflows across **Antigravity Desktop (IDE)** and the **Antigravity CLI (`agy`)** on **Linux and WSL2 (macOS support is best-effort and untested)**:
4
+
5
+ 1. **Task-proportional orchestration** (`squad_planner` / `agy-squad plan`, `dispatch_squad` / `agy-squad dispatch`, and `node bin/agy-squad.mjs` backed by `mcp/handoffs.mjs`)
6
+ 2. **Recursive harness self-diagnosis** ([`.agents/skills/self-diagnosis/SKILL.md`](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/self-diagnosis/SKILL.md))
7
+ 3. **Governed PR & non-diff reviews under Standard v1.4.0** ([`.agents/skills/pr-review/SKILL.md`](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/pr-review/SKILL.md) and [`full-review`](roles-and-workflows.md#full-review))
8
+ 4. **Three-scope evidence retention and teardown** (`L41`)
9
+
10
+ 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](roles-and-workflows.md).
11
+
12
+ ## 1. Orchestrate proportional specialist or lead cohorts
13
+
14
+ ![Six-step swarm lifecycle and dual-verdict gate](assets/swarm-lifecycle.svg)
15
+
16
+ Agy-Squad structures each cohort run into four ordered stages: Pre-Flight Intake, Working Cohort, Independent Integrity Audit, and Acceptance Bundling.
17
+
18
+ ### Phase 0: Pre-flight intake interview
19
+
20
+ 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:
21
+
22
+ | Decision | Options | Governing control |
23
+ | --- | --- | --- |
24
+ | **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` |
25
+ | **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`) |
26
+ | **Teardown and provenance** | Full retention (`--keep-reports`, preserving `scratch/agy-squad/`) or automatic atomic teardown (`--teardown`) | `bin/agy-squad.mjs prune` and `diagnose.mjs` |
27
+ | **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"}` |
28
+ | **Integrity rigor** | Independent flat integrity auditor (`audit-<id>` on `/swarm`, `integrity_auditor` via slot; emits `CLEAN` or `INTEGRITY VIOLATION`) or `--allow-unaudited` opt-out | `bin/agy-squad.mjs bundle` and `mcp/verdicts.mjs` |
29
+ | **Instruction self-containment** | Explicit file paths, objectives, and criteria in every brief; unanchored codes (such as `H4` or `D2`) are rejected | `mcp/briefs.mjs` |
30
+
31
+ ### Stage 1: Working cohort execution
32
+
33
+ 1. **Compile the stage:** For Antigravity native `/swarm`, `squad_planner` (`agy-squad plan`) compiles `swarmAdd` payloads and a parent-authored `provenanceScaffold` (omit `squadId` to compile all manifest squads). For `invoke_subagent`, `dispatch_squad` (`agy-squad dispatch`) builds direct working specialists (`squadId: "<id>"`), squad leads (`squadId: "all_l1"`), or self-diagnosis `all_specialists` via `diagnose.mjs --print-dispatch all_specialists` ([`docs/tools.md`](tools.md)).
34
+ 2. **Inject brief invariants:** `mcp/briefs.mjs` adds alignment rules, flattery penalties, and transcript query rules to every compiled brief so the operator does not repeat boilerplate across squads.
35
+ 3. **Query transcripts in batches:** Squad leads and reviewers inspect child sessions with single-pass batch CLI calls (`agy-context transcript query --id <id> --summary` or `agy-context transcript read --id <id> --last-turns 10`). Iterative 1-to-2-step transcript polling is prohibited.
36
+ 4. **Write to workspace report slots:** `dispatch_squad` sets `TypeName: "self"` and `Workspace: "inherit"` so each specialist writes directly to `scratch/agy-squad/.../specialist-<N>/report.md`.
37
+ 5. **Send a `<= 500` byte receipt (`Pointer-Over-Wire`):** Each child posts one single-line receipt (`READY`, `PARTIAL`, or `NO_REPORT`) under `500` UTF-8 bytes through `send_message`, waking its parent via Reactive Wakeup without pasting full reports into parent context.
38
+ 6. **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 writes `lead/report.md` with `Content Verdict: PASS`, `FAIL`, or `BLOCKED` on its own line (bare `Verdict:` is accepted only as a legacy alias).
39
+
40
+ ### Stage 2: Independent integrity auditor
41
+
42
+ Run the integrity auditor **after working squads finish** and **before acceptance**. For Antigravity native `/swarm` runs, follow `.agents/skills/swarm-governance/SKILL.md`.
43
+
44
+ 1. **Dispatch or spawn the flat auditor:** On `/swarm`, add flat `audit-<id>` (`squad-integrity_auditor/specialist-1/report.md` for single-squad manifests, flat or layered, or `squad-integrity_auditor-<targetSquad>/specialist-1/report.md` for multi-squad manifests, flat or layered). On `invoke_subagent`, call `dispatch_squad` with `squadId: "integrity_auditor:<targetSquad>"` (or `integrity_auditor` for single-squad manifests). Legacy `adversarial_l1`, `adversarial_flat`, and `adversarial_review` stages have been removed.
45
+ 2. **Audit execution traces:** The auditor runs single-pass batch queries (`summaryOnly=true` or `lastTurns=10`) to confirm that specialists executed real tools instead of guessing from memory, avoided sycophantic filler, and had their claims checked by the squad lead.
46
+ 3. **Emit an audit verdict with Evidence Digest:** Run `node bin/agy-squad.mjs digest <record.json>` first so the auditor records `Target Squad: <targetSquad>`, `Evidence Digest: <64-hex>`, and strictly `Integrity Verdict: CLEAN` or `Integrity Verdict: INTEGRITY VIOLATION` (never a content `PASS`).
47
+
48
+ ### Stage 3: Acceptance and cryptographic bundling
49
+
50
+ 1. **Enforce the dual-verdict gate:** `node bin/agy-squad.mjs bundle <record.json>` requires `Content Verdict: PASS` on `lead/report.md`, `Evidence Digest: <64-hex>`, and `Integrity Verdict: CLEAN` for every auditor slot matching `Target Squad` via `mcp/verdicts.mjs`. Any `INTEGRITY VIOLATION`, stale digest, hedged verdict, or missing audit blocks bundling unless `--allow-unaudited` is passed (`auditPolicy: "required"` vs `"unaudited-explicit"`).
51
+ 2. **Record and verify SHA-256 digests:** `mcp/handoffs.mjs` hashes all cited `verifiedFiles`, specialist reports, and every `integrityAudit` / `integrityAudits` report into `lead/report.sources.json`. `node bin/agy-squad.mjs verify <report.sources.json>` enforces the persisted `auditPolicy` alongside archived Markdown and digest matches, and `prune <report.sources.json> <accepted-sha256> [--keep-reports]` safely removes matching loose specialist reports.
52
+
53
+ ## 2. Diagnose and optimize the harness (`self-diagnosis`)
54
+
55
+ The [`self-diagnosis` skill](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/self-diagnosis/SKILL.md) 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.
56
+
57
+ ### Run the zero-subagent profiler
58
+
59
+ 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.4.0 review ledger schema:
60
+
61
+ ```bash
62
+ # Markdown diagnostic report:
63
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdown
64
+
65
+ # JSON output for scripts and CI:
66
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs
67
+
68
+ # Validate a specific PR review ledger under docs/reviews/:
69
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
70
+ --ledger docs/reviews/rebuild-wsl-dispatch-review-r2.md
71
+ ```
72
+
73
+ ### Compile and run targeted diagnostic cohorts
74
+
75
+ 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`):
76
+
77
+ ```bash
78
+ # Primary (/swarm coordinator plan, Flat or Layered, inherit workspace for read-only audit):
79
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
80
+ --print-plan [--mode swarm] [--workspace-isolation inherit]
81
+
82
+ # Or compile invoke_subagent stages via dispatch_squad (flat squad or all_l1 leads):
83
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
84
+ --print-dispatch skill_and_pr_review_audit --parent-id <parent-conversation-id>
85
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs \
86
+ --print-dispatch all_l1 --parent-id <parent-conversation-id>
87
+ ```
88
+
89
+ Every diagnostic pass follows one fixed sequence:
90
+
91
+ `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`
92
+
93
+ ## 3. Review pull requests to the v1.4.0 standard
94
+
95
+ The [`pr-review` skill](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/pr-review/SKILL.md) and [PR Review Standard v1.4.0](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/pr-review/references/pr-review-standard.md) define the repository review contract:
96
+
97
+ | Standard section | Requirement |
98
+ | --- | --- |
99
+ | **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`). |
100
+ | **Sections 2 and 3: Architecture-before-runtime trace** | Trace active POSIX/WSL decisions (`L1-L7, L21, L29-L31, L40-L43` in [`docs/plans/LEDGER.md`](plans/LEDGER.md); `L17` is retired) to public contracts, source code, and tests before evaluating runtime behavior. |
101
+ | **Section 4: Ten review categories** | Map every changed file to one primary category across `ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, and `DEP`. |
102
+ | **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. |
103
+
104
+ `diagnose.mjs` and `npm test` enforce `pr-review` locally in the repository (not as a GitHub branch-protection rule).
105
+
106
+ > [!WARNING]
107
+ > `diagnose.mjs` status (`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. Treat `HEALTHY` as 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.
108
+
109
+ ## 4. Three-scope evidence retention and teardown contract
110
+
111
+ ![Role separation and dual-verdict bundle gate](assets/role-and-verdict-gate.svg)
112
+
113
+ Agy-Squad separates native worker cleanup from report bundling and ledger-gated scratch deletion across three scopes:
114
+
115
+ | Lifecycle scope | Governing tool | What is cleaned up | What is retained and gated |
116
+ | --- | --- | --- | --- |
117
+ | **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 (`L17` retired, `L42`/`L43` active) | Preserves workspace-relative specialist/lead reports and parent-authored `provenanceScaffold` under `scratch/agy-squad/squad-<id>/` (or custom `reportRoot`) |
118
+ | **2. Handoff and integrity bundle** | `node bin/agy-squad.mjs` | `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`) |
119
+ | **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 |
120
+
121
+ To tear down completed self-diagnosis cohorts after updating the target review ledger:
122
+
123
+ ```bash
124
+ node .agents/skills/self-diagnosis/scripts/diagnose.mjs --teardown all \
125
+ --ledger docs/reviews/<target-review-slug>.md
126
+ ```
127
+
128
+ 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](stopping-agents.md)).
@@ -0,0 +1,116 @@
1
+ # Getting started (Desktop IDE & CLI on POSIX / WSL2)
2
+
3
+ Agy-Squad is a subagent planning, self-diagnosis, and review harness for **Antigravity Desktop (IDE)** and the **Antigravity CLI (`agy`)** across **Linux and WSL2 (macOS support is best-effort and untested)**. It pairs [`swarm-governance`](roles-and-workflows.md#swarm-governance) (Execution Modifier) with Task-Spec skills ([`self-diagnosis`](core-workflows.md#2-diagnose-and-optimize-the-harness-self-diagnosis), [`pr-review`](core-workflows.md#3-review-pull-requests-to-the-v140-standard), and [`full-review`](roles-and-workflows.md#full-review)) using `<= 500` byte `Pointer-Over-Wire` receipts, file-backed evidence slots, and SHA-256 bundle checks (`v1.4.0`).
4
+
5
+ ## Host and companion compatibility matrix
6
+
7
+ | Layer | Requirement | Check command |
8
+ | --- | --- | --- |
9
+ | Operating system | Linux or WSL2 on Windows (primary verified targets; macOS is best-effort and untested) | `uname -a` |
10
+ | Node.js | `>= 22.0.0` | `node --version` |
11
+ | Antigravity surface | Antigravity Desktop (IDE) with `/swarm` and/or `invoke_subagent` | Open Desktop IDE |
12
+ | Agy-Context-Saver | `>= 2.0.1` (`PreToolUse` hook + `agy-context` CLI active) for live governed cohorts | `agy-context status` (or `agy-context setup`) |
13
+ | RTK binary | `>= 1.1.0` (`rtk hook antigravity`, provisioned by `Agy-Context-Saver`) | `rtk --version` (or via `agy-context setup`) |
14
+ | Documentation site (optional) | Python 3.11+ with pinned `zensical==0.0.74` for `npm run docs` (`zensical serve`) / `zensical build` (use `python3 -m zensical ...` if `zensical` is not on `PATH`) | `pip install "zensical==0.0.74" && zensical --version` |
15
+ | Native permissions | Controlled by Desktop IDE approvals and `/swarm` / `/agents` | Review before launching workers |
16
+
17
+ ## 1. Install via NPX (Recommended — zero clone required)
18
+
19
+ Register the native Antigravity plugin (`~/.gemini/config/plugins/agy-squad`), link the four governance skills (`pr-review`, `full-review`, `self-diagnosis`, `swarm-governance`), register the `agy-squad` MCP server in `~/.gemini/config/mcp_config.json`, and provision the `agy-squad` CLI shim in `~/.gemini/antigravity/bin/` with a single command:
20
+
21
+ ```bash
22
+ npx --package=agy-squad agy-squad setup
23
+ agy-squad status
24
+ ```
25
+
26
+ ### Local repository checkout (optional)
27
+
28
+ If you are developing `Agy-Squad` from source, clone the repository and run `npm run setup && npm test`:
29
+
30
+ ```bash
31
+ git clone https://github.com/paragon-ux/Agy-Squad.git
32
+ cd Agy-Squad
33
+ npm run setup
34
+ npm test
35
+ ```
36
+
37
+ `npm test` runs locally in Node.js without spawning live subagents. It exercises the lifecycle installer (`setup`, `status`, `--check`, `uninstall`), MCP server, `dispatch_squad` compiler, `squad_planner` planner, handoff bundler, `/self-diagnosis` profiler, and benchmark fixture.
38
+
39
+ ## 2. Manual workspace MCP registration (optional)
40
+
41
+ If you prefer not to use `agy-squad setup`, you can register `agy-squad` manually in `.agents/mcp_config.json` (or your IDE MCP config) using the absolute path from `command -v node`:
42
+
43
+ ```json
44
+ {
45
+ "mcpServers": {
46
+ "agy-squad": {
47
+ "command": "/absolute/path/to/node",
48
+ "args": ["/absolute/path/to/Agy-Squad/mcp/index.js"],
49
+ "env": {
50
+ "AGY_SQUAD_WORKSPACE": "/absolute/path/to/workspace"
51
+ },
52
+ "tools": {
53
+ "dispatch_squad": { "eager": true },
54
+ "squad_planner": { "eager": true }
55
+ }
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ In Desktop IDE sessions, pair `squad_planner` with Antigravity native `/swarm` and the `swarm-governance` skill (asking once upfront when `Flat` vs `Layered` topology is unspecified), or call `dispatch_squad` / `diagnose.mjs --print-dispatch <squadId> --parent-id <conversationId>` when targeting `invoke_subagent`. Enforce strict single-line verdicts and SHA-256 bundles with `node bin/agy-squad.mjs` (`dispatch`, `plan`, `verdict`, `fingerprint`, `inspect`, `digest`, `bundle`, `verify`, `prune`), and stop completed `invoke_subagent` children with `manage_subagents(Action='kill', ConversationIds=[...])`.
62
+
63
+ ## 3. CLI Planner and Governance (`bin/agy-squad.mjs`)
64
+
65
+ ![Six-step swarm lifecycle and dual-verdict gate](assets/swarm-lifecycle.svg)
66
+
67
+ For native `/swarm` planning, `invoke_subagent` stage compilation, and CI verification, `bin/agy-squad.mjs` provides nine subcommands (`dispatch`, `plan`, `fingerprint`, `inspect`, `digest`, `bundle`, `verify`, `prune`, `verdict`). Legacy `agy-squad run` (`bin/terminal.py`) and the standalone `node mcp/handoffs.mjs` CLI were retired in PR #5 ([`L17`, `L42`, `L43`](plans/LEDGER.md)).
68
+
69
+ ### Generate a `/swarm` plan and provenance scaffold
70
+
71
+ ```bash
72
+ node bin/agy-squad.mjs plan \
73
+ --manifest .agents/skills/self-diagnosis/resources/self-diagnosis-manifest.json \
74
+ --model gemini-4-hydrogen-high
75
+ ```
76
+
77
+ Or plan directly from a freeform task description:
78
+
79
+ ```bash
80
+ node bin/agy-squad.mjs plan \
81
+ --mode swarm \
82
+ --model gemini-4-hydrogen-high \
83
+ --scope src/app.js --scope docs/tools.md \
84
+ --role "Implementer" --role "Reviewer" \
85
+ "Verify Phase 2 runtime fixes and update documentation."
86
+ ```
87
+
88
+ ## 4. What successful output looks like
89
+
90
+ 1. In Desktop IDE or CLI planning, `squad_planner` (or `dispatch_squad`) generates worker specs, report slots under `scratch/agy-squad/...`, model provenance metadata, and an `L6`-safe `provenanceScaffold`.
91
+ 2. Each worker writes its evidence report to its assigned slot (`scratch/agy-squad/.../specialist-<N>/report.md`) and posts a single-line `<= 500` byte receipt:
92
+ ```text
93
+ READY scratch/agy-squad/squad-1/specialist-1/report.md — gateway/gateway.mjs:10 timingSafeEqual throws RangeError on short hex
94
+ ```
95
+ 3. The parent (or squad lead) inspects cited source lines and tests to verify correctness, writes a strict `Content Verdict: PASS` line in `lead/report.md` (bare `Verdict: PASS` is accepted only as a legacy alias), pairs with a flat integrity auditor (`audit-<id>` on `/swarm`, `integrity_auditor` via slot; emits `Integrity Verdict: CLEAN`), and runs `node bin/agy-squad.mjs` (`verdict`, `fingerprint`, `inspect`, `digest`, `bundle`, `verify`, `prune`) to record SHA-256 digests in `lead/report.sources.json`.
96
+ 4. Run `swarm status` or `manage_subagents` to inspect running worker models or stop active children ([Stopping agents](stopping-agents.md)).
97
+
98
+ ## When to use Agy-Squad vs. alternatives
99
+
100
+ | Approach | Primary strength | Use Agy-Squad when... | Prefer comparator when... |
101
+ | --- | --- | --- | --- |
102
+ | **Antigravity native `/swarm`** | Native shared board, worktrees (`share`/`branch`), live model switching, and `swarm_monitor` | You want Agy-Squad (`swarm-governance` + `bin/agy-squad.mjs`) on top of `/swarm` for role separation, `Pointer-Over-Wire` disk pointers, and SHA-256 CI proof bundles | You only need ephemeral board coordination without deterministic bundles or strict verdict gates |
103
+ | **Antigravity `/teamwork`** (or `/teamwork-preview`) | Autonomous multi-milestone campaigns with built-in wrapper, explorer, and semantic reviewer agents | You want proportional 2-to-3 agent cohorts in Desktop IDE or CLI, `<= 500` B receipts, SHA-256 evidence bundles, governed teardown, and integrated `self-diagnosis` + `pr-review` (`v1.4.0`) (see [Benchmarks](benchmarks.md)) | You want a long autonomous campaign with built-in LLM reviewer/auditor agents |
104
+ | **Antigravity native subagents** (`invoke_subagent`) | Zero setup for ad hoc parallel tasks | You want a repeatable manifest, report-slot paths, receipt length enforcement, and bundle verification | You only need one quick ad hoc delegation |
105
+ | **Claude Code / Codex subagents** | Native role files and parallel delegation inside those tools | Your workflow runs in Antigravity Desktop or CLI on POSIX / WSL2 | Your team works inside Claude Code or OpenAI Codex |
106
+ | **CrewAI / LangGraph / Microsoft Agent Framework** | General Python/TypeScript SDKs for building standalone multi-agent applications | You want a lightweight workspace harness without building an external orchestration service | You are building a standalone application, stateful graph, or multi-cloud agent service |
107
+
108
+ ## Troubleshooting common issues
109
+
110
+ | Symptom | Cause | Resolution |
111
+ | --- | --- | --- |
112
+ | `Unknown command ...` or `'agy-squad run' was retired` | `agy-squad run` was invoked after Phase 2 retirement ([`L17`](plans/LEDGER.md)) | Run `node bin/agy-squad.mjs plan` with Antigravity native `/swarm`, or register `mcp/index.js` directly in `.agents/mcp_config.json` |
113
+ | Unbounded `read_file` denied by `Agy-Context-Saver` hook during live run | `Agy-Context-Saver` (`>= 2.0.1`) enforces the 3-tier Hybrid Slice Policy (`StartLine`/`EndLine` `<= 150` lines, or full-file `<= 800` lines & `<= 45 KiB`) | Pass bounded `StartLine`/`EndLine` (`<= 150` lines) to `read_file` or run `rtk read <file>` via `run_command`; run `agy-context setup` if `rtk` (`>= 1.1.0`) is missing |
114
+ | `Requested explicit model ... cannot be pinned under executionMode 'subagent'` | `invoke_subagent` accepts only `inherit|flash|flash_lite|pro` | Set `executionMode: "swarm"` (`--mode swarm`) in `squad_planner` to explicitly pin and verify exact model IDs via `swarm status` |
115
+ | Swarm UI shows old posts, retired workers, or loads slowly across waves | Antigravity keeps one append-only board per conversation (`killed: true` entries stay in history) and does not expose user-configurable channels when `swarm` lacks `action: "channel"` | Start a fresh Antigravity conversation per major `/swarm` wave for a clean board, or run follow-up cohorts via `invoke_subagent` ([Shared swarm board and channel limits](concepts.md#shared-swarm-board-and-channel-limits)) |
116
+ | Specialist silent past checkpoint | Waiting on permission prompt or stuck command | Run `swarm status`, `manage_subagents` (Desktop IDE), or `/agents` to inspect or stop the child, then verify underlying processes exited ([Stopping agents](stopping-agents.md)) |
package/docs/index.md ADDED
@@ -0,0 +1,47 @@
1
+ # Agy-Squad
2
+
3
+ Agy-Squad is a subagent planning, self-diagnosis, and review harness for **Antigravity Desktop (IDE)** and the **Antigravity CLI (`agy`)** on **Linux and WSL2 (macOS support is best-effort and untested)**.
4
+
5
+ `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 `node bin/agy-squad.mjs` (`mcp/handoffs.mjs`) to verify SHA-256 input and report digests. During live Desktop IDE runs, `Agy-Context-Saver` (`2.0.1+`) rewrites shell commands through `rtk >= 1.1.0` (`rtk hook antigravity`), enforces 5-tier transcript access governance, and applies Reactive Wakeup backoff.
6
+
7
+ ![Agy-Squad, Antigravity, and Agy-Context-Saver architecture](assets/architecture-overview.svg)
8
+
9
+ ## Start here
10
+
11
+ - **[Getting started (Desktop IDE & CLI on POSIX / WSL2)](getting-started.md):** Host and companion compatibility matrix, clone-and-verify preflight, Desktop IDE MCP registration, and CLI commands (`dispatch`, `plan`, `verdict`, `fingerprint`, `inspect`, `digest`, `bundle`, `verify`, `prune`).
12
+ - **[Core workflows](core-workflows.md):** Task-proportional delegation, recursive [`self-diagnosis`](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/self-diagnosis/SKILL.md), the ten-category [`pr-review` Standard v1.4.0](https://github.com/paragon-ux/Agy-Squad/blob/main/.agents/skills/pr-review/SKILL.md), and the 3-scope evidence-retention and teardown contract.
13
+ - **[Roles, skill workflows, and runtime closure](roles-and-workflows.md):** Single canonical definition of every role, Task-Spec vs. Execution-Modifier skill composition (`swarm-governance`, `pr-review`, `full-review`, `self-diagnosis`), and the 4-check runtime closure checklist.
14
+ - **[Concepts and terminology](concepts.md):** Definitions for stages (`all_l1` vs. `<squadId>` vs. `integrity_auditor` / `audit-<id>`), `squad_planner`, report slots, `Pointer-Over-Wire` receipts, SHA-256 bundles, Reactive Wakeup, `RTK`, and decision ledger codes (`L1` through `L43`).
15
+ - **[Manifest and tool contract](tools.md):** Schema and CLI flags for `squad_planner` (`plan`), `dispatch_squad` (`dispatch`), `node bin/agy-squad.mjs`, and `mcp/handoffs.mjs` (library module).
16
+ - **[Native enforcement ledger](plans/native-enforcement-ledger.md):** Host hook boundary (`PreToolUse`, `StopHook`), `/swarm` channel limits, and Spike status.
17
+ - **[Benchmarks](benchmarks.md):** Canonical metric table, unit definitions, and reproduction guide for the November 8, 2026 audit against Antigravity `/teamwork`.
18
+
19
+ ## Core capabilities
20
+
21
+ 1. **Proportional `/swarm` planning and subagent dispatch:** `squad_planner` (`/swarm` default with explicit `model` pinning, `readOnly`-aware scope-overlap checks, and `L6`-safe `provenanceScaffold`) and `dispatch_squad` (`invoke_subagent`) route worker evidence to `scratch/agy-squad/.../report.md` and return a single-line `<= 500` B `READY` receipt. Ask the user upfront when `Flat` vs `Layered` topology is unspecified.
22
+ 2. **Harness self-diagnosis (`/self-diagnosis`):** `node .agents/skills/self-diagnosis/scripts/diagnose.mjs --markdown` runs a zero-subagent health and token-budget check, or builds targeted audit cohorts (`--print-plan` or `--print-dispatch`) for operator-supervised inspection.
23
+ 3. **Repository review standards (`/pr-review` & `/full-review`, v1.4.0):** Reviewers apply commit and session provenance, architecture-before-runtime tracing, ten mandatory categories (`ARCH`, `DOC`, `SKILL`, `MCP`, `RUN`, `SVC`, `DB`, `SCRIPT`, `TEST`, `DEP`), and `1 ID = 1 Row` ledgers under `docs/reviews/`.
24
+ 4. **Governed evidence retention and teardown:** `bin/agy-squad.mjs` verifies SHA-256 source and report digests before pruning loose specialist reports, binds flat integrity audit `CLEAN` verdicts (`audit-<id>` on `/swarm`, `integrity_auditor[:<id>]` via slot), and gates `diagnose.mjs --teardown` on a verified bundle and updated `docs/reviews/` ledger.
25
+
26
+ ## Companion integration: Agy-Context-Saver
27
+
28
+ `Agy-Squad` and `Agy-Context-Saver` remain separate packages ([`L31`](plans/LEDGER.md)) that interact across four execution stages:
29
+
30
+ | Stage | Owner | Mechanism and tools |
31
+ | --- | --- | --- |
32
+ | 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`). |
33
+ | 2. Subagent execution governance | `Agy-Context-Saver` (`2.0.1+`) | 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`. |
34
+ | 3. Cryptographic bundling and pruning | `Agy-Squad` | `node bin/agy-squad.mjs` (`dispatch -> plan -> verdict -> fingerprint -> inspect -> digest -> bundle -> verify -> prune [--keep-reports]`) validates single-line verdicts, binds `integrityAudit` digests (`CLEAN` + `Target Squad`), writes `report.sources.json`, and optionally removes loose reports (`L1`, `L2`, `L42`, `L43`). |
35
+ | 4. Session and transcript forensics | `Agy-Context-Saver` (`2.0.1+`) | The `agy-context` CLI (`agy-context status`, `agy-context setup`, `agy-context transcript read|query|step|health|list|access`) inspects parent or child `conversationId` records without reading `.system_generated/` directly (`L6`), enforcing `[agy-transcript-access: allow|deny]` directives per worker. |
36
+
37
+ 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.
38
+
39
+ ## Recorded comparison vs. Antigravity `/teamwork`
40
+
41
+ On November 8, 2026, a sequential audit compared both approaches on the six-defect event-relay fixture ([`benchmarks.md`](benchmarks.md)). Both caught all six planted defect categories (`6 / 6`).
42
+
43
+ - **Runtime and steps:** **Agy-Squad + Agy-Context-Saver (`1.8.1`, `rtk 0.51.0`)** finished in **`6m 15s` (`375s`) vs. `26m 19s` (`1,579s`, `4.2x` faster)** and executed **`64` vs. `645` transcript steps** (`90.1%` fewer steps).
44
+ - **Context and transcript size:** Raw transcripts totaled **`148.2 KB` vs. `817.4 KB`** (`81.9%` smaller), and parent context wakeup payloads totaled **`249 B` vs. `4,940 B`** (`95.0%` fewer wakeup bytes).
45
+ - **Verification and cleanup:** The squad lead verified cited fixture lines directly and ran a 20 ms SHA-256 bundle digest check (`handoffs.mjs verify` during the Phase 1 trial; now `node bin/agy-squad.mjs verify`) before pruning loose reports under the 3-scope teardown policy.
46
+
47
+ See [Benchmarks](benchmarks.md) for the full metric table, unit definitions, prompts, and offline vs. live reproduction steps.
@@ -0,0 +1,24 @@
1
+ # Decision and work ledger
2
+
3
+ This ledger records the active Agy-Squad decisions. IDs shared with Agy-Context-Saver stay stable (`L13–L15, L25–L27, L32–L34` are allocated in the Agy-Context-Saver ledger). The previous Docker plan and its decision history are in commit `ee10ebc`.
4
+
5
+ | ID | Decision | Status |
6
+ | --- | --- | --- |
7
+ | L1, L2 | Use host-enforced boundaries and structured permissions. Under WSL `Workspace: "inherit"`, host permissions confine access to the workspace and protect session registrations and staged manifests, while intra-workspace file scope and sibling report slots are verified through receipts and SHA-256 hashes (`mcp/handoffs.mjs`). | Active |
8
+ | L3, L5 | Keep native stop controls available and verify that stopping work cleans up its commands. | Active |
9
+ | L4 | Avoid shared mutable runtime state in the system temporary directory. | Active |
10
+ | L6 | Enforce the boundary around other agents' transcripts. | Active |
11
+ | L7 | Automated tests launch zero real subagents. Any live trial is supervised and run separately by the user. | Active |
12
+ | L8–L12, L35, L36, L38 | Use the Antigravity CLI on WSL for this rebuild. The Windows native-jail, Windows 24H2 terminal-sandbox, and Docker workspace/per-agent container designs are retired. | Superseded by the user's WSL decision, 2026-11-07 |
13
+ | L16 | Retire the legacy shared-container canary. Keep its source in Git history. | Rebuild branch |
14
+ | L17 | Retire the legacy `agy-squad run` CLI PTY launcher (`bin/terminal.py`, `mcp/run-state.mjs`). Keep history in Git; replaced by `squad_planner` + Antigravity native `/swarm` (`L42`, `L43`). | Retired (PR #5 / Phase 2) |
15
+ | L18–L20, L22–L24, L28, L37, L39 | Retire the Docker enforcement, collection, and cleanup mechanisms. Verify the native CLI boundaries and stopping behavior for the trial. | Rebuild branch, WSL trial checks passed |
16
+ | L21, L40 | Keep deny-by-default admission and keep credentials outside agent commands. Verify the native permissions before relying on them. | Active |
17
+ | L29 | Keep distribution private while verifying the native WSL boundaries. Use workspace-local registration for tests. | Active |
18
+ | L30 | Publish documentation as a Zensical site (`zensical.toml`, `.github/workflows/docs.yml`). | Active |
19
+ | L31 | Keep Context-Saver and Squad separate. Expose Squad payload compilation and native swarm planning through two public MCP tools: `dispatch_squad` and `squad_planner`. | Active (updated PR #5) |
20
+ | L41 | Keep self-diagnosis directories and canary runs under workspace-local `scratch/agy-squad/` (`L4`) and tear them down deterministically after verification (`diagnose.mjs --teardown` and `try/finally` canary cleanup), removing empty parent `scratch/agy-squad` and `scratch` directories so no stale report slots or dirty working-tree artifacts remain. | Active |
21
+ | L42 | Pivot execution to Antigravity native `/swarm` (`swarm-governance`), retaining Agy-Squad as the governance, strict single-line verdict (`mcp/verdicts.mjs`), flat `integrity_auditor`, and offline SHA-256 verification CLI (`bin/agy-squad.mjs plan|dispatch|fingerprint|inspect|bundle|verify|prune|verdict`). | Active |
22
+ | L43 | Add `squad_planner` (`mcp/planner.mjs`, CLI `agy-squad plan`) to solve explicit `/swarm` model pinning (`swarm add`/`swarm status` vs. `invoke_subagent` `Model: "inherit"` provenance caveat), writable sibling `scopeFiles` overlap detection (exempting read-only auditors), and parent-authored `L6`-safe `provenanceScaffold` + `bundleRecordTemplates` (raw `.system_generated/` transcripts stay isolated). | Active (PR #5 / Phase 2) |
23
+
24
+ See the [WSL CLI verification checklist](wsl-cli-verification.md) for the launch gates.