{"id":"f3d7bbbd-c215-4515-80d7-4d059d363e62","slug":"cross-machine-coordination","kind":"skill","name":"cross-machine-coordination","summary":"Enables squad agents on different machines to share work via git-based task queuing","owner":"github","repoUrl":"https://github.com/github/gh-aw/tree/HEAD/.squad/templates/skills/cross-machine-coordination","license":"MIT","licenseTier":"permissive","trust":"official","stars":5390,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T05:39:50.119Z","logoUrl":"https://avatars.githubusercontent.com/u/9919?v=4","linkOnly":false,"collection":{"name":"gh-aw","repo":"github/gh-aw"},"skillPath":".squad/templates/skills/cross-machine-coordination","categories":["developer-tools","productivity"],"tags":["gh-extension","actions","cai","ci","claude-code","codex","copilot","github-actions"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T05:39:50.118Z","sample":false,"url":"https://conduits.dev/tools/cross-machine-coordination","language":"Go","transports":[],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Skill: Cross-Machine Coordination Pattern\n\n**Skill ID:** `cross-machine-coordination`  \n**Owner:** Ralph (Work Monitor)  \n**Squad Integration:** All agents  \n**Status:** Specification (ready for implementation)  \n\n---\n\n## Overview\n\nEnables squad agents running on different machines (laptop, DevBox, Azure VM) to securely share work, coordinate execution, and pass results without manual intervention.\n\n**Pattern:** Git-based task queuing + GitHub Issues supplement\n\n---\n\n## Usage\n\n### For Task Sources (Orchestrating Machine)\n\n**To assign work to DevBox:**\n\n```bash\n# Create task file\ncat > .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-voice-clone.yaml << 'EOF'\nid: gpu-voice-clone-001\nsource_machine: laptop-machine\ntarget_machine: devbox\npriority: high\ncreated_at: 2026-03-14T15:30:00Z\ntask_type: gpu_workload\npayload:\n  command: \"python scripts/voice-clone.py --input voice.wav --output cloned.wav\"\n  expected_duration_min: 15\n  resources:\n    gpu: true\n    memory_gb: 8\nstatus: pending\nEOF\n\n# Commit & push\ngit add .squad/cross-machine/tasks/\ngit commit -m \"Cross-machine task: GPU voice cloning [squad:machine-devbox]\"\ngit push origin main\n```\n\nRalph on DevBox will:\n1. Pull the task on next cycle (5-10 min)\n2. Validate schema & command whitelist\n3. Execute the GPU workload\n4. Write result to `.squad/cross-machine/results/gpu-voice-clone-001.yaml`\n5. Commit & push the result\n\n---\n\n### For Task Executors (DevBox, Azure VMs)\n\nRalph automatically watches `.squad/cross-machine/tasks/` for work targeted at this machine.\n\n**On each cycle (5-10 min):**\n\n```python\n# Pseudo-code (Ralph implementation)\n1. git pull origin main\n2. Load all .yaml files in .squad/cross-machine/tasks/\n3. Filter for status=pending AND target_machine=HOSTNAME\n4. For each task:\n   a. Validate schema (must have: id, source_machine, target_machine, payload)\n   b. Validate command against whitelist\n   c. Execute task (with timeout)\n   d. Write result to .squad/cross-machine/results/{id}.yaml\n   e. Commit & push result\n```\n\n---\n\n### For Urgent/Ad-Hoc Tasks\n\n**Use GitHub Issues with `squad:machine-{name}` label:**\n\n```bash\n# Create issue\ngh issue create \\\n  --title \"GPU: Clone voice profile from sample.wav\" \\\n  --body \"Execute voice cloning on DevBox. Input: /path/to/voice-input.wav\" \\\n  --label \"squad:machine-devbox\" \\\n  --label \"urgent\"\n```\n\nRalph on DevBox will:\n1. Detect issue with `squad:machine-devbox` label\n2. Parse task from issue body\n3. Execute task\n4. Comment with result\n5. Close issue\n\n---\n\n## File Formats\n\n### Task File (YAML)\n\n**Location:** `.squad/cross-machine/tasks/{timestamp}-{machine}-{task-id}.yaml`\n\n**Required Fields:**\n```yaml\nid: {task-id}                      # Unique identifier (alphanumeric + dash)\nsource_machine: {hostname}         # Where task was created\ntarget_machine: {hostname}         # Where task will execute\npriority: high|normal|low          # Execution priority\ncreated_at: 2026-03-14T15:30:00Z   # ISO 8601 timestamp\ntask_type: gpu_workload|script|... # Category\npayload:\n  command: \"...\"                   # Shell command to execute\n  expected_duration_min: 15        # Timeout (minutes)\n  resources:\n    gpu: true|false\n    memory_gb: 8\n    cpu_cores: 4\nstatus: pending|executing|completed|failed\n```\n\n**Optional Fields:**\n```yaml\ndescription: \"Human-readable task description\"\ntimeout_override_min: 120          # Override default timeout\nretry_count: 3                     # Retry failed tasks\n```\n\n### Result File (YAML)\n\n**Location:** `.squad/cross-machine/results/{task-id}.yaml`\n\n```yaml\nid: {task-id}                          # Links back to task\ntarget_machine: devbox                 # Executed on\ncompleted_at: 2026-03-14T15:45:00Z    # When it finished\nstatus: completed|failed|timeout       # Outcome\nexit_code: 0                           # Shell exit code\nstdout: \"...\"                          # Captured output\nstderr: \"...\"                          # Captured errors\nduration_seconds: 900                  # How long it took\nartifacts:\n  - path: \"/path/to/artifacts/...\"   # Location of results\n    type: audio|text|model|...\n    size_mb: 2.5\n```\n\n---\n\n## Security Model\n\n### Validation Pipeline\n\nAll tasks go through:\n\n1. **Schema Validation**\n   - YAML structure matches spec\n   - Required fields present\n   - No unexpected fields (reject)\n\n2. **Command Whitelist**\n   - Only approved commands allowed\n   - Path validation (no `../../` escapes)\n   - Environment variable sanitization\n   - No inline shell operators (`&&`, `|`, `>`)\n\n3. **Resource Limits**\n   - Timeout enforced (default: 60 min)\n   - Memory cap: 16GB (adjustable)\n   - CPU threads: 4 (adjustable)\n   - Disk write: 100GB (adjustable)\n\n4. **Execution Isolation**\n   - Runs as unprivileged user\n   - Temp directory cleaned after execution\n   - Network access: read-only (no outbound writes)\n\n5. **Audit Trail**\n   - All executions logged to git\n   - Commit signed with Ralph's key\n   - Result stored immutably\n\n### Threat Mitigations\n\n| Threat | Mitigation |\n|--------|-----------|\n| **Malicious task injection** | Branch protection + PR review before merge |\n| **Credential leakage** | Pre-commit secret scan + environment scrubbing |\n| **Resource exhaustion** | Timeout + memory limits |\n| **Code injection** | Command whitelist + no shell evaluation |\n| **Result tampering** | Git commit history is immutable |\n\n---\n\n## Configuration\n\nRalph reads config from `.squad/config.json`:\n\n```json\n{\n  \"cross_machine\": {\n    \"enabled\": true,\n    \"poll_interval_seconds\": 300,\n    \"this_machine\": \"devbox\",\n    \"max_concurrent_tasks\": 2,\n    \"task_timeout_minutes\": 60,\n    \"command_whitelist\": [\n      \"python scripts/voice-clone.py\",\n      \"python scripts/data-process.py\",\n      \"bash scripts/cleanup.sh\"\n    ],\n    \"result_ttl_days\": 30\n  }\n}\n```\n\n---\n\n## Examples\n\n### Example 1: GPU Voice Cloning (Laptop → DevBox)\n\n**1. Laptop creates task:**\n\n```yaml\n# .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-001.yaml\nid: gpu-voice-clone-001\nsource_machine: laptop-machine\ntarget_machine: devbox\npriority: high\ncreated_at: 2026-03-14T15:30:00Z\ntask_type: gpu_workload\npayload:\n  command: \"python scripts/voice-clone.py --input voice.wav --output cloned.wav\"\n  expected_duration_min: 15\n  resources:\n    gpu: true\n    memory_gb: 8\nstatus: pending\n```\n\n**2. Laptop commits & pushes:**\n\n```bash\ngit add .squad/cross-machine/tasks/\ngit commit -m \"Task: GPU voice cloning [squad:machine-devbox]\"\ngit push origin main\n```\n\n**3. DevBox Ralph (5 min later):**\n\n```\n[Ralph Watch Cycle]\n- Pulled origin/main\n- Detected: gpu-voice-clone-001 (status: pending, target: devbox)\n- Validation: ✅ Schema OK, command whitelisted\n- Executing: python scripts/voice-clone.py ...\n- [15 minutes of processing]\n- Completed: exit code 0\n- Writing result...\n- Committing & pushing...\n```\n\n**4. Laptop Ralph (next cycle) sees result:**\n\n```yaml\n# .squad/cross-machine/results/gpu-voice-clone-001.yaml\nid: gpu-voice-clone-001\ntarget_machine: devbox\ncompleted_at: 2026-03-14T15:45:00Z\nstatus: completed\nexit_code: 0\nstdout: \"Voice cloning completed. Output written to /tmp/cloned.wav\"\nstderr: \"\"\nduration_seconds: 900\nartifacts:\n  - path: \"/path/to/artifacts/voice-clone-001/output.wav\"\n    type: audio\n    size_mb: 2.5\n```\n\n---\n\n### Example 2: Urgent Debug Request (Human → DevBox via Issue)\n\n**Create issue:**\n\n```bash\ngh issue create \\\n  --title \"DevBox: Debug voice model failure\" \\\n  --body \"Error: Model failed to load on last run. Please check /tmp/model.log and report findings.\" \\\n  --label \"squad:machine-devbox\" \\\n  --label \"urgent\"\n```\n\n**DevBox Ralph detects → executes → comments:**\n\n```\n✅ Executed on devbox at 2026-03-14 15:47:00\nCommand: python scripts/debug-model.py\n\nResult:\n------\nModel file: /tmp/model-v2.bin (OK)\nChecksum: a1b2c3d4e5f6 (matches expected)\nMemory available: 12 GB (sufficient)\n\nERROR FOUND: Config file permission issue\n  - File: ~/.config/voice/model.yaml\n  - Permissions: -rw------- (owner-only)\n  - Expected: -rw-r--r-- (world-readable for service)\n\nFIX: Run: chmod 644 ~/.config/voice/model.yaml\n```\n\n---\n\n## Error Handling\n\n### Task Execution Failures\n\nIf a task fails (exit code != 0):\n\n1. Result written with `status: failed` + exit code\n2. stderr captured in result\n3. Committed to git for audit\n4. Source machine can retry by re-pushing task with `status: pending`\n\n### Stalled Tasks\n\nIf a task doesn't complete within timeout:\n\n1. Process killed\n2. Result written with `status: timeout`\n3. stderr: \"Execution exceeded X minutes\"\n4. Source can investigate or retry\n\n### Network Failures\n\nIf git push/pull fails:\n\n- Ralph retries on next cycle\n- Tasks queue locally until connectivity restored\n- No tasks lost (stored in local repo)\n\n---\n\n## Monitoring & Debugging\n\n### Check Task Queue\n\n```bash\nls -la .squad/cross-machine/tasks/\ncat .squad/cross-machine/tasks/*.yaml | grep -E \"^(id|status|target_machine):\"\n```\n\n### Check Results\n\n```bash\nls -la .squad/cross-machine/results/\ncat .squad/cross-machine/results/{task-id}.yaml\n```\n\n### View Execution History\n\n```bash\ngit log --oneline .squad/cross-machine/ | head -20\n```\n\n### Monitor Ralph Cycles\n\n```bash\ntail -f .squad/log/ralph-watch.log | grep \"cross-machine\"\n```\n\n---\n\n## Integration with Ralph Watch\n\nRalph automatically includes this pattern in its watch loop:\n\n```\nRalph Watch Cycle (every 5-10 min):\n1. Fetch GitHub issues with squad:machine-* labels\n2. Poll .squad/cross-machine/tasks/\n3. For each matching task:\n   - Validate\n   - Execute\n   - Write result\n   - Commit & push\n4. Update status in issue (if applicable)\n5. Sleep until next cycle\n```\n\nNo manual Ralph configuration needed — just create task files or issues with the right labels.\n\n---\n\n## Migration from Manual Handoff\n\n**Before (today):**\n- Laptop → user manually copies file to Teams chat\n- user pastes into target terminal\n- user copies output back\n- user pastes result manually\n\n**After (with this pattern):**\n- Laptop Ralph writes task file → git push\n- DevBox Ralph auto-executes → git push result\n- Laptop Ralph auto-reads result\n- 0 human intervention needed\n\n---\n\n## Future Enhancements\n\nPotential expansions (Phase 2+):\n\n1. **Task Priorities:** Execution order based on priority field\n2. **Serial Pipelines:** Machine A → B → C task chains\n3. **GPU Availability Polling:** Query DevBox before submitting work\n4. **Cost Tracking:** Log resource usage per task\n5. **Notification Webhooks:** Alert on task completion\n6. **Web Dashboard:** Real-time task status visualization\n\n---\n\n## Questions?\n\nRefer to research report: `research/active/cross-machine-agents/README.md`\n\nContact: Seven (Research & Docs) or Ralph (Work Monitor)"}