docs: add purpose description to instruction-loader spec

chore: archive add-instruction-loader change
- Move change to archive as 2025-12-28-add-instruction-loader - Create instruction-loader spec with 4 requirements
2026-10-04 06:18:24 +08:00 · 2025-12-28 17:41:36 +11:00 · 2025-12-28 17:34:41 +11:00 · 2025-12-28 17:21:53 +11:00 · 2025-12-28 17:00:15 +11:00 · 2025-12-26 23:45:36 +11:00
109 changed files with 13546 additions and 79 deletions
@@ -142,6 +142,9 @@ jobs:
      - name: Type check
        run: pnpm exec tsc --noEmit

+      - name: Lint
+        run: pnpm lint
+
      - name: Check for build artifacts
        run: |
          if [ ! -d "dist" ]; then
@@ -7,6 +7,7 @@ on:
 permissions:
  contents: write
  pull-requests: write
+  id-token: write # Required for npm OIDC trusted publishing

 concurrency:
  group: release-${{ github.ref }}
@@ -27,11 +28,9 @@ jobs:

      - uses: actions/setup-node@v4
        with:
-          node-version: '20'
+          node-version: '24' # Node 24 includes npm 11.5.1+ required for OIDC
          cache: 'pnpm'
          registry-url: 'https://registry.npmjs.org'
-          scope: '@fission-ai'
-          always-auth: true

      - run: pnpm install --frozen-lockfile

@@ -46,5 +45,4 @@ jobs:
          publish: pnpm run release:ci
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # npm authentication handled via OIDC trusted publishing (no token needed)
@@ -140,8 +140,6 @@ dist/
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*

-# Internal Docs
-docs/

 # Claude
 .claude/
@@ -1,5 +1,43 @@
 # @fission-ai/openspec

+## 0.17.2
+
+### Patch Changes
+
+- 455c65f: Fix `--no-interactive` flag in validate command to properly disable spinner, preventing hangs in pre-commit hooks and CI environments
+
+## 0.17.1
+
+### Patch Changes
+
+- a2757e7: Fix pre-commit hook hang issue in config command by using dynamic import for @inquirer/prompts
+
+  The config command was causing pre-commit hooks to hang indefinitely due to stdin event listeners being registered at module load time. This fix converts the static import to a dynamic import that only loads inquirer when the `config reset` command is actually used interactively.
+
+  Also adds ESLint with a rule to prevent static @inquirer imports, avoiding future regressions.
+
+## 0.17.0
+
+### Minor Changes
+
+- 2e71835: ### New Features
+
+  - Add `openspec config` command for managing global configuration settings
+  - Implement global config directory with XDG Base Directory specification support
+  - Add Oh-my-zsh shell completions support for enhanced CLI experience
+
+  ### Bug Fixes
+
+  - Fix hang in pre-commit hooks by using dynamic imports
+  - Respect XDG_CONFIG_HOME environment variable on all platforms
+  - Resolve Windows compatibility issues in zsh-installer tests
+  - Align cli-completion spec with implementation
+  - Remove hardcoded agent field from slash commands
+
+  ### Documentation
+
+  - Alphabetize AI tools list in README and make it collapsible
+
 ## 0.16.0

 ### Minor Changes
@@ -85,42 +85,49 @@ See the full comparison in [How OpenSpec Compares](#how-openspec-compares).

 ### Supported AI Tools

-#### Native Slash Commands
+<details>
+<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
+
 These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.

 | Tool | Commands |
 |------|----------|
+| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
+| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
+| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
 | **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
-| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
-| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
-| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
+| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
+| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
 | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
-| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
 | **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
-| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
-| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
 | **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
-| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
-| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
-| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
 | **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
-
+| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
+| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
+| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |

 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.

-#### AGENTS.md Compatible
+</details>
+
+<details>
+<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+
 These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).

 | Tools |
 |-------|
 | Amp • Jules • Others |

+</details>
+
 ### Install & Initialize

 #### Prerequisites
@@ -0,0 +1,597 @@
+# POC-OpenSpec-Core Analysis
+
+---
+
+## Design Decisions & Terminology
+
+### Philosophy: Not a Workflow System
+
+This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
+
+| What it's NOT | What it IS |
+|---------------|------------|
+| Linear step-by-step progression | Exploratory, iterative planning |
+| Bureaucratic checkpoints | Enablers that unlock possibilities |
+| "You must complete step 1 first" | "Here's what you could create now" |
+| Form-filling | Fluid document creation |
+
+**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
+
+### Terminology
+
+| Term | Definition | Example |
+|------|------------|---------|
+| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
+| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
+| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
+| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
+
+### Hierarchy
+
+```
+Schema (defines) ──→ Artifacts (guided by) ──→ Templates
+```
+
+- **Schema** = the artifact graph (what exists, dependencies)
+- **Artifact** = a document to produce
+- **Template** = instructions for creating that artifact
+
+### Schema Variations
+
+Schemas can vary across multiple dimensions:
+
+| Dimension | Examples |
+|-----------|----------|
+| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
+| Version | `v1`, `v2`, `v3` |
+| Language | `en`, `zh`, `es` |
+| Custom | `team-alpha`, `experimental` |
+
+### Schema Resolution (XDG Standard)
+
+Schemas follow the XDG Base Directory Specification with a 2-level resolution:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # Global user override
+2. <package>/schemas/<name>/schema.yaml                    # Built-in defaults
+```
+
+**Platform-specific paths:**
+- Unix/macOS: `~/.local/share/openspec/schemas/`
+- Windows: `%LOCALAPPDATA%/openspec/schemas/`
+- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set)
+
+**Why XDG?**
+- Schemas are workflow definitions (data), not user preferences (config)
+- Built-ins baked into package, never auto-copied
+- Users customize by creating files in global data dir
+- Consistent with modern CLI tooling standards
+
+### Template Inheritance (2 Levels Max)
+
+Templates are co-located with schemas in a `templates/` subdirectory:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+2. <package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+```
+
+**Rules:**
+- User overrides take precedence over package built-ins
+- A CLI command shows resolved paths (no guessing)
+- No inheritance between schemas (copy if you need to diverge)
+- Templates are always co-located with their schema
+
+**Why this matters:**
+- Avoids "where does this come from?" debugging
+- No implicit magic that works until it doesn't
+- Schema + templates form a cohesive unit
+
+---
+
+## Executive Summary
+
+This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+
+The system answers:
+- "What artifacts exist for this change?"
+- "What could I create next?" (not "what must I create")
+- "What's blocking X?" (informational, not prescriptive)
+
+---
+
+## Core Components
+
+### 1. ArtifactGraph (Slice 1 - COMPLETE)
+
+The dependency graph engine with XDG-compliant schema resolution.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Model artifacts as a DAG | Artifact with `requires: string[]` |
+| Track completion state | `Set<string>` for completed artifacts |
+| Calculate build order | Kahn's algorithm (topological sort) |
+| Find ready artifacts | Check if all dependencies are in `completed` set |
+| Resolve schemas | XDG global → package built-ins |
+
+**Key Data Structures (Zod-validated):**
+
+```typescript
+// Zod schemas define types + validation
+const ArtifactSchema = z.object({
+  id: z.string().min(1),
+  generates: z.string().min(1),      // e.g., "proposal.md" or "specs/*.md"
+  description: z.string(),
+  template: z.string(),              // path to template file
+  requires: z.array(z.string()).default([]),
+});
+
+const SchemaYamlSchema = z.object({
+  name: z.string().min(1),
+  version: z.number().int().positive(),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1),
+});
+
+// Derived types
+type Artifact = z.infer<typeof ArtifactSchema>;
+type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+```
+
+**Key Methods:**
+- `resolveSchema(name)` - Load schema with XDG fallback
+- `ArtifactGraph.fromSchema(schema)` - Build graph from schema
+- `detectState(graph, changeDir)` - Scan filesystem for completion
+- `getNextArtifacts(graph, completed)` - Find artifacts ready to create
+- `getBuildOrder(graph)` - Topological sort of all artifacts
+- `getBlocked(graph, completed)` - Artifacts with unmet dependencies
+
+---
+
+### 2. Change Utilities (Slice 2)
+
+Simple utility functions for programmatic change creation. No class, no abstraction layer.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Create changes | Create dirs under `openspec/changes/<name>/` with README |
+| Name validation | Enforce kebab-case naming |
+
+**Key Paths:**
+
+```
+openspec/changes/<name>/   → Change instances with artifacts (project-level)
+```
+
+**Key Functions** (`src/utils/change-utils.ts`):
+- `createChange(projectRoot, name, description?)` - Create new change directory + README
+- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }`
+
+**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is.
+
+---
+
+### 3. InstructionLoader (Slice 3)
+
+Template resolution and instruction enrichment.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) |
+| Build dynamic context | Gather dependency status, change info |
+| Enrich templates | Inject context into base templates |
+| Generate status reports | Formatted markdown with progress |
+
+**Key Class - ChangeState:**
+
+```
+ChangeState {
+  changeName: string
+  changeDir: string
+  graph: ArtifactGraph
+  completed: Set<string>
+
+  // Methods
+  getNextSteps(): string[]
+  getStatus(artifactId): ArtifactStatus
+  isComplete(): boolean
+}
+```
+
+**Key Functions:**
+- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
+- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
+
+---
+
+### 4. CLI (Slice 4)
+
+User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
+
+| Command | Function | Status |
+|---------|----------|--------|
+| `status --change <id>` | Show change progress (artifact graph) | **NEW** |
+| `next --change <id>` | Show artifacts ready to create | **NEW** |
+| `instructions <artifact> --change <id>` | Get enriched instructions for artifact | **NEW** |
+| `list` | List all changes | EXISTS (`openspec change list`) |
+| `new <name>` | Create change | **NEW** (uses `createChange()`) |
+| `init` | Initialize structure | EXISTS (`openspec init`) |
+| `templates --change <id>` | Show resolved template paths | **NEW** |
+
+**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
+
+**Existing CLI commands** (not part of this slice):
+- `openspec change list` / `openspec change show <id>` / `openspec change validate <id>`
+- `openspec list --changes` / `openspec list --specs`
+- `openspec view` (dashboard)
+- `openspec init` / `openspec archive <change>`
+
+---
+
+### 5. Claude Commands
+
+Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
+
+| Command | Purpose |
+|---------|---------|
+| `/status` | Show change progress |
+| `/next` | Show what's ready to create |
+| `/run [artifact]` | Execute a specific step (power users) |
+| `/list` | List all changes |
+| `/new <name>` | Create a new change |
+| `/init` | Initialize structure |
+
+**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
+1. Infers change from conversation (confirms if uncertain)
+2. Infers artifact from request
+3. Calls CLI with explicit `--change` parameter
+4. Creates artifact following instructions
+
+This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
+
+**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
+
+---
+
+## Component Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PRESENTATION LAYER                       │
+│  ┌──────────────┐                    ┌────────────────────┐ │
+│  │     CLI      │ ←─shell exec───────│ Claude Commands    │ │
+│  └──────┬───────┘                    └────────────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+          │ imports
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    ORCHESTRATION LAYER                       │
+│  ┌────────────────────┐        ┌──────────────────────────┐ │
+│  │ InstructionLoader  │        │  change-utils (Slice 2)  │ │
+│  │    (Slice 3)       │        │  createChange()          │ │
+│  └─────────┬──────────┘        │  validateChangeName()    │ │
+│            │                   └──────────────────────────┘ │
+└────────────┼────────────────────────────────────────────────┘
+             │ uses
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CORE LAYER                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │               ArtifactGraph (Slice 1)                │   │
+│  │                                                      │   │
+│  │  Schema Resolution (XDG) ──→ Graph ──→ State Detection│   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+             ▲
+             │ reads from
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   PERSISTENCE LAYER                          │
+│  ┌──────────────────┐   ┌────────────────────────────────┐  │
+│  │  XDG Schemas     │   │  Project Artifacts             │  │
+│  │  ~/.local/share/ │   │  openspec/changes/<name>/      │  │
+│  │  openspec/       │   │  - proposal.md, design.md      │  │
+│  │  schemas/        │   │  - specs/*.md, tasks.md        │  │
+│  └──────────────────┘   └────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Design Patterns
+
+### 1. Filesystem as Database
+
+No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
+
+```
+// State detection is just file existence checking
+if (exists(artifactPath)) {
+  completed.add(artifactId)
+}
+```
+
+### 2. Deterministic CLI, Inferring Agent
+
+**CLI layer:** Always deterministic - requires explicit `--change` parameter.
+
+```
+openspec status --change add-auth     # explicit, works
+openspec status                        # error: "No change specified"
+```
+
+**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
+
+This separation means:
+- CLI is pure, testable, no state to corrupt
+- Agent handles all "smartness"
+- No config.yaml tracking of "active change"
+
+### 3. XDG-Compliant Schema Resolution
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
+    ↓ (not found)
+<package>/schemas/<name>/schema.yaml                    # Built-in
+    ↓ (not found)
+Error (schema not found)
+```
+
+### 4. Two-Level Template Fallback
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+    ↓ (not found)
+<package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+    ↓ (not found)
+Error (no silent fallback to avoid confusion)
+```
+
+### 5. Glob Pattern Support
+
+`specs/*.md` allows multiple files to satisfy a single artifact:
+
+```
+if (artifact.generates.includes("*")) {
+  const parentDir = changeDir / patternParts[0]
+  if (exists(parentDir) && hasFiles(parentDir)) {
+    completed.add(artifactId)
+  }
+}
+```
+
+### 6. Stateless State Detection
+
+Every command re-scans the filesystem. No cached state to corrupt.
+
+---
+
+## Artifact Pipeline (Default Schema)
+
+The default `spec-driven` schema:
+
+```
+┌──────────┐
+│ proposal │  (no dependencies)
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  specs   │  (requires: proposal)
+└────┬─────┘
+     │
+     ├──────────────┐
+     ▼              ▼
+┌──────────┐   ┌──────────┐
+│  design  │   │          │
+│          │◄──┤ proposal │
+└────┬─────┘   └──────────┘
+     │         (requires: proposal, specs)
+     ▼
+┌──────────┐
+│  tasks   │  (requires: design)
+└──────────┘
+```
+
+Other schemas (TDD, prototype-first) would have different graphs.
+
+---
+
+## Implementation Order
+
+Structured as **vertical slices** - each slice is independently testable.
+
+---
+
+### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE
+
+**Delivers:** Types + Graph + State Detection + Schema Resolution
+
+**Implementation:** `src/core/artifact-graph/`
+- `types.ts` - Zod schemas and derived TypeScript types
+- `schema.ts` - YAML parsing with Zod validation
+- `graph.ts` - ArtifactGraph class with topological sort
+- `state.ts` - Filesystem-based state detection
+- `resolver.ts` - XDG-compliant schema resolution
+- `builtin-schemas.ts` - Package-bundled default schemas
+
+**Key decisions made:**
+- Zod for schema validation (consistent with project)
+- XDG for global schema overrides
+- `Set<string>` for completion state (immutable, functional)
+- `inProgress` and `failed` states deferred (require external tracking)
+
+---
+
+### Slice 2: "Change Creation Utilities"
+
+**Delivers:** Utility functions for programmatic change creation
+
+**Scope:**
+- `createChange(projectRoot, name, description?)` → creates directory + README
+- `validateChangeName(name)` → kebab-case pattern enforcement
+
+**Not in scope (already exists in CLI commands):**
+- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()`
+- `getChangePath()` → simple `path.join()` inline
+- `changeExists()` → simple `fs.access()` inline
+- `isInitialized()` → simple directory check inline
+
+**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation.
+
+---
+
+### Slice 3: "Get Instructions" (Enrichment)
+
+**Delivers:** Template resolution + context injection
+
+**Testable behaviors:**
+- Template fallback: schema-specific → shared → built-in → error
+- Context injection: completed deps show ✓, missing show ✗
+- Output path shown correctly based on change directory
+
+---
+
+### Slice 4: "CLI + Integration"
+
+**Delivers:** New artifact graph commands (builds on existing CLI)
+
+**New commands:**
+- `status --change <id>` - Show artifact completion state
+- `next --change <id>` - Show ready-to-create artifacts
+- `instructions <artifact> --change <id>` - Get enriched template
+- `templates --change <id>` - Show resolved paths
+- `new <name>` - Create change (wrapper for `createChange()`)
+
+**Already exists (not in scope):**
+- `openspec change list/show/validate` - change management
+- `openspec list --changes/--specs` - listing
+- `openspec view` - dashboard
+- `openspec init` - initialization
+
+**Testable behaviors:**
+- Each new command produces expected output
+- Commands compose correctly (status → next → instructions flow)
+- Error handling for missing changes, invalid artifacts, etc.
+
+---
+
+## Directory Structure
+
+```
+# Global (XDG paths - user overrides)
+~/.local/share/openspec/           # Unix/macOS ($XDG_DATA_HOME/openspec/)
+%LOCALAPPDATA%/openspec/           # Windows
+└── schemas/                       # Schema overrides
+    └── custom-workflow/           # User-defined schema directory
+        ├── schema.yaml            # Schema definition
+        └── templates/             # Co-located templates
+            └── proposal.md
+
+# Package (built-in defaults)
+<package>/
+└── schemas/                       # Built-in schema definitions
+    ├── spec-driven/               # Default: proposal → specs → design → tasks
+    │   ├── schema.yaml
+    │   └── templates/
+    │       ├── proposal.md
+    │       ├── design.md
+    │       ├── spec.md
+    │       └── tasks.md
+    └── tdd/                       # TDD: tests → implementation → docs
+        ├── schema.yaml
+        └── templates/
+            ├── test.md
+            ├── implementation.md
+            ├── spec.md
+            └── docs.md
+
+# Project (change instances)
+openspec/
+└── changes/                       # Change instances
+    ├── add-auth/
+    │   ├── README.md              # Auto-generated on creation
+    │   ├── proposal.md            # Created artifacts
+    │   ├── design.md
+    │   └── specs/
+    │       └── *.md
+    ├── refactor-db/
+    │   └── ...
+    └── archive/                   # Completed changes
+        └── 2025-01-01-add-auth/
+
+.claude/
+├── settings.local.json            # Permissions
+└── commands/                      # Slash commands
+    └── *.md
+```
+
+---
+
+## Schema YAML Format
+
+```yaml
+# Built-in: <package>/schemas/spec-driven/schema.yaml
+# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
+name: spec-driven
+version: 1
+description: Specification-driven development
+
+artifacts:
+  - id: proposal
+    generates: "proposal.md"
+    description: "Create project proposal document"
+    template: "proposal.md"          # resolves from co-located templates/ directory
+    requires: []
+
+  - id: specs
+    generates: "specs/*.md"          # glob pattern
+    description: "Create technical specification documents"
+    template: "specs.md"
+    requires:
+      - proposal
+
+  - id: design
+    generates: "design.md"
+    description: "Create design document"
+    template: "design.md"
+    requires:
+      - proposal
+      - specs
+
+  - id: tasks
+    generates: "tasks.md"
+    description: "Create tasks breakdown document"
+    template: "tasks.md"
+    requires:
+      - design
+```
+
+---
+
+## Summary
+
+| Layer | Component | Responsibility | Status |
+|-------|-----------|----------------|--------|
+| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
+| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
+| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
+| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
+| Integration | Claude Commands | AI assistant glue | Slice 4 |
+
+**What already exists (not in this proposal):**
+- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
+- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
+- `ListCommand.execute()` in `src/core/list.ts`
+- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
+- `src/core/init.ts` - initialization
+- `src/core/archive.ts` - archiving
+
+**Key Principles:**
+- **Filesystem IS the database** - stateless, version-control friendly
+- **Dependencies are enablers** - show what's possible, don't force order
+- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
+- **XDG-compliant paths** - schemas and templates use standard user data directories
+- **2-level inheritance** - user override → package built-in (no deeper)
+- **Schemas are versioned** - support variations by philosophy, version, language
@@ -0,0 +1,42 @@
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+  {
+    files: ['src/**/*.ts'],
+    extends: [...tseslint.configs.recommended],
+    rules: {
+      // Prevent static imports of @inquirer modules to avoid pre-commit hook hangs.
+      // These modules have side effects that can keep the Node.js event loop alive
+      // when stdin is piped. Use dynamic import() instead.
+      // See: https://github.com/Fission-AI/OpenSpec/issues/367
+      'no-restricted-imports': [
+        'error',
+        {
+          patterns: [
+            {
+              group: ['@inquirer/*'],
+              message:
+                'Use dynamic import() for @inquirer modules to prevent pre-commit hook hangs. See #367.',
+            },
+          ],
+        },
+      ],
+      // Disable rules that need broader cleanup - focus on critical issues only
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/no-unused-vars': 'off',
+      'no-empty': 'off',
+      'prefer-const': 'off',
+    },
+  },
+  {
+    // init.ts is dynamically imported from cli/index.ts, so static @inquirer
+    // imports there are safe - they won't be loaded at CLI startup
+    files: ['src/core/init.ts'],
+    rules: {
+      'no-restricted-imports': 'off',
+    },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', '*.js', '*.mjs'],
+  }
+);
@@ -0,0 +1,525 @@
+# Shell Completions Design
+
+## Overview
+
+This design establishes a plugin-based architecture for shell completions that prioritizes clean TypeScript patterns, scalability, and maintainability. The system separates concerns between shell-specific generation logic, dynamic completion data providers, and installation automation.
+
+**Scope:** This proposal implements **Zsh completion only** (with Oh My Zsh priority). The architecture is designed to support bash, fish, and PowerShell in future proposals.
+
+## Native Shell Completion Behaviors
+
+**Design Philosophy:** We integrate with each shell's native completion system rather than attempting to customize or unify behaviors. This ensures familiar UX for users and reduces maintenance complexity.
+
+**Note:** While all four shell behaviors are documented below for architectural reference, **only Zsh is implemented in this proposal**. Bash, Fish, and PowerShell are documented to guide future implementations.
+
+### Bash Completion Behavior
+
+**Interaction Pattern:**
+- **Single TAB:** Completes if only one match exists, otherwise does nothing
+- **Double TAB (TAB TAB):** Displays all possible completions as a list
+- **Type more characters + TAB:** Narrows matches and completes or shows refined list
+
+**OpenSpec Integration:**
+```bash
+# After installing: openspec completion install bash
+openspec val<TAB>           # Completes to "openspec validate"
+openspec validate <TAB><TAB>  # Shows: --all --changes --specs --strict --json [change-ids] [spec-ids]
+openspec show add-<TAB><TAB>  # Shows all changes starting with "add-"
+```
+
+**Implementation:** Uses bash-completion framework with `_init_completion`, `compgen`, and `COMPREPLY` array.
+
+### Zsh Completion Behavior (with Oh My Zsh)
+
+**Interaction Pattern:**
+- **Single TAB:** Shows interactive menu with all matches immediately
+- **TAB / Arrow Keys:** Navigate through completion options
+- **Enter:** Selects highlighted option
+- **Ctrl+C / Esc:** Cancels completion menu
+
+**OpenSpec Integration:**
+```zsh
+# After installing: openspec completion install zsh
+openspec val<TAB>    # Shows menu with "validate" and "view" highlighted
+openspec show <TAB>  # Shows menu with all change IDs and spec IDs, categorized
+```
+
+**Implementation:** Uses Zsh completion system with `_arguments`, `_describe`, and `compadd` built-ins. Oh My Zsh provides enhanced menu styling automatically.
+
+### Fish Completion Behavior
+
+**Interaction Pattern:**
+- **As-you-type:** Gray suggestions appear automatically in real-time
+- **Right Arrow / Ctrl+F:** Accepts the suggestion
+- **TAB:** Shows menu with all matches if multiple exist
+- **TAB again:** Cycles through options or navigates menu
+- **Enter:** Accepts current selection
+
+**OpenSpec Integration:**
+```fish
+# After installing: openspec completion install fish
+openspec val       # Gray suggestion shows "validate" immediately
+openspec show a    # Real-time suggestions for changes starting with "a"
+openspec <TAB>     # Shows all commands with descriptions in paged menu
+```
+
+**Implementation:** Uses Fish's declarative `complete -c` syntax. Completions are auto-loaded from `~/.config/fish/completions/`.
+
+### PowerShell Completion Behavior
+
+**Interaction Pattern:**
+- **TAB:** Cycles forward through completions one at a time (inline replacement)
+- **Shift+TAB:** Cycles backward through completions
+- **Ctrl+Space:** Shows IntelliSense-style menu (PSReadLine v2.2+)
+- **Arrow Keys:** Navigate menu if shown
+
+**OpenSpec Integration:**
+```powershell
+# After installing: openspec completion install powershell
+openspec val<TAB>       # Cycles: validate → view → validate
+openspec show <TAB>     # Cycles through change IDs one by one
+openspec <Ctrl+Space>   # Shows IntelliSense menu with all commands
+```
+
+**Implementation:** Uses `Register-ArgumentCompleter` with custom script block that returns `[System.Management.Automation.CompletionResult]` objects.
+
+### Comparison Table
+
+| Shell       | Trigger         | Display Style          | Navigation           | Selection      |
+|-------------|-----------------|------------------------|----------------------|----------------|
+| Bash        | TAB TAB         | List (printed once)    | Type more + TAB      | Auto-complete  |
+| Zsh         | TAB             | Interactive menu       | TAB/Arrows           | Enter          |
+| Fish        | TAB/Auto        | Real-time + menu       | TAB/Arrows           | Enter/Right    |
+| PowerShell  | TAB             | Inline cycling         | TAB/Shift+TAB        | Stop cycling   |
+
+**Key Insight:** Each shell's completion UX reflects its design philosophy. We respect these conventions rather than forcing uniformity.
+
+## Architectural Principles
+
+### 1. Plugin-Based Generator System
+
+Each shell has unique completion syntax and conventions. Rather than creating a monolithic generator with branching logic, we use a plugin pattern where each shell implements a common interface:
+
+```typescript
+interface CompletionGenerator {
+  generate(): string;
+  getInstallPath(): string;
+  getConfigFile(): string;
+}
+```
+
+**Benefits:**
+- New shells can be added without modifying existing generators
+- Shell-specific logic is isolated and testable
+- Type safety ensures all generators implement required methods
+- Easy to maintain and understand (single responsibility per generator)
+
+**Implementation Classes:**
+- `ZshCompletionGenerator` - Uses Zsh's `_arguments` and `_describe` functions
+- `BashCompletionGenerator` - Uses `_init_completion` and `compgen` built-ins
+- `FishCompletionGenerator` - Uses `complete -c` declarative syntax
+- `PowerShellCompletionGenerator` - Uses `Register-ArgumentCompleter` cmdlet
+
+### 2. Centralized Command Registry
+
+Shell completions must stay synchronized with actual CLI commands. To avoid duplication and drift, we maintain a single source of truth:
+
+```typescript
+type CommandDefinition = {
+  name: string;
+  description: string;
+  flags: FlagDefinition[];
+  acceptsChangeId: boolean;
+  acceptsSpecId: boolean;
+  subcommands?: CommandDefinition[];
+};
+
+const COMMAND_REGISTRY: CommandDefinition[] = [
+  {
+    name: 'init',
+    description: 'Initialize OpenSpec in your project',
+    flags: [
+      { name: '--tools', description: 'Configure AI tools non-interactively', hasValue: true }
+    ],
+    acceptsChangeId: false,
+    acceptsSpecId: false
+  },
+  // ... all other commands
+];
+```
+
+**Benefits:**
+- All generators consume the same command definitions
+- Adding a new command automatically propagates to all shells
+- Flag changes only need to be made in one place
+- Type safety prevents typos and missing fields
+- Easier to test (mock the registry)
+
+**TypeScript Sugar:**
+- Use `const` assertions for readonly registry
+- Leverage discriminated unions for command types
+- Use `satisfies` operator to ensure registry matches interface
+
+### 3. Dynamic Completion Provider
+
+Change and spec IDs are project-specific and discovered at runtime. A dedicated provider encapsulates this logic:
+
+```typescript
+class CompletionProvider {
+  private changeCache: { ids: string[]; timestamp: number } | null = null;
+  private specCache: { ids: string[]; timestamp: number } | null = null;
+  private readonly CACHE_TTL_MS = 2000;
+
+  async getChangeIds(): Promise<string[]> {
+    if (this.changeCache && Date.now() - this.changeCache.timestamp < this.CACHE_TTL_MS) {
+      return this.changeCache.ids;
+    }
+
+    const ids = await discoverActiveChangeIds();
+    this.changeCache = { ids, timestamp: Date.now() };
+    return ids;
+  }
+
+  async getSpecIds(): Promise<string[]> {
+    // Similar caching logic
+  }
+
+  isOpenSpecProject(): boolean {
+    // Check for openspec/ directory
+  }
+}
+```
+
+**Benefits:**
+- Caching reduces file system overhead during rapid tab completion
+- Encapsulates project detection logic
+- Easy to test with mocked file system
+- Shared across all shell generators
+
+**Design Decisions:**
+- 2-second cache TTL balances freshness with performance
+- Cache per-process (not persistent) to avoid stale data across sessions
+- Graceful degradation when outside OpenSpec projects
+
+### 4. Separate Installation Logic
+
+Installation involves shell configuration file manipulation, which differs from generation. We separate this concern:
+
+```typescript
+interface CompletionInstaller {
+  install(): Promise<InstallResult>;
+  uninstall(): Promise<UninstallResult>;
+  isInstalled(): Promise<boolean>;
+}
+```
+
+**Shell-Specific Installers:**
+- `ZshInstaller` - Handles both Oh My Zsh (custom completions) and standard Zsh (fpath)
+- `BashInstaller` - Detects completion directories and sources from `.bashrc`
+- `FishInstaller` - Writes to `~/.config/fish/completions/` (auto-loaded)
+- `PowerShellInstaller` - Appends to PowerShell profile
+
+**Benefits:**
+- Installation logic doesn't pollute generator code
+- Can test installation without generating completion scripts
+- Easier to handle edge cases (missing directories, permissions, already installed)
+
+### 5. Type-Safe Shell Detection
+
+We use TypeScript's literal types and type guards for shell detection:
+
+```typescript
+type SupportedShell = 'bash' | 'zsh' | 'fish' | 'powershell';
+
+function detectShell(): SupportedShell {
+  const shellPath = process.env.SHELL || '';
+  const shellName = path.basename(shellPath).toLowerCase();
+
+  // PowerShell normalization
+  if (shellName === 'pwsh' || shellName === 'powershell') {
+    return 'powershell';
+  }
+
+  const supported: SupportedShell[] = ['bash', 'zsh', 'fish', 'powershell'];
+  if (supported.includes(shellName as SupportedShell)) {
+    return shellName as SupportedShell;
+  }
+
+  throw new Error(`Shell '${shellName}' is not supported. Supported: ${supported.join(', ')}`);
+}
+```
+
+**Benefits:**
+- Compile-time type checking prevents invalid shell names
+- Easy to add new shells (add to union type)
+- Type narrowing works in switch statements
+- Clear error messages for unsupported shells
+
+### 6. Factory Pattern for Instantiation
+
+A factory function selects the appropriate generator/installer based on shell type:
+
+```typescript
+function createGenerator(shell: SupportedShell, provider: CompletionProvider): CompletionGenerator {
+  switch (shell) {
+    case 'bash': return new BashCompletionGenerator(COMMAND_REGISTRY, provider);
+    case 'zsh': return new ZshCompletionGenerator(COMMAND_REGISTRY, provider);
+    case 'fish': return new FishCompletionGenerator(COMMAND_REGISTRY, provider);
+    case 'powershell': return new PowerShellCompletionGenerator(COMMAND_REGISTRY, provider);
+  }
+}
+```
+
+**Benefits:**
+- Single point of instantiation
+- Type safety ensures exhaustive switch (TypeScript error if shell type missing)
+- Easy to inject dependencies (registry, provider)
+
+## Command Structure
+
+**This Proposal (Zsh-only):**
+```
+openspec completion
+├── zsh               # Generate Zsh completion script
+├── install [shell]   # Install Zsh completion (auto-detects or explicit zsh)
+└── uninstall [shell] # Remove Zsh completion (auto-detects or explicit zsh)
+```
+
+**Future (after follow-up proposals):**
+```
+openspec completion
+├── bash              # Generate Bash completion script (future)
+├── zsh               # Generate Zsh completion script (this proposal)
+├── fish              # Generate Fish completion script (future)
+├── powershell        # Generate PowerShell completion script (future)
+├── install [shell]   # Install completion (auto-detects or explicit shell)
+└── uninstall [shell] # Remove completion (auto-detects or explicit shell)
+```
+
+## File Organization
+
+**This Proposal (Zsh-only):**
+```
+src/
+├── commands/
+│   └── completion.ts              # CLI command registration (zsh, install, uninstall)
+├── core/
+│   └── completions/
+│       ├── types.ts               # Interfaces: CompletionGenerator, CommandDefinition, etc.
+│       ├── command-registry.ts    # Single source of truth for OpenSpec commands
+│       ├── completion-provider.ts # Dynamic change/spec ID discovery with caching
+│       ├── factory.ts             # Factory for instantiating Zsh generator/installer
+│       ├── generators/
+│       │   └── zsh-generator.ts   # Zsh completion script generator
+│       └── installers/
+│           └── zsh-installer.ts   # Handles Oh My Zsh + standard Zsh installation
+└── utils/
+    └── shell-detection.ts         # Shell detection (returns 'zsh' or throws)
+```
+
+**Future additions (bash, fish, powershell):**
+- `generators/bash-generator.ts`, `fish-generator.ts`, `powershell-generator.ts`
+- `installers/bash-installer.ts`, `fish-installer.ts`, `powershell-installer.ts`
+- Update `shell-detection.ts` to support additional shell types
+
+## Oh My Zsh Priority
+
+Zsh implementation prioritizes Oh My Zsh because:
+1. **Popularity** - Oh My Zsh is the most popular Zsh configuration framework
+2. **Convention** - Has standard completion directory (`~/.oh-my-zsh/custom/completions/`)
+3. **Detection** - Easy to detect via `$ZSH` environment variable
+4. **Fallback** - Standard Zsh support provides compatibility when Oh My Zsh isn't installed
+
+**Installation Strategy:**
+```typescript
+if (isOhMyZshInstalled()) {
+  // Install to ~/.oh-my-zsh/custom/completions/_openspec
+  // Automatically loaded by Oh My Zsh
+} else {
+  // Install to ~/.zsh/completions/_openspec
+  // Update ~/.zshrc with fpath and compinit if needed
+}
+```
+
+## Caching Strategy
+
+Dynamic completions cache results for 2 seconds to balance freshness with performance:
+
+**Why 2 seconds?**
+- Typical tab completion sessions last < 2 seconds
+- Prevents repeated file system scans during rapid tabbing
+- Short enough to feel "live" when changes/specs are added
+- Automatic per-process expiration (no stale data across sessions)
+
+**Implementation:**
+```typescript
+private changeCache: { ids: string[]; timestamp: number } | null = null;
+private readonly CACHE_TTL_MS = 2000;
+
+if (this.changeCache && Date.now() - this.changeCache.timestamp < this.CACHE_TTL_MS) {
+  return this.changeCache.ids; // Use cached
+}
+// Refresh cache
+```
+
+## Error Handling Philosophy
+
+Completions should degrade gracefully rather than break workflows:
+
+1. **Unsupported shell** - Clear error with list of supported shells
+2. **Not in OpenSpec project** - Skip dynamic completions, only offer static commands
+3. **Permission errors** - Suggest alternative installation methods
+4. **Missing config directories** - Auto-create with user notification
+5. **Already installed** - Offer to reinstall/update
+6. **Not installed (during uninstall)** - Exit gracefully with informational message
+
+## Testing Strategy
+
+Each component is independently testable:
+
+1. **Unit Tests**
+   - Shell detection with mocked `$SHELL` environment variable
+   - Generator output verification (regex pattern matching)
+   - Completion provider caching behavior
+   - Command registry structure validation
+
+2. **Integration Tests**
+   - Installation to temporary test directories
+   - Configuration file modifications
+   - End-to-end command flow (generate → install → verify)
+
+3. **Manual Testing**
+   - Real shell environments (Oh My Zsh, Bash, Fish, PowerShell)
+   - Tab completion behavior in OpenSpec projects
+   - Dynamic change/spec ID suggestions
+   - Installation/uninstallation workflows
+
+## TypeScript Sugar Patterns
+
+### 1. Const Assertions for Immutable Data
+```typescript
+const COMMAND_REGISTRY = [
+  { name: 'init', ... },
+  { name: 'list', ... }
+] as const;
+```
+
+### 2. Discriminated Unions for Command Types
+```typescript
+type Command =
+  | { type: 'simple'; name: string }
+  | { type: 'with-subcommands'; name: string; subcommands: Command[] };
+```
+
+### 3. Template Literal Types for Strings
+```typescript
+type ShellConfigFile = `~/.${SupportedShell}rc` | `~/.${SupportedShell}_profile`;
+```
+
+### 4. Satisfies Operator for Type Validation
+```typescript
+const config = {
+  shell: 'zsh',
+  path: '~/.zshrc'
+} satisfies ShellConfig;
+```
+
+### 5. Optional Chaining and Nullish Coalescing
+```typescript
+const path = process.env.ZSH ?? `${os.homedir()}/.oh-my-zsh`;
+```
+
+### 6. Async/Await with Promise.all for Parallel Operations
+```typescript
+const [changes, specs] = await Promise.all([
+  provider.getChangeIds(),
+  provider.getSpecIds()
+]);
+```
+
+## Scalability Considerations
+
+### Adding a New Shell
+
+1. Define shell in `SupportedShell` union type
+2. Create generator class implementing `CompletionGenerator`
+3. Create installer class implementing `CompletionInstaller`
+4. Add cases to factory functions
+5. Add command registration in CLI
+6. Write tests
+
+**TypeScript will enforce** that all switch statements are updated (exhaustiveness checking).
+
+### Adding a New Command
+
+1. Add to `COMMAND_REGISTRY` with appropriate metadata
+2. All generators automatically include it
+3. Update tests to verify new command appears
+
+### Changing Completion Behavior
+
+Dynamic completion logic is centralized in `CompletionProvider`, making behavior changes trivial without touching shell-specific code.
+
+## Trade-offs and Decisions
+
+### Decision: Separate Generators vs. Template Engine
+
+**Chosen:** Separate generator classes per shell
+
+**Alternative:** Template engine with shell-specific templates
+
+**Rationale:**
+- Shell completion syntax is fundamentally different (not just text substitution)
+- Type safety is better with classes than templates
+- Logic complexity (caching, dynamic completions) doesn't fit template paradigm
+- Easier to debug and test dedicated classes
+
+### Decision: 2-Second Cache TTL
+
+**Chosen:** 2-second cache
+
+**Alternatives:** No cache (slow), longer cache (stale), persistent cache (complex)
+
+**Rationale:**
+- Balances performance with freshness
+- Matches typical user interaction patterns
+- Simple implementation (no invalidation complexity)
+- Automatic cleanup on process exit
+
+### Decision: Oh My Zsh Detection
+
+**Chosen:** Check `$ZSH` env var first, then `~/.oh-my-zsh/` directory
+
+**Rationale:**
+- `$ZSH` is set by Oh My Zsh initialization (reliable)
+- Directory check is fallback for non-interactive scenarios
+- Standard Zsh serves as ultimate fallback
+
+### Decision: Installation Automation vs. Manual Instructions
+
+**Chosen:** Automated installation with install/uninstall commands
+
+**Alternative:** Generate script and provide manual installation instructions
+
+**Rationale:**
+- Better user experience (one command vs. multiple manual steps)
+- Reduces errors from manual configuration
+- Aligns with user expectations for modern CLI tools
+- Still supports manual workflow via script generation to stdout
+
+## Future Enhancements
+
+1. **Contextual Flag Completion** - Suggest only valid flags for current command
+2. **Fuzzy Matching** - Allow partial matching for change/spec IDs
+3. **Rich Descriptions** - Include "why" section in completion suggestions (shell-dependent)
+4. **Completion Stats** - Track completion usage for analytics
+5. **Custom Completion Hooks** - Allow projects to extend completions
+6. **MCP Integration** - Provide completions via Model Context Protocol
+
+## References
+
+- [Bash Programmable Completion](https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html)
+- [Zsh Completion System](https://zsh.sourceforge.io/Doc/Release/Completion-System.html)
+- [Fish Completions](https://fishshell.com/docs/current/completions.html)
+- [PowerShell Argument Completers](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/register-argumentcompleter)
+- [Oh My Zsh Custom Completions](https://github.com/ohmyzsh/ohmyzsh/wiki/Customization#adding-custom-completions)
@@ -0,0 +1,29 @@
+# Add Shell Completions
+
+## Why
+
+OpenSpec CLI commands lack shell completion, forcing users to remember all commands, subcommands, flags, and change/spec IDs manually. This creates friction during daily use and slows developer workflows. Shell completions are a standard expectation for modern CLI tools and significantly improve user experience through:
+- Faster command discovery via tab completion
+- Reduced cognitive load by removing memorization requirements
+- Fewer typos through validated suggestions
+- Professional polish expected of production-grade tools
+
+## What Changes
+
+This change adds shell completion support for the OpenSpec CLI, starting with **Zsh (including Oh My Zsh)** and establishing a scalable architecture for future shells (bash, fish, PowerShell). The implementation provides:
+
+1. **New `openspec completion` command** with Zsh generation and installation/uninstallation capabilities
+2. **Native Zsh integration** that respects standard Zsh tab completion behavior (single-TAB menu navigation)
+3. **Dynamic completion providers** that discover active changes and specs from the current project
+4. **Plugin-based architecture** using TypeScript interfaces for easy extension to additional shells in future proposals
+5. **Installation automation** for Oh My Zsh (priority) and standard Zsh configurations
+6. **Context-aware suggestions** that only activate within OpenSpec-enabled projects
+
+The architecture emphasizes clean TypeScript patterns, composable generators, separation of concerns between shell-specific logic and shared completion data providers, and integration with native shell completion systems. Other shells (bash, fish, PowerShell) are architecturally documented but not implemented in this proposal—they will be added in follow-up changes.
+
+## Deltas
+
+### Delta: New CLI completion specification
+- **Spec:** cli-completion
+- **Operation:** ADDED
+- **Description:** Defines requirements for the new `openspec completion` command including generation, installation, and shell-specific behaviors for Oh My Zsh, bash, fish, and PowerShell.
@@ -0,0 +1,300 @@
+# CLI Completion Specification
+
+## Purpose
+
+The `openspec completion` command SHALL provide shell completion functionality for all OpenSpec CLI commands, flags, and dynamic values (change IDs, spec IDs), with support for Zsh (including Oh My Zsh) and a scalable architecture ready for future shells (bash, fish, PowerShell). The completion system SHALL integrate with Zsh's native completion behavior rather than attempting to customize the user experience.
+
+## ADDED Requirements
+
+### Requirement: Native Shell Behavior Integration
+
+The completion system SHALL respect and integrate with Zsh's native completion patterns and user interaction model.
+
+#### Scenario: Zsh native completion
+
+- **WHEN** generating Zsh completion scripts
+- **THEN** use Zsh completion system with `_arguments`, `_describe`, and `compadd`
+- **AND** completions SHALL trigger on single TAB (standard Zsh behavior)
+- **AND** display as an interactive menu that users navigate with TAB/arrow keys
+- **AND** support Oh My Zsh's enhanced menu styling automatically
+
+#### Scenario: No custom UX patterns
+
+- **WHEN** implementing Zsh completion
+- **THEN** do NOT attempt to customize completion trigger behavior
+- **AND** do NOT override Zsh-specific navigation patterns
+- **AND** ensure completions feel native to experienced Zsh users
+
+### Requirement: Command Structure
+
+The completion command SHALL follow a subcommand pattern for generating and managing completion scripts.
+
+#### Scenario: Available subcommands
+
+- **WHEN** user executes `openspec completion --help`
+- **THEN** display available subcommands:
+  - `zsh` - Generate Zsh completion script
+  - `install [shell]` - Install completion for Zsh (auto-detects or requires explicit shell)
+  - `uninstall [shell]` - Remove completion for Zsh (auto-detects or requires explicit shell)
+
+### Requirement: Shell Detection
+
+The completion system SHALL automatically detect the user's current shell environment.
+
+#### Scenario: Detecting Zsh from environment
+
+- **WHEN** no shell is explicitly specified
+- **THEN** read the `$SHELL` environment variable
+- **AND** extract the shell name from the path (e.g., `/bin/zsh` → `zsh`)
+- **AND** validate the shell is `zsh`
+- **AND** throw an error if the shell is not `zsh`, with message indicating only Zsh is currently supported
+
+#### Scenario: Non-Zsh shell detection
+
+- **WHEN** shell path indicates bash, fish, powershell, or other non-Zsh shell
+- **THEN** throw error: "Shell '<name>' is not supported yet. Currently supported: zsh"
+
+### Requirement: Completion Generation
+
+The completion command SHALL generate Zsh completion scripts on demand.
+
+#### Scenario: Generating Zsh completion
+
+- **WHEN** user executes `openspec completion zsh`
+- **THEN** output a complete Zsh completion script to stdout
+- **AND** include completions for all commands: init, list, show, validate, archive, view, update, change, spec, completion
+- **AND** include all command-specific flags and options
+- **AND** use Zsh's `_arguments` and `_describe` built-in functions
+- **AND** support dynamic completion for change and spec IDs
+
+### Requirement: Dynamic Completions
+
+The completion system SHALL provide context-aware dynamic completions for project-specific values.
+
+#### Scenario: Completing change IDs
+
+- **WHEN** completing arguments for commands that accept change names (show, validate, archive)
+- **THEN** discover active changes from `openspec/changes/` directory
+- **AND** exclude archived changes in `openspec/changes/archive/`
+- **AND** return change IDs as completion suggestions
+- **AND** only provide suggestions when inside an OpenSpec-enabled project
+
+#### Scenario: Completing spec IDs
+
+- **WHEN** completing arguments for commands that accept spec names (show, validate)
+- **THEN** discover specs from `openspec/specs/` directory
+- **AND** return spec IDs as completion suggestions
+- **AND** only provide suggestions when inside an OpenSpec-enabled project
+
+#### Scenario: Completion caching
+
+- **WHEN** dynamic completions are requested
+- **THEN** cache discovered change and spec IDs for 2 seconds
+- **AND** reuse cached values for subsequent requests within cache window
+- **AND** automatically refresh cache after expiration
+
+#### Scenario: Project detection
+
+- **WHEN** user requests completions outside an OpenSpec project
+- **THEN** skip dynamic change/spec ID completions
+- **AND** only suggest static commands and flags
+
+### Requirement: Installation Automation
+
+The completion command SHALL automatically install completion scripts into shell configuration files.
+
+#### Scenario: Installing for Oh My Zsh
+
+- **WHEN** user executes `openspec completion install zsh`
+- **THEN** detect if Oh My Zsh is installed by checking for `$ZSH` environment variable or `~/.oh-my-zsh/` directory
+- **AND** create custom completions directory at `~/.oh-my-zsh/custom/completions/` if it doesn't exist
+- **AND** write completion script to `~/.oh-my-zsh/custom/completions/_openspec`
+- **AND** ensure `~/.oh-my-zsh/custom/completions` is in `$fpath` by updating `~/.zshrc` if needed
+- **AND** display success message with instruction to run `exec zsh` or restart terminal
+
+#### Scenario: Installing for standard Zsh
+
+- **WHEN** user executes `openspec completion install zsh` and Oh My Zsh is not detected
+- **THEN** create completions directory at `~/.zsh/completions/` if it doesn't exist
+- **AND** write completion script to `~/.zsh/completions/_openspec`
+- **AND** add `fpath=(~/.zsh/completions $fpath)` to `~/.zshrc` if not already present
+- **AND** add `autoload -Uz compinit && compinit` to `~/.zshrc` if not already present
+- **AND** display success message with instruction to run `exec zsh` or restart terminal
+
+#### Scenario: Auto-detecting Zsh for installation
+
+- **WHEN** user executes `openspec completion install` without specifying a shell
+- **THEN** detect current shell using shell detection logic
+- **AND** install completion if detected shell is Zsh
+- **AND** throw error if detected shell is not Zsh
+- **AND** display which shell was detected
+
+#### Scenario: Already installed
+
+- **WHEN** completion is already installed for the target shell
+- **THEN** display message indicating completion is already installed
+- **AND** offer to reinstall/update by overwriting existing files
+- **AND** exit with code 0
+
+### Requirement: Uninstallation
+
+The completion command SHALL remove installed completion scripts and configuration.
+
+#### Scenario: Uninstalling Oh My Zsh completion
+
+- **WHEN** user executes `openspec completion uninstall zsh`
+- **THEN** remove `~/.oh-my-zsh/custom/completions/_openspec` if Oh My Zsh is detected
+- **AND** remove `~/.zsh/completions/_openspec` if standard Zsh setup is detected
+- **AND** optionally remove fpath modifications from `~/.zshrc` (with confirmation)
+- **AND** display success message
+
+#### Scenario: Auto-detecting Zsh for uninstallation
+
+- **WHEN** user executes `openspec completion uninstall` without specifying a shell
+- **THEN** detect current shell and uninstall completion if shell is Zsh
+- **AND** throw error if detected shell is not Zsh
+
+#### Scenario: Not installed
+
+- **WHEN** attempting to uninstall completion that isn't installed
+- **THEN** display message indicating completion is not installed
+- **AND** exit with code 0
+
+### Requirement: Architecture Patterns
+
+The completion implementation SHALL follow clean architecture principles with TypeScript best practices.
+
+#### Scenario: Shell-specific generators
+
+- **WHEN** implementing completion generators
+- **THEN** create `ZshCompletionGenerator` class for Zsh
+- **AND** implement a common `CompletionGenerator` interface with methods:
+  - `generate(): string` - Returns complete shell script
+  - `getInstallPath(): string` - Returns target installation path
+  - `getConfigFile(): string` - Returns shell configuration file path
+- **AND** design interface to be extensible for future shells (bash, fish, powershell)
+
+#### Scenario: Dynamic completion providers
+
+- **WHEN** implementing dynamic completions
+- **THEN** create a `CompletionProvider` class that encapsulates project discovery logic
+- **AND** implement methods:
+  - `getChangeIds(): Promise<string[]>` - Discovers active change IDs
+  - `getSpecIds(): Promise<string[]>` - Discovers spec IDs
+  - `isOpenSpecProject(): boolean` - Checks if current directory is OpenSpec-enabled
+- **AND** implement caching with 2-second TTL using class properties
+
+#### Scenario: Command registry
+
+- **WHEN** defining completable commands
+- **THEN** create a centralized `CommandDefinition` type with properties:
+  - `name: string` - Command name
+  - `description: string` - Help text
+  - `flags: FlagDefinition[]` - Available flags
+  - `acceptsChangeId: boolean` - Whether command takes change ID argument
+  - `acceptsSpecId: boolean` - Whether command takes spec ID argument
+  - `subcommands?: CommandDefinition[]` - Nested subcommands
+- **AND** export a `COMMAND_REGISTRY` constant with all command definitions
+- **AND** generators consume this registry to ensure consistency
+
+#### Scenario: Type-safe shell detection
+
+- **WHEN** implementing shell detection
+- **THEN** define a `SupportedShell` type as literal type: `'zsh'`
+- **AND** implement `detectShell()` function that returns 'zsh' or throws error
+- **AND** design type to be extensible (e.g., future: `'bash' | 'zsh' | 'fish' | 'powershell'`)
+
+### Requirement: Error Handling
+
+The completion command SHALL provide clear error messages for common failure scenarios.
+
+#### Scenario: Unsupported shell
+
+- **WHEN** user requests completion for unsupported shell (bash, fish, powershell, etc.)
+- **THEN** display error message: "Shell '<name>' is not supported yet. Currently supported: zsh"
+- **AND** exit with code 1
+
+#### Scenario: Permission errors during installation
+
+- **WHEN** installation fails due to file permission issues
+- **THEN** display clear error message indicating permission problem
+- **AND** suggest using appropriate permissions or alternative installation method
+- **AND** exit with code 1
+
+#### Scenario: Missing shell configuration directory
+
+- **WHEN** expected shell configuration directory doesn't exist
+- **THEN** create the directory automatically (with user notification)
+- **AND** proceed with installation
+
+#### Scenario: Shell not detected
+
+- **WHEN** `openspec completion install` cannot detect current shell or detects non-Zsh shell
+- **THEN** display error: "Could not detect Zsh. Please specify explicitly: openspec completion install zsh"
+- **AND** exit with code 1
+
+### Requirement: Output Format
+
+The completion command SHALL provide machine-parseable and human-readable output.
+
+#### Scenario: Script generation output
+
+- **WHEN** generating completion script to stdout
+- **THEN** output only the completion script content (no extra messages)
+- **AND** allow redirection to files: `openspec completion zsh > /path/to/_openspec`
+
+#### Scenario: Installation success output
+
+- **WHEN** installation completes successfully
+- **THEN** display formatted success message with:
+  - Checkmark indicator
+  - Installation location
+  - Next steps (shell reload instructions)
+- **AND** use colors when terminal supports it (unless `--no-color` is set)
+
+#### Scenario: Verbose installation output
+
+- **WHEN** user provides `--verbose` flag during installation
+- **THEN** display detailed steps:
+  - Shell detection result
+  - Target file paths
+  - Configuration modifications
+  - File creation confirmations
+
+### Requirement: Testing Support
+
+The completion implementation SHALL be testable with unit and integration tests.
+
+#### Scenario: Mock shell environment
+
+- **WHEN** writing tests for shell detection
+- **THEN** allow overriding `$SHELL` environment variable
+- **AND** use dependency injection for file system operations
+
+#### Scenario: Generator output verification
+
+- **WHEN** testing completion generators
+- **THEN** verify generated scripts contain expected patterns
+- **AND** test that command registry is properly consumed
+- **AND** ensure dynamic completion placeholders are present
+
+#### Scenario: Installation simulation
+
+- **WHEN** testing installation logic
+- **THEN** use temporary test directories instead of actual home directories
+- **AND** verify file creation without modifying real shell configurations
+- **AND** test path resolution logic independently
+
+## Not in Scope
+
+The following shells are **architecturally documented but not implemented** in this proposal. They will be added in future proposals:
+
+- **Bash completion** - Will use bash-completion framework with `_init_completion`, `compgen`, and `COMPREPLY`
+- **Fish completion** - Will use Fish's declarative `complete -c` syntax
+- **PowerShell completion** - Will use `Register-ArgumentCompleter` with completion result objects
+
+The plugin-based architecture (CompletionGenerator interface, command registry, dynamic providers) is designed to make adding these shells straightforward in follow-up changes.
+
+## Why
+
+Shell completions are essential for professional CLI tools and significantly improve developer experience by reducing friction, errors, and cognitive load during daily workflows.
@@ -0,0 +1,81 @@
+# Implementation Tasks
+
+## Phase 1: Foundation & Architecture
+
+- [x] Create `src/utils/shell-detection.ts` with `SupportedShell` type and `detectShell()` function
+- [x] Create `src/core/completions/types.ts` with interfaces: `CompletionGenerator`, `CommandDefinition`, `FlagDefinition`
+- [x] Create `src/core/completions/command-registry.ts` with `COMMAND_REGISTRY` constant defining all OpenSpec commands, flags, and metadata
+- [x] Create `src/core/completions/completion-provider.ts` with `CompletionProvider` class for dynamic change/spec ID discovery with 2-second caching
+- [x] Write tests for shell detection (`test/utils/shell-detection.test.ts`)
+- [x] Write tests for completion provider (`test/core/completions/completion-provider.test.ts`)
+
+## Phase 2: Zsh Completion (Oh My Zsh Priority)
+
+- [x] Create `src/core/completions/generators/zsh-generator.ts` implementing `CompletionGenerator` interface
+- [x] Implement Zsh script generation using `_arguments` and `_describe` patterns
+- [x] Add dynamic completion logic for change/spec IDs using completion provider
+- [x] Test Zsh generator output (`test/core/completions/generators/zsh-generator.test.ts`)
+- [x] Create `src/core/completions/installers/zsh-installer.ts` with Oh My Zsh and standard Zsh support
+- [x] Implement Oh My Zsh detection (`$ZSH` env var or `~/.oh-my-zsh/` directory)
+- [x] Implement installation to `~/.oh-my-zsh/custom/completions/_openspec` for Oh My Zsh
+- [x] Implement fallback installation to `~/.zsh/completions/_openspec` with `fpath` updates
+- [x] Test Zsh installer logic with mocked file system (`test/core/completions/installers/zsh-installer.test.ts`)
+
+## Phase 3: CLI Command Implementation
+
+- [x] Create `src/commands/completion.ts` with `CompletionCommand` class
+- [x] Register `completion` command in `src/cli/index.ts` with subcommands: generate, install, uninstall
+- [x] Implement `generateSubcommand()` that outputs Zsh script to stdout
+- [x] Implement `installSubcommand(shell?: 'zsh')` with auto-detection for Zsh-only
+- [x] Implement `uninstallSubcommand(shell?: 'zsh')` for removing Zsh completions
+- [x] Add `--verbose` flag support for detailed installation output
+- [x] Add error handling with clear messages: "Shell '<name>' is not supported yet. Currently supported: zsh"
+- [x] Test completion command integration (`test/commands/completion.test.ts`)
+
+## Phase 4: Integration & Polish
+
+- [x] Create factory pattern in `src/core/completions/factory.ts` to instantiate Zsh generator/installer (extensible for future shells)
+- [x] Add `completion` command to command registry for self-referential completion
+- [x] Implement dynamic completion helper functions in Zsh generator (`_openspec_complete_changes`, `_openspec_complete_specs`, `_openspec_complete_items`)
+- [x] Add 'shell' positional type for completion command arguments
+- [x] Test completion generation with dynamic helpers
+- [x] Test completion install/uninstall flow
+- [x] Verify all tests pass (97 completion tests, 340 total tests)
+- [x] Implement auto-install via npm postinstall script
+- [x] Add safety checks (CI detection, opt-out flag)
+- [x] Handle Oh My Zsh vs standard Zsh installation paths
+- [x] Add test script for postinstall validation
+- [x] Document auto-install behavior and opt-out in README
+- [ ] Manually test Zsh completion in Oh My Zsh environment (install, test tab completion, uninstall)
+- [ ] Manually test Zsh completion in standard Zsh environment
+- [ ] Test dynamic change/spec ID completion in real OpenSpec projects
+- [ ] Verify completion cache behavior (2-second TTL)
+- [ ] Test behavior outside OpenSpec projects (should skip dynamic completions)
+- [x] Update `openspec --help` output to include completion command (automatically done via Commander)
+
+## Phase 5: Edge Cases & Error Handling
+
+- [ ] Test and handle permission errors during installation
+- [ ] Test and handle missing shell configuration directories (auto-create with notification)
+- [ ] Test "already installed" detection and reinstall flow
+- [ ] Test "not installed" detection during uninstall
+- [ ] Verify `--no-color` flag is respected in completion command output
+- [ ] Test shell detection failure scenarios with helpful error messages
+- [ ] Ensure graceful handling when `$SHELL` is unset or invalid
+- [ ] Test non-Zsh shells get clear "not supported yet" error messages
+- [ ] Test generator output can be redirected to files without corruption
+
+## Dependencies
+
+- Phase 2 depends on Phase 1 (foundation must exist first)
+- Phase 3 depends on Phase 2 (CLI needs Zsh generator working)
+- Phase 4 depends on Phase 3 (integration requires CLI + Zsh implementation)
+- Phase 5 depends on Phase 4 (edge case testing after core functionality works)
+
+## Future Work (Not in This Proposal)
+
+- **Bash completions** - Create bash-generator.ts and bash-installer.ts in follow-up proposal
+- **Fish completions** - Create fish-generator.ts and fish-installer.ts in follow-up proposal
+- **PowerShell completions** - Create powershell-generator.ts and powershell-installer.ts in follow-up proposal
+
+The architecture is designed to make adding these shells straightforward by implementing the `CompletionGenerator` interface.
@@ -0,0 +1,105 @@
+## Context
+
+OpenSpec needs a standard location for user-level configuration that works across platforms and follows established conventions. This will serve as the foundation for settings, feature flags, and future artifacts like workflows or templates.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide a single, well-defined location for global config
+- Follow XDG Base Directory Specification (widely adopted by CLI tools)
+- Support cross-platform usage (Unix, macOS, Windows)
+- Keep implementation minimal - just the foundation
+- Enable future expansion (cache, state, workflows)
+
+**Non-Goals:**
+- Project-local config override (not in scope)
+- Config file migration tooling
+- Config validation CLI commands
+- Multiple config profiles
+
+## Decisions
+
+### Path Resolution Strategy
+
+**Decision:** Use XDG Base Directory Specification with platform fallbacks.
+
+```
+Unix/macOS: $XDG_CONFIG_HOME/openspec/ or ~/.config/openspec/
+Windows:    %APPDATA%/openspec/
+```
+
+**Rationale:**
+- XDG is the de facto standard for CLI tools (used by gh, bat, ripgrep, etc.)
+- Environment variable override allows user customization
+- Windows uses its native convention (%APPDATA%) for better integration
+
+**Alternatives considered:**
+- `~/.openspec/` - Simple but clutters home directory
+- `~/Library/Application Support/` on macOS - Overkill for a CLI tool
+
+### Config File Format
+
+**Decision:** JSON (`config.json`)
+
+**Rationale:**
+- Native Node.js support (no dependencies)
+- Human-readable and editable
+- Type-safe with TypeScript
+- Matches project.md's "minimal dependencies" principle
+
+**Alternatives considered:**
+- YAML - Requires dependency, more error-prone to edit
+- TOML - Less common in Node.js ecosystem
+- Environment variables only - Too limited for structured settings
+
+### Config Schema
+
+**Decision:** Flat structure with typed fields, start minimal.
+
+```typescript
+interface GlobalConfig {
+  featureFlags?: Record<string, boolean>;
+}
+```
+
+**Rationale:**
+- `featureFlags` enables controlled rollout of new features
+- Optional fields with defaults avoid breaking changes
+- Flat structure is easy to understand and extend
+
+### Loading Strategy
+
+**Decision:** Read from disk on each call, no caching.
+
+```typescript
+export function getGlobalConfig(): GlobalConfig {
+  return loadConfigFromDisk();
+}
+```
+
+**Rationale:**
+- CLI commands are short-lived; caching adds complexity without benefit
+- Reading a small JSON file is ~1ms; negligible overhead
+- Always returns fresh data; no cache invalidation concerns
+- Simpler implementation
+
+### Directory Creation
+
+**Decision:** Create directory only when saving, not when reading.
+
+**Rationale:**
+- Don't create empty directories on read operations
+- Users who never save config won't have unnecessary directories
+- Aligns with principle of least surprise
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Config file corruption | Return defaults on parse error, log warning |
+| Permissions issues | Check write permissions before save, clear error message |
+| Future schema changes | Use optional fields, add version field if needed later |
+
+## Open Questions
+
+None - this proposal is intentionally minimal.
@@ -0,0 +1,20 @@
+## Why
+
+OpenSpec currently has no mechanism for user-level global settings or feature flags. As the CLI grows, we need a standard location to store user preferences, experimental features, and other configuration that persists across projects. Following XDG Base Directory Specification provides a well-understood, cross-platform approach.
+
+## What Changes
+
+- Add new `src/core/global-config.ts` module with:
+  - Path resolution following XDG Base Directory spec (`$XDG_CONFIG_HOME/openspec/` or fallback)
+  - Cross-platform support (Unix, macOS, Windows)
+  - Lazy config loading with sensible defaults
+  - TypeScript types for config shape
+- Export a global config directory path getter for future use (workflows, templates, cache)
+- Initial config schema supports 1-2 settings/feature flags only
+
+## Impact
+
+- Affected specs: New `global-config` capability (no existing specs modified)
+- Affected code:
+  - New `src/core/global-config.ts`
+  - Update `src/core/index.ts` to export new module
@@ -0,0 +1,76 @@
+## ADDED Requirements
+
+### Requirement: Global Config Directory Path
+
+The system SHALL resolve the global configuration directory path following XDG Base Directory Specification with platform-specific fallbacks.
+
+#### Scenario: Unix/macOS with XDG_CONFIG_HOME set
+- **WHEN** `$XDG_CONFIG_HOME` environment variable is set to `/custom/config`
+- **THEN** `getGlobalConfigDir()` returns `/custom/config/openspec`
+
+#### Scenario: Unix/macOS without XDG_CONFIG_HOME
+- **WHEN** `$XDG_CONFIG_HOME` environment variable is not set
+- **AND** the platform is Unix or macOS
+- **THEN** `getGlobalConfigDir()` returns `~/.config/openspec` (expanded to absolute path)
+
+#### Scenario: Windows platform
+- **WHEN** the platform is Windows
+- **AND** `%APPDATA%` is set to `C:\Users\User\AppData\Roaming`
+- **THEN** `getGlobalConfigDir()` returns `C:\Users\User\AppData\Roaming\openspec`
+
+### Requirement: Global Config Loading
+
+The system SHALL load global configuration from the config directory with sensible defaults when the config file does not exist or cannot be parsed.
+
+#### Scenario: Config file exists and is valid
+- **WHEN** `config.json` exists in the global config directory
+- **AND** the file contains valid JSON matching the config schema
+- **THEN** `getGlobalConfig()` returns the parsed configuration
+
+#### Scenario: Config file does not exist
+- **WHEN** `config.json` does not exist in the global config directory
+- **THEN** `getGlobalConfig()` returns the default configuration
+- **AND** no directory or file is created
+
+#### Scenario: Config file is invalid JSON
+- **WHEN** `config.json` exists but contains invalid JSON
+- **THEN** `getGlobalConfig()` returns the default configuration
+- **AND** a warning is logged to stderr
+
+### Requirement: Global Config Saving
+
+The system SHALL save global configuration to the config directory, creating the directory if it does not exist.
+
+#### Scenario: Save config to new directory
+- **WHEN** `saveGlobalConfig(config)` is called
+- **AND** the global config directory does not exist
+- **THEN** the directory is created
+- **AND** `config.json` is written with the provided configuration
+
+#### Scenario: Save config to existing directory
+- **WHEN** `saveGlobalConfig(config)` is called
+- **AND** the global config directory already exists
+- **THEN** `config.json` is written (overwriting if exists)
+
+### Requirement: Default Configuration
+
+The system SHALL provide a default configuration that is used when no config file exists.
+
+#### Scenario: Default config structure
+- **WHEN** no config file exists
+- **THEN** the default configuration includes an empty `featureFlags` object
+
+### Requirement: Config Schema Evolution
+
+The system SHALL merge loaded configuration with default values to ensure new config fields are available even when loading older config files.
+
+#### Scenario: Config file missing new fields
+- **WHEN** `config.json` exists with `{ "featureFlags": {} }`
+- **AND** the current schema includes a new field `defaultAiTool`
+- **THEN** `getGlobalConfig()` returns `{ featureFlags: {}, defaultAiTool: <default> }`
+- **AND** the loaded values take precedence over defaults for fields that exist in both
+
+#### Scenario: Config file has extra unknown fields
+- **WHEN** `config.json` contains fields not in the current schema
+- **THEN** the unknown fields are preserved in the returned configuration
+- **AND** no error or warning is raised
@@ -0,0 +1,26 @@
+## 1. Core Implementation
+
+- [x] 1.1 Create `src/core/global-config.ts` with path resolution
+  - Implement `getGlobalConfigDir()` following XDG spec
+  - Support `$XDG_CONFIG_HOME` environment variable override
+  - Platform-specific fallbacks (Unix: `~/.config/`, Windows: `%APPDATA%`)
+- [x] 1.2 Define TypeScript interfaces for config shape
+  - `GlobalConfig` interface with optional fields
+  - Start minimal: just `featureFlags?: Record<string, boolean>`
+- [x] 1.3 Implement config loading with defaults
+  - `getGlobalConfig()` - reads config.json if exists, merges with defaults
+  - No directory/file creation on read (lazy initialization)
+- [x] 1.4 Implement config saving
+  - `saveGlobalConfig(config)` - writes config.json, creates directory if needed
+
+## 2. Integration
+
+- [x] 2.1 Export new module from `src/core/index.ts`
+- [x] 2.2 Add constants for config file name and directory name
+
+## 3. Testing
+
+- [x] 3.1 Manual testing of path resolution on current platform
+- [x] 3.2 Test with/without `$XDG_CONFIG_HOME` set
+- [x] 3.3 Test config load when file doesn't exist (should return defaults)
+- [x] 3.4 Unit tests in `test/core/global-config.test.ts` (18 tests)
@@ -0,0 +1,89 @@
+## Context
+
+The `global-config` spec defines how OpenSpec reads/writes `config.json`, but users currently must edit it by hand. This command provides a CLI interface to that config.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide a discoverable CLI for config management
+- Support scripting with machine-readable output
+- Validate config changes with zod schema
+- Handle nested keys gracefully
+
+**Non-Goals:**
+- Project-local config (reserved for future via `--scope` flag)
+- Complex queries (JSONPath, filtering)
+- Config file format migration
+
+## Decisions
+
+### Key Naming: camelCase with Dot Notation
+
+**Decision:** Keys use camelCase matching the JSON structure, with dot notation for nesting.
+
+**Rationale:**
+- Matches the actual JSON keys (no translation layer)
+- Dot notation is intuitive and widely used (lodash, jq, kubectl)
+- Avoids complexity of supporting multiple casing styles
+
+**Examples:**
+```bash
+openspec config get featureFlags              # Returns object
+openspec config get featureFlags.experimental # Returns nested value
+openspec config set featureFlags.newFlag true
+```
+
+### Type Coercion: Auto-detect with `--string` Override
+
+**Decision:** Parse values automatically; provide `--string` flag to force string storage.
+
+**Rationale:**
+- Most intuitive for common cases (`true`, `false`, `123`)
+- Explicit override for edge cases (storing literal string "true")
+- Follows npm/yarn config patterns
+
+**Coercion rules:**
+| Input | Stored As |
+|-------|-----------|
+| `true`, `false` | boolean |
+| Numeric string (`123`, `3.14`) | number |
+| Everything else | string |
+| Any value with `--string` | string |
+
+### Output Format: Raw by Default
+
+**Decision:** `get` prints raw value only. `list` prints YAML-like format by default, JSON with `--json`.
+
+**Rationale:**
+- Raw output enables piping: `VAR=$(openspec config get key)`
+- YAML-like is human-readable for inspection
+- JSON for automation/scripting
+
+### Schema Validation: Zod with Unknown Field Passthrough
+
+**Decision:** Use zod for validation but preserve unknown fields per `global-config` spec.
+
+**Rationale:**
+- Type safety for known fields
+- Forward compatibility (old CLI doesn't break new config)
+- Follows existing `global-config` spec requirement
+
+### Reserved Flag: `--scope`
+
+**Decision:** Reserve `--scope global|project` but only implement `global` initially.
+
+**Rationale:**
+- Avoids breaking change if project-local config is added later
+- Clear error message if someone tries `--scope project`
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Dot notation conflicts with keys containing dots | Rare in practice; document limitation |
+| Type coercion surprises | `--string` escape hatch; document rules |
+| $EDITOR not set | Check and provide helpful error message |
+
+## Open Questions
+
+None - design is straightforward.
@@ -0,0 +1,60 @@
+## Why
+
+Users need a way to view and modify their global OpenSpec settings without manually editing JSON files. The `global-config` spec provides the foundation, but there's no user-facing interface to interact with the config. A dedicated `openspec config` command provides discoverability and ease of use.
+
+## What Changes
+
+Add `openspec config` subcommand with the following operations:
+
+```bash
+openspec config path                          # Show config file location
+openspec config list [--json]                 # Show all current settings
+openspec config get <key>                     # Get a specific value (raw, scriptable)
+openspec config set <key> <value> [--string]  # Set a value (auto-coerce types)
+openspec config unset <key>                   # Remove a key (revert to default)
+openspec config reset --all [-y]              # Reset everything to defaults
+openspec config edit                          # Open config in $EDITOR
+```
+
+**Key design decisions:**
+- **Key naming**: Use camelCase to match JSON structure (e.g., `featureFlags.someFlag`)
+- **Nested keys**: Support dot notation for nested access
+- **Type coercion**: Auto-detect types by default; `--string` flag forces string storage
+- **Scriptable output**: `get` prints raw value only (no labels) for easy piping
+- **Zod validation**: Use zod for config schema validation and type safety
+- **Future-proofing**: Reserve `--scope global|project` flag for potential project-local config
+
+**Example usage:**
+```bash
+$ openspec config path
+/Users/me/.config/openspec/config.json
+
+$ openspec config list
+featureFlags: {}
+
+$ openspec config set featureFlags.enableTelemetry false
+Set featureFlags.enableTelemetry = false
+
+$ openspec config get featureFlags.enableTelemetry
+false
+
+$ openspec config list --json
+{
+  "featureFlags": {}
+}
+
+$ openspec config unset featureFlags.enableTelemetry
+Unset featureFlags.enableTelemetry (reverted to default)
+
+$ openspec config edit
+# Opens $EDITOR with config.json
+```
+
+## Impact
+
+- Affected specs: New `cli-config` capability
+- Affected code:
+  - New `src/commands/config.ts`
+  - New `src/core/config-schema.ts` (zod schema)
+  - Update CLI entry point to register config command
+- Dependencies: Requires `global-config` spec (already implemented)
@@ -0,0 +1,213 @@
+# cli-config Specification
+
+## Purpose
+
+Provide a CLI interface for viewing and modifying global OpenSpec configuration. Enables users to manage settings without manually editing JSON files, with support for scripting and automation.
+
+## ADDED Requirements
+
+### Requirement: Command Structure
+
+The config command SHALL provide subcommands for all configuration operations.
+
+#### Scenario: Available subcommands
+
+- **WHEN** user executes `openspec config --help`
+- **THEN** display available subcommands:
+  - `path` - Show config file location
+  - `list` - Show all current settings
+  - `get <key>` - Get a specific value
+  - `set <key> <value>` - Set a value
+  - `unset <key>` - Remove a key (revert to default)
+  - `reset` - Reset configuration to defaults
+  - `edit` - Open config in editor
+
+### Requirement: Config Path
+
+The config command SHALL display the config file location.
+
+#### Scenario: Show config path
+
+- **WHEN** user executes `openspec config path`
+- **THEN** print the absolute path to the config file
+- **AND** exit with code 0
+
+### Requirement: Config List
+
+The config command SHALL display all current configuration values.
+
+#### Scenario: List config in human-readable format
+
+- **WHEN** user executes `openspec config list`
+- **THEN** display all config values in YAML-like format
+- **AND** show nested objects with indentation
+
+#### Scenario: List config as JSON
+
+- **WHEN** user executes `openspec config list --json`
+- **THEN** output the complete config as valid JSON
+- **AND** output only JSON (no additional text)
+
+### Requirement: Config Get
+
+The config command SHALL retrieve specific configuration values.
+
+#### Scenario: Get top-level key
+
+- **WHEN** user executes `openspec config get <key>` with a valid top-level key
+- **THEN** print the raw value only (no labels or formatting)
+- **AND** exit with code 0
+
+#### Scenario: Get nested key with dot notation
+
+- **WHEN** user executes `openspec config get featureFlags.someFlag`
+- **THEN** traverse the nested structure using dot notation
+- **AND** print the value at that path
+
+#### Scenario: Get non-existent key
+
+- **WHEN** user executes `openspec config get <key>` with a key that does not exist
+- **THEN** print nothing (empty output)
+- **AND** exit with code 1
+
+#### Scenario: Get object value
+
+- **WHEN** user executes `openspec config get <key>` where the value is an object
+- **THEN** print the object as JSON
+
+### Requirement: Config Set
+
+The config command SHALL set configuration values with automatic type coercion.
+
+#### Scenario: Set string value
+
+- **WHEN** user executes `openspec config set <key> <value>`
+- **AND** value does not match boolean or number patterns
+- **THEN** store value as a string
+- **AND** display confirmation message
+
+#### Scenario: Set boolean value
+
+- **WHEN** user executes `openspec config set <key> true` or `openspec config set <key> false`
+- **THEN** store value as boolean (not string)
+- **AND** display confirmation message
+
+#### Scenario: Set numeric value
+
+- **WHEN** user executes `openspec config set <key> <value>`
+- **AND** value is a valid number (integer or float)
+- **THEN** store value as number (not string)
+
+#### Scenario: Force string with --string flag
+
+- **WHEN** user executes `openspec config set <key> <value> --string`
+- **THEN** store value as string regardless of content
+- **AND** this allows storing literal "true" or "123" as strings
+
+#### Scenario: Set nested key
+
+- **WHEN** user executes `openspec config set featureFlags.newFlag true`
+- **THEN** create intermediate objects if they don't exist
+- **AND** set the value at the nested path
+
+### Requirement: Config Unset
+
+The config command SHALL remove configuration overrides.
+
+#### Scenario: Unset existing key
+
+- **WHEN** user executes `openspec config unset <key>`
+- **AND** the key exists in the config
+- **THEN** remove the key from the config file
+- **AND** the value reverts to its default
+- **AND** display confirmation message
+
+#### Scenario: Unset non-existent key
+
+- **WHEN** user executes `openspec config unset <key>`
+- **AND** the key does not exist in the config
+- **THEN** display message indicating key was not set
+- **AND** exit with code 0
+
+### Requirement: Config Reset
+
+The config command SHALL reset configuration to defaults.
+
+#### Scenario: Reset all with confirmation
+
+- **WHEN** user executes `openspec config reset --all`
+- **THEN** prompt for confirmation before proceeding
+- **AND** if confirmed, delete the config file or reset to defaults
+- **AND** display confirmation message
+
+#### Scenario: Reset all with -y flag
+
+- **WHEN** user executes `openspec config reset --all -y`
+- **THEN** reset without prompting for confirmation
+
+#### Scenario: Reset without --all flag
+
+- **WHEN** user executes `openspec config reset` without `--all`
+- **THEN** display error indicating `--all` is required
+- **AND** exit with code 1
+
+### Requirement: Config Edit
+
+The config command SHALL open the config file in the user's editor.
+
+#### Scenario: Open editor successfully
+
+- **WHEN** user executes `openspec config edit`
+- **AND** `$EDITOR` or `$VISUAL` environment variable is set
+- **THEN** open the config file in that editor
+- **AND** create the config file with defaults if it doesn't exist
+- **AND** wait for the editor to close before returning
+
+#### Scenario: No editor configured
+
+- **WHEN** user executes `openspec config edit`
+- **AND** neither `$EDITOR` nor `$VISUAL` is set
+- **THEN** display error message suggesting to set `$EDITOR`
+- **AND** exit with code 1
+
+### Requirement: Key Naming Convention
+
+The config command SHALL use camelCase keys matching the JSON structure.
+
+#### Scenario: Keys match JSON structure
+
+- **WHEN** accessing configuration keys via CLI
+- **THEN** use camelCase matching the actual JSON property names
+- **AND** support dot notation for nested access (e.g., `featureFlags.someFlag`)
+
+### Requirement: Schema Validation
+
+The config command SHALL validate configuration writes against the config schema using zod, while allowing unknown fields for forward compatibility.
+
+#### Scenario: Unknown key accepted
+
+- **WHEN** user executes `openspec config set someFutureKey 123`
+- **THEN** the value is saved successfully
+- **AND** exit with code 0
+
+#### Scenario: Invalid feature flag value rejected
+
+- **WHEN** user executes `openspec config set featureFlags.someFlag notABoolean`
+- **THEN** display a descriptive error message
+- **AND** do not modify the config file
+- **AND** exit with code 1
+
+### Requirement: Reserved Scope Flag
+
+The config command SHALL reserve the `--scope` flag for future extensibility.
+
+#### Scenario: Scope flag defaults to global
+
+- **WHEN** user executes any config command without `--scope`
+- **THEN** operate on global configuration (default behavior)
+
+#### Scenario: Project scope not yet implemented
+
+- **WHEN** user executes `openspec config --scope project <subcommand>`
+- **THEN** display error message: "Project-local config is not yet implemented"
+- **AND** exit with code 1
@@ -0,0 +1,28 @@
+## 1. Core Infrastructure
+
+- [x] 1.1 Create zod schema for global config in `src/core/config-schema.ts`
+- [x] 1.2 Add utility functions for dot-notation key access (get/set nested values)
+- [x] 1.3 Add type coercion logic (auto-detect boolean/number/string)
+
+## 2. Config Command Implementation
+
+- [x] 2.1 Create `src/commands/config.ts` with Commander.js subcommands
+- [x] 2.2 Implement `config path` subcommand
+- [x] 2.3 Implement `config list` subcommand with `--json` flag
+- [x] 2.4 Implement `config get <key>` subcommand (raw output)
+- [x] 2.5 Implement `config set <key> <value>` with `--string` flag
+- [x] 2.6 Implement `config unset <key>` subcommand
+- [x] 2.7 Implement `config reset --all` with `-y` confirmation flag
+- [x] 2.8 Implement `config edit` subcommand (spawn $EDITOR)
+
+## 3. Integration
+
+- [x] 3.1 Register config command in CLI entry point
+- [x] 3.2 Update shell completion registry to include config subcommands
+
+## 4. Testing
+
+- [x] 4.1 Manual testing of all subcommands
+- [x] 4.2 Verify zod validation rejects invalid keys/values
+- [x] 4.3 Test nested key access with dot notation
+- [x] 4.4 Test type coercion edge cases (true/false, numbers, strings)
@@ -0,0 +1,197 @@
+## Context
+
+This implements "Slice 1: What's Ready?" from the artifact POC analysis. The core insight is using the filesystem as a database - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+
+This module will coexist with the current OpenSpec system as a parallel capability, potentially enabling future migration or integration.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Pure dependency graph logic with no side effects
+- Stateless state detection (rescan filesystem each query)
+- Support glob patterns for multi-file artifacts (e.g., `specs/*.md`)
+- Load artifact definitions from YAML schemas
+- Calculate topological build order
+- Determine "ready" artifacts based on dependency completion
+
+**Non-Goals:**
+- CLI commands (Slice 4)
+- Multi-change management (Slice 2)
+- Template resolution and enrichment (Slice 3)
+- Agent integration or Claude commands
+- Replacing existing OpenSpec functionality
+
+## Decisions
+
+### Decision: Filesystem as Database
+Use file existence for state detection rather than a separate state file.
+
+**Rationale:**
+- Stateless - no state corruption possible
+- Git-friendly - state derived from committed files
+- Simple - no sync issues between state file and actual files
+
+**Alternatives considered:**
+- JSON/SQLite state file: More complex, sync issues, not git-friendly
+- Git metadata: Too coupled to git, complex implementation
+
+### Decision: Kahn's Algorithm for Topological Sort
+Use Kahn's algorithm for computing build order.
+
+**Rationale:**
+- Well-understood, O(V+E) complexity
+- Naturally detects cycles during execution
+- Produces a stable, deterministic order
+
+### Decision: Glob Pattern Support
+Support glob patterns like `specs/*.md` in artifact `generates` field.
+
+**Rationale:**
+- Allows multiple files to satisfy a single artifact requirement
+- Common pattern for spec directories with multiple files
+- Uses standard glob syntax
+
+### Decision: Immutable Completed Set
+Represent completion state as an immutable Set of completed artifact IDs.
+
+**Rationale:**
+- Functional style, easier to reason about
+- State derived fresh each query, no mutation needed
+- Clear separation between graph structure and runtime state
+- Filesystem can only detect binary existence (complete vs not complete)
+
+**Note:** `inProgress` and `failed` states are deferred to future slices. They would require external state tracking (e.g., a status file) since file existence alone cannot distinguish these states.
+
+### Decision: Zod for Schema Validation
+Use Zod for validating YAML schema structure and deriving TypeScript types.
+
+**Rationale:**
+- Already a project dependency (v4.0.17) used in `src/core/schemas/`
+- Type inference via `z.infer<>` - single source of truth for types
+- Runtime validation with detailed error messages
+- Consistent with existing project patterns (`base.schema.ts`, `config-schema.ts`)
+
+**Alternatives considered:**
+- Manual validation: More code, error-prone, no type inference
+- JSON Schema: Would require additional dependency, less TypeScript integration
+- io-ts: Not already in project, steeper learning curve
+
+### Decision: Two-Level Schema Resolution
+Schemas resolve from global user data directory, falling back to package built-ins.
+
+**Resolution order:**
+1. `${XDG_DATA_HOME:-~/.local/share}/openspec/schemas/<name>.yaml` - Global user override
+2. `<package>/schemas/<name>.yaml` - Built-in defaults
+
+**Rationale:**
+- Follows XDG Base Directory Specification (schemas are data, not config)
+- Mirrors existing `getGlobalConfigDir()` pattern in `src/core/global-paths.ts`
+- Built-ins baked into package, never auto-copied
+- Users customize by creating files in global data dir
+- Simple - no project-level overrides (can add later if needed)
+
+**XDG compliance:**
+- Uses `XDG_DATA_HOME` env var when set (all platforms)
+- Unix/macOS fallback: `~/.local/share/openspec/`
+- Windows fallback: `%LOCALAPPDATA%/openspec/`
+
+**Alternatives considered:**
+- Project-level overrides: Added complexity, not needed initially
+- Auto-copy to user space: Creates drift, harder to update defaults
+- Config directory (`XDG_CONFIG_HOME`): Schemas are workflow definitions (data), not user preferences (config)
+
+### Decision: Template Field Parsed But Not Resolved
+The `template` field is required in schema YAML for completeness, but template resolution is deferred to Slice 3.
+
+**Rationale:**
+- Slice 1 focuses on "What's Ready?" - dependency and completion queries only
+- Template paths are validated syntactically (non-empty string) but not resolved
+- Keeps Slice 1 focused and independently testable
+
+### Decision: Cycle Error Format
+Cycle errors list all artifact IDs in the cycle for easy debugging.
+
+**Format:** `"Cyclic dependency detected: A → B → C → A"`
+
+**Rationale:**
+- Shows the full cycle path, not just that a cycle exists
+- Actionable - developer can see exactly which artifacts to fix
+- Consistent with Kahn's algorithm which naturally identifies cycle participants
+
+## Data Structures
+
+**Zod Schemas (source of truth):**
+
+```typescript
+import { z } from 'zod';
+
+// Artifact definition schema
+export const ArtifactSchema = z.object({
+  id: z.string().min(1, 'Artifact ID is required'),
+  generates: z.string().min(1),      // e.g., "proposal.md" or "specs/*.md"
+  description: z.string(),
+  template: z.string(),              // path to template file
+  requires: z.array(z.string()).default([]),
+});
+
+// Full schema YAML structure
+export const SchemaYamlSchema = z.object({
+  name: z.string().min(1, 'Schema name is required'),
+  version: z.number().int().positive(),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1, 'At least one artifact required'),
+});
+
+// Derived TypeScript types
+export type Artifact = z.infer<typeof ArtifactSchema>;
+export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+```
+
+**Runtime State (not Zod - internal only):**
+
+```typescript
+// Slice 1: Simple completion tracking via filesystem
+type CompletedSet = Set<string>;
+
+// Return type for blocked query
+interface BlockedArtifacts {
+  [artifactId: string]: string[];  // artifact → list of unmet dependencies
+}
+
+interface ArtifactGraphResult {
+  completed: string[];
+  ready: string[];
+  blocked: BlockedArtifacts;
+  buildOrder: string[];
+}
+```
+
+## File Structure
+
+```
+src/core/artifact-graph/
+├── index.ts           # Public exports
+├── types.ts           # Zod schemas and type definitions
+├── graph.ts           # ArtifactGraph class
+├── state.ts           # State detection logic
+├── resolver.ts        # Schema resolution (global → built-in)
+└── schemas/           # Built-in schema definitions (package level)
+    ├── spec-driven.yaml   # Default: proposal → specs → design → tasks
+    └── tdd.yaml           # Alternative: tests → implementation → docs
+```
+
+**Schema Resolution Paths:**
+- Global user override: `${XDG_DATA_HOME:-~/.local/share}/openspec/schemas/<name>.yaml`
+- Package built-in: `src/core/artifact-graph/schemas/<name>.yaml` (bundled with package)
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Glob pattern edge cases | Use well-tested glob library (fast-glob or similar) |
+| Cycle detection | Kahn's algorithm naturally fails on cycles; provide clear error |
+| Schema evolution | Version field in schema, validate on load |
+
+## Open Questions
+
+None - all questions resolved in Decisions section.
@@ -0,0 +1,18 @@
+## Why
+
+The current OpenSpec system relies on conventions and AI inference for artifact ordering. A formal artifact graph with dependency awareness would enable deterministic "what's ready?" queries, making the system more predictable and enabling future features like automated pipeline execution.
+
+## What Changes
+
+- Add `ArtifactGraph` class to model artifacts as a DAG with dependency relationships
+- Add `ArtifactState` type to track completion status (completed, in_progress, failed)
+- Add filesystem-based state detection using file existence and glob patterns
+- Add schema YAML parser to load artifact definitions
+- Implement topological sort (Kahn's algorithm) for build order calculation
+- Add `getNextArtifacts()` to find artifacts ready for creation
+
+## Impact
+
+- Affected specs: New `artifact-graph` capability
+- Affected code: `src/core/artifact-graph/` (new directory)
+- No changes to existing functionality - this is a parallel module
@@ -0,0 +1,103 @@
+## ADDED Requirements
+
+### Requirement: Schema Loading
+The system SHALL load artifact graph definitions from YAML schema files.
+
+#### Scenario: Valid schema loaded
+- **WHEN** a valid schema YAML file is provided
+- **THEN** the system returns an ArtifactGraph with all artifacts and dependencies
+
+#### Scenario: Invalid schema rejected
+- **WHEN** a schema YAML file is missing required fields
+- **THEN** the system throws an error with a descriptive message
+
+#### Scenario: Cyclic dependencies detected
+- **WHEN** a schema contains cyclic artifact dependencies
+- **THEN** the system throws an error listing the artifact IDs in the cycle
+
+#### Scenario: Invalid dependency reference
+- **WHEN** an artifact's `requires` array references a non-existent artifact ID
+- **THEN** the system throws an error identifying the invalid reference
+
+#### Scenario: Duplicate artifact IDs rejected
+- **WHEN** a schema contains multiple artifacts with the same ID
+- **THEN** the system throws an error identifying the duplicate
+
+### Requirement: Build Order Calculation
+The system SHALL compute a valid topological build order for artifacts.
+
+#### Scenario: Linear dependency chain
+- **WHEN** artifacts form a linear chain (A → B → C)
+- **THEN** getBuildOrder() returns [A, B, C]
+
+#### Scenario: Diamond dependency
+- **WHEN** artifacts form a diamond (A → B, A → C, B → D, C → D)
+- **THEN** getBuildOrder() returns A before B and C, and D last
+
+#### Scenario: Independent artifacts
+- **WHEN** artifacts have no dependencies
+- **THEN** getBuildOrder() returns them in a stable order
+
+### Requirement: State Detection
+The system SHALL detect artifact completion state by scanning the filesystem.
+
+#### Scenario: Simple file exists
+- **WHEN** an artifact generates "proposal.md" and the file exists
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Simple file missing
+- **WHEN** an artifact generates "proposal.md" and the file does not exist
+- **THEN** the artifact is not marked as completed
+
+#### Scenario: Glob pattern with files
+- **WHEN** an artifact generates "specs/*.md" and the specs/ directory contains .md files
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Glob pattern empty
+- **WHEN** an artifact generates "specs/*.md" and the specs/ directory is empty or missing
+- **THEN** the artifact is not marked as completed
+
+#### Scenario: Missing change directory
+- **WHEN** the change directory does not exist
+- **THEN** all artifacts are marked as not completed (empty state)
+
+### Requirement: Ready Artifact Query
+The system SHALL identify which artifacts are ready to be created based on dependency completion.
+
+#### Scenario: Root artifacts ready initially
+- **WHEN** no artifacts are completed
+- **THEN** getNextArtifacts() returns artifacts with no dependencies
+
+#### Scenario: Dependent artifact becomes ready
+- **WHEN** an artifact's dependencies are all completed
+- **THEN** getNextArtifacts() includes that artifact
+
+#### Scenario: Blocked artifacts excluded
+- **WHEN** an artifact has uncompleted dependencies
+- **THEN** getNextArtifacts() does not include that artifact
+
+### Requirement: Completion Check
+The system SHALL determine when all artifacts in a graph are complete.
+
+#### Scenario: All complete
+- **WHEN** all artifacts in the graph are in the completed set
+- **THEN** isComplete() returns true
+
+#### Scenario: Partially complete
+- **WHEN** some artifacts in the graph are not completed
+- **THEN** isComplete() returns false
+
+### Requirement: Blocked Query
+The system SHALL identify which artifacts are blocked and return all their unmet dependencies.
+
+#### Scenario: Artifact blocked by single dependency
+- **WHEN** artifact B requires artifact A and A is not complete
+- **THEN** getBlocked() returns `{ B: ['A'] }`
+
+#### Scenario: Artifact blocked by multiple dependencies
+- **WHEN** artifact C requires A and B, and only A is complete
+- **THEN** getBlocked() returns `{ C: ['B'] }`
+
+#### Scenario: Artifact blocked by all dependencies
+- **WHEN** artifact C requires A and B, and neither is complete
+- **THEN** getBlocked() returns `{ C: ['A', 'B'] }`
@@ -0,0 +1,61 @@
+## 1. Type Definitions
+- [x] 1.1 Create `src/core/artifact-graph/types.ts` with Zod schemas (`ArtifactSchema`, `SchemaYamlSchema`) and inferred types via `z.infer<>`
+- [x] 1.2 Define `CompletedSet` (Set<string>), `BlockedArtifacts`, and `ArtifactGraphResult` types for runtime state
+
+## 2. Schema Parser
+- [x] 2.1 Create `src/core/artifact-graph/schema.ts` with YAML loading and Zod validation via `.safeParse()`
+- [x] 2.2 Implement dependency reference validation (ensure `requires` references valid artifact IDs)
+- [x] 2.3 Implement duplicate artifact ID detection
+- [x] 2.4 Add cycle detection during schema load (error format: "Cyclic dependency detected: A → B → C → A")
+
+## 3. Artifact Graph Core
+- [x] 3.1 Create `src/core/artifact-graph/graph.ts` with ArtifactGraph class
+- [x] 3.2 Implement `fromYaml(path)` - load graph from schema file
+- [x] 3.3 Implement `getBuildOrder()` - topological sort via Kahn's algorithm
+- [x] 3.4 Implement `getArtifact(id)` - retrieve single artifact definition
+- [x] 3.5 Implement `getAllArtifacts()` - list all artifacts
+
+## 4. State Detection
+- [x] 4.1 Create `src/core/artifact-graph/state.ts` with state detection logic
+- [x] 4.2 Implement file existence checking for simple paths
+- [x] 4.3 Implement glob pattern matching for multi-file artifacts
+- [x] 4.4 Implement `detectCompleted(graph, changeDir)` - scan filesystem and return CompletedSet
+- [x] 4.5 Handle missing changeDir gracefully (return empty CompletedSet)
+
+## 5. Ready Calculation
+- [x] 5.1 Implement `getNextArtifacts(graph, completed)` - find artifacts with all deps completed
+- [x] 5.2 Implement `isComplete(graph, completed)` - check if all artifacts done
+- [x] 5.3 Implement `getBlocked(graph, completed)` - return BlockedArtifacts map (artifact → unmet deps)
+
+## 6. Schema Resolution
+- [x] 6.1 Create `src/core/artifact-graph/resolver.ts` with schema resolution logic
+- [x] 6.2 Add `getGlobalDataDir()` to `src/core/global-config.ts` (XDG_DATA_HOME with platform fallbacks)
+- [x] 6.3 Implement `resolveSchema(name)` - global (`${XDG_DATA_HOME}/openspec/schemas/`) → built-in fallback
+
+## 7. Built-in Schemas
+- [x] 7.1 Create `src/core/artifact-graph/schemas/spec-driven.yaml` (default: proposal → specs → design → tasks)
+- [x] 7.2 Create `src/core/artifact-graph/schemas/tdd.yaml` (alternative: tests → implementation → docs)
+
+## 8. Integration
+- [x] 8.1 Create `src/core/artifact-graph/index.ts` with public exports
+
+## 9. Testing
+- [x] 9.1 Test: Parse valid schema YAML returns correct artifact graph
+- [x] 9.2 Test: Parse invalid schema (missing fields) throws descriptive error
+- [x] 9.3 Test: Duplicate artifact IDs throws error
+- [x] 9.4 Test: Invalid `requires` reference throws error identifying the invalid ID
+- [x] 9.5 Test: Cycle in schema throws error listing cycle path (e.g., "A → B → C → A")
+- [x] 9.6 Test: Compute build order returns correct topological ordering (linear chain)
+- [x] 9.7 Test: Compute build order handles diamond dependencies correctly
+- [x] 9.8 Test: Independent artifacts return in stable order
+- [x] 9.9 Test: Empty/missing changeDir returns empty CompletedSet
+- [x] 9.10 Test: File existence marks artifact as completed
+- [x] 9.11 Test: Glob pattern specs/*.md detected as complete when files exist
+- [x] 9.12 Test: Glob pattern with empty directory not marked complete
+- [x] 9.13 Test: getNextArtifacts returns only root artifacts when nothing completed
+- [x] 9.14 Test: getNextArtifacts includes artifact when all deps completed
+- [x] 9.15 Test: getBlocked returns artifact with all unmet dependencies listed
+- [x] 9.16 Test: isComplete() returns true when all artifacts completed
+- [x] 9.17 Test: isComplete() returns false when some artifacts incomplete
+- [x] 9.18 Test: Schema resolution finds global override before built-in
+- [x] 9.19 Test: Schema resolution falls back to built-in when no global
@@ -0,0 +1,74 @@
+## Context
+
+This is Slice 2 of the artifact tracker POC. The goal is to provide utilities for creating change directories programmatically.
+
+**Current state:** No programmatic way to create changes. Users must manually create directories.
+
+**Proposed state:** Utility functions for change creation with name validation.
+
+## Goals / Non-Goals
+
+### Goals
+- **Add** `createChange()` function to create change directories
+- **Add** `validateChangeName()` function for kebab-case validation
+- **Enable** automation (Claude commands, scripts) to create changes
+
+### Non-Goals
+- Refactor existing CLI commands (they work fine)
+- Create abstraction layers or manager classes
+- Change how `ListCommand` or `ChangeCommand` work
+
+## Decisions
+
+### Decision 1: Simple Utility Functions
+
+**Choice**: Add functions to `src/utils/change-utils.ts` - no class.
+
+```typescript
+// src/utils/change-utils.ts
+
+export function validateChangeName(name: string): { valid: boolean; error?: string }
+
+export async function createChange(
+  projectRoot: string,
+  name: string
+): Promise<void>
+```
+
+**Why**:
+- Simple, no abstraction overhead
+- Easy to test
+- Easy to import where needed
+- Matches existing utility patterns in `src/utils/`
+
+**Alternatives considered**:
+- ChangeManager class: Rejected - over-engineered for 2 functions
+- Add to existing command: Rejected - mixes CLI with reusable logic
+
+### Decision 2: Kebab-Case Validation Pattern
+
+**Choice**: Validate names with `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+
+Valid: `add-auth`, `refactor-db`, `add-feature-2`, `refactor`
+Invalid: `Add-Auth`, `add auth`, `add_auth`, `-add-auth`, `add-auth-`, `add--auth`
+
+**Why**:
+- Filesystem-safe (no special characters)
+- URL-safe (for future web UI)
+- Consistent with existing change naming in repo
+
+## File Changes
+
+### New Files
+- `src/utils/change-utils.ts` - Utility functions
+- `src/utils/change-utils.test.ts` - Unit tests
+
+### Modified Files
+- None
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Function might not cover all use cases | Start simple, extend if needed |
+| Naming conflicts with future work | Using clear, specific function names |
@@ -0,0 +1,45 @@
+## Why
+
+There's no programmatic way to create a new change directory. Users must manually:
+1. Create `openspec/changes/<name>/` directory
+2. Create a `proposal.md` file
+3. Hope they got the naming right
+
+This is error-prone and blocks automation (e.g., Claude commands, scripts).
+
+**This proposal adds:**
+1. `createChange(projectRoot, name)` - Create change directories programmatically
+2. `validateChangeName(name)` - Enforce kebab-case naming conventions
+
+## What Changes
+
+### New Utilities
+
+| Function | Description |
+|----------|-------------|
+| `createChange(projectRoot, name)` | Creates `openspec/changes/<name>/` directory |
+| `validateChangeName(name)` | Returns `{ valid: boolean; error?: string }` |
+
+### Name Validation Rules
+
+Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+
+| Valid | Invalid |
+|-------|---------|
+| `add-auth` | `Add-Auth` (uppercase) |
+| `refactor-db` | `add auth` (spaces) |
+| `add-feature-2` | `add_auth` (underscores) |
+| `refactor` | `-add-auth` (leading hyphen) |
+
+### Location
+
+New file: `src/utils/change-utils.ts`
+
+Simple utility functions - no class, no abstraction layer.
+
+## Impact
+
+- **Affected specs**: None
+- **Affected code**: None (new utilities only)
+- **New files**: `src/utils/change-utils.ts`
+- **Breaking changes**: None
@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: Change Creation
+The system SHALL provide a function to create new change directories programmatically.
+
+#### Scenario: Create change
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called
+- **THEN** the system creates `openspec/changes/add-auth/` directory
+
+#### Scenario: Duplicate change rejected
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/add-auth/` already exists
+- **THEN** the system throws an error indicating the change already exists
+
+#### Scenario: Creates parent directories if needed
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/` does not exist
+- **THEN** the system creates the full path including parent directories
+
+#### Scenario: Invalid change name rejected
+- **WHEN** `createChange(projectRoot, 'Add Auth')` is called with an invalid name
+- **THEN** the system throws a validation error
+
+### Requirement: Change Name Validation
+The system SHALL validate change names follow kebab-case conventions.
+
+#### Scenario: Valid kebab-case name accepted
+- **WHEN** a change name like `add-user-auth` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Numeric suffixes accepted
+- **WHEN** a change name like `add-feature-2` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Single word accepted
+- **WHEN** a change name like `refactor` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Uppercase characters rejected
+- **WHEN** a change name like `Add-Auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Spaces rejected
+- **WHEN** a change name like `add auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Underscores rejected
+- **WHEN** a change name like `add_auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Special characters rejected
+- **WHEN** a change name like `add-auth!` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Leading hyphen rejected
+- **WHEN** a change name like `-add-auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Trailing hyphen rejected
+- **WHEN** a change name like `add-auth-` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Consecutive hyphens rejected
+- **WHEN** a change name like `add--auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
@@ -0,0 +1,30 @@
+## Phase 1: Implement Name Validation
+
+- [x] 1.1 Create `src/utils/change-utils.ts`
+- [x] 1.2 Implement `validateChangeName()` with kebab-case pattern
+- [x] 1.3 Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`
+- [x] 1.4 Return `{ valid: boolean; error?: string }`
+- [x] 1.5 Add test: valid names accepted (`add-auth`, `refactor`, `add-feature-2`)
+- [x] 1.6 Add test: uppercase rejected
+- [x] 1.7 Add test: spaces rejected
+- [x] 1.8 Add test: underscores rejected
+- [x] 1.9 Add test: special characters rejected
+- [x] 1.10 Add test: leading/trailing hyphens rejected
+- [x] 1.11 Add test: consecutive hyphens rejected
+
+## Phase 2: Implement Change Creation
+
+- [x] 2.1 Implement `createChange(projectRoot, name)`
+- [x] 2.2 Validate name before creating
+- [x] 2.3 Create parent directories if needed (`openspec/changes/`)
+- [x] 2.4 Throw if change already exists
+- [x] 2.5 Add test: creates directory
+- [x] 2.6 Add test: duplicate change throws error
+- [x] 2.7 Add test: invalid name throws validation error
+- [x] 2.8 Add test: creates parent directories if needed
+
+## Phase 3: Integration
+
+- [x] 3.1 Export functions from `src/utils/index.ts`
+- [x] 3.2 Add JSDoc comments
+- [x] 3.3 Run all tests to verify no regressions
@@ -0,0 +1,149 @@
+## Context
+
+This is Slice 3 of the artifact-graph POC. We have:
+- `ArtifactGraph` class with graph operations (Slice 1)
+- `detectCompleted()` for filesystem-based state detection (Slice 1)
+- `resolveSchema()` for XDG schema resolution (Slice 1)
+- `createChange()` and `validateChangeName()` utilities (Slice 2)
+
+After `restructure-schema-directories` is implemented, schemas will be self-contained directories:
+```
+schemas/<name>/
+├── schema.yaml
+└── templates/
+    └── *.md
+```
+
+This proposal adds template loading and instruction enrichment on top of that structure.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Load templates from schema directories
+- Enrich templates with change-specific context (dependency status)
+- Format change status for CLI output
+
+**Non-Goals:**
+- Template authoring UI
+- Dynamic template compilation/execution
+- Caching (keep it stateless like the rest)
+
+## Decisions
+
+### 1. Pure functions over classes
+
+Follow the pattern in `resolver.ts` and `state.ts`. Use a simple `ChangeContext` interface with pure functions:
+
+```typescript
+interface ChangeContext {
+  changeName: string;
+  changeDir: string;
+  schemaName: string;
+  graph: ArtifactGraph;
+  completed: CompletedSet;
+}
+
+function loadChangeContext(projectRoot: string, changeName: string, schemaName?: string): ChangeContext
+function loadTemplate(schemaName: string, templatePath: string): string
+function getInstructions(artifactId: string, context: ChangeContext): string
+function formatStatus(context: ChangeContext): string
+```
+
+**Why:** Matches existing codebase patterns. Easier to test. No hidden state.
+
+### 2. Template resolution from schema directory
+
+Templates are loaded from the schema's `templates/` subdirectory:
+
+```typescript
+function loadTemplate(schemaName: string, templatePath: string): string {
+  const schemaDir = getSchemaDir(schemaName);  // From resolver.ts
+  const fullPath = path.join(schemaDir, 'templates', templatePath);
+  return fs.readFileSync(fullPath, 'utf-8');
+}
+```
+
+Resolution is handled by `getSchemaDir()` which already checks user override → package built-in.
+
+**Why:** Leverages existing schema resolution. Templates are co-located with schemas.
+
+### 3. Template path from artifact definition
+
+The artifact's `template` field is a path relative to the schema's `templates/` directory:
+
+```yaml
+artifacts:
+  - id: proposal
+    template: "proposal.md"  # → schemas/<schema>/templates/proposal.md
+```
+
+**Why:** Explicit, simple, no magic.
+
+### 4. Minimal context injection
+
+Templates are markdown. Injection prepends a header section with context:
+
+```markdown
+---
+change: add-auth
+artifact: proposal
+schema: spec-driven
+output: openspec/changes/add-auth/proposal.md
+---
+
+## Dependencies
+- [x] (none - this is a root artifact)
+
+## Next Steps
+After creating this artifact, you can work on: design, specs
+
+---
+
+[original template content...]
+```
+
+**Why:** Simple string concatenation. No template engine dependency. Clear separation.
+
+### 5. Status output format
+
+```markdown
+## Change: add-auth (spec-driven)
+
+| Artifact | Status | Output |
+|----------|--------|--------|
+| proposal | done | proposal.md |
+| specs | ready | specs/*.md |
+| design | blocked (needs: proposal) | design.md |
+| tasks | blocked (needs: specs, design) | tasks.md |
+```
+
+**Why:** Markdown table is readable in terminal and docs. Matches CLI output style.
+
+## File Structure
+
+```
+src/core/artifact-graph/
+├── index.ts              # Add new exports
+├── template.ts           # NEW: Template loading
+├── context.ts            # NEW: ChangeContext loading
+└── instructions.ts       # NEW: Enrichment and formatting
+```
+
+## Risks / Trade-offs
+
+**Dependency on restructure-schema-directories:**
+- This proposal requires the schema restructure to be done first
+- Mitigation: Clear dependency documented, implement in order
+
+**No template engine:**
+- Pro: Zero dependencies, simple code
+- Con: Limited expressiveness
+- Mitigation: Current use case only needs static templates + header injection
+
+## Migration Plan
+
+N/A - new capability, no existing code to migrate.
+
+## Open Questions
+
+None.
@@ -0,0 +1,20 @@
+## Why
+
+Slice 1 (artifact-graph) provides graph operations and state detection. Slice 2 (change-utils) provides change creation. We now need the ability to load templates for artifacts and enrich them with change-specific context so users/agents know what to create next.
+
+## What Changes
+
+- Add template resolution from schema directories (uses structure from `restructure-schema-directories`)
+- Add instruction enrichment that injects change context into templates
+- Add status formatting for CLI output
+- New `instruction-loader` capability
+
+## Dependencies
+
+- Requires `restructure-schema-directories` to be implemented first (schemas as directories with co-located templates)
+
+## Impact
+
+- Affected specs: New `instruction-loader` spec
+- Affected code: `src/core/artifact-graph/` (new files)
+- Builds on: `artifact-graph` (Slice 1), uses `ArtifactGraph`, `detectCompleted`, `resolveSchema`
@@ -0,0 +1,70 @@
+# instruction-loader Specification
+
+## Purpose
+Load templates from schema directories and enrich them with change-specific context for guiding artifact creation.
+
+## ADDED Requirements
+
+### Requirement: Template Loading
+The system SHALL load templates from schema directories.
+
+#### Scenario: Load template from schema directory
+- **WHEN** `loadTemplate(schemaName, templatePath)` is called
+- **THEN** the system loads the template from `schemas/<schemaName>/templates/<templatePath>`
+
+#### Scenario: Template file not found
+- **WHEN** a template file does not exist in the schema's templates directory
+- **THEN** the system throws an error with the template path
+
+### Requirement: Change Context Loading
+The system SHALL load change context combining graph and completion state.
+
+#### Scenario: Load context for existing change
+- **WHEN** `loadChangeContext(projectRoot, changeName)` is called for an existing change
+- **THEN** the system returns a context with graph, completed set, schema name, and change info
+
+#### Scenario: Load context with custom schema
+- **WHEN** `loadChangeContext(projectRoot, changeName, schemaName)` is called
+- **THEN** the system uses the specified schema instead of default
+
+#### Scenario: Load context for non-existent change directory
+- **WHEN** `loadChangeContext` is called for a non-existent change directory
+- **THEN** the system returns context with empty completed set
+
+### Requirement: Template Enrichment
+The system SHALL enrich templates with change-specific context.
+
+#### Scenario: Include artifact metadata
+- **WHEN** instructions are generated for an artifact
+- **THEN** the output includes change name, artifact ID, schema name, and output path
+
+#### Scenario: Include dependency status
+- **WHEN** an artifact has dependencies
+- **THEN** the output shows each dependency with completion status (done/missing)
+
+#### Scenario: Include unlocked artifacts
+- **WHEN** instructions are generated
+- **THEN** the output includes which artifacts become available after this one
+
+#### Scenario: Root artifact indicator
+- **WHEN** an artifact has no dependencies
+- **THEN** the dependency section indicates this is a root artifact
+
+### Requirement: Status Formatting
+The system SHALL format change status as readable output.
+
+#### Scenario: All artifacts completed
+- **WHEN** all artifacts are completed
+- **THEN** status shows all artifacts as "done"
+
+#### Scenario: Mixed completion status
+- **WHEN** some artifacts are completed
+- **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"
+
+#### Scenario: Blocked artifact details
+- **WHEN** an artifact is blocked
+- **THEN** status shows which dependencies are missing
+
+#### Scenario: Include output paths
+- **WHEN** status is formatted
+- **THEN** each artifact shows its output path pattern
@@ -0,0 +1,13 @@
+# Tasks
+
+## Implementation Tasks
+
+- [x] Create `instruction-loader` spec in `openspec/specs/instruction-loader/spec.md`
+- [x] Implement `loadTemplate` function to load templates from schema directories
+- [x] Implement `loadChangeContext` function to combine graph and completion state
+- [x] Implement `generateInstructions` function to enrich templates with change context
+- [x] Implement `formatChangeStatus` function for readable status output
+- [x] Export new functions from `src/core/artifact-graph/index.ts`
+- [x] Add comprehensive tests in `test/core/artifact-graph/instruction-loader.test.ts`
+- [x] Verify build passes
+- [x] Verify all tests pass
@@ -0,0 +1,129 @@
+## Context
+
+Built-in schemas are currently embedded as TypeScript objects:
+
+```typescript
+// src/core/artifact-graph/builtin-schemas.ts
+export const SPEC_DRIVEN_SCHEMA: SchemaYaml = {
+  name: 'spec-driven',
+  version: 1,
+  artifacts: [...]
+};
+```
+
+This doesn't support templates co-located with schemas. The instruction loader (Slice 3) needs templates, and the cleanest approach is self-contained schema directories.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Schemas as self-contained directories (schema.yaml + templates/)
+- User overrides via XDG data directory
+- Simple 2-level resolution (user → package)
+- Templates co-located with their schema
+
+**Non-Goals:**
+- Shared template fallback (intentionally avoiding complexity)
+- Runtime schema compilation
+- Schema inheritance
+
+## Decisions
+
+### 1. Directory structure
+
+Each schema is a directory containing `schema.yaml` and `templates/`:
+
+```
+<package>/schemas/
+├── spec-driven/
+│   ├── schema.yaml
+│   └── templates/
+│       ├── proposal.md
+│       ├── design.md
+│       ├── spec.md
+│       └── tasks.md
+└── tdd/
+    ├── schema.yaml
+    └── templates/
+        ├── spec.md
+        ├── test.md
+        ├── implementation.md
+        └── docs.md
+```
+
+**Why:** Self-contained like Helm charts. No cross-schema dependencies. Each schema owns its templates.
+
+### 2. Resolution order (2 levels)
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
+2. <package>/schemas/<name>/schema.yaml                    # Built-in
+3. Error (not found)
+```
+
+**Why:** Simple mental model. User can override entire schema directory or just parts.
+
+### 3. Template path in schema.yaml
+
+The `template` field is relative to the schema's `templates/` directory:
+
+```yaml
+# schemas/spec-driven/schema.yaml
+artifacts:
+  - id: proposal
+    template: "proposal.md"  # → schemas/spec-driven/templates/proposal.md
+```
+
+**Why:** Paths are relative to the schema, not a global templates directory.
+
+### 4. Resolve package directory via import.meta.url
+
+```typescript
+function getPackageSchemasDir(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  // Navigate from src/core/artifact-graph/ to package root
+  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
+}
+```
+
+**Why:** Works in ESM. No hardcoded paths.
+
+### 5. Keep schema.yaml format unchanged
+
+The YAML format stays the same - only the storage location changes:
+
+```yaml
+name: spec-driven
+version: 1
+description: Specification-driven development
+artifacts:
+  - id: proposal
+    generates: "proposal.md"
+    template: "proposal.md"
+    requires: []
+```
+
+**Why:** No breaking changes to schema format. Just moving from TS to YAML files.
+
+## Migration
+
+1. Create `schemas/` directory at package root
+2. Convert `SPEC_DRIVEN_SCHEMA` to `schemas/spec-driven/schema.yaml`
+3. Convert `TDD_SCHEMA` to `schemas/tdd/schema.yaml`
+4. Update `resolveSchema()` to load from directories
+5. Remove `builtin-schemas.ts`
+6. Update `listSchemas()` to scan directories
+
+## Risks / Trade-offs
+
+**File I/O at runtime:**
+- Previously schemas were in-memory objects
+- Now requires reading YAML files
+- Mitigation: Schemas are small, loaded once per operation
+
+**Package distribution:**
+- Must ensure `schemas/` directory is included in npm package
+- Add to `files` in package.json
+
+## Open Questions
+
+None.
@@ -0,0 +1,20 @@
+## Why
+
+Currently, built-in schemas are embedded as TypeScript objects in `builtin-schemas.ts`. This works for schemas but doesn't support co-located templates. To enable self-contained schema packages (schema + templates together), we need to restructure schemas as directories.
+
+## What Changes
+
+- **BREAKING (internal):** Move built-in schemas from embedded TS objects to actual directory structure
+- Schemas become directories containing `schema.yaml` + `templates/`
+- Update `resolveSchema()` to load from directory structure
+- Remove `builtin-schemas.ts` (replaced by file-based schemas)
+- Update resolution to check user dir → package dir
+
+## Impact
+
+- Affected specs: `artifact-graph` (schema resolution changes)
+- Affected code:
+  - Remove `src/core/artifact-graph/builtin-schemas.ts`
+  - Update `src/core/artifact-graph/resolver.ts`
+  - Add `schemas/` directory at package root
+- No external API changes (resolution still returns `SchemaYaml`)
@@ -0,0 +1,49 @@
+## MODIFIED Requirements
+
+### Requirement: Schema Loading
+The system SHALL load artifact graph definitions from YAML schema files within schema directories.
+
+#### Scenario: Valid schema loaded
+- **WHEN** a schema directory contains a valid `schema.yaml` file
+- **THEN** the system returns an ArtifactGraph with all artifacts and dependencies
+
+#### Scenario: Invalid schema rejected
+- **WHEN** a schema YAML file is missing required fields
+- **THEN** the system throws an error with a descriptive message
+
+#### Scenario: Cyclic dependencies detected
+- **WHEN** a schema contains cyclic artifact dependencies
+- **THEN** the system throws an error listing the artifact IDs in the cycle
+
+#### Scenario: Invalid dependency reference
+- **WHEN** an artifact's `requires` array references a non-existent artifact ID
+- **THEN** the system throws an error identifying the invalid reference
+
+#### Scenario: Duplicate artifact IDs rejected
+- **WHEN** a schema contains multiple artifacts with the same ID
+- **THEN** the system throws an error identifying the duplicate
+
+#### Scenario: Schema directory not found
+- **WHEN** resolving a schema name that has no corresponding directory
+- **THEN** the system throws an error listing available schemas
+
+## ADDED Requirements
+
+### Requirement: Schema Directory Structure
+The system SHALL support self-contained schema directories with co-located templates.
+
+#### Scenario: Schema with templates
+- **WHEN** a schema directory contains `schema.yaml` and `templates/` subdirectory
+- **THEN** artifacts can reference templates relative to the schema's templates directory
+
+#### Scenario: User schema override
+- **WHEN** a schema directory exists at `${XDG_DATA_HOME}/openspec/schemas/<name>/`
+- **THEN** the system uses that directory instead of the built-in
+
+#### Scenario: Built-in schema fallback
+- **WHEN** no user override exists for a schema
+- **THEN** the system uses the package built-in schema directory
+
+#### Scenario: List available schemas
+- **WHEN** listing schemas
+- **THEN** the system returns schema names from both user and package directories
@@ -0,0 +1,32 @@
+## 1. Create Schema Directories
+
+- [ ] 1.1 Create `schemas/` directory at package root
+- [ ] 1.2 Create `schemas/spec-driven/schema.yaml` from `SPEC_DRIVEN_SCHEMA`
+- [ ] 1.3 Create `schemas/spec-driven/templates/` with placeholder templates
+- [ ] 1.4 Create `schemas/tdd/schema.yaml` from `TDD_SCHEMA`
+- [ ] 1.5 Create `schemas/tdd/templates/` with placeholder templates
+
+## 2. Update Schema Resolution
+
+- [ ] 2.1 Add `getPackageSchemasDir()` function using `import.meta.url`
+- [ ] 2.2 Add `getSchemaDir(name)` to resolve schema directory path
+- [ ] 2.3 Update `resolveSchema()` to load from directory structure
+- [ ] 2.4 Update `listSchemas()` to scan directories instead of object keys
+- [ ] 2.5 Add tests for user override resolution
+- [ ] 2.6 Add tests for built-in fallback
+
+## 3. Cleanup
+
+- [ ] 3.1 Remove `builtin-schemas.ts`
+- [ ] 3.2 Update `index.ts` exports (remove `BUILTIN_SCHEMAS`, `SPEC_DRIVEN_SCHEMA`, `TDD_SCHEMA`)
+- [ ] 3.3 Update any code that imports removed exports
+
+## 4. Package Distribution
+
+- [ ] 4.1 Add `schemas/` to `files` array in `package.json`
+- [ ] 4.2 Verify schemas are included in built package
+
+## 5. Fix Template Paths
+
+- [ ] 5.1 Update `template` field in schema.yaml files (remove `templates/` prefix)
+- [ ] 5.2 Ensure template paths are relative to schema's templates directory
@@ -0,0 +1,130 @@
+# artifact-graph Specification
+
+## Purpose
+TBD - created by archiving change add-artifact-graph-core. Update Purpose after archive.
+## Requirements
+### Requirement: Schema Loading
+The system SHALL load artifact graph definitions from YAML schema files within schema directories.
+
+#### Scenario: Valid schema loaded
+- **WHEN** a schema directory contains a valid `schema.yaml` file
+- **THEN** the system returns an ArtifactGraph with all artifacts and dependencies
+
+#### Scenario: Invalid schema rejected
+- **WHEN** a schema YAML file is missing required fields
+- **THEN** the system throws an error with a descriptive message
+
+#### Scenario: Cyclic dependencies detected
+- **WHEN** a schema contains cyclic artifact dependencies
+- **THEN** the system throws an error listing the artifact IDs in the cycle
+
+#### Scenario: Invalid dependency reference
+- **WHEN** an artifact's `requires` array references a non-existent artifact ID
+- **THEN** the system throws an error identifying the invalid reference
+
+#### Scenario: Duplicate artifact IDs rejected
+- **WHEN** a schema contains multiple artifacts with the same ID
+- **THEN** the system throws an error identifying the duplicate
+
+#### Scenario: Schema directory not found
+- **WHEN** resolving a schema name that has no corresponding directory
+- **THEN** the system throws an error listing available schemas
+
+### Requirement: Build Order Calculation
+The system SHALL compute a valid topological build order for artifacts.
+
+#### Scenario: Linear dependency chain
+- **WHEN** artifacts form a linear chain (A → B → C)
+- **THEN** getBuildOrder() returns [A, B, C]
+
+#### Scenario: Diamond dependency
+- **WHEN** artifacts form a diamond (A → B, A → C, B → D, C → D)
+- **THEN** getBuildOrder() returns A before B and C, and D last
+
+#### Scenario: Independent artifacts
+- **WHEN** artifacts have no dependencies
+- **THEN** getBuildOrder() returns them in a stable order
+
+### Requirement: State Detection
+The system SHALL detect artifact completion state by scanning the filesystem.
+
+#### Scenario: Simple file exists
+- **WHEN** an artifact generates "proposal.md" and the file exists
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Simple file missing
+- **WHEN** an artifact generates "proposal.md" and the file does not exist
+- **THEN** the artifact is not marked as completed
+
+#### Scenario: Glob pattern with files
+- **WHEN** an artifact generates "specs/*.md" and the specs/ directory contains .md files
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Glob pattern empty
+- **WHEN** an artifact generates "specs/*.md" and the specs/ directory is empty or missing
+- **THEN** the artifact is not marked as completed
+
+#### Scenario: Missing change directory
+- **WHEN** the change directory does not exist
+- **THEN** all artifacts are marked as not completed (empty state)
+
+### Requirement: Ready Artifact Query
+The system SHALL identify which artifacts are ready to be created based on dependency completion.
+
+#### Scenario: Root artifacts ready initially
+- **WHEN** no artifacts are completed
+- **THEN** getNextArtifacts() returns artifacts with no dependencies
+
+#### Scenario: Dependent artifact becomes ready
+- **WHEN** an artifact's dependencies are all completed
+- **THEN** getNextArtifacts() includes that artifact
+
+#### Scenario: Blocked artifacts excluded
+- **WHEN** an artifact has uncompleted dependencies
+- **THEN** getNextArtifacts() does not include that artifact
+
+### Requirement: Completion Check
+The system SHALL determine when all artifacts in a graph are complete.
+
+#### Scenario: All complete
+- **WHEN** all artifacts in the graph are in the completed set
+- **THEN** isComplete() returns true
+
+#### Scenario: Partially complete
+- **WHEN** some artifacts in the graph are not completed
+- **THEN** isComplete() returns false
+
+### Requirement: Blocked Query
+The system SHALL identify which artifacts are blocked and return all their unmet dependencies.
+
+#### Scenario: Artifact blocked by single dependency
+- **WHEN** artifact B requires artifact A and A is not complete
+- **THEN** getBlocked() returns `{ B: ['A'] }`
+
+#### Scenario: Artifact blocked by multiple dependencies
+- **WHEN** artifact C requires A and B, and only A is complete
+- **THEN** getBlocked() returns `{ C: ['B'] }`
+
+#### Scenario: Artifact blocked by all dependencies
+- **WHEN** artifact C requires A and B, and neither is complete
+- **THEN** getBlocked() returns `{ C: ['A', 'B'] }`
+
+### Requirement: Schema Directory Structure
+The system SHALL support self-contained schema directories with co-located templates.
+
+#### Scenario: Schema with templates
+- **WHEN** a schema directory contains `schema.yaml` and `templates/` subdirectory
+- **THEN** artifacts can reference templates relative to the schema's templates directory
+
+#### Scenario: User schema override
+- **WHEN** a schema directory exists at `${XDG_DATA_HOME}/openspec/schemas/<name>/`
+- **THEN** the system uses that directory instead of the built-in
+
+#### Scenario: Built-in schema fallback
+- **WHEN** no user override exists for a schema
+- **THEN** the system uses the package built-in schema directory
+
+#### Scenario: List available schemas
+- **WHEN** listing schemas
+- **THEN** the system returns schema names from both user and package directories
+
@@ -0,0 +1,67 @@
+# change-creation Specification
+
+## Purpose
+Provide programmatic utilities for creating and validating OpenSpec change directories.
+## Requirements
+### Requirement: Change Creation
+The system SHALL provide a function to create new change directories programmatically.
+
+#### Scenario: Create change
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called
+- **THEN** the system creates `openspec/changes/add-auth/` directory
+
+#### Scenario: Duplicate change rejected
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/add-auth/` already exists
+- **THEN** the system throws an error indicating the change already exists
+
+#### Scenario: Creates parent directories if needed
+- **WHEN** `createChange(projectRoot, 'add-auth')` is called and `openspec/changes/` does not exist
+- **THEN** the system creates the full path including parent directories
+
+#### Scenario: Invalid change name rejected
+- **WHEN** `createChange(projectRoot, 'Add Auth')` is called with an invalid name
+- **THEN** the system throws a validation error
+
+### Requirement: Change Name Validation
+The system SHALL validate change names follow kebab-case conventions.
+
+#### Scenario: Valid kebab-case name accepted
+- **WHEN** a change name like `add-user-auth` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Numeric suffixes accepted
+- **WHEN** a change name like `add-feature-2` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Single word accepted
+- **WHEN** a change name like `refactor` is validated
+- **THEN** validation returns `{ valid: true }`
+
+#### Scenario: Uppercase characters rejected
+- **WHEN** a change name like `Add-Auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Spaces rejected
+- **WHEN** a change name like `add auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Underscores rejected
+- **WHEN** a change name like `add_auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Special characters rejected
+- **WHEN** a change name like `add-auth!` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Leading hyphen rejected
+- **WHEN** a change name like `-add-auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Trailing hyphen rejected
+- **WHEN** a change name like `add-auth-` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
+#### Scenario: Consecutive hyphens rejected
+- **WHEN** a change name like `add--auth` is validated
+- **THEN** validation returns `{ valid: false, error: "..." }`
+
@@ -0,0 +1,287 @@
+# cli-completion Specification
+
+## Purpose
+Provide shell completion scripts for the OpenSpec CLI, enabling tab-completion for commands, flags, and dynamic values (change IDs, spec IDs) in supported shells. Currently supports Zsh with architecture designed for future shell expansion.
+## Requirements
+### Requirement: Native Shell Behavior Integration
+
+The completion system SHALL respect and integrate with Zsh's native completion patterns and user interaction model.
+
+#### Scenario: Zsh native completion
+
+- **WHEN** generating Zsh completion scripts
+- **THEN** use Zsh completion system with `_arguments`, `_describe`, and `compadd`
+- **AND** completions SHALL trigger on single TAB (standard Zsh behavior)
+- **AND** display as an interactive menu that users navigate with TAB/arrow keys
+- **AND** support Oh My Zsh's enhanced menu styling automatically
+
+#### Scenario: No custom UX patterns
+
+- **WHEN** implementing Zsh completion
+- **THEN** do NOT attempt to customize completion trigger behavior
+- **AND** do NOT override Zsh-specific navigation patterns
+- **AND** ensure completions feel native to experienced Zsh users
+
+### Requirement: Command Structure
+
+The completion command SHALL follow a subcommand pattern for generating and managing completion scripts.
+
+#### Scenario: Available subcommands
+
+- **WHEN** user executes `openspec completion --help`
+- **THEN** display available subcommands:
+  - `generate [shell]` - Generate completion script for a shell (outputs to stdout)
+  - `install [shell]` - Install completion for Zsh (auto-detects or requires explicit shell)
+  - `uninstall [shell]` - Remove completion for Zsh (auto-detects or requires explicit shell)
+
+### Requirement: Shell Detection
+
+The completion system SHALL automatically detect the user's current shell environment.
+
+#### Scenario: Detecting Zsh from environment
+
+- **WHEN** no shell is explicitly specified
+- **THEN** read the `$SHELL` environment variable
+- **AND** extract the shell name from the path (e.g., `/bin/zsh` → `zsh`)
+- **AND** validate the shell is `zsh`
+- **AND** throw an error if the shell is not `zsh`, with message indicating only Zsh is currently supported
+
+#### Scenario: Non-Zsh shell detection
+
+- **WHEN** shell path indicates bash, fish, powershell, or other non-Zsh shell
+- **THEN** throw error: "Shell '<name>' is not supported yet. Currently supported: zsh"
+
+### Requirement: Completion Generation
+
+The completion command SHALL generate Zsh completion scripts on demand.
+
+#### Scenario: Generating Zsh completion
+
+- **WHEN** user executes `openspec completion generate zsh`
+- **THEN** output a complete Zsh completion script to stdout
+- **AND** include completions for all commands: init, list, show, validate, archive, view, update, change, spec, completion
+- **AND** include all command-specific flags and options
+- **AND** use Zsh's `_arguments` and `_describe` built-in functions
+- **AND** support dynamic completion for change and spec IDs
+
+### Requirement: Dynamic Completions
+
+The completion system SHALL provide context-aware dynamic completions for project-specific values.
+
+#### Scenario: Completing change IDs
+
+- **WHEN** completing arguments for commands that accept change names (show, validate, archive)
+- **THEN** discover active changes from `openspec/changes/` directory
+- **AND** exclude archived changes in `openspec/changes/archive/`
+- **AND** return change IDs as completion suggestions
+- **AND** only provide suggestions when inside an OpenSpec-enabled project
+
+#### Scenario: Completing spec IDs
+
+- **WHEN** completing arguments for commands that accept spec names (show, validate)
+- **THEN** discover specs from `openspec/specs/` directory
+- **AND** return spec IDs as completion suggestions
+- **AND** only provide suggestions when inside an OpenSpec-enabled project
+
+#### Scenario: Completion caching
+
+- **WHEN** dynamic completions are requested
+- **THEN** cache discovered change and spec IDs for 2 seconds
+- **AND** reuse cached values for subsequent requests within cache window
+- **AND** automatically refresh cache after expiration
+
+#### Scenario: Project detection
+
+- **WHEN** user requests completions outside an OpenSpec project
+- **THEN** skip dynamic change/spec ID completions
+- **AND** only suggest static commands and flags
+
+### Requirement: Installation Automation
+
+The completion command SHALL automatically install completion scripts into shell configuration files.
+
+#### Scenario: Installing for Oh My Zsh
+
+- **WHEN** user executes `openspec completion install zsh`
+- **THEN** detect if Oh My Zsh is installed by checking for `$ZSH` environment variable or `~/.oh-my-zsh/` directory
+- **AND** create custom completions directory at `~/.oh-my-zsh/custom/completions/` if it doesn't exist
+- **AND** write completion script to `~/.oh-my-zsh/custom/completions/_openspec`
+- **AND** ensure `~/.oh-my-zsh/custom/completions` is in `$fpath` by updating `~/.zshrc` if needed
+- **AND** display success message with instruction to run `exec zsh` or restart terminal
+
+#### Scenario: Installing for standard Zsh
+
+- **WHEN** user executes `openspec completion install zsh` and Oh My Zsh is not detected
+- **THEN** create completions directory at `~/.zsh/completions/` if it doesn't exist
+- **AND** write completion script to `~/.zsh/completions/_openspec`
+- **AND** add `fpath=(~/.zsh/completions $fpath)` to `~/.zshrc` if not already present
+- **AND** add `autoload -Uz compinit && compinit` to `~/.zshrc` if not already present
+- **AND** display success message with instruction to run `exec zsh` or restart terminal
+
+#### Scenario: Auto-detecting Zsh for installation
+
+- **WHEN** user executes `openspec completion install` without specifying a shell
+- **THEN** detect current shell using shell detection logic
+- **AND** install completion if detected shell is Zsh
+- **AND** throw error if detected shell is not Zsh
+- **AND** display which shell was detected
+
+#### Scenario: Already installed
+
+- **WHEN** completion is already installed for the target shell
+- **THEN** display message indicating completion is already installed
+- **AND** offer to reinstall/update by overwriting existing files
+- **AND** exit with code 0
+
+### Requirement: Uninstallation
+
+The completion command SHALL remove installed completion scripts and configuration.
+
+#### Scenario: Uninstalling Oh My Zsh completion
+
+- **WHEN** user executes `openspec completion uninstall zsh`
+- **THEN** prompt for confirmation before proceeding (unless `--yes` flag provided)
+- **AND** if user declines, cancel uninstall and display "Uninstall cancelled."
+- **AND** if user confirms, remove `~/.oh-my-zsh/custom/completions/_openspec` if Oh My Zsh is detected
+- **AND** remove `~/.zsh/completions/_openspec` if standard Zsh setup is detected
+- **AND** remove fpath modifications from `~/.zshrc`
+- **AND** display success message
+
+#### Scenario: Auto-detecting Zsh for uninstallation
+
+- **WHEN** user executes `openspec completion uninstall` without specifying a shell
+- **THEN** detect current shell and uninstall completion if shell is Zsh
+- **AND** throw error if detected shell is not Zsh
+
+#### Scenario: Not installed
+
+- **WHEN** attempting to uninstall completion that isn't installed
+- **THEN** display error message indicating completion is not installed
+- **AND** exit with code 1
+
+### Requirement: Architecture Patterns
+
+The completion implementation SHALL follow clean architecture principles with TypeScript best practices.
+
+#### Scenario: Shell-specific generators
+
+- **WHEN** implementing completion generators
+- **THEN** create `ZshCompletionGenerator` class for Zsh
+- **AND** implement a common `CompletionGenerator` interface with methods:
+  - `generate(): string` - Returns complete shell script
+  - `getInstallPath(): string` - Returns target installation path
+  - `getConfigFile(): string` - Returns shell configuration file path
+- **AND** design interface to be extensible for future shells (bash, fish, powershell)
+
+#### Scenario: Dynamic completion providers
+
+- **WHEN** implementing dynamic completions
+- **THEN** create a `CompletionProvider` class that encapsulates project discovery logic
+- **AND** implement methods:
+  - `getChangeIds(): Promise<string[]>` - Discovers active change IDs
+  - `getSpecIds(): Promise<string[]>` - Discovers spec IDs
+  - `isOpenSpecProject(): boolean` - Checks if current directory is OpenSpec-enabled
+- **AND** implement caching with 2-second TTL using class properties
+
+#### Scenario: Command registry
+
+- **WHEN** defining completable commands
+- **THEN** create a centralized `CommandDefinition` type with properties:
+  - `name: string` - Command name
+  - `description: string` - Help text
+  - `flags: FlagDefinition[]` - Available flags
+  - `acceptsChangeId: boolean` - Whether command takes change ID argument
+  - `acceptsSpecId: boolean` - Whether command takes spec ID argument
+  - `subcommands?: CommandDefinition[]` - Nested subcommands
+- **AND** export a `COMMAND_REGISTRY` constant with all command definitions
+- **AND** generators consume this registry to ensure consistency
+
+#### Scenario: Type-safe shell detection
+
+- **WHEN** implementing shell detection
+- **THEN** define a `SupportedShell` type as literal type: `'zsh'`
+- **AND** implement `detectShell()` function that returns 'zsh' or throws error
+- **AND** design type to be extensible (e.g., future: `'bash' | 'zsh' | 'fish' | 'powershell'`)
+
+### Requirement: Error Handling
+
+The completion command SHALL provide clear error messages for common failure scenarios.
+
+#### Scenario: Unsupported shell
+
+- **WHEN** user requests completion for unsupported shell (bash, fish, powershell, etc.)
+- **THEN** display error message: "Shell '<name>' is not supported yet. Currently supported: zsh"
+- **AND** exit with code 1
+
+#### Scenario: Permission errors during installation
+
+- **WHEN** installation fails due to file permission issues
+- **THEN** display clear error message indicating permission problem
+- **AND** suggest using appropriate permissions or alternative installation method
+- **AND** exit with code 1
+
+#### Scenario: Missing shell configuration directory
+
+- **WHEN** expected shell configuration directory doesn't exist
+- **THEN** create the directory automatically (with user notification)
+- **AND** proceed with installation
+
+#### Scenario: Shell not detected
+
+- **WHEN** `openspec completion install` cannot detect current shell or detects non-Zsh shell
+- **THEN** display error: "Could not auto-detect shell. Please specify shell explicitly."
+- **AND** display usage hint: "Usage: openspec completion <operation> [shell]"
+- **AND** exit with code 1
+
+### Requirement: Output Format
+
+The completion command SHALL provide machine-parseable and human-readable output.
+
+#### Scenario: Script generation output
+
+- **WHEN** generating completion script to stdout
+- **THEN** output only the completion script content (no extra messages)
+- **AND** allow redirection to files: `openspec completion generate zsh > /path/to/_openspec`
+
+#### Scenario: Installation success output
+
+- **WHEN** installation completes successfully
+- **THEN** display formatted success message with:
+  - Checkmark indicator
+  - Installation location
+  - Next steps (shell reload instructions)
+- **AND** use colors when terminal supports it (unless `--no-color` is set)
+
+#### Scenario: Verbose installation output
+
+- **WHEN** user provides `--verbose` flag during installation
+- **THEN** display detailed steps:
+  - Shell detection result
+  - Target file paths
+  - Configuration modifications
+  - File creation confirmations
+
+### Requirement: Testing Support
+
+The completion implementation SHALL be testable with unit and integration tests.
+
+#### Scenario: Mock shell environment
+
+- **WHEN** writing tests for shell detection
+- **THEN** allow overriding `$SHELL` environment variable
+- **AND** use dependency injection for file system operations
+
+#### Scenario: Generator output verification
+
+- **WHEN** testing completion generators
+- **THEN** verify generated scripts contain expected patterns
+- **AND** test that command registry is properly consumed
+- **AND** ensure dynamic completion placeholders are present
+
+#### Scenario: Installation simulation
+
+- **WHEN** testing installation logic
+- **THEN** use temporary test directories instead of actual home directories
+- **AND** verify file creation without modifying real shell configurations
+- **AND** test path resolution logic independently
+
@@ -0,0 +1,217 @@
+# cli-config Specification
+
+## Purpose
+Provide a user-friendly CLI interface for viewing and modifying global OpenSpec configuration settings without manually editing JSON files.
+## Requirements
+### Requirement: Command Structure
+
+The config command SHALL provide subcommands for all configuration operations.
+
+#### Scenario: Available subcommands
+
+- **WHEN** user executes `openspec config --help`
+- **THEN** display available subcommands:
+  - `path` - Show config file location
+  - `list` - Show all current settings
+  - `get <key>` - Get a specific value
+  - `set <key> <value>` - Set a value
+  - `unset <key>` - Remove a key (revert to default)
+  - `reset` - Reset configuration to defaults
+  - `edit` - Open config in editor
+
+### Requirement: Config Path
+
+The config command SHALL display the config file location.
+
+#### Scenario: Show config path
+
+- **WHEN** user executes `openspec config path`
+- **THEN** print the absolute path to the config file
+- **AND** exit with code 0
+
+### Requirement: Config List
+
+The config command SHALL display all current configuration values.
+
+#### Scenario: List config in human-readable format
+
+- **WHEN** user executes `openspec config list`
+- **THEN** display all config values in YAML-like format
+- **AND** show nested objects with indentation
+
+#### Scenario: List config as JSON
+
+- **WHEN** user executes `openspec config list --json`
+- **THEN** output the complete config as valid JSON
+- **AND** output only JSON (no additional text)
+
+### Requirement: Config Get
+
+The config command SHALL retrieve specific configuration values.
+
+#### Scenario: Get top-level key
+
+- **WHEN** user executes `openspec config get <key>` with a valid top-level key
+- **THEN** print the raw value only (no labels or formatting)
+- **AND** exit with code 0
+
+#### Scenario: Get nested key with dot notation
+
+- **WHEN** user executes `openspec config get featureFlags.someFlag`
+- **THEN** traverse the nested structure using dot notation
+- **AND** print the value at that path
+
+#### Scenario: Get non-existent key
+
+- **WHEN** user executes `openspec config get <key>` with a key that does not exist
+- **THEN** print nothing (empty output)
+- **AND** exit with code 1
+
+#### Scenario: Get object value
+
+- **WHEN** user executes `openspec config get <key>` where the value is an object
+- **THEN** print the object as JSON
+
+### Requirement: Config Set
+
+The config command SHALL set configuration values with automatic type coercion.
+
+#### Scenario: Set string value
+
+- **WHEN** user executes `openspec config set <key> <value>`
+- **AND** value does not match boolean or number patterns
+- **THEN** store value as a string
+- **AND** display confirmation message
+
+#### Scenario: Set boolean value
+
+- **WHEN** user executes `openspec config set <key> true` or `openspec config set <key> false`
+- **THEN** store value as boolean (not string)
+- **AND** display confirmation message
+
+#### Scenario: Set numeric value
+
+- **WHEN** user executes `openspec config set <key> <value>`
+- **AND** value is a valid number (integer or float)
+- **THEN** store value as number (not string)
+
+#### Scenario: Force string with --string flag
+
+- **WHEN** user executes `openspec config set <key> <value> --string`
+- **THEN** store value as string regardless of content
+- **AND** this allows storing literal "true" or "123" as strings
+
+#### Scenario: Set nested key
+
+- **WHEN** user executes `openspec config set featureFlags.newFlag true`
+- **THEN** create intermediate objects if they don't exist
+- **AND** set the value at the nested path
+
+### Requirement: Config Unset
+
+The config command SHALL remove configuration overrides.
+
+#### Scenario: Unset existing key
+
+- **WHEN** user executes `openspec config unset <key>`
+- **AND** the key exists in the config
+- **THEN** remove the key from the config file
+- **AND** the value reverts to its default
+- **AND** display confirmation message
+
+#### Scenario: Unset non-existent key
+
+- **WHEN** user executes `openspec config unset <key>`
+- **AND** the key does not exist in the config
+- **THEN** display message indicating key was not set
+- **AND** exit with code 0
+
+### Requirement: Config Reset
+
+The config command SHALL reset configuration to defaults.
+
+#### Scenario: Reset all with confirmation
+
+- **WHEN** user executes `openspec config reset --all`
+- **THEN** prompt for confirmation before proceeding
+- **AND** if confirmed, delete the config file or reset to defaults
+- **AND** display confirmation message
+
+#### Scenario: Reset all with -y flag
+
+- **WHEN** user executes `openspec config reset --all -y`
+- **THEN** reset without prompting for confirmation
+
+#### Scenario: Reset without --all flag
+
+- **WHEN** user executes `openspec config reset` without `--all`
+- **THEN** display error indicating `--all` is required
+- **AND** exit with code 1
+
+### Requirement: Config Edit
+
+The config command SHALL open the config file in the user's editor.
+
+#### Scenario: Open editor successfully
+
+- **WHEN** user executes `openspec config edit`
+- **AND** `$EDITOR` or `$VISUAL` environment variable is set
+- **THEN** open the config file in that editor
+- **AND** create the config file with defaults if it doesn't exist
+- **AND** wait for the editor to close before returning
+
+#### Scenario: No editor configured
+
+- **WHEN** user executes `openspec config edit`
+- **AND** neither `$EDITOR` nor `$VISUAL` is set
+- **THEN** display error message suggesting to set `$EDITOR`
+- **AND** exit with code 1
+
+### Requirement: Key Naming Convention
+
+The config command SHALL use camelCase keys matching the JSON structure.
+
+#### Scenario: Keys match JSON structure
+
+- **WHEN** accessing configuration keys via CLI
+- **THEN** use camelCase matching the actual JSON property names
+- **AND** support dot notation for nested access (e.g., `featureFlags.someFlag`)
+
+### Requirement: Schema Validation
+
+The config command SHALL validate configuration writes against the config schema using zod, while rejecting unknown keys for `config set` unless explicitly overridden.
+
+#### Scenario: Unknown key rejected by default
+
+- **WHEN** user executes `openspec config set someFutureKey 123`
+- **THEN** display a descriptive error message indicating the key is invalid
+- **AND** do not modify the config file
+- **AND** exit with code 1
+
+#### Scenario: Unknown key accepted with override
+
+- **WHEN** user executes `openspec config set someFutureKey 123 --allow-unknown`
+- **THEN** the value is saved successfully
+- **AND** exit with code 0
+
+#### Scenario: Invalid feature flag value rejected
+
+- **WHEN** user executes `openspec config set featureFlags.someFlag notABoolean`
+- **THEN** display a descriptive error message
+- **AND** do not modify the config file
+- **AND** exit with code 1
+
+### Requirement: Reserved Scope Flag
+
+The config command SHALL reserve the `--scope` flag for future extensibility.
+
+#### Scenario: Scope flag defaults to global
+
+- **WHEN** user executes any config command without `--scope`
+- **THEN** operate on global configuration (default behavior)
+
+#### Scenario: Project scope not yet implemented
+
+- **WHEN** user executes `openspec config --scope project <subcommand>`
+- **THEN** display error message: "Project-local config is not yet implemented"
+- **AND** exit with code 1
@@ -0,0 +1,81 @@
+# global-config Specification
+
+## Purpose
+
+This spec defines how OpenSpec resolves, reads, and writes user-level global configuration. It governs the `src/core/global-config.ts` module, which provides the foundation for storing user preferences, feature flags, and settings that persist across projects. The spec ensures cross-platform compatibility by following XDG Base Directory Specification with platform-specific fallbacks, and guarantees forward/backward compatibility through schema evolution rules.
+## Requirements
+### Requirement: Global Config Directory Path
+
+The system SHALL resolve the global configuration directory path following XDG Base Directory Specification with platform-specific fallbacks.
+
+#### Scenario: Unix/macOS with XDG_CONFIG_HOME set
+- **WHEN** `$XDG_CONFIG_HOME` environment variable is set to `/custom/config`
+- **THEN** `getGlobalConfigDir()` returns `/custom/config/openspec`
+
+#### Scenario: Unix/macOS without XDG_CONFIG_HOME
+- **WHEN** `$XDG_CONFIG_HOME` environment variable is not set
+- **AND** the platform is Unix or macOS
+- **THEN** `getGlobalConfigDir()` returns `~/.config/openspec` (expanded to absolute path)
+
+#### Scenario: Windows platform
+- **WHEN** the platform is Windows
+- **AND** `%APPDATA%` is set to `C:\Users\User\AppData\Roaming`
+- **THEN** `getGlobalConfigDir()` returns `C:\Users\User\AppData\Roaming\openspec`
+
+### Requirement: Global Config Loading
+
+The system SHALL load global configuration from the config directory with sensible defaults when the config file does not exist or cannot be parsed.
+
+#### Scenario: Config file exists and is valid
+- **WHEN** `config.json` exists in the global config directory
+- **AND** the file contains valid JSON matching the config schema
+- **THEN** `getGlobalConfig()` returns the parsed configuration
+
+#### Scenario: Config file does not exist
+- **WHEN** `config.json` does not exist in the global config directory
+- **THEN** `getGlobalConfig()` returns the default configuration
+- **AND** no directory or file is created
+
+#### Scenario: Config file is invalid JSON
+- **WHEN** `config.json` exists but contains invalid JSON
+- **THEN** `getGlobalConfig()` returns the default configuration
+- **AND** a warning is logged to stderr
+
+### Requirement: Global Config Saving
+
+The system SHALL save global configuration to the config directory, creating the directory if it does not exist.
+
+#### Scenario: Save config to new directory
+- **WHEN** `saveGlobalConfig(config)` is called
+- **AND** the global config directory does not exist
+- **THEN** the directory is created
+- **AND** `config.json` is written with the provided configuration
+
+#### Scenario: Save config to existing directory
+- **WHEN** `saveGlobalConfig(config)` is called
+- **AND** the global config directory already exists
+- **THEN** `config.json` is written (overwriting if exists)
+
+### Requirement: Default Configuration
+
+The system SHALL provide a default configuration that is used when no config file exists.
+
+#### Scenario: Default config structure
+- **WHEN** no config file exists
+- **THEN** the default configuration includes an empty `featureFlags` object
+
+### Requirement: Config Schema Evolution
+
+The system SHALL merge loaded configuration with default values to ensure new config fields are available even when loading older config files.
+
+#### Scenario: Config file missing new fields
+- **WHEN** `config.json` exists with `{ "featureFlags": {} }`
+- **AND** the current schema includes a new field `defaultAiTool`
+- **THEN** `getGlobalConfig()` returns `{ featureFlags: {}, defaultAiTool: <default> }`
+- **AND** the loaded values take precedence over defaults for fields that exist in both
+
+#### Scenario: Config file has extra unknown fields
+- **WHEN** `config.json` contains fields not in the current schema
+- **THEN** the unknown fields are preserved in the returned configuration
+- **AND** no error or warning is raised
+
@@ -0,0 +1,70 @@
+# instruction-loader Specification
+
+## Purpose
+The instruction-loader loads instruction templates from schema directories, validates and enriches them with metadata and parameters (such as change context and dependency status), and exposes them for use by downstream services including template retrieval, parameter substitution, and enrichment.
+
+## Requirements
+### Requirement: Template Loading
+The system SHALL load templates from schema directories.
+
+#### Scenario: Load template from schema directory
+- **WHEN** `loadTemplate(schemaName, templatePath)` is called
+- **THEN** the system loads the template from `schemas/<schemaName>/templates/<templatePath>`
+
+#### Scenario: Template file not found
+- **WHEN** a template file does not exist in the schema's templates directory
+- **THEN** the system throws an error with the template path
+
+### Requirement: Change Context Loading
+The system SHALL load change context combining graph and completion state.
+
+#### Scenario: Load context for existing change
+- **WHEN** `loadChangeContext(projectRoot, changeName)` is called for an existing change
+- **THEN** the system returns a context with graph, completed set, schema name, and change info
+
+#### Scenario: Load context with custom schema
+- **WHEN** `loadChangeContext(projectRoot, changeName, schemaName)` is called
+- **THEN** the system uses the specified schema instead of default
+
+#### Scenario: Load context for non-existent change directory
+- **WHEN** `loadChangeContext` is called for a non-existent change directory
+- **THEN** the system returns context with empty completed set
+
+### Requirement: Template Enrichment
+The system SHALL enrich templates with change-specific context.
+
+#### Scenario: Include artifact metadata
+- **WHEN** instructions are generated for an artifact
+- **THEN** the output includes change name, artifact ID, schema name, and output path
+
+#### Scenario: Include dependency status
+- **WHEN** an artifact has dependencies
+- **THEN** the output shows each dependency with completion status (done/missing)
+
+#### Scenario: Include unlocked artifacts
+- **WHEN** instructions are generated
+- **THEN** the output includes which artifacts become available after this one
+
+#### Scenario: Root artifact indicator
+- **WHEN** an artifact has no dependencies
+- **THEN** the dependency section indicates this is a root artifact
+
+### Requirement: Status Formatting
+The system SHALL format change status as readable output.
+
+#### Scenario: All artifacts completed
+- **WHEN** all artifacts are completed
+- **THEN** status shows all artifacts as "done"
+
+#### Scenario: Mixed completion status
+- **WHEN** some artifacts are completed
+- **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"
+
+#### Scenario: Blocked artifact details
+- **WHEN** an artifact is blocked
+- **THEN** status shows which dependencies are missing
+
+#### Scenario: Include output paths
+- **WHEN** status is formatted
+- **THEN** each artifact shows its output path pattern
+
@@ -1,6 +1,6 @@
 {
  "name": "@fission-ai/openspec",
-  "version": "0.16.0",
+  "version": "0.17.2",
  "description": "AI-native system for spec-driven development",
  "keywords": [
    "openspec",
@@ -32,11 +32,14 @@
  "files": [
    "dist",
    "bin",
+    "schemas",
+    "scripts/postinstall.js",
    "!dist/**/*.test.js",
    "!dist/**/__tests__",
    "!dist/**/*.map"
  ],
  "scripts": {
+    "lint": "eslint src/",
    "build": "node build.js",
    "dev": "tsc --watch",
    "dev:cli": "pnpm build && node bin/openspec.js",
@@ -44,8 +47,10 @@
    "test:watch": "vitest",
    "test:ui": "vitest --ui",
    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
    "prepare": "pnpm run build",
    "prepublishOnly": "pnpm run build",
+    "postinstall": "node scripts/postinstall.js",
    "check:pack-version": "node scripts/pack-version-check.mjs",
    "release": "pnpm run release:ci",
    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
@@ -59,7 +64,9 @@
    "@changesets/cli": "^2.27.7",
    "@types/node": "^24.2.0",
    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.39.2",
    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
    "vitest": "^3.2.4"
  },
  "dependencies": {
@@ -67,7 +74,9 @@
    "@inquirer/prompts": "^7.8.0",
    "chalk": "^5.5.0",
    "commander": "^14.0.0",
+    "fast-glob": "^3.3.3",
    "ora": "^8.2.0",
+    "yaml": "^2.8.2",
    "zod": "^4.0.17"
  }
 }
@@ -0,0 +1,28 @@
+name: spec-driven
+version: 1
+description: Default OpenSpec workflow - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    requires: []
+  - id: specs
+    generates: "specs/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    requires:
+      - proposal
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    requires:
+      - proposal
+  - id: tasks
+    generates: tasks.md
+    description: Implementation tasks derived from specs and design
+    template: tasks.md
+    requires:
+      - specs
+      - design
@@ -0,0 +1,19 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->
@@ -0,0 +1,11 @@
+## Why
+
+<!-- Explain the motivation for this change -->
+
+## What Changes
+
+<!-- Describe what will change -->
+
+## Impact
+
+<!-- List affected areas -->
@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->
@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->
@@ -0,0 +1,27 @@
+name: tdd
+version: 1
+description: Test-driven development workflow - tests → implementation → docs
+artifacts:
+  - id: spec
+    generates: spec.md
+    description: Feature specification defining requirements
+    template: spec.md
+    requires: []
+  - id: tests
+    generates: "tests/*.test.ts"
+    description: Test files written before implementation
+    template: test.md
+    requires:
+      - spec
+  - id: implementation
+    generates: "src/*.ts"
+    description: Implementation code to pass the tests
+    template: implementation.md
+    requires:
+      - tests
+  - id: docs
+    generates: "docs/*.md"
+    description: Documentation for the implemented feature
+    template: docs.md
+    requires:
+      - implementation
@@ -0,0 +1,15 @@
+## Overview
+
+<!-- Feature overview -->
+
+## Getting Started
+
+<!-- Quick start guide -->
+
+## Examples
+
+<!-- Code examples -->
+
+## Reference
+
+<!-- API reference or additional details -->
@@ -0,0 +1,11 @@
+## Implementation Notes
+
+<!-- Technical implementation details -->
+
+## API
+
+<!-- Public API documentation -->
+
+## Usage
+
+<!-- Usage examples -->
@@ -0,0 +1,11 @@
+## Feature: <!-- feature name -->
+
+<!-- Feature description -->
+
+## Requirements
+
+<!-- List of requirements -->
+
+## Acceptance Criteria
+
+<!-- List of acceptance criteria -->
@@ -0,0 +1,11 @@
+## Test Plan
+
+<!-- Describe the testing strategy -->
+
+## Test Cases
+
+### <!-- Test case name -->
+
+- **Given:** <!-- preconditions -->
+- **When:** <!-- action -->
+- **Then:** <!-- expected result -->
@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for auto-installing shell completions
+ *
+ * This script runs automatically after npm install unless:
+ * - CI=true environment variable is set
+ * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ *
+ * The script never fails npm install - all errors are caught and handled gracefully.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Check if we should skip installation
+ */
+function shouldSkipInstallation() {
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { skip: true, reason: 'CI environment detected' };
+  }
+
+  // Skip if user opted out
+  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
+    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
+  }
+
+  return { skip: false };
+}
+
+/**
+ * Check if dist/ directory exists
+ */
+async function distExists() {
+  const distPath = path.join(__dirname, '..', 'dist');
+  try {
+    const stat = await fs.stat(distPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the user's shell
+ */
+async function detectShell() {
+  try {
+    const { detectShell } = await import('../dist/utils/shell-detection.js');
+    const result = detectShell();
+    return result.shell;
+  } catch (error) {
+    // Fail silently if detection module doesn't exist
+    return undefined;
+  }
+}
+
+/**
+ * Install completions for the detected shell
+ */
+async function installCompletions(shell) {
+  try {
+    const { CompletionFactory } = await import('../dist/core/completions/factory.js');
+    const { COMMAND_REGISTRY } = await import('../dist/core/completions/command-registry.js');
+
+    // Check if shell is supported
+    if (!CompletionFactory.isSupported(shell)) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Generate completion script
+    const generator = CompletionFactory.createGenerator(shell);
+    const script = generator.generate(COMMAND_REGISTRY);
+
+    // Install completion script
+    const installer = CompletionFactory.createInstaller(shell);
+    const result = await installer.install(script);
+
+    if (result.success) {
+      // Show success message based on installation type
+      if (result.isOhMyZsh) {
+        console.log(`✓ Shell completions installed`);
+        console.log(`  Restart shell: exec zsh`);
+      } else if (result.zshrcConfigured) {
+        console.log(`✓ Shell completions installed and configured`);
+        console.log(`  Restart shell: exec zsh`);
+      } else {
+        console.log(`✓ Shell completions installed to ~/.zsh/completions/`);
+        console.log(`  Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)`);
+        console.log(`  Then: exec zsh`);
+      }
+    } else {
+      // Installation failed, show tip for manual install
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+    }
+  } catch (error) {
+    // Fail gracefully - show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    // Check if we should skip
+    const skipCheck = shouldSkipInstallation();
+    if (skipCheck.skip) {
+      // Silent skip - no output
+      return;
+    }
+
+    // Check if dist/ exists (skip silently if not - expected during dev setup)
+    if (!(await distExists())) {
+      return;
+    }
+
+    // Detect shell
+    const shell = await detectShell();
+    if (!shell) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Install completions
+    await installCompletions(shell);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+    // Show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});
@@ -0,0 +1,57 @@
+#!/bin/bash
+
+# Test script for postinstall.js
+# Tests different scenarios: normal install, CI, opt-out
+
+set -e
+
+echo "======================================"
+echo "Testing OpenSpec Postinstall Script"
+echo "======================================"
+echo ""
+
+# Save original environment
+ORIGINAL_CI="${CI:-}"
+ORIGINAL_OPENSPEC_NO_COMPLETIONS="${OPENSPEC_NO_COMPLETIONS:-}"
+
+# Test 1: Normal install
+echo "Test 1: Normal install (should attempt to install completions)"
+echo "--------------------------------------"
+unset CI
+unset OPENSPEC_NO_COMPLETIONS
+node scripts/postinstall.js
+echo ""
+
+# Test 2: CI environment (should skip silently)
+echo "Test 2: CI=true (should skip silently)"
+echo "--------------------------------------"
+export CI=true
+node scripts/postinstall.js
+echo "[No output expected - skipped due to CI]"
+echo ""
+
+# Test 3: Opt-out flag (should skip silently)
+echo "Test 3: OPENSPEC_NO_COMPLETIONS=1 (should skip silently)"
+echo "--------------------------------------"
+unset CI
+export OPENSPEC_NO_COMPLETIONS=1
+node scripts/postinstall.js
+echo "[No output expected - skipped due to opt-out]"
+echo ""
+
+# Restore original environment
+if [ -n "$ORIGINAL_CI" ]; then
+  export CI="$ORIGINAL_CI"
+else
+  unset CI
+fi
+
+if [ -n "$ORIGINAL_OPENSPEC_NO_COMPLETIONS" ]; then
+  export OPENSPEC_NO_COMPLETIONS="$ORIGINAL_OPENSPEC_NO_COMPLETIONS"
+else
+  unset OPENSPEC_NO_COMPLETIONS
+fi
+
+echo "======================================"
+echo "All tests completed successfully!"
+echo "======================================"
@@ -3,7 +3,6 @@ import { createRequire } from 'module';
 import ora from 'ora';
 import path from 'path';
 import { promises as fs } from 'fs';
-import { InitCommand } from '../core/init.js';
 import { AI_TOOLS } from '../core/config.js';
 import { UpdateCommand } from '../core/update.js';
 import { ListCommand } from '../core/list.js';
@@ -13,6 +12,8 @@ import { registerSpecCommand } from '../commands/spec.js';
 import { ChangeCommand } from '../commands/change.js';
 import { ValidateCommand } from '../commands/validate.js';
 import { ShowCommand } from '../commands/show.js';
+import { CompletionCommand } from '../commands/completion.js';
+import { registerConfigCommand } from '../commands/config.js';

 const program = new Command();
 const require = createRequire(import.meta.url);
@@ -29,7 +30,7 @@ program.option('--no-color', 'Disable color output');
 // Apply global flags before any command runs
 program.hook('preAction', (thisCommand) => {
  const opts = thisCommand.opts();
-  if (opts.noColor) {
+  if (opts.color === false) {
    process.env.NO_COLOR = '1';
  }
 });
@@ -62,6 +63,7 @@ program
        }
      }
      
+      const { InitCommand } = await import('../core/init.js');
      const initCommand = new InitCommand({
        tools: options?.tools,
      });
@@ -199,6 +201,7 @@ program
  });

 registerSpecCommand(program);
+registerConfigCommand(program);

 // Top-level validate command
 program
@@ -250,4 +253,67 @@ program
    }
  });

+// Completion command with subcommands
+const completionCmd = program
+  .command('completion')
+  .description('Manage shell completions for OpenSpec CLI');
+
+completionCmd
+  .command('generate [shell]')
+  .description('Generate completion script for a shell (outputs to stdout)')
+  .action(async (shell?: string) => {
+    try {
+      const completionCommand = new CompletionCommand();
+      await completionCommand.generate({ shell });
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+completionCmd
+  .command('install [shell]')
+  .description('Install completion script for a shell')
+  .option('--verbose', 'Show detailed installation output')
+  .action(async (shell?: string, options?: { verbose?: boolean }) => {
+    try {
+      const completionCommand = new CompletionCommand();
+      await completionCommand.install({ shell, verbose: options?.verbose });
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+completionCmd
+  .command('uninstall [shell]')
+  .description('Uninstall completion script for a shell')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(async (shell?: string, options?: { yes?: boolean }) => {
+    try {
+      const completionCommand = new CompletionCommand();
+      await completionCommand.uninstall({ shell, yes: options?.yes });
+    } catch (error) {
+      console.log();
+      ora().fail(`Error: ${(error as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+// Hidden command for machine-readable completion data
+program
+  .command('__complete <type>', { hidden: true })
+  .description('Output completion data in machine-readable format (internal use)')
+  .action(async (type: string) => {
+    try {
+      const completionCommand = new CompletionCommand();
+      await completionCommand.complete({ type });
+    } catch (error) {
+      // Silently fail for graceful shell completion experience
+      process.exitCode = 1;
+    }
+  });
+
 program.parse();
@@ -1,6 +1,5 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { select } from '@inquirer/prompts';
 import { JsonConverter } from '../core/converters/json-converter.js';
 import { Validator } from '../core/validation/validator.js';
 import { ChangeParser } from '../core/parsers/change-parser.js';
@@ -30,9 +29,10 @@ export class ChangeCommand {
    const changesPath = path.join(process.cwd(), 'openspec', 'changes');

    if (!changeName) {
-      const canPrompt = isInteractive(options?.noInteractive);
+      const canPrompt = isInteractive(options);
      const changes = await this.getActiveChanges(changesPath);
      if (canPrompt && changes.length > 0) {
+        const { select } = await import('@inquirer/prompts');
        const selected = await select({
          message: 'Select a change to show',
          choices: changes.map(id => ({ name: id, value: id })),
@@ -186,9 +186,10 @@ export class ChangeCommand {
    const changesPath = path.join(process.cwd(), 'openspec', 'changes');
    
    if (!changeName) {
-      const canPrompt = isInteractive(options?.noInteractive);
+      const canPrompt = isInteractive(options);
      const changes = await getActiveChangeIds();
      if (canPrompt && changes.length > 0) {
+        const { select } = await import('@inquirer/prompts');
        const selected = await select({
          message: 'Select a change to validate',
          choices: changes.map(id => ({ name: id, value: id })),
@@ -0,0 +1,262 @@
+import ora from 'ora';
+import { CompletionFactory } from '../core/completions/factory.js';
+import { COMMAND_REGISTRY } from '../core/completions/command-registry.js';
+import { detectShell, SupportedShell } from '../utils/shell-detection.js';
+import { CompletionProvider } from '../core/completions/completion-provider.js';
+import { getArchivedChangeIds } from '../utils/item-discovery.js';
+
+interface GenerateOptions {
+  shell?: string;
+}
+
+interface InstallOptions {
+  shell?: string;
+  verbose?: boolean;
+}
+
+interface UninstallOptions {
+  shell?: string;
+  yes?: boolean;
+}
+
+interface CompleteOptions {
+  type: string;
+}
+
+/**
+ * Command for managing shell completions for OpenSpec CLI
+ */
+export class CompletionCommand {
+  private completionProvider: CompletionProvider;
+
+  constructor() {
+    this.completionProvider = new CompletionProvider();
+  }
+  /**
+   * Resolve shell parameter or exit with error
+   *
+   * @param shell - The shell parameter (may be undefined)
+   * @param operationName - Name of the operation (for error messages)
+   * @returns Resolved shell or null if should exit
+   */
+  private resolveShellOrExit(shell: string | undefined, operationName: string): SupportedShell | null {
+    const normalizedShell = this.normalizeShell(shell);
+
+    if (!normalizedShell) {
+      const detectionResult = detectShell();
+
+      if (detectionResult.shell && CompletionFactory.isSupported(detectionResult.shell)) {
+        return detectionResult.shell;
+      }
+
+      // Shell was detected but not supported
+      if (detectionResult.detected && !detectionResult.shell) {
+        console.error(`Error: Shell '${detectionResult.detected}' is not supported yet. Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+        process.exitCode = 1;
+        return null;
+      }
+
+      // No shell specified and cannot auto-detect
+      console.error('Error: Could not auto-detect shell. Please specify shell explicitly.');
+      console.error(`Usage: openspec completion ${operationName} [shell]`);
+      console.error(`Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+      process.exitCode = 1;
+      return null;
+    }
+
+    if (!CompletionFactory.isSupported(normalizedShell)) {
+      console.error(`Error: Shell '${normalizedShell}' is not supported yet. Currently supported: ${CompletionFactory.getSupportedShells().join(', ')}`);
+      process.exitCode = 1;
+      return null;
+    }
+
+    return normalizedShell;
+  }
+
+  /**
+   * Generate completion script and output to stdout
+   *
+   * @param options - Options for generation (shell type)
+   */
+  async generate(options: GenerateOptions = {}): Promise<void> {
+    const shell = this.resolveShellOrExit(options.shell, 'generate');
+    if (!shell) return;
+
+    await this.generateForShell(shell);
+  }
+
+  /**
+   * Install completion script to the appropriate location
+   *
+   * @param options - Options for installation (shell type, verbose output)
+   */
+  async install(options: InstallOptions = {}): Promise<void> {
+    const shell = this.resolveShellOrExit(options.shell, 'install');
+    if (!shell) return;
+
+    await this.installForShell(shell, options.verbose || false);
+  }
+
+  /**
+   * Uninstall completion script from the installation location
+   *
+   * @param options - Options for uninstallation (shell type, yes flag)
+   */
+  async uninstall(options: UninstallOptions = {}): Promise<void> {
+    const shell = this.resolveShellOrExit(options.shell, 'uninstall');
+    if (!shell) return;
+
+    await this.uninstallForShell(shell, options.yes || false);
+  }
+
+  /**
+   * Generate completion script for a specific shell
+   */
+  private async generateForShell(shell: SupportedShell): Promise<void> {
+    const generator = CompletionFactory.createGenerator(shell);
+    const script = generator.generate(COMMAND_REGISTRY);
+    console.log(script);
+  }
+
+  /**
+   * Install completion script for a specific shell
+   */
+  private async installForShell(shell: SupportedShell, verbose: boolean): Promise<void> {
+    const generator = CompletionFactory.createGenerator(shell);
+    const installer = CompletionFactory.createInstaller(shell);
+
+    const spinner = ora(`Installing ${shell} completion script...`).start();
+
+    try {
+      // Generate the completion script
+      const script = generator.generate(COMMAND_REGISTRY);
+
+      // Install it
+      const result = await installer.install(script);
+
+      spinner.stop();
+
+      if (result.success) {
+        console.log(`✓ ${result.message}`);
+
+        if (verbose && result.installedPath) {
+          console.log(`  Installed to: ${result.installedPath}`);
+          if (result.backupPath) {
+            console.log(`  Backup created: ${result.backupPath}`);
+          }
+          if (result.zshrcConfigured) {
+            console.log(`  ~/.zshrc configured automatically`);
+          }
+        }
+
+        // Print instructions (only shown if .zshrc wasn't auto-configured)
+        if (result.instructions && result.instructions.length > 0) {
+          console.log('');
+          for (const instruction of result.instructions) {
+            console.log(instruction);
+          }
+        } else if (result.zshrcConfigured) {
+          console.log('');
+          console.log('Restart your shell or run: exec zsh');
+        }
+      } else {
+        console.error(`✗ ${result.message}`);
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      spinner.stop();
+      console.error(`✗ Failed to install completion script: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
+  }
+
+  /**
+   * Uninstall completion script for a specific shell
+   */
+  private async uninstallForShell(shell: SupportedShell, skipConfirmation: boolean): Promise<void> {
+    const installer = CompletionFactory.createInstaller(shell);
+
+    // Prompt for confirmation unless --yes flag is provided
+    if (!skipConfirmation) {
+      const { confirm } = await import('@inquirer/prompts');
+      const confirmed = await confirm({
+        message: 'Remove OpenSpec configuration from ~/.zshrc?',
+        default: false,
+      });
+
+      if (!confirmed) {
+        console.log('Uninstall cancelled.');
+        return;
+      }
+    }
+
+    const spinner = ora(`Uninstalling ${shell} completion script...`).start();
+
+    try {
+      const result = await installer.uninstall();
+
+      spinner.stop();
+
+      if (result.success) {
+        console.log(`✓ ${result.message}`);
+      } else {
+        console.error(`✗ ${result.message}`);
+        process.exitCode = 1;
+      }
+    } catch (error) {
+      spinner.stop();
+      console.error(`✗ Failed to uninstall completion script: ${error instanceof Error ? error.message : String(error)}`);
+      process.exitCode = 1;
+    }
+  }
+
+  /**
+   * Output machine-readable completion data for shell consumption
+   * Format: tab-separated "id\tdescription" per line
+   *
+   * @param options - Options specifying completion type
+   */
+  async complete(options: CompleteOptions): Promise<void> {
+    const type = options.type.toLowerCase();
+
+    try {
+      switch (type) {
+        case 'changes': {
+          const changeIds = await this.completionProvider.getChangeIds();
+          for (const id of changeIds) {
+            console.log(`${id}\tactive change`);
+          }
+          break;
+        }
+        case 'specs': {
+          const specIds = await this.completionProvider.getSpecIds();
+          for (const id of specIds) {
+            console.log(`${id}\tspecification`);
+          }
+          break;
+        }
+        case 'archived-changes': {
+          const archivedIds = await getArchivedChangeIds();
+          for (const id of archivedIds) {
+            console.log(`${id}\tarchived change`);
+          }
+          break;
+        }
+        default:
+          // Invalid type - silently exit with no output for graceful shell completion failure
+          process.exitCode = 1;
+          break;
+      }
+    } catch {
+      // Silently fail for graceful shell completion experience
+      process.exitCode = 1;
+    }
+  }
+
+  /**
+   * Normalize shell parameter to lowercase
+   */
+  private normalizeShell(shell?: string): string | undefined {
+    return shell?.toLowerCase();
+  }
+}
@@ -0,0 +1,233 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import {
+  getGlobalConfigPath,
+  getGlobalConfig,
+  saveGlobalConfig,
+  GlobalConfig,
+} from '../core/global-config.js';
+import {
+  getNestedValue,
+  setNestedValue,
+  deleteNestedValue,
+  coerceValue,
+  formatValueYaml,
+  validateConfigKeyPath,
+  validateConfig,
+  DEFAULT_CONFIG,
+} from '../core/config-schema.js';
+
+/**
+ * Register the config command and all its subcommands.
+ *
+ * @param program - The Commander program instance
+ */
+export function registerConfigCommand(program: Command): void {
+  const configCmd = program
+    .command('config')
+    .description('View and modify global OpenSpec configuration')
+    .option('--scope <scope>', 'Config scope (only "global" supported currently)')
+    .hook('preAction', (thisCommand) => {
+      const opts = thisCommand.opts();
+      if (opts.scope && opts.scope !== 'global') {
+        console.error('Error: Project-local config is not yet implemented');
+        process.exit(1);
+      }
+    });
+
+  // config path
+  configCmd
+    .command('path')
+    .description('Show config file location')
+    .action(() => {
+      console.log(getGlobalConfigPath());
+    });
+
+  // config list
+  configCmd
+    .command('list')
+    .description('Show all current settings')
+    .option('--json', 'Output as JSON')
+    .action((options: { json?: boolean }) => {
+      const config = getGlobalConfig();
+
+      if (options.json) {
+        console.log(JSON.stringify(config, null, 2));
+      } else {
+        console.log(formatValueYaml(config));
+      }
+    });
+
+  // config get
+  configCmd
+    .command('get <key>')
+    .description('Get a specific value (raw, scriptable)')
+    .action((key: string) => {
+      const config = getGlobalConfig();
+      const value = getNestedValue(config as Record<string, unknown>, key);
+
+      if (value === undefined) {
+        process.exitCode = 1;
+        return;
+      }
+
+      if (typeof value === 'object' && value !== null) {
+        console.log(JSON.stringify(value));
+      } else {
+        console.log(String(value));
+      }
+    });
+
+  // config set
+  configCmd
+    .command('set <key> <value>')
+    .description('Set a value (auto-coerce types)')
+    .option('--string', 'Force value to be stored as string')
+    .option('--allow-unknown', 'Allow setting unknown keys')
+    .action((key: string, value: string, options: { string?: boolean; allowUnknown?: boolean }) => {
+      const allowUnknown = Boolean(options.allowUnknown);
+      const keyValidation = validateConfigKeyPath(key);
+      if (!keyValidation.valid && !allowUnknown) {
+        const reason = keyValidation.reason ? ` ${keyValidation.reason}.` : '';
+        console.error(`Error: Invalid configuration key "${key}".${reason}`);
+        console.error('Use "openspec config list" to see available keys.');
+        console.error('Pass --allow-unknown to bypass this check.');
+        process.exitCode = 1;
+        return;
+      }
+
+      const config = getGlobalConfig() as Record<string, unknown>;
+      const coercedValue = coerceValue(value, options.string || false);
+
+      // Create a copy to validate before saving
+      const newConfig = JSON.parse(JSON.stringify(config));
+      setNestedValue(newConfig, key, coercedValue);
+
+      // Validate the new config
+      const validation = validateConfig(newConfig);
+      if (!validation.success) {
+        console.error(`Error: Invalid configuration - ${validation.error}`);
+        process.exitCode = 1;
+        return;
+      }
+
+      // Apply changes and save
+      setNestedValue(config, key, coercedValue);
+      saveGlobalConfig(config as GlobalConfig);
+
+      const displayValue =
+        typeof coercedValue === 'string' ? `"${coercedValue}"` : String(coercedValue);
+      console.log(`Set ${key} = ${displayValue}`);
+    });
+
+  // config unset
+  configCmd
+    .command('unset <key>')
+    .description('Remove a key (revert to default)')
+    .action((key: string) => {
+      const config = getGlobalConfig() as Record<string, unknown>;
+      const existed = deleteNestedValue(config, key);
+
+      if (existed) {
+        saveGlobalConfig(config as GlobalConfig);
+        console.log(`Unset ${key} (reverted to default)`);
+      } else {
+        console.log(`Key "${key}" was not set`);
+      }
+    });
+
+  // config reset
+  configCmd
+    .command('reset')
+    .description('Reset configuration to defaults')
+    .option('--all', 'Reset all configuration (required)')
+    .option('-y, --yes', 'Skip confirmation prompts')
+    .action(async (options: { all?: boolean; yes?: boolean }) => {
+      if (!options.all) {
+        console.error('Error: --all flag is required for reset');
+        console.error('Usage: openspec config reset --all [-y]');
+        process.exitCode = 1;
+        return;
+      }
+
+      if (!options.yes) {
+        const { confirm } = await import('@inquirer/prompts');
+        const confirmed = await confirm({
+          message: 'Reset all configuration to defaults?',
+          default: false,
+        });
+
+        if (!confirmed) {
+          console.log('Reset cancelled.');
+          return;
+        }
+      }
+
+      saveGlobalConfig({ ...DEFAULT_CONFIG });
+      console.log('Configuration reset to defaults');
+    });
+
+  // config edit
+  configCmd
+    .command('edit')
+    .description('Open config in $EDITOR')
+    .action(async () => {
+      const editor = process.env.EDITOR || process.env.VISUAL;
+
+      if (!editor) {
+        console.error('Error: No editor configured');
+        console.error('Set the EDITOR or VISUAL environment variable to your preferred editor');
+        console.error('Example: export EDITOR=vim');
+        process.exitCode = 1;
+        return;
+      }
+
+      const configPath = getGlobalConfigPath();
+
+      // Ensure config file exists with defaults
+      if (!fs.existsSync(configPath)) {
+        saveGlobalConfig({ ...DEFAULT_CONFIG });
+      }
+
+      // Spawn editor and wait for it to close
+      // Avoid shell parsing to correctly handle paths with spaces in both
+      // the editor path and config path
+      const child = spawn(editor, [configPath], {
+        stdio: 'inherit',
+        shell: false,
+      });
+
+      await new Promise<void>((resolve, reject) => {
+        child.on('close', (code) => {
+          if (code === 0) {
+            resolve();
+          } else {
+            reject(new Error(`Editor exited with code ${code}`));
+          }
+        });
+        child.on('error', reject);
+      });
+
+      try {
+        const rawConfig = fs.readFileSync(configPath, 'utf-8');
+        const parsedConfig = JSON.parse(rawConfig);
+        const validation = validateConfig(parsedConfig);
+
+        if (!validation.success) {
+          console.error(`Error: Invalid configuration - ${validation.error}`);
+          process.exitCode = 1;
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          console.error(`Error: Config file not found at ${configPath}`);
+        } else if (error instanceof SyntaxError) {
+          console.error(`Error: Invalid JSON in ${configPath}`);
+          console.error(error.message);
+        } else {
+          console.error(`Error: Unable to validate configuration - ${error instanceof Error ? error.message : String(error)}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+}
@@ -1,4 +1,3 @@
-import { select } from '@inquirer/prompts';
 import path from 'path';
 import { isInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
@@ -13,11 +12,12 @@ const SPEC_FLAG_KEYS = new Set(['requirements', 'scenarios', 'requirement']);

 export class ShowCommand {
  async execute(itemName?: string, options: { json?: boolean; type?: string; noInteractive?: boolean; [k: string]: any } = {}): Promise<void> {
-    const interactive = isInteractive(options.noInteractive);
+    const interactive = isInteractive(options);
    const typeOverride = this.normalizeType(options.type);

    if (!itemName) {
      if (interactive) {
+        const { select } = await import('@inquirer/prompts');
        const type = await select<ItemType>({
          message: 'What would you like to show?',
          choices: [
@@ -44,6 +44,7 @@ export class ShowCommand {
  }

  private async runInteractiveByType(type: ItemType, options: { json?: boolean; noInteractive?: boolean; [k: string]: any }): Promise<void> {
+    const { select } = await import('@inquirer/prompts');
    if (type === 'change') {
      const changes = await getActiveChangeIds();
      if (changes.length === 0) {
@@ -135,5 +136,3 @@ export class ShowCommand {
    return false;
  }
 }
-
-
@@ -4,7 +4,6 @@ import { join } from 'path';
 import { MarkdownParser } from '../core/parsers/markdown-parser.js';
 import { Validator } from '../core/validation/validator.js';
 import type { Spec } from '../core/schemas/index.js';
-import { select } from '@inquirer/prompts';
 import { isInteractive } from '../utils/interactive.js';
 import { getSpecIds } from '../utils/item-discovery.js';

@@ -70,9 +69,10 @@ export class SpecCommand {

  async show(specId?: string, options: ShowOptions = {}): Promise<void> {
    if (!specId) {
-      const canPrompt = isInteractive(options?.noInteractive);
+      const canPrompt = isInteractive(options);
      const specIds = await getSpecIds();
      if (canPrompt && specIds.length > 0) {
+        const { select } = await import('@inquirer/prompts');
        specId = await select({
          message: 'Select a spec to show',
          choices: specIds.map(id => ({ name: id, value: id })),
@@ -204,9 +204,10 @@ export function registerSpecCommand(rootProgram: typeof program) {
    .action(async (specId: string | undefined, options: { strict?: boolean; json?: boolean; noInteractive?: boolean }) => {
      try {
        if (!specId) {
-          const canPrompt = isInteractive(options?.noInteractive);
+          const canPrompt = isInteractive(options);
          const specIds = await getSpecIds();
          if (canPrompt && specIds.length > 0) {
+            const { select } = await import('@inquirer/prompts');
            specId = await select({
              message: 'Select a spec to validate',
              choices: specIds.map(id => ({ name: id, value: id })),
@@ -247,4 +248,4 @@ export function registerSpecCommand(rootProgram: typeof program) {
    });

  return specCommand;
-}
+}
@@ -1,8 +1,7 @@
-import { select } from '@inquirer/prompts';
 import ora from 'ora';
 import path from 'path';
 import { Validator } from '../core/validation/validator.js';
-import { isInteractive } from '../utils/interactive.js';
+import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
 import { nearestMatches } from '../utils/match.js';

@@ -16,6 +15,7 @@ interface ExecuteOptions {
  strict?: boolean;
  json?: boolean;
  noInteractive?: boolean;
+  interactive?: boolean; // Commander sets this to false when --no-interactive is used
  concurrency?: string;
 }

@@ -29,14 +29,14 @@ interface BulkItemResult {

 export class ValidateCommand {
  async execute(itemName: string | undefined, options: ExecuteOptions = {}): Promise<void> {
-    const interactive = isInteractive(options.noInteractive);
+    const interactive = isInteractive(options);

    // Handle bulk flags first
    if (options.all || options.changes || options.specs) {
      await this.runBulkValidation({
        changes: !!options.all || !!options.changes,
        specs: !!options.all || !!options.specs,
-      }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+      }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
      return;
    }

@@ -64,6 +64,7 @@ export class ValidateCommand {
  }

  private async runInteractiveSelector(opts: { strict: boolean; json: boolean; concurrency?: string }): Promise<void> {
+    const { select } = await import('@inquirer/prompts');
    const choice = await select({
      message: 'What would you like to validate?',
      choices: [
@@ -180,8 +181,8 @@ export class ValidateCommand {
    bullets.forEach(b => console.error(`  ${b}`));
  }

-  private async runBulkValidation(scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string }): Promise<void> {
-    const spinner = !opts.json ? ora('Validating...').start() : undefined;
+  private async runBulkValidation(scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string; noInteractive?: boolean }): Promise<void> {
+    const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
    const [changeIds, specIds] = await Promise.all([
      scope.changes ? getActiveChangeIds() : Promise.resolve<string[]>([]),
      scope.specs ? getSpecIds() : Promise.resolve<string[]>([]),
@@ -212,6 +213,28 @@ export class ValidateCommand {
      });
    }

+    if (queue.length === 0) {
+      spinner?.stop();
+
+      const summary = {
+        totals: { items: 0, passed: 0, failed: 0 },
+        byType: {
+          ...(scope.changes ? { change: { items: 0, passed: 0, failed: 0 } } : {}),
+          ...(scope.specs ? { spec: { items: 0, passed: 0, failed: 0 } } : {}),
+        },
+      } as const;
+
+      if (opts.json) {
+        const out = { items: [] as BulkItemResult[], summary, version: '1.0' };
+        console.log(JSON.stringify(out, null, 2));
+      } else {
+        console.log('No items found to validate.');
+      }
+
+      process.exitCode = 0;
+      return;
+    }
+
    const results: BulkItemResult[] = [];
    let index = 0;
    let running = 0;
@@ -301,5 +324,3 @@ function getPlannedType(index: number, changeIds: string[], specIds: string[]):
  if (specIndex >= 0 && specIndex < specIds.length) return 'spec';
  return undefined;
 }
-
-
@@ -1,7 +1,5 @@
 import { promises as fs } from 'fs';
 import path from 'path';
-import { select, confirm } from '@inquirer/prompts';
-import { FileSystemUtils } from '../utils/file-system.js';
 import { getTaskProgressForChange, formatTaskStatus } from '../utils/task-progress.js';
 import { Validator } from './validation/validator.js';
 import chalk from 'chalk';
@@ -125,6 +123,7 @@ export class ArchiveCommand {
      const timestamp = new Date().toISOString();
      
      if (!options.yes) {
+        const { confirm } = await import('@inquirer/prompts');
        const proceed = await confirm({
          message: chalk.yellow('⚠️  WARNING: Skipping validation may archive invalid specs. Continue? (y/N)'),
          default: false
@@ -149,6 +148,7 @@ export class ArchiveCommand {
    const incompleteTasks = Math.max(progress.total - progress.completed, 0);
    if (incompleteTasks > 0) {
      if (!options.yes) {
+        const { confirm } = await import('@inquirer/prompts');
        const proceed = await confirm({
          message: `Warning: ${incompleteTasks} incomplete task(s) found. Continue?`,
          default: false
@@ -179,6 +179,7 @@ export class ArchiveCommand {

        let shouldUpdateSpecs = true;
        if (!options.yes) {
+          const { confirm } = await import('@inquirer/prompts');
          shouldUpdateSpecs = await confirm({
            message: 'Proceed with spec updates?',
            default: true
@@ -256,6 +257,7 @@ export class ArchiveCommand {
  }

  private async selectChange(changesDir: string): Promise<string | null> {
+    const { select } = await import('@inquirer/prompts');
    // Get all directories in changes (excluding archive)
    const entries = await fs.readdir(changesDir, { withFileTypes: true });
    const changeDirs = entries
@@ -444,15 +446,26 @@ export class ArchiveCommand {

    // Load or create base target content
    let targetContent: string;
+    let isNewSpec = false;
    try {
      targetContent = await fs.readFile(update.target, 'utf-8');
    } catch {
-      // Target spec does not exist; only ADDED operations are permitted
-      if (plan.modified.length > 0 || plan.removed.length > 0 || plan.renamed.length > 0) {
+      // Target spec does not exist; MODIFIED and RENAMED are not allowed for new specs
+      // REMOVED will be ignored with a warning since there's nothing to remove
+      if (plan.modified.length > 0 || plan.renamed.length > 0) {
        throw new Error(
-          `${specName}: target spec does not exist; only ADDED requirements are allowed for new specs.`
+          `${specName}: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.`
        );
      }
+      // Warn about REMOVED requirements being ignored for new specs
+      if (plan.removed.length > 0) {
+        console.log(
+          chalk.yellow(
+            `⚠️  Warning: ${specName} - ${plan.removed.length} REMOVED requirement(s) ignored for new spec (nothing to remove).`
+          )
+        );
+      }
+      isNewSpec = true;
      targetContent = this.buildSpecSkeleton(specName, changeName);
    }

@@ -495,9 +508,15 @@ export class ArchiveCommand {
    for (const name of plan.removed) {
      const key = normalizeRequirementName(name);
      if (!nameToBlock.has(key)) {
-        throw new Error(
-          `${specName} REMOVED failed for header "### Requirement: ${name}" - not found`
-        );
+        // For new specs, REMOVED requirements are already warned about and ignored
+        // For existing specs, missing requirements are an error
+        if (!isNewSpec) {
+          throw new Error(
+            `${specName} REMOVED failed for header "### Requirement: ${name}" - not found`
+          );
+        }
+        // Skip removal for new specs (already warned above)
+        continue;
      }
      nameToBlock.delete(key);
    }
@@ -0,0 +1,167 @@
+import type { Artifact, SchemaYaml, CompletedSet, BlockedArtifacts } from './types.js';
+import { loadSchema, parseSchema } from './schema.js';
+
+/**
+ * Represents an artifact dependency graph.
+ * Provides methods for querying build order, ready artifacts, and completion status.
+ */
+export class ArtifactGraph {
+  private artifacts: Map<string, Artifact>;
+  private schema: SchemaYaml;
+
+  private constructor(schema: SchemaYaml) {
+    this.schema = schema;
+    this.artifacts = new Map(schema.artifacts.map(a => [a.id, a]));
+  }
+
+  /**
+   * Creates an ArtifactGraph from a YAML file path.
+   */
+  static fromYaml(filePath: string): ArtifactGraph {
+    const schema = loadSchema(filePath);
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Creates an ArtifactGraph from YAML content string.
+   */
+  static fromYamlContent(yamlContent: string): ArtifactGraph {
+    const schema = parseSchema(yamlContent);
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Creates an ArtifactGraph from a pre-validated schema object.
+   */
+  static fromSchema(schema: SchemaYaml): ArtifactGraph {
+    return new ArtifactGraph(schema);
+  }
+
+  /**
+   * Gets a single artifact by ID.
+   */
+  getArtifact(id: string): Artifact | undefined {
+    return this.artifacts.get(id);
+  }
+
+  /**
+   * Gets all artifacts in the graph.
+   */
+  getAllArtifacts(): Artifact[] {
+    return Array.from(this.artifacts.values());
+  }
+
+  /**
+   * Gets the schema name.
+   */
+  getName(): string {
+    return this.schema.name;
+  }
+
+  /**
+   * Gets the schema version.
+   */
+  getVersion(): number {
+    return this.schema.version;
+  }
+
+  /**
+   * Computes the topological build order using Kahn's algorithm.
+   * Returns artifact IDs in the order they should be built.
+   */
+  getBuildOrder(): string[] {
+    const inDegree = new Map<string, number>();
+    const dependents = new Map<string, string[]>();
+
+    // Initialize all artifacts
+    for (const artifact of this.artifacts.values()) {
+      inDegree.set(artifact.id, artifact.requires.length);
+      dependents.set(artifact.id, []);
+    }
+
+    // Build reverse adjacency (who depends on whom)
+    for (const artifact of this.artifacts.values()) {
+      for (const req of artifact.requires) {
+        dependents.get(req)!.push(artifact.id);
+      }
+    }
+
+    // Start with roots (in-degree 0), sorted for determinism
+    const queue = [...this.artifacts.keys()]
+      .filter(id => inDegree.get(id) === 0)
+      .sort();
+
+    const result: string[] = [];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      result.push(current);
+
+      // Collect newly ready artifacts, then sort before adding
+      const newlyReady: string[] = [];
+      for (const dep of dependents.get(current)!) {
+        const newDegree = inDegree.get(dep)! - 1;
+        inDegree.set(dep, newDegree);
+        if (newDegree === 0) {
+          newlyReady.push(dep);
+        }
+      }
+      queue.push(...newlyReady.sort());
+    }
+
+    return result;
+  }
+
+  /**
+   * Gets artifacts that are ready to be created (all dependencies completed).
+   */
+  getNextArtifacts(completed: CompletedSet): string[] {
+    const ready: string[] = [];
+
+    for (const artifact of this.artifacts.values()) {
+      if (completed.has(artifact.id)) {
+        continue; // Already completed
+      }
+
+      const allDepsCompleted = artifact.requires.every(req => completed.has(req));
+      if (allDepsCompleted) {
+        ready.push(artifact.id);
+      }
+    }
+
+    // Sort for deterministic ordering
+    return ready.sort();
+  }
+
+  /**
+   * Checks if all artifacts in the graph are completed.
+   */
+  isComplete(completed: CompletedSet): boolean {
+    for (const artifact of this.artifacts.values()) {
+      if (!completed.has(artifact.id)) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Gets blocked artifacts and their unmet dependencies.
+   */
+  getBlocked(completed: CompletedSet): BlockedArtifacts {
+    const blocked: BlockedArtifacts = {};
+
+    for (const artifact of this.artifacts.values()) {
+      if (completed.has(artifact.id)) {
+        continue; // Already completed
+      }
+
+      const unmetDeps = artifact.requires.filter(req => !completed.has(req));
+      if (unmetDeps.length > 0) {
+        blocked[artifact.id] = unmetDeps.sort();
+      }
+    }
+
+    return blocked;
+  }
+}
@@ -0,0 +1,42 @@
+// Types
+export {
+  ArtifactSchema,
+  SchemaYamlSchema,
+  type Artifact,
+  type SchemaYaml,
+  type CompletedSet,
+  type BlockedArtifacts,
+} from './types.js';
+
+// Schema loading and validation
+export { loadSchema, parseSchema, SchemaValidationError } from './schema.js';
+
+// Graph operations
+export { ArtifactGraph } from './graph.js';
+
+// State detection
+export { detectCompleted } from './state.js';
+
+// Schema resolution
+export {
+  resolveSchema,
+  listSchemas,
+  getSchemaDir,
+  getPackageSchemasDir,
+  getUserSchemasDir,
+  SchemaLoadError,
+} from './resolver.js';
+
+// Instruction loading
+export {
+  loadTemplate,
+  loadChangeContext,
+  generateInstructions,
+  formatChangeStatus,
+  TemplateLoadError,
+  type ChangeContext,
+  type ArtifactInstructions,
+  type DependencyStatus,
+  type ArtifactStatus,
+  type ChangeStatus,
+} from './instruction-loader.js';
@@ -0,0 +1,269 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getSchemaDir, resolveSchema } from './resolver.js';
+import { ArtifactGraph } from './graph.js';
+import { detectCompleted } from './state.js';
+import type { Artifact, CompletedSet } from './types.js';
+
+/**
+ * Error thrown when loading a template fails.
+ */
+export class TemplateLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly templatePath: string
+  ) {
+    super(message);
+    this.name = 'TemplateLoadError';
+  }
+}
+
+/**
+ * Change context containing graph, completion state, and metadata.
+ */
+export interface ChangeContext {
+  /** The artifact dependency graph */
+  graph: ArtifactGraph;
+  /** Set of completed artifact IDs */
+  completed: CompletedSet;
+  /** Schema name being used */
+  schemaName: string;
+  /** Change name */
+  changeName: string;
+  /** Path to the change directory */
+  changeDir: string;
+}
+
+/**
+ * Enriched instructions for creating an artifact.
+ */
+export interface ArtifactInstructions {
+  /** Change name */
+  changeName: string;
+  /** Artifact ID */
+  artifactId: string;
+  /** Schema name */
+  schemaName: string;
+  /** Output path pattern (e.g., "proposal.md") */
+  outputPath: string;
+  /** Artifact description */
+  description: string;
+  /** Template content */
+  template: string;
+  /** Dependencies with completion status */
+  dependencies: DependencyStatus[];
+  /** Artifacts that become available after completing this one */
+  unlocks: string[];
+}
+
+/**
+ * Dependency status information.
+ */
+export interface DependencyStatus {
+  /** Artifact ID */
+  id: string;
+  /** Whether the dependency is completed */
+  done: boolean;
+}
+
+/**
+ * Status of a single artifact in the workflow.
+ */
+export interface ArtifactStatus {
+  /** Artifact ID */
+  id: string;
+  /** Output path pattern */
+  outputPath: string;
+  /** Status: done, ready, or blocked */
+  status: 'done' | 'ready' | 'blocked';
+  /** Missing dependencies (only for blocked) */
+  missingDeps?: string[];
+}
+
+/**
+ * Formatted change status.
+ */
+export interface ChangeStatus {
+  /** Change name */
+  changeName: string;
+  /** Schema name */
+  schemaName: string;
+  /** Whether all artifacts are complete */
+  isComplete: boolean;
+  /** Status of each artifact */
+  artifacts: ArtifactStatus[];
+}
+
+/**
+ * Loads a template from a schema's templates directory.
+ *
+ * @param schemaName - Schema name (e.g., "spec-driven")
+ * @param templatePath - Relative path within the templates directory (e.g., "proposal.md")
+ * @returns The template content
+ * @throws TemplateLoadError if the template cannot be loaded
+ */
+export function loadTemplate(schemaName: string, templatePath: string): string {
+  const schemaDir = getSchemaDir(schemaName);
+  if (!schemaDir) {
+    throw new TemplateLoadError(
+      `Schema '${schemaName}' not found`,
+      templatePath
+    );
+  }
+
+  const fullPath = path.join(schemaDir, 'templates', templatePath);
+
+  if (!fs.existsSync(fullPath)) {
+    throw new TemplateLoadError(
+      `Template not found: ${fullPath}`,
+      fullPath
+    );
+  }
+
+  try {
+    return fs.readFileSync(fullPath, 'utf-8');
+  } catch (err) {
+    const ioError = err instanceof Error ? err : new Error(String(err));
+    throw new TemplateLoadError(
+      `Failed to read template: ${ioError.message}`,
+      fullPath
+    );
+  }
+}
+
+/**
+ * Loads change context combining graph and completion state.
+ *
+ * @param projectRoot - Project root directory
+ * @param changeName - Change name
+ * @param schemaName - Optional schema name (defaults to "spec-driven")
+ * @returns Change context with graph, completed set, and metadata
+ */
+export function loadChangeContext(
+  projectRoot: string,
+  changeName: string,
+  schemaName: string = 'spec-driven'
+): ChangeContext {
+  const schema = resolveSchema(schemaName);
+  const graph = ArtifactGraph.fromSchema(schema);
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', changeName);
+  const completed = detectCompleted(graph, changeDir);
+
+  return {
+    graph,
+    completed,
+    schemaName,
+    changeName,
+    changeDir,
+  };
+}
+
+/**
+ * Generates enriched instructions for creating an artifact.
+ *
+ * @param context - Change context
+ * @param artifactId - Artifact ID to generate instructions for
+ * @returns Enriched artifact instructions
+ * @throws Error if artifact not found
+ */
+export function generateInstructions(
+  context: ChangeContext,
+  artifactId: string
+): ArtifactInstructions {
+  const artifact = context.graph.getArtifact(artifactId);
+  if (!artifact) {
+    throw new Error(`Artifact '${artifactId}' not found in schema '${context.schemaName}'`);
+  }
+
+  const template = loadTemplate(context.schemaName, artifact.template);
+  const dependencies = getDependencyStatus(artifact, context.completed);
+  const unlocks = getUnlockedArtifacts(context.graph, artifactId);
+
+  return {
+    changeName: context.changeName,
+    artifactId: artifact.id,
+    schemaName: context.schemaName,
+    outputPath: artifact.generates,
+    description: artifact.description,
+    template,
+    dependencies,
+    unlocks,
+  };
+}
+
+/**
+ * Gets dependency status for an artifact.
+ */
+function getDependencyStatus(
+  artifact: Artifact,
+  completed: CompletedSet
+): DependencyStatus[] {
+  return artifact.requires.map(id => ({
+    id,
+    done: completed.has(id),
+  }));
+}
+
+/**
+ * Gets artifacts that become available after completing the given artifact.
+ */
+function getUnlockedArtifacts(graph: ArtifactGraph, artifactId: string): string[] {
+  const unlocks: string[] = [];
+
+  for (const artifact of graph.getAllArtifacts()) {
+    if (artifact.requires.includes(artifactId)) {
+      unlocks.push(artifact.id);
+    }
+  }
+
+  return unlocks.sort();
+}
+
+/**
+ * Formats the status of all artifacts in a change.
+ *
+ * @param context - Change context
+ * @returns Formatted change status
+ */
+export function formatChangeStatus(context: ChangeContext): ChangeStatus {
+  const artifacts = context.graph.getAllArtifacts();
+  const ready = new Set(context.graph.getNextArtifacts(context.completed));
+  const blocked = context.graph.getBlocked(context.completed);
+
+  const artifactStatuses: ArtifactStatus[] = artifacts.map(artifact => {
+    if (context.completed.has(artifact.id)) {
+      return {
+        id: artifact.id,
+        outputPath: artifact.generates,
+        status: 'done' as const,
+      };
+    }
+
+    if (ready.has(artifact.id)) {
+      return {
+        id: artifact.id,
+        outputPath: artifact.generates,
+        status: 'ready' as const,
+      };
+    }
+
+    return {
+      id: artifact.id,
+      outputPath: artifact.generates,
+      status: 'blocked' as const,
+      missingDeps: blocked[artifact.id] ?? [],
+    };
+  });
+
+  // Sort by build order for consistent output
+  const buildOrder = context.graph.getBuildOrder();
+  const orderMap = new Map(buildOrder.map((id, idx) => [id, idx]));
+  artifactStatuses.sort((a, b) => (orderMap.get(a.id) ?? 0) - (orderMap.get(b.id) ?? 0));
+
+  return {
+    changeName: context.changeName,
+    schemaName: context.schemaName,
+    isComplete: context.graph.isComplete(context.completed),
+    artifacts: artifactStatuses,
+  };
+}
@@ -0,0 +1,158 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getGlobalDataDir } from '../global-config.js';
+import { parseSchema, SchemaValidationError } from './schema.js';
+import type { SchemaYaml } from './types.js';
+
+/**
+ * Error thrown when loading a schema fails.
+ */
+export class SchemaLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly schemaPath: string,
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'SchemaLoadError';
+  }
+}
+
+/**
+ * Gets the package's built-in schemas directory path.
+ * Uses import.meta.url to resolve relative to the current module.
+ */
+export function getPackageSchemasDir(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  // Navigate from dist/core/artifact-graph/ to package root's schemas/
+  return path.join(path.dirname(currentFile), '..', '..', '..', 'schemas');
+}
+
+/**
+ * Gets the user's schema override directory path.
+ */
+export function getUserSchemasDir(): string {
+  return path.join(getGlobalDataDir(), 'schemas');
+}
+
+/**
+ * Resolves a schema name to its directory path.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The path to the schema directory, or null if not found
+ */
+export function getSchemaDir(name: string): string | null {
+  // 1. Check user override directory
+  const userDir = path.join(getUserSchemasDir(), name);
+  const userSchemaPath = path.join(userDir, 'schema.yaml');
+  if (fs.existsSync(userSchemaPath)) {
+    return userDir;
+  }
+
+  // 2. Check package built-in directory
+  const packageDir = path.join(getPackageSchemasDir(), name);
+  const packageSchemaPath = path.join(packageDir, 'schema.yaml');
+  if (fs.existsSync(packageSchemaPath)) {
+    return packageDir;
+  }
+
+  return null;
+}
+
+/**
+ * Resolves a schema name to a SchemaYaml object.
+ *
+ * Resolution order:
+ * 1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml
+ * 2. Package built-in: <package>/schemas/<name>/schema.yaml
+ *
+ * @param name - Schema name (e.g., "spec-driven")
+ * @returns The resolved schema object
+ * @throws Error if schema is not found in any location
+ */
+export function resolveSchema(name: string): SchemaYaml {
+  // Normalize name (remove .yaml extension if provided)
+  const normalizedName = name.replace(/\.ya?ml$/, '');
+
+  const schemaDir = getSchemaDir(normalizedName);
+  if (!schemaDir) {
+    const availableSchemas = listSchemas();
+    throw new Error(
+      `Schema '${normalizedName}' not found. Available schemas: ${availableSchemas.join(', ')}`
+    );
+  }
+
+  const schemaPath = path.join(schemaDir, 'schema.yaml');
+
+  // Load and parse the schema
+  let content: string;
+  try {
+    content = fs.readFileSync(schemaPath, 'utf-8');
+  } catch (err) {
+    const ioError = err instanceof Error ? err : new Error(String(err));
+    throw new SchemaLoadError(
+      `Failed to read schema at '${schemaPath}': ${ioError.message}`,
+      schemaPath,
+      ioError
+    );
+  }
+
+  try {
+    return parseSchema(content);
+  } catch (err) {
+    if (err instanceof SchemaValidationError) {
+      throw new SchemaLoadError(
+        `Invalid schema at '${schemaPath}': ${err.message}`,
+        schemaPath,
+        err
+      );
+    }
+    const parseError = err instanceof Error ? err : new Error(String(err));
+    throw new SchemaLoadError(
+      `Failed to parse schema at '${schemaPath}': ${parseError.message}`,
+      schemaPath,
+      parseError
+    );
+  }
+}
+
+/**
+ * Lists all available schema names.
+ * Combines user override and package built-in schemas.
+ */
+export function listSchemas(): string[] {
+  const schemas = new Set<string>();
+
+  // Add package built-in schemas
+  const packageDir = getPackageSchemasDir();
+  if (fs.existsSync(packageDir)) {
+    for (const entry of fs.readdirSync(packageDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        const schemaPath = path.join(packageDir, entry.name, 'schema.yaml');
+        if (fs.existsSync(schemaPath)) {
+          schemas.add(entry.name);
+        }
+      }
+    }
+  }
+
+  // Add user override schemas (may override package schemas)
+  const userDir = getUserSchemasDir();
+  if (fs.existsSync(userDir)) {
+    for (const entry of fs.readdirSync(userDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        const schemaPath = path.join(userDir, entry.name, 'schema.yaml');
+        if (fs.existsSync(schemaPath)) {
+          schemas.add(entry.name);
+        }
+      }
+    }
+  }
+
+  return Array.from(schemas).sort();
+}
@@ -0,0 +1,124 @@
+import * as fs from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import { SchemaYamlSchema, type SchemaYaml, type Artifact } from './types.js';
+
+export class SchemaValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SchemaValidationError';
+  }
+}
+
+/**
+ * Loads and validates an artifact schema from a YAML file.
+ */
+export function loadSchema(filePath: string): SchemaYaml {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  return parseSchema(content);
+}
+
+/**
+ * Parses and validates an artifact schema from YAML content.
+ */
+export function parseSchema(yamlContent: string): SchemaYaml {
+  const parsed = parseYaml(yamlContent);
+
+  // Validate with Zod
+  const result = SchemaYamlSchema.safeParse(parsed);
+  if (!result.success) {
+    const errors = result.error.issues.map(e => `${e.path.join('.')}: ${e.message}`).join(', ');
+    throw new SchemaValidationError(`Invalid schema: ${errors}`);
+  }
+
+  const schema = result.data;
+
+  // Check for duplicate artifact IDs
+  validateNoDuplicateIds(schema.artifacts);
+
+  // Check that all requires references are valid
+  validateRequiresReferences(schema.artifacts);
+
+  // Check for cycles
+  validateNoCycles(schema.artifacts);
+
+  return schema;
+}
+
+/**
+ * Validates that there are no duplicate artifact IDs.
+ */
+function validateNoDuplicateIds(artifacts: Artifact[]): void {
+  const seen = new Set<string>();
+  for (const artifact of artifacts) {
+    if (seen.has(artifact.id)) {
+      throw new SchemaValidationError(`Duplicate artifact ID: ${artifact.id}`);
+    }
+    seen.add(artifact.id);
+  }
+}
+
+/**
+ * Validates that all `requires` references point to valid artifact IDs.
+ */
+function validateRequiresReferences(artifacts: Artifact[]): void {
+  const validIds = new Set(artifacts.map(a => a.id));
+
+  for (const artifact of artifacts) {
+    for (const req of artifact.requires) {
+      if (!validIds.has(req)) {
+        throw new SchemaValidationError(
+          `Invalid dependency reference in artifact '${artifact.id}': '${req}' does not exist`
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Validates that there are no cyclic dependencies.
+ * Uses DFS to detect cycles and reports the full cycle path.
+ */
+function validateNoCycles(artifacts: Artifact[]): void {
+  const artifactMap = new Map(artifacts.map(a => [a.id, a]));
+  const visited = new Set<string>();
+  const inStack = new Set<string>();
+  const parent = new Map<string, string>();
+
+  function dfs(id: string): string | null {
+    visited.add(id);
+    inStack.add(id);
+
+    const artifact = artifactMap.get(id);
+    if (!artifact) return null;
+
+    for (const dep of artifact.requires) {
+      if (!visited.has(dep)) {
+        parent.set(dep, id);
+        const cycle = dfs(dep);
+        if (cycle) return cycle;
+      } else if (inStack.has(dep)) {
+        // Found a cycle - reconstruct the path
+        const cyclePath = [dep];
+        let current = id;
+        while (current !== dep) {
+          cyclePath.unshift(current);
+          current = parent.get(current)!;
+        }
+        cyclePath.unshift(dep);
+        return cyclePath.join(' → ');
+      }
+    }
+
+    inStack.delete(id);
+    return null;
+  }
+
+  for (const artifact of artifacts) {
+    if (!visited.has(artifact.id)) {
+      const cycle = dfs(artifact.id);
+      if (cycle) {
+        throw new SchemaValidationError(`Cyclic dependency detected: ${cycle}`);
+      }
+    }
+  }
+}
@@ -0,0 +1,64 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import type { CompletedSet } from './types.js';
+import type { ArtifactGraph } from './graph.js';
+import { FileSystemUtils } from '../../utils/file-system.js';
+
+/**
+ * Detects which artifacts are completed by checking file existence in the change directory.
+ * Returns a Set of completed artifact IDs.
+ *
+ * @param graph - The artifact graph to check
+ * @param changeDir - The change directory to scan for files
+ * @returns Set of artifact IDs whose generated files exist
+ */
+export function detectCompleted(graph: ArtifactGraph, changeDir: string): CompletedSet {
+  const completed = new Set<string>();
+
+  // Handle missing change directory gracefully
+  if (!fs.existsSync(changeDir)) {
+    return completed;
+  }
+
+  for (const artifact of graph.getAllArtifacts()) {
+    if (isArtifactComplete(artifact.generates, changeDir)) {
+      completed.add(artifact.id);
+    }
+  }
+
+  return completed;
+}
+
+/**
+ * Checks if an artifact is complete by checking if its generated file(s) exist.
+ * Supports both simple paths and glob patterns.
+ */
+function isArtifactComplete(generates: string, changeDir: string): boolean {
+  const fullPattern = path.join(changeDir, generates);
+
+  // Check if it's a glob pattern
+  if (isGlobPattern(generates)) {
+    return hasGlobMatches(fullPattern);
+  }
+
+  // Simple file path - check if file exists
+  return fs.existsSync(fullPattern);
+}
+
+/**
+ * Checks if a path contains glob pattern characters.
+ */
+function isGlobPattern(pattern: string): boolean {
+  return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
+}
+
+/**
+ * Checks if a glob pattern has any matches.
+ * Normalizes Windows backslashes to forward slashes for cross-platform glob compatibility.
+ */
+function hasGlobMatches(pattern: string): boolean {
+  const normalizedPattern = FileSystemUtils.toPosixPath(pattern);
+  const matches = fg.sync(normalizedPattern, { onlyFiles: true });
+  return matches.length > 0;
+}
@@ -0,0 +1,33 @@
+import { z } from 'zod';
+
+// Artifact definition schema
+export const ArtifactSchema = z.object({
+  id: z.string().min(1, { error: 'Artifact ID is required' }),
+  generates: z.string().min(1, { error: 'generates field is required' }),
+  description: z.string(),
+  template: z.string().min(1, { error: 'template field is required' }),
+  requires: z.array(z.string()).default([]),
+});
+
+// Full schema YAML structure
+export const SchemaYamlSchema = z.object({
+  name: z.string().min(1, { error: 'Schema name is required' }),
+  version: z.number().int().positive({ error: 'Version must be a positive integer' }),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1, { error: 'At least one artifact required' }),
+});
+
+// Derived TypeScript types
+export type Artifact = z.infer<typeof ArtifactSchema>;
+export type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+
+// Runtime state types (not Zod - internal only)
+
+// Slice 1: Simple completion tracking via filesystem
+export type CompletedSet = Set<string>;
+
+// Return type for blocked query
+export interface BlockedArtifacts {
+  [artifactId: string]: string[];
+}
+
@@ -0,0 +1,364 @@
+import { CommandDefinition, FlagDefinition } from './types.js';
+
+/**
+ * Common flags used across multiple commands
+ */
+const COMMON_FLAGS = {
+  json: {
+    name: 'json',
+    description: 'Output as JSON',
+  } as FlagDefinition,
+  jsonValidation: {
+    name: 'json',
+    description: 'Output validation results as JSON',
+  } as FlagDefinition,
+  strict: {
+    name: 'strict',
+    description: 'Enable strict validation mode',
+  } as FlagDefinition,
+  noInteractive: {
+    name: 'no-interactive',
+    description: 'Disable interactive prompts',
+  } as FlagDefinition,
+  type: {
+    name: 'type',
+    description: 'Specify item type when ambiguous',
+    takesValue: true,
+    values: ['change', 'spec'],
+  } as FlagDefinition,
+} as const;
+
+/**
+ * Registry of all OpenSpec CLI commands with their flags and metadata.
+ * This registry is used to generate shell completion scripts.
+ */
+export const COMMAND_REGISTRY: CommandDefinition[] = [
+  {
+    name: 'init',
+    description: 'Initialize OpenSpec in your project',
+    acceptsPositional: true,
+    positionalType: 'path',
+    flags: [
+      {
+        name: 'tools',
+        description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
+        takesValue: true,
+      },
+    ],
+  },
+  {
+    name: 'update',
+    description: 'Update OpenSpec instruction files',
+    acceptsPositional: true,
+    positionalType: 'path',
+    flags: [],
+  },
+  {
+    name: 'list',
+    description: 'List items (changes by default, or specs with --specs)',
+    flags: [
+      {
+        name: 'specs',
+        description: 'List specs instead of changes',
+      },
+      {
+        name: 'changes',
+        description: 'List changes explicitly (default)',
+      },
+    ],
+  },
+  {
+    name: 'view',
+    description: 'Display an interactive dashboard of specs and changes',
+    flags: [],
+  },
+  {
+    name: 'validate',
+    description: 'Validate changes and specs',
+    acceptsPositional: true,
+    positionalType: 'change-or-spec-id',
+    flags: [
+      {
+        name: 'all',
+        description: 'Validate all changes and specs',
+      },
+      {
+        name: 'changes',
+        description: 'Validate all changes',
+      },
+      {
+        name: 'specs',
+        description: 'Validate all specs',
+      },
+      COMMON_FLAGS.type,
+      COMMON_FLAGS.strict,
+      COMMON_FLAGS.jsonValidation,
+      {
+        name: 'concurrency',
+        description: 'Max concurrent validations (defaults to env OPENSPEC_CONCURRENCY or 6)',
+        takesValue: true,
+      },
+      COMMON_FLAGS.noInteractive,
+    ],
+  },
+  {
+    name: 'show',
+    description: 'Show a change or spec',
+    acceptsPositional: true,
+    positionalType: 'change-or-spec-id',
+    flags: [
+      COMMON_FLAGS.json,
+      COMMON_FLAGS.type,
+      COMMON_FLAGS.noInteractive,
+      {
+        name: 'deltas-only',
+        description: 'Show only deltas (JSON only, change-specific)',
+      },
+      {
+        name: 'requirements-only',
+        description: 'Alias for --deltas-only (deprecated, change-specific)',
+      },
+      {
+        name: 'requirements',
+        description: 'Show only requirements, exclude scenarios (JSON only, spec-specific)',
+      },
+      {
+        name: 'no-scenarios',
+        description: 'Exclude scenario content (JSON only, spec-specific)',
+      },
+      {
+        name: 'requirement',
+        short: 'r',
+        description: 'Show specific requirement by ID (JSON only, spec-specific)',
+        takesValue: true,
+      },
+    ],
+  },
+  {
+    name: 'archive',
+    description: 'Archive a completed change and update main specs',
+    acceptsPositional: true,
+    positionalType: 'change-id',
+    flags: [
+      {
+        name: 'yes',
+        short: 'y',
+        description: 'Skip confirmation prompts',
+      },
+      {
+        name: 'skip-specs',
+        description: 'Skip spec update operations',
+      },
+      {
+        name: 'no-validate',
+        description: 'Skip validation (not recommended)',
+      },
+    ],
+  },
+  {
+    name: 'change',
+    description: 'Manage OpenSpec change proposals (deprecated)',
+    flags: [],
+    subcommands: [
+      {
+        name: 'show',
+        description: 'Show a change proposal',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'deltas-only',
+            description: 'Show only deltas (JSON only)',
+          },
+          {
+            name: 'requirements-only',
+            description: 'Alias for --deltas-only (deprecated)',
+          },
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+      {
+        name: 'list',
+        description: 'List all active changes (deprecated)',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'long',
+            description: 'Show id and title with counts',
+          },
+        ],
+      },
+      {
+        name: 'validate',
+        description: 'Validate a change proposal',
+        acceptsPositional: true,
+        positionalType: 'change-id',
+        flags: [
+          COMMON_FLAGS.strict,
+          COMMON_FLAGS.jsonValidation,
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+    ],
+  },
+  {
+    name: 'spec',
+    description: 'Manage OpenSpec specifications',
+    flags: [],
+    subcommands: [
+      {
+        name: 'show',
+        description: 'Show a specification',
+        acceptsPositional: true,
+        positionalType: 'spec-id',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'requirements',
+            description: 'Show only requirements, exclude scenarios (JSON only)',
+          },
+          {
+            name: 'no-scenarios',
+            description: 'Exclude scenario content (JSON only)',
+          },
+          {
+            name: 'requirement',
+            short: 'r',
+            description: 'Show specific requirement by ID (JSON only)',
+            takesValue: true,
+          },
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+      {
+        name: 'list',
+        description: 'List all specifications',
+        flags: [
+          COMMON_FLAGS.json,
+          {
+            name: 'long',
+            description: 'Show id and title with counts',
+          },
+        ],
+      },
+      {
+        name: 'validate',
+        description: 'Validate a specification',
+        acceptsPositional: true,
+        positionalType: 'spec-id',
+        flags: [
+          COMMON_FLAGS.strict,
+          COMMON_FLAGS.jsonValidation,
+          COMMON_FLAGS.noInteractive,
+        ],
+      },
+    ],
+  },
+  {
+    name: 'completion',
+    description: 'Manage shell completions for OpenSpec CLI',
+    flags: [],
+    subcommands: [
+      {
+        name: 'generate',
+        description: 'Generate completion script for a shell (outputs to stdout)',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [],
+      },
+      {
+        name: 'install',
+        description: 'Install completion script for a shell',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [
+          {
+            name: 'verbose',
+            description: 'Show detailed installation output',
+          },
+        ],
+      },
+      {
+        name: 'uninstall',
+        description: 'Uninstall completion script for a shell',
+        acceptsPositional: true,
+        positionalType: 'shell',
+        flags: [],
+      },
+    ],
+  },
+  {
+    name: 'config',
+    description: 'View and modify global OpenSpec configuration',
+    flags: [
+      {
+        name: 'scope',
+        description: 'Config scope (only "global" supported currently)',
+        takesValue: true,
+        values: ['global'],
+      },
+    ],
+    subcommands: [
+      {
+        name: 'path',
+        description: 'Show config file location',
+        flags: [],
+      },
+      {
+        name: 'list',
+        description: 'Show all current settings',
+        flags: [
+          COMMON_FLAGS.json,
+        ],
+      },
+      {
+        name: 'get',
+        description: 'Get a specific value (raw, scriptable)',
+        acceptsPositional: true,
+        flags: [],
+      },
+      {
+        name: 'set',
+        description: 'Set a value (auto-coerce types)',
+        acceptsPositional: true,
+        flags: [
+          {
+            name: 'string',
+            description: 'Force value to be stored as string',
+          },
+          {
+            name: 'allow-unknown',
+            description: 'Allow setting unknown keys',
+          },
+        ],
+      },
+      {
+        name: 'unset',
+        description: 'Remove a key (revert to default)',
+        acceptsPositional: true,
+        flags: [],
+      },
+      {
+        name: 'reset',
+        description: 'Reset configuration to defaults',
+        flags: [
+          {
+            name: 'all',
+            description: 'Reset all configuration (required)',
+          },
+          {
+            name: 'yes',
+            short: 'y',
+            description: 'Skip confirmation prompts',
+          },
+        ],
+      },
+      {
+        name: 'edit',
+        description: 'Open config in $EDITOR',
+        flags: [],
+      },
+    ],
+  },
+];
@@ -0,0 +1,128 @@
+import { getActiveChangeIds, getSpecIds } from '../../utils/item-discovery.js';
+
+/**
+ * Cache entry for completion data
+ */
+interface CacheEntry<T> {
+  data: T;
+  timestamp: number;
+}
+
+/**
+ * Provides dynamic completion suggestions for OpenSpec items (changes and specs).
+ * Implements a 2-second cache to avoid excessive file system operations during
+ * tab completion.
+ */
+export class CompletionProvider {
+  private readonly cacheTTL: number;
+  private changeCache: CacheEntry<string[]> | null = null;
+  private specCache: CacheEntry<string[]> | null = null;
+
+  /**
+   * Creates a new completion provider
+   *
+   * @param cacheTTLMs - Cache time-to-live in milliseconds (default: 2000ms)
+   * @param projectRoot - Project root directory (default: process.cwd())
+   */
+  constructor(
+    private readonly cacheTTLMs: number = 2000,
+    private readonly projectRoot: string = process.cwd()
+  ) {
+    this.cacheTTL = cacheTTLMs;
+  }
+
+  /**
+   * Get all active change IDs for completion
+   *
+   * @returns Array of change IDs
+   */
+  async getChangeIds(): Promise<string[]> {
+    const now = Date.now();
+
+    // Check if cache is valid
+    if (this.changeCache && now - this.changeCache.timestamp < this.cacheTTL) {
+      return this.changeCache.data;
+    }
+
+    // Fetch fresh data
+    const changeIds = await getActiveChangeIds(this.projectRoot);
+
+    // Update cache
+    this.changeCache = {
+      data: changeIds,
+      timestamp: now,
+    };
+
+    return changeIds;
+  }
+
+  /**
+   * Get all spec IDs for completion
+   *
+   * @returns Array of spec IDs
+   */
+  async getSpecIds(): Promise<string[]> {
+    const now = Date.now();
+
+    // Check if cache is valid
+    if (this.specCache && now - this.specCache.timestamp < this.cacheTTL) {
+      return this.specCache.data;
+    }
+
+    // Fetch fresh data
+    const specIds = await getSpecIds(this.projectRoot);
+
+    // Update cache
+    this.specCache = {
+      data: specIds,
+      timestamp: now,
+    };
+
+    return specIds;
+  }
+
+  /**
+   * Get both change and spec IDs for completion
+   *
+   * @returns Object with changeIds and specIds arrays
+   */
+  async getAllIds(): Promise<{ changeIds: string[]; specIds: string[] }> {
+    const [changeIds, specIds] = await Promise.all([
+      this.getChangeIds(),
+      this.getSpecIds(),
+    ]);
+
+    return { changeIds, specIds };
+  }
+
+  /**
+   * Clear all cached data
+   */
+  clearCache(): void {
+    this.changeCache = null;
+    this.specCache = null;
+  }
+
+  /**
+   * Get cache statistics for debugging
+   *
+   * @returns Cache status information
+   */
+  getCacheStats(): {
+    changeCache: { valid: boolean; age?: number };
+    specCache: { valid: boolean; age?: number };
+  } {
+    const now = Date.now();
+
+    return {
+      changeCache: {
+        valid: this.changeCache !== null && now - this.changeCache.timestamp < this.cacheTTL,
+        age: this.changeCache ? now - this.changeCache.timestamp : undefined,
+      },
+      specCache: {
+        valid: this.specCache !== null && now - this.specCache.timestamp < this.cacheTTL,
+        age: this.specCache ? now - this.specCache.timestamp : undefined,
+      },
+    };
+  }
+}
@@ -0,0 +1,74 @@
+import { CompletionGenerator } from './types.js';
+import { ZshGenerator } from './generators/zsh-generator.js';
+import { ZshInstaller, InstallationResult } from './installers/zsh-installer.js';
+import { SupportedShell } from '../../utils/shell-detection.js';
+
+/**
+ * Interface for completion installers
+ */
+export interface CompletionInstaller {
+  install(script: string): Promise<InstallationResult>;
+  uninstall(): Promise<{ success: boolean; message: string }>;
+}
+
+// Re-export InstallationResult for convenience
+export type { InstallationResult };
+
+/**
+ * Factory for creating completion generators and installers
+ * This design makes it easy to add support for additional shells
+ */
+export class CompletionFactory {
+  private static readonly SUPPORTED_SHELLS: SupportedShell[] = ['zsh'];
+
+  /**
+   * Create a completion generator for the specified shell
+   *
+   * @param shell - The target shell
+   * @returns CompletionGenerator instance
+   * @throws Error if shell is not supported
+   */
+  static createGenerator(shell: SupportedShell): CompletionGenerator {
+    switch (shell) {
+      case 'zsh':
+        return new ZshGenerator();
+      default:
+        throw new Error(`Unsupported shell: ${shell}`);
+    }
+  }
+
+  /**
+   * Create a completion installer for the specified shell
+   *
+   * @param shell - The target shell
+   * @returns CompletionInstaller instance
+   * @throws Error if shell is not supported
+   */
+  static createInstaller(shell: SupportedShell): CompletionInstaller {
+    switch (shell) {
+      case 'zsh':
+        return new ZshInstaller();
+      default:
+        throw new Error(`Unsupported shell: ${shell}`);
+    }
+  }
+
+  /**
+   * Check if a shell is supported
+   *
+   * @param shell - The shell to check
+   * @returns true if the shell is supported
+   */
+  static isSupported(shell: string): shell is SupportedShell {
+    return this.SUPPORTED_SHELLS.includes(shell as SupportedShell);
+  }
+
+  /**
+   * Get list of all supported shells
+   *
+   * @returns Array of supported shell names
+   */
+  static getSupportedShells(): SupportedShell[] {
+    return [...this.SUPPORTED_SHELLS];
+  }
+}
@@ -0,0 +1,374 @@
+import { CompletionGenerator, CommandDefinition, FlagDefinition } from '../types.js';
+
+/**
+ * Generates Zsh completion scripts for the OpenSpec CLI.
+ * Follows Zsh completion system conventions using the _openspec function.
+ */
+export class ZshGenerator implements CompletionGenerator {
+  readonly shell = 'zsh' as const;
+
+  /**
+   * Generate a Zsh completion script
+   *
+   * @param commands - Command definitions to generate completions for
+   * @returns Zsh completion script as a string
+   */
+  generate(commands: CommandDefinition[]): string {
+    const script: string[] = [];
+
+    // Header comment
+    script.push('#compdef openspec');
+    script.push('');
+    script.push('# Zsh completion script for OpenSpec CLI');
+    script.push('# Auto-generated - do not edit manually');
+    script.push('');
+
+    // Main completion function
+    script.push('_openspec() {');
+    script.push('  local context state line');
+    script.push('  typeset -A opt_args');
+    script.push('');
+
+    // Generate main command argument specification
+    script.push('  local -a commands');
+    script.push('  commands=(');
+    for (const cmd of commands) {
+      const escapedDesc = this.escapeDescription(cmd.description);
+      script.push(`    '${cmd.name}:${escapedDesc}'`);
+    }
+    script.push('  )');
+    script.push('');
+
+    // Main _arguments call
+    script.push('  _arguments -C \\');
+    script.push('    "1: :->command" \\');
+    script.push('    "*::arg:->args"');
+    script.push('');
+
+    // Command dispatch logic
+    script.push('  case $state in');
+    script.push('    command)');
+    script.push('      _describe "openspec command" commands');
+    script.push('      ;;');
+    script.push('    args)');
+    script.push('      case $words[1] in');
+
+    // Generate completion for each command
+    for (const cmd of commands) {
+      script.push(`        ${cmd.name})`);
+      script.push(`          _openspec_${this.sanitizeFunctionName(cmd.name)}`);
+      script.push('          ;;');
+    }
+
+    script.push('      esac');
+    script.push('      ;;');
+    script.push('  esac');
+    script.push('}');
+    script.push('');
+
+    // Generate individual command completion functions
+    for (const cmd of commands) {
+      script.push(...this.generateCommandFunction(cmd));
+      script.push('');
+    }
+
+    // Add dynamic completion helper functions
+    script.push(...this.generateDynamicCompletionHelpers());
+
+    // Register the completion function
+    script.push('compdef _openspec openspec');
+    script.push('');
+
+    return script.join('\n');
+  }
+
+  /**
+   * Generate a single completion function
+   *
+   * @param functionName - Name of the completion function
+   * @param varName - Name of the local array variable
+   * @param varLabel - Label for the completion items
+   * @param commandLines - Command line(s) to populate the array
+   * @param comment - Optional comment describing the function
+   */
+  private generateCompletionFunction(
+    functionName: string,
+    varName: string,
+    varLabel: string,
+    commandLines: string[],
+    comment?: string
+  ): string[] {
+    const lines: string[] = [];
+
+    if (comment) {
+      lines.push(comment);
+    }
+
+    lines.push(`${functionName}() {`);
+    lines.push(`  local -a ${varName}`);
+
+    if (commandLines.length === 1) {
+      lines.push(`  ${commandLines[0]}`);
+    } else {
+      lines.push(`  ${varName}=(`);
+      for (let i = 0; i < commandLines.length; i++) {
+        const suffix = i < commandLines.length - 1 ? ' \\' : '';
+        lines.push(`    ${commandLines[i]}${suffix}`);
+      }
+      lines.push('  )');
+    }
+
+    lines.push(`  _describe "${varLabel}" ${varName}`);
+    lines.push('}');
+    lines.push('');
+
+    return lines;
+  }
+
+  /**
+   * Generate dynamic completion helper functions for change and spec IDs
+   */
+  private generateDynamicCompletionHelpers(): string[] {
+    const lines: string[] = [];
+
+    lines.push('# Dynamic completion helpers');
+    lines.push('');
+
+    // Helper function for completing change IDs
+    lines.push('# Use openspec __complete to get available changes');
+    lines.push('_openspec_complete_changes() {');
+    lines.push('  local -a changes');
+    lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+    lines.push('    changes+=("$id:$desc")');
+    lines.push('  done < <(openspec __complete changes 2>/dev/null)');
+    lines.push('  _describe "change" changes');
+    lines.push('}');
+    lines.push('');
+
+    // Helper function for completing spec IDs
+    lines.push('# Use openspec __complete to get available specs');
+    lines.push('_openspec_complete_specs() {');
+    lines.push('  local -a specs');
+    lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+    lines.push('    specs+=("$id:$desc")');
+    lines.push('  done < <(openspec __complete specs 2>/dev/null)');
+    lines.push('  _describe "spec" specs');
+    lines.push('}');
+    lines.push('');
+
+    // Helper function for completing both changes and specs
+    lines.push('# Get both changes and specs');
+    lines.push('_openspec_complete_items() {');
+    lines.push('  local -a items');
+    lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+    lines.push('    items+=("$id:$desc")');
+    lines.push('  done < <(openspec __complete changes 2>/dev/null)');
+    lines.push('  while IFS=$\'\\t\' read -r id desc; do');
+    lines.push('    items+=("$id:$desc")');
+    lines.push('  done < <(openspec __complete specs 2>/dev/null)');
+    lines.push('  _describe "item" items');
+    lines.push('}');
+    lines.push('');
+
+    return lines;
+  }
+
+  /**
+   * Generate completion function for a specific command
+   */
+  private generateCommandFunction(cmd: CommandDefinition): string[] {
+    const funcName = `_openspec_${this.sanitizeFunctionName(cmd.name)}`;
+    const lines: string[] = [];
+
+    lines.push(`${funcName}() {`);
+
+    // If command has subcommands, handle them
+    if (cmd.subcommands && cmd.subcommands.length > 0) {
+      lines.push('  local context state line');
+      lines.push('  typeset -A opt_args');
+      lines.push('');
+      lines.push('  local -a subcommands');
+      lines.push('  subcommands=(');
+
+      for (const subcmd of cmd.subcommands) {
+        const escapedDesc = this.escapeDescription(subcmd.description);
+        lines.push(`    '${subcmd.name}:${escapedDesc}'`);
+      }
+
+      lines.push('  )');
+      lines.push('');
+      lines.push('  _arguments -C \\');
+
+      // Add command flags
+      for (const flag of cmd.flags) {
+        lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+      }
+
+      lines.push('    "1: :->subcommand" \\');
+      lines.push('    "*::arg:->args"');
+      lines.push('');
+      lines.push('  case $state in');
+      lines.push('    subcommand)');
+      lines.push('      _describe "subcommand" subcommands');
+      lines.push('      ;;');
+      lines.push('    args)');
+      lines.push('      case $words[1] in');
+
+      for (const subcmd of cmd.subcommands) {
+        lines.push(`        ${subcmd.name})`);
+        lines.push(`          _openspec_${this.sanitizeFunctionName(cmd.name)}_${this.sanitizeFunctionName(subcmd.name)}`);
+        lines.push('          ;;');
+      }
+
+      lines.push('      esac');
+      lines.push('      ;;');
+      lines.push('  esac');
+    } else {
+      // Command without subcommands
+      lines.push('  _arguments \\');
+
+      // Add flags
+      for (const flag of cmd.flags) {
+        lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+      }
+
+      // Add positional argument completion
+      if (cmd.acceptsPositional) {
+        const positionalSpec = this.generatePositionalSpec(cmd.positionalType);
+        lines.push('    ' + positionalSpec);
+      } else {
+        // Remove trailing backslash from last flag
+        if (lines[lines.length - 1].endsWith(' \\')) {
+          lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+        }
+      }
+    }
+
+    lines.push('}');
+
+    // Generate subcommand functions if they exist
+    if (cmd.subcommands) {
+      for (const subcmd of cmd.subcommands) {
+        lines.push('');
+        lines.push(...this.generateSubcommandFunction(cmd.name, subcmd));
+      }
+    }
+
+    return lines;
+  }
+
+  /**
+   * Generate completion function for a subcommand
+   */
+  private generateSubcommandFunction(parentName: string, subcmd: CommandDefinition): string[] {
+    const funcName = `_openspec_${this.sanitizeFunctionName(parentName)}_${this.sanitizeFunctionName(subcmd.name)}`;
+    const lines: string[] = [];
+
+    lines.push(`${funcName}() {`);
+    lines.push('  _arguments \\');
+
+    // Add flags
+    for (const flag of subcmd.flags) {
+      lines.push('    ' + this.generateFlagSpec(flag) + ' \\');
+    }
+
+    // Add positional argument completion
+    if (subcmd.acceptsPositional) {
+      const positionalSpec = this.generatePositionalSpec(subcmd.positionalType);
+      lines.push('    ' + positionalSpec);
+    } else {
+      // Remove trailing backslash from last flag
+      if (lines[lines.length - 1].endsWith(' \\')) {
+        lines[lines.length - 1] = lines[lines.length - 1].slice(0, -2);
+      }
+    }
+
+    lines.push('}');
+
+    return lines;
+  }
+
+  /**
+   * Generate flag specification for _arguments
+   */
+  private generateFlagSpec(flag: FlagDefinition): string {
+    const parts: string[] = [];
+
+    // Handle mutually exclusive short and long forms
+    if (flag.short) {
+      parts.push(`'(-${flag.short} --${flag.name})'{-${flag.short},--${flag.name}}'`);
+    } else {
+      parts.push(`'--${flag.name}`);
+    }
+
+    // Add description
+    const escapedDesc = this.escapeDescription(flag.description);
+    parts.push(`[${escapedDesc}]`);
+
+    // Add value completion if flag takes a value
+    if (flag.takesValue) {
+      if (flag.values && flag.values.length > 0) {
+        // Provide specific value completions
+        const valueList = flag.values.map(v => this.escapeValue(v)).join(' ');
+        parts.push(`:value:(${valueList})`);
+      } else {
+        // Generic value placeholder
+        parts.push(':value:');
+      }
+    }
+
+    // Close the quote (needed for both short and long forms)
+    parts.push("'");
+
+    return parts.join('');
+  }
+
+  /**
+   * Generate positional argument specification
+   */
+  private generatePositionalSpec(positionalType?: string): string {
+    switch (positionalType) {
+      case 'change-id':
+        return "'*: :_openspec_complete_changes'";
+      case 'spec-id':
+        return "'*: :_openspec_complete_specs'";
+      case 'change-or-spec-id':
+        return "'*: :_openspec_complete_items'";
+      case 'path':
+        return "'*:path:_files'";
+      case 'shell':
+        return "'*:shell:(zsh)'";
+      default:
+        return "'*: :_default'";
+    }
+  }
+
+  /**
+   * Escape special characters in descriptions
+   */
+  private escapeDescription(desc: string): string {
+    return desc
+      .replace(/\\/g, '\\\\')
+      .replace(/'/g, "\\'")
+      .replace(/\[/g, '\\[')
+      .replace(/]/g, '\\]')
+      .replace(/:/g, '\\:');
+  }
+
+  /**
+   * Escape special characters in values
+   */
+  private escapeValue(value: string): string {
+    return value
+      .replace(/\\/g, '\\\\')
+      .replace(/'/g, "\\'")
+      .replace(/ /g, '\\ ');
+  }
+
+  /**
+   * Sanitize command names for use in function names
+   */
+  private sanitizeFunctionName(name: string): string {
+    return name.replace(/-/g, '_');
+  }
+}
@@ -0,0 +1,507 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { FileSystemUtils } from '../../../utils/file-system.js';
+
+/**
+ * Installation result information
+ */
+export interface InstallationResult {
+  success: boolean;
+  installedPath?: string;
+  backupPath?: string;
+  isOhMyZsh: boolean;
+  zshrcConfigured?: boolean;
+  message: string;
+  instructions?: string[];
+}
+
+/**
+ * Installer for Zsh completion scripts.
+ * Supports both Oh My Zsh and standard Zsh configurations.
+ */
+export class ZshInstaller {
+  private readonly homeDir: string;
+
+  /**
+   * Markers for .zshrc configuration management
+   */
+  private readonly ZSHRC_MARKERS = {
+    start: '# OPENSPEC:START',
+    end: '# OPENSPEC:END',
+  };
+
+  constructor(homeDir: string = os.homedir()) {
+    this.homeDir = homeDir;
+  }
+
+  /**
+   * Check if Oh My Zsh is installed
+   *
+   * @returns true if Oh My Zsh is detected via $ZSH env var or directory exists
+   */
+  async isOhMyZshInstalled(): Promise<boolean> {
+    // First check for $ZSH environment variable (standard OMZ setup)
+    if (process.env.ZSH) {
+      return true;
+    }
+
+    // Fall back to checking for ~/.oh-my-zsh directory
+    const ohMyZshPath = path.join(this.homeDir, '.oh-my-zsh');
+
+    try {
+      const stat = await fs.stat(ohMyZshPath);
+      return stat.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get the appropriate installation path for the completion script
+   *
+   * @returns Object with installation path and whether it's Oh My Zsh
+   */
+  async getInstallationPath(): Promise<{ path: string; isOhMyZsh: boolean }> {
+    const isOhMyZsh = await this.isOhMyZshInstalled();
+
+    if (isOhMyZsh) {
+      // Oh My Zsh custom completions directory
+      return {
+        path: path.join(this.homeDir, '.oh-my-zsh', 'custom', 'completions', '_openspec'),
+        isOhMyZsh: true,
+      };
+    } else {
+      // Standard Zsh completions directory
+      return {
+        path: path.join(this.homeDir, '.zsh', 'completions', '_openspec'),
+        isOhMyZsh: false,
+      };
+    }
+  }
+
+  /**
+   * Backup an existing completion file if it exists
+   *
+   * @param targetPath - Path to the file to backup
+   * @returns Path to the backup file, or undefined if no backup was needed
+   */
+  async backupExistingFile(targetPath: string): Promise<string | undefined> {
+    try {
+      await fs.access(targetPath);
+      // File exists, create a backup
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const backupPath = `${targetPath}.backup-${timestamp}`;
+      await fs.copyFile(targetPath, backupPath);
+      return backupPath;
+    } catch {
+      // File doesn't exist, no backup needed
+      return undefined;
+    }
+  }
+
+  /**
+   * Get the path to .zshrc file
+   *
+   * @returns Path to .zshrc
+   */
+  private getZshrcPath(): string {
+    return path.join(this.homeDir, '.zshrc');
+  }
+
+  /**
+   * Generate .zshrc configuration content
+   *
+   * @param completionsDir - Directory containing completion scripts
+   * @returns Configuration content
+   */
+  private generateZshrcConfig(completionsDir: string): string {
+    return [
+      '# OpenSpec shell completions configuration',
+      `fpath=("${completionsDir}" $fpath)`,
+      'autoload -Uz compinit',
+      'compinit',
+    ].join('\n');
+  }
+
+  /**
+   * Configure .zshrc to enable completions
+   * Only applies to standard Zsh (not Oh My Zsh)
+   *
+   * @param completionsDir - Directory containing completion scripts
+   * @returns true if configured successfully, false otherwise
+   */
+  async configureZshrc(completionsDir: string): Promise<boolean> {
+    // Check if auto-configuration is disabled
+    if (process.env.OPENSPEC_NO_AUTO_CONFIG === '1') {
+      return false;
+    }
+
+    try {
+      const zshrcPath = this.getZshrcPath();
+      const config = this.generateZshrcConfig(completionsDir);
+
+      // Check write permissions
+      const canWrite = await FileSystemUtils.canWriteFile(zshrcPath);
+      if (!canWrite) {
+        return false;
+      }
+
+      // Use marker-based update
+      await FileSystemUtils.updateFileWithMarkers(
+        zshrcPath,
+        config,
+        this.ZSHRC_MARKERS.start,
+        this.ZSHRC_MARKERS.end
+      );
+
+      return true;
+    } catch (error: any) {
+      // Fail gracefully - don't break installation
+      console.debug(`Unable to configure .zshrc for completions: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Check if .zshrc has OpenSpec configuration markers
+   *
+   * @returns true if .zshrc exists and has markers
+   */
+  private async hasZshrcConfig(): Promise<boolean> {
+    try {
+      const zshrcPath = this.getZshrcPath();
+      const content = await fs.readFile(zshrcPath, 'utf-8');
+      return content.includes(this.ZSHRC_MARKERS.start) && content.includes(this.ZSHRC_MARKERS.end);
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check if fpath configuration is needed for a given directory
+   * Used to verify if Oh My Zsh (or other) completions directory is already in fpath
+   *
+   * @param completionsDir - Directory to check for in fpath
+   * @returns true if configuration is needed, false if directory is already referenced
+   */
+  private async needsFpathConfig(completionsDir: string): Promise<boolean> {
+    try {
+      const zshrcPath = this.getZshrcPath();
+      const content = await fs.readFile(zshrcPath, 'utf-8');
+
+      // Check if fpath already includes this directory
+      return !content.includes(completionsDir);
+    } catch (error) {
+      // If we can't read .zshrc, assume config is needed
+      console.debug(`Unable to read .zshrc to check fpath config: ${error instanceof Error ? error.message : String(error)}`);
+      return true;
+    }
+  }
+
+  /**
+   * Remove .zshrc configuration
+   * Used during uninstallation
+   *
+   * @returns true if removed successfully, false otherwise
+   */
+  async removeZshrcConfig(): Promise<boolean> {
+    try {
+      const zshrcPath = this.getZshrcPath();
+
+      // Check if file exists
+      try {
+        await fs.access(zshrcPath);
+      } catch {
+        // File doesn't exist, nothing to remove
+        return true;
+      }
+
+      // Read file content
+      const content = await fs.readFile(zshrcPath, 'utf-8');
+
+      // Check if markers exist
+      if (!content.includes(this.ZSHRC_MARKERS.start) || !content.includes(this.ZSHRC_MARKERS.end)) {
+        // Markers don't exist, nothing to remove
+        return true;
+      }
+
+      // Remove content between markers (including markers)
+      const lines = content.split('\n');
+      const startIndex = lines.findIndex((line) => line.trim() === this.ZSHRC_MARKERS.start);
+      const endIndex = lines.findIndex((line) => line.trim() === this.ZSHRC_MARKERS.end);
+
+      if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+        // Invalid marker placement
+        return false;
+      }
+
+      // Remove lines between markers (inclusive)
+      lines.splice(startIndex, endIndex - startIndex + 1);
+
+      // Remove trailing empty lines at the start if the markers were at the top
+      while (lines.length > 0 && lines[0].trim() === '') {
+        lines.shift();
+      }
+
+      // Write back
+      await fs.writeFile(zshrcPath, lines.join('\n'), 'utf-8');
+
+      return true;
+    } catch (error: any) {
+      // Fail gracefully
+      console.debug(`Unable to remove .zshrc configuration: ${error.message}`);
+      return false;
+    }
+  }
+
+  /**
+   * Install the completion script
+   *
+   * @param completionScript - The completion script content to install
+   * @returns Installation result with status and instructions
+   */
+  async install(completionScript: string): Promise<InstallationResult> {
+    try {
+      const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+
+      // Check if already installed with same content
+      let isUpdate = false;
+      try {
+        const existingContent = await fs.readFile(targetPath, 'utf-8');
+        if (existingContent === completionScript) {
+          // Already installed and up to date
+          return {
+            success: true,
+            installedPath: targetPath,
+            isOhMyZsh,
+            message: 'Completion script is already installed (up to date)',
+            instructions: [
+              'The completion script is already installed and up to date.',
+              'If completions are not working, try: exec zsh',
+            ],
+          };
+        }
+        // File exists but content is different - this is an update
+        isUpdate = true;
+      } catch (error: any) {
+        // File doesn't exist or can't be read, proceed with installation
+        console.debug(`Unable to read existing completion file at ${targetPath}: ${error.message}`);
+      }
+
+      // Ensure the directory exists
+      const targetDir = path.dirname(targetPath);
+      await fs.mkdir(targetDir, { recursive: true });
+
+      // Backup existing file if updating
+      const backupPath = isUpdate ? await this.backupExistingFile(targetPath) : undefined;
+
+      // Write the completion script
+      await fs.writeFile(targetPath, completionScript, 'utf-8');
+
+      // Auto-configure .zshrc
+      let zshrcConfigured = false;
+      if (isOhMyZsh) {
+        // For Oh My Zsh, verify that custom/completions is in fpath
+        // If not, add it to .zshrc
+        const needsConfig = await this.needsFpathConfig(targetDir);
+        if (needsConfig) {
+          zshrcConfigured = await this.configureZshrc(targetDir);
+        }
+      } else {
+        // Standard Zsh always needs .zshrc configuration
+        zshrcConfigured = await this.configureZshrc(targetDir);
+      }
+
+      // Generate instructions (only if .zshrc wasn't auto-configured)
+      let instructions = zshrcConfigured ? undefined : this.generateInstructions(isOhMyZsh, targetPath);
+
+      // Add fpath guidance for Oh My Zsh installations
+      if (isOhMyZsh) {
+        const fpathGuidance = this.generateOhMyZshFpathGuidance(targetDir);
+        if (fpathGuidance) {
+          instructions = instructions ? [...instructions, '', ...fpathGuidance] : fpathGuidance;
+        }
+      }
+
+      // Determine appropriate message based on update status
+      let message: string;
+      if (isUpdate) {
+        message = backupPath
+          ? 'Completion script updated successfully (previous version backed up)'
+          : 'Completion script updated successfully';
+      } else {
+        message = isOhMyZsh
+          ? 'Completion script installed successfully for Oh My Zsh'
+          : zshrcConfigured
+            ? 'Completion script installed and .zshrc configured successfully'
+            : 'Completion script installed successfully for Zsh';
+      }
+
+      return {
+        success: true,
+        installedPath: targetPath,
+        backupPath,
+        isOhMyZsh,
+        zshrcConfigured,
+        message,
+        instructions,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        isOhMyZsh: false,
+        message: `Failed to install completion script: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  /**
+   * Generate Oh My Zsh fpath verification guidance
+   *
+   * @param completionsDir - Custom completions directory path
+   * @returns Array of guidance strings, or undefined if not needed
+   */
+  private generateOhMyZshFpathGuidance(completionsDir: string): string[] | undefined {
+    return [
+      'Note: Oh My Zsh typically auto-loads completions from custom/completions.',
+      `Verify that ${completionsDir} is in your fpath by running:`,
+      '  echo $fpath | grep "custom/completions"',
+      '',
+      'If not found, completions may not work. Restart your shell to ensure changes take effect.',
+    ];
+  }
+
+  /**
+   * Generate user instructions for enabling completions
+   *
+   * @param isOhMyZsh - Whether Oh My Zsh is being used
+   * @param installedPath - Path where the script was installed
+   * @returns Array of instruction strings
+   */
+  private generateInstructions(isOhMyZsh: boolean, installedPath: string): string[] {
+    if (isOhMyZsh) {
+      return [
+        'Completion script installed to Oh My Zsh completions directory.',
+        'Restart your shell or run: exec zsh',
+        'Completions should activate automatically.',
+      ];
+    } else {
+      const completionsDir = path.dirname(installedPath);
+      const zshrcPath = path.join(this.homeDir, '.zshrc');
+
+      return [
+        'Completion script installed to ~/.zsh/completions/',
+        '',
+        'To enable completions, add the following to your ~/.zshrc file:',
+        '',
+        `  # Add completions directory to fpath`,
+        `  fpath=(${completionsDir} $fpath)`,
+        '',
+        '  # Initialize completion system',
+        '  autoload -Uz compinit',
+        '  compinit',
+        '',
+        'Then restart your shell or run: exec zsh',
+        '',
+        `Check if these lines already exist in ${zshrcPath} before adding.`,
+      ];
+    }
+  }
+
+  /**
+   * Uninstall the completion script
+   *
+   * @returns true if uninstalled successfully, false otherwise
+   */
+  async uninstall(): Promise<{ success: boolean; message: string }> {
+    try {
+      const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+
+      // Try to remove completion script
+      let scriptRemoved = false;
+      try {
+        await fs.access(targetPath);
+        await fs.unlink(targetPath);
+        scriptRemoved = true;
+      } catch {
+        // Script not installed
+      }
+
+      // Try to remove .zshrc configuration (only for standard Zsh)
+      let zshrcWasPresent = false;
+      let zshrcCleaned = false;
+      if (!isOhMyZsh) {
+        zshrcWasPresent = await this.hasZshrcConfig();
+        if (zshrcWasPresent) {
+          zshrcCleaned = await this.removeZshrcConfig();
+        }
+      }
+
+      if (!scriptRemoved && !zshrcWasPresent) {
+        return {
+          success: false,
+          message: 'Completion script is not installed',
+        };
+      }
+
+      const messages: string[] = [];
+      if (scriptRemoved) {
+        messages.push(`Completion script removed from ${targetPath}`);
+      }
+      if (zshrcCleaned && !isOhMyZsh) {
+        messages.push('Removed OpenSpec configuration from ~/.zshrc');
+      }
+
+      return {
+        success: true,
+        message: messages.join('. '),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: `Failed to uninstall completion script: ${error instanceof Error ? error.message : String(error)}`,
+      };
+    }
+  }
+
+  /**
+   * Check if completion script is currently installed
+   *
+   * @returns true if the completion script exists
+   */
+  async isInstalled(): Promise<boolean> {
+    try {
+      const { path: targetPath } = await this.getInstallationPath();
+      await fs.access(targetPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Get information about the current installation
+   *
+   * @returns Installation status information
+   */
+  async getInstallationInfo(): Promise<{
+    installed: boolean;
+    path?: string;
+    isOhMyZsh?: boolean;
+  }> {
+    const installed = await this.isInstalled();
+
+    if (!installed) {
+      return { installed: false };
+    }
+
+    const { path: targetPath, isOhMyZsh } = await this.getInstallationPath();
+
+    return {
+      installed: true,
+      path: targetPath,
+      isOhMyZsh,
+    };
+  }
+}
@@ -0,0 +1,90 @@
+import { SupportedShell } from '../../utils/shell-detection.js';
+
+/**
+ * Definition of a command-line flag/option
+ */
+export interface FlagDefinition {
+  /**
+   * Flag name without dashes (e.g., "json", "strict", "no-interactive")
+   */
+  name: string;
+
+  /**
+   * Short flag name without dash (e.g., "y" for "-y")
+   */
+  short?: string;
+
+  /**
+   * Human-readable description of what the flag does
+   */
+  description: string;
+
+  /**
+   * Whether the flag takes an argument value
+   */
+  takesValue?: boolean;
+
+  /**
+   * Possible values for the flag (for completion suggestions)
+   */
+  values?: string[];
+}
+
+/**
+ * Definition of a CLI command
+ */
+export interface CommandDefinition {
+  /**
+   * Command name (e.g., "init", "validate", "show")
+   */
+  name: string;
+
+  /**
+   * Human-readable description of the command
+   */
+  description: string;
+
+  /**
+   * Flags/options supported by this command
+   */
+  flags: FlagDefinition[];
+
+  /**
+   * Subcommands (e.g., "change show", "spec validate")
+   */
+  subcommands?: CommandDefinition[];
+
+  /**
+   * Whether this command accepts a positional argument (e.g., item name, path)
+   */
+  acceptsPositional?: boolean;
+
+  /**
+   * Type of positional argument for dynamic completion
+   * - 'change-id': Complete with active change IDs
+   * - 'spec-id': Complete with spec IDs
+   * - 'change-or-spec-id': Complete with both changes and specs
+   * - 'path': Complete with file paths
+   * - 'shell': Complete with supported shell names
+   * - undefined: No specific completion
+   */
+  positionalType?: 'change-id' | 'spec-id' | 'change-or-spec-id' | 'path' | 'shell';
+}
+
+/**
+ * Interface for shell-specific completion script generators
+ */
+export interface CompletionGenerator {
+  /**
+   * The shell type this generator targets
+   */
+  readonly shell: SupportedShell;
+
+  /**
+   * Generate the completion script content
+   *
+   * @param commands - Command definitions to generate completions for
+   * @returns The shell-specific completion script as a string
+   */
+  generate(commands: CommandDefinition[]): string;
+}
@@ -0,0 +1,230 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for global OpenSpec configuration.
+ * Uses passthrough() to preserve unknown fields for forward compatibility.
+ */
+export const GlobalConfigSchema = z
+  .object({
+    featureFlags: z
+      .record(z.string(), z.boolean())
+      .optional()
+      .default({}),
+  })
+  .passthrough();
+
+export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
+
+/**
+ * Default configuration values.
+ */
+export const DEFAULT_CONFIG: GlobalConfigType = {
+  featureFlags: {},
+};
+
+const KNOWN_TOP_LEVEL_KEYS = new Set(Object.keys(DEFAULT_CONFIG));
+
+/**
+ * Validate a config key path for CLI set operations.
+ * Unknown top-level keys are rejected unless explicitly allowed by the caller.
+ */
+export function validateConfigKeyPath(path: string): { valid: boolean; reason?: string } {
+  const rawKeys = path.split('.');
+
+  if (rawKeys.length === 0 || rawKeys.some((key) => key.trim() === '')) {
+    return { valid: false, reason: 'Key path must not be empty' };
+  }
+
+  const rootKey = rawKeys[0];
+  if (!KNOWN_TOP_LEVEL_KEYS.has(rootKey)) {
+    return { valid: false, reason: `Unknown top-level key "${rootKey}"` };
+  }
+
+  if (rootKey === 'featureFlags') {
+    if (rawKeys.length > 2) {
+      return { valid: false, reason: 'featureFlags values are booleans and do not support nested keys' };
+    }
+    return { valid: true };
+  }
+
+  if (rawKeys.length > 1) {
+    return { valid: false, reason: `"${rootKey}" does not support nested keys` };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Get a nested value from an object using dot notation.
+ *
+ * @param obj - The object to access
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns The value at the path, or undefined if not found
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+  const keys = path.split('.');
+  let current: unknown = obj;
+
+  for (const key of keys) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    if (typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[key];
+  }
+
+  return current;
+}
+
+/**
+ * Set a nested value in an object using dot notation.
+ * Creates intermediate objects as needed.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @param value - The value to set
+ */
+export function setNestedValue(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const keys = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+      current[key] = {};
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+
+  const lastKey = keys[keys.length - 1];
+  current[lastKey] = value;
+}
+
+/**
+ * Delete a nested value from an object using dot notation.
+ *
+ * @param obj - The object to modify (mutated in place)
+ * @param path - Dot-separated path (e.g., "featureFlags.someFlag")
+ * @returns true if the key existed and was deleted, false otherwise
+ */
+export function deleteNestedValue(obj: Record<string, unknown>, path: string): boolean {
+  const keys = path.split('.');
+  let current: Record<string, unknown> = obj;
+
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (current[key] === undefined || current[key] === null || typeof current[key] !== 'object') {
+      return false;
+    }
+    current = current[key] as Record<string, unknown>;
+  }
+
+  const lastKey = keys[keys.length - 1];
+  if (lastKey in current) {
+    delete current[lastKey];
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Coerce a string value to its appropriate type.
+ * - "true" / "false" -> boolean
+ * - Numeric strings -> number
+ * - Everything else -> string
+ *
+ * @param value - The string value to coerce
+ * @param forceString - If true, always return the value as a string
+ * @returns The coerced value
+ */
+export function coerceValue(value: string, forceString: boolean = false): string | number | boolean {
+  if (forceString) {
+    return value;
+  }
+
+  // Boolean coercion
+  if (value === 'true') {
+    return true;
+  }
+  if (value === 'false') {
+    return false;
+  }
+
+  // Number coercion - must be a valid finite number
+  const num = Number(value);
+  if (!isNaN(num) && isFinite(num) && value.trim() !== '') {
+    return num;
+  }
+
+  return value;
+}
+
+/**
+ * Format a value for YAML-like display.
+ *
+ * @param value - The value to format
+ * @param indent - Current indentation level
+ * @returns Formatted string
+ */
+export function formatValueYaml(value: unknown, indent: number = 0): string {
+  const indentStr = '  '.repeat(indent);
+
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+
+  if (typeof value === 'boolean' || typeof value === 'number') {
+    return String(value);
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return '[]';
+    }
+    return value.map((item) => `${indentStr}- ${formatValueYaml(item, indent + 1)}`).join('\n');
+  }
+
+  if (typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>);
+    if (entries.length === 0) {
+      return '{}';
+    }
+    return entries
+      .map(([key, val]) => {
+        const formattedVal = formatValueYaml(val, indent + 1);
+        if (typeof val === 'object' && val !== null && Object.keys(val).length > 0) {
+          return `${indentStr}${key}:\n${formattedVal}`;
+        }
+        return `${indentStr}${key}: ${formattedVal}`;
+      })
+      .join('\n');
+  }
+
+  return String(value);
+}
+
+/**
+ * Validate a configuration object against the schema.
+ *
+ * @param config - The configuration to validate
+ * @returns Validation result with success status and optional error message
+ */
+export function validateConfig(config: unknown): { success: boolean; error?: string } {
+  try {
+    GlobalConfigSchema.parse(config);
+    return { success: true };
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      const zodError = error as z.ZodError;
+      const messages = zodError.issues.map((e) => `${e.path.join('.')}: ${e.message}`);
+      return { success: false, error: messages.join('; ') };
+    }
+    return { success: false, error: 'Unknown validation error' };
+  }
+}
@@ -3,6 +3,7 @@ import path from 'path';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { Spec, Change } from '../schemas/index.js';
+import { FileSystemUtils } from '../../utils/file-system.js';

 export class JsonConverter {
  convertSpecToJson(filePath: string): string {
@@ -43,7 +44,7 @@ export class JsonConverter {
  }

  private extractNameFromPath(filePath: string): string {
-    const normalizedPath = filePath.replaceAll('\\', '/');
+    const normalizedPath = FileSystemUtils.toPosixPath(filePath);
    const parts = normalizedPath.split('/');
    
    for (let i = parts.length - 1; i >= 0; i--) {
@@ -0,0 +1,136 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+// Constants
+export const GLOBAL_CONFIG_DIR_NAME = 'openspec';
+export const GLOBAL_CONFIG_FILE_NAME = 'config.json';
+export const GLOBAL_DATA_DIR_NAME = 'openspec';
+
+// TypeScript interfaces
+export interface GlobalConfig {
+  featureFlags?: Record<string, boolean>;
+}
+
+const DEFAULT_CONFIG: GlobalConfig = {
+  featureFlags: {}
+};
+
+/**
+ * Gets the global configuration directory path following XDG Base Directory Specification.
+ *
+ * - All platforms: $XDG_CONFIG_HOME/openspec/ if XDG_CONFIG_HOME is set
+ * - Unix/macOS fallback: ~/.config/openspec/
+ * - Windows fallback: %APPDATA%/openspec/
+ */
+export function getGlobalConfigDir(): string {
+  // XDG_CONFIG_HOME takes precedence on all platforms when explicitly set
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome) {
+    return path.join(xdgConfigHome, GLOBAL_CONFIG_DIR_NAME);
+  }
+
+  const platform = os.platform();
+
+  if (platform === 'win32') {
+    // Windows: use %APPDATA%
+    const appData = process.env.APPDATA;
+    if (appData) {
+      return path.join(appData, GLOBAL_CONFIG_DIR_NAME);
+    }
+    // Fallback for Windows if APPDATA is not set
+    return path.join(os.homedir(), 'AppData', 'Roaming', GLOBAL_CONFIG_DIR_NAME);
+  }
+
+  // Unix/macOS fallback: ~/.config
+  return path.join(os.homedir(), '.config', GLOBAL_CONFIG_DIR_NAME);
+}
+
+/**
+ * Gets the global data directory path following XDG Base Directory Specification.
+ * Used for user data like schema overrides.
+ *
+ * - All platforms: $XDG_DATA_HOME/openspec/ if XDG_DATA_HOME is set
+ * - Unix/macOS fallback: ~/.local/share/openspec/
+ * - Windows fallback: %LOCALAPPDATA%/openspec/
+ */
+export function getGlobalDataDir(): string {
+  // XDG_DATA_HOME takes precedence on all platforms when explicitly set
+  const xdgDataHome = process.env.XDG_DATA_HOME;
+  if (xdgDataHome) {
+    return path.join(xdgDataHome, GLOBAL_DATA_DIR_NAME);
+  }
+
+  const platform = os.platform();
+
+  if (platform === 'win32') {
+    // Windows: use %LOCALAPPDATA%
+    const localAppData = process.env.LOCALAPPDATA;
+    if (localAppData) {
+      return path.join(localAppData, GLOBAL_DATA_DIR_NAME);
+    }
+    // Fallback for Windows if LOCALAPPDATA is not set
+    return path.join(os.homedir(), 'AppData', 'Local', GLOBAL_DATA_DIR_NAME);
+  }
+
+  // Unix/macOS fallback: ~/.local/share
+  return path.join(os.homedir(), '.local', 'share', GLOBAL_DATA_DIR_NAME);
+}
+
+/**
+ * Gets the path to the global config file.
+ */
+export function getGlobalConfigPath(): string {
+  return path.join(getGlobalConfigDir(), GLOBAL_CONFIG_FILE_NAME);
+}
+
+/**
+ * Loads the global configuration from disk.
+ * Returns default configuration if file doesn't exist or is invalid.
+ * Merges loaded config with defaults to ensure new fields are available.
+ */
+export function getGlobalConfig(): GlobalConfig {
+  const configPath = getGlobalConfigPath();
+
+  try {
+    if (!fs.existsSync(configPath)) {
+      return { ...DEFAULT_CONFIG };
+    }
+
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const parsed = JSON.parse(content);
+
+    // Merge with defaults (loaded values take precedence)
+    return {
+      ...DEFAULT_CONFIG,
+      ...parsed,
+      // Deep merge featureFlags
+      featureFlags: {
+        ...DEFAULT_CONFIG.featureFlags,
+        ...(parsed.featureFlags || {})
+      }
+    };
+  } catch (error) {
+    // Log warning for parse errors, but not for missing files
+    if (error instanceof SyntaxError) {
+      console.error(`Warning: Invalid JSON in ${configPath}, using defaults`);
+    }
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+/**
+ * Saves the global configuration to disk.
+ * Creates the config directory if it doesn't exist.
+ */
+export function saveGlobalConfig(config: GlobalConfig): void {
+  const configDir = getGlobalConfigDir();
+  const configPath = getGlobalConfigPath();
+
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(configDir)) {
+    fs.mkdirSync(configDir, { recursive: true });
+  }
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+}
@@ -1,2 +1,12 @@
 // Core OpenSpec logic will be implemented here
-export {};
+export {
+  GLOBAL_CONFIG_DIR_NAME,
+  GLOBAL_CONFIG_FILE_NAME,
+  GLOBAL_DATA_DIR_NAME,
+  type GlobalConfig,
+  getGlobalConfigDir,
+  getGlobalConfigPath,
+  getGlobalConfig,
+  saveGlobalConfig,
+  getGlobalDataDir
+} from './global-config.js';
@@ -107,7 +107,7 @@ export class UpdateCommand {

    if (updatedSlashFiles.length > 0) {
      // Normalize to forward slashes for cross-platform log consistency
-      const normalized = updatedSlashFiles.map((p) => p.replace(/\\/g, '/'));
+      const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
      summaryParts.push(`Updated slash commands: ${normalized.join(', ')}`);
    }

@@ -5,12 +5,13 @@ import { SpecSchema, ChangeSchema, Spec, Change } from '../schemas/index.js';
 import { MarkdownParser } from '../parsers/markdown-parser.js';
 import { ChangeParser } from '../parsers/change-parser.js';
 import { ValidationReport, ValidationIssue, ValidationLevel } from './types.js';
-import { 
+import {
  MIN_PURPOSE_LENGTH,
  MAX_REQUIREMENT_TEXT_LENGTH,
-  VALIDATION_MESSAGES 
+  VALIDATION_MESSAGES
 } from './constants.js';
 import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+import { FileSystemUtils } from '../../utils/file-system.js';

 export class Validator {
  private strictMode: boolean;
@@ -359,7 +360,7 @@ export class Validator {
  }

  private extractNameFromPath(filePath: string): string {
-    const normalizedPath = filePath.replaceAll('\\', '/');
+    const normalizedPath = FileSystemUtils.toPosixPath(filePath);
    const parts = normalizedPath.split('/');
    
    // Look for the directory name after 'specs' or 'changes'
@@ -0,0 +1,102 @@
+import path from 'path';
+import { FileSystemUtils } from './file-system.js';
+
+/**
+ * Result of validating a change name.
+ */
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Validates that a change name follows kebab-case conventions.
+ *
+ * Valid names:
+ * - Start with a lowercase letter
+ * - Contain only lowercase letters, numbers, and hyphens
+ * - Do not start or end with a hyphen
+ * - Do not contain consecutive hyphens
+ *
+ * @param name - The change name to validate
+ * @returns Validation result with `valid: true` or `valid: false` with an error message
+ *
+ * @example
+ * validateChangeName('add-auth') // { valid: true }
+ * validateChangeName('Add-Auth') // { valid: false, error: '...' }
+ */
+export function validateChangeName(name: string): ValidationResult {
+  // Pattern: starts with lowercase letter, followed by lowercase letters/numbers,
+  // optionally followed by hyphen + lowercase letters/numbers (repeatable)
+  const kebabCasePattern = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+  if (!name) {
+    return { valid: false, error: 'Change name cannot be empty' };
+  }
+
+  if (!kebabCasePattern.test(name)) {
+    // Provide specific error messages for common mistakes
+    if (/[A-Z]/.test(name)) {
+      return { valid: false, error: 'Change name must be lowercase (use kebab-case)' };
+    }
+    if (/\s/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain spaces (use hyphens instead)' };
+    }
+    if (/_/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain underscores (use hyphens instead)' };
+    }
+    if (name.startsWith('-')) {
+      return { valid: false, error: 'Change name cannot start with a hyphen' };
+    }
+    if (name.endsWith('-')) {
+      return { valid: false, error: 'Change name cannot end with a hyphen' };
+    }
+    if (/--/.test(name)) {
+      return { valid: false, error: 'Change name cannot contain consecutive hyphens' };
+    }
+    if (/[^a-z0-9-]/.test(name)) {
+      return { valid: false, error: 'Change name can only contain lowercase letters, numbers, and hyphens' };
+    }
+    if (/^[0-9]/.test(name)) {
+      return { valid: false, error: 'Change name must start with a letter' };
+    }
+
+    return { valid: false, error: 'Change name must follow kebab-case convention (e.g., add-auth, refactor-db)' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Creates a new change directory.
+ *
+ * @param projectRoot - The root directory of the project (where `openspec/` lives)
+ * @param name - The change name (must be valid kebab-case)
+ * @throws Error if the change name is invalid
+ * @throws Error if the change directory already exists
+ *
+ * @example
+ * // Creates openspec/changes/add-auth/
+ * await createChange('/path/to/project', 'add-auth')
+ */
+export async function createChange(
+  projectRoot: string,
+  name: string
+): Promise<void> {
+  // Validate the name first
+  const validation = validateChangeName(name);
+  if (!validation.valid) {
+    throw new Error(validation.error);
+  }
+
+  // Build the change directory path
+  const changeDir = path.join(projectRoot, 'openspec', 'changes', name);
+
+  // Check if change already exists
+  if (await FileSystemUtils.directoryExists(changeDir)) {
+    throw new Error(`Change '${name}' already exists at ${changeDir}`);
+  }
+
+  // Create the directory (including parent directories if needed)
+  await FileSystemUtils.createDirectory(changeDir);
+}
@@ -1,4 +1,4 @@
-import { promises as fs } from 'fs';
+import { promises as fs, constants as fsConstants } from 'fs';
 import path from 'path';

 function isMarkerOnOwnLine(content: string, markerIndex: number, markerLength: number): boolean {
@@ -42,6 +42,14 @@ function findMarkerIndex(
 }

 export class FileSystemUtils {
+  /**
+   * Converts a path to use forward slashes (POSIX style).
+   * Essential for cross-platform compatibility with glob libraries like fast-glob.
+   */
+  static toPosixPath(p: string): string {
+    return p.replace(/\\/g, '/');
+  }
+
  private static isWindowsBasePath(basePath: string): boolean {
    return /^[A-Za-z]:[\\/]/.test(basePath) || basePath.startsWith('\\');
  }
@@ -93,10 +101,24 @@ export class FileSystemUtils {
        return true;
      }

-      return (stats.mode & 0o222) !== 0;
+      // On Windows, stats.mode doesn't reliably indicate write permissions.
+      // Use fs.access with W_OK to check actual write permissions cross-platform.
+      try {
+        await fs.access(filePath, fsConstants.W_OK);
+        return true;
+      } catch {
+        return false;
+      }
    } catch (error: any) {
      if (error.code === 'ENOENT') {
-        return true;
+        // File doesn't exist; check if we can write to the parent directory
+        const parentDir = path.dirname(filePath);
+        try {
+          await fs.access(parentDir, fsConstants.W_OK);
+          return true;
+        } catch {
+          return false;
+        }
      }

      console.debug(`Unable to determine write permissions for ${filePath}: ${error.message}`);
@@ -1,2 +1,3 @@
-// Shared utilities will be implemented here
-export {};
+// Shared utilities
+export { validateChangeName, createChange } from './change-utils.js';
+export type { ValidationResult } from './change-utils.js';
@@ -1,7 +1,29 @@
-export function isInteractive(noInteractiveFlag?: boolean): boolean {
-  if (noInteractiveFlag) return false;
+export type InteractiveOptions = {
+  /**
+   * Explicit "disable prompts" flag passed by internal callers.
+   */
+  noInteractive?: boolean;
+  /**
+   * Commander-style negated option: `--no-interactive` sets this to false.
+   */
+  interactive?: boolean;
+};
+
+/**
+ * Resolves whether non-interactive mode is requested.
+ * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
+ * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ */
+export function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean {
+  if (typeof value === 'boolean') return value;
+  return value?.noInteractive === true || value?.interactive === false;
+}
+
+export function isInteractive(value?: boolean | InteractiveOptions): boolean {
+  if (resolveNoInteractive(value)) return false;
  if (process.env.OPEN_SPEC_INTERACTIVE === '0') return false;
+  // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
+  if ('CI' in process.env) return false;
  return !!process.stdin.isTTY;
 }

-
@@ -43,3 +43,24 @@ export async function getSpecIds(root: string = process.cwd()): Promise<string[]
  return result.sort();
 }

+export async function getArchivedChangeIds(root: string = process.cwd()): Promise<string[]> {
+  const archivePath = path.join(root, 'openspec', 'changes', 'archive');
+  try {
+    const entries = await fs.readdir(archivePath, { withFileTypes: true });
+    const result: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
+      try {
+        await fs.access(proposalPath);
+        result.push(entry.name);
+      } catch {
+        // skip directories without proposal.md
+      }
+    }
+    return result.sort();
+  } catch {
+    return [];
+  }
+}
+
@@ -0,0 +1,62 @@
+/**
+ * Supported shell types for completion generation
+ */
+export type SupportedShell = 'zsh' | 'bash' | 'fish' | 'powershell';
+
+/**
+ * Result of shell detection
+ */
+export interface ShellDetectionResult {
+  /** The detected shell if supported, otherwise undefined */
+  shell: SupportedShell | undefined;
+  /** The raw shell name detected (even if unsupported), or undefined if nothing detected */
+  detected: string | undefined;
+}
+
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell(): ShellDetectionResult {
+  // Try SHELL environment variable first (Unix-like systems)
+  const shellPath = process.env.SHELL;
+
+  if (shellPath) {
+    const shellName = shellPath.toLowerCase();
+
+    if (shellName.includes('zsh')) {
+      return { shell: 'zsh', detected: 'zsh' };
+    }
+    if (shellName.includes('bash')) {
+      return { shell: 'bash', detected: 'bash' };
+    }
+    if (shellName.includes('fish')) {
+      return { shell: 'fish', detected: 'fish' };
+    }
+
+    // Shell detected but not supported
+    // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+    const match = shellPath.match(/\/([^/]+)$/);
+    const detectedName = match ? match[1] : shellPath;
+    return { shell: undefined, detected: detectedName };
+  }
+
+  // Check for PowerShell on Windows
+  // PSModulePath is a reliable PowerShell-specific environment variable
+  if (process.env.PSModulePath || process.platform === 'win32') {
+    const comspec = process.env.COMSPEC?.toLowerCase();
+
+    // If PSModulePath exists, we're definitely in PowerShell
+    if (process.env.PSModulePath) {
+      return { shell: 'powershell', detected: 'powershell' };
+    }
+
+    // On Windows without PSModulePath, we might be in cmd.exe
+    if (comspec?.includes('cmd.exe')) {
+      return { shell: undefined, detected: 'cmd.exe' };
+    }
+  }
+
+  return { shell: undefined, detected: undefined };
+}
@@ -0,0 +1,269 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest';
+import { CompletionCommand } from '../../src/commands/completion.js';
+import * as shellDetection from '../../src/utils/shell-detection.js';
+
+// Mock the shell detection module
+vi.mock('../../src/utils/shell-detection.js', () => ({
+  detectShell: vi.fn(),
+}));
+
+// Mock the ZshInstaller
+vi.mock('../../src/core/completions/installers/zsh-installer.js', () => ({
+  ZshInstaller: vi.fn().mockImplementation(() => ({
+    install: vi.fn().mockResolvedValue({
+      success: true,
+      installedPath: '/home/user/.oh-my-zsh/completions/_openspec',
+      isOhMyZsh: true,
+      message: 'Completion script installed successfully for Oh My Zsh',
+      instructions: [
+        'Completion script installed to Oh My Zsh completions directory.',
+        'Restart your shell or run: exec zsh',
+        'Completions should activate automatically.',
+      ],
+    }),
+    uninstall: vi.fn().mockResolvedValue({
+      success: true,
+      message: 'Completion script removed from /home/user/.oh-my-zsh/completions/_openspec',
+    }),
+  })),
+}));
+
+describe('CompletionCommand', () => {
+  let command: CompletionCommand;
+  let consoleLogSpy: any;
+  let consoleErrorSpy: any;
+
+  beforeEach(() => {
+    command = new CompletionCommand();
+    consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    process.exitCode = 0;
+  });
+
+  afterEach(() => {
+    consoleLogSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+    vi.clearAllMocks();
+  });
+
+  describe('generate subcommand', () => {
+    it('should generate Zsh completion script to stdout', async () => {
+      await command.generate({ shell: 'zsh' });
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const output = consoleLogSpy.mock.calls[0][0];
+      expect(output).toContain('#compdef openspec');
+      expect(output).toContain('_openspec() {');
+    });
+
+    it('should auto-detect Zsh shell when no shell specified', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: 'zsh', detected: 'zsh' });
+
+      await command.generate({});
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const output = consoleLogSpy.mock.calls[0][0];
+      expect(output).toContain('#compdef openspec');
+    });
+
+    it('should show error when shell cannot be auto-detected', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: undefined, detected: undefined });
+
+      await command.generate({});
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Error: Could not auto-detect shell. Please specify shell explicitly.'
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should show error for unsupported shell', async () => {
+      await command.generate({ shell: 'bash' });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Error: Shell 'bash' is not supported yet. Currently supported: zsh"
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should handle shell parameter case-insensitively', async () => {
+      await command.generate({ shell: 'ZSH' });
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const output = consoleLogSpy.mock.calls[0][0];
+      expect(output).toContain('#compdef openspec');
+    });
+  });
+
+  describe('install subcommand', () => {
+    it('should install Zsh completion script', async () => {
+      await command.install({ shell: 'zsh' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Completion script installed successfully')
+      );
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('should show verbose output when --verbose flag is provided', async () => {
+      await command.install({ shell: 'zsh', verbose: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Installed to:')
+      );
+    });
+
+    it('should auto-detect Zsh shell when no shell specified', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: 'zsh', detected: 'zsh' });
+
+      await command.install({});
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Completion script installed successfully')
+      );
+    });
+
+    it('should show error when shell cannot be auto-detected', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: undefined, detected: undefined });
+
+      await command.install({});
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Error: Could not auto-detect shell. Please specify shell explicitly.'
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should show error for unsupported shell', async () => {
+      await command.install({ shell: 'fish' });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Error: Shell 'fish' is not supported yet. Currently supported: zsh"
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should display installation instructions', async () => {
+      await command.install({ shell: 'zsh' });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Restart your shell or run: exec zsh')
+      );
+    });
+  });
+
+  describe('uninstall subcommand', () => {
+    it('should uninstall Zsh completion script', async () => {
+      await command.uninstall({ shell: 'zsh', yes: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Completion script removed')
+      );
+      expect(process.exitCode).toBe(0);
+    });
+
+    it('should auto-detect Zsh shell when no shell specified', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: 'zsh', detected: 'zsh' });
+
+      await command.uninstall({ yes: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Completion script removed')
+      );
+    });
+
+    it('should show error when shell cannot be auto-detected', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: undefined, detected: undefined });
+
+      await command.uninstall({ yes: true });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Error: Could not auto-detect shell. Please specify shell explicitly.'
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should show error for unsupported shell', async () => {
+      await command.uninstall({ shell: 'powershell', yes: true });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Error: Shell 'powershell' is not supported yet. Currently supported: zsh"
+      );
+      expect(process.exitCode).toBe(1);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle installation failures gracefully', async () => {
+      const { ZshInstaller } = await import('../../src/core/completions/installers/zsh-installer.js');
+      vi.mocked(ZshInstaller).mockImplementationOnce(() => ({
+        install: vi.fn().mockResolvedValue({
+          success: false,
+          isOhMyZsh: false,
+          message: 'Permission denied',
+        }),
+        uninstall: vi.fn(),
+        isInstalled: vi.fn(),
+        getInstallationInfo: vi.fn(),
+        isOhMyZshInstalled: vi.fn(),
+        getInstallationPath: vi.fn(),
+        backupExistingFile: vi.fn(),
+      } as any));
+
+      const cmd = new CompletionCommand();
+      await cmd.install({ shell: 'zsh' });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Permission denied')
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should handle uninstallation failures gracefully', async () => {
+      const { ZshInstaller } = await import('../../src/core/completions/installers/zsh-installer.js');
+      vi.mocked(ZshInstaller).mockImplementationOnce(() => ({
+        install: vi.fn(),
+        uninstall: vi.fn().mockResolvedValue({
+          success: false,
+          message: 'Completion script is not installed',
+        }),
+        isInstalled: vi.fn(),
+        getInstallationInfo: vi.fn(),
+        isOhMyZshInstalled: vi.fn(),
+        getInstallationPath: vi.fn(),
+        backupExistingFile: vi.fn(),
+      } as any));
+
+      const cmd = new CompletionCommand();
+      await cmd.uninstall({ shell: 'zsh', yes: true });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Completion script is not installed')
+      );
+      expect(process.exitCode).toBe(1);
+    });
+  });
+
+  describe('shell detection integration', () => {
+    it('should show appropriate error when detected shell is unsupported', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: undefined, detected: 'bash' });
+
+      await command.generate({});
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Error: Shell 'bash' is not supported yet. Currently supported: zsh"
+      );
+      expect(process.exitCode).toBe(1);
+    });
+
+    it('should respect explicit shell parameter over auto-detection', async () => {
+      vi.mocked(shellDetection.detectShell).mockReturnValue({ shell: undefined, detected: 'bash' });
+
+      await command.generate({ shell: 'zsh' });
+
+      expect(consoleLogSpy).toHaveBeenCalled();
+      const output = consoleLogSpy.mock.calls[0][0];
+      expect(output).toContain('#compdef openspec');
+    });
+  });
+});
@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+describe('config command integration', () => {
+  // These tests use real file system operations with XDG_CONFIG_HOME override
+  let tempDir: string;
+  let originalEnv: NodeJS.ProcessEnv;
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // Create unique temp directory for each test
+    tempDir = path.join(os.tmpdir(), `openspec-config-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+
+    // Save original env and set XDG_CONFIG_HOME
+    originalEnv = { ...process.env };
+    process.env.XDG_CONFIG_HOME = tempDir;
+
+    // Spy on console.error
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    // Restore original env
+    process.env = originalEnv;
+
+    // Clean up temp directory
+    fs.rmSync(tempDir, { recursive: true, force: true });
+
+    // Restore spies
+    consoleErrorSpy.mockRestore();
+
+    // Reset module cache to pick up new XDG_CONFIG_HOME
+    vi.resetModules();
+  });
+
+  it('should use XDG_CONFIG_HOME for config path', async () => {
+    const { getGlobalConfigPath } = await import('../../src/core/global-config.js');
+    const configPath = getGlobalConfigPath();
+    expect(configPath).toBe(path.join(tempDir, 'openspec', 'config.json'));
+  });
+
+  it('should save and load config correctly', async () => {
+    const { getGlobalConfig, saveGlobalConfig } = await import('../../src/core/global-config.js');
+
+    saveGlobalConfig({ featureFlags: { test: true } });
+    const config = getGlobalConfig();
+    expect(config.featureFlags).toEqual({ test: true });
+  });
+
+  it('should return defaults when config file does not exist', async () => {
+    const { getGlobalConfig, getGlobalConfigPath } = await import('../../src/core/global-config.js');
+
+    const configPath = getGlobalConfigPath();
+    // Make sure config doesn't exist
+    if (fs.existsSync(configPath)) {
+      fs.unlinkSync(configPath);
+    }
+
+    const config = getGlobalConfig();
+    expect(config.featureFlags).toEqual({});
+  });
+
+  it('should preserve unknown fields', async () => {
+    const { getGlobalConfig, getGlobalConfigDir } = await import('../../src/core/global-config.js');
+
+    const configDir = getGlobalConfigDir();
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.json'), JSON.stringify({
+      featureFlags: {},
+      customField: 'preserved',
+    }));
+
+    const config = getGlobalConfig();
+    expect((config as Record<string, unknown>).customField).toBe('preserved');
+  });
+
+  it('should handle invalid JSON gracefully', async () => {
+    const { getGlobalConfig, getGlobalConfigDir } = await import('../../src/core/global-config.js');
+
+    const configDir = getGlobalConfigDir();
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(path.join(configDir, 'config.json'), '{ invalid json }');
+
+    const config = getGlobalConfig();
+    // Should return defaults
+    expect(config.featureFlags).toEqual({});
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Invalid JSON'));
+  });
+});
+
+describe('config command shell completion registry', () => {
+  it('should have config command in registry', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    expect(configCmd).toBeDefined();
+    expect(configCmd?.description).toBe('View and modify global OpenSpec configuration');
+  });
+
+  it('should have all config subcommands in registry', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    const subcommandNames = configCmd?.subcommands?.map((s) => s.name) ?? [];
+
+    expect(subcommandNames).toContain('path');
+    expect(subcommandNames).toContain('list');
+    expect(subcommandNames).toContain('get');
+    expect(subcommandNames).toContain('set');
+    expect(subcommandNames).toContain('unset');
+    expect(subcommandNames).toContain('reset');
+    expect(subcommandNames).toContain('edit');
+  });
+
+  it('should have --json flag on list subcommand', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    const listCmd = configCmd?.subcommands?.find((s) => s.name === 'list');
+    const flagNames = listCmd?.flags?.map((f) => f.name) ?? [];
+
+    expect(flagNames).toContain('json');
+  });
+
+  it('should have --string flag on set subcommand', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    const setCmd = configCmd?.subcommands?.find((s) => s.name === 'set');
+    const flagNames = setCmd?.flags?.map((f) => f.name) ?? [];
+
+    expect(flagNames).toContain('string');
+    expect(flagNames).toContain('allow-unknown');
+  });
+
+  it('should have --all and -y flags on reset subcommand', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    const resetCmd = configCmd?.subcommands?.find((s) => s.name === 'reset');
+    const flagNames = resetCmd?.flags?.map((f) => f.name) ?? [];
+
+    expect(flagNames).toContain('all');
+    expect(flagNames).toContain('yes');
+  });
+
+  it('should have --scope flag on config command', async () => {
+    const { COMMAND_REGISTRY } = await import('../../src/core/completions/command-registry.js');
+
+    const configCmd = COMMAND_REGISTRY.find((cmd) => cmd.name === 'config');
+    const flagNames = configCmd?.flags?.map((f) => f.name) ?? [];
+
+    expect(flagNames).toContain('scope');
+  });
+});
+
+describe('config key validation', () => {
+  it('rejects unknown top-level keys', async () => {
+    const { validateConfigKeyPath } = await import('../../src/core/config-schema.js');
+    expect(validateConfigKeyPath('unknownKey').valid).toBe(false);
+  });
+
+  it('allows feature flag keys', async () => {
+    const { validateConfigKeyPath } = await import('../../src/core/config-schema.js');
+    expect(validateConfigKeyPath('featureFlags.someFlag').valid).toBe(true);
+  });
+
+  it('rejects deeply nested feature flag keys', async () => {
+    const { validateConfigKeyPath } = await import('../../src/core/config-schema.js');
+    expect(validateConfigKeyPath('featureFlags.someFlag.extra').valid).toBe(false);
+  });
+});
@@ -130,4 +130,18 @@ describe('top-level validate command', () => {
    const result = await runCLI(['validate', changeId], { cwd: testDir });
    expect(result.exitCode).toBe(0);
  });
+
+  it('respects --no-interactive flag passed via CLI', async () => {
+    // This test ensures Commander.js --no-interactive flag is correctly parsed
+    // and passed to the validate command. The flag sets options.interactive = false
+    // (not options.noInteractive = true) due to Commander.js convention.
+    const result = await runCLI(['validate', '--specs', '--no-interactive'], {
+      cwd: testDir,
+      // Don't set OPEN_SPEC_INTERACTIVE to ensure we're testing the flag itself
+      env: { ...process.env, OPEN_SPEC_INTERACTIVE: undefined },
+    });
+    expect(result.exitCode).toBe(0);
+    // Should complete without hanging and without prompts
+    expect(result.stderr).not.toContain('What would you like to validate?');
+  });
 });
@@ -127,6 +127,133 @@ Then expected result happens`;
      expect(updatedContent).toContain('#### Scenario: Basic test');
    });

+    it('should allow REMOVED requirements when creating new spec file (issue #403)', async () => {
+      const changeName = 'new-spec-with-removed';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'gift-card');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create delta spec with both ADDED and REMOVED requirements
+      // This simulates refactoring where old fields are removed and new ones are added
+      const specContent = `# Gift Card - Changes
+
+## ADDED Requirements
+
+### Requirement: Logo and Background Color
+The system SHALL support logo and backgroundColor fields for gift cards.
+
+#### Scenario: Display gift card with logo
+- **WHEN** a gift card is displayed
+- **THEN** it shows the logo and backgroundColor
+
+## REMOVED Requirements
+
+### Requirement: Image Field
+### Requirement: Thumbnail Field`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive - should succeed with warning about REMOVED requirements
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      
+      // Verify warning was logged about REMOVED requirements being ignored
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('Warning: gift-card - 2 REMOVED requirement(s) ignored for new spec (nothing to remove).')
+      );
+      
+      // Verify spec was created with only ADDED requirements
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'gift-card', 'spec.md');
+      const updatedContent = await fs.readFile(mainSpecPath, 'utf-8');
+      expect(updatedContent).toContain('# gift-card Specification');
+      expect(updatedContent).toContain('### Requirement: Logo and Background Color');
+      expect(updatedContent).toContain('#### Scenario: Display gift card with logo');
+      // REMOVED requirements should not be in the final spec
+      expect(updatedContent).not.toContain('### Requirement: Image Field');
+      expect(updatedContent).not.toContain('### Requirement: Thumbnail Field');
+      
+      // Verify change was archived successfully
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.length).toBeGreaterThan(0);
+      expect(archives.some(a => a.includes(changeName))).toBe(true);
+    });
+
+    it('should still error on MODIFIED when creating new spec file', async () => {
+      const changeName = 'new-spec-with-modified';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'new-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create delta spec with MODIFIED requirement (should fail for new spec)
+      const specContent = `# New Capability - Changes
+
+## ADDED Requirements
+
+### Requirement: New Feature
+New feature description.
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+Modified content.`;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive - should abort with error message (not throw, but log and return)
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      
+      // Verify error message mentions MODIFIED not allowed for new specs
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('new-capability: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.')
+      );
+      expect(console.log).toHaveBeenCalledWith('Aborted. No files were changed.');
+      
+      // Verify spec was NOT created
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'new-capability', 'spec.md');
+      await expect(fs.access(mainSpecPath)).rejects.toThrow();
+      
+      // Verify change was NOT archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.some(a => a.includes(changeName))).toBe(false);
+    });
+
+    it('should still error on RENAMED when creating new spec file', async () => {
+      const changeName = 'new-spec-with-renamed';
+      const changeDir = path.join(tempDir, 'openspec', 'changes', changeName);
+      const changeSpecDir = path.join(changeDir, 'specs', 'another-capability');
+      await fs.mkdir(changeSpecDir, { recursive: true });
+      
+      // Create delta spec with RENAMED requirement (should fail for new spec)
+      const specContent = `# Another Capability - Changes
+
+## ADDED Requirements
+
+### Requirement: New Feature
+New feature description.
+
+## RENAMED Requirements
+- FROM: \`### Requirement: Old Name\`
+- TO: \`### Requirement: New Name\``;
+      await fs.writeFile(path.join(changeSpecDir, 'spec.md'), specContent);
+      
+      // Execute archive - should abort with error message (not throw, but log and return)
+      await archiveCommand.execute(changeName, { yes: true, noValidate: true });
+      
+      // Verify error message mentions RENAMED not allowed for new specs
+      expect(console.log).toHaveBeenCalledWith(
+        expect.stringContaining('another-capability: target spec does not exist; only ADDED requirements are allowed for new specs. MODIFIED and RENAMED operations require an existing spec.')
+      );
+      expect(console.log).toHaveBeenCalledWith('Aborted. No files were changed.');
+      
+      // Verify spec was NOT created
+      const mainSpecPath = path.join(tempDir, 'openspec', 'specs', 'another-capability', 'spec.md');
+      await expect(fs.access(mainSpecPath)).rejects.toThrow();
+      
+      // Verify change was NOT archived
+      const archiveDir = path.join(tempDir, 'openspec', 'changes', 'archive');
+      const archives = await fs.readdir(archiveDir);
+      expect(archives.some(a => a.includes(changeName))).toBe(false);
+    });
+
    it('should throw error if change does not exist', async () => {
      await expect(
        archiveCommand.execute('non-existent-change', { yes: true })
@@ -0,0 +1,268 @@
+import { describe, it, expect } from 'vitest';
+import { ArtifactGraph } from '../../../src/core/artifact-graph/graph.js';
+import type { SchemaYaml } from '../../../src/core/artifact-graph/types.js';
+
+describe('artifact-graph/graph', () => {
+  const createSchema = (artifacts: SchemaYaml['artifacts']): SchemaYaml => ({
+    name: 'test',
+    version: 1,
+    artifacts,
+  });
+
+  describe('fromSchema', () => {
+    it('should create graph from schema object', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getName()).toBe('test');
+      expect(graph.getVersion()).toBe(1);
+    });
+  });
+
+  describe('fromYamlContent', () => {
+    it('should create graph from YAML string', () => {
+      const yaml = `
+name: my-workflow
+version: 2
+artifacts:
+  - id: doc
+    generates: doc.md
+    description: Documentation
+    template: templates/doc.md
+`;
+      const graph = ArtifactGraph.fromYamlContent(yaml);
+
+      expect(graph.getName()).toBe('my-workflow');
+      expect(graph.getVersion()).toBe(2);
+      expect(graph.getArtifact('doc')).toBeDefined();
+    });
+  });
+
+  describe('getArtifact', () => {
+    it('should return artifact by ID', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const artifact = graph.getArtifact('proposal');
+
+      expect(artifact).toBeDefined();
+      expect(artifact?.id).toBe('proposal');
+      expect(artifact?.generates).toBe('proposal.md');
+    });
+
+    it('should return undefined for non-existent ID', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getArtifact('nonexistent')).toBeUndefined();
+    });
+  });
+
+  describe('getAllArtifacts', () => {
+    it('should return all artifacts', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const artifacts = graph.getAllArtifacts();
+
+      expect(artifacts).toHaveLength(3);
+      expect(artifacts.map(a => a.id).sort()).toEqual(['A', 'B', 'C']);
+    });
+  });
+
+  describe('getBuildOrder', () => {
+    it('should return correct order for linear chain A → B → C', () => {
+      const schema = createSchema([
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: ['B'] },
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const order = graph.getBuildOrder();
+
+      expect(order).toEqual(['A', 'B', 'C']);
+    });
+
+    it('should handle diamond dependency correctly', () => {
+      // A → B, A → C, B → D, C → D
+      const schema = createSchema([
+        { id: 'D', generates: 'd.md', description: 'D', template: 't.md', requires: ['B', 'C'] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: ['A'] },
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const order = graph.getBuildOrder();
+
+      // A must come before B and C; D must come last
+      expect(order.indexOf('A')).toBeLessThan(order.indexOf('B'));
+      expect(order.indexOf('A')).toBeLessThan(order.indexOf('C'));
+      expect(order.indexOf('B')).toBeLessThan(order.indexOf('D'));
+      expect(order.indexOf('C')).toBeLessThan(order.indexOf('D'));
+    });
+
+    it('should return independent artifacts in stable sorted order', () => {
+      const schema = createSchema([
+        { id: 'Z', generates: 'z.md', description: 'Z', template: 't.md', requires: [] },
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'M', generates: 'm.md', description: 'M', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const order = graph.getBuildOrder();
+
+      // All independent, should be sorted alphabetically for stability
+      expect(order).toEqual(['A', 'M', 'Z']);
+    });
+  });
+
+  describe('getNextArtifacts', () => {
+    it('should return root artifacts when nothing completed', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const ready = graph.getNextArtifacts(new Set());
+
+      expect(ready.sort()).toEqual(['A', 'C']);
+    });
+
+    it('should include artifact when all deps completed', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const ready = graph.getNextArtifacts(new Set(['A']));
+
+      expect(ready).toEqual(['B']);
+    });
+
+    it('should not include completed artifacts', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const ready = graph.getNextArtifacts(new Set(['A', 'B']));
+
+      expect(ready).toEqual([]);
+    });
+
+    it('should handle diamond dependency correctly', () => {
+      // D requires B and C
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: ['A'] },
+        { id: 'D', generates: 'd.md', description: 'D', template: 't.md', requires: ['B', 'C'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Only A completed - B and C ready, D not
+      expect(graph.getNextArtifacts(new Set(['A'])).sort()).toEqual(['B', 'C']);
+
+      // Only B completed (from deps) - C still needed for D
+      expect(graph.getNextArtifacts(new Set(['A', 'B']))).toEqual(['C']);
+
+      // Both B and C completed - D ready
+      expect(graph.getNextArtifacts(new Set(['A', 'B', 'C']))).toEqual(['D']);
+    });
+  });
+
+  describe('isComplete', () => {
+    it('should return true when all artifacts completed', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.isComplete(new Set(['A', 'B']))).toBe(true);
+    });
+
+    it('should return false when some artifacts incomplete', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.isComplete(new Set(['A']))).toBe(false);
+      expect(graph.isComplete(new Set())).toBe(false);
+    });
+  });
+
+  describe('getBlocked', () => {
+    it('should return empty object when nothing is blocked', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getBlocked(new Set())).toEqual({});
+    });
+
+    it('should return artifact blocked by single dependency', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getBlocked(new Set())).toEqual({ B: ['A'] });
+    });
+
+    it('should return artifact blocked by multiple dependencies', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: [] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: ['A', 'B'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Neither A nor B completed
+      expect(graph.getBlocked(new Set())).toEqual({ C: ['A', 'B'] });
+    });
+
+    it('should only list unmet dependencies', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: [] },
+        { id: 'C', generates: 'c.md', description: 'C', template: 't.md', requires: ['A', 'B'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // A completed, B not
+      expect(graph.getBlocked(new Set(['A']))).toEqual({ C: ['B'] });
+    });
+
+    it('should not include completed artifacts', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+        { id: 'B', generates: 'b.md', description: 'B', template: 't.md', requires: ['A'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getBlocked(new Set(['A', 'B']))).toEqual({});
+    });
+  });
+});
@@ -0,0 +1,264 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  loadTemplate,
+  loadChangeContext,
+  generateInstructions,
+  formatChangeStatus,
+  TemplateLoadError,
+} from '../../../src/core/artifact-graph/instruction-loader.js';
+
+describe('instruction-loader', () => {
+  describe('loadTemplate', () => {
+    it('should load template from schema directory', () => {
+      // Uses built-in spec-driven schema
+      const template = loadTemplate('spec-driven', 'proposal.md');
+
+      expect(template).toContain('## Why');
+      expect(template).toContain('## What Changes');
+    });
+
+    it('should throw TemplateLoadError for non-existent template', () => {
+      expect(() => loadTemplate('spec-driven', 'nonexistent.md')).toThrow(
+        TemplateLoadError
+      );
+    });
+
+    it('should throw TemplateLoadError for non-existent schema', () => {
+      expect(() => loadTemplate('nonexistent-schema', 'proposal.md')).toThrow(
+        TemplateLoadError
+      );
+    });
+
+    it('should include template path in error', () => {
+      try {
+        loadTemplate('spec-driven', 'nonexistent.md');
+        expect.fail('Should have thrown');
+      } catch (err) {
+        expect(err).toBeInstanceOf(TemplateLoadError);
+        expect((err as TemplateLoadError).templatePath).toContain('nonexistent.md');
+      }
+    });
+  });
+
+  describe('loadChangeContext', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('should load context with default schema', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+
+      expect(context.schemaName).toBe('spec-driven');
+      expect(context.changeName).toBe('my-change');
+      expect(context.graph.getName()).toBe('spec-driven');
+      expect(context.completed.size).toBe(0);
+    });
+
+    it('should load context with custom schema', () => {
+      const context = loadChangeContext(tempDir, 'my-change', 'tdd');
+
+      expect(context.schemaName).toBe('tdd');
+      expect(context.graph.getName()).toBe('tdd');
+    });
+
+    it('should detect completed artifacts', () => {
+      // Create change directory with proposal.md
+      const changeDir = path.join(tempDir, 'openspec', 'changes', 'my-change');
+      fs.mkdirSync(changeDir, { recursive: true });
+      fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Proposal');
+
+      const context = loadChangeContext(tempDir, 'my-change');
+
+      expect(context.completed.has('proposal')).toBe(true);
+    });
+
+    it('should return empty completed set for non-existent change directory', () => {
+      const context = loadChangeContext(tempDir, 'nonexistent-change');
+
+      expect(context.completed.size).toBe(0);
+    });
+  });
+
+  describe('generateInstructions', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('should include artifact metadata', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'proposal');
+
+      expect(instructions.changeName).toBe('my-change');
+      expect(instructions.artifactId).toBe('proposal');
+      expect(instructions.schemaName).toBe('spec-driven');
+      expect(instructions.outputPath).toBe('proposal.md');
+    });
+
+    it('should include template content', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'proposal');
+
+      expect(instructions.template).toContain('## Why');
+    });
+
+    it('should show dependencies with completion status', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'specs');
+
+      expect(instructions.dependencies).toHaveLength(1);
+      expect(instructions.dependencies[0].id).toBe('proposal');
+      expect(instructions.dependencies[0].done).toBe(false);
+    });
+
+    it('should mark completed dependencies as done', () => {
+      // Create proposal
+      const changeDir = path.join(tempDir, 'openspec', 'changes', 'my-change');
+      fs.mkdirSync(changeDir, { recursive: true });
+      fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Proposal');
+
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'specs');
+
+      expect(instructions.dependencies[0].done).toBe(true);
+    });
+
+    it('should list artifacts unlocked by this one', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'proposal');
+
+      // proposal unlocks specs and design
+      expect(instructions.unlocks).toContain('specs');
+      expect(instructions.unlocks).toContain('design');
+    });
+
+    it('should have empty dependencies for root artifact', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const instructions = generateInstructions(context, 'proposal');
+
+      expect(instructions.dependencies).toHaveLength(0);
+    });
+
+    it('should throw for non-existent artifact', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+
+      expect(() => generateInstructions(context, 'nonexistent')).toThrow(
+        "Artifact 'nonexistent' not found"
+      );
+    });
+  });
+
+  describe('formatChangeStatus', () => {
+    let tempDir: string;
+
+    beforeEach(() => {
+      tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-test-'));
+    });
+
+    afterEach(() => {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    });
+
+    it('should show all artifacts as ready/blocked when nothing completed', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      expect(status.changeName).toBe('my-change');
+      expect(status.schemaName).toBe('spec-driven');
+      expect(status.isComplete).toBe(false);
+
+      // proposal has no deps, should be ready
+      const proposal = status.artifacts.find(a => a.id === 'proposal');
+      expect(proposal?.status).toBe('ready');
+
+      // specs depends on proposal, should be blocked
+      const specs = status.artifacts.find(a => a.id === 'specs');
+      expect(specs?.status).toBe('blocked');
+      expect(specs?.missingDeps).toContain('proposal');
+    });
+
+    it('should show completed artifacts as done', () => {
+      const changeDir = path.join(tempDir, 'openspec', 'changes', 'my-change');
+      fs.mkdirSync(changeDir, { recursive: true });
+      fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Proposal');
+
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      const proposal = status.artifacts.find(a => a.id === 'proposal');
+      expect(proposal?.status).toBe('done');
+
+      // specs should now be ready
+      const specs = status.artifacts.find(a => a.id === 'specs');
+      expect(specs?.status).toBe('ready');
+    });
+
+    it('should include output paths for each artifact', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      const proposal = status.artifacts.find(a => a.id === 'proposal');
+      expect(proposal?.outputPath).toBe('proposal.md');
+
+      const specs = status.artifacts.find(a => a.id === 'specs');
+      expect(specs?.outputPath).toBe('specs/*.md');
+    });
+
+    it('should report isComplete true when all done', () => {
+      const changeDir = path.join(tempDir, 'openspec', 'changes', 'my-change');
+      fs.mkdirSync(changeDir, { recursive: true });
+      fs.mkdirSync(path.join(changeDir, 'specs'), { recursive: true });
+
+      // Create all required files for spec-driven schema
+      fs.writeFileSync(path.join(changeDir, 'proposal.md'), '# Proposal');
+      fs.writeFileSync(path.join(changeDir, 'specs', 'test.md'), '# Spec');
+      fs.writeFileSync(path.join(changeDir, 'design.md'), '# Design');
+      fs.writeFileSync(path.join(changeDir, 'tasks.md'), '# Tasks');
+
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      expect(status.isComplete).toBe(true);
+      expect(status.artifacts.every(a => a.status === 'done')).toBe(true);
+    });
+
+    it('should show blocked artifacts with missing dependencies', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      // tasks requires specs and design
+      const tasks = status.artifacts.find(a => a.id === 'tasks');
+      expect(tasks?.status).toBe('blocked');
+      expect(tasks?.missingDeps).toContain('specs');
+      expect(tasks?.missingDeps).toContain('design');
+    });
+
+    it('should sort artifacts in build order', () => {
+      const context = loadChangeContext(tempDir, 'my-change');
+      const status = formatChangeStatus(context);
+
+      const ids = status.artifacts.map(a => a.id);
+      const proposalIdx = ids.indexOf('proposal');
+      const specsIdx = ids.indexOf('specs');
+      const tasksIdx = ids.indexOf('tasks');
+
+      // proposal must come before specs, specs before tasks
+      expect(proposalIdx).toBeLessThan(specsIdx);
+      expect(specsIdx).toBeLessThan(tasksIdx);
+    });
+  });
+});
@@ -0,0 +1,327 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import {
+  resolveSchema,
+  listSchemas,
+  SchemaLoadError,
+  getSchemaDir,
+  getPackageSchemasDir,
+  getUserSchemasDir,
+} from '../../../src/core/artifact-graph/resolver.js';
+
+describe('artifact-graph/resolver', () => {
+  let tempDir: string;
+  let originalEnv: NodeJS.ProcessEnv;
+
+  beforeEach(() => {
+    tempDir = path.join(os.tmpdir(), `openspec-resolver-test-${Date.now()}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+    originalEnv = { ...process.env };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('getPackageSchemasDir', () => {
+    it('should return a valid path', () => {
+      const schemasDir = getPackageSchemasDir();
+      expect(typeof schemasDir).toBe('string');
+      expect(schemasDir.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('getUserSchemasDir', () => {
+    it('should use XDG_DATA_HOME when set', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userDir = getUserSchemasDir();
+      expect(userDir).toBe(path.join(tempDir, 'openspec', 'schemas'));
+    });
+  });
+
+  describe('getSchemaDir', () => {
+    it('should return null for non-existent schema', () => {
+      const dir = getSchemaDir('nonexistent-schema');
+      expect(dir).toBeNull();
+    });
+
+    it('should return package dir for built-in schema', () => {
+      const dir = getSchemaDir('spec-driven');
+      expect(dir).not.toBeNull();
+      expect(dir).toContain('schemas');
+      expect(dir).toContain('spec-driven');
+    });
+
+    it('should prefer user override directory', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+      fs.writeFileSync(
+        path.join(userSchemaDir, 'schema.yaml'),
+        'name: custom\nversion: 1\nartifacts: []'
+      );
+
+      const dir = getSchemaDir('spec-driven');
+      expect(dir).toBe(userSchemaDir);
+    });
+  });
+
+  describe('resolveSchema', () => {
+    it('should return built-in spec-driven schema', () => {
+      const schema = resolveSchema('spec-driven');
+
+      expect(schema.name).toBe('spec-driven');
+      expect(schema.version).toBe(1);
+      expect(schema.artifacts.length).toBeGreaterThan(0);
+    });
+
+    it('should return built-in tdd schema', () => {
+      const schema = resolveSchema('tdd');
+
+      expect(schema.name).toBe('tdd');
+      expect(schema.version).toBe(1);
+      expect(schema.artifacts.length).toBeGreaterThan(0);
+    });
+
+    it('should strip .yaml extension from name', () => {
+      const schema1 = resolveSchema('spec-driven');
+      const schema2 = resolveSchema('spec-driven.yaml');
+
+      expect(schema1).toEqual(schema2);
+    });
+
+    it('should strip .yml extension from name', () => {
+      const schema1 = resolveSchema('spec-driven');
+      const schema2 = resolveSchema('spec-driven.yml');
+
+      expect(schema1).toEqual(schema2);
+    });
+
+    it('should prefer user override over built-in', () => {
+      // Set up global data dir
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      // Create a custom schema with same name as built-in
+      const customSchema = `
+name: custom-override
+version: 99
+artifacts:
+  - id: custom
+    generates: custom.md
+    description: Custom artifact
+    template: custom.md
+`;
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), customSchema);
+
+      const schema = resolveSchema('spec-driven');
+
+      expect(schema.name).toBe('custom-override');
+      expect(schema.version).toBe(99);
+    });
+
+    it('should validate user override and throw on invalid schema', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      // Create an invalid schema (missing required fields)
+      const invalidSchema = `
+name: invalid
+version: 1
+artifacts:
+  - id: broken
+    # missing generates, description, template
+`;
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), invalidSchema);
+
+      expect(() => resolveSchema('spec-driven')).toThrow(SchemaLoadError);
+    });
+
+    it('should include file path in validation error message', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      const invalidSchema = `
+name: invalid
+version: 1
+artifacts:
+  - id: broken
+`;
+      const schemaPath = path.join(userSchemaDir, 'schema.yaml');
+      fs.writeFileSync(schemaPath, invalidSchema);
+
+      try {
+        resolveSchema('spec-driven');
+        expect.fail('Should have thrown');
+      } catch (e) {
+        const error = e as SchemaLoadError;
+        expect(error.message).toContain(schemaPath);
+        expect(error.schemaPath).toBe(schemaPath);
+        expect(error.cause).toBeDefined();
+      }
+    });
+
+    it('should detect cycles in user override schemas', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      // Create a schema with cyclic dependencies
+      const cyclicSchema = `
+name: cyclic
+version: 1
+artifacts:
+  - id: a
+    generates: a.md
+    description: A
+    template: a.md
+    requires: [b]
+  - id: b
+    generates: b.md
+    description: B
+    template: b.md
+    requires: [a]
+`;
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), cyclicSchema);
+
+      expect(() => resolveSchema('spec-driven')).toThrow(/Cyclic dependency/);
+    });
+
+    it('should detect invalid requires references in user override schemas', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      // Create a schema with invalid requires reference
+      const invalidRefSchema = `
+name: invalid-ref
+version: 1
+artifacts:
+  - id: a
+    generates: a.md
+    description: A
+    template: a.md
+    requires: [nonexistent]
+`;
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), invalidRefSchema);
+
+      expect(() => resolveSchema('spec-driven')).toThrow(/does not exist/);
+    });
+
+    it('should throw SchemaLoadError on YAML syntax errors', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+
+      // Create malformed YAML
+      const malformedYaml = `
+name: bad
+version: [[[invalid yaml
+`;
+      const schemaPath = path.join(userSchemaDir, 'schema.yaml');
+      fs.writeFileSync(schemaPath, malformedYaml);
+
+      try {
+        resolveSchema('spec-driven');
+        expect.fail('Should have thrown');
+      } catch (e) {
+        expect(e).toBeInstanceOf(SchemaLoadError);
+        const error = e as SchemaLoadError;
+        expect(error.message).toContain('Failed to parse');
+        expect(error.message).toContain(schemaPath);
+      }
+    });
+
+    it('should fall back to built-in when user override not found', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      // Don't create any user schemas
+
+      const schema = resolveSchema('spec-driven');
+
+      expect(schema.name).toBe('spec-driven');
+      expect(schema.version).toBe(1);
+    });
+
+    it('should throw when schema not found', () => {
+      expect(() => resolveSchema('nonexistent-schema')).toThrow(/not found/);
+    });
+
+    it('should list available schemas in error message', () => {
+      try {
+        resolveSchema('nonexistent');
+        expect.fail('Should have thrown');
+      } catch (e) {
+        const error = e as Error;
+        expect(error.message).toContain('spec-driven');
+        expect(error.message).toContain('tdd');
+      }
+    });
+  });
+
+  describe('listSchemas', () => {
+    it('should list built-in schemas', () => {
+      const schemas = listSchemas();
+
+      expect(schemas).toContain('spec-driven');
+      expect(schemas).toContain('tdd');
+    });
+
+    it('should include user override schemas', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'custom-workflow');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), 'name: custom\nversion: 1\nartifacts: []');
+
+      const schemas = listSchemas();
+
+      expect(schemas).toContain('custom-workflow');
+      expect(schemas).toContain('spec-driven');
+    });
+
+    it('should deduplicate schemas with same name', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemaDir = path.join(tempDir, 'openspec', 'schemas', 'spec-driven');
+      fs.mkdirSync(userSchemaDir, { recursive: true });
+      // Override spec-driven
+      fs.writeFileSync(path.join(userSchemaDir, 'schema.yaml'), 'name: custom\nversion: 1\nartifacts: []');
+
+      const schemas = listSchemas();
+
+      // Should only appear once
+      const count = schemas.filter(s => s === 'spec-driven').length;
+      expect(count).toBe(1);
+    });
+
+    it('should return sorted list', () => {
+      const schemas = listSchemas();
+
+      const sorted = [...schemas].sort();
+      expect(schemas).toEqual(sorted);
+    });
+
+    it('should only include directories with schema.yaml', () => {
+      process.env.XDG_DATA_HOME = tempDir;
+      const userSchemasBase = path.join(tempDir, 'openspec', 'schemas');
+
+      // Create a directory without schema.yaml
+      const emptyDir = path.join(userSchemasBase, 'empty-dir');
+      fs.mkdirSync(emptyDir, { recursive: true });
+
+      // Create a valid schema directory
+      const validDir = path.join(userSchemasBase, 'valid-schema');
+      fs.mkdirSync(validDir, { recursive: true });
+      fs.writeFileSync(path.join(validDir, 'schema.yaml'), 'name: valid\nversion: 1\nartifacts: []');
+
+      const schemas = listSchemas();
+
+      expect(schemas).toContain('valid-schema');
+      expect(schemas).not.toContain('empty-dir');
+    });
+  });
+});
@@ -0,0 +1,207 @@
+import { describe, it, expect } from 'vitest';
+import { parseSchema, SchemaValidationError } from '../../../src/core/artifact-graph/schema.js';
+
+describe('artifact-graph/schema', () => {
+  describe('parseSchema', () => {
+    it('should parse valid schema YAML', () => {
+      const yaml = `
+name: test-schema
+version: 1
+description: A test schema
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal
+    template: templates/proposal.md
+    requires: []
+  - id: design
+    generates: design.md
+    description: Design document
+    template: templates/design.md
+    requires:
+      - proposal
+`;
+      const schema = parseSchema(yaml);
+
+      expect(schema.name).toBe('test-schema');
+      expect(schema.version).toBe(1);
+      expect(schema.description).toBe('A test schema');
+      expect(schema.artifacts).toHaveLength(2);
+      expect(schema.artifacts[0].id).toBe('proposal');
+      expect(schema.artifacts[1].requires).toEqual(['proposal']);
+    });
+
+    it('should throw on missing required fields', () => {
+      const yaml = `
+name: test-schema
+version: 1
+artifacts:
+  - id: proposal
+    description: Missing generates and template
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/generates/);
+    });
+
+    it('should throw on missing schema name', () => {
+      const yaml = `
+version: 1
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Test
+    template: templates/proposal.md
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/name/);
+    });
+
+    it('should throw on invalid version (non-positive)', () => {
+      const yaml = `
+name: test
+version: 0
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Test
+    template: templates/proposal.md
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/positive/);
+    });
+
+    it('should throw on empty artifacts array', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts: []
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/artifact/i);
+    });
+
+    it('should throw on duplicate artifact IDs', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: First
+    template: templates/proposal.md
+  - id: proposal
+    generates: other.md
+    description: Duplicate
+    template: templates/other.md
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/Duplicate artifact ID: proposal/);
+    });
+
+    it('should throw on invalid requires reference', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: design
+    generates: design.md
+    description: Design doc
+    template: templates/design.md
+    requires:
+      - nonexistent
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/Invalid dependency reference.*nonexistent/);
+    });
+
+    it('should detect self-referencing cycle', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: A
+    generates: a.md
+    description: Self reference
+    template: templates/a.md
+    requires:
+      - A
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/Cyclic dependency detected/);
+    });
+
+    it('should detect simple A → B → A cycle', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: A
+    generates: a.md
+    description: A
+    template: templates/a.md
+    requires:
+      - B
+  - id: B
+    generates: b.md
+    description: B
+    template: templates/b.md
+    requires:
+      - A
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/Cyclic dependency detected/);
+      expect(() => parseSchema(yaml)).toThrow(/→/);
+    });
+
+    it('should detect longer A → B → C → A cycle and list all IDs', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: A
+    generates: a.md
+    description: A
+    template: templates/a.md
+    requires:
+      - C
+  - id: B
+    generates: b.md
+    description: B
+    template: templates/b.md
+    requires:
+      - A
+  - id: C
+    generates: c.md
+    description: C
+    template: templates/c.md
+    requires:
+      - B
+`;
+      expect(() => parseSchema(yaml)).toThrow(SchemaValidationError);
+      expect(() => parseSchema(yaml)).toThrow(/Cyclic dependency detected/);
+      // Should contain all three in the cycle path
+      const error = (() => {
+        try {
+          parseSchema(yaml);
+        } catch (e) {
+          return e;
+        }
+      })() as Error;
+      expect(error.message).toMatch(/A.*→.*B|B.*→.*C|C.*→.*A/);
+    });
+
+    it('should allow default empty requires array', () => {
+      const yaml = `
+name: test
+version: 1
+artifacts:
+  - id: root
+    generates: root.md
+    description: Root artifact
+    template: templates/root.md
+`;
+      const schema = parseSchema(yaml);
+      expect(schema.artifacts[0].requires).toEqual([]);
+    });
+  });
+});
@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { detectCompleted } from '../../../src/core/artifact-graph/state.js';
+import { ArtifactGraph } from '../../../src/core/artifact-graph/graph.js';
+import type { SchemaYaml } from '../../../src/core/artifact-graph/types.js';
+
+describe('artifact-graph/state', () => {
+  let tempDir: string;
+
+  const createSchema = (artifacts: SchemaYaml['artifacts']): SchemaYaml => ({
+    name: 'test',
+    version: 1,
+    artifacts,
+  });
+
+  beforeEach(() => {
+    tempDir = path.join(os.tmpdir(), `openspec-state-test-${Date.now()}`);
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('detectCompleted', () => {
+    it('should return empty set when changeDir does not exist', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const completed = detectCompleted(graph, '/nonexistent/path');
+
+      expect(completed.size).toBe(0);
+    });
+
+    it('should return empty set when changeDir is empty', () => {
+      const schema = createSchema([
+        { id: 'A', generates: 'a.md', description: 'A', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.size).toBe(0);
+    });
+
+    it('should mark artifact complete when file exists', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create the file
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), 'content');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(true);
+    });
+
+    it('should not mark artifact complete when file does not exist', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+        { id: 'design', generates: 'design.md', description: 'Design', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Only create proposal.md
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), 'content');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(true);
+      expect(completed.has('design')).toBe(false);
+    });
+
+    it('should handle nested paths', () => {
+      const schema = createSchema([
+        { id: 'nested', generates: 'docs/design.md', description: 'Nested', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create nested directory and file
+      fs.mkdirSync(path.join(tempDir, 'docs'), { recursive: true });
+      fs.writeFileSync(path.join(tempDir, 'docs', 'design.md'), 'content');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('nested')).toBe(true);
+    });
+
+    it('should detect glob pattern as complete when files exist', () => {
+      const schema = createSchema([
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create specs directory with files
+      fs.mkdirSync(path.join(tempDir, 'specs'), { recursive: true });
+      fs.writeFileSync(path.join(tempDir, 'specs', 'feature-a.md'), 'content');
+      fs.writeFileSync(path.join(tempDir, 'specs', 'feature-b.md'), 'content');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('specs')).toBe(true);
+    });
+
+    it('should not mark glob pattern complete when directory is empty', () => {
+      const schema = createSchema([
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create empty specs directory
+      fs.mkdirSync(path.join(tempDir, 'specs'), { recursive: true });
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('specs')).toBe(false);
+    });
+
+    it('should not mark glob pattern complete when directory does not exist', () => {
+      const schema = createSchema([
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('specs')).toBe(false);
+    });
+
+    it('should not mark glob pattern complete when only non-matching files exist', () => {
+      const schema = createSchema([
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: [] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create specs directory with non-matching files
+      fs.mkdirSync(path.join(tempDir, 'specs'), { recursive: true });
+      fs.writeFileSync(path.join(tempDir, 'specs', 'readme.txt'), 'content');
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('specs')).toBe(false);
+    });
+
+    it('should handle multiple artifacts with mixed completion', () => {
+      const schema = createSchema([
+        { id: 'proposal', generates: 'proposal.md', description: 'Proposal', template: 't.md', requires: [] },
+        { id: 'specs', generates: 'specs/*.md', description: 'Specs', template: 't.md', requires: ['proposal'] },
+        { id: 'design', generates: 'design.md', description: 'Design', template: 't.md', requires: ['proposal'] },
+        { id: 'tasks', generates: 'tasks.md', description: 'Tasks', template: 't.md', requires: ['specs', 'design'] },
+      ]);
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create some files
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), 'content');
+      fs.mkdirSync(path.join(tempDir, 'specs'), { recursive: true });
+      fs.writeFileSync(path.join(tempDir, 'specs', 'auth.md'), 'content');
+      // design.md and tasks.md do not exist
+
+      const completed = detectCompleted(graph, tempDir);
+
+      expect(completed.has('proposal')).toBe(true);
+      expect(completed.has('specs')).toBe(true);
+      expect(completed.has('design')).toBe(false);
+      expect(completed.has('tasks')).toBe(false);
+    });
+  });
+});
@@ -0,0 +1,222 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { resolveSchema } from '../../../src/core/artifact-graph/resolver.js';
+import { ArtifactGraph } from '../../../src/core/artifact-graph/graph.js';
+import { detectCompleted } from '../../../src/core/artifact-graph/state.js';
+import type { BlockedArtifacts } from '../../../src/core/artifact-graph/types.js';
+
+/**
+ * Normalize BlockedArtifacts for comparison by sorting dependency arrays.
+ * The order of unmet dependencies is not guaranteed, so we sort for stable assertions.
+ */
+function normalizeBlocked(blocked: BlockedArtifacts): BlockedArtifacts {
+  const normalized: BlockedArtifacts = {};
+  for (const [key, deps] of Object.entries(blocked)) {
+    normalized[key] = [...deps].sort();
+  }
+  return normalized;
+}
+
+describe('artifact-graph workflow integration', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    // Use a unique temp directory for each test
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openspec-workflow-test-'));
+  });
+
+  afterEach(() => {
+    // Clean up temp directory after each test
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('spec-driven workflow', () => {
+    it('should progress through complete workflow', () => {
+      // 1. Resolve the real built-in schema
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Verify schema structure
+      expect(graph.getName()).toBe('spec-driven');
+      expect(graph.getAllArtifacts()).toHaveLength(4);
+
+      // 2. Initial state - nothing complete, only proposal is ready
+      let completed = detectCompleted(graph, tempDir);
+      expect(completed.size).toBe(0);
+      expect(graph.getNextArtifacts(completed)).toEqual(['proposal']);
+      expect(graph.isComplete(completed)).toBe(false);
+      expect(normalizeBlocked(graph.getBlocked(completed))).toEqual({
+        specs: ['proposal'],
+        design: ['proposal'],
+        tasks: ['design', 'specs'],
+      });
+
+      // 3. Create proposal.md - now specs and design become ready
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal\n\nInitial proposal content.');
+      completed = detectCompleted(graph, tempDir);
+      expect(completed).toEqual(new Set(['proposal']));
+      expect(graph.getNextArtifacts(completed).sort()).toEqual(['design', 'specs']);
+      expect(normalizeBlocked(graph.getBlocked(completed))).toEqual({
+        tasks: ['design', 'specs'],
+      });
+
+      // 4. Create design.md - specs still needed for tasks
+      fs.writeFileSync(path.join(tempDir, 'design.md'), '# Design\n\nTechnical design content.');
+      completed = detectCompleted(graph, tempDir);
+      expect(completed).toEqual(new Set(['proposal', 'design']));
+      expect(graph.getNextArtifacts(completed)).toEqual(['specs']);
+      expect(graph.getBlocked(completed)).toEqual({
+        tasks: ['specs'],
+      });
+
+      // 5. Create specs directory with a spec file - tasks becomes ready
+      const specsDir = path.join(tempDir, 'specs');
+      fs.mkdirSync(specsDir, { recursive: true });
+      fs.writeFileSync(path.join(specsDir, 'feature-auth.md'), '# Auth Spec\n\nAuthentication specification.');
+      completed = detectCompleted(graph, tempDir);
+      expect(completed).toEqual(new Set(['proposal', 'design', 'specs']));
+      expect(graph.getNextArtifacts(completed)).toEqual(['tasks']);
+      expect(graph.getBlocked(completed)).toEqual({});
+
+      // 6. Create tasks.md - workflow complete
+      fs.writeFileSync(path.join(tempDir, 'tasks.md'), '# Tasks\n\n- [ ] Implement feature');
+      completed = detectCompleted(graph, tempDir);
+      expect(completed).toEqual(new Set(['proposal', 'design', 'specs', 'tasks']));
+      expect(graph.getNextArtifacts(completed)).toEqual([]);
+      expect(graph.isComplete(completed)).toBe(true);
+      expect(graph.getBlocked(completed)).toEqual({});
+    });
+
+    it('should handle out-of-order file creation', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create files in wrong order - design before proposal
+      fs.writeFileSync(path.join(tempDir, 'design.md'), '# Design');
+
+      let completed = detectCompleted(graph, tempDir);
+      // design file exists but it's still marked complete (filesystem-based)
+      expect(completed).toEqual(new Set(['design']));
+      // proposal is still the only "ready" artifact since it has no deps
+      expect(graph.getNextArtifacts(completed)).toEqual(['proposal']);
+
+      // Now create proposal
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal');
+      completed = detectCompleted(graph, tempDir);
+      expect(completed).toEqual(new Set(['proposal', 'design']));
+      // specs is the only thing ready now (design already done)
+      expect(graph.getNextArtifacts(completed)).toEqual(['specs']);
+    });
+
+    it('should handle multiple spec files in glob pattern', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Complete prerequisites
+      fs.writeFileSync(path.join(tempDir, 'proposal.md'), '# Proposal');
+
+      // Create specs directory with multiple files
+      const specsDir = path.join(tempDir, 'specs');
+      fs.mkdirSync(specsDir, { recursive: true });
+      fs.writeFileSync(path.join(specsDir, 'auth.md'), '# Auth');
+      fs.writeFileSync(path.join(specsDir, 'api.md'), '# API');
+      fs.writeFileSync(path.join(specsDir, 'database.md'), '# Database');
+
+      const completed = detectCompleted(graph, tempDir);
+      expect(completed.has('specs')).toBe(true);
+    });
+  });
+
+  describe('tdd workflow', () => {
+    it('should progress through complete workflow', () => {
+      const schema = resolveSchema('tdd');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      expect(graph.getName()).toBe('tdd');
+      expect(graph.getBuildOrder()).toEqual(['spec', 'tests', 'implementation', 'docs']);
+
+      // Initial state
+      let completed = detectCompleted(graph, tempDir);
+      expect(graph.getNextArtifacts(completed)).toEqual(['spec']);
+
+      // Create spec
+      fs.writeFileSync(path.join(tempDir, 'spec.md'), '# Feature Spec');
+      completed = detectCompleted(graph, tempDir);
+      expect(graph.getNextArtifacts(completed)).toEqual(['tests']);
+
+      // Create tests directory with test file
+      const testsDir = path.join(tempDir, 'tests');
+      fs.mkdirSync(testsDir, { recursive: true });
+      fs.writeFileSync(path.join(testsDir, 'feature.test.ts'), 'describe("feature", () => {});');
+      completed = detectCompleted(graph, tempDir);
+      expect(graph.getNextArtifacts(completed)).toEqual(['implementation']);
+
+      // Create src directory with implementation
+      const srcDir = path.join(tempDir, 'src');
+      fs.mkdirSync(srcDir, { recursive: true });
+      fs.writeFileSync(path.join(srcDir, 'feature.ts'), 'export function feature() {}');
+      completed = detectCompleted(graph, tempDir);
+      expect(graph.getNextArtifacts(completed)).toEqual(['docs']);
+
+      // Create docs
+      const docsDir = path.join(tempDir, 'docs');
+      fs.mkdirSync(docsDir, { recursive: true });
+      fs.writeFileSync(path.join(docsDir, 'feature.md'), '# Feature Documentation');
+      completed = detectCompleted(graph, tempDir);
+      expect(graph.isComplete(completed)).toBe(true);
+    });
+  });
+
+  describe('build order consistency', () => {
+    it('should return consistent build order across multiple calls', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const order1 = graph.getBuildOrder();
+      const order2 = graph.getBuildOrder();
+      const order3 = graph.getBuildOrder();
+
+      expect(order1).toEqual(order2);
+      expect(order2).toEqual(order3);
+    });
+  });
+
+  describe('empty and edge cases', () => {
+    it('should handle empty change directory gracefully', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Directory exists but is empty
+      const completed = detectCompleted(graph, tempDir);
+      expect(completed.size).toBe(0);
+      expect(graph.getNextArtifacts(completed)).toEqual(['proposal']);
+    });
+
+    it('should handle non-existent change directory', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      const nonExistentDir = path.join(tempDir, 'does-not-exist');
+      const completed = detectCompleted(graph, nonExistentDir);
+      expect(completed.size).toBe(0);
+    });
+
+    it('should not count non-matching files in glob directories', () => {
+      const schema = resolveSchema('spec-driven');
+      const graph = ArtifactGraph.fromSchema(schema);
+
+      // Create specs directory with wrong file types
+      const specsDir = path.join(tempDir, 'specs');
+      fs.mkdirSync(specsDir, { recursive: true });
+      fs.writeFileSync(path.join(specsDir, 'notes.txt'), 'not a markdown file');
+      fs.writeFileSync(path.join(specsDir, 'data.json'), '{}');
+
+      const completed = detectCompleted(graph, tempDir);
+      expect(completed.has('specs')).toBe(false);
+    });
+  });
+});
@@ -0,0 +1,288 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import { randomUUID } from 'crypto';
+import { CompletionProvider } from '../../../src/core/completions/completion-provider.js';
+
+describe('CompletionProvider', () => {
+  let testDir: string;
+  let provider: CompletionProvider;
+
+  beforeEach(async () => {
+    testDir = path.join(os.tmpdir(), `openspec-test-${randomUUID()}`);
+    await fs.mkdir(testDir, { recursive: true });
+    provider = new CompletionProvider(2000, testDir);
+  });
+
+  afterEach(async () => {
+    await fs.rm(testDir, { recursive: true, force: true });
+  });
+
+  describe('getChangeIds', () => {
+    it('should return empty array when no changes exist', async () => {
+      const changeIds = await provider.getChangeIds();
+      expect(changeIds).toEqual([]);
+    });
+
+    it('should return active change IDs', async () => {
+      // Create openspec/changes directory structure
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      // Create some changes
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      await fs.mkdir(path.join(changesDir, 'change-2'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-2', 'proposal.md'), '# Change 2');
+
+      const changeIds = await provider.getChangeIds();
+      expect(changeIds).toEqual(['change-1', 'change-2']);
+    });
+
+    it('should exclude archive directory', async () => {
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      // Create active change
+      await fs.mkdir(path.join(changesDir, 'active-change'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'active-change', 'proposal.md'), '# Active');
+
+      // Create archived change
+      await fs.mkdir(path.join(changesDir, 'archive', 'old-change'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'archive', 'old-change', 'proposal.md'), '# Old');
+
+      const changeIds = await provider.getChangeIds();
+      expect(changeIds).toEqual(['active-change']);
+    });
+
+    it('should cache results for the TTL duration', async () => {
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      // First call
+      const firstResult = await provider.getChangeIds();
+      expect(firstResult).toEqual(['change-1']);
+
+      // Add another change
+      await fs.mkdir(path.join(changesDir, 'change-2'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-2', 'proposal.md'), '# Change 2');
+
+      // Second call should return cached result (still only change-1)
+      const secondResult = await provider.getChangeIds();
+      expect(secondResult).toEqual(['change-1']);
+    });
+
+    it('should refresh cache after TTL expires', async () => {
+      // Use a very short TTL for testing
+      const shortTTLProvider = new CompletionProvider(50, testDir);
+
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      // First call
+      const firstResult = await shortTTLProvider.getChangeIds();
+      expect(firstResult).toEqual(['change-1']);
+
+      // Add another change
+      await fs.mkdir(path.join(changesDir, 'change-2'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-2', 'proposal.md'), '# Change 2');
+
+      // Wait for cache to expire
+      await new Promise(resolve => setTimeout(resolve, 60));
+
+      // Should now see both changes
+      const secondResult = await shortTTLProvider.getChangeIds();
+      expect(secondResult).toEqual(['change-1', 'change-2']);
+    });
+  });
+
+  describe('getSpecIds', () => {
+    it('should return empty array when no specs exist', async () => {
+      const specIds = await provider.getSpecIds();
+      expect(specIds).toEqual([]);
+    });
+
+    it('should return spec IDs', async () => {
+      const specsDir = path.join(testDir, 'openspec', 'specs');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      // Create some specs
+      await fs.mkdir(path.join(specsDir, 'spec-1'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-1', 'spec.md'), '# Spec 1');
+
+      await fs.mkdir(path.join(specsDir, 'spec-2'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-2', 'spec.md'), '# Spec 2');
+
+      const specIds = await provider.getSpecIds();
+      expect(specIds).toEqual(['spec-1', 'spec-2']);
+    });
+
+    it('should cache results for the TTL duration', async () => {
+      const specsDir = path.join(testDir, 'openspec', 'specs');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      await fs.mkdir(path.join(specsDir, 'spec-1'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-1', 'spec.md'), '# Spec 1');
+
+      // First call
+      const firstResult = await provider.getSpecIds();
+      expect(firstResult).toEqual(['spec-1']);
+
+      // Add another spec
+      await fs.mkdir(path.join(specsDir, 'spec-2'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-2', 'spec.md'), '# Spec 2');
+
+      // Second call should return cached result
+      const secondResult = await provider.getSpecIds();
+      expect(secondResult).toEqual(['spec-1']);
+    });
+
+    it('should refresh cache after TTL expires', async () => {
+      const shortTTLProvider = new CompletionProvider(50, testDir);
+
+      const specsDir = path.join(testDir, 'openspec', 'specs');
+      await fs.mkdir(specsDir, { recursive: true });
+
+      await fs.mkdir(path.join(specsDir, 'spec-1'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-1', 'spec.md'), '# Spec 1');
+
+      const firstResult = await shortTTLProvider.getSpecIds();
+      expect(firstResult).toEqual(['spec-1']);
+
+      // Add another spec
+      await fs.mkdir(path.join(specsDir, 'spec-2'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'spec-2', 'spec.md'), '# Spec 2');
+
+      // Wait for cache to expire
+      await new Promise(resolve => setTimeout(resolve, 60));
+
+      const secondResult = await shortTTLProvider.getSpecIds();
+      expect(secondResult).toEqual(['spec-1', 'spec-2']);
+    });
+  });
+
+  describe('getAllIds', () => {
+    it('should return both change and spec IDs', async () => {
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      const specsDir = path.join(testDir, 'openspec', 'specs');
+      await fs.mkdir(changesDir, { recursive: true });
+      await fs.mkdir(specsDir, { recursive: true });
+
+      // Create a change
+      await fs.mkdir(path.join(changesDir, 'my-change'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'my-change', 'proposal.md'), '# Change');
+
+      // Create a spec
+      await fs.mkdir(path.join(specsDir, 'my-spec'), { recursive: true });
+      await fs.writeFile(path.join(specsDir, 'my-spec', 'spec.md'), '# Spec');
+
+      const result = await provider.getAllIds();
+      expect(result).toEqual({
+        changeIds: ['my-change'],
+        specIds: ['my-spec'],
+      });
+    });
+
+    it('should return empty arrays when no items exist', async () => {
+      const result = await provider.getAllIds();
+      expect(result).toEqual({
+        changeIds: [],
+        specIds: [],
+      });
+    });
+  });
+
+  describe('clearCache', () => {
+    it('should clear all cached data', async () => {
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      // Populate cache
+      await provider.getChangeIds();
+
+      // Clear cache
+      provider.clearCache();
+
+      // Add new change
+      await fs.mkdir(path.join(changesDir, 'change-2'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-2', 'proposal.md'), '# Change 2');
+
+      // Should see new data immediately
+      const result = await provider.getChangeIds();
+      expect(result).toEqual(['change-1', 'change-2']);
+    });
+  });
+
+  describe('getCacheStats', () => {
+    it('should report invalid cache when empty', () => {
+      const stats = provider.getCacheStats();
+      expect(stats.changeCache.valid).toBe(false);
+      expect(stats.specCache.valid).toBe(false);
+      expect(stats.changeCache.age).toBeUndefined();
+      expect(stats.specCache.age).toBeUndefined();
+    });
+
+    it('should report valid cache after data is fetched', async () => {
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      await provider.getChangeIds();
+
+      const stats = provider.getCacheStats();
+      expect(stats.changeCache.valid).toBe(true);
+      expect(stats.changeCache.age).toBeDefined();
+      expect(stats.changeCache.age).toBeLessThan(100);
+    });
+
+    it('should report invalid cache after TTL expires', async () => {
+      const shortTTLProvider = new CompletionProvider(50, testDir);
+
+      const changesDir = path.join(testDir, 'openspec', 'changes');
+      await fs.mkdir(changesDir, { recursive: true });
+
+      await fs.mkdir(path.join(changesDir, 'change-1'), { recursive: true });
+      await fs.writeFile(path.join(changesDir, 'change-1', 'proposal.md'), '# Change 1');
+
+      await shortTTLProvider.getChangeIds();
+
+      // Wait for cache to expire
+      await new Promise(resolve => setTimeout(resolve, 60));
+
+      const stats = shortTTLProvider.getCacheStats();
+      expect(stats.changeCache.valid).toBe(false);
+      expect(stats.changeCache.age).toBeGreaterThan(50);
+    });
+  });
+
+  describe('constructor', () => {
+    it('should use default TTL of 2000ms', async () => {
+      const defaultProvider = new CompletionProvider();
+      expect(defaultProvider).toBeDefined();
+      // We can verify this behavior by checking cache stats after waiting
+    });
+
+    it('should accept custom TTL', async () => {
+      const customProvider = new CompletionProvider(5000, testDir);
+      expect(customProvider).toBeDefined();
+    });
+
+    it('should use process.cwd() as default project root', () => {
+      const defaultProvider = new CompletionProvider();
+      expect(defaultProvider).toBeDefined();
+    });
+  });
+});
@@ -0,0 +1,381 @@
+import { describe, it, expect } from 'vitest';
+import { ZshGenerator } from '../../../../src/core/completions/generators/zsh-generator.js';
+import { CommandDefinition } from '../../../../src/core/completions/types.js';
+
+describe('ZshGenerator', () => {
+  let generator: ZshGenerator;
+
+  beforeEach(() => {
+    generator = new ZshGenerator();
+  });
+
+  describe('interface compliance', () => {
+    it('should have shell property set to "zsh"', () => {
+      expect(generator.shell).toBe('zsh');
+    });
+
+    it('should implement generate method', () => {
+      expect(typeof generator.generate).toBe('function');
+    });
+  });
+
+  describe('generate', () => {
+    it('should generate valid zsh completion script with header', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'init',
+          description: 'Initialize OpenSpec',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('#compdef openspec');
+      expect(script).toContain('# Zsh completion script for OpenSpec CLI');
+      expect(script).toContain('_openspec() {');
+    });
+
+    it('should include all commands in the command list', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'init',
+          description: 'Initialize OpenSpec',
+          flags: [],
+        },
+        {
+          name: 'validate',
+          description: 'Validate specs',
+          flags: [],
+        },
+        {
+          name: 'show',
+          description: 'Show a spec',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'init:Initialize OpenSpec'");
+      expect(script).toContain("'validate:Validate specs'");
+      expect(script).toContain("'show:Show a spec'");
+    });
+
+    it('should generate command completion functions', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'init',
+          description: 'Initialize OpenSpec',
+          flags: [],
+        },
+        {
+          name: 'validate',
+          description: 'Validate specs',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('_openspec_init() {');
+      expect(script).toContain('_openspec_validate() {');
+    });
+
+    it('should handle commands with flags', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'validate',
+          description: 'Validate specs',
+          flags: [
+            {
+              name: 'strict',
+              description: 'Enable strict mode',
+            },
+            {
+              name: 'json',
+              description: 'Output as JSON',
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('--strict');
+      expect(script).toContain('[Enable strict mode]');
+      expect(script).toContain('--json');
+      expect(script).toContain('[Output as JSON]');
+    });
+
+    it('should handle flags with short options', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'show',
+          description: 'Show a spec',
+          flags: [
+            {
+              name: 'requirement',
+              short: 'r',
+              description: 'Show specific requirement',
+              takesValue: true,
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'(-r --requirement)'{-r,--requirement}'[Show specific requirement]:value:'");
+      expect(script).toContain('[Show specific requirement]');
+    });
+
+    it('should handle flags that take values', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'validate',
+          description: 'Validate specs',
+          flags: [
+            {
+              name: 'type',
+              description: 'Specify item type',
+              takesValue: true,
+              values: ['change', 'spec'],
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('--type');
+      expect(script).toContain('[Specify item type]');
+      expect(script).toContain(':value:(change spec)');
+    });
+
+    it('should handle flags with takesValue but no specific values', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'validate',
+          description: 'Validate specs',
+          flags: [
+            {
+              name: 'concurrency',
+              description: 'Max concurrent validations',
+              takesValue: true,
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('--concurrency');
+      expect(script).toContain('[Max concurrent validations]');
+      expect(script).toContain(':value:');
+    });
+
+    it('should handle commands with subcommands', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'change',
+          description: 'Manage changes',
+          flags: [],
+          subcommands: [
+            {
+              name: 'show',
+              description: 'Show a change',
+              flags: [],
+            },
+            {
+              name: 'list',
+              description: 'List changes',
+              flags: [],
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'show:Show a change'");
+      expect(script).toContain("'list:List changes'");
+      expect(script).toContain('_openspec_change_show() {');
+      expect(script).toContain('_openspec_change_list() {');
+    });
+
+    it('should handle positional arguments for change-id', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'archive',
+          description: 'Archive a change',
+          acceptsPositional: true,
+          positionalType: 'change-id',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'*: :_openspec_complete_changes'");
+    });
+
+    it('should handle positional arguments for spec-id', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'show-spec',
+          description: 'Show a spec',
+          acceptsPositional: true,
+          positionalType: 'spec-id',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'*: :_openspec_complete_specs'");
+    });
+
+    it('should handle positional arguments for change-or-spec-id', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'show',
+          description: 'Show an item',
+          acceptsPositional: true,
+          positionalType: 'change-or-spec-id',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'*: :_openspec_complete_items'");
+    });
+
+    it('should handle positional arguments for paths', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'init',
+          description: 'Initialize OpenSpec',
+          acceptsPositional: true,
+          positionalType: 'path',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("'*:path:_files'");
+    });
+
+    it('should escape special characters in descriptions', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'test',
+          description: "Test with 'quotes' and [brackets] and back\\slash and colon:",
+          flags: [
+            {
+              name: 'flag',
+              description: "Special chars: 'quotes' [brackets] back\\slash colon:",
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain("\\'quotes\\'");
+      expect(script).toContain('\\[brackets\\]');
+      expect(script).toContain('\\\\slash');
+      expect(script).toContain('\\:');
+    });
+
+    it('should sanitize command names with hyphens for function names', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'my-command',
+          description: 'A hyphenated command',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('_openspec_my_command() {');
+    });
+
+    it('should handle complex nested subcommands with flags', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'spec',
+          description: 'Manage specs',
+          flags: [],
+          subcommands: [
+            {
+              name: 'validate',
+              description: 'Validate a spec',
+              acceptsPositional: true,
+              positionalType: 'spec-id',
+              flags: [
+                {
+                  name: 'strict',
+                  description: 'Enable strict mode',
+                },
+                {
+                  name: 'json',
+                  description: 'Output as JSON',
+                },
+              ],
+            },
+          ],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('_openspec_spec() {');
+      expect(script).toContain('_openspec_spec_validate() {');
+      expect(script).toContain('--strict');
+      expect(script).toContain('--json');
+      expect(script).toContain("'*: :_openspec_complete_specs'");
+    });
+
+    it('should generate script that ends with compdef registration', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'init',
+          description: 'Initialize',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script.trim().endsWith('compdef _openspec openspec')).toBe(true);
+    });
+
+    it('should handle empty command list', () => {
+      const commands: CommandDefinition[] = [];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('#compdef openspec');
+      expect(script).toContain('_openspec() {');
+    });
+
+    it('should handle commands with no flags', () => {
+      const commands: CommandDefinition[] = [
+        {
+          name: 'view',
+          description: 'Display dashboard',
+          flags: [],
+        },
+      ];
+
+      const script = generator.generate(commands);
+
+      expect(script).toContain('_openspec_view() {');
+      expect(script).toContain('_arguments');
+    });
+  });
+});
--- a/Show More
+++ b/Show More