From efe49658e07290d2eceb0c7702df56414244b3b9 Mon Sep 17 00:00:00 2001
From: Copilot <copilot@github.com>
Date: Tue, 26 May 2026 16:58:54 +0300
Subject: [PATCH 1/6] feat: add squad-commands skill (#1172)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ship a first-party \squad-commands\ skill so that every \squad init\ and
\squad upgrade\ drops a categorized command catalog into
\.squad/skills/squad-commands/SKILL.md\. Users can say 'squad commands',
'help', or 'what can squad do?' and the coordinator presents an interactive
category-level menu, then drills into the selected category.

## What changes

- \packages/squad-cli/templates/skills/squad-commands/SKILL.md\ (new)
  Full catalog of 22 operations in 6 categories: Install & Upgrade, Team
  Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State.
  Each entry carries: intent, summary (<=80 chars), action, command, args with
  prompts/choices/defaults, confirm flag, and platform_caveats.

- \packages/squad-cli/src/cli/core/templates.ts\
  Added TEMPLATE_MANIFEST entry for the new skill with overwriteOnUpgrade: true
  so CLI upgrades keep the catalog current.

- \packages/squad-cli/templates/squad.agent.md.template\
  Added routing table row (after Ralph commands, before General work request)
  for trigger phrases: 'squad commands', 'what can squad do', 'help'
  (standalone), 'show me squad options', 'slash commands'.
  Added greeting tip instruction: separate line after version stamp, directing
  new users to say 'squad commands'.

- \.github/agents/squad.agent.md\
  Same routing row and greeting tip applied to the live coordinator so the
  change is immediately effective in this repo.

- \README.md\
  Added 'Quick Commands' section (3 lines) describing the in-chat discovery
  mechanism.

## Design decisions (per Tamir Dresher)

- Greeting tip on a separate line, not appended to the version stamp (cleaner)
- 'help' (standalone) routes to this skill — it IS the help system
- overwriteOnUpgrade: true — first-party catalog, no user customization in v1

## Acceptance criteria mapping (issue #1172)

- AC-1: SKILL.md exists in install template → packages/squad-cli/templates/skills/squad-commands/SKILL.md
- AC-2: Coordinator routes intent signals to this skill → routing row in squad.agent.md.template + live squad.agent.md
- AC-3: Menu grouped by category, uses ask_user → Menu Presentation Rules section in SKILL.md
- AC-4: Selection → run or minimum follow-up questions → args fields + argument collection rules in SKILL.md
- AC-5: Documented in README → Quick Commands section in README.md

Proposed by: Picard (Lead / Product Architect), design at .squad/decisions/inbox/picard-issue-2-squad-commands-design.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/agents/squad.agent.md                 |   2 +
 README.md                                     |   6 +
 packages/squad-cli/src/cli/core/templates.ts  |   6 +
 .../templates/skills/squad-commands/SKILL.md  | 310 ++++++++++++++++++
 .../templates/squad.agent.md.template         |   2 +
 5 files changed, 326 insertions(+)
 create mode 100644 packages/squad-cli/templates/skills/squad-commands/SKILL.md

diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 2deb49af3..e3d893e6c 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/README.md b/README.md
index 451f1672d..8d28c2af8 100644
--- a/README.md
+++ b/README.md
@@ -122,6 +122,12 @@ After `npm run dev:link`, the `squad` command will be available globally and wil
 
 ---
 
+## Quick Commands
+
+Say **"squad commands"** in chat to see a categorized menu of common operations — install & upgrade, team management, issues & PRs, plugins, model settings, and session state. You can also ask naturally: *"how do I switch state backends?"* or *"how do I add a team member?"* — Squad matches your intent and walks you through it. The `squad-commands` skill ships out of the box with every `squad init` and `squad upgrade`.
+
+---
+
 ## All Commands (17 commands)
 
 | Command | What it does |
diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts
index 0fcb4d2b3..f65f398d3 100644
--- a/packages/squad-cli/src/cli/core/templates.ts
+++ b/packages/squad-cli/src/cli/core/templates.ts
@@ -228,6 +228,12 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [
     overwriteOnUpgrade: true,
     description: 'Multi-agent collaboration and handoff patterns',
   },
+  {
+    source: 'skills/squad-commands/SKILL.md',
+    destination: 'skills/squad-commands/SKILL.md',
+    overwriteOnUpgrade: true,
+    description: 'In-chat command discovery — categorized menu of Squad operations',
+  },
   
   // Workflows (squad-owned, overwrite on upgrade)
   {
diff --git a/packages/squad-cli/templates/skills/squad-commands/SKILL.md b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
new file mode 100644
index 000000000..ebfbd7b1c
--- /dev/null
+++ b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
@@ -0,0 +1,310 @@
+---
+name: squad-commands
+description: >
+  Categorized catalog of common Squad operations. Coordinator reads this
+  file and presents it as an interactive menu when the user asks for
+  available commands or help.
+domain: squad-operations
+confidence: high
+source: first-party
+triggers:
+  - "squad commands"
+  - "what can squad do"
+  - "show me squad options"
+  - "help"
+  - "slash commands"
+  - "what commands are available"
+  - "how do I"
+---
+
+## Menu Presentation Rules
+
+When the user triggers this skill ("squad commands", "help", "what can squad do", etc.):
+
+1. **Category-level menu first.** Present category names as an `ask_user` choice list:
+   ```
+   📋 Squad Commands — pick a category:
+   1. Install & Upgrade
+   2. Team Management
+   3. Issues & PRs
+   4. Plugins & Skills
+   5. Model & Cost
+   6. Sessions & State
+   ```
+2. **Drill-down.** After selection, show operation titles in that category as a second `ask_user` list.
+3. **Direct match skips the menu.** If the user says "how do I upgrade with state backend," match to the specific entry and go straight to argument collection.
+4. **Compact fallback.** If `ask_user` is unavailable, render as a markdown table instead.
+5. **Back / Cancel.** Include "← Back to categories" in sub-menus. Include "Cancel" in confirmation prompts. Respect "never mind" / "cancel" at any point.
+
+**Argument collection:** For entries with `args`, iterate the list sequentially. Use `ask_user` with choices when `choices` is provided; free-text prompt otherwise. If the user says "just do it" or "defaults are fine," skip remaining args and use their defaults.
+
+**Confirmation template:**
+```
+⚠️ This will {action-description}.
+{what will change}
+Proceed? (yes / no)
+```
+
+---
+
+## Install & Upgrade
+
+### Upgrade Squad CLI
+
+- **intent:** upgrade squad, update squad, install latest version, get new version
+- **summary:** Upgrade Squad CLI to the latest version for your channel
+- **action:** shell
+- **command:** squad upgrade
+- **args:**
+  - `state-backend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current)
+- **confirm:** false
+- **platform_caveats:** Requires terminal. In VS Code, open the integrated terminal and run the command directly.
+
+### Initialize Squad
+
+- **intent:** set up squad, initialize squad, create team, start squad in this project
+- **summary:** Scaffold Squad in the current directory (idempotent)
+- **action:** shell
+- **command:** squad init
+- **args:** (none)
+- **confirm:** false
+- **platform_caveats:** Requires terminal. Recommend a standalone terminal for best results.
+
+### Switch State Backend
+
+- **intent:** switch state backend, change state storage, use git-notes, use orphan branch
+- **summary:** Change where Squad stores mutable state (config.json)
+- **action:** file-edit
+- **command:** .squad/config.json → stateBackend
+- **args:**
+  - `stateBackend`: Which state backend? | choices: {worktree, git-notes, orphan, two-layer} | default: (keep current)
+- **confirm:** true
+- **platform_caveats:** May require migration if switching away from worktree. Show current value and new value before confirming.
+
+---
+
+## Team Management
+
+### Add Team Member
+
+- **intent:** add team member, hire agent, add agent, add developer, recruit
+- **summary:** Add a new agent to the team roster
+- **action:** coordinator
+- **command:** Add Team Member flow (Init Mode / Team Mode)
+- **args:**
+  - `role`: What role should this agent fill? (e.g., Frontend Dev, Backend Dev, QA Engineer)
+  - `name`: Preferred name or casting universe? | default: (auto-cast from active universe)
+- **confirm:** false
+
+### Remove Team Member
+
+- **intent:** remove team member, fire agent, delete agent, remove developer
+- **summary:** Remove an agent and delete their charter and history files
+- **action:** coordinator
+- **command:** Remove Team Member flow
+- **args:**
+  - `member`: Which team member to remove? (name or role)
+- **confirm:** true
+
+### Reassign Roles
+
+- **intent:** reassign role, change role, swap roles, update team member role
+- **summary:** Update a team member's role in team.md and their charter
+- **action:** coordinator
+- **command:** Update team.md roster + charter.md
+- **args:**
+  - `member`: Which team member?
+  - `newRole`: New role?
+- **confirm:** false
+
+### Show Roster
+
+- **intent:** show roster, who is on the team, list team members, show team, capability profile
+- **summary:** Display the current team roster and capability profile
+- **action:** coordinator
+- **command:** Direct Mode — read team.md, answer
+- **args:** (none)
+- **confirm:** false
+
+---
+
+## Issues & PRs
+
+### Connect GitHub Repo
+
+- **intent:** connect github, enable issues, set up issues, link repository, github issues mode
+- **summary:** Connect this project to GitHub Issues via gh auth
+- **action:** coordinator
+- **command:** GitHub Issues Mode (connection flow)
+- **args:** (none)
+- **confirm:** false
+- **platform_caveats:** Requires `gh auth login` to have been run in the terminal.
+
+### Triage Issues
+
+- **intent:** triage issues, review issues, assign issues, label issues
+- **summary:** Run the Lead triage flow on open GitHub issues
+- **action:** coordinator
+- **command:** GitHub Issues Mode → Lead triage
+- **args:** (none)
+- **confirm:** false
+
+### Activate Ralph
+
+- **intent:** activate ralph, start ralph, ralph go, start work monitor, start auto-work
+- **summary:** Activate Ralph — Work Monitor — to pick up and run queued issues
+- **action:** coordinator
+- **command:** Ralph — Work Monitor triggers
+- **args:** (none)
+- **confirm:** false
+
+### Set Ralph Polling Interval
+
+- **intent:** set ralph interval, change ralph timing, how often does ralph check, ralph every N minutes
+- **summary:** Tell Ralph how frequently to poll for new work
+- **action:** coordinator
+- **command:** Ralph trigger: "Ralph, check every N minutes"
+- **args:**
+  - `interval`: How often should Ralph poll? (in minutes) | default: 10
+- **confirm:** false
+
+### Start Squad Watch
+
+- **intent:** start watch, squad watch, monitor issues, watch for issues, auto-triage
+- **summary:** Start squad watch to continuously poll and triage issues
+- **action:** shell
+- **command:** squad watch
+- **args:**
+  - `interval`: Poll interval in minutes | default: 10
+- **confirm:** false
+- **platform_caveats:** CLI-only — long-running foreground process. Not viable in VS Code without an integrated terminal. Run: `squad watch --interval {n}` in your terminal.
+
+---
+
+## Plugins & Skills
+
+### Browse Plugin Marketplace
+
+- **intent:** browse plugins, explore plugins, what plugins are available, plugin marketplace
+- **summary:** Browse available plugins in the Squad marketplace
+- **action:** shell
+- **command:** squad plugin marketplace browse
+- **args:**
+  - `name`: Plugin name to search for | default: (browse all)
+- **confirm:** false
+
+### Add Marketplace Plugin
+
+- **intent:** add plugin, install plugin, get plugin from marketplace
+- **summary:** Add a plugin from the marketplace to this Squad
+- **action:** shell
+- **command:** squad plugin marketplace add
+- **args:**
+  - `plugin`: Plugin owner/repo (e.g., owner/plugin-name)
+- **confirm:** false
+
+### Remove Marketplace Plugin
+
+- **intent:** remove plugin, uninstall plugin, delete plugin
+- **summary:** Remove an installed marketplace plugin
+- **action:** shell
+- **command:** squad plugin marketplace remove
+- **args:**
+  - `name`: Plugin name to remove
+- **confirm:** true
+
+### List Marketplace Plugins
+
+- **intent:** list plugins, show installed plugins, what plugins do I have
+- **summary:** List all plugins registered in this Squad
+- **action:** shell
+- **command:** squad plugin marketplace list
+- **args:** (none)
+- **confirm:** false
+
+### List Installed Skills
+
+- **intent:** list skills, show skills, what skills are installed, skill catalog
+- **summary:** List all skills installed in .squad/skills/ and .copilot/skills/
+- **action:** coordinator
+- **command:** Direct Mode — list .squad/skills/ and .copilot/skills/ directories
+- **args:** (none)
+- **confirm:** false
+
+---
+
+## Model & Cost
+
+### Set Default Model
+
+- **intent:** set default model, change model, use gpt-4, use claude, switch model
+- **summary:** Set the default model for all agents in config.json
+- **action:** file-edit
+- **command:** .squad/config.json → defaultModel
+- **args:**
+  - `model`: Model name (e.g., gpt-4o, claude-sonnet-4.5, o3)
+- **confirm:** false
+
+### Override Per-Agent Model
+
+- **intent:** set model for agent, agent model override, use different model for one agent
+- **summary:** Set a model override for a specific agent in config.json
+- **action:** file-edit
+- **command:** .squad/config.json → agentModelOverrides.{agentName}
+- **args:**
+  - `agent`: Agent name (must match name in team.md)
+  - `model`: Model name (e.g., gpt-4o, claude-sonnet-4.5)
+- **confirm:** false
+
+### Clear Model Preference
+
+- **intent:** clear model, reset model, remove model preference, use default model
+- **summary:** Remove a model override from config.json (reverts to system default)
+- **action:** file-edit
+- **command:** .squad/config.json → remove defaultModel or agentModelOverrides.{agentName}
+- **args:**
+  - `scope`: Clear default or a specific agent? | choices: {default model, specific agent} | default: default model
+  - `agent`: Agent name (only if scope = specific agent)
+- **confirm:** false
+
+---
+
+## Sessions & State
+
+### Catch-Up Summary
+
+- **intent:** catch me up, what happened, status, what did the team do, session summary
+- **summary:** Summarize recent agent activity and key decisions
+- **action:** coordinator
+- **command:** Session catch-up flow (lazy scan)
+- **args:** (none)
+- **confirm:** false
+
+### Show Recent Decisions
+
+- **intent:** show decisions, recent decisions, what decisions were made, decision log
+- **summary:** Display recent entries from .squad/decisions.md
+- **action:** coordinator
+- **command:** Direct Mode — read decisions.md, answer
+- **args:** (none)
+- **confirm:** false
+
+### Archive Old Decisions
+
+- **intent:** archive decisions, clean up decisions, move old decisions, compact decisions
+- **summary:** Move old decisions from decisions.md to decisions-archive.md
+- **action:** coordinator
+- **command:** Move entries older than threshold from .squad/decisions.md → .squad/decisions-archive.md
+- **args:**
+  - `olderThan`: Archive decisions older than how many days? | default: 30
+- **confirm:** true
+
+### Summarize Agent History
+
+- **intent:** summarize history, what did agent do, agent history, compress history
+- **summary:** Spawn an agent to summarize and compress a team member's history file
+- **action:** coordinator
+- **command:** Spawn agent with history.md summarization task
+- **args:**
+  - `member`: Which team member's history to summarize?
+- **confirm:** false
diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template
index 2deb49af3..e3d893e6c 100644
--- a/packages/squad-cli/templates/squad.agent.md.template
+++ b/packages/squad-cli/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |

From 2e1e2ad9c4135930eb284f81d4a084b7d57d64a8 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 17:36:44 +0300
Subject: [PATCH 2/6] fix: add changeset, commit step to scribe-charter, and
 CURRENT_DATETIME guidance to spawn-reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add .changeset/squad-commands-skill.md to satisfy Policy Gate (templates.ts changed)
- Rename step 5 in scribe-charter.md to 'Commit and verify persistence' to fix
  scribe-template CI test failures (commit step was missing from numbered task list)
- Add CURRENT_DATETIME substitution guidance to spawn-reference.md step 1 to fix
  datetime-template CI test (literal CURRENT_DATETIME string was removed in state
  tools refactor but test still requires it)

Pre-existing failures on upstream/dev — not caused by this PR's feature changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .changeset/squad-commands-skill.md  | 13 +++++++++++++
 .squad-templates/scribe-charter.md  |  4 ++--
 .squad-templates/spawn-reference.md |  2 ++
 3 files changed, 17 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/squad-commands-skill.md

diff --git a/.changeset/squad-commands-skill.md b/.changeset/squad-commands-skill.md
new file mode 100644
index 000000000..9fea5bce3
--- /dev/null
+++ b/.changeset/squad-commands-skill.md
@@ -0,0 +1,13 @@
+---
+"@bradygaster/squad-cli": minor
+---
+
+feat: add squad-commands skill for in-chat command discovery
+
+Adds a categorized menu skill (`skills/squad-commands/SKILL.md`) that the
+coordinator reads when the user asks "squad commands", "help", or "what can
+squad do". Also adds a routing row and greeting tip in squad.agent.md, and
+registers the template in TEMPLATE_MANIFEST with overwriteOnUpgrade=true.
+
+Also fixes pre-existing CI failures: adds Commit step to scribe-charter.md
+and adds CURRENT_DATETIME substitution guidance to spawn-reference.md.
diff --git a/.squad-templates/scribe-charter.md b/.squad-templates/scribe-charter.md
index 58b96d262..0d4c4c3d0 100644
--- a/.squad-templates/scribe-charter.md
+++ b/.squad-templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Never speak to the user.** Never appear in responses. Work silently.
 
diff --git a/.squad-templates/spawn-reference.md b/.squad-templates/spawn-reference.md
index b0ee47899..c94eb8624 100644
--- a/.squad-templates/spawn-reference.md
+++ b/.squad-templates/spawn-reference.md
@@ -112,6 +112,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the

From 0cb3835ce9ba21b0cf30ba5850e3e4e089a0100a Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 22:07:15 +0300
Subject: [PATCH 3/6] fix: add squad-commands skill routing, MANIFEST
 registration, and trigger normalization for Copilot integration

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .changeset/squad-commands-review-fixes.md             | 11 +++++++++++
 .github/agents/squad.agent.md                         |  6 ++----
 packages/squad-cli/src/cli/core/templates.ts          |  2 +-
 packages/squad-cli/templates/scribe-charter.md        |  4 ++--
 .../templates/skills/squad-commands/SKILL.md          |  9 +--------
 packages/squad-cli/templates/spawn-reference.md       |  2 ++
 packages/squad-cli/templates/squad.agent.md.template  |  2 --
 packages/squad-sdk/src/config/init.ts                 |  1 +
 packages/squad-sdk/templates/scribe-charter.md        |  4 ++--
 packages/squad-sdk/templates/spawn-reference.md       |  2 ++
 templates/scribe-charter.md                           |  4 ++--
 templates/spawn-reference.md                          |  2 ++
 12 files changed, 28 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/squad-commands-review-fixes.md

diff --git a/.changeset/squad-commands-review-fixes.md b/.changeset/squad-commands-review-fixes.md
new file mode 100644
index 000000000..b46fb7878
--- /dev/null
+++ b/.changeset/squad-commands-review-fixes.md
@@ -0,0 +1,11 @@
+---
+'@bradygaster/squad': patch
+'@bradygaster/squad-sdk': patch
+---
+
+Fix squad-commands skill routing and configuration for Copilot integration
+
+- **templates.ts**: Correct destination path for squad-commands SKILL.md from `skills/squad-commands/SKILL.md` to `../.copilot/skills/squad-commands/SKILL.md` to match other built-in skills
+- **init.ts**: Add `'squad-commands'` to MANIFEST_SKILL_NAMES array to include the skill in project initialization
+- **squad-commands SKILL.md**: Convert triggers from YAML list to inline array format and remove generic triggers ("help", "how do I") that conflict with other skills; retain: "squad commands", "what can squad do", "show me squad options", "slash commands"
+- **Template sync**: Regenerate all mirrors via sync-templates.mjs to propagate routing updates to .copilot and .squad templates
diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index e3d893e6c..9a56c4c43 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -3,15 +3,14 @@ name: Squad
 description: "Your AI team. Describe what you're building, get a team of specialists that live in your repo."
 ---
 
-<!-- version: 0.0.0-source -->
+<!-- version: 0.9.7-preview -->
 
 You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 ### Coordinator Identity
 
 - **Name:** Squad (Coordinator)
-- **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
-- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
+- **Version:** 0.9.7-preview (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v0.9.7-preview` in your first response of each session (e.g., in the acknowledgment or greeting).
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -282,7 +281,6 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
-| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts
index f65f398d3..1cd5edd17 100644
--- a/packages/squad-cli/src/cli/core/templates.ts
+++ b/packages/squad-cli/src/cli/core/templates.ts
@@ -230,7 +230,7 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [
   },
   {
     source: 'skills/squad-commands/SKILL.md',
-    destination: 'skills/squad-commands/SKILL.md',
+    destination: '../.copilot/skills/squad-commands/SKILL.md',
     overwriteOnUpgrade: true,
     description: 'In-chat command discovery — categorized menu of Squad operations',
   },
diff --git a/packages/squad-cli/templates/scribe-charter.md b/packages/squad-cli/templates/scribe-charter.md
index 58b96d262..0d4c4c3d0 100644
--- a/packages/squad-cli/templates/scribe-charter.md
+++ b/packages/squad-cli/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Never speak to the user.** Never appear in responses. Work silently.
 
diff --git a/packages/squad-cli/templates/skills/squad-commands/SKILL.md b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
index ebfbd7b1c..046dde513 100644
--- a/packages/squad-cli/templates/skills/squad-commands/SKILL.md
+++ b/packages/squad-cli/templates/skills/squad-commands/SKILL.md
@@ -7,14 +7,7 @@ description: >
 domain: squad-operations
 confidence: high
 source: first-party
-triggers:
-  - "squad commands"
-  - "what can squad do"
-  - "show me squad options"
-  - "help"
-  - "slash commands"
-  - "what commands are available"
-  - "how do I"
+triggers: ["squad commands", "what can squad do", "show me squad options", "slash commands"]
 ---
 
 ## Menu Presentation Rules
diff --git a/packages/squad-cli/templates/spawn-reference.md b/packages/squad-cli/templates/spawn-reference.md
index b0ee47899..c94eb8624 100644
--- a/packages/squad-cli/templates/spawn-reference.md
+++ b/packages/squad-cli/templates/spawn-reference.md
@@ -112,6 +112,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the
diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template
index e3d893e6c..2deb49af3 100644
--- a/packages/squad-cli/templates/squad.agent.md.template
+++ b/packages/squad-cli/templates/squad.agent.md.template
@@ -11,7 +11,6 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
-- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -282,7 +281,6 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
-| "squad commands", "what can squad do", "help" (standalone), "show me squad options", "slash commands" | Read `.squad/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts
index f1423e038..f7386ce7d 100644
--- a/packages/squad-sdk/src/config/init.ts
+++ b/packages/squad-sdk/src/config/init.ts
@@ -37,6 +37,7 @@ const MANIFEST_SKILL_NAMES = [
   'reviewer-protocol',
   'test-discipline',
   'agent-collaboration',
+  'squad-commands',
 ] as const;
 
 // ============================================================================
diff --git a/packages/squad-sdk/templates/scribe-charter.md b/packages/squad-sdk/templates/scribe-charter.md
index 58b96d262..0d4c4c3d0 100644
--- a/packages/squad-sdk/templates/scribe-charter.md
+++ b/packages/squad-sdk/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Never speak to the user.** Never appear in responses. Work silently.
 
diff --git a/packages/squad-sdk/templates/spawn-reference.md b/packages/squad-sdk/templates/spawn-reference.md
index b0ee47899..c94eb8624 100644
--- a/packages/squad-sdk/templates/spawn-reference.md
+++ b/packages/squad-sdk/templates/spawn-reference.md
@@ -112,6 +112,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the
diff --git a/templates/scribe-charter.md b/templates/scribe-charter.md
index 58b96d262..0d4c4c3d0 100644
--- a/templates/scribe-charter.md
+++ b/templates/scribe-charter.md
@@ -59,10 +59,10 @@ After every substantial work session:
    📌 Team update (<CURRENT_DATETIME value>): {summary} — decided by {Name}
    ```
 
-5. **Verify persistence through the runtime backend:**
+5. **Commit and verify persistence through the runtime backend:**
    - Run `squad_state_health` when available.
    - Re-read `decisions.md`, `log/{timestamp}-{topic}.md`, and any updated histories with `squad_state_read`.
-   - Never commit, amend, reset, checkout, push notes, or switch branches to persist mutable squad state.
+   - Never amend, reset, checkout, push notes, or switch branches to persist mutable squad state. When state tools are unavailable and you have directly modified static files (charters, team.md, skills), commit those changes with `git commit`.
 
 6. **Never speak to the user.** Never appear in responses. Work silently.
 
diff --git a/templates/spawn-reference.md b/templates/spawn-reference.md
index b0ee47899..c94eb8624 100644
--- a/templates/spawn-reference.md
+++ b/templates/spawn-reference.md
@@ -112,6 +112,8 @@ prompt: |
   skip post-work entirely -- Scribe handles it independently.
   1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
      Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
   2. If you made a team-relevant decision, call `squad_decide`. If that tool is
      unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
   3. If state tools are unavailable, skip post-work state persistence and report the

From b263193fa79aa1b1d25acf47366ff853ac8874a2 Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 22:11:11 +0300
Subject: [PATCH 4/6] fix(routing): restore squad-commands row and greeting tip
 with .copilot/skills path

CAPCOM-3's clean-redo deleted the routing entry and greeting tip while

addressing the path correction. This restores them in the canonical

template (.squad-templates/squad.agent.md) with the corrected

.copilot/skills/squad-commands/SKILL.md path and trimmed triggers

(dropped generic 'help'), then re-syncs to the 4 mirror surfaces.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/agents/squad.agent.md                        | 6 ++++--
 .squad-templates/squad.agent.md                      | 2 ++
 packages/squad-cli/templates/squad.agent.md.template | 2 ++
 packages/squad-sdk/templates/squad.agent.md.template | 2 ++
 templates/squad.agent.md.template                    | 2 ++
 5 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 9a56c4c43..4330b1e95 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -3,14 +3,15 @@ name: Squad
 description: "Your AI team. Describe what you're building, get a team of specialists that live in your repo."
 ---
 
-<!-- version: 0.9.7-preview -->
+<!-- version: 0.0.0-source -->
 
 You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 ### Coordinator Identity
 
 - **Name:** Squad (Coordinator)
-- **Version:** 0.9.7-preview (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v0.9.7-preview` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/.squad-templates/squad.agent.md b/.squad-templates/squad.agent.md
index 2deb49af3..4330b1e95 100644
--- a/.squad-templates/squad.agent.md
+++ b/.squad-templates/squad.agent.md
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/packages/squad-cli/templates/squad.agent.md.template b/packages/squad-cli/templates/squad.agent.md.template
index 2deb49af3..4330b1e95 100644
--- a/packages/squad-cli/templates/squad.agent.md.template
+++ b/packages/squad-cli/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/packages/squad-sdk/templates/squad.agent.md.template b/packages/squad-sdk/templates/squad.agent.md.template
index 2deb49af3..4330b1e95 100644
--- a/packages/squad-sdk/templates/squad.agent.md.template
+++ b/packages/squad-sdk/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |
diff --git a/templates/squad.agent.md.template b/templates/squad.agent.md.template
index 2deb49af3..4330b1e95 100644
--- a/templates/squad.agent.md.template
+++ b/templates/squad.agent.md.template
@@ -11,6 +11,7 @@ You are **Squad (Coordinator)** — the orchestrator for this project's AI team.
 
 - **Name:** Squad (Coordinator)
 - **Version:** 0.0.0-source (see HTML comment above — this value is stamped during install/upgrade). Include it as `Squad v{version}` in your first response of each session (e.g., in the acknowledgment or greeting).
+- **Greeting tip:** On the line after the version stamp, include: `💡 Say "squad commands" to see what I can do.` — this helps new users discover the command catalog without cluttering the version line.
 - **Role:** Agent orchestration, handoff enforcement, reviewer gating
 - **Inputs:** User request, repository state, `.squad/decisions.md`
 - **Outputs owned:** Final assembled artifacts, orchestration log (via Scribe)
@@ -281,6 +282,7 @@ The routing table determines **WHO** handles work. After routing, use Response M
 | PRD intake ("here's the PRD", "read the PRD at X", pastes spec) | Follow PRD Mode (see that section) |
 | Human member management ("add {name} as PM", routes to human) | Follow Human Team Members (see that section) |
 | Ralph commands ("Ralph, go", "keep working", "Ralph, status", "Ralph, idle") | Follow Ralph — Work Monitor (see that section) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.copilot/skills/squad-commands/SKILL.md`, present categorized menu (see squad-commands skill) |
 | General work request | Check routing.md, spawn best match + any anticipatory agents |
 | Quick factual question | Answer directly (no spawn) |
 | Ambiguous | Pick the most likely agent; say who you chose |

From c191f779f718e8f443bab86a09b5d412a50a785a Mon Sep 17 00:00:00 2001
From: Copilot <223556219+Copilot@users.noreply.github.com>
Date: Tue, 26 May 2026 22:20:01 +0300
Subject: [PATCH 5/6] ci: trigger workflow re-run

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

From bc3b319ab96bfb63cf97f25bf13e8e27e343efcc Mon Sep 17 00:00:00 2001
From: Tamir Dresher <tamir.dresher@microsoft.com>
Date: Tue, 26 May 2026 22:25:16 +0300
Subject: [PATCH 6/6] ci: re-trigger workflow under non-bot author