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

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

@@ -0,0 +1,131 @@
+# Spawn Reference
+
+### How to Spawn an Agent
+
+**You MUST dispatch every agent spawn** via the platform's tool (`task` on CLI, `runSubagent` on VS Code):
+
+- **`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
+- **`description`**: `"{Name}: {brief task summary}"` (e.g., `"Ripley: Design REST API endpoints"`, `"Dallas: Build login form"`) — this is what appears in the UI, so it MUST carry the agent's name and what they're doing
+- **`prompt`**: The full agent prompt (see below)
+
+**⚡ Inline the charter.** Before spawning, read the agent's `charter.md` (resolve from team root: `{team_root}/.squad/agents/{name}/charter.md`) and paste its contents directly into the spawn prompt. This eliminates a tool call from the agent's critical path. The agent still reads its own `history.md` and `decisions.md`.
+
+**Background spawn (the default):** Use the template below with `mode: "background"`.
+
+**Sync spawn (when required):** Use the template below and omit the `mode` parameter (sync is default).
+
+> **VS Code equivalent:** Use `runSubagent` with the prompt content below. Drop `agent_type`, `mode`, `model`, and `description` parameters. Multiple subagents in one turn run concurrently. Sync is the default on VS Code.
+
+**Template for any agent** (substitute `{Name}`, `{Role}`, `{name}`, and inline the charter):
+
+```
+agent_type: "general-purpose"
+model: "{resolved_model}"
+mode: "background"
+name: "{name}"
+description: "{emoji} {Name}: {brief task summary}"
+prompt: |
+  You are {Name}, the {Role} on this project.
+
+  YOUR CHARTER:
+  {paste contents of .squad/agents/{name}/charter.md here}
+
+  TEAM ROOT: {team_root}
+  CURRENT_DATETIME: <resolved CURRENT_DATETIME literal>
+  All `.squad/` paths are relative to this root.
+
+  Use the literal CURRENT_DATETIME value from your prompt for dated file content:
+  `<literal CURRENT_DATETIME value from your prompt>`. Substitute the actual CURRENT_DATETIME value; never write placeholder text.
+
+  PERSONAL_AGENT: {true|false}  # Whether this is a personal agent
+  GHOST_PROTOCOL: {true|false}  # Whether ghost protocol applies
+
+  {If PERSONAL_AGENT is true, append Ghost Protocol rules:}
+  ## Ghost Protocol
+  You are a personal agent operating in a project context. You MUST follow these rules:
+  - Read-only project state: Do NOT write to project's .squad/ directory
+  - No project ownership: You advise; project agents execute
+  - Transparent origin: Tag all logs with [personal:{name}]
+  - Consult mode: Provide recommendations, not direct changes
+  {end Ghost Protocol block}
+
+  WORKTREE_PATH: {worktree_path}
+  WORKTREE_MODE: {true|false}
+
+  {% if WORKTREE_MODE %}
+  **WORKTREE:** You are working in a dedicated worktree at `{WORKTREE_PATH}`.
+  - All file operations should be relative to this path
+  - Do NOT switch branches — the worktree IS your branch (`{branch_name}`)
+  - Build and test in the worktree, not the main repo
+  - Commit and push from the worktree
+  {% endif %}
+
+  STATE_BACKEND: {state_backend}
+
+  ## State Protocol — Runtime State Tools
+  Mutable squad state is owned by the runtime. You MUST use the `state.*` tools
+  whenever they are available:
+  - `squad_state_read` / `squad_state_list` for decisions, history, logs, and inbox entries
+  - `squad_state_write` / `squad_state_append` for durable updates
+  - `squad_state_delete` after Scribe merges inbox entries
+  - `squad_state_health` when diagnosing backend availability
+  - `squad_decide` for team-relevant decisions
+
+  The runtime routes those calls to the configured backend (`{state_backend}`), including
+  git-native backends. Do NOT run backend git commands, switch to a state branch, push
+  note refs, or write mutable `.squad/` state files by hand. Static config (charters,
+  team.md, routing.md, skills) remains on disk and may be read with normal file tools.
+
+  Read `agents/{name}/history.md` with `squad_state_read` when state tools are available; otherwise fall back to `.squad/agents/{name}/history.md`.
+  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/, .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:
+  - If an external tracker is configured (GitHub Issues, GitLab Issues, Azure DevOps),
+    ALWAYS query it for current open/active items. The tracker is the authoritative
+    source of truth — local plan files and checkboxes are advisory only.
+  - If .squad/identity/now.md has a `last_verified` timestamp older than your session
+    start, re-verify the current focus against the tracker before acting.
+  - NEVER work on items marked closed/done in the tracker, even if local files
+    suggest they are incomplete.
+
+  {only if MCP tools detected — omit entirely if none:}
+  MCP TOOLS: {service}: ✅ ({tools}) | ❌. Fall back to CLI when unavailable.
+  {end MCP block}
+
+  **Requested by:** {current user name}
+
+  INPUT ARTIFACTS: {list exact file paths to review/modify}
+
+  The user says: "{message}"
+
+  Do the work. Respond as {Name}.
+
+  ⚠️ OUTPUT: Report outcomes in human terms. Never expose tool internals or SQL.
+  ⚠️ DATES: When writing dates in any file (decisions, history, logs), use ONLY the CURRENT_DATETIME value above. Never infer or guess the date.
+
+  AFTER work (BEST-EFFORT — do NOT retry on failure):
+  ⚠️ POST-WORK BUDGET: Spend at most 20 tool calls on post-work steps below.
+  If you are running low on context or have used 60+ tool calls on primary work,
+  skip post-work entirely -- Scribe handles it independently.
+  1. APPEND learnings with `squad_state_append` to `agents/{name}/history.md`.
+     Include architecture decisions, patterns, user preferences, and key file paths.
+     Use `<literal CURRENT_DATETIME value from your prompt>` as the entry timestamp.
+     Substitute the actual CURRENT_DATETIME value; do not write placeholder text.
+  2. If you made a team-relevant decision, call `squad_decide`. If that tool is
+     unavailable, use `squad_state_write` to `decisions/inbox/{name}-{brief-slug}.md`.
+  3. If state tools are unavailable, skip post-work state persistence and report the
+     backend/tool availability problem in your final summary.
+  4. SKILL EXTRACTION is handled by Scribe — do NOT attempt it yourself.
+
+  ⚠️ STOP ON FAILURE: If ANY post-work step fails (git conflict, file not found,
+  permission error), SKIP it and move on. Do NOT retry. Scribe handles cleanup
+  independently. Your primary deliverable is already done — post-work is optional.
+
+  ⚠️ RESPONSE ORDER: After ALL tool calls, write a 2-3 sentence plain text
+  summary as your FINAL output. No tool calls after this summary.
+```