Skip to content

Commit a2ca2f7

Browse files
tamirdresherCopilotbradygasterReno (Copilot)Copilot
authored
chore: promote v0.10.1 dev → main + v0.10 stabilisation blog post (#1313)
* fix: auto-scaffold Fact Checker agent during init and cast (#1222) The Fact Checker role landed in v0.10.0 (#789) with catalog entry, charter template, skill, AGENT_TEMPLATES map entry, and template manifest entry — but was never wired into the user-facing onboarding flow. Users running 'squad init' got Scribe/Ralph/Rai but never saw Fact Checker as a default or cast option. This mirrors how Rai was wired: - init.ts: adds 'fact-checker' to the default agents: array passed to sdkInitSquad() - cast.ts: adds factCheckerMember(), factCheckerCharter(), hasFactChecker branches in castTeam(), and the roster banner line Smoke-tested locally: 'squad init' in a clean repo now produces .squad/agents/fact-checker/charter.md alongside scribe/ralph/Rai. Closes #1222 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(upgrade): auto-scaffold Rai + Fact Checker on squad upgrade (#1222) Extends the #1222 fix to the third code path. \squad upgrade\ was intentionally silent on agents (preserves user state). For users upgrading from v0.9.x or earlier (no Rai) or v0.10.0 (no fact-checker), this means they'd never get the built-in agents unless they re-ran \squad init\ (which would overwrite other state). Adds \�nsureBuiltinAgents()\ to \ unEnsureChecks()\. Idempotent — only scaffolds when the agent directory is absent. Never overwrites existing charters or history files. Sources content from the shipped \ emplates/{Rai,fact-checker}-charter.md\ templates (already present via TEMPLATE_MANIFEST). Scribe and Ralph are intentionally NOT scaffolded by upgrade — they predate this fix in every squad, and their charters are inlined in cast.ts (no shipped template file). Smoke tested locally: - Set up a simulated v0.9.4 squad (scribe + ralph only) - Ran \squad upgrade\ → 'scaffolded 2 built-in agent(s): Rai, fact-checker' - Ran upgrade again → no re-scaffold (idempotent) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(permissions): use 'approve-once' for Copilot CLI v1.0.54+ contract (#1192) The Copilot CLI post-v1.0.54 changed the permission handler contract to expect 'approve-once' instead of 'approved'. Update the handler, type definition, and error hint to match the new contract. Closes #1191 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: Squad.Agents.AI - Microsoft Agent Framework adapter for the Squad CLI (#1207) * feat: Squad.Agents.AI community NuGet for MAF integration Squad CLI as Microsoft.Extensions.AI IChatClient, composing GitHub.Copilot.SDK via AsAIAgent() from Microsoft.Agents.AI.GitHub.Copilot 1.7.0-preview. Closes Track A of the Q1-Q7 design lock (see tamresearch1 .squad/decisions.md Decisions 441, 443, 444, 447). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: add PR body for #3 * fix(SquadAgent): inherit AIAgent (was IChatClient force-cast) - SquadAgent now properly inherits from Microsoft.Agents.AI.AIAgent - Removed (IChatClient)(object)agent force-cast - Overrides all AIAgent abstract members (CreateSessionCoreAsync, RunCoreAsync, etc.) - DI registration now registers AIAgent (not IChatClient) - README updated to use AIAgent.RunAsync API - No more abstraction inversion; AIAgent is the correct layer Fixes the architectural error identified by Tamir. * docs(SquadAgent): rewrite README — prerequisites, Hello World, troubleshooting, preview callout Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(SquadAgent): GitHubTokenProvider callback + redact options ToString Adds async token provider pattern for production scenarios (KeyVault/MSI integration). - GitHubTokenProvider property takes precedence over GitHubToken - GitHubToken marked [JsonIgnore] to prevent serialization leaks - SquadAgentOptions.ToString() redacts GitHubToken field - Updated CreateCopilotClient to resolve token from provider first Mitigates P0 #3: token leakage via ILogger structured-log calls, IOptions snapshots, and serializers. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(SquadAgent): document GitHubTokenProvider callback for production token management Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(SquadAgent): bind ConnectionStrings__squad via IConfigureOptions + add smoke tests Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(README): replace removed WithTeamRoot with positional teamRoot ctor WithTeamRoot was deleted in commit 35767c90 in favor of mandatory positional teamRoot constructor argument on AddSquad. The Aspire example in the Squad.Agents.AI README still showed the old fluent API, which would now fail at compile time for anyone copy-pasting. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test(squad-agents-ai): add routing integration tests Closes the routing-verification gap identified during squad-squad onboarding: the API surface existed but routing semantics weren't functionally tested. New tests verify persona pass-through, boundary-instruction injection on first turn, WorkingDirectory isolation (Decision 452a), and CopilotClientOptions-based routing (Decision 447). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci(squad-agents-ai): add .NET build/test/pack workflow PR #3 CI was Node/docs-only — adding the .NET gate so green actually reflects the package code. Matrix on ubuntu + windows, restore/build/test/pack, uploads TestResults and nupkg artifacts. Closes the build-verification gap identified during squad-squad onboarding (see .squad/decisions.md adoption record, 2026-06-02). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci(squad-agents-ai): NuGet publish workflow + Dependabot config - .github/workflows/squad-agents-ai-release.yml: workflow_dispatch and tag-driven publish to nuget.org with --skip-duplicate idempotency, fail-fast on missing NUGET_API_KEY secret, optional GitHub Release on tag - .github/dependabot.yml: nuget (src + test) + github-actions, weekly, M.A.AI major allowed, OpenTelemetry major deferred (per Decision 602) Closes the release-pipeline + supply-chain-tracking gaps identified during squad-squad onboarding. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(squad-agents-ai): release-ready docs + .csproj packaging metadata - README updates / XML docs on public surface - CHANGELOG.md with [0.1.0-preview] - 2026-06-02 entry - .csproj: Description, RepositoryUrl, Authors, PackageTags, PackageReadmeFile - Verified via dotnet pack — .nupkg contains README, LICENSE, xml-docs Closes the docs-readiness gap for v0.1-preview publish. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci(squad-agents-ai): switch release triggers to dev/main branch-driven Per Tamir's release-strategy directive (decisions.md 2026-06-02): - dev merges → prerelease publish (suffix scheme mirrors Squad CLI) - main merges → stable publish - workflow_dispatch retained as manual escape hatch - tag-driven trigger removed (branches are the source of truth) Version derivation pattern adapted from the Squad CLI's existing release workflow. --skip-duplicate retained for idempotent reruns. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs+fix: PR #3 review pass — hygiene, XML docs, cliArgs, multi-named connections - Rewrite the package README and PR validation flow around the AIAgent surface and ambient Copilot authentication. - Keep public docs free of internal process references and remove obsolete deferral language. - Preserve connection-string cliArgs through CopilotClientOptions and cover the behavior with a routing test. - Add named connection-string lookup via AddSquadAgent("name") using ConnectionStrings:squad-{name}. - Document the new public overloads and verify the package builds without warnings. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: Round 2 — keyed DI, BYOK delegate, routing gate, security hardening - Add ConfigureCopilotClient delegate on SquadAgentOptions for BYOK - Add routing gate: snapshot/restore Cwd/CliPath/CliArgs after delegate (Picard C1) - Add 4 AddKeyedSquadAgent overloads with .NET 8+ keyed DI - Fix Environment credential leak: [JsonIgnore] on Environment, GitHubTokenProvider, ConfigureCopilotClient - ToString() redacts token-pattern keys (TOKEN/KEY/SECRET/HMAC/PASSWORD/CREDENTIAL) - Add 21 new tests (43 total): security redaction, keyed DI, BYOK routing gate - Update README: streaming, keyed DI, BYOK, security sections Complies with: Picard C1-C4, Worf SC-1 through SC-8. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat: add Squad.Agents.AI sample app demonstrating DI, keyed DI, BYOK, and streaming - samples/squad-agents-ai-sample/Program.cs: four runnable flows Flow 1 -- AddSquadAgent + RunAsync (basic DI) Flow 2 -- AddKeyedSquadAgent x2 + GetRequiredKeyedService<SquadAgent> Flow 3 -- ConfigureCopilotClient delegate (BYOK token + env var injection) Flow 4 -- RunStreamingAsync with await foreach token-by-token output - samples/squad-agents-ai-sample/Squad.Agents.AI.Sample.csproj: net10.0, project reference to src/Squad.Agents.AI, Microsoft.Extensions.Hosting 10.0.0 - samples/squad-agents-ai-sample/README.md: prerequisites, run commands, per-flow walkthrough, troubleshooting table - .github/workflows/squad-agents-ai-ci.yml: adds paths trigger and restore + build steps for the sample (no run step -- requires live CLI) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(Squad.Agents.AI): co-locate sample under src/ and consolidate README - Moves the sample app from samples/squad-agents-ai-sample/ to src/Squad.Agents.AI/samples/Squad.Agents.AI.Sample/ so it lives alongside the package it demonstrates. - Folds the sample's standalone README into the package README, giving consumers one canonical doc for both the API and the runnable demo. - Adds <Compile Remove="samples/**/*.cs" /> to Squad.Agents.AI.csproj so the library's wildcard glob does not pick up Program.cs in the co-located samples subdirectory. - Updates the .csproj project reference, and CI workflow paths to match the new layout. - Verified end-to-end: dotnet build, dotnet test (43/43 passing), and a sample sanity-check run (clear CLI-not-found error, no stack trace). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(Squad.Agents.AI): remove outdated draft PR body file The standalone pr-body.md was an early draft authored before the live PR description took its final shape. The PR body on GitHub is the canonical source; this file is dead weight and would confuse maintainers reviewing the diff. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(Squad.Agents.AI): address PR #1207 reviewer feedback (12 items) - Snapshot CliArgs by value, not reference, so in-place mutation by SDK consumers is also caught by the routing guard. - Validate name/connectionName/serviceKey is non-empty in all DI registration overloads; previously null/whitespace produced invalid connection-string keys. - Replace ghp_-prefixed placeholder in the sample with a clearly-fake token to avoid tripping secret-scanning and to remove a real-token lookalike. - Remove brittle 'PR #3' references from README and CHANGELOG; describe the feature without tying to a specific PR thread. - Update NuGet metadata and README links to point to bradygaster/squad (canonical repo) instead of the tamirdresher fork. - Multi-target the test project to match the package's target framework set so CI exercises every framework the package ships against. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(Squad.Agents.AI): adopt DelegatingAIAgent base + MAF ctor pattern (PR #1207 r2) Addresses westey-m's review feedback: - Extend Microsoft.Agents.AI.DelegatingAIAgent — drops ~70 lines of manual Core* overrides; pass-through is provided by the base class. - Adopt MAF constructor pattern: \(string squadFolderPath, SquadAgentOptions? options = null, ILoggerFactory? loggerFactory = null)\. Required settings on the constructor, options optional, ILoggerFactory stays on ctor for DI injection. - Routing-guard, IAsyncDisposable, and security posture preserved. - Add Squad.Agents.AI.slnx solution for easy IDE open. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Reno (Copilot) <reno@clawpilotsquad.dev> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: tamirdresher <tamirdresher@users.noreply.github.com> * ci(Squad.Agents.AI): switch NuGet publish to Trusted Publishing (OIDC) (#1240) Replace the long-lived NUGET_API_KEY repo secret with NuGet/login@v1 OIDC token exchange (1-hour API key) per the modern Trusted Publishing flow: https://learn.microsoft.com/nuget/nuget-org/trusted-publishing Why --- - No long-lived credentials stored in the repo. - Token is scoped to this workflow + repo + branch via the OIDC subject claim and the Trusted Publishing policy registered on nuget.org. - Eliminates the chicken-and-egg between needing admin to set NUGET_API_KEY and needing the package live to validate the workflow. What changed ------------ - Add `id-token: write` to the publish job (required for OIDC). - Drop the `Verify NuGet API key` step. - Drop the `--api-key ` reference to secrets.NUGET_API_KEY. - Add `NuGet/login@v1` step that exchanges the OIDC token for a short-lived API key, exposed via `steps.nuget-login.outputs.NUGET_API_KEY`. - Add a fail-fast check for the new `vars.NUGET_USER` repository variable (non-sensitive; the nuget.org profile name that performs the exchange). - Update the file header documentation to reflect the new flow and link to the Trusted Publishing setup page. Required configuration before first publish ------------------------------------------- 1. Create the `Squad` organization on nuget.org and add owners. 2. Configure a Trusted Publishing policy at https://www.nuget.org/account/trusted-publishing owned by the Squad org: Repository Owner: bradygaster Repository: squad Workflow File: squad-agents-ai-release.yml Environment: (empty) 3. Set repository variable NUGET_USER (Settings → Secrets and variables → Actions → Variables) to a Squad-org-member's nuget.org profile name (NOT email). Variable, not secret — the username is non-sensitive. Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(Squad.Agents.AI): expose SessionConfig + default OnPermissionRequest (#1252) Squad.Agents.AI 0.1.0-preview.2 calls `CopilotClient.AsAIAgent(instructions, name)` which leaves `SessionConfig.OnPermissionRequest` unset. The first call to `SquadAgent.CreateSessionAsync()` therefore throws: System.ArgumentException: An OnPermissionRequest handler is required when creating a session. For example, to allow all permissions, use CreateSessionAsync(new() { OnPermissionRequest = PermissionHandler.ApproveAll }); There was no public way for consumers to fix it from the outside — `ConfigureCopilotClient` only exposes `CopilotClientOptions`, not the per-session `SessionConfig` that owns the permission handler. What changed ------------ - `SquadAgent` now switches to the `AsAIAgent(client, sessionConfig, ...)` overload and constructs a `SessionConfig` with: - `OnPermissionRequest = PermissionHandler.ApproveAll` (sensible default for a host-process Squad adapter; the host already chose to instantiate Squad and is responsible for sandboxing). - `WorkingDirectory` defaulting to the resolved `Cwd` / `SquadFolderPath`. - `SystemMessage = new SystemMessageConfig { Content = Instructions }` when `SquadAgentOptions.Instructions` is set. - `SquadAgentOptions.ConfigureSession: Action<SessionConfig>?` is new — runs after Squad applies its defaults so a consumer can swap in a stricter permission handler, pin the model, restrict tools, etc. Tests ----- - New `SquadAgentSessionConfigTests` (4 cases) exercising the new surface: `ConfigureSession` is settable, runs against the live SessionConfig, can replace the permission handler, and can set `AvailableTools`. - All existing 43 tests still pass per TFM (141 total across net8/9/10). Verified -------- - The end-to-end consumer smoke test in `C:\Users\tamirdresher\source\repos\squad-agents-ai-consume-test` previously had to fall back to the raw SDK because of the missing handler. With this change, `SquadAgent.CreateSessionAsync()` returns successfully and `RunAsync` drives real 3-turn conversations against `.squad/`-init'd teams. Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Squad.Agents.AI 0.2.0: bump to MAF 1.10.0-rc1 / SDK 1.0.0 GA — file-IO works (#1259) * Squad.Agents.AI: bump to MAF 1.10.0-rc1 / SDK 1.0.0 GA — file-IO now works Microsoft.Agents.AI.GitHub.Copilot bumped from 1.7.0-preview to 1.10.0-rc1, which transitively brings GitHub.Copilot.SDK 1.0.0 GA. SDK 1.0.0 reshaped CopilotClientOptions and SessionConfig (the breaking namespace + property renames are mirrored below), but in return Copilot CLI 1.0.61 talks to the SDK over the new ACP-style protocol — meaning the agent's view/grep/powershell tools finally work end-to-end without 'permission errors' or 'content exclusion policy' hallucinations. SDK 1.0.0 API migrations applied: * Namespace GitHub.Copilot.SDK -> GitHub.Copilot. * CopilotClientOptions.Cwd -> WorkingDirectory. * CopilotClientOptions.CliPath + .CliArgs collapsed into a single CopilotClientOptions.Connection (RuntimeConnection). We now build the Connection via RuntimeConnection.ForStdio(CliPath, CliArgs) only when the consumer supplied either a custom CLI path or extra CLI args; otherwise the SDK's default child-process connection is used and the bundled copilot.exe (downloaded by the SDK's build/ targets) is invoked. * SessionConfig.ConfigDir -> SessionConfig.ConfigDirectory. * PermissionRequestHandler is no longer a named delegate type; we use type inference where the test code referenced it. Public Squad.Agents.AI surface is intentionally unchanged: SquadAgentOptions still exposes Cwd, CliPath, CliArgs, ConfigureSession, ConfigureCopilotClient. We translate to the SDK 1.0.0 shape internally. Routing gate (Picard Condition 1 / Worf SC-3) updated to snapshot and restore WorkingDirectory + Connection instead of the old Cwd / CliPath / CliArgs trio. A delegate that REPLACES Connection (e.g. via RuntimeConnection.ForStdio(...)) is reverted, mirroring the previous CliPath / CliArgs hijack tests. Verified end-to-end against a real .squad-initialised team root: the coordinator successfully reads .squad/team.md and enumerates every cast member with their role. The dotnet test suite passes 46/46 across net8.0, net9.0, and net10.0 (-1 vs baseline because the old CliPath and CliArgs hijack tests collapsed into a single Connection hijack test, which is the right granularity for SDK 1.0.0). Version bumped 0.1.0-preview -> 0.2.0 to surface the MAF/SDK transitive bump. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address Copilot review feedback (#1259) - Remove duplicate 'using GitHub.Copilot' in SquadAgentSessionConfigTests (regex replace inadvertently doubled the directive when migrating from the old GitHub.Copilot.SDK namespace). - Drop hardcoded teamRoot override I left behind in the sample Program.cs during the CLI-not-found debug session. The sample now correctly reads SQUAD_TEAM_ROOT (or falls back to CWD) as documented. - Fix mismatched comment in SquadAgent: the SDK-protocol section now correctly references --allow-all (matching the flag actually injected in CreateCopilotClient), not the narrower --allow-all-tools. - Detect more existing permission-opening flags before injecting our default --allow-all so a host that opts in via --allow-all-paths, --allow-all-urls, or the omnibus --yolo no longer gets --allow-all prepended on top. Comparison is now case-insensitive. Updated the connection-string test that asserted the old over-eager behavior. Also add .vs/, *.user, *.userprefs to .gitignore so VS solution junk doesn't surface in git status. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: address pre-existing Copilot review comments from PR #1212 (#1258) - Workflow permissions: add issues: write to squad-pr-nudge, squad-impact, and squad-repo-health workflows that call issues.createComment - Logic bug: fix ahead_by → behind_by in pr-nudge stale branch check - Logic bug: fix PR_LABELS fallback producing string instead of null - Script fix: check legacy statuses for failure/error in checkCIStatus() - Script fix: truncation row column count mismatch in pr-readiness.mjs - Script fix: validate JSON.parse result is array before using as labels - Script fix: isNodeBuiltin now validates node: prefix against known builtins - YAML escaping: use JSON.stringify for skill descriptions in apm.yml Closes #1213 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: expose memory tools via MCP + route writes through governed pipeline (#1251) - Expose memory.classify, memory.write, memory.search, memory.promote, memory.delete, memory.audit through the squad_state MCP server (#1244) - Pin squad_state to user-level ~/.copilot/mcp-config.json during init/upgrade for external `copilot -p` mode compatibility (#1247) - Update squad.agent.md directive-capture and decision-recording instructions to route through memory.write instead of raw squad_state_write to the drop-box (#1246) Closes #1244 Closes #1247 Closes #1246 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs(skills): update path references from .squad/skills/ to .copilot/skills/ (#1260) The CLI and SDK write skills to .copilot/skills/ by default, but docs still referenced .squad/skills/. Update all documentation to use the canonical .copilot/skills/ path and add a note about legacy fallback. Closes #1241 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * feat(init): prompt to add @copilot as a team member during squad init (#1262) Add an interactive prompt during squad init that asks users if they want to add @copilot (the GitHub Copilot coding agent) as an autonomous team member. If accepted, adds the Coding Agent section to team.md and copies copilot-instructions.md into the project. Non-interactive mode skips silently with a hint to run `squad copilot enable` later. Closes #1147 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: align skills path + state-backend upgrade flow (#1241, #1226) (#1249) - Update all docs references from .squad/skills/ to .copilot/skills/ - Note that both paths are scanned at read time but .copilot/skills/ is write default - List all 6 git hooks (add pre-commit and post-commit to docs) - Correct 'read-only reference' claim about migrated files - Add recovery section for pre-commit hook refusal scenarios Closes #1241 Closes #1226 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Squad.Agents.AI 0.3.0: first-class subagent observability (#1265) Adds a typed OnSubagentTrace callback + OpenTelemetry ActivitySource so consumers can see subagent dispatch (the coordinator's 'task' tool spawning specialist sub-agents and their replies) without writing their own polymorphic dispatch over the raw GitHub.Copilot SessionEvent hierarchy. The previous 0.2.x surface required consumers to write the same boilerplate the aspire-squad-resource demo had to (CopilotSessionTraceMapper.cs): switch on every event subtype, unwrap subagent context, manage Activity lifetime. 0.3.0 makes that the SDK's job. New public surface: * SquadAgentOptions.OnSubagentTrace (Action<SquadAgentTraceEvent>) Set this to subscribe to subagent lifecycle (Selected / Started / Completed / Failed), assistant messages from coordinator AND subagents, tool start/complete, and SessionIdle. Setting OnSubagentTrace implicitly turns on SessionConfig.IncludeSubAgentStreamingEvents so subagent replies actually flow up to the parent session (otherwise they stay inside the subagent session and never reach the callback). * SquadAgentTraceEvent record — typed envelope (Kind, RawEventType, Timestamp, SdkAgentId, SubagentName, SubagentDisplayName, ToolCallId, Content, Success, RawEvent). Carries the original SessionEvent on RawEvent for advanced consumers but exposes everything else through neutral primitive types so the callback signature has no transitive dependency on GitHub.Copilot.SDK. * SquadAgentTraceEventKind enum — categorises the SessionEvent into the well-known cases that downstream observability surfaces want. * SquadAgentDiagnostics.ActivitySourceName ('Microsoft.Agents.AI.Squad') + SquadAgentDiagnostics.ActivitySource — one Activity per subagent dispatch is opened on SubagentStartedEvent and disposed on the matching SubagentCompletedEvent / SubagentFailedEvent, tagged with squad.subagent.name, squad.subagent.display_name, squad.subagent.sdk_agent_id, and squad.subagent.reply_preview (a short truncated copy of the subagent's assistant message). Hosts that .AddSource(SquadAgentDiagnostics.ActivitySourceName) on their OpenTelemetry tracer get these spans in their backend — the Aspire dashboard renders them in the trace view automatically. Internal: * SquadSubagentTraceMapper — wires SessionEvent -> SquadAgentTraceEvent and the Activity lifecycle. Held by SquadAgent and disposed during DisposeAsync to drain any subagent activities that never received a matching Completed event (e.g. session ended mid-dispatch). * InternalsVisibleTo=Squad.Agents.AI.Tests so the mapper can be unit tested directly without spinning a real CLI session. Tests: 54/54 passing across net8, net9, net10 (+8 new tests for the observability surface including Activity lifetime, tag propagation, mid-session disposal, and consumer-callback exception isolation). Verified end-to-end against the tamresearch1 Star Trek squad: the OnSubagentTrace callback observed two parallel subagent dispatches (Picard, Data), captured each of their replies attributed to the right SdkAgentId, and the matching 'squad.subagent Picard' / 'squad.subagent Data' OTel spans opened and closed cleanly with the reply tagged on each span. Version bumped 0.2.0 -> 0.3.0 to signal the new public surface. Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore(lockfile): sync package-lock with package.json after v0.10.0 bump (#1266) After the v0.10.0 stable release on 2026-06-07, the root package-lock.json still recorded packages/squad-cli@0.9.6-preview.15 and packages/squad-sdk@0.9.6-preview.13 for the workspace entries. The package.json files were updated correctly during the release, but the lockfile workspace metadata was not regenerated. This causes `npm ci --ignore-scripts` to fail in the `sdk-exports-validation` CI job whenever package.json versions diverge from these stale lockfile entries (which happens on every build that runs `scripts/bump-build.mjs`). Confirmed on PR #1257. This commit regenerates only the workspace version metadata (`packages/squad-cli` and `packages/squad-sdk`) — no dependency trees are touched. Verified locally on Windows + Node v23.5.0: - `npm ci --ignore-scripts` at repo root: ✅ exit 0 (was already passing on dev because root package.json/lockfile match; failure mode is the workspace-entry mismatch surfacing under specific build conditions) - `npm install --ignore-scripts`: no further drift produced - Full `npm test` suite: 6535 passed / 134 failed / 60 skipped — the 134 failures are all pre-existing Windows file-locking flakiness (EBUSY/ENOTEMPTY/hook-timeout); identical failure mode and similar count on the immediate pre-merge commit cc37a2f7 (125 failures pre-merge, 134 post-merge — diff is within flake noise). - Targeted re-run of the 5 "newly failing" files in isolation: 93/93 passing — confirms the bulk-run failures are concurrency-induced flakes, not regressions from the recent merges (#1251, #1258, #1260, #1262, #1249). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(bump-build): also update package-lock workspace entries (#1267) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: release pipeline version pinning (#1203, #1204) (#1250) * fix: release pipeline version pinning (#1203, #1204) - Lower SDK dependency floor from >=0.10.0 to >=0.9.0 so the CLI tarball resolves against the last published SDK when current version isn't yet on the registry (Closes #1203) - Add isLocalOrUnpublishedVersion guard so local dev builds and versions with build metadata (+) fall back to @insider instead of writing unresolvable version strings into MCP config (Closes #1204) - Extend resolveSquadStateMcpSpec to short-circuit for build-metadata versions - Add CI step to verify SDK dependency is resolvable before CLI publish Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: reset accidentally-bumped version 0.10.0-build.2 -> 0.10.0 Pre-publish version guard rejects -build.N suffixes (release pipeline policy). The bump was made by an unintended local 'npm run build' run before commit. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamir.dresher@gmail.com> Co-authored-by: Copilot <tamirdresher@users.noreply.github.com> * chore: include CHANGELOG.md in published npm tarball (#1257) * chore: include CHANGELOG.md in published npm tarball Add CHANGELOG.md to the files array in both squad-cli and squad-sdk package.json files so changelogs are included in published npm tarballs. This enables offline what's-new prompts and removes the need for GitHub API calls to show release notes. Closes #1171 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: reset accidentally-bumped versions to 0.10.0 Pre-publish version guard rejects -build.N suffixes (release pipeline policy). Both SDK and CLI package.json had -build.4 from a local 'npm run build' run before commit. --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamir.dresher@gmail.com> Co-authored-by: Copilot <tamirdresher@users.noreply.github.com> * Squad.Agents.AI 0.4.0: default-on subagent observability + Aspire-style connection-string lookup (#1271) Two small but high-impact changes that remove ~30 lines of boilerplate from every consumer (Aspire and otherwise) and make the OpenTelemetry story self-explanatory. ## 1. EmitSubagentActivities (default true) — telemetry independent of callback Today, the per-subagent OpenTelemetry Activity emission is a side-effect of setting `OnSubagentTrace`. A host that just wants `squad.subagent {Name}` spans in their backend has to wire a callback they don't need. `Microsoft.Agents.AI.Squad` is silent until then. 0.4.0 makes activity emission the default: * New `SquadAgentOptions.EmitSubagentActivities` (defaults to `true`). * `SquadAgent` installs `SquadSubagentTraceMapper` whenever `EmitSubagentActivities || OnSubagentTrace != null`, so spans flow with zero extra wiring. * `OnSubagentTrace` becomes a pure customisation hook (logging, dashboards, metrics) — independent of telemetry. Set `EmitSubagentActivities = false` to opt out of built-in spans when you want to handle telemetry yourself. Plus richer span shape: every lifecycle phase is now an `ActivityEvent` on the live subagent span (visible as annotated markers on the timeline in Aspire / Jaeger / etc.): * `squad.subagent.start` — on SubagentStarted * `squad.subagent.message` — on AssistantMessage (with message_preview tag) * `squad.subagent.completed` — on SubagentCompleted * `squad.subagent.failed` — on SubagentFailed Net effect for a consumer: builder.Services.AddOpenTelemetry() .WithTracing(t => t.AddSource(SquadAgentDiagnostics.ActivitySourceName)); builder.Services.AddSquadAgent(o => o.SquadFolderPath = "/team"); …and the dashboard lights up. No callback wiring, no Activity.Current?.AddEvent plumbing in the host. ## 2. Aspire-style connection-string lookup (with legacy fallback) Aspire injects connection strings under the literal resource name — e.g. an AppHost that calls `builder.AddSquad("research-squad", ...)` exposes `ConnectionStrings:research-squad` to the consumer. The 0.3.0 SDK only looked at `ConnectionStrings:squad-research-squad` (prefixed), so Aspire consumers had to manually call `Configuration.GetConnectionString(name)`, parse the URI, and feed `SquadFolderPath` into the configure callback themselves. 0.4.0 tries the literal name first and falls back to the legacy prefixed form: | Style | Example | Lookup | |--------------------------------------|---------------------------------------------|--------------------------------------------| | Aspire-style direct (tried first) | `AddSquadAgent("research-squad")` | `ConnectionStrings:research-squad` | | Legacy prefixed fallback | `AddSquadAgent("research")` | `ConnectionStrings:squad-research` | Both work. Existing consumers using `ConnectionStrings:squad-{name}` continue unchanged; new Aspire consumers get the natural one-line registration. ## Tests 54 → 64 tests, all passing on net8.0/9.0/10.0. New `SquadAgentDefaultObservabilityTests` covers: * Default-on activity emission (without consumer callback) * Opt-out path (`EmitSubagentActivities = false`) — span suppression + callback still fires * Each ActivityEvent name (`start` / `message` / `completed` / `failed`) * Connection-string precedence: Aspire-direct preferred, prefixed fallback used, same rule applies for keyed registrations Existing `SquadSubagentTraceTests` and the new class share an `[Collection("SquadActivityListeners")]` so they run serially — process-global `ActivityListener` state caused cross-test pollution otherwise. ## Files * `src/Squad.Agents.AI/SquadAgentOptions.cs` — new `EmitSubagentActivities` property + reworked `OnSubagentTrace` XML doc to clarify independence. * `src/Squad.Agents.AI/SquadAgent.cs` — install trace mapper when telemetry OR callback is requested. * `src/Squad.Agents.AI/SquadSubagentTraceMapper.cs` — accept `emitActivities` flag; gate `StartActivity`/`Dispose` on it; add `ActivityEvent` annotations at every lifecycle boundary. * `src/Squad.Agents.AI/SquadAgentOptionsConfigurator.cs` — accept a list of candidate connection-string names; first non-empty wins. * `src/Squad.Agents.AI/SquadServiceCollectionExtensions.cs` — new `GetConnectionStringNames` returns `[name, "squad-"+name]` so both Aspire and legacy conventions resolve. * `src/Squad.Agents.AI/Squad.Agents.AI.csproj` — bump 0.3.0 → 0.4.0. * `src/Squad.Agents.AI/README.md` — new "Subagent observability" section, updated "Aspire / configuration path" section, two new option rows in the Key Options table. ## Backward compatibility Fully backward compatible. The two-arg `SquadSubagentTraceMapper` constructor defaults `emitActivities` to `true`, `EmitSubagentActivities` defaults to `true`, and the legacy `ConnectionStrings:squad-{name}` lookup still resolves. Net change for an existing consumer that had OnSubagentTrace set: nothing (mapper runs in both 0.3.0 and 0.4.0 because OnSubagentTrace is non-null). Net change for a consumer that did NOT set OnSubagentTrace but did AddSource: they now get spans they always asked for. Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Squad.Agents.AI 0.5.0: auto-inject --agent squad (CLI parity by default) (#1275) * Squad.Agents.AI 0.5.0: auto-inject --agent squad (CLI parity by default) The whole point of SquadAgent is to wrap a Squad coordinator team — but the 0.4.x SDK launched the underlying copilot.exe with the CLI's built-in generic agent. The coordinator therefore had no instructions to eager-execute, fan out, or dispatch via the task tool, so it role-played responses inline. Concretely: this SDK call builder.Services.AddSquadAgent(o => o.SquadFolderPath = teamRoot); did NOT behave the same as running copilot --agent squad interactively against the same team root. Consumers had to remember to add `opts.CliArgs.Add(""--agent""); opts.CliArgs.Add(""squad"");` themselves, which is an SDK leak — the class is literally called SquadAgent. 0.5.0 makes --agent squad the SDK default: * New `SquadAgentOptions.AgentFileName` (defaults to `""squad""`). * On client construction, SquadAgent looks for `{teamRoot}/.github/agents/{AgentFileName}.agent.md`. If it exists, `--agent {AgentFileName}` is auto-prepended to the CLI args. * If the file is missing (folder not Squad-initialized), the inject is silently skipped and a Debug log line explains why. The CLI then starts with its default agent, which is what 0.4.x did anyway. * If the consumer already supplied `--agent X` in `CliArgs`, the explicit value wins and we do NOT add a second one. * Set `AgentFileName = null` (or whitespace) to opt out entirely. Net effect: SquadAgent.RunAsync now matches `copilot --agent squad` for any Squad-initialized team root, without the consumer doing anything. ## Tests 64 -> 71 tests, all passing on net8.0/9.0/10.0. New `SquadAgentDefaultAgentFlagTests` (uses a per-test temp dir to scaffold or omit the agent file deterministically): * Default AgentFileName is ""squad"" * Auto-inject when squad.agent.md exists * No inject when the file is missing (graceful degradation) * Explicit --agent in CliArgs wins (no second --agent added) * Custom AgentFileName=""data"" injects --agent data when data.agent.md exists * AgentFileName=null opts out entirely * AgentFileName=whitespace opts out entirely Backward compatibility: existing routing tests use a non-existent `C:\squad-team-root` path, so the file-existence check silently skips the inject — those tests continue to pass with no changes. ## Files * `src/Squad.Agents.AI/SquadAgentOptions.cs` — new `AgentFileName` property with XML doc covering the default, the opt-out, and the not-yet-initialized fallback. * `src/Squad.Agents.AI/SquadAgent.cs` — auto-inject logic in `CreateCopilotClient` (after the `--allow-all` block, before `options.CliArgs` are appended) with file-existence + already-supplied guards and a Debug log when the file is missing. * `src/Squad.Agents.AI/Squad.Agents.AI.csproj` — bump 0.4.0 -> 0.5.0. * `src/Squad.Agents.AI/README.md` — new ""Coordinator agent selection"" section with the precedence table; `AgentFileName` row added to Key Options table. * `+test/Squad.Agents.AI.Tests/SquadAgentDefaultAgentFlagTests.cs` Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * amend: use SessionConfig.Agent instead of --agent CLI args GitHub.Copilot SDK's SessionConfigBase exposes an Agent (string) property that is the first-class equivalent of the Copilot CLI's --agent flag. It discovers and loads .github/agents/{name}.agent.md exactly the same way the CLI does, but without us having to munge CliArgs. Switch the 0.5.0 default-coordinator-agent implementation: - SquadAgent now sets sessionConfig.Agent = options.AgentFileName (default ""squad"") right after constructing the SessionConfig, before ConfigureSession runs. - Drop the --agent CliArgs hack (we no longer need to detect ""did the consumer already pass --agent?"" because ConfigureSession naturally wins over our default). - Tests now assert against sessionConfig.Agent via reflection over the inner DelegatingAIAgent — exactly what consumers using ConfigureSession would see. - README ""Coordinator agent selection"" section reworded to say ""sets SessionConfig.Agent"" instead of ""auto-adds --agent"". 71/71 tests still pass on net8.0/9.0/10.0. The fifth new test (ConfigureSession_CanOverrideAutoSetAgent) explicitly proves the ConfigureSession callback can replace the auto-set value, which is the clean override path now that --agent CliArgs is gone. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Squad.Agents.AI 0.5.1: fix 0.5.0 regression — use --agent CLI flag (not SessionConfig.Agent) (#1277) 0.5.0 (#1275) replaced the previous --agent CliArgs approach with sessionConfig.Agent = options.AgentFileName, on the theory that the SDK property was the first-class equivalent of the CLI's --agent flag. It is not. SessionConfig.Agent looks up the name in the SDK's CustomAgents registry (programmatic agent definitions, never populated by SquadAgent), NOT in .github/agents/*.agent.md files on disk. The result was a runtime error on every RunAsync call against a Squad-initialised team: Communication error with Copilot CLI: Request session.create failed with message: Custom agent 'squad' not found Verified at GitHub.Copilot.SDK 1.0.0: * SessionConfigBase.Agent (string) — selects from CustomAgents * SessionConfigBase.CustomAgents (IList<CustomAgentConfig>) — programmatically defined inline agents (Name, Prompt, Tools, Skills, Model, etc.). Empty by default. * The CLI's --agent flag is currently the only path that reads .github/agents/{name}.agent.md on disk. 0.5.1 reverts to the original CliArgs implementation: * SquadAgent now auto-prepends '--agent {AgentFileName}' to combinedCliArgs (back to what 0.5.0 originally proposed before the SessionConfig.Agent detour). * The file-existence check at {teamRoot}/.github/agents/{name}.agent.md still gates the inject so non-Squad-initialized folders degrade gracefully (no --agent passed -> CLI uses default agent). * The 'consumer already supplied --agent in CliArgs' guard is back so the SDK does not add a duplicate. Tests: * New SquadAgentDefaultAgentFlagTests covers all seven cases via reflection over Connection.Args (the CLI-args path the SDK actually uses): default 'squad' value, auto-inject when file exists, no inject when missing, explicit --agent wins, custom AgentFileName works, AgentFileName=null/whitespace opts out. * The older SquadAgentDefaultAgentTests (which targeted SessionConfig.Agent) is removed since that property does NOT do what we wanted. 71/71 tests passing on net8.0/9.0/10.0. Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Add squad registry add/list/remove for discovery-only peer squads (#1291) Closes #1290. Adds CLI surface for managing .squad/squad-registry.json, symmetric to squad upstream. Registry entries are discovery-only (visible to squad discover and squad delegate) but do NOT trigger inheritance of the peer squad's skills/decisions/wisdom/routing. Previously users had to hand-edit .squad/squad-registry.json — even the squad discover empty-state hint told them to "create a squad-registry.json" manually. This adds proper commands: squad registry add <name> <path> # validates manifest, refuses duplicate squad registry list # show all registered peers squad registry remove <name> # remove by name Also fixes a subtle path-semantics confusion: readManifest() now accepts BOTH the repo root AND a path with a trailing .squad segment. The docs and SKILL.md showed the .squad-suffixed form but the code previously joined .squad/manifest.json onto whatever you gave it, so the suffixed form silently failed empirical reproduction (discover returned nothing). Test coverage: 18 new tests in cross-squad-registry.test.ts covering the dual-path readManifest fix, registry round-trip, add/list/remove behavior including duplicate-name and invalid-manifest rejection, and end-to-end integration with discoverSquads. Also updates: - cross-squad SKILL.md (canonical + 2 template mirrors) to document the registry vs upstream distinction explicitly - squad discover empty-state hint to mention squad registry add - squad help text with the new commands - SDK exports for the new registry helpers + RegistryEntry/ AddRegistryEntryResult types End-to-end verified locally: - squad registry add (both repo-root and .squad-suffixed paths) - squad registry list (rich output) - squad registry remove (success + missing-name warning) - squad discover picks up registry entries with source=registry - 50/50 tests pass (32 existing + 18 new) - npm run build clean Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(cli): stop writing squad_state to ~/.copilot/mcp-config.json on every init/upgrade (#1296) (#1298) * fix(cli): stop writing squad_state to ~/.copilot/mcp-config.json on every init/upgrade (#1296) squad init (init.ts:408) and squad upgrade (upgrade.ts:738) unconditionally called ensureSquadStateMcpInUserConfig, writing squad_state_<hash> to ~/.copilot/mcp-config.json keyed by a stable project-path hash. Each new squad init accumulated another entry in HOME with no garbage collection. This contradicted the explicit iter-8 design intent documented at packages/squad-cli/src/cli/core/mcp-root.ts:1-27, which says iter-8 stops writing to HOME and writes squad_state ONLY to repo-root .mcp.json. The repo-root .mcp.json writes (init.ts:403 / upgrade.ts:728) already cover all documented Copilot CLI launch modes - copilot and copilot -p both walk up from cwd to find .mcp.json. Out-of-tree copilot -p invocations should use --additional-mcp-config @.mcp.json (already documented at init.ts:494). Changes: * Removed the unconditional ensureSquadStateMcpInUserConfig call from init.ts:408 and upgrade.ts:738. Replaced both with comments explaining iter-8 + #1296. * Removed the now-unused import from both files. * Kept the function definition at mcp-root.ts:178-228 - a future squad doctor --mcp-prune cleanup helper may want to inspect HOME. Tests: * New regression test in test/cli/init.test.ts: "should NOT write any squad_state entries to ~/.copilot/mcp-config.json (#1296)". Isolates the developer's real HOME by setting USERPROFILE/HOME to a temp dir before init, asserts no squad_state* keys appear under temp HOME. * All 40 existing init tests still pass. npm run lint clean. Closes #1296 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: comments reference actual Copilot CLI version (≥1.0.59), drop hardcoded test line numbers Reviewer follow-ups on #1298 (closes #1296): 1. The comments in init.ts/upgrade.ts/mcp-root.ts referenced 'Copilot CLI 5.3+' as the version that auto-loads .mcp.json. The real shipping CLI is at 1.0.62 (5.3 was a typo'd projection from review). Updated all 5 occurrences to '≥1.0.59' — the lowest version where the .mcp.json walk-up behavior is documented. 2. The init.test.ts regression comment hard-coded line numbers (init.ts:408, upgrade.ts:738) that will go stale on any unrelated edit to those files. Rewrote the comment to identify the call by function name (ensureSquadStateMcpInUserConfig) instead — durable against re-orderings. Verified: regression: #1296 test still passes (1/16 in init.test). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(init): post-init package.json script tip includes --agent squad The post-init tip showing how to add a non-interactive `squad:copilot` script to package.json was: "squad:copilot": "copilot --additional-mcp-config @.mcp.json" This omits `--agent squad`, so users who copy/paste it get a generic Copilot CLI session that doesn't load the Squad coordinator, team.md, casting, or MCP-wired memory/state tools — only the additional MCP config gets loaded. Same underlying issue surfaced in the cross-squad- communication SKILL.md sweep (squad/wire-cross-squad-skill commit 6b0eac21): anywhere we spawn `copilot` into a Squad-initialised repo, we must pass `--agent squad`. Single-line fix: "squad:copilot": "copilot --agent squad --additional-mcp-config @.mcp.json" Verified: a fresh `squad init` smoke test now prints the corrected tip line verbatim. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> * fix(sdk): wire team.md/routing.md/casting state on \squad preset apply\ (#1288) (#1293) * fix(sdk): wire team.md/routing.md/casting state on `squad preset apply` (#1288) `squad preset apply <name>` only copied agent charters into .squad/agents/. It left .squad/team.md `## Members` empty, .squad/routing.md missing `## Work Type -> Agent` rows, and never created .squad/casting/registry.json, history.json, or policy.json. Net result: the coordinator's mode-switch check saw an empty Members table and treated every session as Init Mode, proposing to re-scaffold the team the user already applied. This change adds a merge-friendly scaffold module (packages/squad-sdk/src/presets/scaffold.ts) that runs after charters are copied and: * writes/updates team.md `## Members` (creates from scratch if missing; appends new rows to an existing table while preserving the surrounding Coordinator / Project Context sections; idempotent on repeat apply) * writes/updates routing.md `## Work Type -> Agent` (creates or appends) * writes/merges casting/registry.json (universe = `preset:<name>`) * appends a snapshot to casting/history.json + a universe_usage_history entry * creates casting/policy.json with defaults only if missing (never clobbers) Agents with `status: 'error'` are excluded from wiring; agents with `status: 'skipped'` (already exist in target) ARE wired so the team reflects user intent. Scaffolder failure is reported as a synthetic error result without masking the per-agent install results. Verified: * npm run lint passes * test/presets.test.ts: 28/28 pass including 4 new regression tests - wires preset agents into team.md ## Members (#1288) - merges preset agents into an existing team.md without duplicating rows - writes casting registry.json, history.json, and policy.json (#1288) - appends routing rows for preset agents to routing.md (#1288) Out of scope (tracked separately): deduplicating these writers with the equivalent fresh-write versions in packages/squad-cli/src/cli/core/cast.ts. Closes #1288 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(presets): role-aware Status cell + non-colliding sentinel for synthetic scaffold error Two reviewer follow-ups on #1293 (closes #1288): 1. Members-table Status was hardcoded to '✅ Active' for every preset agent. Presets that ship one of the always-on built-ins (Scribe, Ralph, Rai, Fact Checker) would render with the wrong status label compared to a fresh cast: '✅ Active' instead of '📋 Silent' / '🔄 Monitor' / '🛡️ RAI' / '🔍 Verifier'. Added a small statusForRole() helper that mirrors the role→status mapping in cast.ts:652-655 (case-insensitive role matching to tolerate preset authors who lowercase the role string). Built-in role names get their canonical labels; everything else falls back to '✅ Active'. Added a regression test asserting the labels for a preset that ships scribe/ralph/rai/fact-checker + one regular agent. 2. Synthetic scaffold-failure result row used 'agent: presetName' for its 'agent' field. If the preset itself happens to include an agent literally named after the preset ('squad preset apply geektime' on a preset whose roster has a 'geektime' agent), the consumer of PresetApplyResult[] could not distinguish the synthetic scaffold- level error from a real per-agent install error. Replaced with the angle-bracketed sentinel '<scaffold>' (which validateName() rejects, so it can never collide with a real agent name) and moved the preset name into the human-readable reason string so consumers don't lose that context. Verified: 29/29 preset tests pass (28 existing + 1 new role-status test). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> * fix(docs): tell coordinator to roster Fact Checker on first-time cast (#1299) (#1300) * fix(docs): tell coordinator to roster Fact Checker on first-time cast (#1299) squad init correctly creates .squad/agents/fact-checker/ on disk (per merged PR #1223). But when the user opens copilot --agent squad and the coordinator runs first-time casting, it OMITS Fact Checker from the team.md ## Members table while including Scribe, Ralph, and Rai. Root cause: .squad-templates/squad.agent.md had two gaps: 1. Line 56 said "team size (typically 4-5 + Scribe)" — naming only Scribe 2. Rai had a dedicated ## Rai section with explicit "Rai always appears in team.md" instruction — Fact Checker had no equivalent section So the model added Rai (because instructed to) but had no instruction to add Fact Checker, even though the agent dir was scaffolded on disk. Fix: * Update team-size line to name all 4 always-on built-ins: Scribe + Ralph + Rai + Fact Checker * Add full ## Fact Checker — Verification & Devil's Advocate section mirroring the Rai pattern: roster-entry instruction, dual operating mode (per #789 + #1254), trigger phrase table, confidence ratings, DA brief structure, boundaries, state location Sync via sync-templates.mjs --sync propagates squad.agent.md changes to all 4 mirror targets: .squad-templates/, templates/, packages/squad-cli/ templates/, packages/squad-sdk/templates/, .github/agents/. Tests: new test/squad-agent-roster.test.ts runs against all 4 template targets and asserts: * The "Determine team size" line names all 4 built-ins * A ## Fact Checker section exists with "always appears in team.md" * The section declares dual operating mode (anchors #789 + #1254 design so a future PR can't accidentally split Fact Checker and Devil's Advocate again — cf. closed PR #1294) * Existing Ralph + Rai sections still present 16/16 pass. Closes #1299 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * doc(squad.agent.md): clarify Fact Checker is exempt from casting + correct on-demand reference path Reviewer follow-ups on #1300: 1. Team-size phrasing — the line read 'typically 4-5 + Scribe + Ralph + Rai + Fact Checker' which a model could parse as arithmetic (4-5 + 4 = 8-9, but it could also collapse). Rewrote it to make the composition explicit: '4-5 cast (user-domain) agents + 4 always-on built-ins = 8-9 total roster entries'. 2. Cast-exemption parity — Scribe, Ralph, and Rai each have an explicit 'exempt from casting' bullet but Fact Checker did not. Added the matching bullet right after Rai's. 3. Bad on-demand reference path — the FC section pointed at '.squad/templates/fact-checker-charter.md'. That file IS shipped (TEMPLATE_MANIFEST destination 'templates/fact-checker-charter.md') but only AFTER 'squad init' or 'squad upgrade' has populated .squad/templates/. A reader of squad.agent.md on an un-initialized repo (or in .github/agents/ on the cloud agent surface) would follow a dead link. Repointed to the '.squad/agents/fact-checker/charter.md' instance that ensureBuiltinAgents creates as part of the same init/upgrade path — that's where the rich charter actually lives at runtime per #1299 + #1301. All 4 mirrored copies re-synced via scripts/sync-templates.mjs. fact-checker-role.test.ts: 8/8 pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> * fix(sdk): plumb Fact Checker like Rai — rich charter at init + .squad/fact-checker/ state dir (#1299 deep) (#1301) * fix(sdk): plumb Fact Checker like Rai — rich charter at init + .squad/fact-checker/ state dir (#1299 deep) PR #1300 fixed the documentation gap so the coordinator knows to roster Fact Checker. This PR fixes the structural gap behind it. Per user testing 2026-06-13: even after #1300 the actual agent on disk was still "a name on disk with a 21-line placeholder". Three structural problems: 1. squad init never used the rich {role}-charter.md templates. Both Rai and fact-checker got 478-byte generic stubs from generateCharter(). Rich templates only ran via squad upgrade's ensureBuiltinAgents path. 2. fact-checker had no state dir. Rai gets .squad/rai/{policy.md, audit-trail.md} via init.ts lines 879-941. fact-checker had nothing equivalent. 3. fact-checker-charter.md was only in packages/squad-cli/templates/ — missing from .squad-templates/ (canonical source) AND packages/ squad-sdk/templates/. SDK init's getSDKTemplatesDir() resolves to the SDK templates dir, so even if init tried to read the rich charter, the file wasn't there. Fix (4 parts): Part 1 - Rich charter at init (benefits BOTH Rai and fact-checker): * SDK init.ts agent loop now looks up {templatesDir}/{role}-charter.md for each agent and uses that as charter.md content if it exists. Falls back to generateCharter() for user-defined agents. * Result: fresh squad init produces .squad/agents/Rai/charter.md at 4525 bytes (full Rai charter) and fact-checker/charter.md at 3024 bytes (full FC charter). Previously both were 478-byte stubs. Part 2 - .squad/fact-checker/ state dir mirroring .squad/rai/: * New block in init.ts (right after the Rai seeding) creates .squad/fact-checker/policy.md (from templates/fact-checker-policy.md or inline fallback) and audit-trail.md. * New .squad-templates/fact-checker-policy.md (~6KB) is the canonical authority for dual-mode operating rules per #789 + #1254: - Mode 1 Verification: ✅/⚠️/❌/🔍 confidence rating taxonomy - Mode 2 Devil's Advocate: required brief structure - Hard anti-fabrication rules - Advisory by default with narrow blocking exceptions - Audit trail rules (succinct, never raw source) Part 3 - Fix .squad-templates/ distribution gap: * Copied fact-checker-charter.md into .squad-templates/ so sync-templates.mjs propagates it to all 4 mirror targets including packages/squad-sdk/templates/. This unblocks Part 1. Part 4 - Plumbing: * .gitattributes: .squad/fact-checker/audit-trail.md merge=union * TEMPLATE_MANIFEST: fact-checker-policy.md * squad.agent.md Files Catalog: 2 new rows for FC state files Tests: 3 new regression tests in test/init.test.ts (28/28 pass total). npm run lint clean. Composability: This PR builds on #1300 (which adds the ## Fact Checker section to squad.agent.md and the team-size line fix). Both PRs modify squad.agent.md in disjoint regions and merge in either order. Full plumbing requires BOTH to land. Closes #1299 (deep fix; #1300 was the surface fix) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(sdk): lowercase fallback for rich-charter template lookup + sync .github/agents Two reviewer follow-ups on #1301 (#1299 deep): 1. Case-sensitive FS bug in rich-charter lookup The lookup tried '\-charter.md' and '\-charter.md' only. For Rai (role='Rai', name='Rai') this becomes 'Rai-charter.md', but the actual file shipped lowercase ('rai-charter.md'). On Windows the lookup succeeded because the filesystem is case-insensitive; on Linux CI it silently missed and fell back to the 478-byte generic stub — exactly the regression #1299 was trying to fix. Reproduced by 'should use the rich Rai-charter.md template at init' failing with 'expected 476 to be greater than 1000' on GitHub Actions. Add toLowerCase() candidates after the exact-case ones. De-dupe via a Set so we don't double-stat when role and name are already lowercase (fact-checker case). Guard each candidate against blank keys. 2. Template-sync parity The canonical .squad-templates/squad.agent.md gained two Fact Checker rows in the Files Catalog but the mirrored .github/agents/squad.agent.md copy was never re-synced, so the template-sync.test.ts byte-for-byte parity check would have fired. Run 'node scripts/sync-templates.mjs --sync' to regenerate. Verified: vitest 'rich Rai-charter' passes locally after the fix (previously failing on Linux CI run 27464079078). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.github.com> * fix(skills): rename squad disambiguation skill to squad-help (supersedes #1297) (#1302) * fix(skills): rename disambiguation skill 'squad' -> 'squad-help' (supersedes #1297) PR #1297 added a disambiguation skill named 'squad' so models calling skill(Squad) would get a redirect. After local end-to-end testing on 2026-06-13: skill ships to disk correctly but never shows up in Copilot CLI's /skills list. Root cause (verified against Copilot CLI source 1.0.62-2 app.js): 1. Copilot CLI's skill schema is {name, description, source, baseDir, allowedTools, pluginName, pluginVersion} (line 989). Frontmatter fields triggers:, domain:, confidence:, license: are silently ignored. 2. Skill loader returns {skills, warnings, errors} (line 4427). Skills that fail to load are reported as errors. 3. A skill named 'squad' collides with the Copilot agent named 'Squad' (registered at .github/agents/squad.agent.md). The agent wins; the skill is hidden from /skills. Fix: * Rename 'squad' -> 'squad-help' (avoids the agent-name collision; still descriptive enough for natural-language match when user says 'how do I use squad' or 'squad help') * SKILL.md content: name: 'squad-help', removed unused triggers:/domain:/ confidence:/source:/license: fields, added allowedTools: [], rewrote description: to be self-explanatory, added explicit note that /squad slash command does NOT exist (slash commands are CLI built-ins, not auto-mapped from skills) * MANIFEST_SKILL_NAMES in sdk-init.ts: 'squad' -> 'squad-help' * New TEMPLATE_MANIFEST entry in templates.ts for squad-help (so squad upgrade also propagates the skill - that code path uses TEMPLATE_MANIFEST instead of MANIFEST_SKILL_NAMES) Tests: new test asserts .copilot/skills/squad-help/SKILL.md exists with right frontmatter; explicit regression guard against re-introducing name: 'squad'. 26/26 init tests pass. npm run lint clean. Supersedes #1297. Out of scope (separate issue worth filing): squad upgrade synced only 10 of 16 installed skills - TEMPLATE_MANIFEST (used by upgrade) is out of sync with MANIFEST_SKILL_NAMES (used by init). Skills from PRs #1292 + #1295 (tiered-memory, iterative-retrieval, reflect, cross-squad, cross-squad-communication) have entries in MANIFEST_SKILL_NAMES but not TEMPLATE_MANIFEST. Follow-up will fix. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(skill): add confidence + domain frontmatter to squad-help Reviewer follow-up on #1302: the isSkillContent() classifier in sharing/consult.ts:990 requires BOTH name: AND confidence: in the frontmatter to recognize a file as a skill. Without confidence:, squad-help would not be detected as a skill in cross-squad merge / share / promote flows — it would be misclassified as a generic markdown decision. The Copilot CLI itself silently ignores custom frontmatter fields (per sdk/index.js decompile — only name/description/allowedTools/ user-invocable are read), so adding confidence: high and domain: squad-onboarding is safe at the CLI surface and necessary at the SDK surface. Applied identically to all 3 mirrored copies of squad-help/SKILL.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <Copilot@users.noreply.github.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Tamir Dresher <tamirdresher@users.noreply.…
1 parent 28a15a7 commit a2ca2f7

187 files changed

Lines changed: 15359 additions & 377 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
"@bradygaster/squad-sdk": patch
4+
---
5+
6+
Fix #1289, #1264: Bundle missing skills on `squad init` and strip fabricated provenance from tiered-memory SKILL.md
7+
8+
**Problem**
9+
10+
Two regressions shipped in v0.10.0 caused several skills to silently never reach users:
11+
12+
1. **#1289** — `squad-commands` and `squad-version-check` were in `MANIFEST_SKILL_NAMES` (sdk-init.ts) but missing from `packages/squad-sdk/templates/skills/`. The install loop silently skipped them with `if (storage.existsSync(srcSkill))`, so every `squad init` produced an install with these two skills absent. The trigger phrase `squad commands` was a dead no-op for every v0.10.0 user.
13+
14+
2. **#1264** — `tiered-memory`, `iterative-retrieval`, and `reflect` skill files existed in both templates dirs but were never added to `MANIFEST_SKILL_NAMES`, so they never installed either. Additionally, `tiered-memory/SKILL.md` claimed `confidence: high` and `source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads)` — the referenced repository does not exist and the measurement table at the bottom of the SKILL contained fabricated numbers. The SKILL also referenced `docs/tiered-memory-guide.md`, which does not exist.
15+
16+
3. The previously-merged cross-squad fix (#1291) updated `cross-squad/SKILL.md` content but never added it to `MANIFEST_SKILL_NAMES`, so it also never installed.
17+
18+
**Fix**
19+
20+
- **Source of truth.** Added the 5 missing skill directories to `.squad/skills/` (`squad-commands`, `squad-version-check`, `tiered-memory`, `iterative-retrieval`, `reflect`). The pre-existing `sync-skill-templates.mjs` runs in `prebuild` and propagates them to both `packages/squad-cli/templates/skills/` and `packages/squad-sdk/templates/skills/`.
21+
22+
- **`MANIFEST_SKILL_NAMES`** grew from 10 → 14 entries: added `tiered-memory`, `iterative-retrieval`, `reflect`, `cross-squad`.
23+
24+
- **Anti-regression guard.** The install loop in `sdk-init.ts` now collects missing skill source dirs and `throw`s with a clear remediation message (`Run \`node scripts/sync-skill-templates.mjs\``) instead of silently skipping. This is what would have surfaced #1289 at build time instead of in user installs.
25+
26+
- **Provenance honesty.** `tiered-memory/SKILL.md` rewritten to:
27+
- Frontmatter: `confidence: design (runtime not yet implemented)` + `source: design proposal`
28+
- Added prominent "Status (v0.10.0)" callout linking to #1264 for the runtime gap
29+
- Removed the fabricated `tamirdresher/tamresearch1` measurement table
30+
- Removed reference to non-existent `docs/tiered-memory-guide.md`
31+
- References section now points to real issues (#1264, #686, #600)
32+
33+
- **Test guard.** New regression test in `test/init.test.ts` (`should install every manifest-curated skill`) asserts every entry in the expected manifest list ends up at `.copilot/skills/{name}/SKILL.md` after `initSquad()`.
34+
35+
**Out of scope (tracked separately)**
36+
37+
The tiered-memory runtime (storage scaffolding under `.squad/memory/hot|cold|wiki/`, Scribe promotion logic, spawn-template tier-aware reads) remains tracked in #1264. This change lands the install-time fixes; runtime work follows in a separate PR.
38+
39+
The comprehensive `cross-squad-communication` plugin from `tamirdresher/squad-skills` is also separate; this change just adds the existing upstream `cross-squad` skill to the manifest so users get the registry-aware version that landed with #1291.
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
---
4+
5+
docs: clarify in `init.ts` and `.gitattributes` / `.gitignore` generators that `.squad/casting/*` files are authoritative identity (registry + history), NOT mutable two-layer state. They belong on `main`, must be committed, and should NOT receive a `merge=union` driver or be added to `.gitignore`. Pure comment additions — no runtime behavior change.
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
"@bradygaster/squad-sdk": patch
3+
"@bradygaster/squad-cli": patch
4+
---
5+
6+
fix: conditional .gitignore entries for two-layer/orphan state backends
7+
8+
When the state backend is `two-layer` or `orphan`, `squad init` and `squad upgrade` now add `.squad/decisions.md` and `.squad/agents/*/history.md` to `.gitignore` (delimited by `# Squad: state owned by squad-state branch` marker comments). When the backend is switched back to `local`, the marker block is removed so those files become committable again.
9+
10+
Defense-in-depth complement to the existing pre-commit hook — prevents `git add .`, IDE "stage all", and `git add -A` from silently staging two-layer state into the working tree.
Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
"@bradygaster/squad-sdk": minor
3+
"@bradygaster/squad-cli": minor
4+
---
5+
6+
Move bundled skills from `.copilot/skills/` to `.github/skills/` so they're visible to all Copilot surfaces (closes #1126)
7+
8+
## Symptom (per #1126)
9+
10+
Squad-bundled skills installed at `.copilot/skills/` are **invisible to every Copilot surface except Squad itself**:
11+
- ❌ GitHub Copilot cloud agent
12+
- ❌ Copilot CLI (outside Squad sessions)
13+
- ❌ VS Code Copilot extension (agent mode)
14+
- ❌ `@copilot` coding agent on issues
15+
- ❌ Any future Copilot surface
16+
17+
Per the [official Agent Skills docs](https://docs.github.com/en/copilot/concepts/agents/about-agent-skills), [add-skills docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/add-skills), and [VS Code docs](https://code.visualstudio.com/docs/copilot/customization/agent-skills), the canonical **project-level** custom-skills location is `.github/skills/`. `.copilot/skills/` at repo root is not recognized by any Copilot surface — the home-directory equivalent `~/.copilot/skills/` IS recognized for **personal** skills, which is the source of the original mistake.
18+
19+
## Fix
20+
21+
1. **`squad init`** writes bundled skills to `.github/skills/{name}/SKILL.md` (was `.copilot/skills/`).
22+
2. **`squad upgrade`** does the same AND auto-migrates legacy `.copilot/skills/{manifest-skill}/` into `.github/skills/{manifest-skill}/` (best-effort, preserves user-added non-manifest skills at `.copilot/skills/`, tombstones the legacy dir when empty).
23+
3. **`TEMPLATE_MANIFEST`** destinations rewritten: all 10 skill entries now target `../.github/skills/` instead of `../.copilot/skills/`.
24+
4. **`ENSURE_DIRECTORIES`** (upgrade.ts) updated so existing squads get `.github/skills/` created on upgrade.
25+
5. **squad.agent.md** narrative updated: 5-path scan order now lists `.github/skills/` as path #2 (Copilot CLI's canonical custom-skills location) and `.copilot/skills/` as path #3 (Legacy install path; `squad upgrade` migrates). Personal scope (`~/.copilot/skills/`) preserved as-is.
26+
6. **All other docs** (`spawn-reference.md`, `README.md`, `squad-commands` skill, `release-process` skill, `build.ts`, SDK type comments) updated to reference `.github/skills/` as the install destination.
27+
28+
## Migration semantics (`squad upgrade`)
29+
30+
`migrateLegacyCopilotSkills()` runs **before** `syncAllSkills`:
31+
32+
| Scenario | Migration action | User-added skills at `.copilot/skills/` |
33+
|---|---|---|
34+
| `.copilot/skills/{manifest-skill}/` exists, `.github/skills/{manifest-skill}/` does NOT | Move legacy → new; remove legacy | Untouched |
35+
| `.copilot/skills/{manifest-skill}/` exists AND `.github/skills/{manifest-skill}/` exists | Tombstone legacy (new wins) | Untouched |
36+
| `.copilot/skills/my-custom-skill/` (NOT in TEMPLATE_MANIFEST) | Left alone | Preserved |
37+
| `.copilot/skills/` becomes empty after migration | Directory removed | n/a |
38+
39+
All migration steps are best-effort with try/catch — disk-write failures don't block upgrade.
40+
41+
## Tests
42+
43+
New regression tests:
44+
- `test/init.test.ts > should install Squad-bundled skills at .github/skills/...` — asserts canonical path, asserts legacy path is NOT created
45+
- `test/cli/upgrade.test.ts > should migrate manifest skills from .copilot/skills/ to .github/skills/` — asserts manifest skill moves, user-added skill preserved
46+
- `test/cli/upgrade.test.ts > should NOT clobber a customized .github/skills/{name} if the legacy copy exists` — asserts both-locations case tombstones legacy without losing the new
47+
48+
Updated existing tests:
49+
- `test/builtin-skills.test.ts` regex now matches `.github/skills/`
50+
- `test/cli/init.test.ts`, `test/init.test.ts`, `test/init-sdk.test.ts`, `test/cli/upgrade.test.ts`, `test/human-journeys.test.ts`, `test/repl-ux-fixes.test.ts`, `test/cli/init-upgrade-parity.test.ts` — install-path assertions updated to `.github/skills/`
51+
52+
**188/188 init/upgrade/builtin tests pass; `npm run lint` clean.**
53+
54+
## What's NOT changed (intentional)
55+
56+
- **`.copilot/skills/` scan path stays in `squad.agent.md`'s 5-path skill discovery** — the coordinator still discovers user-added skills at the legacy location for backward compat; only Squad-installed (manifest) skills migrate.
57+
- **`~/.copilot/skills/` (personal scope) is unchanged** — that's Copilot CLI's official personal-skills location and remains valid.
58+
- **`test/skill-source.test.ts`, `test/skills-export-import.test.cjs`, `test/tools.test.ts`, `test/skill-script-loader.test.ts`** are NOT touched — they test the runtime skill loader and tool behavior, which still supports `.copilot/skills/` as a valid scan path.
59+
60+
## Composability
61+
62+
- **Disjoint from #1292, #1293, #1295, #1297, #1298, #1300, #1301, #1302, #1303** — touches the same `TEMPLATE_MANIFEST` array as #1292/#1295/#1303 but only modifies the destination path, not the source or entry list. Conflicts on `MANIFEST_SKILL_NAMES` are trivial: take the union of skill names with the `../.github/skills/` destination from this PR.
63+
- This is the **canonical fix** for #1126; closes that issue.
64+
65+
## Out of scope (separate follow-ups)
66+
67+
- Backward-compat shim that adds a `.copilot/skills -> .github/skills` symlink. Not needed because users won't be looking at `.copilot/skills/` anymore once their tools find skills at `.github/skills/`. Filed as a follow-up if anyone reports broken muscle memory.
68+
- A `squad doctor --skills` check that warns when `.copilot/skills/` still has manifest skills after upgrade (suggesting the migration silently failed). Worth adding to the next maintenance pass.
Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
"@bradygaster/squad-cli": patch
3+
---
4+
5+
Fix #1296: stop writing `squad_state_<hash>` to `~/.copilot/mcp-config.json` on every `squad init` / `squad upgrade`
6+
7+
`squad init` (line 408 of `packages/squad-cli/src/cli/core/init.ts`) and `squad upgrade` (line 738 of `upgrade.ts`) unconditionally called `ensureSquadStateMcpInUserConfig`, which wrote a `squad_state_<hash>` entry to `~/.copilot/mcp-config.json` keyed by a stable hash of the project path. Every new `squad init` accumulated another entry in HOME with no garbage collection.
8+
9+
This contradicted the explicit iter-8 design intent documented at `packages/squad-cli/src/cli/core/mcp-root.ts:1-27`:
10+
11+
> *iter-7: wrote `squad_state_<hash>` into the user's HOME `~/.copilot/mcp-config.json`. That polluted HOME with one entry per Squad project and required a stale-entry GC that we never built. It also touched a file outside the project, which is surprising for `squad init` / `squad upgrade`.*
12+
>
13+
> *iter-8 flips it back inside the project: we write `squad_state` to a repo-root `.mcp.json` ... **No HOME modifications.***
14+
15+
The repo-root `.mcp.json` writes (init.ts:403 / upgrade.ts:728) already cover all documented Copilot CLI launch modes:
16+
17+
- ``copilot`` from the project root → walks up from cwd to git root, auto-loads `.mcp.json`
18+
- ``copilot -p`` from the project root → same `.mcp.json` is found
19+
20+
For ``copilot -p`` invocations launched from **outside** the project root, the right pattern is `--additional-mcp-config @.mcp.json` (already documented as the recommended pattern at init.ts:494).
21+
22+
**Changes**
23+
24+
- Removed the unconditional `ensureSquadStateMcpInUserConfig` call from `init.ts:408` and `upgrade.ts:738`. Replaced both with comments explaining the iter-8 design and pointing at #1296.
25+
- Removed the now-unused import from both files.
26+
- The function definition itself (`mcp-root.ts:178-228`) is **kept** — a future `squad doctor --mcp-prune` cleanup helper may want to inspect HOME for orphan entries. It's just no longer called from the init/upgrade auto-flow.
27+
28+
**Tests**
29+
30+
New regression test in `test/cli/init.test.ts`:
31+
32+
> `should NOT write any squad_state entries to ~/.copilot/mcp-config.json (regression: #1296)`
33+
34+
Isolates the developer's real HOME by setting `USERPROFILE`/`HOME` to a temp dir before init, then asserts no `squad_state*` keys appear under that temp HOME after init. The test passes only because the unconditional write is gone — previously this assertion would have failed.
35+
36+
All 40 existing init tests still pass; `npm run lint` clean.
37+
38+
**Cleanup**
39+
40+
A follow-up could add `squad doctor --mcp-prune` to walk `~/.copilot/mcp-config.json`, find `squad_state_<hash>` entries whose target directory no longer exists, and remove them. Out of scope for this fix.
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
"@bradygaster/squad-cli": minor
3+
"@bradygaster/squad-sdk": minor
4+
---
5+
6+
Fix #1299 (deep): Fact Checker gets the same plumbing as Rai — rich charter at init + state directory + policy template
7+
8+
PR #1300 (also #1299) fixed the documentation gap so the coordinator knows to roster Fact Checker. This PR fixes the **structural** gap behind it. Per user testing on 2026-06-13, even after #1300 the actual agent on disk is still a "name on disk with a 21-line placeholder" — three concrete problems:
9+
10+
| Piece | Rai before this PR | Fact Checker before this PR |
11+
|-------|--------------------|------------------------------|
12+
| `charter.md` at init | Generic 478-byte stub from `generateCharter()` | Generic 523-byte stub from `generateCharter()` |
13+
| Rich charter template usage | Only used by `squad upgrade` (never by `squad init`) | Same — never used by `squad init` |
14+
| `.squad/{name}/policy.md` | ✅ Seeded from `rai-policy.md` (4160 bytes) | ❌ Directory does not exist |
15+
| `.squad/{name}/audit-trail.md` | ✅ Seeded with append-only header | ❌ Directory does not exist |
16+
| `merge=union` in `.gitattributes` | ✅ `.squad/rai/audit-trail.md` | ❌ No entry for fact-checker |
17+
| `fact-checker-charter.md` distribution | n/a | Only in `packages/squad-cli/templates/` — missing from `.squad-templates/` (canonical source) AND `packages/squad-sdk/templates/`, so the SDK init path could never find it |
18+
19+
## Fix (4 parts)
20+
21+
### Part 1 — Rich charter at init (benefits BOTH Rai and Fact Checker)
22+
23+
`packages/squad-sdk/src/config/init.ts` agent loop now looks up `{templatesDir}/{role}-charter.md` for each agent and uses that as `charter.md` content if it exists. Falls back to `generateCharter()` for user-defined agents that have no rich template (everyone except the built-ins).
24+
25+
Result: a fresh `squad init` produces `.squad/agents/Rai/charter.md` with the full Rai charter (4525 bytes) and `.squad/agents/fact-checker/charter.md` with the full Fact Checker charter (3024 bytes). Previously both were 478-byte stubs.
26+
27+
### Part 2 — `.squad/fact-checker/` state dir, mirroring `.squad/rai/`
28+
29+
Added a new block in `init.ts` (right after the Rai seeding at lines 879–941) that creates:
30+
31+
- `.squad/fact-checker/policy.md` — seeded from `templates/fact-checker-policy.md` (or a minimal inline fallback if the template is stripped)
32+
- `.squad/fact-checker/audit-trail.md` — seeded with an append-only header
33+
34+
The policy template (`.squad-templates/fact-checker-policy.md`, ~6 KB) is the canonical authority for the dual-mode operating rules per #789 + #1254:
35+
36+
- **Mode 1 Verification:** confidence rating taxonomy (✅/⚠️/❌/🔍), what gets checked (URLs, packages, APIs, file paths, signatures, quotes, statistics, cross-references)
37+
- **Mode 2 Devil's Advocate:** required brief structure (steelman → assumptions → pre-mortem → alternatives → risk acceptance)
38+
- **Hard rules:** anti-fabrication guarantees — never cite unverified URL/package/API, never invent measurement data, never fabricate counter-hypotheses, never block on opinion
39+
- **Advisory by default** with two narrow blocking exceptions (❌ at Pre-Ship; coordinator-escalated DA risk)
40+
- **Opt-out model** mirroring Rai's
41+
- **Audit trail rules** — succinct (verdict + citation, never raw source material)
42+
- **Reviewer Rejection Protocol integration** for ❌ Contradicted verdicts
43+
44+
### Part 3 — Fix the `.squad-templates/` distribution gap
45+
46+
The existing `fact-checker-charter.md` had been added directly to `packages/squad-cli/templates/` only, bypassing the canonical `.squad-templates/` source. That meant `sync-templates.mjs` couldn't propagate it to `packages/squad-sdk/templates/` (which `getSDKTemplatesDir()` resolves at runtime), so the SDK init code path could never find the rich charter even if it tried.
47+
48+
Fix: copied `fact-checker-charter.md` to `.squad-templates/` and re-synced. Now all 4 mirror targets have it. This unblocks Part 1.
49+
50+
### Part 4 — Plumbing updates
51+
52+
- `.gitattributes` block: added `.squad/fact-checker/audit-trail.md merge=union` alongside Rai's existing entry
53+
- `packages/squad-cli/src/cli/core/templates.ts`: new `TEMPLATE_MANIFEST` entry for `fact-checker-policy.md → templates/fact-checker-policy.md` so `squad upgrade` propagates it
54+
- `.squad-templates/squad.agent.md` Files Catalog table: 2 new rows for `.squad/fact-checker/policy.md` (authoritative) and `.squad/fact-checker/audit-trail.md` (derived/append-only)
55+
56+
## Tests
57+
58+
`test/init.test.ts` gains 3 regression tests (28/28 pass total):
59+
60+
1. `should seed .squad/fact-checker/{policy,audit-trail}.md (regression: bradygaster/squad#1299)` — asserts policy declares both modes + anti-fabrication rules + confidence ratings; audit trail is append-only.
61+
2. `should use the rich fact-checker-charter.md template for built-in agents at init (#1299)` — asserts the rendered charter is > 1 KB (not the 478-byte stub) and contains Verification Methodology + Confidence Ratings.
62+
3. `should use the rich Rai-charter.md template at init (companion to fact-checker fix, #1299)` — asserts Rai gets the same treatment; charter references `.squad/rai/policy.md` and `.squad/rai/audit-trail.md`.
63+
64+
`npm run lint` clean.
65+
66+
## Composability
67+
68+
This PR builds on #1300 (which adds the `## Fact Checker` section to `squad.agent.md` and the "team size" line fix). Both modify `.squad-templates/squad.agent.md` but in **disjoint regions**:
69+
70+
- #1300 touches the team-size line at L56 and inserts a new `## Fact Checker` section before `## PRD Mode`
71+
- #1301 touches the Files Catalog table at L710-711
72+
73+
They will merge cleanly in either order. The user-facing experience requires BOTH to land for full plumbing.
74+
75+
## Closes / refs
76+
77+
Closes #1299 (deep fix; #1300 was the surface fix).

0 commit comments

Comments
 (0)