cross-machine-coordination

Enables squad agents on different machines to share work via git-based task queuing

Quality

63%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.squad/skills/cross-machine-coordination/SKILL.md

Skill: Cross-Machine Coordination Pattern

Skill ID: cross-machine-coordination
Owner: Ralph (Work Monitor)
Squad Integration: All agents
Status: Specification (ready for implementation)

Overview

Enables squad agents running on different machines (laptop, DevBox, Azure VM) to securely share work, coordinate execution, and pass results without manual intervention.

Pattern: Git-based task queuing + GitHub Issues supplement

Usage

For Task Sources (Orchestrating Machine)

To assign work to DevBox:

# Create task file
cat > .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-voice-clone.yaml << 'EOF'
id: gpu-voice-clone-001
source_machine: laptop-machine
target_machine: devbox
priority: high
created_at: 2026-03-14T15:30:00Z
task_type: gpu_workload
payload:
  command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav"
  expected_duration_min: 15
  resources:
    gpu: true
    memory_gb: 8
status: pending
EOF

# Commit & push
git add .squad/cross-machine/tasks/
git commit -m "Cross-machine task: GPU voice cloning [squad:machine-devbox]"
git push origin main

Ralph on DevBox will:

Pull the task on next cycle (5-10 min)
Validate schema & command whitelist
Execute the GPU workload
Write result to .squad/cross-machine/results/gpu-voice-clone-001.yaml
Commit & push the result

For Task Executors (DevBox, Azure VMs)

Ralph automatically watches .squad/cross-machine/tasks/ for work targeted at this machine.

On each cycle (5-10 min):

# Pseudo-code (Ralph implementation)
1. git pull origin main
2. Load all .yaml files in .squad/cross-machine/tasks/
3. Filter for status=pending AND target_machine=HOSTNAME
4. For each task:
   a. Validate schema (must have: id, source_machine, target_machine, payload)
   b. Validate command against whitelist
   c. Execute task (with timeout)
   d. Write result to .squad/cross-machine/results/{id}.yaml
   e. Commit & push result

For Urgent/Ad-Hoc Tasks

Use GitHub Issues with squad:machine-{name} label:

# Create issue
gh issue create \
  --title "GPU: Clone voice profile from sample.wav" \
  --body "Execute voice cloning on DevBox. Input: /path/to/voice-input.wav" \
  --label "squad:machine-devbox" \
  --label "urgent"

Ralph on DevBox will:

Detect issue with squad:machine-devbox label
Parse task from issue body
Execute task
Comment with result
Close issue

File Formats

Task File (YAML)

Location: .squad/cross-machine/tasks/{timestamp}-{machine}-{task-id}.yaml

Required Fields:

id: {task-id}                      # Unique identifier (alphanumeric + dash)
source_machine: {hostname}         # Where task was created
target_machine: {hostname}         # Where task will execute
priority: high|normal|low          # Execution priority
created_at: 2026-03-14T15:30:00Z   # ISO 8601 timestamp
task_type: gpu_workload|script|... # Category
payload:
  command: "..."                   # Shell command to execute
  expected_duration_min: 15        # Timeout (minutes)
  resources:
    gpu: true|false
    memory_gb: 8
    cpu_cores: 4
status: pending|executing|completed|failed

Optional Fields:

description: "Human-readable task description"
timeout_override_min: 120          # Override default timeout
retry_count: 3                     # Retry failed tasks

Result File (YAML)

Location: .squad/cross-machine/results/{task-id}.yaml

id: {task-id}                          # Links back to task
target_machine: devbox                 # Executed on
completed_at: 2026-03-14T15:45:00Z    # When it finished
status: completed|failed|timeout       # Outcome
exit_code: 0                           # Shell exit code
stdout: "..."                          # Captured output
stderr: "..."                          # Captured errors
duration_seconds: 900                  # How long it took
artifacts:
  - path: "/path/to/artifacts/..."   # Location of results
    type: audio|text|model|...
    size_mb: 2.5

Security Model

Validation Pipeline

All tasks go through:

Schema Validation
- YAML structure matches spec
- Required fields present
- No unexpected fields (reject)
Command Whitelist
- Only approved commands allowed
- Path validation (no ../../ escapes)
- Environment variable sanitization
- No inline shell operators (&&, |, >)
Resource Limits
- Timeout enforced (default: 60 min)
- Memory cap: 16GB (adjustable)
- CPU threads: 4 (adjustable)
- Disk write: 100GB (adjustable)
Execution Isolation
- Runs as unprivileged user
- Temp directory cleaned after execution
- Network access: read-only (no outbound writes)
Audit Trail
- All executions logged to git
- Commit signed with Ralph's key
- Result stored immutably

Threat Mitigations

Threat	Mitigation
Malicious task injection	Branch protection + PR review before merge
Credential leakage	Pre-commit secret scan + environment scrubbing
Resource exhaustion	Timeout + memory limits
Code injection	Command whitelist + no shell evaluation
Result tampering	Git commit history is immutable

Configuration

Ralph reads config from .squad/config.json:

{
  "cross_machine": {
    "enabled": true,
    "poll_interval_seconds": 300,
    "this_machine": "devbox",
    "max_concurrent_tasks": 2,
    "task_timeout_minutes": 60,
    "command_whitelist": [
      "python scripts/voice-clone.py",
      "python scripts/data-process.py",
      "bash scripts/cleanup.sh"
    ],
    "result_ttl_days": 30
  }
}

Examples

Example 1: GPU Voice Cloning (Laptop → DevBox)

1. Laptop creates task:

# .squad/cross-machine/tasks/2026-03-14T1530Z-laptop-gpu-001.yaml
id: gpu-voice-clone-001
source_machine: laptop-machine
target_machine: devbox
priority: high
created_at: 2026-03-14T15:30:00Z
task_type: gpu_workload
payload:
  command: "python scripts/voice-clone.py --input voice.wav --output cloned.wav"
  expected_duration_min: 15
  resources:
    gpu: true
    memory_gb: 8
status: pending

2. Laptop commits & pushes:

git add .squad/cross-machine/tasks/
git commit -m "Task: GPU voice cloning [squad:machine-devbox]"
git push origin main

3. DevBox Ralph (5 min later):

[Ralph Watch Cycle]
- Pulled origin/main
- Detected: gpu-voice-clone-001 (status: pending, target: devbox)
- Validation: ✅ Schema OK, command whitelisted
- Executing: python scripts/voice-clone.py ...
- [15 minutes of processing]
- Completed: exit code 0
- Writing result...
- Committing & pushing...

4. Laptop Ralph (next cycle) sees result:

# .squad/cross-machine/results/gpu-voice-clone-001.yaml
id: gpu-voice-clone-001
target_machine: devbox
completed_at: 2026-03-14T15:45:00Z
status: completed
exit_code: 0
stdout: "Voice cloning completed. Output written to /tmp/cloned.wav"
stderr: ""
duration_seconds: 900
artifacts:
  - path: "/path/to/artifacts/voice-clone-001/output.wav"
    type: audio
    size_mb: 2.5

Example 2: Urgent Debug Request (Human → DevBox via Issue)

Create issue:

gh issue create \
  --title "DevBox: Debug voice model failure" \
  --body "Error: Model failed to load on last run. Please check /tmp/model.log and report findings." \
  --label "squad:machine-devbox" \
  --label "urgent"

DevBox Ralph detects → executes → comments:

✅ Executed on devbox at 2026-03-14 15:47:00
Command: python scripts/debug-model.py

Result:
------
Model file: /tmp/model-v2.bin (OK)
Checksum: a1b2c3d4e5f6 (matches expected)
Memory available: 12 GB (sufficient)

ERROR FOUND: Config file permission issue
  - File: ~/.config/voice/model.yaml
  - Permissions: -rw------- (owner-only)
  - Expected: -rw-r--r-- (world-readable for service)

FIX: Run: chmod 644 ~/.config/voice/model.yaml

Error Handling

Task Execution Failures

If a task fails (exit code != 0):

Result written with status: failed + exit code
stderr captured in result
Committed to git for audit
Source machine can retry by re-pushing task with status: pending

Stalled Tasks

If a task doesn't complete within timeout:

Process killed
Result written with status: timeout
stderr: "Execution exceeded X minutes"
Source can investigate or retry

Network Failures

If git push/pull fails:

Ralph retries on next cycle
Tasks queue locally until connectivity restored
No tasks lost (stored in local repo)

Monitoring & Debugging

Check Task Queue

ls -la .squad/cross-machine/tasks/
cat .squad/cross-machine/tasks/*.yaml | grep -E "^(id|status|target_machine):"

Check Results

ls -la .squad/cross-machine/results/
cat .squad/cross-machine/results/{task-id}.yaml

View Execution History

git log --oneline .squad/cross-machine/ | head -20

Monitor Ralph Cycles

tail -f .squad/log/ralph-watch.log | grep "cross-machine"

Integration with Ralph Watch

Ralph automatically includes this pattern in its watch loop:

Ralph Watch Cycle (every 5-10 min):
1. Fetch GitHub issues with squad:machine-* labels
2. Poll .squad/cross-machine/tasks/
3. For each matching task:
   - Validate
   - Execute
   - Write result
   - Commit & push
4. Update status in issue (if applicable)
5. Sleep until next cycle

No manual Ralph configuration needed — just create task files or issues with the right labels.

Migration from Manual Handoff

Before (today):

Laptop → user manually copies file to Teams chat
user pastes into target terminal
user copies output back
user pastes result manually

After (with this pattern):

Laptop Ralph writes task file → git push
DevBox Ralph auto-executes → git push result
Laptop Ralph auto-reads result
0 human intervention needed

Future Enhancements

Potential expansions (Phase 2+):

Task Priorities: Execution order based on priority field
Serial Pipelines: Machine A → B → C task chains
GPU Availability Polling: Query DevBox before submitting work
Cost Tracking: Log resource usage per task
Notification Webhooks: Alert on task completion
Web Dashboard: Real-time task status visualization

Questions?

Refer to research report: research/active/cross-machine-agents/README.md

Contact: Seven (Research & Docs) or Ralph (Work Monitor)

Repository: bradygaster/squad
Path: .squad/skills/cross-machine-coordination/SKILL.md
Commit: e23dd92

Last updated: 1 day ago
First committed: 3 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.