From ae56ed82bd49d8e9709baefe79f3889531b8e4ab Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 16 Nov 2026 20:10:06 -0800 Subject: [PATCH 1/3] fix(cast): list built-in members in team.md so every host sees the same roster (#2522) `squad init` scaffolds the Scribe, Ralph, Rai and Fact Checker charters but leaves the roster empty, and `squad cast --name` only adds the member being cast. A team cast that way (Claude Code's Init Mode path) had no built-ins in team.md, so Copilot, which reads the roster from team.md, reported a smaller team than Claude did. - squad cast adds the `## Built-in Support Agents` table (the same one createTeam writes) when the built-in charters exist and team.md doesn't list them anywhere. It stays out of `## Members`, so Init Mode's empty-roster check is unaffected. - Coordinator wording (Copilot template and the shared source for other hosts): a roster answer lists the members and built-ins and describes the coordinator separately, instead of listing "Squad" as a member. - Regenerated the Claude plugin tree and the Copilot projection snapshot. Closes #2522 Co-Authored-By: Claude Opus 5.5 --- .changeset/cast-builtin-roster.md | 6 ++ .github/agents/squad.agent.md | 2 + .squad-templates/squad.agent.md | 2 + packages/squad-cli/src/cli/commands/cast.ts | 16 +++++ packages/squad-cli/src/cli/core/cast.ts | 26 +++++++ .../templates/squad.agent.md.template | 2 + .../src/client/adapters/coordinator.ts | 2 +- .../templates/squad.agent.md.template | 2 + plugins/squad/agents/squad.md | 2 +- templates/squad.agent.md.template | 2 + ...-projection-regression-guards.test.ts.snap | 2 +- test/cli/cast.test.ts | 71 +++++++++++++++++++ 12 files changed, 132 insertions(+), 3 deletions(-) create mode 100644 .changeset/cast-builtin-roster.md diff --git a/.changeset/cast-builtin-roster.md b/.changeset/cast-builtin-roster.md new file mode 100644 index 000000000..599845fa5 --- /dev/null +++ b/.changeset/cast-builtin-roster.md @@ -0,0 +1,6 @@ +--- +'@bradygaster/squad-cli': patch +'@bradygaster/squad-sdk': patch +--- + +`squad cast` now adds the built-in support agents (Scribe, Ralph, Rai, Fact Checker) to `team.md` when the roster doesn't list them yet, so Claude Code and Copilot report the same team after a cast. Coordinators also describe themselves separately in roster answers instead of listing "Squad" as a member (#2522). diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md index 32eab19d8..02f4a0a40 100644 --- a/.github/agents/squad.agent.md +++ b/.github/agents/squad.agent.md @@ -375,6 +375,8 @@ After routing determines WHO handles work, select a **response MODE** (Direct / | **Standard** | Normal tasks needing full context (one agent, full ceremony) — *default* | | **Full** | Multi-agent "Team" requests touching 3+ concerns (parallel fan-out) | +**Roster answers** ("who's on the team?") are Direct: list the `## Members` rows and the built-in support agents (Scribe, Ralph, Rai, Fact Checker). The `## Coordinator` row is you, not a member: describe yourself separately ("I'm Squad, the coordinator") rather than listing yourself in the team. + **For the full decision table, exemplar prompts, mode-upgrade rules, the Lightweight Spawn Template, and explore-agent usage:** invoke the `skill` tool on **`coordinator-response-mode`** to load the complete protocol. ### Per-Agent Model Selection diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md index 32eab19d8..02f4a0a40 100644 --- a/.squad-templates/squad.agent.md +++ b/.squad-templates/squad.agent.md @@ -375,6 +375,8 @@ After routing determines WHO handles work, select a **response MODE** (Direct / | **Standard** | Normal tasks needing full context (one agent, full ceremony) — *default* | | **Full** | Multi-agent "Team" requests touching 3+ concerns (parallel fan-out) | +**Roster answers** ("who's on the team?") are Direct: list the `## Members` rows and the built-in support agents (Scribe, Ralph, Rai, Fact Checker). The `## Coordinator` row is you, not a member: describe yourself separately ("I'm Squad, the coordinator") rather than listing yourself in the team. + **For the full decision table, exemplar prompts, mode-upgrade rules, the Lightweight Spawn Template, and explore-agent usage:** invoke the `skill` tool on **`coordinator-response-mode`** to load the complete protocol. ### Per-Agent Model Selection diff --git a/packages/squad-cli/src/cli/commands/cast.ts b/packages/squad-cli/src/cli/commands/cast.ts index 16670ced9..70d3a38e1 100644 --- a/packages/squad-cli/src/cli/commands/cast.ts +++ b/packages/squad-cli/src/cli/commands/cast.ts @@ -25,6 +25,7 @@ import { LocalAgentSource } from '@bradygaster/squad-sdk/config/agent-source'; import { resolveSquadPaths, resolveExternalStateDir } from '@bradygaster/squad-sdk/resolution'; import { BOLD, RESET, info, success } from '../core/output.js'; import { fatal, fatalNoSquad } from '../core/errors.js'; +import { ensureBuiltinSupportSection } from '../core/cast.js'; const storage = new FSStorageProvider(); @@ -212,6 +213,20 @@ function updateTeamMdWithAgent(squadDir: string, name: string, role: string, slu storage.writeSync(teamPath, updated); } +/** + * `squad init` creates the built-in charters but leaves the roster empty, and casting one member at + * a time only adds that member's row. List the built-ins in `team.md` too, so every host reading the + * roster sees the same team (#2522). Skipped when the built-ins were never scaffolded. + */ +function ensureBuiltinRoster(squadDir: string): void { + if (!storage.existsSync(path.join(squadDir, 'agents', 'scribe', 'charter.md'))) return; + const teamPath = path.join(squadDir, 'team.md'); + const existing = storage.readSync(teamPath); + if (existing === undefined) return; + const updated = ensureBuiltinSupportSection(existing); + if (updated !== existing) storage.writeSync(teamPath, updated); +} + function updateRoutingMdWithAgent(squadDir: string, name: string, role: string): void { const routingPath = path.join(squadDir, 'routing.md'); const row = `| ${role} | ${name} | — |`; @@ -391,6 +406,7 @@ export async function runCastAdd(cwd: string, options: CastAddOptions): Promise< } updateTeamMdWithAgent(squadDir, rawName, displayRole, slug); + ensureBuiltinRoster(squadDir); updateRoutingMdWithAgent(squadDir, rawName, displayRole); await updateCastingStateWithAgent(squadDir, rawName, displayRole, slug); await addAgentToConfig(teamRoot, slug, displayRole); diff --git a/packages/squad-cli/src/cli/core/cast.ts b/packages/squad-cli/src/cli/core/cast.ts index 00b79ccd7..f5066a72a 100644 --- a/packages/squad-cli/src/cli/core/cast.ts +++ b/packages/squad-cli/src/cli/core/cast.ts @@ -550,6 +550,32 @@ function buildSupportTable(): string { `; } +/** + * Add the `## Built-in Support Agents` table to a `team.md` that does not list the built-ins + * anywhere, placed where `createTeam` puts it (before `## Coding Agent` or `## Project Context`, + * else at the end). A roster that already names them (in that section, a legacy + * `## Support Identities` section, or as rows under `## Members`) is returned unchanged, so this + * is idempotent. Kept out of `## Members` so Init Mode's "empty roster" check still counts only + * cast members (#2522). + */ +export function ensureBuiltinSupportSection(content: string): string { + if ( + content.includes('## Built-in Support Agents') + || content.includes('## Support Identities') + || content.includes('.squad/agents/scribe/charter.md') + ) { + return content; + } + const section = buildSupportTable(); + for (const heading of ['## Coding Agent', '## Project Context']) { + const idx = content.indexOf(`\n${heading}`); + if (idx !== -1) { + return `${content.slice(0, idx + 1)}${section}\n${content.slice(idx + 1)}`; + } + } + return `${content.trimEnd()}\n\n${section}`; +} + function replaceSection(content: string, headings: string[], replacement: string): string { for (const heading of headings) { const headingIndex = content.indexOf(heading); diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template index 32eab19d8..02f4a0a40 100644 --- a/packages/squad-cli/templates/squad.agent.md.template +++ b/packages/squad-cli/templates/squad.agent.md.template @@ -375,6 +375,8 @@ After routing determines WHO handles work, select a **response MODE** (Direct / | **Standard** | Normal tasks needing full context (one agent, full ceremony) — *default* | | **Full** | Multi-agent "Team" requests touching 3+ concerns (parallel fan-out) | +**Roster answers** ("who's on the team?") are Direct: list the `## Members` rows and the built-in support agents (Scribe, Ralph, Rai, Fact Checker). The `## Coordinator` row is you, not a member: describe yourself separately ("I'm Squad, the coordinator") rather than listing yourself in the team. + **For the full decision table, exemplar prompts, mode-upgrade rules, the Lightweight Spawn Template, and explore-agent usage:** invoke the `skill` tool on **`coordinator-response-mode`** to load the complete protocol. ### Per-Agent Model Selection diff --git a/packages/squad-sdk/src/client/adapters/coordinator.ts b/packages/squad-sdk/src/client/adapters/coordinator.ts index 879829a59..3db15aa4c 100644 --- a/packages/squad-sdk/src/client/adapters/coordinator.ts +++ b/packages/squad-sdk/src/client/adapters/coordinator.ts @@ -136,7 +136,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep ## Behavioral contract (same as Copilot) -10. **Response Mode Selection.** Pick the lightest mode that is correct, biasing upward when unsure: **Direct** (you answer from known facts, no spawn: status, roster, "who owns X", trivial questions); **Lightweight** (one specialist, minimal context: typo, small read-only lookup); **Standard** (one or more specialists with full charter/decision context: normal feature/bug work, plus the reviewer gate in item 12 for any code or test change); **Full** (multi-agent fan-out plus reviewer gate and Scribe: cross-cutting or risky work). Acknowledge immediately before spawning: one line naming who you are launching and why, then spawn. +10. **Response Mode Selection.** Pick the lightest mode that is correct, biasing upward when unsure: **Direct** (you answer from known facts, no spawn: status, roster, "who owns X", trivial questions; a roster answer lists the \`## Members\` rows and the built-in support agents, and describes you, the coordinator, separately rather than as a member); **Lightweight** (one specialist, minimal context: typo, small read-only lookup); **Standard** (one or more specialists with full charter/decision context: normal feature/bug work, plus the reviewer gate in item 12 for any code or test change); **Full** (multi-agent fan-out plus reviewer gate and Scribe: cross-cutting or risky work). Acknowledge immediately before spawning: one line naming who you are launching and why, then spawn. 11. **Scribe spawn protocol and drop-box pattern.** Agents never write \`${S}/decisions.md\` directly: decisions go to \`${S}/decisions/inbox/\` (via \`squad_decide\`). **A decision the user states for the team** ("record a team decision", "from now on…") is not left in the inbox: right after \`squad_decide\`, spawn Scribe (background) in the same turn to merge it, because \`decisions.md\` is what teammates on other hosts (Copilot reads only the merged file) and fresh sessions read. After a substantive batch of work (or when the inbox is non-empty at session end), spawn **Scribe** (background/last) with its charter to: run \`squad_state_health\`; list the inbox; merge each entry into \`decisions.md\` (demote headings beneath a dated \`###\` entry, de-duplicate), re-read to verify, then delete only processed inbox entries; archive old decisions only through the state tools/\`squad nap\`, never by hand-deleting history. Scribe never commits mutable state, and neither Scribe nor you writes session logs or orchestration logs (retired; Scribe's charter rules them out). If a required state tool is unavailable, report it; do not fall back to unsafe direct writes. 12. **Reviewer rejection protocol and strict lockout.** Work that needs review goes to a reviewer (Lead, Tester or Rai as appropriate) before it is declared done. Every code or test change needs review, as does anything \`routing.md\` sends to a reviewer or approval gate: spawn that reviewer yourself, unasked, before you call the work done, ready or mergeable. The reviewer is never an author of the work. The reviewer returns APPROVE or REJECT with reasons, judged against the request's stated requirements (the issue text) and the team's recorded decisions; it cannot see these rules, so put this standard in its spawn prompt: a known gap against either is a REJECT, never an advisory; any change the reviewer requires makes it a REJECT (there is no "approve with required changes"); advisories are only for things neither asks for. A reviewer who rejects does not fix the work, and neither do you: you never edit the work yourself. If a reviewer writes code anyway, that code needs a different reviewer. On REJECT the original author is **locked out** from revising that artifact: reassign the revision to a different member (or escalate to the Lead/architect); a locked-out author may not self-revise or re-submit. Re-review is required after the revision. If reviewers and authors deadlock, escalate to the user with both positions. Record verdicts via \`squad_decide\`. 13. **Rai (RAI Reviewer).** Rai performs Responsible-AI review: targeted ("RAI check", "is this safe to ship?"), pre-ship for user-facing artifacts, and pre-merge. Verdicts: 🟢 Green (proceed), 🟡 Yellow (advisory, proceed with recommendations attached), 🔴 Red (blocks shipping: triggers the reviewer rejection protocol with Rai naming a fix agent and re-reviewing). Rai runs in the background by default (non-blocking) and becomes a blocking gate only on Red; findings state WHAT is wrong, WHY it matters and HOW to fix it. Policy and audit trail: \`${S}/rai/policy.md\`, \`${S}/rai/audit-trail.md\` (append via state tools). diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template index 32eab19d8..02f4a0a40 100644 --- a/packages/squad-sdk/templates/squad.agent.md.template +++ b/packages/squad-sdk/templates/squad.agent.md.template @@ -375,6 +375,8 @@ After routing determines WHO handles work, select a **response MODE** (Direct / | **Standard** | Normal tasks needing full context (one agent, full ceremony) — *default* | | **Full** | Multi-agent "Team" requests touching 3+ concerns (parallel fan-out) | +**Roster answers** ("who's on the team?") are Direct: list the `## Members` rows and the built-in support agents (Scribe, Ralph, Rai, Fact Checker). The `## Coordinator` row is you, not a member: describe yourself separately ("I'm Squad, the coordinator") rather than listing yourself in the team. + **For the full decision table, exemplar prompts, mode-upgrade rules, the Lightweight Spawn Template, and explore-agent usage:** invoke the `skill` tool on **`coordinator-response-mode`** to load the complete protocol. ### Per-Agent Model Selection diff --git a/plugins/squad/agents/squad.md b/plugins/squad/agents/squad.md index 026537348..1a2f715e0 100644 --- a/plugins/squad/agents/squad.md +++ b/plugins/squad/agents/squad.md @@ -25,7 +25,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep ## Behavioral contract (same as Copilot) -10. **Response Mode Selection.** Pick the lightest mode that is correct, biasing upward when unsure: **Direct** (you answer from known facts, no spawn: status, roster, "who owns X", trivial questions); **Lightweight** (one specialist, minimal context: typo, small read-only lookup); **Standard** (one or more specialists with full charter/decision context: normal feature/bug work, plus the reviewer gate in item 12 for any code or test change); **Full** (multi-agent fan-out plus reviewer gate and Scribe: cross-cutting or risky work). Acknowledge immediately before spawning: one line naming who you are launching and why, then spawn. +10. **Response Mode Selection.** Pick the lightest mode that is correct, biasing upward when unsure: **Direct** (you answer from known facts, no spawn: status, roster, "who owns X", trivial questions; a roster answer lists the `## Members` rows and the built-in support agents, and describes you, the coordinator, separately rather than as a member); **Lightweight** (one specialist, minimal context: typo, small read-only lookup); **Standard** (one or more specialists with full charter/decision context: normal feature/bug work, plus the reviewer gate in item 12 for any code or test change); **Full** (multi-agent fan-out plus reviewer gate and Scribe: cross-cutting or risky work). Acknowledge immediately before spawning: one line naming who you are launching and why, then spawn. 11. **Scribe spawn protocol and drop-box pattern.** Agents never write `.squad/decisions.md` directly: decisions go to `.squad/decisions/inbox/` (via `squad_decide`). **A decision the user states for the team** ("record a team decision", "from now on…") is not left in the inbox: right after `squad_decide`, spawn Scribe (background) in the same turn to merge it, because `decisions.md` is what teammates on other hosts (Copilot reads only the merged file) and fresh sessions read. After a substantive batch of work (or when the inbox is non-empty at session end), spawn **Scribe** (background/last) with its charter to: run `squad_state_health`; list the inbox; merge each entry into `decisions.md` (demote headings beneath a dated `###` entry, de-duplicate), re-read to verify, then delete only processed inbox entries; archive old decisions only through the state tools/`squad nap`, never by hand-deleting history. Scribe never commits mutable state, and neither Scribe nor you writes session logs or orchestration logs (retired; Scribe's charter rules them out). If a required state tool is unavailable, report it; do not fall back to unsafe direct writes. 12. **Reviewer rejection protocol and strict lockout.** Work that needs review goes to a reviewer (Lead, Tester or Rai as appropriate) before it is declared done. Every code or test change needs review, as does anything `routing.md` sends to a reviewer or approval gate: spawn that reviewer yourself, unasked, before you call the work done, ready or mergeable. The reviewer is never an author of the work. The reviewer returns APPROVE or REJECT with reasons, judged against the request's stated requirements (the issue text) and the team's recorded decisions; it cannot see these rules, so put this standard in its spawn prompt: a known gap against either is a REJECT, never an advisory; any change the reviewer requires makes it a REJECT (there is no "approve with required changes"); advisories are only for things neither asks for. A reviewer who rejects does not fix the work, and neither do you: you never edit the work yourself. If a reviewer writes code anyway, that code needs a different reviewer. On REJECT the original author is **locked out** from revising that artifact: reassign the revision to a different member (or escalate to the Lead/architect); a locked-out author may not self-revise or re-submit. Re-review is required after the revision. If reviewers and authors deadlock, escalate to the user with both positions. Record verdicts via `squad_decide`. 13. **Rai (RAI Reviewer).** Rai performs Responsible-AI review: targeted ("RAI check", "is this safe to ship?"), pre-ship for user-facing artifacts, and pre-merge. Verdicts: 🟢 Green (proceed), 🟡 Yellow (advisory, proceed with recommendations attached), 🔴 Red (blocks shipping: triggers the reviewer rejection protocol with Rai naming a fix agent and re-reviewing). Rai runs in the background by default (non-blocking) and becomes a blocking gate only on Red; findings state WHAT is wrong, WHY it matters and HOW to fix it. Policy and audit trail: `.squad/rai/policy.md`, `.squad/rai/audit-trail.md` (append via state tools). diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template index 32eab19d8..02f4a0a40 100644 --- a/templates/squad.agent.md.template +++ b/templates/squad.agent.md.template @@ -375,6 +375,8 @@ After routing determines WHO handles work, select a **response MODE** (Direct / | **Standard** | Normal tasks needing full context (one agent, full ceremony) — *default* | | **Full** | Multi-agent "Team" requests touching 3+ concerns (parallel fan-out) | +**Roster answers** ("who's on the team?") are Direct: list the `## Members` rows and the built-in support agents (Scribe, Ralph, Rai, Fact Checker). The `## Coordinator` row is you, not a member: describe yourself separately ("I'm Squad, the coordinator") rather than listing yourself in the team. + **For the full decision table, exemplar prompts, mode-upgrade rules, the Lightweight Spawn Template, and explore-agent usage:** invoke the `skill` tool on **`coordinator-response-mode`** to load the complete protocol. ### Per-Agent Model Selection diff --git a/test/__snapshots__/host-projection-regression-guards.test.ts.snap b/test/__snapshots__/host-projection-regression-guards.test.ts.snap index 0c9565206..706acbc97 100644 --- a/test/__snapshots__/host-projection-regression-guards.test.ts.snap +++ b/test/__snapshots__/host-projection-regression-guards.test.ts.snap @@ -4,7 +4,7 @@ exports[`host projection regression guards (#2438) > guard 1: the Copilot projec { ".copilot/mcp-config.json": "c68ab872f9f9b0a4ff12b221ee8bccb6dfec1bf1b886f05971935d5bc48b33e6", ".gitattributes": "fe8886d03bd8d8c7fb0b274cb8748fe4c97b08ce8b55c2aa72a2e173a0235ce3", - ".github/agents/squad.agent.md": "b5160cf1f21a717653cfd0c068f7b405fe8fb40c86c47882b105a0e383cae7fa", + ".github/agents/squad.agent.md": "6e883a1e30bd23577fe287171de9520cdb056f3824de8d4112c72f1d509305d7", ".github/skills/agent-collaboration/SKILL.md": "e1943766f6aa5efeb145f22d1583f5b38d4d8a7109ae17f085ec064dada4b9bf", ".github/skills/coordinator-init-mode/SKILL.md": "3e74448a48372968a7d14c43e7461bed1aee968073461341a6e33d57de0f85e1", ".github/skills/coordinator-response-mode/SKILL.md": "0be5f6ac5e3ad7c8b818770a72fa8bf3693196c23c9bba1ae7675caabd73e8c1", diff --git a/test/cli/cast.test.ts b/test/cli/cast.test.ts index b0101a7da..654960a63 100644 --- a/test/cli/cast.test.ts +++ b/test/cli/cast.test.ts @@ -244,6 +244,8 @@ describe('squad cast', () => { const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); expect(teamMd).toContain('| Probe |'); expect(teamMd).toContain('.squad/agents/probe/charter.md'); + // No built-in charters were scaffolded here, so no built-in rows are invented (#2522). + expect(teamMd).not.toContain('## Built-in Support Agents'); const registryRaw = await readFile(join(sq, 'casting', 'registry.json'), 'utf-8'); const registry = JSON.parse(registryRaw) as { agents: Record }; @@ -255,6 +257,75 @@ describe('squad cast', () => { expect(castOutput).toContain('Probe'); }); + describe('built-in members in team.md (#2522)', () => { + const INIT_TEAM_MD = [ + '# Squad Team', + '', + '## Coordinator', + '', + '| Name | Role | Notes |', + '|------|------|-------|', + '| Squad | Coordinator | Routes work, enforces handoffs and reviewer gates. |', + '', + '## Members', + '', + '| Name | Role | Charter | Status |', + '|------|------|---------|--------|', + '', + '## Project Context', + '', + '- **Project:** demo', + '', + ].join('\n'); + + async function scaffoldInitShape(teamMd: string): Promise { + const sq = join(TEST_ROOT, '.squad'); + for (const id of ['scribe', 'ralph', 'rai', 'fact-checker']) { + await mkdir(join(sq, 'agents', id), { recursive: true }); + await writeFile(join(sq, 'agents', id, 'charter.md'), `# ${id}\n`); + } + await writeFile(join(sq, 'team.md'), teamMd); + await writeFile(join(sq, 'routing.md'), '# Routing\n'); + await writeFile(join(sq, 'decisions.md'), '# Decisions\n'); + return sq; + } + + it('lists the built-ins once, outside ## Members, after casting members into an init roster', async () => { + const sq = await scaffoldInitShape(INIT_TEAM_MD); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); + await runCastAdd(TEST_ROOT, { name: 'Penny', role: 'Lead' }); + await runCastAdd(TEST_ROOT, { name: 'Tally', role: 'Tester' }); + + const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); + expect(teamMd.split('## Built-in Support Agents').length).toBe(2); + for (const name of ['Scribe', 'Ralph', 'Rai', 'Fact Checker']) { + expect(teamMd).toContain(`| ${name} |`); + } + // Placed before Project Context, and ## Members still holds only the cast members. + expect(teamMd.indexOf('## Built-in Support Agents')).toBeLessThan(teamMd.indexOf('## Project Context')); + const members = teamMd.slice(teamMd.indexOf('## Members'), teamMd.indexOf('## Built-in Support Agents')); + expect(members).toContain('| Penny |'); + expect(members).toContain('| Tally |'); + expect(members).not.toContain('Scribe'); + }); + + it('leaves a roster that already lists the built-ins under ## Members alone', async () => { + const withBuiltins = INIT_TEAM_MD.replace( + '|------|------|---------|--------|\n', + '|------|------|---------|--------|\n| Scribe | Decision Merger | `.squad/agents/scribe/charter.md` | 📋 Silent |\n', + ); + const sq = await scaffoldInitShape(withBuiltins); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); + await runCastAdd(TEST_ROOT, { name: 'Penny', role: 'Lead' }); + + const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); + expect(teamMd).not.toContain('## Built-in Support Agents'); + expect(teamMd.split('| Scribe |').length).toBe(2); + }); + }); + it('rejects missing --name or --role with SquadError (#2191)', async () => { await scaffold(TEST_ROOT); const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); From 7346c258c5c429669171226efde033d331c5ea3b Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 16 Nov 2026 20:13:42 -0800 Subject: [PATCH 2/3] chore: fold the changeset into CHANGELOG.md (changeset drift limit) Co-Authored-By: Claude Opus 5.5 --- .changeset/cast-builtin-roster.md | 6 ------ CHANGELOG.md | 1 + 2 files changed, 1 insertion(+), 6 deletions(-) delete mode 100644 .changeset/cast-builtin-roster.md diff --git a/.changeset/cast-builtin-roster.md b/.changeset/cast-builtin-roster.md deleted file mode 100644 index 599845fa5..000000000 --- a/.changeset/cast-builtin-roster.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -'@bradygaster/squad-cli': patch -'@bradygaster/squad-sdk': patch ---- - -`squad cast` now adds the built-in support agents (Scribe, Ralph, Rai, Fact Checker) to `team.md` when the roster doesn't list them yet, so Claude Code and Copilot report the same team after a cast. Coordinators also describe themselves separately in roster answers instead of listing "Squad" as a member (#2522). diff --git a/CHANGELOG.md b/CHANGELOG.md index fbce47aa9..884f88c73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -81,6 +81,7 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o - **Squad's own tools no longer prompt in Claude Code.** In a demo dry run, a fresh `squad init --client claude` project hit 13 permission prompts while casting the team, and the coordinator ended up hand-writing charters and asking the user to run `squad cast` themselves. `squad init` and `squad upgrade` now add a scoped allowlist to `.claude/settings.json`: the `squad_state` tools the coordinator uses, by name (never the experimental backend's approval tools), and `squad cast`, `squad client sync`, `squad lockout reject` and `squad lockout status` (the steps that release a lockout, `assign`, `submit`, `approve` and `override`, still ask), as `squad …` and, when `.mcp.json` runs Squad's own launcher, as `node .squad/squad.mjs …`. Nothing else is allowed, and `squad cast` now refuses to write through a symbolic link. Your own rules come first and are never touched; Squad records the rules it added in `.claude/.squad-permissions.json`, and rollback removes only those, and `"claudePermissions": "off"` in `.squad/config.json` turns it off. Claude Code applies project allow rules only after the folder is trusted (the trust prompt on your first interactive `claude` run there). `squad init` now says so, and if a cast is still denied the coordinator stops and asks instead of retrying variants or hand-writing the team. - **`squad_decide` says where a git-branch backend stored the decision.** In a live run on the `orphan` backend, the coordinator told the user the decision was in `.squad/decisions/inbox/…`, but it was only on the `squad-state` branch. The tool result now says the path is a key on that branch, so the coordinator reports it correctly. - **A decision made in Claude Code reaches teammates on Copilot.** In a live run with one squad and two people, Alex on Claude Code recorded "API errors are JSON `{error, code}`". Blake on Copilot CLI was then told no error convention existed. Claude's coordinator had left the decision in the inbox, but Copilot's reads only the merged `decisions.md`. The non-Copilot coordinators now spawn Scribe in the same turn for a decision the user states. In a re-run, Blake saw both of Alex's decisions with their authors, and Alex saw Blake's. +- **Claude Code and Copilot report the same roster.** In a live run on one squad, Claude cast the team with `squad cast`, which added only the cast members to `team.md`. Claude still listed Scribe, Ralph, Rai and Fact Checker, but Copilot, which reads the roster from `team.md`, showed three specialists and listed the coordinator ("Squad") as a member. `squad cast` now adds the built-in support agents' table when the roster doesn't list them, and the coordinators describe themselves separately in roster answers (#2522). - **Claude Code gets only its own Init Mode skill.** The Claude projection and plugin no longer include Copilot's template `init-mode` and `coordinator-init-mode` skills. Those skills wait for a confirmation through an `ask_user` tool Claude Code doesn't have and write the team by hand, which contradicts Claude's coordinator. Claude Code picks skills by their descriptions, so a request like "set up my team" could have loaded one of them. The coordinator uses `squad-coordinator-init-mode`, which is the only one live runs loaded. A Squad-generated copy left in `.claude/skills/` is removed on the next `squad upgrade`. Copilot is unchanged. - **The reviewer gate runs on its own and means it.** In the same dry run, the coordinator declared a bug fix done without the lead's review even though `routing.md` named the lead as the approval gate; when asked, the lead listed six known gaps against the issue and still approved; and a reviewer's own fix went unreviewed. The non-Copilot coordinators now send every code or test change to the reviewer before calling it done, unasked; the reviewer is never an author, judges against the issue and the team's recorded decisions (a known gap against either is a REJECT, not an advisory), and code a reviewer writes needs a different reviewer. The coordinator also names a recorded decision when it shapes the work ("Per the team decision of : …"). - **Coordinators wait for a human's sign-off.** When `team.md` or `routing.md` says a human must sign off on work (a release, tag, publish, merge or deploy), the Claude, Kiro, OpenCode, Cursor, Codex and Antigravity coordinators no longer treat the request itself as the sign-off. They name the rule and the human, ask whether you are that human or have their sign-off, go ahead only on an explicit yes, and record it in the decisions inbox. In a non-interactive run they stop at the gate. Seen in a live test: asked to "cut the 1.0.0 release", the Claude coordinator used to bump, tag and run `npm publish` itself. From 0ae302351098f500c8ff6126956a0247f5f277ad Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Mon, 16 Nov 2026 20:19:55 -0800 Subject: [PATCH 3/3] fix(cast): handle each built-in on its own when adding roster rows (review) Add a row only for a built-in whose charter exists and that the roster doesn't already list (by charter path or name row), instead of using Scribe as the sentinel for all four. Co-Authored-By: Claude Opus 5.5 --- packages/squad-cli/src/cli/commands/cast.ts | 10 ++-- packages/squad-cli/src/cli/core/cast.ts | 44 ++++++++++++------ test/cli/cast.test.ts | 51 +++++++++++++++++---- 3 files changed, 81 insertions(+), 24 deletions(-) diff --git a/packages/squad-cli/src/cli/commands/cast.ts b/packages/squad-cli/src/cli/commands/cast.ts index 70d3a38e1..50bd196d6 100644 --- a/packages/squad-cli/src/cli/commands/cast.ts +++ b/packages/squad-cli/src/cli/commands/cast.ts @@ -216,14 +216,18 @@ function updateTeamMdWithAgent(squadDir: string, name: string, role: string, slu /** * `squad init` creates the built-in charters but leaves the roster empty, and casting one member at * a time only adds that member's row. List the built-ins in `team.md` too, so every host reading the - * roster sees the same team (#2522). Skipped when the built-ins were never scaffolded. + * roster sees the same team (#2522). Only built-ins whose charter exists get a row. */ function ensureBuiltinRoster(squadDir: string): void { - if (!storage.existsSync(path.join(squadDir, 'agents', 'scribe', 'charter.md'))) return; + const installed = new Set( + ['scribe', 'ralph', 'rai', 'fact-checker'] + .filter((id) => storage.existsSync(path.join(squadDir, 'agents', id, 'charter.md'))), + ); + if (installed.size === 0) return; const teamPath = path.join(squadDir, 'team.md'); const existing = storage.readSync(teamPath); if (existing === undefined) return; - const updated = ensureBuiltinSupportSection(existing); + const updated = ensureBuiltinSupportSection(existing, installed); if (updated !== existing) storage.writeSync(teamPath, updated); } diff --git a/packages/squad-cli/src/cli/core/cast.ts b/packages/squad-cli/src/cli/core/cast.ts index f5066a72a..56ee28b27 100644 --- a/packages/squad-cli/src/cli/core/cast.ts +++ b/packages/squad-cli/src/cli/core/cast.ts @@ -550,23 +550,41 @@ function buildSupportTable(): string { `; } +/** The `## Built-in Support Agents` rows, keyed by built-in ID (matches `buildSupportTable`). */ +const BUILTIN_SUPPORT_ROWS: ReadonlyArray<{ id: string; name: string; row: string }> = [ + { id: 'scribe', name: 'Scribe', row: '| Scribe | Decision Merger | `.squad/agents/scribe/charter.md` | 📋 Silent |' }, + { id: 'ralph', name: 'Ralph', row: '| Ralph | Work Monitor | `.squad/agents/ralph/charter.md` | 🔄 Monitor |' }, + { id: 'rai', name: 'Rai', row: '| Rai | RAI Reviewer | `.squad/agents/rai/charter.md` | 🛡️ RAI |' }, + { id: 'fact-checker', name: 'Fact Checker', row: "| Fact Checker | Devil's Advocate & Verification Agent | `.squad/agents/fact-checker/charter.md` | 🔍 Verifier |" }, +]; + /** - * Add the `## Built-in Support Agents` table to a `team.md` that does not list the built-ins - * anywhere, placed where `createTeam` puts it (before `## Coding Agent` or `## Project Context`, - * else at the end). A roster that already names them (in that section, a legacy - * `## Support Identities` section, or as rows under `## Members`) is returned unchanged, so this - * is idempotent. Kept out of `## Members` so Init Mode's "empty roster" check still counts only - * cast members (#2522). + * Add a `## Built-in Support Agents` table to `team.md` for the built-ins that are installed + * (`installedIds`, e.g. those whose charter exists) but not yet on the roster, placed where + * `createTeam` puts it (before `## Coding Agent` or `## Project Context`, else at the end). Each + * built-in is checked on its own: one already listed anywhere (by charter path or a `| Name |` row, + * under `## Members` or elsewhere) is not repeated, and one that isn't installed gets no row. A + * roster that already has the section (or a legacy `## Support Identities` one) is left to + * `createTeam`, which owns it. Idempotent. Kept out of `## Members` so Init Mode's "empty roster" + * check still counts only cast members (#2522). */ -export function ensureBuiltinSupportSection(content: string): string { - if ( - content.includes('## Built-in Support Agents') - || content.includes('## Support Identities') - || content.includes('.squad/agents/scribe/charter.md') - ) { +export function ensureBuiltinSupportSection(content: string, installedIds: ReadonlySet): string { + if (content.includes('## Built-in Support Agents') || content.includes('## Support Identities')) { return content; } - const section = buildSupportTable(); + const missing = BUILTIN_SUPPORT_ROWS.filter(({ id, name }) => + installedIds.has(id) + && !content.includes(`.squad/agents/${id}/charter.md`) + && !new RegExp(`^\\|\\s*${name}\\s*\\|`, 'm').test(content)); + if (missing.length === 0) return content; + const section = [ + '## Built-in Support Agents', + '', + '| Name | Role | Charter | Status |', + '|------|------|---------|--------|', + ...missing.map(({ row }) => row), + '', + ].join('\n'); for (const heading of ['## Coding Agent', '## Project Context']) { const idx = content.indexOf(`\n${heading}`); if (idx !== -1) { diff --git a/test/cli/cast.test.ts b/test/cli/cast.test.ts index 654960a63..b60b004ce 100644 --- a/test/cli/cast.test.ts +++ b/test/cli/cast.test.ts @@ -278,9 +278,12 @@ describe('squad cast', () => { '', ].join('\n'); - async function scaffoldInitShape(teamMd: string): Promise { + async function scaffoldInitShape( + teamMd: string, + builtins: string[] = ['scribe', 'ralph', 'rai', 'fact-checker'], + ): Promise { const sq = join(TEST_ROOT, '.squad'); - for (const id of ['scribe', 'ralph', 'rai', 'fact-checker']) { + for (const id of builtins) { await mkdir(join(sq, 'agents', id), { recursive: true }); await writeFile(join(sq, 'agents', id, 'charter.md'), `# ${id}\n`); } @@ -310,19 +313,51 @@ describe('squad cast', () => { expect(members).not.toContain('Scribe'); }); - it('leaves a roster that already lists the built-ins under ## Members alone', async () => { - const withBuiltins = INIT_TEAM_MD.replace( - '|------|------|---------|--------|\n', - '|------|------|---------|--------|\n| Scribe | Decision Merger | `.squad/agents/scribe/charter.md` | 📋 Silent |\n', + it('leaves a roster that already lists every built-in under ## Members alone', async () => { + const allRows = [ + '| Scribe | Decision Merger | `.squad/agents/scribe/charter.md` | 📋 Silent |', + '| Ralph | Work Monitor | `.squad/agents/ralph/charter.md` | 🔄 Monitor |', + '| Rai | RAI Reviewer | `.squad/agents/rai/charter.md` | 🛡️ RAI |', + '| Fact Checker | Fact Checker | `.squad/agents/fact-checker/charter.md` | 🔍 Verifier |', + ].join('\n'); + const sq = await scaffoldInitShape( + INIT_TEAM_MD.replace('|------|------|---------|--------|\n', `|------|------|---------|--------|\n${allRows}\n`), ); - const sq = await scaffoldInitShape(withBuiltins); vi.spyOn(console, 'log').mockImplementation(() => {}); const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); await runCastAdd(TEST_ROOT, { name: 'Penny', role: 'Lead' }); const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); expect(teamMd).not.toContain('## Built-in Support Agents'); - expect(teamMd.split('| Scribe |').length).toBe(2); + for (const name of ['Scribe', 'Ralph', 'Rai', 'Fact Checker']) { + expect(teamMd.split(`| ${name} |`).length).toBe(2); + } + }); + + it('adds only the built-ins not already listed, even when Scribe is absent', async () => { + // A legacy roster that lists Ralph (with no charter link) but not Scribe. + const sq = await scaffoldInitShape( + INIT_TEAM_MD.replace('|------|------|---------|--------|\n', '|------|------|---------|--------|\n| Ralph | Work Monitor | — | 🔄 Monitor |\n'), + ); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); + await runCastAdd(TEST_ROOT, { name: 'Penny', role: 'Lead' }); + + const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); + expect(teamMd.split('| Ralph |').length).toBe(2); + const support = teamMd.slice(teamMd.indexOf('## Built-in Support Agents')); + for (const name of ['Scribe', 'Rai', 'Fact Checker']) expect(support).toContain(`| ${name} |`); + }); + + it('adds rows only for built-ins whose charter exists', async () => { + const sq = await scaffoldInitShape(INIT_TEAM_MD, ['scribe']); + vi.spyOn(console, 'log').mockImplementation(() => {}); + const { runCastAdd } = await import('@bradygaster/squad-cli/commands/cast'); + await runCastAdd(TEST_ROOT, { name: 'Penny', role: 'Lead' }); + + const teamMd = await readFile(join(sq, 'team.md'), 'utf-8'); + expect(teamMd).toContain('| Scribe |'); + for (const name of ['Ralph', 'Rai', 'Fact Checker']) expect(teamMd).not.toContain(`| ${name} |`); }); });