@bradygaster/squad-cli 0.10.0 → 0.11.0

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

@@ -1,3 +1,12 @@
+---
+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

package/templates/skills/tiered-memory/SKILL.md

@@ -1,33 +1,35 @@
 ---
 name: tiered-memory
-description: Three-tier agent memory model (hot/cold/wiki) for 20-55% context reduction per spawn
+description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn
 domain: memory-management, performance
-confidence: high
-source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads)
+confidence: design (runtime not yet implemented)
+source: design proposal
 ---
 
 # Skill: Tiered Agent Memory
 
+> **Status (v0.10.0):** This skill describes a **design proposal**, not a shipped runtime. Skill files install via `squad init`/`upgrade`, but the underlying tier scaffolding (`.squad/memory/hot/`, `cold/`, `wiki/`), Scribe promotion logic, and spawn-template tier-aware reads are tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264). Until those land, agents continue to load full `history.md` + `decisions.md` on every spawn.
+
 ## Overview
 
-Squad agents currently load their full context history on every spawn, resulting in 34–74KB payloads per agent (8,800–18,500 tokens). Measurement shows 82–96% of that context is "old noise" — information that is no longer relevant to the current task. The Tiered Agent Memory skill introduces a three-tier memory model that eliminates this bloat, achieving 20–55% context reduction per spawn in production.
+Squad agents today load their full context history on every spawn, which grows unboundedly across sessions. The Tiered Agent Memory model proposes a three-tier separation so agents only load the bytes that are actually relevant to the current task, with older context kept available on demand.
 
 ---
 
 ## Memory Tiers
 
 ### 🔥 Hot Tier — Current Session Context
-- **Size target:** ~2–4KB
+- **Size target:** keep small (~2–4KB typical)
 - **Load policy:** Always loaded. Every spawn includes hot memory by default.
 - **Contents:** Current task description, active decisions made this session, immediate blockers, last 3–5 actions taken, who you are talking to right now.
 - **Lifetime:** Current session only. Discarded after session ends (Scribe promotes relevant parts to Cold).
 - **Purpose:** Provide immediate task context without any latency or load decision.
 
 ### ❄️ Cold Tier — Summarized Cross-Session History
-- **Size target:** ~8–12KB
+- **Size target:** larger summary, not full transcript (~8–12KB typical)
 - **Load policy:** Load on demand. Include only when the task explicitly needs history.
 - **Contents:** Summarized past sessions (compressed by Scribe), cross-session decisions, recurring patterns, unresolved issues from prior work.
-- **Lifetime:** 30 days rolling window. After 30 days, Scribe promotes to Wiki tier.
+- **Lifetime:** Rolling window (default proposal: 30 days). Eligible entries are then promoted to Wiki.
 - **Purpose:** Answer "what have we tried before?" and "what was decided?" without replaying full transcripts.
 - **How to include:** Pass `--include-cold` in spawn template or add `## Cold Memory` section.
 
@@ -89,49 +91,34 @@ See: .squad/memory/wiki/{topic}.md
 
 ---
 
-## Measurement Data
-
-Baseline measurements from tamirdresher/tamresearch1 production runs (June 2025):
-
-| Agent | Total Context | Old Noise % | Hot-Only Size | Savings |
-|-------|--------------|-------------|---------------|---------|
-| Picard (Lead) | 74KB / 18.5K tokens | 96% | ~3KB | 55% |
-| Scribe | 52KB / 13K tokens | 91% | ~4KB | 48% |
-| Data | 43KB / 10.7K tokens | 88% | ~3.5KB | 42% |
-| Ralph | 38KB / 9.5K tokens | 85% | ~3KB | 38% |
-| Worf | 34KB / 8.5K tokens | 82% | ~3KB | 20% |
-
-**Average savings: 20–55% per spawn** with Hot-only loading. Cold + Wiki on-demand adds ~2–8KB when needed, still well below current baselines.
-
----
-
-## Integration with Scribe Agent
+## Integration with Scribe Agent (design — not yet implemented)
 
-Scribe is the memory coordinator for this system. It automates tier promotion:
+Scribe is the proposed memory coordinator for this system. Once the runtime lands, Scribe will:
 
-1. **End of session:** Scribe compresses Hot → Cold summary (keeps ~10% of session verbosity)
-2. **After 30 days:** Scribe promotes Cold → Wiki for decisions/facts that aged into stable knowledge
-3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session using `scribe:wiki-write`
+1. **End of session:** Compress Hot → Cold summary (target: ~10% of session verbosity)
+2. **Aged cold entries:** Promote Cold → Wiki for decisions/facts that aged into stable knowledge
+3. **On-demand wiki writes:** Any agent can request Scribe to write a wiki entry mid-session
 
-See Scribe charter: `.squad/agents/scribe/charter.md`
+Until then, see the Scribe charter for current behavior: `.squad/agents/scribe/charter.md`
 
 ---
 
-## Implementation Checklist
+## Implementation Checklist (tracked in #1264)
 
 - [ ] Scribe writes Hot context file at session start (`.squad/memory/hot/{agent}.md`)
 - [ ] Scribe compresses and writes Cold summary at session end
 - [ ] Spawn templates default to Hot-only
 - [ ] Coordinators add `--include-cold` / `--include-wiki` flags as needed
 - [ ] Wiki entries stored in `.squad/memory/wiki/`
-- [ ] Cold entries stored in `.squad/memory/cold/` with 30-day TTL
+- [ ] Cold entries stored in `.squad/memory/cold/` with rolling TTL
 
 ---
 
 ## References
 
-- Upstream issue: bradygaster/squad#600
-- Production data: tamirdresher/tamresearch1 (June 2025)
+- Tracking issue: [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — installation gap + runtime status
+- Original design spike: [bradygaster/squad#686](https://github.com/bradygaster/squad/issues/686) — tiered memory implementation plan
+- Related: [bradygaster/squad#600](https://github.com/bradygaster/squad/issues/600) — context payload growth
 
 ---
 
@@ -162,7 +149,7 @@ Use this template when spawning any Squad agent. By default it loads **Hot tier
 
 ### 🔥 Hot (always included)
 
-> Paste current session context here (2–4KB max):
+> Paste current session context here (~2–4KB target):
 
 ```
 Current task: {task_description}
@@ -178,12 +165,12 @@ Talking to: {current_interlocutor}
 
 > Load on demand. Do not inline unless specifically needed.
 
-Summarized cross-session history is at:  
+Summarized cross-session history is at:
 `.squad/memory/cold/{agent-name}.md`
 
 Include when:
 - Resuming interrupted work
-- Debugging a recurring issue  
+- Debugging a recurring issue
 - "What have we tried before?"
 
 **To load cold memory, add this section and fetch the file before spawning:**
@@ -218,17 +205,17 @@ Include when:
 ## Escalation
 
 If blocked or uncertain:
-- Architecture questions → @picard  
-- Security concerns → @worf  
-- Infrastructure/deployment → @belanna  
-- Memory/history questions → @scribe  
+- Architecture questions → @picard
+- Security concerns → @worf
+- Infrastructure/deployment → @belanna
+- Memory/history questions → @scribe
 
 ---
 
 ## Notes
 
-- Hot tier is always included and should stay under 4KB
-- Cold adds ~8–12KB; only include when history is relevant
+- Hot tier is always included; keep it focused
+- Cold adds a summary; only include when history is relevant
 - Wiki adds variable size; only include specific relevant docs
-- See `skills/tiered-memory/SKILL.md` for full tier reference
-- See `docs/tiered-memory-guide.md` for wiring instructions
+- Runtime backing is tracked in [bradygaster/squad#1264](https://github.com/bradygaster/squad/issues/1264) — until those changes land, this skill is design-only and agents continue to load full history.md + decisions.md on every spawn
+

package/templates/spawn-reference.md

@@ -2,7 +2,62 @@
 
 ### How to Spawn an Agent
 
-**You MUST dispatch every agent spawn** via the platform's tool (`task` on CLI, `runSubagent` on VS Code):
+**You MUST dispatch every agent spawn** via the platform's tool:
+- **CLI:** `task` tool
+- **VS Code:** `runSubagent` tool
+- **Copilot App:** `create_session` tool (when available — see Sub-Sessions below)
+
+**Platform detection (run once at session start):**
+- `create_session` tool exists → **App mode** → sub-sessions for commit-producing work
+- `runSubagent` tool exists → **VS Code mode** → subagents
+- `task` tool exists → **CLI mode** → task tool
+- None available → **work inline** (last resort fallback)
+
+---
+
+### Sub-Sessions (Copilot App Mode)
+
+When `create_session` is available, spawn commit-producing agents as **sub-sessions** instead of tasks. Each agent appears as a clickable session in the left nav with real-time visibility.
+
+**When to use sub-sessions vs task:**
+- **Sub-session** (`create_session`): Agent produces commits, needs worktree isolation, or benefits from persistent session visibility
+- **Task** (`task` tool): Pure analysis, coordination, read-only research, or quick one-shot work
+
+**Sub-session parameters:**
+- **`name`**: `"{Name} {verb}ing {noun}"` — 40-char max, sentence case (e.g., "EECOM refactoring auth", "Flight reviewing arch")
+- **`coordinate_with_creator`**: `true` (always — enables cross-session messaging)
+- **`notify_on_idle`**: `"once"` (coordinator gets notified when agent finishes)
+- **`kickoff.prompt`**: The full agent prompt (same as task prompt below)
+- **`kickoff.mode`**: `"autopilot"` (agents work autonomously)
+- **`kickoff.model`**: `"{resolved_model}"`
+
+**Constraints:**
+- **Max depth:** 1 — no sub-sub-sessions. If an agent needs to delegate, it uses `task` tool.
+- **Concurrency cap:** Maximum 4-5 simultaneous sub-sessions. Queue additional spawns.
+- **Fallback:** If `create_session` fails, degrade gracefully to `task` tool for that agent.
+
+**Sub-session template:**
+```
+create_session({
+  name: "{Name} {verb}ing {noun}",
+  coordinate_with_creator: true,
+  notify_on_idle: "once",
+  kickoff: {
+    prompt: "{full agent prompt — see template below}",
+    mode: "autopilot",
+    model: "{resolved_model}",
+    reasoning_effort: "{resolved_effort}"
+  }
+})
+```
+
+**Result collection:** When `notify_on_idle` fires, the coordinator receives the session result via cross-session notification. No polling required.
+
+---
+
+### Task Tool Spawn (CLI Mode)
+
+Standard spawn via `task` tool — used in CLI, or as fallback when `create_session` is unavailable:
 
 - **`agent_type`**: `"general-purpose"` (always — this gives agents full tool access)
 - **`mode`**: `"background"` (default) or `"sync"` — use `"background"` for all parallelizable work; use `"sync"` only when the result is needed before the next step can proceed
@@ -81,7 +136,7 @@ prompt: |
   Read `decisions.md` with `squad_state_read` when state tools are available; otherwise fall back to `.squad/decisions.md`.
   If .squad/identity/wisdom.md exists, read it before starting work.
   If .squad/identity/now.md exists, read it at spawn time.
-  Check project skill directories (.squad/skills/, .copilot/skills/, .github/skills/, .claude/skills/, .agents/skills/) for any SKILL.md the coordinator attached to your prompt.
+  Check project skill directories (.squad/skills/, .github/skills/, .copilot/skills/, .claude/skills/, .agents/skills/) for any SKILL.md the coordinator attached to your prompt.
   Read any relevant SKILL.md files before working.
 
   ⚠️ WORK FRESHNESS: When determining what to work on: