Repository navigation
docs(claude): align Claude Code spec, docs and matrix with the code; add host projection regression guards (#2440) - #2445
Merged
Conversation
Contributor
🟠 Impact Analysis — PR #2445Risk tier: 🟠 HIGH 📊 Summary
🎯 Risk Factors
📦 Modules Affecteddocs (5 files)
root (3 files)
scripts (1 file)
squad-sdk (1 file)
tests (3 files)
This report is generated automatically for every PR. See #733 for details. |
Contributor
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 2 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ✅ | Branch up to date | Up to date with dev |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | No .squad/ or docs/proposals/ files |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | All 3 Copilot thread(s) resolved |
| ❌ | CI passing | 1 check(s) still running |
Files Changed (13 files, +415 −30)
| File | +/− |
|---|---|
.changeset/claude-agent-tool-dispatch.md |
+5 −0 |
README.md |
+2 −2 |
docs/specification/adr-003-host-neutral-canonical-coordinator.md |
+106 −0 |
docs/specification/client-harness-adapters-v0.2.md |
+20 −7 |
docs/src/content/docs/concepts/squad-2-0-architecture.md |
+1 −1 |
docs/src/content/docs/reference/host-feature-matrix.md |
+8 −8 |
docs/src/content/docs/scenarios/client-compatibility.md |
+35 −1 |
packages/squad-sdk/src/client/adapters/coordinator.ts |
+2 −2 |
scripts/render-host-feature-matrix.mjs |
+1 −1 |
test-fixtures/spec/suite-v0.2/host-feature-matrix.json |
+7 −7 |
test/__snapshots__/host-projection-regression-guards.test.ts.snap |
+41 −0 |
test/clients.test.ts |
+1 −1 |
test/host-projection-regression-guards.test.ts |
+186 −0 |
Total: +415 −30
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Regression snapshots retain machine-specific paths that make hashes checkout-dependent, while Claude’s runtime flag contradicts its documented support and upgrade/rollback coverage remains missing.
3 open issues
What changed in this PR
This PR prepares Squad’s Claude Code host work by aligning documentation and generated instructions with current capabilities, adding regression guards, and recording the canonical-coordinator question without implementing it.
Changes:
- Updates Claude dispatch terminology from
TasktoAgentand clarifies host capabilities and remaining gaps. - Adds Copilot projection snapshots, upgrade checks, and Claude install/uninstall preservation guards.
- Adds ADR-003 with Proposed status; no coordinator migration is implemented.
| File | Description |
|---|---|
test/host-projection-regression-guards.test.ts |
Adds projection and upgrade regression guards. |
test/clients.test.ts |
Expects Claude’s Agent dispatch primitive. |
test/__snapshots__/host-projection-regression-guards.test.ts.snap |
Records Copilot projection hashes. |
test-fixtures/spec/suite-v0.2/host-feature-matrix.json |
Corrects Claude capability descriptions. |
scripts/render-host-feature-matrix.mjs |
Clarifies shared-digest gaps in generated documentation. |
README.md |
Broadens host messaging and qualifies model selection. |
packages/squad-sdk/src/client/adapters/coordinator.ts |
Updates Claude dispatch instructions and options. |
docs/src/content/docs/scenarios/client-compatibility.md |
Adds Claude setup and capability guidance. |
docs/src/content/docs/reference/host-feature-matrix.md |
Reflects updated matrix descriptions and gap notes. |
docs/src/content/docs/concepts/squad-2-0-architecture.md |
Updates the Claude dispatch tool name. |
docs/specification/client-harness-adapters-v0.2.md |
Corrects Claude parameters and managed-file markers. |
docs/specification/adr-003-host-neutral-canonical-coordinator.md |
Proposes options for a host-neutral canonical coordinator. |
.changeset/claude-agent-tool-dispatch.md |
Records the SDK’s generated Claude instruction change. |
Review effort: Balanced (auto)
bradygaster
commented
Nov 9, 2026
bradygaster
left a comment
bradygaster
left a comment
Collaborator
Author
There was a problem hiding this comment.
Working as architect (Lead Architect). Advisory COMMENT, not approval; this API identity is also the PR author's.
Reviewed 7a19c26fe5cd7f760e4cba80e2ab6c700728b3af against #2440 / #2438. ADR-003 remains Proposed, with no migration implemented. No request to pull later-phase harness/hooks/member projection work into this PR.
Corrections: I independently reproduced the machine-dependent MCP snapshot failure and confirmed that guard 4 never upgrades an already-configured Claude install. Copilot has since posted both findings; please address its existing threads rather than creating duplicate work. The additional inline comment separates Squad's dispatch policy from the current host capability.
Validation in an isolated detached worktree:
npm run build --workspace packages/squad-sdkandnpm run build --workspace packages/squad-cli: passed.node node_modules/vitest/vitest.mjs run test/clients.test.ts test/host-projection-regression-guards.test.ts --reporter=dot: 115 passed, 35 expected failures, 1 failed (guard 1, only.mcp.jsonhash differs). Fixture/profile directories were redirected outside the checkout, under this review's session files. The built MCP launch spec includes absolute Node and CLI-entry paths, which the snapshot normalization retains.node node_modules/vitest/vitest.mjs run test/squad-20-host-feature-matrix.test.ts -t 'host-feature-matrix.json integrity' --reporter=dot: 9 passed, 11 skipped.node scripts/render-host-feature-matrix.mjs --check: passed.
No full-suite or live Claude/API run; CI's main test job was still running when checked. No fixes or changes to the author's worktree.
bradygaster
added a commit
that referenced
this pull request
Nov 9, 2026
…e, mark Claude perSpawnModel Review feedback on #2445. - Pin the squad_state launch spec to the exact-version npx form in the host projection guards. In a built checkout the real resolver writes the local node binary and checkout path into .mcp.json, so the Copilot snapshot depended on where the checkout lives. Regenerate the snapshot. - Add guard 5: with user content in .mcp.json, .gitignore and CLAUDE.md, `squad upgrade --client claude` (plain and --force) on an existing Claude install changes nothing, user content survives, and removing Claude restores the user's bytes. - Set hosts.claude.runtime.perSpawnModel to true (the Agent tool takes a per-call model) and regenerate the matrix page. The model-selection cell stays unsupported/expected-fail until the coordinator uses it. Refs #2440 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Collaborator
Author
|
Thanks for the responses. Focused follow-up on
Verified in an isolated detached worktree: both workspace builds passed; |
bradygaster
added a commit
that referenced
this pull request
Nov 9, 2026
… a Claude Code limit Review feedback on #2445. Current Claude Code releases allow nested subagents, so the Claude dispatch section and the client-compatibility row no longer claim subagents cannot spawn subagents. They state Squad's policy instead: specialists are dispatched only from the coordinator. Behavior is unchanged. The host-agnostic Ralph-mode sentence in the shared digest is left as is (it applies to every host). Refs #2440 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bradygaster
force-pushed
the
squad/2440-claude-spec-code-agreement
branch
from
November 9, 2026 18:03
8981f10 to
2782111
Compare
…add host projection regression guards 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>
bradygaster
force-pushed
the
squad/2440-claude-spec-code-agreement
branch
from
November 9, 2026 18:42
2782111 to
aac2e3e
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Working as docs-devrel and architect (labels on #2440).
What
PR 1 of epic #2438 (Claude Code as a first-class host). The spec, docs and host feature matrix now agree with the code on Claude Code. The PR also adds the regression guards every later PR in the epic must keep green, and records the Phase 7 canonical-coordinator question as a Proposed ADR.
Task→Agent: Claude Code's subagent tool is nowAgent. The rename covers the Claude dispatch section incoordinator.ts, harness-adapters §5 and §7.2, the architecture doc and five matrix cells. §7.2 also describesmodel,run_in_backgroundandisolation: "worktree".Harness-adapters §13: the spec claimed
<!-- SQUAD:claude:START -->markers in.gitignore.apply.tsactually writes lines under a# squad:claudecomment, andCLAUDE.mduses thesquad:begin/squad:endblock. The spec now describes both.model-selection.claude: the old reason ("Taskhas no per-call model") was wrong. The cell now says Claude Code supports it and Squad's coordinator doesn't use it yet. It staysunsupported/ expected-fail; making it supported is a coordinator change tracked in Claude host PR 3: Claude projection v2 (member subagents, skills, hooks, watch preset) (#2438 Phases 2, 3, 4, 6) #2442.Docs:
client-compatibility.mdRegression guards (
test/host-projection-regression-guards.test.ts):squad init+squad upgradewrites for Copilot. Only the version and CRLF are normalized.squad upgradeandsquad upgrade --forceon a steady-state Copilot-only repo change no file.squad upgrade --client copilotchanges only.squad/config.jsonand writes no Claude files.uninstallClients(['claude'])leaves every Copilot file byte-identical.Byte-exact rollback of user files for all 7 hosts was already covered by the existing "Reviewer gate" test in
clients.test.ts.ADR-003 (Proposed): a host-neutral canonical coordinator. No implementation; merging this PR does not approve it.
Why
Closes #2440. This is Phase 0 and Phase 7 (decision only) of #2438. It merges first so PRs 2 and 3 (#2441, #2442) are built on correct spec text and checked by the guards.
How
host-feature-matrix.jsonand the renderer, then re-ranscripts/render-host-feature-matrix.mjs.dev's code: I revertedcoordinator.tstodev, re-ran the guard, and got the same snapshot. Copilot output is unchanged.dev, the firstsquad upgradeafterinitis never a no-op, even for Copilot-only repos (it adds workflows, casting files and.gitignorelines). The guard therefore runsinit+ oneupgradefirst..squad-templates/). The Copilot-specific part is the workspace: users only get.github/agents/squad.agent.md, and every other host's digest is told to read it as authoritative.Test results
npm run lint,eslinton the new test,markdownlint-cli2andcspellon the changed docs: clean.test/clients.test.tsand the new guard tests pass after rebasing onto the latestdev: 116 passed, 35 expected-fail.upstream-*,memory-*,profile-fs-guard,export-import,gh-aw-bootstrap-workflow,upgrade-profile-teamroot, and two bridge tests insquad-20-host-feature-matrix). The same 26 fail on cleandevwith these changes stashed. They're temp-path checks (for example "Path traversal" against the temp directory), not this change. CI (Ubuntu) is the reference.PR Readiness Checklist
Branch & Commit
dev(notmain)devBuild & Test
npm run buildpassesnpm testpasses: see Test results (failures matchdevlocally; relying on CI)npm run lintpassesnpm run lint:eslintpasses (on the changed test files)Changeset
.changeset/claude-agent-tool-dispatch.md,squad-sdkpatch)Docs
client-compatibility.md)Exports
Breaking Changes
None. Existing Claude Code installs see a wording-only diff in
.claude/agents/squad.mdon the nextsquad upgrade --client claude. Copilot output is unchanged (guard 1).Waivers
None.
🤖 Generated with Claude Code