machine-capabilities.md (2476B)
1 # Machine Capability Discovery & Label-Based Routing 2 3 > Enable Ralph to skip issues requiring capabilities the current machine lacks. 4 5 ## Overview 6 7 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. 8 9 ## Setup 10 11 ### 1. Create a Capabilities Manifest 12 13 Create `~/.squad/machine-capabilities.json` (user-wide) or `.squad/machine-capabilities.json` (project-local): 14 15 ```json 16 { 17 "machine": "MY-LAPTOP", 18 "capabilities": ["browser", "personal-gh", "onedrive"], 19 "missing": ["gpu", "docker", "azure-speech"], 20 "lastUpdated": "2026-03-22T00:00:00Z" 21 } 22 ``` 23 24 ### 2. Label Issues with Requirements 25 26 Add `needs:*` labels to issues that require specific capabilities: 27 28 | Label | Meaning | 29 |-------|---------| 30 | `needs:browser` | Requires Playwright / browser automation | 31 | `needs:gpu` | Requires NVIDIA GPU | 32 | `needs:personal-gh` | Requires personal GitHub account | 33 | `needs:emu-gh` | Requires Enterprise Managed User account | 34 | `needs:azure-cli` | Requires authenticated Azure CLI | 35 | `needs:docker` | Requires Docker daemon | 36 | `needs:onedrive` | Requires OneDrive sync | 37 | `needs:teams-mcp` | Requires Teams MCP tools | 38 39 Custom capabilities are supported — any `needs:X` label works if `X` is in the machine's `capabilities` array. 40 41 ### 3. Run Ralph 42 43 ```bash 44 squad watch --interval 5 45 ``` 46 47 Ralph will log skipped issues: 48 ``` 49 ⏭️ Skipping #42 "Train ML model" — missing: gpu 50 ✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule) 51 ``` 52 53 ## How It Works 54 55 1. Ralph loads `machine-capabilities.json` at startup 56 2. For each open issue, Ralph extracts `needs:*` labels 57 3. If any required capability is missing, the issue is skipped 58 4. Issues without `needs:*` labels are always processed (opt-in system) 59 60 ## Kubernetes Integration 61 62 On Kubernetes, machine capabilities map to node labels: 63 64 ```yaml 65 # Node labels (set by capability DaemonSet or manually) 66 node.squad.dev/gpu: "true" 67 node.squad.dev/browser: "true" 68 69 # Pod spec uses nodeSelector 70 spec: 71 nodeSelector: 72 node.squad.dev/gpu: "true" 73 ``` 74 75 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.