@bradygaster/squad-cli 0.9.0 → 0.9.2-insider.5

package/templates/skills/cross-machine-coordination/SKILL.md

@@ -0,0 +1,434 @@
+# 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:**
+
+```bash
+# 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:
+1. Pull the task on next cycle (5-10 min)
+2. Validate schema & command whitelist
+3. Execute the GPU workload
+4. Write result to `.squad/cross-machine/results/gpu-voice-clone-001.yaml`
+5. 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):**
+
+```python
+# 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:**
+
+```bash
+# 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:
+1. Detect issue with `squad:machine-devbox` label
+2. Parse task from issue body
+3. Execute task
+4. Comment with result
+5. Close issue
+
+---
+
+## File Formats
+
+### Task File (YAML)
+
+**Location:** `.squad/cross-machine/tasks/{timestamp}-{machine}-{task-id}.yaml`
+
+**Required Fields:**
+```yaml
+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:**
+```yaml
+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`
+
+```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:
+
+1. **Schema Validation**
+   - YAML structure matches spec
+   - Required fields present
+   - No unexpected fields (reject)
+
+2. **Command Whitelist**
+   - Only approved commands allowed
+   - Path validation (no `../../` escapes)
+   - Environment variable sanitization
+   - No inline shell operators (`&&`, `|`, `>`)
+
+3. **Resource Limits**
+   - Timeout enforced (default: 60 min)
+   - Memory cap: 16GB (adjustable)
+   - CPU threads: 4 (adjustable)
+   - Disk write: 100GB (adjustable)
+
+4. **Execution Isolation**
+   - Runs as unprivileged user
+   - Temp directory cleaned after execution
+   - Network access: read-only (no outbound writes)
+
+5. **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`:
+
+```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:**
+
+```yaml
+# .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:**
+
+```bash
+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:**
+
+```yaml
+# .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:**
+
+```bash
+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):
+
+1. Result written with `status: failed` + exit code
+2. stderr captured in result
+3. Committed to git for audit
+4. Source machine can retry by re-pushing task with `status: pending`
+
+### Stalled Tasks
+
+If a task doesn't complete within timeout:
+
+1. Process killed
+2. Result written with `status: timeout`
+3. stderr: "Execution exceeded X minutes"
+4. 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
+
+```bash
+ls -la .squad/cross-machine/tasks/
+cat .squad/cross-machine/tasks/*.yaml | grep -E "^(id|status|target_machine):"
+```
+
+### Check Results
+
+```bash
+ls -la .squad/cross-machine/results/
+cat .squad/cross-machine/results/{task-id}.yaml
+```
+
+### View Execution History
+
+```bash
+git log --oneline .squad/cross-machine/ | head -20
+```
+
+### Monitor Ralph Cycles
+
+```bash
+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+):
+
+1. **Task Priorities:** Execution order based on priority field
+2. **Serial Pipelines:** Machine A → B → C task chains
+3. **GPU Availability Polling:** Query DevBox before submitting work
+4. **Cost Tracking:** Log resource usage per task
+5. **Notification Webhooks:** Alert on task completion
+6. **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)

package/templates/skills/error-recovery/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: "error-recovery"
+description: "Standard recovery patterns for all squad agents. When something fails, adapt — don't just report the failure."
+domain: "reliability, agent-coordination"
+confidence: "high"
+license: MIT
+---
+
+# Error Recovery Patterns
+
+Standard recovery patterns for all squad agents. When something fails, **adapt** — don't just report the failure.
+
+---
+
+## 1. Retry with Backoff
+
+**When:** Transient failures — API timeouts, rate limits, network errors, temporary service unavailability.
+
+**Pattern:**
+1. Wait briefly, then retry (start at 2s, double each attempt)
+2. Maximum 3 retries before escalating
+3. Log each attempt with the error received
+
+**Example:** API call returns 429 Too Many Requests → wait 2s → retry → wait 4s → retry → wait 8s → retry → escalate if still failing.
+
+---
+
+## 2. Fallback Alternatives
+
+**When:** Primary tool or approach fails and an alternative exists.
+
+**Pattern:**
+1. Attempt primary approach
+2. On failure, identify alternative tool/method
+3. Try the alternative with the same intent
+4. Document which alternative was used and why
+
+**Example:** Primary CLI tool fails → fall back to direct API call for the same operation.
+
+---
+
+## 3. Diagnose-and-Fix
+
+**When:** Build failures, test failures, linting errors — structured errors with actionable output.
+
+**Pattern:**
+1. Read the full error output carefully
+2. Identify the root cause from error messages
+3. Attempt a targeted fix
+4. Re-run to verify the fix
+5. Maximum 3 fix-retry cycles before escalating
+
+**Example:** Build fails with a type error → check for missing import → add it → rebuild.
+
+---
+
+## 4. Escalate with Context
+
+**When:** Recovery attempts have been exhausted, or the failure requires human judgment.
+
+**Pattern:**
+1. Summarize what was attempted and what failed
+2. Include the exact error messages
+3. State what you believe the root cause is
+4. Suggest next steps or who might be able to help
+5. Hand off to the coordinator or the appropriate specialist
+
+**Example:** After 3 failed build attempts → "Build fails on line 42 with null reference. Tried X, Y, Z. Likely a design issue in the Foo module. Recommend the code owner review."
+
+---
+
+## 5. Graceful Degradation
+
+**When:** A non-critical step fails but the overall task can still deliver value.
+
+**Pattern:**
+1. Determine if the failed step is critical to the task outcome
+2. If non-critical, log the failure and continue
+3. Deliver partial results with a clear note of what was skipped
+4. Offer to retry the skipped step separately
+
+**Example:** Generating a report with 5 sections — section 3 data source is unavailable → produce the report with 4 sections, note that section 3 was skipped and why.
+
+---
+
+## Applying These Patterns
+
+Each agent should reference these patterns in their charter's `## Error Recovery` section, tailored to their domain. The charter should list the agent's most common failure modes and map each to the appropriate pattern above.
+
+**Selection guide:**
+
+| Failure Type | Primary Pattern | Fallback Pattern |
+|---|---|---|
+| Network/API transient | Retry with Backoff | Escalate with Context |
+| Tool/dependency missing | Fallback Alternatives | Escalate with Context |
+| Build/test error | Diagnose-and-Fix | Escalate with Context |
+| Auth/permissions | Retry with Backoff | Escalate with Context |
+| Non-critical data missing | Graceful Degradation | — |
+| Unknown/novel error | Escalate with Context | — |

package/templates/skills/iterative-retrieval/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: "iterative-retrieval"
+description: "Max-3-cycle protocol for agent sub-tasks with WHY context and coordinator validation. Use when spawning sub-agents to complete scoped work."
+domain: "agent-coordination"
+confidence: "high"
+license: MIT
+---
+
+# Iterative Retrieval Skill
+
+Squad agents frequently spawn sub-agents to complete scoped work. Without structure, these
+handoffs become vague, cycles multiply, and outputs land without being checked. The
+**Iterative Retrieval Pattern** caps cycles at 3, mandates WHY context in every spawn, and
+requires the coordinator to validate agent output before closing an issue.
+
+---
+
+## Spawn Prompt Template
+
+Every agent spawn must include the following four sections. Copy and fill in the template:
+
+```
+## Task
+{What you need done — concrete and bounded}
+
+## WHY this matters
+{The motivation and context. What system or user goal does this serve? What breaks if skipped?}
+
+## Success criteria
+{How you will know the output is correct. Be explicit — list acceptance criteria, not vibes.}
+Example:
+- [ ] File X exists and contains Y
+- [ ] No regressions in existing tests
+- [ ] PR is open targeting main with description matching the issue
+
+## Escalation path
+{What the agent should do if uncertain or stuck. "Stop and ask me" is valid.}
+Example:
+- If requirements are ambiguous → stop, comment on the issue, set label status:needs-decision
+- If blocked by a dependency → label status:blocked, explain in a comment
+- If 3 cycles exhausted without resolution → write a summary to inbox and surface to coordinator
+```
+
+---
+
+## 3-Cycle Protocol
+
+| Cycle | Description | Exit condition |
+|-------|-------------|----------------|
+| **1** | Initial attempt | Done → coordinator validates. Incomplete → surface delta. |
+| **2** | Targeted retry with specific corrections | Done → coordinator validates. Incomplete → one more. |
+| **3** | Final attempt with all context from cycles 1–2 | Done or escalate — no cycle 4. |
+
+### Rules
+
+1. **After each cycle**, the coordinator evaluates the output against the success criteria
+   before accepting it or spawning the next cycle.
+2. **Objective context forward**: each subsequent spawn includes a summary of what was tried
+   and what is still missing — not just a repeat of the original task.
+3. **Cycle 3 exhausted** → escalate: write a summary to `.squad/decisions/inbox/`, label the
+   issue `status:needs-decision`, and notify the user.
+
+---
+
+## Coordinator Validation Checklist
+
+Before accepting agent output and closing an issue, the coordinator must check:
+
+- [ ] All success criteria from the spawn prompt are met
+- [ ] PR exists and description matches the issue (if code work)
+- [ ] No obvious regressions (grep for TODO/FIXME introduced, build passes)
+- [ ] Agent did not silently skip parts of the task
+- [ ] If the agent reported uncertainty — was it resolved or escalated?
+
+If any item fails → do **not** accept. Spawn cycle N+1 (up to cycle 3) with specific deltas.
+
+---
+
+## When to Escalate vs Retry
+
+**Retry (cycle N+1)** when:
+- Output is structurally correct but missing specific items
+- Agent misunderstood scope (provide more context and re-run)
+- Partial success — clearly identified remaining delta
+
+**Escalate** when:
+- Requirements are fundamentally unclear (decision needed)
+- 3 cycles complete without convergence
+- Agent returned conflicting results across cycles
+- Task requires elevated permissions or external action
+- The work depends on another issue that isn't done yet
+
+---
+
+## Issue Dedup Check (Mandatory)
+
+Before any agent creates a GitHub issue, it **must** search for existing open issues to avoid
+duplicates.
+
+```bash
+# Check for existing open issues before creating a new one
+gh issue list --search "<keywords from your issue title>" --state open
+```
+
+- If an open issue already covers the same problem → **comment on it** instead of creating a new one.
+- If no duplicate → proceed to create the issue.
+- Use 2–3 representative keywords from the planned issue title as the search query.
+
+---
+
+## Mandatory Output Requirement (Research-Then-Execute)
+
+Every research or analysis task completed under this protocol **MUST** end with at least one
+concrete action before the cycle is closed. Acceptable follow-up actions:
+
+- GitHub issue created documenting the findings and next steps
+- PR opened implementing a recommendation
+- Decision recorded in `.squad/decisions/inbox/`
+- Documented recommendation with a named assignee and due date
+
+**Pure analysis reports without actionable follow-up will be rejected during triage.**
+If no action is warranted, the agent must explicitly state why and get coordinator sign-off.
+
+---
+
+## Anti-Patterns
+
+- **Spawning without WHY** — agents can't prioritise trade-offs without motivation context.
+- **Accepting output without validating** — one failed check avoids merging broken work.
+- **Cycle 4+** — if 3 cycles haven't converged, the problem is in the requirements, not the agent.
+- **Vague success criteria** — "looks good" is not a criterion. Use checkboxes.
+- **Forwarding WHAT without delta** — cycle 2+ prompts must include what cycle 1 got wrong.
+- **Creating issues without dedup check** — always search before creating.
+- **Research without action** — delivering analysis with no issue, PR, decision, or assignee is incomplete work.
+
+---
+
+## Examples
+
+### Good spawn prompt
+```
+## Task
+Add an "Iterative Retrieval Protocol" section to `.squad/agents/coordinator/charter.md` explaining
+the 3-cycle rule, WHY format, and validation checklist.
+
+## WHY this matters
+The coordinator spawns sub-agents on every round. Without a documented protocol, agents run unbounded
+cycles and outputs go unvalidated — leading to stale issues and silent failures.
+
+## Success criteria
+- [ ] Section "Iterative Retrieval Protocol" exists in charter.md
+- [ ] Section documents max-3-cycles rule
+- [ ] Section documents WHY format requirement
+- [ ] Section contains validation checklist (at least 4 items)
+- [ ] No other sections of charter.md are modified
+
+## Escalation path
+If the charter.md format is unclear, check another agent charter as a reference.
+If uncertain about content, stop and surface to coordinator.
+```
+
+### Bad spawn prompt (don't do this)
+```
+Update the coordinator charter with the iterative retrieval stuff.
+```