|
| 1 | +# ADR 003: Host-Neutral Canonical Coordinator in the Workspace |
| 2 | + |
| 3 | +**Status:** Proposed |
| 4 | + |
| 5 | +**Tracking:** [#2438](https://github.com/github/squad/issues/2438) (Phase 7) |
| 6 | + |
| 7 | +**Affects:** `squad-client-harness-adapters/v0.2` §4–§5 (projection contract |
| 8 | +and canonical paths) and §13 (upgrade and rollback) |
| 9 | + |
| 10 | +This ADR records a decision to be made. It does not change any code. Merging it |
| 11 | +with status Proposed does not approve it. |
| 12 | + |
| 13 | +## Context |
| 14 | + |
| 15 | +### Where the coordinator lives today |
| 16 | + |
| 17 | +In this repository the coordinator's source is already host-neutral: |
| 18 | +`.squad-templates/squad.agent.md`, copied by `scripts/sync-templates.mjs` into |
| 19 | +`templates/`, `packages/squad-cli/templates/` and |
| 20 | +`packages/squad-sdk/templates/`. |
| 21 | + |
| 22 | +In a **user workspace**, the only full copy is the Copilot one. |
| 23 | +`squad init` writes `.github/agents/squad.agent.md` (about 80 KB), and |
| 24 | +`CANONICAL_COORDINATOR_AGENT_PATH` in |
| 25 | +`packages/squad-sdk/src/client/adapters/coordinator.ts` points at it. Every |
| 26 | +other host gets a compact digest (under 24 KB, enforced by |
| 27 | +`test/clients.test.ts`) that says: |
| 28 | + |
| 29 | +- `.github/agents/squad.agent.md` is the authoritative coordinator contract; |
| 30 | +- when that file exists in the workspace, read it. |
| 31 | + |
| 32 | +So a Claude Code, Kiro, OpenCode, Cursor, Codex or Antigravity coordinator |
| 33 | +depends on a file that lives under a Copilot-specific path and is shaped for |
| 34 | +Copilot. A workspace that projects only non-Copilot hosts still gets |
| 35 | +`.github/agents/squad.agent.md`, because `squad init` always writes it. |
| 36 | + |
| 37 | +### Why it matters now |
| 38 | + |
| 39 | +Epic #2438 makes Claude Code a first-class host. Phase 4 of that epic slims the |
| 40 | +Claude coordinator by moving on-demand sections into Claude skills. How far |
| 41 | +that can go depends on what the Claude coordinator is told is authoritative: |
| 42 | +while the answer is "the Copilot file", the Claude coordinator may still read |
| 43 | +80 KB of Copilot-shaped text on demand, which undercuts the slimming. |
| 44 | + |
| 45 | +## Options |
| 46 | + |
| 47 | +### A. Keep the canonical file at `.github/agents/squad.agent.md` (status quo) |
| 48 | + |
| 49 | +- No migration. Copilot surfaces keep discovering it where they do today. |
| 50 | +- Non-Copilot hosts keep pointing at a Copilot path. Phase 4 slims only what |
| 51 | + the Claude coordinator loads by default, not what it treats as authoritative. |
| 52 | + |
| 53 | +### B. Move the canonical file to a host-neutral workspace path and generate Copilot's from it |
| 54 | + |
| 55 | +For example `.squad/coordinator.md` (inside the team directory) or a path |
| 56 | +under `.squad-templates/` in the workspace. |
| 57 | + |
| 58 | +- Every host, Copilot included, becomes a projection of one host-neutral |
| 59 | + source, which matches how the other six hosts already work. |
| 60 | +- `.github/agents/squad.agent.md` is still written for Copilot, generated from |
| 61 | + the neutral source. Copilot discovery is unchanged. |
| 62 | +- The digests point at the neutral path instead of the Copilot one. |
| 63 | +- This is a projection-version change (harness-adapters §5) for every host, |
| 64 | + and needs a migration in `squad upgrade`. |
| 65 | + |
| 66 | +### C. Keep the Copilot file canonical, but stop pointing non-Copilot hosts at it |
| 67 | + |
| 68 | +- Each host's digest becomes self-sufficient, with on-demand sections served |
| 69 | + by host-native mechanisms (Claude skills, Kiro steering, and so on). |
| 70 | +- No new file. The canonical contract remains defined only for Copilot, so |
| 71 | + keeping the hosts' behavior in step relies on the digest parity tests alone. |
| 72 | + |
| 73 | +## Constraints on any choice |
| 74 | + |
| 75 | +- **Copilot output stays byte-identical.** If B is chosen, the generated |
| 76 | + `.github/agents/squad.agent.md` must match today's bytes, checked by the |
| 77 | + Copilot snapshot in `test/host-projection-regression-guards.test.ts`. |
| 78 | +- **Copilot discovery is unaffected.** Copilot CLI, the Copilot app and VS Code |
| 79 | + auto-discover `.github/agents/`; that file must keep being written wherever |
| 80 | + Copilot is configured. |
| 81 | +- **Upgrade and rollback stay byte-preserving** (harness-adapters §13): a user |
| 82 | + who never opts in to a non-Copilot host sees no change. |
| 83 | +- **The behavioral-contract parity tests keep passing** for every host. |
| 84 | + |
| 85 | +## Open questions |
| 86 | + |
| 87 | +1. Is moving the canonical file off the Copilot path acceptable for the Copilot |
| 88 | + surfaces that auto-discover `.github/agents/`, given that the generated file |
| 89 | + stays in place? |
| 90 | +2. If B: should the neutral file live inside the team directory (`.squad/`), |
| 91 | + where it can be served by `squad_state_read` and follows `teamRoot` in |
| 92 | + remote mode, or outside it? |
| 93 | +3. If B: is the Copilot file still written for workspaces where Copilot is not |
| 94 | + in `clients[]`? |
| 95 | + |
| 96 | +## Decision |
| 97 | + |
| 98 | +Not yet made. Implementation, if approved, is a separate PR with its own |
| 99 | +projection version bump and CHANGELOG entry. |
| 100 | + |
| 101 | +## Related artifacts |
| 102 | + |
| 103 | +- [Squad Client and Harness Adapter Profile v0.2](client-harness-adapters-v0.2.md) |
| 104 | +- [ADR 001: Client, Control, and Execution Boundary](adr-001-client-control-execution-boundary.md) |
| 105 | +- `packages/squad-sdk/src/client/adapters/coordinator.ts` |
| 106 | +- `scripts/sync-templates.mjs` |
0 commit comments