[Feature Request] Multi-repository / microservice spec management

[alfred-openspec]

Problem

Teams working with microservice architectures maintain separate repositories for frontend, backend, and other services. A single feature or change often spans multiple repos, creating several challenges:

1. Where should specs live? When a spec cannot be mapped to a specific repo, there is no clear home for it.
2. Agent awareness: If specs live in an independent "pure" spec repository, agents need to know which code repositories are relevant to each change spec.
3. Cross-repo consistency: Specs may differ per repo, so centralizing them does not fully solve the problem.

User Story

"To a significant degree, we work with microservice-based projects and usually maintain separate repositories for frontend and backend. This makes it difficult for us to map a feature / change to one specific repository."

"Where should the spec be maintained when it can't be mapped to a specific repo?"

"If the specs live in an independent, 'pure' spec repository, how do we teach the agent which repositories are relevant should this be part of the change spec?"

— Martin.KvL (Discord, team at rio.cloud using OpenSpec in production across greenfield + brownfield projects)

Current Workarounds

• Create a separate repo or workspace that teams work out of
• Use custom research skills within teams, included in the top-level project repo, to point agents at relevant code repos

Proposed Considerations

• First-class support for a centralized spec repo that references multiple code repos
• Spec-level metadata linking to relevant repositories
• Agent tooling that can resolve cross-repo references and apply changes across repos from a single spec
• Support for per-repo spec variants when a feature manifests differently across services

Related

• Collaboration & Orchestration #435 (Collaboration & Orchestration)
• [Proposal] Add hierarchical spec structure support #662 (Hierarchical spec structure support)
• Nested Specs #594 (Nested Specs)

[1code-async]

Task completed.

The enrichment comment has been posted on issue #725. Here's a summary of what was included:

Key findings:

1. Existing internal exploration — The codebase already contains a 680+ line workspace-architecture.md exploration document that evaluates four models (Flat, Nested, Distributed, Hybrid) for multi-repo spec management. Model D (Hybrid) is the recommended direction and closely matches what the issue requests.

2. Extension points identified — The existing metadata.sourcePath field in the spec schema, ProjectConfigSchema, and .openspec.yaml change metadata all provide natural extension points for adding multi-repo support.

3. Related issue cluster — Five related open issues ([Proposal] Add hierarchical spec structure support #662, Nested Specs #594, Collaboration & Orchestration #435, [Feature Request] Allow configurable OpenSpec directory name #581, Feedback: Support custom openspec/ directory path #697) form a coherent cluster. A natural implementation order was suggested: hierarchical specs → configurable paths → multi-repo workspace.

4. Open design questions — Surfaced the five key design decisions from the exploration that this issue could help resolve.

5. Not a duplicate — Confirmed this is distinct from existing issues, targeting the unique coordination problem of multi-repository spec management.

Comment: #725 (comment)

---

View full conversation

Powered by 1Code

[1code-async]

Issue Enrichment: Codebase Context & Related Work

Existing Exploration

This feature request aligns closely with work already explored internally. The workspace architecture exploration (openspec/explorations/workspace-architecture.md) is a 680+ line document that directly addresses the multi-repo question raised here. It evaluates four models:

Model	Description	Multi-Repo Fit
A: Flat Root (current)	All specs in one openspec/specs/	Single repo only
B: Nested Specs	Domain → platform hierarchy	Monorepo-friendly
C: Distributed Specs	Each repo has its own openspec/	Multi-repo native, but cross-cutting specs are awkward
D: Hybrid (recommended)	Nested specs within each project + workspace manifest for cross-repo coordination	Best fit for the use case described in this issue

Model D specifically proposes a workspace.yaml manifest and per-initiative links.yaml to coordinate changes across repos — which is essentially what @alfred-openspec and Martin.KvL are requesting:

~/work/
├── contracts/
│   └── openspec/
├── billing-service/
│   └── openspec/
├── web-client/
│   └── openspec/
└── payments-workspace/
    └── .openspec-workspace/
        ├── workspace.yaml          # Lists all project roots
        └── initiatives/add-3ds/
            └── links.yaml          # Maps initiative → per-repo changes

Current Extension Points

Several existing schema fields and config structures could serve as foundations:

• metadata.sourcePath in src/core/schemas/spec.schema.ts:13 — an optional field on specs that's defined but currently unused. Could be extended to reference external repos.
• ProjectConfigSchema in src/core/project-config.ts:19-41 — currently supports schema, context, and rules. A natural place to add workspace/repo references.
• .openspec.yaml change metadata — currently only stores schema and created. Could be extended with cross-repo linking fields.
• Context injection (project config context field) — already allows injecting shared knowledge into all AI prompts, which is the manual version of what "agent awareness of relevant repos" would formalize.

Related Issues (Cluster Analysis)

This issue sits within a cluster of related open requests:

Issue	Title	Relationship
#662	[Proposal] Hierarchical spec structure support	Prerequisite — nested spec paths are needed before multi-repo can work cleanly. Has a detailed proposal and references PR #660.
#594	Nested Specs	The user-facing pain point that #662 formalizes.
#435	Collaboration & Orchestration	Multi-user workspaces and multi-agent orchestration — foundational for cross-repo team workflows.
#581	Allow configurable OpenSpec directory name	Relevant for repos that want openspec/ at non-standard paths (monorepo subdirectories, etc.).
#697	Support custom openspec/ directory path	Same concern — relocating openspec/ for monorepo cleanliness.

A natural implementation order would be: #662 (hierarchical specs) → #581/#697 (configurable paths) → #725 (multi-repo workspace).

Open Design Questions (from exploration)

The workspace exploration explicitly defers these decisions, which this issue could help resolve:

1. Where do shared/cross-cutting specs live? Dedicated "contracts" repo, duplicated per-repo, or one repo as source of truth?
2. Where do cross-repo changes live? In one repo (biased ownership), a separate workspace repo, or user-level config?
3. How do changes propagate? Explicit dependency tracking between specs, or out-of-band team coordination?
4. What's a "workspace" vs "project"? Explicit tracked concept, or ad-hoc multi-root (like Claude Code's /add-dir)?
5. Does OpenSpec need dependency tracking? Auto-warn when upstream contract changes, or keep it simple?

Suggested Starting Points for Contributors

1. Read the exploration: openspec/explorations/workspace-architecture.md — covers the design space comprehensively.
2. Schema extension: Start with ProjectConfigSchema in src/core/project-config.ts to prototype a workspace or repos field.
3. Spec metadata: Extend SpecSchema in src/core/schemas/spec.schema.ts — the existing metadata.sourcePath could become metadata.sourceRepo.
4. Resolve [Proposal] Add hierarchical spec structure support #662 first: Hierarchical spec support is a likely prerequisite, as multi-repo specs naturally form a hierarchy.

Not a Duplicate

This is not a duplicate of any existing issue. While #662 and #594 address spec organization, and #435 addresses collaboration, this issue uniquely focuses on the multi-repository coordination problem — where specs live when work spans repos, and how agents discover relevant code repositories. It represents a distinct feature area that builds on top of the others.