Repository navigation
feat: Distributed Mesh — Cross-Machine Squad Coordination #371
Description
Distributed Mesh Extension — Cross-Machine Squad Coordination
Summary
This proposal adds the distributed mesh pattern to Squad, enabling squads on different machines to coordinate work through shared context — complementing the existing upstream inheritance model.
Problem
Today, upstream inheritance (upstream.json) provides hierarchical, read-only context flow from parent to child squads. But there's no built-in way for peer squads to coordinate across machines, organizations, or git boundaries.
Proposed Solution
A documentation-and-templates-first approach that introduces three coordination zones:
| Zone | Scope | Transport | Auth |
|---|---|---|---|
| Zone 1 | Same machine | Filesystem | OS-level |
| Zone 2 | Same org, different machines | Git (shared repo) | SSH / PAT |
| Zone 3 | Cross-org | HTTPS /.well-known/squad/manifest.json |
OAuth / API key |
Key Design Decisions
- No code changes to existing SDK modules — this is templates + docs only
- Complementary to upstream — a squad can have both upstream (policies flowing down) and mesh peers (lateral coordination)
- Write partitioning — each squad owns a namespace, preventing conflicts
- Reuses existing building blocks —
src/sharing/(cache, conflicts, versioning) andsrc/upstream/(git-based resolution) provide the foundation
Upstream vs Mesh Relationship
| Upstream | Mesh | |
|---|---|---|
| Direction | Top-down (parent → child) | Peer-to-peer (squad ↔ squad) |
| Access | Read-only | Read-write (partitioned) |
| Purpose | Org policies, shared context | Cross-squad coordination |
| Config | upstream.json |
mesh.json |
What's Included
- Docs: Full feature page at
docs/features/distributed-mesh.mdwith architecture, zones, security model, and upstream comparison - Templates:
templates/mesh/withmesh.json.example, sync scripts (bash + PowerShell), and README - Skills:
SKILL.mdplaced in all template directories (SDK, CLI, root) plus runtime skill - Cross-references: Updated
scenarios/multiple-squads.mdand navigation
References
- Upstream module:
packages/squad-sdk/src/upstream/ - Sharing module:
packages/squad-sdk/src/sharing/(reusable building blocks) - Implementation branch:
squad/distributed-mesh-integration
Activity
github-actions commentedon Mar 13, 2026
squad:keaton. Check.squad/team.md(or.ai-team/team.md) for valid member names.github-actions commentedon Mar 13, 2026
🏗️ Squad Triage — Flight (Lead)
Issue: #371 — feat: Distributed Mesh — Cross-Machine Squad Coordination
Assigned to: DSKY (TUI Engineer)
Reason: Issue relates to frontend/UI work
@copilot evaluation: 🔴 Not suitable — issue involves work outside the coding agent's capability profile.
Team roster:
squad:flightsquad:proceduressquad:eecomsquad:fidosquad:paosquad:capcomsquad:controlsquad:surgeonsquad:boostersquad:gncsquad:networksquad:retrosquad:incosquad:guidosquad:telemetrysquad:voxsquad:dskysquad:simssquad:handbooksquad:ralphsquad:copilotgithub-actions commentedon Mar 13, 2026
squad:fenster. Check.squad/team.md(or.ai-team/team.md) for valid member names.14 remaining items
test: speed gate tests for the impatient user journey (github#412)
Visual polish: separators, help, status, agents, thinking indicator (g…
feat: a11y fixes and test coverage (github#382)
fix: correct ThinkingIndicator test assertion (github#415)
Fix github#422: Add context to thinking spinner (github#435)
Fix github#422: Add context to thinking spinner (github#436)
Fix github#420/github#425: Add SDK connection feedback (github#437)
Fix github#432: Show retry warnings earlier (github#441)
Fix github#421: Lead with default behavior in --help (github#438)
Fix github#423/github#399: Make welcome non-blocking (github#439)
Fix github#428/github#401: Verify input buffering covers all paths (g…
Fix github#430: Wire coordinator streaming deltas (github#442)
fix: update test assertions to match new UX copy (github#443)