fix: clarify openspec/README.md in tasks (AI instructions file)

The diff command now applies deltas and shows side-by-side
requirement comparison rather than just displaying delta instructions.

openspec/changes/add-requirement-markers/proposal.md

@@ -1,15 +0,0 @@
-# Add @requirement Markers for Requirement Identification
-
-## Why
-Specs contain WHEN/THEN patterns that define system requirements, but extracting these programmatically requires brittle regex parsing that may miss edge cases or break with formatting changes.
-
-## What Changes
-- Define @requirement marker convention for identifying key requirements in specs
-- Each marker includes a brief identifier (e.g., @requirement user-register)
-- Markers appear directly before their WHEN/THEN blocks
-- Document convention in openspec-conventions spec
-
-## Impact
-- Affected specs: openspec-conventions (new)
-- Affected code: None initially - enables future tooling
-- Breaking changes: None - additive convention only

openspec/changes/add-requirement-markers/specs/openspec-conventions/spec.md

@@ -1,219 +0,0 @@
-# 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
-
-## Requirement Markers
-
-### Marker Syntax
-
-@requirement marker-syntax
-WHEN writing a requirement in a spec
-THEN prefix it with @requirement followed by a brief kebab-case identifier
-AND place the marker on the line immediately before the WHEN statement
-
-@requirement marker-identifier
-WHEN choosing an identifier for @requirement
-THEN use kebab-case (lowercase with hyphens)
-AND keep it brief but descriptive (2-4 words)
-AND ensure it's unique within the spec
-
-@requirement marker-placement
-WHEN adding @requirement markers to a spec
-THEN place them in the ## Behavior or ## Behaviors section
-AND ensure each WHEN/THEN block has exactly one marker
-AND maintain a blank line after each THEN block for readability
-
-### Examples
-
-@requirement valid-marker-example
-WHEN a spec includes properly formatted markers
-THEN tools can extract and identify requirements programmatically
-AND the spec remains human-readable
-
-Example of correct usage:
-```markdown
-## Behavior
-
-@requirement user-register
-WHEN user registers with valid email
-THEN create account and send confirmation
-
-@requirement user-login
-WHEN user logs in with correct credentials
-THEN return JWT token with user data
-
-@requirement invalid-credentials
-WHEN user provides invalid credentials
-THEN return 401 unauthorized error
-```
-
-@requirement invalid-marker-detection
-WHEN a requirement lacks an @requirement marker
-THEN tools should gracefully skip it
-AND optionally warn about unmarked requirements
-
-### Edge Cases
-
-@requirement multiline-when-then
-WHEN a WHEN or THEN clause spans multiple lines
-THEN the @requirement marker still goes on the line before WHEN
-AND the entire block is considered part of that requirement
-
-@requirement multiple-then-clauses
-WHEN a requirement has multiple THEN clauses using AND
-THEN treat them as part of the same requirement
-AND use a single @requirement marker for the entire block
-
-@requirement nested-conditions
-WHEN requirements have nested conditions or complex logic
-THEN keep the @requirement marker simple
-AND let the WHEN/THEN content contain the complexity
-
-## Spec Structure
-
-@requirement spec-file-location
-WHEN creating a spec file
-THEN place it in openspec/specs/[capability-name]/spec.md
-AND use kebab-case for the capability name
-
-@requirement spec-sections
-WHEN structuring a spec
-THEN include these sections in order:
-- # [Capability Name] Specification
-- ## Purpose (brief description)
-- ## Behavior or ## Behaviors (with @requirement markers)
-- ## Examples (optional, for complex requirements)
-
-## Benefits of Requirement Markers
-
-@requirement tooling-extraction
-WHEN tools need to extract requirements from specs
-THEN they can parse @requirement markers reliably
-AND avoid complex regex patterns for WHEN/THEN extraction
-
-@requirement requirement-counting
-WHEN displaying change summaries
-THEN tools can count requirements by counting @requirement markers
-AND show accurate requirement counts per spec
-
-@requirement requirement-referencing
-WHEN documenting or discussing specific requirements
-THEN use the @requirement identifier for clear reference
-AND maintain consistency across documentation
-
-## 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/add-requirement-markers/tasks.md

@@ -1,24 +0,0 @@
-# Implementation Tasks
-
-## 1. Define Convention
-- [ ] 1.1 Document @requirement marker syntax
-- [ ] 1.2 Define identifier naming guidelines
-- [ ] 1.3 Specify marker placement rules
-- [ ] 1.4 Add examples of proper usage
-
-## 2. Create Specification
-- [ ] 2.1 Write openspec-conventions spec
-- [ ] 2.2 Include requirement marker section
-- [ ] 2.3 Add good and bad examples
-- [ ] 2.4 Document edge cases
-
-## 3. Update Existing Specs
-- [ ] 3.1 Add @requirement markers to cli-init spec
-- [ ] 3.2 Add @requirement markers to cli-update spec
-- [ ] 3.3 Add @requirement markers to cli-view spec
-- [ ] 3.4 Review and update any other existing specs
-
-## 4. Documentation
-- [ ] 4.1 Update README with marker convention
-- [ ] 4.2 Add marker usage to CLAUDE.md
-- [ ] 4.3 Create examples for AI assistants

openspec/changes/adopt-delta-based-changes/proposal.md

@@ -0,0 +1,66 @@
+# Adopt Delta-Based Changes for Specifications
+
+## Why
+
+The current approach of storing complete future states in change proposals creates a poor review experience. When reviewing changes on GitHub, reviewers see entire spec files (often 100+ lines) as "added" in green, making it impossible to identify what actually changed. With the recent structured format adoption, we now have clear section boundaries that enable a better approach: storing only additions and modifications.
+
+## What Changes
+
+Store only the requirements that actually change, not complete future states:
+
+- **ADDED Requirements**: New capabilities being introduced
+- **MODIFIED Requirements**: Existing requirements being changed (must match current header)
+- **REMOVED Requirements**: Deprecated capabilities
+- **RENAMED Requirements**: Explicit header changes (e.g., `FROM: Old Name` → `TO: New Name`)
+
+The archive command will programmatically apply these deltas using normalized header matching (trim leading/trailing whitespace) instead of manually copying entire files.
+
+## Impact
+
+**Affected specs**: openspec-conventions, cli-archive, cli-diff
+
+**Benefits**:
+- GitHub diffs show only actual changes (25 lines instead of 150+)
+- Reviewers immediately see what's being added, modified, or removed
+- Conflicts are more apparent when two changes modify the same requirement
+- Archive command can programmatically apply changes
+
+**Format**: Delta format only - all changes must use ADDED/MODIFIED/REMOVED sections.
+
+## Example
+
+Instead of storing a 150-line complete future spec, store only:
+
+```markdown
+# User Authentication - Changes
+
+## ADDED Requirements
+
+### Requirement: OAuth Support
+Users SHALL authenticate via OAuth providers including Google and GitHub.
+
+#### Scenario: OAuth login flow
+- **WHEN** user selects OAuth provider
+- **THEN** redirect to provider authorization
+- **AND** exchange authorization code for tokens
+
+## MODIFIED Requirements
+
+### Requirement: Session Management
+Sessions SHALL expire after 30 minutes of inactivity.
+
+#### Scenario: Inactive session timeout  
+- **WHEN** no activity for 30 minutes ← (was 60 minutes)
+- **THEN** invalidate session token
+- **AND** require re-authentication
+
+## RENAMED Requirements
+- FROM: `### Requirement: Basic Authentication`
+- TO: `### Requirement: Email Authentication`
+```
+
+This makes reviews focused and changes explicit.
+
+## Conflict Resolution
+
+Git naturally detects conflicts when two changes modify the same requirement header. This is actually better than full-state storage where Git might silently merge incompatible changes.

openspec/changes/adopt-delta-based-changes/specs/cli-archive/spec.md

@@ -0,0 +1,46 @@
+# CLI Archive Command - Changes
+
+## MODIFIED Requirements
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL apply delta changes to main specs to reflect the deployed reality.
+
+#### Scenario: Applying delta changes
+
+- **WHEN** archiving a change with delta-based specs
+- **THEN** parse and apply delta changes as defined in openspec-conventions
+- **AND** validate all operations before applying
+
+#### Scenario: Validating delta changes
+
+- **WHEN** processing delta changes
+- **THEN** perform validations as specified in openspec-conventions
+- **AND** if validation fails, show specific errors and abort
+
+#### Scenario: Conflict detection
+
+- **WHEN** applying deltas would create duplicate requirement headers
+- **THEN** abort with error message showing the conflict
+- **AND** suggest manual resolution
+
+### Requirement: Display Output
+
+The command SHALL provide clear feedback about delta operations.
+
+#### Scenario: Showing delta application
+
+- **WHEN** applying delta changes
+- **THEN** display for each spec:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+- **AND** use standard output symbols (+ ~ - →) as defined in openspec-conventions:
+  ```
+  Applying changes to specs/user-auth/spec.md:
+    + 2 added
+    ~ 3 modified
+    - 1 removed
+    → 1 renamed
+  ```

openspec/changes/adopt-delta-based-changes/specs/cli-diff/spec.md

@@ -0,0 +1,35 @@
+# CLI Diff Command - Changes
+
+## REMOVED Requirements
+
+### Requirement: Display Format
+
+**Reason for removal**: The standard unified diff format is replaced by requirement-level side-by-side comparison that better shows semantic changes rather than line-by-line text differences.
+
+## MODIFIED Requirements
+
+### Requirement: Diff Output
+
+The command SHALL show a requirement-level comparison displaying only changed requirements.
+
+#### Scenario: Side-by-side comparison of changes
+
+- **WHEN** running `openspec diff <change>`
+- **THEN** display only requirements that have changed
+- **AND** show them in a side-by-side format that:
+  - Clearly shows the current version on the left
+  - Shows the future version on the right
+  - Indicates new requirements (not in current)
+  - Indicates removed requirements (not in future)
+  - Aligns modified requirements for easy comparison
+
+### Requirement: Validation
+
+The command SHALL validate that changes can be applied successfully.
+
+#### Scenario: Invalid delta references
+
+- **WHEN** delta references non-existent requirement
+- **THEN** show error message with specific requirement
+- **AND** continue showing other valid changes
+- **AND** clearly mark failed changes in the output

openspec/changes/adopt-delta-based-changes/specs/openspec-conventions/spec.md

@@ -0,0 +1,109 @@
+# OpenSpec Conventions - Changes
+
+## ADDED Requirements
+
+### Requirement: Header-Based Requirement Identification
+
+Requirement headers SHALL serve as unique identifiers for programmatic matching between current specs and proposed changes.
+
+#### Scenario: Matching requirements programmatically
+
+- **WHEN** processing delta changes
+- **THEN** use the `### Requirement: [Name]` header as the unique identifier
+- **AND** match using normalized headers: `normalize(header) = trim(header)`
+- **AND** compare headers with case-sensitive equality after normalization
+
+#### Scenario: Handling requirement renames
+
+- **WHEN** renaming a requirement
+- **THEN** use a special `## RENAMED Requirements` section
+- **AND** specify both old and new names explicitly:
+  ```markdown
+  ## RENAMED Requirements
+  - FROM: `### Requirement: Old Name`
+  - TO: `### Requirement: New Name`
+  ```
+- **AND** if content also changes, include under MODIFIED using the NEW header
+
+#### Scenario: Validating header uniqueness
+
+- **WHEN** creating or modifying requirements
+- **THEN** ensure no duplicate headers exist within a spec
+- **AND** validation tools SHALL flag duplicate headers as errors
+
+## MODIFIED Requirements
+
+### Requirement: Change Storage Convention
+
+Change proposals SHALL store only the additions, modifications, and removals to specifications, not complete future states.
+
+#### Scenario: Creating change proposals with additions
+
+- **WHEN** creating a change proposal that adds new requirements
+- **THEN** include only the new requirements under `## ADDED Requirements`
+- **AND** each requirement SHALL include its complete content
+- **AND** use the standard structured format for requirements and scenarios
+
+#### Scenario: Creating change proposals with modifications  
+
+- **WHEN** creating a change proposal that modifies existing requirements
+- **THEN** include the modified requirements under `## MODIFIED Requirements`
+- **AND** use the same header text as in the current spec (normalized)
+- **AND** include the complete modified requirement (not a diff)
+- **AND** optionally annotate what changed with inline comments like `← (was X)`
+
+#### Scenario: Creating change proposals with removals
+
+- **WHEN** creating a change proposal that removes requirements
+- **THEN** list them under `## REMOVED Requirements`
+- **AND** use the normalized header text for identification
+- **AND** include reason for removal
+- **AND** document any migration path if applicable
+
+
+The `changes/[name]/specs/` directory SHALL contain:
+- Delta files showing only what changes
+- Sections for ADDED, MODIFIED, REMOVED, and RENAMED requirements
+- Normalized header matching for requirement identification
+- Complete requirements using the structured format
+- Clear indication of change type for each requirement
+
+#### Scenario: Using standard output symbols
+
+- **WHEN** displaying delta operations in CLI output
+- **THEN** use these standard symbols:
+  - `+` for ADDED (green)
+  - `~` for MODIFIED (yellow)
+  - `-` for REMOVED (red)
+  - `→` for RENAMED (cyan)
+
+### Requirement: Archive Process Enhancement
+
+The archive process SHALL programmatically apply delta changes to current specifications using header-based matching.
+
+#### Scenario: Archiving changes with deltas
+
+- **WHEN** archiving a completed change
+- **THEN** the archive command SHALL:
+  1. Parse RENAMED sections first and apply renames
+  2. Parse REMOVED sections and remove by normalized header match
+  3. Parse MODIFIED sections and replace by normalized header match (using new names if renamed)
+  4. Parse ADDED sections and append new requirements
+- **AND** validate that all MODIFIED/REMOVED headers exist in current spec
+- **AND** validate that ADDED headers don't already exist
+- **AND** generate the updated spec in the main specs/ directory
+
+#### Scenario: Handling conflicts during archive
+
+- **WHEN** delta changes conflict with current spec state
+- **THEN** the archive command SHALL report specific conflicts
+- **AND** require manual resolution before proceeding
+- **AND** provide clear guidance on resolving conflicts
+
+## REMOVED Requirements
+
+### Requirement: Future State Storage
+
+**Reason for removal**: Replaced by delta-based change storage which provides better review experience and clearer change tracking.
+
+**Migration path**: All new changes must use delta format.

openspec/changes/adopt-delta-based-changes/tasks.md

@@ -0,0 +1,39 @@
+# Implementation Tasks
+
+## 1. Update Conventions
+- [ ] 1.1 Update openspec-conventions spec with delta-based approach
+- [ ] 1.2 Add Header-Based Requirement Identification
+- [ ] 1.3 Define ADDED/MODIFIED/REMOVED/RENAMED sections
+- [ ] 1.4 Document standard output symbols (+ ~ - →)
+- [ ] 1.5 Update openspec/README.md with delta-based conventions
+- [ ] 1.6 Update examples to use delta format
+
+## 2. Update Diff Command
+- [ ] 2.1 Update cli-diff spec with requirement-level comparison
+- [ ] 2.2 Parse specs into requirement-level structures
+- [ ] 2.3 Apply deltas to generate future state
+- [ ] 2.4 Implement side-by-side comparison view (changes only)
+- [ ] 2.5 Add tests for requirement-level comparison
+- [ ] 2.6 Add tests for side-by-side view formatting
+
+## 3. Update Archive Command
+- [ ] 3.1 Update cli-archive spec with delta processing behavior
+- [ ] 3.2 Implement normalized header matching (trim whitespace)
+- [ ] 3.3 Parse delta sections (ADDED/MODIFIED/REMOVED/RENAMED)
+- [ ] 3.4 Apply changes in order: RENAMED → REMOVED → MODIFIED → ADDED
+- [ ] 3.5 Validate delta operations:
+  - [ ] 3.5.1 MODIFIED/REMOVED requirements exist
+  - [ ] 3.5.2 ADDED requirements don't already exist
+  - [ ] 3.5.3 RENAMED FROM headers exist, TO headers don't
+  - [ ] 3.5.4 No duplicate headers within specs
+  - [ ] 3.5.5 Renamed requirements aren't also in ADDED
+- [ ] 3.6 Display operation counts (+ 2 added, ~ 3 modified, etc.)
+- [ ] 3.7 Add tests for header normalization
+- [ ] 3.8 Add tests for applying deltas in correct order
+- [ ] 3.9 Add tests for validation edge cases
+
+## Notes
+- Archive command is critical path - must work reliably
+- All new changes must use delta format
+- Header normalization: normalize(header) = trim(header)
+- Diff command shows only changed requirements in side-by-side comparison

openspec/changes/structured-spec-format/tasks.md

@@ -1,19 +1,19 @@
 ## 1. Update OpenSpec Conventions Spec
 
-- [ ] 1.1 Add "Specification Format" section to openspec-conventions
-- [ ] 1.2 Document structured format with Requirement/Scenario headers
-- [ ] 1.3 Define bold keyword usage (WHEN/THEN/AND) for scenarios
-- [ ] 1.4 Include examples demonstrating the format within the spec itself
+- [x] 1.1 Add "Specification Format" section to openspec-conventions
+- [x] 1.2 Document structured format with Requirement/Scenario headers
+- [x] 1.3 Define bold keyword usage (WHEN/THEN/AND) for scenarios
+- [x] 1.4 Include examples demonstrating the format within the spec itself
 
 ## 2. Update Documentation
 
-- [ ] 2.1 Update the "Why This Approach" section with structured format benefits
-- [ ] 2.2 Ensure spec follows its own format as a demonstration
+- [x] 2.1 Update the "Why This Approach" section with structured format benefits
+- [x] 2.2 Ensure spec follows its own format as a demonstration
 
 ## 3. Update Existing Specs
 
-- [ ] 3.1 Update cli-init spec to use structured format in Behavior section
-- [ ] 3.2 Update cli-list spec to use structured format in Behavior section
-- [ ] 3.3 Update cli-update spec to use structured format in Behavior section
-- [ ] 3.4 Update cli-diff spec to use structured format in Behavior section
-- [ ] 3.5 Update cli-archive spec to use structured format in Behavior section
+- [x] 3.1 Update cli-init spec to use structured format in Behavior section
+- [x] 3.2 Update cli-list spec to use structured format in Behavior section
+- [x] 3.3 Update cli-update spec to use structured format in Behavior section
+- [x] 3.4 Update cli-diff spec to use structured format in Behavior section
+- [x] 3.5 Update cli-archive spec to use structured format in Behavior section

openspec/specs/cli-archive/spec.md

@@ -13,66 +13,98 @@ Options:
 
 ## Behavior
 
-### Change Selection
-WHEN no change-name is provided
-THEN display interactive list of available changes (excluding archive/)
-AND allow user to select one
+### Requirement: Change Selection
 
-WHEN change-name is provided
-THEN use that change directly
-AND validate it exists
+The command SHALL support both interactive and direct change selection methods.
 
-### Task Completion Check
-The command SHALL scan the change's tasks.md file for incomplete tasks (marked with `- [ ]`)
+#### Scenario: Interactive selection
 
-WHEN incomplete tasks are found
-THEN display all incomplete tasks to the user
-AND prompt for confirmation to continue
-AND default to "No" for safety
+- **WHEN** no change-name is provided
+- **THEN** display interactive list of available changes (excluding archive/)
+- **AND** allow user to select one
 
-WHEN all tasks are complete OR no tasks.md exists
-THEN proceed with archiving without prompting
+#### Scenario: Direct selection
 
-### Archive Process
-The archive operation SHALL:
-1. Create archive/ directory if it doesn't exist
-2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
-3. Check if target directory already exists
-4. Update main specs from the change's future state specs (see Spec Update Process below)
-5. Move the entire change directory to the archive location
+- **WHEN** change-name is provided
+- **THEN** use that change directly
+- **AND** validate it exists
 
-WHEN target archive already exists
-THEN fail with error message
-AND do not overwrite existing archive
+### Requirement: Task Completion Check
 
-WHEN move succeeds
-THEN display success message with archived name and list of updated specs
+The command SHALL verify task completion status before archiving to prevent premature archival.
 
-### Spec Update Process
-Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality:
+#### Scenario: Incomplete tasks found
 
-WHEN the change contains specs in `changes/[name]/specs/`
-THEN:
-1. Analyze which specs will be affected by comparing with existing specs
-2. Display a summary of spec updates to the user (see Confirmation Behavior below)
-3. Prompt for confirmation unless `--yes` flag is provided
-4. If confirmed, for each capability spec in the change directory:
-   - Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
-   - Create the target directory structure if it doesn't exist
-   - Overwrite existing spec files (specs represent current reality, change specs are the new reality)
-   - Track which specs were updated for the success message
+- **WHEN** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display all incomplete tasks to the user
+- **AND** prompt for confirmation to continue
+- **AND** default to "No" for safety
 
-WHEN no specs exist in the change
-THEN skip the spec update step
-AND proceed with archiving
+#### Scenario: All tasks complete
 
-### Confirmation Behavior
-The spec update confirmation SHALL:
-- Display a clear summary showing:
+- **WHEN** all tasks are complete OR no tasks.md exists
+- **THEN** proceed with archiving without prompting
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date
+  3. Check if target directory already exists
+  4. Update main specs from the change's future state specs (see Spec Update Process below)
+  5. Move the entire change directory to the archive location
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs
+
+### Requirement: Spec Update Process
+
+Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality.
+
+#### Scenario: Updating specs from change
+
+- **WHEN** the change contains specs in `changes/[name]/specs/`
+- **THEN** execute these steps:
+  1. Analyze which specs will be affected by comparing with existing specs
+  2. Display a summary of spec updates to the user (see Confirmation Behavior below)
+  3. Prompt for confirmation unless `--yes` flag is provided
+  4. If confirmed, for each capability spec in the change directory:
+     - Copy the spec from `changes/[name]/specs/[capability]/spec.md` to `openspec/specs/[capability]/spec.md`
+     - Create the target directory structure if it doesn't exist
+     - Overwrite existing spec files (specs represent current reality, change specs are the new reality)
+     - Track which specs were updated for the success message
+
+#### Scenario: No specs in change
+
+- **WHEN** no specs exist in the change
+- **THEN** skip the spec update step
+- **AND** proceed with archiving
+
+### Requirement: Confirmation Behavior
+
+The spec update confirmation SHALL provide clear visibility into changes before they are applied.
+
+#### Scenario: Displaying confirmation
+
+- **WHEN** prompting for confirmation
+- **THEN** display a clear summary showing:
   - Which specs will be created (new capabilities)
   - Which specs will be updated (existing capabilities)
   - The source path for each spec
-- Format the confirmation prompt as:
+- **AND** format the confirmation prompt as:
   ```
   The following specs will be updated:
   
@@ -84,21 +116,33 @@ The spec update confirmation SHALL:
   
   Update 2 specs and archive 'add-archive-command'? [y/N]:
   ```
-- Default to "No" for safety (require explicit "y" or "yes")
-- Skip confirmation when `--yes` or `-y` flag is provided
+#### Scenario: Handling confirmation response
 
-WHEN user declines the confirmation
-THEN abort the entire archive operation
-AND display message: "Archive cancelled. No changes were made."
-AND exit with non-zero status code
+- **WHEN** waiting for user confirmation
+- **THEN** default to "No" for safety (require explicit "y" or "yes")
+- **AND** skip confirmation when `--yes` or `-y` flag is provided
+
+#### Scenario: User declines confirmation
+
+- **WHEN** user declines the confirmation
+- **THEN** abort the entire archive operation
+- **AND** display message: "Archive cancelled. No changes were made."
+- **AND** exit with non-zero status code
 
 ## Error Handling
 
-SHALL handle the following error conditions:
-- Missing openspec/changes/ directory
-- Change not found
-- Archive target already exists
-- File system permissions issues
+### Requirement: Error Conditions
+
+The command SHALL handle various error conditions gracefully.
+
+#### Scenario: Handling errors
+
+- **WHEN** errors occur
+- **THEN** handle the following conditions:
+  - Missing openspec/changes/ directory
+  - Change not found
+  - Archive target already exists
+  - File system permissions issues
 
 ## Why These Decisions
 

openspec/specs/cli-diff/spec.md

@@ -12,45 +12,88 @@ openspec diff [change-name]
 
 ## Behavior
 
-### Without Arguments
+### Requirement: Without Arguments
 
-WHEN running `openspec diff` without arguments
-THEN list all available changes in the `changes/` directory (excluding archive)
-AND prompt user to select a change
+The command SHALL provide an interactive selection when no change is specified.
 
-### With Change Name
+#### Scenario: Running without arguments
 
-WHEN running `openspec diff <change-name>`
-THEN compare all spec files in `changes/<change-name>/specs/` with corresponding files in `specs/`
+- **WHEN** running `openspec diff` without arguments
+- **THEN** list all available changes in the `changes/` directory (excluding archive)
+- **AND** prompt user to select a change
 
-### Diff Output
+### Requirement: With Change Name
 
-FOR each spec file in the change:
-- IF file exists in both locations THEN show unified diff
-- IF file only exists in change THEN show as new file (all lines with +)
-- IF file only exists in current specs THEN show as deleted (all lines with -)
+The command SHALL compare specs when a specific change is provided.
 
-### Display Format
+#### Scenario: Running with change name
 
-The diff SHALL use standard unified diff format:
-- Lines prefixed with `-` for removed content
-- Lines prefixed with `+` for added content
-- Lines without prefix for unchanged context
-- File headers showing the paths being compared
+- **WHEN** running `openspec diff <change-name>`
+- **THEN** compare all spec files in `changes/<change-name>/specs/` with corresponding files in `specs/`
 
-### Color Support
+### Requirement: Diff Output
 
-WHEN terminal supports colors:
-- Removed lines displayed in red
-- Added lines displayed in green
-- File headers displayed in bold
-- Context lines in default color
+The command SHALL generate appropriate diff output for all spec changes.
 
-### Error Handling
+#### Scenario: Comparing existing files
 
-WHEN specified change doesn't exist THEN display error "Change '<name>' not found"
-WHEN no specs directory in change THEN display "No spec changes found for '<name>'"
-WHEN changes directory doesn't exist THEN display "No OpenSpec changes directory found"
+- **WHEN** file exists in both locations
+- **THEN** show unified diff
+
+#### Scenario: New files
+
+- **WHEN** file only exists in change
+- **THEN** show as new file (all lines with +)
+
+#### Scenario: Deleted files
+
+- **WHEN** file only exists in current specs
+- **THEN** show as deleted (all lines with -)
+
+### Requirement: Display Format
+
+The command SHALL use standard unified diff format for consistency with existing tools.
+
+#### Scenario: Formatting diff output
+
+- **WHEN** displaying diff output
+- **THEN** use standard unified diff format:
+  - Lines prefixed with `-` for removed content
+  - Lines prefixed with `+` for added content
+  - Lines without prefix for unchanged context
+  - File headers showing the paths being compared
+
+### Requirement: Color Support
+
+The command SHALL enhance readability with colors when supported.
+
+#### Scenario: Terminal with color support
+
+- **WHEN** terminal supports colors
+- **THEN** display:
+  - Removed lines in red
+  - Added lines in green
+  - File headers in bold
+  - Context lines in default color
+
+### Requirement: Error Handling
+
+The command SHALL provide clear error messages for various failure conditions.
+
+#### Scenario: Change not found
+
+- **WHEN** specified change doesn't exist
+- **THEN** display error "Change '<name>' not found"
+
+#### Scenario: No specs in change
+
+- **WHEN** no specs directory in change
+- **THEN** display "No spec changes found for '<name>'"
+
+#### Scenario: Missing changes directory
+
+- **WHEN** changes directory doesn't exist
+- **THEN** display "No OpenSpec changes directory found"
 
 ## Examples
 

openspec/specs/cli-init/spec.md

@@ -6,20 +6,28 @@ The `openspec init` command SHALL create a complete OpenSpec directory structure
 
 ## Behavior
 
-### Progress Indicators
+### Requirement: Progress Indicators
 
-WHEN executing initialization steps
-THEN validate environment silently in background (no output unless error)
-AND display progress with ora spinners:
-- Show spinner: "⠋ Creating OpenSpec structure..."
-- Then success: "✔ OpenSpec structure created"
-- Show spinner: "⠋ Configuring AI tools..."
-- Then success: "✔ AI tools configured"
+The command SHALL display progress indicators during initialization to provide clear feedback about each step.
 
-### Directory Creation
+#### Scenario: Displaying initialization progress
 
-WHEN `openspec init` is executed
-THEN create the following directory structure:
+- **WHEN** executing initialization steps
+- **THEN** validate environment silently in background (no output unless error)
+- **AND** display progress with ora spinners:
+  - Show spinner: "⠋ Creating OpenSpec structure..."
+  - Then success: "✔ OpenSpec structure created"
+  - Show spinner: "⠋ Configuring AI tools..."
+  - Then success: "✔ AI tools configured"
+
+### Requirement: Directory Creation
+
+The command SHALL create the complete OpenSpec directory structure with all required directories and files.
+
+#### Scenario: Creating OpenSpec structure
+
+- **WHEN** `openspec init` is executed
+- **THEN** create the following directory structure:
 ```
 openspec/
 ├── project.md
@@ -29,27 +37,41 @@ openspec/
     └── archive/
 ```
 
-### File Generation
+### Requirement: File Generation
 
-The command SHALL generate:
-- `README.md` containing complete OpenSpec instructions for AI assistants
-- `project.md` with project context template
+The command SHALL generate required template files with appropriate content for immediate use.
 
-### AI Tool Configuration
+#### Scenario: Generating template files
 
-WHEN run interactively
-THEN prompt user to select AI tools to configure:
-- Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
-- Cursor (future)
-- Aider (future)
+- **WHEN** initializing OpenSpec
+- **THEN** generate `README.md` containing complete OpenSpec instructions for AI assistants
+- **AND** generate `project.md` with project context template
 
-### AI Tool Configuration Details
+### Requirement: AI Tool Configuration
 
-WHEN Claude Code is selected
-THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+The command SHALL configure AI coding assistants with OpenSpec instructions based on user selection.
 
-WHEN CLAUDE.md does not exist
-THEN create new file with OpenSpec content wrapped in markers:
+#### Scenario: Prompting for AI tool selection
+
+- **WHEN** run interactively
+- **THEN** prompt user to select AI tools to configure:
+  - Claude Code (updates/creates CLAUDE.md with OpenSpec markers)
+  - Cursor (future)
+  - Aider (future)
+
+### Requirement: AI Tool Configuration Details
+
+The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.
+
+#### Scenario: Configuring Claude Code
+
+- **WHEN** Claude Code is selected
+- **THEN** create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+#### Scenario: Creating new CLAUDE.md
+
+- **WHEN** CLAUDE.md does not exist
+- **THEN** create new file with OpenSpec content wrapped in markers:
 ```markdown
 <!-- OPENSPEC:START -->
 # OpenSpec Project
@@ -62,51 +84,71 @@ See @openspec/README.md for detailed conventions and guidelines.
 <!-- OPENSPEC:END -->
 ```
 
-WHEN CLAUDE.md already exists
-THEN preserve all existing content
-AND insert OpenSpec content at the beginning of the file using markers
-AND ensure markers don't duplicate if they already exist
+#### Scenario: Updating existing CLAUDE.md
 
-The marker system SHALL:
-- Use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
-- Use `<!-- OPENSPEC:END -->` to mark the end of managed content
-- Allow OpenSpec to update its content without affecting user customizations
-- Preserve all content outside the markers intact
+- **WHEN** CLAUDE.md already exists
+- **THEN** preserve all existing content
+- **AND** insert OpenSpec content at the beginning of the file using markers
+- **AND** ensure markers don't duplicate if they already exist
+
+#### Scenario: Managing content with markers
+
+- **WHEN** using the marker system
+- **THEN** use `<!-- OPENSPEC:START -->` to mark the beginning of managed content
+- **AND** use `<!-- OPENSPEC:END -->` to mark the end of managed content
+- **AND** allow OpenSpec to update its content without affecting user customizations
+- **AND** preserve all content outside the markers intact
 
 WHY use markers:
 - Users may have existing CLAUDE.md instructions they want to keep
 - OpenSpec can update its instructions in future versions
 - Clear boundary between OpenSpec-managed and user-managed content
 
-### Interactive Mode
+### Requirement: Interactive Mode
 
-WHEN run
-THEN prompt user with: "Which AI tool do you use?"
-AND show single-select menu with available tools:
-- Claude Code
-AND show disabled options as "coming soon" (not selectable):
-- Cursor (coming soon)
-- Aider (coming soon)  
-- Continue (coming soon)
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
 
-User navigation:
-- Use arrow keys to move between options
-- Press Enter to select the highlighted option
+#### Scenario: Displaying interactive menu
 
-### Safety Checks
+- **WHEN** run
+- **THEN** prompt user with: "Which AI tool do you use?"
+- **AND** show single-select menu with available tools:
+  - Claude Code
+- **AND** show disabled options as "coming soon" (not selectable):
+  - Cursor (coming soon)
+  - Aider (coming soon)  
+  - Continue (coming soon)
 
-WHEN `openspec/` directory already exists
-THEN display error with ora fail indicator:
-"✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
+#### Scenario: Navigating the menu
 
-WHEN checking initialization feasibility
-THEN verify write permissions in the target directory silently
-AND only display error if permissions are insufficient
+- **WHEN** user is in the menu
+- **THEN** allow arrow keys to move between options
+- **AND** allow Enter key to select the highlighted option
 
-### Success Output
+### Requirement: Safety Checks
 
-WHEN initialization completes successfully
-THEN display actionable prompts for AI-driven workflow:
+The command SHALL perform safety checks to prevent overwriting existing structures and ensure proper permissions.
+
+#### Scenario: Detecting existing initialization
+
+- **WHEN** `openspec/` directory already exists
+- **THEN** display error with ora fail indicator:
+  - "✖ Error: OpenSpec seems to already be initialized. Use 'openspec update' to update the structure."
+
+#### Scenario: Checking write permissions
+
+- **WHEN** checking initialization feasibility
+- **THEN** verify write permissions in the target directory silently
+- **AND** only display error if permissions are insufficient
+
+### Requirement: Success Output
+
+The command SHALL provide clear, actionable next steps upon successful initialization.
+
+#### Scenario: Displaying success message
+
+- **WHEN** initialization completes successfully
+- **THEN** display actionable prompts for AI-driven workflow:
 ```
 ✔ OpenSpec initialized successfully!
 
@@ -132,12 +174,18 @@ The prompts SHALL:
 - Guide users through the AI-driven workflow
 - Replace placeholder text ([YOUR FEATURE HERE]) with actual features
 
-### Exit Codes
+### Requirement: Exit Codes
 
-- 0: Success
-- 1: General error (including when OpenSpec directory already exists)
-- 2: Insufficient permissions (reserved for future use)
-- 3: User cancelled operation (reserved for future use)
+The command SHALL use consistent exit codes to indicate different failure modes.
+
+#### Scenario: Returning exit codes
+
+- **WHEN** the command completes
+- **THEN** return appropriate exit code:
+  - 0: Success
+  - 1: General error (including when OpenSpec directory already exists)
+  - 2: Insufficient permissions (reserved for future use)
+  - 3: User cancelled operation (reserved for future use)
 
 ## Why
 

openspec/specs/cli-list/spec.md

@@ -6,28 +6,40 @@ The `openspec list` command SHALL provide developers with a quick overview of al
 
 ## Behavior
 
-### Command Execution
+### Requirement: Command Execution
 
-WHEN `openspec list` is executed
-THEN scan the `openspec/changes/` directory for change directories
-AND exclude the `archive/` subdirectory from results
-AND parse each change's `tasks.md` file to count task completion
+The command SHALL scan and analyze all active changes to provide a comprehensive overview.
 
-### Task Counting
+#### Scenario: Scanning for changes
 
-WHEN parsing a `tasks.md` file
-THEN count tasks matching these patterns:
-- Completed: Lines containing `- [x]`
-- Incomplete: Lines containing `- [ ]`
-AND calculate total tasks as the sum of completed and incomplete
+- **WHEN** `openspec list` is executed
+- **THEN** scan the `openspec/changes/` directory for change directories
+- **AND** exclude the `archive/` subdirectory from results
+- **AND** parse each change's `tasks.md` file to count task completion
 
-### Output Format
+### Requirement: Task Counting
 
-WHEN displaying the list
-THEN show a table with columns:
-- Change name (directory name)
-- Task progress (e.g., "3/5 tasks" or "✓ Complete")
-- Status indicator:
+The command SHALL accurately count task completion status using standard markdown checkbox patterns.
+
+#### Scenario: Counting tasks in tasks.md
+
+- **WHEN** parsing a `tasks.md` file
+- **THEN** count tasks matching these patterns:
+  - Completed: Lines containing `- [x]`
+  - Incomplete: Lines containing `- [ ]`
+- **AND** calculate total tasks as the sum of completed and incomplete
+
+### Requirement: Output Format
+
+The command SHALL display changes in a clear, readable table format with progress indicators.
+
+#### Scenario: Displaying change list
+
+- **WHEN** displaying the list
+- **THEN** show a table with columns:
+  - Change name (directory name)
+  - Task progress (e.g., "3/5 tasks" or "✓ Complete")
+- **AND** use status indicators:
   - `✓` for fully completed changes (all tasks done)
   - Progress fraction for partial completion
 
@@ -40,23 +52,38 @@ Changes:
   add-list-command     1/4 tasks
 ```
 
-### Empty State
+### Requirement: Empty State
 
-WHEN no active changes exist (only archive/ or empty changes/)
-THEN display: "No active changes found."
+The command SHALL provide clear feedback when no active changes are present.
 
-### Error Handling
+#### Scenario: Handling empty state
 
-IF a change directory has no `tasks.md` file
-THEN display the change with "No tasks" status
+- **WHEN** no active changes exist (only archive/ or empty changes/)
+- **THEN** display: "No active changes found."
 
-IF `openspec/changes/` directory doesn't exist
-THEN display error: "No OpenSpec changes directory found. Run 'openspec init' first."
-AND exit with code 1
+### Requirement: Error Handling
 
-### Sorting
+The command SHALL gracefully handle missing files and directories with appropriate messages.
 
-Changes SHALL be displayed in alphabetical order by change name for consistency.
+#### Scenario: Missing tasks.md file
+
+- **WHEN** a change directory has no `tasks.md` file
+- **THEN** display the change with "No tasks" status
+
+#### Scenario: Missing changes directory
+
+- **WHEN** `openspec/changes/` directory doesn't exist
+- **THEN** display error: "No OpenSpec changes directory found. Run 'openspec init' first."
+- **AND** exit with code 1
+
+### Requirement: Sorting
+
+The command SHALL maintain consistent ordering of changes for predictable output.
+
+#### Scenario: Ordering changes
+
+- **WHEN** displaying multiple changes
+- **THEN** sort them in alphabetical order by change name
 
 ## Why
 

openspec/specs/cli-update/spec.md

@@ -6,45 +6,65 @@ As a developer using OpenSpec, I want to update the OpenSpec instructions in my
 
 ## Core Requirements
 
-### Update Behavior
+### Requirement: Update Behavior
 
 The update command SHALL update OpenSpec instruction files to the latest templates.
 
-WHEN a user runs `openspec update` THEN the command SHALL:
-- Check if the `openspec` directory exists
-- Replace `openspec/README.md` with the latest template (complete replacement)
-- Update the OpenSpec-managed block in `CLAUDE.md` using markers
-  - Preserve user content outside markers
-  - Create `CLAUDE.md` if missing
-- Display ASCII-safe success message: "Updated OpenSpec instructions"
+#### Scenario: Running update command
 
-### Prerequisites
+- **WHEN** a user runs `openspec update`
+- **THEN** the command SHALL:
+  - Check if the `openspec` directory exists
+  - Replace `openspec/README.md` with the latest template (complete replacement)
+  - Update the OpenSpec-managed block in `CLAUDE.md` using markers
+    - Preserve user content outside markers
+    - Create `CLAUDE.md` if missing
+  - Display ASCII-safe success message: "Updated OpenSpec instructions"
 
-The command SHALL require:
-- An existing `openspec` directory (created by `openspec init`)
+### Requirement: Prerequisites
 
-IF the `openspec` directory does not exist THEN:
-- Display error: "No OpenSpec directory found. Run 'openspec init' first."
-- Exit with code 1
+The command SHALL require an existing OpenSpec structure before allowing updates.
 
-### File Handling
+#### Scenario: Checking prerequisites
 
-The update command SHALL:
-- Completely replace `openspec/README.md` with the latest template
-- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
-- Use the default directory name `openspec`
-- Be idempotent (repeated runs have no additional effect)
+- **GIVEN** the command requires an existing `openspec` directory (created by `openspec init`)
+- **WHEN** the `openspec` directory does not exist
+- **THEN** display error: "No OpenSpec directory found. Run 'openspec init' first."
+- **AND** exit with code 1
+
+### Requirement: File Handling
+
+The update command SHALL handle file updates in a predictable and safe manner.
+
+#### Scenario: Updating files
+
+- **WHEN** updating files
+- **THEN** completely replace `openspec/README.md` with the latest template
+- **AND** update only the OpenSpec-managed block in `CLAUDE.md` using markers
+- **AND** use the default directory name `openspec`
+- **AND** be idempotent (repeated runs have no additional effect)
 
 ## Edge Cases
 
-### File Permissions
-IF file write fails THEN let the error bubble up naturally with file path.
+### Requirement: Error Handling
 
-### Missing CLAUDE.md
-IF CLAUDE.md doesn't exist THEN create it with the template content.
+The command SHALL handle edge cases gracefully.
 
-### Custom Directory Name
-Not supported in this change. The default directory name `openspec` SHALL be used.
+#### Scenario: File permission errors
+
+- **WHEN** file write fails
+- **THEN** let the error bubble up naturally with file path
+
+#### Scenario: Missing CLAUDE.md
+
+- **WHEN** CLAUDE.md doesn't exist
+- **THEN** create it with the template content
+
+#### Scenario: Custom directory names
+
+- **WHEN** considering custom directory names
+- **THEN** not supported in this change
+- **AND** the default directory name `openspec` SHALL be used
 
 ## Success Criteria
 

openspec/specs/openspec-conventions/spec.md

@@ -14,8 +14,14 @@ The system SHALL follow these principles:
 
 ## Directory Structure
 
-WHEN an OpenSpec project is initialized
-THEN it SHALL have this structure:
+### Requirement: Project Structure
+
+An OpenSpec project SHALL maintain a consistent directory structure for specifications and changes.
+
+#### Scenario: Initializing project structure
+
+- **WHEN** an OpenSpec project is initialized
+- **THEN** it SHALL have this structure:
 ```
 openspec/
 ├── project.md              # Project-specific context
@@ -36,23 +42,63 @@ openspec/
         └── YYYY-MM-DD-[name]/
 ```
 
+## Specification Format
+
+### Requirement: Structured Format for Behavioral Specs
+
+Behavioral specifications SHALL use a structured format with consistent section headers and keywords to ensure visual consistency and parseability.
+
+#### Scenario: Writing requirement sections
+
+- **WHEN** documenting a requirement in a behavioral specification
+- **THEN** use a level-3 heading with format `### Requirement: [Name]`
+- **AND** immediately follow with a SHALL statement describing core behavior
+- **AND** keep requirement names descriptive and under 50 characters
+
+#### Scenario: Documenting scenarios
+
+- **WHEN** documenting specific behaviors or use cases
+- **THEN** use level-4 headings with format `#### Scenario: [Description]`
+- **AND** use bullet points with bold keywords for steps:
+  - **GIVEN** for initial state (optional)
+  - **WHEN** for conditions or triggers
+  - **THEN** for expected outcomes
+  - **AND** for additional outcomes or conditions
+
+#### Scenario: Adding implementation details
+
+- **WHEN** a step requires additional detail
+- **THEN** use sub-bullets under the main step
+- **AND** maintain consistent indentation
+  - Sub-bullets provide examples or specifics
+  - Keep sub-bullets concise
+
+
 ## Change Storage Convention
 
-### Future State Storage
+### Requirement: Future State Storage
 
-WHEN creating a change proposal
-THEN store the complete future state of affected specs
-AND use clean markdown without diff syntax
+Change proposals SHALL store complete future state specifications without diff syntax.
+
+#### Scenario: Creating change proposals
+
+- **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
+### Requirement: Proposal Format
 
-WHEN documenting what changes
-THEN the proposal SHALL explicitly describe each change:
+Proposals SHALL explicitly document all changes with clear from/to comparisons.
+
+#### Scenario: Documenting changes
+
+- **WHEN** documenting what changes
+- **THEN** the proposal SHALL explicitly describe each change:
 
 ```markdown
 **[Section or Behavior Name]**
@@ -78,8 +124,14 @@ The change process SHALL follow these states:
 
 ## Viewing Changes
 
-WHEN reviewing proposed changes
-THEN reviewers can compare using:
+### Requirement: Change Review
+
+The system SHALL support multiple methods for reviewing proposed changes.
+
+#### Scenario: Reviewing 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
@@ -117,4 +169,9 @@ Clean future state storage provides:
 - **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
+- **Clear intent**: Explicit proposals document reasoning
+
+The structured format adds:
+- **Visual Consistency**: Requirement and Scenario prefixes make sections instantly recognizable
+- **Parseability**: Consistent structure enables tooling and automation
+- **Gradual Adoption**: Existing specs can migrate incrementally