feat: add OpenSpec change proposal for archive command

feat: add diff command to view spec changes

openspec/changes/add-archive-command/proposal.md

@@ -0,0 +1,12 @@
+## Why
+Need a command to archive completed changes to the archive folder with proper date prefixing, following OpenSpec conventions. Currently changes must be manually moved and renamed.
+
+## What Changes
+- Add new `archive` command to CLI that moves changes to `changes/archive/YYYY-MM-DD-[change-name]/`
+- Check for incomplete tasks before archiving and warn user
+- Allow interactive selection of change to archive
+- Prevent archiving if target directory already exists
+
+## Impact
+- Affected specs: cli-archive (new)
+- Affected code: src/cli/index.ts, src/core/archive.ts (new)

openspec/changes/add-archive-command/specs/cli-archive/spec.md

@@ -0,0 +1,60 @@
+# CLI Archive Command Specification
+
+## Purpose
+The archive command moves completed changes from the active changes directory to the archive folder with date-based naming, following OpenSpec conventions.
+
+## Command Syntax
+```bash
+openspec archive [change-name]
+```
+
+## Behavior
+
+### Change Selection
+WHEN no change-name is provided
+THEN display interactive list of available changes (excluding archive/)
+AND allow user to select one
+
+WHEN change-name is provided
+THEN use that change directly
+AND validate it exists
+
+### Task Completion Check
+The command SHALL scan the change's tasks.md file for incomplete tasks (marked with `- [ ]`)
+
+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 all tasks are complete OR no tasks.md exists
+THEN proceed with archiving without prompting
+
+### 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. Move the entire change directory to the archive location
+
+WHEN target archive already exists
+THEN fail with error message
+AND do not overwrite existing archive
+
+WHEN move succeeds
+THEN display success message with archived name
+
+## Error Handling
+
+SHALL handle the following error conditions:
+- Missing openspec/changes/ directory
+- Change not found
+- Archive target already exists
+- File system permissions issues
+
+## Why These Decisions
+
+**Interactive selection**: Reduces typing and helps users see available changes
+**Task checking**: Prevents accidental archiving of incomplete work
+**Date prefixing**: Maintains chronological order and prevents naming conflicts
+**No overwrite**: Preserves historical archives and prevents data loss

openspec/changes/add-archive-command/tasks.md

@@ -0,0 +1,30 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [ ] 1.1 Create `src/core/archive.ts` with ArchiveCommand class
+  - [ ] 1.1.1 Implement change selection (interactive if not provided)
+  - [ ] 1.1.2 Implement incomplete task checking from tasks.md
+  - [ ] 1.1.3 Implement confirmation prompt for incomplete tasks
+  - [ ] 1.1.4 Implement archive move with date prefixing
+
+## 2. CLI Integration
+- [ ] 2.1 Add archive command to `src/cli/index.ts`
+  - [ ] 2.1.1 Import ArchiveCommand
+  - [ ] 2.1.2 Register command with commander
+  - [ ] 2.1.3 Add proper error handling
+
+## 3. Error Handling
+- [ ] 3.1 Handle missing openspec/changes/ directory
+- [ ] 3.2 Handle change not found
+- [ ] 3.3 Handle archive target already exists
+- [ ] 3.4 Handle user cancellation
+
+## 4. Testing
+- [ ] 4.1 Test with fully completed change
+- [ ] 4.2 Test with incomplete tasks (warning shown)
+- [ ] 4.3 Test interactive selection mode
+- [ ] 4.4 Test duplicate archive prevention
+
+## 5. Build and Validation
+- [ ] 5.1 Ensure TypeScript compilation succeeds
+- [ ] 5.2 Test command execution

openspec/changes/add-list-command/proposal.md

@@ -0,0 +1,20 @@
+# Add List Command to OpenSpec CLI
+
+## Why
+
+Developers need visibility into available changes and their status to understand the project's evolution and pending work.
+
+## What Changes
+
+- Add `openspec list` command that displays all changes in the changes/ directory
+- Show each change name with task completion count (e.g., "add-auth: 3/5 tasks")
+- Display completion status indicator (✓ for fully complete, progress for partial)
+- Skip the archive/ subdirectory to focus on active changes
+- Simple table output for easy scanning
+
+## Impact
+
+- Affected specs: New capability `cli-list` will be added
+- Affected code:
+  - `src/cli/index.ts` - Add list command
+  - `src/core/list.ts` - New file with directory scanning and task parsing (~60 lines)

openspec/changes/add-list-command/specs/cli-list/spec.md

@@ -0,0 +1,69 @@
+# List Command Specification
+
+## Purpose
+
+The `openspec list` command SHALL provide developers with a quick overview of all active changes in the project, showing their names and task completion status.
+
+## Behavior
+
+### 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
+
+### Task Counting
+
+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
+
+### Output Format
+
+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:
+  - `✓` for fully completed changes (all tasks done)
+  - Progress fraction for partial completion
+
+Example output:
+```
+Changes:
+  add-auth-feature     3/5 tasks
+  update-api-docs      ✓ Complete
+  fix-validation       0/2 tasks
+  add-list-command     1/4 tasks
+```
+
+### Empty State
+
+WHEN no active changes exist (only archive/ or empty changes/)
+THEN display: "No active changes found."
+
+### Error Handling
+
+IF a change directory has no `tasks.md` file
+THEN display the change with "No tasks" status
+
+IF `openspec/changes/` directory doesn't exist
+THEN display error: "No OpenSpec changes directory found. Run 'openspec init' first."
+AND exit with code 1
+
+### Sorting
+
+Changes SHALL be displayed in alphabetical order by change name for consistency.
+
+## Why
+
+Developers need a quick way to:
+- See what changes are in progress
+- Identify which changes are ready to archive
+- Understand the overall project evolution status
+- Get a bird's-eye view without opening multiple files
+
+This command provides that visibility with minimal effort, following OpenSpec's philosophy of simplicity and clarity.

openspec/changes/add-list-command/tasks.md

@@ -0,0 +1,26 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [ ] 1.1 Create `src/core/list.ts` with list logic
+  - [ ] 1.1.1 Implement directory scanning (exclude archive/)
+  - [ ] 1.1.2 Implement task counting from tasks.md files
+  - [ ] 1.1.3 Format output as simple table
+- [ ] 1.2 Add list command to CLI in `src/cli/index.ts`
+  - [ ] 1.2.1 Register `openspec list` command
+  - [ ] 1.2.2 Connect to list.ts implementation
+
+## 2. Error Handling
+- [ ] 2.1 Handle missing openspec/changes/ directory
+- [ ] 2.2 Handle changes without tasks.md files
+- [ ] 2.3 Handle empty changes directory
+
+## 3. Testing
+- [ ] 3.1 Add tests for list functionality
+  - [ ] 3.1.1 Test with multiple changes
+  - [ ] 3.1.2 Test with completed changes
+  - [ ] 3.1.3 Test with no changes
+  - [ ] 3.1.4 Test error conditions
+
+## 4. Documentation
+- [ ] 4.1 Update CLI help text with list command
+- [ ] 4.2 Add list command to README if applicable

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

@@ -0,0 +1,15 @@
+# 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

@@ -0,0 +1,219 @@
+# 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

@@ -0,0 +1,24 @@
+# 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