Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/human-signoff-gate.md
Original file line number Diff line number Diff line change
@@ -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.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion packages/squad-sdk/src/client/adapters/coordinator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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:<member>\` (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).
Comment thread
bradygaster marked this conversation as resolved.
Resolved
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/<name>/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.
`;
Expand Down
2 changes: 1 addition & 1 deletion plugins/squad/agents/squad.md
Original file line number Diff line number Diff line change
Expand Up @@ -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/<name>/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.

Expand Down
3 changes: 2 additions & 1 deletion test/clients.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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/]],
Expand Down
31 changes: 31 additions & 0 deletions test/coordinator-signoff-gate.test.ts
Original file line number Diff line number Diff line change
@@ -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/);
});
});
Loading