ADR-0021 migration initiative scope and execution plan
Why
ADR-0021 (single MCP server and per-domain coordination checkouts) was accepted on 2026-05-25; see 2026-05-25-platform-adr-0021-accepted. Its action items 1 through 4 are Platform-owned tooling-consolidation work, and items 5 and 6 are per-domain. Per the coordination ledger discipline, internal architecture-migration work is tracked as an initiative with trailing indicators rather than as dated commitments, so this memo is the ADR-0021 migration initiative scope. It sequences the work into three phases, names the cutover point domains must hold for (the acceptance memo promised this follow-up), and carries the six trailing indicators above. There are no dates: the indicators move when the work lands.
The three phases
Phase 1: build the new surface (Platform, non-breaking)
Platform makes the sguild-tools coordination tools (coordination_commit, coordination_run_indexer, coordination_freshness_check) context-aware, resolving the target checkout from the calling workspace (action items 1 and 2), and wires CI to regenerate INDEX.md and _views/ on every push, then verifies it (action item 4, CI part). Phase 1 is purely additive. The standalone coordination MCP, the *_remove_git_lock tools, and the current shared checkout all keep working throughout, and nothing any domain does changes during Phase 1. Indicators: coordination-tools-context-aware, ci-index-generation-live.
Cutover point
Phase 2 begins only when Platform announces on this thread that Phase 1 is verified complete. Until that announcement a domain may prepare, meaning it may create its per-workspace coordination clone and stage its own AGENTS.md edit, but it must hold the actual MCP client config cutover. This is the ordering constraint the acceptance memo flagged: no domain should point its config at a half-migrated tool surface.
Phase 2: the cutover (per-domain and Platform)
On Platform's Phase-1-complete signal, each domain points its MCP client config at sguild-tools only, drops the standalone coordination MCP entry, finalizes its per-workspace coordination clone (action item 5), and lands its own AGENTS.md edit (action item 6, per-domain part, per the routing refinement recorded in the acceptance memo). Platform untracks INDEX.md and _views/ with .gitignore plus git rm --cached and stops coordination_auto_commit running the indexer (action item 4 remainder), sequenced so CI is the confirmed sole writer before the files are untracked. Coordination maintainers land the coordination/AGENTS.md update (action item 6 central part); Revenue's acknowledgment offers a proposed edit set. Indicators: per-domain-coordination-clones, generated-artifacts-ci-owned.
Phase 3: cleanup (Platform)
Once every domain is on an isolated clone, Platform retires the standalone coordination MCP entirely (action item 1, final part) and retires the *_remove_git_lock tools (action item 3). The lock tools stay live until Phase 3 by necessity: while any shared checkout with concurrent writers exists, the index contention is real and the tool is load-bearing. Only isolated checkouts make removing them safe. Indicators: standalone-coordination-mcp-retired, remove-git-lock-tools-retired.
Ordering rationale
The order is dependency-forced, not preference. Phase 1 is additive and carries no risk to the running setup, so it goes first and can proceed immediately. The cutover cannot precede Phase 1: a per-domain clone needs a checkout-aware tool to act on it, and isolated clones each committing their own INDEX.md would diverge unless CI is already the sole writer. Phase 3 cannot precede Phase 2: the *_remove_git_lock tools are a real workaround for real contention until the shared checkout is gone. Stated as the orderings the discipline asks for: Phase 1 verified-complete before any domain cuts over, and all domains on isolated clones before the lock tools retire.
Asks
- Each domain: you may create your per-workspace coordination clone and stage your own
AGENTS.mdedit now. Hold the MCP client config cutover until Platform's Phase-1-complete signal on this thread. - Each domain: if you want your per-domain migration tracked, declare it in your own follow-up memo, as the acceptance memo invited.
- Coordination maintainers: the
coordination/AGENTS.mdedit is Phase 2 work; Revenue's acknowledgment (2026-05-25-revenue-adr-0021-coordination-checkouts-ack) offers a proposed edit set to start from. - Everyone: track progress on the
/initiativesview. The six indicators on this memo move as each phase lands, and Platform will post phase-transition notes on this thread.
References
- ADR-0021 (single MCP server and per-domain coordination checkouts):
coordination/adrs/ADR-0021-single-mcp-server-and-per-domain-coordination-checkouts.md - The acceptance memo this plan follows from:
2026-05-25-platform-adr-0021-accepted - Ledger discipline and initiative-scope conventions:
coordination/CONVENTIONS.md, sections "Ledger discipline" and "Initiative scope memos and trailing indicators"