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

package/templates/session-init-reference.md

@@ -0,0 +1,199 @@
+# Session Init Reference
+
+Procedures the coordinator runs at session start, in order. Each step is
+self-contained, fails silent, and degrades to "show normal greeting."
+
+---
+
+## Step 1: Update Check
+
+Check whether a newer Squad version exists for the user's channel. Append to
+the greeting if a newer version is found. Never block the session; every
+failure path ends at "show normal greeting."
+
+### 1.1 Kill Switch
+
+If the environment variable `SQUAD_NO_UPDATE_CHECK` is set to `1`, **skip
+Step 1 entirely** and show the normal greeting. This is the same kill switch
+as the upstream CLI banner — one opt-out disables both.
+
+### 1.2 Channel Detection
+
+Read the stamped version from the `<!-- version: X -->` HTML comment at the
+top of `squad.agent.md` (or from the `- **Version:** X` identity line as
+fallback). Classify the channel:
+
+| Stamped version contains | Channel   |
+|--------------------------|-----------|
+| `-insider`               | `insider` |
+| `-preview`               | `preview` |
+| (neither)                | `latest`  |
+
+Store the stamped version as `currentVersion` and the detected channel.
+
+### 1.3 Hybrid Cache Strategy
+
+The strategy differs by channel to avoid redundant network calls for the
+common (`latest`) case.
+
+#### For `latest` channel — read upstream OS-specific cache
+
+The upstream Squad CLI (`self-update.ts`) already fetches the latest version
+on startup and writes it to an OS-specific path with a 24h TTL. Read that
+cache instead of making a new npm call.
+
+**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
+
+On `STALE` or `MISS`, show the normal greeting (no notice). Do **not** make an
+independent npm call for `latest`-channel users — the upstream CLI will refresh
+the cache on its next run.
+
+**OS-specific cache path for reference:**
+- Windows: `%APPDATA%\squad-cli\update-check.json`
+- Linux: `~/.config/squad-cli/update-check.json`
+- macOS: `~/Library/Application Support/squad-cli/update-check.json`
+
+#### For `insider` / `preview` channels — own probe with repo-local cache
+
+The upstream cache only stores the `latest` dist-tag and is not useful for
+pre-release channels. Use a separate probe.
+
+**Step A — Check repo-local cache:**
+
+Read `.squad/.cache/version-check.json`. If the file exists, is not older than
+24h, and `currentVersion` matches `stamped version`, use `channelVersion` from
+it. Skip the npm probe.
+
+**Repo-local cache schema:**
+```json
+{
+  "checkedAt": "2026-05-26T14:13:28.492Z",
+  "currentVersion": "0.9.6-insider.2",
+  "channel": "insider",
+  "channelVersion": "0.9.7-insider.1"
+}
+```
+
+**Step B — npm probe (on cache miss / stale / version mismatch):**
+
+```
+npm view @bradygaster/squad-cli dist-tags --json
+```
+
+- Timeout: **5 seconds.** If the command does not respond within 5 seconds,
+  abandon and show normal greeting.
+- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`).
+  Write `.squad/.cache/version-check.json` with the schema above.
+  Create `.squad/.cache/` if it does not exist.
+- On any error (network failure, registry unreachable, parse error): show
+  normal greeting.
+
+### 1.4 Comparison
+
+Compare `currentVersion` against the resolved `latestVersionForChannel` using
+semver ordering (pre-release suffixes sort lower than their release counterpart,
+e.g., `0.9.5-insider.1 < 0.9.5`).
+
+- `latestVersionForChannel > currentVersion` → update available
+- Equal or older → no notice
+
+### 1.5 Greeting Append
+
+When an update is available, append to the normal greeting (on the same line,
+separated by ` · `):
+
+```
+ · 🆕 v{latestVersionForChannel} available — say "upgrade squad"
+```
+
+Example complete greeting line:
+```
+Squad v0.9.4-insider.1 · 🆕 v0.9.7-insider.1 available — say "upgrade squad"
+```
+
+Do not mention the update check, the cache, or the mechanism. Just the notice.
+
+### 1.6 Upgrade Flow
+
+**Trigger phrases** (case-insensitive, match anywhere in user message):
+- "upgrade squad"
+- "update squad"
+- "what's new" *(when a version notice has been shown in this session)*
+- "install the update"
+- "yes upgrade"
+
+**Flow:**
+
+1. **Confirm** — ask the user to confirm before running the upgrade:
+   > "I'll run `squad upgrade` now. This overwrites `squad.agent.md` and
+   > casting files but preserves `config.json`, `team.md`, `decisions.md`,
+   > and all agent history. Ready?"
+   Wait for affirmative response before proceeding.
+
+2. **Run upgrade:**
+   ```
+   squad upgrade
+   ```
+   Capture output. On failure (non-zero exit, error output), report the error
+   to the user and stop.
+
+3. **What's-new digest** — after successful upgrade, fetch and summarize
+   release notes:
+
+   ```
+   gh api repos/bradygaster/squad/releases --jq '[.[] | select(.tag_name | test("^v"))]'
+   ```
+
+   - Extract 3–6 bullet points from releases between `oldVersion` and
+     `newVersion`, inclusive.
+   - Priority: `feat` entries first, then `fix`, then `docs`.
+   - Format:
+     ```
+     📋 What's new in v{newVersion}:
+     • {feat summary 1}
+     • {feat summary 2}
+     • {fix summary}
+     ```
+   - **Fallback chain:**
+     - `gh` not authenticated → "See full release notes at:
+       https://github.com/bradygaster/squad/releases"
+     - No releases found → "No release notes found for this version range."
+     - Network failure → link to releases page
+
+4. **Restart prompt** — after showing the digest, prompt the user:
+   > "`squad.agent.md` has been updated. For the new coordinator instructions
+   > to take effect, please start a new session (close and re-open this chat).
+   > Your team state and decisions are unchanged."
+
+### 1.7 Failure Modes
+
+Every failure path ends at "show normal greeting." The update check never
+interrupts or delays the session.
+
+| Failure | Behavior |
+|---------|----------|
+| `node` not on PATH | `MISS` → normal greeting |
+| Upstream cache missing / corrupt | `MISS` → normal greeting |
+| Upstream cache stale (`latest` channel) | Normal greeting (no npm call) |
+| npm probe timeout (5s) | Normal greeting |
+| npm probe network error | Normal greeting |
+| npm probe parse error | Normal greeting |
+| `.squad/.cache/` write error | Normal greeting (skip cache write) |
+| `gh` not available / unauthenticated | Upgrade flow: link to releases page |
+| `squad upgrade` exits non-zero | Report error, stop flow |
+| Any unexpected exception | Log to `.squad/orchestration-log/`, normal greeting |
+
+---
+
+## (Future steps reserved)
+
+- Step 2: \<reserved\> — e.g., dependency drift check
+- Step 3: \<reserved\> — e.g., repo policy / state-backend audit

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

@@ -1,9 +1,20 @@
 ---
 name: "cross-squad"
-description: "Coordinating work across multiple Squad instances"
+description: "Coordinating work across multiple Squad instances — discovery, delegation, and disambiguation when the user says 'squad' (the product) vs casual English 'group of agents'."
 domain: "orchestration"
 confidence: "medium"
 source: "manual"
+triggers:
+  - "spawn N squads"
+  - "spawn a squad"
+  - "another squad"
+  - "two squads of"
+  - "second squad"
+  - "fan out to squads"
+  - "delegate to a squad"
+  - "set up squads for"
+  - "create a squad to review"
+  - "ask the other squad"
 tools:
   - name: "squad-discover"
     description: "List known squads and their capabilities"
@@ -14,21 +25,60 @@ tools:
 ---
 
 ## Context
+
+> **Read this FIRST any time the user says "squad" as a thing to spawn, delegate to, address, or fan out to** — e.g., *"spawn two squads of designers and devs"*, *"ask the other squad"*, *"delegate to a squad"*. In Squad-PRODUCT vocabulary, "squad" is a **peer** (an independent installation with its own `.squad/`, `team.md`, MCP server, and agents) — NOT a generic English synonym for "team" or "group". Do not fan out raw `task` agents inside your own coordinator context when the user means "another squad". Use the discovery and communication patterns below (and the companion `cross-squad-communication` skill for the actual protocols).
+
 When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling.
 
+> **Companion skill — for protocol details:** `cross-squad-communication/SKILL.md` covers the four communication patterns (synchronous CLI, read-only knowledge query, git-based async, and GitHub-issue-based delegation) once a peer squad is discovered via the registry below. This skill answers "who?" — the companion answers "how?".
+
 Cross-squad orchestration applies when:
 - A task requires capabilities owned by another squad
 - An architectural decision affects multiple squads
 - A feature spans multiple repositories with different squads
 - A squad needs to request infrastructure, tooling, or support from another squad
 
+## Disambiguation: "squad" vs ad-hoc agents
+
+When the user uses the word **"squad" / "squads"** or asks to **"spawn a team"**, the coordinator MUST treat it as a literal reference to a Squad install (a `.squad/` directory with its own roster, casting, and coordinator) — NOT as a casual synonym for "a group of sub-agents".
+
+### Default behaviour (apply unless explicitly told otherwise)
+
+| User says | Coordinator does |
+|---|---|
+| *"spawn two squads of X and Y"* / *"set up squads for X, Y, Z"* | Bootstrap N **real** Squad installs — separate folder + `git init` + `squad init` per squad — then use the cross-squad patterns below (`.squad/manifest.json`, `squad registry add`, `squad delegate`) and the protocols in the `cross-squad-communication` skill |
+| *"ask the other squad about X"* / *"delegate to the data squad"* | Discover the peer via `squad registry list` (or by reading a known `.squad/manifest.json`), then use `cross-squad-communication` Pattern 0 / 1 / 2 / 3 — never re-implement the protocol with `task` |
+| *"spawn a few agents to do X"* / *"have some agents review X"* / *"in parallel, get sub-agents to..."* | Ad-hoc `task` fan-out is fine — no `.squad/` bootstrap needed. This is the only path where raw `task` is appropriate when the user mentioned a multi-agent activity |
+
+### Ambiguous? `ask_user`, never silently downgrade
+
+If the request **could** be either interpretation AND bootstrapping real squads is non-trivial (more than one or two `squad init` runs), you MUST use the `ask_user` tool with a 2-choice prompt before proceeding:
+
+```
+question: "Should I create separate Squad installs or just dispatch ad-hoc agents?"
+choices:
+  - "Real squads — separate .squad/ per squad (heavier, persistent, can be re-engaged later)"
+  - "Ad-hoc agents — one-shot `task` dispatch (lighter, ephemeral, no .squad/ created)"
+```
+
+The cost of asking is one `ask_user`. The cost of getting it wrong is the user has to redo the work. **Never silently pick the cheaper option just because it feels disproportionate for the task size — surface the trade-off and let the user pick.**
+
+### Anti-patterns (every one of these is a real failure mode observed in production)
+
+- **Calling `task` sub-agents "squad-alpha" / "squad-beta"** and treating them as squads. Naming something a squad doesn't make it one — a squad has its own `.squad/`, `team.md`, MCP server, and coordinator. If those aren't there, it's not a squad.
+- **Matching a prior session's ad-hoc pattern without re-checking current intent.** If you see existing `reviews/squad-alpha/` folders from a previous run, that's a hint, NOT a contract — the user may have meant something different this time. Re-evaluate from scratch.
+- **Silently choosing the cheaper interpretation because "bootstrapping two real squads for a 30-line app feels disproportionate".** That's a judgment call for the USER to make, not the coordinator. Use `ask_user`.
+- **Loading the `cross-squad` skill, reading it, then doing `task` fan-out anyway** because the eager-execution / parallel-fan-out doctrine pulled you back. The disambiguation rule on this page OVERRIDES the generic fan-out doctrine when "squad" was the trigger.
+
 ## Patterns
 
 ### Discovery via Manifest
-Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through:
-1. **Well-known paths**: Check `.squad/manifest.json` in known org repos
-2. **Upstream config**: Squads already listed in `.squad/upstream.json` are checked for manifests
-3. **Explicit registry**: A central `squad-registry.json` can list all squads in an org
+Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through two mechanisms:
+
+1. **`.squad/squad-registry.json`** — **discovery-only.** Peer squads are findable via `squad discover` and addressable via `squad delegate`, but their skills/decisions/wisdom are NOT loaded into your coordinator. Manage with `squad registry add/list/remove`.
+2. **`.squad/upstream.json`** — **discovery + inheritance.** Squads listed here are also discoverable, AND your coordinator inherits their skills/decisions/wisdom/routing at session start. Manage with `squad upstream add/list/remove/sync`.
+
+Both forms read the peer's manifest via the same code path. The `path` field is the **repository root** (e.g. `../friend-repo`), and Squad appends `.squad/manifest.json` internally. Pointing at the `.squad/` directory works too — Squad accepts both forms (`readManifest` strips a trailing `.squad` if present).
 
 ```json
 {
@@ -73,9 +123,19 @@ Track delegated work completion:
 
 ## Examples
 
+### Registering a peer squad (no inheritance)
+```bash
+# Friend's repo is checked out at ../friend-platform/
+squad registry add platform-squad ../friend-platform
+
+# Verify
+squad registry list
+squad discover
+```
+
 ### Discovering squads
 ```bash
-# List all squads discoverable from upstreams and known repos
+# List all squads discoverable from registry + upstreams
 squad discover
 
 # Output: