diff --git a/openspec/changes/adopt-future-state-storage/proposal.md b/openspec/changes/adopt-future-state-storage/proposal.md new file mode 100644 index 000000000..f73848a47 --- /dev/null +++ b/openspec/changes/adopt-future-state-storage/proposal.md @@ -0,0 +1,24 @@ +# Adopt Future State Storage for OpenSpec Changes + +## Why + +The current approach of storing spec changes as diff files (`.spec.md.diff`) creates friction for both humans and AI. Diff syntax with `+` and `-` prefixes makes specs hard to read, AI tools struggle with the format when understanding future state, and GitHub can't show nice comparisons between current and proposed specs in different folders. + +## What Changes + +- Change from storing diffs (`patches/[capability]/spec.md.diff`) to storing complete future state (`specs/[capability]/spec.md`) +- Update all documentation to reflect new storage format +- Migrate existing `add-init-command` change to new format +- Add new `openspec-conventions` capability to document these conventions + + + +## Impact + +- Affected specs: New `openspec-conventions` capability +- Affected code: + - openspec/README.md (lines 85-108) + - docs/PRD.md (lines 376-382, 778-783) + - docs/openspec-walkthrough.md (lines 58-62, 112-126) + - openspec/changes/add-init-command/ (migration needed) + diff --git a/openspec/changes/adopt-future-state-storage/specs/openspec-conventions/spec.md b/openspec/changes/adopt-future-state-storage/specs/openspec-conventions/spec.md new file mode 100644 index 000000000..246e203e2 --- /dev/null +++ b/openspec/changes/adopt-future-state-storage/specs/openspec-conventions/spec.md @@ -0,0 +1,120 @@ +# OpenSpec Conventions Specification + +## Purpose + +OpenSpec conventions SHALL define how system capabilities are documented, how changes are proposed and tracked, and how specifications evolve over time. This meta-specification serves as the source of truth for OpenSpec's own conventions. + +## Core Principles + +The system SHALL follow these principles: +- Specs reflect what IS currently built and deployed +- Changes contain proposals for what SHOULD be changed +- AI drives the documentation process +- Specs are living documentation kept in sync with deployed code + +## Directory Structure + +WHEN an OpenSpec project is initialized +THEN it SHALL have this structure: +``` +openspec/ +├── project.md # Project-specific context +├── README.md # AI assistant instructions +├── specs/ # Current deployed capabilities +│ └── [capability]/ # Single, focused capability +│ ├── spec.md # WHAT and WHY +│ └── design.md # HOW (optional, for established patterns) +└── changes/ # Proposed changes + ├── [change-name]/ # Descriptive change identifier + │ ├── proposal.md # Why, what, and impact + │ ├── tasks.md # Implementation checklist + │ ├── design.md # Technical decisions (optional) + │ └── specs/ # Complete future state + │ └── [capability]/ + │ └── spec.md # Clean markdown (no diff syntax) + └── archive/ # Completed changes + └── YYYY-MM-DD-[name]/ +``` + +## Change Storage Convention + +### Future State Storage + +WHEN creating a change proposal +THEN store the complete future state of affected specs +AND use clean markdown without diff syntax + +The `changes/[name]/specs/` directory SHALL contain: +- Complete spec files as they will exist after the change +- Clean markdown without `+` or `-` prefixes +- All formatting and structure of the final intended state + +### Proposal Format + +WHEN documenting what changes +THEN the proposal SHALL explicitly describe each change: + +```markdown +**[Section or Behavior Name]** +- From: [current state/requirement] +- To: [future state/requirement] +- Reason: [why this change is needed] +- Impact: [breaking/non-breaking, who's affected] +``` + +This explicit format compensates for not having inline diffs and ensures reviewers understand exactly what will change. + +## Change Lifecycle + +The change process SHALL follow these states: + +1. **Propose**: AI creates change with future state specs and explicit proposal +2. **Review**: Humans review proposal and future state +3. **Approve**: Change is approved for implementation +4. **Implement**: Follow tasks.md checklist (can span multiple PRs) +5. **Deploy**: Changes are deployed to production +6. **Update**: Specs in `specs/` are updated to match deployed reality +7. **Archive**: Change is moved to `archive/YYYY-MM-DD-[name]/` + +## Viewing Changes + +WHEN reviewing proposed changes +THEN reviewers can compare using: +- GitHub PR diff view when changes are committed +- Command line: `diff -u specs/[capability]/spec.md changes/[name]/specs/[capability]/spec.md` +- Any visual diff tool comparing current vs future state + +The system relies on tools to generate diffs rather than storing them. + +## Capability Naming + +Capabilities SHALL use: +- Verb-noun patterns (e.g., `user-auth`, `payment-capture`) +- Hyphenated lowercase names +- Singular focus (one responsibility per capability) +- No nesting (flat structure under `specs/`) + +## When Changes Require Proposals + +A proposal SHALL be created for: +- New features or capabilities +- Breaking changes to existing behavior +- Architecture or pattern changes +- Performance optimizations that change behavior +- Security updates affecting access patterns + +A proposal is NOT required for: +- Bug fixes restoring intended behavior +- Typos or formatting fixes +- Non-breaking dependency updates +- Adding tests for existing behavior +- Documentation clarifications + +## Why This Approach + +Clean future state storage provides: +- **Readability**: No diff syntax pollution +- **AI-compatibility**: Standard markdown that AI tools understand +- **Simplicity**: No special parsing or processing needed +- **Tool-agnostic**: Any diff tool can show changes +- **Clear intent**: Explicit proposals document reasoning \ No newline at end of file diff --git a/openspec/changes/adopt-future-state-storage/tasks.md b/openspec/changes/adopt-future-state-storage/tasks.md new file mode 100644 index 000000000..fb831f3e6 --- /dev/null +++ b/openspec/changes/adopt-future-state-storage/tasks.md @@ -0,0 +1,38 @@ +# Implementation Tasks + +## 1. Update Core Documentation +- [ ] 1.1 Update openspec/README.md section on "Creating a Change Proposal" + - [ ] Replace `patches/` with `specs/` in directory structure + - [ ] Update step 3 to show storing complete future state + - [ ] Remove diff syntax instructions (+/- prefixes) + +## 2. Migrate Existing Change +- [ ] 2.1 Convert add-init-command change to new format + - [ ] Create `specs/cli-init/spec.md` with clean content (no diff markers) + - [ ] Delete old `patches/` directory +- [ ] 2.2 Test that the migrated change is clear and reviewable + +## 3. Update Documentation Examples +- [ ] 3.1 Update docs/PRD.md + - [ ] Fix directory structure examples (lines 376-382) + - [ ] Update archive examples (lines 778-783) + - [ ] Ensure consistency throughout +- [ ] 3.2 Update docs/openspec-walkthrough.md + - [ ] Replace diff examples with future state examples + - [ ] Ensure the walkthrough reflects new approach + +## 4. Create New Spec +- [ ] 4.1 Finalize openspec-conventions spec in main specs/ directory + - [ ] Document the future state storage approach + - [ ] Include examples of good proposals + - [ ] Make it the source of truth for conventions + +## 5. Validation +- [ ] 5.1 Verify all documentation is consistent +- [ ] 5.2 Test creating a new change with the new approach +- [ ] 5.3 Ensure GitHub PR view shows diffs clearly + +## 6. Deployment +- [ ] 6.1 Get approval for this change +- [ ] 6.2 Implement all tasks above +- [ ] 6.3 After deployment, archive this change with completion date \ No newline at end of file