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
222 changed files with 19165 additions and 332 deletions
@@ -0,0 +1,11 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+# Minimal configuration for getting started
+language: "en-US"
+reviews:
+  profile: "chill"
+  high_level_summary: true
+  auto_review:
+    enabled: true
+    drafts: false
+    base_branches:
+      - ".*"
@@ -0,0 +1,92 @@
+# Dev Container Setup
+
+This directory contains the VS Code dev container configuration for OpenSpec development.
+
+## What's Included
+
+- **Node.js 20 LTS** (>=20.19.0) - TypeScript/JavaScript runtime
+- **pnpm** - Fast, disk space efficient package manager
+- **Git + GitHub CLI** - Version control tools
+- **VS Code Extensions**:
+  - ESLint & Prettier for code quality
+  - Vitest Explorer for running tests
+  - GitLens for enhanced git integration
+  - Error Lens for inline error highlighting
+  - Code Spell Checker
+  - Path IntelliSense
+
+## How to Use
+
+### First Time Setup
+
+1. **Install Prerequisites** (on your local machine):
+   - [VS Code](https://code.visualstudio.com/)
+   - [Docker Desktop](https://www.docker.com/products/docker-desktop)
+   - [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
+
+2. **Open in Container**:
+   - Open this project in VS Code
+   - You'll see a notification: "Folder contains a Dev Container configuration file"
+   - Click "Reopen in Container"
+
+   OR
+
+   - Open Command Palette (`Cmd/Ctrl+Shift+P`)
+   - Type "Dev Containers: Reopen in Container"
+   - Press Enter
+
+3. **Wait for Setup**:
+   - The container will build (first time takes a few minutes)
+   - `pnpm install` runs automatically via `postCreateCommand`
+   - All extensions install automatically
+
+### Daily Development
+
+Once set up, the container preserves your development environment:
+
+```bash
+# Run development build
+pnpm run dev
+
+# Run CLI in development
+pnpm run dev:cli
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Build the project
+pnpm run build
+```
+
+### SSH Keys
+
+Your SSH keys are mounted read-only from `~/.ssh`, so git operations work seamlessly with GitHub/GitLab.
+
+### Rebuilding the Container
+
+If you modify `.devcontainer/devcontainer.json`:
+- Command Palette → "Dev Containers: Rebuild Container"
+
+## Benefits
+
+- No need to install Node.js or pnpm on your local machine
+- Consistent development environment across team members
+- Isolated from other Node.js projects on your machine
+- All dependencies and tools containerized
+- Easy onboarding for new developers
+
+## Troubleshooting
+
+**Container won't build:**
+- Ensure Docker Desktop is running
+- Check Docker has enough memory allocated (recommend 4GB+)
+
+**Extensions not appearing:**
+- Rebuild the container: "Dev Containers: Rebuild Container"
+
+**Permission issues:**
+- The container runs as the `node` user (non-root)
+- Files created in the container are owned by this user
@@ -0,0 +1,68 @@
+{
+  "name": "OpenSpec Development",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
+
+  // Additional tools and features
+  "features": {
+    "ghcr.io/devcontainers/features/git:1": {
+      "version": "latest",
+      "ppa": true
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "latest"
+    }
+  },
+
+  // Configure tool-specific properties
+  "customizations": {
+    "vscode": {
+      // Set default container specific settings
+      "settings": {
+        "typescript.tsdk": "node_modules/typescript/lib",
+        "typescript.enablePromptUseWorkspaceTsdk": true,
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.codeActionsOnSave": {
+          "source.fixAll": "explicit"
+        },
+        "files.eol": "\n",
+        "terminal.integrated.defaultProfile.linux": "bash"
+      },
+
+      // Add extensions you want installed when the container is created
+      "extensions": [
+        // TypeScript/JavaScript essentials
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+
+        // Testing
+        "vitest.explorer",
+
+        // Git
+        "eamodio.gitlens",
+
+        // Utilities
+        "streetsidesoftware.code-spell-checker",
+        "usernamehw.errorlens",
+        "christian-kohler.path-intellisense"
+      ]
+    }
+  },
+
+  // Use 'forwardPorts' to make a list of ports inside the container available locally
+  // "forwardPorts": [],
+
+  // Use 'postCreateCommand' to run commands after the container is created
+  "postCreateCommand": "corepack enable && corepack prepare pnpm@latest --activate && pnpm install",
+
+  // Configure mounts to preserve SSH keys for git operations
+  "mounts": [
+    "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/node/.ssh,readonly,type=bind,consistency=cached"
+  ],
+
+  // Set the default user to 'node' (non-root user)
+  "remoteUser": "node",
+
+  // Ensure git is properly configured
+  "initializeCommand": "echo 'Initializing dev container...'"
+}
@@ -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,10 +140,11 @@ dist/
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*

-# Internal Docs
-docs/

 # Claude
 .claude/
 CLAUDE.md
 .DS_Store
+
+# Pnpm
+.pnpm-store/
@@ -1,5 +1,165 @@
 # @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
+
+- c08fbc1: Add new AI tool integrations and enhancements:
+
+  - **feat(iflow-cli)**: Add iFlow-cli integration with slash command support and documentation
+  - **feat(init)**: Add IDE restart instruction after init to inform users about slash command availability
+    **feat(antigravity)**: Add Antigravity slash command support
+  - **fix**: Generate TOML commands for Qwen Code (fixes #293)
+  - Clarify scaffold proposal documentation and enhance proposal guidelines
+  - Update proposal guidelines to emphasize design-first approach before implementation
+
+## Unreleased
+
+### Minor Changes
+
+- Add Antigravity slash command support so `openspec init` can generate `.agent/workflows/openspec-*.md` files with description-only frontmatter and `openspec update` refreshes existing workflows alongside Windsurf.
+
+## 0.15.0
+
+### Minor Changes
+
+- 4758c5c: Add support for new AI tools with native slash command integration
+
+  - **Gemini CLI**: Add native TOML-based slash command support for Gemini CLI with `.gemini/commands/openspec/` integration
+  - **RooCode**: Add RooCode integration with configurator, slash commands, and templates
+  - **Cline**: Fix Cline to use workflows instead of rules for slash commands (`.clinerules/workflows/` paths)
+  - **Documentation**: Update documentation to reflect new integrations and workflow changes
+
+## 0.14.0
+
+### Minor Changes
+
+- 8386b91: Add support for new AI assistants and configuration improvements
+
+  - feat: add Qwen Code support with slash command integration
+  - feat: add $ARGUMENTS support to apply slash command for dynamic variable passing
+  - feat: add Qoder CLI support to configuration and documentation
+  - feat: add CoStrict AI assistant support
+  - fix: recreate missing openspec template files in extend mode
+  - fix: prevent false 'already configured' detection for tools
+  - fix: use change-id as fallback title instead of "Untitled Change"
+  - docs: add guidance for populating project-level context
+  - docs: add Crush to supported AI tools in README
+
+## 0.13.0
+
+### Minor Changes
+
+- 668a125: Add support for multiple AI assistants and improve validation
+
+  This release adds support for several new AI coding assistants:
+
+  - CodeBuddy Code - AI-powered coding assistant
+  - CodeRabbit - AI code review assistant
+  - Cline - Claude-powered CLI assistant
+  - Crush AI - AI assistant platform
+  - Auggie (Augment CLI) - Code augmentation tool
+
+  New features:
+
+  - Archive slash command now supports arguments for more flexible workflows
+
+  Bug fixes:
+
+  - Delta spec validation now handles case-insensitive headers and properly detects empty sections
+  - Archive validation now correctly honors --no-validate flag and ignores metadata
+
+  Documentation improvements:
+
+  - Added VS Code dev container configuration for easier development setup
+  - Updated AGENTS.md with explicit change-id notation
+  - Enhanced slash commands documentation with restart notes
+
+## 0.12.0
+
+### Minor Changes
+
+- 082abb4: Add factory function support for slash commands and non-interactive init options
+
+  This release includes two new features:
+
+  - **Factory function support for slash commands**: Slash commands can now be defined as functions that return command objects, enabling dynamic command configuration
+  - **Non-interactive init options**: Added `--tools`, `--all-tools`, and `--skip-tools` CLI flags to `openspec init` for automated initialization in CI/CD pipelines while maintaining backward compatibility with interactive mode
+
+## 0.11.0
+
+### Minor Changes
+
+- 312e1d6: Add Amazon Q Developer CLI integration. OpenSpec now supports Amazon Q Developer with automatic prompt generation in `.amazonq/prompts/` directory, allowing you to use OpenSpec slash commands with Amazon Q's @-syntax.
+
+## 0.10.0
+
+### Minor Changes
+
+- d7e0ce8: Improve init wizard Enter key behavior to allow proceeding through prompts more naturally
+
+## 0.9.2
+
+### Patch Changes
+
+- 2ae0484: Fix cross-platform path handling issues. This release includes fixes for joinPath behavior and slash command path resolution to ensure OpenSpec works correctly across all platforms.
+
+## 0.9.1
+
+### Patch Changes
+
+- 8210970: Fix OpenSpec not working on Windows when Codex integration is selected. This release includes fixes for cross-platform path handling and normalization to ensure OpenSpec works correctly on Windows systems.
+
+## 0.9.0
+
+### Minor Changes
+
+- efbbf3b: Add support for Codex and GitHub Copilot slash commands with YAML frontmatter and $ARGUMENTS
+
+## Unreleased
+
+### Minor Changes
+
+- Add GitHub Copilot slash command support. OpenSpec now writes prompts to `.github/prompts/openspec-{proposal,apply,archive}.prompt.md` with YAML frontmatter and `$ARGUMENTS` placeholder, and refreshes them on `openspec update`.
+
 ## 0.8.1

 ### Patch Changes
@@ -85,26 +85,48 @@ 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` |
-| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
+| **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/`) |
+| **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/`) |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
+| **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 • Gemini CLI • GitHub Copilot • Others |
+| Amp • Jules • Others |
+
+</details>

 ### Install & Initialize

@@ -135,13 +157,26 @@ openspec init
 ```

 **What happens during initialization:**
- You'll be prompted to pick any natively supported AI tools (Claude Code, Cursor, OpenCode, etc.); other assistants always rely on the shared `AGENTS.md` stub
+- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
 - OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
 - A new `openspec/` directory structure is created in your project

 **After setup:**
 - Primary AI tools can trigger `/openspec` workflows without additional configuration
 - Run `openspec list` to verify the setup and view any active changes
+- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
+  so a fresh launch ensures they appear
+
+### Optional: Populate Project Context
+
+After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
+
+```text
+Populate your project context:
+"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
+```
+
+Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.

 ### Create Your First Change

@@ -208,7 +243,7 @@ Or run the command yourself in terminal:
 $ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
 ```

-**Note:** Tools with native slash commands (Claude Code, Cursor, Codex) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
+**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".

 ## Command Reference

@@ -320,7 +355,7 @@ Without specs, AI coding assistants generate code from vague prompts, often miss
 1. **Initialize OpenSpec** – Run `openspec init` in your repo.
 2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
 3. **Grow incrementally** – Each change archives into living specs that document your system.
-4. **Stay flexible** – Different teammates can use Claude Code, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
+4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.

 Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.

@@ -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,98 @@
+# OpenSpec Parallel Delta Remediation Plan
+
+## Problem Summary
+- Active changes apply requirement-level replacements when archiving. When two changes touch the same requirement, the second archive overwrites the first and silently drops scenarios (e.g., Windsurf vs. Kilo Code slash command updates).
+- The archive workflow (`src/core/archive.ts:191` and `src/core/archive.ts:501`) rebuilds main specs by replacing entire requirement blocks with the content contained in the change delta. The delta format (`src/core/parsers/requirement-blocks.ts:113`) has no notion of base versions or scenario-level operations.
+- The tooling cannot detect divergence between the change author’s starting point and the live spec, so parallel development corrupts the source of truth without warning.
+
+## Observed Failure Mode
+- Change A (`add-windsurf-workflows`) adds a Windsurf scenario under `Slash Command Configuration`.
+- Change B (`add-kilocode-workflows`) adds a Kilo Code scenario to the same requirement, starting from the pre-Windsurf spec.
+- After Change A archives, the main spec contains both scenarios.
+- When Change B archives, `buildUpdatedSpec` sees a `MODIFIED` block for `Slash Command Configuration` and replaces the requirement with the four-scenario variant shipped in that change. Because that file never learned about Windsurf, the Windsurf scenario disappears.
+- There is no warning, diff, or conflict indicator—the archive completes successfully, and the source-of-truth spec now omits a shipped scenario.
+
+## Root Causes
+1. **Replace-only semantics.** `buildUpdatedSpec` performs hash-map substitution of requirement blocks and cannot merge or compare individual scenarios (`src/core/archive.ts:455`-`src/core/archive.ts:526`).
+2. **Missing base fingerprint.** Changes do not persist the requirement content they were authored against, so the archive step cannot tell if the live spec diverged.
+3. **Single-level granularity.** The delta language only understands requirements. Even if we introduced scenario-level parsing, we would still lose sibling edits without an accompanying merge strategy.
+4. **Lack of conflict UX.** The CLI never forces contributors to reconcile parallel updates. There is no equivalent of `git merge`, `git rebase`, or conflict markers.
+
+## Design Objectives
+- Preserve every approved scenario regardless of archive order.
+- Detect and block speculative archives when the live spec diverges from the author’s base.
+- Provide a deterministic, reviewable conflict resolution flow that mirrors source-control best practices.
+- Keep the authoring experience ergonomic: deltas should remain human-editable markdown.
+- Support incremental adoption so existing repositories can roll forward without breaking active work.
+
+## Proposed Fix: Layered Remediation
+
+### Phase 0 – Stop the Bleeding (Detection & Guardrails)
+1. **Persist requirement fingerprints alongside each change.**
+   - When scaffolding or validating a change, capture the current requirement body for every `MODIFIED`/`REMOVED`/`RENAMED` entry and write it to `changes/<id>/meta.json`.
+   - Store a stable hash (e.g., SHA-256) of the base requirement content and the raw text itself for later merges.
+2. **Validate fingerprints during archive.**
+   - Before `buildUpdatedSpec` mutates specs, recompute the requirement hash from the live spec.
+   - If the hash differs from the stored base, abort and instruct the user to rebase. This makes the destructive path impossible.
+3. **Surface intent in CLI output.**
+   - Show which requirements are stale, when they diverged, and which change last touched them.
+4. **Document interim manual mitigation.**
+   - Update `openspec/AGENTS.md` and docs so contributors know to rerun `openspec change sync` (see Phase 1) whenever another change lands.
+
+_Outcome:_ We prevent data loss immediately while we work on a richer merge story.
+
+### Phase 1 – Add a Rebase Workflow (Author-Side Merge)
+1. **Introduce `openspec change sync <id>` (or `rebase`).**
+   - Reads the stored base snapshot, the current spec, and the author’s delta.
+   - Performs a 3-way merge per requirement. A naive diff3 on markdown lines is acceptable initially because we already operate on requirement-sized chunks.
+   - If the merge is clean, rewrite the `MODIFIED` block with the merged text and refresh the stored fingerprint.
+   - On conflict, write conflict markers inside the change delta (similar to Git) and require the author to hand-edit before re-running validation.
+2. **Enrich validator messages.**
+   - `openspec validate` should flag unresolved conflict markers or fingerprint mismatches so errors appear early in the workflow.
+3. **Optional:** Offer a `--rewrite-scenarios` helper that merges bullet lists of scenarios to reduce manual editing noise.
+
+_Outcome:_ Contributors can safely reconcile their work with the latest spec before archiving, restoring true parallel development.
+
+### Phase 2 – Increase Delta Granularity
+1. **Extend the delta language with scenario-level directives.**
+   - Allow `## MODIFIED Requirements` + `## ADDED Scenarios` / `## MODIFIED Scenarios` sections nested under the requirement header.
+   - Backed by stable scenario identifiers (explicit IDs or generated hashes) stored in `meta.json`. This lets the system reason about individual scenarios.
+2. **Teach the parser to understand nested operations.**
+   - Update `parseDeltaSpec` to emit scenario-level operations in addition to requirement blocks.
+   - Update `buildUpdatedSpec` (or its replacement) to merge scenario lists, preserving order while inserting new entries in a deterministic fashion.
+3. **Automate migration.**
+   - Provide a one-time command that inspects each existing spec, injects scenario IDs, and rewrites in-flight change deltas into the richer format.
+4. **Continue to rely on the Phase 1 rebase flow for conflicts when two changes edit the same scenario body or description.**
+
+_Outcome:_ Most concurrent updates become commutative, drastically reducing the odds of human merges.
+
+### Phase 3 – Structured Spec Graph (Long-Term)
+1. **Define stable requirement IDs.**
+   - Embed `Requirement ID: <uuid>` markers in specs so renames and moves are trackable.
+   - This enables future features like cross-capability references and better diff visualizations.
+2. **Model spec edits as operations over an AST.**
+   - Build an intermediate representation (IR) for requirements/scenarios/metadata.
+   - Use operational transforms or CRDT-like techniques to guarantee merge associativity.
+3. **Integrate with Git directly.**
+   - Offer optional `openspec branch` scaffolding that aligns spec changes with Git branches, letting teams leverage Git’s conflict editor for the markdown IR.
+
+_Outcome:_ OpenSpec graduates from replace-based updates to a resilient, intent-preserving spec management platform.
+
+## Migration & Product Impacts
+- **Backfill metadata:** add hashes for all active changes and the current main specs during the initial rollout.
+- **CLI UX:** new commands (`change sync`, enhanced `archive`) require documentation, help text, and release notes.
+- **Docs & AGENTS updates:** reinforce the rebase workflow and explain conflict resolution to AI assistants.
+- **Testing:** introduce fixtures covering divergent requirement fingerprints and merge resolution logic.
+- **Telemetry (optional):** log fingerprint mismatches so we can see how often teams hit conflicts after the rollout.
+
+## Open Questions / Risks
+- How should we order scenarios when multiple changes insert at different points? (Consider optional `position` metadata or deterministic alphabetical fallbacks.)
+- What is the graceful failure mode if contributors delete the `meta.json` file? (CLI should recreate fingerprints on demand.)
+- Do we need to support offline authors who cannot easily re-run the sync command before archiving? (Potential `--accept-outdated` escape hatch for emergencies.)
+- How will archived historical changes be handled? We may need a migration script to embed fingerprints retroactively so re-validation succeeds.
+
+## Immediate Next Steps
+1. Prototype fingerprint capture during `openspec change validate` and block archive on mismatches.
+2. Ship `openspec change sync` with line-based diff3 merging and conflict markers.
+3. Update contributor docs and AI instructions to mandate running `sync` before archiving.
+4. Plan the scenario-level delta extension and migration path as a follow-up RFC.
@@ -60,7 +60,7 @@ Track these steps as TODOs and complete them one by one.
 After deployment, create separate PR to:
 - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
 - Update `specs/` if capabilities changed
- Use `openspec archive [change] --skip-specs --yes` for tooling-only changes
+- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
 - Run `openspec validate --strict` to confirm the archived change passes checks

 ## Before Any Task
@@ -95,9 +95,8 @@ After deployment, create separate PR to:
 openspec list                  # List active changes
 openspec list --specs          # List specifications
 openspec show [item]           # Display change or spec
-openspec diff [change]         # Show spec differences
 openspec validate [item]       # Validate changes or specs
-openspec archive [change] [--yes|-y]      # Archive after deployment (add --yes for non-interactive runs)
+openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)

 # Project management
 openspec init [path]           # Initialize OpenSpec
@@ -448,9 +447,8 @@ Only add complexity with:
 ```bash
 openspec list              # What's in progress?
 openspec show [item]       # View details
-openspec diff [change]     # What's changing?
 openspec validate --strict # Is it correct?
-openspec archive [change] [--yes|-y]  # Mark complete (add --yes for automation)
+openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
 ```

 Remember: Specs are truth. Changes are proposals. Keep them in sync.
@@ -0,0 +1,11 @@
+## Why
+Google is rolling out Antigravity, a Windsurf-derived IDE that discovers workflows from `.agent/workflows/*.md`. Today OpenSpec can only scaffold slash commands for Windsurf directories, so Antigravity users cannot run the proposal/apply/archive flows from the IDE.
+
+## What Changes
+- Add Antigravity as a selectable native tool in `openspec init` so it creates `.agent/workflows/openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md` with YAML frontmatter containing only a `description` field plus the standard OpenSpec-managed body.
+- Ensure `openspec update` refreshes the body of any existing Antigravity workflows inside `.agent/workflows/` without creating missing files, mirroring the Windsurf behavior.
+- Share e2e/template coverage confirming the generator writes the proper directory, filename casing, and frontmatter format so Antigravity picks up the workflows.
+
+## Impact
+- Affected specs: `specs/cli-init`, `specs/cli-update`
+- Expected code: CLI init/update tool registries, slash-command templates, associated tests
@@ -0,0 +1,9 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Antigravity
+- **WHEN** the user selects Antigravity during initialization
+- **THEN** create `.agent/workflows/openspec-proposal.md`, `.agent/workflows/openspec-apply.md`, and `.agent/workflows/openspec-archive.md`
+- **AND** ensure each file begins with YAML frontmatter that contains only a `description: <stage summary>` field followed by the shared OpenSpec workflow instructions wrapped in managed markers
+- **AND** populate the workflow body with the same proposal/apply/archive guidance used for other tools so Antigravity behaves like Windsurf while pointing to the `.agent/workflows/` directory
@@ -0,0 +1,8 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
+
+#### Scenario: Updating slash commands for Antigravity
+- **WHEN** `.agent/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh the OpenSpec-managed portion of each file so the workflow copy matches other tools while preserving the existing single-field `description` frontmatter
+- **AND** skip creating any missing workflow files during update, mirroring the behavior for Windsurf and other IDEs
@@ -0,0 +1,12 @@
+## 1. CLI init support
+- [x] 1.1 Surface Antigravity in the native-tool picker (interactive + `--tools`) so it toggles alongside other IDEs.
+- [x] 1.2 Generate `.agent/workflows/openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md` with YAML frontmatter restricted to a single `description` field for each stage and wrap the body in OpenSpec markers.
+- [x] 1.3 Confirm workspace scaffolding covers missing directory creation and re-run scenarios so repeated init refreshes the managed block.
+
+## 2. CLI update support
+- [x] 2.1 Detect existing Antigravity workflow files during `openspec update` and refresh only the managed body, skipping creation when files are missing.
+- [x] 2.2 Ensure update logic preserves the `description` frontmatter block exactly as written by init, including case and spacing, and refreshes body templates alongside other tools.
+
+## 3. Templates and tests
+- [x] 3.1 Add shared template entries for Antigravity that reuse the Windsurf copy but target `.agent/workflows` plus the description-only frontmatter requirement.
+- [x] 3.2 Expand automated coverage (unit or integration) verifying init and update produce the expected file paths and frontmatter + body markers for Antigravity.
@@ -1,8 +0,0 @@
-## MODIFIED Requirements
-### Requirement: Slash Command Updates
-The update command SHALL refresh existing slash command files for configured tools without creating new ones.
-#### Scenario: Updating slash commands for Kilo Code
- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
- **AND** ensure templates include instructions for the relevant workflow stage
- **AND** skip creating missing files (the update command only refreshes what already exists)
@@ -2,9 +2,9 @@
 Manual setup for new changes leads to formatting mistakes in spec deltas and slows agents who must recreate the same file skeletons for every proposal. A built-in scaffold command will generate compliant templates so assistants can focus on the change content instead of structure.

 ## What Changes
- Add an `openspec scaffold <change-id>` CLI command that creates a change directory with validated `proposal.md`, `tasks.md`, and spec delta templates.
- Update CLI documentation and quick-reference guidance so agents discover the scaffold workflow before drafting files manually.
- Add automated coverage (unit/integ tests) to ensure the command respects existing naming rules and generated Markdown passes validation.
+- Add an `openspec scaffold <change-id>` CLI command that creates a change directory (if it does not already exist) with validated `proposal.md`, `tasks.md`, and spec delta templates.
+- Update CLI documentation and quick-reference guidance so agents discover the scaffold workflow before drafting files manually, including reminders on when to create spec deltas.
+- Add automated coverage (unit/integ tests) to ensure the command respects naming rules, copies templates correctly, fails for existing directories, and produces output that passes `openspec validate --strict` untouched.

 ## Impact
 - Affected specs: `specs/cli-scaffold`
@@ -9,13 +9,13 @@ The CLI SHALL expose an `openspec scaffold <change-id>` command that validates t
 - **AND** exit with code 0 after successful scaffolding

 ### Requirement: Change Directory Structure
-The scaffold command SHALL create the standard change workspace with proposal, tasks, optional design, and delta directories laid out according to OpenSpec conventions.
+The scaffold command SHALL create the standard change workspace (if it does not already exist) with proposal, tasks, optional design, and `specs/` directories laid out according to OpenSpec conventions.

 #### Scenario: Generating change workspace
 - **WHEN** scaffolding a new change with id `add-user-notifications`
- **THEN** create `openspec/changes/add-user-notifications/`
- **AND** generate `proposal.md`, `tasks.md`, and `design.md` (commented placeholder content) in that directory when missing
- **AND** create `openspec/changes/add-user-notifications/specs/` ready for capability-specific deltas
+- **THEN** create `openspec/changes/add-user-notifications/` if it does not exist
+- **AND** copy the default template bundle (proposal, tasks, design placeholders) into that directory in a single operation
+- **AND** create an empty `openspec/changes/add-user-notifications/specs/` directory ready for capability-specific deltas that will be authored later

 ### Requirement: Template Content Guidance
 The scaffold command SHALL populate generated Markdown files with OpenSpec-compliant templates so authors can copy, edit, and pass validation without reformatting.
@@ -25,15 +25,7 @@ The scaffold command SHALL populate generated Markdown files with OpenSpec-compl
 - **THEN** include the `## Why`, `## What Changes`, and `## Impact` headings with placeholder guidance text
 - **AND** ensure `tasks.md` starts with `## 1. Implementation` and numbered checklist items using `- [ ]` syntax
 - **AND** annotate optional sections (like `design.md`) with inline TODO comments so users understand when to keep or delete them
-
-### Requirement: Delta Spec Creation
-The scaffold command SHALL create at least one capability delta file with correctly formatted requirement and scenario placeholders that guide authors to enter the actual behavior.
-
-#### Scenario: Creating spec delta skeleton
- **WHEN** scaffolding a change and the capability `cli-scaffold` is provided interactively or via flags
- **THEN** generate `openspec/changes/add-user-notifications/specs/cli-scaffold/spec.md`
- **AND** include `## ADDED Requirements` with at least one `### Requirement:` block and matching `#### Scenario:` entries that remind the author to replace placeholder text
- **AND** ensure the generated delta passes `openspec validate add-user-notifications --strict` until the author edits it
+- **AND** include a short reminder inside `specs/README.md` (or similar) instructing authors to add deltas once they know the affected capability

 ### Requirement: Idempotent Execution
 The scaffold command SHALL be safe to rerun, preserving user edits while filling in any missing managed sections.
@@ -1,11 +1,12 @@
 ## 1. CLI scaffolding command
 - [ ] 1.1 Register an `openspec scaffold` command in the CLI entrypoint with `change-id` argument validation.
- [ ] 1.2 Implement generator logic that creates the change directory structure plus default `proposal.md`, `tasks.md`, and delta spec skeletons without overwriting existing populated files.
+- [ ] 1.2 Implement generator logic that copies the default change template bundle (`proposal.md`, `tasks.md`, optional `design.md`, `specs/README.md`) into `openspec/changes/<id>/`, creating the directory tree in a single pass.
+- [ ] 1.3 Detect when `openspec/changes/<id>/` already exists and exit with a clear error instead of overwriting user files.

 ## 2. Templates and documentation
- [ ] 2.1 Surface copy/paste templates and scaffold usage in the top-level quick reference for `openspec/AGENTS.md`.
- [ ] 2.2 Refresh other CLI docs (`docs/`, README) to mention the scaffold workflow and link to instructions.
+- [ ] 2.1 Update `openspec/AGENTS.md` quick reference so agents see `openspec scaffold` before drafting files manually.
+- [ ] 2.2 Refresh CLI docs/README/help text to mention the scaffold workflow, template bundle contents, and when to add spec deltas manually.

 ## 3. Test coverage
- [ ] 3.1 Add unit tests covering name validation, file generation, and idempotent reruns.
- [ ] 3.2 Add integration coverage ensuring generated files pass `openspec validate --strict` without manual edits.
+- [ ] 3.1 Add unit tests covering name validation, template copying, and existing-directory failures.
+- [ ] 3.2 Add integration coverage ensuring a freshly scaffolded change (without deltas) passes `openspec validate --strict` until the author customizes it.
@@ -1,8 +0,0 @@
-## MODIFIED Requirements
-### Requirement: Slash Command Updates
-The update command SHALL refresh existing slash command files for configured tools without creating new ones.
-#### Scenario: Updating slash commands for Windsurf
- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
- **AND** ensure templates include instructions for the relevant workflow stage
- **AND** skip creating missing files (the update command only refreshes what already exists)
@@ -1,17 +0,0 @@
-## 1. CLI wiring
- [ ] 1.1 Add Windsurf to the selectable AI tools in `openspec init`, including "already configured" detection.
- [ ] 1.2 Register a `WindsurfSlashCommandConfigurator` that writes workflows to `.windsurf/workflows/` and ensures the directory exists.
- [ ] 1.3 Ensure `openspec update` pulls the Windsurf configurator when winds is selected and skips creation when files are absent.
-
-## 2. Workflow templates
- [ ] 2.1 Reuse the shared proposal/apply/archive bodies, adding Windsurf-specific headings/description before the OpenSpec markers.
- [ ] 2.2 Confirm generated Markdown (per file) stays comfortably under the 12k character ceiling noted in the Windsurf docs.
-
-## 3. Tests & safeguards
- [ ] 3.1 Extend init tests to assert creation of `.windsurf/workflows/openspec-*.md` when Windsurf is chosen.
- [ ] 3.2 Extend update tests to assert existing Windsurf workflows are refreshed and non-existent files are ignored.
- [ ] 3.3 Add regression coverage for marker preservation inside Windsurf workflow files.
-
-## 4. Documentation
- [ ] 4.1 Update README (and any user-facing docs) to list Windsurf under native slash/workflow integrations.
- [ ] 4.2 Call out Windsurf workflow support in release notes or CHANGELOG if applicable.
@@ -1,13 +1,13 @@
 ## Why
- Codex (the VS Code extension formerly known as Codeium Chat) exposes "slash commands" by reading Markdown prompt files from `~/.codex/prompts/`. Each file name becomes the `/command` users can run, with numbered placeholders (`$1`, `$2`, …) bound to the arguments they supply. The workflow screenshot shared by Kevin Kern ("Codex problem analyzer") shows the format OpenSpec should target so teams can invoke curated workflows straight from the chat palette.
+- Codex (the VS Code extension formerly known as Codeium Chat) exposes "slash commands" by reading Markdown prompt files from `~/.codex/prompts/`. Each file name becomes the `/command` users can run, with YAML frontmatter for metadata (`description`, `argument-hint`) and `$ARGUMENTS` to capture user input. The workflow screenshot shared by Kevin Kern ("Codex problem analyzer") shows the format OpenSpec should target so teams can invoke curated workflows straight from the chat palette.
 - Teams already rely on OpenSpec to manage the slash-command surface area for Claude, Cursor, OpenCode, Kilo Code, and Windsurf. Leaving Codex out forces them to manually copy/paste OpenSpec guardrails into `~/.codex/prompts/*.md`, which drifts quickly and undermines the "single source of truth" promise of the CLI.
 - Codex commands live outside the repository (under the user's home directory), so shipping an automated configurator that both scaffolds the prompts and keeps them refreshed via `openspec update` eliminates error-prone manual steps and keeps OpenSpec instructions synchronized across assistants.

 ## What Changes
 - Add Codex to the `openspec init` tool picker with the same "already configured" detection we use for other editors, wiring an implementation that writes managed Markdown prompts directly to Codex's global directory (`~/.codex/prompts` or `$CODEX_HOME/prompts`) with OpenSpec marker blocks.
- Produce three Codex prompt files—`openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`—whose content mirrors the shared slash-command templates while adapting to Codex's numbered argument placeholders (e.g., `$1` for the change identifier or follow-up question text).
+- Produce three Codex prompt files—`openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`—whose content mirrors the shared slash-command templates while using YAML frontmatter (`description` and `argument-hint` fields) and `$ARGUMENTS` to capture all arguments as a single string (matching the GitHub Copilot pattern and official Codex specification).
 - Document Codex's global-only discovery and that OpenSpec writes prompts directly to `~/.codex/prompts` (or `$CODEX_HOME/prompts`).
- Teach `openspec update` to refresh existing Codex prompts in-place (and only when they already exist) in the global directory.
+- Teach `openspec update` to refresh existing Codex prompts in-place (and only when they already exist) in the global directory, updating both frontmatter and body.
 - Document Codex support alongside other slash-command integrations and add regression coverage that exercises init/update behaviour against a temporary global prompts directory via `CODEX_HOME`.

 ## Impact
@@ -0,0 +1,25 @@
+## Why
+- GitHub Copilot supports custom slash commands through markdown files in `.github/prompts/<name>.prompt.md`. Each file includes YAML frontmatter with a `description` label and uses `$ARGUMENTS` to capture user input. This format allows teams to expose curated workflows directly in Copilot's chat interface.
+- Teams already rely on OpenSpec to manage slash-command configurations for Claude Code, Cursor, OpenCode, Codex, Kilo Code, and Windsurf. Excluding GitHub Copilot forces developers to manually maintain OpenSpec prompts in `.github/prompts/`, which leads to drift and undermines OpenSpec's "single source of truth" promise.
+- GitHub Copilot discovers prompts from the repository's `.github/prompts/` directory, making it straightforward to version control and share across the team. Adding automated generation and refresh through `openspec init` and `openspec update` eliminates manual synchronization and keeps OpenSpec instructions consistent across all AI assistants.
+
+## What Changes
+- Add GitHub Copilot to the `openspec init` tool picker with "already configured" detection similar to other editors, wiring an implementation that writes managed Markdown prompt files to `.github/prompts/` with OpenSpec marker blocks.
+- Generate three GitHub Copilot prompt files—`openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`—whose content mirrors shared slash-command templates while conforming to Copilot's frontmatter and `$ARGUMENTS` placeholder convention.
+- Document GitHub Copilot's repository-based discovery and that OpenSpec writes prompts to `.github/prompts/` with managed blocks.
+- Teach `openspec update` to refresh existing GitHub Copilot prompts in-place (only when they already exist) in the repository's `.github/prompts/` directory.
+- Document GitHub Copilot support alongside other slash-command integrations and add test coverage that exercises init/update behavior for `.github/prompts/` files.
+
+## Impact
+- Specs: `cli-init`, `cli-update`
+- Code: `src/core/configurators/slash/github-copilot.ts` (new), `src/core/configurators/slash/registry.ts`, `src/core/templates/slash-command-templates.ts`, CLI tool summaries, docs
+- Tests: integration coverage for GitHub Copilot prompt scaffolding and refresh logic
+- Docs: README and CHANGELOG entries announcing GitHub Copilot slash-command support
+
+## Current Spec Reference
+- `specs/cli-init/spec.md`
+  - Requirements cover init UX, directory scaffolding, AI tool configuration, and existing slash-command support for Claude Code, Cursor, OpenCode, Codex, Kilo Code, and Windsurf.
+  - Our `## MODIFIED` delta in `changes/.../specs/cli-init/spec.md` will copy the full "Slash Command Configuration" requirement (header, description, and all scenarios) before appending the new GitHub Copilot scenario so archiving retains every prior scenario.
+- `specs/cli-update/spec.md`
+  - Requirements define update preconditions, template refresh behavior, and slash-command refresh logic for existing tools.
+  - The corresponding delta preserves the entire "Slash Command Updates" requirement while adding the GitHub Copilot refresh scenario, ensuring the archive workflow replaces the block without losing existing scenarios or the "Missing slash command file" guardrail.
@@ -0,0 +1,48 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
@@ -0,0 +1,48 @@
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Updating slash commands for GitHub Copilot
+- **WHEN** `.github/prompts/` contains `openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`
+- **THEN** refresh each file using shared templates while preserving the YAML frontmatter
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update
@@ -0,0 +1,30 @@
+## Implementation Tasks
+
+- [x] Create `src/core/configurators/slash/github-copilot.ts` implementing `SlashCommandConfigurator` base class
+  - Implement `getRelativePath()` to return `.github/prompts/openspec-{proposal,apply,archive}.prompt.md`
+  - Implement `getFrontmatter()` to generate YAML frontmatter with `description` field and include `$ARGUMENTS` placeholder
+  - Implement `generateAll()` to create `.github/prompts/` directory and write three prompt files with frontmatter, markers, and shared template bodies
+  - Implement `updateExisting()` to refresh only the managed block between markers while preserving frontmatter
+  - Set `toolId = "github-copilot"` and `isAvailable = true`
+
+- [x] Register GitHub Copilot configurator in `src/core/configurators/slash/registry.ts`
+  - Import `GitHubCopilotSlashCommandConfigurator`
+  - Add to `SLASH_COMMAND_CONFIGURATORS` array
+  - Update tool picker display name to "GitHub Copilot"
+
+- [x] Update `src/core/init.ts` to include GitHub Copilot in the AI tool selection prompt
+  - Add GitHub Copilot to the available tools list with detection for existing `.github/prompts/openspec-*.prompt.md` files
+  - Display "(already configured)" when prompt files exist
+
+- [x] Update `src/core/update.ts` to refresh GitHub Copilot prompts when they exist
+  - Call `updateExisting()` for GitHub Copilot configurator when `.github/prompts/` contains OpenSpec prompt files
+
+- [x] Add integration tests for GitHub Copilot slash command generation
+  - Test `generateAll()` creates three prompt files with correct structure (frontmatter + markers + body)
+  - Test `updateExisting()` preserves frontmatter and only updates managed blocks
+  - Test that missing prompt files are not created during update
+
+- [x] Update documentation
+  - Add GitHub Copilot to README slash-command support table
+  - Document `.github/prompts/` as the discovery location
+  - Add CHANGELOG entry for GitHub Copilot support
@@ -17,6 +17,25 @@ The command SHALL configure AI coding assistants with OpenSpec instructions usin

 ### Requirement: Slash Command Configuration
 The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
 #### Scenario: Generating slash commands for Kilo Code
 - **WHEN** the user selects Kilo Code during initialization
 - **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
@@ -0,0 +1,27 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update
@@ -0,0 +1,12 @@
+## Why
+The current `openspec init` command requires interactive prompts, preventing automation in CI/CD pipelines and scripted setups. Adding non-interactive options will enable programmatic initialization for automated workflows while maintaining the existing interactive experience as the default.
+
+## What Changes
+- Replace the multiple flag design with a single `--tools` option that accepts `all`, `none`, or a comma-separated list of tool IDs
+- Update InitCommand to bypass interactive prompts when `--tools` is supplied and apply single-flag validation rules
+- Document the non-interactive behavior via the CLI init spec delta (scenarios for `all`, `none`, list parsing, and invalid entries)
+- Generate CLI help text dynamically from `AI_TOOLS` so supported tools stay in sync
+
+## Impact
+- Affected specs: `specs/cli-init/spec.md`
+- Affected code: `src/cli/index.ts`, `src/core/init.ts`
@@ -0,0 +1,39 @@
+# Delta for CLI Init Specification
+
+## ADDED Requirements
+### Requirement: Non-Interactive Mode
+The command SHALL support non-interactive operation through command-line options for automation and CI/CD use cases.
+
+#### Scenario: Select all tools non-interactively
+- **WHEN** run with `--tools all`
+- **THEN** automatically select every available AI tool without prompting
+- **AND** proceed with initialization using the selected tools
+
+#### Scenario: Select specific tools non-interactively
+- **WHEN** run with `--tools claude,cursor`
+- **THEN** parse the comma-separated tool IDs and validate against available tools
+- **AND** proceed with initialization using only the specified valid tools
+
+#### Scenario: Skip tool configuration non-interactively
+- **WHEN** run with `--tools none`
+- **THEN** skip AI tool configuration entirely
+- **AND** only create the OpenSpec directory structure and template files
+
+#### Scenario: Invalid tool specification
+- **WHEN** run with `--tools` containing any IDs not present in the AI tool registry
+- **THEN** exit with code 1 and display available values (`all`, `none`, or the supported tool IDs)
+
+#### Scenario: Help text lists available tool IDs
+- **WHEN** displaying CLI help for `openspec init`
+- **THEN** show the `--tools` option description with the valid values derived from the AI tool registry
+
+## MODIFIED Requirements
+### Requirement: Interactive Mode
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
+
+#### Scenario: Displaying interactive menu
+- **WHEN** run in fresh or extend mode without non-interactive options
+- **THEN** present a looping select menu that lets users toggle tools with Enter and finish via a "Done" option
+- **AND** label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
+- **AND** change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
+- **AND** display inline instructions clarifying that Enter toggles a tool and selecting "Done" confirms the list
@@ -0,0 +1,17 @@
+## 1. CLI Option Registration
+- [x] 1.1 Replace the multiple flag design with a single `--tools <value>` option supporting `all|none|a,b,c` and keep strict argument validation.
+- [x] 1.2 Populate the `--tools` help text dynamically from the `AI_TOOLS` registry.
+
+## 2. InitCommand Modifications
+- [x] 2.1 Accept the single tools option in the InitCommand constructor and plumb it through existing flows.
+- [x] 2.2 Update tool selection logic to shortcut prompts for `all`, `none`, and explicit lists.
+- [x] 2.3 Fail fast with exit code 1 and a helpful message when the parsed list contains unsupported tool IDs.
+
+## 3. Specification Updates
+- [x] 3.1 Capture the non-interactive scenarios (`all`, `none`, list, invalid) in the change delta without modifying `specs/cli-init/spec.md` directly.
+- [x] 3.2 Document that CLI help reflects the available tool IDs managed by `AI_TOOLS`.
+
+## 4. Testing
+- [x] 4.1 Add unit coverage for parsing `--tools` values, including invalid entries.
+- [x] 4.2 Add integration coverage ensuring non-interactive runs generate the expected files and exit codes.
+- [x] 4.3 Verify the interactive flow remains unchanged when `--tools` is omitted.
@@ -16,6 +16,25 @@ The command SHALL configure AI coding assistants with OpenSpec instructions usin

 ### Requirement: Slash Command Configuration
 The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
 #### Scenario: Generating slash commands for Windsurf
 - **WHEN** the user selects Windsurf during initialization
 - **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
@@ -0,0 +1,27 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update
@@ -0,0 +1,17 @@
+## 1. CLI wiring
+- [x] 1.1 Add Windsurf to the selectable AI tools in `openspec init`, including "already configured" detection.
+- [x] 1.2 Register a `WindsurfSlashCommandConfigurator` that writes workflows to `.windsurf/workflows/` and ensures the directory exists.
+- [x] 1.3 Ensure `openspec update` pulls the Windsurf configurator when winds is selected and skips creation when files are absent.
+
+## 2. Workflow templates
+- [x] 2.1 Reuse the shared proposal/apply/archive bodies, adding Windsurf-specific headings/description before the OpenSpec markers.
+- [x] 2.2 Confirm generated Markdown (per file) stays comfortably under the 12k character ceiling noted in the Windsurf docs.
+
+## 3. Tests & safeguards
+- [x] 3.1 Extend init tests to assert creation of `.windsurf/workflows/openspec-*.md` when Windsurf is chosen.
+- [x] 3.2 Extend update tests to assert existing Windsurf workflows are refreshed and non-existent files are ignored.
+- [x] 3.3 Add regression coverage for marker preservation inside Windsurf workflow files.
+
+## 4. Documentation
+- [x] 4.1 Update README (and any user-facing docs) to list Windsurf under native slash/workflow integrations.
+- [x] 4.2 Call out Windsurf workflow support in release notes or CHANGELOG if applicable.
@@ -0,0 +1,12 @@
+## 1. Messaging enhancements
+- [x] 1.1 Inventory current validation failures and map each to the desired message improvements.
+- [x] 1.2 Implement structured error builders that include file paths, normalized header names, and example fixes.
+- [x] 1.3 Ensure `openspec validate --help` and troubleshooting docs mention the richer messages and debug tips.
+
+## 2. Tests
+- [x] 2.1 Add unit tests for representative errors (no deltas, missing requirement body, missing scenarios) asserting the new wording.
+- [x] 2.2 Add integration coverage verifying the Next steps footer reflects contextual guidance.
+
+## 3. Documentation
+- [x] 3.1 Update troubleshooting sections and CLI docs with sample output from the enhanced errors.
+- [x] 3.2 Note the change in CHANGELOG or release notes if applicable.
@@ -0,0 +1,11 @@
+## 1. Instruction redesign
+- [x] 1.1 Draft a quick-reference section that surfaces file templates and formatting rules at the top of `openspec/AGENTS.md`.
+- [x] 1.2 Reorganize the workflow narrative with inline examples and progressive disclosure for advanced topics.
+
+## 2. Templates and checklists
+- [x] 2.1 Add copy/paste templates for proposal, tasks, design, and spec delta files.
+- [x] 2.2 Insert a pre-validation checklist capturing common lint failures before running `openspec validate`.
+
+## 3. Documentation updates
+- [x] 3.1 Update supporting docs or README pointers so contributors find the redesigned instructions.
+- [x] 3.2 Confirm examples and references stay in sync with the new scaffold command guidance.
@@ -0,0 +1,14 @@
+## Why
+- Users frequently scroll to a tool and press Enter without toggling it, resulting in no configuration changes.
+- The current workflow deviates from common CLI expectations where Enter confirms the highlighted item.
+- Aligning behavior with user expectations reduces friction during onboarding.
+
+## What Changes
+- Update the init wizard so pressing Enter on a highlighted tool selects it before moving to the review step.
+- Adjust interactive instructions to clarify Enter selects the current tool and Space still toggles selections.
+- Refresh specs to capture the clarified behavior for the interactive menu.
+
+## Impact
+- Users who press Enter without toggling now configure the highlighted tool instead of exiting with no selections.
+- Spacebar multi-select support remains unchanged for power users.
+- Documentation better reflects how the wizard behaves.
@@ -0,0 +1,10 @@
+## MODIFIED Requirements
+### Requirement: Interactive Mode
+The command SHALL provide an interactive menu for AI tool selection with clear navigation instructions.
+#### Scenario: Displaying interactive menu
+- **WHEN** run in fresh or extend mode
+- **THEN** present a looping select menu that lets users toggle tools with Space and review selections with Enter
+- **AND** when Enter is pressed on a highlighted selectable tool that is not already selected, automatically add it to the selection before moving to review so the highlighted tool is configured
+- **AND** label already configured tools with "(already configured)" while keeping disabled options marked "coming soon"
+- **AND** change the prompt copy in extend mode to "Which AI tools would you like to add or refresh?"
+- **AND** display inline instructions clarifying that Space toggles tools and Enter selects the highlighted tool before reviewing selections
@@ -0,0 +1,8 @@
+## 1. Implementation
+- [x] Update the tool selection wizard to auto-select the highlighted tool when Enter is pressed without prior toggles.
+- [x] Refresh inline instructions copy so Enter behavior is clear.
+- [x] Adjust or add tests if needed to cover the new selection flow.
+
+## 2. Validation
+- [x] Run `pnpm run build`.
+- [x] Run `pnpm test` (or targeted suite) if applicable.
@@ -0,0 +1,11 @@
+## 1. Implementation
+- [x] 1.1 Refactor `openspec init` to always generate the root `AGENTS.md` stub (initial run and extend mode) via shared helper logic.
+- [x] 1.2 Rework the AI tool selection wizard to surface "Natively supported" vs "Other tools" groupings and make the stub non-optional.
+- [x] 1.3 Update CLI messaging, templates, and configurators so the new flow stays in sync across init and update commands.
+- [x] 1.4 Refresh unit/integration tests to cover the unconditional stub and the regrouped prompt layout.
+- [x] 1.5 Update documentation, README snippets, and CHANGELOG entries that mention the opt-in `AGENTS.md` experience.
+
+## 2. Validation
+- [x] 2.1 Run `pnpm test` targeting CLI init/update suites.
+- [x] 2.2 Execute `openspec validate update-cli-init-root-agents --strict`.
+- [x] 2.3 Perform a manual smoke test: run `openspec init` in a temp directory, confirm stub + grouped prompts, rerun in extend mode.
@@ -1,12 +1,12 @@
 ## 1. Release workflow automation
- [ ] 1.1 Add a `.github/workflows/release.yml` that runs on pushes to `main`, sets up pnpm + Node 20, installs dependencies, and invokes `changesets/action@v1` with `publish: pnpm run release`.
- [ ] 1.2 Configure the action with `createGithubReleases: true` and document required secrets (`NPM_TOKEN`, default `GITHUB_TOKEN`) plus recommended concurrency safeguards.
- [ ] 1.3 Validate the workflow using `act` or a dry-run push to confirm the action opens release PRs when changesets exist and publishes when the release PR merge lands.
+- [x] 1.1 Add a `.github/workflows/release.yml` that runs on pushes to `main`, sets up pnpm + Node 20, installs dependencies, and invokes `changesets/action@v1` with `publish: pnpm run release`.
+- [x] 1.2 Configure the action with `createGithubReleases: true` and document required secrets (`NPM_TOKEN`, default `GITHUB_TOKEN`) plus recommended concurrency safeguards.
+- [x] 1.3 Validate the workflow using `act` or a dry-run push to confirm the action opens release PRs when changesets exist and publishes when the release PR merge lands.

 ## 2. Package release script
- [ ] 2.1 Add a `release` script to `package.json` that builds the project and runs `changeset publish` using pnpm.
- [ ] 2.2 Ensure the script respects the existing `prepare`/`prepublishOnly` hooks to avoid duplicate builds and update documentation or scripts if adjustments are needed.
+- [x] 2.1 Add a `release` script to `package.json` that builds the project and runs `changeset publish` using pnpm.
+- [x] 2.2 Ensure the script respects the existing `prepare`/`prepublishOnly` hooks to avoid duplicate builds and update documentation or scripts if adjustments are needed.

 ## 3. Documentation and recovery steps
- [ ] 3.1 Update maintainer docs (e.g., README or `/docs`) with the end-to-end automated release flow, explicitly removing the manual tag/release steps that are no longer required and explaining how changesets drive the release PR.
- [ ] 3.2 Document fallback steps for failed publishes (rerun workflow, manual publish) and the hotfix path when a release must be cut without pending changesets.
+- [x] 3.1 Update maintainer docs (e.g., README or `/docs`) with the end-to-end automated release flow, explicitly removing the manual tag/release steps that are no longer required and explaining how changesets drive the release PR.
+- [x] 3.2 Document fallback steps for failed publishes (rerun workflow, manual publish) and the hotfix path when a release must be cut without pending changesets.
@@ -0,0 +1,17 @@
+# Add Archive Command Arguments
+
+## Why
+The `/openspec:archive` slash command currently lacks argument support, forcing the AI to infer which change to archive from conversation context or by listing all changes. This creates a safety risk where the wrong proposal could be archived if the context is ambiguous or multiple changes exist. Users expect to specify the change ID explicitly, matching the behavior of the CLI command `openspec archive <id>`.
+
+## What Changes
+- Add `$ARGUMENTS` placeholder to the OpenCode archive slash command frontmatter (matching existing pattern for proposal command)
+- Update archive command template steps to validate the specific change ID argument when provided
+- Note: Codex, GitHub Copilot, and Amazon Q already have `$ARGUMENTS` for archive; Claude/Cursor/Windsurf/Kilocode don't support arguments
+
+## Impact
+- Affected specs: `cli-update` (slash command generation logic)
+- Affected code:
+  - `src/core/configurators/slash/opencode.ts` (add `$ARGUMENTS` to archive frontmatter)
+  - `src/core/templates/slash-command-templates.ts` (archive template steps for argument validation)
+- Breaking: No - this is additive functionality that makes the command safer
+- User-facing: Yes - OpenCode users will be able to pass the change ID as an argument: `/openspec:archive <change-id>`
@@ -0,0 +1,32 @@
+# CLI Update Specification Delta
+
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+### Requirement: Archive Command Argument Support
+The archive slash command template SHALL support optional change ID arguments for tools that support `$ARGUMENTS` placeholder.
+
+#### Scenario: Archive command with change ID argument
+- **WHEN** a user invokes `/openspec:archive <change-id>` with a change ID
+- **THEN** the template SHALL instruct the AI to validate the provided change ID against `openspec list`
+- **AND** use the provided change ID for archiving if valid
+- **AND** fail fast if the provided change ID doesn't match an archivable change
+
+#### Scenario: Archive command without argument (backward compatibility)
+- **WHEN** a user invokes `/openspec:archive` without providing a change ID
+- **THEN** the template SHALL instruct the AI to identify the change ID from context or by running `openspec list`
+- **AND** proceed with the existing behavior (maintaining backward compatibility)
+
+#### Scenario: OpenCode archive template generation
+- **WHEN** generating the OpenCode archive slash command file
+- **THEN** include the `$ARGUMENTS` placeholder in the frontmatter
+- **AND** wrap it in a clear structure like `<ChangeId>\n  $ARGUMENTS\n</ChangeId>` to indicate the expected argument
+- **AND** include validation steps in the template body to check if the change ID is valid
@@ -0,0 +1,15 @@
+# Implementation Tasks
+
+## 1. Update OpenCode Configurator
+- [x] 1.1 Add `$ARGUMENTS` placeholder to OpenCode archive frontmatter (matching the proposal pattern)
+- [x] 1.2 Format it as `<ChangeId>\n  $ARGUMENTS\n</ChangeId>` or similar structure for clarity
+- [x] 1.3 Ensure `updateExisting` rewrites the archive frontmatter/body so `$ARGUMENTS` persists after `openspec update`
+
+## 2. Update Slash Command Templates
+- [x] 2.1 Modify archive steps to validate change ID argument when provided via `$ARGUMENTS`
+- [x] 2.2 Keep backward compatibility - allow inferring from context if no argument provided
+- [x] 2.3 Add step to validate the change ID exists using `openspec list` before archiving
+
+## 3. Update Documentation
+- [x] 3.1 Update AGENTS.md archive examples to show argument usage
+- [x] 3.2 Document that OpenCode now supports `/openspec:archive <change-id>`
@@ -0,0 +1,15 @@
+## Why
+Add support for Cline (VS Code extension) in OpenSpec to enable developers to use Cline's AI-powered coding capabilities for spec-driven development workflows.
+
+## What Changes
+- Add Cline slash command configurator for proposal, apply, and archive operations
+- Add Cline root CLINE.md configurator for project-level instructions
+- Add Cline template exports
+- Update tool and slash command registries to include Cline
+- Add comprehensive test coverage
+- **BREAKING**: None - this is additive functionality
+
+## Impact
+- Affected specs: cli-init (new tool option)
+- Affected code: src/core/configurators/slash/cline.ts, src/core/configurators/cline.ts, registry files
+- New files: .clinerules/openspec-*.md, CLINE.md
@@ -0,0 +1,97 @@
+## MODIFIED Requirements
+### Requirement: AI Tool Configuration Details
+
+The command SHALL properly configure selected AI tools with OpenSpec-specific instructions using a marker system.
+
+#### Scenario: Configuring Claude Code
+
+- **WHEN** Claude Code is selected
+- **THEN** create or update `CLAUDE.md` in the project root directory (not inside openspec/)
+- **AND** populate the managed block with a short stub that points teammates to `@/openspec/AGENTS.md`
+
+#### Scenario: Configuring CodeBuddy Code
+
+- **WHEN** CodeBuddy Code is selected
+- **THEN** create or update `CODEBUDDY.md` in the project root directory (not inside openspec/)
+- **AND** populate the managed block with a short stub that points teammates to `@/openspec/AGENTS.md`
+
+#### Scenario: Configuring Cline
+
+- **WHEN** Cline is selected
+- **THEN** create or update `CLINE.md` in the project root directory (not inside openspec/)
+- **AND** populate the managed block with a short stub that points teammates to `@/openspec/AGENTS.md`
+
+#### Scenario: Creating new CLAUDE.md
+
+- **WHEN** CLAUDE.md does not exist
+- **THEN** create new file with stub instructions wrapped in markers so the full workflow stays in `openspec/AGENTS.md`:
+```markdown
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+This project uses OpenSpec to manage AI assistant workflows.
+
+- Full guidance lives in '@/openspec/AGENTS.md'.
+- Keep this managed block so 'openspec update' can refresh the instructions.
+<!-- OPENSPEC:END -->
+```
+
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for CodeBuddy Code
+- **WHEN** the user selects CodeBuddy Code during initialization
+- **THEN** create `.codebuddy/commands/openspec/proposal.md`, `.codebuddy/commands/openspec/apply.md`, and `.codebuddy/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cline
+- **WHEN** the user selects Cline during initialization
+- **THEN** create `.clinerules/openspec-proposal.md`, `.clinerules/openspec-apply.md`, and `.clinerules/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
@@ -0,0 +1,19 @@
+## 1. Implementation
+- [x] 1.1 Create ClineSlashCommandConfigurator class in src/core/configurators/slash/cline.ts
+- [x] 1.2 Create ClineConfigurator class in src/core/configurators/cline.ts
+- [x] 1.3 Create cline-template.ts for template exports
+- [x] 1.4 Define file paths for Cline rules (.clinerules/)
+- [x] 1.5 Create Cline-specific frontmatter (Markdown heading format)
+- [x] 1.6 Register Cline in slash/registry.ts
+- [x] 1.7 Register Cline in configurators/registry.ts
+- [x] 1.8 Add Cline to AI_TOOLS in config.ts
+- [x] 1.9 Add getClineTemplate() to templates/index.ts
+- [x] 1.10 Update README with Cline documentation
+
+## 2. Testing
+- [x] 2.1 Add init tests for CLINE.md creation and updates
+- [x] 2.2 Add init tests for .clinerules/ file creation
+- [x] 2.3 Add update tests for CLINE.md updates
+- [x] 2.4 Add update tests for .clinerules/ file refreshes
+- [x] 2.5 Test integration with openspec init --tools cline
+- [x] 2.6 Verify all 225 tests pass
@@ -0,0 +1,13 @@
+## Why
+Add support for Crush AI assistant in OpenSpec to enable developers to use Crush's enhanced capabilities for spec-driven development workflows.
+
+## What Changes
+- Add Crush slash command configurator for proposal, apply, and archive operations
+- Add Crush-specific AGENTS.md configuration template 
+- Update tool registry to include Crush configurator
+- **BREAKING**: None - this is additive functionality
+
+## Impact
+- Affected specs: cli-init (new tool option)
+- Affected code: src/core/configurators/slash/crush.ts, registry.ts
+- New files: .crush/commands/openspec/ (proposal.md, apply.md, archive.md)
@@ -0,0 +1,67 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for CodeBuddy Code
+- **WHEN** the user selects CodeBuddy Code during initialization
+- **THEN** create `.codebuddy/commands/openspec/proposal.md`, `.codebuddy/commands/openspec/apply.md`, and `.codebuddy/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cline
+- **WHEN** the user selects Cline during initialization
+- **THEN** create `.clinerules/openspec-proposal.md`, `.clinerules/openspec-apply.md`, and `.clinerules/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Crush
+- **WHEN** the user selects Crush during initialization
+- **THEN** create `.crush/commands/openspec/proposal.md`, `.crush/commands/openspec/apply.md`, and `.crush/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
@@ -0,0 +1,7 @@
+## 1. Implementation
+- [x] 1.1 Create CrushSlashCommandConfigurator class in src/core/configurators/slash/crush.ts
+- [x] 1.2 Define file paths for Crush commands (.crush/commands/openspec/)
+- [x] 1.3 Create Crush-specific frontmatter for proposal, apply, archive commands
+- [x] 1.4 Register Crush configurator in slash/registry.ts
+- [x] 1.5 Add Crush to available tools in cli-init command
+- [x] 1.6 Test integration with openspec init --tool crush
@@ -0,0 +1,12 @@
+## Why
+Factory's Droid CLI recently shipped custom slash commands that mirror other native assistant integrations. Teams using OpenSpec want the same managed workflows they already get for Cursor, Windsurf, and others so init/update can provision and refresh Factory commands without manual setup.
+
+## What Changes
+- Extend the native tool registry so Factory/Droid appears alongside other slash-command integrations during `openspec init`.
+- Add shared templates that generate the three Factory custom commands (proposal, apply, archive) and wrap them in OpenSpec markers for safe refreshes.
+- Update the init and update command flows so they create or refresh Factory command files when the tool is selected or already present.
+- Refresh CLI specs to document the Factory support and align validation expectations.
+
+## Impact
+- Affected specs: `specs/cli-init`, `specs/cli-update`
+- Affected code (expected): tool registry, slash-command template manager, init/update command helpers, documentation snippets
@@ -0,0 +1,54 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Configuration
+The init command SHALL generate slash command files for supported editors using shared templates.
+
+#### Scenario: Generating slash commands for Claude Code
+- **WHEN** the user selects Claude Code during initialization
+- **THEN** create `.claude/commands/openspec/proposal.md`, `.claude/commands/openspec/apply.md`, and `.claude/commands/openspec/archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Cursor
+- **WHEN** the user selects Cursor during initialization
+- **THEN** create `.cursor/commands/openspec-proposal.md`, `.cursor/commands/openspec-apply.md`, and `.cursor/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Factory Droid
+- **WHEN** the user selects Factory Droid during initialization
+- **THEN** create `.factory/commands/openspec-proposal.md`, `.factory/commands/openspec-apply.md`, and `.factory/commands/openspec-archive.md`
+- **AND** populate each file from shared templates that include Factory-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** include the `$ARGUMENTS` placeholder in the template body so droid receives any user-supplied input
+- **AND** wrap the generated content in OpenSpec managed markers so `openspec update` can safely refresh the commands
+
+#### Scenario: Generating slash commands for OpenCode
+- **WHEN** the user selects OpenCode during initialization
+- **THEN** create `.opencode/commands/openspec-proposal.md`, `.opencode/commands/openspec-apply.md`, and `.opencode/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Windsurf
+- **WHEN** the user selects Windsurf during initialization
+- **THEN** create `.windsurf/workflows/openspec-proposal.md`, `.windsurf/workflows/openspec-apply.md`, and `.windsurf/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Kilo Code
+- **WHEN** the user selects Kilo Code during initialization
+- **THEN** create `.kilocode/workflows/openspec-proposal.md`, `.kilocode/workflows/openspec-apply.md`, and `.kilocode/workflows/openspec-archive.md`
+- **AND** populate each file from shared templates (wrapped in OpenSpec markers) so workflow text matches other tools
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for Codex
+- **WHEN** the user selects Codex during initialization
+- **THEN** create global prompt files at `~/.codex/prompts/openspec-proposal.md`, `~/.codex/prompts/openspec-apply.md`, and `~/.codex/prompts/openspec-archive.md` (or under `$CODEX_HOME/prompts` if set)
+- **AND** populate each file from shared templates that map the first numbered placeholder (`$1`) to the primary user input (e.g., change identifier or question text)
+- **AND** wrap the generated content in OpenSpec markers so `openspec update` can refresh the prompts without touching surrounding custom notes
+
+#### Scenario: Generating slash commands for GitHub Copilot
+- **WHEN** the user selects GitHub Copilot during initialization
+- **THEN** create `.github/prompts/openspec-proposal.prompt.md`, `.github/prompts/openspec-apply.prompt.md`, and `.github/prompts/openspec-archive.prompt.md`
+- **AND** populate each file with YAML frontmatter containing a `description` field that summarizes the workflow stage
+- **AND** include `$ARGUMENTS` placeholder to capture user input
+- **AND** wrap the shared template body with OpenSpec markers so `openspec update` can refresh the content
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
@@ -0,0 +1,54 @@
+## MODIFIED Requirements
+### Requirement: Slash Command Updates
+The update command SHALL refresh existing slash command files for configured tools without creating new ones.
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Factory Droid
+- **WHEN** `.factory/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using the shared Factory templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** ensure the template body retains the `$ARGUMENTS` placeholder so user input keeps flowing into droid
+- **AND** update only the content inside the OpenSpec managed markers, leaving any unmanaged notes untouched
+- **AND** skip creating missing files during update
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/command/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** `.windsurf/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Updating slash commands for GitHub Copilot
+- **WHEN** `.github/prompts/` contains `openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`
+- **THEN** refresh each file using shared templates while preserving the YAML frontmatter
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update
@@ -0,0 +1,11 @@
+## 1. Factory tool registration
+- [x] 1.1 Add Factory/Droid metadata to the native tool registry used by init/update (ID, display name, command paths, availability flags).
+- [x] 1.2 Surface Factory in interactive prompts and non-interactive `--tools` parsing alongside existing slash-command integrations.
+
+## 2. Slash command templates
+- [x] 2.1 Create shared templates for Factory's `openspec-proposal`, `openspec-apply`, and `openspec-archive` custom commands following Factory's CLI format.
+- [x] 2.2 Wire the templates into init/update so generation happens on create and refresh respects OpenSpec markers.
+
+## 3. Verification
+- [x] 3.1 Update or add automated coverage that ensures Factory command files are scaffolded and refreshed correctly.
+- [x] 3.2 Document the new option in any user-facing copy (help text, README snippets) if required by spec.
@@ -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
@@ -1,12 +0,0 @@
-## 1. Messaging enhancements
- [ ] 1.1 Inventory current validation failures and map each to the desired message improvements.
- [ ] 1.2 Implement structured error builders that include file paths, normalized header names, and example fixes.
- [ ] 1.3 Ensure `openspec validate --help` and troubleshooting docs mention the richer messages and debug tips.
-
-## 2. Tests
- [ ] 2.1 Add unit tests for representative errors (no deltas, missing requirement body, missing scenarios) asserting the new wording.
- [ ] 2.2 Add integration coverage verifying the Next steps footer reflects contextual guidance.
-
-## 3. Documentation
- [ ] 3.1 Update troubleshooting sections and CLI docs with sample output from the enhanced errors.
- [ ] 3.2 Note the change in CHANGELOG or release notes if applicable.
--- a/Show More
+++ b/Show More