From 34e104b10197551c4a76cb0fa71139f93518cb01 Mon Sep 17 00:00:00 2001 From: Copilot Date: Sat, 13 Jun 2026 10:28:13 +0300 Subject: [PATCH 1/2] fix(sdk,cli): bundle missing skills on init + strip fabricated provenance from tiered-memory (#1289, #1264) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two regressions shipped in v0.10.0 caused several skills to silently never reach users: * #1289 — squad-commands + squad-version-check were in MANIFEST_SKILL_NAMES but missing from packages/squad-sdk/templates/skills/. The install loop silently skipped missing source dirs (storage.existsSync check, no log), so every squad init produced an install with these two absent and the `squad commands` trigger phrase was a dead no-op for every v0.10.0 user. * #1264 — tiered-memory, iterative-retrieval, reflect existed in templates but were never added to MANIFEST_SKILL_NAMES. tiered-memory/SKILL.md also claimed confidence: high with fabricated tamirdresher/tamresearch1 measurement data, and referenced a non-existent docs/tiered-memory-guide.md. * PR #1291 updated cross-squad/SKILL.md but never added it to the manifest. This change: * Adds 5 missing skill dirs to .squad/skills/ (canonical source): squad-commands, squad-version-check, tiered-memory, iterative-retrieval, reflect. sync-skill-templates.mjs (which runs in prebuild) propagates them to both packages/squad-cli/templates/skills/ and packages/squad-sdk/templates/skills/. * Grows MANIFEST_SKILL_NAMES from 10 → 14 entries: adds tiered-memory, iterative-retrieval, reflect, cross-squad. * Replaces the silent skip in sdk-init.ts with a thrown error that names the missing skill(s) and points at sync-skill-templates.mjs. This is what would have surfaced #1289 at build time instead of in user installs. * Rewrites tiered-memory/SKILL.md to be honest about status: - frontmatter: confidence: design + source: design proposal - prominent Status callout linking to #1264 for the runtime gap - removed fabricated measurement table - removed reference to non-existent docs/tiered-memory-guide.md - References section points only to real issues (#1264, #686, #600) * Adds a regression test in test/init.test.ts that asserts every manifest-curated skill ends up installed at .copilot/skills/{name}/SKILL.md. Verified: * npm run lint — passes (after build) * test/init.test.ts — 26/26 pass including new regression test * Targeted suites (test/init, test/cli/init, test/sdk) — 292/292 pass Out of scope (tracked separately): * tiered-memory runtime backing (.squad/memory/hot|cold|wiki/ scaffolding, Scribe promotion, tier-aware spawn template) — follow-up in #1264 * cross-squad-communication plugin port from tamirdresher/squad-skills — separate PR Closes #1289 Refs #1264 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .changeset/bundle-missing-skills-1289-1264.md | 39 +++ .squad/skills/iterative-retrieval/SKILL.md | 165 ++++++++++ .squad/skills/reflect/SKILL.md | 229 +++++++++++++ .squad/skills/squad-commands/SKILL.md | 303 ++++++++++++++++++ .squad/skills/squad-version-check/SKILL.md | 160 +++++++++ .squad/skills/tiered-memory/SKILL.md | 221 +++++++++++++ .../templates/skills/tiered-memory/SKILL.md | 75 ++--- packages/squad-sdk/src/config/init.ts | 26 ++ .../templates/skills/squad-commands/SKILL.md | 303 ++++++++++++++++++ .../skills/squad-version-check/SKILL.md | 160 +++++++++ .../templates/skills/tiered-memory/SKILL.md | 75 ++--- test/init.test.ts | 39 +++ 12 files changed, 1707 insertions(+), 88 deletions(-) create mode 100644 .changeset/bundle-missing-skills-1289-1264.md create mode 100644 .squad/skills/iterative-retrieval/SKILL.md create mode 100644 .squad/skills/reflect/SKILL.md create mode 100644 .squad/skills/squad-commands/SKILL.md create mode 100644 .squad/skills/squad-version-check/SKILL.md create mode 100644 .squad/skills/tiered-memory/SKILL.md create mode 100644 packages/squad-sdk/templates/skills/squad-commands/SKILL.md create mode 100644 packages/squad-sdk/templates/skills/squad-version-check/SKILL.md diff --git a/.changeset/bundle-missing-skills-1289-1264.md b/.changeset/bundle-missing-skills-1289-1264.md new file mode 100644 index 000000000..87d4ad480 --- /dev/null +++ b/.changeset/bundle-missing-skills-1289-1264.md @@ -0,0 +1,39 @@ +--- +"@bradygaster/squad-cli": patch +"@bradygaster/squad-sdk": patch +--- + +Fix #1289, #1264: Bundle missing skills on `squad init` and strip fabricated provenance from tiered-memory SKILL.md + +**Problem** + +Two regressions shipped in v0.10.0 caused several skills to silently never reach users: + +1. **#1289** — `squad-commands` and `squad-version-check` were in `MANIFEST_SKILL_NAMES` (sdk-init.ts) but missing from `packages/squad-sdk/templates/skills/`. The install loop silently skipped them with `if (storage.existsSync(srcSkill))`, so every `squad init` produced an install with these two skills absent. The trigger phrase `squad commands` was a dead no-op for every v0.10.0 user. + +2. **#1264** — `tiered-memory`, `iterative-retrieval`, and `reflect` skill files existed in both templates dirs but were never added to `MANIFEST_SKILL_NAMES`, so they never installed either. Additionally, `tiered-memory/SKILL.md` claimed `confidence: high` and `source: earned (production measurements in tamirdresher/tamresearch1, 34-74KB baseline payloads)` — the referenced repository does not exist and the measurement table at the bottom of the SKILL contained fabricated numbers. The SKILL also referenced `docs/tiered-memory-guide.md`, which does not exist. + +3. The previously-merged cross-squad fix (#1291) updated `cross-squad/SKILL.md` content but never added it to `MANIFEST_SKILL_NAMES`, so it also never installed. + +**Fix** + +- **Source of truth.** Added the 5 missing skill directories to `.squad/skills/` (`squad-commands`, `squad-version-check`, `tiered-memory`, `iterative-retrieval`, `reflect`). The pre-existing `sync-skill-templates.mjs` runs in `prebuild` and propagates them to both `packages/squad-cli/templates/skills/` and `packages/squad-sdk/templates/skills/`. + +- **`MANIFEST_SKILL_NAMES`** grew from 10 → 14 entries: added `tiered-memory`, `iterative-retrieval`, `reflect`, `cross-squad`. + +- **Anti-regression guard.** The install loop in `sdk-init.ts` now collects missing skill source dirs and `throw`s with a clear remediation message (`Run \`node scripts/sync-skill-templates.mjs\``) instead of silently skipping. This is what would have surfaced #1289 at build time instead of in user installs. + +- **Provenance honesty.** `tiered-memory/SKILL.md` rewritten to: + - Frontmatter: `confidence: design (runtime not yet implemented)` + `source: design proposal` + - Added prominent "Status (v0.10.0)" callout linking to #1264 for the runtime gap + - Removed the fabricated `tamirdresher/tamresearch1` measurement table + - Removed reference to non-existent `docs/tiered-memory-guide.md` + - References section now points to real issues (#1264, #686, #600) + +- **Test guard.** New regression test in `test/init.test.ts` (`should install every manifest-curated skill`) asserts every entry in the expected manifest list ends up at `.copilot/skills/{name}/SKILL.md` after `initSquad()`. + +**Out of scope (tracked separately)** + +The tiered-memory runtime (storage scaffolding under `.squad/memory/hot|cold|wiki/`, Scribe promotion logic, spawn-template tier-aware reads) remains tracked in #1264. This change lands the install-time fixes; runtime work follows in a separate PR. + +The comprehensive `cross-squad-communication` plugin from `tamirdresher/squad-skills` is also separate; this change just adds the existing upstream `cross-squad` skill to the manifest so users get the registry-aware version that landed with #1291. diff --git a/.squad/skills/iterative-retrieval/SKILL.md b/.squad/skills/iterative-retrieval/SKILL.md new file mode 100644 index 000000000..4d8eea993 --- /dev/null +++ b/.squad/skills/iterative-retrieval/SKILL.md @@ -0,0 +1,165 @@ +--- +name: "iterative-retrieval" +description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work." +domain: "agent-coordination" +confidence: "high" +license: MIT +--- + +# Iterative Retrieval Skill + +Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these +handoffs become vague, cycles multiply, and outputs land without being checked. The +**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and +requires the coordinator to validate agent output before closing an issue. + +--- + +## Spawn Prompt Template + +Every agent spawn must include the following four sections. Copy and fill in the template: + +``` +## Task +{What you need done — concrete and bounded} + +## WHY this matters +{The motivation and context. What system or user goal does this serve? What breaks if skipped?} + +## Success criteria +{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.} +Example: +- [ ] File X exists and contains Y +- [ ] No regressions in existing tests +- [ ] PR is open targeting main with description matching the issue + +## Escalation path +{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.} +Example: +- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision +- If blocked by a dependency → label status:blocked, explain in a comment +- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator +``` + +--- + +## 3-Cycle Protocol + +| Cycle | Description | Exit condition | +|-------|-------------|----------------| +| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. | +| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. | +| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. | + +### Rules + +1. **After each cycle**, the coordinator evaluates the output against the success criteria + before accepting it or spawning the next cycle. +2. **Objective context forward**: each subsequent spawn includes a summary of what was tried + and what is still missing — not just a repeat of the original task. +3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the + issue `status:needs-decision`, and notify the user. + +--- + +## Coordinator Validation Checklist + +Before accepting agent output and closing an issue, the coordinator must check: + +- [ ] All success criteria from the spawn prompt are met +- [ ] PR exists and description matches the issue (if code work) +- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes) +- [ ] Agent did not silently skip parts of the task +- [ ] If the agent reported uncertainty — was it resolved or escalated? + +If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas. + +--- + +## When to Escalate vs Retry + +**Retry (cycle N+1)** when: +- Output is structurally correct but missing specific items +- Agent misunderstood scope (provide more context and re-run) +- Partial success — clearly identified remaining delta + +**Escalate** when: +- Requirements are fundamentally unclear (decision needed) +- 3 cycles complete without convergence +- Agent returned conflicting results across cycles +- Task requires elevated permissions or external action +- The work depends on another issue that isn't done yet + +--- + +## Issue Dedup Check (Mandatory) + +Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid +duplicates. + +```bash +# Check for existing open issues before creating a new one +gh issue list --search "" --state open +``` + +- If an open issue already covers the same problem → **comment on it** instead of creating a new one. +- If no duplicate → proceed to create the issue. +- Use 2–3 representative keywords from the planned issue title as the search query. + +--- + +## Mandatory Output Requirement (Research-Then-Execute) + +Every research or analysis task completed under this protocol **MUST** end with at least one +concrete action before the cycle is closed. Acceptable follow-up actions: + +- GitHub issue created documenting the findings and next steps +- PR opened implementing a recommendation +- Decision recorded in `.squad/decisions/inbox/` +- Documented recommendation with a named assignee and due date + +**Pure analysis reports without actionable follow-up will be rejected during triage.** +If no action is warranted, the agent must explicitly state why and get coordinator sign-off. + +--- + +## Anti-Patterns + +- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context. +- **Accepting output without validating** — one failed check avoids merging broken work. +- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent. +- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes. +- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong. +- **Creating issues without dedup check** — always search before creating. +- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work. + +--- + +## Examples + +### Good spawn prompt +``` +## Task +Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining +the 3-cycle rule, WHY format, and validation checklist. + +## WHY this matters +The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded +cycles and outputs go unvalidated — leading to stale issues and silent failures. + +## Success criteria +- [ ] Section "Iterative Retrieval Protocol" exists in charter.md +- [ ] Section documents max-3-cycles rule +- [ ] Section documents WHY format requirement +- [ ] Section contains validation checklist (at least 4 items) +- [ ] No other sections of charter.md are modified + +## Escalation path +If the charter.md format is unclear, check another agent charter as a reference. +If uncertain about content, stop and surface to coordinator. +``` + +### Bad spawn prompt (don't do this) +``` +Update the coordinator charter with the iterative retrieval stuff. +``` diff --git a/.squad/skills/reflect/SKILL.md b/.squad/skills/reflect/SKILL.md new file mode 100644 index 000000000..6a85b5190 --- /dev/null +++ b/.squad/skills/reflect/SKILL.md @@ -0,0 +1,229 @@ +--- +name: reflect +description: Learning capture system that extracts HIGH/MED/LOW confidence patterns from conversations to prevent repeating mistakes. Use after user corrections ("no", "wrong"), praise ("perfect", "exactly"), or when discovering edge cases. Complements .squad/agents/{agent}/history.md and .squad/decisions.md. +license: MIT +version: 1.0.0-squad +domain: team-memory, learning +confidence: high +--- + +# Reflect Skill + +**Critical learning capture system** for Squad. Prevents repeating mistakes and preserves successful patterns across sessions. + +Analyze conversations and propose improvements to squad knowledge based on what worked, what didn't, and edge cases discovered. **Every correction is a learning opportunity.** + +--- + +## Integration with Squad Architecture + +**Reflect complements existing Squad knowledge systems:** + +1. **`.squad/agents/{agent}/history.md`** — Permanent learnings from completed work (append-only; each agent updates their own file; Scribe propagates cross-agent updates) +2. **`.squad/decisions.md`** — Team-wide decisions that all agents respect +3. **`reflect` skill** — Captures in-flight learnings from conversations that may graduate to history.md or decisions.md + +**Workflow:** +- Use `reflect` during work to capture learnings +- At session end, review captured learnings +- Promote HIGH confidence patterns → lead agent for decision.md review +- Promote agent-specific patterns → `{agent}/history.md` updates + +--- + +## Triggers + +### 🔴 HIGH Priority (Invoke Immediately) + +| Trigger | Example | Why Critical | +|---------|---------|--------------| +| User correction | "no", "wrong", "not like that", "never do" | Captures mistakes to prevent repetition | +| Architectural insight | "you removed that without understanding why" | Documents design decisions (Chesterton's Fence) | +| Immediate fixes | "debug", "root cause", "fix all" | Learns from errors in real-time | + +### 🟡 MEDIUM Priority (Invoke After Multiple) + +| Trigger | Example | Why Important | +|---------|---------|---------------| +| User praise | "perfect", "exactly", "great" | Reinforces successful patterns | +| Tool preferences | "use X instead of Y", "prefer" | Builds workflow preferences | +| Edge cases | "what if X happens?", "don't forget", "ensure" | Captures scenarios to handle | + +### 🟢 LOW Priority (Invoke at Session End) + +| Trigger | Example | Why Useful | +|---------|---------|------------| +| Repeated patterns | Frequent use of specific commands/tools | Identifies workflow preferences | +| Session end | After complex work | Consolidates all session learnings | + +--- + +## Process + +### Phase 1: Identify Learning Target + +Determine what knowledge system should be updated: + +1. **Agent-specific learning** → `.squad/agents/{agent}/history.md` +2. **Team-wide decision** → `.squad/decisions/inbox/{agent}-{topic}.md` +3. **Skill-specific improvement** → Document in session, recommend to skill owner + +### Phase 2: Analyze Conversation + +Scan for learning signals with confidence levels: + +#### HIGH Confidence: Corrections + +User actively steered or corrected output. + +**Detection patterns:** +- Explicit rejection: "no", "not like that", "that's wrong" +- Strong directives: "never do", "always do", "don't ever" +- User provided alternative implementation + +**Example:** +```text +User: "No, use the azure-devops MCP tool instead of raw API calls" +→ [HIGH] + Add constraint: "Prefer azure-devops MCP tools over REST API" +``` + +#### MEDIUM Confidence: Success Patterns + +Output was accepted or praised. + +**Detection patterns:** +- Explicit praise: "perfect", "great", "yes", "exactly" +- User built on output without modification +- Output was committed without changes + +**Example:** +```text +User: "Perfect, that's exactly what I needed" +→ [MED] + Add preference: "Include usage examples in documentation" +``` + +#### MEDIUM Confidence: Edge Cases + +Scenarios not anticipated. + +**Detection patterns:** +- Questions not answered +- Workarounds user had to apply +- Error handling gaps discovered + +#### LOW Confidence: Preferences + +Accumulated patterns over time. + +--- + +### Phase 3: Propose Learnings + +Present findings: + +```text +┌─────────────────────────────────────────────────────────────┐ +│ REFLECTION: {target (agent/decision/skill)} │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ [HIGH] + Add constraint: "{specific constraint}" │ +│ Source: "{quoted user correction}" │ +│ Target: .squad/decisions/inbox/{agent}-{topic}.md │ +│ │ +│ [MED] + Add preference: "{specific preference}" │ +│ Source: "{evidence from conversation}" │ +│ Target: .squad/agents/{agent}/history.md │ +│ │ +│ [LOW] ~ Note for review: "{observation}" │ +│ Source: "{pattern observed}" │ +│ Target: Session notes only │ +│ │ +├─────────────────────────────────────────────────────────────┤ +│ Apply changes? [Y/n/edit] │ +└─────────────────────────────────────────────────────────────┘ +``` + +**Confidence Threshold:** + +| Threshold | Action | +|-----------|--------| +| ≥1 HIGH signal | Always propose (user explicitly corrected) | +| ≥2 MED signals | Propose (sufficient pattern) | +| ≥3 LOW signals | Propose (accumulated evidence) | +| 1-2 LOW only | Skip (insufficient evidence) | + +### Phase 4: Persist Learnings + +**ALWAYS show changes before applying.** + +After user approval: + +1. **For Agent History:** + - Append to `.squad/agents/{agent}/history.md` under `## Learnings` section + - Format: Date, assignment context, key learning + +2. **For Team Decisions:** + - Create `.squad/decisions/inbox/{agent}-{topic}.md` + - Lead agent reviews and merges to `decisions.md` if appropriate + +3. **For Skills:** + - Document recommendation in session notes + - Squad lead reviews and routes to skill owner + +--- + +## Usage Examples + +### Example 1: User Correction + +**Conversation:** +``` +Agent: "I'll use grep to search the repository" +User: "No, use the code search tools first, grep is too slow" +``` + +**Reflection Output:** +``` +[HIGH] + Add constraint: "Use code intelligence tools before grep" + Source: "No, use the code search tools first, grep is too slow" + Target: .squad/agents/{agent}/history.md +``` + +### Example 2: Success Pattern + +**Conversation:** +``` +Agent: [Creates PR with detailed description and test plan] +User: "Perfect! This is exactly the format I want for all PRs" +``` + +**Reflection Output:** +``` +[MED] + Add preference: "Include test plan in PR descriptions" + Source: User praised detailed PR format + Target: .squad/decisions/inbox/pr-format.md (for team adoption) +``` + +--- + +## When to Use + +✅ **Use reflect when:** +- User says "no", "wrong", "not like that" (HIGH priority) +- User says "perfect", "exactly", "great" (MED priority) +- You discover edge cases or gaps +- Complex work session with multiple learnings +- At end of sprint/milestone to consolidate patterns + +❌ **Don't use reflect when:** +- Simple one-off questions with no pattern +- User is just exploring ideas (no concrete decisions) +- Learning is already captured in history.md/decisions.md + +--- + +## See Also + +- `.squad/decisions.md` — Team-wide decisions +- `.squad/agents/*/history.md` — Agent-specific learnings +- `.squad/routing.md` — Work assignment patterns diff --git a/.squad/skills/squad-commands/SKILL.md b/.squad/skills/squad-commands/SKILL.md new file mode 100644 index 000000000..046dde513 --- /dev/null +++ b/.squad/skills/squad-commands/SKILL.md @@ -0,0 +1,303 @@ +--- +name: squad-commands +description: > + Categorized catalog of common Squad operations. Coordinator reads this + file and presents it as an interactive menu when the user asks for + available commands or help. +domain: squad-operations +confidence: high +source: first-party +triggers: ["squad commands", "what can squad do", "show me squad options", "slash 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 diff --git a/.squad/skills/squad-version-check/SKILL.md b/.squad/skills/squad-version-check/SKILL.md new file mode 100644 index 000000000..291a4d337 --- /dev/null +++ b/.squad/skills/squad-version-check/SKILL.md @@ -0,0 +1,160 @@ +# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics + +**Confidence:** medium +**Discovered by:** Data +**Date:** 2026-05-26 +**Validated in:** Issue #1173 recon (bradygaster/squad) + +--- + +## What This Skill Covers + +Reusable knowledge about how `@bradygaster/squad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt. + +--- + +## Package & Registry Facts + +- **Package name:** `@bradygaster/squad-cli` +- **Registry:** npm (public) +- **CLI binary:** `squad` (registered via `package.json#bin.squad`) +- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase) + +--- + +## Version Stamping Mechanism + +**Source file:** `dist/cli/core/version.js` + +Three functions: + +### `getPackageVersion()` +Walks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist/cli/core/version.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found. + +### `stampVersion(filePath, version)` +Mutates `squad.agent.md` in three places: +1. HTML comment: `` (must be on the line immediately after frontmatter `---`) +2. Identity line: `- **Version:** {version}` +3. Greeting instruction: backtick-quoted `` `Squad v{version}` `` + +**Called by:** both `init` and `upgrade` — after copying the template to the destination. + +### `readInstalledVersion(filePath)` +Reads the stamped version back from `squad.agent.md`: +1. First tries HTML comment format: `//` +2. Falls back to old frontmatter format: `/^version:\s*"([^"]+)"/m` +3. Returns `'0.0.0'` on any error + +--- + +## `squad upgrade` Behavior + +**Source file:** `dist/cli/core/upgrade.js` + +### What gets overwritten: +- `squad.agent.md` — full overwrite from template, then `stampVersion()` +- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled) +- GitHub Actions workflows — from `templates/workflows/`; non-npm projects get type-aware stubs +- Runs `runMigrations()` after file copy + +### What is PRESERVED: +- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned) +- `agents/*/history.md` (individual agent memory) +- `.squad/config.json` — **never touched**; `stateBackend` survives intact +- User-added files not in TEMPLATE_MANIFEST + +### Self-upgrade path (`selfUpgradeCli()`): +Detects npm/pnpm/yarn via `npm_execpath` and `npm_config_user_agent`. Runs: +- npm: `npm install -g @bradygaster/squad-cli@latest` +- pnpm: `pnpm add -g @bradygaster/squad-cli@latest` +- yarn: `yarn global add @bradygaster/squad-cli@latest` +Use `@insider` tag for insider builds. + +### `compareSemver(a, b)` utility (in upgrade.js): +Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` < `0.9.5`). Can be ported directly if needed in prompt logic. + +--- + +## `.squad/config.json` — What It Holds + +```json +{ + "version": 1, + "stateBackend": "worktree" +} +``` + +Other optional fields added by the coordinator at runtime: +- `defaultModel` — global model override for all agent spawns +- `agentModelOverrides.{agentName}` — per-agent model override + +The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences). + +--- + +## Version-Check Probe (npm Registry) + +Use this one-liner from inside a coordinator prompt to fetch dist-tags: + +``` +npm view @bradygaster/squad-cli dist-tags --json +``` + +- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting. +- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`). +- On any error (network failure, registry unreachable, parse error): show normal greeting. + +--- + +## Upstream OS-Specific Cache + +The CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL. + +**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 + +**OS-specific cache path:** +- Windows: `%APPDATA%\squad-cli\update-check.json` +- Linux: `~/.config/squad-cli/update-check.json` +- macOS: `~/Library/Application Support/squad-cli/update-check.json` + +--- + +## Repo-Local Cache Convention: `.squad/.cache/version-check.json` + +Used by coordinator for `insider`/`preview` channels (the upstream cache only stores `latest`). + +**Schema:** +```json +{ + "checkedAt": "2026-05-26T14:13:28.492Z", + "currentVersion": "0.9.6-insider.2", + "channel": "insider", + "channelVersion": "0.9.7-insider.1" +} +``` + +**TTL:** 24 hours from `checkedAt`. +**Gitignore:** `.squad/.cache/` is listed in `.gitignore` — cache files are never committed. + +--- + +## Key File Paths (installed CLI) + +| Purpose | Path | +|---|---| +| Version utilities | `dist/cli/core/version.js` | +| Upgrade logic | `dist/cli/core/upgrade.js` | +| Init logic | `dist/cli/core/init.js` | +| Template manifest | `dist/cli/core/templates.js` | +| Copilot install helper | `dist/cli/copilot-install.js` | +| squad.agent.md template | `templates/squad.agent.md.template` | +| Session init reference | `templates/session-init-reference.md` | +| All templates | `templates/` | diff --git a/.squad/skills/tiered-memory/SKILL.md b/.squad/skills/tiered-memory/SKILL.md new file mode 100644 index 000000000..5921eb80a --- /dev/null +++ b/.squad/skills/tiered-memory/SKILL.md @@ -0,0 +1,221 @@ +--- +name: tiered-memory +description: Three-tier agent memory model (hot/cold/wiki) for context reduction per spawn +domain: memory-management, performance +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 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:** 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:** 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:** 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. + +### 📚 Wiki Tier — Durable Structured Knowledge +- **Size target:** variable, structured reference docs +- **Load policy:** Async write, selective read. Load only when task requires domain knowledge. +- **Contents:** Architecture decisions (ADRs), agent charters, routing rules, stable conventions, external API contracts, known platform constraints. +- **Lifetime:** Permanent until explicitly deprecated. +- **Purpose:** Authoritative reference. Not history — structured facts. +- **How to include:** Pass `--include-wiki` or reference specific wiki doc paths in spawn template. + +--- + +## When to Load Each Tier + +| Situation | Hot | Cold | Wiki | +|-----------|-----|------|------| +| New task, no prior context needed | ✅ | ❌ | ❌ | +| Resuming interrupted work | ✅ | ✅ | ❌ | +| Debugging a recurring issue | ✅ | ✅ | ❌ | +| Implementing against a spec/ADR | ✅ | ❌ | ✅ | +| Onboarding to unfamiliar subsystem | ✅ | ❌ | ✅ | +| Post-incident review | ✅ | ✅ | ✅ | + +--- + +## Spawn Template Pattern + +The default spawn prompt should include **Hot tier only**: + +``` +## Memory Context + +### Hot (current session) +{hot_context} +``` + +Add `--include-cold` when the task needs history: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Cold (summarized history — load on demand) +See: .squad/memory/cold/{agent-name}.md +``` + +Add `--include-wiki` when the task needs domain knowledge: +``` +## Memory Context + +### Hot (current session) +{hot_context} + +### Wiki (durable reference) +See: .squad/memory/wiki/{topic}.md +``` + +--- + +## Integration with Scribe Agent (design — not yet implemented) + +Scribe is the proposed memory coordinator for this system. Once the runtime lands, Scribe will: + +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 + +Until then, see the Scribe charter for current behavior: `.squad/agents/scribe/charter.md` + +--- + +## 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 rolling TTL + +--- + +## References + +- 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 + +--- + +## Spawn Template + +# Spawn Template: Agent with Tiered Memory + +Use this template when spawning any Squad agent. By default it loads **Hot tier only**. Add optional sections as needed. + +--- + +## Task + +{task_description} + +## WHY + +{why_this_matters} + +## Success Criteria + +- [ ] {criterion_1} +- [ ] {criterion_2} + +--- + +## Memory Context + +### 🔥 Hot (always included) + +> Paste current session context here (~2–4KB target): + +``` +Current task: {task_description} +Active decisions: {decisions_this_session} +Last actions: {last_3_to_5_actions} +Blockers: {current_blockers_or_none} +Talking to: {current_interlocutor} +``` + +--- + +### ❄️ Cold (include when task needs history — add `--include-cold`) + +> Load on demand. Do not inline unless specifically needed. + +Summarized cross-session history is at: +`.squad/memory/cold/{agent-name}.md` + +Include when: +- Resuming interrupted work +- Debugging a recurring issue +- "What have we tried before?" + +**To load cold memory, add this section and fetch the file before spawning:** + +``` +## Cold Memory Summary +{contents_of_.squad/memory/cold/{agent-name}.md} +``` + +--- + +### 📚 Wiki (include when task needs domain knowledge — add `--include-wiki`) + +> Load on demand. Reference specific wiki docs by path. + +Wiki entries are at: `.squad/memory/wiki/` + +Include when: +- Implementing against an ADR or spec +- Onboarding to unfamiliar subsystem +- Need stable conventions or API contracts + +**To load wiki, add this section and reference the specific doc:** + +``` +## Wiki Reference +{contents_of_.squad/memory/wiki/{topic}.md} +``` + +--- + +## Escalation + +If blocked or uncertain: +- Architecture questions → @picard +- Security concerns → @worf +- Infrastructure/deployment → @belanna +- Memory/history questions → @scribe + +--- + +## Notes + +- 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 +- 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 + diff --git a/packages/squad-cli/templates/skills/tiered-memory/SKILL.md b/packages/squad-cli/templates/skills/tiered-memory/SKILL.md index bb82e662c..5921eb80a 100644 --- a/packages/squad-cli/templates/skills/tiered-memory/SKILL.md +++ b/packages/squad-cli/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 + diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts index 211801e9f..d0ccf2179 100644 --- a/packages/squad-sdk/src/config/init.ts +++ b/packages/squad-sdk/src/config/init.ts @@ -27,6 +27,11 @@ import { ensureMemoryGovernanceDefaults } from '../memory/index.js'; /** * The curated built-in skills shipped on init. * Only these skills are installed — not the full templates/skills/ directory. + * + * Drift policy: every entry MUST have a corresponding directory under + * packages/squad-sdk/templates/skills/. The install loop (below) throws on + * missing source dirs instead of silently skipping — see bradygaster/squad#1289 + * for the prior silent-skip bug that shipped two missing skills in v0.10.0. */ const MANIFEST_SKILL_NAMES = [ 'squad-conventions', @@ -41,6 +46,10 @@ const MANIFEST_SKILL_NAMES = [ 'squad-version-check', 'squad-help', 'cross-squad-communication', + 'tiered-memory', + 'iterative-retrieval', + 'reflect', + 'cross-squad', ] as const; // ============================================================================ @@ -1290,13 +1299,30 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre const existingSkills = storage.existsSync(skillsDir) ? storage.listSync(skillsDir) : []; if (existingSkills.length === 0) { storage.mkdirSync(skillsDir, { recursive: true }); + const missing: string[] = []; for (const skillName of MANIFEST_SKILL_NAMES) { const srcSkill = join(skillsSrc, skillName); if (storage.existsSync(srcSkill)) { copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage); + } else { + missing.push(skillName); } } + if (missing.length > 0) { + // Manifest/templates drift — fail loudly so v0.10.0-style silent-skip + // regressions (#1289) cannot reach users. The sync script + // scripts/sync-skill-templates.mjs is responsible for keeping + // packages/squad-sdk/templates/skills/ in step with .squad/skills/. + throw new Error( + `Skill template drift: MANIFEST_SKILL_NAMES references ${missing.length} skill(s) ` + + `missing from the SDK templates dir (${skillsSrc}): ${missing.join(', ')}. ` + + `Run \`node scripts/sync-skill-templates.mjs\` from the squad repo root, ` + + `or add the missing skill(s) under .squad/skills/.` + ); + } createdFiles.push('.github/skills'); + createdFiles.push('.copilot/skills'); +>>>>>>> 7d945fea (fix(sdk,cli): bundle missing skills on init + strip fabricated provenance from tiered-memory (#1289, #1264)) } } diff --git a/packages/squad-sdk/templates/skills/squad-commands/SKILL.md b/packages/squad-sdk/templates/skills/squad-commands/SKILL.md new file mode 100644 index 000000000..046dde513 --- /dev/null +++ b/packages/squad-sdk/templates/skills/squad-commands/SKILL.md @@ -0,0 +1,303 @@ +--- +name: squad-commands +description: > + Categorized catalog of common Squad operations. Coordinator reads this + file and presents it as an interactive menu when the user asks for + available commands or help. +domain: squad-operations +confidence: high +source: first-party +triggers: ["squad commands", "what can squad do", "show me squad options", "slash 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 diff --git a/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md b/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md new file mode 100644 index 000000000..291a4d337 --- /dev/null +++ b/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md @@ -0,0 +1,160 @@ +# SKILL: Squad CLI Internals — Version Stamping & Upgrade Mechanics + +**Confidence:** medium +**Discovered by:** Data +**Date:** 2026-05-26 +**Validated in:** Issue #1173 recon (bradygaster/squad) + +--- + +## What This Skill Covers + +Reusable knowledge about how `@bradygaster/squad-cli` stamps its version into `squad.agent.md`, how `squad upgrade` works, what it preserves vs. overwrites, and how to probe the npm registry for the latest version from a coordinator prompt. + +--- + +## Package & Registry Facts + +- **Package name:** `@bradygaster/squad-cli` +- **Registry:** npm (public) +- **CLI binary:** `squad` (registered via `package.json#bin.squad`) +- **Node version requirement:** Node ≥22.5.0 (ESM-only codebase) + +--- + +## Version Stamping Mechanism + +**Source file:** `dist/cli/core/version.js` + +Three functions: + +### `getPackageVersion()` +Walks up from the compiled JS file to find `package.json`. Returns `pkg.version`. Works from both `dist/cli/core/version.js` and a bundled root `cli.js`. Returns `'0.0.0'` as fallback if not found. + +### `stampVersion(filePath, version)` +Mutates `squad.agent.md` in three places: +1. HTML comment: `` (must be on the line immediately after frontmatter `---`) +2. Identity line: `- **Version:** {version}` +3. Greeting instruction: backtick-quoted `` `Squad v{version}` `` + +**Called by:** both `init` and `upgrade` — after copying the template to the destination. + +### `readInstalledVersion(filePath)` +Reads the stamped version back from `squad.agent.md`: +1. First tries HTML comment format: `//` +2. Falls back to old frontmatter format: `/^version:\s*"([^"]+)"/m` +3. Returns `'0.0.0'` on any error + +--- + +## `squad upgrade` Behavior + +**Source file:** `dist/cli/core/upgrade.js` + +### What gets overwritten: +- `squad.agent.md` — full overwrite from template, then `stampVersion()` +- Files with `overwriteOnUpgrade: true` in `TEMPLATE_MANIFEST`: casting JSON files, template .md files, `copilot-instructions.md` (if @copilot enabled) +- GitHub Actions workflows — from `templates/workflows/`; non-npm projects get type-aware stubs +- Runs `runMigrations()` after file copy + +### What is PRESERVED: +- `team.md`, `routing.md`, `decisions.md`, `ceremonies.md` (user-owned) +- `agents/*/history.md` (individual agent memory) +- `.squad/config.json` — **never touched**; `stateBackend` survives intact +- User-added files not in TEMPLATE_MANIFEST + +### Self-upgrade path (`selfUpgradeCli()`): +Detects npm/pnpm/yarn via `npm_execpath` and `npm_config_user_agent`. Runs: +- npm: `npm install -g @bradygaster/squad-cli@latest` +- pnpm: `pnpm add -g @bradygaster/squad-cli@latest` +- yarn: `yarn global add @bradygaster/squad-cli@latest` +Use `@insider` tag for insider builds. + +### `compareSemver(a, b)` utility (in upgrade.js): +Returns -1/0/1. Handles pre-release: strips pre-release for base comparison, then treats pre-release as less than release (e.g., `0.9.5-insider.1` < `0.9.5`). Can be ported directly if needed in prompt logic. + +--- + +## `.squad/config.json` — What It Holds + +```json +{ + "version": 1, + "stateBackend": "worktree" +} +``` + +Other optional fields added by the coordinator at runtime: +- `defaultModel` — global model override for all agent spawns +- `agentModelOverrides.{agentName}` — per-agent model override + +The file is read-only from the upgrade path's perspective. Only the coordinator writes to it (for model preferences). + +--- + +## Version-Check Probe (npm Registry) + +Use this one-liner from inside a coordinator prompt to fetch dist-tags: + +``` +npm view @bradygaster/squad-cli dist-tags --json +``` + +- Timeout: **5 seconds.** If no response within 5 seconds, abandon and show normal greeting. +- On success: extract `dist-tags[channel]` (e.g., `dist-tags["insider"]`). +- On any error (network failure, registry unreachable, parse error): show normal greeting. + +--- + +## Upstream OS-Specific Cache + +The CLI (`self-update.ts`) writes `latest` version info to an OS-specific path with a 24h TTL. + +**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 + +**OS-specific cache path:** +- Windows: `%APPDATA%\squad-cli\update-check.json` +- Linux: `~/.config/squad-cli/update-check.json` +- macOS: `~/Library/Application Support/squad-cli/update-check.json` + +--- + +## Repo-Local Cache Convention: `.squad/.cache/version-check.json` + +Used by coordinator for `insider`/`preview` channels (the upstream cache only stores `latest`). + +**Schema:** +```json +{ + "checkedAt": "2026-05-26T14:13:28.492Z", + "currentVersion": "0.9.6-insider.2", + "channel": "insider", + "channelVersion": "0.9.7-insider.1" +} +``` + +**TTL:** 24 hours from `checkedAt`. +**Gitignore:** `.squad/.cache/` is listed in `.gitignore` — cache files are never committed. + +--- + +## Key File Paths (installed CLI) + +| Purpose | Path | +|---|---| +| Version utilities | `dist/cli/core/version.js` | +| Upgrade logic | `dist/cli/core/upgrade.js` | +| Init logic | `dist/cli/core/init.js` | +| Template manifest | `dist/cli/core/templates.js` | +| Copilot install helper | `dist/cli/copilot-install.js` | +| squad.agent.md template | `templates/squad.agent.md.template` | +| Session init reference | `templates/session-init-reference.md` | +| All templates | `templates/` | diff --git a/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md b/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md index bb82e662c..5921eb80a 100644 --- a/packages/squad-sdk/templates/skills/tiered-memory/SKILL.md +++ b/packages/squad-sdk/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 + diff --git a/test/init.test.ts b/test/init.test.ts index 335aaf929..7441fe1f9 100644 --- a/test/init.test.ts +++ b/test/init.test.ts @@ -261,6 +261,45 @@ describe('Squad Initialization', () => { expect(charter).toMatch(/\.squad\/rai\/audit-trail\.md/); }); + it('should install every manifest-curated skill (regression: bradygaster/squad#1289, #1264)', async () => { + // Sanity check: every skill listed in MANIFEST_SKILL_NAMES must end up + // installed under .copilot/skills/. The prior v0.10.0 install path + // silently skipped skills whose source dir was missing from the SDK + // templates dir; this test exists to ensure that regression cannot + // happen again (the loop now throws on drift, but a missing + // SKILL.md after install would still indicate a deeper issue). + const expectedSkills = [ + 'squad-conventions', + 'error-recovery', + 'secret-handling', + 'git-workflow', + 'session-recovery', + 'reviewer-protocol', + 'test-discipline', + 'agent-collaboration', + 'squad-commands', + 'squad-version-check', + 'tiered-memory', + 'iterative-retrieval', + 'reflect', + 'cross-squad', + ]; + + const agents: InitAgentSpec[] = [{ name: 'lead', role: 'lead' }]; + const options: InitOptions = { + teamRoot: TEST_ROOT, + projectName: 'Test Project', + agents + }; + + await initSquad(options); + + for (const skill of expectedSkills) { + const skillPath = join(TEST_ROOT, '.copilot', 'skills', skill, 'SKILL.md'); + expect(existsSync(skillPath), `expected ${skill}/SKILL.md to be installed`).toBe(true); + } + }); + it('should create .gitattributes for merge drivers', async () => { const agents: InitAgentSpec[] = [{ name: 'lead', role: 'lead' }]; const options: InitOptions = { From 852dc6c316596644a34e14bc664fa953b78bfaaa Mon Sep 17 00:00:00 2001 From: Tamir Dresher Date: Sat, 13 Jun 2026 15:52:47 +0300 Subject: [PATCH 2/2] fix: precheck drift, end-user remediation, TEMPLATE_MANIFEST sync, frontmatter, single-source test MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five reviewer follow-ups on #1292 (closes #1289, refs #1264): 1. (1292-a) Drift guard ran the copy loop FIRST and threw at the end if any source dir was missing — leaving a partial skills install on disk. Refactored to a pre-check pass that walks MANIFEST_SKILL_NAMES once for existence, throws if any source is missing, then runs the copy loop only if everything is present. Result: no partial state when a packaging bug ships. 2. (1292-b) Remediation text told the user to 'run scripts/sync-skill-templates.mjs from the squad repo root', which doesn't exist in an installed @bradygaster/squad-sdk tarball. Rewrote the message to target end users (try squad upgrade, report a bug if it persists) and kept the contributor hint as a parenthetical aside. 3. (1292-c) MANIFEST_SKILL_NAMES grew to 14 entries (squad-commands, squad-version-check, tiered-memory, iterative-retrieval, reflect, cross-squad added across PRs), but TEMPLATE_MANIFEST in packages/squad-cli/src/cli/core/templates.ts had only 10 — so squad upgrade would skip the new ones. Added matching entries for tiered-memory/iterative-retrieval/reflect/cross-squad (the 4 not already covered by other PRs). 4. (1292-d) packages/squad-cli/templates/skills/squad-version-check/ SKILL.md (and the 2 mirrors) shipped without ANY YAML frontmatter — just a freeform '**Confidence:**' Markdown line. isSkillContent() in consult.ts requires '---\\nname:...\\nconfidence:' front-matter to classify the file as a skill, so squad-version- check was misclassified in share / promote / merge flows. Added proper frontmatter (name, description, allowedTools, confidence, domain, source) to all 3 mirrors. 5. (1292-e) The regression test duplicated the MANIFEST_SKILL_NAMES list literal — adding a new skill would have required two edits to stay green. Exported MANIFEST_SKILL_NAMES from sdk/config and updated the test to import + iterate the same array the install loop reads. Future skill additions only need one edit. Verified: 26/26 init tests pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .squad/skills/squad-version-check/SKILL.md | 9 +++++ packages/squad-cli/src/cli/core/templates.ts | 24 +++++++++++++ .../skills/squad-version-check/SKILL.md | 9 +++++ packages/squad-sdk/src/config/init.ts | 36 +++++++++++-------- .../skills/squad-version-check/SKILL.md | 9 +++++ test/init.test.ts | 29 ++++++--------- 6 files changed, 83 insertions(+), 33 deletions(-) diff --git a/.squad/skills/squad-version-check/SKILL.md b/.squad/skills/squad-version-check/SKILL.md index 291a4d337..3f3aebb0a 100644 --- a/.squad/skills/squad-version-check/SKILL.md +++ b/.squad/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 diff --git a/packages/squad-cli/src/cli/core/templates.ts b/packages/squad-cli/src/cli/core/templates.ts index 1c1c87c31..0745b9c1c 100644 --- a/packages/squad-cli/src/cli/core/templates.ts +++ b/packages/squad-cli/src/cli/core/templates.ts @@ -275,6 +275,30 @@ export const TEMPLATE_MANIFEST: TemplateFile[] = [ overwriteOnUpgrade: true, description: 'Cross-squad delegation — calling another squad as a sub-agent', }, + { + source: 'skills/tiered-memory/SKILL.md', + destination: '../.github/skills/tiered-memory/SKILL.md', + overwriteOnUpgrade: true, + description: 'Tiered-memory access patterns (hot/cold/wiki)', + }, + { + source: 'skills/iterative-retrieval/SKILL.md', + destination: '../.github/skills/iterative-retrieval/SKILL.md', + overwriteOnUpgrade: true, + description: 'Iterative retrieval for long-running squad work', + }, + { + source: 'skills/reflect/SKILL.md', + destination: '../.github/skills/reflect/SKILL.md', + overwriteOnUpgrade: true, + description: 'Reflection skill for capturing session learnings', + }, + { + source: 'skills/cross-squad/SKILL.md', + destination: '../.github/skills/cross-squad/SKILL.md', + overwriteOnUpgrade: true, + description: 'Cross-squad discovery — finding peer squads via registry/upstream', + }, // Session init reference (squad-owned, coordinator reads at session start) { diff --git a/packages/squad-cli/templates/skills/squad-version-check/SKILL.md b/packages/squad-cli/templates/skills/squad-version-check/SKILL.md index 291a4d337..3f3aebb0a 100644 --- a/packages/squad-cli/templates/skills/squad-version-check/SKILL.md +++ b/packages/squad-cli/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 diff --git a/packages/squad-sdk/src/config/init.ts b/packages/squad-sdk/src/config/init.ts index d0ccf2179..022e99dcb 100644 --- a/packages/squad-sdk/src/config/init.ts +++ b/packages/squad-sdk/src/config/init.ts @@ -33,7 +33,7 @@ import { ensureMemoryGovernanceDefaults } from '../memory/index.js'; * missing source dirs instead of silently skipping — see bradygaster/squad#1289 * for the prior silent-skip bug that shipped two missing skills in v0.10.0. */ -const MANIFEST_SKILL_NAMES = [ +export const MANIFEST_SKILL_NAMES = [ 'squad-conventions', 'error-recovery', 'secret-handling', @@ -1298,31 +1298,39 @@ ${projectDescription ? `- **Description:** ${projectDescription}\n` : ''}- **Cre const skillsSrc = join(templatesDir, 'skills'); const existingSkills = storage.existsSync(skillsDir) ? storage.listSync(skillsDir) : []; if (existingSkills.length === 0) { - storage.mkdirSync(skillsDir, { recursive: true }); + // Pre-check drift BEFORE writing any skill file so a manifest/template + // mismatch fails atomically with no partial install left on disk. The + // earlier shape ran the copy loop first and threw at the end — users + // saw 8 of 10 skills appear, then an error, with no clean rollback. const missing: string[] = []; for (const skillName of MANIFEST_SKILL_NAMES) { - const srcSkill = join(skillsSrc, skillName); - if (storage.existsSync(srcSkill)) { - copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage); - } else { + if (!storage.existsSync(join(skillsSrc, skillName))) { missing.push(skillName); } } if (missing.length > 0) { // Manifest/templates drift — fail loudly so v0.10.0-style silent-skip - // regressions (#1289) cannot reach users. The sync script - // scripts/sync-skill-templates.mjs is responsible for keeping - // packages/squad-sdk/templates/skills/ in step with .squad/skills/. + // regressions (#1289) cannot reach users. End-users see this when an + // installed @bradygaster/squad-sdk ships with its templates dir + // missing skills the SDK code knows about — almost always a packaging + // bug. The fix is to upgrade to a non-broken SDK version + // (`squad upgrade`); the dev-facing sync-skill-templates.mjs script + // is referenced only as the contributor-side root cause. throw new Error( - `Skill template drift: MANIFEST_SKILL_NAMES references ${missing.length} skill(s) ` + + `Skill template drift in installed @bradygaster/squad-sdk: ` + + `MANIFEST_SKILL_NAMES references ${missing.length} skill(s) ` + `missing from the SDK templates dir (${skillsSrc}): ${missing.join(', ')}. ` + - `Run \`node scripts/sync-skill-templates.mjs\` from the squad repo root, ` + - `or add the missing skill(s) under .squad/skills/.` + `This is a packaging bug — try \`squad upgrade\` or reinstall the SDK; ` + + `if it persists, please report it at https://github.com/bradygaster/squad/issues. ` + + `(Contributors: re-run \`node scripts/sync-skill-templates.mjs\` from the repo root before packaging.)` ); } + storage.mkdirSync(skillsDir, { recursive: true }); + for (const skillName of MANIFEST_SKILL_NAMES) { + const srcSkill = join(skillsSrc, skillName); + copyRecursiveSync(srcSkill, join(skillsDir, skillName), storage); + } createdFiles.push('.github/skills'); - createdFiles.push('.copilot/skills'); ->>>>>>> 7d945fea (fix(sdk,cli): bundle missing skills on init + strip fabricated provenance from tiered-memory (#1289, #1264)) } } diff --git a/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md b/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md index 291a4d337..3f3aebb0a 100644 --- a/packages/squad-sdk/templates/skills/squad-version-check/SKILL.md +++ b/packages/squad-sdk/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 diff --git a/test/init.test.ts b/test/init.test.ts index 7441fe1f9..1548fef64 100644 --- a/test/init.test.ts +++ b/test/init.test.ts @@ -8,7 +8,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'; import { mkdir, rm, readFile, writeFile } from 'fs/promises'; import { join } from 'path'; import { existsSync } from 'fs'; -import { initSquad } from '@bradygaster/squad-sdk/config'; +import { initSquad, MANIFEST_SKILL_NAMES } from '@bradygaster/squad-sdk/config'; import { onboardAgent, addAgentToConfig } from '@bradygaster/squad-sdk/agents'; import type { InitOptions, InitAgentSpec } from '@bradygaster/squad-sdk/config'; import type { OnboardOptions } from '@bradygaster/squad-sdk/agents'; @@ -268,22 +268,13 @@ describe('Squad Initialization', () => { // templates dir; this test exists to ensure that regression cannot // happen again (the loop now throws on drift, but a missing // SKILL.md after install would still indicate a deeper issue). - const expectedSkills = [ - 'squad-conventions', - 'error-recovery', - 'secret-handling', - 'git-workflow', - 'session-recovery', - 'reviewer-protocol', - 'test-discipline', - 'agent-collaboration', - 'squad-commands', - 'squad-version-check', - 'tiered-memory', - 'iterative-retrieval', - 'reflect', - 'cross-squad', - ]; + // + // The expected list comes from the same MANIFEST_SKILL_NAMES export + // the production install loop reads — so the test cannot fall out + // of sync when a new skill is added. Sanity-asserted to be non-empty + // so a future accidental empty export doesn't make this test pass + // trivially. + expect(MANIFEST_SKILL_NAMES.length).toBeGreaterThan(0); const agents: InitAgentSpec[] = [{ name: 'lead', role: 'lead' }]; const options: InitOptions = { @@ -294,8 +285,8 @@ describe('Squad Initialization', () => { await initSquad(options); - for (const skill of expectedSkills) { - const skillPath = join(TEST_ROOT, '.copilot', 'skills', skill, 'SKILL.md'); + for (const skill of MANIFEST_SKILL_NAMES) { + const skillPath = join(TEST_ROOT, '.github', 'skills', skill, 'SKILL.md'); expect(existsSync(skillPath), `expected ${skill}/SKILL.md to be installed`).toBe(true); } });