@bradygaster/squad-cli 0.8.25 → 0.9.1

package/templates/skills/distributed-mesh/sync-mesh.ps1

@@ -0,0 +1,111 @@
+# sync-mesh.ps1 — Materialize remote squad state locally
+#
+# Reads mesh.json, fetches remote squads into local directories.
+# Run before agent reads. No daemon. No service. ~40 lines.
+#
+# Usage: .\sync-mesh.ps1 [path-to-mesh.json]
+#        .\sync-mesh.ps1 -Init [path-to-mesh.json]
+# Requires: git
+param(
+    [switch]$Init,
+    [string]$MeshJson = "mesh.json"
+)
+$ErrorActionPreference = "Stop"
+
+# Handle -Init mode
+if ($Init) {
+    if (-not (Test-Path $MeshJson)) {
+        Write-Host "❌ $MeshJson not found"
+        exit 1
+    }
+    
+    Write-Host "🚀 Initializing mesh state repository..."
+    $config = Get-Content $MeshJson -Raw | ConvertFrom-Json
+    $squads = $config.squads.PSObject.Properties.Name
+    
+    # Create squad directories with placeholder SUMMARY.md
+    foreach ($squad in $squads) {
+        if (-not (Test-Path $squad)) {
+            New-Item -ItemType Directory -Path $squad | Out-Null
+            Write-Host "  ✓ Created $squad/"
+        } else {
+            Write-Host "  • $squad/ exists (skipped)"
+        }
+        
+        $summaryPath = "$squad/SUMMARY.md"
+        if (-not (Test-Path $summaryPath)) {
+            "# $squad`n`n_No state published yet._" | Set-Content $summaryPath
+            Write-Host "  ✓ Created $summaryPath"
+        } else {
+            Write-Host "  • $summaryPath exists (skipped)"
+        }
+    }
+    
+    # Generate root README.md
+    if (-not (Test-Path "README.md")) {
+        $readme = @"
+# Squad Mesh State Repository
+
+This repository tracks published state from participating squads.
+
+## Participating Squads
+
+"@
+        foreach ($squad in $squads) {
+            $zone = $config.squads.$squad.zone
+            $readme += "- **$squad** (Zone: $zone)`n"
+        }
+        $readme += @"
+
+Each squad directory contains a ``SUMMARY.md`` with their latest published state.
+State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``.
+"@
+        $readme | Set-Content "README.md"
+        Write-Host "  ✓ Created README.md"
+    } else {
+        Write-Host "  • README.md exists (skipped)"
+    }
+    
+    Write-Host ""
+    Write-Host "✅ Mesh state repository initialized"
+    exit 0
+}
+
+$config = Get-Content $MeshJson -Raw | ConvertFrom-Json
+
+# Zone 2: Remote-trusted — git clone/pull
+foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-trusted" }) {
+    $squad  = $entry.Name
+    $source = $entry.Value.source
+    $ref    = if ($entry.Value.ref) { $entry.Value.ref } else { "main" }
+    $target = $entry.Value.sync_to
+
+    if (Test-Path "$target/.git") {
+        git -C $target pull --rebase --quiet 2>$null
+        if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: pull failed (using stale)" }
+    } else {
+        New-Item -ItemType Directory -Force -Path (Split-Path $target -Parent) | Out-Null
+        git clone --quiet --depth 1 --branch $ref $source $target 2>$null
+        if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: clone failed (unavailable)" }
+    }
+}
+
+# Zone 3: Remote-opaque — fetch published contracts
+foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-opaque" }) {
+    $squad  = $entry.Name
+    $source = $entry.Value.source
+    $target = $entry.Value.sync_to
+    $auth   = $entry.Value.auth
+
+    New-Item -ItemType Directory -Force -Path $target | Out-Null
+    $params = @{ Uri = $source; OutFile = "$target/SUMMARY.md"; UseBasicParsing = $true }
+    if ($auth -eq "bearer") {
+        $tokenVar = ($squad.ToUpper() -replace '-', '_') + "_TOKEN"
+        $token = [Environment]::GetEnvironmentVariable($tokenVar)
+        if ($token) { $params.Headers = @{ Authorization = "Bearer $token" } }
+    }
+    try { Invoke-WebRequest @params -ErrorAction Stop }
+    catch { "# ${squad} — unavailable ($(Get-Date))" | Set-Content "$target/SUMMARY.md" }
+}
+
+Write-Host "✓ Mesh sync complete"

package/templates/skills/distributed-mesh/sync-mesh.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# sync-mesh.sh — Materialize remote squad state locally
+#
+# Reads mesh.json, fetches remote squads into local directories.
+# Run before agent reads. No daemon. No service. ~40 lines.
+#
+# Usage: ./sync-mesh.sh [path-to-mesh.json]
+#        ./sync-mesh.sh --init [path-to-mesh.json]
+# Requires: jq (https://github.com/jqlang/jq), git, curl
+
+set -euo pipefail
+
+# Handle --init mode
+if [ "${1:-}" = "--init" ]; then
+  MESH_JSON="${2:-mesh.json}"
+  
+  if [ ! -f "$MESH_JSON" ]; then
+    echo "❌ $MESH_JSON not found"
+    exit 1
+  fi
+  
+  echo "🚀 Initializing mesh state repository..."
+  squads=$(jq -r '.squads | keys[]' "$MESH_JSON")
+  
+  # Create squad directories with placeholder SUMMARY.md
+  for squad in $squads; do
+    if [ ! -d "$squad" ]; then
+      mkdir -p "$squad"
+      echo "  ✓ Created $squad/"
+    else
+      echo "  • $squad/ exists (skipped)"
+    fi
+    
+    if [ ! -f "$squad/SUMMARY.md" ]; then
+      echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md"
+      echo "  ✓ Created $squad/SUMMARY.md"
+    else
+      echo "  • $squad/SUMMARY.md exists (skipped)"
+    fi
+  done
+  
+  # Generate root README.md
+  if [ ! -f "README.md" ]; then
+    {
+      echo "# Squad Mesh State Repository"
+      echo ""
+      echo "This repository tracks published state from participating squads."
+      echo ""
+      echo "## Participating Squads"
+      echo ""
+      for squad in $squads; do
+        zone=$(jq -r ".squads.\"$squad\".zone" "$MESH_JSON")
+        echo "- **$squad** (Zone: $zone)"
+      done
+      echo ""
+      echo "Each squad directory contains a \`SUMMARY.md\` with their latest published state."
+      echo "State is synchronized using \`sync-mesh.sh\` or \`sync-mesh.ps1\`."
+    } > README.md
+    echo "  ✓ Created README.md"
+  else
+    echo "  • README.md exists (skipped)"
+  fi
+  
+  echo ""
+  echo "✅ Mesh state repository initialized"
+  exit 0
+fi
+
+MESH_JSON="${1:-mesh.json}"
+
+# Zone 2: Remote-trusted — git clone/pull
+for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-trusted") | .key' "$MESH_JSON"); do
+  source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON")
+  ref=$(jq -r ".squads.\"$squad\".ref // \"main\"" "$MESH_JSON")
+  target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON")
+
+  if [ -d "$target/.git" ]; then
+    git -C "$target" pull --rebase --quiet 2>/dev/null \
+      || echo "⚠ $squad: pull failed (using stale)"
+  else
+    mkdir -p "$(dirname "$target")"
+    git clone --quiet --depth 1 --branch "$ref" "$source" "$target" 2>/dev/null \
+      || echo "⚠ $squad: clone failed (unavailable)"
+  fi
+done
+
+# Zone 3: Remote-opaque — fetch published contracts
+for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-opaque") | .key' "$MESH_JSON"); do
+  source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON")
+  target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON")
+  auth=$(jq -r ".squads.\"$squad\".auth // \"\"" "$MESH_JSON")
+
+  mkdir -p "$target"
+  auth_flag=""
+  if [ "$auth" = "bearer" ]; then
+    token_var="$(echo "${squad}" | tr '[:lower:]-' '[:upper:]_')_TOKEN"
+    [ -n "${!token_var:-}" ] && auth_flag="--header \"Authorization: Bearer ${!token_var}\""
+  fi
+
+  eval curl --silent --fail $auth_flag "$source" -o "$target/SUMMARY.md" 2>/dev/null \
+    || echo "# ${squad} — unavailable ($(date))" > "$target/SUMMARY.md"
+done
+
+echo "✓ Mesh sync complete"

package/templates/skills/docs-standards/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: "docs-standards"
+description: "Microsoft Style Guide + Squad-specific documentation patterns"
+domain: "documentation"
+confidence: "high"
+source: "earned (PAO charter, multiple doc PR reviews)"
+---
+
+## Context
+
+Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability.
+
+## Patterns
+
+### Microsoft Style Guide Rules
+- **Sentence-case headings:** "Getting started" not "Getting Started"
+- **Active voice:** "Run the command" not "The command should be run"
+- **Second person:** "You can configure..." not "Users can configure..."
+- **Present tense:** "The system routes..." not "The system will route..."
+- **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements)
+
+### Squad Formatting Patterns
+- **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data
+- **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy
+- **Experimental warnings:** Features in preview get callout at top
+- **Cross-references at bottom:** Related pages linked after main content
+
+### Structure
+- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)**
+
+### Test Sync Rule
+- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit
+
+## Examples
+
+✓ **Correct:**
+```markdown
+# Getting started with Squad
+
+> ⚠️ **Experimental:** This feature is in preview.
+
+Try this:
+\`\`\`bash
+squad init
+\`\`\`
+
+Squad helps you build AI teams...
+
+---
+
+## Install Squad
+
+Run the following command...
+```
+
+✗ **Incorrect:**
+```markdown
+# Getting Started With Squad  // Title case
+
+Squad is a tool which will help users... // Third person, future tense
+
+You can install Squad with npm & configure it... // Ampersand in prose
+```
+
+## Anti-Patterns
+
+- Title-casing headings because "it looks nicer"
+- Writing in passive voice or third person
+- Long paragraphs of dense text (breaks scannability)
+- Adding doc pages without updating test assertions
+- Using ampersands outside code blocks

package/templates/skills/economy-mode/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "economy-mode"
+description: "Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active."
+domain: "model-selection"
+confidence: "low"
+source: "manual"
+---
+
+## SCOPE
+
+✅ THIS SKILL PRODUCES:
+- A modified Layer 3 model selection table applied when economy mode is active
+- `economyMode: true` written to `.squad/config.json` when activated persistently
+- Spawn acknowledgments with `💰` indicator when economy mode is active
+
+❌ THIS SKILL DOES NOT PRODUCE:
+- Code, tests, or documentation
+- Cost reports or billing artifacts
+- Changes to Layer 0, Layer 1, or Layer 2 resolution (user intent always wins)
+
+## Context
+
+Economy mode shifts Layer 3 (Task-Aware Auto-Selection) to lower-cost alternatives. It does NOT override persistent config (`defaultModel`, `agentModelOverrides`) or per-agent charter preferences — those represent explicit user intent and always take priority.
+
+Use this skill when the user wants to reduce costs across an entire session or permanently, without manually specifying models for each agent.
+
+## Activation Methods
+
+| Method | How |
+|--------|-----|
+| Session phrase | "use economy mode", "save costs", "go cheap", "reduce costs" |
+| Persistent config | `"economyMode": true` in `.squad/config.json` |
+| CLI flag | `squad --economy` |
+
+**Deactivation:** "turn off economy mode", "disable economy mode", or remove `economyMode` from `config.json`.
+
+## Economy Model Selection Table
+
+When economy mode is **active**, Layer 3 auto-selection uses this table instead of the normal defaults:
+
+| Task Output | Normal Mode | Economy Mode |
+|-------------|-------------|--------------|
+| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` |
+| Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` |
+
+**Prefer `gpt-4.1` over `gpt-5-mini`** when the task involves structured output or agentic tool use. Prefer `gpt-5-mini` for pure text generation tasks where latency matters.
+
+## AGENT WORKFLOW
+
+### On Session Start
+
+1. READ `.squad/config.json`
+2. CHECK for `economyMode: true` — if present, activate economy mode for the session
+3. STORE economy mode state in session context
+
+### On User Phrase Trigger
+
+**Session-only (no config change):** "use economy mode", "save costs", "go cheap"
+
+1. SET economy mode active for this session
+2. ACKNOWLEDGE: `✅ Economy mode active — using cost-optimized models this session. (Layer 0 and Layer 2 preferences still apply)`
+
+**Persistent:** "always use economy mode", "save economy mode"
+
+1. WRITE `economyMode: true` to `.squad/config.json` (merge, don't overwrite other fields)
+2. ACKNOWLEDGE: `✅ Economy mode saved — cost-optimized models will be used until disabled.`
+
+### On Every Agent Spawn (Economy Mode Active)
+
+1. CHECK Layer 0a/0b first (agentModelOverrides, defaultModel) — if set, use that. Economy mode does NOT override Layer 0.
+2. CHECK Layer 1 (session directive for a specific model) — if set, use that. Economy mode does NOT override explicit session directives.
+3. CHECK Layer 2 (charter preference) — if set, use that. Economy mode does NOT override charter preferences.
+4. APPLY economy table at Layer 3 instead of normal table.
+5. INCLUDE `💰` in spawn acknowledgment: `🔧 {Name} ({model} · 💰 economy) — {task}`
+
+### On Deactivation
+
+**Trigger phrases:** "turn off economy mode", "disable economy mode", "use normal models"
+
+1. REMOVE `economyMode` from `.squad/config.json` (if it was persisted)
+2. CLEAR session economy mode state
+3. ACKNOWLEDGE: `✅ Economy mode disabled — returning to standard model selection.`
+
+### STOP
+
+After updating economy mode state and including the `💰` indicator in spawn acknowledgments, this skill is done. Do NOT:
+- Change Layer 0, Layer 1, or Layer 2 model choices
+- Override charter-specified models
+- Generate cost reports or comparisons
+- Fall back to premium models via economy mode (economy mode never bumps UP)
+
+## Config Schema
+
+`.squad/config.json` economy-related fields:
+
+```json
+{
+  "version": 1,
+  "economyMode": true
+}
+```
+
+- `economyMode` — when `true`, Layer 3 uses the economy table. Optional; absent = economy mode off.
+- Combines with `defaultModel` and `agentModelOverrides` — Layer 0 always wins.
+
+## Anti-Patterns
+
+- **Don't override Layer 0 in economy mode.** If the user set `defaultModel: "claude-opus-4.6"`, they want quality. Economy mode only affects Layer 3 auto-selection.
+- **Don't silently apply economy mode.** Always acknowledge when activated or deactivated.
+- **Don't treat economy mode as permanent by default.** Session phrases activate session-only; only "always" or `config.json` persist it.
+- **Don't bump premium tasks down too far.** Architecture and security reviews shift from opus to sonnet in economy mode — they do NOT go to fast/cheap models.