cross-squad-communication

Context

When multiple repositories each have their own Squad (AI team), they need to exchange information: knowledge queries, PR reviews, task delegation, and dependency analysis. Each squad has its own agents, MCP tools, and issue tracker — there is no shared runtime.

Companion skill — read first: cross-squad/SKILL.md covers discovery of peer squads via squad registry add/list/remove. This skill picks up after a peer is known and covers the communication protocols themselves — the four numbered patterns below: Pattern 0 (synchronous CLI), Pattern 1 (read-only knowledge query), Pattern 2 (git-based async), and Pattern 3 (GitHub-issue-based delegation). A separate non-numbered appendix (Cross-Repo Dependency Scan) is provided as a related analysis tool, not a communication pattern. The two skills are designed to be used together.

When this skill applies:

• A squad agent needs information from another squad-enabled repo
• A task needs to be delegated to another squad
• Cross-repo dependency analysis is needed
• PR review requests span repo boundaries

Key constraint: Each squad has its own runtime, MCP tools, and issue tracker. Cross-squad communication can be synchronous (via CLI session targeting the other repo) or asynchronous (file-based or issue-based). The coordinator decides which approach fits.

Patterns

Decision Tree: Choosing the Right Pattern

Is the target repo cloned locally?
├─ NO → Use Pattern 3 (Issue-Based) or Pattern 2 (Git-Based Async)
└─ YES
    ├─ Is this a quick query / knowledge lookup?
    │   └─ YES → Use Pattern 0 (Synchronous CLI) — fastest
    ├─ Does the work need to persist as artifacts?
    │   └─ YES → Use Pattern 2 (Git-Based Async)
    ├─ Is it a long-running analysis or multi-cycle task?
    │   └─ YES → Use Pattern 2 (Git-Based Async)
    └─ Is the target squad's Ralph running?
        ├─ YES → Pattern 2 or 3 (async processing available)
        └─ NO → Pattern 0 (Synchronous CLI) or Pattern 1 (Read-Only)