Skip to content

feat(skills): make /squad a real slash command (user-invocable: true + rename squad-commands → squad) - #1303

Merged
tamirdresher merged 2 commits into
github:devfrom
tamirdresher:squad/skills-userinvocable-slash
Jun 13, 2026
Merged

feat(skills): make /squad a real slash command (user-invocable: true + rename squad-commands → squad)#1303
tamirdresher merged 2 commits into
github:devfrom
tamirdresher:squad/skills-userinvocable-slash

Conversation

@tamirdresher

@tamirdresher tamirdresher commented Jun 13, 2026

Copy link
Copy Markdown
Collaborator

"@bradygaster/squad-sdk": minor
"@bradygaster/squad-cli": minor

Make /squad a real slash command — rename squad-commands skill to squad with user-invocable: true

What this enables

Users can type /squad in any Copilot CLI session in a squad-initialized project and get the categorized command catalog (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State). This is what users naturally expect — Squad ships an in-chat command surface, and the slash key is the muscle memory.

Verified mechanism (Copilot CLI 1.0.62-2)

Decompiling ~/.copilot/pkg/win32-x64/1.0.62-2/sdk/index.js line 2618:

getLoadedSkills().filter(e => e.userInvocable)
  .map(e => ({name: `/${eF(e)}`, isSkill: true, skill: e}))

Any skill with frontmatter user-invocable: true is auto-registered by Copilot CLI as a slash command at /<skill-name>. The built-in customize-cloud-agent skill shipped with Copilot CLI uses this exact pattern with user-invocable: false; setting it to true makes the skill appear in /skills AND as a slash keystroke.

The previous skill squad-commands had no user-invocable field (Copilot CLI defaults to false), so /squad-commands did not exist. Users either typed natural language ("squad commands", "what can squad do") or never discovered the menu.

Changes

  1. Renamed the squad-commands skill to squad (canonical source in .squad/skills/squad/).
  2. Frontmatter rewritten to match Copilot CLI's actual schema (verified against decompiled source):
    • name: squad (was squad-commands — /squad is shorter, intuitive, and matches the agent name without colliding because slash commands and skill lookups are separate namespaces)
    • user-invocable: true ← the load-bearing change
    • description: rewritten to be self-explanatory so natural-language match also still works
    • allowedTools: [] (matches Copilot CLI's schema)
    • Removed unused fields: domain:, confidence:, source:, triggers: (all silently ignored by Copilot CLI)
  3. Body text updated to reference /squad as the primary invocation path.
  4. MANIFEST_SKILL_NAMES in packages/squad-sdk/src/config/init.ts: 'squad-commands' → 'squad'.
  5. TEMPLATE_MANIFEST in packages/squad-cli/src/cli/core/templates.ts: updated source + destination + description to reflect the rename.
  6. Removed stale packages/{squad-cli,squad-sdk}/templates/skills/squad-commands/ directories.

Test coverage

New test/init.test.ts > should install the squad slash-command skill with user-invocable: true:

  • Asserts .copilot/skills/squad/SKILL.md exists after initSquad()
  • Asserts frontmatter contains user-invocable: true (load-bearing — without this, no slash command)
  • Asserts frontmatter name: squad (load-bearing — slash command is /<name>)
  • Asserts the menu presentation rules are still in the body

26/26 init tests pass; npm run lint clean.

How users will experience this

After squad init + opening Copilot CLI in the project:

> /squad
📋 Squad Commands — pick a category:
  1. Install & Upgrade
  2. Team Management
  3. Issues & PRs
  4. Plugins & Skills
  5. Model & Cost
  6. Sessions & State

Composability with other open PRs

Out of scope (future, mentioned in user request)

The user wants to eventually install the squad skill machine-wide (e.g., ~/.copilot/skills/squad/) so /squad init works in any folder even before squad is initialized in that project. That's a separate piece of work because:

  1. It requires a squad install --global-skill command or similar (none exists today)
  2. The /squad menu currently calls into squad CLI subcommands that assume .squad/ exists in cwd — the menu would need a "Init Mode" branch for the "no .squad/ yet" case
  3. Copilot CLI's ~/.copilot/skills/ is a personal scope, so it'd need to be opt-in per-user

Will file a follow-up issue tracking that work after this lands.

Copilot AI review requested due to automatic review settings June 13, 2026 11:31
@github-actions

github-actions Bot commented Jun 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🟠 Impact Analysis — PR #1303

Risk tier: 🟠 HIGH

📊 Summary

Metric Count
Files changed 12
Files added 3
Files modified 9
Files deleted 0
Modules touched 7

🎯 Risk Factors

  • 12 files changed (6-20 → MEDIUM)
  • 7 modules touched (5-8 → HIGH)

📦 Modules Affected

ci-workflows (1 file)
  • .github/agents/squad.agent.md
root (2 files)
  • .changeset/fix-squad-slash-command.md
  • templates/squad.agent.md.template
squad-cli (3 files)
  • packages/squad-cli/src/cli/core/templates.ts
  • packages/squad-cli/templates/skills/squad/SKILL.md
  • packages/squad-cli/templates/squad.agent.md.template
squad-sdk (3 files)
  • packages/squad-sdk/src/config/init.ts
  • packages/squad-sdk/templates/skills/squad/SKILL.md
  • packages/squad-sdk/templates/squad.agent.md.template
squad-state (1 file)
  • .squad/skills/squad/SKILL.md
templates (1 file)
  • .squad-templates/squad.agent.md
tests (1 file)
  • test/init.test.ts

This report is generated automatically for every PR. See #733 for details.

@github-actions

github-actions Bot commented Jun 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🛫 PR Readiness Check

ℹ️ This comment updates on each push. Last checked: commit 93d67da

PR Scope: 📦🔧 Mixed (product + infrastructure)

⚠️ 4 item(s) to address before review

Status Check Details
❌ Single commit 2 commits — consider squashing before review
✅ Not in draft Ready for review
✅ Branch up to date Up to date with dev
❌ Copilot review No Copilot review yet — it may still be processing
✅ Changeset present Changeset file found
✅ Scope clean ⚠️ PR includes 1 .squad/ file(s) — ensure these are intentional
✅ No merge conflicts No merge conflicts
❌ Copilot threads resolved 1 unresolved Copilot thread(s) — fix and resolve before merging
❌ CI passing 6 check(s) still running

Files Changed (12 files, +720 −34)

File +/−
.changeset/fix-squad-slash-command.md +76 −0
.github/agents/squad.agent.md +1 −1
.squad-templates/squad.agent.md +1 −1
.squad/skills/squad/SKILL.md +6 −10
packages/squad-cli/src/cli/core/templates.ts +3 −3
packages/squad-cli/templates/skills/squad/SKILL.md +299 −0
packages/squad-cli/templates/squad.agent.md.template +1 −1
packages/squad-sdk/src/config/init.ts +1 −1
packages/squad-sdk/templates/skills/squad/SKILL.md +299 −0
packages/squad-sdk/templates/squad.agent.md.template +1 −1
templates/squad.agent.md.template +1 −1
test/init.test.ts +31 −15

Total: +720 −34

This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.

@github-actions

github-actions Bot commented Jun 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

⚠️ Squad File Leakage Detected

The following .squad/ files were modified in this PR:

  • .squad/skills/squad/SKILL.md

These files affect team routing, agent charters, and decisions.
If intentional, ensure approval from the team lead.

@github-actions

github-actions Bot commented Jun 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🏗️ Architectural Review

⚠️ Architectural review: 1 warning(s).

Severity Category Finding Files
🟡 warning bootstrap-area 1 file(s) in the bootstrap area (packages/squad-cli/src/cli/core/) were modified. These files must maintain zero external dependencies. Review carefully. packages/squad-cli/src/cli/core/templates.ts

Automated architectural review — informational only.

tamirdresher pushed a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
Copilot Copilot
Merge PR github#1303: /squad slash command (user-invocable: true + re…
37900a3 
…name)

# Conflicts:
#	test/init.test.ts
Copilot AI reviewed Jun 13, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR makes the built-in “command catalog” skill user-invocable as /squad by renaming the former squad-commands skill to squad, updating the init/upgrade manifests, and adding a regression test to assert the required frontmatter is installed.

Changes:

  • Rename squad-commands → squad and add user-invocable: true in the skill frontmatter so Copilot CLI can register /squad.
  • Update SDK init manifest and CLI template manifest to install/upgrade the new squad skill path.
  • Add an init regression test ensuring the installed SKILL.md contains user-invocable: true and name: squad.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
test/init.test.ts Adds regression coverage asserting the installed squad skill frontmatter enables /squad.
packages/squad-sdk/templates/skills/squad/SKILL.md Adds the renamed squad skill template (SDK side) with user-invocable: true.
packages/squad-sdk/src/config/init.ts Updates MANIFEST_SKILL_NAMES to install squad instead of squad-commands.
packages/squad-cli/templates/skills/squad/SKILL.md Adds the renamed squad skill template (CLI side) with user-invocable: true.
packages/squad-cli/src/cli/core/templates.ts Updates upgrade template manifest entry to copy skills/squad/SKILL.md into .copilot/skills/squad/.
.squad/skills/squad/SKILL.md Renames canonical skill source content + frontmatter to squad and makes it user-invocable.
.changeset/fix-squad-slash-command.md Adds a changeset documenting the rename and slash-command behavior.

Comment thread packages/squad-sdk/src/config/init.ts
Comment on lines 38 to 42
'test-discipline',
'agent-collaboration',
'squad-commands',
'squad',
'squad-version-check',
] as const;
@tamirdresher tamirdresher mentioned this pull request Jun 13, 2026
Merged
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
fix(squad.agent.md): update squad-commands → squad skill xref
7bfd64b 
Follow-up to reviewer comment on github#1303: when this PR renamed
'.copilot/skills/squad-commands/SKILL.md' to '.copilot/skills/squad/SKILL.md'
(to make /squad a real user-invocable slash command), the routing-table
entry inside squad.agent.md still pointed at the old path. Coordinators
loading squad.agent.md from a freshly upgraded squad would have followed
a dead reference and reported 'skill not found'.

Updated the row in all 5 mirrored copies (.squad-templates, .github/agents,
packages/squad-cli/templates, packages/squad-sdk/templates, templates/).
Also added a hint that users can invoke the skill directly via /squad,
since that is now the documented surface for the same content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
fix: TEMPLATE_MANIFEST entry for cross-squad-communication + pattern …
f5415a2 
…numbering + honest source/validation

Five reviewer follow-ups on github#1295:

1. MANIFEST_SKILL_NAMES added 'cross-squad-communication' but
   TEMPLATE_MANIFEST didn't — 'squad upgrade' would skip the skill
   even though 'squad init' installed it. Added the missing entry to
   TEMPLATE_MANIFEST so upgrade syncs it like every other manifest
   skill. (Same drift bug pattern noted on github#1292/github#1303.)

2-3. Both SKILL.md files (companion 'cross-squad' and full
   'cross-squad-communication') said the skill covers 'the four
   communication patterns (sync CLI, async git-based, issue-based)'
   but only listed three — Pattern 1 (read-only knowledge query)
   was missing from the intro list. Rewrote both intro lines to
   spell out all four: Pattern 0 (sync CLI), Pattern 1 (read-only),
   Pattern 2 (git-based async), Pattern 3 (issue-based).

4. The doc had 'Pattern 4: Cross-Repo Dependency Scan' which broke
   the 'four numbered patterns 0-3' framing — Pattern 4 isn't a
   communication protocol, it's a one-off analysis utility for
   discovering how two repos relate. Moved it to a clearly labeled
   '### Appendix' section with a note explaining why it's not a
   numbered pattern.

5. Frontmatter 'source:' claimed the skill was 'validated against
   two production squad instances' but the Validation Status section
   said Patterns 2 and 3 were 'untested end-to-end'. Reworded
   'source:' to acknowledge that only Pattern 0 (and partially
   Pattern 1) are end-to-end-validated; Patterns 2/3 are documented
   from design and need live validation before production use.
   Also softened the same overclaim in the Validation Status prose
   (replaced 'validated against two production' with 'drafted
   against two prototype' + explicit acknowledgement that 2/3 are
   design-only).

All 3 mirrored copies of cross-squad-communication/SKILL.md and 3
copies of cross-squad/SKILL.md kept in sync (canonical = .squad/,
mirrors = packages/squad-cli/templates/, packages/squad-sdk/templates/).

Verified: 31/31 init + builtin-skills tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tamirdresher

tamirdresher commented Jun 13, 2026

Copy link
Copy Markdown
Collaborator Author

Reviewer thread addressed in commit 7bfd64b:

  • Broken xref to renamed skill — updated the squad.agent.md routing-table row that pointed at the old .copilot/skills/squad-commands/SKILL.md to point at .copilot/skills/squad/SKILL.md (the rename target of this PR), and added a hint that users can invoke the skill via /squad.

Applied to all 5 mirrored copies (.squad-templates, .github/agents, packages/squad-cli/templates, packages/squad-sdk/templates, templates/).

@tamirdresher tamirdresher mentioned this pull request Jun 13, 2026
Merged
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
Merge PR github#1303: /squad slash command (user-invocable: true + re…
83ec80b 
…name)

# Conflicts:
#	test/init.test.ts
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
Merge PR github#1303: /squad slash command
2b16eb7 
# Conflicts:
#	test/init.test.ts
bradygaster
bradygaster approved these changes Jun 13, 2026
View reviewed changes

@bradygaster bradygaster left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Flight approves. Promoting /squad to a real user-invocable slash command is the right UX surface and the rename is consistent.

Copilot @tamirdresher
feat(skills): make /squad a real slash command — rename squad-command…
b94cebe 
…s to squad with user-invocable:true

Users want /squad in Copilot CLI to show Squad's command catalog. Verified
via Copilot CLI 1.0.62-2 source (sdk/index.js line 2618):

  getLoadedSkills().filter(e => e.userInvocable)
    .map(e => ({name: \/\\, isSkill: true, skill: e}))

Any skill with frontmatter user-invocable: true is auto-registered as a
slash command at /<skill-name>. The previous skill 'squad-commands' had
no user-invocable field (Copilot CLI defaults to false), so /squad-commands
never existed and users had no slash entrypoint.

Changes:
* Renamed squad-commands -> squad (canonical .squad/skills/squad/)
* Frontmatter rewritten to Copilot CLI schema:
  - name: squad (was squad-commands)
  - user-invocable: true (the load-bearing change)
  - description: self-explanatory for natural-language match
  - allowedTools: []
  - Removed unused fields: domain:, confidence:, source:, triggers:
* Body updated to reference /squad as primary invocation
* MANIFEST_SKILL_NAMES updated
* TEMPLATE_MANIFEST updated (so squad upgrade syncs it too)
* Removed stale squad-commands template dirs from both packages

Tests: new test asserts user-invocable: true frontmatter AND name: squad
(both are load-bearing for the slash command to register). 26/26 init
tests pass. npm run lint clean.

Composability:
* Disjoint from github#1292 (skills bundling) - both touch MANIFEST_SKILL_NAMES
  but this is a rename not an add
* Disjoint from github#1302 (squad-help disambiguation) - that one covers the
  skill(Squad) misdirect, this one covers the /squad slash UX

Out of scope (future): machine-wide install (~/.copilot/skills/squad/)
so /squad init works in folders without .squad/ yet. Requires a
squad install --global-skill command + 'no .squad yet' menu branch.
Will file separate follow-up.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
fix(squad.agent.md): update squad-commands → squad skill xref
347d673 
Follow-up to reviewer comment on github#1303: when this PR renamed
'.copilot/skills/squad-commands/SKILL.md' to '.copilot/skills/squad/SKILL.md'
(to make /squad a real user-invocable slash command), the routing-table
entry inside squad.agent.md still pointed at the old path. Coordinators
loading squad.agent.md from a freshly upgraded squad would have followed
a dead reference and reported 'skill not found'.

Updated the row in all 5 mirrored copies (.squad-templates, .github/agents,
packages/squad-cli/templates, packages/squad-sdk/templates, templates/).
Also added a hint that users can invoke the skill directly via /squad,
since that is now the documented surface for the same content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tamirdresher
tamirdresher force-pushed the squad/skills-userinvocable-slash branch from 7bfd64b to 347d673 Compare June 13, 2026 16:44
@tamirdresher
fix(squad.agent.md): update squad-commands → squad skill xref
93d67da 
Follow-up to reviewer comment on github#1303: when this PR renamed
'.copilot/skills/squad-commands/SKILL.md' to '.copilot/skills/squad/SKILL.md'
(to make /squad a real user-invocable slash command), the routing-table
entry inside squad.agent.md still pointed at the old path. Coordinators
loading squad.agent.md from a freshly upgraded squad would have followed
a dead reference and reported 'skill not found'.

Updated the row in all 5 mirrored copies (.squad-templates, .github/agents,
packages/squad-cli/templates, packages/squad-sdk/templates, templates/).
Also added a hint that users can invoke the skill directly via /squad,
since that is now the documented surface for the same content.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@tamirdresher
tamirdresher force-pushed the squad/skills-userinvocable-slash branch from 347d673 to 93d67da Compare June 13, 2026 16:53
@tamirdresher
tamirdresher merged commit 608f858 into github:dev Jun 13, 2026
14 checks passed
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
test(init): update squad-help + /squad slash test paths to .github/sk…
dd4cd90 
…ills/ (cascade fix on top of github#1126)

After github#1303 + github#1302 landed first (with their tests asserting
.copilot/skills/), the rebase of github#1304 (which moves manifest skills
to .github/skills/) leaves the test paths pointing at the old
location. Update them so the rebased branch's CI is green.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher added a commit that referenced this pull request Jun 13, 2026
@tamirdresher Copilot
fix(skills): install bundled skills to .github/skills/ (closes #1126) (…
40f78f2 
…#1304)

* fix(skills): install bundled skills to .github/skills/ (closes #1126)

Per the official Agent Skills spec docs (GitHub, VS Code), the canonical
project-level custom-skills location is .github/skills/. The legacy
.copilot/skills/ is invisible to all Copilot surfaces except Squad
itself - cloud agent, CLI outside Squad, VS Code extension, @copilot
coding agent all ignore it.

Changes:
* squad init writes bundled skills to .github/skills/{name}/SKILL.md
* squad upgrade does the same AND migrates legacy .copilot/skills/{name}/
  -> .github/skills/{name}/ for manifest skills only (user-added skills
  at .copilot/skills/ are preserved). Tombstones empty legacy dir.
* TEMPLATE_MANIFEST destinations: 10 skill entries retargeted
* ENSURE_DIRECTORIES: .copilot/skills -> .github/skills
* squad.agent.md narrative: 5-path scan order now lists .github/skills
  as primary, .copilot/skills as legacy. Personal scope unchanged.
* All user-facing docs updated (README, spawn-reference, squad-commands
  skill, release-process skill, build.ts skill creation paths, SDK
  type-comment paths).

Migration semantics in upgrade.ts:
* Move-only-if-new-location-empty: legacy at .copilot/skills/, new
  location empty -> move + tombstone legacy
* Tombstone-on-collision: both locations exist -> remove legacy, new
  wins (then syncAllSkills overwrites manifest skills per
  overwriteOnUpgrade=true semantics)
* Preserve user-added: skills NOT in TEMPLATE_MANIFEST stay at
  .copilot/skills/ untouched
* All best-effort with try/catch - disk failures do not block upgrade

Tests (188/188 pass):
* New: init.test.ts asserts canonical path + legacy NOT created
* New: upgrade.test.ts asserts manifest migration + user-skill
  preservation + collision tombstoning
* Updated: 8 existing test files retargeted to .github/skills

NOT changed (intentional):
* .copilot/skills/ stays in coordinator skill-discovery scan order for
  backward compat with user-added skills
* ~/.copilot/skills/ (personal scope) unchanged - that's Copilot CLI's
  official personal-skills location
* Runtime skill-loader tests (skill-source, skills-export-import,
  tools, skill-script-loader) unchanged - those test loader behavior
  which still supports .copilot/skills/ as a scan path

Closes #1126

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: squad_skill writes to .github/skills, sync .github/agents copy, align issue refs

Reviewer follow-ups on #1304 (closes #1126):

1. squad_skill tool implementation matches its description now
   Description says skills live at '.github/skills/{name}/SKILL.md' but the
   handler was still writing to '.copilot/skills/' — every successful 'write'
   shipped to a different path than what the tool documented (and what
   squad init/upgrade now install to). Fixed the handler so:
   - write operations go to '.github/skills/{name}/SKILL.md'
   - read operations check .github/skills first, then fall back to
     .copilot/skills (legacy) and .squad/skills (in-repo team skills),
     in that precedence — so users with un-migrated existing skills can
     still read them.

2. .github/agents/squad.agent.md re-synced from .squad-templates
   The canonical template had the corrected routing-table reference
   ('.github/skills/squad-commands/SKILL.md') but the .github/agents
   mirror copy was never re-synced. The byte-for-byte template-sync
   parity test would have fired on next CI. Ran
   'node scripts/sync-templates.mjs --sync'.

3. Align issue references: #1304 → #1126 in code/docs/tests
   This PR closes #1126; #1304 is the PR number. The migrator docstring,
   the init.ts comment, and the two upgrade.test.ts cases all called the
   regression '#1304' — confusing for anyone digging into git blame for
   the canonical issue. Renamed to #1126 where the references describe
   the bug origin (kept #1304 only where the comment specifically
   describes 'the PR that implemented it').

4. Migrator docstring corrected to match reality
   Old docstring claimed 'skips skills already present at the new
   location with the same content' but the implementation never compares
   content — it unconditionally tombstones the legacy copy when the new
   location exists. Rewrote the doc paragraph to describe what the code
   actually does (preserves the new-location copy verbatim).

Verified locally:
  ✓ vitest test/cli/upgrade.test.ts -t 'migrate manifest skills|should NOT clobber'
  ✓ vitest test/tools.test.ts -t squad_skill

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test(tools): squad_skill writes go to .github/skills now (CI fix)

CI failure on commit 9de50de: 'squad_skill handler > should write
skill file' and 'should default confidence to medium' both still
asserted '.copilot/skills/{name}/SKILL.md' as the write destination.
With squad_skill's handler now writing to '.github/skills/' (the
canonical Copilot CLI custom-skills location, per the fix in the
same commit), those assertions need to be updated. The handler's
read-fallback chain still finds .copilot/skills/ and .squad/skills/
for legacy installs, but the write target is fixed.

Verified locally: 5/5 squad_skill tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* test(init): update squad-help + /squad slash test paths to .github/skills/ (cascade fix on top of #1126)

After #1303 + #1302 landed first (with their tests asserting
.copilot/skills/), the rebase of #1304 (which moves manifest skills
to .github/skills/) leaves the test paths pointing at the old
location. Update them so the rebased branch's CI is green.

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>
tamirdresher added a commit to tamirdresher/squad that referenced this pull request Jun 13, 2026
@tamirdresher
fix: TEMPLATE_MANIFEST entry for cross-squad-communication + pattern …
3e0fba4 
…numbering + honest source/validation

Five reviewer follow-ups on github#1295:

1. MANIFEST_SKILL_NAMES added 'cross-squad-communication' but
   TEMPLATE_MANIFEST didn't — 'squad upgrade' would skip the skill
   even though 'squad init' installed it. Added the missing entry to
   TEMPLATE_MANIFEST so upgrade syncs it like every other manifest
   skill. (Same drift bug pattern noted on github#1292/github#1303.)

2-3. Both SKILL.md files (companion 'cross-squad' and full
   'cross-squad-communication') said the skill covers 'the four
   communication patterns (sync CLI, async git-based, issue-based)'
   but only listed three — Pattern 1 (read-only knowledge query)
   was missing from the intro list. Rewrote both intro lines to
   spell out all four: Pattern 0 (sync CLI), Pattern 1 (read-only),
   Pattern 2 (git-based async), Pattern 3 (issue-based).

4. The doc had 'Pattern 4: Cross-Repo Dependency Scan' which broke
   the 'four numbered patterns 0-3' framing — Pattern 4 isn't a
   communication protocol, it's a one-off analysis utility for
   discovering how two repos relate. Moved it to a clearly labeled
   '### Appendix' section with a note explaining why it's not a
   numbered pattern.

5. Frontmatter 'source:' claimed the skill was 'validated against
   two production squad instances' but the Validation Status section
   said Patterns 2 and 3 were 'untested end-to-end'. Reworded
   'source:' to acknowledge that only Pattern 0 (and partially
   Pattern 1) are end-to-end-validated; Patterns 2/3 are documented
   from design and need live validation before production use.
   Also softened the same overclaim in the Validation Status prose
   (replaced 'validated against two production' with 'drafted
   against two prototype' + explicit acknowledgement that 2/3 are
   design-only).

All 3 mirrored copies of cross-squad-communication/SKILL.md and 3
copies of cross-squad/SKILL.md kept in sync (canonical = .squad/,
mirrors = packages/squad-cli/templates/, packages/squad-sdk/templates/).

Verified: 31/31 init + builtin-skills tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
tamirdresher added a commit that referenced this pull request Jun 13, 2026
@tamirdresher Copilot
feat(sdk): bundle cross-squad-communication skill (#5 cross-squad pro…
6afd067 
…tocols) (#1295)

* feat(sdk): bundle cross-squad-communication skill (#5 cross-squad protocols)

PR #1291 added squad registry add/list/remove and the cross-squad/SKILL.md
for peer discovery. But discovery is only half the story — once a peer is
known, agents need to know HOW to actually exchange info with it.

This change ports cross-squad-communication from tamirdresher/squad-skills
into the bundled skills so a fresh squad init produces a coordinator that
knows the four communication patterns:

* Pattern 0: Synchronous CLI session (--working-directory targeting peer)
* Pattern 1: Read-only metadata scan (team.md / decisions.md)
* Pattern 2: Async git-based request/response (.squad/cross-squad/...)
* Pattern 3: Issue-based delegation (gh issue with squad:cross-squad label)

Plus decision tree for pattern choice, anti-patterns, request/response
YAML schemas, and validation status.

Changes:

* .squad/skills/cross-squad-communication/SKILL.md (379 lines, canonical
  source). sync-skill-templates.mjs propagates to both packages templates.
* MANIFEST_SKILL_NAMES in packages/squad-sdk/src/config/init.ts grows by 1
  entry: cross-squad-communication. Now 11 entries.
* cross-squad/SKILL.md gets a one-paragraph "Companion skill" note pointing
  to cross-squad-communication for protocol details. Together: cross-squad
  answers "who?" (registry discovery), cross-squad-communication answers
  "how?" (the 4 patterns).

The original plugin documented validation against specific internal
Microsoft repos. Examples in this version use generic names (platform-squad,
research-squad) so they are meaningful to upstream users. Protocol mechanics
are unchanged. Frontmatter source: attributes the port.

Test: new "should install cross-squad-communication skill" in init.test.ts
asserts SKILL.md is at install path and content contains expected pattern
names. 26/26 init tests pass. npm run lint clean.

Composes with #1291:
* squad init → both skills bundled
* squad registry add ../peer → peer discoverable
* coordinator: "ask peer X for their team members" → uses Pattern 1 by
  reading team.md from the registered peer

Note on overlap with #1292:
PR #1292 (skills bundling fix) adds 4 entries to MANIFEST_SKILL_NAMES; this
PR adds 1. Disjoint additions to the same array; either can land first.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: TEMPLATE_MANIFEST entry for cross-squad-communication + pattern numbering + honest source/validation

Five reviewer follow-ups on #1295:

1. MANIFEST_SKILL_NAMES added 'cross-squad-communication' but
   TEMPLATE_MANIFEST didn't — 'squad upgrade' would skip the skill
   even though 'squad init' installed it. Added the missing entry to
   TEMPLATE_MANIFEST so upgrade syncs it like every other manifest
   skill. (Same drift bug pattern noted on #1292/#1303.)

2-3. Both SKILL.md files (companion 'cross-squad' and full
   'cross-squad-communication') said the skill covers 'the four
   communication patterns (sync CLI, async git-based, issue-based)'
   but only listed three — Pattern 1 (read-only knowledge query)
   was missing from the intro list. Rewrote both intro lines to
   spell out all four: Pattern 0 (sync CLI), Pattern 1 (read-only),
   Pattern 2 (git-based async), Pattern 3 (issue-based).

4. The doc had 'Pattern 4: Cross-Repo Dependency Scan' which broke
   the 'four numbered patterns 0-3' framing — Pattern 4 isn't a
   communication protocol, it's a one-off analysis utility for
   discovering how two repos relate. Moved it to a clearly labeled
   '### Appendix' section with a note explaining why it's not a
   numbered pattern.

5. Frontmatter 'source:' claimed the skill was 'validated against
   two production squad instances' but the Validation Status section
   said Patterns 2 and 3 were 'untested end-to-end'. Reworded
   'source:' to acknowledge that only Pattern 0 (and partially
   Pattern 1) are end-to-end-validated; Patterns 2/3 are documented
   from design and need live validation before production use.
   Also softened the same overclaim in the Validation Status prose
   (replaced 'validated against two production' with 'drafted
   against two prototype' + explicit acknowledgement that 2/3 are
   design-only).

All 3 mirrored copies of cross-squad-communication/SKILL.md and 3
copies of cross-squad/SKILL.md kept in sync (canonical = .squad/,
mirrors = packages/squad-cli/templates/, packages/squad-sdk/templates/).

Verified: 31/31 init + builtin-skills tests pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(skill): cross-squad-communication uses real Copilot CLI invocations (ghcs→copilot, real flags)

The cross-squad-communication SKILL.md as drafted instructed coordinators
to use a non-existent CLI shape. Verified empirically against
`copilot --help` (v1.0.62):

  - `ghcs` is not a binary on a clean install; the real CLI is
    `copilot` (resolved to C:\ProgramData\global-npm\copilot.ps1 on
    a default node install).
  - `--working-directory <dir>` does not exist. Real flag is
    `-C <directory>` (git-style "change directory first").
  - `--no-mcp` does not exist. Real flag is `--disable-builtin-mcps`.
  - `-p, --prompt <text>` takes the prompt STRING, not a path. Earlier
    examples passed `-p \` (a path), which makes the CLI try
    to execute the path string as a prompt. Read the file with
    `Get-Content -Raw` first.
  - `--allow-all-tools` was missing from autonomous (non-interactive)
    invocations — without it every tool call prompts for permission and
    hangs the cross-squad delegation indefinitely.
  - Log directory was `~/.agency/logs/` (older `agency` runtime). New
    CLI logs under `~/.copilot/logs/`. Switched to a `Test-Path`-guarded
    fallback so both transitional and clean installs resolve correctly.

All 14 call-site occurrences in cross-squad-communication/SKILL.md
updated (3 mirrored copies). Mirrors verified byte-identical.

New regression test in test/cross-squad.test.ts asserts each of the 8
correctness properties (ghcs/—working-directory/—no-mcp absent;
`copilot -C`, `--allow-all-tools`, `--disable-builtin-mcps`,
`-p (Get-Content`, and `.copilot\\logs + Test-Path` present) for
every mirror. 8 × 3 mirrors = 24 new assertions; 56/56 cross-squad
tests pass.

Catches a fairly large embarrassment: had this skill landed as drafted,
every fresh `squad init` coordinator would have run a totally bogus
CLI command on the first delegation attempt. Credit to the peer-squad
`read this skill, ran into errors, asked why` loop for surfacing it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(skill): every cross-squad copilot spawn passes --agent squad

A peer-squad delegation that runs the Copilot CLI without --agent squad
gets a generic Copilot CLI session — the spawned process never loads
.github/agents/squad.agent.md, the peer's team.md, MCP tools, casting,
or coordinator behaviour. The whole point of cross-squad delegation
collapses: the answer comes from an off-the-shelf model, not from the
peer's Squad.

All 7 example command lines in cross-squad-communication/SKILL.md
(Pattern 0 Options A/B/C, Liveness Protocol MCP-skip retry, and the
two Anti-Pattern examples) now include --agent squad. Also added a new
top-of-Patterns "Universal rule: every copilot spawn into a peer squad
MUST pass --agent squad" section that:

  - States the rule once, prominently.
  - Explains the failure mode (generic session, no team.md / MCP /
    coordinator loaded) so future edits don't strip the flag thinking
    it's redundant.
  - Notes the only exception (--resume preserves original session
    agent).
  - Generalises the rule beyond cross-squad: "anywhere else you spawn
    copilot into a Squad-initialised repo — e.g., post-init tips and
    any automation that invokes the CLI on a squadified folder."

Also added a precondition note to Pattern 0 Requirements: the target
repo must be Squad-initialised (.squad/config.json +
.github/agents/squad.agent.md present) so --agent squad resolves.

Verified empirically: copilot --help (v1.0.62) confirms
--agent <agent> is the real flag name.

squad delegate (CLI command) was audited and does NOT need this fix
— it uses `gh issue create`, not `copilot`, so the issue body lands
in the peer repo's GitHub Issues for async pickup, not via direct CLI
spawn.

Regression tests in test/cross-squad.test.ts:
  - 'every copilot spawn into a peer squad includes --agent squad'
    — scans every copilot command line (excluding --resume / prose
    references) and asserts each one has --agent squad. Tells you
    the exact offending line on failure.
  - 'explains WHY --agent squad is required (universal rule paragraph)'
    — defends against a future edit that strips the rationale.
  - 2 new assertions × 3 mirror locations = 6 new tests.
  - 62/62 cross-squad tests pass.

All 3 mirrored copies of cross-squad-communication/SKILL.md kept in
sync (canonical = .squad/, mirrors = packages/squad-cli/templates/,
packages/squad-sdk/templates/).

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>
tamirdresher added a commit that referenced this pull request Jun 13, 2026
@tamirdresher
fix(coordinator): route "spawn a squad" / "another squad" prompts thr…
b79e64a 
…ough the cross-squad skill (#1307)

* fix(coordinator): route "spawn a squad" / "another squad" prompts through the cross-squad skill

A coordinator initialised by `squad init` saw prompts like "spawn two
squads of designers and devs" and fanned out raw `task` agents inside
its own context, treating "squad" as generic English for "team / group".
It never invoked the bundled `cross-squad` or `cross-squad-communication`
skills, so the peer-squad delegation protocol (registry / manifest / sync
CLI / git-async / GH-issue patterns) was bypassed entirely.

Two structural holes in squad.agent.md allowed this:

  1. The Routing table had no row mapping "spawn a squad" phrasing to the
     Squad-PRODUCT concept (only "upgrade squad" / "squad commands" rows
     covered Squad-as-a-product vocabulary).
  2. The Skill-aware-routing block was process discipline ("check skill
     directories by domain relevance") with no hard "if the user's word
     matches a skill name, MUST load the skill" trigger.

This fix:

  - Adds a new routing-table row for the squad-spawning vocabulary
    ("spawn a squad", "another squad", "two squads", "second squad",
    "fan out to squads", "delegate to a squad"). Action: invoke the
    skill tool on cross-squad AND cross-squad-communication BEFORE any
    task spawn, then delegate via Pattern 0/1/2/3.

  - Adds a "Hard trigger — keyword-to-skill match" paragraph at the top
    of the Skill-aware-routing block. If any word in the user's request
    matches an installed skill name (squad → cross-squad, reflect →
    reflect, ceremony → matching ceremony skill, fact-check →
    fact-checking, release → release-process), the coordinator MUST
    invoke the skill tool to fully load that skill before designing its
    approach. Includes a "failure mode this rule closes" pointer so the
    guard survives future paraphrasing.

  - Strengthens cross-squad/SKILL.md with a Read-this-FIRST callout
    above the existing Context paragraph, so even a coordinator that
    skips the routing-table row still hits the trigger when it does
    eventually load the skill.

  - Adds a regression test (template-sync.test.ts) that asserts the row
    + the hard-trigger paragraph + the worked example are present in
    every mirrored copy of squad.agent.md (5 locations).

All 4 mirrors re-synced via `scripts/sync-templates.mjs --sync`.
Verified: 223/223 template-sync tests pass.

Composability: disjoint from #1292/#1293/#1295/#1298/#1300/#1301/#1302/
#1303/#1304/#1306 — only touches squad.agent.md mirrors + cross-squad/
SKILL.md + the template-sync test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(coordinator): strengthen squad-spawn disambiguation — ask_user on ambiguity + anti-patterns

Real-world failure (2026-06-13): even AFTER the routing-table row and
hard-trigger paragraph from b5d05fb landed, a peer-squad coordinator
*still* did ad-hoc `task` fan-out for "spawn two squads of engineers
and QAs". Self-diagnosis surfaced four contributing failure modes:

  1. Prior-session anchoring (saw earlier `reviews/squad-alpha/` folders
     and matched the pattern without re-evaluating user intent).
  2. Ambiguous wording, lazy interpretation (silently picked the
     cheaper option instead of asking).
  3. Coordinator doctrine biases toward `task` fan-out (the existing
     Eager Execution / Parallel Fan-Out section pulled the coordinator
     back even after it had loaded `cross-squad`).
  4. Cost/overhead instinct ("two real squads for a 30-line app feels
     disproportionate" — judged silently instead of surfacing the
     trade-off).

The original PR #1307 fix closed modes 1 and 3 mechanically (forces
the skill to load) but left modes 2 and 4 open (didn't dictate what
to DO with that knowledge). This commit closes them:

A. squad.agent.md routing row — added two explicit clauses:
   - "**Default = literal Squad install.** Calling `task` sub-agents
     'squad-alpha' / 'squad-beta' does NOT make them squads — that is
     the explicit anti-pattern."
   - "**If the request is ambiguous** ... you MUST `ask_user` with a
     2-choice prompt — and never silently pick the cheaper option."
   No escape hatch. The coordinator can no longer rationalise the
   downgrade as a judgment call.

B. cross-squad/SKILL.md — added a full `## Disambiguation: 'squad' vs
   ad-hoc agents` section with:
   - Default-behaviour table mapping common phrasings to expected
     coordinator actions (real squads vs ad-hoc agents vs ambiguous).
   - ask_user 2-choice protocol verbatim (heavier/persistent vs
     lighter/ephemeral) so the coordinator has the exact prompt shape.
   - Four named anti-patterns drawn directly from the observed failure:
     * Naming task agents "squad-alpha" doesn't make them squads
     * Prior-session anchoring (pattern is a hint, not a contract)
     * Silent cheaper-option pick (judgment call belongs to the user)
     * Loading the skill but doing task fan-out anyway (disambiguation
       rule OVERRIDES generic fan-out doctrine when "squad" was the
       trigger)
   - Sharpened `description:` so the squad skill-aware-router has
     better natural-language hooks.
   - `triggers:` frontmatter array (Copilot CLI ignores `triggers:` per
     sdk/index.js decompile, but the squad coordinator's skill-aware
     routing system uses natural-language matching against frontmatter
     + content, so documenting the phrases here helps that matcher fire).

C. Regression tests in test/template-sync.test.ts:
   - Routing row must mention `ask_user` + "anti-pattern" (new × 5
     mirrors = 5 assertions).
   - cross-squad/SKILL.md must have `## Disambiguation` section,
     default-behaviour rule, ask_user requirement, the squad-alpha
     anti-pattern, and triggers: frontmatter (5 new × 3 mirrors = 15
     assertions).
   - 20 new assertions total; 243/243 template-sync tests pass.

cross-squad/SKILL.md mirrored to packages/squad-cli/templates/skills/
and packages/squad-sdk/templates/skills/ (byte-identical). squad.agent.md
re-synced to all 4 mirrors via scripts/sync-templates.mjs.

Composability: still disjoint from all other open PRs. Pure additions
to two files (squad.agent.md row, cross-squad/SKILL.md content) plus
mirrors + tests.

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>
This was referenced Jun 13, 2026
Closed
Open
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@bradygaster bradygaster bradygaster approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@tamirdresher @bradygaster