Multi-Repo Orchestration: Enhance Product + Architect Extensions + New Orchestrate Extension

[kanfil]

Multi-Repo Orchestration for Spec-Kit

Problem Statement

Enterprise features span multiple repositories (microservices, shared libraries, infrastructure repos). Current SDD tools keep specs co-located with code in a single repository, creating three critical gaps:

1. Where does the spec live? No coherence across repo boundaries.
2. Who decomposes the work? Architects must manually break stories into repo-specific sub-issues.
3. How do you track progress? Business context gets lost when scattered across repos.

This aligns with the challenges identified in InfoQ's "Spec-Driven Development – Adoption at Enterprise Scale", particularly the "Mono-Repo Focus" and "Lack of Separation of Concerns" gaps.

Proposed Solution

Three workstreams that build on each other:

---

Workstream 1: Enhance Product Extension

Add multi-repo PRD/PDR awareness and decomposition:

• Multi-Repo PRD Location Strategy — PRD can live in an orchestrator repo, distributed across repos, or in team-ai-directives
• Repository Mapping Section in PRD template — maps feature areas to responsible repos with dependencies
• Cross-Repo Product Validation — new validation pass (Pass H) to verify feature specs in child repos align with parent PRD, detect scope creep, validate persona consistency

Files to modify:

• extensions/product/extension.yml
• extensions/product/config-template.yml
• extensions/product/commands/implement.md
• extensions/product/commands/validate.md
• extensions/product/commands/analyze.md
• extensions/product/templates/prd-template.md
• extensions/product/scripts/bash/setup-product.sh

---

Workstream 2: Enhance Architect Extension

Add multi-repo architecture context and cross-repo ADR management:

• Multi-Repo Architecture Registry — repo registry with responsibilities and integration patterns
• Cross-Repo ADR Management — detect conflicting decisions across repos (e.g., one repo uses PostgreSQL, another MongoDB without justification)
• Multi-Repo Architecture Description — AD.md with repository topology view, cross-repo integration patterns, shared concerns
• Enhanced Analysis — Pass H (cross-repo ADR consistency), Pass I (integration pattern compliance), Pass J (shared dependency coherence)

Files to modify:

• extensions/architect/extension.yml
• extensions/architect/config-template.yml
• extensions/architect/commands/init.md
• extensions/architect/commands/specify.md
• extensions/architect/commands/analyze.md
• extensions/architect/templates/AD-template.md
• extensions/architect/templates/feature-AD-template.md
• extensions/architect/scripts/bash/setup-architect.sh

---

Workstream 3: Create Orchestrate Extension (New Bundled Extension)

New extension for cross-repo feature lifecycle management:

Commands

Command	Purpose
/orchestrate.init	Initialize multi-repo orchestration with repo registry and architecture context
/orchestrate.decompose	Decompose a parent spec into per-repo child specs and branches
/orchestrate.status	Show cross-repo feature progress dashboard
/orchestrate.sync	Propagate parent spec changes to affected child specs
/orchestrate.complete	Verify all child specs implemented and integration tests pass

Key Artifacts

• .specify/orchestration/repos.yml — Registry of participating repos with paths/URLs, branches, responsibilities
• .specify/orchestration/architecture-context.yml — Integration patterns, constraints, communication protocols
• specs/###-feature-name/orchestration.md — Parent orchestration spec with repo decomposition, dependency graph, integration points
• Child specs — Full spec-kit artifacts in each repo with parent_ref linking back

Workflow

1. /orchestrate.init          → Set up repo registry + architecture context
2. /spec.specify "feature"    → Create parent spec.md
3. /orchestrate.decompose     → AI generates orchestration.md, creates child branches + specs
4. Developer works each repo  → /spec.plan, /spec.tasks, /spec.implement per repo
5. /orchestrate.status        → Cross-repo progress dashboard
6. /orchestrate.sync          → Propagate parent changes to children (if needed)
7. /orchestrate.complete      → Verify all merged, integration tests pass, close feature

Extension Structure

extensions/orchestrate/
├── extension.yml
├── README.md
├── config-template.yml
├── commands/
│   ├── init.md
│   ├── decompose.md
│   ├── status.md
│   ├── sync.md
│   └── complete.md
├── templates/
│   ├── repos-config-template.yml
│   ├── architecture-context-template.yml
│   ├── orchestration-template.md
│   └── child-spec-header.md
└── scripts/
    ├── bash/
    │   ├── setup-orchestrate.sh
    │   ├── decompose-feature.sh
    │   ├── sync-changes.sh
    │   └── check-status.sh
    └── powershell/
        └── (equivalents)

Hooks & Handoffs

• Hook on after_spec: Prompt for decomposition when orchestration is configured
• Hook on after_implement: Verify cross-repo completeness
• Handoff to product.specify: Define cross-repo product scope
• Handoff to architect.specify: Define multi-repo architecture
• Handoff to levelup.specify: Extract cross-repo patterns after completion

---

Integration with Existing Extensions

Extension	Integration
Product	orchestrate.init → product.specify for cross-repo PRD; PRD includes repo mapping
Architect	orchestrate.init → architect.specify for multi-repo AD; ADRs reference repos
LevelUp	orchestrate.complete → levelup.specify for cross-repo pattern extraction
Jira/Linear	orchestrate.decompose creates parent issue + sub-issues per repo
Core spec-kit	Hooks on after_spec and after_implement; child specs use full spec-kit workflow

---

Implementation Order

1. Product extension enhancements (Workstream 1)
2. Architect extension enhancements (Workstream 2)
3. Orchestrate extension (Workstream 3)
4. Update cli_customization.py — add orchestrate to bundled extensions
5. Update catalog.json — register new extension
6. Documentation — README for orchestrate extension, update main README

---

Design Decisions

Decision	Rationale
Parent spec stays in orchestrator repo	Single source of truth for business intent
Child specs are full spec-kit artifacts	Each repo maintains its own context — no loss of local detail
Architecture context separate from feature specs	Evolves at different pace; matches InfoQ separation-of-concerns principle
Decomposition is AI-assisted, not automatic	Architect reviews and approves before child specs are created
Works with monorepos too	path: entries for local repos, url: for remote — same mechanism
No shared git state between repos	Each child repo is independent; orchestration metadata lives only in orchestrator repo