@bradygaster/squad-cli 0.8.25 → 0.9.1

package/templates/ralph-circuit-breaker.md

@@ -0,0 +1,313 @@
+# Ralph Circuit Breaker — Model Rate Limit Fallback
+
+> Classic circuit breaker pattern (Hystrix / Polly / Resilience4j) applied to Copilot model selection.
+> When the preferred model hits rate limits, Ralph automatically degrades to free-tier models, then self-heals.
+
+## Problem
+
+When running multiple Ralph instances across repos, Copilot model rate limits cause cascading failures.
+All Ralphs fail simultaneously when the preferred model (e.g., `claude-sonnet-4.6`) hits quota.
+
+Premium models burn quota fast:
+| Model | Multiplier | Risk |
+|-------|-----------|------|
+| `claude-sonnet-4.6` | 1x | Moderate with many Ralphs |
+| `claude-opus-4.6` | 10x | High |
+| `gpt-5.4` | 50x | Very high |
+| `gpt-5.4-mini` | **0x** | **Free — unlimited** |
+| `gpt-5-mini` | **0x** | **Free — unlimited** |
+| `gpt-4.1` | **0x** | **Free — unlimited** |
+
+## Circuit Breaker States
+
+```
+┌─────────┐   rate limit error    ┌────────┐
+│ CLOSED  │ ───────────────────►  │  OPEN  │
+│ (normal)│                       │(fallback)│
+└────┬────┘   ◄──────────────── └────┬────┘
+     │        2 consecutive          │
+     │        successes              │ cooldown expires
+     │                               ▼
+     │                          ┌──────────┐
+     └───── success ◄────────  │HALF-OPEN │
+             (close)            │ (testing) │
+                                └──────────┘
+```
+
+### CLOSED (normal operation)
+- Use preferred model from config
+- Every successful response confirms circuit stays closed
+- On rate limit error → transition to OPEN
+
+### OPEN (rate limited — fallback active)
+- Fall back through the free-tier model chain:
+  1. `gpt-5.4-mini`
+  2. `gpt-5-mini`
+  3. `gpt-4.1`
+- Start cooldown timer (default: 10 minutes)
+- When cooldown expires → transition to HALF-OPEN
+
+### HALF-OPEN (testing recovery)
+- Try preferred model again
+- If 2 consecutive successes → transition to CLOSED
+- If rate limit error → back to OPEN, reset cooldown
+
+## State File: `.squad/ralph-circuit-breaker.json`
+
+```json
+{
+  "state": "closed",
+  "preferredModel": "claude-sonnet-4.6",
+  "fallbackChain": ["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"],
+  "currentFallbackIndex": 0,
+  "cooldownMinutes": 10,
+  "openedAt": null,
+  "halfOpenSuccesses": 0,
+  "consecutiveFailures": 0,
+  "metrics": {
+    "totalFallbacks": 0,
+    "totalRecoveries": 0,
+    "lastFallbackAt": null,
+    "lastRecoveryAt": null
+  }
+}
+```
+
+## PowerShell Functions
+
+Paste these into your `ralph-watch.ps1` or source them from a shared module.
+
+### `Get-CircuitBreakerState`
+
+```powershell
+function Get-CircuitBreakerState {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    if (-not (Test-Path $StateFile)) {
+        $default = @{
+            state              = "closed"
+            preferredModel     = "claude-sonnet-4.6"
+            fallbackChain      = @("gpt-5.4-mini", "gpt-5-mini", "gpt-4.1")
+            currentFallbackIndex = 0
+            cooldownMinutes    = 10
+            openedAt           = $null
+            halfOpenSuccesses  = 0
+            consecutiveFailures = 0
+            metrics            = @{
+                totalFallbacks  = 0
+                totalRecoveries = 0
+                lastFallbackAt  = $null
+                lastRecoveryAt  = $null
+            }
+        }
+        $default | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+        return $default
+    }
+
+    return (Get-Content $StateFile -Raw | ConvertFrom-Json)
+}
+```
+
+### `Save-CircuitBreakerState`
+
+```powershell
+function Save-CircuitBreakerState {
+    param(
+        [object]$State,
+        [string]$StateFile = ".squad/ralph-circuit-breaker.json"
+    )
+
+    $State | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+}
+```
+
+### `Get-CurrentModel`
+
+Returns the model Ralph should use right now, based on circuit state.
+
+```powershell
+function Get-CurrentModel {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+
+    switch ($cb.state) {
+        "closed" {
+            return $cb.preferredModel
+        }
+        "open" {
+            # Check if cooldown has expired
+            if ($cb.openedAt) {
+                $opened = [DateTime]::Parse($cb.openedAt)
+                $elapsed = (Get-Date) - $opened
+                if ($elapsed.TotalMinutes -ge $cb.cooldownMinutes) {
+                    # Transition to half-open
+                    $cb.state = "half-open"
+                    $cb.halfOpenSuccesses = 0
+                    Save-CircuitBreakerState -State $cb -StateFile $StateFile
+                    Write-Host "  [circuit-breaker] Cooldown expired. Testing preferred model..." -ForegroundColor Yellow
+                    return $cb.preferredModel
+                }
+            }
+            # Still in cooldown — use fallback
+            $idx = [Math]::Min($cb.currentFallbackIndex, $cb.fallbackChain.Count - 1)
+            return $cb.fallbackChain[$idx]
+        }
+        "half-open" {
+            return $cb.preferredModel
+        }
+        default {
+            return $cb.preferredModel
+        }
+    }
+}
+```
+
+### `Update-CircuitBreakerOnSuccess`
+
+Call after every successful model response.
+
+```powershell
+function Update-CircuitBreakerOnSuccess {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures = 0
+
+    if ($cb.state -eq "half-open") {
+        $cb.halfOpenSuccesses++
+        if ($cb.halfOpenSuccesses -ge 2) {
+            # Recovery! Close the circuit
+            $cb.state = "closed"
+            $cb.openedAt = $null
+            $cb.halfOpenSuccesses = 0
+            $cb.currentFallbackIndex = 0
+            $cb.metrics.totalRecoveries++
+            $cb.metrics.lastRecoveryAt = (Get-Date).ToString("o")
+            Save-CircuitBreakerState -State $cb -StateFile $StateFile
+            Write-Host "  [circuit-breaker] RECOVERED — back to preferred model ($($cb.preferredModel))" -ForegroundColor Green
+            return
+        }
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+        Write-Host "  [circuit-breaker] Half-open success $($cb.halfOpenSuccesses)/2" -ForegroundColor Yellow
+        return
+    }
+
+    # closed state — nothing to do
+}
+```
+
+### `Update-CircuitBreakerOnRateLimit`
+
+Call when a model response indicates rate limiting (HTTP 429 or error message containing "rate limit").
+
+```powershell
+function Update-CircuitBreakerOnRateLimit {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures++
+
+    if ($cb.state -eq "closed" -or $cb.state -eq "half-open") {
+        # Open the circuit
+        $cb.state = "open"
+        $cb.openedAt = (Get-Date).ToString("o")
+        $cb.halfOpenSuccesses = 0
+        $cb.currentFallbackIndex = 0
+        $cb.metrics.totalFallbacks++
+        $cb.metrics.lastFallbackAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+
+        $fallbackModel = $cb.fallbackChain[0]
+        Write-Host "  [circuit-breaker] RATE LIMITED — falling back to $fallbackModel (cooldown: $($cb.cooldownMinutes)m)" -ForegroundColor Red
+        return
+    }
+
+    if ($cb.state -eq "open") {
+        # Already open — try next fallback in chain if current one also fails
+        if ($cb.currentFallbackIndex -lt ($cb.fallbackChain.Count - 1)) {
+            $cb.currentFallbackIndex++
+            $nextModel = $cb.fallbackChain[$cb.currentFallbackIndex]
+            Write-Host "  [circuit-breaker] Fallback also limited — trying $nextModel" -ForegroundColor Red
+        }
+        # Reset cooldown timer
+        $cb.openedAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+    }
+}
+```
+
+## Integration with ralph-watch.ps1
+
+In your Ralph polling loop, wrap the model selection:
+
+```powershell
+# At the top of your polling loop
+$model = Get-CurrentModel
+
+# When invoking copilot CLI
+$result = copilot-cli --model $model ...
+
+# After the call
+if ($result -match "rate.?limit" -or $LASTEXITCODE -eq 429) {
+    Update-CircuitBreakerOnRateLimit
+} else {
+    Update-CircuitBreakerOnSuccess
+}
+```
+
+### Full integration example
+
+```powershell
+# Source the circuit breaker functions
+. .squad-templates/ralph-circuit-breaker-functions.ps1
+
+while ($true) {
+    $model = Get-CurrentModel
+    Write-Host "Polling with model: $model"
+
+    try {
+        # Your existing Ralph logic here, but pass $model
+        $response = Invoke-RalphCycle -Model $model
+
+        # Success path
+        Update-CircuitBreakerOnSuccess
+    }
+    catch {
+        if ($_.Exception.Message -match "rate.?limit|429|quota|Too Many Requests") {
+            Update-CircuitBreakerOnRateLimit
+            # Retry immediately with fallback model
+            continue
+        }
+        # Other errors — handle normally
+        throw
+    }
+
+    Start-Sleep -Seconds $pollInterval
+}
+```
+
+## Configuration
+
+Override defaults by editing `.squad/ralph-circuit-breaker.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `preferredModel` | `claude-sonnet-4.6` | Model to use when circuit is closed |
+| `fallbackChain` | `["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"]` | Ordered fallback models (all free-tier) |
+| `cooldownMinutes` | `10` | How long to wait before testing recovery |
+
+## Metrics
+
+The state file tracks operational metrics:
+
+- **totalFallbacks** — How many times the circuit opened
+- **totalRecoveries** — How many times it recovered to preferred model
+- **lastFallbackAt** — ISO timestamp of last rate limit event
+- **lastRecoveryAt** — ISO timestamp of last successful recovery
+
+Query metrics with:
+```powershell
+$cb = Get-Content .squad/ralph-circuit-breaker.json | ConvertFrom-Json
+Write-Host "Fallbacks: $($cb.metrics.totalFallbacks) | Recoveries: $($cb.metrics.totalRecoveries)"
+```

package/templates/raw-agent-output.md

@@ -1,37 +1,37 @@
-# Raw Agent Output — Appendix Format
-
-> This template defines the format for the `## APPENDIX: RAW AGENT OUTPUTS` section
-> in any multi-agent artifact.
-
-## Rules
-
-1. **Verbatim only.** Paste the agent's response exactly as returned. No edits.
-2. **No summarizing.** Do not condense, paraphrase, or rephrase any part of the output.
-3. **No rewriting.** Do not fix typos, grammar, formatting, or style.
-4. **No code fences around the entire output.** The raw output is pasted as-is, not wrapped in ``` blocks.
-5. **One section per agent.** Each agent that contributed gets its own heading.
-6. **Order matches work order.** List agents in the order they were spawned.
-7. **Include all outputs.** Even if an agent's work was rejected, include their output for diagnostic traceability.
-
-## Format
-
-```markdown
-## APPENDIX: RAW AGENT OUTPUTS
-
-### {Name} ({Role}) — Raw Output
-
-{Paste agent's verbatim response here, unedited}
-
-### {Name} ({Role}) — Raw Output
-
-{Paste agent's verbatim response here, unedited}
-```
-
-## Why This Exists
-
-The appendix provides diagnostic integrity. It lets anyone verify:
-- What each agent actually said (vs. what the Coordinator assembled)
-- Whether the Coordinator faithfully represented agent work
-- What was lost or changed in synthesis
-
-Without raw outputs, multi-agent collaboration is unauditable.
+# Raw Agent Output — Appendix Format
+
+> This template defines the format for the `## APPENDIX: RAW AGENT OUTPUTS` section
+> in any multi-agent artifact.
+
+## Rules
+
+1. **Verbatim only.** Paste the agent's response exactly as returned. No edits.
+2. **No summarizing.** Do not condense, paraphrase, or rephrase any part of the output.
+3. **No rewriting.** Do not fix typos, grammar, formatting, or style.
+4. **No code fences around the entire output.** The raw output is pasted as-is, not wrapped in ``` blocks.
+5. **One section per agent.** Each agent that contributed gets its own heading.
+6. **Order matches work order.** List agents in the order they were spawned.
+7. **Include all outputs.** Even if an agent's work was rejected, include their output for diagnostic traceability.
+
+## Format
+
+```markdown
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+```
+
+## Why This Exists
+
+The appendix provides diagnostic integrity. It lets anyone verify:
+- What each agent actually said (vs. what the Coordinator assembled)
+- Whether the Coordinator faithfully represented agent work
+- What was lost or changed in synthesis
+
+Without raw outputs, multi-agent collaboration is unauditable.

package/templates/roster.md

@@ -1,60 +1,60 @@
-# Team Roster
-
-> {One-line project description}
-
-## Coordinator
-
-| Name | Role | Notes |
-|------|------|-------|
-| Squad | Coordinator | Routes work, enforces handoffs and reviewer gates. Does not generate domain artifacts. |
-
-## Members
-
-| Name | Role | Charter | Status |
-|------|------|---------|--------|
-| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
-| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
-| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
-| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
-| Scribe | Session Logger | `.squad/agents/scribe/charter.md` | 📋 Silent |
-| Ralph | Work Monitor | — | 🔄 Monitor |
-
-## Coding Agent
-
-<!-- copilot-auto-assign: false -->
-
-| Name | Role | Charter | Status |
-|------|------|---------|--------|
-| @copilot | Coding Agent | — | 🤖 Coding Agent |
-
-### Capabilities
-
-**🟢 Good fit — auto-route when enabled:**
-- Bug fixes with clear reproduction steps
-- Test coverage (adding missing tests, fixing flaky tests)
-- Lint/format fixes and code style cleanup
-- Dependency updates and version bumps
-- Small isolated features with clear specs
-- Boilerplate/scaffolding generation
-- Documentation fixes and README updates
-
-**🟡 Needs review — route to @copilot but flag for squad member PR review:**
-- Medium features with clear specs and acceptance criteria
-- Refactoring with existing test coverage
-- API endpoint additions following established patterns
-- Migration scripts with well-defined schemas
-
-**🔴 Not suitable — route to squad member instead:**
-- Architecture decisions and system design
-- Multi-system integration requiring coordination
-- Ambiguous requirements needing clarification
-- Security-critical changes (auth, encryption, access control)
-- Performance-critical paths requiring benchmarking
-- Changes requiring cross-team discussion
-
-## Project Context
-
-- **Owner:** {user name}
-- **Stack:** {languages, frameworks, tools}
-- **Description:** {what the project does, in one sentence}
-- **Created:** {timestamp}
+# Team Roster
+
+> {One-line project description}
+
+## Coordinator
+
+| Name | Role | Notes |
+|------|------|-------|
+| Squad | Coordinator | Routes work, enforces handoffs and reviewer gates. Does not generate domain artifacts. |
+
+## Members
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| Scribe | Session Logger | `.squad/agents/scribe/charter.md` | 📋 Silent |
+| Ralph | Work Monitor | — | 🔄 Monitor |
+
+## Coding Agent
+
+<!-- copilot-auto-assign: false -->
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| @copilot | Coding Agent | — | 🤖 Coding Agent |
+
+### Capabilities
+
+**🟢 Good fit — auto-route when enabled:**
+- Bug fixes with clear reproduction steps
+- Test coverage (adding missing tests, fixing flaky tests)
+- Lint/format fixes and code style cleanup
+- Dependency updates and version bumps
+- Small isolated features with clear specs
+- Boilerplate/scaffolding generation
+- Documentation fixes and README updates
+
+**🟡 Needs review — route to @copilot but flag for squad member PR review:**
+- Medium features with clear specs and acceptance criteria
+- Refactoring with existing test coverage
+- API endpoint additions following established patterns
+- Migration scripts with well-defined schemas
+
+**🔴 Not suitable — route to squad member instead:**
+- Architecture decisions and system design
+- Multi-system integration requiring coordination
+- Ambiguous requirements needing clarification
+- Security-critical changes (auth, encryption, access control)
+- Performance-critical paths requiring benchmarking
+- Changes requiring cross-team discussion
+
+## Project Context
+
+- **Owner:** {user name}
+- **Stack:** {languages, frameworks, tools}
+- **Description:** {what the project does, in one sentence}
+- **Created:** {timestamp}

package/templates/routing.md

@@ -1,54 +1,39 @@
-# Work Routing
-
-How to decide who handles what.
-
-## Routing Table
-
-| Work Type | Route To | Examples |
-|-----------|----------|----------|
-| {domain 1} | {Name} | {example tasks} |
-| {domain 2} | {Name} | {example tasks} |
-| {domain 3} | {Name} | {example tasks} |
-| Code review | {Name} | Review PRs, check quality, suggest improvements |
-| Testing | {Name} | Write tests, find edge cases, verify fixes |
-| Scope & priorities | {Name} | What to build next, trade-offs, decisions |
-| Async issue work (bugs, tests, small features) | @copilot 🤖 | Well-defined tasks matching capability profile |
-| Session logging | Scribe | Automatic — never needs routing |
-
-## Issue Routing
-
-| Label | Action | Who |
-|-------|--------|-----|
-| `squad` | Triage: analyze issue, evaluate @copilot fit, assign `squad:{member}` label | Lead |
-| `squad:{name}` | Pick up issue and complete the work | Named member |
-| `squad:copilot` | Assign to @copilot for autonomous work (if enabled) | @copilot 🤖 |
-
-### How Issue Assignment Works
-
-1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, evaluating @copilot's capability profile, assigning the right `squad:{member}` label, and commenting with triage notes.
-2. **@copilot evaluation:** The Lead checks if the issue matches @copilot's capability profile (🟢 good fit / 🟡 needs review / 🔴 not suitable). If it's a good fit, the Lead may route to `squad:copilot` instead of a squad member.
-3. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
-4. When `squad:copilot` is applied and auto-assign is enabled, `@copilot` is assigned on the issue and picks it up autonomously.
-5. Members can reassign by removing their label and adding another member's label.
-6. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
-
-### Lead Triage Guidance for @copilot
-
-When triaging, the Lead should ask:
-
-1. **Is this well-defined?** Clear title, reproduction steps or acceptance criteria, bounded scope → likely 🟢
-2. **Does it follow existing patterns?** Adding a test, fixing a known bug, updating a dependency → likely 🟢
-3. **Does it need design judgment?** Architecture, API design, UX decisions → likely 🔴
-4. **Is it security-sensitive?** Auth, encryption, access control → always 🔴
-5. **Is it medium complexity with specs?** Feature with clear requirements, refactoring with tests → likely 🟡
-
-## Rules
-
-1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
-2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
-3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
-4. **When two agents could handle it**, pick the one whose domain is the primary concern.
-5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
-6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
-7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.
-8. **@copilot routing** — when evaluating issues, check @copilot's capability profile in `team.md`. Route 🟢 good-fit tasks to `squad:copilot`. Flag 🟡 needs-review tasks for PR review. Keep 🔴 not-suitable tasks with squad members.
+# Work Routing
+
+How to decide who handles what.
+
+## Routing Table
+
+| Work Type | Route To | Examples |
+|-----------|----------|----------|
+| {domain 1} | {Name} | {example tasks} |
+| {domain 2} | {Name} | {example tasks} |
+| {domain 3} | {Name} | {example tasks} |
+| Code review | {Name} | Review PRs, check quality, suggest improvements |
+| Testing | {Name} | Write tests, find edge cases, verify fixes |
+| Scope & priorities | {Name} | What to build next, trade-offs, decisions |
+| Session logging | Scribe | Automatic — never needs routing |
+
+## Issue Routing
+
+| Label | Action | Who |
+|-------|--------|-----|
+| `squad` | Triage: analyze issue, assign `squad:{member}` label | Lead |
+| `squad:{name}` | Pick up issue and complete the work | Named member |
+
+### How Issue Assignment Works
+
+1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, assigning the right `squad:{member}` label, and commenting with triage notes.
+2. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
+3. Members can reassign by removing their label and adding another member's label.
+4. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
+
+## Rules
+
+1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
+2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
+3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
+4. **When two agents could handle it**, pick the one whose domain is the primary concern.
+5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
+6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
+7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.