Skip to content

Commit 9865671

Browse files
bradygasterclaude
andauthored
docs(claude): align Claude Code spec, docs and matrix with the code; add host projection regression guards (#2445)
Phase 0 of #2438, plus the Phase 7 ADR as Proposed. - Rename Claude Code's subagent tool from `Task` to `Agent` in the Claude dispatch section, harness-adapters §5/§7.2, the architecture doc and the host feature matrix; describe `model`, `run_in_background` and `isolation: "worktree"`. Describe coordinator-only dispatch as Squad's policy rather than a Claude Code limitation. - Correct harness-adapters §13: Claude's `.gitignore` lines sit under a `# squad:claude` comment, and `CLAUDE.md` uses the squad:begin/end block. - Restate the model-selection.claude cell: the host supports per-call and frontmatter models (runtime.perSpawnModel is now true); the cell stays unsupported until the digest gains the section (#2442). - Add a Claude Code section to client-compatibility.md, make the README badge and model line host-aware, and note that shared-digest gaps are not host-specific. - Add regression guards with a pinned squad_state launch spec: Copilot projection snapshot, no-diff steady-state upgrade, --client copilot touches only config.json, add/remove of Claude leaves Copilot files byte-identical, and upgrading an existing Claude install keeps user content and rolls back to the user's bytes. - Add ADR-003 (Proposed) on a host-neutral canonical coordinator. Closes #2440 Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 9da4ad3 commit 9865671

13 files changed

Lines changed: 415 additions & 30 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
---
4+
5+
The Claude Code coordinator now names Claude Code's `Agent` subagent tool (formerly `Task`) and describes its `run_in_background` and `isolation: "worktree"` options. Existing Claude Code installs see this wording change in `.claude/agents/squad.md` on the next `squad upgrade --client claude`; Copilot output is unchanged.

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
**Human-led AI agent teams for any project.** One command. A team that helps you move faster with your code.
66

7-
[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad)
7+
[![Platform](https://img.shields.io/badge/platform-GitHub%20Copilot%20%2B%206%20more%20hosts-blue)](#use-squad-in-other-ai-hosts)
88

99
Breaking changes are documented in [CHANGELOG.md](CHANGELOG.md).
1010

@@ -442,7 +442,7 @@ When agents finish, the coordinator records follow-up work and leaves a breadcru
442442

443443
**And it's all in git.** Anyone who clones your repo gets the team — with all their accumulated knowledge.
444444

445-
**Each agent gets the right model.** Squad picks models quality-first by default: premium for architecture, research and review, standard for code and docs, fast for mechanical work. Opt in to the `balanced` or `economy` profile, or to the `hydrafusion` research preview with `"modelProfile": "hydrafusion"` in `.squad/config.json`. Per-agent selection works in the Copilot CLI and app; VS Code runs every agent on the one session model. See [Model Selection](https://github.github.com/squad/docs/features/model-selection/).
445+
**Each agent gets the right model.** Squad picks models quality-first by default: premium for architecture, research and review, standard for code and docs, fast for mechanical work. Opt in to the `balanced` or `economy` profile, or to the `hydrafusion` research preview with `"modelProfile": "hydrafusion"` in `.squad/config.json`. Per-agent selection works in the Copilot CLI and app; VS Code runs every agent on the one session model, and so do the other hosts (Claude Code, Kiro, OpenCode, Cursor, Codex, Antigravity) for now — see the [Host Feature Matrix](docs/src/content/docs/reference/host-feature-matrix.md). See [Model Selection](https://github.github.com/squad/docs/features/model-selection/).
446446

447447
---
448448

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
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`

‎docs/specification/client-harness-adapters-v0.2.md‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -289,7 +289,7 @@ distinct from negotiated `effectiveCapabilities`.
289289
| Host (`ClientId` / `hostKind`) | Agent anchor | MCP config | Support files | `submit` projection |
290290
|---|---|---|---|---|
291291
| GitHub Copilot (`copilot` / `github-copilot`) | `.github/agents/squad.agent.md` | `.mcp.json` | `.github/copilot-instructions.md` when present | `create_session`, `task`, or `runSubagent` depending on surface |
292-
| Claude Code (`claude` / `claude-code`) | `.claude/agents/squad.md` | `.mcp.json` | `CLAUDE.md` marker block, `.gitignore` `# squad:claude` lines | Claude `Task` subagent tool |
292+
| Claude Code (`claude` / `claude-code`) | `.claude/agents/squad.md` | `.mcp.json` | `CLAUDE.md` marker block, `.gitignore` `# squad:claude` lines | Claude `Agent` subagent tool |
293293
| Kiro (`kiro`) | `.kiro/steering/squad.md` | `.kiro/settings/mcp.json` | `.kiro/agents/squad.json`, Kiro spec and steering hooks | Kiro agent or spec execution hook |
294294
| OpenCode (`opencode`) | `.opencode/agent/squad.md` | `opencode.json` | host agent and MCP definition blocks in `opencode.json` | OpenCode agent execution entry declared in `opencode.json` |
295295
| Cursor (`cursor`) | `.cursor/agents/squad.md` | `.cursor/mcp.json` | `.cursor/rules/squad.mdc` | Cursor agent dispatch or inline agent run with projected rules |
@@ -364,9 +364,19 @@ detail inside the harness adapter rather than a different workspace contract.
364364

365365
### 7.2 `submit`
366366

367-
`submit` maps to Claude Code's `Task` subagent tool. The harness adapter is
368-
responsible for shaping the portable prompt, handling streaming callbacks, and
369-
projecting Claude's task identity into the broker run identity.
367+
`submit` maps to Claude Code's `Agent` subagent tool (named `Task` in earlier
368+
Claude Code releases). Each call takes a `prompt` and a `subagent_type`, and
369+
optionally:
370+
371+
- `model`: a per-call model override; subagent definitions in
372+
`.claude/agents/` can also set `model` and `effort` in their frontmatter;
373+
- `run_in_background`: run the subagent without blocking the caller;
374+
- `isolation: "worktree"`: run the subagent in its own git worktree under
375+
`.claude/worktrees/` (which is why the projection ignores that directory).
376+
377+
The harness adapter is responsible for shaping the portable prompt, handling
378+
streaming callbacks, and projecting Claude's subagent identity into the broker
379+
run identity.
370380

371381
### 7.3 `projectWorkspace`
372382

@@ -499,9 +509,12 @@ Companion-file ownership is explicit:
499509

500510
- `.kiro/steering/squad.md`, `.kiro/agents/squad.json`, and
501511
`.kiro/settings/mcp.json` are fully Squad-managed once projected;
502-
- `.claude/worktrees/` integration uses Squad-owned ID-scoped `.gitignore`
503-
marker blocks with `<!-- SQUAD:claude:START -->` and
504-
`<!-- SQUAD:claude:END -->`;
512+
- `.claude/worktrees/` integration adds Squad-owned `.gitignore` lines under
513+
an ID-scoped `# squad:claude` comment; rollback removes that comment and the
514+
listed lines directly beneath it, and lines the user already had stay;
515+
- the `CLAUDE.md` integration is a marker block between
516+
`<!-- squad:begin (managed by Squad; do not edit between markers) -->` and
517+
`<!-- squad:end -->`;
505518
- `AGENTS.md` and `GEMINI.md` integrations are marker-scoped and therefore use
506519
byte-preserving rollback outside those managed regions.
507520

‎docs/src/content/docs/concepts/squad-2-0-architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ The client plane lives in `@bradygaster/squad-sdk/client` (with `@bradygaster/sq
4949
| Host (`ClientId`) | Generated workspace projection | Coordinator dispatch primitive |
5050
|---|---|---|
5151
| GitHub Copilot (`copilot`) | `.github/agents/squad.agent.md`, `.mcp.json` | Copilot `task` / `create_session` / `runSubagent` |
52-
| Claude Code (`claude`) | `.claude/agents/squad.md`, `CLAUDE.md` (managed marker block), `.mcp.json`, `.gitignore` block for `.claude/worktrees/` | Claude `Task` subagent tool |
52+
| Claude Code (`claude`) | `.claude/agents/squad.md`, `CLAUDE.md` (managed marker block), `.mcp.json`, `.gitignore` block for `.claude/worktrees/` | Claude `Agent` subagent tool |
5353
| Kiro (`kiro`) | `.kiro/steering/squad.md` (`inclusion: manual`), `.kiro/agents/squad.json`, `.kiro/settings/mcp.json` | Kiro `squad` agent referencing `../steering/squad.md` |
5454
| OpenCode (`opencode`) | `.opencode/agent/squad.md`, `opencode.json` | OpenCode `@agent` / `task` primitive |
5555
| Cursor (`cursor`) | `.cursor/agents/squad.md`, `.cursor/rules/squad.mdc` (`alwaysApply: false`), `.cursor/mcp.json` | Cursor subagents or inline charter turn |

0 commit comments

Comments
 (0)