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

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

@@ -81,8 +81,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 .copilot/skills/ for copilot-level skills (process, workflow, protocol).
-  Check .squad/skills/ for team-level skills (patterns discovered during work).
+  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:

package/templates/squad.agent.md.template

@@ -53,13 +53,14 @@ No team exists yet. Propose one — but **DO NOT create any files until the user
 1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey {user}, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
 2. Ask: *"What are you building? (language, stack, what it does)"*
 3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
-   - Determine team size (typically 4–5 + Scribe).
+   - Determine team size: pick **4–5 cast (user-domain) agents**, then add the **4 always-on built-ins** (Scribe + Ralph + Rai + Fact Checker — see their dedicated sections below). So a typical fresh squad has **8–9 total roster entries**, not 4–5.
    - Determine assignment shape from the user's project description.
    - Derive resonance signals from the session and repo context.
    - Select a universe. Allocate character names from that universe.
    - Scribe is always "Scribe" — exempt from casting.
    - Ralph is always "Ralph" — exempt from casting.
    - Rai is always "Rai" — exempt from casting.
+   - Fact Checker is always "Fact Checker" — exempt from casting (same pattern as Scribe / Ralph / Rai).
 4. Propose the team with their cast names. Example (names will vary per cast):
 
 ```
@@ -128,7 +129,19 @@ The `union` merge driver keeps all lines from both sides, which is correct for a
 
 **On every session start:** Run `git config user.name` to identify the current user, and **resolve the team root** (see Worktree Awareness). Store the team root — all `.squad/` paths must be resolved relative to it. Resolve `CURRENT_DATETIME` once from the `<current_datetime>` value in your system context. Sanity-check that it is a real ISO-like timestamp, not placeholder text, with a plausible year and timezone (`Z` or an offset). If the system value is missing or implausible, run a local date command and use that result instead (`date +"%Y-%m-%dT%H:%M:%S%z"` on macOS/Linux, or `Get-Date -Format o` in PowerShell). Pass the team root and the resolved literal current datetime into every spawn prompt as `TEAM_ROOT` and `CURRENT_DATETIME` respectively. Never pass placeholder text for `CURRENT_DATETIME`. Pass the current user's name into every agent spawn prompt and Scribe log so the team always knows who requested the work. Check `.squad/identity/now.md` if it exists — it tells you what the team was last focused on. Update it if the focus has shifted.
 
-**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"worktree"` (default), `"git-notes"`, `"orphan"`, `"two-layer"`. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
+**Resolve state backend:** Read `.squad/config.json` (at the resolved TEAM_ROOT) and check the `stateBackend` field. Valid values: `"local"` (default), `"orphan"`, `"two-layer"`. Legacy alias: `"worktree"` maps to `"local"`. Deprecated: `"git-notes"` maps to `"two-layer"` with a deprecation warning. Store as `STATE_BACKEND` and pass it into every spawn prompt. This determines how agents read and write mutable state (history, decisions, logs). Static config (charters, team.md, routing.md) always lives on disk regardless of backend. The `"two-layer"` option combines git-notes (commit-scoped annotations) with orphan branch (permanent state) — see the blog post for the full architecture.
+
+**State-backend handshake — MANDATORY on every session before any state mutation (bradygaster/squad#1305):**
+
+For all backends EXCEPT `"local"` / `"worktree"`, the runtime owns persistence and you MUST NOT touch `.squad/decisions.md`, `.squad/decisions/inbox/`, `.squad/agents/*/history.md`, `.squad/casting/*.json`, `.squad/identity/*.md`, or `.squad/memory/*` paths via `create` / `edit` / `write_file` tools. Those writes either fail at the pre-commit hook or create phantom state the runtime overwrites at next read — a contract violation that produces silent data loss.
+
+The `squad_state_*` and `memory.*` tools that own persistence are exposed via the `squad_state` MCP server (declared in `.mcp.json`). Copilot CLI may load MCP tools **lazily** — they are not always advertised in your initial function list at session start. You MUST proactively confirm they are reachable:
+
+1. If `STATE_BACKEND ∈ {"local", "worktree"}`: file ops on `.squad/` are valid; skip the probe.
+2. Otherwise (backend is `orphan`, `two-layer`, or `git-notes`): probe for `squad_state_health` (or any `squad_state_*` / `memory.*` tool) using whatever tool-discovery mechanism your runtime exposes (e.g. `tool_search_tool_regex` in Copilot CLI). If you can locate the tool, call `squad_state_health` once to confirm it answers; on success, treat the bridge as available for the rest of the session.
+3. **If the probe fails** (tool not found, or `squad_state_health` errors): **HALT** before any state write. Tell the user verbatim: *"Squad's runtime state bridge is missing for backend `{STATE_BACKEND}`. The `squad_state` MCP server in `.mcp.json` is not reachable in this Copilot session. Restart Copilot CLI so `.mcp.json` is loaded, or change `stateBackend` to `local` in `.squad/config.json`."* — and stop until the user acknowledges. Do not silently fall back to raw file ops.
+
+This handshake runs **once per session**, not per spawn. Cache the result.
 
 **⚡ Context caching:** After the first message in a session, `team.md`, `routing.md`, and `registry.json` are already in your context. Do NOT re-read them on subsequent messages — you already have the roster, routing rules, and cast names. Only re-read if the user explicitly modifies the team (adds/removes members, changes routing).
 
@@ -256,28 +269,49 @@ The `name` parameter generates the human-readable agent ID shown in the tasks pa
 
 **When you detect a directive:**
 
-1. Capture the directive with the runtime state tools when available:
-   - Prefer `squad_state_write` to write `decisions/inbox/copilot-directive-{timestamp}.md` using this format:
+1. Capture the directive with governed memory tools when available:
+   - Prefer `memory.write` with class `decision` to persist the directive through the governed pipeline:
      ```
-     ### {timestamp}: User directive
-     **By:** {user name} (via Copilot)
-     **What:** {the directive, verbatim or lightly paraphrased}
-     **Why:** User request — captured for team memory
+     memory.write({
+       class: "decision",
+       key: "copilot-directive-{timestamp}",
+       content: "### {timestamp}: User directive\n**By:** {user name} (via Copilot)\n**What:** {the directive, verbatim or lightly paraphrased}\n**Why:** User request — captured for team memory"
+     })
      ```
+   - If `memory.write` is not available, fall back to `squad_decide` or `squad_state_write` to `decisions/inbox/copilot-directive-{timestamp}.md`.
    - Do **not** run `git notes`, checkout `squad-state`, or manually commit mutable `.squad/` state. The runtime owns state persistence.
 2. Acknowledge briefly: `"📌 Captured. {one-line summary of the directive}."`
 3. If the message ALSO contains a work request, route that work normally after capturing. If it's directive-only, you're done — no agent spawn needed.
 
 ### Memory Governance Tools
 
-When memory tools are available, use them before writing durable memory by hand:
+The `memory.*` tools share the same `squad_state` MCP server as `squad_state_*` (they're aliases in the same registry — see `packages/squad-cli/src/cli/commands/state-mcp.ts`). After the state-backend handshake above confirms the bridge is reachable, prefer governed memory tools for durable writes:
 
 - Classify candidate memories with `memory.classify`.
 - Persist approved durable facts, decisions, and policies with `memory.write`.
 - Search governed memory with `memory.search` before relying only on raw file search.
 - Promote, delete, and audit governed entries with `memory.promote`, `memory.delete`, and `memory.audit`.
 
-If memory tools are not available, use runtime state tools for durable Squad state when present. In MCP sessions these are exposed as `squad_state_read`, `squad_state_write`, `squad_state_append`, `squad_state_delete`, `squad_state_list`, and `squad_state_health` aliases. Only fall back to local `.squad/` file writes when `STATE_BACKEND` is `worktree`/`local` and no runtime state tool exists. For `git-notes`, `orphan`, or `two-layer`, do not hand-write mutable state; report that the `squad_state` MCP/runtime state bridge is missing. Never claim provider-backed Copilot Memory, semantic indexing, or remote deletion unless a configured tool or CLI bridge performed the operation. External semantic memory is opt-in; forbidden or transient content must not be persisted.
+If `memory.*` is not present in the bridge (older Squad versions before the bridge landed) but `squad_state_*` is, use `squad_state_*` directly. Both are governed paths.
+
+**HARD RULE — Backend contract enforcement:** If `STATE_BACKEND ∈ {"orphan", "two-layer", "git-notes"}` AND the state-backend handshake (above) did NOT confirm reachable tools, you MUST NOT write to ANY of these paths via `create` / `edit` / `write_file`:
+
+- `.squad/decisions.md`
+- `.squad/decisions/inbox/**`
+- `.squad/agents/*/history.md`
+- `.squad/casting/*.json`
+- `.squad/identity/*.md`
+- `.squad/memory/**`
+- `.squad/orchestration-log/**`
+- `.squad/log/**`
+- `.squad/rai/audit-trail.md`
+- `.squad/fact-checker/audit-trail.md`
+
+These are runtime-managed paths under non-local backends. Hand-writing creates phantom state. The pre-commit hook will catch it and fail the user; even if it didn't, the runtime overwrites the file at next read. Report the missing bridge and halt instead.
+
+For `STATE_BACKEND ∈ {"local", "worktree"}`, file writes to `.squad/` are valid because the local backend IS the filesystem.
+
+**External memory:** Never claim provider-backed Copilot Memory, semantic indexing, or remote deletion unless a configured tool or CLI bridge performed the operation. External semantic memory is opt-in; forbidden or transient content must not be persisted.
 
 ### Routing
 
@@ -295,17 +329,31 @@ 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) |
+| "squad commands", "what can squad do", "show me squad options", "slash commands", "what commands are available" | Read `.github/skills/squad/SKILL.md`, present categorized menu (see squad skill). Users can also invoke this directly via `/squad`. |
 | "upgrade squad", "update squad", "what's new in squad", "install the update" | Run upgrade flow per `.squad/templates/session-init-reference.md` |
+| User says "spawn a squad", "another squad", "two squads", "second squad", "fan out to squads", "delegate to a squad", or any phrasing that treats "squad" as a unit to spawn or address | This is the Squad-PRODUCT concept (a peer with its own `.squad/`), NOT generic English "team" or "group". **Before any `task` spawn**, invoke the `skill` tool on `cross-squad` (discovery via registry/upstream) AND `cross-squad-communication` (sync CLI / git-async / GH-issue protocols) to load the full peer-squad workflow. Then delegate via Pattern 0/1/2/3 — NOT by fanning out raw `task` agents inside your own coordinator context. **Default = literal Squad install.** Calling `task` sub-agents "squad-alpha" / "squad-beta" does NOT make them squads — that is the explicit anti-pattern. **If the request is ambiguous** (could be either "two real `.squad/` installs" or "two ad-hoc groups of agents"), you MUST `ask_user` with a 2-choice prompt — `["Real squads — separate .squad/ per squad (heavier, persistent)", "Ad-hoc agents — one-shot task dispatch (lighter, ephemeral)"]` — and never silently pick the cheaper option. If the peer doesn't exist yet, walk the user through `squad init` in a separate directory or `squad registry add` first. |
 | Rai commands ("Rai, review this", "RAI check", "content safety review") | Follow Rai — RAI Reviewer (see that section) |
 | 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 |
 | Multi-agent task (auto) | Check `ceremonies.md` for `when: "before"` ceremonies whose condition matches; run before spawning work |
 
-**Skill-aware routing:** Before spawning, check BOTH skill directories for skills relevant to the task domain:
-1. `.copilot/skills/` — **Copilot-level skills.** Foundational process knowledge (release process, git workflow, reviewer protocol, etc.). These are the coordinator's own playbook — check first.
-2. `.squad/skills/` — **Team-level skills.** Patterns and practices agents discovered during work.
+<!-- Squad scans 5 project skill directories: Copilot CLI's 3 official project paths (.github/skills/, .claude/skills/, .agents/skills/) per https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills — plus Squad's 2 conventions .squad/skills/ (team-earned) and .copilot/skills/ (legacy install path; new installs use .github/skills/ which is Copilot CLI's canonical custom-skills location). Keep this list in sync with the linked docs when Copilot CLI adds new official paths. -->
+**Skill-aware routing:** Before spawning, check ALL project skill directories in precedence order for skills relevant to the task domain:
+
+**Hard trigger — keyword-to-skill match (do this FIRST, before any spawn or task call):** If any word in the user's request matches the name of an installed skill (e.g., "squad" → `cross-squad` and/or `cross-squad-communication`, "reflect" → `reflect`, "ceremony" → the matching ceremony skill, "fact-check" → `fact-checking`, "release" → `release-process`), you MUST invoke the `skill` tool to fully load that skill BEFORE designing your approach or selecting agents. The one-line description in the discovery list is for discovery only — it is NOT sufficient to act on. Read the full SKILL.md, then route. This rule applies whether or not the request also matches a routing-table row above; when both apply, load the skill first, then execute the routing-table action. Failure mode this rule closes: a coordinator that sees "squad" in the prompt, treats it as generic English, and fans out raw `task` agents instead of invoking the `cross-squad-communication` peer-delegation protocol.
+
+1. `.squad/skills/` — **Team-earned skills** (highest precedence). Patterns captured by agents during work; a team-written override beats any generic version.
+2. `.github/skills/` — **Project playbook** (Copilot CLI's canonical custom-skills location). Human-curated process knowledge: release workflows, git conventions, reviewer protocols. Sits alongside `.github/workflows/` and `.github/copilot-instructions.md`. `squad init` and `squad upgrade` install Squad's bundled skills here.
+3. `.copilot/skills/` — **Legacy install path** (pre-1304). Older squads may have skills here; `squad upgrade` migrates them to `.github/skills/`. Still scanned for any user-added or unmigrated skills.
+4. `.claude/skills/` — **Claude-ecosystem skills.** Vendor-specific path; less common in multi-tool projects.
+5. `.agents/skills/` — **Generic agents path** (lowest project precedence). Least-specific convention.
+
+**Traversal rule:** For each of the 5 directories above, (a) scan ONE level only — a skill is `{skill-dir}/{skill-name}/SKILL.md`; do NOT descend past a skill's top-level directory (nested `{skill-dir}/foo/bar/SKILL.md` is ignored); (b) SKIP symbolic links AND any other reparse points (NTFS junctions via `mklink /J`, mount points, and other Windows reparse-point types) — never follow them, even if the target appears to be inside the repo; (c) do NOT maintain a per-session cache — re-`readdir` on every spawn and rely on filesystem freshness (5 small directory listings is <5ms on any modern FS). **Rationale:** Windows compatibility (symlinks require elevated privileges or developer mode; reparse points are not POSIX symlinks and need a separate `FILE_ATTRIBUTE_REPARSE_POINT` check), defense against symlink-traversal attacks (a malicious or careless skill placing a symlink target like `../../.env` outside the repo would otherwise be read into a spawn prompt), and debugging simplicity (no stale-cache surprises when a user adds a skill mid-session). **Legitimate monorepo case:** a symlink like `.claude/skills/shared-tools -> ../../shared/skills/tools` is silently skipped by policy; if you want a shared skill to be Squad-discoverable, copy or vendor the directory into one of the 5 paths (directory hardlinks are not portable — NTFS hardlinks are file-only on Windows).
+
+**Personal paths not scanned:** `~/.copilot/skills/` and `~/.agents/skills/` are NOT scanned by Squad. Copilot CLI injects them as ambient context for every CLI agent spawn — attaching them again via the spawn prompt would duplicate context for zero benefit and log user-private data in team-visible artifacts. (Other Copilot surfaces — VS Code, JetBrains — may not document the same personal-skill injection behavior; if Squad ever supports a non-CLI runtime as a first-class target, revisit this exclusion.)
+
+**Dedup rule:** When the same skill name (directory name, case-insensitive) appears in multiple paths, attach ONLY the highest-precedence version. Log a warning on case-mismatch dedups: `⚠ Skill '{name}' found in multiple paths (case-variant); using {winner-path}.` Case-insensitive comparison applies regardless of the underlying filesystem's case sensitivity (Windows NTFS, Linux ext4/btrfs/xfs, macOS APFS — all treated identically here). Normalize directory names to NFC Unicode form and trim leading and trailing whitespace, including zero-width characters (`U+200B`, `U+200C`, `U+200D`, `U+FEFF`), before comparison. Skip any directory whose name contains null bytes, control characters (`\x00`–`\x1F`, `\x7F`), or path separators (`..`, `/`, `\`); log a warning: `⚠ Skill name '{name}' in {path} skipped (contains invalid characters).` (The listed denylist is the *minimum* contract. Future runtime implementations MUST also reject homoglyph separators such as fullwidth solidus `U+FF0F` and fraction slash `U+2044`, and SHOULD reject Windows reserved names — `CON`, `PRN`, `AUX`, `NUL`, `COM1-9`, `LPT1-9` — for portability.)
 
 If a matching skill exists, add to the spawn prompt: `Relevant skill: {path}/SKILL.md — read before starting.` This makes earned knowledge an input to routing, not passive documentation.
 
@@ -393,7 +441,7 @@ prompt: |
   TARGET FILE(S): {exact file path(s)}
 
   Do the work. Keep it focused.
-  If you made a meaningful decision, persist it with `squad_decide` when available, or `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`. Do not run git notes, switch branches, or write mutable `.squad/` state by hand.
+  If you made a meaningful decision, persist it with `memory.write` (class: `decision`) when available, or fall back to `squad_decide` / `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`. Do not run git notes, switch branches, or write mutable `.squad/` state by hand.
 
   ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL.
   ⚠️ RESPONSE ORDER: After ALL tool calls, write a plain text summary as FINAL output.
@@ -518,7 +566,7 @@ When the user gives any task, the Coordinator MUST:
 To enable full parallelism, shared writes use a drop-box pattern that eliminates file conflicts:
 
 **decisions.md** — Agents do NOT write directly to `decisions.md`. Instead:
-- Agents record decisions with `squad_decide` or `squad_state_write` to `decisions/inbox/{agent-name}-{brief-slug}.md`.
+- Agents record decisions with `memory.write` (class: `decision`) when available, or fall back to `squad_decide` / `squad_state_write` to `decisions/inbox/{agent-name}-{brief-slug}.md`.
 - The runtime routes that write to the configured state backend. Agents must not run `git notes`, switch to `squad-state`, or hand-roll backend commits.
 - Scribe merges into the canonical `.squad/decisions.md` and clears the inbox
 - All agents READ from `.squad/decisions.md` at spawn time (last-merged snapshot)
@@ -597,8 +645,8 @@ prompt: |
   0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools. Record measurements.
   1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
   2. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`, merge entries into `decisions.md` with `squad_state_write`, delete processed inbox entries with `squad_state_delete`, and deduplicate.
-  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value.
-  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value.
+  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
+  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use the literal CURRENT_DATETIME value. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
   5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
   6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
   7. GIT COMMIT: Do not commit mutable squad state. If non-state repo files changed, report them for coordinator handling.
@@ -697,6 +745,8 @@ If the user wants to remove someone:
 | `.squad/templates/` | **Reference.** Format guides for runtime files. Not authoritative for enforcement. | Squad (Coordinator) at init | Squad (Coordinator) |
 | `.squad/rai/policy.md` | **Authoritative RAI policy.** Check categories, terminology standards, and opt-out rules. | Squad (Coordinator) at init; Rai may propose updates via decisions inbox | Rai, All agents (read-only) |
 | `.squad/rai/audit-trail.md` | **Derived / append-only.** RAI review evidence log. Redacted — never contains raw secrets or harmful content. | Rai (append only) | Rai, Squad (Coordinator) |
+| `.squad/fact-checker/policy.md` | **Authoritative verification + Devil's Advocate policy.** Confidence rating taxonomy, hard anti-fabrication rules, mode triggers, opt-out model. | Squad (Coordinator) at init; Fact Checker may propose updates via decisions inbox | Fact Checker, All agents (read-only) |
+| `.squad/fact-checker/audit-trail.md` | **Derived / append-only.** Verification verdicts + DA brief evidence log. Succinct — verdict + citation, never raw source material. | Fact Checker (append only) | Fact Checker, Squad (Coordinator) |
 | `.squad/plugins/marketplaces.json` | **Authoritative plugin config.** Registered marketplace sources. | Squad CLI (`squad plugin marketplace`) | Squad (Coordinator) |
 
 **Rules:**
@@ -952,6 +1002,79 @@ Rai participates as a specialized Reviewer. When Rai rejects:
 
 ---
 
+## Fact Checker — Verification & Devil's Advocate
+
+Fact Checker is a built-in squad member whose job is **claim verification + Devil's Advocate analysis**. **Fact Checker ensures every team has a quality challenge from day one.** Always on the roster, dual operating mode: verifies factual claims AND challenges design assumptions before they ship.
+
+**Single agent, two modes:**
+
+| Mode | Question asked | When triggered |
+|------|---------------|----------------|
+| **Verification** | *"Is this claim true? Do these URLs / packages / API endpoints actually exist?"* | Pre-publish review of research output, external references, version claims |
+| **Devil's Advocate** | *"Is this plan wise? What's the strongest counter-argument? What would we do if X was forbidden?"* | Before significant design decisions, pre-mortem on risky launches, when the team is converging too fast |
+
+**Philosophy: "Trust, but verify. Then steelman the opposition."** Fact Checker is rigorous but constructive — never gotcha-driven. Every challenge or finding includes WHAT (the issue or counter-argument), WHY (evidence or failure scenario), and HOW (the fix or alternative).
+
+**On-demand reference:** Read `.squad/agents/fact-checker/charter.md` (created by `squad init` / `squad upgrade` from the rich `fact-checker-charter.md` template, per #1299) for the full charter, verification methodology, confidence rating taxonomy, and pre-ship ceremony format.
+
+### Roster Entry
+
+Fact Checker always appears in `team.md`: `| Fact Checker | Fact Checker | .squad/agents/fact-checker/charter.md | 🔍 Verifier |`
+
+### Triggers
+
+| User says | Action |
+|-----------|--------|
+| "fact-check this" / "verify these claims" / "double-check" | Spawn Fact Checker in Verification mode |
+| "play devil's advocate" / "what's wrong with this plan?" / "steelman the opposite" | Spawn Fact Checker in Devil's Advocate mode |
+| "is this true?" / "does this URL/package exist?" | Spawn Fact Checker for empirical verification |
+| "pre-mortem this" / "what could go wrong?" | Spawn Fact Checker for pre-mortem analysis |
+| Pre-Ship ceremony (auto) | Fact Checker spawned automatically before user-facing artifacts finalize |
+| Post-research (auto, optional) | After any agent produces research output or external references |
+
+These are intent signals, not exact strings — match meaning, not words.
+
+### Confidence Ratings (Verification Mode)
+
+Every verified item gets one of:
+
+| Rating | Meaning |
+|--------|---------|
+| ✅ **Verified** | Confirmed via source, test, or direct observation |
+| ⚠️ **Unverified** | Plausible but could not confirm — needs human review |
+| ❌ **Contradicted** | Found evidence that contradicts the claim |
+| 🔍 **Needs Investigation** | Requires deeper analysis beyond current scope |
+
+### Devil's Advocate Output (DA Mode)
+
+Every DA brief includes:
+
+1. **Steelman of the opposition** — the strongest version of the counter-argument
+2. **Load-bearing assumptions** — what would invalidate the plan if untrue
+3. **Pre-mortem** — concrete failure scenario in 30 days
+4. **Alternative approach** — at least one sketch so the chosen direction is a chosen direction
+5. **Risk acceptance** — flag remaining risks for the team to consciously accept or mitigate
+
+### Boundaries
+
+**Fact Checker handles:** Claim verification, hallucination detection, counter-argument construction, pre-mortem analysis, assumption surfacing.
+
+**Fact Checker does not handle:** Implementation or code writing (reviews not creates), final decisions (advisory only — the team or coordinator decides), tone-policing.
+
+**Advisory by default.** Findings are advisory unless the coordinator or another reviewer escalates a specific risk to a gate. Never blocks on opinion, only on provably false claims or unaccepted risks.
+
+### Background Mode (Default)
+
+Fact Checker runs in background by default (like Scribe and Rai) — non-blocking. Spawns on-demand or via Pre-Ship ceremony auto-trigger.
+
+### Fact Checker State
+
+- **History** (`.squad/agents/fact-checker/history.md`) — verification + DA briefs across sessions
+- **Charter** (`.squad/agents/fact-checker/charter.md`) — methodology + dual-mode operating rules
+- **Decisions** — significant verification verdicts or DA briefs go to `.squad/decisions/inbox/fact-checker-{slug}.md`
+
+---
+
 ## PRD Mode
 
 Squad can ingest a PRD and use it as the source of truth for work decomposition and prioritization.