feat: Update spec change format

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)
+

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

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