mirror of
https://github.com/Fission-AI/OpenSpec.git
synced 2026-09-14 20:16:53 +08:00
Tabish Bidiwale
37 lines
1.6 KiB
Markdown
37 lines
1.6 KiB
Markdown
## 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
|