From efbe378221f167b0ec4d27cb83087d86c9526e92 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Thu, 12 Nov 2026 09:52:31 -0800 Subject: [PATCH 1/3] docs(adr-003): analysis of gains, risks and scope for the canonical coordinator Co-Authored-By: Claude Opus 5.5 --- ...-003-host-neutral-canonical-coordinator.md | 74 +++++++++++++++++++ 1 file changed, 74 insertions(+) diff --git a/docs/specification/adr-003-host-neutral-canonical-coordinator.md b/docs/specification/adr-003-host-neutral-canonical-coordinator.md index 309051691..86330e05f 100644 --- a/docs/specification/adr-003-host-neutral-canonical-coordinator.md +++ b/docs/specification/adr-003-host-neutral-canonical-coordinator.md @@ -93,6 +93,80 @@ under `.squad-templates/` in the workspace. 3. If B: is the Copilot file still written for workspaces where Copilot is not in `clients[]`? +## Analysis (2026-11-12) + +Input for the decision, not the decision itself. + +### Evidence: the pointer is not followed + +The "Why it matters now" concern is that a non-Copilot coordinator may read +80 KB of Copilot-shaped text on demand. In 43 recorded Claude Code sessions on +Squad repositories (lab runs for #2438 and #2463, the end-to-end test, and a +fresh `squad init --client claude` repository cast and built through +`claude -p --agent squad` on 2026-11-12), no session read +`.github/agents/squad.agent.md`. None did through Read, Bash or Grep. The +coordinators worked from their digest, skills and `.squad/` files. The cost +that option B removes is mostly theoretical today. + +### What B gains + +- One host-neutral source with every host as a projection of it. This matches + how the other six hosts already work and how harness-adapters §4–§5 + describes projection. +- No host's digest names a Copilot path as its authority. +- If the neutral file lives under `.squad/`, `squad_state_read` can serve it, + and it follows `teamRoot` in remote mode. +- Not writing `.github/agents/squad.agent.md` for repositories without Copilot + (open question 3, and #2458) is sometimes counted as a gain of B. It does + not depend on moving the canonical file, and can be decided on its own. + +### What B risks + +- **Copilot users carry the risk.** The workspace file is not a plain template + copy. It carries a version stamp; `squad cast` writes the team-capabilities + block into it (#1608), which outer coordinators read; and `squad upgrade` + backs up local customizations to `.local-backup` (#1052), so users do edit + it. A generated Copilot file must reproduce all of this and stay + byte-identical (the Copilot snapshot in + `test/host-projection-regression-guards.test.ts`). +- **Customizations.** Edits to a generated file are overwritten on the next + refresh. Users with a customized file need a migration path and a clear + message. +- **Placement.** In a monorepo, `squad init` writes the Copilot file at the git + root while `.squad/` can sit in a subfolder, and remote mode moves the team + root. A neutral file and the Copilot file it generates are not always + side by side. +- **Churn.** It is a projection-version change for all seven hosts, so every + repository gets a diff on its next `squad upgrade`. Rollback must stay + byte-preserving (§13), and the upgrade matrix needs re-recording on Linux and + Windows. +- **Drift.** Users who keep editing the generated Copilot file create a second + copy that diverges from the neutral source. + +### Scope + +- **Option B:** about 2–3 days. The canonical path appears in about 20 source + files (init, upgrade, cast, team capabilities, the legacy fallback, help text + and the adapter contract) and 44 test files. The work: the neutral file and a + generator that keeps Copilot output byte-identical (stamp and capabilities + block included); the upgrade migration and rollback, with customized files; + monorepo and remote placement; a projection version bump for every host; a + regenerated Claude plugin and a re-recorded upgrade matrix; spec and docs. +- **Option C:** about half a day. Rewrite the "Authoritative specification" + paragraph in `coreCoordinatorProtocol` (`coordinator.ts`) so each digest is + self-sufficient (Claude already serves on-demand sections as skills), update + the digest parity tests, and regenerate. No migration, and no change to + Copilot output. +- **Not writing the Copilot file without Copilot** (separate from both): + small, but a behavior change that needs its own decision. + +### Recommendation + +Choose C now and defer B. C removes the dependency on a Copilot path at almost +no risk. B is worth revisiting if a single source starts to matter: for +example, if Copilot's file needs host-specific content, or remote teams need +the coordinator served through `squad_state`. Neither choice gates a release. + ## Decision Not yet made. Implementation, if approved, is a separate PR with its own From b64e03967996a64c6c6c4b6b9858c09b141bfb85 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Thu, 12 Nov 2026 09:58:28 -0800 Subject: [PATCH 2/3] docs(adr-003): state the evidence precisely and link it Co-Authored-By: Claude Opus 5.5 --- ...-003-host-neutral-canonical-coordinator.md | 23 +++++++++++++------ 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/specification/adr-003-host-neutral-canonical-coordinator.md b/docs/specification/adr-003-host-neutral-canonical-coordinator.md index 86330e05f..048e7b41e 100644 --- a/docs/specification/adr-003-host-neutral-canonical-coordinator.md +++ b/docs/specification/adr-003-host-neutral-canonical-coordinator.md @@ -100,13 +100,22 @@ Input for the decision, not the decision itself. ### Evidence: the pointer is not followed The "Why it matters now" concern is that a non-Copilot coordinator may read -80 KB of Copilot-shaped text on demand. In 43 recorded Claude Code sessions on -Squad repositories (lab runs for #2438 and #2463, the end-to-end test, and a -fresh `squad init --client claude` repository cast and built through -`claude -p --agent squad` on 2026-11-12), no session read -`.github/agents/squad.agent.md`. None did through Read, Bash or Grep. The -coordinators worked from their digest, skills and `.squad/` files. The cost -that option B removes is mostly theoretical today. +80 KB of Copilot-shaped text on demand. Local Claude Code transcripts for Squad +test repositories (2026-11-10 to 2026-11-12, Claude Code 2.1.317–2.1.318) were +checked for any Read, Bash, Grep or Glob call on +`.github/agents/squad.agent.md`. None of the 43 sessions (223 tool calls) +touched it. Most of those sessions are short probes. Seven did real team +work: the end-to-end test and a fresh `squad init --client claude` repository +cast and built through `claude -p --agent squad`. Those seven made 177 tool +calls, 32 member spawns and 96 `squad_state` or `.squad/` accesses. In both +repositories the 82–83 KB Copilot file was present and the digest pointed at +it. The coordinators worked from their digest, skills and `squad_state`. + +This is a strong signal, not proof: seven sessions, one model family, one +Claude Code version, and a longer session (a ceremony, Ralph mode) could still +follow the pointer. The method, a table and the script are on +[#2469](https://github.com/github/squad/issues/2469#issuecomment-6831645352). +Still, the cost that option B removes is mostly theoretical today. ### What B gains From d448970355d23c07d9ca94872d3d148d042c5475 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Thu, 12 Nov 2026 18:20:37 -0800 Subject: [PATCH 3/3] docs(adr-003): record the team direction and link #2487, #2488 Co-Authored-By: Claude Opus 5.5 --- .../adr-003-host-neutral-canonical-coordinator.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/specification/adr-003-host-neutral-canonical-coordinator.md b/docs/specification/adr-003-host-neutral-canonical-coordinator.md index 048e7b41e..d08eb9b6b 100644 --- a/docs/specification/adr-003-host-neutral-canonical-coordinator.md +++ b/docs/specification/adr-003-host-neutral-canonical-coordinator.md @@ -176,6 +176,17 @@ no risk. B is worth revisiting if a single source starts to matter: for example, if Copilot's file needs host-specific content, or remote teams need the coordinator served through `squad_state`. Neither choice gates a release. +### Team direction (2026-11-12) + +Maintainer discussion favored C for 2.0 and B only as a bounded, opt-in +experiment ([summary](https://github.com/github/squad/issues/2469)). It also +noted that the session evidence shows which files were read, not that the +coordinator behaves correctly, so C must be shown with behavioral scenarios run +with the Copilot file absent. C is tracked in +[#2487](https://github.com/github/squad/issues/2487) and the B spike in +[#2488](https://github.com/github/squad/issues/2488). This records the +discussion; it does not accept this ADR. + ## Decision Not yet made. Implementation, if approved, is a separate PR with its own