[A2A] Multi-Repo Coordination Patterns and Best Practices #336

Overview

Design patterns and best practices for multi-repo coordination using Squad A2A. Document common workflows, anti-patterns, and team guidelines.

Reference

• PRD: See tamresearch1 repo, branch squad/296-cross-repo-a2a, file .squad/research/cross-repo-a2a-prd.md
• Related Issue: tamirdresher_microsoft/tamresearch1#296

Coordination Patterns

Pattern 1: Breaking Change Broadcast

Scenario: Backend makes API breaking change
Flow:

1. Backend squad commits change + decision doc
2. Backend runs: squad broadcast "API v2 released - migration required"
3. Dependent squads receive notification
4. Dependent squads query: squad ask backend "API v2 migration guide"
5. Auto-create issues in dependent repos

Benefits: Instant notification, zero manual coordination
Tools: Broadcast command, queryDecisions RPC

Pattern 2: Cross-Repo Dependency Sync

Scenario: Frontend depends on backend library version
Flow:

1. Frontend squad queries: squad ask backend "stable version of api-client"
2. Backend responds with version + changelog
3. Frontend auto-updates package.json
4. CI runs, tests pass
5. Auto-merge PR

Benefits: Always-current dependencies, automated sync
Tools: Custom squad scripts, GitHub Actions integration

Pattern 3: Shared Research Repository

Scenario: Multiple squads researching same tech (e.g., Kubernetes)
Flow:

1. First squad researches, writes .squad/research/k8s-ingress.md
2. Second squad needs same info: squad ask infrastructure "ingress recommendation"
3. Infrastructure squad returns cached research
4. Research gets reused 5x, saves 20 hours

Benefits: Knowledge reuse, consistent decisions
Tools: shareResearch RPC, search index

Pattern 4: Multi-Repo Initiative Coordination

Scenario: Security audit across 10 repos
Flow:

1. Security squad creates task template
2. Security runs: squad broadcast --delegate "Audit for hardcoded secrets"
3. Each squad runs local audit script
4. Squads report back: squad delegate security "Audit results for repo X"
5. Security aggregates, creates master report

Benefits: Parallel execution, consistent methodology
Tools: Task delegation, aggregation scripts

Pattern 5: Architecture Decision Sync

Scenario: Org-wide decision on auth strategy (JWT vs. session)
Flow:

1. Architecture squad writes decision: .squad/decisions/auth-strategy.md
2. All squads subscribe to architecture squad
3. Architecture squad updates decision
4. All squads notified in real-time
5. Dependent squads create tasks to align

Benefits: Single source of truth, instant propagation
Tools: Subscription API (Phase 3), watch mechanism

Anti-Patterns

Anti-Pattern 1: Over-Broadcasting

Problem: Spamming all squads with every minor change
Impact: Notification fatigue, ignored messages
Solution: Use severity levels, targeted broadcasts (filter by domain/tech)

Anti-Pattern 2: Synchronous Blocking

Problem: Frontend waits for backend squad response before proceeding
Impact: Deadlocks, slow development
Solution: Async task delegation, timeout + fallback

Anti-Pattern 3: No Access Control

Problem: All squads can query/modify all others
Impact: Unauthorized changes, chaos
Solution: RBAC (Phase 2/3), explicit permissions in Agent Cards

Anti-Pattern 4: Agent Card Bloat

Problem: Exposing too much metadata, internal URLs, sensitive info
Impact: Privacy leaks, attack surface
Solution: Minimal Agent Cards, .squadignore, review cards regularly

Anti-Pattern 5: Manual Discovery

Problem: Developers manually configure squad endpoints
Impact: Stale configs, broken connections
Solution: Auto-discovery (local registry), zero manual config

Team Guidelines

When to Use A2A

✅ Multi-repo projects (microservices, monorepo split)
✅ Breaking changes coordination
✅ Shared technology decisions
✅ Cross-cutting initiatives (security, performance)
✅ Dependency version tracking

❌ Single-repo projects (no value, adds complexity)
❌ Sensitive data exchange (use secure channels)
❌ High-frequency updates (use webhooks, not polling)

Best Practices

1. Document Decisions: Write .squad/decisions/ docs before broadcasting
2. Version Agent Cards: Include version in card for compatibility
3. Test Locally First: Verify A2A setup with 2 squads before org rollout
4. Monitor Health: Run squad health --all daily in CI
5. Audit Logs: Review A2A audit logs weekly for anomalies
6. Rotate Certs: Automate TLS cert rotation (every 90 days)
7. Progressive Disclosure: Start with local discovery, expand to network when needed

Deliverables

• Pattern library document (Markdown)
• Example workflows (scripts + docs)
• Anti-pattern catalog
• Team playbook
• Video tutorials (5-10 min each)
• Sample repositories (demo multi-repo setup)
• Integration with docs site

Success Criteria

• 5+ patterns documented with examples
• 80% of multi-repo teams using at least 1 pattern
• Zero incidents from anti-patterns after 3 months
• Playbook rated >4/5 by users

Timeline

4 weeks (iterative, based on early adopter feedback)