fission-ai__openspec/openspec/changes/archive/2025-08-19-structured-spec-format/proposal.md

Why

OpenSpec specifications lack a consistent structure that makes sections visually identifiable and programmatically parseable across different specs. This makes it harder to maintain consistency and build tooling.

What Changes

Specification Format Section

• From: No formal structure requirements for specifications
• To: Structured format with ### Requirement: and #### Scenario: headers
• Reason: Visual consistency and parseability across all specs
• Impact: Non-breaking - existing specs can migrate gradually

Keyword Formatting

• From: Inconsistent use of WHEN/THEN/AND keywords
• To: Bold keywords (WHEN, THEN, AND) in scenario bullets
• Reason: Improved readability and consistent visual hierarchy
• Impact: Non-breaking - formatting enhancement only

Format Flexibility

• From: Implicit understanding that different content needs different formats
• To: Explicit allowance for alternative formats (OpenAPI, JSON Schema, etc.)
• Reason: Address concern that not all specs fit requirement/scenario pattern
• Impact: Non-breaking - clarifies existing practice

Migration Guidelines

• From: No migration guidance
• To: Documented gradual migration approach
• Reason: Allows incremental adoption without disrupting existing specs
• Impact: Non-breaking - opt-in migration as specs are modified

Impact

• Affected specs: openspec-conventions (enhancement to existing capability)
• Affected code: None initially - this is a documentation standard enhancement
• Migration: Gradual - existing specs migrate as they're modified
• Tooling: Enables future parsing tools but doesn't require them