@bradygaster/squad-sdk 0.9.0 → 0.9.1

package/templates/keda-scaler.md

@@ -1,164 +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)
+# 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

@@ -1,75 +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"
-```
-
+# 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.

package/templates/mcp-config.md

@@ -1,90 +1,90 @@
-# MCP Integration — Configuration and Samples
-
-MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
-
-> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
-
-## Config File Locations
-
-Users configure MCP servers at these locations (checked in priority order):
-1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
-2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
-3. **User-level:** `~/.copilot/mcp-config.json` (personal)
-4. **CLI override:** `--additional-mcp-config` flag (session-specific)
-
-## Sample Config — Trello
-
-```json
-{
-  "mcpServers": {
-    "trello": {
-      "command": "npx",
-      "args": ["-y", "@trello/mcp-server"],
-      "env": {
-        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
-        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — GitHub
-
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-github"],
-      "env": {
-        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — Azure
-
-```json
-{
-  "mcpServers": {
-    "azure": {
-      "command": "npx",
-      "args": ["-y", "@azure/mcp-server"],
-      "env": {
-        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
-        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
-        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
-        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
-      }
-    }
-  }
-}
-```
-
-## Sample Config — Aspire
-
-```json
-{
-  "mcpServers": {
-    "aspire": {
-      "command": "npx",
-      "args": ["-y", "@aspire/mcp-server"],
-      "env": {
-        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
-      }
-    }
-  }
-}
-```
-
-## Authentication Notes
-
-- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
-- **Trello requires API key + token** from https://trello.com/power-ups/admin
-- **Azure requires service principal credentials** — see Azure docs for setup
-- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
-
-Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.
+# MCP Integration — Configuration and Samples
+
+MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
+
+> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
+
+## Config File Locations
+
+Users configure MCP servers at these locations (checked in priority order):
+1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal)
+4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+
+## Sample Config — Trello
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "npx",
+      "args": ["-y", "@trello/mcp-server"],
+      "env": {
+        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
+        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Azure
+
+```json
+{
+  "mcpServers": {
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp-server"],
+      "env": {
+        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
+        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
+        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
+        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Aspire
+
+```json
+{
+  "mcpServers": {
+    "aspire": {
+      "command": "npx",
+      "args": ["-y", "@aspire/mcp-server"],
+      "env": {
+        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
+      }
+    }
+  }
+}
+```
+
+## Authentication Notes
+
+- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
+- **Trello requires API key + token** from https://trello.com/power-ups/admin
+- **Azure requires service principal credentials** — see Azure docs for setup
+- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
+
+Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.