@bradygaster/squad-cli 0.9.6-insider.2 → 0.10.0-insider.1

package/templates/skills/squad/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: squad
+description: >-
+  Squad's command catalog and interactive menu. Invoke via /squad (slash command) or natural language ("squad commands", "what can squad do", "show me squad options"). Presents categorized operations (Install & Upgrade, Team Management, Issues & PRs, Plugins & Skills, Model & Cost, Sessions & State) as an interactive picker. Routes to the right squad CLI command or the Squad coordinator agent.
+user-invocable: true
+allowedTools: []
+---
+
+## Menu Presentation Rules
+
+When the user triggers this skill (via `/squad` slash command, "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

package/templates/skills/squad-help/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: "squad-help"
+description: "How to actually use Squad — Squad is a custom Copilot agent (invoked via the task tool with agent_type='Squad'), not a skill. This file explains the right invocation paths for setting up a team, listing squad commands, and initializing Squad in a new project."
+allowedTools: []
+confidence: high
+domain: squad-onboarding
+---
+
+# Skill: squad-help
+
+> **Quick reference.** If you're reading this because a user said "use squad" or "squad" or "set up a squad", you're in the right place — read on for the correct invocation paths.
+
+---
+
+## Squad is a custom agent, not a skill
+
+The Squad framework registers a **custom Copilot CLI agent** at `.github/agents/squad.agent.md`. The agent is named **`Squad`** and its description is *"Your AI team. Describe what you're building, get a team of specialists that live in your repo."*
+
+Copilot CLI agents and skills are different things:
+
+| Thing | How to invoke | Example |
+|---|---|---|
+| **Skill** | `skill(name)` tool call or natural-language match | `skill(squad-commands)` |
+| **Agent** | `task` tool with `agent_type=<name>` | `task(name="...", agent_type="Squad", prompt="...")` |
+| **Slash command** | Built-in CLI keyword | `/agent`, `/skills`, `/mcp` |
+
+Calling `skill(Squad)` will fail with *"Skill not found: Squad"* because Squad is the agent, not a skill. (`/squad` as a slash command also does not exist — only built-in CLI keywords like `/agent`, `/skills`, `/mcp` are slash commands. There's no way to map a skill name to a slash command without a Copilot CLI feature change.)
+
+---
+
+## How to actually use Squad
+
+Pick the path that matches the user's intent:
+
+### A) Invoke the Squad coordinator agent (most common)
+
+The Squad coordinator orchestrates a team of specialists. It routes work to the right agent, scaffolds a team if none exists, and enforces handoffs.
+
+```text
+task(
+  name="<short-task-name>",
+  agent_type="Squad",
+  prompt="<what you want the team to do>"
+)
+```
+
+Use this when the user says things like:
+- *"Use Squad to build X"*
+- *"Set up an AI team for this project"*
+- *"Have the Squad coordinator design Y"*
+- *"Spawn Squad"* / *"Squad, help me with ..."*
+
+### B) See what Squad commands exist
+
+The `squad-commands` skill is a categorized catalog of common Squad operations. The coordinator presents it as an interactive menu.
+
+Trigger by natural-language match: `"squad commands"`, `"what can squad do"`, `"show me squad options"`, `"slash commands"`, `"what commands are available"`.
+
+Use this when the user says things like:
+- *"What can Squad do?"*
+- *"Show me the squad commands"*
+- *"squad help"*
+
+### C) Initialize Squad in a fresh project
+
+`squad init` is a **shell command**, not a tool call. The user runs it in their terminal in a project that has no `.squad/` directory yet.
+
+```bash
+squad init
+```
+
+Do **not** try to invoke this from inside an existing Copilot session — `.squad/` is already initialized if you're reading this file.
+
+---
+
+## What NOT to do
+
+- ❌ Do not call `skill(Squad)`, `skill(squad)`, or `skill(squad-coordinator)` — Squad is not a skill.
+- ❌ Do not type `/squad` expecting a slash command — slash commands are CLI keywords, not skill names. Use `/agent` (browse) or invoke the `Squad` agent via the `task` tool.
+- ❌ Do not call `task(agent_type="Squad", …)` for tiny tasks the current agent can handle directly. Squad is for work that needs orchestration; trivial edits do not.
+
+---
+
+## How this skill was discovered
+
+This skill ships from the Squad SDK templates and is wired into `MANIFEST_SKILL_NAMES`. It lives at `.copilot/skills/squad-help/SKILL.md` so the Copilot CLI's `/skills` loader picks it up alongside the other bundled Squad skills.
+
+If you removed this skill on purpose, the model will fall back to its own reasoning and may make the lookup mistakes described above.
+
+---
+
+## See also
+
+- `.github/agents/squad.agent.md` — the actual Squad coordinator agent
+- `.copilot/skills/squad-commands/SKILL.md` — the command catalog
+- `.copilot/skills/squad-conventions/SKILL.md` — conventions for working on the Squad codebase itself
+- `.copilot/skills/squad-version-check/SKILL.md` — version-stamping mechanics

package/templates/skills/squad-version-check/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: "squad-version-check"
+description: "Internals of how @bradygaster/squad-cli stamps its version, how `squad upgrade` works (what it preserves vs overwrites), and how to probe the npm registry for the latest version from a coordinator prompt."
+allowedTools: []
+confidence: medium
+domain: squad-internals
+source: "Discovered by Data; validated in bradygaster/squad#1173 recon (2026-05-26)."
+---
+
+# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics
+
+**Confidence:** medium
+**Discovered by:** Data
+**Date:** 2026-05-26
+**Validated in:** Issue #1173 recon (bradygaster/squad)
+
+---
+
+## What This Skill Covers
+
+Reusable knowledge about how `@bradygaster/squad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt.
+
+---
+
+## Package & Registry Facts
+
+- **Package name:** `@bradygaster/squad-cli`
+- **Registry:** npm (public)
+- **CLI binary:** `squad` (registered via `package.json#bin.squad`)
+- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase)
+
+---
+
+## Version Stamping Mechanism
+
+**Source file:** `dist/cli/core/version.js`
+
+Three functions:
+
+### `getPackageVersion()`
+Walks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist/cli/core/version.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found.
+
+### `stampVersion(filePath, version)`
+Mutates `squad.agent.md` in three places:
+1. HTML comment: `<!-- version: {version} -->` (must be on the line immediately after frontmatter `---`)
+2. Identity line: `- **Version:** {version}`
+3. Greeting instruction: backtick-quoted `` `Squad v{version}` ``
+
+**Called by:** both `init` and `upgrade` — after copying the template to the destination.
+
+### `readInstalledVersion(filePath)`
+Reads the stamped version back from `squad.agent.md`:
+1. First tries HTML comment format: `/<!-- version: ([0-9.]+(?:-[a-z]+(?:\.\d+)?)?) -->/`
+2. Falls back to old frontmatter format: `/^version:\s*"([^"]+)"/m`
+3. Returns `'0.0.0'` on any error
+
+---
+
+## `squad upgrade` Behavior
+
+**Source file:** `dist/cli/core/upgrade.js`
+
+### What gets overwritten:
+- `squad.agent.md` — full overwrite from template, then `stampVersion()`
+- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled)
+- GitHub Actions workflows — from `templates/workflows/`; non-npm projects get type-aware stubs
+- Runs `runMigrations()` after file copy
+
+### What is PRESERVED:
+- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned)
+- `agents/*/history.md` (individual agent memory)
+- `.squad/config.json` — **never touched**; `stateBackend` survives intact
+- User-added files not in TEMPLATE_MANIFEST
+
+### Self-upgrade path (`selfUpgradeCli()`):
+Detects npm/pnpm/yarn via `npm_execpath` and `npm_config_user_agent`. Runs:
+- npm: `npm install -g @bradygaster/squad-cli@latest`
+- pnpm: `pnpm add -g @bradygaster/squad-cli@latest`
+- yarn: `yarn global add @bradygaster/squad-cli@latest`
+Use `@insider` tag for insider builds.
+
+### `compareSemver(a, b)` utility (in upgrade.js):
+Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` < `0.9.5`). Can be ported directly if needed in prompt logic.
+
+---
+
+## `.squad/config.json` — What It Holds
+
+```json
+{
+  "version": 1,
+  "stateBackend": "worktree"
+}
+```
+
+Other optional fields added by the coordinator at runtime:
+- `defaultModel` — global model override for all agent spawns
+- `agentModelOverrides.{agentName}` — per-agent model override
+
+The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences).
+
+---
+
+## Version-Check Probe (npm Registry)
+
+Use this one-liner from inside a coordinator prompt to fetch dist-tags:
+
+```
+npm view @bradygaster/squad-cli dist-tags --json
+```
+
+- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting.
+- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`).
+- On any error (network failure, registry unreachable, parse error): show normal greeting.
+
+---
+
+## Upstream OS-Specific Cache
+
+The CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL.
+
+**One-liner to read the upstream cache:**
+```
+node -e "const p=require('path'),o=require('os');const b=process.env.APPDATA||(process.platform==='darwin'?p.join(o.homedir(),'Library','Application Support'):p.join(o.homedir(),'.config'));const f=p.join(b,'squad-cli','update-check.json');try{const d=JSON.parse(require('fs').readFileSync(f,'utf8'));const age=Date.now()-d.checkedAt;if(age<86400000)console.log(JSON.stringify(d));else console.log('STALE')}catch{console.log('MISS')}"
+```
+
+Output semantics:
+- Valid JSON `{"latestVersion":"X.Y.Z","checkedAt":N}` → cache hit; use `latestVersion`
+- `STALE` → cache expired (older than 24h); treat as no data
+- `MISS` → cache missing or corrupt; treat as no data
+
+**OS-specific cache path:**
+- Windows: `%APPDATA%\squad-cli\update-check.json`
+- Linux: `~/.config/squad-cli/update-check.json`
+- macOS: `~/Library/Application Support/squad-cli/update-check.json`
+
+---
+
+## Repo-Local Cache Convention: `.squad/.cache/version-check.json`
+
+Used by coordinator for `insider`/`preview` channels (the upstream cache only stores `latest`).
+
+**Schema:**
+```json
+{
+  "checkedAt": "2026-05-26T14:13:28.492Z",
+  "currentVersion": "0.9.6-insider.2",
+  "channel": "insider",
+  "channelVersion": "0.9.7-insider.1"
+}
+```
+
+**TTL:** 24 hours from `checkedAt`.
+**Gitignore:** `.squad/.cache/` is listed in `.gitignore` — cache files are never committed.
+
+---
+
+## Key File Paths (installed CLI)
+
+| Purpose | Path |
+|---|---|
+| Version utilities | `dist/cli/core/version.js` |
+| Upgrade logic | `dist/cli/core/upgrade.js` |
+| Init logic | `dist/cli/core/init.js` |
+| Template manifest | `dist/cli/core/templates.js` |
+| Copilot install helper | `dist/cli/copilot-install.js` |
+| squad.agent.md template | `templates/squad.agent.md.template` |
+| Session init reference | `templates/session-init-reference.md` |
+| All templates | `templates/` |