feat: add extension-fragments mechanism for coordinator plugins#1124
Draft
sabbour wants to merge 1 commit into
Draft
feat: add extension-fragments mechanism for coordinator plugins#1124sabbour wants to merge 1 commit into
sabbour wants to merge 1 commit into
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a coordinator “extension fragments” prompt mechanism for plugin-provided context, while also expanding the GitHub App identity system (SDK identity module, token resolver canonicalization, and GH_TOKEN injection during agent spawn) along with extensive new tests and docs.
Changes:
- Add “Extension Fragments” guidance to the coordinator prompt plus a plugin author guide for installing fragments via postinstall scripts.
- Add/expand identity capabilities (SDK identity module exports, CLI
identitycommand wiring, GH_TOKEN injection duringspawnAgent, and a canonicalresolve-token.mjsgenerator + CI guards). - Add a large suite of identity- and template-synchronization regression tests and supporting documentation.
Reviewed changes
Copilot reviewed 91 out of 100 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| vitest.config.ts | Raises global test timeout to accommodate slower integration-style tests. |
| test/scripts/resolve-token-sync.test.ts | CI guard ensuring all resolve-token.mjs template copies stay in sync with the canonical source. |
| test/identity/sync-resolve.test.ts | Tests resolveTokenSync cache-only behavior and mock parity. |
| test/identity/storage.test.ts | Covers identity config/app registration storage helpers. |
| test/identity/spawn-token-injection.test.ts | Verifies spawnAgent GH_TOKEN injection + restoration. |
| test/identity/role-slugs.test.ts | Tests role title → canonical identity slug mapping. |
| test/identity/resolve-token-root.test.ts | Validates resolve-token.mjs derives project root from script location, not cwd. |
| test/identity/no-token-disclosure.test.ts | Regression guard preventing partial token logging in e2e script. |
| test/identity/manifest-timeout.test.ts | Adds timeout-related tests for manifest flow (currently does not exercise production code). |
| test/identity/key-age.test.ts | Tests key age reporting helper (getKeyAgeDays). |
| test/identity/identity-menu-choices.test.ts | Regression guard for identity menu option handling. |
| test/identity/gitignore-keys.test.ts | Ensures .gitignore ignores .squad/identity/keys/. |
| test/identity/formatting.test.ts | Tests comment/commit formatting utilities. |
| test/identity/explain.test.ts | Tests squad identity explain JSON output and masking behavior. |
| test/identity/exec.test.ts | Tests execWithRoleToken / withRoleToken GH_TOKEN lifecycle behavior. |
| test/identity/dedup.test.ts | Tests concurrent token resolution deduplication behavior. |
| templates/squad.agent.md.template | Updates agent template with identity block + identity resolution guidance. |
| templates/scripts/resolve-token.mjs | Generated standalone token resolver copy for templates. |
| scripts/sync-templates.mjs | Skips scripts/resolve-token.mjs because it’s owned by a dedicated generator. |
| packages/squad-sdk/templates/squad.agent.md.template | SDK template copy of agent prompt (currently diverges from canonical template re: token-in-URL pattern). |
| packages/squad-sdk/templates/scripts/resolve-token.mjs | Generated resolver script copy for SDK templates. |
| packages/squad-sdk/src/index.ts | Exports identity module from the SDK barrel. |
| packages/squad-sdk/src/identity/types.ts | Adds identity types/constants (tiers, roles, config, formatting inputs). |
| packages/squad-sdk/src/identity/storage.ts | Adds sync identity config/app registration/key checks and key age helper. |
| packages/squad-sdk/src/identity/role-slugs.ts | Adds role title → slug resolution table (header comment currently says “8” slugs). |
| packages/squad-sdk/src/identity/index.ts | Public identity module entrypoint (types + helpers + token APIs + exec helpers). |
| packages/squad-sdk/src/identity/formatting.ts | Adds comment/commit formatting helpers with role-based emoji prefixes. |
| packages/squad-sdk/src/identity/exec.ts | Adds execWithRoleToken / withRoleToken helpers that manage GH_TOKEN lifecycle. |
| packages/squad-sdk/src/config/init.ts | Ensures .squad/scripts directory is created during init. |
| packages/squad-sdk/package.json | Adds ./identity export and updates package version (currently set to a prerelease build). |
| packages/squad-cli/templates/squad.agent.md.template | CLI template copy of agent prompt with identity guidance. |
| packages/squad-cli/templates/scripts/resolve-token.mjs | Generated resolver script copy for CLI templates. |
| packages/squad-cli/src/cli/shell/spawn.ts | Injects GH_TOKEN per spawned agent role (sync cache-first, async fallback, restore in finally). |
| packages/squad-cli/src/cli/index.ts | Re-exports runIdentity. |
| packages/squad-cli/src/cli/core/templates.ts | Adds scripts/resolve-token.mjs to the init/upgrade template manifest. |
| packages/squad-cli/src/cli-entry.ts | Wires new squad identity command entrypoint. |
| packages/squad-cli/scripts/sync-resolve-token.mjs | Generator to propagate canonical resolver into all template directories (+ --check mode). |
| packages/squad-cli/scripts/resolve-token.source.mjs | Canonical source for resolve-token.mjs. |
| package.json | Runs resolver sync in prebuild and adds sync:resolve-token scripts. |
| docs/reviews/pr-27-identity-consistency-review-2026-04-21.md | Adds historical review artifact documentation. |
| docs/reviews/pr-25-canonicalization-review-2026-04-21.md | Adds historical review artifact documentation. |
| docs/reviews/pr-23-retry-review-2026-04-21.md | Adds historical review artifact documentation. |
| docs/proposals/avatars/README.md | Documents role avatar assets guidance. |
| docs/plugins/squad-coordinator-extensions.md | New plugin author guide for coordinator extension fragments. |
| docs/identity/token-precedence.md | Documents GH_TOKEN vs GITHUB_TOKEN precedence and troubleshooting. |
| docs/identity/retry-policy.md | Documents identity retry policy contract. |
| docs/identity/maintaining-resolve-token.md | Documents how to maintain canonical resolver + generator workflow. |
| .squad/decisions/inbox/flight-pr23-verdict.md | Adds decision inbox artifact. |
| .squad/decisions/inbox/flight-pr21-review.md | Adds decision inbox artifact. |
| .squad/decisions/inbox/fido-resolve-token-canonical.md | Adds decision inbox artifact for resolver canonicalization. |
| .squad/decisions/inbox/eecom-identity-quick-wins.md | Adds decision inbox artifact. |
| .squad/decisions/inbox/eecom-h14-key-age.md | Adds decision inbox artifact. |
| .squad/decisions/inbox/eecom-h12-dedup.md | Adds decision inbox artifact. |
| .squad/decisions.md | Appends multiple decisions, including a “no prerelease versions on dev/main” policy. |
| .squad/agents/flight/history.md | Adds historical review notes. |
| .squad/agents/eecom/history.md | Adds implementation/review learnings history. |
| .squad-templates/squad.agent.md | Canonical agent governance template updated with identity guidance. |
| .squad-templates/scripts/resolve-token.mjs | Generated resolver script copy for canonical templates. |
| .gitignore | Adds .squad/identity/keys/ ignore rule. |
| .github/agents/squad.agent.md | Updates coordinator governance doc; currently diverges from canonical template and includes token-in-URL pattern. |
| .copilot/skills/injectable-random/SKILL.md | Documents deterministic randomness seam pattern. |
| .changeset/wire-gh-token-spawn.md | Changeset for GH_TOKEN spawn injection feature. |
| .changeset/team-aware-identity-create.md | Changeset for team-aware identity create behavior. |
| .changeset/identity-token-precedence-docs.md | Changeset for token precedence docs. |
| .changeset/identity-token-lifecycle.md | Changeset for identity lifecycle features. |
| .changeset/identity-rotate-command.md | Changeset for identity rotate command. |
| .changeset/identity-retry-resilience.md | Changeset for identity retry resilience. |
| .changeset/identity-module.md | Changeset for adding the identity module. |
| .changeset/identity-import-multi-repo.md | Changeset for import/multi-repo identity flow. |
| .changeset/identity-hardening.md | Changeset for identity hardening items. |
| .changeset/identity-doctor-explain.md | Changeset for doctor/explain commands. |
| .changeset/identity-dedup-key-age.md | Changeset for dedup/key-age/sync resolver. |
| .changeset/identity-consistency-fix.md | Changeset for identity consistency fixes. |
| .changeset/gitignore-identity-secrets.md | Changeset for .gitignore identity secret rules. |
| .changeset/exec-with-role-token.md | Changeset for exec/withRoleToken helpers. |
| .changeset/env-var-credentials.md | Changeset for env-var based identity credentials. |
| .changeset/canonicalize-resolve-token.md | Changeset for resolver canonicalization. |
| .changeset/auto-install-app.md | Changeset for auto-install app flow. |
Comments suppressed due to low confidence (2)
.github/agents/squad.agent.md:543
test/template-sync.test.tsenforces that.github/agents/squad.agent.mdis byte-for-byte identical to.squad-templates/squad.agent.md(and the other mirrored template copies). This new “Extension Fragments” section makes.github/agents/squad.agent.mddiverge from the canonical template, so the template-sync CI test will fail unless the canonical.squad-templates/squad.agent.mdand all mirrors are updated to include the exact same content.
### Extension Fragments
Extension fragments let MCP packages, domain tools, and team-specific plugins extend your Squad coordinator context without forking or editing `squad.agent.md` directly. Changes survive Squad upgrades.
#### Where fragments live
.github/agents/squad.agent.md:541
- PR description/title focus on coordinator “extension fragments”, but this PR also introduces substantial identity/GH_TOKEN injection changes (new identity module/tests, template updates, CLI spawn behavior, package version change, etc.). Please either update the PR description to cover the full scope or split the unrelated identity work into a separate PR to keep review/rollback risk manageable.
### Extension Fragments
Extension fragments let MCP packages, domain tools, and team-specific plugins extend your Squad coordinator context without forking or editing `squad.agent.md` directly. Changes survive Squad upgrades.
Comment on lines
1
to
6
| { | ||
| "name": "@bradygaster/squad-sdk", | ||
| "version": "0.9.1", | ||
| "version": "0.9.1-build.5", | ||
| "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot", | ||
| "type": "module", | ||
| "main": "./dist/index.js", |
Comment on lines
+343
to
+345
| {only if identity configured:} | ||
| GIT IDENTITY: Commit as `{app_slug}[bot]`. Push with token: `TOKEN=$(node {team_root}/.squad/scripts/resolve-token.mjs '{role_slug}'); if [ -n "$TOKEN" ]; then git push https://x-access-token:${TOKEN}@github.com/{owner}/{repo}.git {branch}; else git push; fi`. PR: `if [ -n "$TOKEN" ]; then GH_TOKEN=$TOKEN gh pr create --repo {owner}/{repo} ...; else gh pr create ...; fi`. PR body: `🤖 [{app_slug}](https://github.com/apps/{app_slug})`. | ||
| {end identity block} |
Comment on lines
+1
to
+6
| /** | ||
| * Identity Module — Role slug mapping | ||
| * | ||
| * Maps role titles/patterns to the 8 canonical identity slugs. | ||
| * Used to resolve which GitHub App identity an agent should use. | ||
| * |
Add a generic, repeatable extension mechanism so MCP packages and domain tools can extend Squad coordinator context without forking or editing squad.agent.md. Changes: - squad.agent.md: new '### Extension Fragments' section after MCP Integration. Defines scan dirs (~/.squad/extensions/coordinator/ and <repo>/.squad/extensions/coordinator/), fragment YAML front matter shape, loading rules, and anti-patterns. - squad.agent.md: Source of Truth table updated with extension-fragments row. - docs/plugins/squad-coordinator-extensions.md: full plugin-author guide covering fragment format, style rules, postinstall pattern, idempotency contract, user override, and upgrade story. Motivation: @sabbour/squadboard ships a coordinator fragment that tells Squad how to use Squadboard MCP tools. Without a stable install path, every Squad upgrade overwrites that knowledge. This mechanism gives squadboard (and any future plugin — Trello, Aspire, Notion, etc.) a repeatable, upgrade-safe home. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
sabbour
force-pushed
the
feat/extension-fragments
branch
from
8c61e3d to
ad8b366
Compare
Author
|
♻️ Force-pushed clean diff — was 100 files/+14,863 due to 8 stale identity-WIP commits (#21–#27 had already been merged to |
sabbour
commented
May 16, 2026
Comment on lines
+582
to
+599
| A minimal squadboard fragment example: | ||
|
|
||
| ```markdown | ||
| --- | ||
| name: squadboard | ||
| version: 0.1.0 | ||
| extends: squad | ||
| inject_into: [after-mcp-detection] | ||
| --- | ||
|
|
||
| ## Squadboard Integration | ||
|
|
||
| If tools with the `squadboard_` prefix exist, Squadboard is installed. Use: | ||
| - `squadboard_capture` — drop a directive into the board inbox | ||
| - `squadboard_list_issues` — read the backlog | ||
| ``` | ||
|
|
||
| Install the fragment via a postinstall script to `~/.squad/extensions/coordinator/squadboard.md`. See [docs/plugins/squad-coordinator-extensions.md](../../docs/plugins/squad-coordinator-extensions.md) for the full authoring guide and postinstall pattern. |
Author
There was a problem hiding this comment.
Probably better as a commented example
sabbour
commented
May 16, 2026
|
|
||
| Install: `npm install -g @sabbour/squadboard` → fragment auto-installs to `~/.squad/extensions/coordinator/squadboard.md`. | ||
|
|
||
| See [`packages/server/coordinator-fragment.md`](https://github.com/asabbour/squadboard/blob/main/packages/server/coordinator-fragment.md) for the full source. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds a generic, repeatable extension mechanism so MCP packages and domain tools can extend the Squad coordinator's context without forking
squad.agent.mdor having their knowledge wiped on every Squad upgrade.Why
@sabbour/squadboard(and any Trello, Aspire, Azure, Notion plugin) needs a stable way to tell Squad how to use its MCP tools. Right now, users either hand-editsquad.agent.md(overwritten on upgrade) or lose the integration entirely. This mechanism fixes that.What changed
.github/agents/squad.agent.mdAdded
### Extension Fragmentssection after the existing MCP Integration section:~/.squad/extensions/coordinator/*.md(user-global) and<repo>/.squad/extensions/coordinator/*.md(project-local, overrides same-filename user-global).name,version,extends: squad,inject_intodirectives.Updated Source of Truth Hierarchy table to include the extension-fragments row.
docs/plugins/squad-coordinator-extensions.md(new)Full plugin-author guide:
@sabbour/squadboardas reference implementationExample fragment
Installed by
@sabbour/squadboardpostinstall to~/.squad/extensions/coordinator/squadboard.md.Contract version
This establishes Squad extension contract v1. Future Squad releases should treat
~/.squad/extensions/coordinator/as a stable install target and not remove or ignore it during upgrades.Filed by Kobayashi (Squadboard SDK Integrator) — Wave 18, 2026-05-15.