@bradygaster/squad-cli 0.9.1 → 0.9.2-insider.6

package/templates/skills/reskill/SKILL.md

@@ -1,92 +1,92 @@
----
-name: "reskill"
-description: "Team-wide charter and history optimization through skill extraction"
-domain: "team-optimization"
-confidence: "high"
-source: "manual — Brady directive to reduce per-agent context overhead"
----
-
-## Context
-
-When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills.
-
-This is a periodic maintenance activity. Run whenever charter/history bloat is suspected.
-
-## Process
-
-### Step 1: Audit
-Read all agent charters and histories. Measure byte sizes. Identify:
-
-- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template)
-- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns)
-- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills
-
-### Step 2: Extract
-For each identified pattern:
-1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md`
-2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns)
-3. Set confidence: low (first observation), medium (2+ agents), high (team-wide)
-
-### Step 3: Trim
-**Charters** — target ≤1.5KB per agent:
-- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it)
-- Remove Voice section (tagline blockquote at top of charter already captures it)
-- Trim Model section to single line: `Preferred: {model}`
-- Remove "When I'm unsure" boilerplate from Boundaries
-- Remove domain knowledge now covered by a skill — add skill reference comment if helpful
-- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only)
-
-**Histories** — target ≤8KB per agent:
-- Apply history-hygiene skill to any history >12KB
-- Promote recurring patterns (3+ occurrences across agents) to skills
-- Summarize old entries into `## Core Context` section
-- Remove session-specific metadata (dates, branch names, requester names)
-
-### Step 4: Report
-Output a savings table:
-
-| Agent | Charter Before | Charter After | History Before | History After | Saved |
-|-------|---------------|---------------|----------------|---------------|-------|
-
-Include totals and percentage reduction.
-
-## Patterns
-
-### Minimal Charter Template (target format after reskill)
-
-```
-# {Name} — {Role}
-
-> {Tagline — one sentence capturing voice and philosophy}
-
-## Identity
-- **Name:** {Name}
-- **Role:** {Role}
-- **Expertise:** {comma-separated list}
-
-## What I Own
-- {bullet list of owned artifacts/domains}
-
-## How I Work
-- {unique patterns and principles — NOT boilerplate}
-
-## Boundaries
-**I handle:** {domain list}
-**I don't handle:** {explicit exclusions}
-
-## Model
-Preferred: {model}
-```
-
-### Skill Extraction Threshold
-- **1 charter** → leave in charter (unique to that agent)
-- **2 charters** → consider extracting if >500 bytes of overlap
-- **3+ charters** → always extract to a shared skill
-
-## Anti-Patterns
-- Don't delete unique per-agent identity or domain-specific knowledge
-- Don't create skills for content only one agent uses
-- Don't merge unrelated patterns into a single mega-skill
-- Don't remove Model preference line (coordinator needs it for model selection)
-- Don't touch `.squad/decisions.md` during reskill
-- Don't remove the tagline blockquote — it's the charter's soul in one line
+---
+name: "reskill"
+description: "Team-wide charter and history optimization through skill extraction"
+domain: "team-optimization"
+confidence: "high"
+source: "manual — Brady directive to reduce per-agent context overhead"
+---
+
+## Context
+
+When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills.
+
+This is a periodic maintenance activity. Run whenever charter/history bloat is suspected.
+
+## Process
+
+### Step 1: Audit
+Read all agent charters and histories. Measure byte sizes. Identify:
+
+- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template)
+- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns)
+- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills
+
+### Step 2: Extract
+For each identified pattern:
+1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md`
+2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns)
+3. Set confidence: low (first observation), medium (2+ agents), high (team-wide)
+
+### Step 3: Trim
+**Charters** — target ≤1.5KB per agent:
+- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it)
+- Remove Voice section (tagline blockquote at top of charter already captures it)
+- Trim Model section to single line: `Preferred: {model}`
+- Remove "When I'm unsure" boilerplate from Boundaries
+- Remove domain knowledge now covered by a skill — add skill reference comment if helpful
+- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only)
+
+**Histories** — target ≤8KB per agent:
+- Apply history-hygiene skill to any history >12KB
+- Promote recurring patterns (3+ occurrences across agents) to skills
+- Summarize old entries into `## Core Context` section
+- Remove session-specific metadata (dates, branch names, requester names)
+
+### Step 4: Report
+Output a savings table:
+
+| Agent | Charter Before | Charter After | History Before | History After | Saved |
+|-------|---------------|---------------|----------------|---------------|-------|
+
+Include totals and percentage reduction.
+
+## Patterns
+
+### Minimal Charter Template (target format after reskill)
+
+```
+# {Name} — {Role}
+
+> {Tagline — one sentence capturing voice and philosophy}
+
+## Identity
+- **Name:** {Name}
+- **Role:** {Role}
+- **Expertise:** {comma-separated list}
+
+## What I Own
+- {bullet list of owned artifacts/domains}
+
+## How I Work
+- {unique patterns and principles — NOT boilerplate}
+
+## Boundaries
+**I handle:** {domain list}
+**I don't handle:** {explicit exclusions}
+
+## Model
+Preferred: {model}
+```
+
+### Skill Extraction Threshold
+- **1 charter** → leave in charter (unique to that agent)
+- **2 charters** → consider extracting if >500 bytes of overlap
+- **3+ charters** → always extract to a shared skill
+
+## Anti-Patterns
+- Don't delete unique per-agent identity or domain-specific knowledge
+- Don't create skills for content only one agent uses
+- Don't merge unrelated patterns into a single mega-skill
+- Don't remove Model preference line (coordinator needs it for model selection)
+- Don't touch `.squad/decisions.md` during reskill
+- Don't remove the tagline blockquote — it's the charter's soul in one line

package/templates/skills/retro-enforcement/SKILL.md

@@ -0,0 +1,148 @@
+# Skill: Retro Enforcement
+
+## Purpose
+
+Ensure retrospectives happen on schedule and that their action items are tracked in GitHub Issues — not markdown checklists.
+
+This skill addresses a specific, measured failure mode: **0% completion rate on markdown retro action items across 6 consecutive retrospectives**. GitHub Issues have an 85%+ completion rate in the same squad. The format was the problem, not the people.
+
+## Core Function: Test-RetroOverdue
+
+```powershell
+function Test-RetroOverdue {
+    param(
+        [string]$LogDir    = ".squad/log",
+        [int]$WindowDays   = 7,
+        [string]$Pattern   = "*retrospective*"
+    )
+
+    $cutoff = (Get-Date).AddDays(-$WindowDays)
+
+    $retroLogs = Get-ChildItem -Path $LogDir -Filter $Pattern -ErrorAction SilentlyContinue |
+                 Where-Object { $_.LastWriteTime -ge $cutoff }
+
+    return ($retroLogs.Count -eq 0)
+}
+```
+
+### Returns
+- `$true` — No retro log found within the window. **Retro is overdue. Block other work.**
+- `$false` — At least one retro log found within the window. Proceed normally.
+
+### Detection Logic
+
+The function checks `.squad/log/` for any file matching `*retrospective*` dated within the last `$WindowDays` days (default: 7). If none is found, the retro is overdue.
+
+**File naming convention:** `.squad/log/{ISO8601-timestamp}-retrospective.md`
+
+Example: `.squad/log/2026-03-24T14-45-00Z-retrospective.md`
+
+## Coordinator Integration
+
+Call `Test-RetroOverdue` **at the start of every round**, before building the work queue.
+
+```powershell
+# At round start — before any work queue construction
+if (Test-RetroOverdue -LogDir ".squad/log" -WindowDays 7) {
+    Write-Host "[RETRO] Retrospective overdue. Running before other work."
+
+    # Spawn retro facilitator
+    Invoke-RetroSession -Mode "catch-up"
+
+    # Wait for retro log to be written
+    # Then resume normal round
+}
+
+# Proceed with normal work queue
+$workQueue = Get-PendingIssues | Sort-Object -Property Priority
+```
+
+### Blocking Semantics
+
+When `Test-RetroOverdue` returns `$true`:
+
+1. **Do not start any other work** until the retro completes
+2. **Spawn the facilitator agent** (Scribe or designated) with retro mode
+3. **Wait for the log file** to be written to `.squad/log/`
+4. **Verify action items** were created as GitHub Issues (not markdown)
+5. **Resume normal round** after retro log confirmed
+
+## Action Item Enforcement
+
+Every retro action item MUST become a GitHub Issue. The facilitator agent is responsible for this. The coordinator verifies.
+
+### Verification Check
+
+```powershell
+function Test-RetroActionItemsCreated {
+    param([string]$RetroLogPath)
+
+    $content = Get-Content $RetroLogPath -Raw
+
+    # Check for Issue references (e.g., #1478, https://github.com/.../issues/1478)
+    $issueRefs = [regex]::Matches($content, '(?:#\d{3,}|issues/\d{3,})')
+
+    # Check for unclosed markdown checkboxes (bad pattern)
+    $openCheckboxes = [regex]::Matches($content, '- \[ \]')
+
+    if ($openCheckboxes.Count -gt 0) {
+        Write-Warning "[RETRO] Found $($openCheckboxes.Count) markdown checkboxes — convert to Issues"
+        return $false
+    }
+
+    return ($issueRefs.Count -gt 0)
+}
+```
+
+### Why Not Markdown Checklists
+
+From production data in tamirdresher/tamresearch1:
+
+| Retro | Action Items Format | Completion |
+|-------|---------------------|------------|
+| 2025-12-05 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2025-12-19 | Markdown `- [ ]` | 0/3 = **0%** |
+| 2026-01-09 | Markdown `- [ ]` | 0/5 = **0%** |
+| 2026-01-23 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2026-02-07 | Markdown `- [ ]` | 0/3 = **0%** |
+| 2026-02-21 | Markdown `- [ ]` | 0/4 = **0%** |
+| 2026-03-24 | GitHub Issues | 4/4 = **100%** (after enforcement) |
+
+**Root cause:** Markdown checklists have no assignee, no notifications, no close event, and no query surface. They are invisible to every workflow that drives completion.
+
+## Cadence Enforcement
+
+### Recommended schedule
+- Weekly squads: window = 7 days
+- Bi-weekly squads: window = 14 days
+
+### Ralph integration example
+
+```powershell
+# ralph-watch.ps1 — round start hook
+function Invoke-RoundStart {
+    # 1. Always check retro first
+    if (Test-RetroOverdue -LogDir "$RepoRoot/.squad/log" -WindowDays 7) {
+        Write-Host "[RALPH] Retro overdue — enforcing before work queue"
+        Invoke-RetroSession
+        return  # Re-enter round after retro completes
+    }
+
+    # 2. Normal work queue
+    $issues = Get-ReadyIssues
+    foreach ($issue in $issues) {
+        Invoke-WorkItem -Issue $issue
+    }
+}
+```
+
+## Skill Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | `retro-enforcement` |
+| **Category** | Ceremonies / Process |
+| **Trigger** | Coordinator round start |
+| **Dependencies** | `.squad/log/` directory, GitHub Issues API |
+| **Tested in** | tamirdresher/tamresearch1 (production, March 2026) |
+| **Outcome** | Retro cadence restored; action item completion 0% → 100% |

package/templates/skills/reviewer-protocol/SKILL.md

@@ -1,79 +1,79 @@
----
-name: "reviewer-protocol"
-description: "Reviewer rejection workflow and strict lockout semantics"
-domain: "orchestration"
-confidence: "high"
-source: "extracted"
----
-
-## Context
-
-When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review.
-
-## Patterns
-
-### Reviewer Rejection Protocol
-
-When a team member has a **Reviewer** role:
-
-- Reviewers may **approve** or **reject** work from other agents.
-- On **rejection**, the Reviewer may choose ONE of:
-  1. **Reassign:** Require a *different* agent to do the revision (not the original author).
-  2. **Escalate:** Require a *new* agent be spawned with specific expertise.
-- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise.
-- If the Reviewer approves, work proceeds normally.
-
-### Strict Lockout Semantics
-
-When an artifact is **rejected** by a Reviewer:
-
-1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions.
-2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate).
-3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent.
-4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced.
-5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts.
-6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise.
-7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author.
-
-## Examples
-
-**Example 1: Reassign after rejection**
-1. Fenster writes authentication module
-2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this."
-3. Coordinator: Fenster is now locked out of this artifact
-4. Coordinator spawns Verbal to revise the authentication module
-5. Verbal produces v2
-6. Hockney reviews v2 → approves
-7. Lockout clears for next artifact
-
-**Example 2: Escalate for expertise**
-1. Edie writes TypeScript config
-2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate."
-3. Coordinator: Edie is now locked out
-4. Coordinator spawns new agent (or existing TS expert) to revise
-5. New agent produces v2
-6. Keaton reviews v2
-
-**Example 3: Deadlock handling**
-1. Fenster writes module → rejected
-2. Verbal revises → rejected
-3. Hockney revises → rejected
-4. All 3 eligible agents are now locked out
-5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]"
-
-**Example 4: Reviewer accidentally names original author**
-1. Fenster writes module → rejected
-2. Hockney says: "Fenster should fix the error handling"
-3. Coordinator: "Fenster is locked out as the original author. Please name a different agent."
-4. Hockney: "Verbal, then"
-5. Coordinator spawns Verbal
-
-## Anti-Patterns
-
-- ❌ Allowing the original author to self-revise after rejection
-- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision
-- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user)
-- ❌ Applying lockout across unrelated artifacts (scope is per-artifact)
-- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent)
-- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle)
-- ❌ Skipping verification that the revision agent is not the original author
+---
+name: "reviewer-protocol"
+description: "Reviewer rejection workflow and strict lockout semantics"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+---
+
+## Context
+
+When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review.
+
+## Patterns
+
+### Reviewer Rejection Protocol
+
+When a team member has a **Reviewer** role:
+
+- Reviewers may **approve** or **reject** work from other agents.
+- On **rejection**, the Reviewer may choose ONE of:
+  1. **Reassign:** Require a *different* agent to do the revision (not the original author).
+  2. **Escalate:** Require a *new* agent be spawned with specific expertise.
+- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise.
+- If the Reviewer approves, work proceeds normally.
+
+### Strict Lockout Semantics
+
+When an artifact is **rejected** by a Reviewer:
+
+1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions.
+2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate).
+3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent.
+4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced.
+5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts.
+6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise.
+7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author.
+
+## Examples
+
+**Example 1: Reassign after rejection**
+1. Fenster writes authentication module
+2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this."
+3. Coordinator: Fenster is now locked out of this artifact
+4. Coordinator spawns Verbal to revise the authentication module
+5. Verbal produces v2
+6. Hockney reviews v2 → approves
+7. Lockout clears for next artifact
+
+**Example 2: Escalate for expertise**
+1. Edie writes TypeScript config
+2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate."
+3. Coordinator: Edie is now locked out
+4. Coordinator spawns new agent (or existing TS expert) to revise
+5. New agent produces v2
+6. Keaton reviews v2
+
+**Example 3: Deadlock handling**
+1. Fenster writes module → rejected
+2. Verbal revises → rejected
+3. Hockney revises → rejected
+4. All 3 eligible agents are now locked out
+5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]"
+
+**Example 4: Reviewer accidentally names original author**
+1. Fenster writes module → rejected
+2. Hockney says: "Fenster should fix the error handling"
+3. Coordinator: "Fenster is locked out as the original author. Please name a different agent."
+4. Hockney: "Verbal, then"
+5. Coordinator spawns Verbal
+
+## Anti-Patterns
+
+- ❌ Allowing the original author to self-revise after rejection
+- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision
+- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user)
+- ❌ Applying lockout across unrelated artifacts (scope is per-artifact)
+- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent)
+- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle)
+- ❌ Skipping verification that the revision agent is not the original author