blue/docs/spikes/cross-repo-coordination.md

Spike: Cross-Repo Coordination

Status	Complete
Outcome	Recommends Implementation
RFC	0001-cross-repo-realms
Question	How can Blue sessions in different repos be aware of each other and coordinate changes when repos have dependencies?
Time Box	2 hours
Started	2026-01-24

---

Context

We have repos with cross-repo dependencies:

• aperture (training-tools webapp) - runs in Account A
• fungal-image-analysis - runs in Account B, grants IAM access to Account A

When changes are made in one repo (e.g., adding a new S3 path pattern), the corresponding changes must be made in the other (e.g., updating IAM policies).

Current Pain Points

1. No awareness - Blue session in repo A doesn't know repo B exists
2. No dependency graph - Changes to IAM policies don't trigger awareness of dependent services
3. Manual coordination - Developer must remember to update both repos
4. Planning blindness - RFCs in one repo can't reference or depend on RFCs in another

---

Research Areas

1. Dependency Declaration

How do we declare cross-repo dependencies?

Option A: Blue manifest file

# .blue/manifest.yaml
dependencies:
  - repo: ../fungal-image-analysis
    type: infrastructure
    resources:
      - cdk/training_tools_access_stack.py

Option B: In-document links

<!-- In RFC -->
| **Cross-Repo** | [fungal-image-analysis](../fungal-image-analysis) |

Option C: Centralized registry

# ~/.blue/repos.yaml (or domain-level DB)
repos:
  aperture:
    path: /Users/ericg/letemcook/aperture
    depends_on: [fungal-image-analysis]
  fungal-image-analysis:
    path: /Users/ericg/letemcook/fungal-image-analysis
    depended_by: [aperture]

2. Session Coordination

How do Blue sessions communicate?

Option A: Shared SQLite (domain store)

• All repos in a domain share a single .data/domain.db
• Sessions register themselves and their active RFCs
• Can query "who else is working on related changes?"

Option B: File-based signals

• Write .blue/active-session.json with current work
• Other sessions poll or watch for changes

Option C: IPC/Socket

• Blue MCP server listens on a socket
• Sessions can query each other directly
• More complex but real-time

3. Change Propagation

When a change is made in repo A that affects repo B, what happens?

Option A: Manual notification

⚠️ This change affects dependent repo: fungal-image-analysis
   - cdk/training_tools_access_stack.py may need updates
   Run: blue_cross_repo_check

Option B: Automatic RFC creation

• Detect affected files via dependency graph
• Create draft RFC in dependent repo
• Link the RFCs together

Option C: Unified worktree

• Create worktrees in both repos simultaneously
• Single branch name spans repos
• Coordinate commits

4. Planning Integration

How do cross-repo RFCs work together?

Requirements:

• RFC in repo A can declare dependency on RFC in repo B
• Status changes propagate (can't implement A until B is accepted)
• Plan tasks can span repos

Proposal:

| **Depends On** | fungal-image-analysis:rfc-0060-cross-account-access |
| **Blocks** | aperture:rfc-0045-training-metrics |

---

Findings

Key Insight: Domain-Level Store

The cleanest solution is a domain-level store that sits above individual repos:

~/.blue/domains/
  letemcook/
    domain.db          # Cross-repo coordination
    repos.yaml         # Repo registry
    sessions/          # Active sessions

This enables:

1. Single source of truth for repo relationships
2. Cross-repo RFC dependencies
3. Session awareness without IPC complexity
4. Centralized audit of cross-repo changes

Proposed Architecture

┌─────────────────────────────────────────────────────────┐
│                    Domain Store                          │
│  ~/.blue/domains/letemcook/domain.db                    │
│  - repos table (path, name, dependencies)               │
│  - cross_repo_links table (source_rfc, target_rfc)     │
│  - active_sessions table (repo, rfc, agent_id)         │
└─────────────────────────────────────────────────────────┘
           │                              │
           ▼                              ▼
┌─────────────────────┐      ┌─────────────────────┐
│     aperture        │      │ fungal-image-analysis│
│  .blue/blue.db      │      │  .blue/blue.db      │
│  docs/rfcs/         │      │  docs/rfcs/         │
└─────────────────────┘      └─────────────────────┘

New Tools Needed

1. blue_domain_init - Initialize domain, register repos
2. blue_domain_link - Link two repos as dependencies
3. blue_cross_repo_check - Check if changes affect other repos
4. blue_cross_repo_rfc - Create linked RFCs across repos

---

Outcome

Recommendation: Implement domain-level store with cross-repo RFC linking.

Next Steps:

1. Design domain store schema (new RFC)
2. Add domain detection to Blue startup
3. Implement cross-repo RFC dependencies
4. Add change impact detection

---

Notes

• Start simple: just repo registry + session awareness
• Don't over-engineer IPC - polling shared DB is sufficient
• Consider git worktree naming conventions that span repos