@bradygaster/squad-cli 0.9.0 → 0.9.2-insider.5

package/templates/skills/notification-routing/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "notification-routing"
+description: "Route agent notifications to specific channels by type — prevent alert fatigue from single-channel flooding"
+domain: "communication"
+confidence: "high"
+source: "earned"
+---
+
+## Context
+
+When a Squad grows beyond a few agents, notifications flood a single channel — failure alerts drown in daily
+briefings, tech news buries security findings, and everything gets ignored. This is the pub-sub problem:
+a single message queue for everything is a recipe for missed alerts.
+
+The fix is **topic-based routing**: agents tag notifications with a channel type, and a routing function
+sends them to the appropriate destination.
+
+**Trigger symptoms:**
+- Important alerts missed because they're buried in routine notifications
+- Team members turning off notifications entirely (signal overwhelm)
+- Onboarding friction: "where do I look for X?"
+
+## Patterns
+
+### Channel Config Schema
+
+Define a `.squad/teams-channels.json` (or equivalent) mapping notification types to channel identifiers:
+
+```json
+{
+  "teamId": "your-team-id",
+  "channels": {
+    "notifications": "squad-alerts",
+    "tech-news":     "tech-news",
+    "security":      "security-findings",
+    "releases":      "release-announcements",
+    "daily-digest":  "daily-digest"
+  }
+}
+```
+
+Place this in `.squad/` (git-tracked, shared across the team). For platforms that use channel IDs instead of
+names (Teams, Slack), store the resolved ID alongside the name to avoid name-collision bugs:
+
+```json
+{
+  "channels": {
+    "notifications": { "name": "squad-alerts", "id": "channel-id-opaque-string" }
+  }
+}
+```
+
+### CHANNEL: Tag Convention
+
+Agents prefix their output with `CHANNEL:<type>` to signal where the notification should go:
+
+```
+CHANNEL:security
+Worf found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5
+```
+
+### Routing Dispatcher (shell pseudocode)
+
+```bash
+dispatch_notification() {
+  local raw_output="$1"
+  local channel="notifications"  # default
+
+  if echo "$raw_output" | grep -qE '^CHANNEL:[a-z][a-z0-9-]*'; then
+    channel=$(echo "$raw_output" | head -1 | cut -d: -f2)
+    raw_output=$(echo "$raw_output" | tail -n +2)
+  fi
+
+  send_notification --channel "$channel" --message "$raw_output"
+}
+```
+
+### Provider-Agnostic Adapter
+
+The routing layer is provider-agnostic. Plug in your platform adapter:
+
+```
+.squad/notify-adapter.sh   # Teams / Slack / Discord / webhook -- swappable
+```
+
+The routing config and CHANNEL: tags never change. Only the adapter changes per deployment.
+
+## Anti-Patterns
+
+**Never send all notification types to one channel:**
+```
+send_notification --channel "general" --message "$anything"
+```
+
+**Never use display names as identifiers (name collision risk):**
+```
+send_to_team --name "Squad" --channel "notifications"
+```
+
+Resolve channel IDs once at setup. Use IDs at runtime.
+
+## Distributed Systems Pattern
+
+This is **pub-sub with topic routing** -- the same principle as Kafka topics, RabbitMQ routing keys, and
+AWS SNS topic filtering. Route by type. Each consumer subscribes to the topics it cares about.

package/templates/skills/pr-screenshots/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: "pr-screenshots"
+description: "Capture Playwright screenshots and embed them in GitHub PR descriptions"
+domain: "pull-requests, visual-review, docs, testing"
+confidence: "high"
+source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)"
+---
+
+## Context
+
+When a PR includes visual changes (docs sites, UI components, generated pages), reviewers
+need to see what the PR delivers without checking out the branch. Screenshots belong in
+the **PR description body**, not as committed files and not as text descriptions.
+
+Use this skill whenever:
+- A PR touches docs site pages (Astro, Starlight, etc.)
+- A PR adds or changes UI components
+- A PR generates visual artifacts (TypeDoc, Storybook, diagrams)
+- Playwright tests already capture screenshots as part of testing
+
+## Patterns
+
+### 1. Capture screenshots with Playwright
+
+If Playwright tests already exist and produce screenshots, reuse those. Otherwise,
+write a minimal capture script:
+
+```javascript
+// scripts/capture-pr-screenshots.mjs
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+
+const screenshots = [
+  { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' },
+  { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' },
+];
+
+for (const { url, name } of screenshots) {
+  await page.goto(url, { waitUntil: 'networkidle' });
+  await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false });
+}
+
+await browser.close();
+```
+
+### 2. Host screenshots on a temporary branch
+
+GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary
+images directly. Use a temporary orphan branch to host the images:
+
+```powershell
+# Save current branch
+$currentBranch = git branch --show-current
+
+# Create orphan branch with only screenshot files
+git checkout --orphan screenshots-temp
+git reset
+git add screenshots/*.png
+git commit -m "screenshots for PR review"
+git push origin screenshots-temp --force
+
+# Build raw URLs
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+# Each image: $base/{name}.png
+
+# Return to working branch
+git checkout -f $currentBranch
+```
+
+### 3. Embed in PR description
+
+Use `gh pr edit` with the raw URLs embedded as markdown images:
+
+```powershell
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+
+gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @"
+## {PR Title}
+
+### What this PR delivers
+- {bullet points of changes}
+
+---
+
+### Screenshots
+
+#### {Page/Feature Name}
+![{alt text}]($base/{name}.png)
+
+#### {Another Page}
+![{alt text}]($base/{another-name}.png)
+
+---
+
+### To verify locally
+```bash
+{commands to run locally}
+```
+"@
+```
+
+### 4. Cleanup after merge
+
+After the PR is merged, delete the temporary branch:
+
+```bash
+git push origin --delete screenshots-temp
+```
+
+### 5. Gitignore screenshots locally
+
+Screenshots are build artifacts — never commit them to feature branches:
+
+```gitignore
+# PR screenshots (hosted on temp branch, not committed to features)
+screenshots/
+docs/tests/screenshots/
+```
+
+## Examples
+
+### Example: Docs site PR with 3 pages
+
+1. Start dev server: `cd docs && npm run dev`
+2. Run Playwright tests (they capture screenshots as a side effect)
+3. Push screenshots to `screenshots-temp` branch
+4. Update PR body with embedded `![...]()` image references
+5. Reviewer sees the pages inline without checking out the branch
+
+### Example: Reusing existing Playwright test screenshots
+
+If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`:
+
+```powershell
+cd docs && npx playwright test tests/api-reference.spec.mjs
+# Screenshots now at docs/tests/screenshots/*.png
+# Push those to screenshots-temp and embed in PR
+```
+
+## Anti-Patterns
+
+- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale
+- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting
+- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads
+- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern
+- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see
+- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge

package/templates/skills/ralph-two-pass-scan/SKILL.md

@@ -0,0 +1,35 @@
+# Skill: Ralph — Two-Pass Issue Scanning
+**Confidence:** high
+**Domain:** work-monitoring
+**Last validated:** 2026-03-24
+
+## Context
+Cuts GitHub API calls from N+1 to ~7 per round (~72% reduction) by separating list scanning from full hydration.
+Addresses the scanning inefficiency described in issue #596.
+
+## Pattern
+
+### Pass 1 — Lightweight Scan
+
+```
+gh issue list --state open --json number,title,labels,assignees --limit 100
+```
+
+**Skip hydration if ANY of these match:**
+
+| Condition | Skip reason |
+|-----------|-------------|
+| `assignees` non-empty AND no `status:needs-review` | Already owned |
+| Labels contain `status:blocked` or `status:waiting-external` | Externally gated |
+| Labels contain `status:done` or `status:postponed` | Closed loop |
+| Title matches stale/noisy pattern (`[chore]`, `[auto]`) | Low-signal |
+
+### Pass 2 — Selective Hydration
+
+For each issue surviving Pass 1:
+
+```
+gh issue view <number> --json number,title,body,labels,assignees,comments,state
+```
+
+Then apply normal Ralph triage logic. Rule of thumb: hydrate ≤ 30% of scanned list. If more than 30% survive Pass 1, tighten filter rules.

package/templates/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