spec.md is the requirements file of two methodologies. In Spec Kit it is a feature specification: prioritised user stories with acceptance scenarios, technology-neutral FR- requirements, key entities, and measurable SC- success criteria. In OpenSpec it is a delta spec for one capability: ADDED, MODIFIED, REMOVED, and RENAMED requirements, each with WHEN / THEN scenarios, that merge into a long-lived baseline on apply.
Spec Kit's spec.md is a brief for one new room: who uses it, in what order the jobs matter (P1 first), and how you will know it worked. OpenSpec's spec.md is a redline on the existing drawings: this requirement is added, that one changes to read as follows, this one is struck. Same filename, opposite starting points - a blank room versus a standing building.
The feature specification
Written by the Spec Kit workflow's specify stage to specs/<NNN-feature>/spec.md, mirroring GitHub Spec Kit's spec-template.md. Spec Kit is feature-scoped: one numbered feature directory per session, so the interview stays focused on a single feature rather than a roadmap.
# Feature Specification: Photo Albums
**Feature Branch**: `001-photo-albums`
**Created**: 2026-06-13
**Status**: Draft
**Input**: User description: "Organise photos into albums with drag-and-drop"
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Create an album (Priority: P1)
A user groups existing photos into a named album from the library view.
**Why this priority**: Every other story depends on an album existing.
**Independent Test**: Create an album with three photos; it appears in the sidebar.
**Acceptance Scenarios**:
1. **Given** a library with photos, **When** the user selects three and chooses "New album",
**Then** an album containing exactly those photos is created and listed.
### User Story 2 - Reorder photos (Priority: P2)
…
### Edge Cases
- What happens when an album is deleted while another tab is viewing it?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST let a user create an album from a selection of photos
- **FR-002**: System MUST persist album ordering across sessions
### Key Entities
- **Album**: name, cover photo, ordered list of photos
## Success Criteria *(mandatory)*
- **SC-001**: Users create an album in under 30 seconds
- **SC-002**: Reordering 200 photos completes without visible lag
## Assumptions
- Photos are already uploaded; this feature does not cover ingestion.- User stories are ranked P1 / P2 / P3, each with Why this priority, an Independent Test (a viable MVP slice on its own), and one to three Given / When / Then acceptance scenarios. Later, tasks.md gets one phase per story.
- FR-### and SC-### numbering is sequential and zero-padded. FRs say what, never which stack; SCs are numbers, times, percentages, or binary outcomes.
[NEEDS CLARIFICATION: …]markers are allowed inline - at most three per file, each a specific answerable question.- Edge Cases and Assumptions stay short: three to six bullets each.
The delta spec
Written by the OpenSpec workflow's specs stage, one file per capability the proposal named, at openspec/changes/<change-id>/specs/<capability>/spec.md - the path the OpenSpec CLI reads. Only the delta headers that apply are included.
## ADDED Requirements
### Requirement: Session rename
The system SHALL let the session owner replace the AI-generated session summary
with a user-supplied one of at most 500 characters.
#### Scenario: Owner renames a session
- **WHEN** the owner submits a new name from the session menu
- **THEN** the session list and chat header show the new name
- **AND** other open clients receive the update in real time
## MODIFIED Requirements
### Requirement: Session summary generation
The system SHALL generate a summary when a session starts and SHALL NOT overwrite
a summary the user has set manually.
#### Scenario: Agent regenerates a summary
- **WHEN** the agent proposes a new summary for a manually renamed session
- **THEN** the manual name is kept
## RENAMED Requirements
- FROM: `### Requirement: Session title`
- TO: `### Requirement: Session summary generation`- Exact headers:
## ADDED Requirements,## MODIFIED Requirements,## REMOVED Requirements,## RENAMED Requirements. The OpenSpec validator enforces them. - Every ADDED / MODIFIED requirement has SHALL / MUST text and at least one
#### Scenario:with- **WHEN**/- **THEN**(and optional- **AND**) bullets. - MODIFIED describes the post-change behaviour in full, not just the diff; REMOVED states the requirement and why; RENAMED uses
- FROM:/- TO:pairs of backtick-quoted headers, never an arrow. - One capability per file. On
openspec archive(or/opsx:archive), the delta merges intoopenspec/specs/<capability>/spec.md, the capability's living baseline.
How they map to MySpec's requirements.md
| MySpec requirements.md | Spec Kit spec.md | OpenSpec delta spec.md | |
|---|---|---|---|
| Scope | Whole product (greenfield) or change delta (brownfield) | One feature | One capability of one change |
| Requirement unit | FR-/NFR- with EARS+ ACs; AR-/BR-/CR- deltas | User stories + FR-/SC- | ADDED / MODIFIED / REMOVED / RENAMED Requirement + Scenario |
| Criteria syntax | WHEN / WHILE / IF … THEN … SHALL | Given / When / Then | WHEN / THEN / AND |
| Non-functional | NFR- with Target and Priority | SC- measurable outcomes | Folded into requirements or design.md |
| Diagrams | Requirement diagrams | - | - |
Review rules
- Spec Kit: stories in priority order with tests and scenarios; FRs technology-neutral; SCs measurable; ≤3 clarification markers.
- OpenSpec: exact delta headers; every requirement has SHALL / MUST text and a scenario; grounded in the explored codebase for MODIFIED / REMOVED / RENAMED.
- A stack choice inside an FR; a success criterion that cannot be measured.
- Two capabilities bundled in one delta file; a MODIFIED entry that shows only the diff.
- A whole-document code fence or a metadata footer.
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.