openspec-design

OpenSpec Design

BC-first structural design engine. Produces design.md — the missing layer between proposal.md and tasks.md.

Domain-agnostic: Containers are any bounded unit — services, files, skill directories, workflow phases, document sections, process stages. Not limited to software architecture. Choose the zoom level that fits the change.

You are designing: $ARGUMENTS

Commands

design

Analyze proposal → BC check → Minimal Design Kit → write design.md.

Input: $ARGUMENTS = design <change-id>

Workflow:

1. Read context:

   • openspec/project.md → execution mode
   • openspec/changes/{id}/proposal.md → change scope

2. BC check (mandatory first step — stop if fails):

   • Scan proposal for BC violation signals (see reference.md §BC Signals)
   • If multi-domain detected → output split recommendation and STOP
   • If single-domain → proceed

3. Design phase (only if BC check passes):

   • Produce all 5 sections of design.md (see §Output Format)
   • Maintain mode (project.md mode = maintain) → delta-only, skip full kit

4. Write: openspec/changes/{id}/design.md

BC split output (stop before design artifacts):

⚠️ Bounded Context boundary crossed

This change appears to span multiple domains:
- BC1: {name} — {what it owns}
- BC2: {name} — {what it owns}

Recommendation: Split into separate OpenSpec changes:
1. openspec-plan create {change-id}-{bc1}: {description}
2. openspec-plan create {change-id}-{bc2}: {description}

Why: 1 change = 1 BC enables isolated testing, clear ownership,
and tractable troubleshooting. Mixing domains creates ambiguous
failures where you can't tell which boundary is broken.

Override: Add ADR to proposal.md documenting why mixed-domain is
intentional, then re-invoke /openspec-design design {id}.

maintain

Delta-only design update for an existing design.md.

Input: $ARGUMENTS = maintain <change-id>

Workflow:

1. Read existing openspec/changes/{id}/design.md
2. Read proposal.md for what changed
3. BC check on the delta only
4. Output: which sections change, what moves, why
5. Append ## Delta section to design.md (do not rewrite existing sections)