feat: Distributed Mesh — Cross-Machine Squad Coordination

[andikrueger]

Distributed Mesh Integration

Closes #371
Replaces #372 (closed — had a base branch mismatch that inflated the diff to 697 files)

What This Does

Adds the distributed mesh extension to Squad — enabling cross-machine squad coordination via git (Zone 2: same-org) and HTTP (Zone 3: cross-org). This complements the existing upstream inheritance model with peer-to-peer coordination capabilities.

Changes

Documentation

• New feature page: docs/src/content/docs/features/distributed-mesh.md (298 lines)
  • Three-zone architecture (local → git → HTTP)
  • Security model and write partitioning
  • Upstream vs mesh comparison table
• Cross-reference added to scenarios/multiple-squads.md
• Navigation updated in docs/src/navigation.ts

Templates

• templates/mesh/ — scaffolding for mesh setup:
  • mesh.json.example — configuration template for all 3 zones
  • sync-mesh.sh / sync-mesh.ps1 — sync scripts
  • README.md — quick-start guide
• SKILL.md in all template directories (SDK, CLI, root) + runtime skill

Tests

• Updated test/docs-build.test.ts — added distributed-mesh to EXPECTED_FEATURES array

Design Decisions

• Templates + docs only — no code changes to existing SDK modules
• Complementary to upstream — upstream = org policies flowing down (read-only), mesh = peer coordination (read-write)
• Write partitioning — each squad owns a namespace to prevent conflicts
• Leverages existing code — src/sharing/ (cache, conflicts, versioning) and src/upstream/ (git resolution) provide the foundation for future code implementation

How to Test

1. Check out this branch
2. Run npm run build and npm test to verify docs build and test assertions pass
3. Review the docs page at features/distributed-mesh

---

Working as the Squad team (Flight 🏗️ + PAO 📣 + Network 📦) with @copilot coordination

[andikrueger]

Added second commit (d3835ea): Deterministic skill rewrite

• SKILL.md now has explicit SCOPE section (produces vs. does not produce)
• Deterministic 5-step AGENT WORKFLOW ending at STOP
• Fixed ambiguous language ('do the task', phase advancement)
• Added decision template inline
• Expanded anti-patterns (code generation, scope creep)
• All 4 SKILL.md copies synced
• Docs page updated with 'Skill scope' section

This addresses the testing feedback where agents generated 43 tests + a validator instead of just mesh.json.

[andikrueger]

Self-contained skill model (commit a9e9d63)

Updated the distributed-mesh skill to follow the GitHub agent-skills spec pattern:

What changed:

• Scripts (sync-mesh.sh, sync-mesh.ps1) and mesh.json.example are now bundled inside each skill directory
• SKILL.md workflow is now fully zero-touch: ASK → GENERATE → COPY → INIT → DECIDE → STOP
• The agent copies scripts from its own skill directory — no manual user steps
• Added \--init\\ flag to sync scripts for automatic state repo scaffolding

Before: Agent told user to manually copy scripts from templates/mesh/
After: Agent reads SKILL.md, copies bundled scripts itself, runs --init. Zero-touch.

20 files changed, 1362 insertions(+), 126 deletions(-)

[bradygaster]

Hey @andikrueger — heads up: the distributed-mesh feature addition introduced a test assertion drift in docs-build.test.ts (EXPECTED_FEATURES expected 33, found 34 on disk). FIDO is fixing it now on dev. No action needed from you — just letting you know for future PRs: when adding feature files, update the test assertions in the same commit. Thanks for the great contribution! 🚀