design.md is an optional file in an OpenSpec change folder that records the relevant current state of the codebase (Context), what the change must and must not achieve (Goals / Non-Goals), the key technical decisions with rationale and alternatives, and the risks and trade-offs with their mitigations. In older MySpec bundles the same filename was the technical solution, now called solution.md.
Not the full drawing set - the page in the site diary that says "we ran the new duct through the old chase because the joists could not take a second penetration; the alternative was a bulkhead, which the client rejected; risk: the chase is shared with the sprinkler feed, so it gets pressure-tested first." Short, specific, and the first thing the next engineer reads when something looks odd.
Where it lives and when it is worth writing
The OpenSpec workflow writes it in its design stage - labelled "Solution" in the stepper, because the platform normalises the legacy design stage id to solution - to openspec/changes/<change-id>/design.md, after the delta specs and before the tasks. It is optional in OpenSpec: write it when the change carries non-trivial technical decisions or trade-offs; keep it brief for small changes. Decisions must stay traceable to the proposal and the delta specs - it never introduces a capability the proposal did not name.
Four sections, in order
## Context
The relevant current state of the codebase - modules, data flow, constraints - the change
operates within, anchored in what was read during explore. Cite real modules / files.
## Goals / Non-Goals
**Goals:**
- What this change must achieve.
**Non-Goals:**
- What is explicitly out of scope, to bound the change.
## Decisions
- **Decision**: <what> - Rationale: <why>. Alternatives: <what was rejected>.
## Risks / Trade-offs
- **Risk / Trade-off**: <what> - Mitigation: <how>.## Context
Session summaries are written only by the ai-agent (SessionService.setSummary) and
surfaced by the webapp from context.sessionSummary. There is no user-facing write path.
## Goals / Non-Goals
**Goals:**
- Let the owner rename a session without touching the agent's summary generation.
**Non-Goals:**
- Renaming from the MCP server (already covered by rename_spec_session).
## Decisions
- **Decision**: store the manual name in the same context.sessionSummary key with a
`summaryLockedByUser` flag - Rationale: no schema migration; every reader already
uses that key. Alternatives: a new column (rejected: migration + dual reads).
## Risks / Trade-offs
- **Risk**: an older agent build overwrites a locked summary - Mitigation: the platform
ignores agent writes when the flag is set.design.md in MySpec bundles
MySpec's technical solution file was originally named design.md. It was renamed solution.md, and the platform treats the two as the same solution file type. Consequences worth knowing:
- An old bundle downloaded through the MCP server may still contain
design.md; match onfile_type, not the filename. - The stepper shows OpenSpec's design stage as "Solution": the platform rewrites the legacy
designstage id tosolutionone way, and the same alias maps thedesignfile type tosolution. - A MySpec
design.mdis a full solution document (architecture, data model, API design, diagrams); an OpenSpecdesign.mdis the short decisions record described above. Do not expect one to look like the other.
Review rules
- Context cites real modules and files from the explore stage.
- Goals and Non-Goals bound the change; every decision has a rationale and a rejected alternative; every risk has a mitigation.
- Nothing here widens the scope beyond the proposal's capabilities.
- A greenfield architecture essay for a two-file change.
- Decisions without alternatives, risks without mitigations, or a whole-document code fence.
Related spec files
Project vision, core principles, and the MUST / MUST NOT constraints every later file has to obey.
User roles, FR-/NFR- requirements with EARS+ acceptance criteria; a coded AR-/BR-/CR- delta for brownfield changes.
Architecture, modules, data model, and API design with Mermaid flowchart, ER and sequence diagrams - plus C4 diagrams when your organisation enables them.
Ordered, sized implementation tasks grouped into milestones, traced back to requirement IDs.
Why a brownfield change is needed, what changes, the technical solution, and its impact on existing code.
Spec Kit's prioritised user stories and success criteria, or OpenSpec's ADDED / MODIFIED / REMOVED / RENAMED requirement deltas.
Spec Kit's technical plan: technical context, constitution gates, architecture, data model, and key decisions.
OpenSpec's optional context, goals / non-goals, decisions, and risks for a change.
Workflows that write it
The default four-file bundle: interview → constitution → requirements → solution → tasks.
GitHub Spec Kit's feature-scoped flow: interview → constitution → specify → plan → tasks.
OpenSpec's change-proposal flow: explore → proposal → delta specs → design → tasks.
Let the AI Architect write it for you
MySpec interviews you, then drafts every spec file with collect → generate → review gates. Free during Open Beta.