OpenSpec packages specification-driven development as agent skills, commands, and artifact structures. Initialization creates an openspec folder for configuration and specification artifacts, and installs support for a selected coding agent. section 2.4.2
A change moves through three phases:
- Propose: clarify scope and author specification artifacts for discovery, design, and tasks. section 2.4.4
- Apply: have the agent implement the change against the specification. section 2.4.4
- Archive: move specifications for reviewed and accepted implementation to a logical conclusion. section 2.4.4
A URL shortener proposal
A first slice specifies anonymous link creation, persistent mappings, and redirects while excluding accounts, aliases, expiration, and tracking. Requirements can make invalid-URL behavior explicit, including returning an error without storing a mapping. section 2.4.4 section 3.2.2
Listing 3.2 Capturing malformed URL validation in Gherkin format
Feature: Shorten URL
Scenario: Reject malformed URL
Given the user submits a malformed URL
When the shorten URL request is processed
Then the service returns the expected validation status
And the response explains the validation failure
And no short link is storedA malformed-URL scenario demonstrates how WHEN/THEN requirements preserve the response and storage behavior that a thin prose requirement could omit. section 3.2.2
When behavior goes missing, distinguish whether the dialogue failed to elicit the intent or the specification failed to retain it. OpenSpec's native scenario format uses Gherkin-flavored WHEN/THEN blocks to capture validation details. section 3.2.2
