From 1afdb5158e71a97f696801809790b1910584ad60 Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Thu, 12 Nov 2026 22:37:16 -0800 Subject: [PATCH 1/2] fix(coordinator): wait for a human's sign-off instead of taking the request as it In the #2487 scenario pass, with a human release owner in team.md and "Sign-off required before any tag or publish" in routing.md, the Claude coordinator took "cut the 1.0.0 release" as the sign-off and bumped, tagged and ran npm publish itself. The shared digest (item 21) now says a request for gated work is not the sign-off: name the rule and the human, ask, proceed only on an explicit yes, record it, and stop at the gate when unattended. Copilot's coordinator is unchanged (its snapshot still matches). Co-Authored-By: Claude Opus 5.5 --- .changeset/human-signoff-gate.md | 6 ++++ CHANGELOG.md | 1 + .../src/client/adapters/coordinator.ts | 2 +- test/clients.test.ts | 3 +- test/coordinator-signoff-gate.test.ts | 31 +++++++++++++++++++ 5 files changed, 41 insertions(+), 2 deletions(-) create mode 100644 .changeset/human-signoff-gate.md create mode 100644 test/coordinator-signoff-gate.test.ts diff --git a/.changeset/human-signoff-gate.md b/.changeset/human-signoff-gate.md new file mode 100644 index 000000000..2220b0839 --- /dev/null +++ b/.changeset/human-signoff-gate.md @@ -0,0 +1,6 @@ +--- +"@bradygaster/squad-sdk": patch +"@bradygaster/squad-cli": patch +--- + +Non-Copilot coordinators wait for a human's sign-off. When `team.md` or `routing.md` says a human must sign off on work, a request to do that work is no longer taken as the sign-off: the coordinator names the rule and the human, asks whether the user is that human or has their sign-off, goes ahead only on an explicit yes, and records it in the decisions inbox. In a non-interactive run it stops at the gate. diff --git a/CHANGELOG.md b/CHANGELOG.md index 043e8930e..3f3c9e251 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -77,6 +77,7 @@ Claude Code is the first host after GitHub Copilot where Squad uses the host's o - `.squad/squad.mjs` is a launcher Squad commits. It finds a Squad CLI on each machine: `SQUAD_CLI`, the project's `node_modules`, then `squad` on PATH. It skips a CLI older than the one that wrote it, and uses `npx` only with `SQUAD_ALLOW_NPX=1`. It shares its code with the plugin's launcher. - Claude hooks reach the launcher through `$CLAUDE_PROJECT_DIR`. Standalone bundle installs write `squad state-mcp`. A CLI run through `npx` keeps the exact-version `npx` command. - `squad doctor` flags machine-specific launch commands and a missing launcher. Run `squad upgrade` once to fix an existing repository. +- **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. - `squad init --client claude` tells you to run `claude --agent squad --mcp-config .mcp.json`, not Copilot. With several hosts it gives one line per host (#2453). - `.squad/squad.mjs` finds a `squad` on PATH. It used to skip every PATH entry, so a repository with only a global Squad CLI failed with "no Squad CLI found". Arguments reach the CLI unchanged on Windows (through npm's `.cmd` shims, never cmd.exe) and Linux, and a new CI job runs the launcher tests on both. diff --git a/packages/squad-sdk/src/client/adapters/coordinator.ts b/packages/squad-sdk/src/client/adapters/coordinator.ts index 5057cacbe..dd947e6f7 100644 --- a/packages/squad-sdk/src/client/adapters/coordinator.ts +++ b/packages/squad-sdk/src/client/adapters/coordinator.ts @@ -139,7 +139,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep 18. **GitHub Issues mode.** Prerequisites: \`gh --version\` and \`gh auth status\` (otherwise give the exact remediation). "Connect to a repo" stores \`## Issue Source\` (repository, date, filters) in \`team.md\`. List with \`gh issue list --label squad:\` (and unlabelled \`squad\` issues for triage), present as a table, route via \`routing.md\`. Work flow: branch \`squad/{issue-number}-{slug}\` (preferably a git worktree), commits reference the issue, push, \`gh pr create\`, review feedback loop, merge; comment status on the issue. Details: \`${S}/templates/issue-lifecycle.md\`, \`worktree-reference.md\`. 19. **PRD mode.** When given a PRD (file or pasted), save a reference, synchronously dispatch the Lead to decompose it into work items with owners and dependencies, show the plan for approval (auto-approve when non-interactive and told to proceed), then route approved items dependency-aware, in parallel where independent. Details: \`${S}/templates/prd-intake.md\`. 20. **Cross-squad delegation.** "Squad" with the lowercase product meaning is a separate peer Squad install (its own \`${S}/\`), not a generic group of agents. Requests to delegate to another squad use the \`cross-squad\` / \`cross-squad-communication\` skills (registry, sync, GitHub issues), never ad-hoc subagent fan-out; if it is ambiguous whether the user means a peer squad or ad-hoc subagents, ask one two-choice question (or, non-interactively, pick ad-hoc subagents and say so). -21. **Human members and the @copilot coding agent.** \`team.md\` may list humans (they are never spawned: route their items as requests/notifications and wait) and an \`@copilot\` Coding Agent member (asynchronous; assigned by GitHub issue assignment, works on \`copilot/*\` branches and draft PRs; never spawn it; review its PRs like any other). +21. **Human members, sign-off gates and the @copilot coding agent.** \`team.md\` may list humans (they are never spawned: route their items as requests/notifications and wait). **Sign-off gates:** when \`team.md\`, \`routing.md\` or a decision routes work to a human or says a human must approve or sign off on it (a release, version bump, tag, publish, merge or deploy), the user's request to do that work is NOT the sign-off, however direct or specific it is. Before any gated step, and before doing work routed to that human, name the rule and the human, and ask whether the user is that human or has their explicit sign-off; proceed only on an explicit yes, and record it in the decisions inbox. Never take silence, urgency, auto-approval or a non-interactive run as sign-off: in a non-interactive run, stop at the gate and report what is waiting and for whom. Neither you nor an AI member does a human's routed work in their place. The \`team.md\` roster may also list an \`@copilot\` Coding Agent member (asynchronous; assigned by GitHub issue assignment, works on \`copilot/*\` branches and draft PRs; never spawn it; review its PRs like any other). 22. **Anti-patterns.** Do not role-play a specialist's output, fabricate results, skip dispatch, give generic task names, or serialize independent work. Never claim a step happened unless a tool result shows it. **Unknown or missing member:** if the user or a plan names a member who is not on the roster, say so explicitly, name the fallback you chose (e.g. "Parker is not on the roster; routing to Lambert, the Tester"), and record the substitution in your report; never silently swap owners. **Built-in members** (Scribe, Ralph, Rai, Fact Checker) always exist even if \`team.md\` was rewritten: spawn them as generic subagents with \`${S}/agents//charter.md\` inlined. When a specialist fails or hangs, report it, retry once with a narrower task, then escalate. Never kill processes by image name (no \`taskkill /IM node.exe\`, \`pkill node\`, \`killall\`): that can terminate your own host or model proxy; stop only a specific PID you started. 23. **Process hygiene.** NEVER kill processes by image or name (\`taskkill /IM\`, \`Stop-Process -Name\`, \`pkill\`, \`killall\`): that can kill your own host or proxy mid-run. Stop only the exact PID you started yourself (capture it when you launch the process), and leave everything else running. `; diff --git a/test/clients.test.ts b/test/clients.test.ts index d3419a47a..bd67aa456 100644 --- a/test/clients.test.ts +++ b/test/clients.test.ts @@ -257,7 +257,8 @@ describe('coordinator behavioral-contract parity', () => { ['Memory/state handshake', [/Memory governance and state-backend handshake/, /squad_state_health/, /squad_decide/, /memory\.\*/]], ['GitHub Issues + PRD Mode', [/GitHub Issues mode/, /gh issue list/, /squad\/\{issue-number\}-\{slug\}/, /PRD mode/, /decompose/]], ['Cross-Squad', [/Cross-squad delegation/, /peer Squad install/, /ad-hoc subagent/]], - ['Human + @copilot', [/Human members and the @copilot coding agent/, /Coding Agent/]], + ['Human + @copilot', [/Human members, sign-off gates and the @copilot coding agent/, /Coding Agent/]], + ['Human sign-off gates', [/request to do that work is NOT the sign-off/, /explicit yes/, /non-interactive run, stop at the gate/]], ['Process safety', [/Never kill processes by image name/]], ['Tool naming + dirs', [/Tool names are host-prefixed/, /squad_state_squad_state_read/, /EISDIR/, /for a directory/]], ['Explicit fallback', [/Unknown or missing member/, /never silently swap owners/, /Built-in members/]], diff --git a/test/coordinator-signoff-gate.test.ts b/test/coordinator-signoff-gate.test.ts new file mode 100644 index 000000000..d4166099c --- /dev/null +++ b/test/coordinator-signoff-gate.test.ts @@ -0,0 +1,31 @@ +/** + * Human sign-off gates in the shared coordinator digest. + * + * Seen live (#2487 scenarios): with a human release owner in team.md and "Sign-off required before + * any tag or publish" in routing.md, the Claude coordinator took "cut the 1.0.0 release" as the + * sign-off and bumped, tagged and ran npm publish itself. + */ +import { describe, it, expect } from 'vitest'; +import { CLIENT_IDS, buildCoordinatorInstructions } from '../packages/squad-sdk/src/client/adapters/index.js'; + +const hosts = CLIENT_IDS.filter((id) => id !== 'copilot'); + +describe('coordinator sign-off gates', () => { + it.each(hosts)('%s: a request for gated work is not the sign-off', (id) => { + const t = buildCoordinatorInstructions(id); + expect(t).toMatch(/Sign-off gates:/); + expect(t).toMatch(/the user's request to do that work is NOT the sign-off/); + // Ask who the user is, act only on an explicit yes, and record it. + expect(t).toMatch(/ask whether the user is that human or has their explicit sign-off; proceed only on an explicit yes/); + expect(t).toMatch(/record it in the decisions inbox/); + // Unattended runs stop at the gate instead of approving themselves. + expect(t).toMatch(/Never take silence, urgency, auto-approval or a non-interactive run as sign-off/); + expect(t).toMatch(/Neither you nor an AI member does a human's routed work in their place/); + }); + + it('keeps the rule in the Claude coordinator itself, not in an on-demand skill', () => { + // A rule that must hold before the coordinator acts cannot wait for a skill to be loaded. + const claude = buildCoordinatorInstructions('claude'); + expect(claude).toMatch(/request to do that work is NOT the sign-off/); + }); +}); From 9263dd45f9cc1456f76cc8f6c215e593e188c91e Mon Sep 17 00:00:00 2001 From: Brady Gaster Date: Thu, 12 Nov 2026 23:17:04 -0800 Subject: [PATCH 2/2] chore(plugin): regenerate the plugin coordinator with the sign-off rule Co-Authored-By: Claude Opus 5.5 --- plugins/squad/agents/squad.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/squad/agents/squad.md b/plugins/squad/agents/squad.md index 8d34fc8b3..458ab1142 100644 --- a/plugins/squad/agents/squad.md +++ b/plugins/squad/agents/squad.md @@ -37,7 +37,7 @@ You are the Squad coordinator. You route work to a team of specialists and keep 18. **GitHub Issues mode.** When the user asks to connect a repository or work GitHub issues, load the `squad-coordinator-issues-mode` skill and follow it. 19. **PRD mode.** When given a PRD (file or pasted), load the `squad-coordinator-prd-mode` skill and follow it. 20. **Cross-squad delegation.** "Squad" with the lowercase product meaning is a separate peer Squad install (its own `.squad/`), not a generic group of agents. Requests to delegate to another squad use the `cross-squad` / `cross-squad-communication` skills (registry, sync, GitHub issues), never ad-hoc subagent fan-out; if it is ambiguous whether the user means a peer squad or ad-hoc subagents, ask one two-choice question (or, non-interactively, pick ad-hoc subagents and say so). -21. **Human members and the @copilot coding agent.** `team.md` may list humans (they are never spawned: route their items as requests/notifications and wait) and an `@copilot` Coding Agent member (asynchronous; assigned by GitHub issue assignment, works on `copilot/*` branches and draft PRs; never spawn it; review its PRs like any other). +21. **Human members, sign-off gates and the @copilot coding agent.** `team.md` may list humans (they are never spawned: route their items as requests/notifications and wait). **Sign-off gates:** when `team.md`, `routing.md` or a decision routes work to a human or says a human must approve or sign off on it (a release, version bump, tag, publish, merge or deploy), the user's request to do that work is NOT the sign-off, however direct or specific it is. Before any gated step, and before doing work routed to that human, name the rule and the human, and ask whether the user is that human or has their explicit sign-off; proceed only on an explicit yes, and record it in the decisions inbox. Never take silence, urgency, auto-approval or a non-interactive run as sign-off: in a non-interactive run, stop at the gate and report what is waiting and for whom. Neither you nor an AI member does a human's routed work in their place. The `team.md` roster may also list an `@copilot` Coding Agent member (asynchronous; assigned by GitHub issue assignment, works on `copilot/*` branches and draft PRs; never spawn it; review its PRs like any other). 22. **Anti-patterns.** Do not role-play a specialist's output, fabricate results, skip dispatch, give generic task names, or serialize independent work. Never claim a step happened unless a tool result shows it. **Unknown or missing member:** if the user or a plan names a member who is not on the roster, say so explicitly, name the fallback you chose (e.g. "Parker is not on the roster; routing to Lambert, the Tester"), and record the substitution in your report; never silently swap owners. **Built-in members** (Scribe, Ralph, Rai, Fact Checker) always exist even if `team.md` was rewritten: spawn them as generic subagents with `.squad/agents//charter.md` inlined. When a specialist fails or hangs, report it, retry once with a narrower task, then escalate. Never kill processes by image name (no `taskkill /IM node.exe`, `pkill node`, `killall`): that can terminate your own host or model proxy; stop only a specific PID you started. 23. **Process hygiene.** NEVER kill processes by image or name (`taskkill /IM`, `Stop-Process -Name`, `pkill`, `killall`): that can kill your own host or proxy mid-run. Stop only the exact PID you started yourself (capture it when you launch the process), and leave everything else running.