squad-commands

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