A product manager walks in with one new feature: discount codes at checkout. It sounds small until we notice it touches order-service, pricing-service, and probably notification-service. Three services, three repos, three sets of reviewers. So here is the question: where does the spec live?
That is exactly the wall I hit when I first rolled out OpenSpec multi-repo work in a microservices environment. This article is a field report: the first approach that wore me out, and the pattern I have stuck with since, which is an umbrella repo plus git submodules plus git worktrees. With it, one feature from the PM becomes one proposal that can be implemented in parallel across many services.
Note: the pattern here is my personal recommendation from working on microservice teams, not an official OpenSpec feature. The official multi-repo features are Stores and Worksets, which are still in beta at the time of writing. The examples were run with OpenSpec CLI v1.16.x and Go 1.23+ services.
What we will cover
- A short take on Spec-Driven Development (SDD) and why it matters with AI coding agents
- What OpenSpec is and how its loop works
- Why SDD gets awkward once our services are spread over many repos
- The umbrella repo + submodules + worktrees architecture
- The end-to-end workflow for one cross-service change, from
exploretoarchive - Ground rules, gotchas, and the downsides of SDD for microservices
Prerequisites
- Node.js 22.12+ and the OpenSpec CLI (
npm install -g @fission-ai/openspec@latest) - Git 2.30+ (we need
submoduleandworktree) - An AI coding tool that OpenSpec supports. The examples use Claude Code
- GitHub CLI (
gh) to open PRs from the terminal - Basic microservices knowledge. If that is new, start with SDD for Go microservices
What is Spec-Driven Development (SDD)?
Spec-Driven Development (SDD) is a way of working where we and our AI agent agree on what to build as a written specification, and only then does the AI write the how. The spec lives in Git, gets reviewed like code, and is re-read by the agent in later sessions.
Why bother? AI agents are fast, and they are also very literal. When requirements live only in chat history, the output often “works” while missing the intent. Close the session and the context is gone.
flowchart LR
subgraph Vibe["Vibe coding"]
V1["Prompt in chat"] --> V2["AI writes code"]
V2 --> V3["Works, but is it what we meant?"]
V3 -->|"re-prompt"| V1
end
subgraph SDD["Spec-Driven Development"]
S1["Agree on the spec"] --> S2["Human reviews the spec"]
S2 --> S3["AI implements against the spec"]
S3 --> S4["Spec stays in Git as the source of truth"]
end
style S1 fill:#f0f4ff,stroke:#4f6ef7
style S4 fill:#f0f4ff,stroke:#4f6ef7
Diagram 1: vibe coding loops inside the chat, while SDD puts the agreement in a file we can review.
The analogy that works for me: SDD is like writing the API contract before writing the handler. We stop arguing about code and start arguing about behavior.
What is OpenSpec?
OpenSpec is a lightweight, open source SDD tool. It keeps specifications in an openspec/ folder inside the repo, and every modification is written as a change containing a proposal, delta specs, a design, and a task list.
Three things make it a good fit for systems that already exist:
- Built for brownfield. We do not have to spec the whole system up front. We write specs only for what we are about to change, and
openspec/specs/grows over time. - Delta specs. A change holds only what is added (
ADDED), modified (MODIFIED), or removed (REMOVED). When the change is archived, the deltas merge into the main specs. - Cross-tool. The commands run in many AI coding tools, so the team is not locked into one editor.
OpenSpec folder structure
1openspec/
2├── config.yaml # project context + rules for the AI
3├── specs/ # main specs: what the system does today
4│ └── orders/spec.md
5└── changes/
6 ├── add-order-discount/ # one active change
7 │ ├── proposal.md # why and what
8 │ ├── specs/ # delta specs
9 │ ├── design.md # how (only when needed)
10 │ └── tasks.md # checklist the agent works through
11 └── archive/ # finished changesHow OpenSpec works: the five-step loop
flowchart LR
E["explore
discuss, no code"] --> P["propose
create the change folder"]
P --> R{"human review
approved?"}
R -->|"revise"| P
R -->|"yes"| A["apply
AI works through tasks.md"]
A --> AR["archive
merge deltas into specs"]
style P fill:#f0f4ff,stroke:#4f6ef7
style A fill:#f0f4ff,stroke:#4f6ef7
style AR fill:#f0f4ff,stroke:#4f6ef7
Diagram 2: the OpenSpec loop. A human holds the review gate before a single line of code is written.
One beginner trap worth remembering: openspec ... commands run in the terminal, while /opsx:... commands run in the AI chat.
Why is OpenSpec multi-repo hard with microservices?
OpenSpec is centered on a single project root by default. In a monolith or a monorepo, that is fine. With microservices, each service has its own repo, CI, and PRs, and that is where the story starts.
My first attempt: one OpenSpec per repo
I started with the most obvious setup: every service repo had its own openspec/ folder with its own proposals. For discussion, I wrote a Technical Requirement Document (TRD) by going through each service one at a time, then stitched the pieces into a single document I could present to the team and the lead.
It worked, and it was exhausting:
- I had to open each service repo and run
/opsx:explorein every one of them just to understand where that service stood. - Planning a new feature also happened per service, and I was the glue between the documents.
- Whenever the PM brought a feature that touched more than two services, the assessment had to be repeated in each service separately. That is where the time went, not into design.
flowchart TD
PM["PM: one new feature"] --> A1["Open order-service
run explore"]
PM --> A2["Open pricing-service
run explore"]
PM --> A3["Open notification-service
run explore"]
A1 --> D1["Proposal in order-service"]
A2 --> D2["Proposal in pricing-service"]
A3 --> D3["Proposal in notification-service"]
D1 --> M["Manually merge into one TRD"]
D2 --> M
D3 --> M
M --> T["Present to team and lead"]
style M fill:#fff4e5,stroke:#f59e0b
Diagram 3: the per-repo approach. The yellow node is the manual work that eats the most time.
The idea that changed how I work
That led to the idea: one feature from the PM should be one OpenSpec proposal, even when the implementation is spread across many repos. I run /opsx:explore once in a single root folder, and the AI helps me trace every service related to the feature. The result is one proposal (or a few) that can be implemented in parallel in each microservice.
The payoff grows with the number of services and with how tightly they depend on each other.
Three options and their trade-offs
| Option | Where specs live | Upside | Downside |
|---|---|---|---|
| OpenSpec per repo | In each service | Simple, each team is independent | Cross-service features get fragmented, explore is repeated, the TRD is merged by hand |
| Stores + Worksets (official) | A separate planning repo | Supported by OpenSpec itself | Still beta; commands and file formats may change between releases |
| Umbrella repo + submodules + worktrees | In the umbrella repo | Plain Git, stable, one explore for every service | The team needs submodule discipline |
I went with the third option because it relies only on Git, which everyone already understands.
Architecture: umbrella repo + submodules + worktrees
The idea: one umbrella repo holds the specs and points at the service repos through submodules. Specs and changes live at the root; code stays in each service repo. Worktrees come in when several changes run in parallel.
graph TD
U["platform (umbrella repo)"] --> O["openspec/
specs + changes for all services"]
U --> S1["services/order-service
git submodule"]
U --> S2["services/pricing-service
git submodule"]
U --> W["services/worktree/
git-ignored"]
W --> C1["add-order-discount/order-service
branch feat/add-order-discount"]
W --> C2["add-order-discount/pricing-service
branch feat/add-order-discount"]
S1 -.->|"worktree of"| C1
S2 -.->|"worktree of"| C2
style U fill:#f0f4ff,stroke:#4f6ef7
style O fill:#f0f4ff,stroke:#4f6ef7
Diagram 4: the umbrella repo holds only specs and pointers. The code still belongs to the service repos.
1platform/ # umbrella repo: specs + pointers
2├── openspec/
3│ ├── config.yaml
4│ ├── specs/
5│ │ ├── order-service/orders/spec.md
6│ │ └── pricing-service/discounts/spec.md
7│ └── changes/
8│ └── add-order-discount/ # deltas for BOTH services
9├── services/
10│ ├── order-service/ # git submodule (own repo, CI, PRs)
11│ ├── pricing-service/ # git submodule
12│ └── worktree/ # git-ignored, only for parallel changes
13│ └── add-order-discount/
14│ ├── order-service/ # worktree on feat/add-order-discount
15│ └── pricing-service/ # worktree on feat/add-order-discount
16├── .gitmodules
17├── .gitignore # contains: services/worktree/
18└── CLAUDE.md| Part | Holds | Rule |
|---|---|---|
openspec/ | Every service’s specs + cross-service changes | Capabilities are prefixed with the service name: order-service/orders |
services/<service>/ | Submodule, each service’s main checkout | Always points at a commit already merged in that service |
services/worktree/<change>/<service>/ | One worktree per change per service | Used when more than one change runs at once, removed after merge |
The workflow for one cross-service change
Before the commands, here is the big picture.
flowchart TD
X["/opsx:explore at the umbrella root
AI scans every related service"] --> P["/opsx:propose
one change, deltas per service"]
P --> R{"Review and merge proposal
to umbrella main"}
R --> W["Create one worktree
per touched service"]
W --> A["/opsx:apply
agent edits only this change's worktrees"]
A --> PR["One PR per service repo
same branch name"]
PR --> M["Merge services
backward compatible one first"]
M --> U["Umbrella PR
bump submodule pointers + archive"]
U --> C["Remove worktrees"]
style X fill:#f0f4ff,stroke:#4f6ef7
style P fill:#f0f4ff,stroke:#4f6ef7
style R fill:#f0f4ff,stroke:#4f6ef7
style U fill:#f0f4ff,stroke:#4f6ef7
Diagram 5: blue nodes happen in the umbrella repo; the rest happen in the service repos.
sequenceDiagram
participant Dev as Developer
participant Agent as AI Agent
participant Umbrella as Umbrella Repo
participant Pricing as pricing-service Repo
participant Order as order-service Repo
Dev->>Agent: /opsx:explore add order discount
Agent->>Umbrella: Read openspec/ and services/*
Agent-->>Dev: Affected services and options
Dev->>Agent: /opsx:propose add-order-discount
Agent->>Umbrella: Write proposal, delta specs, design, tasks
Dev->>Umbrella: Review and merge proposal PR
Dev->>Agent: /opsx:apply add-order-discount
Agent->>Pricing: Commit on feat/add-order-discount
Agent->>Order: Commit on feat/add-order-discount
Dev->>Pricing: Merge PR first
Dev->>Order: Merge PR second
Dev->>Umbrella: Bump submodule pointers and archive
Diagram 6: how the developer, the agent, the umbrella repo, and the service repos interact for one change.
Step-by-step implementation
1. Set up the umbrella repo and submodules
We do this once per platform.
1mkdir platform && cd platform && git init -b main
2
3# Register each service as a submodule tracking its main branch
4git submodule add -b main https://github.com/<org>/order-service.git services/order-service
5git submodule add -b main https://github.com/<org>/pricing-service.git services/pricing-service
6
7# Worktrees are a working tool, never part of the umbrella history
8echo "services/worktree/" >> .gitignore
9
10openspec init --tools claude
11git add -A && git commit -m "chore: umbrella repo with service submodules"
12
13# Make git pull/switch update submodules too
14git config submodule.recurse trueTeammates clone it with one command:
1git clone --recurse-submodules https://github.com/<org>/platform.git2. Teach the agent the multi-repo layout
The agent has no idea that services/ contains other repos unless we say so. Two files do the job: openspec/config.yaml and CLAUDE.md.
1# openspec/config.yaml
2schema: spec-driven
3
4context: |
5 Umbrella repo. Specs live in openspec/; code lives in git submodules under services/:
6 services/order-service (Go, orders API), services/pricing-service (Go, pricing API).
7 One change may touch several services. Capabilities are named <service>/<area>,
8 e.g. order-service/orders. Each service has its own repo, CI, and PR.
9
10rules:
11 design:
12 - 'File change paths start with services/<service>/. Add a "Merge order" section:
13 which service merges first, and why that order stays backward compatible.'
14 tasks:
15 - 'Group tasks per service: "## 1. pricing-service", "## 2. order-service",
16 then Tests and Review. Every task names its service.'1<!-- CLAUDE.md -->
2## Multi-repo rules
3
4- Code for a change lives in services/worktree/<change>/<service>/ when that folder exists,
5 otherwise in services/<service>/. Never edit another change's worktree.
6- Commit and push inside each service; each service gets its own PR on feat/<change>.
7- The umbrella only commits openspec/ and submodule pointers. Never commit inside
8 services/worktree/ from the umbrella.The Merge order rule in design.md looks minor. It is what saves us from deployments waiting on each other.
3. Run explore from the umbrella root
This replaces the “open every repo one by one” ritual. From the umbrella root:
1/opsx:explore
2PM wants discount codes at checkout. Which services are affected,
3what contracts change, and what is the smallest safe increment?Because every service sits under services/, the agent can read the handlers in order-service, the pricing rules in pricing-service, and the existing specs in openspec/specs/ in one session. explore writes no files. The output is understanding and options, which doubles as the material we present to the team and the lead, with no document stitching across three repos.
4. Create one proposal for several services
1/opsx:propose add-order-discount
2Orders (order-service) accept a discount code; pricing (pricing-service) validates it.
3Deltas on order-service/orders and pricing-service/discounts.
4Keep both APIs backward compatible.We get one change folder holding the deltas for both services:
1openspec/changes/add-order-discount/
2├── proposal.md
3├── specs/order-service/orders/spec.md # MODIFIED: create order accepts discountCode
4├── specs/pricing-service/discounts/spec.md # ADDED: validate discount code
5├── design.md # file changes per service + Merge order
6└── tasks.md # 1. pricing-service 2. order-service 3. Tests 4. ReviewA sample delta spec for pricing-service:
1## ADDED Requirements
2
3### Requirement: Validate discount code
4The pricing service SHALL validate a discount code against an order subtotal
5and return the discount amount.
6
7#### Scenario: Valid code
8- **WHEN** a request contains an active code and a subtotal above the minimum spend
9- **THEN** the service returns the discount amount and HTTP 200
10
11#### Scenario: Expired code
12- **WHEN** a request contains a code past its expiry date
13- **THEN** the service returns HTTP 422 with reason `DISCOUNT_EXPIRED`Merge the proposal into the umbrella’s main first, as a small PR containing only openspec/. That way the spec review happens before any code exists, and other changes can run in parallel on top of it.
5. Create a worktree per change
Create one worktree for each service the change touches. The branch name is the same in every service: feat/<change>.
1C=add-order-discount
2for s in order-service pricing-service; do
3 git -C services/$s fetch origin
4 # New branch feat/$C from origin/main, checked out in its own folder
5 git -C services/$s worktree add -b feat/$C ../worktree/$C/$s origin/main
6done
7
8ls services/worktree/$C # order-service pricing-serviceWhy worktrees instead of checking out a branch in the submodule? Because as soon as two changes run at once, two agent sessions fight over the same working directory. With worktrees, each change gets its own folder and nothing gets overwritten.
6. Run apply
Run it from the umbrella root, one agent session per change:
1/opsx:apply add-order-discount
2Code for this change lives only in services/worktree/add-order-discount/.
3Follow the Merge order in design.md.7. Open PRs per service, follow the merge order, bump submodule pointers
1C=add-order-discount
2
3# Follow the Merge order from design.md: pricing-service first
4for s in pricing-service order-service; do
5 git -C services/worktree/$C/$s push -u origin feat/$C
6 (cd services/worktree/$C/$s && gh pr create --fill --title "feat: $C")
7done
8
9# After BOTH service PRs are merged:
10git -C services/order-service pull origin main
11git -C services/pricing-service pull origin main
12
13git switch -c chore/archive-$C
14openspec archive $C --yes
15git add openspec services/order-service services/pricing-service # new submodule pointers
16git commit -m "chore: archive $C and bump order-service, pricing-service"
17gh pr create --fill8. Clean up the worktrees
1for s in order-service pricing-service; do
2 git -C services/$s worktree remove ../worktree/$C/$s
3 git -C services/$s branch -d feat/$C
4doneA real example: discount codes in Santekno Shop
Here is why the merge order matters. order-service will call a new endpoint in pricing-service. If order-service ships first, it calls an endpoint that does not exist yet.
So design.md says: pricing-service merges first (the new endpoint is additive, no consumer breaks), then order-service. On the order-service side, the new field is optional so existing clients keep working:
1package order
2
3// CreateOrderRequest is the payload for POST /orders.
4// DiscountCode is optional so existing clients keep working unchanged.
5type CreateOrderRequest struct {
6 UserID string `json:"userId"`
7 Items []OrderItem `json:"items"`
8 DiscountCode *string `json:"discountCode,omitempty"`
9}
10
11// OrderItem is a single product line in an order.
12type OrderItem struct {
13 ProductID string `json:"productId"`
14 Quantity int `json:"quantity"`
15}
16
17// HasDiscount reports whether the client sent a non-empty discount code.
18func (r CreateOrderRequest) HasDiscount() bool {
19 return r.DiscountCode != nil && *r.DiscountCode != ""
20}The lifecycle of the change looks like this:
stateDiagram-v2
[*] --> Explored: /opsx explore at umbrella root
Explored --> Proposed: /opsx propose
Proposed --> Approved: proposal PR merged to umbrella main
Approved --> InProgress: worktrees created, /opsx apply
InProgress --> PricingMerged: pricing-service PR merged
PricingMerged --> OrderMerged: order-service PR merged
OrderMerged --> Archived: bump pointers, openspec archive
Archived --> [*]
Diagram 7: the states of a cross-service change. Archiving happens only after every service PR is merged.
Meanwhile, if the PM brings a second feature, say add-shipping-estimate, we create a new set of worktrees under services/worktree/add-shipping-estimate/ and start a second agent session. Two changes, two sets of folders, nobody steps on anybody.
Ground rules
| Rule | Why |
|---|---|
| One change = one branch with the same name in every service | The order-service and pricing-service PRs are easy to trace through the change name |
| Merge services first, then the umbrella | A submodule pointer may only point at a commit already on the service’s main |
API changes must be backward compatible; the merge order is written in design.md | Services deploy separately; there is no atomic cross-repo deploy |
| Archive in the umbrella after every service PR is merged | Main specs describe only what is really running |
services/worktree/ is git-ignored and removed when done | Worktrees are a working tool, not part of the umbrella’s history |
Tips & gotchas
| Symptom | Fix |
|---|---|
services/order-service is empty after cloning | git submodule update --init --recursive |
| The submodule is in detached HEAD | Normal for submodules. Work in the feat/<change> worktree, or git -C services/order-service switch main |
fatal: 'feat/x' is already checked out | Another worktree uses that branch. Check git -C services/order-service worktree list |
Umbrella git status shows modified: services/order-service (new commits) | The pointer moved. Commit it only after the service PR is merged |
A few more things I learned the hard way:
- Never commit a submodule pointer to an unmerged commit. Once the service branch is rebased or squashed, the umbrella points at a commit that no longer exists.
- Pin the OpenSpec CLI version in team docs and CI. OpenSpec ships very often. Upgrade on purpose, not by accident.
- Write
contextinconfig.yamllike onboarding a new engineer. Name the language, each service’s responsibility, and who calls whom. The quality ofexploredepends heavily on it. - Small proposals get approved faster. If a feature is too big, split it into several changes that can run in parallel.
When this pattern is the wrong fit
- We already have a monorepo. Stock OpenSpec is enough; no umbrella needed.
- Only one or two services that rarely interact. The submodule overhead is not worth it. OpenSpec per repo is still reasonable.
- A feature that calls a system owned by another team. What we need there is a contract between teams, not access to their code. See the contract-first approach in SDD for Go microservices .
- The team is not comfortable with submodules yet. Take time to get used to them first, or evaluate Stores and Worksets once they leave beta.
The downsides of SDD for microservices
To be fair, none of this is free. Here are the drawbacks of SDD in a microservices setup that we should be aware of before adopting it:
- Overhead for small changes. A proposal, delta specs, a design, and tasks are too much for a one-line bug fix or a config tweak. Without an agreed rule for which changes must go through a spec, the team soon feels the process is slowing them down.
- Spec drift still happens. A hotfix pushed straight to a service repo never passes through the umbrella, so the main specs quietly fall behind the code. More services means more doors for drift. It takes discipline or automated checks; see spec drift detection .
- No atomicity across repos. The spec is one change, but merges and deploys stay separate per service. If the
pricing-servicePR is merged while theorder-servicePR is stuck in review, the system sits in a half-finished state and the change cannot be archived yet. - Review becomes the new bottleneck. A cross-service proposal has to be read by the owner of every service. AI also produces long documents easily, and a spec approved without really being read is worse than no spec, because it gives a false sense of safety.
- Context and token cost. Running
exploreat the root means the agent reads many services at once. With dozens of services, sessions get expensive and the analysis can degrade if thecontextinconfig.yamldoes not steer the agent toward the relevant ones. - Access and ownership. The umbrella repo requires read access to every service repo. In organizations with access boundaries between teams, that may not be allowed. It also has to be clear who owns the umbrella and who can approve proposals.
- A spec is not a contract test. Writing “backward compatible” in
design.mdenforces nothing at runtime. Contracts between services still need contract testing and CI in each service. - The tooling moves fast. OpenSpec ships very often and its official multi-repo features are still beta. The submodule + worktree pattern also adds Git friction that everyone on the team has to learn.
None of these cancel the benefits, but all of them are real. My rule of thumb: use SDD for changes that alter behavior or a contract between services, and let small changes go through the normal PR path.
Conclusion
Running OpenSpec multi-repo in a microservices setup is less about extra tooling and more about choosing the right home for the specs. With an umbrella repo, submodules, and worktrees, one feature from the PM becomes one proposal, /opsx:explore runs once from the root, and the implementation proceeds in parallel in each service with its own PR and CI.
For me the biggest shift was at the start of the cycle: the time I used to spend opening repos one by one and stitching documents together now goes into discussing the design.
Further reading on Santekno:
- SDD for Go microservices: API contracts between services to understand service contracts
- The SDD tools ecosystem in 2026 to compare OpenSpec with other tools
- Spec drift detection so specs and code do not quietly part ways
- SDD in a team for reviewing specs together
Official references: the OpenSpec documentation and the Fission-AI/OpenSpec repo .