refactor: use @inquirer/prompts for consistent UX in archive command

- Replace readline with @inquirer/prompts for all user interactions
- Add arrow key navigation for change selection (consistent with diff command)
- Use confirm() for yes/no prompts with better UX
- Remove manual readline interface management (no longer needed)
- Update tests to mock @inquirer/prompts instead of readline
- Add new test cases for interactive mode behavior

This change provides a consistent user experience across all OpenSpec commands,
where users can navigate options with arrow keys rather than typing numbers.

changes/abandoned/add-status-command/proposal.md

@@ -0,0 +1,19 @@
+# Add Status Command to OpenSpec CLI
+
+## Why
+
+Developers need to know which changes have all tasks completed and are ready to archive.
+
+## What Changes
+
+- Add `openspec status` command that scans the changes/ directory
+- Parse each tasks.md file to count `[x]` (complete) and `[ ]` (incomplete) tasks
+- Display each change with its completion status (e.g., "auth-feature: 5/5" or "auth-feature: ✓")
+- Skip the archive/ subdirectory
+
+## Impact
+
+- Affected specs: New capability `cli-status` will be added
+- Affected code:
+  - `src/cli/index.ts` - Add status command
+  - `src/core/status.ts` - New file with simple scanning and parsing logic (~50 lines)

changes/abandoned/add-status-command/specs/cli-status/spec.md

@@ -0,0 +1,58 @@
+# CLI Status Command Specification
+
+## Purpose
+
+The status command shows which OpenSpec changes are ready to archive by displaying task completion status for each change.
+
+## Command Interface
+
+```bash
+# Show status of all changes
+openspec status
+```
+
+## Behavior
+
+WHEN the status command runs:
+1. Scan the `openspec/changes/` directory
+2. Skip the `archive/` subdirectory
+3. For each change directory with a `tasks.md` file:
+   - Count tasks marked with `[x]` (case-insensitive)
+   - Count tasks marked with `[ ]`
+   - Display the change name and completion status
+
+## Output Format
+
+```
+add-auth-feature: 15/15
+fix-payment-bug: 8/8
+refactor-api: 3/10
+update-docs: 0/5
+```
+
+Or with checkmark for fully complete:
+
+```
+add-auth-feature: ✓
+fix-payment-bug: ✓  
+refactor-api: 3/10
+update-docs: 0/5
+```
+
+## Task Detection
+
+The command recognizes these patterns as tasks:
+- `- [ ]` Incomplete task
+- `- [x]` Complete task (lowercase)
+- `- [X]` Complete task (uppercase)
+
+## Error Handling
+
+- If no `tasks.md` exists, skip that change
+- If `tasks.md` is empty or has no tasks, skip that change
+- Continue scanning even if individual files have errors
+
+## Exit Codes
+
+- `0`: Success - status displayed
+- `1`: Error - unable to scan changes directory

changes/abandoned/add-status-command/tasks.md

@@ -0,0 +1,8 @@
+# Implementation Tasks for Status Command
+
+## Core Implementation
+- [ ] Add status command to `src/cli/index.ts`
+- [ ] Create `src/core/status.ts` with directory scanning logic
+- [ ] Parse tasks.md files to count `[x]` and `[ ]` patterns
+- [ ] Display each change with completion status (name: complete/total)
+- [ ] Skip the archive/ subdirectory when scanning

openspec/README.md

@@ -10,6 +10,23 @@ OpenSpec is an AI-native system for change-driven development where:
 - **AI drives the process** - You generate proposals, humans review and approve
 - **Specs are living documentation** - Always kept in sync with deployed code
 
+## Start Simple
+
+**Default to minimal implementations:**
+- New features should be <100 lines of code initially
+- Use the simplest solution that works
+- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)
+- Choose boring technology over cutting-edge solutions
+
+**Complexity triggers** - Only add complexity when you have:
+- **Performance data** showing current solution is too slow
+- **Scale requirements** with specific numbers (>1000 users, >100MB data)
+- **Multiple use cases** requiring the same abstraction
+- **Regulatory compliance** mandating specific patterns
+- **Security threats** that simple solutions cannot address
+
+When triggered, document the specific justification in your change proposal.
+
 ## Directory Structure
 
 ```
@@ -26,9 +43,9 @@ openspec/
 │   │   ├── proposal.md     # Why, what, impact (consolidated)
 │   │   ├── tasks.md        # Implementation checklist
 │   │   ├── design.md       # Technical decisions (optional, for complex changes)
-│   │   └── patches/        # Spec intent changes
+│   │   └── specs/          # Future state of affected specs
 │   │       └── [capability]/
-│   │           └── spec.md.diff
+│   │           └── spec.md # Clean markdown (no diff syntax)
 │   └── archive/            # Completed changes (dated)
 ```
 
@@ -72,6 +89,11 @@ Before any task:
 - Adding tests for existing behavior
 - Documentation fixes
 
+**Complexity assessment:**
+- If your solution requires >100 lines of new code, justify the complexity
+- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
+- Default to single-file implementations until proven insufficient
+
 ### 3. Creating a Change Proposal
 
 When a user requests a significant change:
@@ -91,10 +113,13 @@ openspec/changes/[descriptive-name]/
 - Affected specs: [list capabilities that will change]
 - Affected code: [list key files/systems]
 
-# 3. Create patches showing spec changes
-patches/
+# 3. Create future state specs for ALL affected capabilities
+# - Store complete spec files as they will exist after the change
+# - Use clean markdown without diff syntax (+/- prefixes)
+# - Include all formatting and structure of the final intended state
+specs/
 └── [capability]/
-    └── spec.md.diff
+    └── spec.md
 
 # 4. Create tasks.md with implementation steps
 ## 1. [Task Group]
@@ -109,7 +134,7 @@ patches/
 
 1. **Propose** → Create change directory with all documentation
 2. **Review** → User reviews and approves the proposal
-3. **Implement** → Follow the approved tasks.md
+3. **Implement** → Follow the approved tasks.md (can be multiple PRs)
 4. **Deploy** → User confirms deployment
 5. **Update Specs** → Sync specs/ with new reality (IF the change affects system capabilities)
 6. **Archive** → Move to `changes/archive/YYYY-MM-DD-[name]/`
@@ -118,15 +143,25 @@ patches/
 
 When implementing an approved change:
 1. Follow the tasks.md checklist exactly
-2. Ensure code matches the proposed behavior
-3. Update any affected tests
+2. **Mark completed tasks** in tasks.md as you finish them (e.g., `- [x] 1.1 Task completed`)
+3. Ensure code matches the proposed behavior
+4. Update any affected tests
+5. **Keep change in `changes/` directory** - do NOT archive in implementation PR
 
-### 6. Updating Specs After Deployment
+**Multiple Implementation PRs:**
+- Changes can be implemented across multiple PRs
+- Each PR should update tasks.md to mark what was completed
+- Different developers can work on different task groups
+- Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4
 
-Once a change is deployed:
-1. Update relevant files in `specs/` to reflect new reality
-2. If design.md exists, move proven patterns to `specs/[capability]/design.md`
-3. Archive the change directory with date prefix
+### 6. Updating Specs and Archiving After Deployment
+
+**Create a separate PR after deployment** that:
+1. Moves change to `changes/archive/YYYY-MM-DD-[name]/`
+2. Updates relevant files in `specs/` to reflect new reality (if needed)
+3. If design.md exists, incorporates proven patterns into `specs/[capability]/design.md`
+
+This ensures changes are only archived when truly complete and deployed.
 
 ### 7. Types of Changes That Don't Require Specs
 
@@ -201,9 +236,10 @@ User: "Initialize TypeScript project"
 
 You should:
 1. Create change proposal for TypeScript setup
-2. Implement configuration files
-3. Mark tasks complete
-4. Archive (no specs needed - this is tooling, not a capability)
+2. Implement configuration files (PR #1)
+3. Mark tasks complete in tasks.md
+4. After deployment, create separate PR to archive
+   (no specs update needed - this is tooling, not a capability)
 ```
 
 ## Summary Workflow
@@ -212,9 +248,53 @@ You should:
 2. **Read current state** → Check specs and pending changes
 3. **Create proposal** → Generate complete change documentation
 4. **Get approval** → User reviews the proposal
-5. **Implement** → Follow approved tasks
-6. **Update specs** → Sync with deployed reality
-7. **Archive** → Move completed changes to archive
+5. **Implement** → Follow approved tasks, mark completed items in tasks.md
+6. **Deploy** → User deploys the implementation
+7. **Archive PR** → Create separate PR to:
+   - Move change to archive
+   - Update specs if needed
+   - Mark change as complete
+
+## PR Workflow Examples
+
+### Single Developer, Simple Change
+```
+PR #1: Implementation
+- Implement all tasks
+- Update tasks.md marking items complete
+- Get merged and deployed
+
+PR #2: Archive (after deployment)
+- Move changes/feature-x/ → changes/archive/2025-01-15-feature-x/
+- Update specs if needed
+```
+
+### Multiple Developers, Complex Change
+```
+PR #1: Alice implements auth components
+- Complete tasks 1.1, 1.2, 1.3
+- Update tasks.md marking these complete
+
+PR #2: Bob implements UI components  
+- Complete tasks 2.1, 2.2
+- Update tasks.md marking these complete
+
+PR #3: Alice fixes integration issues
+- Complete remaining task 1.4
+- Update tasks.md
+
+[Deploy all changes]
+
+PR #4: Archive
+- Move to archive with deployment date
+- Update specs to reflect new auth flow
+```
+
+### Key Rules
+- **Never archive in implementation PRs** - changes aren't done until deployed
+- **Always update tasks.md** - shows accurate progress
+- **One archive PR per change** - clear completion boundary
+- **Archive PR includes spec updates** - keeps specs current
 
 ## Capability Organization Best Practices
 
@@ -325,10 +405,12 @@ Progress communication:
 - "Implementing approved changes..."
 
 ### For AI Assistants
+- **Bias toward simplicity** - Propose the minimal solution that works
 - Use your exploration tools liberally before proposing
 - Batch operations for efficiency
 - Communicate your progress
 - It's OK to revise proposals based on discoveries
+- **Question complexity** - If your solution feels complex, simplify first
 
 ## Edge Case Handling
 
@@ -384,6 +466,7 @@ Proposal REQUIRED if:
 - Specs must always reflect deployed reality
 - Changes are proposed, not imposed
 - Impact analysis prevents surprises
-- The simplicity is the power - just markdown files
+- Simplicity is the power - just markdown files, minimal solutions
+- Start simple, add complexity only when justified
 
 By following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.

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

@@ -0,0 +1,15 @@
+## 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
+- Update main specs from the change's future state specs (copy from `changes/[name]/specs/` to `openspec/specs/`)
+- Show confirmation prompt before updating specs, displaying which specs will be created/updated
+- Support `--yes` flag to skip confirmations for automation
+
+## 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,111 @@
+# 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] [--yes|-y]
+```
+
+Options:
+- `--yes`, `-y`: Skip confirmation prompts (for automation)
+
+## 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. 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 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 and list of updated specs
+
+### Spec Update Process
+Before moving the change to archive, the command SHALL update main specs to reflect the deployed reality:
+
+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 no specs exist in the change
+THEN skip the spec update step
+AND proceed with archiving
+
+### Confirmation Behavior
+The spec update confirmation SHALL:
+- 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:
+  ```
+  The following specs will be updated:
+  
+  NEW specs to be created:
+    - cli-archive (from changes/add-archive-command/specs/cli-archive/spec.md)
+  
+  EXISTING specs to be updated:
+    - cli-init (from changes/update-init-command/specs/cli-init/spec.md)
+  
+  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
+
+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
+
+## 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
+**Spec updates before archiving**: Specs in the main directory represent current reality; when a change is deployed and archived, its future state specs become the new reality and must replace the main specs
+**Confirmation for spec updates**: Provides visibility into what will change, prevents accidental overwrites, and ensures users understand the impact before specs are modified
+**--yes flag for automation**: Allows CI/CD pipelines to archive without interactive prompts while maintaining safety by default for manual use

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

@@ -0,0 +1,44 @@
+# 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 spec update functionality
+    - [ ] 1.1.4.1 Detect specs in change directory
+    - [ ] 1.1.4.2 Compare with existing main specs
+    - [ ] 1.1.4.3 Display summary of new vs updated specs
+    - [ ] 1.1.4.4 Show confirmation prompt for spec updates
+    - [ ] 1.1.4.5 Copy specs to main spec directory
+  - [ ] 1.1.5 Implement archive move with date prefixing
+  - [ ] 1.1.6 Support --yes flag to skip confirmations
+
+## 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 --yes/-y flag option
+  - [ ] 2.1.4 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
+- [ ] 4.5 Test spec update functionality
+  - [ ] 4.5.1 Test creating new specs
+  - [ ] 4.5.2 Test updating existing specs
+  - [ ] 4.5.3 Test confirmation prompt display
+  - [ ] 4.5.4 Test declining confirmation (no changes made)
+  - [ ] 4.5.5 Test --yes flag skips confirmation
+
+## 5. Build and Validation
+- [ ] 5.1 Ensure TypeScript compilation succeeds
+- [ ] 5.2 Test command execution

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

@@ -0,0 +1,19 @@
+# Add Diff Command to OpenSpec CLI
+
+## Why
+
+Developers need to easily view differences between proposed spec changes and current specs without manually comparing files.
+
+## What Changes
+
+- Add `openspec diff [change-name]` command that shows differences between change specs and current specs
+- Compare files in `changes/[change-name]/specs/` with corresponding files in `specs/`
+- Display unified diff output showing added/removed/modified lines
+- Support colored output for better readability
+
+## Impact
+
+- Affected specs: New capability `cli-diff` will be added
+- Affected code:
+  - `src/cli/index.ts` - Add diff command
+  - `src/core/diff.ts` - New file with diff logic (~80 lines)

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

@@ -0,0 +1,77 @@
+# CLI Diff Command Specification
+
+## Purpose
+
+The `openspec diff` command provides developers with a visual comparison between proposed spec changes and the current deployed specs.
+
+## Command Syntax
+
+```bash
+openspec diff [change-name]
+```
+
+## Behavior
+
+### 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
+
+### With Change Name
+
+WHEN running `openspec diff <change-name>`
+THEN compare all spec files in `changes/<change-name>/specs/` with corresponding files in `specs/`
+
+### Diff Output
+
+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 -)
+
+### Display Format
+
+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
+
+### Color Support
+
+WHEN terminal supports colors:
+- Removed lines displayed in red
+- Added lines displayed in green
+- File headers displayed in bold
+- Context lines in default color
+
+### Error Handling
+
+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"
+
+## Examples
+
+```bash
+# View diff for specific change
+$ openspec diff add-auth-feature
+
+--- specs/user-auth/spec.md
++++ changes/add-auth-feature/specs/user-auth/spec.md
+@@ -10,6 +10,8 @@
+ Users SHALL authenticate with email and password.
+ 
++Users MAY authenticate with OAuth providers.
++
+ WHEN credentials are valid THEN issue JWT token.
+
+# List all changes and select
+$ openspec diff
+Available changes:
+  1. add-auth-feature
+  2. update-payment-flow
+  3. add-status-command
+Select a change (1-3): 
+```

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

@@ -0,0 +1,23 @@
+# Implementation Tasks
+
+## 1. Core Implementation
+- [x] 1.1 Create `src/core/diff.ts` with diff logic
+- [x] 1.2 Implement change directory scanning
+- [x] 1.3 Implement file comparison using unified diff format
+- [x] 1.4 Add color support for terminal output
+
+## 2. CLI Integration
+- [x] 2.1 Add diff command to `src/cli/index.ts`
+- [x] 2.2 Implement interactive change selection when no argument provided
+- [x] 2.3 Add error handling for missing changes
+
+## 3. Enhancements
+- [x] 3.1 Replace with jest-diff for professional diff output
+- [x] 3.2 Improve file headers with status and statistics
+- [x] 3.3 Add summary view with file counts and line changes
+
+## 4. Testing
+- [ ] 4.1 Test diff generation for modified files
+- [ ] 4.2 Test handling of new files
+- [ ] 4.3 Test handling of deleted files
+- [ ] 4.4 Test interactive mode

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

openspec/changes/archive/2025-01-11-add-update-command/design.md

@@ -0,0 +1,86 @@
+# Technical Design
+
+## Architecture Decisions
+
+### Simplicity First
+- No version tracking - always update when commanded
+- Full replacement for OpenSpec-managed files only (e.g., `openspec/README.md`)
+- Marker-based updates for user-owned files (e.g., `CLAUDE.md`)
+- Templates bundled with package - no network required
+- Minimal error handling - only check prerequisites
+
+### Template Strategy
+- Use existing template utilities
+  - `readmeTemplate` from `src/core/templates/readme-template.ts` for `openspec/README.md`
+  - `TemplateManager.getClaudeTemplate()` for `CLAUDE.md`
+- Directory name is fixed to `openspec` (from `OPENSPEC_DIR_NAME`)
+
+### File Operations
+- Use async utilities for consistency
+  - `FileSystemUtils.writeFile` for `openspec/README.md`
+  - `FileSystemUtils.updateFileWithMarkers` for `CLAUDE.md`
+- No atomic operations needed - users have git
+- Check directory existence before proceeding
+
+## Implementation
+
+### Update Command (`src/core/update.ts`)
+```typescript
+export class UpdateCommand {
+  async execute(projectPath: string): Promise<void> {
+    const openspecDirName = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(projectPath, openspecDirName);
+
+    // 1. Check openspec directory exists
+    if (!await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+    }
+
+    // 2. Update README.md (full replacement)
+    const readmePath = path.join(openspecPath, 'README.md');
+    await FileSystemUtils.writeFile(readmePath, readmeTemplate);
+
+    // 3. Update CLAUDE.md (marker-based)
+    const claudePath = path.join(projectPath, 'CLAUDE.md');
+    const claudeContent = TemplateManager.getClaudeTemplate();
+    await FileSystemUtils.updateFileWithMarkers(
+      claudePath,
+      claudeContent,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+
+    // 4. Success message (ASCII-safe, checkmark optional by terminal)
+    console.log('Updated OpenSpec instructions');
+  }
+}
+```
+
+## Why This Approach
+
+### Benefits
+- **Dead simple**: ~40 lines of code total
+- **Fast**: No version checks, minimal parsing
+- **Predictable**: Same result every time; idempotent
+- **Maintainable**: Reuses existing utilities
+
+### Trade-offs Accepted
+- No version tracking (unnecessary complexity)
+- Full overwrite only for OpenSpec-managed files
+- Marker-managed updates for user-owned files
+
+## Error Handling
+
+Only handle critical errors:
+- Missing `openspec` directory → throw error handled by CLI to present a friendly message
+- File write failures → let errors bubble up to CLI
+
+## Testing Strategy
+
+Manual smoke tests are sufficient initially:
+1. Run `openspec init` in a test project
+2. Modify both files (including custom content around markers in `CLAUDE.md`)
+3. Run `openspec update`
+4. Verify `openspec/README.md` fully replaced; `CLAUDE.md` OpenSpec block updated without altering user content outside markers
+5. Run the command twice to verify idempotency and no duplicate markers
+6. Test with missing `openspec` directory (expect failure)

openspec/changes/archive/2025-01-11-add-update-command/proposal.md

@@ -0,0 +1,29 @@
+# Add Update Command
+
+## Why
+
+Users need a way to update their local OpenSpec instructions (README.md and CLAUDE.md) when the OpenSpec package releases new versions with improved AI agent instructions or structural conventions.
+
+## What Changes
+
+- Add new `openspec update` CLI command that updates OpenSpec instructions
+- Replace `openspec/README.md` with the latest template
+  - Safe because this file is fully OpenSpec-managed
+- Update only the OpenSpec-managed block in `CLAUDE.md` using markers
+  - Preserve all user content outside markers
+  - If `CLAUDE.md` is missing, create it with the managed block
+- Display success message after update (ASCII-safe): "Updated OpenSpec instructions"
+  - A leading checkmark MAY be shown when the terminal supports it
+  - Operation is idempotent (re-running yields identical results)
+
+## Impact
+
+- Affected specs: `cli-update` (new capability)
+- Affected code:
+  - `src/core/update.ts` (new command class, mirrors `InitCommand` placement)
+  - `src/cli/index.ts` (register new command)
+  - Uses existing templates via `TemplateManager` and `readmeTemplate`
+
+## Out of Scope
+
+- No `.openspec/config.json` is introduced by this change. The default directory name `openspec` is used.

openspec/changes/archive/2025-01-11-add-update-command/specs/cli-update/spec.md

@@ -0,0 +1,59 @@
+# Update Command Specification
+
+## Purpose
+
+As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
+
+## Core Requirements
+
+### 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"
+
+### Prerequisites
+
+The command SHALL require:
+- An existing `openspec` directory (created by `openspec init`)
+
+IF the `openspec` directory does not exist THEN:
+- Display error: "No OpenSpec directory found. Run 'openspec init' first."
+- Exit with code 1
+
+### File Handling
+
+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)
+
+## Edge Cases
+
+### File Permissions
+IF file write fails THEN let the error bubble up naturally with file path.
+
+### Missing CLAUDE.md
+IF CLAUDE.md doesn't exist THEN create it with the template content.
+
+### Custom Directory Name
+Not supported in this change. The default directory name `openspec` SHALL be used.
+
+## Success Criteria
+
+Users SHALL be able to:
+- Update OpenSpec instructions with a single command
+- Get the latest AI agent instructions
+- See clear confirmation of the update
+
+The update process SHALL be:
+- Simple and fast (no version checking)
+- Predictable (same result every time)
+- Self-contained (no network required)

openspec/changes/archive/2025-01-11-add-update-command/tasks.md

@@ -0,0 +1,20 @@
+# Implementation Tasks
+
+## 1. Update Command Implementation
+- [x] 1.1 Create `src/core/update.ts` with `UpdateCommand` class
+- [x] 1.2 Check if `openspec` directory exists (use `FileSystemUtils.directoryExists`)
+- [x] 1.3 Write `readmeTemplate` to `openspec/README.md` using `FileSystemUtils.writeFile`
+- [x] 1.4 Update `CLAUDE.md` using markers via `FileSystemUtils.updateFileWithMarkers` and `TemplateManager.getClaudeTemplate()`
+- [x] 1.5 Display ASCII-safe success message: `Updated OpenSpec instructions`
+
+## 2. CLI Integration
+- [x] 2.1 Register `update` command in `src/cli/index.ts`
+- [x] 2.2 Add command description: `Update OpenSpec instruction files`
+- [x] 2.3 Handle errors with `ora().fail(...)` and exit code 1 (missing `openspec` directory, file write errors)
+
+## 3. Testing
+- [x] 3.1 Verify `openspec/README.md` is fully replaced with latest template
+- [x] 3.2 Verify `CLAUDE.md` OpenSpec block updates without altering user content outside markers
+- [x] 3.3 Verify idempotency (running twice yields identical files, no duplicate markers)
+- [x] 3.4 Verify error when `openspec` directory is missing with friendly message
+- [x] 3.5 Verify success message displays properly in ASCII-only terminals

openspec/changes/archive/2025-01-13-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/archive/2025-01-13-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/archive/2025-01-13-add-list-command/tasks.md

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

openspec/changes/archive/2025-08-06-add-init-command/design.md

@@ -0,0 +1,104 @@
+# Technical Design for Init Command
+
+## Architecture Overview
+
+The init command follows a modular architecture with clear separation of concerns:
+
+```
+CLI Layer (src/cli/index.ts)
+    ↓
+Core Logic (src/core/init.ts)
+    ↓
+Templates (src/core/templates/)
+    ↓
+File System Utils (src/utils/file-system.ts)
+```
+
+## Key Design Decisions
+
+### 1. Template Management
+
+**Decision**: Store templates as TypeScript modules rather than separate files
+**Rationale**: 
+- Ensures templates are bundled with the compiled code
+- Allows for dynamic content insertion
+- Type-safe template handling
+- No need for complex file path resolution
+
+### 2. Interactive vs Non-Interactive Mode
+
+**Decision**: Support both interactive (default) and non-interactive modes
+**Rationale**:
+- Interactive mode for developer experience
+- Non-interactive for CI/CD and automation
+- Flags: `--yes` to accept defaults, `--no-input` for full automation
+
+### 3. Directory Structure Creation
+
+**Decision**: Create all directories upfront, then populate files
+**Rationale**:
+- Fail fast if permissions issues
+- Clear transaction boundary
+- Easier to clean up on failure
+
+### 4. Error Handling Strategy
+
+**Decision**: Implement rollback on failure
+**Rationale**:
+- Prevent partial installations
+- Clear error states
+- Better user experience
+
+## Implementation Details
+
+### File System Operations
+
+```typescript
+// Atomic directory creation with rollback
+interface InitTransaction {
+  createdPaths: string[];
+  rollback(): Promise<void>;
+  commit(): Promise<void>;
+}
+```
+
+### Template System
+
+```typescript
+interface Template {
+  path: string;
+  content: string | ((context: ProjectContext) => string);
+}
+
+interface ProjectContext {
+  projectName: string;
+  description: string;
+  techStack: string[];
+  conventions: string;
+}
+```
+
+### CLI Command Structure
+
+```bash
+openspec init [path]           # Initialize in specified path (default: current directory)
+  --yes                       # Accept all defaults
+  --no-input                  # Skip all prompts
+  --force                     # Overwrite existing OpenSpec directory
+  --dry-run                   # Show what would be created
+```
+
+## Security Considerations
+
+1. **Path Traversal**: Sanitize all user-provided paths
+2. **File Permissions**: Check write permissions before starting
+3. **Existing Files**: Never overwrite without explicit --force flag
+4. **Template Injection**: Sanitize user inputs in templates
+
+## Future Extensibility
+
+The design supports future enhancements:
+- Custom template sources
+- Project type presets (API, web app, library)
+- Migration from other documentation systems
+- Integration with version control systems

openspec/changes/archive/2025-08-06-add-init-command/proposal.md

@@ -0,0 +1,30 @@
+# Add Init Command for OpenSpec
+
+## Why
+
+Projects need a simple way to adopt OpenSpec conventions. Currently, users must manually create the directory structure and understand all the conventions, which creates friction for adoption. An init command would enable instant OpenSpec setup with proper structure and guidance.
+
+## What Changes
+
+- Add `openspec init` CLI command that creates the complete OpenSpec directory structure
+- Generate template files (README.md with AI instructions, project.md template)
+- Interactive prompt to select which AI tools to configure (Claude Code initially, others marked as "coming soon")
+- Support for multiple AI coding assistants with extensible plugin architecture
+- Smart file updates using content markers to preserve existing configurations
+- Custom directory naming with `--dir` flag
+- Validation to prevent overwriting existing OpenSpec structures
+- Clear error messages with helpful guidance (e.g., suggesting 'openspec update' for existing structures)
+- Display actionable next steps after successful initialization
+
+### Breaking Changes
+- None - this is a new feature
+
+## Impact
+
+- Affected specs: None (new feature)
+- Affected code: 
+  - src/cli/index.ts (add init command)
+  - src/core/init.ts (new - initialization logic)
+  - src/core/templates/ (new - template files)
+  - src/core/configurators/ (new - AI tool plugins)
+  - src/utils/file-system.ts (new - file operations)

openspec/changes/archive/2025-08-06-add-init-command/specs/cli-init/spec.md

@@ -0,0 +1,148 @@
+# CLI Init Specification
+
+## Purpose
+
+The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
+
+## Behavior
+
+### 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"
+
+### Directory Creation
+
+WHEN `openspec init` is executed
+THEN create the following directory structure:
+```
+openspec/
+├── project.md
+├── README.md
+├── specs/
+└── changes/
+    └── archive/
+```
+
+### File Generation
+
+The command SHALL generate:
+- `README.md` containing complete OpenSpec instructions for AI assistants
+- `project.md` with project context template
+
+### AI Tool Configuration
+
+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)
+
+### AI Tool Configuration Details
+
+WHEN Claude Code is selected
+THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+WHEN CLAUDE.md does not exist
+THEN create new file with OpenSpec content wrapped in markers:
+```markdown
+<!-- OPENSPEC:START -->
+# OpenSpec Project
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+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
+
+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
+
+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
+
+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)
+
+User navigation:
+- Use arrow keys to move between options
+- Press Enter to select the highlighted option
+
+### Safety Checks
+
+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."
+
+WHEN checking initialization feasibility
+THEN verify write permissions in the target directory silently
+AND only display error if permissions are insufficient
+
+### Success Output
+
+WHEN initialization completes successfully
+THEN display actionable prompts for AI-driven workflow:
+```
+✔ OpenSpec initialized successfully!
+
+Next steps - Copy these prompts to Claude:
+
+────────────────────────────────────────────────────────────
+1. Populate your project context:
+   "Please read openspec/project.md and help me fill it out
+    with details about my project, tech stack, and conventions"
+
+2. Create your first change proposal:
+   "I want to add [YOUR FEATURE HERE]. Please create an
+    OpenSpec change proposal for this feature"
+
+3. Learn the OpenSpec workflow:
+   "Please explain the OpenSpec workflow from openspec/README.md
+    and how I should work with you on this project"
+────────────────────────────────────────────────────────────
+```
+
+The prompts SHALL:
+- Be copy-pasteable for immediate use with AI tools
+- Guide users through the AI-driven workflow
+- Replace placeholder text ([YOUR FEATURE HERE]) with actual features
+
+### 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)
+
+## Why
+
+Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:
+- Consistent structure across all projects
+- Proper AI instruction files are always included
+- Quick onboarding for new projects
+- Clear conventions from the start

openspec/changes/archive/2025-08-06-add-init-command/tasks.md

@@ -0,0 +1,38 @@
+# Implementation Tasks for Init Command
+
+## 1. Core Infrastructure
+- [x] 1.1 Create src/utils/file-system.ts with directory/file creation utilities
+- [x] 1.2 Create src/core/templates/index.ts for template management
+- [x] 1.3 Create src/core/init.ts with main initialization logic
+- [x] 1.4 Create src/core/config.ts for configuration management
+
+## 2. Template Files
+- [x] 2.1 Create src/core/templates/readme-template.ts with OpenSpec README content
+- [x] 2.2 Create src/core/templates/project-template.ts with customizable project.md
+- [x] 2.3 Create src/core/templates/claude-template.ts for CLAUDE.md content with markers
+
+## 3. AI Tool Configurators
+- [x] 3.1 Create src/core/configurators/base.ts with ToolConfigurator interface
+- [x] 3.2 Create src/core/configurators/claude.ts for Claude Code configuration
+- [x] 3.3 Create src/core/configurators/registry.ts for tool registration
+- [x] 3.4 Implement marker-based file updates for existing configurations
+
+## 4. Init Command Implementation
+- [x] 4.1 Add init command to src/cli/index.ts using Commander
+- [x] 4.2 Implement AI tool selection with multi-select prompt (Claude Code available, others "coming soon") - requires at least one selection
+- [x] 4.3 Add validation for existing OpenSpec directories with helpful error message
+- [x] 4.4 Implement directory structure creation
+- [x] 4.5 Implement file generation with templates and markers
+
+## 5. User Experience
+- [x] 5.1 Add colorful console output for better UX
+- [x] 5.2 Implement progress indicators (Step 1/3, 2/3, 3/3)
+- [x] 5.3 Add success message with actionable next steps (edit project.md, create first change)
+- [x] 5.4 Add error handling with helpful messages
+
+## 6. Testing and Documentation
+- [x] 6.1 Add unit tests for file system utilities
+- [x] 6.2 Add unit tests for marker-based file updates
+- [x] 6.3 Add integration tests for init command
+- [x] 6.4 Update package.json with proper bin configuration
+- [x] 6.5 Test the built CLI command end-to-end

openspec/changes/archive/2025-08-06-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/archive/2025-08-06-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/archive/2025-08-06-adopt-future-state-storage/tasks.md

@@ -0,0 +1,38 @@
+# Implementation Tasks
+
+## 1. Update Core Documentation
+- [x] 1.1 Update openspec/README.md section on "Creating a Change Proposal"
+  - [x] Replace `patches/` with `specs/` in directory structure
+  - [x] Update step 3 to show storing complete future state
+  - [x] Remove diff syntax instructions (+/- prefixes)
+
+## 2. Migrate Existing Change
+- [x] 2.1 Convert add-init-command change to new format
+  - [x] Create `specs/cli-init/spec.md` with clean content (no diff markers)
+  - [x] Delete old `patches/` directory
+- [x] 2.2 Test that the migrated change is clear and reviewable
+
+## 3. Update Documentation Examples
+- [x] 3.1 Update docs/PRD.md
+  - [x] Fix directory structure examples (lines 376-382)
+  - [x] Update archive examples (lines 778-783)
+  - [x] Ensure consistency throughout
+- [x] 3.2 Update docs/openspec-walkthrough.md
+  - [x] Replace diff examples with future state examples
+  - [x] Ensure the walkthrough reflects new approach
+
+## 4. Create New Spec
+- [x] 4.1 Finalize openspec-conventions spec in main specs/ directory
+  - [x] Document the future state storage approach
+  - [x] Include examples of good proposals
+  - [x] Make it the source of truth for conventions
+
+## 5. Validation
+- [x] 5.1 Verify all documentation is consistent
+- [x] 5.2 Test creating a new change with the new approach
+- [x] 5.3 Ensure GitHub PR view shows diffs clearly
+
+## 6. Deployment
+- [x] 6.1 Get approval for this change
+- [x] 6.2 Implement all tasks above
+- [x] 6.3 After deployment, archive this change with completion date

openspec/changes/archive/2025-08-11-add-complexity-guidelines/proposal.md

@@ -0,0 +1,13 @@
+# Add Complexity Management Guidelines
+
+## Why
+OpenSpec currently lacks guidance on managing complexity, leading to over-engineered solutions when simple ones suffice.
+
+## What Changes
+- Add "Start Simple" section to openspec/README.md with default minimalism rules
+- Add complexity triggers to help identify when complexity is justified
+- Enhance AI assistant instructions in CLAUDE.md to bias toward simplicity
+
+## Impact
+- Affected specs: None (documentation only)
+- Affected code: openspec/README.md, CLAUDE.md

openspec/changes/archive/2025-08-11-add-complexity-guidelines/specs/openspec-docs/README.md

@@ -0,0 +1,472 @@
+# OpenSpec Instructions
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+## Core Principle
+
+OpenSpec is an AI-native system for change-driven development where:
+- **Specs** (`specs/`) reflect what IS currently built and deployed
+- **Changes** (`changes/`) contain proposals for what SHOULD be changed
+- **AI drives the process** - You generate proposals, humans review and approve
+- **Specs are living documentation** - Always kept in sync with deployed code
+
+## Start Simple
+
+**Default to minimal implementations:**
+- New features should be <100 lines of code initially
+- Use the simplest solution that works
+- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)
+- Choose boring technology over cutting-edge solutions
+
+**Complexity triggers** - Only add complexity when you have:
+- **Performance data** showing current solution is too slow
+- **Scale requirements** with specific numbers (>1000 users, >100MB data)
+- **Multiple use cases** requiring the same abstraction
+- **Regulatory compliance** mandating specific patterns
+- **Security threats** that simple solutions cannot address
+
+When triggered, document the specific justification in your change proposal.
+
+## Directory Structure
+
+```
+openspec/
+├── project.md              # Project-specific context (tech stack, conventions)
+├── README.md               # This file - OpenSpec instructions
+├── specs/                  # Current truth - what IS built
+│   ├── [capability]/       # Single, focused capability
+│   │   ├── spec.md         # WHAT the capability does and WHY
+│   │   └── design.md       # HOW it's built (established patterns)
+│   └── ...
+├── changes/                # Proposed changes - what we're CHANGING
+│   ├── [change-name]/
+│   │   ├── proposal.md     # Why, what, impact (consolidated)
+│   │   ├── tasks.md        # Implementation checklist
+│   │   ├── design.md       # Technical decisions (optional, for complex changes)
+│   │   └── specs/          # Future state of affected specs
+│   │       └── [capability]/
+│   │           └── spec.md # Clean markdown (no diff syntax)
+│   └── archive/            # Completed changes (dated)
+```
+
+### Capability Organization
+
+**Use capabilities, not features** - Each directory under `specs/` represents a single, focused responsibility:
+- **Verb-noun naming**: `user-auth`, `payment-capture`, `order-checkout`
+- **10-minute rule**: Each capability should be understandable in <10 minutes
+- **Single purpose**: If it needs "AND" to describe it, split it
+
+Examples:
+```
+✅ GOOD: user-auth, user-sessions, payment-capture, payment-refunds
+❌ BAD: users, payments, core, misc
+```
+
+## Key Behavioral Rules
+
+### 1. Always Start by Reading
+
+Before any task:
+1. **Read relevant specs** in `specs/[capability]/spec.md` to understand current state
+2. **Check pending changes** in `changes/` directory for potential conflicts
+3. **Read project.md** for project-specific conventions
+
+### 2. When to Create Change Proposals
+
+**ALWAYS create a change proposal for:**
+- New features or functionality
+- Breaking changes (API changes, schema updates)
+- Architecture changes or new patterns
+- Performance optimizations that change behavior
+- Security updates affecting auth/access patterns
+- Any change requiring multiple steps or affecting multiple systems
+
+**SKIP proposals for:**
+- Bug fixes that restore intended behavior
+- Typos, formatting, or comment updates
+- Dependency updates (unless breaking)
+- Configuration or environment variable changes
+- Adding tests for existing behavior
+- Documentation fixes
+
+**Complexity assessment:**
+- If your solution requires >100 lines of new code, justify the complexity
+- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
+- Default to single-file implementations until proven insufficient
+
+### 3. Creating a Change Proposal
+
+When a user requests a significant change:
+
+```bash
+# 1. Create the change directory
+openspec/changes/[descriptive-name]/
+
+# 2. Generate proposal.md with all context
+## Why
+[1-2 sentences on the problem/opportunity]
+
+## What Changes  
+[Bullet list of changes, including breaking changes]
+
+## Impact
+- Affected specs: [list capabilities that will change]
+- Affected code: [list key files/systems]
+
+# 3. Create future state specs for ALL affected capabilities
+# - Store complete spec files as they will exist after the change
+# - Use clean markdown without diff syntax (+/- prefixes)
+# - Include all formatting and structure of the final intended state
+specs/
+└── [capability]/
+    └── spec.md
+
+# 4. Create tasks.md with implementation steps
+## 1. [Task Group]
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+# 5. For complex changes, add design.md
+[Technical decisions and trade-offs]
+```
+
+### 4. The Change Lifecycle
+
+1. **Propose** → Create change directory with all documentation
+2. **Review** → User reviews and approves the proposal
+3. **Implement** → Follow the approved tasks.md (can be multiple PRs)
+4. **Deploy** → User confirms deployment
+5. **Update Specs** → Sync specs/ with new reality (IF the change affects system capabilities)
+6. **Archive** → Move to `changes/archive/YYYY-MM-DD-[name]/`
+
+### 5. Implementing Changes
+
+When implementing an approved change:
+1. Follow the tasks.md checklist exactly
+2. **Mark completed tasks** in tasks.md as you finish them (e.g., `- [x] 1.1 Task completed`)
+3. Ensure code matches the proposed behavior
+4. Update any affected tests
+5. **Keep change in `changes/` directory** - do NOT archive in implementation PR
+
+**Multiple Implementation PRs:**
+- Changes can be implemented across multiple PRs
+- Each PR should update tasks.md to mark what was completed
+- Different developers can work on different task groups
+- Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4
+
+### 6. Updating Specs and Archiving After Deployment
+
+**Create a separate PR after deployment** that:
+1. Moves change to `changes/archive/YYYY-MM-DD-[name]/`
+2. Updates relevant files in `specs/` to reflect new reality (if needed)
+3. If design.md exists, incorporates proven patterns into `specs/[capability]/design.md`
+
+This ensures changes are only archived when truly complete and deployed.
+
+### 7. Types of Changes That Don't Require Specs
+
+Some changes only affect development infrastructure and don't need specs:
+- Initial project setup (package.json, tsconfig.json, etc.)
+- Development tooling changes (linters, formatters, build tools)
+- CI/CD configuration
+- Development dependencies
+
+For these changes:
+1. Implement → Deploy → Mark tasks complete → Archive
+2. Skip the "Update Specs" step entirely
+
+### What Deserves a Spec?
+
+Ask yourself:
+- Is this a system capability that users or other systems interact with?
+- Does it have ongoing behavior that needs documentation?
+- Would a new developer need to understand this to work with the system?
+
+If NO to all → No spec needed (likely just tooling/infrastructure)
+
+## Understanding Specs vs Code
+
+### Specs Document WHAT and WHY
+```markdown
+# Authentication Spec
+
+Users SHALL authenticate with email and password.
+
+WHEN credentials are valid THEN issue JWT token.
+WHEN credentials are invalid THEN return generic error.
+
+WHY: Prevent user enumeration attacks.
+```
+
+### Code Documents HOW
+```javascript
+// Implementation details
+const user = await db.users.findOne({ email });
+const valid = await bcrypt.compare(password, user.hashedPassword);
+```
+
+**Key Distinction**: Specs capture intent, constraints, and decisions that aren't obvious from code.
+
+## Common Scenarios
+
+### New Feature Request
+```
+User: "Add password reset functionality"
+
+You should:
+1. Read specs/user-auth/spec.md
+2. Check changes/ for pending auth changes
+3. Create changes/add-password-reset/ with proposal
+4. Wait for approval before implementing
+```
+
+### Bug Fix
+```
+User: "Getting null pointer error when bio is empty"
+
+You should:
+1. Check if spec says bios are optional
+2. If yes → Fix directly (it's a bug)
+3. If no → Create change proposal (it's a behavior change)
+```
+
+### Infrastructure Setup
+```
+User: "Initialize TypeScript project"
+
+You should:
+1. Create change proposal for TypeScript setup
+2. Implement configuration files (PR #1)
+3. Mark tasks complete in tasks.md
+4. After deployment, create separate PR to archive
+   (no specs update needed - this is tooling, not a capability)
+```
+
+## Summary Workflow
+
+1. **Receive request** → Determine if it needs a change proposal
+2. **Read current state** → Check specs and pending changes
+3. **Create proposal** → Generate complete change documentation
+4. **Get approval** → User reviews the proposal
+5. **Implement** → Follow approved tasks, mark completed items in tasks.md
+6. **Deploy** → User deploys the implementation
+7. **Archive PR** → Create separate PR to:
+   - Move change to archive
+   - Update specs if needed
+   - Mark change as complete
+
+## PR Workflow Examples
+
+### Single Developer, Simple Change
+```
+PR #1: Implementation
+- Implement all tasks
+- Update tasks.md marking items complete
+- Get merged and deployed
+
+PR #2: Archive (after deployment)
+- Move changes/feature-x/ → changes/archive/2025-01-15-feature-x/
+- Update specs if needed
+```
+
+### Multiple Developers, Complex Change
+```
+PR #1: Alice implements auth components
+- Complete tasks 1.1, 1.2, 1.3
+- Update tasks.md marking these complete
+
+PR #2: Bob implements UI components  
+- Complete tasks 2.1, 2.2
+- Update tasks.md marking these complete
+
+PR #3: Alice fixes integration issues
+- Complete remaining task 1.4
+- Update tasks.md
+
+[Deploy all changes]
+
+PR #4: Archive
+- Move to archive with deployment date
+- Update specs to reflect new auth flow
+```
+
+### Key Rules
+- **Never archive in implementation PRs** - changes aren't done until deployed
+- **Always update tasks.md** - shows accurate progress
+- **One archive PR per change** - clear completion boundary
+- **Archive PR includes spec updates** - keeps specs current
+
+## Capability Organization Best Practices
+
+### Naming Capabilities
+- Use **verb-noun** patterns: `user-auth`, `payment-capture`, `order-checkout`
+- Be specific: `payment-capture` not just `payments`
+- Keep flat: Avoid nesting capabilities within capabilities
+- Singular focus: If you need "AND" to describe it, split it
+
+### When to Split Capabilities
+Split when you have:
+- Multiple unrelated API endpoints
+- Different user personas or actors
+- Separate deployment considerations
+- Independent evolution paths
+
+#### Capability Boundary Guidelines
+- Would you import these separately? → Separate capabilities
+- Different deployment cadence? → Separate capabilities
+- Different teams own them? → Separate capabilities
+- Shared data models are OK, shared business logic means combine
+
+Examples:
+- user-auth (login/logout) vs user-sessions (token management) → SEPARATE
+- payment-capture vs payment-refunds → SEPARATE (different workflows)
+- user-profile vs user-settings → COMBINE (same data model, same owner)
+
+### Cross-Cutting Concerns
+For system-wide policies (rate limiting, error handling, security), document them in:
+- `project.md` for project-wide conventions
+- Within relevant capability specs where they apply
+- Or create a dedicated capability if complex enough (e.g., `api-rate-limiting/`)
+
+### Examples of Well-Organized Capabilities
+```
+specs/
+├── user-auth/              # Login, logout, password reset
+├── user-sessions/          # Token management, refresh
+├── user-profile/           # Profile CRUD operations
+├── payment-capture/        # Processing payments
+├── payment-refunds/        # Handling refunds
+└── order-checkout/         # Checkout workflow
+```
+
+For detailed guidance, see the [Capability Organization Guide](../docs/capability-organization.md).
+
+## Common Scenarios and Clarifications
+
+### Decision Ambiguity: Bug vs Behavior Change
+
+When specs are missing or ambiguous:
+- If NO spec exists → Treat current code behavior as implicit spec, require proposal
+- If spec is VAGUE → Require proposal to clarify spec alongside fix
+- If code and spec DISAGREE → Spec is truth, code is buggy (fix without proposal)
+- If unsure → Default to creating a proposal (safer option)
+
+Example:
+```
+User: "The API returns 404 for missing users but should return 400"
+AI: Is this a bug (spec says 400) or behavior change (spec says 404)?
+```
+
+### When You Don't Know the Scope
+It's OK to explore first! Tell the user you need to investigate, then create an informed proposal.
+
+### Exploration Phase (When Needed)
+
+BEFORE creating proposal, you may need exploration when:
+- User request is vague or high-level
+- Multiple implementation approaches exist
+- Scope is unclear without seeing code
+
+Exploration checklist:
+1. Tell user you need to explore first
+2. Use Grep/Read to understand current state
+3. Create initial proposal based on findings
+4. Refine with user feedback
+
+Example:
+```
+User: "Add caching to improve performance"
+AI: "Let me explore the codebase to understand the current architecture and identify caching opportunities."
+[After exploration]
+AI: "Based on my analysis, I've identified three areas where caching would help. Here's my proposal..."
+```
+
+### When No Specs Exist
+Treat current code as implicit spec. Your proposal should document current state AND proposed changes.
+
+### When in Doubt
+Default to creating a proposal. It's easier to skip an unnecessary proposal than fix an undocumented change.
+
+### AI Workflow Adaptations
+
+Task tracking with OpenSpec:
+- Track exploration tasks separately from implementation
+- Document proposal creation steps as you go
+- Keep implementation tasks separate until proposal approved
+
+Parallel operations encouraged:
+- Read multiple specs simultaneously
+- Check multiple pending changes at once
+- Batch related searches for efficiency
+
+Progress communication:
+- "Exploring codebase to understand scope..."
+- "Creating proposal based on findings..."
+- "Implementing approved changes..."
+
+### For AI Assistants
+- **Bias toward simplicity** - Propose the minimal solution that works
+- Use your exploration tools liberally before proposing
+- Batch operations for efficiency
+- Communicate your progress
+- It's OK to revise proposals based on discoveries
+- **Question complexity** - If your solution feels complex, simplify first
+
+## Edge Case Handling
+
+### Multi-Capability Changes
+Create ONE proposal that:
+- Lists all affected capabilities
+- Shows changes per capability
+- Has unified task list
+- Gets approved as a whole
+
+### Outdated Specs
+If specs clearly outdated:
+1. Create proposal to update specs to match reality
+2. Implement new feature in separate proposal
+3. OR combine both in one proposal with clear sections
+
+### Emergency Hotfixes
+For critical production issues:
+1. Announce: "This is an emergency fix"
+2. Implement fix immediately
+3. Create retroactive proposal
+4. Update specs after deployment
+5. Tag with [EMERGENCY] in archive
+
+### Pure Refactoring
+No proposal needed for:
+- Code formatting/style
+- Internal refactoring (same API)
+- Performance optimization (same behavior)
+- Adding types to untyped code
+
+Proposal REQUIRED for:
+- API changes (even if compatible)
+- Database schema changes
+- Architecture changes
+- New dependencies
+
+### Observability Additions
+No proposal needed for:
+- Adding log statements
+- New metrics/traces
+- Debugging additions
+- Error tracking
+
+Proposal REQUIRED if:
+- Changes log format/structure
+- Adds new monitoring service
+- Changes what's logged (privacy)
+
+## Remember
+
+- You are the process driver - automate documentation burden
+- Specs must always reflect deployed reality
+- Changes are proposed, not imposed
+- Impact analysis prevents surprises
+- **Simplicity is the power** - just markdown files, minimal solutions
+- Start simple, add complexity only when justified
+
+By following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.

openspec/changes/archive/2025-08-11-add-complexity-guidelines/tasks.md

@@ -0,0 +1,9 @@
+# Implementation Tasks
+
+## 1. Update OpenSpec README
+- [x] 1.1 Add "Start Simple" section after Core Principle
+- [x] 1.2 Add complexity triggers to "When to Create Change Proposals" section
+- [x] 1.3 Update AI workflow guidance to emphasize minimal implementations
+
+## 2. Update CLAUDE.md
+- [x] 2.1 Add complexity management rules to project instructions

openspec/specs/cli-init/spec.md

@@ -0,0 +1,148 @@
+# CLI Init Specification
+
+## Purpose
+
+The `openspec init` command SHALL create a complete OpenSpec directory structure in any project, enabling immediate adoption of OpenSpec conventions with support for multiple AI coding assistants.
+
+## Behavior
+
+### 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"
+
+### Directory Creation
+
+WHEN `openspec init` is executed
+THEN create the following directory structure:
+```
+openspec/
+├── project.md
+├── README.md
+├── specs/
+└── changes/
+    └── archive/
+```
+
+### File Generation
+
+The command SHALL generate:
+- `README.md` containing complete OpenSpec instructions for AI assistants
+- `project.md` with project context template
+
+### AI Tool Configuration
+
+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)
+
+### AI Tool Configuration Details
+
+WHEN Claude Code is selected
+THEN create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+
+WHEN CLAUDE.md does not exist
+THEN create new file with OpenSpec content wrapped in markers:
+```markdown
+<!-- OPENSPEC:START -->
+# OpenSpec Project
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+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
+
+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
+
+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
+
+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)
+
+User navigation:
+- Use arrow keys to move between options
+- Press Enter to select the highlighted option
+
+### Safety Checks
+
+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."
+
+WHEN checking initialization feasibility
+THEN verify write permissions in the target directory silently
+AND only display error if permissions are insufficient
+
+### Success Output
+
+WHEN initialization completes successfully
+THEN display actionable prompts for AI-driven workflow:
+```
+✔ OpenSpec initialized successfully!
+
+Next steps - Copy these prompts to Claude:
+
+────────────────────────────────────────────────────────────
+1. Populate your project context:
+   "Please read openspec/project.md and help me fill it out
+    with details about my project, tech stack, and conventions"
+
+2. Create your first change proposal:
+   "I want to add [YOUR FEATURE HERE]. Please create an
+    OpenSpec change proposal for this feature"
+
+3. Learn the OpenSpec workflow:
+   "Please explain the OpenSpec workflow from openspec/README.md
+    and how I should work with you on this project"
+────────────────────────────────────────────────────────────
+```
+
+The prompts SHALL:
+- Be copy-pasteable for immediate use with AI tools
+- Guide users through the AI-driven workflow
+- Replace placeholder text ([YOUR FEATURE HERE]) with actual features
+
+### 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)
+
+## Why
+
+Manual creation of OpenSpec structure is error-prone and creates adoption friction. A standardized init command ensures:
+- Consistent structure across all projects
+- Proper AI instruction files are always included
+- Quick onboarding for new projects
+- Clear conventions from the start

openspec/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/specs/cli-update/spec.md

@@ -0,0 +1,59 @@
+# Update Command Specification
+
+## Purpose
+
+As a developer using OpenSpec, I want to update the OpenSpec instructions in my project when new versions are released, so that I can benefit from improvements to AI agent instructions.
+
+## Core Requirements
+
+### 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"
+
+### Prerequisites
+
+The command SHALL require:
+- An existing `openspec` directory (created by `openspec init`)
+
+IF the `openspec` directory does not exist THEN:
+- Display error: "No OpenSpec directory found. Run 'openspec init' first."
+- Exit with code 1
+
+### File Handling
+
+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)
+
+## Edge Cases
+
+### File Permissions
+IF file write fails THEN let the error bubble up naturally with file path.
+
+### Missing CLAUDE.md
+IF CLAUDE.md doesn't exist THEN create it with the template content.
+
+### Custom Directory Name
+Not supported in this change. The default directory name `openspec` SHALL be used.
+
+## Success Criteria
+
+Users SHALL be able to:
+- Update OpenSpec instructions with a single command
+- Get the latest AI agent instructions
+- See clear confirmation of the update
+
+The update process SHALL be:
+- Simple and fast (no version checking)
+- Predictable (same result every time)
+- Self-contained (no network required)

openspec/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

package.json

@@ -37,6 +37,9 @@
     "build": "node build.js",
     "dev": "tsc --watch",
     "dev:cli": "pnpm build && node bin/openspec.js",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
     "prepare": "npm run build"
   },
   "engines": {
@@ -44,10 +47,15 @@
   },
   "devDependencies": {
     "@types/node": "^24.2.0",
-    "typescript": "^5.9.2"
+    "@vitest/ui": "^3.2.4",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
   },
   "dependencies": {
     "@inquirer/prompts": "^7.8.0",
-    "commander": "^14.0.0"
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "jest-diff": "^30.0.5",
+    "ora": "^8.2.0"
   }
 }

src/cli/index.ts

@@ -1,4 +1,12 @@
 import { Command } from 'commander';
+import ora from 'ora';
+import path from 'path';
+import { promises as fs } from 'fs';
+import { InitCommand } from '../core/init.js';
+import { UpdateCommand } from '../core/update.js';
+import { DiffCommand } from '../core/diff.js';
+import { ListCommand } from '../core/list.js';
+import { ArchiveCommand } from '../core/archive.js';
 
 const program = new Command();
 
@@ -7,4 +15,95 @@ program
   .description('AI-native system for spec-driven development')
   .version('0.0.1');
 
+program
+  .command('init [path]')
+  .description('Initialize OpenSpec in your project')
+  .action(async (targetPath = '.') => {
+    try {
+      // Validate that the path is a valid directory
+      const resolvedPath = path.resolve(targetPath);
+      
+      try {
+        const stats = await fs.stat(resolvedPath);
+        if (!stats.isDirectory()) {
+          throw new Error(`Path "${targetPath}" is not a directory`);
+        }
+      } catch (error: any) {
+        if (error.code === 'ENOENT') {
+          // Directory doesn't exist, but we can create it
+          console.log(`Directory "${targetPath}" doesn't exist, it will be created.`);
+        } else if (error.message && error.message.includes('not a directory')) {
+          throw error;
+        } else {
+          throw new Error(`Cannot access path "${targetPath}": ${error.message}`);
+        }
+      }
+      
+      const initCommand = new InitCommand();
+      await initCommand.execute(targetPath);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update [path]')
+  .description('Update OpenSpec instruction files')
+  .action(async (targetPath = '.') => {
+    try {
+      const resolvedPath = path.resolve(targetPath);
+      const updateCommand = new UpdateCommand();
+      await updateCommand.execute(resolvedPath);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('diff [change-name]')
+  .description('Show differences between proposed spec changes and current specs')
+  .action(async (changeName?: string) => {
+    try {
+      const diffCommand = new DiffCommand();
+      await diffCommand.execute(changeName);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('list')
+  .description('List all active changes with their task status')
+  .action(async () => {
+    try {
+      const listCommand = new ListCommand();
+      await listCommand.execute();
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('archive [change-name]')
+  .description('Archive a completed change and update main specs')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(async (changeName?: string, options?: { yes?: boolean }) => {
+    try {
+      const archiveCommand = new ArchiveCommand();
+      await archiveCommand.execute(changeName, options);
+    } catch (error) {
+      console.log(); // Empty line for spacing
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
 program.parse();

src/core/archive.ts

@@ -0,0 +1,224 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { select, confirm } from '@inquirer/prompts';
+import { FileSystemUtils } from '../utils/file-system.js';
+
+interface SpecUpdate {
+  source: string;
+  target: string;
+  exists: boolean;
+}
+
+export class ArchiveCommand {
+  async execute(changeName?: string, options: { yes?: boolean } = {}): Promise<void> {
+    const targetPath = '.';
+    const changesDir = path.join(targetPath, 'openspec', 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    const mainSpecsDir = path.join(targetPath, 'openspec', 'specs');
+
+    // Check if changes directory exists
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+    }
+
+    // Get change name interactively if not provided
+    if (!changeName) {
+      const selectedChange = await this.selectChange(changesDir);
+      if (!selectedChange) {
+        console.log('No change selected. Aborting.');
+        return;
+      }
+      changeName = selectedChange;
+    }
+
+    const changeDir = path.join(changesDir, changeName);
+
+    // Verify change exists
+    try {
+      const stat = await fs.stat(changeDir);
+      if (!stat.isDirectory()) {
+        throw new Error(`Change '${changeName}' not found.`);
+      }
+    } catch {
+      throw new Error(`Change '${changeName}' not found.`);
+    }
+
+    // Check for incomplete tasks
+    const tasksPath = path.join(changeDir, 'tasks.md');
+    const incompleteTasks = await this.checkIncompleteTasks(tasksPath);
+    
+    if (incompleteTasks > 0) {
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
+          default: false
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      } else {
+        console.log(`Warning: ${incompleteTasks} incomplete task(s) found. Continuing due to --yes flag.`);
+      }
+    }
+
+    // Find specs to update
+    const specUpdates = await this.findSpecUpdates(changeDir, mainSpecsDir);
+    
+    if (specUpdates.length > 0) {
+      console.log('\nSpecs to update:');
+      for (const update of specUpdates) {
+        const status = update.exists ? 'update' : 'create';
+        const capability = path.basename(path.dirname(update.target));
+        console.log(`  ${capability}: ${status}`);
+      }
+
+      if (!options.yes) {
+        const proceed = await confirm({
+          message: 'Proceed with spec updates?',
+          default: true
+        });
+        if (!proceed) {
+          console.log('Archive cancelled.');
+          return;
+        }
+      }
+
+      // Update specs
+      for (const update of specUpdates) {
+        await this.updateSpec(update);
+      }
+      console.log('Specs updated successfully.');
+    }
+
+    // Create archive directory with date prefix
+    const archiveName = `${this.getArchiveDate()}-${changeName}`;
+    const archivePath = path.join(archiveDir, archiveName);
+
+    // Check if archive already exists
+    try {
+      await fs.access(archivePath);
+      throw new Error(`Archive '${archiveName}' already exists.`);
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        throw error;
+      }
+    }
+
+    // Create archive directory if needed
+    await fs.mkdir(archiveDir, { recursive: true });
+
+    // Move change to archive
+    await fs.rename(changeDir, archivePath);
+    
+    console.log(`Change '${changeName}' archived as '${archiveName}'.`);
+  }
+
+  private async selectChange(changesDir: string): Promise<string | null> {
+    // Get all directories in changes (excluding archive)
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changeDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+      .map(entry => entry.name)
+      .sort();
+
+    if (changeDirs.length === 0) {
+      console.log('No active changes found.');
+      return null;
+    }
+
+    console.log('Available changes:');
+    const choices = changeDirs.map(name => ({
+      name: name,
+      value: name
+    }));
+
+    try {
+      const answer = await select({
+        message: 'Select a change to archive',
+        choices
+      });
+      return answer;
+    } catch (error) {
+      // User cancelled (Ctrl+C)
+      return null;
+    }
+  }
+
+  private async checkIncompleteTasks(tasksPath: string): Promise<number> {
+    try {
+      const content = await fs.readFile(tasksPath, 'utf-8');
+      const lines = content.split('\n');
+      let incompleteTasks = 0;
+      
+      for (const line of lines) {
+        if (line.includes('- [ ]')) {
+          incompleteTasks++;
+        }
+      }
+      
+      return incompleteTasks;
+    } catch {
+      // No tasks.md file or error reading it
+      return 0;
+    }
+  }
+
+  private async findSpecUpdates(changeDir: string, mainSpecsDir: string): Promise<SpecUpdate[]> {
+    const updates: SpecUpdate[] = [];
+    const changeSpecsDir = path.join(changeDir, 'specs');
+
+    try {
+      const entries = await fs.readdir(changeSpecsDir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const specFile = path.join(changeSpecsDir, entry.name, 'spec.md');
+          const targetFile = path.join(mainSpecsDir, entry.name, 'spec.md');
+          
+          try {
+            await fs.access(specFile);
+            
+            // Check if target exists
+            let exists = false;
+            try {
+              await fs.access(targetFile);
+              exists = true;
+            } catch {
+              exists = false;
+            }
+
+            updates.push({
+              source: specFile,
+              target: targetFile,
+              exists
+            });
+          } catch {
+            // Source spec doesn't exist, skip
+          }
+        }
+      }
+    } catch {
+      // No specs directory in change
+    }
+
+    return updates;
+  }
+
+  private async updateSpec(update: SpecUpdate): Promise<void> {
+    // Create target directory if needed
+    const targetDir = path.dirname(update.target);
+    await fs.mkdir(targetDir, { recursive: true });
+
+    // Copy spec file
+    const content = await fs.readFile(update.source, 'utf-8');
+    await fs.writeFile(update.target, content);
+  }
+
+  private getArchiveDate(): string {
+    // Returns date in YYYY-MM-DD format
+    return new Date().toISOString().split('T')[0];
+  }
+}

src/core/config.ts

@@ -0,0 +1,17 @@
+export const OPENSPEC_DIR_NAME = 'openspec';
+
+export interface OpenSpecConfig {
+  aiTools: string[];
+}
+
+export const OPENSPEC_MARKERS = {
+  start: '<!-- OPENSPEC:START -->',
+  end: '<!-- OPENSPEC:END -->'
+};
+
+export const AI_TOOLS = [
+  { name: 'Claude Code', value: 'claude', available: true },
+  { name: 'Cursor', value: 'cursor', available: false },
+  { name: 'Aider', value: 'aider', available: false },
+  { name: 'Continue', value: 'continue', available: false }
+];

src/core/configurators/base.ts

@@ -0,0 +1,6 @@
+export interface ToolConfigurator {
+  name: string;
+  configFileName: string;
+  isAvailable: boolean;
+  configure(projectPath: string, openspecDir: string): Promise<void>;
+}

src/core/configurators/claude.ts

@@ -0,0 +1,23 @@
+import path from 'path';
+import { ToolConfigurator } from './base.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { TemplateManager } from '../templates/index.js';
+import { OPENSPEC_MARKERS } from '../config.js';
+
+export class ClaudeConfigurator implements ToolConfigurator {
+  name = 'Claude Code';
+  configFileName = 'CLAUDE.md';
+  isAvailable = true;
+
+  async configure(projectPath: string, openspecDir: string): Promise<void> {
+    const filePath = path.join(projectPath, this.configFileName);
+    const content = TemplateManager.getClaudeTemplate();
+    
+    await FileSystemUtils.updateFileWithMarkers(
+      filePath,
+      content,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+  }
+}

src/core/configurators/registry.ts

@@ -0,0 +1,28 @@
+import { ToolConfigurator } from './base.js';
+import { ClaudeConfigurator } from './claude.js';
+
+export class ToolRegistry {
+  private static tools: Map<string, ToolConfigurator> = new Map();
+
+  static {
+    const claudeConfigurator = new ClaudeConfigurator();
+    // Register with the ID that matches the checkbox value
+    this.tools.set('claude', claudeConfigurator);
+  }
+
+  static register(tool: ToolConfigurator): void {
+    this.tools.set(tool.name.toLowerCase().replace(/\s+/g, '-'), tool);
+  }
+
+  static get(toolId: string): ToolConfigurator | undefined {
+    return this.tools.get(toolId);
+  }
+
+  static getAll(): ToolConfigurator[] {
+    return Array.from(this.tools.values());
+  }
+
+  static getAvailable(): ToolConfigurator[] {
+    return this.getAll().filter(tool => tool.isAvailable);
+  }
+}

src/core/diff.ts

@@ -0,0 +1,179 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { diffStringsUnified } from 'jest-diff';
+import { select } from '@inquirer/prompts';
+
+// Constants
+const ARCHIVE_DIR = 'archive';
+const MARKDOWN_EXT = '.md';
+const OPENSPEC_DIR = 'openspec';
+const CHANGES_DIR = 'changes';
+const SPECS_DIR = 'specs';
+
+export class DiffCommand {
+  private filesChanged: number = 0;
+  private linesAdded: number = 0;
+  private linesRemoved: number = 0;
+
+  async execute(changeName?: string): Promise<void> {
+    const changesDir = path.join(process.cwd(), OPENSPEC_DIR, CHANGES_DIR);
+    
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error('No OpenSpec changes directory found');
+    }
+
+    if (!changeName) {
+      changeName = await this.selectChange(changesDir);
+      if (!changeName) return;
+    }
+
+    const changeDir = path.join(changesDir, changeName);
+    
+    try {
+      await fs.access(changeDir);
+    } catch {
+      throw new Error(`Change '${changeName}' not found`);
+    }
+
+    const changeSpecsDir = path.join(changeDir, SPECS_DIR);
+    
+    try {
+      await fs.access(changeSpecsDir);
+    } catch {
+      console.log(`No spec changes found for '${changeName}'`);
+      return;
+    }
+
+    // Reset counters
+    this.filesChanged = 0;
+    this.linesAdded = 0;
+    this.linesRemoved = 0;
+
+    await this.showDiffs(changeSpecsDir);
+
+    // Show summary
+    if (this.filesChanged > 0) {
+      console.log(chalk.bold(`\n📊 Summary: ${this.filesChanged} file(s) changed, ${chalk.green(`+${this.linesAdded}`)} ${chalk.red(`-${this.linesRemoved}`)}`));
+    }
+  }
+
+  private async selectChange(changesDir: string): Promise<string | undefined> {
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changes = entries
+      .filter(entry => entry.isDirectory() && entry.name !== ARCHIVE_DIR)
+      .map(entry => entry.name);
+
+    if (changes.length === 0) {
+      console.log('No changes found');
+      return undefined;
+    }
+
+    console.log('Available changes:');
+    const choices = changes.map((name) => ({
+      name: name,
+      value: name
+    }));
+
+    const answer = await select({
+      message: 'Select a change',
+      choices
+    });
+
+    return answer as string;
+  }
+
+  private async showDiffs(changeSpecsDir: string): Promise<void> {
+    const currentSpecsDir = path.join(process.cwd(), OPENSPEC_DIR, SPECS_DIR);
+    await this.walkAndDiff(changeSpecsDir, currentSpecsDir, '');
+  }
+
+  private async walkAndDiff(changeDir: string, currentDir: string, relativePath: string): Promise<void> {
+    const entries = await fs.readdir(path.join(changeDir, relativePath), { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const entryPath = path.join(relativePath, entry.name);
+      
+      if (entry.isDirectory()) {
+        await this.walkAndDiff(changeDir, currentDir, entryPath);
+      } else if (entry.isFile() && entry.name.endsWith(MARKDOWN_EXT)) {
+        await this.diffFile(
+          path.join(changeDir, entryPath),
+          path.join(currentDir, entryPath),
+          entryPath
+        );
+      }
+    }
+  }
+
+  private async diffFile(changePath: string, currentPath: string, displayPath: string): Promise<void> {
+    let changeContent = '';
+    let currentContent = '';
+    let isNewFile = false;
+    let isDeleted = false;
+    
+    try {
+      changeContent = await fs.readFile(changePath, 'utf-8');
+    } catch {
+      changeContent = '';
+    }
+    
+    try {
+      currentContent = await fs.readFile(currentPath, 'utf-8');
+    } catch {
+      currentContent = '';
+      isNewFile = true;
+    }
+
+    if (changeContent === currentContent) {
+      return;
+    }
+
+    if (changeContent === '' && currentContent !== '') {
+      isDeleted = true;
+    }
+
+    // Enhanced header with file status
+    console.log(chalk.bold.cyan(`\n${'═'.repeat(60)}`));
+    console.log(chalk.bold.cyan(`📄 ${displayPath}`));
+    
+    if (isNewFile) {
+      console.log(chalk.green(`   Status: NEW FILE`));
+    } else if (isDeleted) {
+      console.log(chalk.red(`   Status: DELETED`));
+    } else {
+      console.log(chalk.yellow(`   Status: MODIFIED`));
+    }
+    
+    // Use jest-diff for the actual diff with custom options
+    const diffOptions = {
+      aAnnotation: 'Current',
+      bAnnotation: 'Proposed',
+      aColor: chalk.red,
+      bColor: chalk.green,
+      commonColor: chalk.gray,
+      contextLines: 3,
+      expand: false,
+      includeChangeCounts: true,
+    };
+
+    const diff = diffStringsUnified(currentContent, changeContent, diffOptions);
+    
+    // Count lines for statistics (approximate)
+    const addedLines = (diff.match(/^\+[^+]/gm) || []).length;
+    const removedLines = (diff.match(/^-[^-]/gm) || []).length;
+    
+    console.log(chalk.gray(`   Lines: ${chalk.green(`+${addedLines}`)} ${chalk.red(`-${removedLines}`)}`));
+    console.log(chalk.bold.cyan(`${'─'.repeat(60)}\n`));
+    
+    // Display the diff
+    console.log(diff);
+    
+    // Update counters
+    this.filesChanged++;
+    this.linesAdded += addedLines;
+    this.linesRemoved += removedLines;
+  }
+}

src/core/init.ts

@@ -0,0 +1,133 @@
+import path from 'path';
+import { select } from '@inquirer/prompts';
+import ora from 'ora';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { TemplateManager, ProjectContext } from './templates/index.js';
+import { ToolRegistry } from './configurators/registry.js';
+import { OpenSpecConfig, AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
+
+export class InitCommand {
+  async execute(targetPath: string): Promise<void> {
+    const projectPath = path.resolve(targetPath);
+    const openspecDir = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(projectPath, openspecDir);
+
+    // Validation happens silently in the background
+    await this.validate(projectPath, openspecPath);
+
+    // Get configuration (after validation to avoid prompts if validation fails)
+    const config = await this.getConfiguration();
+
+    // Step 1: Create directory structure
+    const structureSpinner = ora({ text: 'Creating OpenSpec structure...', stream: process.stdout }).start();
+    await this.createDirectoryStructure(openspecPath);
+    await this.generateFiles(openspecPath, config);
+    structureSpinner.succeed('OpenSpec structure created');
+
+    // Step 2: Configure AI tools
+    const toolSpinner = ora({ text: 'Configuring AI tools...', stream: process.stdout }).start();
+    await this.configureAITools(projectPath, openspecDir, config.aiTools);
+    toolSpinner.succeed('AI tools configured');
+
+    // Success message
+    this.displaySuccessMessage(openspecDir, config);
+  }
+
+  private async validate(projectPath: string, openspecPath: string): Promise<void> {
+    // Check if OpenSpec already exists
+    if (await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(
+        `OpenSpec seems to already be initialized at ${openspecPath}.\n` +
+        `Use 'openspec update' to update the structure.`
+      );
+    }
+
+    // Check write permissions
+    if (!await FileSystemUtils.ensureWritePermissions(projectPath)) {
+      throw new Error(`Insufficient permissions to write to ${projectPath}`);
+    }
+
+  }
+
+  private async getConfiguration(): Promise<OpenSpecConfig> {
+    const config: OpenSpecConfig = {
+      aiTools: []
+    };
+
+    // Single-select for better UX
+    const selectedTool = await select({
+      message: 'Which AI tool do you use?',
+      choices: AI_TOOLS.map(tool => ({
+        name: tool.available ? tool.name : `${tool.name} (coming soon)`,
+        value: tool.value,
+        disabled: !tool.available
+      }))
+    });
+    
+    config.aiTools = [selectedTool as string];
+
+    return config;
+  }
+
+  private async createDirectoryStructure(openspecPath: string): Promise<void> {
+    const directories = [
+      openspecPath,
+      path.join(openspecPath, 'specs'),
+      path.join(openspecPath, 'changes'),
+      path.join(openspecPath, 'changes', 'archive')
+    ];
+
+    for (const dir of directories) {
+      await FileSystemUtils.createDirectory(dir);
+    }
+  }
+
+  private async generateFiles(openspecPath: string, config: OpenSpecConfig): Promise<void> {
+    const context: ProjectContext = {
+      // Could be enhanced with prompts for project details
+    };
+
+    const templates = TemplateManager.getTemplates(context);
+    
+    for (const template of templates) {
+      const filePath = path.join(openspecPath, template.path);
+      const content = typeof template.content === 'function' 
+        ? template.content(context) 
+        : template.content;
+      
+      await FileSystemUtils.writeFile(filePath, content);
+    }
+  }
+
+  private async configureAITools(projectPath: string, openspecDir: string, toolIds: string[]): Promise<void> {
+    for (const toolId of toolIds) {
+      const configurator = ToolRegistry.get(toolId);
+      if (configurator && configurator.isAvailable) {
+        await configurator.configure(projectPath, openspecDir);
+      }
+    }
+  }
+
+  private displaySuccessMessage(openspecDir: string, config: OpenSpecConfig): void {
+    console.log(); // Empty line for spacing
+    ora().succeed('OpenSpec initialized successfully!');
+    
+    // Get the selected tool name for display
+    const selectedToolId = config.aiTools[0];
+    const selectedTool = AI_TOOLS.find(t => t.value === selectedToolId);
+    const toolName = selectedTool ? selectedTool.name : 'your AI assistant';
+    
+    console.log(`\nNext steps - Copy these prompts to ${toolName}:\n`);
+    console.log('────────────────────────────────────────────────────────────');
+    console.log('1. Populate your project context:');
+    console.log('   "Please read openspec/project.md and help me fill it out');
+    console.log('    with details about my project, tech stack, and conventions"\n');
+    console.log('2. Create your first change proposal:');
+    console.log('   "I want to add [YOUR FEATURE HERE]. Please create an');
+    console.log('    OpenSpec change proposal for this feature"\n');
+    console.log('3. Learn the OpenSpec workflow:');
+    console.log('   "Please explain the OpenSpec workflow from openspec/README.md');
+    console.log('    and how I should work with you on this project"');
+    console.log('────────────────────────────────────────────────────────────\n');
+  }
+}

src/core/list.ts

@@ -0,0 +1,90 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+interface ChangeInfo {
+  name: string;
+  completedTasks: number;
+  totalTasks: number;
+}
+
+export class ListCommand {
+  async execute(targetPath: string = '.'): Promise<void> {
+    const changesDir = path.join(targetPath, 'openspec', 'changes');
+    
+    // Check if changes directory exists
+    try {
+      await fs.access(changesDir);
+    } catch {
+      throw new Error("No OpenSpec changes directory found. Run 'openspec init' first.");
+    }
+
+    // Get all directories in changes (excluding archive)
+    const entries = await fs.readdir(changesDir, { withFileTypes: true });
+    const changeDirs = entries
+      .filter(entry => entry.isDirectory() && entry.name !== 'archive')
+      .map(entry => entry.name);
+
+    if (changeDirs.length === 0) {
+      console.log('No active changes found.');
+      return;
+    }
+
+    // Collect information about each change
+    const changes: ChangeInfo[] = [];
+    
+    for (const changeDir of changeDirs) {
+      const tasksPath = path.join(changesDir, changeDir, 'tasks.md');
+      let completedTasks = 0;
+      let incompleteTasks = 0;
+      
+      try {
+        const content = await fs.readFile(tasksPath, 'utf-8');
+        const lines = content.split('\n');
+        
+        for (const line of lines) {
+          if (line.includes('- [x]')) {
+            completedTasks++;
+          } else if (line.includes('- [ ]')) {
+            incompleteTasks++;
+          }
+        }
+      } catch {
+        // No tasks.md file
+        changes.push({
+          name: changeDir,
+          completedTasks: 0,
+          totalTasks: 0
+        });
+        continue;
+      }
+      
+      changes.push({
+        name: changeDir,
+        completedTasks,
+        totalTasks: completedTasks + incompleteTasks
+      });
+    }
+
+    // Sort alphabetically by name
+    changes.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Display results
+    console.log('Changes:');
+    for (const change of changes) {
+      const padding = '  ';
+      const nameWidth = Math.max(...changes.map(c => c.name.length));
+      const paddedName = change.name.padEnd(nameWidth);
+      
+      let status: string;
+      if (change.totalTasks === 0) {
+        status = 'No tasks';
+      } else if (change.completedTasks === change.totalTasks) {
+        status = '✓ Complete';
+      } else {
+        status = `${change.completedTasks}/${change.totalTasks} tasks`;
+      }
+      
+      console.log(`${padding}${paddedName}     ${status}`);
+    }
+  }
+}

src/core/templates/claude-template.ts

@@ -0,0 +1,26 @@
+export const claudeTemplate = `# OpenSpec Project
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+This project uses OpenSpec for spec-driven development. Specifications are the source of truth.
+
+See @openspec/README.md for detailed conventions and guidelines.
+
+## Complexity Management
+
+**Default to minimal solutions:**
+- Propose <100 lines of new code for features
+- Prefer single-file implementations until proven insufficient
+- Avoid frameworks, abstractions, and optimizations without clear justification
+- Choose boring, well-understood patterns over novel approaches
+
+**Question requests for complexity:**
+- Caching? → Ask for performance data and targets
+- New framework? → Suggest plain code first
+- Extra layers? → Start with the thinnest viable design
+
+**Justify complexity with data:**
+- Performance metrics showing current solution is too slow
+- Concrete scale requirements (e.g., >1000 users, >100MB data)
+- Multiple proven use cases requiring an abstraction
+`;

src/core/templates/index.ts

@@ -0,0 +1,29 @@
+import { readmeTemplate } from './readme-template.js';
+import { projectTemplate, ProjectContext } from './project-template.js';
+import { claudeTemplate } from './claude-template.js';
+
+export interface Template {
+  path: string;
+  content: string | ((context: ProjectContext) => string);
+}
+
+export class TemplateManager {
+  static getTemplates(context: ProjectContext = {}): Template[] {
+    return [
+      {
+        path: 'README.md',
+        content: readmeTemplate
+      },
+      {
+        path: 'project.md',
+        content: projectTemplate(context)
+      }
+    ];
+  }
+
+  static getClaudeTemplate(): string {
+    return claudeTemplate;
+  }
+}
+
+export { ProjectContext } from './project-template.js';

src/core/templates/project-template.ts

@@ -0,0 +1,38 @@
+export interface ProjectContext {
+  projectName?: string;
+  description?: string;
+  techStack?: string[];
+  conventions?: string;
+}
+
+export const projectTemplate = (context: ProjectContext = {}) => `# ${context.projectName || 'Project'} Context
+
+## Overview
+${context.description || '[Describe your project\'s purpose and goals]'}
+
+## Tech Stack
+${context.techStack?.length ? context.techStack.map(tech => `- ${tech}`).join('\n') : '- [List your primary technologies]\n- [e.g., TypeScript, React, Node.js]'}
+
+## Project Conventions
+
+### Code Style
+[Describe your code style preferences, formatting rules, and naming conventions]
+
+### Architecture Patterns
+[Document your architectural decisions and patterns]
+
+### Testing Strategy
+[Explain your testing approach and requirements]
+
+### Git Workflow
+[Describe your branching strategy and commit conventions]
+
+## Domain Context
+[Add domain-specific knowledge that AI assistants need to understand]
+
+## Important Constraints
+[List any technical, business, or regulatory constraints]
+
+## External Dependencies
+[Document key external services, APIs, or systems]
+`;

src/core/templates/readme-template.ts

@@ -0,0 +1,473 @@
+export const readmeTemplate = `# OpenSpec Instructions
+
+This document provides instructions for AI coding assistants on how to use OpenSpec conventions for spec-driven development. Follow these rules precisely when working on OpenSpec-enabled projects.
+
+## Core Principle
+
+OpenSpec is an AI-native system for change-driven development where:
+- **Specs** (\`specs/\`) reflect what IS currently built and deployed
+- **Changes** (\`changes/\`) contain proposals for what SHOULD be changed
+- **AI drives the process** - You generate proposals, humans review and approve
+- **Specs are living documentation** - Always kept in sync with deployed code
+
+## Start Simple
+
+**Default to minimal implementations:**
+- New features should be <100 lines of code initially
+- Use the simplest solution that works
+- Avoid premature optimization (no caching, parallelization, or complex patterns without proven need)
+- Choose boring technology over cutting-edge solutions
+
+**Complexity triggers** - Only add complexity when you have:
+- **Performance data** showing current solution is too slow
+- **Scale requirements** with specific numbers (>1000 users, >100MB data)
+- **Multiple use cases** requiring the same abstraction
+- **Regulatory compliance** mandating specific patterns
+- **Security threats** that simple solutions cannot address
+
+When triggered, document the specific justification in your change proposal.
+
+## Directory Structure
+
+\`\`\`
+openspec/
+├── project.md              # Project-specific context (tech stack, conventions)
+├── README.md               # This file - OpenSpec instructions
+├── specs/                  # Current truth - what IS built
+│   ├── [capability]/       # Single, focused capability
+│   │   ├── spec.md         # WHAT the capability does and WHY
+│   │   └── design.md       # HOW it's built (established patterns)
+│   └── ...
+├── changes/                # Proposed changes - what we're CHANGING
+│   ├── [change-name]/
+│   │   ├── proposal.md     # Why, what, impact (consolidated)
+│   │   ├── tasks.md        # Implementation checklist
+│   │   ├── design.md       # Technical decisions (optional, for complex changes)
+│   │   └── specs/          # Future state of affected specs
+│   │       └── [capability]/
+│   │           └── spec.md # Clean markdown (no diff syntax)
+│   └── archive/            # Completed changes (dated)
+\`\`\`
+
+### Capability Organization
+
+**Use capabilities, not features** - Each directory under \`specs/\` represents a single, focused responsibility:
+- **Verb-noun naming**: \`user-auth\`, \`payment-capture\`, \`order-checkout\`
+- **10-minute rule**: Each capability should be understandable in <10 minutes
+- **Single purpose**: If it needs "AND" to describe it, split it
+
+Examples:
+\`\`\`
+✅ GOOD: user-auth, user-sessions, payment-capture, payment-refunds
+❌ BAD: users, payments, core, misc
+\`\`\`
+
+## Key Behavioral Rules
+
+### 1. Always Start by Reading
+
+Before any task:
+1. **Read relevant specs** in \`specs/[capability]/spec.md\` to understand current state
+2. **Check pending changes** in \`changes/\` directory for potential conflicts
+3. **Read project.md** for project-specific conventions
+
+### 2. When to Create Change Proposals
+
+**ALWAYS create a change proposal for:**
+- New features or functionality
+- Breaking changes (API changes, schema updates)
+- Architecture changes or new patterns
+- Performance optimizations that change behavior
+- Security updates affecting auth/access patterns
+- Any change requiring multiple steps or affecting multiple systems
+
+**SKIP proposals for:**
+- Bug fixes that restore intended behavior
+- Typos, formatting, or comment updates
+- Dependency updates (unless breaking)
+- Configuration or environment variable changes
+- Adding tests for existing behavior
+- Documentation fixes
+
+**Complexity assessment:**
+- If your solution requires >100 lines of new code, justify the complexity
+- If adding dependencies, frameworks, or architectural patterns, document why simpler alternatives won't work
+- Default to single-file implementations until proven insufficient
+
+### 3. Creating a Change Proposal
+
+When a user requests a significant change:
+
+\`\`\`bash
+# 1. Create the change directory
+openspec/changes/[descriptive-name]/
+
+# 2. Generate proposal.md with all context
+## Why
+[1-2 sentences on the problem/opportunity]
+
+## What Changes  
+[Bullet list of changes, including breaking changes]
+
+## Impact
+- Affected specs: [list capabilities that will change]
+- Affected code: [list key files/systems]
+
+# 3. Create future state specs for ALL affected capabilities
+# - Store complete spec files as they will exist after the change
+# - Use clean markdown without diff syntax (+/- prefixes)
+# - Include all formatting and structure of the final intended state
+specs/
+└── [capability]/
+    └── spec.md
+
+# 4. Create tasks.md with implementation steps
+## 1. [Task Group]
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+# 5. For complex changes, add design.md
+[Technical decisions and trade-offs]
+\`\`\`
+
+### 4. The Change Lifecycle
+
+1. **Propose** → Create change directory with all documentation
+2. **Review** → User reviews and approves the proposal
+3. **Implement** → Follow the approved tasks.md (can be multiple PRs)
+4. **Deploy** → User confirms deployment
+5. **Update Specs** → Sync specs/ with new reality (IF the change affects system capabilities)
+6. **Archive** → Move to \`changes/archive/YYYY-MM-DD-[name]/\`
+
+### 5. Implementing Changes
+
+When implementing an approved change:
+1. Follow the tasks.md checklist exactly
+2. **Mark completed tasks** in tasks.md as you finish them (e.g., \`- [x] 1.1 Task completed\`)
+3. Ensure code matches the proposed behavior
+4. Update any affected tests
+5. **Keep change in \`changes/\` directory** - do NOT archive in implementation PR
+
+**Multiple Implementation PRs:**
+- Changes can be implemented across multiple PRs
+- Each PR should update tasks.md to mark what was completed
+- Different developers can work on different task groups
+- Example: PR #1 completes tasks 1.1-1.3, PR #2 completes tasks 2.1-2.4
+
+### 6. Updating Specs and Archiving After Deployment
+
+**Create a separate PR after deployment** that:
+1. Moves change to \`changes/archive/YYYY-MM-DD-[name]/\`
+2. Updates relevant files in \`specs/\` to reflect new reality (if needed)
+3. If design.md exists, incorporates proven patterns into \`specs/[capability]/design.md\`
+
+This ensures changes are only archived when truly complete and deployed.
+
+### 7. Types of Changes That Don't Require Specs
+
+Some changes only affect development infrastructure and don't need specs:
+- Initial project setup (package.json, tsconfig.json, etc.)
+- Development tooling changes (linters, formatters, build tools)
+- CI/CD configuration
+- Development dependencies
+
+For these changes:
+1. Implement → Deploy → Mark tasks complete → Archive
+2. Skip the "Update Specs" step entirely
+
+### What Deserves a Spec?
+
+Ask yourself:
+- Is this a system capability that users or other systems interact with?
+- Does it have ongoing behavior that needs documentation?
+- Would a new developer need to understand this to work with the system?
+
+If NO to all → No spec needed (likely just tooling/infrastructure)
+
+## Understanding Specs vs Code
+
+### Specs Document WHAT and WHY
+\`\`\`markdown
+# Authentication Spec
+
+Users SHALL authenticate with email and password.
+
+WHEN credentials are valid THEN issue JWT token.
+WHEN credentials are invalid THEN return generic error.
+
+WHY: Prevent user enumeration attacks.
+\`\`\`
+
+### Code Documents HOW
+\`\`\`javascript
+// Implementation details
+const user = await db.users.findOne({ email });
+const valid = await bcrypt.compare(password, user.hashedPassword);
+\`\`\`
+
+**Key Distinction**: Specs capture intent, constraints, and decisions that aren't obvious from code.
+
+## Common Scenarios
+
+### New Feature Request
+\`\`\`
+User: "Add password reset functionality"
+
+You should:
+1. Read specs/user-auth/spec.md
+2. Check changes/ for pending auth changes
+3. Create changes/add-password-reset/ with proposal
+4. Wait for approval before implementing
+\`\`\`
+
+### Bug Fix
+\`\`\`
+User: "Getting null pointer error when bio is empty"
+
+You should:
+1. Check if spec says bios are optional
+2. If yes → Fix directly (it's a bug)
+3. If no → Create change proposal (it's a behavior change)
+\`\`\`
+
+### Infrastructure Setup
+\`\`\`
+User: "Initialize TypeScript project"
+
+You should:
+1. Create change proposal for TypeScript setup
+2. Implement configuration files (PR #1)
+3. Mark tasks complete in tasks.md
+4. After deployment, create separate PR to archive
+   (no specs update needed - this is tooling, not a capability)
+\`\`\`
+
+## Summary Workflow
+
+1. **Receive request** → Determine if it needs a change proposal
+2. **Read current state** → Check specs and pending changes
+3. **Create proposal** → Generate complete change documentation
+4. **Get approval** → User reviews the proposal
+5. **Implement** → Follow approved tasks, mark completed items in tasks.md
+6. **Deploy** → User deploys the implementation
+7. **Archive PR** → Create separate PR to:
+   - Move change to archive
+   - Update specs if needed
+   - Mark change as complete
+
+## PR Workflow Examples
+
+### Single Developer, Simple Change
+\`\`\`
+PR #1: Implementation
+- Implement all tasks
+- Update tasks.md marking items complete
+- Get merged and deployed
+
+PR #2: Archive (after deployment)
+- Move changes/feature-x/ → changes/archive/2025-01-15-feature-x/
+- Update specs if needed
+\`\`\`
+
+### Multiple Developers, Complex Change
+\`\`\`
+PR #1: Alice implements auth components
+- Complete tasks 1.1, 1.2, 1.3
+- Update tasks.md marking these complete
+
+PR #2: Bob implements UI components  
+- Complete tasks 2.1, 2.2
+- Update tasks.md marking these complete
+
+PR #3: Alice fixes integration issues
+- Complete remaining task 1.4
+- Update tasks.md
+
+[Deploy all changes]
+
+PR #4: Archive
+- Move to archive with deployment date
+- Update specs to reflect new auth flow
+\`\`\`
+
+### Key Rules
+- **Never archive in implementation PRs** - changes aren't done until deployed
+- **Always update tasks.md** - shows accurate progress
+- **One archive PR per change** - clear completion boundary
+- **Archive PR includes spec updates** - keeps specs current
+
+## Capability Organization Best Practices
+
+### Naming Capabilities
+- Use **verb-noun** patterns: \`user-auth\`, \`payment-capture\`, \`order-checkout\`
+- Be specific: \`payment-capture\` not just \`payments\`
+- Keep flat: Avoid nesting capabilities within capabilities
+- Singular focus: If you need "AND" to describe it, split it
+
+### When to Split Capabilities
+Split when you have:
+- Multiple unrelated API endpoints
+- Different user personas or actors
+- Separate deployment considerations
+- Independent evolution paths
+
+#### Capability Boundary Guidelines
+- Would you import these separately? → Separate capabilities
+- Different deployment cadence? → Separate capabilities
+- Different teams own them? → Separate capabilities
+- Shared data models are OK, shared business logic means combine
+
+Examples:
+- user-auth (login/logout) vs user-sessions (token management) → SEPARATE
+- payment-capture vs payment-refunds → SEPARATE (different workflows)
+- user-profile vs user-settings → COMBINE (same data model, same owner)
+
+### Cross-Cutting Concerns
+For system-wide policies (rate limiting, error handling, security), document them in:
+- \`project.md\` for project-wide conventions
+- Within relevant capability specs where they apply
+- Or create a dedicated capability if complex enough (e.g., \`api-rate-limiting/\`)
+
+### Examples of Well-Organized Capabilities
+\`\`\`
+specs/
+├── user-auth/              # Login, logout, password reset
+├── user-sessions/          # Token management, refresh
+├── user-profile/           # Profile CRUD operations
+├── payment-capture/        # Processing payments
+├── payment-refunds/        # Handling refunds
+└── order-checkout/         # Checkout workflow
+\`\`\`
+
+For detailed guidance, see the [Capability Organization Guide](../docs/capability-organization.md).
+
+## Common Scenarios and Clarifications
+
+### Decision Ambiguity: Bug vs Behavior Change
+
+When specs are missing or ambiguous:
+- If NO spec exists → Treat current code behavior as implicit spec, require proposal
+- If spec is VAGUE → Require proposal to clarify spec alongside fix
+- If code and spec DISAGREE → Spec is truth, code is buggy (fix without proposal)
+- If unsure → Default to creating a proposal (safer option)
+
+Example:
+\`\`\`
+User: "The API returns 404 for missing users but should return 400"
+AI: Is this a bug (spec says 400) or behavior change (spec says 404)?
+\`\`\`
+
+### When You Don't Know the Scope
+It's OK to explore first! Tell the user you need to investigate, then create an informed proposal.
+
+### Exploration Phase (When Needed)
+
+BEFORE creating proposal, you may need exploration when:
+- User request is vague or high-level
+- Multiple implementation approaches exist
+- Scope is unclear without seeing code
+
+Exploration checklist:
+1. Tell user you need to explore first
+2. Use Grep/Read to understand current state
+3. Create initial proposal based on findings
+4. Refine with user feedback
+
+Example:
+\`\`\`
+User: "Add caching to improve performance"
+AI: "Let me explore the codebase to understand the current architecture and identify caching opportunities."
+[After exploration]
+AI: "Based on my analysis, I've identified three areas where caching would help. Here's my proposal..."
+\`\`\`
+
+### When No Specs Exist
+Treat current code as implicit spec. Your proposal should document current state AND proposed changes.
+
+### When in Doubt
+Default to creating a proposal. It's easier to skip an unnecessary proposal than fix an undocumented change.
+
+### AI Workflow Adaptations
+
+Task tracking with OpenSpec:
+- Track exploration tasks separately from implementation
+- Document proposal creation steps as you go
+- Keep implementation tasks separate until proposal approved
+
+Parallel operations encouraged:
+- Read multiple specs simultaneously
+- Check multiple pending changes at once
+- Batch related searches for efficiency
+
+Progress communication:
+- "Exploring codebase to understand scope..."
+- "Creating proposal based on findings..."
+- "Implementing approved changes..."
+
+### For AI Assistants
+- **Bias toward simplicity** - Propose the minimal solution that works
+- Use your exploration tools liberally before proposing
+- Batch operations for efficiency
+- Communicate your progress
+- It's OK to revise proposals based on discoveries
+- **Question complexity** - If your solution feels complex, simplify first
+
+## Edge Case Handling
+
+### Multi-Capability Changes
+Create ONE proposal that:
+- Lists all affected capabilities
+- Shows changes per capability
+- Has unified task list
+- Gets approved as a whole
+
+### Outdated Specs
+If specs clearly outdated:
+1. Create proposal to update specs to match reality
+2. Implement new feature in separate proposal
+3. OR combine both in one proposal with clear sections
+
+### Emergency Hotfixes
+For critical production issues:
+1. Announce: "This is an emergency fix"
+2. Implement fix immediately
+3. Create retroactive proposal
+4. Update specs after deployment
+5. Tag with [EMERGENCY] in archive
+
+### Pure Refactoring
+No proposal needed for:
+- Code formatting/style
+- Internal refactoring (same API)
+- Performance optimization (same behavior)
+- Adding types to untyped code
+
+Proposal REQUIRED for:
+- API changes (even if compatible)
+- Database schema changes
+- Architecture changes
+- New dependencies
+
+### Observability Additions
+No proposal needed for:
+- Adding log statements
+- New metrics/traces
+- Debugging additions
+- Error tracking
+
+Proposal REQUIRED if:
+- Changes log format/structure
+- Adds new monitoring service
+- Changes what's logged (privacy)
+
+## Remember
+
+- You are the process driver - automate documentation burden
+- Specs must always reflect deployed reality
+- Changes are proposed, not imposed
+- Impact analysis prevents surprises
+- Simplicity is the power - just markdown files, minimal solutions
+- Start simple, add complexity only when justified
+
+By following these conventions, you enable true spec-driven development where documentation stays current, changes are traceable, and evolution is intentional.
+`;

src/core/update.ts

@@ -0,0 +1,35 @@
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { TemplateManager } from './templates/index.js';
+import { OPENSPEC_DIR_NAME, OPENSPEC_MARKERS } from './config.js';
+import { readmeTemplate } from './templates/readme-template.js';
+
+export class UpdateCommand {
+  async execute(projectPath: string): Promise<void> {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const openspecDirName = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(resolvedProjectPath, openspecDirName);
+
+    // 1. Check openspec directory exists
+    if (!await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+    }
+
+    // 2. Update README.md (full replacement)
+    const readmePath = path.join(openspecPath, 'README.md');
+    await FileSystemUtils.writeFile(readmePath, readmeTemplate);
+
+    // 3. Update CLAUDE.md (marker-based)
+    const claudePath = path.join(resolvedProjectPath, 'CLAUDE.md');
+    const claudeContent = TemplateManager.getClaudeTemplate();
+    await FileSystemUtils.updateFileWithMarkers(
+      claudePath,
+      claudeContent,
+      OPENSPEC_MARKERS.start,
+      OPENSPEC_MARKERS.end
+    );
+
+    // 4. Success message (ASCII-safe)
+    console.log('Updated OpenSpec instructions');
+  }
+}

src/utils/file-system.ts

@@ -0,0 +1,93 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+
+export class FileSystemUtils {
+  static async createDirectory(dirPath: string): Promise<void> {
+    await fs.mkdir(dirPath, { recursive: true });
+  }
+
+  static async fileExists(filePath: string): Promise<boolean> {
+    try {
+      await fs.access(filePath);
+      return true;
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        console.debug(`Unable to check if file exists at ${filePath}: ${error.message}`);
+      }
+      return false;
+    }
+  }
+
+  static async directoryExists(dirPath: string): Promise<boolean> {
+    try {
+      const stats = await fs.stat(dirPath);
+      return stats.isDirectory();
+    } catch (error: any) {
+      if (error.code !== 'ENOENT') {
+        console.debug(`Unable to check if directory exists at ${dirPath}: ${error.message}`);
+      }
+      return false;
+    }
+  }
+
+  static async writeFile(filePath: string, content: string): Promise<void> {
+    const dir = path.dirname(filePath);
+    await this.createDirectory(dir);
+    await fs.writeFile(filePath, content, 'utf-8');
+  }
+
+  static async readFile(filePath: string): Promise<string> {
+    return await fs.readFile(filePath, 'utf-8');
+  }
+
+  static async updateFileWithMarkers(
+    filePath: string,
+    content: string,
+    startMarker: string,
+    endMarker: string
+  ): Promise<void> {
+    let existingContent = '';
+    
+    if (await this.fileExists(filePath)) {
+      existingContent = await this.readFile(filePath);
+      
+      const startIndex = existingContent.indexOf(startMarker);
+      const endIndex = existingContent.indexOf(endMarker);
+      
+      if (startIndex !== -1 && endIndex !== -1) {
+        const before = existingContent.substring(0, startIndex);
+        const after = existingContent.substring(endIndex + endMarker.length);
+        existingContent = before + startMarker + '\n' + content + '\n' + endMarker + after;
+      } else if (startIndex === -1 && endIndex === -1) {
+        existingContent = startMarker + '\n' + content + '\n' + endMarker + '\n\n' + existingContent;
+      } else {
+        throw new Error(`Invalid marker state in ${filePath}. Found start: ${startIndex !== -1}, Found end: ${endIndex !== -1}`);
+      }
+    } else {
+      existingContent = startMarker + '\n' + content + '\n' + endMarker;
+    }
+    
+    await this.writeFile(filePath, existingContent);
+  }
+
+  static async ensureWritePermissions(dirPath: string): Promise<boolean> {
+    try {
+      // If directory doesn't exist, check parent directory permissions
+      if (!await this.directoryExists(dirPath)) {
+        const parentDir = path.dirname(dirPath);
+        if (!await this.directoryExists(parentDir)) {
+          await this.createDirectory(parentDir);
+        }
+        return await this.ensureWritePermissions(parentDir);
+      }
+      
+      const testFile = path.join(dirPath, '.openspec-test-' + Date.now());
+      await fs.writeFile(testFile, '');
+      await fs.unlink(testFile);
+      return true;
+    } catch (error: any) {
+      console.debug(`Insufficient permissions to write to ${dirPath}: ${error.message}`);
+      return false;
+    }
+  }
+}

test/core/archive.test.ts

@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { ArchiveCommand } from '../../src/core/archive.js';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+
+// Mock @inquirer/prompts
+vi.mock('@inquirer/prompts', () => ({
+  select: vi.fn(),
+  confirm: vi.fn()
+}));
+
+describe('ArchiveCommand', () => {
+  let tempDir: string;
+  let archiveCommand: ArchiveCommand;
+  const originalConsoleLog = console.log;
+
+  beforeEach(async () => {
+    // Create temp directory
+    tempDir = path.join(os.tmpdir(), `openspec-archive-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+    
+    // Change to temp directory
+    process.chdir(tempDir);
+    
+    // Create OpenSpec structure
+    const openspecDir = path.join(tempDir, 'openspec');
+    await fs.mkdir(path.join(openspecDir, 'changes'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'specs'), { recursive: true });
+    await fs.mkdir(path.join(openspecDir, 'changes', 'archive'), { recursive: true });
+    
+    // Suppress console.log during tests
+    console.log = vi.fn();
+    
+    archiveCommand = new ArchiveCommand();
+  });
+
+  afterEach(async () => {
+    // Restore console.log
+    console.log = originalConsoleLog;
+    
+    // Clear mocks
+    vi.clearAllMocks();
+    
+    // Clean up temp directory
+    try {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    } catch (error) {
+      // Ignore cleanup errors
+    }
+  });
+
+  describe('execute', () => {
+    it('should archive a change successfully', async () => {
+      // Create a test change
+      const changeName = 'test-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with completed tasks
+      const tasksContent = '- [x] Task 1\n- [x] Task 2';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Check that change was moved to archive
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      
+      expect(archives.length).toBe(1);
+      expect(archives[0]).toMatch(new RegExp(`\\d{4}-\\d{2}-\\d{2}-${changeName}`));
+      
+      // Verify original change directory no longer exists
+      await expect(fs.access(changeDir)).rejects.toThrow();
+    });
+
+    it('should warn about incomplete tasks', async () => {
+      const changeName = 'incomplete-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [x] Task 1\n- [ ] Task 2\n- [ ] Task 3';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Verify warning was logged
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: 2 incomplete task(s) found')
+      );
+    });
+
+    it('should update specs when archiving', async () => {
+      const changeName = 'spec-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'test-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create spec in change
+      const specContent = '# Test Capability Spec\n\nTest content';
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive with --yes flag
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Verify spec was copied to main specs
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'test-capability', 'spec.md');
+      const copiedContent = await fs.readFile(mainSpecPath, 'utf-8');
+      expect(copiedContent).toBe(specContent);
+    });
+
+    it('should throw error if change does not exist', async () => {
+      await expect(
+        archiveCommand.execute('non-existent-change', { yes: true })
+      ).rejects.toThrow("Change 'non-existent-change' not found.");
+    });
+
+    it('should throw error if archive already exists', async () => {
+      const changeName = 'duplicate-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create existing archive with same date
+      const date = new Date().toISOString().split('T')[0];
+      const archivePath = path.join(tempDir, 'openspec', 'changes', 'archive', `${date}-${changeName}`);
+      await fs.mkdir(archivePath, { recursive: true });
+      
+      // Try to archive
+      await expect(
+        archiveCommand.execute(changeName, { yes: true })
+      ).rejects.toThrow(`Archive '${date}-${changeName}' already exists.`);
+    });
+
+    it('should handle changes without tasks.md', async () => {
+      const changeName = 'no-tasks-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without tasks.md
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without warnings
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('incomplete task(s)')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+
+    it('should handle changes without specs', async () => {
+      const changeName = 'no-specs-feature';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Execute archive without specs
+      await archiveCommand.execute(changeName, { yes: true });
+      
+      // Should complete without spec updates
+      expect(console.log).not.toHaveBeenCalledWith(
+        expect.stringContaining('Specs to update')
+      );
+      
+      // Verify change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBe(1);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should throw error when openspec directory does not exist', async () => {
+      // Remove openspec directory
+      await fs.rm(path.join(tempDir, 'openspec'), { recursive: true });
+      
+      await expect(
+        archiveCommand.execute('any-change', { yes: true })
+      ).rejects.toThrow("No OpenSpec changes directory found. Run 'openspec init' first.");
+    });
+  });
+
+  describe('interactive mode', () => {
+    it('should use select prompt for change selection', async () => {
+      const { select } = await import('@inquirer/prompts');
+      const mockSelect = select as unknown as ReturnType<typeof vi.fn>;
+      
+      // Create test changes
+      const change1 = 'feature-a';
+      const change2 = 'feature-b';
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change1), { recursive: true });
+      await fs.mkdir(path.join(tempDir, 'openspec', 'changes', change2), { recursive: true });
+      
+      // Mock select to return first change
+      mockSelect.mockResolvedValueOnce(change1);
+      
+      // Execute without change name
+      await archiveCommand.execute(undefined, { yes: true });
+      
+      // Verify select was called with correct options
+      expect(mockSelect).toHaveBeenCalledWith({
+        message: 'Select a change to archive',
+        choices: [
+          { name: change1, value: change1 },
+          { name: change2, value: change2 }
+        ]
+      });
+      
+      // Verify the selected change was archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives[0]).toContain(change1);
+    });
+
+    it('should use confirm prompt for task warnings', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'incomplete-interactive';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return true (proceed)
+      mockConfirm.mockResolvedValueOnce(true);
+      
+      // Execute without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify confirm was called
+      expect(mockConfirm).toHaveBeenCalledWith({
+        message: 'Warning: 1 incomplete task(s) found. Continue?',
+        default: false
+      });
+    });
+
+    it('should cancel when user declines task warning', async () => {
+      const { confirm } = await import('@inquirer/prompts');
+      const mockConfirm = confirm as unknown as ReturnType<typeof vi.fn>;
+      
+      const changeName = 'cancel-test';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      await fs.mkdir(changeDir, { recursive: true });
+      
+      // Create tasks.md with incomplete tasks
+      const tasksContent = '- [ ] Task 1';
+      await fs.writeFile(path.join(changeDir, 'tasks.md'), tasksContent);
+      
+      // Mock confirm to return false (cancel)
+      mockConfirm.mockResolvedValueOnce(false);
+      
+      // Execute without --yes flag
+      await archiveCommand.execute(changeName);
+      
+      // Verify archive was cancelled
+      expect(console.log).toHaveBeenCalledWith('Archive cancelled.');
+      
+      // Verify change was not archived
+      await expect(fs.access(changeDir)).resolves.not.toThrow();
+    });
+  });
+});

test/core/init.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { InitCommand } from '../../src/core/init.js';
+import * as prompts from '@inquirer/prompts';
+
+vi.mock('@inquirer/prompts', () => ({
+  select: vi.fn()
+}));
+
+describe('InitCommand', () => {
+  let testDir: string;
+  let initCommand: InitCommand;
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-init-test-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+    initCommand = new InitCommand();
+    
+    // Mock console.log to suppress output during tests
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  describe('execute', () => {
+    it('should create OpenSpec directory structure', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      await initCommand.execute(testDir);
+      
+      const openspecPath = path.join(testDir, 'openspec');
+      expect(await directoryExists(openspecPath)).toBe(true);
+      expect(await directoryExists(path.join(openspecPath, 'specs'))).toBe(true);
+      expect(await directoryExists(path.join(openspecPath, 'changes'))).toBe(true);
+      expect(await directoryExists(path.join(openspecPath, 'changes', 'archive'))).toBe(true);
+    });
+
+    it('should create README.md and project.md', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      await initCommand.execute(testDir);
+      
+      const openspecPath = path.join(testDir, 'openspec');
+      expect(await fileExists(path.join(openspecPath, 'README.md'))).toBe(true);
+      expect(await fileExists(path.join(openspecPath, 'project.md'))).toBe(true);
+      
+      const readmeContent = await fs.readFile(path.join(openspecPath, 'README.md'), 'utf-8');
+      expect(readmeContent).toContain('OpenSpec Instructions');
+      
+      const projectContent = await fs.readFile(path.join(openspecPath, 'project.md'), 'utf-8');
+      expect(projectContent).toContain('Project Context');
+    });
+
+    it('should create CLAUDE.md when Claude Code is selected', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      await initCommand.execute(testDir);
+      
+      const claudePath = path.join(testDir, 'CLAUDE.md');
+      expect(await fileExists(claudePath)).toBe(true);
+      
+      const content = await fs.readFile(claudePath, 'utf-8');
+      expect(content).toContain('<!-- OPENSPEC:START -->');
+      expect(content).toContain('OpenSpec Project');
+      expect(content).toContain('<!-- OPENSPEC:END -->');
+    });
+
+    it('should update existing CLAUDE.md with markers', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      const claudePath = path.join(testDir, 'CLAUDE.md');
+      const existingContent = '# My Project Instructions\nCustom instructions here';
+      await fs.writeFile(claudePath, existingContent);
+      
+      await initCommand.execute(testDir);
+      
+      const updatedContent = await fs.readFile(claudePath, 'utf-8');
+      expect(updatedContent).toContain('<!-- OPENSPEC:START -->');
+      expect(updatedContent).toContain('OpenSpec Project');
+      expect(updatedContent).toContain('<!-- OPENSPEC:END -->');
+      expect(updatedContent).toContain('Custom instructions here');
+    });
+
+    it('should throw error if OpenSpec already exists', async () => {
+      const openspecPath = path.join(testDir, 'openspec');
+      await fs.mkdir(openspecPath, { recursive: true });
+      
+      await expect(initCommand.execute(testDir)).rejects.toThrow(
+        /OpenSpec seems to already be initialized/
+      );
+    });
+
+    it('should handle non-existent target directory', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      const newDir = path.join(testDir, 'new-project');
+      await initCommand.execute(newDir);
+      
+      const openspecPath = path.join(newDir, 'openspec');
+      expect(await directoryExists(openspecPath)).toBe(true);
+    });
+
+    it('should display success message with selected tool name', async () => {
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      const logSpy = vi.spyOn(console, 'log');
+      
+      await initCommand.execute(testDir);
+      
+      const calls = logSpy.mock.calls.flat().join('\n');
+      expect(calls).toContain('Copy these prompts to Claude Code');
+    });
+  });
+
+  describe('AI tool selection', () => {
+    it('should prompt for AI tool selection', async () => {
+      const selectMock = vi.mocked(prompts.select);
+      selectMock.mockResolvedValue('claude');
+      
+      await initCommand.execute(testDir);
+      
+      expect(selectMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          message: 'Which AI tool do you use?'
+        })
+      );
+    });
+
+    it('should handle different AI tool selections', async () => {
+      // For now, only Claude is available, but test the structure
+      vi.mocked(prompts.select).mockResolvedValue('claude');
+      
+      await initCommand.execute(testDir);
+      
+      // When other tools are added, we'd test their specific configurations here
+      const claudePath = path.join(testDir, 'CLAUDE.md');
+      expect(await fileExists(claudePath)).toBe(true);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should provide helpful error for insufficient permissions', async () => {
+      // This is tricky to test cross-platform, but we can test the error message
+      const readOnlyDir = path.join(testDir, 'readonly');
+      await fs.mkdir(readOnlyDir);
+      
+      // Mock the permission check to fail
+      const originalCheck = fs.writeFile;
+      vi.spyOn(fs, 'writeFile').mockImplementation(async (filePath: any, ...args: any[]) => {
+        if (typeof filePath === 'string' && filePath.includes('.openspec-test-')) {
+          throw new Error('EACCES: permission denied');
+        }
+        return originalCheck.call(fs, filePath, ...args);
+      });
+      
+      await expect(initCommand.execute(readOnlyDir)).rejects.toThrow(
+        /Insufficient permissions/
+      );
+    });
+  });
+});
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function directoryExists(dirPath: string): Promise<boolean> {
+  try {
+    const stats = await fs.stat(dirPath);
+    return stats.isDirectory();
+  } catch {
+    return false;
+  }
+}

test/core/list.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { ListCommand } from '../../src/core/list.js';
+
+describe('ListCommand', () => {
+  let tempDir: string;
+  let originalLog: typeof console.log;
+  let logOutput: string[] = [];
+
+  beforeEach(async () => {
+    // Create temp directory
+    tempDir = path.join(os.tmpdir(), `openspec-list-test-${Date.now()}`);
+    await fs.mkdir(tempDir, { recursive: true });
+
+    // Mock console.log to capture output
+    originalLog = console.log;
+    console.log = (...args: any[]) => {
+      logOutput.push(args.join(' '));
+    };
+    logOutput = [];
+  });
+
+  afterEach(async () => {
+    // Restore console.log
+    console.log = originalLog;
+
+    // Clean up temp directory
+    await fs.rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe('execute', () => {
+    it('should handle missing openspec/changes directory', async () => {
+      const listCommand = new ListCommand();
+      
+      await expect(listCommand.execute(tempDir)).rejects.toThrow(
+        "No OpenSpec changes directory found. Run 'openspec init' first."
+      );
+    });
+
+    it('should handle empty changes directory', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toEqual(['No active changes found.']);
+    });
+
+    it('should exclude archive directory', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'archive'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'my-change'), { recursive: true });
+      
+      // Create tasks.md with some tasks
+      await fs.writeFile(
+        path.join(changesDir, 'my-change', 'tasks.md'),
+        '- [x] Task 1\n- [ ] Task 2\n'
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toContain('Changes:');
+      expect(logOutput.some(line => line.includes('my-change'))).toBe(true);
+      expect(logOutput.some(line => line.includes('archive'))).toBe(false);
+    });
+
+    it('should count tasks correctly', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'test-change'), { recursive: true });
+      
+      await fs.writeFile(
+        path.join(changesDir, 'test-change', 'tasks.md'),
+        `# Tasks
+- [x] Completed task 1
+- [x] Completed task 2
+- [ ] Incomplete task 1
+- [ ] Incomplete task 2
+- [ ] Incomplete task 3
+Regular text that should be ignored
+`
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('2/5 tasks'))).toBe(true);
+    });
+
+    it('should show complete status for fully completed changes', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'completed-change'), { recursive: true });
+      
+      await fs.writeFile(
+        path.join(changesDir, 'completed-change', 'tasks.md'),
+        '- [x] Task 1\n- [x] Task 2\n- [x] Task 3\n'
+      );
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('✓ Complete'))).toBe(true);
+    });
+
+    it('should handle changes without tasks.md', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'no-tasks'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput.some(line => line.includes('no-tasks') && line.includes('No tasks'))).toBe(true);
+    });
+
+    it('should sort changes alphabetically', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      await fs.mkdir(path.join(changesDir, 'zebra'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'alpha'), { recursive: true });
+      await fs.mkdir(path.join(changesDir, 'middle'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      const changeLines = logOutput.filter(line => 
+        line.includes('alpha') || line.includes('middle') || line.includes('zebra')
+      );
+      
+      expect(changeLines[0]).toContain('alpha');
+      expect(changeLines[1]).toContain('middle');
+      expect(changeLines[2]).toContain('zebra');
+    });
+
+    it('should handle multiple changes with various states', async () => {
+      const changesDir = path.join(tempDir, 'openspec', 'changes');
+      
+      // Complete change
+      await fs.mkdir(path.join(changesDir, 'completed'), { recursive: true });
+      await fs.writeFile(
+        path.join(changesDir, 'completed', 'tasks.md'),
+        '- [x] Task 1\n- [x] Task 2\n'
+      );
+
+      // Partial change
+      await fs.mkdir(path.join(changesDir, 'partial'), { recursive: true });
+      await fs.writeFile(
+        path.join(changesDir, 'partial', 'tasks.md'),
+        '- [x] Done\n- [ ] Not done\n- [ ] Also not done\n'
+      );
+
+      // No tasks
+      await fs.mkdir(path.join(changesDir, 'no-tasks'), { recursive: true });
+
+      const listCommand = new ListCommand();
+      await listCommand.execute(tempDir);
+
+      expect(logOutput).toContain('Changes:');
+      expect(logOutput.some(line => line.includes('completed') && line.includes('✓ Complete'))).toBe(true);
+      expect(logOutput.some(line => line.includes('partial') && line.includes('1/3 tasks'))).toBe(true);
+      expect(logOutput.some(line => line.includes('no-tasks') && line.includes('No tasks'))).toBe(true);
+    });
+  });
+});

test/utils/file-system.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
+
+describe('FileSystemUtils', () => {
+  let testDir: string;
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-test-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('createDirectory', () => {
+    it('should create a directory', async () => {
+      const dirPath = path.join(testDir, 'new-dir');
+      await FileSystemUtils.createDirectory(dirPath);
+      
+      const stats = await fs.stat(dirPath);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    it('should create nested directories', async () => {
+      const dirPath = path.join(testDir, 'nested', 'deep', 'dir');
+      await FileSystemUtils.createDirectory(dirPath);
+      
+      const stats = await fs.stat(dirPath);
+      expect(stats.isDirectory()).toBe(true);
+    });
+
+    it('should not throw if directory already exists', async () => {
+      const dirPath = path.join(testDir, 'existing-dir');
+      await fs.mkdir(dirPath);
+      
+      await expect(FileSystemUtils.createDirectory(dirPath)).resolves.not.toThrow();
+    });
+  });
+
+  describe('fileExists', () => {
+    it('should return true for existing file', async () => {
+      const filePath = path.join(testDir, 'test.txt');
+      await fs.writeFile(filePath, 'test content');
+      
+      const exists = await FileSystemUtils.fileExists(filePath);
+      expect(exists).toBe(true);
+    });
+
+    it('should return false for non-existing file', async () => {
+      const filePath = path.join(testDir, 'non-existent.txt');
+      
+      const exists = await FileSystemUtils.fileExists(filePath);
+      expect(exists).toBe(false);
+    });
+
+    it('should return false for directory path', async () => {
+      const dirPath = path.join(testDir, 'dir');
+      await fs.mkdir(dirPath);
+      
+      const exists = await FileSystemUtils.fileExists(dirPath);
+      expect(exists).toBe(true); // fs.access doesn't distinguish between files and directories
+    });
+  });
+
+  describe('directoryExists', () => {
+    it('should return true for existing directory', async () => {
+      const dirPath = path.join(testDir, 'test-dir');
+      await fs.mkdir(dirPath);
+      
+      const exists = await FileSystemUtils.directoryExists(dirPath);
+      expect(exists).toBe(true);
+    });
+
+    it('should return false for non-existing directory', async () => {
+      const dirPath = path.join(testDir, 'non-existent-dir');
+      
+      const exists = await FileSystemUtils.directoryExists(dirPath);
+      expect(exists).toBe(false);
+    });
+
+    it('should return false for file path', async () => {
+      const filePath = path.join(testDir, 'file.txt');
+      await fs.writeFile(filePath, 'content');
+      
+      const exists = await FileSystemUtils.directoryExists(filePath);
+      expect(exists).toBe(false);
+    });
+  });
+
+  describe('writeFile', () => {
+    it('should write content to file', async () => {
+      const filePath = path.join(testDir, 'output.txt');
+      const content = 'Hello, World!';
+      
+      await FileSystemUtils.writeFile(filePath, content);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(content);
+    });
+
+    it('should create directory if it does not exist', async () => {
+      const filePath = path.join(testDir, 'nested', 'dir', 'output.txt');
+      const content = 'Nested content';
+      
+      await FileSystemUtils.writeFile(filePath, content);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(content);
+    });
+
+    it('should overwrite existing file', async () => {
+      const filePath = path.join(testDir, 'existing.txt');
+      await fs.writeFile(filePath, 'old content');
+      
+      const newContent = 'new content';
+      await FileSystemUtils.writeFile(filePath, newContent);
+      
+      const readContent = await fs.readFile(filePath, 'utf-8');
+      expect(readContent).toBe(newContent);
+    });
+  });
+
+  describe('readFile', () => {
+    it('should read file content', async () => {
+      const filePath = path.join(testDir, 'input.txt');
+      const content = 'Test content';
+      await fs.writeFile(filePath, content);
+      
+      const readContent = await FileSystemUtils.readFile(filePath);
+      expect(readContent).toBe(content);
+    });
+
+    it('should throw for non-existing file', async () => {
+      const filePath = path.join(testDir, 'non-existent.txt');
+      
+      await expect(FileSystemUtils.readFile(filePath)).rejects.toThrow();
+    });
+  });
+
+  describe('ensureWritePermissions', () => {
+    it('should return true for writable directory', async () => {
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(testDir);
+      expect(hasPermission).toBe(true);
+    });
+
+    it('should return true for non-existing directory with writable parent', async () => {
+      const dirPath = path.join(testDir, 'new-dir');
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(dirPath);
+      expect(hasPermission).toBe(true);
+    });
+
+    it('should handle deeply nested non-existing directories', async () => {
+      const dirPath = path.join(testDir, 'a', 'b', 'c', 'd');
+      const hasPermission = await FileSystemUtils.ensureWritePermissions(dirPath);
+      expect(hasPermission).toBe(true);
+    });
+  });
+});

test/utils/marker-updates.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../src/utils/file-system.js';
+
+describe('FileSystemUtils.updateFileWithMarkers', () => {
+  let testDir: string;
+  const START_MARKER = '<!-- OPENSPEC:START -->';
+  const END_MARKER = '<!-- OPENSPEC:END -->';
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-marker-test-${Date.now()}`);
+    await fs.mkdir(testDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('new file creation', () => {
+    it('should create new file with markers and content', async () => {
+      const filePath = path.join(testDir, 'new-file.md');
+      const content = 'OpenSpec content';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n${content}\n${END_MARKER}`);
+    });
+  });
+
+  describe('existing file without markers', () => {
+    it('should prepend markers and content to existing file', async () => {
+      const filePath = path.join(testDir, 'existing.md');
+      const existingContent = '# Existing Content\nUser content here';
+      await fs.writeFile(filePath, existingContent);
+      
+      const newContent = 'OpenSpec content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(
+        `${START_MARKER}\n${newContent}\n${END_MARKER}\n\n${existingContent}`
+      );
+    });
+  });
+
+  describe('existing file with markers', () => {
+    it('should replace content between markers', async () => {
+      const filePath = path.join(testDir, 'with-markers.md');
+      const beforeContent = '# Before\nSome content before';
+      const oldManagedContent = 'Old OpenSpec content';
+      const afterContent = '# After\nSome content after';
+      
+      const existingFile = `${beforeContent}\n${START_MARKER}\n${oldManagedContent}\n${END_MARKER}\n${afterContent}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New OpenSpec content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(
+        `${beforeContent}\n${START_MARKER}\n${newContent}\n${END_MARKER}\n${afterContent}`
+      );
+    });
+
+    it('should preserve content before and after markers', async () => {
+      const filePath = path.join(testDir, 'preserve.md');
+      const userContentBefore = '# User Content Before\nImportant user notes';
+      const userContentAfter = '## User Content After\nMore user notes';
+      
+      const existingFile = `${userContentBefore}\n${START_MARKER}\nOld content\n${END_MARKER}\n${userContentAfter}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'Updated content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(userContentBefore);
+      expect(result).toContain(userContentAfter);
+      expect(result).toContain(newContent);
+      expect(result).not.toContain('Old content');
+    });
+
+    it('should handle markers at the beginning of file', async () => {
+      const filePath = path.join(testDir, 'markers-at-start.md');
+      const afterContent = 'User content after markers';
+      
+      const existingFile = `${START_MARKER}\nOld content\n${END_MARKER}\n${afterContent}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n${newContent}\n${END_MARKER}\n${afterContent}`);
+    });
+
+    it('should handle markers at the end of file', async () => {
+      const filePath = path.join(testDir, 'markers-at-end.md');
+      const beforeContent = 'User content before markers';
+      
+      const existingFile = `${beforeContent}\n${START_MARKER}\nOld content\n${END_MARKER}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      const newContent = 'New content';
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        newContent,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${beforeContent}\n${START_MARKER}\n${newContent}\n${END_MARKER}`);
+    });
+  });
+
+  describe('invalid marker states', () => {
+    it('should throw error if only start marker exists', async () => {
+      const filePath = path.join(testDir, 'invalid-start.md');
+      const existingFile = `Some content\n${START_MARKER}\nManaged content\nNo end marker`;
+      await fs.writeFile(filePath, existingFile);
+      
+      await expect(
+        FileSystemUtils.updateFileWithMarkers(
+          filePath,
+          'New content',
+          START_MARKER,
+          END_MARKER
+        )
+      ).rejects.toThrow(/Invalid marker state/);
+    });
+
+    it('should throw error if only end marker exists', async () => {
+      const filePath = path.join(testDir, 'invalid-end.md');
+      const existingFile = `Some content\nNo start marker\nManaged content\n${END_MARKER}`;
+      await fs.writeFile(filePath, existingFile);
+      
+      await expect(
+        FileSystemUtils.updateFileWithMarkers(
+          filePath,
+          'New content',
+          START_MARKER,
+          END_MARKER
+        )
+      ).rejects.toThrow(/Invalid marker state/);
+    });
+  });
+
+  describe('idempotency', () => {
+    it('should produce same result when called multiple times with same content', async () => {
+      const filePath = path.join(testDir, 'idempotent.md');
+      const content = 'Consistent content';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const firstResult = await fs.readFile(filePath, 'utf-8');
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const secondResult = await fs.readFile(filePath, 'utf-8');
+      expect(secondResult).toBe(firstResult);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty content', async () => {
+      const filePath = path.join(testDir, 'empty-content.md');
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        '',
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toBe(`${START_MARKER}\n\n${END_MARKER}`);
+    });
+
+    it('should handle content with special characters', async () => {
+      const filePath = path.join(testDir, 'special-chars.md');
+      const content = '# Special chars: ${}[]()<>|\\`*_~';
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(content);
+    });
+
+    it('should handle multi-line content', async () => {
+      const filePath = path.join(testDir, 'multi-line.md');
+      const content = `Line 1
+Line 2
+Line 3
+
+Line 5 with gap`;
+      
+      await FileSystemUtils.updateFileWithMarkers(
+        filePath,
+        content,
+        START_MARKER,
+        END_MARKER
+      );
+      
+      const result = await fs.readFile(filePath, 'utf-8');
+      expect(result).toContain(content);
+    });
+  });
+});

tsconfig.json

@@ -17,5 +17,5 @@
     "allowSyntheticDefaultImports": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "test"]
 }

vitest.config.ts

@@ -0,0 +1,22 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    coverage: {
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        'bin/',
+        '*.config.ts',
+        'build.js',
+        'test/**'
+      ]
+    },
+    testTimeout: 10000,
+    hookTimeout: 10000
+  }
+});