merge: resolve conflicts with main branch

The diff command added unnecessary complexity and duplicated functionality
already available through the show command. Users can now use:
- `openspec show <change>` for structured change viewing
- `openspec show <change> --json --deltas-only` for delta-only views
- Standard git diff or other tools for file comparisons

This change:
- Removes ~227 lines of code and the jest-diff dependency
- Simplifies the CLI interface
- Reduces maintenance burden
- Aligns with verb-first command structure

.changeset/README.md

@@ -0,0 +1,6 @@
+This directory is managed by Changesets.
+
+- Add a changeset locally with `pnpm changeset`.
+- The CI "Release (prepare)" workflow opens/updates a Version Packages PR.
+- Publishing happens from a GitHub Release via the "Publish to npm" workflow.
+

.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
+

.github/workflows/ci.yml

@@ -0,0 +1,141 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build project
+        run: pnpm run build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Upload test coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage/
+          retention-days: 7
+
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build project
+        run: pnpm run build
+
+      - name: Type check
+        run: pnpm exec tsc --noEmit
+
+      - name: Check for build artifacts
+        run: |
+          if [ ! -d "dist" ]; then
+            echo "Error: dist directory not found after build"
+            exit 1
+          fi
+          if [ ! -f "dist/cli/index.js" ]; then
+            echo "Error: CLI entry point not found"
+            exit 1
+          fi
+
+  validate-changesets:
+    name: Validate Changesets
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate changesets
+        run: |
+          if command -v changeset &> /dev/null; then
+            pnpm exec changeset status --since=origin/main
+          else
+            echo "Changesets not configured, skipping validation"
+          fi
+
+  required-checks:
+    name: All checks passed
+    runs-on: ubuntu-latest
+    needs: [test, lint]
+    if: always()
+    steps:
+      - name: Verify all checks passed
+        run: |
+          if [[ "${{ needs.test.result }}" != "success" ]]; then
+            echo "Test job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.lint.result }}" != "success" ]]; then
+            echo "Lint job failed"
+            exit 1
+          fi
+          echo "All required checks passed!"

.github/workflows/release-prepare.yml

@@ -0,0 +1,37 @@
+name: Release (prepare)
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - run: pnpm install --frozen-lockfile
+
+      # Opens/updates the Version Packages PR; no publishing here
+      - name: Create/Update Version PR
+        uses: changesets/action@v1
+        with:
+          title: 'chore(release): version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.github/workflows/release-publish.yml

@@ -0,0 +1,72 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  id-token: write
+
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+          scope: '@fission-ai'
+          always-auth: true
+
+      - run: pnpm install --frozen-lockfile
+      
+      - name: Build project
+        run: pnpm run build
+
+      - name: Ensure running from a tag
+        run: |
+          if [[ "$GITHUB_REF" != refs/tags/* ]]; then
+            echo "This workflow must run from a tag (got: $GITHUB_REF)";
+            exit 1;
+          fi
+
+      - name: Verify release tag matches package.json
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "Tag v$TAG does not match package.json $PKG_VERSION"; exit 1
+          fi
+
+      - name: Debug npm auth and context
+        run: |
+          test -n "$NODE_AUTH_TOKEN" || (echo "NODE_AUTH_TOKEN is missing" && exit 1)
+          echo "NODE_AUTH_TOKEN present"
+          npm --version
+          pnpm --version
+          node --version
+          npm config get registry
+          npm whoami
+          npm ping
+
+      - run: pnpm test
+
+      - name: Publish
+        run: pnpm publish --access public --provenance --no-git-checks --tag next

.release-notes/0.1.0.md

@@ -0,0 +1,4 @@
+
+### Minor Changes
+
+- 24b4866: Initial release

CHANGELOG.md

@@ -0,0 +1,7 @@
+# @fission-ai/openspec
+
+## 0.1.0
+
+### Minor Changes
+
+- 24b4866: Initial release

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 OpenSpec Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -1,119 +1,270 @@
 # OpenSpec
 
-A specification-driven development system for maintaining living documentation alongside your code.
+[![CI](https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg)](https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@fission-ai/openspec)](https://www.npmjs.com/package/@fission-ai/openspec)
+[![node](https://img.shields.io/node/v/@fission-ai/openspec)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
+
+**Supported AI Tools:** ✅ Claude Code | 🔜 Cursor (coming soon) | 🔜 AGENTS.md support (coming soon)
+
+Create **alignment** between humans and AI coding assistants through spec-driven development. **No API keys required.**
+
+OpenSpec ensures you and your AI assistant agree on what to build before any code is written. By discussing and refining specifications first, you bring determinism to AI code generation, getting exactly what you want, not what the AI thinks you might want.
+
+## Why OpenSpec?
+
+**The Problem:** AI coding assistants are powerful but unpredictable. Without clear specifications, they generate code based on assumptions, often missing requirements or adding unwanted features. Teams waste time in review cycles because humans and AI aren't aligned on what to build.
+
+**The Solution:** OpenSpec creates alignment BEFORE code is written:
+- **Human-AI Alignment** - You and your AI agree on specifications before implementation
+- **Deterministic Output** - Clear specs lead to predictable code generation
+- **Team Alignment** - Everyone reviews specs, not code surprises
+- **Focus on What, Not How** - Define requirements while AI handles implementation
+- **Living Documentation** - Specs evolve with your code as a natural byproduct
+
+## What You Get
+
+- **Alignment First** - Ensure humans and AI agree on what to build before writing code
+- **Predictable AI Output** - Turn non-deterministic AI into a reliable development partner
+- **Universal Tool Support** - Works with any AI assistant - Claude Code, Cursor, or future tools
+- **No API Keys Required** - Integrates through context rules, not external services
+- **Spec-Level Reviews** - Teams review intentions, not implementation details
+- **Clear Feature Scope** - Know exactly what you're building and what you're not
+- **Progress Tracking** - See what's proposed, in progress, or completed at a glance
+
+## How It Works
+
+```
+┌─────────────┐       ┌─────────────┐       ┌──────────────┐
+│    SPECS    │       │   CHANGES   │       │   ARCHIVE    │
+│   (Truth)   │◀──────│ (Proposals) │──────▶│ (Completed)  │
+└─────────────┘       └─────────────┘       └──────────────┘
+      ▲                      │                      │
+      │                      ▼                      │
+      │               ┌─────────────┐               │
+      └───────────────│    CODE     │◀──────────────┘
+                      └─────────────┘
+
+1. SPECS define current capabilities (what IS built)
+2. CHANGES propose modifications using deltas (what SHOULD change)  
+3. CODE implements the changes following tasks
+4. ARCHIVE preserves completed changes after deployment
+```
 
 ## Installation
 
+### Prerequisites
+
+- Node.js >= 20.19.0
+
+### Install OpenSpec
+
+Install globally:
+
 ```bash
-npm install -g openspec
+npm install -g @fission-ai/openspec
 ```
 
-## Quick Start
+## Getting Started
+
+### 1. Initialize OpenSpec in Your Project
 
 ```bash
-# Initialize OpenSpec in your project
+# Navigate to your project
+cd my-project
+
+# Initialize OpenSpec
 openspec init
 
-# Update existing OpenSpec instructions (team-friendly)
-openspec update
+# Select your AI tool (more coming soon!):
+# "Which AI tool do you use?"
+#   > Claude Code
+#     Cursor (coming soon)
 
-# List specs or changes
-openspec spec list        # specs (IDs by default; use --long for details)
-openspec change list      # changes (IDs by default; use --long for details)
-
-# Show differences between specs and proposed changes
-openspec diff [change-name]
-
-# Archive completed changes
-openspec archive [change-name]
+# This creates:
+# openspec/
+#   ├── specs/       # Current specifications (truth)
+#   ├── changes/     # Proposed changes
+#   └── README.md    # AI instructions for your tool
 ```
 
-## Commands
+### 2. Create Your First Change
 
-### `openspec init`
+Jump straight into creating a change proposal with your AI assistant (works with Claude Code, Cursor, or any AI tool):
 
-Initializes OpenSpec in your project by creating:
-- `openspec/` directory structure
-- `openspec/README.md` with OpenSpec instructions
-- AI tool configuration files (based on your selection)
+```markdown
+// Quick win - Add a simple new feature:
+You: "I want to add a user profile API endpoint.
+      Please create an OpenSpec change proposal for this."
 
-### `openspec update`
+AI: "I'll create an OpenSpec change proposal for the user profile API..."
+    *Creates openspec/changes/add-user-profile-api/ with:*
+    - proposal.md (why this feature is needed)
+    - tasks.md (implementation checklist)
+    - design.md (API design decisions)
+    - specs/user-profile/spec.md (new requirements)
 
-Updates OpenSpec instructions to the latest version. This command is **team-friendly** and only updates files that already exist:
+You: "The proposal looks good. Let's implement it."
 
-- Always updates `openspec/README.md` with the latest OpenSpec instructions
-- **Only updates existing AI tool configuration files** (e.g., CLAUDE.md, CURSOR.md)
-- **Never creates new AI tool configuration files**
-- Preserves content outside of OpenSpec markers in AI tool files
+AI: "Following the tasks in openspec/changes/add-user-profile-api/tasks.md:
+     Task 1.1: Create user profile model..."
+    *Implements each task systematically*
+```
 
-This allows team members to use different AI tools without conflicts. Each developer can maintain their preferred AI tool configuration file, and `openspec update` will respect their choice.
+### 3. Track Your Work
 
-### `openspec spec`
+```bash
+# View active changes (what's being worked on)
+openspec list
 
-Manage and view specifications.
+# Validate your changes are properly formatted
+openspec validate add-2fa --strict
 
-Examples:
-- `openspec spec show <spec-id>`
-  - Text mode: prints raw `spec.md` content
-  - JSON mode (`--json`): returns minimal, stable shape
-    - Filters are JSON-only: `--requirements`, `--no-scenarios`, `-r/--requirement <1-based>`
-- `openspec spec list`
-  - Prints IDs only by default
-  - Use `--long` to include `title` and `[requirements N]`
-- `openspec spec validate <spec-id>`
-  - Text: human-readable summary to stdout/stderr
-  - `--json` for structured report
+# After deployment, archive the completed change
+openspec archive add-2fa
+# This moves the change to archive/ and updates specs/
+```
 
-### `openspec change`
+## Common Commands
 
-Manage and view change proposals.
+```bash
+# Most used:
+openspec list              # See what changes you're working on
+openspec archive <change>  # Mark a change as complete after deployment
 
-Examples:
-- `openspec change show <change-id>`
-  - Text mode: prints raw `proposal.md` content
-  - JSON mode (`--json`): `{ id, title, deltaCount, deltas }`
-  - Filtering is JSON-only: `--deltas-only` (alias: `--requirements-only`, deprecated)
-- `openspec change list`
-  - Prints IDs only by default
-  - Use `--long` to include `title` and counts `[deltas N] [tasks x/y]`
-- `openspec change validate <change-id>`
-  - Text: human-readable result
-  - `--json` for structured report
+# Also useful:
+openspec validate <change> # Check formatting before committing
+openspec show <change>     # View change details
+```
 
-### `openspec diff [change-name]`
+## Example: How AI Creates OpenSpec Files
 
-Shows the differences between current specs and proposed changes:
-- Displays a unified diff format
-- Helps review what will change before implementation
-- Useful for pull request reviews
+When you ask your AI assistant to "add two-factor authentication", it creates:
 
-### `openspec archive [change-name]`
+```
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md           # Current auth spec (if exists)
+└── changes/
+    └── add-2fa/              # AI creates this entire structure
+        ├── proposal.md       # Why and what changes
+        ├── tasks.md          # Implementation checklist
+        ├── design.md         # Technical decisions (optional)
+        └── specs/
+            └── auth/
+                └── spec.md   # Delta showing additions
+```
 
-Archives a completed change:
-- Moves change from `openspec/changes/` to `openspec/changes/archive/`
-- Adds a date prefix to the archived change
-- Updates specs to reflect the new state
-- Use `--skip-specs` to archive without updating specs (for abandoned changes)
+### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
 
-## Team Collaboration
+```markdown
+# Auth Specification
 
-OpenSpec is designed for team collaboration:
+## Purpose
+Authentication and session management.
+
+## Requirements
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN a JWT is returned
+```
+
+### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required
+```
+
+### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column to users table
+- [ ] 1.2 Create OTP verification logs table
+
+## 2. Backend Implementation  
+- [ ] 2.1 Add OTP generation endpoint
+- [ ] 2.2 Modify login flow to require OTP
+- [ ] 2.3 Add OTP verification endpoint
+
+## 3. Frontend Updates
+- [ ] 3.1 Create OTP input component
+- [ ] 3.2 Update login flow UI
+```
+
+**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
+
+## Understanding OpenSpec Files
+
+### Delta Format
+
+Deltas are "patches" that show how specs change:
+
+- **`## ADDED Requirements`** - New capabilities
+- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
+- **`## REMOVED Requirements`** - Deprecated features
+
+**Format requirements:**
+- Use `### Requirement: <name>` for headers
+- Every requirement needs at least one `#### Scenario:` block
+- Use SHALL/MUST in requirement text
+
+
+## Why OpenSpec Works
+
+OpenSpec creates **alignment** between you and your AI coding assistant:
+
+1. **You describe** what you want to build
+2. **AI creates specs** before writing any code
+3. **You review and adjust** the specifications
+4. **AI implements** exactly what was specified
+5. **Everyone understands** what's being built through clear specs
+
+**True Interoperability:** OpenSpec is designed to be universal. No API keys, no vendor lock-in. It works by adding context rules to ANY AI coding tool - whether you use Claude Code today, switch to Cursor tomorrow, or adopt the next breakthrough AI assistant. Your specs remain portable and your workflow stays consistent.
+
+
+## How OpenSpec Compares
+
+### vs. Kiro.dev
+OpenSpec groups all changes for a feature in one place (`openspec/changes/feature-name/`), making it easy to track what needs to be done. Kiro spreads changes across multiple spec folders, making feature tracking harder.
+
+### vs. No Specs
+Without specs, AI coding assistants generate code based on vague prompts, often missing requirements or adding unwanted features. OpenSpec ensures alignment before any code is written.
+
+## Team Adoption
+
+### Getting Started with Your Team
+
+1. **Initialize OpenSpec** - Run `openspec init` in your project
+2. **Start with new features** - Use OpenSpec for your next change proposal
+3. **Build incrementally** - Each new feature adds to your spec library
+4. **Future capability** - We're working on tools to generate specs from existing code
+
+**Tool Freedom:** Your team can use different AI assistants. One developer might use Claude Code while another uses Cursor - OpenSpec keeps everyone aligned through shared specifications. Run `openspec update` to configure for any supported tool without affecting others.
 
-1. **AI Tool Flexibility**: Each team member can use their preferred AI assistant (Claude, Cursor, etc.)
-2. **Non-Invasive Updates**: The `update` command only modifies existing files, never forcing tools on team members
-3. **Specification Sharing**: The `openspec/` directory contains shared specifications that all team members work from
-4. **Change Tracking**: Proposed changes are visible to all team members for review before implementation
 
 ## Contributing
 
-See `openspec/specs/` for the current system specifications and `openspec/changes/` for pending improvements.
-
-## Notes
-
-- The legacy `openspec list` command is deprecated. Use `openspec spec list` and `openspec change list`.
-- Text output is raw-first (no formatting or filtering). Prefer `--json` for tooling-friendly output.
-- Global `--no-color` disables ANSI colors and respects `NO_COLOR`.
+- Install dependencies: `npm install`
+- Build: `npm run build`
+- Test: `npm test`
+- Develop CLI locally: `npm run dev` or `npm run dev:cli`
+- Conventional commits (one-line): `type(scope): subject`
 
 ## License
 
-MIT
+MIT
+

openspec/README.md

@@ -55,7 +55,6 @@ After deployment, create separate PR to:
 openspec list                  # List active changes
 openspec list --specs          # List specifications
 openspec show [item]           # Display change or spec
-openspec diff [change]         # Show spec differences
 openspec validate [item]       # Validate changes or specs
 openspec archive [change]      # Archive after deployment
 
@@ -290,7 +289,6 @@ Only add complexity with:
 ```bash
 openspec list              # What's in progress?
 openspec show [item]       # View details
-openspec diff [change]     # What's changing?
 openspec validate --strict # Is it correct?
 openspec archive [change]  # Mark complete
 ```

openspec/changes/adopt-verb-noun-cli-structure/specs/cli-list/spec.md

@@ -1,57 +0,0 @@
-# Delta: CLI List Command
-
-## MODIFIED Requirements
-
-### Requirement: Command Execution
-The command SHALL scan and analyze either active changes or specs based on the selected mode.
-
-#### Scenario: Scanning for changes (default)
-- **WHEN** `openspec list` is executed without flags
-- **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
-
-#### Scenario: Scanning for specs
-- **WHEN** `openspec list --specs` is executed
-- **THEN** scan the `openspec/specs/` directory for capabilities
-- **AND** read each capability's `spec.md`
-- **AND** parse requirements to compute requirement counts
-
-### Requirement: Output Format
-The command SHALL display items in a clear, readable table format with mode-appropriate progress or counts.
-
-#### Scenario: Displaying change list (default)
-- **WHEN** displaying the list of changes
-- **THEN** show a table with columns:
-  - Change name (directory name)
-  - Task progress (e.g., "3/5 tasks" or "✓ Complete")
-
-#### Scenario: Displaying spec list
-- **WHEN** displaying the list of specs
-- **THEN** show a table with columns:
-  - Spec id (directory name)
-  - Requirement count (e.g., "requirements 12")
-
-### Requirement: Empty State
-The command SHALL provide clear feedback when no items are present for the selected mode.
-
-#### Scenario: Handling empty state (changes)
-- **WHEN** no active changes exist (only archive/ or empty changes/)
-- **THEN** display: "No active changes found."
-
-#### Scenario: Handling empty state (specs)
-- **WHEN** no specs directory exists or contains no capabilities
-- **THEN** display: "No specs found."
-
-### Requirement: Flags
-The command SHALL accept flags to select the noun being listed.
-
-#### Scenario: Selecting specs
-- **WHEN** `--specs` is provided
-- **THEN** list specs instead of changes
-
-#### Scenario: Selecting changes
-- **WHEN** `--changes` is provided
-- **THEN** list changes explicitly (same as default behavior)
-
-

openspec/changes/improve-deterministic-tests/proposal.md

@@ -0,0 +1,78 @@
+# Change: Improve Deterministic Tests (Isolate From Repo State)
+
+## Problem
+
+Some unit tests (e.g., ChangeCommand.show/validate) read the live repository
+state via `process.cwd()` and `openspec/changes`. This makes outcomes depend on
+whatever directories happen to exist and the order returned by `fs.readdir`,
+causing flaky success/failure across environments.
+
+Symptoms observed:
+- Tests sometimes select a partial or unrelated change folder.
+- Failures like missing `proposal.md` when a stray change directory is picked.
+- Environment/sandbox differences alter `readdir` ordering and worker behavior.
+
+## Goals
+
+- Make tests deterministic and hermetic.
+- Remove dependence on real repo contents and directory ordering.
+- Keep runtime behavior unchanged for end users.
+
+## Non‑Goals
+
+- Introduce heavy frameworks or test harness complexity.
+- Redesign CLI behavior or change default paths for users.
+
+## Approach
+
+1) Test-local fixture root
+- Each suite that touches filesystem discovery creates a temporary directory:
+  - `openspec/changes/sample-change/proposal.md`
+  - `openspec/changes/sample-change/specs/sample/spec.md`
+- `beforeAll`: `process.chdir(tmpRoot)`; `afterAll`: restore original cwd.
+- Use a constant `changeName = 'sample-change'`; remove reliance on
+  `readdir` order.
+
+2) Optional thin DI for commands (minimal, if needed)
+- Allow `ChangeCommand` (and similar) to accept an optional `root` path
+  (default `process.cwd()`), used for path resolution.
+- Tests pass the temp root explicitly; production code remains unchanged.
+
+3) Harden discovery helpers (safe enhancement)
+- Update `getActiveChangeIds()`/`getActiveChanges()` to include only
+  directories containing `proposal.md` (and optionally at least one
+  `specs/*/spec.md`).
+- Prevents incomplete/stray change folders from being treated as active.
+
+## Rationale
+
+- Small, focused changes eliminate flakiness without altering user workflows.
+- Temporary fixtures are a well-understood testing pattern and keep tests fast.
+- Optional constructor root param is a minimal DI surface that avoids global
+  stubbing and keeps code simple.
+
+## Risks & Mitigations
+
+- Risk: Tests forget to restore `process.cwd()`.
+  - Mitigation: Add `afterAll` guard restoring cwd; reset `process.exitCode` in
+    `afterEach` where modified.
+- Risk: Behavior divergence if DI root is misused.
+  - Mitigation: Default to `process.cwd()`; only tests pass custom roots.
+
+## Acceptance Criteria
+
+- Tests that previously depended on repo state now:
+  - Create and use a temp fixture root.
+  - Do not read real `openspec/changes` during execution.
+  - Pass consistently regardless of directory order or stray folders.
+- No change to CLI behavior for end users (paths still default to cwd).
+
+## Rollout
+
+- Phase 1: Convert the suites that hit `ChangeCommand.show/validate` to
+  isolated fixtures; verify stability locally and in CI.
+- Phase 2: Apply the same pattern to any remaining suites that touch file
+  discovery (`list`, `show`, `validate`, `diff`).
+- Phase 3 (optional): Introduce the constructor `root` param and discovery
+  hardening, if Phase 1 alone isn’t sufficient.
+

openspec/changes/improve-deterministic-tests/tasks.md

@@ -0,0 +1,25 @@
+# Implementation Tasks
+
+## 1. Test Isolation
+- [x] 1.1 Create temp fixture roots per suite (openspec/changes, openspec/specs)
+- [x] 1.2 Use process.chdir to temp root within tests
+- [x] 1.3 Restore original cwd and clean temp dirs after each
+
+## 2. Deterministic Discovery
+- [x] 2.1 Implement getActiveChangeIds(root?) to only include dirs with proposal.md
+- [x] 2.2 Implement getSpecIds(root?) to only include dirs with spec.md
+- [x] 2.3 Return sorted results to avoid fs.readdir ordering variance
+
+## 3. Command Integration
+- [x] 3.1 Ensure change/show/validate rely on cwd and discovery helpers
+- [x] 3.2 Keep runtime behavior unchanged for end users
+
+## 4. Validation
+- [x] 4.1 Convert affected command tests (show, spec, validate, change) to isolated fixtures
+- [x] 4.2 Verify tests pass consistently across environments
+- [x] 4.3 Confirm no reads from real repo state during tests
+
+## 5. Optional (Not Needed Now)
+- [x] 5.1 Add optional root param to discovery helpers (default process.cwd())
+- [ ] 5.2 Consider threading root through command constructors if ever required
+

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

@@ -0,0 +1,81 @@
+# Remove Diff Command
+
+## Problem
+
+The `openspec diff` command adds unnecessary complexity to the OpenSpec CLI for several reasons:
+
+1. **Redundant functionality**: The `openspec show` command already provides comprehensive visualization of changes through structured JSON output and markdown rendering
+2. **Maintenance burden**: The diff command requires a separate dependency (jest-diff) and additional code complexity (~227 lines)
+3. **Limited value**: Developers can achieve better diff visualization using existing tools:
+   - Git diff for actual file changes
+   - The `show` command for structured change viewing
+   - Standard diff utilities for comparing spec files directly
+4. **Inconsistent with verb-noun pattern**: The command doesn't follow the preferred verb-first command structure that other commands are migrating to
+
+## Solution
+
+Remove the `openspec diff` command entirely and guide users to more appropriate alternatives:
+
+1. **For viewing change content**: Use `openspec show <change-name>` which provides:
+   - Structured JSON output with `--json` flag
+   - Markdown rendering for human-readable format
+   - Delta-only views with `--deltas-only` flag
+   - Full spec content visualization
+
+2. **For comparing files**: Use standard tools:
+   - `git diff` for version control comparisons
+   - System diff utilities for file-by-file comparisons
+   - IDE diff viewers for visual comparisons
+
+## Benefits
+
+- **Reduced complexity**: Removes ~227 lines of code and the jest-diff dependency
+- **Clearer user journey**: Directs users to the canonical `show` command for viewing changes
+- **Lower maintenance**: Fewer commands to maintain and test
+- **Better alignment**: Focuses on the core OpenSpec workflow without redundant features
+
+## Implementation
+
+### Files to Remove
+- `/src/core/diff.ts` - The entire diff command implementation
+- `/openspec/specs/cli-diff/spec.md` - The diff command specification
+
+### Files to Update
+- `/src/cli/index.ts` - Remove diff command registration (lines 8, 84-96)
+- `/package.json` - Remove jest-diff dependency
+- `/README.md` - Remove diff command documentation
+- `/openspec/README.md` - Remove diff command references
+- Various documentation files mentioning `openspec diff`
+
+### Migration Guide for Users
+
+Users currently using `openspec diff` should transition to:
+
+```bash
+# Before
+openspec diff add-feature
+
+# After - view the change proposal
+openspec show add-feature
+
+# After - view only the deltas
+openspec show add-feature --json --deltas-only
+
+# After - use git for file comparisons
+git diff openspec/specs openspec/changes/add-feature/specs
+```
+
+## Risks
+
+- **User disruption**: Existing users may have workflows depending on the diff command
+  - Mitigation: Provide clear migration guide and deprecation period
+  
+- **Loss of visual diff**: The colored, unified diff format will no longer be available
+  - Mitigation: Users can use git diff or other tools for visual comparisons
+
+## Success Metrics
+
+- Successful removal with no broken dependencies
+- Documentation updated to reflect the change
+- Tests passing without the diff command
+- Reduced package size from removing jest-diff dependency

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

@@ -0,0 +1,41 @@
+# Remove Diff Command - Tasks
+
+## 1. Remove Core Implementation
+- [x] Delete `/src/core/diff.ts`
+- [x] Remove DiffCommand import from `/src/cli/index.ts`
+- [x] Remove diff command registration from CLI
+
+## 2. Remove Specifications
+- [x] Delete `/openspec/specs/cli-diff/spec.md`
+- [x] Archive the spec for historical reference if needed
+
+## 3. Update Dependencies
+- [x] Remove jest-diff from package.json dependencies
+- [x] Run pnpm install to update lock file
+
+## 4. Update Documentation
+- [x] Update main README.md to remove diff command references
+- [x] Update openspec/README.md to remove diff command from command list
+- [x] Update CLAUDE.md template if it mentions diff command
+- [x] Update any example workflows that use diff command
+
+## 5. Update Related Files
+- [x] Search and update any remaining references to "openspec diff" in:
+  - Template files
+  - Test files (if any exist for diff command)
+  - Archive documentation
+  - Change proposals
+
+## 6. Add Deprecation Notice (Optional Phase)
+- [ ] Consider adding a deprecation warning before full removal
+- [ ] Provide helpful message directing users to `openspec show` command
+
+## 7. Testing
+- [x] Ensure all tests pass after removal
+- [x] Verify CLI help text no longer shows diff command
+- [x] Test that show command provides adequate replacement functionality
+
+## 8. Documentation of Alternative Workflows
+- [x] Document how to use `openspec show` for viewing changes
+- [x] Document how to use git diff for file comparisons
+- [x] Add migration guide to help text or documentation

openspec/specs/cli-diff/spec.md

@@ -1,123 +0,0 @@
-# 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]
-```
-## Requirements
-### Requirement: Without Arguments
-
-The command SHALL provide an interactive selection when no change is specified.
-
-#### Scenario: Running 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
-
-### Requirement: With Change Name
-
-The command SHALL compare specs when a specific change is provided.
-
-#### Scenario: Running with change name
-
-- **WHEN** running `openspec diff <change-name>`
-- **THEN** compare all spec files in `changes/<change-name>/specs/` with corresponding files in `specs/`
-
-### Requirement: Diff Output
-
-The command SHALL show a requirement-level comparison displaying only changed requirements.
-
-#### Scenario: Side-by-side comparison of changes
-
-- **WHEN** running `openspec diff <change>`
-- **THEN** display only requirements that have changed
-- **AND** show them in a side-by-side format that:
-  - Clearly shows the current version on the left
-  - Shows the future version on the right
-  - Indicates new requirements (not in current)
-  - Indicates removed requirements (not in future)
-  - Aligns modified requirements for easy comparison
-
-### Requirement: Color Support
-
-The command SHALL enhance readability with colors when supported.
-
-#### Scenario: Terminal with color support
-
-- **WHEN** terminal supports colors
-- **THEN** display:
-  - Removed lines in red
-  - Added lines in green
-  - File headers in bold
-  - Context lines in default color
-
-### Requirement: Error Handling
-
-The command SHALL provide clear error messages for various failure conditions.
-
-#### Scenario: Change not found
-
-- **WHEN** specified change doesn't exist
-- **THEN** display error "Change '<name>' not found"
-
-#### Scenario: No specs in change
-
-- **WHEN** no specs directory in change
-- **THEN** display "No spec changes found for '<name>'"
-
-#### Scenario: Missing changes directory
-
-- **WHEN** changes directory doesn't exist
-- **THEN** display "No OpenSpec changes directory found"
-
-### Requirement: Validation
-
-The command SHALL validate that changes can be applied successfully.
-
-#### Scenario: Invalid delta references
-
-- **WHEN** delta references non-existent requirement
-- **THEN** show error message with specific requirement
-- **AND** continue showing other valid changes
-- **AND** clearly mark failed changes in the output
-
-### Requirement: Diff Command Enhancement
-
-The diff command SHALL validate change structure before displaying differences.
-
-#### Scenario: Validate before diff
-
-- **WHEN** executing `openspec diff change-name`
-- **THEN** validate change structure
-- **AND** show validation warnings if present
-- **AND** continue with diff display
-
-## 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): 
-```

package.json

@@ -1,6 +1,6 @@
 {
-  "name": "openspec",
-  "version": "0.1.0-beta.0",
+  "name": "@fission-ai/openspec",
+  "version": "0.1.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -9,15 +9,16 @@
     "ai",
     "development"
   ],
-  "homepage": "https://github.com/tabdilsaidixit/openspec",
+  "homepage": "https://github.com/Fission-AI/OpenSpec",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tabdilsaidixit/openspec.git"
+    "url": "https://github.com/Fission-AI/OpenSpec"
   },
   "license": "MIT",
   "author": "OpenSpec Contributors",
   "type": "module",
   "publishConfig": {
+    "access": "public",
     "tag": "next"
   },
   "exports": {
@@ -45,12 +46,14 @@
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
     "prepare": "pnpm run build",
-    "prepublishOnly": "pnpm run build"
+    "prepublishOnly": "pnpm run build",
+    "changeset": "changeset"
   },
   "engines": {
     "node": ">=20.19.0"
   },
   "devDependencies": {
+    "@changesets/cli": "^2.27.7",
     "@types/node": "^24.2.0",
     "@vitest/ui": "^3.2.4",
     "typescript": "^5.9.2",
@@ -60,7 +63,6 @@
     "@inquirer/prompts": "^7.8.0",
     "chalk": "^5.5.0",
     "commander": "^14.0.0",
-    "jest-diff": "^30.0.5",
     "ora": "^8.2.0",
     "zod": "^4.0.17"
   }

src/cli/index.ts

@@ -5,7 +5,6 @@ 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';
 import { registerSpecCommand } from '../commands/spec.js';
@@ -81,20 +80,6 @@ program
     }
   });
 
-program
-  .command('diff [change-name]')
-  .description('Show differences between proposed spec changes and current specs (includes validation warnings)')
-  .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 items (changes by default). Use --specs to list specs.')

src/commands/change.ts

@@ -241,10 +241,18 @@ export class ChangeCommand {
   private async getActiveChanges(changesPath: string): Promise<string[]> {
     try {
       const entries = await fs.readdir(changesPath, { withFileTypes: true });
-      return entries
-        .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== ARCHIVE_DIR)
-        .map(entry => entry.name)
-        .sort();
+      const result: string[] = [];
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === ARCHIVE_DIR) continue;
+        const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+        try {
+          await fs.access(proposalPath);
+          result.push(entry.name);
+        } catch {
+          // skip directories without proposal.md
+        }
+      }
+      return result.sort();
     } catch {
       return [];
     }
@@ -280,4 +288,4 @@ export class ChangeCommand {
     console.error('Next steps:');
     bullets.forEach(b => console.error(`  ${b}`));
   }
-}
+}

src/core/diff.ts

@@ -1,227 +0,0 @@
-import { promises as fs } from 'fs';
-import path from 'path';
-import chalk from 'chalk';
-import { diffStringsUnified } from 'jest-diff';
-import { select } from '@inquirer/prompts';
-import { Validator } from './validation/validator.js';
-
-// 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;
-    }
-
-    // Validate specs and show warnings (non-blocking)
-    const validator = new Validator();
-    let hasWarnings = false;
-    
-    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');
-          
-          try {
-            await fs.access(specFile);
-            const report = await validator.validateSpec(specFile);
-            
-            if (report.issues.length > 0) {
-              const warnings = report.issues.filter(i => i.level === 'WARNING');
-              const errors = report.issues.filter(i => i.level === 'ERROR');
-              
-              if (errors.length > 0 || warnings.length > 0) {
-                if (!hasWarnings) {
-                  console.log(chalk.yellow('\n⚠️  Validation warnings found:'));
-                  hasWarnings = true;
-                }
-                
-                console.log(chalk.yellow(`\n  ${entry.name}/spec.md:`));
-                for (const issue of errors) {
-                  console.log(chalk.red(`    ✗ ${issue.message}`));
-                }
-                for (const issue of warnings) {
-                  console.log(chalk.yellow(`    ⚠ ${issue.message}`));
-                }
-              }
-            }
-          } catch {
-            // Spec file doesn't exist, skip validation
-          }
-        }
-      }
-      
-      if (hasWarnings) {
-        console.log(chalk.yellow('\nConsider fixing these issues before archiving.\n'));
-      }
-    } catch {
-      // No specs directory, skip validation
-    }
-
-    // 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/templates/claude-template.ts

@@ -35,7 +35,6 @@ After deployment, use \`openspec archive [change]\` (add \`--skip-specs\` for to
 openspec list              # Active changes
 openspec list --specs      # Existing specifications
 openspec show [item]       # View details
-openspec diff [change]     # Show spec differences
 openspec validate --strict # Validate thoroughly
 openspec archive [change]  # Archive after deployment
 

src/utils/item-discovery.ts

@@ -5,10 +5,18 @@ export async function getActiveChangeIds(root: string = process.cwd()): Promise<
   const changesPath = path.join(root, 'openspec', 'changes');
   try {
     const entries = await fs.readdir(changesPath, { withFileTypes: true });
-    return entries
-      .filter(entry => entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'archive')
-      .map(entry => entry.name)
-      .sort();
+    const result: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive') continue;
+      const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+      try {
+        await fs.access(proposalPath);
+        result.push(entry.name);
+      } catch {
+        // skip directories without proposal.md
+      }
+    }
+    return result.sort();
   } catch {
     return [];
   }
@@ -35,4 +43,3 @@ export async function getSpecIds(root: string = process.cwd()): Promise<string[]
   return result.sort();
 }
 
-

test/commands/change.interactive-show.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -9,9 +9,6 @@ describe('change show (interactive behavior)', () => {
   const changesDir = path.join(testDir, 'openspec', 'changes');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(changesDir, { recursive: true });

test/commands/change.interactive-validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -12,9 +12,6 @@ describe('change validate (interactive behavior)', () => {
   const changesDir = path.join(testDir, 'openspec', 'changes');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(changesDir, { recursive: true });

test/commands/show.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -10,9 +10,6 @@ describe('top-level show command', () => {
   const specsDir = path.join(testDir, 'openspec', 'specs');
   const openspecBin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(changesDir, { recursive: true });

test/commands/spec.interactive-show.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -9,9 +9,6 @@ describe('spec show (interactive behavior)', () => {
   const specsDir = path.join(testDir, 'openspec', 'specs');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(specsDir, { recursive: true });

test/commands/spec.interactive-validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -9,9 +9,6 @@ describe('spec validate (interactive behavior)', () => {
   const specsDir = path.join(testDir, 'openspec', 'specs');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(specsDir, { recursive: true });

test/commands/spec.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach, beforeAll } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -9,10 +9,6 @@ describe('spec command', () => {
   const specsDir = path.join(testDir, 'openspec', 'specs');
   const openspecBin = path.join(projectRoot, 'bin', 'openspec.js');
   
-  beforeAll(() => {
-    // Ensure CLI is built so bin/openspec.js loads latest logic from dist/
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
   
   beforeEach(async () => {
     await fs.mkdir(specsDir, { recursive: true });

test/commands/validate.enriched-output.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -9,10 +9,6 @@ describe('validate command enriched human output', () => {
   const changesDir = path.join(testDir, 'openspec', 'changes');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    // Build once so the bin can resolve dist
-    try { execSync('pnpm -s build', { stdio: 'pipe' }); } catch {}
-  });
 
   beforeEach(async () => {
     await fs.mkdir(changesDir, { recursive: true });

test/commands/validate.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { promises as fs } from 'fs';
 import path from 'path';
 import { execSync } from 'child_process';
@@ -10,9 +10,6 @@ describe('top-level validate command', () => {
   const specsDir = path.join(testDir, 'openspec', 'specs');
   const bin = path.join(projectRoot, 'bin', 'openspec.js');
 
-  beforeAll(() => {
-    execSync('pnpm -s build', { stdio: 'pipe' });
-  });
 
   beforeEach(async () => {
     await fs.mkdir(changesDir, { recursive: true });

test/core/commands/change-command.list.test.ts

@@ -1,14 +1,29 @@
-import { describe, it, expect, beforeAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { ChangeCommand } from '../../../src/commands/change.js';
-
-// These tests assume the repository's own openspec/changes directory exists
-// and contains at least one active change (e.g., add-change-commands)
+import path from 'path';
+import { promises as fs } from 'fs';
+import os from 'os';
 
 describe('ChangeCommand.list', () => {
   let cmd: ChangeCommand;
+  let tempRoot: string;
+  let originalCwd: string;
 
-  beforeAll(() => {
+  beforeAll(async () => {
     cmd = new ChangeCommand();
+    originalCwd = process.cwd();
+    tempRoot = path.join(os.tmpdir(), `openspec-change-command-list-${Date.now()}`);
+    const changeDir = path.join(tempRoot, 'openspec', 'changes', 'demo');
+    await fs.mkdir(changeDir, { recursive: true });
+    const proposal = `# Change: Demo\n\n## Why\nTest list.\n\n## What Changes\n- **auth:** Add requirement`;
+    await fs.writeFile(path.join(changeDir, 'proposal.md'), proposal, 'utf-8');
+    await fs.writeFile(path.join(changeDir, 'tasks.md'), '- [x] Task 1\n- [ ] Task 2\n', 'utf-8');
+    process.chdir(tempRoot);
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await fs.rm(tempRoot, { recursive: true, force: true });
   });
 
   it('returns JSON with expected shape', async () => {

test/core/commands/change-command.show-validate.test.ts

@@ -1,34 +1,33 @@
-import { describe, it, expect, beforeAll } from 'vitest';
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { ChangeCommand } from '../../../src/commands/change.js';
 import path from 'path';
 import { promises as fs } from 'fs';
-
-async function findSingleActiveChange(root: string): Promise<string | undefined> {
-  const changesDir = path.join(root, 'openspec', 'changes');
-  try {
-    const entries = await fs.readdir(changesDir, { withFileTypes: true });
-    const names = entries
-      .filter((e) => e.isDirectory() && e.name !== 'archive')
-      .map((e) => e.name);
-    if (names.length === 1) return names[0];
-    return names.includes('add-change-commands') ? 'add-change-commands' : names[0];
-  } catch {
-    return undefined;
-  }
-}
+import os from 'os';
 
 describe('ChangeCommand.show/validate', () => {
   let cmd: ChangeCommand;
-  let changeName: string | undefined;
+  let changeName: string;
+  let tempRoot: string;
+  let originalCwd: string;
 
   beforeAll(async () => {
     cmd = new ChangeCommand();
-    changeName = await findSingleActiveChange(process.cwd());
+    originalCwd = process.cwd();
+    tempRoot = path.join(os.tmpdir(), `openspec-change-command-${Date.now()}`);
+    const changesDir = path.join(tempRoot, 'openspec', 'changes', 'sample-change');
+    await fs.mkdir(changesDir, { recursive: true });
+    const proposal = `# Change: Sample Change\n\n## Why\nConsistency in tests.\n\n## What Changes\n- **auth:** Add requirement`;
+    await fs.writeFile(path.join(changesDir, 'proposal.md'), proposal, 'utf-8');
+    process.chdir(tempRoot);
+    changeName = 'sample-change';
+  });
+
+  afterAll(async () => {
+    process.chdir(originalCwd);
+    await fs.rm(tempRoot, { recursive: true, force: true });
   });
 
   it('show --json prints JSON including deltas', async () => {
-    if (!changeName) return; // skip if no changes present
-
     const logs: string[] = [];
     const origLog = console.log;
     try {
@@ -67,8 +66,6 @@ describe('ChangeCommand.show/validate', () => {
   });
 
   it('show --json --requirements-only returns minimal object with deltas (deprecated alias)', async () => {
-    if (!changeName) return; // skip if no changes present
-
     const logs: string[] = [];
     const origLog = console.log;
     try {
@@ -93,8 +90,6 @@ describe('ChangeCommand.show/validate', () => {
   });
 
   it('validate --strict --json returns a report with valid boolean', async () => {
-    if (!changeName) return; // skip if no changes present
-
     const logs: string[] = [];
     const origLog = console.log;
     try {

vitest.config.ts

@@ -4,6 +4,9 @@ export default defineConfig({
   test: {
     globals: true,
     environment: 'node',
+    globalSetup: './vitest.setup.ts',
+    // Keep default pool settings; some tests rely on process.chdir,
+    // which is not supported in worker threads
     include: ['test/**/*.test.ts'],
     coverage: {
       reporter: ['text', 'json', 'html'],
@@ -19,4 +22,4 @@ export default defineConfig({
     testTimeout: 10000,
     hookTimeout: 10000
   }
-});
+});

vitest.setup.ts

@@ -0,0 +1,21 @@
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+
+// Run once before all tests
+export async function setup() {
+  const distPath = path.join(process.cwd(), 'dist', 'cli', 'index.js');
+  
+  if (!existsSync(distPath)) {
+    console.log('Building project before tests...');
+    try {
+      execSync('pnpm run build', { 
+        stdio: 'inherit',
+        cwd: process.cwd()
+      });
+    } catch (error) {
+      console.error('Failed to build project:', error);
+      process.exit(1);
+    }
+  }
+}