SDLC Agent-Skill Wiki

artifact-spec-delta

2 min read

Artifact: spec delta

OpenSpec’s signature artifact — openspec/changes/<name>/specs/<domain>/spec.md. Rather than rewrite the whole product spec for a change, a delta describes only what is changing relative to the living spec (openspec/specs/), under three sections:

## ADDED Requirements
### Requirement: <new behavior>          # appended to main spec on merge
 
## MODIFIED Requirements
### Requirement: <changed behavior>       # replaces the existing requirement
[updated text] (Previously: <old text>)
 
## REMOVED Requirements
### Requirement: <deprecated behavior>    # deleted from main spec
(Reason for removal)

Each requirement is a single behavioral statement using RFC 2119 keywords (MUST/SHALL, SHOULD, MAY) and carries Given/When/Then scenarios as concrete, testable examples:

#### Scenario: <case>
- GIVEN <precondition>
- WHEN <action>
- THEN <observable result>

On openspec-sync / openspec-archive the sections are applied in strict order — RENAMED → REMOVED → MODIFIED → ADDED — and merged into the living spec, which then again describes current behavior. Deltas keep changes small, prevent merge conflicts across parallel changes, and make the framework brownfield-first.

The living openspec/specs/ is the durable source of truth this delta targets; the delta itself is temporary, discarded (into archive/) once merged. This is the mechanism behind pattern-living-specification.

  • openspec-propose — authors the delta as part of the one-step proposal.
  • openspec-sync — merges the delta into the living spec (its consumer).

See Also

Graph View

Backlinks