@bradygaster/squad-cli 0.8.25 → 0.9.1

package/templates/skills/ci-validation-gates/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: "ci-validation-gates"
+description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22"
+domain: "ci-cd"
+confidence: "high"
+source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident"
+---
+
+## Context
+
+CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here.
+
+## Patterns
+
+### Semver Validation Gate
+Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them.
+
+```yaml
+- name: Validate semver
+  run: |
+    VERSION="${{ github.event.release.tag_name }}"
+    VERSION="${VERSION#v}"
+    if ! npx semver "$VERSION" > /dev/null 2>&1; then
+      echo "❌ Invalid semver: $VERSION"
+      echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid."
+      exit 1
+    fi
+    echo "✅ Valid semver: $VERSION"
+```
+
+### NPM Token Type Verification
+NPM_TOKEN MUST be an Automation token, not a User token with 2FA:
+- User tokens require OTP — CI can't provide it → EOTP error
+- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation
+- Verify before first publish in any workflow
+
+### Retry Logic for npm Registry Propagation
+npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable.
+- Propagation: typically 5-30s, up to 2min in rare cases
+- All verify steps: 5 attempts, 15-second intervals
+- Log each attempt: "Attempt 1/5: Checking package..."
+- Exit loop on success, fail after max attempts
+
+```yaml
+- name: Verify package (with retry)
+  run: |
+    MAX_ATTEMPTS=5
+    WAIT_SECONDS=15
+    for attempt in $(seq 1 $MAX_ATTEMPTS); do
+      echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..."
+      if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
+        echo "✅ Package verified"
+        exit 0
+      fi
+      [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS
+    done
+    echo "❌ Failed to verify after $MAX_ATTEMPTS attempts"
+    exit 1
+```
+
+### Draft Release Detection
+Draft releases don't emit `release: published` event. Workflows MUST:
+- Trigger on `release: published` (NOT `created`)
+- If using workflow_dispatch: verify release is published via GitHub API before proceeding
+
+### Build Script Protection
+Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions.
+
+## Known Failure Modes (v0.8.22 Incident)
+
+| # | What Happened | Root Cause | Prevention |
+|---|---------------|-----------|------------|
+| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish |
+| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only |
+| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals |
+| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases |
+| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 |
+
+## Anti-Patterns
+- ❌ Publishing without semver validation gate
+- ❌ Single-shot verification without retry
+- ❌ Hard-coded secrets in workflows
+- ❌ Silent CI failures — every error needs actionable output with remediation
+- ❌ Assuming npm publish is instantly queryable

package/templates/skills/cli-wiring/SKILL.md

@@ -0,0 +1,47 @@
+# Skill: CLI Command Wiring
+
+**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`.
+
+## Checklist — Adding a New CLI Command
+
+1. **Create command file** in `packages/squad-cli/src/cli/commands/<name>.ts`
+   - Export a `run<Name>(cwd, options)` async function (or class with static methods for utility modules)
+
+2. **Add routing block** in `packages/squad-cli/src/cli-entry.ts` inside `main()`:
+   ```ts
+   if (cmd === '<name>') {
+     const { run<Name> } = await import('./cli/commands/<name>.js');
+     // parse args, call function
+     await run<Name>(process.cwd(), options);
+     return;
+   }
+   ```
+
+3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`):
+   ```ts
+   console.log(`  ${BOLD}<name>${RESET}     <description>`);
+   console.log(`             Usage: <name> [flags]`);
+   ```
+
+4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3.
+
+## Wiring Patterns by Command Type
+
+| Type | Example | How to wire |
+|------|---------|-------------|
+| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` |
+| Placeholder command | `loop`, `hire` | Inline in cli-entry.ts, prints pending message |
+| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) |
+| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias |
+
+## Common Import Pattern
+
+```ts
+import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js';
+```
+
+Use dynamic `await import()` for command modules to keep startup fast (lazy loading).
+
+## History
+
+- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, hire were already present.

package/templates/skills/client-compatibility/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: "client-compatibility"
+description: "Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+---
+
+## Context
+
+Squad runs on multiple Copilot surfaces (CLI, VS Code, JetBrains, GitHub.com). The coordinator must detect its platform and adapt spawning behavior accordingly. Different tools are available on different platforms, requiring conditional logic for agent spawning, SQL usage, and response timing.
+
+## Patterns
+
+### Platform Detection
+
+Before spawning agents, determine the platform by checking available tools:
+
+1. **CLI mode** — `task` tool is available → full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`.
+
+2. **VS Code mode** — `runSubagent` or `agent` tool is available → conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically — no `read_agent` needed.
+
+3. **Fallback mode** — neither `task` nor `runSubagent`/`agent` available → work inline. Do not apologize or explain the limitation. Execute the task directly.
+
+If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface).
+
+### VS Code Spawn Adaptations
+
+When in VS Code mode, the coordinator changes behavior in these ways:
+
+- **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter — pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI.
+- **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling.
+- **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains — they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker.
+- **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable.
+- **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done.
+- **`read_agent`:** Skip entirely. Results return automatically when subagents complete.
+- **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools.
+- **`description`:** Drop it. The agent name is already in the prompt.
+- **Prompt content:** Keep ALL prompt structure — charter, identity, task, hygiene, response order blocks are surface-independent.
+
+### Feature Degradation Table
+
+| Feature | CLI | VS Code | Degradation |
+|---------|-----|---------|-------------|
+| Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None — equivalent concurrency |
+| Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent |
+| Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group |
+| Launch table UX | Show table → results later | Skip table → results with response | UX only — results are correct |
+| SQL tool | Available | Not available | Avoid SQL in cross-platform code paths |
+| Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block — harmless if unnecessary |
+
+### SQL Tool Caveat
+
+The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.squad/` files) for anything that must work everywhere.
+
+## Examples
+
+**Example 1: CLI parallel spawn**
+```typescript
+// Coordinator detects task tool available → CLI mode
+task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... })
+task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... })
+// Later: read_agent for both
+```
+
+**Example 2: VS Code parallel spawn**
+```typescript
+// Coordinator detects runSubagent available → VS Code mode
+runSubagent({ prompt: "...Fenster charter + task..." })
+runSubagent({ prompt: "...Hockney charter + task..." })
+runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group
+// Results return automatically, no read_agent
+```
+
+**Example 3: Fallback mode**
+```typescript
+// Neither task nor runSubagent available → work inline
+// Coordinator executes the task directly without spawning
+```
+
+## Anti-Patterns
+
+- ❌ Using SQL tool in cross-platform workflows (breaks on VS Code/JetBrains/GitHub.com)
+- ❌ Attempting per-spawn model selection on VS Code (Phase 1 — only session model works)
+- ❌ Fire-and-forget Scribe on VS Code (must batch as last subagent)
+- ❌ Showing launch table on VS Code (results already inline)
+- ❌ Apologizing or explaining platform limitations to the user
+- ❌ Using `task` when only `runSubagent` is available
+- ❌ Dropping prompt structure (charter/identity/task) on non-CLI platforms

package/templates/skills/cross-squad/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "cross-squad"
+description: "Coordinating work across multiple Squad instances"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+tools:
+  - name: "squad-discover"
+    description: "List known squads and their capabilities"
+    when: "When you need to find which squad can handle a task"
+  - name: "squad-delegate"
+    description: "Create work in another squad's repository"
+    when: "When a task belongs to another squad's domain"
+---
+
+## Context
+When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling.
+
+Cross-squad orchestration applies when:
+- A task requires capabilities owned by another squad
+- An architectural decision affects multiple squads
+- A feature spans multiple repositories with different squads
+- A squad needs to request infrastructure, tooling, or support from another squad
+
+## Patterns
+
+### Discovery via Manifest
+Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through:
+1. **Well-known paths**: Check `.squad/manifest.json` in known org repos
+2. **Upstream config**: Squads already listed in `.squad/upstream.json` are checked for manifests
+3. **Explicit registry**: A central `squad-registry.json` can list all squads in an org
+
+```json
+{
+  "name": "platform-squad",
+  "version": "1.0.0",
+  "description": "Platform infrastructure team",
+  "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"],
+  "contact": {
+    "repo": "org/platform",
+    "labels": ["squad:platform"]
+  },
+  "accepts": ["issues", "prs"],
+  "skills": ["helm-developer", "operator-developer", "pipeline-engineer"]
+}
+```
+
+### Context Sharing
+When delegating work, share only what the target squad needs:
+- **Capability list**: What this squad can do (from manifest)
+- **Relevant decisions**: Only decisions that affect the target squad
+- **Handoff context**: A concise description of why this work is being delegated
+
+Do NOT share:
+- Internal team state (casting history, session logs)
+- Full decision archives (send only relevant excerpts)
+- Authentication credentials or secrets
+
+### Work Handoff Protocol
+1. **Check manifest**: Verify the target squad accepts the work type (issues, PRs)
+2. **Create issue**: Use `gh issue create` in the target repo with:
+   - Title: `[cross-squad] <description>`
+   - Label: `squad:cross-squad` (or the squad's configured label)
+   - Body: Context, acceptance criteria, and link back to originating issue
+3. **Track**: Record the cross-squad issue URL in the originating squad's orchestration log
+4. **Poll**: Periodically check if the delegated issue is closed/completed
+
+### Feedback Loop
+Track delegated work completion:
+- Poll target issue status via `gh issue view`
+- Update originating issue with status changes
+- Close the feedback loop when delegated work merges
+
+## Examples
+
+### Discovering squads
+```bash
+# List all squads discoverable from upstreams and known repos
+squad discover
+
+# Output:
+#   platform-squad  →  org/platform  (kubernetes, helm, monitoring)
+#   frontend-squad  →  org/frontend  (react, nextjs, storybook)
+#   data-squad      →  org/data      (spark, airflow, dbt)
+```
+
+### Delegating work
+```bash
+# Delegate a task to the platform squad
+squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service"
+
+# Creates issue in org/platform with cross-squad label and context
+```
+
+### Manifest in squad.config.ts
+```typescript
+export default defineSquad({
+  manifest: {
+    name: 'platform-squad',
+    capabilities: ['kubernetes', 'helm'],
+    contact: { repo: 'org/platform', labels: ['squad:platform'] },
+    accepts: ['issues', 'prs'],
+    skills: ['helm-developer', 'operator-developer'],
+  },
+});
+```
+
+## Anti-Patterns
+- **Direct file writes across repos** — Never modify another squad's `.squad/` directory. Use issues and PRs as the communication protocol.
+- **Tight coupling** — Don't depend on another squad's internal structure. Use the manifest as the public API contract.
+- **Unbounded delegation** — Always include acceptance criteria and a timeout. Don't create open-ended requests.
+- **Skipping discovery** — Don't hardcode squad locations. Use manifests and the discovery protocol.
+- **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-squad issues.
+- **Circular delegation** — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong.

package/templates/skills/distributed-mesh/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "distributed-mesh"
+description: "How to coordinate with squads on different machines using git as transport"
+domain: "distributed-coordination"
+confidence: "high"
+source: "multi-model-consensus (Opus 4.6, Sonnet 4.5, GPT-5.4)"
+---
+
+## SCOPE
+
+**✅ THIS SKILL PRODUCES (exactly these, nothing more):**
+
+1. **`mesh.json`** — Generated from user answers about zones and squads (which squads participate, what zone each is in, paths/URLs for each), using `mesh.json.example` in this skill's directory as the schema template
+2. **`sync-mesh.sh` and `sync-mesh.ps1`** — Copied from this skill's directory into the project root (these are bundled resources, NOT generated code)
+3. **Zone 2 state repo initialization** (if applicable) — If the user specified a Zone 2 shared state repo, run `sync-mesh.sh --init` to scaffold the state repo structure
+4. **A decision entry** in `.squad/decisions/inbox/` documenting the mesh configuration for team awareness
+
+**❌ THIS SKILL DOES NOT PRODUCE:**
+
+- **No application code** — No validators, libraries, or modules of any kind
+- **No test files** — No test suites, test cases, or test scaffolding
+- **No GENERATING sync scripts** — They are bundled with this skill as pre-built resources. COPY them, don't generate them.
+- **No daemons or services** — No background processes, servers, or persistent runtimes
+- **No modifications to existing squad files** beyond the decision entry (no changes to team.md, routing.md, agent charters, etc.)
+
+**Your role:** Configure the mesh topology and install the bundled sync scripts. Nothing more.
+
+## Context
+
+When squads are on different machines (developer laptops, CI runners, cloud VMs, partner orgs), the local file-reading convention still works — but remote files need to arrive on your disk first. This skill teaches the pattern for distributed squad communication.
+
+**When this applies:**
+- Squads span multiple machines, VMs, or CI runners
+- Squads span organizations or companies
+- An agent needs context from a squad whose files aren't on the local filesystem
+
+**When this does NOT apply:**
+- All squads are on the same machine (just read the files directly)
+
+## Patterns
+
+### The Core Principle
+
+> "The filesystem is the mesh, and git is how the mesh crosses machine boundaries."
+
+The agent interface never changes. Agents always read local files. The distributed layer's only job is to make remote files appear locally before the agent reads them.
+
+### Three Zones of Communication
+
+**Zone 1 — Local:** Same filesystem. Read files directly. Zero transport.
+
+**Zone 2 — Remote-Trusted:** Different host, same org, shared git auth. Transport: `git pull` from a shared repo. This collapses Zone 2 into Zone 1 — files materialize on disk, agent reads them normally.
+
+**Zone 3 — Remote-Opaque:** Different org, no shared auth. Transport: `curl` to fetch published contracts (SUMMARY.md). One-way visibility — you see only what they publish.
+
+### Agent Lifecycle (Distributed)
+
+```
+1. SYNC:    git pull (Zone 2) + curl (Zone 3) — materialize remote state
+2. READ:    cat .mesh/**/state.md — all files are local now
+3. WORK:    do their assigned work (the agent's normal task, NOT mesh-building)
+4. WRITE:   update own billboard, log, drops
+5. PUBLISH: git add + commit + push — share state with remote peers
+```
+
+Steps 2–4 are identical to local-only. Steps 1 and 5 are the entire distributed extension. **Note:** "WORK" means the agent performs its normal squad duties — it does NOT mean "build mesh infrastructure."
+
+### The mesh.json Config
+
+```json
+{
+  "squads": {
+    "auth-squad": { "zone": "local", "path": "../auth-squad/.mesh" },
+    "ci-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/ci-squad.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/ci-squad"
+    },
+    "partner-fraud": {
+      "zone": "remote-opaque",
+      "source": "https://partner.dev/squad-contracts/fraud/SUMMARY.md",
+      "sync_to": ".mesh/remotes/partner-fraud",
+      "auth": "bearer"
+    }
+  }
+}
+```
+
+Three zone types, one file. Local squads need only a path. Remote-trusted need a git URL. Remote-opaque need an HTTP URL.
+
+### Write Partitioning
+
+Each squad writes only to its own directory (`boards/{self}.md`, `squads/{self}/*`, `drops/{date}-{self}-*.md`). No two squads write to the same file. Git push/pull never conflicts. If push fails ("branch is behind"), the fix is always `git pull --rebase && git push`.
+
+### Trust Boundaries
+
+Trust maps to git permissions:
+- **Same repo access** = full mesh visibility
+- **Read-only access** = can observe, can't write
+- **No access** = invisible (correct behavior)
+
+For selective visibility, use separate repos per audience (internal, partner, public). Git permissions ARE the trust negotiation.
+
+### Phased Rollout
+
+- **Phase 0:** Convention only — document zones, agree on mesh.json fields, manually run `git pull`/`git push`. Zero new code.
+- **Phase 1:** Sync script (~30 lines bash or PowerShell) when manual sync gets tedious.
+- **Phase 2:** Published contracts + curl fetch when a Zone 3 partner appears.
+- **Phase 3:** Never. No MCP federation, A2A, service discovery, message queues.
+
+**Important:** Phases are NOT auto-advanced. These are project-level decisions — you start at Phase 0 (manual sync) and only move forward when the team decides complexity is justified.
+
+### Mesh State Repo
+
+The shared mesh state repo is a plain git repository — NOT a Squad project. It holds:
+- One directory per participating squad
+- Each directory contains at minimum a SUMMARY.md with the squad's current state
+- A root README explaining what the repo is and who participates
+
+No `.squad/` folder, no agents, no automation. Write partitioning means each squad only pushes to its own directory. The repo is a rendezvous point, not an intelligent system.
+
+If you want a squad that *observes* mesh health, that's a separate Squad project that lists the state repo as a Zone 2 remote in its `mesh.json` — it does NOT live inside the state repo.
+
+## Examples
+
+### Developer Laptop + CI Squad (Zone 2)
+
+Auth-squad agent wakes up. `git pull` brings ci-squad's latest results. Agent reads: "3 test failures in auth module." Adjusts work. Pushes results when done. **Overhead: one `git pull`, one `git push`.**
+
+### Two Orgs Collaborating (Zone 3)
+
+Payment-squad fetches partner's published SUMMARY.md via curl. Reads: "Risk scoring v3 API deprecated April 15. New field `device_fingerprint` required." The consuming agent (in payment-squad's team) reads this information and uses it to inform its work — for example, updating payment integration code to include the new field. Partner can't see payment-squad's internals.
+
+### Same Org, Shared Mesh Repo (Zone 2)
+
+Three squads on different machines. One shared git repo holds the mesh. Each squad: `git pull` before work, `git push` after. Write partitioning ensures zero merge conflicts.
+
+## AGENT WORKFLOW (Deterministic Setup)
+
+When a user invokes this skill to set up a distributed mesh, follow these steps **exactly, in order:**
+
+### Step 1: ASK the user for mesh topology
+
+Ask these questions (adapt phrasing naturally, but get these answers):
+
+1. **Which squads are participating?** (List of squad names)
+2. **For each squad, which zone is it in?**
+   - `local` — same filesystem (just need a path)
+   - `remote-trusted` — different machine, same org, shared git access (need git URL + ref)
+   - `remote-opaque` — different org, no shared auth (need HTTPS URL to published contract)
+3. **For each squad, what's the connection info?**
+   - Local: relative or absolute path to their `.mesh/` directory
+   - Remote-trusted: git URL (SSH or HTTPS), ref (branch/tag), and where to sync it to locally
+   - Remote-opaque: HTTPS URL to their SUMMARY.md, where to sync it, and auth type (none/bearer)
+4. **Where should the shared state live?** (For Zone 2 squads: git repo URL for the mesh state, or confirm each squad syncs independently)
+
+### Step 2: GENERATE `mesh.json`
+
+Using the answers from Step 1, create a `mesh.json` file at the project root. Use `mesh.json.example` from THIS skill's directory (`.squad/skills/distributed-mesh/mesh.json.example`) as the schema template.
+
+Structure:
+
+```json
+{
+  "squads": {
+    "<squad-name>": { "zone": "local", "path": "<relative-or-absolute-path>" },
+    "<squad-name>": {
+      "zone": "remote-trusted",
+      "source": "<git-url>",
+      "ref": "<branch-or-tag>",
+      "sync_to": ".mesh/remotes/<squad-name>"
+    },
+    "<squad-name>": {
+      "zone": "remote-opaque",
+      "source": "<https-url-to-summary>",
+      "sync_to": ".mesh/remotes/<squad-name>",
+      "auth": "<none|bearer>"
+    }
+  }
+}
+```
+
+Write this file to the project root. Do NOT write any other code.
+
+### Step 3: COPY sync scripts
+
+Copy the bundled sync scripts from THIS skill's directory into the project root:
+
+- **Source:** `.squad/skills/distributed-mesh/sync-mesh.sh`
+- **Destination:** `sync-mesh.sh` (project root)
+
+- **Source:** `.squad/skills/distributed-mesh/sync-mesh.ps1`
+- **Destination:** `sync-mesh.ps1` (project root)
+
+These are bundled resources. Do NOT generate them — COPY them directly.
+
+### Step 4: RUN `--init` (if Zone 2 state repo exists)
+
+If the user specified a Zone 2 shared state repo in Step 1, run the initialization:
+
+**On Unix/Linux/macOS:**
+```bash
+bash sync-mesh.sh --init
+```
+
+**On Windows:**
+```powershell
+.\sync-mesh.ps1 -Init
+```
+
+This scaffolds the state repo structure (squad directories, placeholder SUMMARY.md files, root README).
+
+**Skip this step if:**
+- No Zone 2 squads are configured (local/opaque only)
+- The state repo already exists and is initialized
+
+### Step 5: WRITE a decision entry
+
+Create a decision file at `.squad/decisions/inbox/<your-agent-name>-mesh-setup.md` with this content:
+
+```markdown
+### <YYYY-MM-DD>: Mesh configuration
+
+**By:** <your-agent-name> (via distributed-mesh skill)
+
+**What:** Configured distributed mesh with <N> squads across zones <list-zones-used>
+
+**Squads:**
+- `<squad-name>` — Zone <X> — <brief-connection-info>
+- `<squad-name>` — Zone <X> — <brief-connection-info>
+- ...
+
+**State repo:** <git-url-if-zone-2-used, or "N/A (local/opaque only)">
+
+**Why:** <user's stated reason for setting up the mesh, or "Enable cross-machine squad coordination">
+```
+
+Write this file. The Scribe will merge it into the main decisions file later.
+
+### Step 6: STOP
+
+**You are done.** Do not:
+- Generate sync scripts (they're bundled with this skill — COPY them)
+- Write validator code
+- Write test files
+- Create any other modules, libraries, or application code
+- Modify existing squad files (team.md, routing.md, charters)
+- Auto-advance to Phase 2 or Phase 3
+
+Output a simple completion message:
+
+```
+✅ Mesh configured. Created:
+- mesh.json (<N> squads)
+- sync-mesh.sh and sync-mesh.ps1 (copied from skill bundle)
+- Decision entry: .squad/decisions/inbox/<filename>
+
+Run `bash sync-mesh.sh` (or `.\sync-mesh.ps1` on Windows) before agents start to materialize remote state.
+```
+
+---
+
+## Anti-Patterns
+
+**❌ Code generation anti-patterns:**
+- Writing `mesh-config-validator.js` or any validator module
+- Writing test files for mesh configuration
+- Generating sync scripts instead of copying the bundled ones from this skill's directory
+- Creating library modules or utilities
+- Building any code that "runs the mesh" — the mesh is read by agents, not executed
+
+**❌ Architectural anti-patterns:**
+- Building a federation protocol — Git push/pull IS federation
+- Running a sync daemon or server — Agents are not persistent. Sync at startup, publish at shutdown
+- Real-time notifications — Agents don't need real-time. They need "recent enough." `git pull` is recent enough
+- Schema validation for markdown — The LLM reads markdown. If the format changes, it adapts
+- Service discovery protocol — mesh.json is a file with 10 entries. Not a "discovery problem"
+- Auth framework — Git SSH keys and HTTPS tokens. Not a framework. Already configured
+- Message queues / event buses — Agents wake, read, work, write, sleep. Nobody's home to receive events
+- Any component requiring a running process — That's the line. Don't cross it
+
+**❌ Scope creep anti-patterns:**
+- Auto-advancing phases without user decision
+- Modifying agent charters or routing rules
+- Setting up CI/CD pipelines for mesh sync
+- Creating dashboards or monitoring tools

package/templates/skills/distributed-mesh/mesh.json.example

@@ -0,0 +1,30 @@
+{
+  "squads": {
+    "auth-squad": {
+      "zone": "local",
+      "path": "../auth-squad/.mesh"
+    },
+    "api-squad": {
+      "zone": "local",
+      "path": "../api-squad/.mesh"
+    },
+    "ci-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/ci-squad.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/ci-squad"
+    },
+    "data-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/data-pipeline.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/data-squad"
+    },
+    "partner-fraud": {
+      "zone": "remote-opaque",
+      "source": "https://partner.example.com/squad-contracts/fraud/SUMMARY.md",
+      "sync_to": ".mesh/remotes/partner-fraud",
+      "auth": "bearer"
+    }
+  }
+}