@bradygaster/squad-sdk 0.8.25 → 0.9.1

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.

package/templates/keda-scaler.md

@@ -0,0 +1,164 @@
+# KEDA External Scaler for GitHub Issue-Driven Agent Autoscaling
+
+> Scale agent pods to zero when idle, up when work arrives — driven by GitHub Issues.
+
+## Overview
+
+When running Squad on Kubernetes, agent pods sit idle when no work exists. [KEDA](https://keda.sh) (Kubernetes Event-Driven Autoscaler) solves this for queue-based workloads, but GitHub Issues isn't a native KEDA trigger.
+
+The `keda-copilot-scaler` is a KEDA External Scaler (gRPC) that bridges this gap:
+1. Polls GitHub API for issues matching specific labels (e.g., `squad:copilot`)
+2. Reports queue depth as a KEDA metric
+3. Handles rate limits gracefully (Retry-After, exponential backoff)
+4. Supports composite scaling decisions
+
+## Quick Start
+
+### Prerequisites
+- Kubernetes cluster with KEDA v2.x installed
+- GitHub personal access token (PAT) with `repo` scope
+- Helm 3.x
+
+### 1. Install the Scaler
+
+```bash
+helm install keda-copilot-scaler oci://ghcr.io/tamirdresher/keda-copilot-scaler \
+  --namespace squad-scaler --create-namespace \
+  --set github.owner=YOUR_ORG \
+  --set github.repo=YOUR_REPO \
+  --set github.token=YOUR_TOKEN
+```
+
+Or with Kustomize:
+```bash
+kubectl apply -k https://github.com/tamirdresher/keda-copilot-scaler/deploy/kustomize
+```
+
+### 2. Create a ScaledObject
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  name: picard-scaler
+  namespace: squad
+spec:
+  scaleTargetRef:
+    name: picard-deployment
+  minReplicaCount: 0          # Scale to zero when idle
+  maxReplicaCount: 3
+  pollingInterval: 30         # Check every 30 seconds
+  cooldownPeriod: 300         # Wait 5 minutes before scaling down
+  triggers:
+  - type: external
+    metadata:
+      scalerAddress: keda-copilot-scaler.squad-scaler.svc.cluster.local:6000
+      owner: your-org
+      repo: your-repo
+      labels: squad:copilot    # Only count issues with this label
+      threshold: "1"           # Scale up when >= 1 issue exists
+```
+
+### 3. Verify
+
+```bash
+# Check the scaler is running
+kubectl get pods -n squad-scaler
+
+# Check ScaledObject status
+kubectl get scaledobject picard-scaler -n squad
+
+# Watch scaling events
+kubectl get events -n squad --watch
+```
+
+## Scaling Behavior
+
+| Open Issues | Target Replicas | Behavior |
+|------------|----------------|----------|
+| 0 | 0 | Scale to zero — save resources |
+| 1–3 | 1 | Single agent handles work |
+| 4–10 | 2 | Scale up for parallel processing |
+| 10+ | 3 (max) | Maximum parallelism |
+
+The threshold and max replicas are configurable per ScaledObject.
+
+## Rate Limit Awareness
+
+The scaler tracks GitHub API rate limits:
+- Reads `X-RateLimit-Remaining` from API responses
+- Backs off when quota is low (< 100 remaining)
+- Reports rate limit metrics as secondary KEDA triggers
+- Never exhausts API quota from polling
+
+## Integration with Squad
+
+### Machine Capabilities (#514)
+
+Combine with machine capability labels for intelligent scheduling:
+
+```yaml
+# Only scale pods on GPU-capable nodes
+spec:
+  template:
+    spec:
+      nodeSelector:
+        node.squad.dev/gpu: "true"
+  triggers:
+  - type: external
+    metadata:
+      labels: squad:copilot,needs:gpu
+```
+
+### Cooperative Rate Limiting (#515)
+
+The scaler exposes rate limit metrics that feed into the cooperative rate limiting system:
+- Current `X-RateLimit-Remaining` value
+- Predicted time to exhaustion (from predictive circuit breaker)
+- Can return 0 target replicas when rate limited → pods scale to zero
+
+## Architecture
+
+```
+GitHub API                    KEDA                    Kubernetes
+┌──────────┐              ┌──────────┐           ┌──────────────┐
+│  Issues   │◄── poll ──►│  Scaler   │──metrics─►│ HPA / KEDA   │
+│  (REST)   │             │  (gRPC)   │           │ Controller   │
+└──────────┘              └──────────┘           └──────┬───────┘
+                                                        │
+                                                  scale up/down
+                                                        │
+                                                 ┌──────▼───────┐
+                                                 │ Agent Pods    │
+                                                 │ (0–N replicas)│
+                                                 └──────────────┘
+```
+
+## Configuration Reference
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `github.owner` | — | Repository owner |
+| `github.repo` | — | Repository name |
+| `github.token` | — | GitHub PAT with `repo` scope |
+| `github.labels` | `squad:copilot` | Comma-separated label filter |
+| `scaler.port` | `6000` | gRPC server port |
+| `scaler.pollInterval` | `30s` | GitHub API polling interval |
+| `scaler.rateLimitThreshold` | `100` | Stop polling below this remaining |
+
+## Source & Contributing
+
+- **Repository:** [tamirdresher/keda-copilot-scaler](https://github.com/tamirdresher/keda-copilot-scaler)
+- **License:** MIT
+- **Language:** Go
+- **Tests:** 51 passing (unit + integration)
+- **CI:** GitHub Actions
+
+The scaler is maintained as a standalone project. PRs and issues welcome.
+
+## References
+
+- [KEDA External Scalers](https://keda.sh/docs/latest/concepts/external-scalers/) — KEDA documentation
+- [Squad on AKS](https://github.com/tamirdresher/squad-on-aks) — Full Kubernetes deployment example
+- [Machine Capabilities](machine-capabilities.md) — Capability-based routing (#514)
+- [Cooperative Rate Limiting](cooperative-rate-limiting.md) — Multi-agent rate management (#515)

package/templates/machine-capabilities.md

@@ -0,0 +1,75 @@
+# Machine Capability Discovery & Label-Based Routing
+
+> Enable Ralph to skip issues requiring capabilities the current machine lacks.
+
+## Overview
+
+When running Squad across multiple machines (laptops, DevBoxes, GPU servers, Kubernetes nodes), each machine has different tooling. The capability system lets you declare what each machine can do, and Ralph automatically routes work accordingly.
+
+## Setup
+
+### 1. Create a Capabilities Manifest
+
+Create `~/.squad/machine-capabilities.json` (user-wide) or `.squad/machine-capabilities.json` (project-local):
+
+```json
+{
+  "machine": "MY-LAPTOP",
+  "capabilities": ["browser", "personal-gh", "onedrive"],
+  "missing": ["gpu", "docker", "azure-speech"],
+  "lastUpdated": "2026-03-22T00:00:00Z"
+}
+```
+
+### 2. Label Issues with Requirements
+
+Add `needs:*` labels to issues that require specific capabilities:
+
+| Label | Meaning |
+|-------|---------|
+| `needs:browser` | Requires Playwright / browser automation |
+| `needs:gpu` | Requires NVIDIA GPU |
+| `needs:personal-gh` | Requires personal GitHub account |
+| `needs:emu-gh` | Requires Enterprise Managed User account |
+| `needs:azure-cli` | Requires authenticated Azure CLI |
+| `needs:docker` | Requires Docker daemon |
+| `needs:onedrive` | Requires OneDrive sync |
+| `needs:teams-mcp` | Requires Teams MCP tools |
+
+Custom capabilities are supported — any `needs:X` label works if `X` is in the machine's `capabilities` array.
+
+### 3. Run Ralph
+
+```bash
+squad watch --interval 5
+```
+
+Ralph will log skipped issues:
+```
+⏭️ Skipping #42 "Train ML model" — missing: gpu
+✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule)
+```
+
+## How It Works
+
+1. Ralph loads `machine-capabilities.json` at startup
+2. For each open issue, Ralph extracts `needs:*` labels
+3. If any required capability is missing, the issue is skipped
+4. Issues without `needs:*` labels are always processed (opt-in system)
+
+## Kubernetes Integration
+
+On Kubernetes, machine capabilities map to node labels:
+
+```yaml
+# Node labels (set by capability DaemonSet or manually)
+node.squad.dev/gpu: "true"
+node.squad.dev/browser: "true"
+
+# Pod spec uses nodeSelector
+spec:
+  nodeSelector:
+    node.squad.dev/gpu: "true"
+```
+
+A DaemonSet can run capability discovery on each node and maintain labels automatically. See the [squad-on-aks](https://github.com/tamirdresher/squad-on-aks) project for a complete Kubernetes deployment example.