From 318388665a58cfa460f2b4e6586dbf9a014ae434 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 11 Nov 2026 20:41:24 -0800 Subject: [PATCH 1/2] fix(claude): refresh members after routing; clearer health dirs; no retired logs (#2456, #2455, #2454) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - #2456: `squad client sync` re-projects the configured hosts. Init Mode runs it once routing.md is written, so Claude member subagent descriptions carry "Owns: …" from routing instead of the role alone. - #2455: health metadata (squad_state_health, squad health --json) adds resolvedTeamRoot and resolvedSquadDir; resolvedTeamDir keeps its value (the team root) for squad-state-health/v1 consumers. - #2454: the coordinator digest no longer asks Scribe for session and orchestration logs, matching Scribe's charter and the Copilot coordinator; the parity test pins the new rule. Co-Authored-By: Claude Opus 5.5 --- .changeset/claude-polish.md | 10 +++++++ CHANGELOG.md | 3 +++ docs/src/content/docs/reference/cli.md | 2 +- .../scenarios/using-squad-across-clients.md | 6 +++++ packages/squad-cli/src/cli-entry.ts | 2 +- packages/squad-cli/src/cli/commands/client.ts | 26 ++++++++++++++++++- packages/squad-cli/src/cli/commands/health.ts | 7 +++++ .../squad-cli/src/cli/core/command-help.ts | 8 +++--- .../src/client/adapters/coordinator.ts | 4 +-- packages/squad-sdk/src/tools/index.ts | 6 +++++ plugins/squad/agents/squad.md | 2 +- .../squad-coordinator-init-mode/SKILL.md | 2 +- test/claude-members.test.ts | 26 +++++++++++++++++++ test/cli/state-mcp.test.ts | 2 ++ test/clients.test.ts | 3 ++- 15 files changed, 98 insertions(+), 11 deletions(-) create mode 100644 .changeset/claude-polish.md diff --git a/.changeset/claude-polish.md b/.changeset/claude-polish.md new file mode 100644 index 000000000..4890a0fdd --- /dev/null +++ b/.changeset/claude-polish.md @@ -0,0 +1,10 @@ +--- +"@bradygaster/squad-sdk": patch +"@bradygaster/squad-cli": patch +--- + +Claude Code follow-ups from the end-to-end test: + +- New `squad client sync` refreshes the configured hosts' files. Init Mode now runs it after writing `routing.md`, so Claude Code member subagent descriptions say what each member owns instead of repeating the role (#2456). +- `squad_state_health` and `squad health --json` add `resolvedTeamRoot` (the directory that contains `.squad`) and `resolvedSquadDir` (the squad directory itself). `resolvedTeamDir` keeps its value, the team root, for existing consumers (#2455). +- The Claude coordinator no longer asks Scribe for session or orchestration logs, which Scribe's charter and the Copilot coordinator retired (#2454). diff --git a/CHANGELOG.md b/CHANGELOG.md index 80e402e4b..34861cf94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,9 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o - The Claude coordinator names Claude Code's `Agent` subagent tool (formerly `Task`). The Claude Code spec, docs and host feature matrix now match the code, and host-projection regression guards keep them that way (#2440, #2445). - Every generated Claude Markdown file states its projection version. Files from earlier projections are still recognised as Squad's and upgraded in place, and rolling back the `CLAUDE.md`, `AGENTS.md` and `GEMINI.md` blocks restores the original bytes exactly (#2450). +- New `squad client sync` refreshes the configured hosts' files without a full upgrade. Init Mode runs it after writing `routing.md`, so each Claude Code member subagent's description names what the member owns instead of repeating its role (#2456). +- `squad_state_health` and `squad health --json` add `resolvedTeamRoot` (the directory that contains `.squad`) and `resolvedSquadDir` (the squad directory itself). `resolvedTeamDir` keeps its value, the team root, for existing consumers (#2455). +- The Claude coordinator no longer asks Scribe for session or orchestration logs, matching Scribe's charter and the Copilot coordinator (#2454). - Copilot output, `.github/agents/squad.agent.md` and the projections for other hosts are unchanged. ## [2.0.0-preview.4] - 2026-11-09 diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index 041c0d0c2..3169afd37 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/docs/src/content/docs/reference/cli.md @@ -84,7 +84,7 @@ prerequisites, all supported methods, and update commands. | `squad state-mcp [--experimental-backend]` | Run the `squad_state` stdio MCP server; pass `--experimental-backend` (or `SQUAD_EXPERIMENTAL_BACKEND=1`) to also expose the 11 experimental `squad_backend_*` conversation tools (transcript/event-log only until a harness is registered) | Yes | | `squad --version` | Print installed version | No | -`squad health --json` preserves the `squad-health/v1` schema and includes `metadata` fields for `cliVersion`, `sdkVersion`, `stateBackend`, `resolvedTeamDir`, `bridgeVersion`, and `launchMode`. Human-readable output is unchanged. +`squad health --json` preserves the `squad-health/v1` schema and includes `metadata` fields for `cliVersion`, `sdkVersion`, `stateBackend`, `resolvedTeamRoot` (the directory that contains `.squad`), `resolvedSquadDir` (the squad directory itself), `bridgeVersion`, and `launchMode`. `resolvedTeamDir` is kept for existing consumers and holds the same value as `resolvedTeamRoot`; despite its name, it is not the squad directory. Human-readable output is unchanged. The `squad_state_health` MCP tool includes the same fields in a JSON `Health metadata` line while retaining its existing state and storage lines. diff --git a/docs/src/content/docs/scenarios/using-squad-across-clients.md b/docs/src/content/docs/scenarios/using-squad-across-clients.md index fbd11151b..378261f20 100644 --- a/docs/src/content/docs/scenarios/using-squad-across-clients.md +++ b/docs/src/content/docs/scenarios/using-squad-across-clients.md @@ -28,6 +28,12 @@ For an existing repo: npx squad upgrade --client copilot,claude,cursor ``` +To refresh the configured hosts' files without a full upgrade, for example after you edit `.squad/routing.md` (Claude Code member subagent descriptions are built from it): + +```bash +npx squad client sync +``` + ## What each adapter generates | Client (`ClientId`) | Generated files | diff --git a/packages/squad-cli/src/cli-entry.ts b/packages/squad-cli/src/cli-entry.ts index d99515f7e..4e058855a 100644 --- a/packages/squad-cli/src/cli-entry.ts +++ b/packages/squad-cli/src/cli-entry.ts @@ -181,7 +181,7 @@ async function main(): Promise { console.log(` --insider (with --self: force the insider channel)`); console.log(` --force (with --self: allow a downgrade)`); console.log(` ${BOLD}client${RESET} Manage client host projections (Copilot, Claude, Kiro, …)`); - console.log(` Usage: client list [--json] | client add [--dry-run]`); + console.log(` Usage: client list [--json] | client add | client sync`); console.log(` ${BOLD}roster${RESET} Explicitly opt optional built-ins into team.md`); console.log(` Usage: roster add|remove [--dry-run]`); console.log(` ${BOLD}update-check${RESET} Report cached CLI update status (for tooling/CI)`); diff --git a/packages/squad-cli/src/cli/commands/client.ts b/packages/squad-cli/src/cli/commands/client.ts index 0a4ec240e..ef302c424 100644 --- a/packages/squad-cli/src/cli/commands/client.ts +++ b/packages/squad-cli/src/cli/commands/client.ts @@ -154,6 +154,30 @@ export async function runClientCommand(dest: string, args: string[]): Promise [--dry-run]`); + if (sub === 'sync') { + // Re-project the configured hosts, e.g. after routing.md changes (#2456): Claude member + // subagent descriptions are built from it. Only Squad-managed files are rewritten. + try { + const squadDir = detectSquadDir(dest).path; + const synced = await syncClients(dest, squadDir, { dryRun, warn: (m) => console.warn(m) }); + if (synced.clients.length === 0) { + console.log('No client hosts configured in .squad/config.json; nothing to sync. Add one with: squad client add '); + return 0; + } + if (dryRun) { + console.log(`Would refresh client host files for: ${synced.clients.join(', ')} (nothing written: --dry-run)`); + return 0; + } + reportClientResults(synced.results); + const failed = synced.results.some((r) => r.action === 'error'); + console.log(`${failed ? '⚠' : `${GREEN}✓${RESET}`} clients synced: ${synced.clients.join(', ')}`); + return failed ? 1 : 0; + } catch (err) { + console.error(`❌ ${err instanceof Error ? err.message : String(err)}`); + return 1; + } + } + + console.error(`❌ Unknown client subcommand: ${sub}\n Usage: squad client list [--json] | squad client add [--dry-run] | squad client sync [--dry-run]`); return 1; } diff --git a/packages/squad-cli/src/cli/commands/health.ts b/packages/squad-cli/src/cli/commands/health.ts index bcb60ed61..68eaac75c 100644 --- a/packages/squad-cli/src/cli/commands/health.ts +++ b/packages/squad-cli/src/cli/commands/health.ts @@ -49,7 +49,12 @@ export interface HealthReport { cliVersion: string; sdkVersion: string; stateBackend: string; + /** The team root (the directory that contains `.squad`), despite its name; kept for v1 consumers (#2455). */ resolvedTeamDir: string | null; + /** The team root: the directory that contains the squad directory. */ + resolvedTeamRoot: string | null; + /** The squad directory itself (`.squad`, or a flat externalized team directory). */ + resolvedSquadDir: string | null; bridgeVersion: string; launchMode: 'cli'; }; @@ -642,6 +647,8 @@ function healthMetadata( sdkVersion: SDK_VERSION, stateBackend, resolvedTeamDir: stateDir ? resolvedTeamDirectory(stateDir) : null, + resolvedTeamRoot: stateDir ? resolvedTeamDirectory(stateDir) : null, + resolvedSquadDir: stateDir ? path.resolve(stateDir) : null, bridgeVersion: cliVersion, launchMode: 'cli', }; diff --git a/packages/squad-cli/src/cli/core/command-help.ts b/packages/squad-cli/src/cli/core/command-help.ts index b7ea1b14c..36181b5cb 100644 --- a/packages/squad-cli/src/cli/core/command-help.ts +++ b/packages/squad-cli/src/cli/core/command-help.ts @@ -73,14 +73,16 @@ const COMMAND_HELP: Record = { client: (version) => { header('client', version, 'Manage client host projections'); console.log(`Usage: squad client list [--json]`); - console.log(` squad client add [--dry-run]\n`); + console.log(` squad client add [--dry-run]`); + console.log(` squad client sync [--dry-run]\n`); console.log(`Lists the hosts configured in .squad/config.json (clients[]) and whether their`); console.log(`projected files exist. An empty clients[] means only the default GitHub Copilot`); - console.log(`host (.github/agents/squad.agent.md + .mcp.json) is projected.\n`); + console.log(`host (.github/agents/squad.agent.md + .mcp.json) is projected. sync refreshes the`); + console.log(`configured hosts' files, e.g. Claude member subagents after routing.md changes.\n`); console.log(`Hosts: copilot, claude, kiro, opencode, cursor, codex, antigravity, or "all".\n`); console.log(`Options:`); console.log(` ${BOLD}--json${RESET} Emit structured JSON instead of text`); - console.log(` ${BOLD}--dry-run${RESET} With add: show what would be projected, write nothing\n`); + console.log(` ${BOLD}--dry-run${RESET} With add or sync: show what would be projected, write nothing\n`); }, roster: (version) => { diff --git a/packages/squad-sdk/src/client/adapters/coordinator.ts b/packages/squad-sdk/src/client/adapters/coordinator.ts index c859a89ed..486fc2795 100644 --- a/packages/squad-sdk/src/client/adapters/coordinator.ts +++ b/packages/squad-sdk/src/client/adapters/coordinator.ts @@ -112,7 +112,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep 0. **Init Mode (only when there is truly no team).** Decide this with \`squad_state_read\` of \`team.md\` (or \`squad_state_list\`), NEVER with glob/grep/search tools: many hosts' glob/grep skip dot-directories like \`${S}/\` and will wrongly report "no matches". If \`team.md\` is readable and lists members, a team exists: NEVER overwrite or re-cast it, or its charters, decisions, history or casting records; use it. Only if \`team.md\` does not exist or has an empty roster: - **Phase 1 (propose).** Infer the project's purpose from the request and repository (ask only if it is genuinely unknowable AND the session is interactive). Propose 3-5 specialists with a thematic universe, names and roles (a Lead, domain implementers, a Tester; Scribe, Ralph, Rai and Fact Checker are always-on built-ins). - **Auto-confirm (default).** Do NOT stop to ask questions in Init Mode. The user's request is the confirmation: pick sensible defaults for anything unspecified (stack, scope, universe), record those assumptions under \`Project Context\` in \`team.md\`, and continue to Phase 2 in the SAME turn. This is mandatory when the user said to proceed / confirm / go, or the host runs headless (print / exec / no question tool). Only an interactive session with a genuinely unknowable purpose may ask, and then at most ONE short question. Never end the turn with only a proposal or questions. - - **Phase 2 (create).** If you can run shell commands, add EVERY member with the CLI, one call each: \`npx squad cast --name --role ""\` (it writes the charter, history, the \`team.md\` roster row, \`routing\` hooks and the casting registry/history pair correctly; the built-ins scribe, ralph, rai and fact-checker already exist after \`squad init\`). Then write/adjust \`${S}/routing.md\` as an ordinary file. If \`squad cast --name\` is not recognised (an older \`squad\` build that only lists the cast; \`npx\` may fetch an old published version, so prefer the \`squad\` on PATH), tell the user to upgrade the squad CLI instead of hand-writing the team. NEVER hand-write or edit anything under \`${S}/casting/\` (\`registry.json\`, \`history.json\`, \`registry-history.commit.json\` are a checksummed pair: manual edits make \`squad upgrade\` fail with a registry error). If you cannot run shell commands, write \`team.md\` (a markdown table with \`Name\`, \`Role\`, \`Charter\`, \`Status\` columns; the Coordinator row stays separate), \`${S}/agents//charter.md\` and \`history.md\` as ordinary files, leave \`${S}/casting/\` untouched and tell the user to run \`squad cast --name --role ""\` for each member to register them. + - **Phase 2 (create).** If you can run shell commands, add EVERY member with the CLI, one call each: \`npx squad cast --name --role ""\` (it writes the charter, history, the \`team.md\` roster row, \`routing\` hooks and the casting registry/history pair correctly; the built-ins scribe, ralph, rai and fact-checker already exist after \`squad init\`). Then write/adjust \`${S}/routing.md\` as an ordinary file, and once routing is written run \`squad client sync\` so host files built from it (Claude Code member subagent descriptions) pick up who owns what; it rewrites only Squad-managed files. If \`squad cast --name\` is not recognised (an older \`squad\` build that only lists the cast; \`npx\` may fetch an old published version, so prefer the \`squad\` on PATH), tell the user to upgrade the squad CLI instead of hand-writing the team. NEVER hand-write or edit anything under \`${S}/casting/\` (\`registry.json\`, \`history.json\`, \`registry-history.commit.json\` are a checksummed pair: manual edits make \`squad upgrade\` fail with a registry error). If you cannot run shell commands, write \`team.md\` (a markdown table with \`Name\`, \`Role\`, \`Charter\`, \`Status\` columns; the Coordinator row stays separate), \`${S}/agents//charter.md\` and \`history.md\` as ordinary files, leave \`${S}/casting/\` untouched and tell the user to run \`squad cast --name --role ""\` for each member to register them. - **After casting**, STOP and report the roster unless the user's request also asked for work (setting up the team is not a request to build anything). - **Scratch space.** Use \`${S}/scratch/\` (inside the workspace) for temporary files; never write outside the workspace directory (hosts reject external-directory access). 1. **Load team context first.** Read \`${S}/team.md\` (roster), \`${S}/routing.md\` (who owns what), \`${S}/decisions.md\` and the decisions inbox before routing anything. Cache them for the session; re-read only when a state change was announced. @@ -128,7 +128,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); **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\`). 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; append a session log to \`${S}/log/\` and an entry to \`${S}/orchestration-log/\`; archive old decisions only through the state tools/\`squad nap\`, never by hand-deleting history. Scribe never commits mutable state. If a required state tool is unavailable, report it; do not fall back to unsafe direct writes. +11. **Scribe spawn protocol and drop-box pattern.** Agents never write \`${S}/decisions.md\` directly: decisions go to \`${S}/decisions/inbox/\` (via \`squad_decide\`). 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. A reviewer returns APPROVE or REJECT with reasons. 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). 14. **Fact Checker (verification and devil's advocate).** Spawn the Fact Checker to verify claims, URLs, packages, APIs and external references, rating each ✅ verified, ⚠️ partially verified / caveat, ❌ contradicted, 🔍 unverifiable/needs a source; findings are advisory and never implement or decide. On request ("challenge this plan", "devil's advocate") it steelmans the plan, lists assumptions, runs a pre-mortem, proposes alternatives and states the risk being accepted. Audit trail: \`${S}/fact-checker/audit-trail.md\`. diff --git a/packages/squad-sdk/src/tools/index.ts b/packages/squad-sdk/src/tools/index.ts index 87c37dcef..463a2b477 100644 --- a/packages/squad-sdk/src/tools/index.ts +++ b/packages/squad-sdk/src/tools/index.ts @@ -957,7 +957,13 @@ export class ToolRegistry { cliVersion: this.cliVersion, sdkVersion: SQUAD_STATE_VERSION, stateBackend: this.backendName, + /** + * The team root (the directory that contains `.squad`), despite its name. Kept as is for + * `squad-state-health/v1` consumers; prefer `resolvedTeamRoot` / `resolvedSquadDir` (#2455). + */ resolvedTeamDir: resolvedTeamDirectory(this.squadRoot), + resolvedTeamRoot: resolvedTeamDirectory(this.squadRoot), + resolvedSquadDir: path.resolve(this.squadRoot), bridgeVersion: this.runtimeVersion, launchMode: this.launchMode, }; diff --git a/plugins/squad/agents/squad.md b/plugins/squad/agents/squad.md index 356d8ded3..e1f7caff4 100644 --- a/plugins/squad/agents/squad.md +++ b/plugins/squad/agents/squad.md @@ -26,7 +26,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); **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`). 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; append a session log to `.squad/log/` and an entry to `.squad/orchestration-log/`; archive old decisions only through the state tools/`squad nap`, never by hand-deleting history. Scribe never commits mutable state. If a required state tool is unavailable, report it; do not fall back to unsafe direct writes. +11. **Scribe spawn protocol and drop-box pattern.** Agents never write `.squad/decisions.md` directly: decisions go to `.squad/decisions/inbox/` (via `squad_decide`). 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. A reviewer returns APPROVE or REJECT with reasons. 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). 14. **Fact Checker (verification and devil's advocate).** Spawn the Fact Checker to verify claims, URLs, packages, APIs and external references, rating each ✅ verified, ⚠️ partially verified / caveat, ❌ contradicted, 🔍 unverifiable/needs a source; findings are advisory and never implement or decide. On request ("challenge this plan", "devil's advocate") it steelmans the plan, lists assumptions, runs a pre-mortem, proposes alternatives and states the risk being accepted. Audit trail: `.squad/fact-checker/audit-trail.md`. diff --git a/plugins/squad/skills/squad-coordinator-init-mode/SKILL.md b/plugins/squad/skills/squad-coordinator-init-mode/SKILL.md index 6bcfe586f..50e246675 100644 --- a/plugins/squad/skills/squad-coordinator-init-mode/SKILL.md +++ b/plugins/squad/skills/squad-coordinator-init-mode/SKILL.md @@ -11,6 +11,6 @@ This is the full text of core-protocol item 0 of the Squad coordinator, loaded o **Init Mode (only when there is truly no team).** Decide this with `squad_state_read` of `team.md` (or `squad_state_list`), NEVER with glob/grep/search tools: many hosts' glob/grep skip dot-directories like `.squad/` and will wrongly report "no matches". If `team.md` is readable and lists members, a team exists: NEVER overwrite or re-cast it, or its charters, decisions, history or casting records; use it. Only if `team.md` does not exist or has an empty roster: - **Phase 1 (propose).** Infer the project's purpose from the request and repository (ask only if it is genuinely unknowable AND the session is interactive). Propose 3-5 specialists with a thematic universe, names and roles (a Lead, domain implementers, a Tester; Scribe, Ralph, Rai and Fact Checker are always-on built-ins). - **Auto-confirm (default).** Do NOT stop to ask questions in Init Mode. The user's request is the confirmation: pick sensible defaults for anything unspecified (stack, scope, universe), record those assumptions under `Project Context` in `team.md`, and continue to Phase 2 in the SAME turn. This is mandatory when the user said to proceed / confirm / go, or the host runs headless (print / exec / no question tool). Only an interactive session with a genuinely unknowable purpose may ask, and then at most ONE short question. Never end the turn with only a proposal or questions. - - **Phase 2 (create).** If you can run shell commands, add EVERY member with the CLI, one call each: `npx squad cast --name --role ""` (it writes the charter, history, the `team.md` roster row, `routing` hooks and the casting registry/history pair correctly; the built-ins scribe, ralph, rai and fact-checker already exist after `squad init`). Then write/adjust `.squad/routing.md` as an ordinary file. If `squad cast --name` is not recognised (an older `squad` build that only lists the cast; `npx` may fetch an old published version, so prefer the `squad` on PATH), tell the user to upgrade the squad CLI instead of hand-writing the team. NEVER hand-write or edit anything under `.squad/casting/` (`registry.json`, `history.json`, `registry-history.commit.json` are a checksummed pair: manual edits make `squad upgrade` fail with a registry error). If you cannot run shell commands, write `team.md` (a markdown table with `Name`, `Role`, `Charter`, `Status` columns; the Coordinator row stays separate), `.squad/agents//charter.md` and `history.md` as ordinary files, leave `.squad/casting/` untouched and tell the user to run `squad cast --name --role ""` for each member to register them. + - **Phase 2 (create).** If you can run shell commands, add EVERY member with the CLI, one call each: `npx squad cast --name --role ""` (it writes the charter, history, the `team.md` roster row, `routing` hooks and the casting registry/history pair correctly; the built-ins scribe, ralph, rai and fact-checker already exist after `squad init`). Then write/adjust `.squad/routing.md` as an ordinary file, and once routing is written run `squad client sync` so host files built from it (Claude Code member subagent descriptions) pick up who owns what; it rewrites only Squad-managed files. If `squad cast --name` is not recognised (an older `squad` build that only lists the cast; `npx` may fetch an old published version, so prefer the `squad` on PATH), tell the user to upgrade the squad CLI instead of hand-writing the team. NEVER hand-write or edit anything under `.squad/casting/` (`registry.json`, `history.json`, `registry-history.commit.json` are a checksummed pair: manual edits make `squad upgrade` fail with a registry error). If you cannot run shell commands, write `team.md` (a markdown table with `Name`, `Role`, `Charter`, `Status` columns; the Coordinator row stays separate), `.squad/agents//charter.md` and `history.md` as ordinary files, leave `.squad/casting/` untouched and tell the user to run `squad cast --name --role ""` for each member to register them. - **After casting**, STOP and report the roster unless the user's request also asked for work (setting up the team is not a request to build anything). - **Scratch space.** Use `.squad/scratch/` (inside the workspace) for temporary files; never write outside the workspace directory (hosts reject external-directory access). diff --git a/test/claude-members.test.ts b/test/claude-members.test.ts index 10c016baf..37fa53b4c 100644 --- a/test/claude-members.test.ts +++ b/test/claude-members.test.ts @@ -222,6 +222,32 @@ describe('CLI: squad upgrade --client claude and squad cast write member subagen expect(fs.readFileSync(path.join(root, '.claude/agents/dallas.md'), 'utf8')).toMatch(/^---\nname: dallas\n/); }, 60_000); + it('squad client sync picks up routing written after casting (#2456)', async () => { + const { runInit } = await import('../packages/squad-cli/src/cli/core/init.js'); + const { runCastAdd } = await import('../packages/squad-cli/src/cli/commands/cast.js'); + const { runClientCommand } = await import('../packages/squad-cli/src/cli/commands/client.js'); + await runInit(root, { clients: ['claude'], includeWorkflows: false, includeVscodeDefault: false }); + await runCastAdd(root, { name: 'Dallas', role: 'Backend Dev' }); + const member = path.join(root, '.claude/agents/dallas.md'); + expect(fs.readFileSync(member, 'utf8')).not.toContain('Payments API'); + + // Init Mode writes routing.md after casting, as an ordinary file. + const routing = path.join(root, '.squad/routing.md'); + fs.writeFileSync(routing, `${fs.readFileSync(routing, 'utf8')}\n| Work Type | Route To | Examples |\n|---|---|---|\n| Payments API | Dallas | refunds |\n`); + expect(await runClientCommand(root, ['sync', '--dry-run'])).toBe(0); + expect(fs.readFileSync(member, 'utf8')).not.toContain('Payments API'); + expect(await runClientCommand(root, ['sync'])).toBe(0); + expect(fs.readFileSync(member, 'utf8')).toMatch(/^description: ".*Owns: [^"]*Payments API/m); + }, 60_000); + + it('squad client sync with no configured host writes nothing (#2456)', async () => { + const { runInit } = await import('../packages/squad-cli/src/cli/core/init.js'); + const { runClientCommand } = await import('../packages/squad-cli/src/cli/commands/client.js'); + await runInit(root, { includeWorkflows: false, includeVscodeDefault: false }); + expect(await runClientCommand(root, ['sync'])).toBe(0); + expect(fs.existsSync(path.join(root, '.claude'))).toBe(false); + }, 60_000); + it('squad cast writes nothing under .claude when claude is not configured', async () => { const { runInit } = await import('../packages/squad-cli/src/cli/core/init.js'); const { runCastAdd } = await import('../packages/squad-cli/src/cli/commands/cast.js'); diff --git a/test/cli/state-mcp.test.ts b/test/cli/state-mcp.test.ts index beb8117b6..8ef8adf54 100644 --- a/test/cli/state-mcp.test.ts +++ b/test/cli/state-mcp.test.ts @@ -122,6 +122,8 @@ describe('state-mcp bridge', () => { sdkVersion, stateBackend: 'two-layer', resolvedTeamDir: TMP, + resolvedTeamRoot: TMP, + resolvedSquadDir: join(TMP, '.squad'), bridgeVersion: version, launchMode: 'stdio', }); diff --git a/test/clients.test.ts b/test/clients.test.ts index 0c920a316..d3419a47a 100644 --- a/test/clients.test.ts +++ b/test/clients.test.ts @@ -247,7 +247,8 @@ describe('coordinator Ralph mode', () => { describe('coordinator behavioral-contract parity', () => { const sections: Array<[string, RegExp[]]> = [ ['Response Mode', [/Response Mode Selection/, /\*\*Direct\*\*/, /\*\*Lightweight\*\*/, /\*\*Standard\*\*/, /\*\*Full\*\*/]], - ['Scribe', [/Scribe spawn protocol and drop-box/, /decisions\/inbox\//, /orchestration-log\//, /\/log\//, /squad_state_health/]], + // Session and orchestration logs are retired, as in the Copilot coordinator and Scribe's charter (#2454). + ['Scribe', [/Scribe spawn protocol and drop-box/, /decisions\/inbox\//, /neither Scribe nor you writes session logs or orchestration logs/, /squad_state_health/]], ['Reviewer Rejection', [/Reviewer rejection protocol and strict lockout/, /locked out/, /may not self-revise/]], ['Rai', [/Rai \(RAI Reviewer\)/, /🟢 Green/, /🟡 Yellow/, /🔴 Red/, /blocks shipping/]], ['Fact Checker', [/Fact Checker \(verification and devil's advocate\)/, /✅/, /⚠️/, /❌/, /🔍/, /steelmans/, /pre-mortem/]], From 9dd78d3845c19be339c77f921d033672fb74bb58 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Wed, 11 Nov 2026 20:44:51 -0800 Subject: [PATCH 2/2] docs(claude): skill frontmatter for the plugin; explain the Copilot base files (#2458) - cli-wiring and retro-enforcement get name/description frontmatter in .squad-templates and their two package mirrors (templates/, whose other files have drifted, gets these two only). `claude plugin validate plugins/squad` now passes with no warnings. - client-compatibility.md says why `squad init --client claude` also writes the GitHub Copilot files: Copilot is the base host and .github/agents/squad.agent.md the canonical coordinator (ADR-003 proposes otherwise), with --no-workflows / --no-vscode-default to skip the optional parts. Co-Authored-By: Claude Opus 5.5 --- .squad-templates/skills/cli-wiring/SKILL.md | 8 ++++++++ .squad-templates/skills/retro-enforcement/SKILL.md | 8 ++++++++ docs/src/content/docs/scenarios/client-compatibility.md | 2 ++ packages/squad-cli/templates/skills/cli-wiring/SKILL.md | 8 ++++++++ .../squad-cli/templates/skills/retro-enforcement/SKILL.md | 8 ++++++++ packages/squad-sdk/templates/skills/cli-wiring/SKILL.md | 8 ++++++++ .../squad-sdk/templates/skills/retro-enforcement/SKILL.md | 8 ++++++++ plugins/squad/skills/cli-wiring/SKILL.md | 7 +++++++ plugins/squad/skills/retro-enforcement/SKILL.md | 7 +++++++ templates/skills/cli-wiring/SKILL.md | 8 ++++++++ templates/skills/retro-enforcement/SKILL.md | 8 ++++++++ 11 files changed, 80 insertions(+) diff --git a/.squad-templates/skills/cli-wiring/SKILL.md b/.squad-templates/skills/cli-wiring/SKILL.md index 5b315b02d..15a38c7f3 100644 --- a/.squad-templates/skills/cli-wiring/SKILL.md +++ b/.squad-templates/skills/cli-wiring/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "cli-wiring" +description: "Checklist for wiring a new Squad CLI command: route it in cli-entry.ts, add help text, and test that it is reachable" +domain: "cli" +confidence: "high" +source: "team-decision" +--- + # Skill: CLI Command Wiring **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. diff --git a/.squad-templates/skills/retro-enforcement/SKILL.md b/.squad-templates/skills/retro-enforcement/SKILL.md index e7d319276..76979cea8 100644 --- a/.squad-templates/skills/retro-enforcement/SKILL.md +++ b/.squad-templates/skills/retro-enforcement/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "retro-enforcement" +description: "Keep retrospectives on schedule and track their action items as GitHub Issues, not markdown checklists" +domain: "process" +confidence: "high" +source: "team-decision" +--- + # Skill: Retro Enforcement ## Purpose diff --git a/docs/src/content/docs/scenarios/client-compatibility.md b/docs/src/content/docs/scenarios/client-compatibility.md index 8355d7440..0e9b26443 100644 --- a/docs/src/content/docs/scenarios/client-compatibility.md +++ b/docs/src/content/docs/scenarios/client-compatibility.md @@ -200,6 +200,8 @@ Squad runs on VS Code with **conditional support**. Key differences from CLI: - `.gitignore` — `.claude/worktrees/` under a `# squad:claude` comment - `.claude/settings.json` — Squad's governance hooks, only if you opt in (see below). Your other settings and hooks are kept. +`squad init --client claude` also writes the GitHub Copilot files: `.github/agents/squad.agent.md`, `.github/skills/`, `.copilot/mcp-config.json`, the Squad workflows under `.github/workflows/` and `.vscode/settings.json`. This is intended. GitHub Copilot is the base host, and `.github/agents/squad.agent.md` is the canonical coordinator that the other hosts' coordinators are checked against ([ADR-003](https://github.com/github/squad/blob/dev/docs/specification/adr-003-host-neutral-canonical-coordinator.md) proposes a host-neutral source instead). Skip the workflows with `--no-workflows` and the VS Code setting with `--no-vscode-default`. + ### Starting a session ```bash diff --git a/packages/squad-cli/templates/skills/cli-wiring/SKILL.md b/packages/squad-cli/templates/skills/cli-wiring/SKILL.md index 5b315b02d..15a38c7f3 100644 --- a/packages/squad-cli/templates/skills/cli-wiring/SKILL.md +++ b/packages/squad-cli/templates/skills/cli-wiring/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "cli-wiring" +description: "Checklist for wiring a new Squad CLI command: route it in cli-entry.ts, add help text, and test that it is reachable" +domain: "cli" +confidence: "high" +source: "team-decision" +--- + # Skill: CLI Command Wiring **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. diff --git a/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md b/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md index e7d319276..76979cea8 100644 --- a/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md +++ b/packages/squad-cli/templates/skills/retro-enforcement/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "retro-enforcement" +description: "Keep retrospectives on schedule and track their action items as GitHub Issues, not markdown checklists" +domain: "process" +confidence: "high" +source: "team-decision" +--- + # Skill: Retro Enforcement ## Purpose diff --git a/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md b/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md index 5b315b02d..15a38c7f3 100644 --- a/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md +++ b/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "cli-wiring" +description: "Checklist for wiring a new Squad CLI command: route it in cli-entry.ts, add help text, and test that it is reachable" +domain: "cli" +confidence: "high" +source: "team-decision" +--- + # Skill: CLI Command Wiring **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. diff --git a/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md b/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md index e7d319276..76979cea8 100644 --- a/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md +++ b/packages/squad-sdk/templates/skills/retro-enforcement/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "retro-enforcement" +description: "Keep retrospectives on schedule and track their action items as GitHub Issues, not markdown checklists" +domain: "process" +confidence: "high" +source: "team-decision" +--- + # Skill: Retro Enforcement ## Purpose diff --git a/plugins/squad/skills/cli-wiring/SKILL.md b/plugins/squad/skills/cli-wiring/SKILL.md index 3331308a8..82a7f2995 100644 --- a/plugins/squad/skills/cli-wiring/SKILL.md +++ b/plugins/squad/skills/cli-wiring/SKILL.md @@ -1,3 +1,10 @@ +--- +name: "cli-wiring" +description: "Checklist for wiring a new Squad CLI command: route it in cli-entry.ts, add help text, and test that it is reachable" +domain: "cli" +confidence: "high" +source: "team-decision" +--- # Skill: CLI Command Wiring diff --git a/plugins/squad/skills/retro-enforcement/SKILL.md b/plugins/squad/skills/retro-enforcement/SKILL.md index 636891d3d..64e4ce758 100644 --- a/plugins/squad/skills/retro-enforcement/SKILL.md +++ b/plugins/squad/skills/retro-enforcement/SKILL.md @@ -1,3 +1,10 @@ +--- +name: "retro-enforcement" +description: "Keep retrospectives on schedule and track their action items as GitHub Issues, not markdown checklists" +domain: "process" +confidence: "high" +source: "team-decision" +--- # Skill: Retro Enforcement diff --git a/templates/skills/cli-wiring/SKILL.md b/templates/skills/cli-wiring/SKILL.md index 5b315b02d..15a38c7f3 100644 --- a/templates/skills/cli-wiring/SKILL.md +++ b/templates/skills/cli-wiring/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "cli-wiring" +description: "Checklist for wiring a new Squad CLI command: route it in cli-entry.ts, add help text, and test that it is reachable" +domain: "cli" +confidence: "high" +source: "team-decision" +--- + # Skill: CLI Command Wiring **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. diff --git a/templates/skills/retro-enforcement/SKILL.md b/templates/skills/retro-enforcement/SKILL.md index e7d319276..76979cea8 100644 --- a/templates/skills/retro-enforcement/SKILL.md +++ b/templates/skills/retro-enforcement/SKILL.md @@ -1,3 +1,11 @@ +--- +name: "retro-enforcement" +description: "Keep retrospectives on schedule and track their action items as GitHub Issues, not markdown checklists" +domain: "process" +confidence: "high" +source: "team-decision" +--- + # Skill: Retro Enforcement ## Purpose