From b5be00bfe5ca3e14f6136496a1f079fb259250c2 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Wed, 6 Aug 2025 14:26:19 +1000 Subject: [PATCH 1/2] Add change for updating spec storage format --- .../adopt-future-state-storage/proposal.md | 79 ++++++++++++ .../specs/openspec-conventions/spec.md | 120 ++++++++++++++++++ .../adopt-future-state-storage/tasks.md | 44 +++++++ 3 files changed, 243 insertions(+) create mode 100644 openspec/changes/adopt-future-state-storage/proposal.md create mode 100644 openspec/changes/adopt-future-state-storage/specs/openspec-conventions/spec.md create mode 100644 openspec/changes/adopt-future-state-storage/tasks.md 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..dba3ddf50 --- /dev/null +++ b/openspec/changes/adopt-future-state-storage/proposal.md @@ -0,0 +1,79 @@ +# 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 + +### OpenSpec Change Storage Convention + +**Change File Structure** +- From: Store changes as diff files in `patches/[capability]/spec.md.diff` +- To: Store complete future state as clean markdown in `specs/[capability]/spec.md` +- Reason: Clean markdown is readable, AI-friendly, and tool-compatible +- Impact: Breaking - existing changes must be migrated to new format + +**Proposal Documentation Requirements** +- From: Proposals can be brief since diffs show changes +- To: Proposals must explicitly document all behavioral changes with before/after +- Reason: Compensate for not having inline diffs by being explicit +- Impact: Non-breaking - improves clarity and review process + +### File Updates Required + +**openspec/README.md (AI Instructions)** +- Section: "Creating a Change Proposal" (lines 85-108) +- From: Instructions to create `patches/` directory with diff files +- To: Instructions to create `specs/` directory with complete future state +- Impact: Changes how AI assistants create proposals + +**docs/PRD.md** +- Multiple sections showing directory structures (lines 376-382, 778-783) +- From: Examples showing `patches/*.diff` structure +- To: Examples showing `specs/*.md` structure +- Impact: Documentation consistency + +**docs/openspec-walkthrough.md** +- Example change structure (lines 58-62, 112-126) +- From: Shows diff file examples +- To: Shows clean future state examples +- Impact: Tutorial accuracy + +### New Capability: openspec-conventions + +Adding a new spec that documents OpenSpec's own storage conventions, making them explicit and versionable. This meta-spec will serve as the source of truth for how OpenSpec changes should be structured. + +## Impact Summary + +- **Breaking changes**: Existing changes using diff format need migration +- **Affected systems**: + - AI assistants creating changes + - Developers reviewing changes + - Any tooling that processes change files +- **Migration required**: Yes - convert existing `add-init-command` change from diff to future state format + +## Benefits + +1. **AI-friendly**: AI tools can read and write normal markdown without diff syntax parsing +2. **Human-readable**: Reviewers see the intended end state clearly without mental diff processing +3. **Simple tooling**: Standard `diff` command or GitHub PR view shows changes +4. **Clean files**: No syntax pollution with `+` and `-` prefixes +5. **Better proposals**: Explicit change documentation improves review quality + +## Migration Path + +For the existing `add-init-command` change: +1. Apply the current diff to generate the complete future state +2. Store as `specs/cli-init/spec.md` (clean markdown) +3. Update proposal to be explicit about what's new +4. Remove old `patches/` directory + +## Viewing Changes + +With this approach, reviewers can see changes using: +- GitHub PR diff view (automatic when files change) +- Command line: `diff -u specs/user-auth/spec.md changes/[name]/specs/user-auth/spec.md` +- Any diff tool (VS Code, GitHub Desktop, etc.) + +The key insight: we don't need to store diffs when tools can generate them on demand. \ No newline at end of file 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..e00957de3 --- /dev/null +++ b/openspec/changes/adopt-future-state-storage/tasks.md @@ -0,0 +1,44 @@ +# 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 + - [ ] Add note about explicit proposal requirements +- [ ] 1.2 Update enhanced proposal format example + - [ ] Show before/after comparisons + - [ ] Include breaking change indicators + - [ ] Add impact analysis requirements + +## 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) + - [ ] Update proposal.md to be explicit about new capability + - [ ] 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 + - [ ] Update the proposal format shown + - [ ] 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 From 6b8845b10a4c94d37524dff4fe928f00deed5eb9 Mon Sep 17 00:00:00 2001 From: Tabish Bidiwale Date: Wed, 6 Aug 2025 15:42:19 +1000 Subject: [PATCH 2/2] remove any updates to the proposal format --- .../adopt-future-state-storage/proposal.md | 77 +++---------------- .../adopt-future-state-storage/tasks.md | 8 +- 2 files changed, 12 insertions(+), 73 deletions(-) diff --git a/openspec/changes/adopt-future-state-storage/proposal.md b/openspec/changes/adopt-future-state-storage/proposal.md index dba3ddf50..f73848a47 100644 --- a/openspec/changes/adopt-future-state-storage/proposal.md +++ b/openspec/changes/adopt-future-state-storage/proposal.md @@ -6,74 +6,19 @@ The current approach of storing spec changes as diff files (`.spec.md.diff`) cre ## What Changes -### OpenSpec Change Storage Convention +- 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 -**Change File Structure** -- From: Store changes as diff files in `patches/[capability]/spec.md.diff` -- To: Store complete future state as clean markdown in `specs/[capability]/spec.md` -- Reason: Clean markdown is readable, AI-friendly, and tool-compatible -- Impact: Breaking - existing changes must be migrated to new format -**Proposal Documentation Requirements** -- From: Proposals can be brief since diffs show changes -- To: Proposals must explicitly document all behavioral changes with before/after -- Reason: Compensate for not having inline diffs by being explicit -- Impact: Non-breaking - improves clarity and review process -### File Updates Required +## Impact -**openspec/README.md (AI Instructions)** -- Section: "Creating a Change Proposal" (lines 85-108) -- From: Instructions to create `patches/` directory with diff files -- To: Instructions to create `specs/` directory with complete future state -- Impact: Changes how AI assistants create proposals +- 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) -**docs/PRD.md** -- Multiple sections showing directory structures (lines 376-382, 778-783) -- From: Examples showing `patches/*.diff` structure -- To: Examples showing `specs/*.md` structure -- Impact: Documentation consistency - -**docs/openspec-walkthrough.md** -- Example change structure (lines 58-62, 112-126) -- From: Shows diff file examples -- To: Shows clean future state examples -- Impact: Tutorial accuracy - -### New Capability: openspec-conventions - -Adding a new spec that documents OpenSpec's own storage conventions, making them explicit and versionable. This meta-spec will serve as the source of truth for how OpenSpec changes should be structured. - -## Impact Summary - -- **Breaking changes**: Existing changes using diff format need migration -- **Affected systems**: - - AI assistants creating changes - - Developers reviewing changes - - Any tooling that processes change files -- **Migration required**: Yes - convert existing `add-init-command` change from diff to future state format - -## Benefits - -1. **AI-friendly**: AI tools can read and write normal markdown without diff syntax parsing -2. **Human-readable**: Reviewers see the intended end state clearly without mental diff processing -3. **Simple tooling**: Standard `diff` command or GitHub PR view shows changes -4. **Clean files**: No syntax pollution with `+` and `-` prefixes -5. **Better proposals**: Explicit change documentation improves review quality - -## Migration Path - -For the existing `add-init-command` change: -1. Apply the current diff to generate the complete future state -2. Store as `specs/cli-init/spec.md` (clean markdown) -3. Update proposal to be explicit about what's new -4. Remove old `patches/` directory - -## Viewing Changes - -With this approach, reviewers can see changes using: -- GitHub PR diff view (automatic when files change) -- Command line: `diff -u specs/user-auth/spec.md changes/[name]/specs/user-auth/spec.md` -- Any diff tool (VS Code, GitHub Desktop, etc.) - -The key insight: we don't need to store diffs when tools can generate them on demand. \ 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 index e00957de3..fb831f3e6 100644 --- a/openspec/changes/adopt-future-state-storage/tasks.md +++ b/openspec/changes/adopt-future-state-storage/tasks.md @@ -4,16 +4,11 @@ - [ ] 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 - - [ ] Add note about explicit proposal requirements -- [ ] 1.2 Update enhanced proposal format example - - [ ] Show before/after comparisons - - [ ] Include breaking change indicators - - [ ] Add impact analysis requirements + - [ ] 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) - - [ ] Update proposal.md to be explicit about new capability - [ ] Delete old `patches/` directory - [ ] 2.2 Test that the migrated change is clear and reviewable @@ -24,7 +19,6 @@ - [ ] Ensure consistency throughout - [ ] 3.2 Update docs/openspec-walkthrough.md - [ ] Replace diff examples with future state examples - - [ ] Update the proposal format shown - [ ] Ensure the walkthrough reflects new approach ## 4. Create New Spec