@bradygaster/squad-sdk 0.8.24 → 0.9.0

package/templates/cooperative-rate-limiting.md

@@ -0,0 +1,229 @@
+# Cooperative Rate Limiting for Multi-Agent Deployments
+
+> Coordinate API quota across multiple Ralph instances to prevent cascading failures.
+
+## Problem
+
+The [circuit breaker template](ralph-circuit-breaker.md) handles single-instance rate limiting well. But when multiple Ralphs run across machines (or pods on K8s), each instance independently hits API limits:
+
+- **No coordination** — 5 Ralphs each think they have full API quota
+- **Thundering herd** — All Ralphs retry simultaneously after rate limit resets
+- **Priority inversion** — Low-priority work exhausts quota before critical work runs
+- **Reactive only** — Circuit opens AFTER 429, wasting the failed request
+
+## Solution: 6-Pattern Architecture
+
+These patterns layer on top of the existing circuit breaker. Each is independent — adopt one or all.
+
+### Pattern 1: Traffic Light (RAAS — Rate-Aware Agent Scheduling)
+
+Map GitHub API `X-RateLimit-Remaining` to traffic light states:
+
+| State | Remaining % | Behavior |
+|-------|------------|----------|
+| 🟢 GREEN | >20% | Normal operation |
+| 🟡 AMBER | 5–20% | Only P0 agents proceed |
+| 🔴 RED | <5% | Block all except emergency P0 |
+
+```typescript
+type TrafficLight = 'green' | 'amber' | 'red';
+
+function getTrafficLight(remaining: number, limit: number): TrafficLight {
+  const pct = remaining / limit;
+  if (pct > 0.20) return 'green';
+  if (pct > 0.05) return 'amber';
+  return 'red';
+}
+
+function shouldProceed(light: TrafficLight, agentPriority: number): boolean {
+  if (light === 'green') return true;
+  if (light === 'amber') return agentPriority === 0; // P0 only
+  return false; // RED — block all
+}
+```
+
+### Pattern 2: Cooperative Token Pool (CMARP)
+
+A shared JSON file (`~/.squad/rate-pool.json`) distributes API quota:
+
+```json
+{
+  "totalLimit": 5000,
+  "resetAt": "2026-03-22T20:00:00Z",
+  "allocations": {
+    "picard": { "priority": 0, "allocated": 2000, "used": 450, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "data": { "priority": 1, "allocated": 1750, "used": 200, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "ralph": { "priority": 2, "allocated": 1250, "used": 100, "leaseExpiry": "2026-03-22T19:55:00Z" }
+  }
+}
+```
+
+**Rules:**
+- P0 agents (Lead) get 40% of quota
+- P1 agents (specialists) get 35%
+- P2 agents (Ralph, Scribe) get 25%
+- Stale leases (>5 minutes without heartbeat) are auto-recovered
+- Each agent checks their remaining allocation before making API calls
+
+```typescript
+interface RatePoolAllocation {
+  priority: number;
+  allocated: number;
+  used: number;
+  leaseExpiry: string;
+}
+
+interface RatePool {
+  totalLimit: number;
+  resetAt: string;
+  allocations: Record<string, RatePoolAllocation>;
+}
+
+function canUseQuota(pool: RatePool, agentName: string): boolean {
+  const alloc = pool.allocations[agentName];
+  if (!alloc) return true; // Unknown agent — allow (graceful)
+  
+  // Reclaim stale leases from crashed agents
+  const now = new Date();
+  for (const [name, a] of Object.entries(pool.allocations)) {
+    if (new Date(a.leaseExpiry) < now && name !== agentName) {
+      a.allocated = 0; // Reclaim
+    }
+  }
+  
+  return alloc.used < alloc.allocated;
+}
+```
+
+### Pattern 3: Predictive Circuit Breaker (PCB)
+
+Opens the circuit BEFORE getting a 429 by predicting when quota will run out:
+
+```typescript
+interface RateSample {
+  timestamp: number;  // Date.now()
+  remaining: number;  // from X-RateLimit-Remaining header
+}
+
+class PredictiveCircuitBreaker {
+  private samples: RateSample[] = [];
+  private readonly maxSamples = 10;
+  private readonly warningThresholdSeconds = 120;
+
+  addSample(remaining: number): void {
+    this.samples.push({ timestamp: Date.now(), remaining });
+    if (this.samples.length > this.maxSamples) {
+      this.samples.shift();
+    }
+  }
+
+  /** Predict seconds until quota exhaustion using linear regression */
+  predictExhaustion(): number | null {
+    if (this.samples.length < 3) return null;
+
+    const n = this.samples.length;
+    const first = this.samples[0];
+    const last = this.samples[n - 1];
+    
+    const elapsedMs = last.timestamp - first.timestamp;
+    if (elapsedMs === 0) return null;
+    
+    const consumedPerMs = (first.remaining - last.remaining) / elapsedMs;
+    if (consumedPerMs <= 0) return null; // Not consuming — safe
+    
+    const msUntilExhausted = last.remaining / consumedPerMs;
+    return msUntilExhausted / 1000;
+  }
+
+  shouldOpen(): boolean {
+    const eta = this.predictExhaustion();
+    if (eta === null) return false;
+    return eta < this.warningThresholdSeconds;
+  }
+}
+```
+
+### Pattern 4: Priority Retry Windows (PWJG)
+
+Non-overlapping jitter windows prevent thundering herd:
+
+| Priority | Retry Window | Description |
+|----------|-------------|-------------|
+| P0 (Lead) | 500ms–5s | Recovers first |
+| P1 (Specialists) | 2s–30s | Moderate delay |
+| P2 (Ralph/Scribe) | 5s–60s | Most patient |
+
+```typescript
+function getRetryDelay(priority: number, attempt: number): number {
+  const windows: Record<number, [number, number]> = {
+    0: [500, 5000],     // P0: 500ms–5s
+    1: [2000, 30000],   // P1: 2s–30s
+    2: [5000, 60000],   // P2: 5s–60s
+  };
+  
+  const [min, max] = windows[priority] ?? windows[2];
+  const base = Math.min(min * Math.pow(2, attempt), max);
+  const jitter = Math.random() * base * 0.5;
+  return base + jitter;
+}
+```
+
+### Pattern 5: Resource Epoch Tracker (RET)
+
+Heartbeat-based lease system for multi-machine deployments:
+
+```typescript
+interface ResourceLease {
+  agent: string;
+  machine: string;
+  leaseStart: string;
+  leaseExpiry: string;  // Typically 5 minutes from now
+  allocated: number;
+}
+
+// Each agent renews its lease every 2 minutes
+// If lease expires (agent crashed), allocation is reclaimed
+```
+
+### Pattern 6: Cascade Dependency Detector (CDD)
+
+Track downstream failures and apply backpressure:
+
+```
+Agent A (rate limited) → Agent B (waiting for A) → Agent C (waiting for B)
+                         ↑ Backpressure signal: "don't start new work"
+```
+
+When a dependency is rate-limited, upstream agents should pause new work rather than queuing requests that will fail.
+
+## Kubernetes Integration
+
+On K8s, cooperative rate limiting can use KEDA to scale pods based on API quota:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+spec:
+  scaleTargetRef:
+    name: ralph-deployment
+  triggers:
+  - type: external
+    metadata:
+      scalerAddress: keda-copilot-scaler:6000
+      # Scaler returns 0 when rate limited → pods scale to zero
+```
+
+See [keda-copilot-scaler](https://github.com/tamirdresher/keda-copilot-scaler) for a complete implementation.
+
+## Quick Start
+
+1. **Minimum viable:** Adopt Pattern 1 (Traffic Light) — read `X-RateLimit-Remaining` from API responses
+2. **Multi-machine:** Add Pattern 2 (Cooperative Pool) — shared `rate-pool.json`
+3. **Production:** Add Pattern 3 (Predictive CB) — prevent 429s entirely
+4. **Kubernetes:** Add KEDA scaler for automatic pod scaling
+
+## References
+
+- [Circuit Breaker Template](ralph-circuit-breaker.md) — Foundation patterns
+- [Squad on AKS](https://github.com/tamirdresher/squad-on-aks) — Production K8s deployment
+- [KEDA Copilot Scaler](https://github.com/tamirdresher/keda-copilot-scaler) — Custom KEDA external scaler

package/templates/issue-lifecycle.md

@@ -0,0 +1,412 @@
+# Issue Lifecycle — Repo Connection & PR Flow
+
+Reference for connecting Squad to a repository and managing the issue→branch→PR→merge lifecycle.
+
+## Repo Connection Format
+
+When connecting Squad to an issue tracker, store the connection in `.squad/team.md`:
+
+```markdown
+## Issue Source
+
+**Repository:** {owner}/{repo}  
+**Connected:** {date}  
+**Platform:** {GitHub | Azure DevOps | Planner}  
+**Filters:**
+- Labels: `{label-filter}`
+- Project: `{project-name}` (ADO/Planner only)
+- Plan: `{plan-id}` (Planner only)
+```
+
+**Detection triggers:**
+- User says "connect to {repo}"
+- User says "monitor {repo} for issues"
+- Ralph is activated without an issue source
+
+## Platform-Specific Issue States
+
+Each platform tracks issue lifecycle differently. Squad normalizes these into a common board state.
+
+### GitHub
+
+| GitHub State | GitHub API Fields | Squad Board State |
+|--------------|-------------------|-------------------|
+| Open, no assignee | `state: open`, `assignee: null` | `untriaged` |
+| Open, assigned, no branch | `state: open`, `assignee: @user`, no linked PR | `assigned` |
+| Open, branch exists | `state: open`, linked branch exists | `inProgress` |
+| Open, PR opened | `state: open`, PR exists, `reviewDecision: null` | `needsReview` |
+| Open, PR approved | `state: open`, PR `reviewDecision: APPROVED` | `readyToMerge` |
+| Open, changes requested | `state: open`, PR `reviewDecision: CHANGES_REQUESTED` | `changesRequested` |
+| Open, CI failure | `state: open`, PR `statusCheckRollup: FAILURE` | `ciFailure` |
+| Closed | `state: closed` | `done` |
+
+**Issue labels used by Squad:**
+- `squad` — Issue is in Squad backlog
+- `squad:{member}` — Assigned to specific agent
+- `squad:untriaged` — Needs triage
+- `go:needs-research` — Needs investigation before implementation
+- `priority:p{N}` — Priority level (0=critical, 1=high, 2=medium, 3=low)
+- `next-up` — Queued for next agent pickup
+
+**Branch naming convention:**
+```
+squad/{issue-number}-{kebab-case-slug}
+```
+Example: `squad/42-fix-login-validation`
+
+### Azure DevOps
+
+| ADO State | Squad Board State |
+|-----------|-------------------|
+| New | `untriaged` |
+| Active, no branch | `assigned` |
+| Active, branch exists | `inProgress` |
+| Active, PR opened | `needsReview` |
+| Active, PR approved | `readyToMerge` |
+| Resolved | `done` |
+| Closed | `done` |
+
+**Work item tags used by Squad:**
+- `squad` — Work item is in Squad backlog
+- `squad:{member}` — Assigned to specific agent
+
+**Branch naming convention:**
+```
+squad/{work-item-id}-{kebab-case-slug}
+```
+Example: `squad/1234-add-auth-module`
+
+### Microsoft Planner
+
+Planner does not have native Git integration. Squad uses Planner for task tracking and GitHub/ADO for code management.
+
+| Planner Status | Squad Board State |
+|----------------|-------------------|
+| Not Started | `untriaged` |
+| In Progress, no PR | `inProgress` |
+| In Progress, PR opened | `needsReview` |
+| Completed | `done` |
+
+**Planner→Git workflow:**
+1. Task created in Planner bucket
+2. Agent reads task from Planner
+3. Agent creates branch in GitHub/ADO repo
+4. Agent opens PR referencing Planner task ID in description
+5. Agent marks task as "Completed" when PR merges
+
+## Issue → Branch → PR → Merge Lifecycle
+
+### 1. Issue Assignment (Triage)
+
+**Trigger:** Ralph detects an untriaged issue or user manually assigns work.
+
+**Actions:**
+1. Read `.squad/routing.md` to determine which agent should handle the issue
+2. Apply `squad:{member}` label (GitHub) or tag (ADO)
+3. Transition issue to `assigned` state
+4. Optionally spawn agent immediately if issue is high-priority
+
+**Issue read command:**
+```bash
+# GitHub
+gh issue view {number} --json number,title,body,labels,assignees
+
+# Azure DevOps
+az boards work-item show --id {id} --output json
+```
+
+### 2. Branch Creation (Start Work)
+
+**Trigger:** Agent accepts issue assignment and begins work.
+
+**Actions:**
+1. Ensure working on latest base branch (usually `main` or `dev`)
+2. Create feature branch using Squad naming convention
+3. Transition issue to `inProgress` state
+
+**Branch creation commands:**
+
+**Standard (single-agent, no parallelism):**
+```bash
+git checkout main && git pull && git checkout -b squad/{issue-number}-{slug}
+```
+
+**Worktree (parallel multi-agent):**
+```bash
+git worktree add ../worktrees/{issue-number} -b squad/{issue-number}-{slug}
+cd ../worktrees/{issue-number}
+```
+
+> **Note:** Worktree support is in progress (#525). Current implementation uses standard checkout.
+
+### 3. Implementation & Commit
+
+**Actions:**
+1. Agent makes code changes
+2. Commits reference the issue number
+3. Pushes branch to remote
+
+**Commit message format:**
+```
+{type}({scope}): {description} (#{issue-number})
+
+{detailed explanation if needed}
+
+{breaking change notice if applicable}
+
+Closes #{issue-number}
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
+```
+
+**Commit types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `ci`
+
+**Push command:**
+```bash
+git push -u origin squad/{issue-number}-{slug}
+```
+
+### 4. PR Creation
+
+**Trigger:** Agent completes implementation and is ready for review.
+
+**Actions:**
+1. Open PR from feature branch to base branch
+2. Reference issue in PR description
+3. Apply labels if needed
+4. Transition issue to `needsReview` state
+
+**PR creation commands:**
+
+**GitHub:**
+```bash
+gh pr create --title "{title}" \
+  --body "Closes #{issue-number}\n\n{description}" \
+  --head squad/{issue-number}-{slug} \
+  --base main
+```
+
+**Azure DevOps:**
+```bash
+az repos pr create --title "{title}" \
+  --description "Closes #{work-item-id}\n\n{description}" \
+  --source-branch squad/{work-item-id}-{slug} \
+  --target-branch main
+```
+
+**PR description template:**
+```markdown
+Closes #{issue-number}
+
+## Summary
+{what changed}
+
+## Changes
+- {change 1}
+- {change 2}
+
+## Testing
+{how this was tested}
+
+{If working as a squad member:}
+Working as {member} ({role})
+
+{If needs human review:}
+⚠️ This task was flagged as "needs review" — please have a squad member review before merging.
+```
+
+### 5. PR Review & Updates
+
+**Review states:**
+- **Approved** → `readyToMerge`
+- **Changes requested** → `changesRequested`
+- **CI failure** → `ciFailure`
+
+**When changes are requested:**
+1. Agent addresses feedback
+2. Commits fixes to the same branch
+3. Pushes updates
+4. Requests re-review
+
+**Update workflow:**
+```bash
+# Make changes
+git add .
+git commit -m "fix: address review feedback"
+git push
+```
+
+**Re-request review (GitHub):**
+```bash
+gh pr ready {pr-number}
+```
+
+### 6. PR Merge
+
+**Trigger:** PR is approved and CI passes.
+
+**Merge strategies:**
+
+**GitHub (merge commit):**
+```bash
+gh pr merge {pr-number} --merge --delete-branch
+```
+
+**GitHub (squash):**
+```bash
+gh pr merge {pr-number} --squash --delete-branch
+```
+
+**Azure DevOps:**
+```bash
+az repos pr update --id {pr-id} --status completed --delete-source-branch true
+```
+
+**Post-merge actions:**
+1. Issue automatically closes (if "Closes #{number}" is in PR description)
+2. Feature branch is deleted
+3. Squad board state transitions to `done`
+4. Worktree cleanup (if worktree was used — #525)
+
+### 7. Cleanup
+
+**Standard workflow cleanup:**
+```bash
+git checkout main
+git pull
+git branch -d squad/{issue-number}-{slug}
+```
+
+**Worktree cleanup (future, #525):**
+```bash
+cd {original-cwd}
+git worktree remove ../worktrees/{issue-number}
+```
+
+## Spawn Prompt Additions for Issue Work
+
+When spawning an agent to work on an issue, include this context block:
+
+```markdown
+## ISSUE CONTEXT
+
+**Issue:** #{number} — {title}  
+**Platform:** {GitHub | Azure DevOps | Planner}  
+**Repository:** {owner}/{repo}  
+**Assigned to:** {member}
+
+**Description:**
+{issue body}
+
+**Labels/Tags:**
+{labels}
+
+**Acceptance Criteria:**
+{criteria if present in issue}
+
+**Branch:** `squad/{issue-number}-{slug}`
+
+**Your task:**
+{specific directive to the agent}
+
+**After completing work:**
+1. Commit with message referencing issue number
+2. Push branch
+3. Open PR using:
+   ```
+   gh pr create --title "{title}" --body "Closes #{number}\n\n{description}" --head squad/{issue-number}-{slug} --base {base-branch}
+   ```
+4. Report PR URL to coordinator
+```
+
+## Ralph's Role in Issue Lifecycle
+
+Ralph (the work monitor) continuously checks issue and PR state:
+
+1. **Triage:** Detects untriaged issues, assigns `squad:{member}` labels
+2. **Spawn:** Launches agents for assigned issues
+3. **Monitor:** Tracks PR state transitions (needsReview → changesRequested → readyToMerge)
+4. **Merge:** Automatically merges approved PRs
+5. **Cleanup:** Marks issues as done when PRs merge
+
+**Ralph's work-check cycle:**
+```
+Scan → Categorize → Dispatch → Watch → Report → Loop
+```
+
+See `.squad/templates/ralph-reference.md` for Ralph's full lifecycle.
+
+## PR Review Handling
+
+### Automated Approval (CI-only projects)
+
+If the project has no human reviewers configured:
+1. PR opens
+2. CI runs
+3. If CI passes, Ralph auto-merges
+4. Issue closes
+
+### Human Review Required
+
+If the project requires human approval:
+1. PR opens
+2. Human reviewer is notified (GitHub/ADO notifications)
+3. Reviewer approves or requests changes
+4. If approved + CI passes, Ralph merges
+5. If changes requested, agent addresses feedback
+
+### Squad Member Review
+
+If the issue was assigned to a squad member and they authored the PR:
+1. Another squad member reviews (conflict of interest avoidance)
+2. Original author is locked out from re-working rejected code (rejection lockout)
+3. Reviewer can approve edits or reject outright
+
+## Common Issue Lifecycle Patterns
+
+### Pattern 1: Quick Fix (Single Agent, No Review)
+```
+Issue created → Assigned to agent → Branch created → Code fixed → 
+PR opened → CI passes → Auto-merged → Issue closed
+```
+
+### Pattern 2: Feature Development (Human Review)
+```
+Issue created → Assigned to agent → Branch created → Feature implemented → 
+PR opened → Human reviews → Changes requested → Agent fixes → 
+Re-reviewed → Approved → Merged → Issue closed
+```
+
+### Pattern 3: Research-Then-Implement
+```
+Issue created → Labeled `go:needs-research` → Research agent spawned → 
+Research documented → Research PR merged → Implementation issue created → 
+Implementation agent spawned → Feature built → PR merged
+```
+
+### Pattern 4: Parallel Multi-Agent (Future, #525)
+```
+Epic issue created → Decomposed into sub-issues → Each sub-issue assigned → 
+Multiple agents work in parallel worktrees → PRs opened concurrently → 
+All PRs reviewed → All PRs merged → Epic closed
+```
+
+## Anti-Patterns
+
+- ❌ Creating branches without linking to an issue
+- ❌ Committing without issue reference in message
+- ❌ Opening PRs without "Closes #{number}" in description
+- ❌ Merging PRs before CI passes
+- ❌ Leaving feature branches undeleted after merge
+- ❌ Using `checkout -b` when parallel agents are active (causes working directory conflicts)
+- ❌ Manually transitioning issue states — let the platform and Squad automation handle it
+- ❌ Skipping the branch naming convention — breaks Ralph's tracking logic
+
+## Migration Notes
+
+**v0.8.x → v0.9.x (Worktree Support):**
+- `checkout -b` → `git worktree add` for parallel agents
+- Worktree cleanup added to post-merge flow
+- `TEAM_ROOT` passing to agents to support worktree-aware state resolution
+
+This template will be updated as worktree lifecycle support lands in #525.