Blueprint layer — bridging requirements documents to OpenSpec changes

[JiangWay]

Hi all,

I've been running OpenSpec on a production project for a while and wanted to share a pattern that keeps coming up. Curious if anyone else has run into the same thing.

TL;DR: When requirements are bigger than a single change, there's a gap between "I have a requirements doc" and "I have well-scoped OpenSpec changes." I'm experimenting with a blueprint layer that bridges this gap — a tracking file + LLM-assisted decomposition, without touching the existing change lifecycle. Would love to hear if others face this too, and what shape a solution should take.

---

The problem

OpenSpec's changes/ workflow is great for individual units of work: propose, apply, verify, archive. But when a real-world requirements document lands on your desk — say, "build an online shop" with 20+ features — the gap between that document and a set of well-scoped changes/ is entirely manual.

From running ~30 OpenSpec change cycles on a production project, three pain points keep surfacing:

1. Requirements-to-changes splitting is manual and error-prone

A requirements document (FRS-style) arrives as a single markdown file. Today, you read it, mentally decompose it into changes, figure out dependencies between them, and create each one by hand. For our first requirements doc (18 changes), this decomposition took multiple rounds of manual derivation — and we still missed dependency edges.

2. No "what should I work on next?" guidance

Once you have 18 todo items from a requirements doc, picking the right next change isn't obvious. You need to consider:

• Which changes have all their dependencies completed?
• What capability area am I currently working in? (context-switching between unrelated features is expensive)
• What was recently completed? (continuation signals)

Today this is gut feeling. It works at 5 changes; it doesn't at 20+.

3. State synchronization relies on discipline

After completing a change cycle (archive), you need to manually update the tracking document — flip an emoji, update counters, fix links. It's a 30-second task, but forgetting it once creates state drift that compounds. We've already hit this: an archived change still showing as "in-progress" in the tracker, discovered only when the numbers stopped adding up.

---

Proposed concept: Blueprints

A blueprint is a lightweight tracking document that sits between a requirements document and individual OpenSpec changes. Think of it as a "project board in a markdown file."

openspec/
├── specs/           ← what the system looks like (existing)
├── changes/         ← individual units of work (existing)
└── blueprints/      ← NEW: requirements → changes mapping
    ├── shop-init/
    │   └── requirement.md    ← original requirements doc
    └── shop-add-cart/
        └── requirement.md    ← original requirements doc

A blueprint file contains:

• Metadata: key, title, source requirements link, totals
• A table of changes with status (todo/in-progress/done), dependencies, capability grouping, and out-of-scope items
• Out-of-scope section: explicitly captures what was considered but deferred

Sample blueprint

---
key: shop-init
title: Online shop — initial build
status: active
totals: { todo: 12, in-progress: 1, done: 6 }
---

# shop-init blueprint

| ID  | Change                          | Status | Capability       | Depends |
|-----|---------------------------------|--------|------------------|---------|
| 001 | add-service-skeleton            | ✅     | service-skeleton | —       |
| 008 | narrow-product-catalog          | 🚧     | product-catalog  | 002,007 |
| 009 | add-checkout-flow               | 📋     | checkout-flow    | 008     |

## Out of scope
- International payments — deferred to future `shop-international` blueprint
- Mobile native app — not in this requirements document

---

Proposed workflow

The blueprint lifecycle wraps around the existing OpenSpec change cycle without modifying it:

Requirements doc arrives
  ↓
blueprint new    →  LLM reads requirements, explores codebase,
                    splits into changes with dependencies
  ↓
blueprint pick   →  Recommends next changes (dependency-aware + LLM ranking)
                    or explicitly starts a specific change (📋 → 🚧)
  ↓
  [ existing OpenSpec cycle: explore → apply → verify → archive ]
  ↓
blueprint ship   →  Marks change complete (🚧 → ✅), updates counters
  ↓
  ← loop back to pick next →

Key design choice: the existing explore / apply / verify / archive commands remain completely untouched. Blueprint adds two bookend commands (pick before, ship after) rather than modifying the existing workflow. This keeps the current cycle stable and makes blueprints entirely opt-in.

State drift protection

Since the decoupled design means you could forget pick or ship, several lightweight mechanisms help:

• blueprint status automatically warns about drift (e.g., "change X is archived but blueprint still shows 🚧")
• blueprint status --check provides a scriptable diagnostic (exit code for CI/hooks)
• blueprint sync can auto-reconcile drift when it happens

---

What I'd love community input on

Q1: Does this problem resonate?

Are you also dealing with multi-change requirements? How do you currently decompose a requirements document into individual changes? Is the manual decomposition actually a bottleneck, or is it valuable thinking time?

Q2: Blueprint scope — project board or smarter?

Should blueprints be:

• (a) A simple tracking table (pure bookkeeping, no intelligence) — users manage everything manually
• (b) An LLM-assisted layer (what I'm proposing) — auto-decomposition, dependency-aware recommendations, smart pick ordering

Option (a) is simpler to implement and reason about. Option (b) addresses the "what's next?" problem but adds complexity.

Q3: Integration depth with existing commands

I'm proposing a fully decoupled approach (new blueprint * subcommands, zero changes to existing explore/apply/verify/archive). An alternative would be to have archive automatically update the blueprint. The tradeoff:

• Decoupled (current proposal): safer, no regression risk to existing workflow, but requires explicit pick/ship calls
• Integrated: smoother UX (fewer commands to remember), but couples blueprint awareness into commands that currently work independently

Which do you prefer? Or is there a middle ground?

Q4: Requirements ingestion — how structured?

The blueprint new command assumes a markdown requirements document as input. In practice, requirements arrive in many forms:

• Markdown/text documents
• Jira/Linear/Redmine tickets
• Slack conversations
• Verbal discussions captured as notes

Should the blueprint layer define a lightweight requirements format, or should it be flexible about input shape and let the LLM figure it out?

Q5: Naming and conventions

• blueprint as the term — does it make sense, or is there a better word? (Considered: roadmap, plan, epic, milestone)
• Status emoji 📋 / 🚧 / ✅ with terms todo / in-progress / done — familiar enough from tools like Linear/Jira/GitHub Projects?

---

What this is NOT

• Not a project management tool. Blueprints don't handle timelines, assignments, sprints, or velocity. They track "what's done, what's next" for a set of related changes.
• Not a replacement for thinking. The LLM-assisted decomposition is a starting point, not a final answer. Human review of the generated changes is expected and encouraged.
• Not mandatory. Hotfix changes, one-off experiments, and small features can skip blueprints entirely. The existing workflow remains the default.

---

Context

I've been running OpenSpec on a production LINE Business Connect project (~30 completed change cycles). The blueprint concept emerged from repeatedly hitting the three pain points above. I have a working local implementation that I'd be happy to contribute upstream if there's community interest.

Full design details (decision log with tradeoffs for each design choice) are available — happy to share if the discussion warrants diving deeper.