docs: add multi-language output guide

Document how to configure OpenSpec to generate artifacts in languages
other than English using the existing context field in config.yaml.

Includes examples for Portuguese, Spanish, Chinese, Japanese, French,
and German, plus tips for handling technical terminology.

.actrc

@@ -0,0 +1 @@
+-P ubuntu-latest=catthehacker/ubuntu:act-latest

.changeset/README.md

@@ -1,6 +1,95 @@
-This directory is managed by Changesets.
+# Changesets
 
-- Add a changeset locally with `pnpm changeset`.
-- The CI "Release (prepare)" workflow opens/updates a Version Packages PR.
-- Publishing happens from a GitHub Release via the "Publish to npm" workflow.
+This directory is managed by [Changesets](https://github.com/changesets/changesets).
 
+## Quick Start
+
+```bash
+pnpm changeset
+```
+
+Follow the prompts to select version bump type and describe your changes.
+
+## Workflow
+
+1. **Add a changeset** — Run `pnpm changeset` locally before or after your PR
+2. **Version PR** — CI opens/updates a "Version Packages" PR when changesets merge to main
+3. **Release** — Merging the Version PR triggers npm publish and GitHub Release
+
+> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI.
+
+## Template
+
+Use this structure for your changeset content:
+
+```markdown
+---
+"@fission-ai/openspec": patch
+---
+
+### New Features
+
+- **Feature name** — What users can now do
+
+### Bug Fixes
+
+- Fixed issue where X happened when Y
+
+### Breaking Changes
+
+- `oldMethod()` has been removed, use `newMethod()` instead
+
+### Deprecations
+
+- `legacyOption` is deprecated and will be removed in v2.0
+
+### Other
+
+- Internal refactoring of X for better performance
+```
+
+Include only the sections relevant to your change.
+
+## Version Bump Guide
+
+| Type | When to use | Example |
+|------|-------------|---------|
+| `patch` | Bug fixes, small improvements | Fixed crash when config missing |
+| `minor` | New features, non-breaking additions | Added `--verbose` flag |
+| `major` | Breaking changes, removed features | Renamed `init` to `setup` |
+
+## When to Create a Changeset
+
+**Create one for:**
+- New features or commands
+- Bug fixes that affect users
+- Breaking changes or deprecations
+- Performance improvements users would notice
+
+**Skip for:**
+- Documentation-only changes
+- Test additions/fixes
+- Internal refactoring with no user impact
+- CI/tooling changes
+
+## Writing Good Descriptions
+
+**Do:** Write for users, not developers
+```markdown
+- **Shell completions** — Tab completion now available for Bash, Fish, and PowerShell
+```
+
+**Don't:** Write implementation details
+```markdown
+- Added ShellCompletionGenerator class with Bash/Fish/PowerShell subclasses
+```
+
+**Do:** Explain the impact
+```markdown
+- Fixed config loading to respect `XDG_CONFIG_HOME` on Linux
+```
+
+**Don't:** Just reference the fix
+```markdown
+- Fixed #123
+```

.changeset/config.json

@@ -1,6 +1,9 @@
 {
   "$schema": "https://unpkg.com/@changesets/config/schema.json",
-  "changelog": "@changesets/cli/changelog",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "Fission-AI/OpenSpec" }
+  ],
   "commit": false,
   "fixed": [],
   "linked": [],

.github/workflows/README.md

@@ -0,0 +1,20 @@
+# Github Workflows
+
+## Testing CI Locally
+
+Test GitHub Actions workflows locally using [act](https://nektosact.com/):
+
+```bash
+# Test all PR checks
+act pull_request
+
+# Test specific job
+act pull_request -j nix-flake-validate
+
+# Dry run to see what would execute
+act pull_request --dryrun
+```
+
+The `.actrc` file configures act to use the appropriate Docker image.
+
+

.github/workflows/ci.yml

@@ -15,6 +15,29 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  # Detect which files changed to enable path-based filtering
+  changes:
+    name: Detect changes
+    runs-on: ubuntu-latest
+    outputs:
+      nix: ${{ steps.filter.outputs.nix }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Check for Nix-related changes
+        uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            nix:
+              - 'flake.nix'
+              - 'flake.lock'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'scripts/update-flake.sh'
+              - '.github/workflows/ci.yml'
+
   test_pr:
     name: Test
     runs-on: ubuntu-latest
@@ -156,6 +179,66 @@ jobs:
             exit 1
           fi
 
+  nix-flake-validate:
+    name: Nix Flake Validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    needs: changes
+    if: needs.changes.outputs.nix == 'true'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@v13
+
+      - name: Setup Nix cache
+        uses: DeterminateSystems/magic-nix-cache-action@v8
+
+      - name: Build with Nix
+        run: nix build
+
+      - name: Verify build output
+        run: |
+          if [ ! -e "result" ]; then
+            echo "Error: Nix build output 'result' symlink not found"
+            exit 1
+          fi
+          if [ ! -f "result/bin/openspec" ]; then
+            echo "Error: openspec binary not found in build output"
+            exit 1
+          fi
+          echo "✅ Build output verified"
+
+      - name: Test binary execution
+        run: |
+          VERSION=$(nix run . -- --version)
+          echo "OpenSpec version: $VERSION"
+          if [ -z "$VERSION" ]; then
+            echo "Error: Version command returned empty output"
+            exit 1
+          fi
+          echo "✅ Binary execution successful"
+
+      - name: Validate update script
+        run: |
+          echo "Testing update-flake.sh script..."
+          bash scripts/update-flake.sh
+          echo "✅ Update script executed successfully"
+
+      - name: Check flake.nix modifications
+        run: |
+          if git diff --quiet flake.nix; then
+            echo "⚠️  Warning: flake.nix was not modified by update script"
+          else
+            echo "✅ flake.nix was updated by script"
+            git diff flake.nix
+          fi
+
+      - name: Restore flake.nix
+        if: always()
+        run: git checkout -- flake.nix || true
+
   validate-changesets:
     name: Validate Changesets
     runs-on: ubuntu-latest
@@ -191,7 +274,7 @@ jobs:
   required-checks-pr:
     name: All checks passed
     runs-on: ubuntu-latest
-    needs: [test_pr, lint]
+    needs: [test_pr, lint, nix-flake-validate]
     if: always() && github.event_name == 'pull_request'
     steps:
       - name: Verify all checks passed
@@ -204,12 +287,20 @@ jobs:
             echo "Lint job failed"
             exit 1
           fi
+          # Nix validation may be skipped if no Nix-related files changed
+          if [[ "${{ needs.nix-flake-validate.result }}" != "success" && "${{ needs.nix-flake-validate.result }}" != "skipped" ]]; then
+            echo "Nix flake validation job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.nix-flake-validate.result }}" == "skipped" ]]; then
+            echo "Nix flake validation skipped (no Nix-related changes)"
+          fi
           echo "All required checks passed!"
 
   required-checks-main:
     name: All checks passed
     runs-on: ubuntu-latest
-    needs: [test_matrix, lint]
+    needs: [test_matrix, lint, nix-flake-validate]
     if: always() && github.event_name != 'pull_request'
     steps:
       - name: Verify all checks passed
@@ -222,4 +313,12 @@ jobs:
             echo "Lint job failed"
             exit 1
           fi
+          # Nix validation may be skipped if no Nix-related files changed
+          if [[ "${{ needs.nix-flake-validate.result }}" != "success" && "${{ needs.nix-flake-validate.result }}" != "skipped" ]]; then
+            echo "Nix flake validation job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.nix-flake-validate.result }}" == "skipped" ]]; then
+            echo "Nix flake validation skipped (no Nix-related changes)"
+          fi
           echo "All required checks passed!"

.github/workflows/polish-release-notes.yml

@@ -0,0 +1,146 @@
+name: Polish Release Notes
+
+# Uses Claude to transform raw changelog into polished release notes.
+# Triggered automatically by release-prepare after publishing, or manually.
+on:
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'Release tag to polish (e.g., v0.18.0)'
+        required: true
+        type: string
+
+env:
+  TAG_NAME: ${{ inputs.tag_name }}
+
+permissions:
+  contents: write
+
+jobs:
+  polish:
+    # Only run on the main repo, not forks
+    if: github.repository == 'Fission-AI/OpenSpec'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get current release body
+        id: get-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release view "${{ env.TAG_NAME }}" --json body -q '.body' > current-notes.md
+          echo "Fetched release notes for ${{ env.TAG_NAME }}"
+
+      - name: Transform release notes with Claude
+        uses: anthropics/claude-code-action@v1
+        id: claude
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          claude_args: "--allowedTools Write,Read"
+          prompt: |
+            Transform the changelog in `current-notes.md` into release notes for OpenSpec ${{ env.TAG_NAME }}.
+
+            ## Voice
+
+            OpenSpec is a developer tool. Write like you're talking to a peer:
+            - Direct and practical, not marketing copy
+            - Focus on what changed and why it matters
+            - Skip the hype, keep it real
+
+            ## Output
+
+            Create two files:
+
+            ### 1. `release-title.txt`
+
+            A short title in this format:
+            ```
+            ${{ env.TAG_NAME }} - [1-4 words describing the release]
+            ```
+
+            Examples:
+            - `v0.18.0 - OPSX Experimental Workflow`
+            - `v0.16.0 - Antigravity, iFlow Support`
+            - `v0.15.0 - Gemini CLI, RooCode`
+
+            Rules for title:
+            - Lead with the most notable addition
+            - 1-4 words after the dash, no fluff
+            - If multiple features, comma-separate the top 2
+            - For bugfix-only releases, use something like `v0.17.2 - Pre-commit Hook Fix`
+
+            ### 2. `polished-notes.md`
+
+            ```markdown
+            ## What's New in ${{ env.TAG_NAME }}
+
+            [One sentence: what's the theme of this release?]
+
+            ### New
+
+            - **Feature name** - What it does and why you'd use it
+
+            ### Improved
+
+            - **Area** - What got better
+
+            ### Fixed
+
+            - What was broken, now works
+            ```
+
+            Omit empty sections.
+
+            ## Rules
+
+            1. Write for developers using OpenSpec with AI coding assistants
+            2. Remove commit hashes (like `eb152eb:`), PR numbers, and changesets wrappers (`### Minor Changes`)
+            3. Lead with what users can do, not implementation details
+            4. One to two sentences per item, max
+            5. Use **bold** for feature/area names
+            6. Skip internal changes (CI, refactors, tests) unless they affect users
+            7. If the input is already well-formatted, just clean up structure and remove noise
+
+            ## Example
+
+            Before:
+            ```
+            ### Minor Changes
+            - 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system
+              **New Commands:**
+              - `/opsx:ff` - Fast-forward through artifact creation
+            ```
+
+            After (polished-notes.md):
+            ```
+            ### New
+
+            - **Fast-forward mode** - Generate all planning artifacts at once with `/opsx:ff`. Useful when you already know what you're building.
+            ```
+
+            After (release-title.txt):
+            ```
+            v0.18.0 - OPSX Experimental Workflow
+            ```
+
+            Write both files. No other output.
+
+      - name: Update release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ env.TAG_NAME }}"
+
+          if [ -f "polished-notes.md" ] && [ -f "release-title.txt" ]; then
+            TITLE=$(cat release-title.txt)
+            gh release edit "$TAG" --title "$TITLE" --notes-file polished-notes.md
+            echo "Updated: $TITLE"
+          elif [ -f "polished-notes.md" ]; then
+            gh release edit "$TAG" --notes-file polished-notes.md
+            echo "Updated notes (title unchanged)"
+          else
+            echo "No changes generated, keeping original"
+          fi

.github/workflows/release-prepare.yml

@@ -18,9 +18,20 @@ jobs:
     if: github.repository == 'Fission-AI/OpenSpec'
     runs-on: ubuntu-latest
     steps:
+      # Generate GitHub App token first - used for checkout and changesets
+      # This allows git operations to trigger CI workflows on the version PR
+      # (GITHUB_TOKEN cannot trigger workflows by design)
+      - name: Generate GitHub App Token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
 
       - uses: pnpm/action-setup@v4
         with:
@@ -36,6 +47,7 @@ jobs:
 
       # Opens/updates the Version Packages PR; publishes when the Version PR merges
       - name: Create/Update Version PR
+        id: changesets
         uses: changesets/action@v1
         with:
           title: 'chore(release): version packages'
@@ -44,5 +56,16 @@ jobs:
           # so package.json already contains the bumped version.
           publish: pnpm run release:ci
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           # npm authentication handled via OIDC trusted publishing (no token needed)
+
+      # Trigger release notes polishing after a release is published
+      - name: Polish release notes
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          # Get version from package.json (just bumped by changesets)
+          TAG="v$(jq -r .version package.json)"
+          echo "Triggering polish workflow for $TAG"
+          gh workflow run polish-release-notes.yml -f tag_name="$TAG"

.gitignore

@@ -148,3 +148,4 @@ CLAUDE.md
 
 # Pnpm
 .pnpm-store/
+result

CHANGELOG.md

@@ -1,5 +1,110 @@
 # @fission-ai/openspec
 
+## 0.22.0
+
+### Minor Changes
+
+- [#530](https://github.com/Fission-AI/OpenSpec/pull/530) [`33466b1`](https://github.com/Fission-AI/OpenSpec/commit/33466b1e2a6798bdd6d0e19149173585b0612e6f) Thanks [@TabishB](https://github.com/TabishB)! - Add project-level configuration, project-local schemas, and schema management commands
+
+  **New Features**
+
+  - **Project-level configuration** — Configure OpenSpec behavior per-project via `openspec/config.yaml`, including custom rules injection, context files, and schema resolution settings
+  - **Project-local schemas** — Define custom artifact schemas within your project's `openspec/schemas/` directory for project-specific workflows
+  - **Schema management commands** — New `openspec schema` commands (`list`, `show`, `export`, `validate`) for inspecting and managing artifact schemas (experimental)
+
+  **Bug Fixes**
+
+  - Fixed config loading to handle null `rules` field in project configuration
+
+## 0.21.0
+
+### Minor Changes
+
+- [#516](https://github.com/Fission-AI/OpenSpec/pull/516) [`b5a8847`](https://github.com/Fission-AI/OpenSpec/commit/b5a884748be6156a7bb140b4941cfec4f20a9fc8) Thanks [@TabishB](https://github.com/TabishB)! - Add feedback command and Nix flake support
+
+  **New Features**
+
+  - **Feedback command** — Submit feedback directly from the CLI with `openspec feedback`, which creates GitHub Issues with automatic metadata inclusion and graceful fallback for manual submission
+  - **Nix flake support** — Install and develop openspec using Nix with the new `flake.nix`, including automated flake maintenance and CI validation
+
+  **Bug Fixes**
+
+  - **Explore mode guardrails** — Explore mode now explicitly prevents implementation, keeping the focus on thinking and discovery while still allowing artifact creation
+
+  **Other**
+
+  - Improved change inference in `opsx apply` — automatically detects the target change from conversation context or prompts when ambiguous
+  - Streamlined archive sync assessment with clearer delta spec location guidance
+
+## 0.20.0
+
+### Minor Changes
+
+- [#502](https://github.com/Fission-AI/OpenSpec/pull/502) [`9db74aa`](https://github.com/Fission-AI/OpenSpec/commit/9db74aa5ac6547efadaed795217cfa17444f2004) Thanks [@TabishB](https://github.com/TabishB)! - Add `/opsx:verify` command and fix vitest process storms
+
+  **New Features**
+
+  - **`/opsx:verify` command** — Validate that change implementations match their specifications
+
+  **Bug Fixes**
+
+  - Fixed vitest process storms by capping worker parallelism
+  - Fixed agent workflows to use non-interactive mode for validation commands
+  - Fixed PowerShell completions generator to remove trailing commas
+
+## 0.19.0
+
+### Minor Changes
+
+- eb152eb: Add Continue IDE support, shell completions, and `/opsx:explore` command
+
+  **New Features**
+
+  - **Continue IDE support** – OpenSpec now generates slash commands for [Continue](https://continue.dev/), expanding editor integration options alongside Cursor, Windsurf, Claude Code, and others
+  - **Shell completions for Bash, Fish, and PowerShell** – Run `openspec completion install` to set up tab completion in your preferred shell
+  - **`/opsx:explore` command** – A new thinking partner mode for exploring ideas and investigating problems before committing to changes
+  - **Codebuddy slash command improvements** – Updated frontmatter format for better compatibility
+
+  **Bug Fixes**
+
+  - Shell completions now correctly offer parent-level flags (like `--help`) when a command has subcommands
+  - Fixed Windows compatibility issues in tests
+
+  **Other**
+
+  - Added optional anonymous usage statistics to help understand how OpenSpec is used. This is **opt-out** by default – set `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable. Only command names and version are collected; no arguments, file paths, or content. Automatically disabled in CI environments.
+
+## 0.18.0
+
+### Minor Changes
+
+- 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system
+
+  **New Commands:**
+
+  - `/opsx:ff` - Fast-forward through artifact creation, generating all needed artifacts in one go
+  - `/opsx:sync` - Sync delta specs from a change to main specs
+  - `/opsx:archive` - Archive completed changes with smart sync check
+
+  **Artifact Workflow Enhancements:**
+
+  - Schema-aware apply instructions with inline guidance and XML output
+  - Agent schema selection for experimental artifact workflow
+  - Per-change schema metadata via `.openspec.yaml` files
+  - Agent Skills for experimental artifact workflow
+  - Instruction loader for template loading and change context
+  - Restructured schemas as directories with templates
+
+  **Improvements:**
+
+  - Enhanced list command with last modified timestamps and sorting
+  - Change creation utilities for better workflow support
+
+  **Fixes:**
+
+  - Normalize paths for cross-platform glob compatibility
+  - Allow REMOVED requirements when creating new spec files
+
 ## 0.17.2
 
 ### Patch Changes
@@ -20,13 +125,15 @@
 
 ### Minor Changes
 
-- 2e71835: ### New Features
+- 2e71835: Add `openspec config` command and Oh-my-zsh completions
+
+  **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
+  **Bug Fixes**
 
   - Fix hang in pre-commit hooks by using dynamic imports
   - Respect XDG_CONFIG_HOME environment variable on all platforms
@@ -34,7 +141,7 @@
   - Align cli-completion spec with implementation
   - Remove hardcoded agent field from slash commands
 
-  ### Documentation
+  **Documentation**
 
   - Alphabetize AI tools list in README and make it collapsible
 
@@ -55,6 +162,8 @@
 
 ### Minor Changes
 
+- Add Continue slash command support so `openspec init` can generate `.continue/prompts/openspec-*.prompt` files with MARKDOWN frontmatter and `$ARGUMENTS` placeholder, and refresh them on `openspec update`.
+
 - 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

MAINTAINERS.md

@@ -0,0 +1,17 @@
+# Maintainers
+
+People who maintain and guide OpenSpec.
+
+## Core Maintainers
+
+| Name | GitHub | Role |
+|------|--------|------|
+| Tabish Bidiwale | [@TabishB](https://github.com/TabishB) | Lead maintainer |
+
+## Advisors
+
+Advisors help shape technical direction and provide guidance to the project.
+
+| Name | GitHub | Focus |
+|------|--------|-------|
+| Hari Krishnan | [@harikrishnan83](https://github.com/harikrishnan83) | Technical direction |

README.md

@@ -26,6 +26,10 @@
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
+<p align="center">
+  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
+</p>
+
 # OpenSpec
 
 OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
@@ -99,6 +103,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **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) |
+| **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.continue/prompts/`) |
 | **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` |
@@ -135,6 +140,8 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`.
 
 #### Step 1: Install the CLI globally
 
+**Option A: Using npm**
+
 ```bash
 npm install -g @fission-ai/openspec@latest
 ```
@@ -144,6 +151,39 @@ Verify installation:
 openspec --version
 ```
 
+**Option B: Using Nix (NixOS and Nix package manager)**
+
+Run OpenSpec directly without installation:
+```bash
+nix run github:Fission-AI/OpenSpec -- init
+```
+
+Or install to your profile:
+```bash
+nix profile install github:Fission-AI/OpenSpec
+```
+
+Or add to your development environment in `flake.nix`:
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    openspec.url = "github:Fission-AI/OpenSpec";
+  };
+
+  outputs = { nixpkgs, openspec, ... }: {
+    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
+      buildInputs = [ openspec.packages.x86_64-linux.default ];
+    };
+  };
+}
+```
+
+Verify installation:
+```bash
+openspec --version
+```
+
 #### Step 2: Initialize OpenSpec in your project
 
 Navigate to your project directory:
@@ -368,6 +408,53 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 2. **Refresh agent instructions**
    - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
 
+## Experimental Features
+
+<details>
+<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
+
+**Why this exists:**
+- Standard workflow is locked down — you can't tweak instructions or customize
+- When AI output is bad, you can't improve the prompts yourself
+- Same workflow for everyone, no way to match how your team works
+
+**What's different:**
+- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
+- **Granular** — each artifact has its own instructions, test and tweak individually
+- **Customizable** — define your own workflows, artifacts, and dependencies
+- **Fluid** — no phase gates, update any artifact anytime
+
+```
+You can always go back:
+
+  proposal ──→ specs ──→ design ──→ tasks ──→ implement
+     ▲           ▲          ▲                    │
+     └───────────┴──────────┴────────────────────┘
+```
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
+| `/opsx:archive` | Archive when done |
+
+**Setup:** `openspec artifact-experimental-setup`
+
+[Full documentation →](docs/experimental-workflow.md)
+
+</details>
+
+<details>
+<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>
+
+We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
+
+**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+
+</details>
+
 ## Contributing
 
 - Install dependencies: `pnpm install`
@@ -376,6 +463,13 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 - Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
 - Conventional commits (one-line): `type(scope): subject`
 
+<details>
+<summary><strong>Maintainers & Advisors</strong></summary>
+
+See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and advisors who help guide the project.
+
+</details>
+
 ## License
 
 MIT

docs/experimental-release-plan.md

@@ -0,0 +1,926 @@
+# OpenSpec Experimental Release Plan
+
+This document outlines the plan to release the experimental artifact workflow system for user testing.
+
+## Overview
+
+The goal is to allow users to test the new artifact-driven workflow system alongside the existing OpenSpec commands. This experimental system (`opsx`) provides a more granular, step-by-step approach to creating change artifacts.
+
+## Three Workflow Modes
+
+### 1. Old Workflow (Current Production)
+- **Commands**: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
+- **Behavior**: Hardcoded slash commands that generate all artifacts in one command
+- **Status**: Production, unchanged
+
+### 2. New Artifact System - Batch Mode (Future)
+- **Commands**: Refactored `/openspec:proposal` using schemas
+- **Behavior**: Schema-driven but generates all artifacts at once (like legacy)
+- **Status**: Not in scope for this experimental release
+- **Note**: This is a future refactor to unify the old system with schemas
+
+### 3. New Artifact System - Granular Mode (Experimental)
+- **Commands**: `/opsx:new`, `/opsx:continue`
+- **Behavior**: One artifact at a time, dependency-driven, iterative
+- **Status**: Target for this experimental release
+
+---
+
+## Work Items
+
+### 1. Rename AWF to OPSX
+
+**Current State:**
+- Commands: `/awf:start`, `/awf:continue`
+- Files: `.claude/commands/awf/start.md`, `.claude/commands/awf/continue.md`
+
+**Target State:**
+- Commands: `/opsx:new`, `/opsx:continue`
+- Files: `.claude/commands/opsx/new.md`, `.claude/commands/opsx/continue.md`
+
+**Tasks:**
+- [x] Create `.claude/commands/opsx/` directory
+- [x] Rename `start.md` → `new.md` and update content
+- [x] Copy `continue.md` with updated references
+- [x] Update all references from "awf" to "opsx" in command content
+- [x] Update frontmatter (name, description) to use "opsx" naming
+- [x] Remove `.claude/commands/awf/` directory
+
+**CLI Commands:**
+The underlying CLI commands (`openspec status`, `openspec instructions`, etc.) remain unchanged. Only the slash command names change.
+
+---
+
+### 2. Remove WF Skill Files
+
+**Current State:**
+- `.claude/commands/wf/start.md` - References non-existent `openspec wf` commands
+- `.claude/commands/wf/continue.md` - References non-existent `openspec wf` commands
+
+**Target State:**
+- Directory and files removed
+
+**Tasks:**
+- [x] Delete `.claude/commands/wf/start.md`
+- [x] Delete `.claude/commands/wf/continue.md`
+- [x] Delete `.claude/commands/wf/` directory
+
+---
+
+### 3. Add Agent Skills for Experimental Workflow
+
+**Purpose:**
+Generate experimental workflow skills using the [Agent Skills](https://agentskills.io/specification) open standard.
+
+**Why Skills Instead of Slash Commands:**
+- **Cross-editor compatibility**: Skills work in Claude Code, Cursor, Windsurf, and other compatible editors automatically
+- **Simpler implementation**: Single directory (`.claude/skills/`) instead of 18+ editor-specific configurators
+- **Standard format**: Open standard with simple YAML frontmatter + markdown
+- **User invocation**: Users explicitly invoke skills when they want to use them
+
+**Behavior:**
+1. Create `.claude/skills/` directory if it doesn't exist
+2. Generate two skills using the Agent Skills specification:
+   - `openspec-new-change/SKILL.md` - Start a new change with artifact workflow
+   - `openspec-continue-change/SKILL.md` - Continue working on a change (create next artifact)
+3. Skills are added **alongside** existing `/openspec:*` commands (not replacing)
+
+**Supported Editors:**
+- Claude Code (native support)
+- Cursor (native support via Settings → Rules → Import Settings)
+- Windsurf (imports `.claude` configs)
+- Cline, Codex, and other Agent Skills-compatible editors
+
+**Tasks:**
+- [x] Create skill template content for `openspec-new-change` (based on current opsx:new)
+- [x] Create skill template content for `openspec-continue-change` (based on current opsx:continue)
+- [x] Add temporary `artifact-experimental-setup` command to CLI
+- [x] Implement skill file generation (YAML frontmatter + markdown body)
+- [x] Add success message with usage instructions
+
+**Note:** The `artifact-experimental-setup` command is temporary and will be merged into `openspec init` once the experimental workflow is promoted to stable.
+
+**Skill Format:**
+Each skill is a directory with a `SKILL.md` file:
+```
+.claude/skills/
+├── openspec-new-change/
+│   └── SKILL.md          # name, description, instructions
+├── openspec-continue-change/
+│   └── SKILL.md          # name, description, instructions
+└── openspec-apply-change/
+    └── SKILL.md          # name, description, instructions
+```
+
+**CLI Interface:**
+```bash
+openspec artifact-experimental-setup
+
+# Output:
+# 🧪 Experimental Artifact Workflow Skills Created
+#
+#   ✓ .claude/skills/openspec-new-change/SKILL.md
+#   ✓ .claude/skills/openspec-continue-change/SKILL.md
+#   ✓ .claude/skills/openspec-apply-change/SKILL.md
+#
+# 📖 Usage:
+#
+#   Skills work automatically in compatible editors:
+#   • Claude Code - Auto-detected, ready to use
+#   • Cursor - Enable in Settings → Rules → Import Settings
+#   • Windsurf - Auto-imports from .claude directory
+#
+#   Ask Claude naturally:
+#   • "I want to start a new OpenSpec change to add <feature>"
+#   • "Continue working on this change"
+#
+#   Claude will automatically use the appropriate skill.
+#
+# 💡 This is an experimental feature.
+#    Feedback welcome at: https://github.com/Fission-AI/OpenSpec/issues
+```
+
+**Implementation Notes:**
+- Simple file writing: Create directories and write templated `SKILL.md` files (no complex logic)
+- Use existing `FileSystemUtils.writeFile()` pattern like slash command configurators
+- Template structure: YAML frontmatter + markdown body
+- Keep existing `/opsx:*` slash commands for now (manual cleanup later)
+- Skills use invocation model (user explicitly asks Claude to use them)
+- Skill `description` field guides when Claude suggests using the skill
+- Each `SKILL.md` has required fields: `name` (matches directory) and `description`
+
+---
+
+### 4. Update `/opsx:new` Command Content
+
+**Current Behavior (awf:start):**
+1. Ask user what they want to build (if no input)
+2. Create change directory
+3. Show artifact status
+4. Show what's ready
+5. Get instructions for proposal
+6. STOP and wait
+
+**New Behavior (opsx:new):**
+Same flow but with updated naming:
+- References to "awf" → "opsx"
+- References to `/awf:continue` → `/opsx:continue`
+- Update frontmatter name/description
+
+**Tasks:**
+- [x] Update all "awf" references to "opsx"
+- [x] Update command references in prompt text
+- [x] Verify CLI commands still work (they use `openspec`, not `awf`)
+
+---
+
+### 5. Update `/opsx:continue` Command Content
+
+**Current Behavior (awf:continue):**
+1. Prompt for change selection (if not provided)
+2. Check current status
+3. Create ONE artifact based on what's ready
+4. Show progress and what's unlocked
+5. STOP
+
+**New Behavior (opsx:continue):**
+Same flow with updated naming.
+
+**Tasks:**
+- [x] Update all "awf" references to "opsx"
+- [x] Update command references in prompt text
+
+---
+
+### 6. End-to-End Testing
+
+**Objective:**
+Run through a complete workflow with Claude using the new skills to create a real feature, validating the entire flow works.
+
+**Test Scenario:**
+Use a real OpenSpec feature as the test case (dog-fooding).
+
+**Test Flow:**
+1. Run `openspec artifact-experimental-setup` to create skills
+2. Verify `.claude/skills/openspec-new-change/SKILL.md` created
+3. Verify `.claude/skills/openspec-continue-change/SKILL.md` created
+4. Verify `.claude/skills/openspec-apply-change/SKILL.md` created
+5. Ask Claude: "I want to start a new OpenSpec change to add feature X"
+6. Verify Claude invokes the `openspec-new-change` skill
+7. Verify change directory created at `openspec/changes/add-feature-x/`
+8. Verify proposal template shown
+9. Ask Claude: "Continue working on this change"
+10. Verify Claude invokes the `openspec-continue-change` skill
+11. Verify `proposal.md` created with content
+12. Ask Claude: "Continue" (create specs)
+13. Verify `specs/*.md` created
+14. Ask Claude: "Continue" (create design)
+15. Verify `design.md` created
+16. Ask Claude: "Continue" (create tasks)
+17. Verify `tasks.md` created
+18. Verify status shows 4/4 complete
+19. Implement the feature based on tasks
+20. Run `/openspec:archive` to archive the change
+
+**Validation Checklist:**
+- [ ] `openspec artifact-experimental-setup` creates correct directory structure
+- [ ] Skills are auto-detected in Claude Code
+- [ ] Skill descriptions trigger appropriate invocations
+- [ ] Skills create change directory and show proposal template
+- [ ] Skills correctly identify ready artifacts
+- [ ] Skills create artifacts with meaningful content
+- [ ] Dependency detection works (specs requires proposal, etc.)
+- [ ] Progress tracking is accurate
+- [ ] Template content is useful and well-structured
+- [ ] Error handling works (invalid names, missing changes, etc.)
+- [ ] Works with different schemas (spec-driven, tdd)
+- [ ] Test in Cursor (Settings → Rules → Import Settings)
+
+**Document Results:**
+- Create test log documenting what worked and what didn't
+- Note any friction points or confusing UX
+- Identify bugs or improvements needed before user release
+
+---
+
+### 7. Documentation for Users
+
+**Create user-facing documentation explaining:**
+
+1. **What is the experimental workflow?**
+   - A new way to create OpenSpec changes step-by-step using Agent Skills
+   - One artifact at a time with dependency tracking
+   - More interactive and iterative than the batch approach
+   - Works across Claude Code, Cursor, Windsurf, and other compatible editors
+
+2. **How to set up experimental workflow**
+   ```bash
+   openspec artifact-experimental-setup
+   ```
+
+   Note: This is a temporary command that will be integrated into `openspec init` once promoted to stable.
+
+3. **Available skills**
+   - `openspec-new-change` - Start a new change with artifact workflow
+   - `openspec-continue-change` - Continue working (create next artifact)
+
+4. **How to use**
+   - **Claude Code**: Skills are auto-detected, just ask Claude naturally
+     - "I want to start a new OpenSpec change to add X"
+     - "Continue working on this change"
+   - **Cursor**: Enable in Settings → Rules → Import Settings
+   - **Windsurf**: Auto-imports `.claude` directory
+
+5. **Example workflow**
+   - Step-by-step walkthrough with natural language interactions
+   - Show how Claude invokes skills based on user requests
+
+6. **Feedback mechanism**
+   - GitHub issue template for feedback
+   - What to report (bugs, UX issues, suggestions)
+
+**Tasks:**
+- [ ] Create `docs/experimental-workflow.md` user guide
+- [ ] Add GitHub issue template for experimental feedback
+- [ ] Update README with mention of experimental features
+
+---
+
+## Dependency Graph
+
+```
+1. Remove WF skill files
+   └── (no dependencies)
+
+2. Rename AWF to OPSX
+   └── (no dependencies)
+
+3. Add Agent Skills
+   └── Depends on: Rename AWF to OPSX (uses opsx content as templates)
+
+4. Update opsx:new content
+   └── Depends on: Rename AWF to OPSX
+
+5. Update opsx:continue content
+   └── Depends on: Rename AWF to OPSX
+
+6. E2E Testing
+   └── Depends on: Add Agent Skills (tests the skills workflow)
+
+7. User Documentation
+   └── Depends on: E2E Testing (need to know final behavior)
+```
+
+---
+
+## Out of Scope
+
+The following are explicitly NOT part of this experimental release:
+
+1. **Batch mode refactor** - Making legacy `/openspec:proposal` use schemas
+2. **New schemas** - Only shipping with existing `spec-driven` and `tdd`
+3. **Schema customization UI** - No `openspec schema list` or similar
+4. **Multiple editor support in CLI** - Skills work cross-editor automatically via `.claude/skills/`
+5. **Replacing existing commands** - Skills are additive, not replacing `/openspec:*` or `/opsx:*`
+
+---
+
+## Success Criteria
+
+The experimental release is ready when:
+
+1. `openspec-new-change`, `openspec-continue-change`, and `openspec-apply-change` skills work end-to-end
+2. `openspec artifact-experimental-setup` creates skills in `.claude/skills/`
+3. Skills work in Claude Code and are compatible with Cursor/Windsurf
+4. At least one complete workflow has been tested manually
+5. User documentation exists explaining how to generate and use skills
+6. Feedback mechanism is in place
+7. WF skill files are removed
+8. No references to "awf" remain in user-facing content
+
+---
+
+## Open Questions
+
+1. **Schema selection** - Should `opsx:new` allow selecting a schema, or always use `spec-driven`?
+   - Current: Always uses `spec-driven` as default
+   - Consider: Add `--schema tdd` option or prompt
+
+2. **Namespace in CLI** - Should experimental CLI commands be namespaced?
+   - Current: `openspec status`, `openspec instructions` (no namespace)
+   - Alternative: `openspec opsx status` (explicit experimental namespace)
+   - Recommendation: Keep current, less typing for users
+
+3. **Deprecation path** - If opsx becomes the default, how do we migrate?
+   - Not needed for experimental release
+   - Document that command names may change
+
+---
+
+## Estimated Work Breakdown
+
+| Item | Complexity | Notes |
+|------|------------|-------|
+| Remove WF files | Trivial | Just delete 2 files + directory |
+| Rename AWF → OPSX | Low | File renames + content updates |
+| Add Agent Skills | **Low** | **Simple: 3-4 files, single output directory, standard format** |
+| Update opsx:new content | Low | Text replacements |
+| Update opsx:continue content | Low | Text replacements |
+| E2E Testing | Medium | Manual testing, documenting results |
+| User Documentation | Medium | New docs, issue template |
+
+**Key Improvement:** Switching to Agent Skills reduces complexity significantly:
+- **Before:** 20+ files (type definitions, 18+ editor configurators, editor selection UI)
+- **After:** 3-4 files (skill templates, simple CLI command)
+- **Cross-editor:** Works automatically in Claude Code, Cursor, Windsurf without extra code
+
+---
+
+## User Feedback from E2E Testing
+
+### What Worked Well
+
+1. **Clear dependency graph** ⭐ HIGH PRIORITY - KEEP
+   - The status command showing blocked/unblocked artifacts was intuitive:
+     ```
+     [x] proposal
+     [ ] design
+     [-] tasks (blocked by: design, specs)
+     ```
+   - Users always knew what they could work on next
+   - **Relevance**: Core UX strength to preserve
+
+2. **Structured instructions output** ⭐ HIGH PRIORITY - KEEP
+   - `openspec instructions <artifact>` gave templates, output paths, and context in one call
+   - Very helpful for understanding what to create
+   - **Relevance**: Essential for agent-driven workflow
+
+3. **Simple scaffolding** ✅ WORKS WELL
+   - `openspec new change "name"` just worked - created directory structure without fuss
+   - **Relevance**: Good baseline, room for improvement (see pain points)
+
+---
+
+### Pain Points & Confusion
+
+1. **Redundant CLI calls** ⚠️ MEDIUM PRIORITY
+   - Users called both `status` AND `next` every time, but they overlap significantly
+   - `status` already shows what's blocked
+   - **Recommendation**: Consider merging or making `next` give actionable guidance beyond just listing names
+   - **Relevance**: Reduces friction in iterative workflow
+
+2. **Specs directory structure was ambiguous** 🔥 HIGH PRIORITY - FIX
+   - Instructions said: `Write to: .../specs/**/*.md`
+   - Users had to guess: `specs/spec.md`? `specs/game/spec.md`? `specs/tic-tac-toe/spec.md`?
+   - Users ended up doing manual `mkdir -p .../specs/tic-tac-toe` then writing `spec.md` inside
+   - **Recommendation**: CLI should scaffold this directory structure automatically
+   - **Relevance**: Critical agent UX - ambiguous paths cause workflow friction
+
+3. **Repetitive --change flag** ⚠️ MEDIUM PRIORITY
+   - Every command needed `--change "tic-tac-toe-game"`
+   - After 10+ calls, this felt verbose
+   - **Recommendation**: `openspec use "tic-tac-toe-game"` to set context, then subsequent commands assume that change
+   - **Relevance**: Quality of life improvement for iterative sessions
+
+4. **No validation feedback** 🔥 HIGH PRIORITY - ADD
+   - After writing each artifact, users just ran `status` hoping it would show `[x]`
+   - Questions raised:
+     - How did it know the artifact was "done"? File existence?
+     - What if spec format was wrong (e.g., wrong heading levels)?
+   - **Recommendation**: Add `openspec validate --change "name"` to check content quality
+   - **Relevance**: Critical for user confidence and catching errors early
+
+5. **Query-heavy, action-light CLI** 🔥 HIGH PRIORITY - ENHANCE
+   - Most commands retrieve info. The only "action" is `new change`
+   - Artifact creation is manual Write to guessed paths
+   - **Recommendation**: `openspec create proposal --change "name"` could scaffold the file with template pre-filled, then user just edits
+   - **Relevance**: Directly impacts agent productivity - reduce manual file writing
+
+6. **Instructions output was verbose** ⚠️ LOW PRIORITY
+   - XML-style output (`<artifact>`, `<template>`, `<instruction>`) was parseable but long
+   - Key info (output path, template) was buried in ~50 lines
+   - **Recommendation**: Add compact mode or structured JSON output for agents
+   - **Relevance**: Nice-to-have for agent parsing efficiency
+
+---
+
+### Workflow Friction
+
+1. **Mandatory "STOP and wait" after showing proposal template** ⚠️ MEDIUM PRIORITY
+   - The skill said "STOP and wait" after showing the proposal template
+   - This felt overly cautious when user had already provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthetics")
+   - **Recommendation**: Make the pause optional or conditional based on context clarity
+   - **Relevance**: Reduces unnecessary round-trips in agent conversations
+
+2. **No connection to implementation** 🔥 HIGH PRIORITY - ROADMAP ITEM
+   - After 4/4 artifacts complete, then what? The workflow ends at planning
+   - No `openspec apply` or guidance on how to execute the tasks
+   - User asked "would you like me to implement?" but that's outside OpenSpec's scope currently
+   - **Recommendation**: Add implementation bridge - either:
+     - `openspec apply` command to start execution phase
+     - Clear handoff to existing `/openspec:apply` workflow
+     - Documentation on next steps after planning completes
+   - **Relevance**: Critical missing piece - users expect end-to-end workflow
+
+---
+
+### Priority Summary
+
+**MUST FIX (High Priority):**
+1. Specs directory structure ambiguity (#2)
+2. Add validation feedback (#4)
+3. Make CLI more action-oriented (#5)
+4. Bridge to implementation phase (#2 in Workflow Friction)
+5. Keep clear dependency graph (#1 in What Worked)
+6. Keep structured instructions (#2 in What Worked)
+
+**SHOULD FIX (Medium Priority):**
+1. Reduce redundant CLI calls (#1)
+2. Repetitive `--change` flag (#3)
+3. Mandatory STOP behavior (#1 in Workflow Friction)
+
+**NICE TO HAVE (Low Priority):**
+1. Compact instructions output mode (#6)
+
+---
+
+## Design Decisions (from E2E Testing Feedback)
+
+Based on dev testing and analysis of agent workflow friction, we identified three blockers for experimental release and made the following decisions.
+
+### Blockers Identified
+
+From the pain points in E2E testing, three issues are blocking the experimental release:
+
+1. **Specs directory ambiguity** - Agents don't know where to write spec files or how to name capabilities
+2. **CLI is query-heavy** - Most commands retrieve info, artifact creation is manual
+3. **Apply integration missing** - After 4/4 artifacts complete, no guidance on implementation phase
+
+### Decision 1: Capability Discovery in Proposal (RESOLVED)
+
+**Problem:** The specs artifact instruction says "Create one spec file per capability in `specs/<name>/spec.md`" but:
+- Agent doesn't know what `<name>` should be
+- Capability identification requires research (existing specs, codebase)
+- Proposal template asks for "Affected specs" but doesn't structure it
+- Research happens implicitly, output isn't captured
+
+**Decision:** Enrich the proposal template to explicitly capture capability discovery.
+
+**Current proposal template:**
+```markdown
+## Why
+## What Changes
+## Impact
+- Affected specs: List capabilities...  ← vague, easy to skip
+- Affected code: ...
+```
+
+**New proposal template:**
+```markdown
+## Why
+## What Changes
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced (will create new specs/<name>/spec.md) -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities being changed (will update existing specs) -->
+- `<existing-name>`: <what's changing>
+
+## Impact
+<!-- Affected code, APIs, dependencies, systems -->
+```
+
+**Rationale:**
+- Proposal already asks for capabilities (just poorly) - this makes it explicit
+- Captured output is reviewable (vs implicit research that can't be verified)
+- Creates clear contract between proposal and specs phases
+- Distinguishes NEW vs MODIFIED upfront (critical for specs phase)
+- Agent can't skip research - it's part of the deliverable
+
+**Implementation:**
+- Update `schemas/spec-driven/templates/proposal.md`
+- Update proposal instruction in `schemas/spec-driven/schema.yaml`
+- Update skill instructions to guide capability discovery
+
+### Decision 2: CLI Action Commands (IN PROGRESS)
+
+**Problem:** CLI is mostly query-oriented. Agents run `openspec status`, `openspec next`, `openspec instructions` but then must manually write files.
+
+#### Decision 2a: Remove `openspec next` command (RESOLVED)
+
+**Problem:** The `next` command is redundant. It only shows which artifacts are ready, but `status` already shows this information (artifacts with status "ready" vs "blocked" vs "done").
+
+**Current behavior:**
+```bash
+openspec status --change "X"  # Shows: proposal (done), specs (ready), design (blocked), tasks (blocked)
+openspec next --change "X"    # Shows: ["specs"]  ← redundant
+```
+
+**Decision:** Remove the `next` command. Agents should use `status` which provides the same info plus more context.
+
+**Implementation:**
+- Remove `next` command from CLI
+- Update skill instructions to use `status` instead of `next`
+- Update AGENTS.md references
+
+#### Decision 2b: CLI Scaffolding (RESOLVED - NO)
+
+**Problem:** After getting instructions, agents manually write files. Should CLI scaffold artifacts instead?
+
+**Options considered:**
+- Add `openspec create <artifact>` commands that scaffold files with templates
+- Keep current approach where agent writes files directly from instructions
+- Hybrid: CLI can scaffold, agent can also write directly
+
+**Decision:** Keep current flow. No scaffolding commands.
+
+**Rationale (from agent ergonomics perspective):**
+- One Write is better than multiple Edits - agent composes full content atomically
+- `instructions` already provides template in context - scaffolding just moves it to a file
+- Fewer tool calls: `instructions` + Write (2) vs `create` + `instructions` + Read + Edit×N (4+)
+- Scaffolding doesn't solve the real problem (not knowing WHAT to write)
+- Real problem solved by proposal template change (capability discovery)
+
+**For multi-file artifacts (specs):** Scaffolding can't help because CLI doesn't know capability names until proposal is complete. The capability discovery in proposal solves this.
+
+### Decision 3: Apply Integration (RESOLVED)
+
+**Original problem:** After planning completes (4/4 artifacts), the experimental workflow ends. No guidance on implementation.
+
+**Key insight: No phases, just actions.**
+
+Through discussion, we realized phases (planning → implementation → archive) are an artificial constraint. Work is fluid:
+- You might start implementing, realize the design is wrong → update design.md
+- You're halfway through tasks, discover a new requirement → update specs
+- You bounce between "planning" and "implementing" constantly
+
+**The better model: Actions on a Change**
+
+A change is a thing (with artifacts). Actions are verbs you perform on a change. Actions aren't phases - they're fluid operations you can perform anytime.
+
+| Action | What it does | Skill | CLI Command |
+|--------|--------------|-------|-------------|
+| `new` | Create a change (scaffold directory) | `opsx:new` | `openspec new change` |
+| `continue` | Create next artifact (dependency-aware) | `opsx:continue` | `openspec instructions` |
+| `apply` | Implement tasks (execute, check off) | `opsx:apply` (NEW) | TBD |
+| `update` | Refresh/update artifacts based on learnings | `opsx:update` (NEW) | TBD |
+| `explore` | Research, ask questions, understand | `opsx:explore` (NEW) | TBD |
+| `validate` | Check artifacts are correct/complete | TBD | `openspec validate` |
+| `archive` | Finalize and move to archive | existing | `openspec archive` |
+
+**Key principles:**
+- Actions are modeled as skills (primary interface for agents)
+- Some skills have matching CLI commands for convenience
+- Skills and CLI commands are decoupled - not everything needs both
+- Actions can be performed in any order (with soft prerequisites)
+- No linear phase gates
+
+**What the schema defines:**
+- Artifacts (what they are, where they go)
+- Dependencies (what must exist first)
+- Required vs optional
+- Templates + instructions
+
+**What the schema does NOT define:**
+- Phases
+- When you can modify things
+- Linear workflow
+
+**Progress tracking:**
+- tasks.md checkboxes = implementation progress
+- Artifact existence = planning progress
+- Archive readiness = user decides (or all tasks done)
+
+**For experimental release:**
+- Create `opsx:apply` skill (guidance for implementing tasks)
+- Document the "actions on a change" model
+- Other actions (update, explore) can come later
+
+---
+
+### Design: `openspec-apply-change` Skill
+
+#### Overview
+
+The apply skill guides agents through implementing tasks from a completed (or in-progress) change. Unlike the old `/openspec:apply` command, this skill:
+- Is **fluid** - can be invoked anytime, not just after all artifacts are done
+- Allows **artifact updates** - if implementation reveals issues, update design/specs
+- Works **until done** - keeps going through tasks until complete or blocked
+- Tracks **progress via checkboxes** - tasks.md is the source of truth
+
+#### Skill Metadata
+
+```yaml
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+```
+
+#### When to Invoke
+
+The skill should be invoked when:
+- User says "implement this change" or "start implementing"
+- User says "work on the tasks" or "do the next task"
+- User says "apply this change"
+- All artifacts are complete and user wants to proceed
+- User wants to continue implementation after a break
+
+#### Input
+
+- Optionally: change name
+- Optionally: specific task number to work on
+- If omitted: prompt for change selection (same pattern as continue-change)
+
+#### Steps
+
+```markdown
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use **AskUserQuestion** to let user select.
+
+   Show changes that have tasks.md (implementation-ready).
+   Mark changes with incomplete tasks as "(In Progress)".
+
+2. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (proposal, specs, design, tasks)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If blocked (missing artifacts): show message, suggest `openspec-continue-change`
+   - If all done: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+3. **Read context files**
+
+   Read the files listed in the instructions:
+   - `proposal.md` - why and what
+   - `specs/*.md` - requirements and scenarios
+   - `design.md` - technical approach (if exists)
+   - `tasks.md` - the implementation checklist
+
+4. **Show current progress**
+
+   Display:
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+5. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in tasks.md: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+6. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+```
+
+#### Output Format
+
+**During implementation:**
+```
+## Implementing: add-user-auth
+
+Working on task 3/7: Create UserAuth service class
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: Add login endpoint to AuthController
+[...implementation happening...]
+✓ Task complete
+
+Working on task 5/7: Add JWT token generation
+[...implementation happening...]
+```
+
+**On completion:**
+```
+## Implementation Complete
+
+**Change:** add-user-auth
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Create UserAuth service class
+- [x] Add login endpoint to AuthController
+- [x] Add JWT token generation
+- [x] Add logout endpoint
+- [x] Add auth middleware
+- [x] Write unit tests
+- [x] Update API documentation
+
+All tasks complete! Ready to archive this change.
+```
+
+**On pause (issue encountered):**
+```
+## Implementation Paused
+
+**Change:** add-user-auth
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+Task 5 "Add JWT token generation" - the design specifies using RS256 but
+the existing auth library only supports HS256.
+
+**Options:**
+1. Update design.md to use HS256 instead
+2. Add a new JWT library that supports RS256
+3. Other approach
+
+What would you like to do?
+```
+
+#### Guardrails
+
+- Keep going through tasks until done or blocked
+- Always read context before starting (specs, design)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+
+#### Fluid Workflow Integration
+
+The apply skill supports the "actions on a change" model:
+
+**Can be invoked anytime:**
+- Before all artifacts are done (if tasks.md exists)
+- After partial implementation
+- Interleaved with other actions (update, continue)
+
+**Allows artifact updates:**
+- If implementation reveals design issues → suggest `opsx:update` or manual edit
+- If requirements need clarification → suggest updating specs
+- Not phase-locked - work fluidly
+
+**Example fluid workflow:**
+```
+User: "Implement add-user-auth"
+→ openspec-apply-change: implements tasks 1, 2, 3, 4...
+→ Pauses at task 5: "Design says RS256 but library only supports HS256"
+
+User: "Let's use HS256 instead, update the design"
+→ User edits design.md (or uses opsx:update in future)
+
+User: "Continue implementing"
+→ openspec-apply-change: implements tasks 5, 6, 7
+→ "All tasks complete! Ready to archive."
+```
+
+#### CLI Commands Used
+
+```bash
+openspec list --json                        # List changes for selection
+openspec status --change "<name>"           # Check artifact completion
+openspec instructions apply --change "<name>" # Get apply instructions (NEW)
+# File reads via Read tool for proposal, specs, design, tasks
+# File edits via Edit tool for checking off tasks
+```
+
+#### New CLI Command: `openspec instructions apply`
+
+For consistency with artifact instructions.
+
+**Usage:**
+```bash
+openspec instructions apply --change "<name>" [--json]
+```
+
+**Output (Markdown format):**
+```markdown
+## Apply: add-user-auth
+
+### Context Files
+- proposal: openspec/changes/add-user-auth/proposal.md
+- specs: openspec/changes/add-user-auth/specs/**/*.md
+- design: openspec/changes/add-user-auth/design.md
+- tasks: openspec/changes/add-user-auth/tasks.md
+
+### Progress
+2/7 complete
+
+### Tasks
+- [x] Create UserAuth service class
+- [x] Add login endpoint
+- [ ] Add JWT token generation
+- [ ] Add logout endpoint
+- [ ] Add auth middleware
+- [ ] Write unit tests
+- [ ] Update API documentation
+
+### Instruction
+Read context files, work through pending tasks, mark complete as you go.
+Pause if you hit blockers or need clarification.
+```
+
+**Benefits of CLI command:**
+- **Consistency** - same pattern as `openspec instructions <artifact>`
+- **Structured output** - progress, tasks, context paths in one call
+- **Clean format** - markdown is readable and compact (vs verbose XML)
+- **Extensibility** - can add more sections later if needed
+- **JSON option** - `--json` flag available for programmatic use
+
+#### Differences from Old `/openspec:apply`
+
+| Aspect | Old `/openspec:apply` | New `openspec-apply-change` |
+|--------|----------------------|----------------------------|
+| Invocation | After all artifacts done | Anytime (if tasks.md exists) |
+| Granularity | All tasks at once | All tasks, but pauses on issues |
+| Artifact updates | Not mentioned | Encouraged when needed |
+| Progress tracking | Update all at end | Update after each task |
+| Flow control | Push through everything | Pause on blockers, resume after |
+| Context loading | Read once at start | Read context, reference as needed |
+| Issue handling | Not specified | Pause, present options, wait for guidance |
+
+#### Implementation Notes
+
+1. **Add CLI command**: Add `openspec instructions apply` to artifact-workflow.ts
+   - Parse tasks.md for progress (count done/pending)
+   - Return context paths, progress, task list, simple instruction
+2. **Add to skill-templates.ts**: Create `getApplyChangeSkillTemplate()` function
+3. **Update artifact-experimental-setup**: Generate this skill alongside new/continue
+4. **Update skills list**: Add to `.claude/skills/` directory
+5. **Test the flow**: Verify it works with existing changes that have tasks.md
+
+---
+
+## Next Steps
+
+1. ~~Review this plan and confirm scope~~ (Done - blockers identified)
+2. ~~Design decisions~~ (Done - all 3 blockers resolved)
+3. ~~Design apply skill~~ (Done - documented above)
+4. ~~Implement proposal template change (Decision 1 - capability discovery)~~ (Done)
+5. ~~Remove `openspec next` command (Decision 2a)~~ (Done)
+6. ~~Add `openspec instructions apply` CLI command~~ (Done)
+7. ~~Create `openspec-apply-change` skill~~ (Done)
+8. Conduct E2E testing with updated workflow
+9. Write user docs (document "actions on a change" model)
+10. Release to test users

docs/experimental-workflow.md

@@ -0,0 +1,665 @@
+# Experimental Workflow (OPSX)
+
+> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/BYjPaKbqMt).
+>
+> **Compatibility:** Claude Code only (for now)
+
+## What Is It?
+
+OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
+
+## Why This Exists
+
+The standard OpenSpec workflow works, but it's **locked down**:
+
+- **Instructions are hardcoded** — buried in TypeScript, you can't change them
+- **All-or-nothing** — one big command creates everything, can't test individual pieces
+- **Fixed structure** — same workflow for everyone, no customization
+- **Black box** — when AI output is bad, you can't tweak the prompts
+
+**OPSX opens it up.** Now anyone can:
+
+1. **Experiment with instructions** — edit a template, see if the AI does better
+2. **Test granularly** — validate each artifact's instructions independently
+3. **Customize workflows** — define your own artifacts and dependencies
+4. **Iterate quickly** — change a template, test immediately, no rebuild
+
+```
+Standard workflow:                    OPSX:
+┌────────────────────────┐           ┌────────────────────────┐
+│  Hardcoded in package  │           │  schema.yaml           │◄── You edit this
+│  (can't change)        │           │  templates/*.md        │◄── Or this
+│        ↓               │           │        ↓               │
+│  Wait for new release  │           │  Instant effect        │
+│        ↓               │           │        ↓               │
+│  Hope it's better      │           │  Test it yourself      │
+└────────────────────────┘           └────────────────────────┘
+```
+
+**This is for everyone:**
+- **Teams** — create workflows that match how you actually work
+- **Power users** — tweak prompts to get better AI outputs for your codebase
+- **OpenSpec contributors** — experiment with new approaches without releases
+
+We're all still learning what works best. OPSX lets us learn together.
+
+## The User Experience
+
+**The problem with linear workflows:**
+You're "in planning phase", then "in implementation phase", then "done". But real work doesn't work that way. You implement something, realize your design was wrong, need to update specs, continue implementing. Linear phases fight against how work actually happens.
+
+**OPSX approach:**
+- **Actions, not phases** — create, implement, update, archive — do any of them anytime
+- **Dependencies are enablers** — they show what's possible, not what's required next
+- **Update as you learn** — halfway through implementation? Go back and fix the design. That's normal.
+
+```
+You can always go back:
+
+     ┌────────────────────────────────────┐
+     │                                    │
+     ▼                                    │
+  proposal ──→ specs ──→ design ──→ tasks ──→ implement
+     ▲           ▲          ▲               │
+     │           │          │               │
+     └───────────┴──────────┴───────────────┘
+              update as you learn
+```
+
+## Setup
+
+```bash
+# 1. Make sure you have openspec installed and initialized
+openspec init
+
+# 2. Generate the experimental skills
+openspec artifact-experimental-setup
+```
+
+This creates skills in `.claude/skills/` that Claude Code auto-detects.
+
+During setup, you'll be prompted to create a **project config** (`openspec/config.yaml`). This is optional but recommended.
+
+## Project Configuration
+
+Project config lets you set defaults and inject project-specific context into all artifacts.
+
+### Creating Config
+
+Config is created during `artifact-experimental-setup`, or manually:
+
+```yaml
+# openspec/config.yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  API conventions: RESTful, JSON responses
+  Testing: Vitest for unit tests, Playwright for e2e
+  Style: ESLint with Prettier, strict TypeScript
+
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams
+  specs:
+    - Use Given/When/Then format for scenarios
+  design:
+    - Include sequence diagrams for complex flows
+```
+
+### Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema` | string | Default schema for new changes (e.g., `spec-driven`, `tdd`) |
+| `context` | string | Project context injected into all artifact instructions |
+| `rules` | object | Per-artifact rules, keyed by artifact ID |
+
+### How It Works
+
+**Schema precedence** (highest to lowest):
+1. CLI flag (`--schema tdd`)
+2. Change metadata (`.openspec.yaml` in change directory)
+3. Project config (`openspec/config.yaml`)
+4. Default (`spec-driven`)
+
+**Context injection:**
+- Context is prepended to every artifact's instructions
+- Wrapped in `<context>...</context>` tags
+- Helps AI understand your project's conventions
+
+**Rules injection:**
+- Rules are only injected for matching artifacts
+- Wrapped in `<rules>...</rules>` tags
+- Appear after context, before the template
+
+### Artifact IDs by Schema
+
+**spec-driven** (default):
+- `proposal` — Change proposal
+- `specs` — Specifications
+- `design` — Technical design
+- `tasks` — Implementation tasks
+
+**tdd**:
+- `spec` — Feature specification
+- `tests` — Test file
+- `implementation` — Implementation code
+- `docs` — Documentation
+
+### Config Validation
+
+- Unknown artifact IDs in `rules` generate warnings
+- Schema names are validated against available schemas
+- Context has a 50KB size limit
+- Invalid YAML is reported with line numbers
+
+### Troubleshooting
+
+**"Unknown artifact ID in rules: X"**
+- Check artifact IDs match your schema (see list above)
+- Run `openspec schemas --json` to see artifact IDs for each schema
+
+**Config not being applied:**
+- Ensure file is at `openspec/config.yaml` (not `.yml`)
+- Check YAML syntax with a validator
+- Config changes take effect immediately (no restart needed)
+
+**Context too large:**
+- Context is limited to 50KB
+- Summarize or link to external docs instead
+
+## Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through ideas, investigate problems, clarify requirements |
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward — create all planning artifacts at once |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
+| `/opsx:sync` | Sync delta specs to main specs |
+| `/opsx:archive` | Archive when done |
+
+## Usage
+
+### Explore an idea
+```
+/opsx:explore
+```
+Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:new` or `/opsx:ff`.
+
+### Start a new change
+```
+/opsx:new
+```
+You'll be asked what you want to build and which workflow schema to use.
+
+### Create artifacts
+```
+/opsx:continue
+```
+Shows what's ready to create based on dependencies, then creates one artifact. Use repeatedly to build up your change incrementally.
+
+```
+/opsx:ff add-dark-mode
+```
+Creates all planning artifacts at once. Use when you have a clear picture of what you're building.
+
+### Implement (the fluid part)
+```
+/opsx:apply
+```
+Works through tasks, checking them off as you go. **Key difference:** if you discover issues during implementation, you can update your specs, design, or tasks — then continue. No phase gates. If you're juggling multiple changes, you can run `/opsx:apply <name>`; otherwise it should infer from the conversation and prompt you to choose if it can’t tell.
+
+### Finish up
+```
+/opsx:sync      # Update main specs with your delta specs
+/opsx:archive   # Move to archive when done
+```
+
+## When to Update vs. Start Fresh
+
+OPSX lets you update artifacts anytime. But when does "update as you learn" become "this is different work"?
+
+### What a Proposal Captures
+
+A proposal defines three things:
+1. **Intent** — What problem are you solving?
+2. **Scope** — What's in/out of bounds?
+3. **Approach** — How will you solve it?
+
+The question is: which changed, and by how much?
+
+### Update the Existing Change When:
+
+**Same intent, refined execution**
+- You discover edge cases you didn't consider
+- The approach needs tweaking but the goal is unchanged
+- Implementation reveals the design was slightly off
+
+**Scope narrows**
+- You realize full scope is too big, want to ship MVP first
+- "Add dark mode" → "Add dark mode toggle (system preference in v2)"
+
+**Learning-driven corrections**
+- Codebase isn't structured how you thought
+- A dependency doesn't work as expected
+- "Use CSS variables" → "Use Tailwind's dark: prefix instead"
+
+### Start a New Change When:
+
+**Intent fundamentally changed**
+- The problem itself is different now
+- "Add dark mode" → "Add comprehensive theme system with custom colors, fonts, spacing"
+
+**Scope exploded**
+- Change grew so much it's essentially different work
+- Original proposal would be unrecognizable after updates
+- "Fix login bug" → "Rewrite auth system"
+
+**Original is completable**
+- The original change can be marked "done"
+- New work stands alone, not a refinement
+- Complete "Add dark mode MVP" → Archive → New change "Enhance dark mode"
+
+### The Heuristics
+
+```
+                        ┌─────────────────────────────────────┐
+                        │     Is this the same work?          │
+                        └──────────────┬──────────────────────┘
+                                       │
+                    ┌──────────────────┼──────────────────┐
+                    │                  │                  │
+                    ▼                  ▼                  ▼
+             Same intent?      >50% overlap?      Can original
+             Same problem?     Same scope?        be "done" without
+                    │                  │          these changes?
+                    │                  │                  │
+          ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
+          │                 │  │             │   │               │
+         YES               NO YES           NO  NO              YES
+          │                 │  │             │   │               │
+          ▼                 ▼  ▼             ▼   ▼               ▼
+       UPDATE            NEW  UPDATE       NEW  UPDATE          NEW
+```
+
+| Test | Update | New Change |
+|------|--------|------------|
+| **Identity** | "Same thing, refined" | "Different work" |
+| **Scope overlap** | >50% overlaps | <50% overlaps |
+| **Completion** | Can't be "done" without changes | Can finish original, new work stands alone |
+| **Story** | Update chain tells coherent story | Patches would confuse more than clarify |
+
+### The Principle
+
+> **Update preserves context. New change provides clarity.**
+>
+> Choose update when the history of your thinking is valuable.
+> Choose new when starting fresh would be clearer than patching.
+
+Think of it like git branches:
+- Keep committing while working on the same feature
+- Start a new branch when it's genuinely new work
+- Sometimes merge a partial feature and start fresh for phase 2
+
+## What's Different?
+
+| | Standard (`/openspec:proposal`) | Experimental (`/opsx:*`) |
+|---|---|---|
+| **Structure** | One big proposal document | Discrete artifacts with dependencies |
+| **Workflow** | Linear phases: plan → implement → archive | Fluid actions — do anything anytime |
+| **Iteration** | Awkward to go back | Update artifacts as you learn |
+| **Customization** | Fixed structure | Schema-driven (define your own artifacts) |
+
+**The key insight:** work isn't linear. OPSX stops pretending it is.
+
+## Architecture Deep Dive
+
+This section explains how OPSX works under the hood and how it compares to the standard workflow.
+
+### Philosophy: Phases vs Actions
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         STANDARD WORKFLOW                                    │
+│                    (Phase-Locked, All-or-Nothing)                           │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌──────────────┐      ┌──────────────┐      ┌──────────────┐             │
+│   │   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │             │
+│   │    PHASE     │      │    PHASE     │      │    PHASE     │             │
+│   └──────────────┘      └──────────────┘      └──────────────┘             │
+│         │                     │                     │                       │
+│         ▼                     ▼                     ▼                       │
+│   /openspec:proposal   /openspec:apply      /openspec:archive              │
+│                                                                             │
+│   • Creates ALL artifacts at once                                          │
+│   • Can't go back to update specs during implementation                    │
+│   • Phase gates enforce linear progression                                  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            OPSX WORKFLOW                                     │
+│                      (Fluid Actions, Iterative)                             │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│              ┌────────────────────────────────────────────┐                 │
+│              │           ACTIONS (not phases)             │                 │
+│              │                                            │                 │
+│              │   new ◄──► continue ◄──► apply ◄──► sync   │                 │
+│              │    │          │           │          │     │                 │
+│              │    └──────────┴───────────┴──────────┘     │                 │
+│              │              any order                     │                 │
+│              └────────────────────────────────────────────┘                 │
+│                                                                             │
+│   • Create artifacts one at a time OR fast-forward                         │
+│   • Update specs/design/tasks during implementation                        │
+│   • Dependencies enable progress, phases don't exist                       │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Component Architecture
+
+**Standard workflow** uses hardcoded templates in TypeScript:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      STANDARD WORKFLOW COMPONENTS                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Hardcoded Templates (TypeScript strings)                                  │
+│                    │                                                        │
+│                    ▼                                                        │
+│   Configurators (18+ classes, one per editor)                               │
+│                    │                                                        │
+│                    ▼                                                        │
+│   Generated Command Files (.claude/commands/openspec/*.md)                  │
+│                                                                             │
+│   • Fixed structure, no artifact awareness                                  │
+│   • Change requires code modification + rebuild                             │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**OPSX** uses external schemas and a dependency graph engine:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         OPSX COMPONENTS                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   Schema Definitions (YAML)                                                 │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │  name: spec-driven                                                  │   │
+│   │  artifacts:                                                         │   │
+│   │    - id: proposal                                                   │   │
+│   │      generates: proposal.md                                         │   │
+│   │      requires: []              ◄── Dependencies                     │   │
+│   │    - id: specs                                                      │   │
+│   │      generates: specs/**/*.md  ◄── Glob patterns                    │   │
+│   │      requires: [proposal]      ◄── Enables after proposal           │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                    │                                                        │
+│                    ▼                                                        │
+│   Artifact Graph Engine                                                     │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │  • Topological sort (dependency ordering)                           │   │
+│   │  • State detection (filesystem existence)                           │   │
+│   │  • Rich instruction generation (templates + context)                │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                    │                                                        │
+│                    ▼                                                        │
+│   Skill Files (.claude/skills/openspec-*/SKILL.md)                          │
+│                                                                             │
+│   • Cross-editor compatible (Claude Code, Cursor, Windsurf)                 │
+│   • Skills query CLI for structured data                                    │
+│   • Fully customizable via schema files                                     │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Dependency Graph Model
+
+Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, not gates:
+
+```
+                              proposal
+                             (root node)
+                                  │
+                    ┌─────────────┴─────────────┐
+                    │                           │
+                    ▼                           ▼
+                 specs                       design
+              (requires:                  (requires:
+               proposal)                   proposal)
+                    │                           │
+                    └─────────────┬─────────────┘
+                                  │
+                                  ▼
+                               tasks
+                           (requires:
+                           specs, design)
+                                  │
+                                  ▼
+                          ┌──────────────┐
+                          │ APPLY PHASE  │
+                          │ (requires:   │
+                          │  tasks)      │
+                          └──────────────┘
+```
+
+**State transitions:**
+
+```
+   BLOCKED ────────────────► READY ────────────────► DONE
+      │                        │                       │
+   Missing                  All deps               File exists
+   dependencies             are DONE               on filesystem
+```
+
+### Information Flow
+
+**Standard workflow** — agent receives static instructions:
+
+```
+  User: "/openspec:proposal"
+           │
+           ▼
+  ┌─────────────────────────────────────────┐
+  │  Static instructions:                   │
+  │  • Create proposal.md                   │
+  │  • Create tasks.md                      │
+  │  • Create design.md                     │
+  │  • Create specs/*.md                    │
+  │                                         │
+  │  No awareness of what exists or         │
+  │  dependencies between artifacts         │
+  └─────────────────────────────────────────┘
+           │
+           ▼
+  Agent creates ALL artifacts in one go
+```
+
+**OPSX** — agent queries for rich context:
+
+```
+  User: "/opsx:continue"
+           │
+           ▼
+  ┌──────────────────────────────────────────────────────────────────────────┐
+  │  Step 1: Query current state                                             │
+  │  ┌────────────────────────────────────────────────────────────────────┐  │
+  │  │  $ openspec status --change "add-auth" --json                      │  │
+  │  │                                                                    │  │
+  │  │  {                                                                 │  │
+  │  │    "artifacts": [                                                  │  │
+  │  │      {"id": "proposal", "status": "done"},                         │  │
+  │  │      {"id": "specs", "status": "ready"},      ◄── First ready      │  │
+  │  │      {"id": "design", "status": "ready"},                          │  │
+  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
+  │  │    ]                                                               │  │
+  │  │  }                                                                 │  │
+  │  └────────────────────────────────────────────────────────────────────┘  │
+  │                                                                          │
+  │  Step 2: Get rich instructions for ready artifact                        │
+  │  ┌────────────────────────────────────────────────────────────────────┐  │
+  │  │  $ openspec instructions specs --change "add-auth" --json          │  │
+  │  │                                                                    │  │
+  │  │  {                                                                 │  │
+  │  │    "template": "# Specification\n\n## ADDED Requirements...",      │  │
+  │  │    "dependencies": [{"id": "proposal", "path": "...", "done": true}│  │
+  │  │    "unlocks": ["tasks"]                                            │  │
+  │  │  }                                                                 │  │
+  │  └────────────────────────────────────────────────────────────────────┘  │
+  │                                                                          │
+  │  Step 3: Read dependencies → Create ONE artifact → Show what's unlocked  │
+  └──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Iteration Model
+
+**Standard workflow** — awkward to iterate:
+
+```
+  ┌─────────┐     ┌─────────┐     ┌─────────┐
+  │/proposal│ ──► │ /apply  │ ──► │/archive │
+  └─────────┘     └─────────┘     └─────────┘
+       │               │
+       │               ├── "Wait, the design is wrong"
+       │               │
+       │               ├── Options:
+       │               │   • Edit files manually (breaks context)
+       │               │   • Abandon and start over
+       │               │   • Push through and fix later
+       │               │
+       │               └── No official "go back" mechanism
+       │
+       └── Creates ALL artifacts at once
+```
+
+**OPSX** — natural iteration:
+
+```
+  /opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
+      │                │                  │
+      │                │                  ├── "The design is wrong"
+      │                │                  │
+      │                │                  ▼
+      │                │            Just edit design.md
+      │                │            and continue!
+      │                │                  │
+      │                │                  ▼
+      │                │         /opsx:apply picks up
+      │                │         where you left off
+      │                │
+      │                └── Creates ONE artifact, shows what's unlocked
+      │
+      └── Scaffolds change, waits for direction
+```
+
+### Custom Schemas
+
+Create custom workflows using the schema management commands:
+
+```bash
+# Create a new schema from scratch (interactive)
+openspec schema init my-workflow
+
+# Or fork an existing schema as a starting point
+openspec schema fork spec-driven my-workflow
+
+# Validate your schema structure
+openspec schema validate my-workflow
+
+# See where a schema resolves from (useful for debugging)
+openspec schema which my-workflow
+```
+
+Schemas are stored in `openspec/schemas/` (project-local, version controlled) or `~/.local/share/openspec/schemas/` (user global).
+
+**Schema structure:**
+```
+openspec/schemas/research-first/
+├── schema.yaml
+└── templates/
+    ├── research.md
+    ├── proposal.md
+    └── tasks.md
+```
+
+**Example schema.yaml:**
+```yaml
+name: research-first
+artifacts:
+  - id: research        # Added before proposal
+    generates: research.md
+    requires: []
+
+  - id: proposal
+    generates: proposal.md
+    requires: [research]  # Now depends on research
+
+  - id: tasks
+    generates: tasks.md
+    requires: [proposal]
+```
+
+**Dependency Graph:**
+```
+   research ──► proposal ──► tasks
+```
+
+### Summary
+
+| Aspect | Standard | OPSX |
+|--------|----------|------|
+| **Templates** | Hardcoded TypeScript | External YAML + Markdown |
+| **Dependencies** | None (all at once) | DAG with topological sort |
+| **State** | Phase-based mental model | Filesystem existence |
+| **Customization** | Edit source, rebuild | Create schema.yaml |
+| **Iteration** | Phase-locked | Fluid, edit anything |
+| **Editor Support** | 18+ configurator classes | Single skills directory |
+
+## Schemas
+
+Schemas define what artifacts exist and their dependencies. Currently available:
+
+- **spec-driven** (default): proposal → specs → design → tasks
+- **tdd**: tests → implementation → docs
+
+```bash
+# List available schemas
+openspec schemas
+
+# See all schemas with their resolution sources
+openspec schema which --all
+
+# Create a new schema interactively
+openspec schema init my-workflow
+
+# Fork an existing schema for customization
+openspec schema fork spec-driven my-workflow
+
+# Validate schema structure before use
+openspec schema validate my-workflow
+```
+
+## Tips
+
+- Use `/opsx:explore` to think through an idea before committing to a change
+- `/opsx:ff` when you know what you want, `/opsx:continue` when exploring
+- During `/opsx:apply`, if something's wrong — fix the artifact, then continue
+- Tasks track progress via checkboxes in `tasks.md`
+- Check status anytime: `openspec status --change "name"`
+
+## Feedback
+
+This is rough. That's intentional — we're learning what works.
+
+Found a bug? Have ideas? Join us on [Discord](https://discord.gg/BYjPaKbqMt) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).

docs/multi-language-output.md

@@ -0,0 +1,217 @@
+# Multi-Language Output Guide
+
+Configure OpenSpec to generate artifacts in languages other than English.
+
+## Overview
+
+OpenSpec can output proposals, specs, designs, and tasks in any language by adding language instructions to your project's `context` configuration. This approach uses the existing config system without requiring any code changes.
+
+## Quick Setup
+
+### If you already have a config file
+
+Add a language instruction to your existing `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+  Use Portuguese technical terminology where appropriate.
+
+  # Your other project context below...
+  Tech stack: TypeScript, React, Node.js
+```
+
+That's it. All generated artifacts will now be in Portuguese.
+
+### If you don't have a config file yet
+
+You can create one interactively or manually:
+
+**Option 1: Interactive setup**
+
+```bash
+openspec artifact-experimental-setup
+```
+
+This will guide you through creating `openspec/config.yaml` with schema selection, context, and rules.
+
+**Option 2: Manual creation**
+
+Create the file `openspec/config.yaml` in your project root:
+
+```bash
+mkdir -p openspec
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+EOF
+```
+
+## Language Examples
+
+### Portuguese (Brazil)
+
+```yaml
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts (proposals, specs, designs, tasks) must be written in Brazilian Portuguese.
+  Use Brazilian Portuguese conventions for technical terminology.
+```
+
+### Spanish
+
+```yaml
+context: |
+  Idioma: Español
+  Todos los artefactos deben escribirse en español.
+  Utilizar terminología técnica en español cuando sea posible.
+```
+
+### Chinese (Simplified)
+
+```yaml
+context: |
+  语言：中文（简体）
+  所有产出物（提案、规格、设计、任务）必须用简体中文撰写。
+  技术术语可以保留英文原文，但说明应使用中文。
+```
+
+### Japanese
+
+```yaml
+context: |
+  言語：日本語
+  すべての成果物は日本語で作成してください。
+  技術用語は必要に応じて英語を併記可能です。
+```
+
+### French
+
+```yaml
+context: |
+  Langue : Français
+  Tous les artefacts doivent être rédigés en français.
+  Utiliser la terminologie technique française lorsque possible.
+```
+
+### German
+
+```yaml
+context: |
+  Sprache: Deutsch
+  Alle Artefakte müssen auf Deutsch verfasst werden.
+  Technische Fachbegriffe können auf Englisch beibehalten werden.
+```
+
+## How It Works
+
+The `context` field in `openspec/config.yaml` is injected into every artifact's instructions as an XML block:
+
+```xml
+<context>
+Language: Portuguese (pt-BR)
+All artifacts must be written in Brazilian Portuguese.
+...
+</context>
+
+<template>
+[Schema's template content]
+</template>
+```
+
+The AI assistant sees this context when generating any artifact and follows the language instruction.
+
+## Tips
+
+### Be Explicit About Scope
+
+Specify which parts should be in the target language:
+
+```yaml
+context: |
+  Language: Spanish
+  Write all prose, descriptions, and explanations in Spanish.
+  Code comments may remain in English for consistency with the codebase.
+  Variable names and code identifiers should stay in English.
+```
+
+### Handle Technical Terms
+
+Decide how to handle technical terminology:
+
+```yaml
+context: |
+  Language: Japanese
+  Write in Japanese, but:
+  - Keep technical terms like "API", "REST", "GraphQL" in English
+  - Provide Japanese explanations in parentheses for complex terms on first use
+  - Code examples and file paths remain in English
+```
+
+### Combine with Other Context
+
+Language settings work alongside your other project context:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+
+  Tech stack: TypeScript, React 18, Node.js 20
+  Database: PostgreSQL with Prisma ORM
+  Testing: Vitest + React Testing Library
+
+  Conventions:
+  - Use functional components with hooks
+  - Follow existing patterns in src/components/
+```
+
+## Verification
+
+To verify your language config is working:
+
+```bash
+# Create a test change
+openspec new change test-language
+
+# Check the instructions - should show your language context
+openspec instructions proposal --change test-language
+
+# Output will include:
+# <context>
+# Language: Portuguese (pt-BR)
+# All artifacts must be written in Brazilian Portuguese.
+# ...
+# </context>
+```
+
+## Limitations
+
+- Language instructions apply to **all** artifacts. You cannot set different languages for different artifact types.
+- The effectiveness depends on the AI model's proficiency in the target language.
+- Technical diagrams, code samples, and file paths typically remain in English regardless of language setting.
+
+## Future Considerations
+
+We're considering adding a dedicated `language` field to the config schema in a future release:
+
+```yaml
+# Potential future syntax (not yet implemented)
+schema: spec-driven
+language: pt-BR
+```
+
+For now, the `context` approach described above is the recommended method. It provides full flexibility and works with all current versions of OpenSpec.
+
+## Related Documentation
+
+- [Project Config Demo](./project-config-demo.md) - Overview of project configuration
+- [Experimental Workflow Guide](./experimental-workflow.md) - Full workflow documentation

docs/project-config-demo.md

@@ -0,0 +1,205 @@
+# Project Config Demo Guide
+
+A quick-reference guide for demonstrating the `openspec/config.yaml` feature.
+
+## Summary: What Project Config Does
+
+The feature adds `openspec/config.yaml` as a lightweight customization layer that lets teams:
+
+- **Set a default schema** - New changes automatically use this schema instead of having to specify `--schema` every time
+- **Inject project context** - Shared context (tech stack, conventions) shown to AI when creating any artifact
+- **Add per-artifact rules** - Custom rules that only apply to specific artifacts (e.g., proposal, specs)
+
+## Demo Walkthrough
+
+### Demo 1: Interactive Setup (Recommended Entry Point)
+
+The easiest way to demo is through the experimental setup command:
+
+```bash
+openspec artifact-experimental-setup
+```
+
+After creating skills/commands, it will prompt:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Project Configuration (Optional)
+
+Configure project defaults for OpenSpec workflows.
+
+? Create openspec/config.yaml? (Y/n)
+```
+
+Walk through:
+
+1. **Select schema** - Shows available schemas with their artifact flows
+2. **Add context** - Opens editor for multi-line project context (tech stack, conventions)
+3. **Add rules** - Checkbox to select artifacts, then line-by-line rule entry
+
+This creates `openspec/config.yaml` with the user's choices.
+
+### Demo 2: Manual Config Creation
+
+Show that users can create the config directly:
+
+```bash
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js, PostgreSQL
+  API style: RESTful, documented in docs/api.md
+  Testing: Jest + React Testing Library
+  We value backwards compatibility for all public APIs
+
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams and notify in #platform-changes
+  specs:
+    - Use Given/When/Then format
+    - Reference existing patterns before inventing new ones
+EOF
+```
+
+### Demo 3: Effect on New Changes
+
+Show that creating a new change now uses the default schema:
+
+```bash
+# Before config: had to specify schema
+openspec new change my-feature --schema spec-driven
+
+# After config: schema is automatic
+openspec new change my-feature
+# Automatically uses spec-driven from config
+```
+
+### Demo 4: Context and Rules Injection
+
+The key demo moment - show how instructions are enriched:
+
+```bash
+# Get instructions for an artifact
+openspec instructions proposal --change my-feature
+```
+
+Output shows the XML structure:
+
+```xml
+<context>
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+API style: RESTful, documented in docs/api.md
+...
+</context>
+
+<rules>
+- Include rollback plan
+- Identify affected teams and notify in #platform-changes
+</rules>
+
+<template>
+[Schema's built-in proposal template]
+</template>
+```
+
+Key points to highlight:
+
+- **Context** appears in ALL artifacts (proposal, specs, design, tasks)
+- **Rules** ONLY appear for the matching artifact (proposal rules only in proposal instructions)
+
+### Demo 5: Precedence Override
+
+Show the schema resolution order:
+
+```bash
+# Config sets schema: spec-driven
+
+# 1. CLI flag wins
+openspec new change feature-a --schema tdd  # Uses tdd
+
+# 2. Change metadata wins over config
+# (if .openspec.yaml in change directory specifies schema)
+
+# 3. Config is used as default
+openspec new change feature-b  # Uses spec-driven from config
+
+# 4. Hardcoded default (no config)
+# Would fall back to spec-driven anyway
+```
+
+### Demo 6: Validation and Error Handling
+
+Show graceful error handling:
+
+```bash
+# Create config with typo
+echo "schema: spec-drivne" > openspec/config.yaml
+
+# Try to use it - shows fuzzy matching suggestions
+openspec new change test
+# Schema 'spec-drivne' not found
+# Did you mean: spec-driven (built-in)
+```
+
+```bash
+# Unknown artifact ID in rules - warns but doesn't halt
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+rules:
+  testplan:  # Schema doesn't have this
+    - Some rule
+EOF
+
+openspec instructions proposal --change test
+# ⚠️ Unknown artifact ID in rules: "testplan". Valid IDs for schema "spec-driven": ...
+# (continues working)
+```
+
+## Quick Demo Script
+
+Here's a quick all-in-one demo:
+
+```bash
+# 1. Show there's no config initially
+cat openspec/config.yaml 2>/dev/null || echo "No config exists"
+
+# 2. Create a simple config
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+context: |
+  This is a demo project using React and TypeScript.
+  We follow semantic versioning.
+rules:
+  proposal:
+    - Include migration steps if breaking change
+EOF
+
+# 3. Show the config
+cat openspec/config.yaml
+
+# 4. Create a change (uses default schema from config)
+openspec new change demo-feature
+
+# 5. Show instructions with injected context/rules
+openspec instructions proposal --change demo-feature | head -30
+
+# 6. Show that specs don't have proposal rules
+openspec instructions specs --change demo-feature | head -30
+```
+
+## What to Emphasize in Demo
+
+- **Low friction** - Teams can customize without forking schemas
+- **Shared context** - Everyone on the team gets the same project knowledge
+- **Per-artifact rules** - Targeted guidance where it matters
+- **Graceful failures** - Typos warn, don't break workflow
+- **Team sharing** - Just commit `openspec/config.yaml` and everyone benefits
+
+## Related Documentation
+
+- [Experimental Workflow Guide](./experimental-workflow.md) - Full user guide with config section
+- [Project Config Proposal](../openspec/changes/project-config/proposal.md) - Original design proposal
+- [Project Config Design](../openspec/changes/project-config/design.md) - Technical implementation details

docs/schema-customization.md

@@ -0,0 +1,211 @@
+# Schema Customization
+
+This document describes how users can customize OpenSpec schemas and templates, the current manual process, and the gap that needs to be addressed.
+
+---
+
+## Overview
+
+OpenSpec uses a 2-level schema resolution system following the XDG Base Directory Specification:
+
+1. **User override**: `${XDG_DATA_HOME}/openspec/schemas/<name>/`
+2. **Package built-in**: `<npm-package>/schemas/<name>/`
+
+When a schema is requested (e.g., `spec-driven`), the resolver checks the user directory first. If found, that entire schema directory is used. Otherwise, it falls back to the package's built-in schema.
+
+---
+
+## Current Manual Process
+
+To override the default `spec-driven` schema, a user must:
+
+### 1. Determine the correct directory path
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.local/share/openspec/schemas/` |
+| Windows | `%LOCALAPPDATA%\openspec\schemas\` |
+| All (if set) | `$XDG_DATA_HOME/openspec/schemas/` |
+
+### 2. Create the directory structure
+
+```bash
+# macOS/Linux example
+mkdir -p ~/.local/share/openspec/schemas/spec-driven/templates
+```
+
+### 3. Find and copy the default schema files
+
+The user must locate the installed npm package to copy the defaults:
+
+```bash
+# Find the package location (varies by install method)
+npm list -g openspec --parseable
+# or
+which openspec && readlink -f $(which openspec)
+
+# Copy files from the package's schemas/ directory
+cp <package-path>/schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
+cp <package-path>/schemas/spec-driven/templates/*.md ~/.local/share/openspec/schemas/spec-driven/templates/
+```
+
+### 4. Modify the copied files
+
+Edit `schema.yaml` to change the workflow structure:
+
+```yaml
+name: spec-driven
+version: 1
+description: My custom workflow
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal
+    template: proposal.md
+    requires: []
+  # Add, remove, or modify artifacts...
+```
+
+Edit templates in `templates/` to customize the content guidance.
+
+### 5. Verify the override is active
+
+Currently there's no command to verify which schema is being used. Users must trust that the file exists in the right location.
+
+---
+
+## Gap Analysis
+
+The current process has several friction points:
+
+| Issue | Impact |
+|-------|--------|
+| **Path discovery** | Users must know XDG conventions and platform-specific paths |
+| **Package location** | Finding the npm package path varies by install method (global, local, pnpm, yarn, volta, etc.) |
+| **No scaffolding** | Users must manually create directories and copy files |
+| **No verification** | No way to confirm which schema is actually being resolved |
+| **No diffing** | When upgrading openspec, users can't see what changed in built-in templates |
+| **Full copy required** | Must copy entire schema even to change one template |
+
+### User Stories Not Currently Supported
+
+1. *"I want to add a `research` artifact before `proposal`"* — requires manual copy and edit
+2. *"I want to customize just the proposal template"* — must copy entire schema
+3. *"I want to see what the default schema looks like"* — must find package path
+4. *"I want to revert to defaults"* — must delete files and hope paths are correct
+5. *"I upgraded openspec, did the templates change?"* — no way to diff
+
+---
+
+## Proposed Solution: Schema Configurator
+
+A CLI command (or set of commands) that handles path resolution and file operations for users.
+
+### Option A: Single `openspec schema` command
+
+```bash
+# List available schemas (built-in and user overrides)
+openspec schema list
+
+# Show where a schema resolves from
+openspec schema which spec-driven
+# Output: /Users/me/.local/share/openspec/schemas/spec-driven/ (user override)
+# Output: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+
+# Copy a built-in schema to user directory for customization
+openspec schema copy spec-driven
+# Creates ~/.local/share/openspec/schemas/spec-driven/ with all files
+
+# Show diff between user override and built-in
+openspec schema diff spec-driven
+
+# Remove user override (revert to built-in)
+openspec schema reset spec-driven
+
+# Validate a schema
+openspec schema validate spec-driven
+```
+
+### Option B: Dedicated `openspec customize` command
+
+```bash
+# Interactive schema customization
+openspec customize
+# Prompts: Which schema? What do you want to change? etc.
+
+# Copy and open for editing
+openspec customize spec-driven
+# Copies to user dir, prints path, optionally opens in $EDITOR
+```
+
+### Option C: Init-time schema selection
+
+```bash
+# During project init, offer schema customization
+openspec init
+# ? Select a workflow schema:
+#   > spec-driven (default)
+#     tdd
+#     minimal
+#     custom (copy and edit)
+```
+
+### Recommended Approach
+
+**Option A** provides the most flexibility and follows Unix conventions (subcommands for discrete operations). Key commands in priority order:
+
+1. `openspec schema list` — see what's available
+2. `openspec schema which <name>` — debug resolution
+3. `openspec schema copy <name>` — scaffold customization
+4. `openspec schema diff <name>` — compare with built-in
+5. `openspec schema reset <name>` — revert to defaults
+
+---
+
+## Implementation Considerations
+
+### Path Resolution
+
+The resolver already exists in `src/core/artifact-graph/resolver.ts`:
+
+```typescript
+export function getPackageSchemasDir(): string { ... }
+export function getUserSchemasDir(): string { ... }
+export function getSchemaDir(name: string): string | null { ... }
+export function listSchemas(): string[] { ... }
+```
+
+New commands would leverage these existing functions.
+
+### File Operations
+
+- Copy should preserve file permissions
+- Copy should not overwrite existing user files without `--force`
+- Reset should prompt for confirmation
+
+### Template-Only Overrides
+
+A future enhancement could support overriding individual templates without copying the entire schema. This would require changes to the resolution logic:
+
+```
+Current: schema dir (user) OR schema dir (built-in)
+Future:  schema.yaml from user OR built-in
+         + each template from user OR built-in (independent fallback)
+```
+
+This adds complexity but enables the "I just want to change one template" use case.
+
+---
+
+## Related Documents
+
+- [Schema Workflow Gaps](./schema-workflow-gaps.md) — End-to-end workflow analysis and phased implementation plan
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
+| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
+| `src/core/global-config.ts` | XDG path helpers |
+| `schemas/spec-driven/` | Default schema and templates |

docs/schema-workflow-gaps.md

@@ -0,0 +1,379 @@
+# Schema Workflow: End-to-End Analysis
+
+This document analyzes the complete user journey for working with schemas in OpenSpec, identifies gaps, and proposes a phased solution.
+
+---
+
+## Current State
+
+### What Exists
+
+| Component | Status |
+|-----------|--------|
+| Schema resolution | 3-level: project → user → package (PR #522) |
+| Built-in schemas | `spec-driven`, `tdd` |
+| Artifact workflow commands | `status`, `next`, `instructions`, `templates` with `--schema` flag |
+| Change creation | `openspec new change <name>` — no schema binding |
+| Project-local schemas | ✅ Supported via `openspec/schemas/` (PR #522) |
+| Schema management CLI | ✅ `schema which`, `validate`, `fork`, `init` (PR #525) |
+
+### What's Missing
+
+| Component | Status |
+|-----------|--------|
+| Schema bound to change | Not stored — must pass `--schema` every time |
+| Project default schema | None — hardcoded to `spec-driven` |
+
+---
+
+## User Journey Analysis
+
+### Scenario 1: Using a Non-Default Schema
+
+**Goal:** User wants to use TDD workflow for a new feature.
+
+**Today's experience:**
+```bash
+openspec new change add-auth
+# Creates directory, no schema info stored
+
+openspec status --change add-auth
+# Shows spec-driven artifacts (WRONG - user wanted TDD)
+
+# User realizes mistake...
+openspec status --change add-auth --schema tdd
+# Correct, but must remember --schema every time
+
+# 6 months later...
+openspec status --change add-auth
+# Wrong again - nobody remembers this was TDD
+```
+
+**Problems:**
+- Schema is a runtime argument, not persisted
+- Easy to forget `--schema` and get wrong results
+- No record of intended schema for future reference
+
+---
+
+### Scenario 2: Customizing a Schema
+
+**Goal:** User wants to add a "research" artifact before "proposal".
+
+**Today's experience:**
+```bash
+# Step 1: Figure out where to put overrides
+# Must know XDG conventions:
+#   macOS/Linux: ~/.local/share/openspec/schemas/
+#   Windows: %LOCALAPPDATA%\openspec\schemas/
+
+# Step 2: Create directory structure
+mkdir -p ~/.local/share/openspec/schemas/my-workflow/templates
+
+# Step 3: Find the npm package to copy defaults
+npm list -g openspec --parseable
+# Output varies by package manager:
+#   npm: /usr/local/lib/node_modules/openspec
+#   pnpm: ~/.local/share/pnpm/global/5/node_modules/openspec
+#   volta: ~/.volta/tools/image/packages/openspec/...
+#   yarn: ~/.config/yarn/global/node_modules/openspec
+
+# Step 4: Copy files
+cp -r <package-path>/schemas/spec-driven/* \
+      ~/.local/share/openspec/schemas/my-workflow/
+
+# Step 5: Edit schema.yaml and templates
+# No way to verify override is active
+# No way to diff against original
+```
+
+**Problems:**
+- Must know XDG path conventions
+- Finding npm package path varies by install method
+- No tooling to scaffold or verify
+- No diff capability when upgrading openspec
+
+---
+
+### Scenario 3: Team Sharing Custom Workflow
+
+**Goal:** Team wants everyone to use the same custom schema.
+
+**Today's options:**
+1. Everyone manually sets up XDG override — error-prone, drift risk
+2. Document setup in README — still manual, easy to miss
+3. Publish separate npm package — overkill for most teams
+4. Check schema into repo — **not supported** (no project-local resolution)
+
+**Problems:**
+- No project-local schema resolution
+- Can't version control custom schemas with the codebase
+- No single source of truth for team workflow
+
+---
+
+## Gap Summary
+
+| Gap | Impact | Status |
+|-----|--------|--------|
+| Schema not bound to change | Wrong results, forgotten context | ⏳ Pending (Phase 1) |
+| No project-local schemas | Can't share via repo | ✅ Fixed (PR #522) |
+| No schema management CLI | Manual path hunting | ✅ Fixed (PR #525) |
+| No project default schema | Must specify every time | ⏳ Pending (Phase 4) |
+| No init-time schema selection | Missed setup opportunity | ⏳ Pending (Phase 4) |
+
+---
+
+## Proposed Architecture
+
+### New File Structure
+
+```
+openspec/
+├── config.yaml                 # Project config (NEW)
+├── schemas/                    # Project-local schemas (NEW)
+│   └── my-workflow/
+│       ├── schema.yaml
+│       └── templates/
+│           ├── research.md
+│           ├── proposal.md
+│           └── ...
+└── changes/
+    └── add-auth/
+        ├── change.yaml         # Change metadata (NEW)
+        ├── proposal.md
+        └── ...
+```
+
+### config.yaml (Project Config)
+
+```yaml
+# openspec/config.yaml
+defaultSchema: spec-driven
+```
+
+Sets the project-wide default schema. Used when:
+- Creating new changes without `--schema`
+- Running commands on changes without `change.yaml`
+
+### change.yaml (Change Metadata)
+
+```yaml
+# openspec/changes/add-auth/change.yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+description: Add user authentication system
+```
+
+Binds a specific schema to a change. Created automatically by `openspec new change`.
+
+### Schema Resolution Order
+
+```
+1. ./openspec/schemas/<name>/                    # Project-local
+2. ~/.local/share/openspec/schemas/<name>/       # User global (XDG)
+3. <npm-package>/schemas/<name>/                 # Built-in
+```
+
+Project-local takes priority, enabling version-controlled custom schemas.
+
+### Schema Selection Order (Per Command)
+
+```
+1. --schema CLI flag                    # Explicit override
+2. change.yaml in change directory      # Change-specific binding
+3. openspec/config.yaml defaultSchema   # Project default
+4. "spec-driven"                        # Hardcoded fallback
+```
+
+---
+
+## Ideal User Experience
+
+### Creating a Change
+
+```bash
+# Uses project default (from config.yaml, or spec-driven)
+openspec new change add-auth
+# Creates openspec/changes/add-auth/change.yaml:
+#   schema: spec-driven
+#   created: 2025-01-15T10:30:00Z
+
+# Explicit schema for this change
+openspec new change add-auth --schema tdd
+# Creates change.yaml with schema: tdd
+```
+
+### Working with Changes
+
+```bash
+# Auto-reads schema from change.yaml — no --schema needed
+openspec status --change add-auth
+# Output: "Change: add-auth (schema: tdd)"
+# Shows which artifacts are ready/blocked/done
+
+# Explicit override still works (with informational message)
+openspec status --change add-auth --schema spec-driven
+# "Note: change.yaml specifies 'tdd', using 'spec-driven' per --schema flag"
+```
+
+### Customizing Schemas
+
+```bash
+# See what's available
+openspec schema list
+# Built-in:
+#   spec-driven    proposal → specs → design → tasks
+#   tdd            spec → tests → implementation → docs
+# Project: (none)
+# User: (none)
+
+# Copy to project for customization
+openspec schema copy spec-driven my-workflow
+# Created ./openspec/schemas/my-workflow/
+# Edit schema.yaml and templates/ to customize
+
+# Copy to global (user-level override)
+openspec schema copy spec-driven --global
+# Created ~/.local/share/openspec/schemas/spec-driven/
+
+# See where a schema resolves from
+openspec schema which spec-driven
+# ./openspec/schemas/spec-driven/ (project)
+# or: ~/.local/share/openspec/schemas/spec-driven/ (user)
+# or: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+
+# Compare override with built-in
+openspec schema diff spec-driven
+# Shows diff between user/project version and package built-in
+
+# Remove override, revert to built-in
+openspec schema reset spec-driven
+# Removes ./openspec/schemas/spec-driven/ (or --global for user dir)
+```
+
+### Project Setup
+
+```bash
+openspec init
+# ? Select default workflow schema:
+#   > spec-driven (proposal → specs → design → tasks)
+#     tdd (spec → tests → implementation → docs)
+#     (custom schemas if detected)
+#
+# Writes to openspec/config.yaml:
+#   defaultSchema: spec-driven
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Change Metadata (change.yaml)
+
+**Priority:** High
+**Solves:** "Forgot --schema", lost context, wrong results
+
+**Scope:**
+- Create `change.yaml` when running `openspec new change`
+- Store `schema`, `created` timestamp
+- Modify workflow commands to read schema from `change.yaml`
+- `--schema` flag overrides (with informational message)
+- Backwards compatible: missing `change.yaml` → use default
+
+**change.yaml format:**
+```yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+```
+
+**Migration:**
+- Existing changes without `change.yaml` continue to work
+- Default to `spec-driven` (current behavior)
+- Optional: `openspec migrate` to add `change.yaml` to existing changes
+
+---
+
+### Phase 2: Project-Local Schemas
+
+**Status:** ✅ Complete (PR #522)
+**Solves:** Team sharing, version control, no XDG knowledge needed
+
+**Implemented:**
+- `./openspec/schemas/` added to resolution order (first priority)
+- `openspec schema fork <name> [new-name]` creates in project by default
+- Teams can commit `openspec/schemas/` to repo
+
+**Resolution order:**
+```
+1. ./openspec/schemas/<name>/           # Project-local
+2. ~/.local/share/openspec/schemas/<name>/  # User global
+3. <npm-package>/schemas/<name>/        # Built-in
+```
+
+---
+
+### Phase 3: Schema Management CLI
+
+**Status:** ✅ Complete (PR #525)
+**Solves:** Path discovery, scaffolding, debugging
+
+**Implemented Commands:**
+```bash
+openspec schema which [name]          # Show resolution path, --all for all schemas
+openspec schema validate [name]       # Validate schema structure and templates
+openspec schema fork <source> [name]  # Copy existing schema for customization
+openspec schema init <name>           # Create new project-local schema (interactive)
+```
+
+**Not implemented (may add later):**
+- `schema diff` — Compare override with built-in
+- `schema reset` — Remove override, revert to built-in
+
+---
+
+### Phase 4: Project Config + Init Enhancement
+
+**Priority:** Low
+**Solves:** Project-wide defaults, streamlined setup
+
+**Scope:**
+- Add `openspec/config.yaml` with `defaultSchema` field
+- `openspec init` prompts for schema selection
+- Store selection in `config.yaml`
+- Commands use as fallback when no `change.yaml` exists
+
+**config.yaml format:**
+```yaml
+defaultSchema: spec-driven
+```
+
+---
+
+## Backwards Compatibility
+
+| Scenario | Behavior |
+|----------|----------|
+| Existing change without `change.yaml` | Uses `--schema` flag or project default or `spec-driven` |
+| Existing project without `config.yaml` | Falls back to `spec-driven` |
+| `--schema` flag provided | Overrides `change.yaml` (with info message) |
+| No project-local schemas dir | Skipped in resolution, checks user/built-in |
+
+All existing functionality continues to work. New features are additive.
+
+---
+
+## Related Documents
+
+- [Schema Customization](./schema-customization.md) — Details on manual override process and CLI gaps
+- [Artifact POC](./artifact_poc.md) — Core artifact graph architecture
+
+## Related Code
+
+| File | Purpose |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
+| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
+| `src/core/global-config.ts` | XDG path helpers |
+| `src/commands/artifact-workflow.ts` | CLI commands |
+| `src/utils/change-utils.ts` | Change creation utilities |

flake.lock

@@ -0,0 +1,27 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1767640445,
+        "narHash": "sha256-UWYqmD7JFBEDBHWYcqE6s6c77pWdcU/i+bwD6XxMb8A=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "9f0c42f8bc7151b8e7e5840fb3bd454ad850d8c5",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,87 @@
+{
+  description = "OpenSpec - AI-native system for spec-driven development";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs = { self, nixpkgs }:
+    let
+      supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];
+
+      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
+    in
+    {
+      packages = forAllSystems (system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = pkgs.stdenv.mkDerivation (finalAttrs: {
+            pname = "openspec";
+            version = "0.20.0";
+
+            src = ./.;
+
+            pnpmDeps = pkgs.fetchPnpmDeps {
+              inherit (finalAttrs) pname version src;
+              pnpm = pkgs.pnpm_9;
+              fetcherVersion = 3;
+              hash = "sha256-m/7IdY1ou9ljjYAcx3W8AyEJvIZfCBWIWxproQ/INPA=";
+            };
+
+            nativeBuildInputs = with pkgs; [
+              nodejs_20
+              npmHooks.npmInstallHook
+              pnpmConfigHook
+              pnpm_9
+            ];
+
+            buildPhase = ''
+              runHook preBuild
+
+              pnpm run build
+
+              runHook postBuild
+            '';
+
+            dontNpmPrune = true;
+
+            meta = with pkgs.lib; {
+              description = "AI-native system for spec-driven development";
+              homepage = "https://github.com/Fission-AI/OpenSpec";
+              license = licenses.mit;
+              maintainers = [ ];
+              mainProgram = "openspec";
+            };
+          });
+        });
+
+      apps = forAllSystems (system: {
+        default = {
+          type = "app";
+          program = "${self.packages.${system}.default}/bin/openspec";
+        };
+      });
+
+      devShells = forAllSystems (system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = pkgs.mkShell {
+            buildInputs = with pkgs; [
+              nodejs_20
+              pnpm_9
+            ];
+
+            shellHook = ''
+              echo "OpenSpec development environment"
+              echo "Node version: $(node --version)"
+              echo "pnpm version: $(pnpm --version)"
+              echo "Run 'pnpm install' to install dependencies"
+            '';
+          };
+        });
+    };
+}

openspec/AGENTS.md

@@ -9,7 +9,7 @@ Instructions for AI coding assistants using OpenSpec for spec-driven development
 - Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
 - Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
 - Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
-- Validate: `openspec validate [change-id] --strict` and fix issues
+- Validate: `openspec validate [change-id] --strict --no-interactive` and fix issues
 - Request approval: Do not start implementation until proposal is approved
 
 ## Three-Stage Workflow
@@ -44,7 +44,7 @@ Skip proposal for:
 1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
 2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
 3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
-4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
+4. Run `openspec validate <id> --strict --no-interactive` and resolve any issues before sharing the proposal.
 
 ### Stage 2: Implementing Changes
 Track these steps as TODOs and complete them one by one.
@@ -61,7 +61,7 @@ After deployment, create separate PR to:
 - Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
 - Update `specs/` if capabilities changed
 - 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
+- Run `openspec validate --strict --no-interactive` to confirm the archived change passes checks
 
 ## Before Any Task
 
@@ -108,7 +108,7 @@ openspec validate              # Bulk validation mode
 
 # Debugging
 openspec show [change] --json --deltas-only
-openspec validate [change] --strict
+openspec validate [change] --strict --no-interactive
 ```
 
 ### Command Flags
@@ -160,6 +160,8 @@ New request?
 
 2. **Write proposal.md:**
 ```markdown
+# Change: [Brief description of change]
+
 ## Why
 [1-2 sentences on problem/opportunity]
 
@@ -304,7 +306,7 @@ Example for RENAMED:
 
 ```bash
 # Always use strict mode for comprehensive checks
-openspec validate [change] --strict
+openspec validate [change] --strict --no-interactive
 
 # Debug delta parsing
 openspec show [change] --json | jq '.deltas'
@@ -341,7 +343,7 @@ Users MUST provide a second factor during login.
 EOF
 
 # 4) Validate
-openspec validate $CHANGE --strict
+openspec validate $CHANGE --strict --no-interactive
 ```
 
 ## Multi-Capability Example
@@ -447,7 +449,7 @@ Only add complexity with:
 ```bash
 openspec list              # What's in progress?
 openspec show [item]       # View details
-openspec validate --strict # Is it correct?
+openspec validate --strict --no-interactive  # Is it correct?
 openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
 ```
 

openspec/changes/add-antigravity-support/specs/cli-init/spec.md

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

openspec/changes/add-antigravity-support/specs/cli-update/spec.md

@@ -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, 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

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

@@ -0,0 +1,20 @@
+## Why
+
+Users and agents need a simple way to submit feedback about OpenSpec directly from the CLI. Currently there's no mechanism to collect user feedback, feature requests, or bug reports in a way that enables follow-up conversation. Using GitHub Issues allows us to track feedback, prevent spam via GitHub auth, and enables outreach to users.
+
+## What Changes
+
+- Add `openspec feedback <message>` CLI command
+- Leverage `gh` CLI for GitHub authentication and issue creation
+- Add `/feedback` skill for agent-assisted feedback with context enrichment
+- Ensure cross-platform compatibility (macOS, Linux, Windows)
+
+## Impact
+
+- Affected specs: New `cli-feedback` capability
+- Affected code:
+  - `src/cli/index.ts` - Register feedback command
+  - `src/commands/feedback.ts` - Command implementation using `gh` CLI
+  - `src/core/templates/skill-templates.ts` - Feedback skill template
+  - `src/core/completions/command-registry.ts` - Shell completions
+- External dependency: Requires `gh` CLI installed and authenticated

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

@@ -0,0 +1,188 @@
+## ADDED Requirements
+
+### Requirement: Feedback command
+
+The system SHALL provide an `openspec feedback` command that creates a GitHub Issue in the openspec repository using the `gh` CLI. The system SHALL use `execFileSync` with argument arrays to prevent shell injection vulnerabilities.
+
+#### Scenario: Simple feedback submission
+
+- **WHEN** user executes `openspec feedback "Great tool!"`
+- **THEN** the system executes `gh issue create` with title "Feedback: Great tool!"
+- **AND** the issue is created in the openspec repository
+- **AND** the issue has the `feedback` label
+- **AND** the system displays the created issue URL
+
+#### Scenario: Safe command execution
+
+- **WHEN** submitting feedback via `gh` CLI
+- **THEN** the system uses `execFileSync` with separate arguments array
+- **AND** user input is NOT passed through a shell
+- **AND** shell metacharacters (quotes, backticks, $(), etc.) are treated as literal text
+
+#### Scenario: Feedback with body
+
+- **WHEN** user executes `openspec feedback "Title here" --body "Detailed description..."`
+- **THEN** the system creates a GitHub Issue with the specified title
+- **AND** the issue body contains the detailed description
+- **AND** the issue body includes metadata (OpenSpec version, platform, timestamp)
+
+### Requirement: GitHub CLI dependency
+
+The system SHALL use `gh` CLI for automatic feedback submission when available, and provide a manual submission fallback when `gh` is not installed or not authenticated. The system SHALL use platform-appropriate commands to detect `gh` CLI availability.
+
+#### Scenario: Missing gh CLI with fallback
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh` CLI is not installed (not found in PATH)
+- **THEN** the system displays warning: "GitHub CLI not found. Manual submission required."
+- **AND** outputs structured feedback content with delimiters:
+  - "--- FORMATTED FEEDBACK ---"
+  - Title line
+  - Labels line
+  - Body content with metadata
+  - "--- END FEEDBACK ---"
+- **AND** displays pre-filled GitHub issue URL for manual submission
+- **AND** exits with zero code (successful fallback)
+
+#### Scenario: Cross-platform gh CLI detection on Unix
+
+- **WHEN** system is running on macOS or Linux (platform is 'darwin' or 'linux')
+- **AND** checking if `gh` CLI is installed
+- **THEN** the system executes `which gh` command
+
+#### Scenario: Cross-platform gh CLI detection on Windows
+
+- **WHEN** system is running on Windows (platform is 'win32')
+- **AND** checking if `gh` CLI is installed
+- **THEN** the system executes `where gh` command
+
+#### Scenario: Unauthenticated gh CLI with fallback
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh` CLI is installed but not authenticated
+- **THEN** the system displays warning: "GitHub authentication required. Manual submission required."
+- **AND** outputs structured feedback content (same format as missing gh CLI scenario)
+- **AND** displays pre-filled GitHub issue URL for manual submission
+- **AND** displays authentication instructions: "To auto-submit in the future: gh auth login"
+- **AND** exits with zero code (successful fallback)
+
+#### Scenario: Authenticated gh CLI
+
+- **WHEN** user runs `openspec feedback "message"`
+- **AND** `gh auth status` returns success (authenticated)
+- **THEN** the system proceeds with feedback submission
+
+### Requirement: Issue metadata
+
+The system SHALL include relevant metadata in the GitHub Issue body.
+
+#### Scenario: Standard metadata
+
+- **WHEN** creating a GitHub Issue for feedback
+- **THEN** the issue body includes:
+  - OpenSpec CLI version
+  - Platform (darwin, linux, win32)
+  - Submission timestamp
+  - Separator line: "---\nSubmitted via OpenSpec CLI"
+
+#### Scenario: Windows platform metadata
+
+- **WHEN** creating a GitHub Issue for feedback on Windows
+- **THEN** the issue body includes "Platform: win32"
+- **AND** all platform detection uses Node.js `os.platform()` API
+
+#### Scenario: No sensitive metadata
+
+- **WHEN** creating a GitHub Issue for feedback
+- **THEN** the issue body does NOT include:
+  - File paths from user's system
+  - Project names or directory names
+  - Environment variables
+  - IP addresses
+
+### Requirement: Feedback always works
+
+The system SHALL allow feedback submission regardless of telemetry settings.
+
+#### Scenario: Feedback with telemetry disabled
+
+- **WHEN** user has disabled telemetry via `OPENSPEC_TELEMETRY=0`
+- **AND** user runs `openspec feedback "message"`
+- **THEN** the feedback is still submitted via `gh` CLI
+- **AND** telemetry events are not sent
+
+#### Scenario: Feedback in CI environment
+
+- **WHEN** `CI=true` is set in the environment
+- **AND** user runs `openspec feedback "message"`
+- **THEN** the feedback submission proceeds normally (if `gh` is available and authenticated)
+
+### Requirement: Error handling
+
+The system SHALL handle feedback submission errors gracefully.
+
+#### Scenario: gh CLI execution failure
+
+- **WHEN** `gh issue create` command fails
+- **THEN** the system displays the error output from `gh` CLI
+- **AND** exits with the same exit code as `gh`
+
+#### Scenario: Network failure
+
+- **WHEN** `gh` CLI reports network connectivity issues
+- **THEN** the system displays the error message from `gh`
+- **AND** suggests checking network connectivity
+- **AND** exits with non-zero code
+
+### Requirement: Feedback skill for agents
+
+The system SHALL provide a `/feedback` skill that guides agents through collecting and submitting user feedback.
+
+#### Scenario: Agent-initiated feedback
+
+- **WHEN** user invokes `/feedback` in an agent conversation
+- **THEN** the agent gathers context from the conversation
+- **AND** drafts a feedback issue with enriched content
+- **AND** anonymizes sensitive information
+- **AND** presents the draft to the user for approval
+- **AND** submits via `openspec feedback` command on user confirmation
+
+#### Scenario: Context enrichment
+
+- **WHEN** agent drafts feedback
+- **THEN** the agent includes relevant context such as:
+  - What task was being performed
+  - What worked well or poorly
+  - Specific friction points or praise
+
+#### Scenario: Anonymization
+
+- **WHEN** agent drafts feedback
+- **THEN** the agent removes or replaces:
+  - File paths with `<path>` or generic descriptions
+  - API keys, tokens, secrets with `<redacted>`
+  - Company/organization names with `<company>`
+  - Personal names with `<user>`
+  - Specific URLs with `<url>` unless public/relevant
+
+#### Scenario: User confirmation required
+
+- **WHEN** agent has drafted feedback
+- **THEN** the agent MUST show the complete draft to the user
+- **AND** ask for explicit approval before submitting
+- **AND** allow the user to request modifications
+- **AND** only submit after user confirms
+
+### Requirement: Shell completions
+
+The system SHALL provide shell completions for the feedback command.
+
+#### Scenario: Command completion
+
+- **WHEN** user types `openspec fee<TAB>`
+- **THEN** the shell completes to `openspec feedback`
+
+#### Scenario: Flag completion
+
+- **WHEN** user types `openspec feedback "msg" --<TAB>`
+- **THEN** the shell suggests available flags (`--body`)

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

@@ -0,0 +1,30 @@
+## 1. Feedback Command
+
+- [x] 1.1 Create `src/commands/feedback.ts` with command implementation
+- [x] 1.2 Check `gh` CLI availability using platform-appropriate command (`which` on Unix/macOS, `where` on Windows)
+- [x] 1.3 Check GitHub auth status with `gh auth status`
+- [x] 1.4 Execute `gh issue create` with formatted title and body using `execFileSync` to prevent shell injection
+- [x] 1.5 Display issue URL returned by `gh` CLI
+- [x] 1.6 Register `feedback <message>` command in `src/cli/index.ts`
+- [x] 1.7 Ensure cross-platform compatibility (macOS, Linux, Windows)
+
+## 2. Shell Completions
+
+- [x] 2.1 Add `feedback` command to command registry
+- [x] 2.2 Regenerate completion scripts for all shells
+
+## 3. Feedback Skill
+
+- [x] 3.1 Create feedback skill template in `skill-templates.ts`
+- [x] 3.2 Document context gathering workflow
+- [x] 3.3 Document anonymization rules
+- [x] 3.4 Document user confirmation flow
+
+## 4. Testing
+
+- [x] 4.1 Add unit tests for feedback command (mock `gh` subprocess calls)
+- [x] 4.2 Add integration test for full feedback flow with mocked `gh` CLI
+- [x] 4.3 Test error handling for missing `gh` CLI
+- [x] 4.4 Test error handling for unauthenticated `gh` session
+- [x] 4.5 Test cross-platform `gh` CLI detection (verify `which` on Unix, `where` on Windows)
+- [x] 4.6 Test platform metadata includes correct value for Windows (win32)

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

@@ -1,11 +0,0 @@
-## Why
-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 (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`
-- Affected code: `src/cli/index.ts`, `src/commands`, `docs/`

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

@@ -1,36 +0,0 @@
-## ADDED Requirements
-### Requirement: Scaffolding Command Registration
-The CLI SHALL expose an `openspec scaffold <change-id>` command that validates the change identifier before generating files.
-
-#### Scenario: Registering scaffold command
-- **WHEN** a user runs `openspec scaffold add-user-notifications`
-- **THEN** the CLI SHALL reject invalid identifiers (non kebab-case) before proceeding
-- **AND** display usage documentation via `openspec scaffold --help`
-- **AND** exit with code 0 after successful scaffolding
-
-### Requirement: Change Directory Structure
-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/` 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.
-
-#### Scenario: Populating proposal and tasks templates
-- **WHEN** the scaffold command writes `proposal.md`
-- **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
-- **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.
-
-#### Scenario: Rerunning scaffold on existing change
-- **WHEN** the command is executed again for an existing change directory containing user-edited files
-- **THEN** leave existing content untouched except for managed placeholder regions or missing files that need creation
-- **AND** update the filesystem summary to highlight which files were skipped, created, or refreshed

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

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

openspec/changes/add-verify-skill/design.md

@@ -0,0 +1,96 @@
+# Design: Add /opsx:verify Skill
+
+## Architecture Decision: Dynamic Generation via Setup Command
+
+### Context
+
+All existing opsx experimental skills (explore, new, continue, apply, ff, sync, archive) are dynamically generated when users run `openspec artifact-experimental-setup`. They are not manually created files checked into the repository.
+
+### Decision
+
+**Integrate verify into the existing artifact-experimental-setup system rather than creating static skill files.**
+
+### Rationale
+
+1. **Consistency**: All 7 existing opsx skills follow this pattern. Adding verify as the 8th skill should follow the same architecture.
+
+2. **Maintainability**: Template functions in `skill-templates.ts` are the single source of truth. Changes to skill definitions automatically propagate to all users when they re-run setup.
+
+3. **Distribution**: Users get the verify skill automatically when running `openspec artifact-experimental-setup`, just like all other opsx skills. No special installation steps needed.
+
+4. **Versioning**: Skills are generated from the installed npm package version, ensuring consistency between CLI version and skill behavior.
+
+### Implementation Approach
+
+#### 1. Template Functions
+
+Add two template functions to `src/core/templates/skill-templates.ts`:
+
+```typescript
+export function getVerifyChangeSkillTemplate(): SkillTemplate
+export function getOpsxVerifyCommandTemplate(): CommandTemplate
+```
+
+These return the skill definition (for Agent Skills) and slash command definition (for explicit invocation).
+
+#### 2. Setup Integration
+
+Update `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts`:
+
+- Import both template functions
+- Add verify to the `skills` array (position 8)
+- Add verify to the `commands` array (position 8)
+- Update help text to list `/opsx:verify`
+
+#### 3. Generated Artifacts
+
+When users run `openspec artifact-experimental-setup`, the command creates:
+
+- `.claude/skills/openspec-verify-change/SKILL.md` - Agent Skills format
+- `.claude/commands/opsx/verify.md` - Slash command format
+
+Both are generated from the template functions, with YAML frontmatter automatically added.
+
+### Alternatives Considered
+
+**Alternative 1: Static skill files in repository**
+
+Create `.claude/skills/openspec-verify-change/SKILL.md` as a static file in the OpenSpec repository.
+
+**Rejected because:**
+- Inconsistent with all other opsx skills
+- Requires users to manually copy/update files
+- Versioning becomes complicated (repo version vs installed package version)
+- Breaks the established pattern
+
+**Alternative 2: Separate verify setup command**
+
+Add `openspec setup-verify` as a separate command.
+
+**Rejected because:**
+- Fragments the setup experience
+- Users would need to run multiple commands
+- Doesn't scale if we add more skills in the future
+- Goes against the "setup once, get everything" philosophy
+
+### Trade-offs
+
+**Advantages:**
+- Consistent with existing architecture
+- Zero additional setup burden for users
+- Easy to update and maintain
+- Automatic version compatibility
+
+**Disadvantages:**
+- Slightly more complex initial implementation (template functions + integration)
+- Requires understanding the setup system (but that's already documented)
+
+### Verification
+
+The implementation correctly follows this design if:
+
+1. Both template functions exist in `skill-templates.ts`
+2. Verify appears in both skills and commands arrays in `artifact-workflow.ts`
+3. Help text mentions `/opsx:verify`
+4. Running `openspec artifact-experimental-setup` generates both skill and command files
+5. Build succeeds with no TypeScript errors

openspec/changes/add-verify-skill/proposal.md

@@ -0,0 +1,48 @@
+# Change: Add /opsx:verify Skill
+
+## Why
+
+Users need a way to validate that their implementation actually matches what was requested before archiving a change. Currently, there's no systematic way to check:
+- Whether all tasks are truly complete
+- Whether the implementation covers all spec requirements and scenarios
+- Whether the implementation follows the design decisions
+- Whether the code is coherent and makes sense
+
+A user requested: "Can we get a :verify that will ensure that the implementation matches what was requested?"
+
+## What Changes
+
+- Add `getVerifyChangeSkillTemplate()` function to `skill-templates.ts`
+- Add `getOpsxVerifyCommandTemplate()` function to `skill-templates.ts`
+- Integrate verify skill into `artifactExperimentalSetupCommand` in `artifact-workflow.ts`
+- Add verify to the skills and commands arrays in the setup command
+- Update help text to include `/opsx:verify` in the list of available commands
+- Create `opsx-verify-skill` capability spec
+
+## Verification Dimensions
+
+The skill verifies across three dimensions:
+
+1. **Completeness** - Are all tasks done? Are all specs addressed?
+2. **Correctness** - Does the implementation match specs? Are scenarios covered?
+3. **Coherence** - Does the implementation make sense? Does it follow design.md?
+
+## Output Format
+
+Produces a prioritized report with:
+- Summary scorecard (tasks, specs, design adherence)
+- Critical issues first (must fix before archive)
+- Warnings second (should fix)
+- Suggestions third (nice to have)
+- Actionable fix recommendations for each issue
+
+## Impact
+
+- Affected specs: New `opsx-verify-skill` spec
+- Affected code:
+  - `src/core/templates/skill-templates.ts` - Added 2 new template functions
+  - `src/commands/artifact-workflow.ts` - Integrated verify into experimental setup
+- Generated artifacts: When users run `openspec artifact-experimental-setup`:
+  - Creates `.claude/skills/openspec-verify-change/SKILL.md`
+  - Creates `.claude/commands/opsx/verify.md`
+- Related skills: Works alongside `/opsx:apply` and before `/opsx:archive`

openspec/changes/add-verify-skill/specs/opsx-verify-skill/spec.md

@@ -0,0 +1,190 @@
+# opsx-verify-skill Specification
+
+## Purpose
+Defines the agent skill for verifying that implementation matches change artifacts (specs, tasks, design).
+
+## ADDED Requirements
+
+### Requirement: Verify Skill Invocation
+The system SHALL provide an `/opsx:verify` skill that validates implementation against change artifacts.
+
+#### Scenario: Verify with change name provided
+- **WHEN** agent executes `/opsx:verify <change-name>`
+- **THEN** the agent verifies implementation for that specific change
+- **AND** produces a verification report
+
+#### Scenario: Verify without change name
+- **WHEN** agent executes `/opsx:verify` without a change name
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows only changes that have implementation tasks
+
+#### Scenario: Change has no tasks
+- **WHEN** selected change has no tasks.md or tasks are empty
+- **THEN** the agent reports "No tasks to verify"
+- **AND** suggests running `/opsx:continue` to create tasks
+
+### Requirement: Completeness Verification
+The agent SHALL verify that all required work has been completed.
+
+#### Scenario: Task completion check
+- **WHEN** verifying completeness
+- **THEN** the agent reads tasks.md
+- **AND** counts tasks marked `- [x]` (complete) vs `- [ ]` (incomplete)
+- **AND** reports completion status with specific incomplete tasks listed
+
+#### Scenario: Spec coverage check
+- **WHEN** verifying completeness
+- **AND** delta specs exist in `openspec/changes/<name>/specs/`
+- **THEN** the agent extracts all requirements from delta specs
+- **AND** searches codebase for implementation of each requirement
+- **AND** reports which requirements appear to have implementation vs which are missing
+
+#### Scenario: All tasks complete
+- **WHEN** all tasks are marked complete
+- **THEN** report "Tasks: N/N complete"
+- **AND** mark completeness dimension as passed
+
+#### Scenario: Incomplete tasks found
+- **WHEN** some tasks are incomplete
+- **THEN** report "Tasks: X/N complete"
+- **AND** list each incomplete task
+- **AND** mark as CRITICAL issue
+- **AND** suggest: "Complete remaining tasks or mark as done if already implemented"
+
+### Requirement: Correctness Verification
+The agent SHALL verify that implementation matches the specifications.
+
+#### Scenario: Requirement implementation mapping
+- **WHEN** verifying correctness
+- **THEN** for each requirement in delta specs:
+  - Search codebase for implementation
+  - Identify relevant files and line numbers
+  - Assess whether implementation satisfies the requirement
+
+#### Scenario: Scenario coverage check
+- **WHEN** verifying correctness
+- **THEN** for each scenario in delta specs:
+  - Check if the scenario's conditions are handled in code
+  - Check if tests exist that cover the scenario
+  - Report coverage status
+
+#### Scenario: Implementation matches spec
+- **WHEN** implementation appears to satisfy a requirement
+- **THEN** report which files/lines implement it
+- **AND** mark requirement as covered
+
+#### Scenario: Implementation diverges from spec
+- **WHEN** implementation exists but doesn't match spec intent
+- **THEN** report the divergence as WARNING
+- **AND** explain what differs
+- **AND** suggest: either update implementation or update spec to match reality
+
+#### Scenario: Missing implementation
+- **WHEN** no implementation found for a requirement
+- **THEN** report as CRITICAL issue
+- **AND** suggest: "Implement requirement X" with guidance on what's needed
+
+### Requirement: Coherence Verification
+The agent SHALL verify that implementation is sensible and follows design decisions.
+
+#### Scenario: Design.md adherence check
+- **WHEN** verifying coherence
+- **AND** design.md exists for the change
+- **THEN** extract key decisions from design.md
+- **AND** verify implementation follows those decisions
+- **AND** report any deviations
+
+#### Scenario: No design.md
+- **WHEN** verifying coherence
+- **AND** no design.md exists
+- **THEN** skip design adherence check
+- **AND** note "No design.md to verify against"
+
+#### Scenario: Design decision followed
+- **WHEN** implementation follows a design decision
+- **THEN** report as confirmed
+- **AND** cite evidence from code
+
+#### Scenario: Design decision violated
+- **WHEN** implementation contradicts a design decision
+- **THEN** report as WARNING
+- **AND** explain the contradiction
+- **AND** suggest: either update implementation or update design.md
+
+#### Scenario: Code pattern consistency
+- **WHEN** verifying coherence
+- **THEN** check if new code follows existing project patterns
+- **AND** flag any significant deviations as suggestions
+
+### Requirement: Verification Report Format
+The agent SHALL produce a structured, prioritized report.
+
+#### Scenario: Report summary
+- **WHEN** verification completes
+- **THEN** display summary scorecard:
+  ```
+  ## Verification Report: <change-name>
+
+  ### Summary
+  | Dimension    | Status   |
+  |--------------|----------|
+  | Completeness | X/Y      |
+  | Correctness  | X/Y      |
+  | Coherence    | Followed |
+  ```
+
+#### Scenario: Issue prioritization
+- **WHEN** issues are found
+- **THEN** group and display in priority order:
+  1. CRITICAL - Must fix before archive (missing implementation, incomplete tasks)
+  2. WARNING - Should fix (divergence from spec/design, missing tests)
+  3. SUGGESTION - Nice to fix (pattern inconsistencies, minor improvements)
+
+#### Scenario: Actionable recommendations
+- **WHEN** reporting an issue
+- **THEN** include specific, actionable fix recommendation
+- **AND** reference relevant files and line numbers where applicable
+- **AND** avoid vague suggestions like "consider reviewing"
+
+#### Scenario: All checks pass
+- **WHEN** no issues found across all dimensions
+- **THEN** display:
+  ```
+  All checks passed. Ready for archive.
+  ```
+
+#### Scenario: Critical issues found
+- **WHEN** CRITICAL issues exist
+- **THEN** display:
+  ```
+  X critical issue(s) found. Fix before archiving.
+  ```
+- **AND** do NOT suggest running archive
+
+#### Scenario: Only warnings/suggestions
+- **WHEN** no CRITICAL issues but warnings exist
+- **THEN** display:
+  ```
+  No critical issues. Y warning(s) to consider.
+  Ready for archive (with noted improvements).
+  ```
+
+### Requirement: Flexible Artifact Handling
+The agent SHALL gracefully handle changes with varying artifact completeness.
+
+#### Scenario: Minimal change (tasks only)
+- **WHEN** change has only tasks.md
+- **THEN** verify task completion only
+- **AND** skip spec and design checks
+- **AND** note which checks were skipped
+
+#### Scenario: Change with specs but no design
+- **WHEN** change has tasks.md and delta specs but no design.md
+- **THEN** verify completeness and correctness
+- **AND** skip design adherence
+- **AND** still check code coherence against project patterns
+
+#### Scenario: Full change (all artifacts)
+- **WHEN** change has proposal, design, specs, and tasks
+- **THEN** perform all verification checks
+- **AND** cross-reference artifacts for consistency

openspec/changes/add-verify-skill/tasks.md

@@ -0,0 +1,15 @@
+# Tasks: Add /opsx:verify Skill
+
+## 1. Skill Template Functions
+- [x] 1.1 Add `getVerifyChangeSkillTemplate()` to skill-templates.ts
+- [x] 1.2 Add `getOpsxVerifyCommandTemplate()` to skill-templates.ts
+
+## 2. Integration with artifact-experimental-setup
+- [x] 2.1 Import verify template functions in artifact-workflow.ts
+- [x] 2.2 Add verify to skills array in artifactExperimentalSetupCommand
+- [x] 2.3 Add verify to commands array in artifactExperimentalSetupCommand
+- [x] 2.4 Add verify to help text output
+
+## 3. Verification (Build & Test)
+- [x] 3.1 Verify TypeScript compilation succeeds
+- [x] 3.2 Verify all 8 skills are now included (was 7, now 8)

openspec/changes/archive/2025-12-23-extend-shell-completions/proposal.md

@@ -0,0 +1,15 @@
+# Change Proposal: Extend Shell Completions
+
+## Why
+
+Zsh completions provide an excellent developer experience, but many developers use bash, fish, or PowerShell. Extending completion support to these shells removes friction for the majority of developers who don't use Zsh.
+
+## What Changes
+
+This change adds bash, fish, and PowerShell completion support following the same architectural patterns, documentation methodology, and testing rigor established for Zsh completions.
+
+## Deltas
+
+- **Spec:** `cli-completion`
+  - **Operation:** MODIFIED
+  - **Description:** Extend completion generation, installation, and testing requirements to support bash, fish, and PowerShell while maintaining the existing Zsh implementation and architectural patterns

openspec/changes/archive/2025-12-23-extend-shell-completions/specs/cli-completion/spec.md

@@ -0,0 +1,328 @@
+# cli-completion Spec Delta
+
+## MODIFIED Requirements
+
+### Requirement: Native Shell Behavior Integration
+
+The completion system SHALL respect and integrate with each supported shell'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: Bash native completion
+
+- **WHEN** generating Bash completion scripts
+- **THEN** use Bash completion with `complete` builtin and `COMPREPLY` array
+- **AND** completions SHALL trigger on double TAB (standard Bash behavior)
+- **AND** display as space-separated list or column format
+- **AND** support both bash-completion v1 and v2 patterns
+
+#### Scenario: Fish native completion
+
+- **WHEN** generating Fish completion scripts
+- **THEN** use Fish's `complete` command with conditions
+- **AND** completions SHALL trigger on single TAB with auto-suggestion preview
+- **AND** display with Fish's native coloring and description alignment
+- **AND** leverage Fish's built-in caching automatically
+
+#### Scenario: PowerShell native completion
+
+- **WHEN** generating PowerShell completion scripts
+- **THEN** use `Register-ArgumentCompleter` with scriptblock
+- **AND** completions SHALL trigger on TAB with cycling behavior
+- **AND** display with PowerShell's native completion UI
+- **AND** support both Windows PowerShell 5.1 and PowerShell Core 7+
+
+#### Scenario: No custom UX patterns
+
+- **WHEN** implementing completion for any shell
+- **THEN** do NOT attempt to customize completion trigger behavior
+- **AND** do NOT override shell-specific navigation patterns
+- **AND** ensure completions feel native to experienced users of that 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 one of: `zsh`, `bash`, `fish`, `powershell`
+- **AND** throw an error if the shell is not supported
+
+#### Scenario: Detecting Bash from environment
+
+- **WHEN** `$SHELL` contains `bash` in the path
+- **THEN** detect shell as `bash`
+- **AND** proceed with bash-specific completion logic
+
+#### Scenario: Detecting Fish from environment
+
+- **WHEN** `$SHELL` contains `fish` in the path
+- **THEN** detect shell as `fish`
+- **AND** proceed with fish-specific completion logic
+
+#### Scenario: Detecting PowerShell from environment
+
+- **WHEN** `$PSModulePath` environment variable is present
+- **THEN** detect shell as `powershell`
+- **AND** proceed with PowerShell-specific completion logic
+
+#### Scenario: Unsupported shell detection
+
+- **WHEN** shell path indicates an unsupported shell
+- **THEN** throw error: "Shell '<name>' is not supported. Supported shells: zsh, bash, fish, powershell"
+
+### Requirement: Completion Generation
+
+The completion command SHALL generate completion scripts for all supported shells on demand.
+
+#### Scenario: Generating Zsh completion
+
+- **WHEN** user executes `openspec completion generate zsh`
+- **THEN** output a complete Zsh completion script to stdout
+- **AND** include completions for all commands: init, list, show, validate, archive, view, update, change, spec, completion
+- **AND** include all command-specific flags and options
+- **AND** use Zsh's `_arguments` and `_describe` built-in functions
+- **AND** support dynamic completion for change and spec IDs
+
+#### Scenario: Generating Bash completion
+
+- **WHEN** user executes `openspec completion generate bash`
+- **THEN** output a complete Bash completion script to stdout
+- **AND** include completions for all commands and subcommands
+- **AND** use `complete -F` with custom completion function
+- **AND** populate `COMPREPLY` with appropriate suggestions
+- **AND** support dynamic completion for change and spec IDs via `openspec __complete`
+
+#### Scenario: Generating Fish completion
+
+- **WHEN** user executes `openspec completion generate fish`
+- **THEN** output a complete Fish completion script to stdout
+- **AND** use `complete -c openspec` with conditions
+- **AND** include command-specific completions with `--condition` predicates
+- **AND** support dynamic completion for change and spec IDs via `openspec __complete`
+- **AND** include descriptions for each completion option
+
+#### Scenario: Generating PowerShell completion
+
+- **WHEN** user executes `openspec completion generate powershell`
+- **THEN** output a complete PowerShell completion script to stdout
+- **AND** use `Register-ArgumentCompleter -CommandName openspec`
+- **AND** implement scriptblock that handles command context
+- **AND** support dynamic completion for change and spec IDs via `openspec __complete`
+- **AND** return `[System.Management.Automation.CompletionResult]` objects
+
+### Requirement: Installation Automation
+
+The completion command SHALL automatically install completion scripts into shell configuration files for all supported shells.
+
+#### 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: Installing for Bash with bash-completion
+
+- **WHEN** user executes `openspec completion install bash`
+- **THEN** detect if bash-completion is installed by checking for `/usr/share/bash-completion` or `/etc/bash_completion.d`
+- **AND** if bash-completion is available, write to `/etc/bash_completion.d/openspec` (with sudo) or `~/.local/share/bash-completion/completions/openspec`
+- **AND** if bash-completion is not available, write to `~/.bash_completion.d/openspec` and source it from `~/.bashrc`
+- **AND** add sourcing line to `~/.bashrc` using marker-based updates if needed
+- **AND** display success message with instruction to run `exec bash` or restart terminal
+
+#### Scenario: Installing for Fish
+
+- **WHEN** user executes `openspec completion install fish`
+- **THEN** create Fish completions directory at `~/.config/fish/completions/` if it doesn't exist
+- **AND** write completion script to `~/.config/fish/completions/openspec.fish`
+- **AND** Fish automatically loads completions from this directory (no config file modification needed)
+- **AND** display success message indicating completions are immediately available
+
+#### Scenario: Installing for PowerShell
+
+- **WHEN** user executes `openspec completion install powershell`
+- **THEN** detect PowerShell profile location via `$PROFILE` environment variable or default paths
+- **AND** create profile directory if it doesn't exist
+- **AND** add completion script import to profile using marker-based updates
+- **AND** write completion script to PowerShell modules directory or alongside profile
+- **AND** display success message with instruction to restart PowerShell or run `. $PROFILE`
+
+#### Scenario: Auto-detecting shell for installation
+
+- **WHEN** user executes `openspec completion install` without specifying a shell
+- **THEN** detect current shell using shell detection logic
+- **AND** install completion for the detected shell (zsh, bash, fish, or powershell)
+- **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 for all supported shells.
+
+#### Scenario: Uninstalling Zsh completion
+
+- **WHEN** user executes `openspec completion uninstall zsh`
+- **THEN** prompt for confirmation before proceeding (unless `--yes` flag provided)
+- **AND** if user declines, cancel uninstall and display "Uninstall cancelled."
+- **AND** if user confirms, remove `~/.oh-my-zsh/custom/completions/_openspec` if Oh My Zsh is detected
+- **AND** remove `~/.zsh/completions/_openspec` if standard Zsh setup is detected
+- **AND** remove fpath modifications from `~/.zshrc` using marker-based removal
+- **AND** display success message
+
+#### Scenario: Uninstalling Bash completion
+
+- **WHEN** user executes `openspec completion uninstall bash`
+- **THEN** prompt for confirmation (unless `--yes` flag provided)
+- **AND** if user confirms, remove completion file from bash-completion directory or `~/.bash_completion.d/`
+- **AND** remove sourcing lines from `~/.bashrc` using marker-based removal
+- **AND** display success message
+
+#### Scenario: Uninstalling Fish completion
+
+- **WHEN** user executes `openspec completion uninstall fish`
+- **THEN** prompt for confirmation (unless `--yes` flag provided)
+- **AND** if user confirms, remove `~/.config/fish/completions/openspec.fish`
+- **AND** display success message (no config file modification needed)
+
+#### Scenario: Uninstalling PowerShell completion
+
+- **WHEN** user executes `openspec completion uninstall powershell`
+- **THEN** prompt for confirmation (unless `--yes` flag provided)
+- **AND** if user confirms, remove completion import from PowerShell profile using marker-based removal
+- **AND** remove completion script file
+- **AND** display success message
+
+#### Scenario: Auto-detecting shell for uninstallation
+
+- **WHEN** user executes `openspec completion uninstall` without specifying a shell
+- **THEN** detect current shell and uninstall completion for that shell
+
+#### Scenario: Not installed
+
+- **WHEN** attempting to uninstall completion that isn't installed
+- **THEN** display error message indicating completion is not installed
+- **AND** exit with code 1
+
+### Requirement: Architecture Patterns
+
+The completion implementation SHALL follow clean architecture principles with TypeScript best practices, supporting multiple shells through a plugin-based pattern.
+
+#### Scenario: Shell-specific generators
+
+- **WHEN** implementing completion generators
+- **THEN** create generator classes for each shell: `ZshGenerator`, `BashGenerator`, `FishGenerator`, `PowerShellGenerator`
+- **AND** implement a common `CompletionGenerator` interface with method:
+  - `generate(commands: CommandDefinition[]): string` - Returns complete shell script
+- **AND** each generator handles shell-specific syntax, escaping, and patterns
+- **AND** all generators consume the same `CommandDefinition[]` from the command registry
+
+#### Scenario: Shell-specific installers
+
+- **WHEN** implementing completion installers
+- **THEN** create installer classes for each shell: `ZshInstaller`, `BashInstaller`, `FishInstaller`, `PowerShellInstaller`
+- **AND** implement a common `CompletionInstaller` interface with methods:
+  - `install(script: string): Promise<InstallationResult>` - Installs completion script
+  - `uninstall(): Promise<{ success: boolean; message: string }>` - Removes completion
+- **AND** each installer handles shell-specific paths, config files, and installation patterns
+
+#### Scenario: Factory pattern for shell selection
+
+- **WHEN** selecting shell-specific implementation
+- **THEN** use `CompletionFactory` class with static methods:
+  - `createGenerator(shell: SupportedShell): CompletionGenerator`
+  - `createInstaller(shell: SupportedShell): CompletionInstaller`
+- **AND** factory uses switch statements with TypeScript exhaustiveness checking
+- **AND** adding new shell requires updating `SupportedShell` type and factory cases
+
+#### 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
+  - `acceptsPositional: boolean` - Whether command takes positional arguments
+  - `positionalType: string` - Type of positional (change-id, spec-id, path, shell)
+  - `subcommands?: CommandDefinition[]` - Nested subcommands
+- **AND** export a `COMMAND_REGISTRY` constant with all command definitions
+- **AND** all generators consume this registry to ensure consistency across shells
+
+#### Scenario: Type-safe shell detection
+
+- **WHEN** implementing shell detection
+- **THEN** define a `SupportedShell` type as literal type: `'zsh' | 'bash' | 'fish' | 'powershell'`
+- **AND** implement `detectShell()` function in `src/utils/shell-detection.ts`
+- **AND** return detected shell or throw error with supported shells list
+
+### Requirement: Testing Support
+
+The completion implementation SHALL be testable with unit and integration tests for all supported shells.
+
+#### Scenario: Mock shell environment
+
+- **WHEN** writing tests for shell detection
+- **THEN** allow overriding `$SHELL` and `$PSModulePath` environment variables
+- **AND** use dependency injection for file system operations
+- **AND** test detection for all four shells independently
+
+#### Scenario: Generator output verification
+
+- **WHEN** testing completion generators
+- **THEN** create test suite for each shell generator (zsh, bash, fish, powershell)
+- **AND** verify generated scripts contain expected patterns for that shell
+- **AND** test that command registry is properly consumed
+- **AND** ensure dynamic completion placeholders are present
+- **AND** verify shell-specific syntax and escaping
+
+#### Scenario: Installer simulation
+
+- **WHEN** testing installation logic
+- **THEN** create test suite for each shell installer
+- **AND** use temporary test directories instead of actual home directories
+- **AND** verify file creation without modifying real shell configurations
+- **AND** test path resolution logic independently
+- **AND** mock file system operations to avoid side effects
+
+#### Scenario: Cross-shell consistency
+
+- **WHEN** testing completion behavior
+- **THEN** verify all shells support the same commands and flags
+- **AND** verify dynamic completions work consistently across shells
+- **AND** ensure error messages are consistent across shells

openspec/changes/archive/2025-12-23-extend-shell-completions/tasks.md

@@ -0,0 +1,49 @@
+# Implementation Tasks
+
+## Phase 1: Foundation and Bash Support
+
+- [x] Update `SupportedShell` type in `src/utils/shell-detection.ts` to include `'bash' | 'fish' | 'powershell'`
+- [x] Extend shell detection logic to recognize bash, fish, and PowerShell from environment variables
+- [x] Create `src/core/completions/generators/bash-generator.ts` implementing `CompletionGenerator` interface
+- [x] Create `src/core/completions/installers/bash-installer.ts` implementing `CompletionInstaller` interface
+- [x] Update `CompletionFactory.createGenerator()` to support bash
+- [x] Update `CompletionFactory.createInstaller()` to support bash
+- [x] Create test file `test/core/completions/generators/bash-generator.test.ts` mirroring zsh test structure
+- [x] Create test file `test/core/completions/installers/bash-installer.test.ts` mirroring zsh test structure
+- [x] Verify bash completions work manually: `openspec completion install bash && exec bash`
+
+## Phase 2: Fish Support
+
+- [x] Create `src/core/completions/generators/fish-generator.ts` implementing `CompletionGenerator` interface
+- [x] Create `src/core/completions/installers/fish-installer.ts` implementing `CompletionInstaller` interface
+- [x] Update `CompletionFactory.createGenerator()` to support fish
+- [x] Update `CompletionFactory.createInstaller()` to support fish
+- [x] Create test file `test/core/completions/generators/fish-generator.test.ts`
+- [x] Create test file `test/core/completions/installers/fish-installer.test.ts`
+- [x] Verify fish completions work manually: `openspec completion install fish`
+
+## Phase 3: PowerShell Support
+
+- [x] Create `src/core/completions/generators/powershell-generator.ts` implementing `CompletionGenerator` interface
+- [x] Create `src/core/completions/installers/powershell-installer.ts` implementing `CompletionInstaller` interface
+- [x] Update `CompletionFactory.createGenerator()` to support powershell
+- [x] Update `CompletionFactory.createInstaller()` to support powershell
+- [x] Create test file `test/core/completions/generators/powershell-generator.test.ts`
+- [x] Create test file `test/core/completions/installers/powershell-installer.test.ts`
+- [x] Verify PowerShell completions work manually on Windows or macOS PowerShell
+
+## Phase 4: Documentation and Testing
+
+- [x] Update `CLAUDE.md` or relevant documentation to mention all four supported shells
+- [x] Add cross-shell consistency test verifying all shells support same commands
+- [x] Run `pnpm test` to ensure all tests pass
+- [x] Run `pnpm run build` to verify TypeScript compilation
+- [x] Test all shells on different platforms (Linux for bash/fish/zsh, Windows/macOS for PowerShell)
+
+## Phase 5: Validation and Cleanup
+
+- [x] Run `openspec validate extend-shell-completions --strict` and resolve all issues
+- [x] Update error messages to list all four supported shells
+- [x] Verify `openspec completion --help` documentation is current
+- [x] Test auto-detection works for all shells
+- [x] Ensure uninstall works cleanly for all shells

openspec/changes/archive/2025-12-30-add-antigravity-support/specs/cli-init/spec.md

@@ -0,0 +1,105 @@
+# Delta for CLI Init
+
+## 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
+
+#### 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 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
+
+#### Scenario: Generating slash commands for Gemini CLI
+- **WHEN** the user selects Gemini CLI during initialization
+- **THEN** create `.gemini/commands/openspec/proposal.toml`, `.gemini/commands/openspec/apply.toml`, and `.gemini/commands/openspec/archive.toml`
+- **AND** populate each file as TOML that sets a stage-specific `description = "<summary>"` and a multi-line `prompt = """` block with the shared OpenSpec template
+- **AND** wrap the OpenSpec managed markers (`<!-- OPENSPEC:START -->` / `<!-- OPENSPEC:END -->`) inside the `prompt` value so `openspec update` can safely refresh the body between markers without touching the TOML framing
+- **AND** ensure the slash-command copy matches the existing proposal/apply/archive templates used by other tools
+
+#### Scenario: Generating slash commands for iFlow CLI
+- **WHEN** the user selects iFlow CLI during initialization
+- **THEN** create `.iflow/commands/openspec-proposal.md`, `.iflow/commands/openspec-apply.md`, and `.iflow/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include YAML frontmatter with `name`, `id`, `category`, and `description` fields for each command
+- **AND** wrap the generated content in OpenSpec managed markers so `openspec update` can safely refresh the commands
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for RooCode
+- **WHEN** the user selects RooCode during initialization
+- **THEN** create `.roo/commands/openspec-proposal.md`, `.roo/commands/openspec-apply.md`, and `.roo/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include simple Markdown headings (e.g., `# OpenSpec: Proposal`) without YAML frontmatter
+- **AND** wrap the generated content in OpenSpec managed markers where applicable so `openspec update` can safely refresh the commands
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage

openspec/changes/archive/2025-12-30-add-antigravity-support/specs/cli-update/spec.md

@@ -0,0 +1,92 @@
+# Delta for CLI Update
+
+## 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
+
+#### 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 CodeBuddy Code
+- **WHEN** `.codebuddy/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 Cline
+- **WHEN** `.clinerules/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Crush
+- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **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
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+#### 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: Updating slash commands for Gemini CLI
+- **WHEN** `.gemini/commands/openspec/` contains `proposal.toml`, `apply.toml`, and `archive.toml`
+- **THEN** refresh the body of each file using the shared proposal/apply/archive templates
+- **AND** replace only the content between `<!-- OPENSPEC:START -->` and `<!-- OPENSPEC:END -->` markers inside the `prompt = """` block so the TOML framing (`description`, `prompt`) stays intact
+- **AND** skip creating any missing `.toml` files during update; only pre-existing Gemini commands are refreshed
+
+#### Scenario: Updating slash commands for iFlow CLI
+- **WHEN** `.iflow/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** preserve the YAML frontmatter with `name`, `id`, `category`, and `description` fields
+- **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

openspec/changes/archive/2025-12-30-fix-cline-workflows-implementation/proposal.md

@@ -8,6 +8,6 @@ The Cline implementation was architecturally incorrect. According to Cline's off
 - **BREAKING**: Existing Cline users will need to re-run `openspec init` to get the corrected workflow files
 
 ## Impact
-- Affected specs: cli-init (corrected Cline workflow paths)
+- Affected specs: cli-init, cli-update (corrected Cline workflow paths)
 - Affected code: `src/core/configurators/slash/cline.ts`, test files, README.md
 - Modified files: `.clinerules/workflows/openspec-*.md` (moved from `.clinerules/openspec-*.md`)

openspec/changes/archive/2025-12-30-fix-cline-workflows-implementation/specs/cli-init/spec.md

@@ -0,0 +1,105 @@
+# Delta for CLI Init
+
+## 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
+
+#### 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/workflows/openspec-proposal.md`, `.clinerules/workflows/openspec-apply.md`, and `.clinerules/workflows/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 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
+
+#### Scenario: Generating slash commands for Gemini CLI
+- **WHEN** the user selects Gemini CLI during initialization
+- **THEN** create `.gemini/commands/openspec/proposal.toml`, `.gemini/commands/openspec/apply.toml`, and `.gemini/commands/openspec/archive.toml`
+- **AND** populate each file as TOML that sets a stage-specific `description = "<summary>"` and a multi-line `prompt = """` block with the shared OpenSpec template
+- **AND** wrap the OpenSpec managed markers (`<!-- OPENSPEC:START -->` / `<!-- OPENSPEC:END -->`) inside the `prompt` value so `openspec update` can safely refresh the body between markers without touching the TOML framing
+- **AND** ensure the slash-command copy matches the existing proposal/apply/archive templates used by other tools
+
+#### Scenario: Generating slash commands for iFlow CLI
+- **WHEN** the user selects iFlow CLI during initialization
+- **THEN** create `.iflow/commands/openspec-proposal.md`, `.iflow/commands/openspec-apply.md`, and `.iflow/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include YAML frontmatter with `name`, `id`, `category`, and `description` fields for each command
+- **AND** wrap the generated content in OpenSpec managed markers so `openspec update` can safely refresh the commands
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage
+
+#### Scenario: Generating slash commands for RooCode
+- **WHEN** the user selects RooCode during initialization
+- **THEN** create `.roo/commands/openspec-proposal.md`, `.roo/commands/openspec-apply.md`, and `.roo/commands/openspec-archive.md`
+- **AND** populate each file from shared templates so command text matches other tools
+- **AND** include simple Markdown headings (e.g., `# OpenSpec: Proposal`) without YAML frontmatter
+- **AND** wrap the generated content in OpenSpec managed markers where applicable so `openspec update` can safely refresh the commands
+- **AND** each template includes instructions for the relevant OpenSpec workflow stage

openspec/changes/archive/2025-12-30-fix-cline-workflows-implementation/specs/cli-update/spec.md

@@ -0,0 +1,92 @@
+# Delta for CLI Update
+
+## 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
+
+#### 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 CodeBuddy Code
+- **WHEN** `.codebuddy/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 Cline
+- **WHEN** `.clinerules/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Crush
+- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **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
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+#### 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: Updating slash commands for Gemini CLI
+- **WHEN** `.gemini/commands/openspec/` contains `proposal.toml`, `apply.toml`, and `archive.toml`
+- **THEN** refresh the body of each file using the shared proposal/apply/archive templates
+- **AND** replace only the content between `<!-- OPENSPEC:START -->` and `<!-- OPENSPEC:END -->` markers inside the `prompt = """` block so the TOML framing (`description`, `prompt`) stays intact
+- **AND** skip creating any missing `.toml` files during update; only pre-existing Gemini commands are refreshed
+
+#### Scenario: Updating slash commands for iFlow CLI
+- **WHEN** `.iflow/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** preserve the YAML frontmatter with `name`, `id`, `category`, and `description` fields
+- **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

openspec/changes/archive/2026-01-06-add-agent-schema-selection/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+With per-change schema metadata in place (see `add-per-change-schema-metadata`), agents can now create changes with different workflow schemas. However, the agent skills are still hardcoded to `spec-driven` artifacts and don't offer schema selection to users.
+
+## What Changes
+
+**Scope: Experimental artifact workflow agent skills**
+
+**Depends on:** `add-per-change-schema-metadata` (must be implemented first)
+
+- Update `openspec-new-change` skill to prompt user for schema selection
+- Update `openspec-continue-change` skill to work with any schema's artifacts
+- Update `openspec-apply-change` skill to handle schema-specific task structures
+- Add schema descriptions to help users choose appropriate workflow
+
+## Capabilities
+
+### Modified Capabilities
+- `cli-artifact-workflow`: Agent skills support dynamic schema selection
+
+## Impact
+
+- **Affected code**: `src/core/templates/skill-templates.ts`
+- **User experience**: Users can choose TDD, spec-driven, or future workflows when starting a change
+- **Agent behavior**: Skills read artifact list from schema rather than hardcoding
+- **Backward compatible**: Default remains `spec-driven` if user doesn't choose

openspec/changes/archive/2026-01-06-add-agent-schema-selection/tasks.md

@@ -0,0 +1,32 @@
+## Prerequisites
+
+- [x] 0.1 Implement `add-per-change-schema-metadata` change first
+
+## 1. Schema Discovery
+
+- [x] 1.1 Add CLI command or helper to list schemas with descriptions (for agent use)
+- [x] 1.2 Ensure `openspec templates --schema <name>` returns artifact list for any schema
+
+## 2. Update New Change Skill
+
+- [x] 2.1 Add schema selection prompt using AskUserQuestion tool
+- [x] 2.2 Present available schemas with descriptions (spec-driven, tdd, etc.)
+- [x] 2.3 Pass selected schema to `openspec new change --schema <name>`
+- [x] 2.4 Update output to show which schema/workflow was selected
+
+## 3. Update Continue Change Skill
+
+- [x] 3.1 Remove hardcoded artifact references (proposal, specs, design, tasks)
+- [x] 3.2 Read artifact list dynamically from `openspec status --json`
+- [x] 3.3 Adjust artifact creation guidelines to be schema-agnostic
+- [x] 3.4 Handle schema-specific artifact types (e.g., TDD's `tests` artifact)
+
+## 4. Update Apply Change Skill
+
+- [x] 4.1 Make task detection work with different schema structures
+- [x] 4.2 Adjust context file reading for schema-specific artifacts
+
+## 5. Documentation
+
+- [x] 5.1 Add schema descriptions to help text or skill instructions
+- [x] 5.2 Document when to use each schema (TDD for bug fixes, spec-driven for features, etc.)

openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/design.md

@@ -0,0 +1,147 @@
+## Context
+
+The experimental artifact workflow supports multiple schemas (`spec-driven`, `tdd`), but schema selection must be passed on every command. This creates friction for agents and users.
+
+We need a lightweight metadata file to persist the schema choice per change.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Store schema choice once at change creation
+- Auto-detect schema in experimental workflow commands
+- Maintain backward compatibility (no metadata = default)
+- Validate metadata with Zod schema
+
+**Non-Goals:**
+- Migrate existing changes (they use default)
+- Extend to legacy commands
+- Store additional metadata beyond schema (keep minimal for now)
+
+## Decisions
+
+### Decision: Zod Schema Design
+
+The metadata file (`.openspec.yaml`) will be validated with this Zod schema:
+
+```typescript
+// src/core/artifact-graph/types.ts (or new metadata.ts)
+
+import { z } from 'zod';
+import { listSchemas } from './resolver.js';
+
+/**
+ * Schema for per-change metadata stored in .openspec.yaml
+ */
+export const ChangeMetadataSchema = z.object({
+  // Required: which workflow schema this change uses
+  schema: z.string().min(1, { message: 'schema is required' }).refine(
+    (val) => listSchemas().includes(val),
+    (val) => ({ message: `Unknown schema '${val}'. Available: ${listSchemas().join(', ')}` })
+  ),
+
+  // Optional: creation timestamp (ISO date string)
+  created: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+    message: 'created must be YYYY-MM-DD format'
+  }).optional(),
+});
+
+export type ChangeMetadata = z.infer<typeof ChangeMetadataSchema>;
+```
+
+**Rationale:**
+- `schema` is required and validated against available schemas at parse time
+- `created` is optional, ISO date format for consistency
+- Minimal fields - can extend later without breaking existing files
+- Follows existing codebase pattern (see `ArtifactSchema`, `SchemaYamlSchema`)
+
+### Decision: File Location and Format
+
+**Location:** `openspec/changes/<name>/.openspec.yaml`
+
+**Format:**
+```yaml
+schema: tdd
+created: 2025-01-05
+```
+
+**Alternatives considered:**
+- `change.yaml` - less hidden, but clutters directory
+- Frontmatter in `proposal.md` - couples to proposal existence
+- `openspec.json` - YAML matches existing schema files
+
+### Decision: Read/Write Functions
+
+```typescript
+// src/utils/change-metadata.ts
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+import { ChangeMetadataSchema, type ChangeMetadata } from '../core/artifact-graph/types.js';
+
+const METADATA_FILENAME = '.openspec.yaml';
+
+export function writeChangeMetadata(
+  changeDir: string,
+  metadata: ChangeMetadata
+): void {
+  // Validate before writing
+  const validated = ChangeMetadataSchema.parse(metadata);
+  const content = yaml.stringify(validated);
+  fs.writeFileSync(path.join(changeDir, METADATA_FILENAME), content);
+}
+
+export function readChangeMetadata(
+  changeDir: string
+): ChangeMetadata | null {
+  const metaPath = path.join(changeDir, METADATA_FILENAME);
+
+  if (!fs.existsSync(metaPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(metaPath, 'utf-8');
+  const parsed = yaml.parse(content);
+
+  // Validate and return (throws ZodError if invalid)
+  return ChangeMetadataSchema.parse(parsed);
+}
+```
+
+### Decision: Schema Resolution Order
+
+When determining which schema to use:
+
+1. **Explicit `--schema` flag** (highest priority - user override)
+2. **`.openspec.yaml` metadata** (persisted choice)
+3. **Default `spec-driven`** (fallback)
+
+```typescript
+function resolveSchemaForChange(
+  changeDir: string,
+  explicitSchema?: string
+): string {
+  if (explicitSchema) return explicitSchema;
+
+  const metadata = readChangeMetadata(changeDir);
+  if (metadata?.schema) return metadata.schema;
+
+  return 'spec-driven';
+}
+```
+
+## Risks / Trade-offs
+
+- **Extra file per change** → Minimal overhead, hidden file
+- **YAML parsing dependency** → Already using `yaml` package for schema files
+- **Schema validation at read time** → Fail fast with clear error if corrupted
+
+## Migration Plan
+
+No migration needed:
+- Existing changes without `.openspec.yaml` continue to work (use default)
+- New changes created with `openspec new change --schema X` get metadata file
+
+## Open Questions
+
+- Should `openspec new change` prompt for schema interactively if not specified? (Leaning no - default is fine)

openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+Currently, the schema (workflow type) must be passed via `--schema` flag on every experimental workflow command. This is repetitive and error-prone. Agents have no way to know which schema a change uses, so they default to `spec-driven` and cannot leverage alternative workflows like `tdd`.
+
+## What Changes
+
+**Scope: Experimental artifact workflow only** (`openspec new change`, `openspec status`, `openspec instructions`, `openspec templates`)
+
+- Store schema choice in `.openspec.yaml` metadata file when creating a change via `openspec new change`
+- Auto-detect schema from metadata in experimental workflow commands
+- Make `--schema` flag optional (override only, metadata takes precedence)
+- Add `--schema` option to `openspec new change` command
+
+**Not affected**: Legacy commands (`openspec validate`, `openspec archive`, `openspec list`, `openspec show`)
+
+## Capabilities
+
+### New Capabilities
+- `change-metadata`: Reading/writing per-change metadata files
+
+### Modified Capabilities
+- `cli-artifact-workflow`: Commands auto-detect schema from change metadata
+
+## Impact
+
+- **Affected code**: `src/utils/change-utils.ts`, `src/core/artifact-graph/instruction-loader.ts`, `src/commands/artifact-workflow.ts`
+- **Agent skills**: Can be simplified - no longer need to pass schema explicitly
+- **Backward compatible**: Changes without `.openspec.yaml` fall back to `spec-driven` default
+- **Isolation**: All changes contained within experimental workflow code; legacy commands untouched

openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,98 @@
+## ADDED Requirements
+
+### Requirement: Change Metadata
+
+The system SHALL store and validate per-change metadata in `.openspec.yaml` files using a Zod schema.
+
+#### Scenario: Metadata file created with new change
+
+- **WHEN** user runs `openspec new change add-feature --schema tdd`
+- **THEN** the system creates `.openspec.yaml` in the change directory
+- **AND** the file contains `schema: tdd` and `created: <YYYY-MM-DD>`
+
+#### Scenario: Metadata validated on read
+
+- **WHEN** the system reads `.openspec.yaml`
+- **AND** the `schema` field references an unknown schema
+- **THEN** the system displays a validation error listing available schemas
+
+#### Scenario: Metadata schema validation
+
+- **WHEN** `.openspec.yaml` contains invalid YAML or missing required fields
+- **THEN** the system displays a Zod validation error with details
+
+#### Scenario: Missing metadata file
+
+- **WHEN** a change directory has no `.openspec.yaml` file
+- **THEN** the system falls back to the default schema (`spec-driven`)
+
+## MODIFIED Requirements
+
+### Requirement: New Change Command
+
+The system SHALL create new change directories with validation and optional schema metadata.
+
+#### Scenario: Create valid change
+
+- **WHEN** user runs `openspec new change add-feature`
+- **THEN** the system creates `openspec/changes/add-feature/` directory
+- **AND** creates `.openspec.yaml` with `schema: spec-driven` (default)
+
+#### Scenario: Create change with schema
+
+- **WHEN** user runs `openspec new change add-feature --schema tdd`
+- **THEN** the system creates `openspec/changes/add-feature/` directory
+- **AND** creates `.openspec.yaml` with `schema: tdd`
+
+#### Scenario: Invalid schema on create
+
+- **WHEN** user runs `openspec new change add-feature --schema unknown`
+- **THEN** the system displays an error listing available schemas
+- **AND** does not create the change directory
+
+#### Scenario: Invalid change name
+
+- **WHEN** user runs `openspec new change "Add Feature"` with invalid name
+- **THEN** the system displays validation error with guidance
+
+#### Scenario: Duplicate change name
+
+- **WHEN** user runs `openspec new change existing-change` for an existing change
+- **THEN** the system displays an error indicating the change already exists
+
+#### Scenario: Create with description
+
+- **WHEN** user runs `openspec new change add-feature --description "Add new feature"`
+- **THEN** the system creates the change directory with description in README.md
+
+### Requirement: Schema Selection
+
+The system SHALL support custom schema selection for workflow commands, with automatic detection from change metadata.
+
+#### Scenario: Schema auto-detected from metadata
+
+- **WHEN** user runs `openspec status --change <id>` without `--schema`
+- **AND** the change has `.openspec.yaml` with `schema: tdd`
+- **THEN** the system uses the `tdd` schema
+
+#### Scenario: Explicit schema overrides metadata
+
+- **WHEN** user runs `openspec status --change <id> --schema spec-driven`
+- **AND** the change has `.openspec.yaml` with `schema: tdd`
+- **THEN** the system uses `spec-driven` (explicit flag wins)
+
+#### Scenario: Default schema fallback
+
+- **WHEN** user runs workflow commands without `--schema`
+- **AND** the change has no `.openspec.yaml` file
+- **THEN** the system uses the "spec-driven" schema
+
+#### Scenario: Custom schema via flag
+
+- **WHEN** user runs `openspec status --change <id> --schema tdd`
+- **THEN** the system uses the specified schema for artifact graph
+
+#### Scenario: Unknown schema
+
+- **WHEN** user specifies an unknown schema
+- **THEN** the system displays an error listing available schemas

openspec/changes/archive/2026-01-06-add-per-change-schema-metadata/tasks.md

@@ -0,0 +1,29 @@
+## 1. Zod Schema and Types
+
+- [x] 1.1 Add `ChangeMetadataSchema` Zod schema to `src/core/artifact-graph/types.ts`
+- [x] 1.2 Export `ChangeMetadata` type inferred from schema
+
+## 2. Core Metadata Functions
+
+- [x] 2.1 Create `src/utils/change-metadata.ts` with `writeChangeMetadata()` function
+- [x] 2.2 Add `readChangeMetadata()` function with Zod validation
+- [x] 2.3 Update `createChange()` to accept optional `schema` param and write metadata
+
+## 3. Auto-Detection in Instruction Loader
+
+- [x] 3.1 Modify `loadChangeContext()` to read schema from `.openspec.yaml`
+- [x] 3.2 Make `schemaName` parameter optional (fall back to metadata, then default)
+
+## 4. CLI Updates
+
+- [x] 4.1 Add `--schema <name>` option to `openspec new change` command
+- [x] 4.2 Verify existing commands (`status`, `instructions`) work with auto-detection
+
+## 5. Tests
+
+- [x] 5.1 Test `ChangeMetadataSchema` validates correctly (valid/invalid cases)
+- [x] 5.2 Test `writeChangeMetadata()` creates valid YAML
+- [x] 5.3 Test `readChangeMetadata()` parses and validates schema
+- [x] 5.4 Test `loadChangeContext()` auto-detects schema from metadata
+- [x] 5.5 Test fallback to default when no metadata exists
+- [x] 5.6 Test `--schema` flag overrides metadata

openspec/changes/archive/2026-01-06-add-specs-apply-command/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-06

openspec/changes/archive/2026-01-06-add-specs-apply-command/design.md

@@ -0,0 +1,77 @@
+## Context
+
+Currently, delta specs are only applied to main specs when running `openspec archive`. This bundles two concerns:
+1. Applying spec changes (delta → main)
+2. Archiving the change (move to archive folder)
+
+Users want flexibility to sync specs earlier, especially when iterating. The archive command already contains the reconciliation logic in `buildUpdatedSpec()`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Decouple spec syncing from archiving
+- Provide `/opsx:sync` skill for agents to sync specs on demand
+- Keep operation idempotent (safe to run multiple times)
+
+**Non-Goals:**
+- Tracking whether specs have been synced (no state)
+- Changing archive behavior (it will continue to apply specs)
+- Supporting partial application (all deltas sync together)
+
+## Decisions
+
+### 1. Reuse existing reconciliation logic
+
+**Decision**: Extract `buildUpdatedSpec()` logic from `ArchiveCommand` into a shared module.
+
+**Rationale**: The archive command already implements delta parsing and application. Rather than duplicate, we extract and reuse.
+
+**Alternatives considered**:
+- Duplicate logic in new command (rejected: maintenance burden)
+- Have sync call archive with flags (rejected: coupling)
+
+### 2. No state tracking
+
+**Decision**: Don't track whether specs have been synced. Each invocation reads delta and main specs, reconciles.
+
+**Rationale**:
+- Idempotent operations don't need state
+- Avoids sync issues between flag and reality
+- Simpler implementation and mental model
+
+**Alternatives considered**:
+- Track `specsSynced: true` in `.openspec.yaml` (rejected: unnecessary complexity)
+- Store snapshot of synced deltas (rejected: over-engineering)
+
+### 3. Agent-driven approach (no CLI command)
+
+**Decision**: The `/opsx:sync` skill is fully agent-driven - the agent reads delta specs and directly edits main specs.
+
+**Rationale**:
+- Allows intelligent merging (add scenarios without copying entire requirements)
+- Delta represents *intent*, not wholesale replacement
+- More flexible and natural editing workflow
+- Archive still uses programmatic merge (for finalized changes)
+
+### 4. Archive behavior unchanged
+
+**Decision**: Archive continues to apply specs as part of its flow. If specs are already reconciled, the operation is a no-op.
+
+**Rationale**: Backward compatibility. Users who don't use `/opsx:sync` get the same experience.
+
+## Risks / Trade-offs
+
+**[Risk] Multiple changes modify same spec**
+→ Last to sync wins. Same as today with archive. Users should coordinate or use sequential archives.
+
+**[Risk] User syncs specs then continues editing deltas**
+→ Running `/opsx:sync` again reconciles. Idempotent design handles this.
+
+**[Trade-off] No undo mechanism**
+→ Users can `git checkout` main specs if needed. Explicit undo command is out of scope.
+
+## Implementation Approach
+
+1. Extract spec application logic from `ArchiveCommand.buildUpdatedSpec()` into `src/core/specs-apply.ts`
+2. Add skill template for `/opsx:sync` in `skill-templates.ts`
+3. Register skill in managed skills

openspec/changes/archive/2026-01-06-add-specs-apply-command/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+Spec application is currently bundled with archive - users must run `openspec archive` to apply delta specs to main specs. This couples two distinct concerns (applying specs vs. archiving the change) and forces users to wait until they're "done" to see main specs updated. Users want the flexibility to sync specs earlier in the workflow while iterating.
+
+## What Changes
+
+- Add `/opsx:sync` skill that syncs delta specs to main specs as a standalone action
+- The operation is idempotent - safe to run multiple times, agent reconciles main specs to match deltas
+- Archive continues to work as today (applies specs if not already reconciled, then moves to archive)
+- No new state tracking - the agent reads delta and main specs, reconciles on each run
+- Agent-driven approach allows intelligent merging (partial updates, adding scenarios)
+
+**Workflow becomes:**
+```
+/opsx:new → /opsx:continue → /opsx:apply → archive
+                                  │
+                                  └── /opsx:sync (optional, anytime)
+```
+
+## Capabilities
+
+### New Capabilities
+- `specs-sync-skill`: Skill template for `/opsx:sync` command that reconciles main specs with delta specs
+
+### Modified Capabilities
+- None (agent-driven, no CLI command needed)
+
+## Impact
+
+- **Skills**: New `openspec-sync-specs` skill in `skill-templates.ts`
+- **Archive**: No changes needed - already does reconciliation, will continue to work
+- **Agent workflow**: Users gain flexibility to sync specs before archive

openspec/changes/archive/2026-01-06-add-specs-apply-command/specs/specs-sync-skill/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: Specs Sync Skill
+The system SHALL provide an `/opsx:sync` skill that syncs delta specs from a change to the main specs.
+
+#### Scenario: Sync delta specs to main specs
+- **WHEN** agent executes `/opsx:sync` with a change name
+- **THEN** the agent reads delta specs from `openspec/changes/<name>/specs/`
+- **AND** reads corresponding main specs from `openspec/specs/`
+- **AND** reconciles main specs to match what the deltas describe
+
+#### Scenario: Idempotent operation
+- **WHEN** agent executes `/opsx:sync` multiple times on the same change
+- **THEN** the result is the same as running it once
+- **AND** no duplicate requirements are created
+
+#### Scenario: Change selection prompt
+- **WHEN** agent executes `/opsx:sync` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows changes that have delta specs
+
+### Requirement: Delta Reconciliation Logic
+The agent SHALL reconcile main specs with delta specs using the delta operation headers.
+
+#### Scenario: ADDED requirements
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** the requirement does not exist in main spec
+- **THEN** add the requirement to main spec
+
+#### Scenario: ADDED requirement already exists
+- **WHEN** delta contains `## ADDED Requirements` with a requirement
+- **AND** a requirement with the same name already exists in main spec
+- **THEN** update the existing requirement to match the delta version
+
+#### Scenario: MODIFIED requirements
+- **WHEN** delta contains `## MODIFIED Requirements` with a requirement
+- **AND** the requirement exists in main spec
+- **THEN** replace the requirement in main spec with the delta version
+
+#### Scenario: REMOVED requirements
+- **WHEN** delta contains `## REMOVED Requirements` with a requirement name
+- **AND** the requirement exists in main spec
+- **THEN** remove the requirement from main spec
+
+#### Scenario: RENAMED requirements
+- **WHEN** delta contains `## RENAMED Requirements` with FROM:/TO: format
+- **AND** the FROM requirement exists in main spec
+- **THEN** rename the requirement to the TO name
+
+#### Scenario: New capability spec
+- **WHEN** delta spec exists for a capability not in main specs
+- **THEN** create new main spec file at `openspec/specs/<capability>/spec.md`
+
+### Requirement: Skill Output
+The skill SHALL provide clear feedback on what was synced.
+
+#### Scenario: Show synced changes
+- **WHEN** reconciliation completes successfully
+- **THEN** display summary of changes per capability:
+  - Number of requirements added
+  - Number of requirements modified
+  - Number of requirements removed
+  - Number of requirements renamed
+
+#### Scenario: No changes needed
+- **WHEN** main specs already match delta specs
+- **THEN** display "Specs already in sync - no changes needed"

openspec/changes/archive/2026-01-06-add-specs-apply-command/tasks.md

@@ -0,0 +1,40 @@
+## Tasks
+
+### Core Implementation
+
+- [x] Extract spec application logic from `ArchiveCommand` into `src/core/specs-apply.ts`
+  - Move `buildUpdatedSpec()`, `findSpecUpdates()`, `writeUpdatedSpec()` to shared module
+  - Keep `ArchiveCommand` importing from the new module
+  - Ensure all validation logic is preserved
+
+### Skill Template
+
+- [x] Add `getSyncSpecsSkillTemplate()` function in `src/core/templates/skill-templates.ts`
+  - Skill name: `openspec-sync-specs`
+  - Description: Sync delta specs to main specs
+  - **Agent-driven**: Instructions for agent to read deltas and edit main specs directly
+
+- [x] Add `/opsx:sync` slash command template in `skill-templates.ts`
+  - Mirror the skill template for slash command format
+  - **Agent-driven**: No CLI command, agent does the merge
+
+### Registration
+
+- [x] Register skill in managed skills (via `artifact-experimental-setup`)
+  - Add to skill list with appropriate metadata
+  - Ensure it appears in setup output
+
+### Design Decision
+
+**Why agent-driven instead of CLI-driven?**
+
+The programmatic merge operates at requirement-level granularity:
+- MODIFIED requires copying ALL scenarios, not just the changed ones
+- If agent forgets a scenario, it gets deleted
+- Delta specs become bloated with copied content
+
+Agent-driven approach:
+- Agent can apply partial updates (add a scenario without copying others)
+- Delta represents *intent*, not wholesale replacement
+- More flexible and natural editing workflow
+- Archive still uses programmatic merge (for finalized changes)

openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/proposal.md

@@ -0,0 +1,138 @@
+## Why
+
+The `generateApplyInstructions` function is hardcoded to check for `spec-driven` artifacts (`proposal.md`, `specs/`, `design.md`, `tasks.md`). If a user selects a different schema like `tdd`, the apply instructions are meaningless - they check for files that don't exist in that schema.
+
+This blocks the experimental workflow from supporting multiple schemas properly.
+
+## What Changes
+
+**Scope: Experimental artifact workflow** (`openspec instructions apply`)
+
+**Depends on:** `add-per-change-schema-metadata` (to know which schema a change uses)
+
+- Make `generateApplyInstructions` read artifact definitions from the schema
+- Dynamically determine which artifacts exist based on schema
+- Define when a change becomes "implementable" (see Design Decision below)
+- Generate schema-appropriate context files and instructions
+
+## Design Decision: When is a change implementable?
+
+This is the key question. Different approaches:
+
+### Option A: Explicit `apply` artifact in schema
+
+Add a field to mark which artifact is the "implementation gate":
+
+```yaml
+artifacts:
+  - id: tasks
+    generates: tasks.md
+    apply: true  # ← This artifact triggers apply mode
+```
+
+**Pros:** Explicit, flexible
+**Cons:** Another field to maintain, what if multiple artifacts are `apply: true`?
+
+### Option B: Leaf artifacts are implementable
+
+The artifact(s) with no dependents (nothing depends on them) are the apply target.
+
+- `spec-driven`: `tasks` is a leaf → apply = execute tasks
+- `tdd`: `docs` is a leaf → but that doesn't make sense for TDD...
+
+**Pros:** No extra schema field, derived from graph
+**Cons:** Doesn't match TDD semantics (implementation is the action, not docs)
+
+### Option C: Schema-level `apply_phase` definition
+
+Add a top-level field to the schema:
+
+```yaml
+name: spec-driven
+apply_phase:
+  requires: [tasks]  # Must exist before apply
+  tracks: tasks.md   # File with checkboxes to track
+  instruction: "Work through tasks, mark complete as you go"
+```
+
+```yaml
+name: tdd
+apply_phase:
+  requires: [tests]  # Must have tests before implementing
+  tracks: null       # No checkbox tracking - just make tests pass
+  instruction: "Run tests, implement until green, refactor"
+```
+
+**Pros:** Full flexibility, schema controls its own apply semantics
+**Cons:** More complex schema format
+
+### Option D: Convention-based (artifact ID matching)
+
+If artifact ID is `tasks` or `implementation`, it's the apply target.
+
+**Pros:** Simple, no schema changes
+**Cons:** Brittle, doesn't work for custom schemas
+
+### Option E: All artifacts complete → apply available
+
+Apply becomes available when ALL schema artifacts exist. Implementation is whatever the user does after planning.
+
+**Pros:** Simple, no schema changes
+**Cons:** Doesn't guide what "apply" means for different workflows
+
+---
+
+## Decision: Add `apply` block to schema.yaml
+
+Add a top-level `apply` field to schema definitions:
+
+```yaml
+name: spec-driven
+version: 1
+description: Default OpenSpec workflow
+
+artifacts:
+  # ... existing artifacts ...
+
+apply:
+  requires: [tasks]           # Artifacts that must exist before apply
+  tracks: tasks.md            # File with checkboxes for progress (optional)
+  instruction: |              # Guidance shown to agent
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.
+```
+
+```yaml
+name: tdd
+version: 1
+description: Test-driven development workflow
+
+artifacts:
+  # ... existing artifacts ...
+
+apply:
+  requires: [tests]           # Must have tests before implementing
+  tracks: null                # No checkbox tracking
+  instruction: |
+    Run tests to see failures. Implement minimal code to pass each test.
+    Refactor while keeping tests green.
+```
+
+**Key properties:**
+- `requires`: Array of artifact IDs that must exist before apply is available
+- `tracks`: Path to file with checkboxes (relative to change dir), or `null` if no tracking
+- `instruction`: Custom guidance for the apply phase
+
+**Fallback behavior:** Schemas without `apply` block default to "all artifacts must exist"
+
+## Capabilities
+
+### Modified Capabilities
+- `cli-artifact-workflow`: Apply instructions become schema-aware
+
+## Impact
+
+- **Affected code**: `src/commands/artifact-workflow.ts` (generateApplyInstructions)
+- **Schema format**: May need new `apply_phase` field
+- **Existing schemas**: Need to add apply_phase to `spec-driven` and `tdd`
+- **Backward compatible**: Schemas without apply_phase can use default behavior

openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: Schema Apply Block
+
+The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
+
+#### Scenario: Schema with apply block
+
+- **WHEN** a schema defines an `apply` block
+- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
+- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
+- **AND** uses `apply.instruction` for guidance shown to the agent
+
+#### Scenario: Schema without apply block
+
+- **WHEN** a schema has no `apply` block
+- **THEN** the system requires all artifacts to exist before apply is available
+- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
+
+### Requirement: Apply Instructions Command
+
+The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
+
+#### Scenario: Generate apply instructions
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** all required artifacts (per schema's `apply.requires`) exist
+- **THEN** the system outputs:
+  - Context files from all existing artifacts
+  - Schema-specific instruction text
+  - Progress tracking file path (if `apply.tracks` is set)
+
+#### Scenario: Apply blocked by missing artifacts
+
+- **WHEN** user runs `openspec instructions apply --change <id>`
+- **AND** required artifacts are missing
+- **THEN** the system indicates apply is blocked
+- **AND** lists which artifacts must be created first
+
+#### Scenario: Apply instructions JSON output
+
+- **WHEN** user runs `openspec instructions apply --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `contextFiles`: array of paths to existing artifacts
+  - `instruction`: the apply instruction text
+  - `tracks`: path to progress file or null
+  - `applyRequires`: list of required artifact IDs
+
+## MODIFIED Requirements
+
+### Requirement: Status Command
+
+The system SHALL display artifact completion status for a change, including apply readiness.
+
+#### Scenario: Status JSON includes apply requirements
+
+- **WHEN** user runs `openspec status --change <id> --json`
+- **THEN** the system outputs JSON with:
+  - `changeName`, `schemaName`, `isComplete`, `artifacts` array
+  - `applyRequires`: array of artifact IDs needed for apply phase

openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md

@@ -0,0 +1,35 @@
+## Prerequisites
+
+- [x] 0.1 Implement `add-per-change-schema-metadata` first (to auto-detect schema)
+
+## 1. Schema Format
+
+- [x] 1.1 Add `ApplyPhaseSchema` Zod schema to `src/core/artifact-graph/types.ts`
+- [x] 1.2 Update `SchemaYamlSchema` to include optional `apply` field
+- [x] 1.3 Export `ApplyPhase` type
+
+## 2. Update Existing Schemas
+
+- [x] 2.1 Add `apply` block to `schemas/spec-driven/schema.yaml`
+- [x] 2.2 Add `apply` block to `schemas/tdd/schema.yaml`
+
+## 3. Refactor generateApplyInstructions
+
+- [x] 3.1 Load schema via `resolveSchema(schemaName)`
+- [x] 3.2 Read `apply.requires` to determine required artifacts
+- [x] 3.3 Check artifact existence dynamically (not hardcoded paths)
+- [x] 3.4 Use `apply.tracks` for progress tracking (or skip if null)
+- [x] 3.5 Use `apply.instruction` for the instruction text
+- [x] 3.6 Build `contextFiles` from all existing artifacts in schema
+
+## 4. Handle Fallback
+
+- [x] 4.1 If schema has no `apply` block, require all artifacts to exist
+- [x] 4.2 Default instruction: "All artifacts complete. Proceed with implementation."
+
+## 5. Tests
+
+- [x] 5.1 Test apply instructions with spec-driven schema
+- [x] 5.2 Test apply instructions with tdd schema
+- [x] 5.3 Test fallback when schema has no apply block
+- [x] 5.4 Test blocked state when required artifacts missing

openspec/changes/archive/2026-01-06-opsx-archive-command/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-07

openspec/changes/archive/2026-01-06-opsx-archive-command/design.md

@@ -0,0 +1,84 @@
+## Context
+
+The experimental workflow (OPSX) provides a complete lifecycle for creating changes:
+- `/opsx:new` - Scaffold a new change with schema
+- `/opsx:continue` - Create next artifact
+- `/opsx:ff` - Fast-forward all artifacts
+- `/opsx:apply` - Implement tasks
+- `/opsx:sync` - Sync delta specs to main
+
+The missing piece is archiving. The existing `openspec archive` command works but:
+1. Applies specs programmatically (not agent-driven)
+2. Doesn't use the artifact graph for completion checking
+3. Doesn't integrate with the OPSX workflow philosophy
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add `/opsx:archive` skill to complete the OPSX workflow lifecycle
+- Use artifact graph for schema-aware completion checking
+- Integrate with `/opsx:sync` for agent-driven spec syncing
+- Preserve `.openspec.yaml` schema metadata in archive
+
+**Non-Goals:**
+- Replacing the existing `openspec archive` CLI command
+- Changing how specs are applied in the CLI command
+- Modifying the artifact graph or schema system
+
+## Decisions
+
+### Decision 1: Skill-only implementation (no new CLI command)
+
+The `/opsx:archive` will be a slash command/skill only, not a new CLI command.
+
+**Rationale**: The existing `openspec archive` CLI command already handles the core archive functionality (moving to archive folder, date prefixing). The OPSX version just needs different pre-archive checks and optional sync prompting, which are agent behaviors better suited to a skill.
+
+**Alternatives considered**:
+- Adding flags to `openspec archive` (e.g., `--experimental`) - Rejected: adds complexity to CLI, harder to maintain two code paths
+- New CLI command `openspec archive-experimental` - Rejected: unnecessary duplication, agent skills are the OPSX pattern
+
+### Decision 2: Prompt for sync before archive
+
+The skill will check for unsynced delta specs and prompt the user before archiving.
+
+**Rationale**: The OPSX philosophy is agent-driven intelligent merging via `/opsx:sync`. Rather than programmatically applying specs like the regular archive command, we prompt the user to sync first if needed. This maintains workflow flexibility (user can decline and just archive).
+
+**Flow**:
+1. Check if `specs/` directory exists in the change
+2. If yes, ask: "This change has delta specs. Would you like to sync them to main specs before archiving?"
+3. If user says yes, execute `/opsx:sync` logic
+4. Proceed with archive regardless of answer
+
+### Decision 3: Use artifact graph for completion checking
+
+The skill will use `openspec status --change "<name>" --json` to check artifact completion instead of just validating proposal.md and specs.
+
+**Rationale**: The experimental workflow is schema-aware. Different schemas have different required artifacts. The artifact graph knows which artifacts are complete/incomplete for the current schema.
+
+**Behavior**:
+- Show warning if any artifacts are not `done`
+- Don't block archive (user may have valid reasons to archive early)
+- List incomplete artifacts so user can make informed decision
+
+### Decision 4: Reuse tasks.md completion check from regular archive
+
+The skill will parse tasks.md and warn about incomplete tasks, same as regular archive.
+
+**Rationale**: Task completion checking is valuable regardless of workflow. The logic is simple (count `- [ ]` vs `- [x]`) and doesn't need special OPSX handling.
+
+### Decision 5: Move change to archive/ with date prefix
+
+Same archive behavior as regular command: move to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+**Rationale**: Consistency with existing archive convention. The `.openspec.yaml` file moves with the change, preserving schema metadata.
+
+## Risks / Trade-offs
+
+**Risk**: Users confused about when to use `/opsx:archive` vs `openspec archive`
+→ **Mitigation**: Documentation should clarify: use `/opsx:archive` if you've been using the OPSX workflow, use `openspec archive` otherwise. Both produce the same archived result.
+
+**Risk**: Incomplete sync if user declines and has delta specs
+→ **Mitigation**: The prompt is informational; user has full control. They may want to archive without syncing (e.g., abandoned change). Log a note in output.
+
+**Trade-off**: No programmatic spec application in OPSX archive
+→ **Accepted**: This is intentional. OPSX philosophy is agent-driven merging. If user wants programmatic application, use `openspec archive` instead.

openspec/changes/archive/2026-01-06-opsx-archive-command/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+The experimental workflow (OPSX) provides a schema-driven, artifact-by-artifact approach to creating changes with `/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:apply`, and `/opsx:sync`. However, there's no corresponding archive command to finalize and archive completed changes. Users must currently fall back to the regular `openspec archive` command, which doesn't integrate with the OPSX philosophy of agent-driven spec syncing and schema-aware artifact tracking.
+
+## What Changes
+
+- Add `/opsx:archive` slash command for archiving changes in the experimental workflow
+- Use artifact graph to check completion status (schema-aware) instead of just validating proposal + specs
+- Prompt for `/opsx:sync` before archiving instead of programmatically applying specs
+- Preserve `.openspec.yaml` schema metadata when moving to archive
+- Integrate with existing OPSX commands for a cohesive workflow
+
+## Capabilities
+
+### New Capabilities
+
+- `opsx-archive-skill`: Slash command and skill for archiving completed changes in the experimental workflow. Checks artifact completion via artifact graph, verifies task completion, optionally syncs specs via `/opsx:sync`, and moves the change to `archive/YYYY-MM-DD-<name>/`.
+
+### Modified Capabilities
+
+(none - this is a new skill that doesn't modify existing specs)
+
+## Impact
+
+- New file: `.claude/commands/opsx/archive.md`
+- New skill definition (generated via `openspec artifact-experimental-setup`)
+- No changes to existing archive command or other OPSX commands
+- Completes the OPSX command suite for full lifecycle management

openspec/changes/archive/2026-01-06-opsx-archive-command/specs/opsx-archive-skill/spec.md

@@ -0,0 +1,122 @@
+## ADDED Requirements
+
+### Requirement: OPSX Archive Skill
+
+The system SHALL provide an `/opsx:archive` skill that archives completed changes in the experimental workflow.
+
+#### Scenario: Archive a change with all artifacts complete
+
+- **WHEN** agent executes `/opsx:archive` with a change name
+- **AND** all artifacts in the schema are complete
+- **AND** all tasks are complete
+- **THEN** the agent moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- **AND** displays success message with archived location
+
+#### Scenario: Change selection prompt
+
+- **WHEN** agent executes `/opsx:archive` without specifying a change
+- **THEN** the agent prompts user to select from available changes
+- **AND** shows only active changes (excludes archive/)
+
+### Requirement: Artifact Completion Check
+
+The skill SHALL check artifact completion status using the artifact graph before archiving.
+
+#### Scenario: Incomplete artifacts warning
+
+- **WHEN** agent checks artifact status
+- **AND** one or more artifacts have status other than `done`
+- **THEN** display warning listing incomplete artifacts
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All artifacts complete
+
+- **WHEN** agent checks artifact status
+- **AND** all artifacts have status `done`
+- **THEN** proceed without warning
+
+### Requirement: Task Completion Check
+
+The skill SHALL check task completion status from tasks.md before archiving.
+
+#### Scenario: Incomplete tasks found
+
+- **WHEN** agent reads tasks.md
+- **AND** incomplete tasks are found (marked with `- [ ]`)
+- **THEN** display warning showing count of incomplete tasks
+- **AND** prompt user for confirmation to continue
+- **AND** proceed if user confirms
+
+#### Scenario: All tasks complete
+
+- **WHEN** agent reads tasks.md
+- **AND** all tasks are complete (marked with `- [x]`)
+- **THEN** proceed without task-related warning
+
+#### Scenario: No tasks file
+
+- **WHEN** tasks.md does not exist
+- **THEN** proceed without task-related warning
+
+### Requirement: Spec Sync Prompt
+
+The skill SHALL prompt to sync delta specs before archiving if specs exist.
+
+#### Scenario: Delta specs exist
+
+- **WHEN** agent checks for delta specs
+- **AND** `specs/` directory exists in the change with spec files
+- **THEN** prompt user: "This change has delta specs. Would you like to sync them to main specs before archiving?"
+- **AND** if user confirms, execute `/opsx:sync` logic
+- **AND** proceed with archive regardless of sync choice
+
+#### Scenario: No delta specs
+
+- **WHEN** agent checks for delta specs
+- **AND** no `specs/` directory or no spec files exist
+- **THEN** proceed without sync prompt
+
+### Requirement: Archive Process
+
+The skill SHALL move the change to the archive folder with date prefix.
+
+#### Scenario: Successful archive
+
+- **WHEN** archiving a change
+- **THEN** create `archive/` directory if it doesn't exist
+- **AND** generate target name as `YYYY-MM-DD-<change-name>` using current date
+- **AND** move entire change directory to archive location
+- **AND** preserve `.openspec.yaml` file in archived change
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive directory already exists
+- **THEN** fail with error message
+- **AND** suggest renaming existing archive or using different date
+
+### Requirement: Skill Output
+
+The skill SHALL provide clear feedback about the archive operation.
+
+#### Scenario: Archive complete with sync
+
+- **WHEN** archive completes after syncing specs
+- **THEN** display summary:
+  - Specs synced (from `/opsx:sync` output)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete without sync
+
+- **WHEN** archive completes without syncing specs
+- **THEN** display summary:
+  - Note that specs were not synced (if applicable)
+  - Change archived to location
+  - Schema that was used
+
+#### Scenario: Archive complete with warnings
+
+- **WHEN** archive completes with incomplete artifacts or tasks
+- **THEN** include note about what was incomplete
+- **AND** suggest reviewing if archive was intentional

openspec/changes/archive/2026-01-06-opsx-archive-command/tasks.md

@@ -0,0 +1,23 @@
+## 1. Create Slash Command
+
+- [x] 1.1 Create `.claude/commands/opsx/archive.md` with skill definition
+- [x] 1.2 Add YAML frontmatter (name, description, category, tags)
+- [x] 1.3 Implement change selection logic (prompt if not provided)
+- [x] 1.4 Implement artifact completion check using `openspec status --json`
+- [x] 1.5 Implement task completion check (parse tasks.md for `- [ ]`)
+- [x] 1.6 Implement spec sync prompt (check for specs/ directory, offer `/opsx:sync`)
+- [x] 1.7 Implement archive process (move to archive/YYYY-MM-DD-<name>/)
+- [x] 1.8 Add output formatting for success/warning cases
+
+## 2. Regenerate Skills
+
+- [x] 2.1 Run `openspec artifact-experimental-setup` to regenerate skills
+- [x] 2.2 Verify skill appears in `.claude/skills/` directory
+
+## 3. Testing
+
+- [x] 3.1 Test `/opsx:archive` with a complete change (all artifacts, all tasks done)
+- [x] 3.2 Test `/opsx:archive` with incomplete artifacts (verify warning shown)
+- [x] 3.3 Test `/opsx:archive` with incomplete tasks (verify warning shown)
+- [x] 3.4 Test `/opsx:archive` with delta specs (verify sync prompt shown)
+- [x] 3.5 Test `/opsx:archive` without change name (verify selection prompt)

openspec/changes/archive/2026-01-07-add-nix-flake-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-07

openspec/changes/archive/2026-01-07-add-nix-flake-support/design.md

@@ -0,0 +1,94 @@
+## Context
+
+OpenSpec is a TypeScript CLI tool using pnpm for dependency management. The project requires Node.js ≥20.19.0. Nix uses its own build system that needs to understand how to fetch dependencies and build the project reproducibly.
+
+The Nix ecosystem has specific patterns for packaging Node.js/pnpm projects that differ from the traditional npm ecosystem.
+
+## Goals
+
+- Enable OpenSpec to be run directly via `nix run github:Fission-AI/OpenSpec`
+- Support all major platforms (Linux x86/ARM, macOS x86/ARM)
+- Use existing pnpm-lock.yaml for reproducible builds
+- Provide development environment for Nix users
+
+## Non-Goals
+
+- Replace existing npm/pnpm publishing workflow
+- Publish to nixpkgs (can be done later as separate effort)
+- Support Windows (Nix doesn't run natively on Windows)
+
+## Decisions
+
+### Use stdenv.mkDerivation instead of buildNpmPackage
+
+**Decision**: Package OpenSpec using `stdenv.mkDerivation` with pnpm hooks.
+
+**Rationale**: The zigbee2mqtt package in nixpkgs demonstrates the current best practice for pnpm projects. Using `buildNpmPackage` with pnpm requires complex configuration, while `mkDerivation` with the right hooks is more straightforward and better supported.
+
+**Alternative considered**: Using `buildNpmPackage` with `npmConfigHook = pkgs.pnpmConfigHook` - this is the older pattern and causes issues with dependency fetching.
+
+### Use fetchPnpmDeps with explicit pnpm version
+
+**Decision**: Use `pkgs.fetchPnpmDeps` with `pnpm = pkgs.pnpm_9` and `fetcherVersion = 3`.
+
+**Rationale**:
+- pnpm lockfile version 9.0 requires fetcherVersion 3
+- Explicit pnpm_9 ensures consistency between fetch and build
+- This is the documented way to handle pnpm projects in nixpkgs
+
+### Multi-platform support without flake-utils
+
+**Decision**: Implement multi-platform support using plain Nix with `nixpkgs.lib.genAttrs`.
+
+**Rationale**: Per user request, avoid extra dependencies. The `genAttrs` pattern is simple and well-understood in the Nix community.
+
+### Node.js 20 instead of latest
+
+**Decision**: Pin to nodejs_20 to match package.json engines requirement.
+
+**Rationale**: Ensures consistency with development environment and npm package requirements. Avoids potential compatibility issues with newer Node versions.
+
+## Key Implementation Details
+
+### Dependency Hash Management
+
+The `pnpmDeps.hash` field must be updated whenever dependencies change. The workflow:
+1. Set hash to fake value (all zeros)
+2. Run `nix build`
+3. Nix fails with actual hash
+4. Update flake.nix with correct hash
+
+This is standard Nix workflow for fixed-output derivations.
+
+### Build Inputs
+
+Required nativeBuildInputs:
+- `nodejs_20` - runtime
+- `npmHooks.npmInstallHook` - handles installation phase
+- `pnpmConfigHook` - configures pnpm environment
+- `pnpm_9` - pnpm executable
+
+The `dontNpmPrune = true` is important to keep all dependencies after build.
+
+## Risks / Trade-offs
+
+**[Risk]** Hash needs updating when dependencies change → **Mitigation**: Document this clearly; error message from Nix provides correct hash
+
+**[Risk]** Nix builds might lag behind npm releases → **Mitigation**: This is fine; Nix users can still use npm if they need bleeding edge
+
+**[Trade-off]** Additional maintenance burden for hash updates → **Benefit**: Better experience for Nix ecosystem users
+
+## Migration Plan
+
+1. Add flake.nix to repository
+2. Test builds on multiple platforms (can use GitHub Actions with Nix)
+3. Update README with Nix installation instructions
+4. Optionally add to CI pipeline to catch hash mismatches early
+
+No breaking changes - this is purely additive.
+
+## Open Questions
+
+- Should we add automatic hash updating to CI? (Could use nix-update-script)
+- Should we submit to nixpkgs after validation? (Separate decision)
+- Do we want to support older Node versions in flake? (Probably no - stick to package.json requirement)

openspec/changes/archive/2026-01-07-add-nix-flake-support/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+OpenSpec users on NixOS or using the Nix package manager cannot easily install or run OpenSpec without going through npm. Adding a Nix flake makes OpenSpec a first-class citizen in the Nix ecosystem, enabling users to run `nix run github:Fission-AI/OpenSpec -- init` or include OpenSpec in their development environments declaratively.
+
+## What Changes
+
+- Add `flake.nix` to repository root with multi-platform support (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin)
+- Package uses pnpm for dependency management (matching existing development workflow)
+- Support both direct execution via `nix run` and installation via `nix profile install`
+- Provide dev shell for contributors using Nix
+
+## Capabilities
+
+### New Capabilities
+- `nix-flake-support`: Nix flake configuration for building and running OpenSpec
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- **New files**: `flake.nix` in repository root
+- **Documentation**: Should add installation instructions for Nix users
+- **CI/CD**: Could add flake checking to CI pipeline (optional)
+- **Maintenance**: Requires updating pnpmDeps hash when dependencies change

openspec/changes/archive/2026-01-07-add-nix-flake-support/specs/nix-flake-support/spec.md

@@ -0,0 +1,79 @@
+## ADDED Requirements
+
+### Requirement: Multi-platform Nix flake
+The system SHALL provide a Nix flake that builds OpenSpec for multiple platforms.
+
+#### Scenario: Build on Linux x86_64
+- **WHEN** user runs `nix build` on x86_64-linux system
+- **THEN** system builds OpenSpec package successfully
+- **AND** package includes the `openspec` binary
+
+#### Scenario: Build on macOS ARM
+- **WHEN** user runs `nix build` on aarch64-darwin system
+- **THEN** system builds OpenSpec package successfully
+- **AND** package includes the `openspec` binary
+
+#### Scenario: Build on Linux ARM
+- **WHEN** user runs `nix build` on aarch64-linux system
+- **THEN** system builds OpenSpec package successfully
+
+#### Scenario: Build on macOS x86_64
+- **WHEN** user runs `nix build` on x86_64-darwin system
+- **THEN** system builds OpenSpec package successfully
+
+### Requirement: Direct execution via nix run
+The system SHALL allow users to run OpenSpec directly from GitHub without installing.
+
+#### Scenario: Run init command from GitHub
+- **WHEN** user runs `nix run github:Fission-AI/OpenSpec -- init`
+- **THEN** system downloads and builds OpenSpec
+- **AND** executes `openspec init` command
+
+#### Scenario: Run any OpenSpec command
+- **WHEN** user runs `nix run github:Fission-AI/OpenSpec -- <command> <args>`
+- **THEN** system executes `openspec <command> <args>`
+
+### Requirement: pnpm dependency management
+The system SHALL use pnpm for building OpenSpec in the Nix flake.
+
+#### Scenario: Fetch dependencies with pnpm
+- **WHEN** Nix builds the package
+- **THEN** system uses `fetchPnpmDeps` to download dependencies
+- **AND** uses pnpm-lock.yaml for reproducible builds
+- **AND** uses fetcherVersion 3 for lockfile version 9.0
+
+#### Scenario: Build with pnpm
+- **WHEN** Nix runs the build phase
+- **THEN** system executes `pnpm run build`
+- **AND** produces dist directory with compiled TypeScript
+
+### Requirement: Node.js version compatibility
+The system SHALL use Node.js 20 as specified in package.json engines field.
+
+#### Scenario: Build with correct Node version
+- **WHEN** Nix builds OpenSpec
+- **THEN** system uses nodejs_20 from nixpkgs
+- **AND** build succeeds without version compatibility errors
+
+### Requirement: Development shell
+The system SHALL provide a Nix development shell for contributors.
+
+#### Scenario: Enter dev shell
+- **WHEN** user runs `nix develop` in OpenSpec repository
+- **THEN** system provides shell with nodejs_20 and pnpm_9
+- **AND** displays welcome message with versions
+- **AND** provides instructions to run `pnpm install`
+
+### Requirement: Proper binary installation
+The system SHALL install the openspec binary correctly.
+
+#### Scenario: Binary in PATH
+- **WHEN** package is built or installed
+- **THEN** `openspec` binary is available in `$out/bin/openspec`
+- **AND** binary is executable
+- **AND** binary can be invoked without full path when installed
+
+#### Scenario: Binary executes correctly
+- **WHEN** user runs the installed `openspec` command
+- **THEN** system executes the CLI entry point
+- **AND** all subcommands work correctly

openspec/changes/archive/2026-01-07-add-nix-flake-support/tasks.md

@@ -0,0 +1,65 @@
+## 1. Create Flake Structure
+
+- [x] 1.1 Create flake.nix in repository root
+- [x] 1.2 Define inputs (nixpkgs only, no flake-utils)
+- [x] 1.3 Set up supportedSystems list (4 platforms)
+- [x] 1.4 Create forAllSystems helper function
+
+## 2. Configure Package Build
+
+- [x] 2.1 Set up stdenv.mkDerivation with finalAttrs pattern
+- [x] 2.2 Configure pnpmDeps with fetchPnpmDeps
+- [x] 2.3 Set pnpm = pnpm_9 and fetcherVersion = 3
+- [x] 2.4 Add placeholder hash (all zeros)
+- [x] 2.5 Configure nativeBuildInputs (nodejs_20, hooks, pnpm_9)
+- [x] 2.6 Set dontNpmPrune = true
+
+## 3. Define Build Phase
+
+- [x] 3.1 Add buildPhase with runHook preBuild
+- [x] 3.2 Add pnpm run build command
+- [x] 3.3 Add runHook postBuild
+
+## 4. Configure Installation
+
+- [x] 4.1 Let npmInstallHook handle installation automatically
+- [x] 4.2 Verify binary ends up in $out/bin/openspec
+
+## 5. Add Metadata
+
+- [x] 5.1 Set meta.description
+- [x] 5.2 Set meta.homepage
+- [x] 5.3 Set meta.license (MIT)
+- [x] 5.4 Set meta.mainProgram = "openspec"
+
+## 6. Configure App Entry Point
+
+- [x] 6.1 Add apps output with forAllSystems
+- [x] 6.2 Set default app to openspec binary
+- [x] 6.3 Test that nix run works
+
+## 7. Add Development Shell
+
+- [x] 7.1 Add devShells output with forAllSystems
+- [x] 7.2 Include nodejs_20 and pnpm_9 in buildInputs
+- [x] 7.3 Add shellHook with welcome message and instructions
+
+## 8. Get Correct Dependency Hash
+
+- [x] 8.1 Run nix build to trigger hash mismatch
+- [x] 8.2 Copy correct hash from error message
+- [x] 8.3 Update pnpmDeps.hash in flake.nix
+- [x] 8.4 Verify build succeeds
+
+## 9. Testing
+
+- [x] 9.1 Test `nix build` on x86_64-linux
+- [x] 9.2 Test `nix run . -- --version` works
+- [x] 9.3 Test `nix develop` provides correct environment
+- [ ] 9.4 Test on macOS if available
+- [ ] 9.5 Test `nix run github:Fission-AI/OpenSpec -- init` after merge to main
+
+## 10. Documentation
+
+- [x] 10.1 Add Nix installation section to README
+- [x] 10.2 Include example commands for common Nix workflows in README

openspec/changes/archive/2026-01-09-add-flake-update-script/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-09

openspec/changes/archive/2026-01-09-add-flake-update-script/design.md

@@ -0,0 +1,117 @@
+## Context
+
+The Nix flake added in the previous change requires manual maintenance when:
+1. Package version changes (must update flake.nix version field)
+2. Dependencies change (must update pnpmDeps hash)
+
+Currently this requires maintainers to:
+- Manually edit flake.nix version
+- Set placeholder hash
+- Run nix build to get error
+- Copy hash from error message
+- Update flake.nix again
+- Verify build works
+
+This is tedious and error-prone, especially for maintainers unfamiliar with Nix.
+
+## Goals
+
+- Automate version and hash updates for flake.nix
+- Make script idempotent and safe to run multiple times
+- Provide clear feedback during execution
+- Integrate easily into release workflow
+
+## Non-Goals
+
+- Automatically commit changes (maintainer decides when to commit)
+- Support non-pnpm package managers
+- Handle complex Nix configurations beyond OpenSpec's use case
+
+## Decisions
+
+### Use Bash instead of Node.js script
+
+**Decision**: Implement as bash script rather than Node.js.
+
+**Rationale**:
+- Needs to call Nix commands which are bash-native
+- Parsing Nix output is simpler in bash with grep/sed
+- Maintainers updating flake.nix likely have Nix installed (bash environment)
+- Node.js would add unnecessary complexity for shell operations
+
+**Alternative considered**: Node.js script with child_process - adds dependency on extra npm packages for shell operations, less natural for Nix tooling.
+
+### Extract hash from build error output
+
+**Decision**: Trigger intentional build failure with placeholder hash to get correct hash.
+
+**Rationale**: This is the standard Nix workflow for updating fixed-output derivations. No API exists to compute the hash without building.
+
+**Alternative considered**: Pre-compute hash from pnpm-lock.yaml - would require understanding Nix's hash algorithm and pnpm's lockfile structure, fragile and non-standard.
+
+### Use sed for in-place file editing
+
+**Decision**: Use `sed -i` for updating flake.nix in place.
+
+**Rationale**: Simple, available on all Unix-like systems, handles the specific replacement patterns needed.
+
+**Alternative considered**:
+- Using Node.js to parse/modify: Overkill for simple string replacement
+- Manual `sed` without `-i`: Requires temp files, more complex
+
+### Verify build after hash update
+
+**Decision**: Always run verification build after updating hash.
+
+**Rationale**: Catches errors immediately, gives maintainer confidence the update worked.
+
+**Trade-off**: Takes extra time (~30s) but prevents broken flake.nix commits.
+
+## Key Implementation Details
+
+### Path Resolution
+
+Script calculates paths relative to its own location:
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+```
+
+This allows running from any working directory.
+
+### Error Handling
+
+Uses `set -euo pipefail` for strict error handling:
+- `-e`: Exit on any command failure
+- `-u`: Exit on undefined variable access
+- `-o pipefail`: Catch failures in pipes
+
+### Hash Extraction Pattern
+
+Uses grep with Perl regex to extract hash:
+```bash
+grep -oP 'got:\s+\Ksha256-[A-Za-z0-9+/=]+'
+```
+
+This reliably extracts the hash regardless of surrounding text.
+
+## Risks / Trade-offs
+
+**[Risk]** Script assumes standard Nix error message format → **Mitigation**: If extraction fails, script exits with error and shows full output
+
+**[Risk]** Build might fail for reasons other than hash mismatch → **Mitigation**: Script checks for hash in output before proceeding
+
+**[Trade-off]** Requires Nix installed to run → **Benefit**: Only maintainers updating flake need to run this, and they have Nix
+
+## Migration Plan
+
+1. Add script to scripts directory
+2. Document in scripts/README.md
+3. Use in next version bump to verify workflow
+4. Update CONTRIBUTING.md if needed to mention script
+
+No breaking changes - purely additive tooling.
+
+## Open Questions
+
+None - straightforward automation script.

openspec/changes/archive/2026-01-09-add-flake-update-script/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+Maintaining the Nix flake requires manual updates to version and dependency hash when releasing new versions or updating dependencies. This is error-prone and requires maintainers to understand Nix internals. Automating this process ensures consistency and reduces friction for releases.
+
+## What Changes
+
+- Add `scripts/update-flake.sh` to automatically update flake.nix version and dependency hash
+- Add `scripts/README.md` documenting all maintenance scripts
+- Script extracts version from package.json and determines correct pnpm dependency hash automatically
+
+## Capabilities
+
+### New Capabilities
+- `flake-update-script`: Automation script for maintaining flake.nix
+
+### Modified Capabilities
+- None
+
+## Impact
+
+- **New files**: `scripts/update-flake.sh`, `scripts/README.md`
+- **Maintainer workflow**: Version bumps now include running `./scripts/update-flake.sh`
+- **Dependencies**: Script requires Node.js (already a dependency) and Nix (for maintainers using Nix)

openspec/changes/archive/2026-01-09-add-flake-update-script/specs/flake-update-script/spec.md

@@ -0,0 +1,86 @@
+## ADDED Requirements
+
+### Requirement: Automatic Version Update
+The script SHALL automatically update the version in flake.nix to match package.json.
+
+#### Scenario: Version extraction from package.json
+- **WHEN** script runs
+- **THEN** version is read from package.json using Node.js
+- **AND** version field in flake.nix is updated to match
+
+#### Scenario: Version already up-to-date
+- **WHEN** script runs and flake.nix version already matches package.json
+- **THEN** script reports version is up-to-date
+- **AND** continues to hash update
+
+### Requirement: Automatic Hash Determination
+The script SHALL automatically determine and update the correct pnpm dependency hash.
+
+#### Scenario: Trigger build to get hash
+- **WHEN** script needs to determine correct hash
+- **THEN** script sets placeholder hash in flake.nix
+- **AND** runs nix build which fails with correct hash
+- **AND** extracts correct hash from build error output
+
+#### Scenario: Hash extraction from build output
+- **WHEN** nix build fails with hash mismatch
+- **THEN** script parses "got: sha256-..." from error output
+- **AND** updates flake.nix with correct hash
+
+#### Scenario: Hash update failure
+- **WHEN** script cannot extract hash from build output
+- **THEN** script exits with error
+- **AND** displays build output for debugging
+
+### Requirement: Build Verification
+The script SHALL verify that flake.nix builds successfully after updates.
+
+#### Scenario: Successful verification
+- **WHEN** hash has been updated
+- **THEN** script runs nix build to verify
+- **AND** reports success if build completes
+
+#### Scenario: Dirty git tree warning
+- **WHEN** build succeeds but git tree is dirty
+- **THEN** script reports warning about dirty tree
+- **AND** still indicates build success
+
+### Requirement: User Feedback
+The script SHALL provide clear progress information and next steps.
+
+#### Scenario: Progress reporting
+- **WHEN** script runs
+- **THEN** each step is reported with descriptive message
+- **AND** detected version and hash are displayed
+
+#### Scenario: Success summary
+- **WHEN** script completes successfully
+- **THEN** summary shows updated version and hash
+- **AND** next steps are displayed (test, commit, etc.)
+
+### Requirement: Script Safety
+The script SHALL fail fast on errors and use safe defaults.
+
+#### Scenario: Bash error handling
+- **WHEN** script encounters an error
+- **THEN** script exits immediately (set -e)
+- **AND** undefined variables cause exit (set -u)
+- **AND** pipe failures are caught (set -o pipefail)
+
+#### Scenario: File path resolution
+- **WHEN** script determines file locations
+- **THEN** paths are calculated relative to script location
+- **AND** script works regardless of working directory
+
+### Requirement: Documentation
+The system SHALL provide documentation for the update script.
+
+#### Scenario: Script usage documentation
+- **WHEN** maintainer needs to use update script
+- **THEN** scripts/README.md explains when and how to use it
+- **AND** example workflow is provided
+
+#### Scenario: Script listing
+- **WHEN** maintainer views scripts/README.md
+- **THEN** all maintenance scripts are documented
+- **AND** purpose of each script is clear

openspec/changes/archive/2026-01-09-add-flake-update-script/tasks.md

@@ -0,0 +1,55 @@
+## 1. Create Update Script
+
+- [x] 1.1 Create scripts/update-flake.sh file
+- [x] 1.2 Add shebang and error handling (set -euo pipefail)
+- [x] 1.3 Add path resolution for project root and files
+- [x] 1.4 Make script executable (chmod +x)
+
+## 2. Implement Version Update Logic
+
+- [x] 2.1 Extract version from package.json using Node.js
+- [x] 2.2 Use sed to update version in flake.nix
+- [x] 2.3 Report if version already up-to-date
+- [x] 2.4 Display detected version to user
+
+## 3. Implement Hash Update Logic
+
+- [x] 3.1 Set placeholder hash in flake.nix
+- [x] 3.2 Run nix build and capture output (allow failure)
+- [x] 3.3 Extract correct hash from build error using grep
+- [x] 3.4 Handle case where hash extraction fails
+- [x] 3.5 Update flake.nix with correct hash
+- [x] 3.6 Display detected hash to user
+
+## 4. Add Build Verification
+
+- [x] 4.1 Run nix build after hash update
+- [x] 4.2 Check for dirty git tree warning
+- [x] 4.3 Report success or failure clearly
+
+## 5. Add User Feedback
+
+- [x] 5.1 Add progress messages for each step
+- [x] 5.2 Add success summary with version and hash
+- [x] 5.3 Add next steps instructions (test, commit)
+- [x] 5.4 Add error messages with context
+
+## 6. Create Documentation
+
+- [x] 6.1 Create scripts/README.md
+- [x] 6.2 Document update-flake.sh purpose and usage
+- [x] 6.3 Add example workflow
+- [x] 6.4 Document other existing scripts
+
+## 7. Testing
+
+- [x] 7.1 Test script runs successfully
+- [x] 7.2 Verify version is extracted correctly
+- [x] 7.3 Verify hash is updated correctly
+- [x] 7.4 Verify build succeeds after update
+- [x] 7.5 Test idempotency (running twice works)
+
+## 8. Integration
+
+- [ ] 8.1 Add note to release process documentation
+- [ ] 8.2 Use in next actual version bump to validate workflow

openspec/changes/archive/2026-01-09-add-posthog-analytics/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-10

openspec/changes/archive/2026-01-09-add-posthog-analytics/design.md

@@ -0,0 +1,175 @@
+## Context
+
+OpenSpec needs usage analytics to understand adoption and inform product decisions. PostHog provides a privacy-conscious analytics platform suitable for open source projects.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Track daily/weekly/monthly active usage
+- Understand command usage patterns
+- Keep implementation minimal and privacy-respecting
+- Enable opt-out with minimal friction
+
+**Non-Goals:**
+- Detailed error tracking or diagnostics
+- User identification or profiling
+- Complex event hierarchies
+- Full CLI command for telemetry management (env var sufficient for now)
+
+## Decisions
+
+### Opt-Out Model
+
+**Decision:** Telemetry enabled by default, opt-out via environment variable.
+
+```bash
+OPENSPEC_TELEMETRY=0    # Disable telemetry
+DO_NOT_TRACK=1          # Industry standard, also respected
+```
+
+Auto-disabled when `CI=true` is detected.
+
+**Rationale:**
+- Opt-in typically yields ~3% participation—not enough for meaningful data
+- Understanding usage patterns requires statistically significant sample sizes
+- Environment variable opt-out is simple and immediate
+- Respecting `DO_NOT_TRACK` follows industry convention
+
+**Alternatives considered:**
+- Opt-in only - Insufficient data for product decisions
+- Config file setting - More complex, env var sufficient for MVP
+- Full `openspec telemetry` command - Can add later if users request
+
+### Event Design
+
+**Decision:** Single event type with minimal properties.
+
+```typescript
+{
+  event: 'command_executed',
+  properties: {
+    command: 'init',      // Command name only
+    version: '1.2.3'      // OpenSpec version
+  }
+}
+```
+
+**Rationale:**
+- Answers the core questions: how much usage, which commands are popular
+- PostHog derives DAU/WAU/MAU from anonymous user counts over time
+- No arguments, paths, or content—clean privacy story
+- Easy to explain in disclosure notice
+
+**Not tracked:**
+- Command arguments
+- File paths or contents
+- Error messages or stack traces
+- Project names or spec content
+- IP addresses (`$ip: null` explicitly set)
+
+### Anonymous ID
+
+**Decision:** Random UUID, lazily generated on first telemetry send, stored in global config.
+
+```typescript
+// ~/.config/openspec/config.json
+{
+  "telemetry": {
+    "anonymousId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
+  }
+}
+```
+
+**Rationale:**
+- Random UUID has no relation to the person—can't be reversed
+- Stored in config so same user = same ID across sessions (needed for DAU/WAU/MAU)
+- Lazy generation means no ID created if user opts out before first command
+- User can delete config to reset identity
+
+**Alternatives considered:**
+- Machine-derived hash (hostname, MAC) - Feels invasive, fingerprint-like
+- Per-session UUID - Breaks user counting metrics entirely
+
+### SDK Configuration
+
+**Decision:** PostHog Node SDK with immediate flush, shutdown on exit.
+
+```typescript
+const posthog = new PostHog(API_KEY, {
+  flushAt: 1,        // Send immediately, don't batch
+  flushInterval: 0   // No timer-based flushing
+});
+
+// Before CLI exits
+await posthog.shutdown();
+```
+
+**Rationale:**
+- CLI processes are short-lived; batching would lose events
+- `flushAt: 1` ensures each event sends immediately
+- `shutdown()` guarantees flush before process exit
+- Adds ~100-300ms to exit—negligible for typical CLI workflows
+
+**Error handling:**
+- Network failures silently ignored (telemetry shouldn't break CLI)
+- `shutdown()` wrapped in try/catch
+
+### Hook Location
+
+**Decision:** Commander.js `preAction` and `postAction` hooks.
+
+```typescript
+program
+  .hook('preAction', (thisCommand) => {
+    maybeShowTelemetryNotice();
+    trackCommand(thisCommand.name(), VERSION);
+  })
+  .hook('postAction', async () => {
+    await shutdown();
+  });
+```
+
+**Rationale:**
+- Centralized—one place for all telemetry logic
+- Automatic—new commands get tracked without code changes
+- Clean separation—command handlers don't know about telemetry
+
+**Subcommand handling:**
+- Track full command path for nested commands (e.g., `change:apply`)
+
+### First-Run Notice
+
+**Decision:** One-liner on first command ever, stored "seen" flag in config.
+
+```
+Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0
+```
+
+**Rationale:**
+- First command (not just `init`) ensures notice is always seen
+- Non-blocking—no prompt, just informational
+- One-liner is visible but not intrusive
+- Storing "seen" in config prevents repeated display
+
+**Config after first run:**
+```json
+{
+  "telemetry": {
+    "anonymousId": "...",
+    "noticeSeen": true
+  }
+}
+```
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Users prefer opt-in | Clear disclosure, trivial opt-out, transparent about what's collected |
+| GDPR concerns | No personal data, no IP, user can delete config |
+| Slows CLI exit by ~200ms | Negligible for most workflows; can optimize if needed |
+| PostHog outage affects CLI | Fire-and-forget with timeout; failures are silent |
+
+## Open Questions
+
+None—design is intentionally minimal. Future enhancements (dedicated command, workflow tracking) can be added based on user feedback.

openspec/changes/archive/2026-01-09-add-posthog-analytics/proposal.md

@@ -0,0 +1,37 @@
+## Why
+
+OpenSpec currently has no visibility into how the tool is being used. Without analytics, we cannot:
+- Understand which commands and features are most valuable to users
+- Measure adoption and usage patterns
+- Make data-driven decisions about product development
+
+Adding PostHog analytics enables product insights while respecting user privacy through transparent, opt-out telemetry.
+
+## What Changes
+
+- Add PostHog Node.js SDK as a dependency
+- Implement telemetry system with environment variable opt-out
+- Track command usage (command name and version only)
+- Show first-run notice informing users about telemetry
+- Store anonymous ID in global config (`~/.config/openspec/config.json`)
+- Respect `DO_NOT_TRACK` and `OPENSPEC_TELEMETRY=0` environment variables
+- Auto-disable in CI environments
+
+## Capabilities
+
+### New Capabilities
+
+- `telemetry`: Anonymous usage analytics using PostHog. Covers command tracking, opt-out controls, and first-run disclosure notice.
+
+### Modified Capabilities
+
+- `global-config`: Add telemetry state storage (anonymous ID, notice seen flag)
+
+## Impact
+
+- **Dependencies**: Add `posthog-node` package
+- **Privacy**: Opt-out via env var, no personal data collected, clear disclosure
+- **Configuration**: New global config fields for telemetry state
+- **Network**: Async event sending with flush on exit (~100-300ms added)
+- **CI/CD**: Telemetry auto-disabled when `CI=true`
+- **Documentation**: Update README with telemetry disclosure

openspec/changes/archive/2026-01-09-add-posthog-analytics/specs/global-config/spec.md

@@ -0,0 +1,21 @@
+## MODIFIED Requirements
+
+### Requirement: Global configuration storage
+The system SHALL store global configuration in `~/.config/openspec/config.json`, including telemetry state with `anonymousId` and `noticeSeen` fields.
+
+#### Scenario: Initial config creation
+- **WHEN** no global config file exists
+- **AND** the first telemetry event is about to be sent
+- **THEN** the system creates `~/.config/openspec/config.json` with telemetry configuration
+
+#### Scenario: Telemetry config structure
+- **WHEN** reading or writing telemetry configuration
+- **THEN** the config contains a `telemetry` object with `anonymousId` (string UUID) and `noticeSeen` (boolean) fields
+
+#### Scenario: Config file format
+- **WHEN** storing configuration
+- **THEN** the system writes valid JSON that can be read and modified by users
+
+#### Scenario: Existing config preservation
+- **WHEN** adding telemetry fields to an existing config file
+- **THEN** the system preserves all existing configuration fields

openspec/changes/archive/2026-01-09-add-posthog-analytics/specs/telemetry/spec.md

@@ -0,0 +1,116 @@
+## ADDED Requirements
+
+### Requirement: Command execution tracking
+The system SHALL send a `command_executed` event to PostHog when any CLI command executes, including only the command name and OpenSpec version as properties.
+
+#### Scenario: Standard command execution
+- **WHEN** a user runs any openspec command
+- **THEN** the system sends a `command_executed` event with `command` and `version` properties
+
+#### Scenario: Subcommand execution
+- **WHEN** a user runs a nested command like `openspec change apply`
+- **THEN** the system sends a `command_executed` event with the full command path (e.g., `change:apply`)
+
+### Requirement: Privacy-preserving event design
+The system SHALL NOT include command arguments, file paths, project names, spec content, error messages, or IP addresses in telemetry events.
+
+#### Scenario: Command with arguments
+- **WHEN** a user runs `openspec init my-project --force`
+- **THEN** the telemetry event contains only `command: "init"` and `version: "<version>"` without arguments
+
+#### Scenario: IP address exclusion
+- **WHEN** the system sends a telemetry event
+- **THEN** the event explicitly sets `$ip: null` to prevent IP tracking
+
+### Requirement: Environment variable opt-out
+The system SHALL disable telemetry when `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` environment variables are set.
+
+#### Scenario: OPENSPEC_TELEMETRY opt-out
+- **WHEN** `OPENSPEC_TELEMETRY=0` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: DO_NOT_TRACK opt-out
+- **WHEN** `DO_NOT_TRACK=1` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: Environment variable takes precedence
+- **WHEN** the user has previously used the CLI (config exists)
+- **AND** the user sets `OPENSPEC_TELEMETRY=0`
+- **THEN** telemetry is disabled regardless of config state
+
+### Requirement: CI environment auto-disable
+The system SHALL automatically disable telemetry when `CI=true` environment variable is detected.
+
+#### Scenario: CI environment detection
+- **WHEN** `CI=true` is set in the environment
+- **THEN** the system sends no telemetry events
+
+#### Scenario: CI with explicit enable
+- **WHEN** `CI=true` is set
+- **AND** `OPENSPEC_TELEMETRY=1` is explicitly set
+- **THEN** telemetry remains disabled (CI takes precedence for privacy)
+
+### Requirement: First-run telemetry notice
+The system SHALL display a one-line telemetry disclosure notice on the first command execution, before any telemetry is sent.
+
+#### Scenario: First command execution
+- **WHEN** a user runs their first openspec command
+- **AND** telemetry is enabled
+- **THEN** the system displays: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0"
+
+#### Scenario: Subsequent command execution
+- **WHEN** a user has already seen the notice (noticeSeen: true in config)
+- **THEN** the system does not display the notice
+
+#### Scenario: Notice before telemetry
+- **WHEN** displaying the first-run notice
+- **THEN** the notice appears before any telemetry event is sent
+
+### Requirement: Anonymous user identification
+The system SHALL generate a random UUID as an anonymous identifier on first telemetry send, stored in global config.
+
+#### Scenario: First telemetry event
+- **WHEN** the first telemetry event is sent
+- **AND** no anonymousId exists in config
+- **THEN** the system generates a random UUID v4 and stores it in config
+
+#### Scenario: Persistent identity
+- **WHEN** a user runs multiple commands across sessions
+- **THEN** the same anonymousId is used for all events
+
+#### Scenario: Lazy generation with opt-out
+- **WHEN** a user opts out before running any command
+- **THEN** no anonymousId is ever generated or stored
+
+### Requirement: Immediate event sending
+The system SHALL send telemetry events immediately without batching, using `flushAt: 1` and `flushInterval: 0` configuration.
+
+#### Scenario: Event transmission timing
+- **WHEN** a command executes
+- **THEN** the telemetry event is sent immediately, not queued for batch transmission
+
+### Requirement: Graceful shutdown
+The system SHALL call `posthog.shutdown()` before CLI exit to ensure pending events are flushed.
+
+#### Scenario: Normal exit
+- **WHEN** a command completes successfully
+- **THEN** the system awaits `shutdown()` before exiting
+
+#### Scenario: Error exit
+- **WHEN** a command fails with an error
+- **THEN** the system still awaits `shutdown()` before exiting
+
+### Requirement: Silent failure handling
+The system SHALL silently ignore telemetry failures without affecting CLI functionality.
+
+#### Scenario: Network failure
+- **WHEN** the telemetry request fails due to network error
+- **THEN** the CLI command completes normally without error message
+
+#### Scenario: PostHog outage
+- **WHEN** PostHog service is unavailable
+- **THEN** the CLI command completes normally without error message
+
+#### Scenario: Shutdown failure
+- **WHEN** `shutdown()` fails or times out
+- **THEN** the CLI exits normally without error message

openspec/changes/archive/2026-01-09-add-posthog-analytics/tasks.md

@@ -0,0 +1,47 @@
+## 1. Setup
+
+- [x] 1.1 Add `posthog-node` package as a dependency
+- [x] 1.2 Create `src/telemetry/` module directory
+- [x] 1.3 Add PostHog API key configuration (environment variable or embedded)
+
+## 2. Global Config
+
+- [x] 2.1 Create or extend global config module for `~/.config/openspec/config.json`
+- [x] 2.2 Implement read/write functions that preserve existing config fields
+- [x] 2.3 Define telemetry config structure (`anonymousId`, `noticeSeen`)
+
+## 3. Core Telemetry Module
+
+- [x] 3.1 Implement `isTelemetryEnabled()` checking `OPENSPEC_TELEMETRY`, `DO_NOT_TRACK`, and `CI` env vars
+- [x] 3.2 Implement `getOrCreateAnonymousId()` with lazy UUID generation
+- [x] 3.3 Initialize PostHog client with `flushAt: 1` and `flushInterval: 0`
+- [x] 3.4 Implement `trackCommand(commandName, version)` with `$ip: null`
+- [x] 3.5 Implement `shutdown()` with try/catch for silent failure handling
+
+## 4. First-Run Notice
+
+- [x] 4.1 Implement `maybeShowTelemetryNotice()` function
+- [x] 4.2 Check `noticeSeen` flag before displaying notice
+- [x] 4.3 Display notice text: "Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0"
+- [x] 4.4 Update `noticeSeen` in config after first display
+
+## 5. CLI Integration
+
+- [x] 5.1 Add Commander.js `preAction` hook to show notice and track command
+- [x] 5.2 Add Commander.js `postAction` hook to call shutdown
+- [x] 5.3 Handle subcommand path extraction (e.g., `change:apply`)
+
+## 6. Testing
+
+- [x] 6.1 Test opt-out via `OPENSPEC_TELEMETRY=0`
+- [x] 6.2 Test opt-out via `DO_NOT_TRACK=1`
+- [x] 6.3 Test auto-disable in CI environment
+- [x] 6.4 Test first-run notice display and noticeSeen persistence
+- [x] 6.5 Test anonymous ID generation and persistence
+- [x] 6.6 Test silent failure on network error (mock PostHog)
+
+## 7. Documentation
+
+- [x] 7.1 Add telemetry disclosure section to README
+- [x] 7.2 Document opt-out methods (`OPENSPEC_TELEMETRY=0`, `DO_NOT_TRACK=1`)
+- [x] 7.3 Document what data is collected and not collected

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/proposal.md

@@ -0,0 +1,16 @@
+## Why
+
+CodeBuddy slash command configurator currently uses inconsistent frontmatter fields compared to other tools. It uses `category` and `tags` fields (like Crush) but should use `argument-hint` field (like Factory, Auggie, and Codex) for better consistency. Additionally, the `proposal` command is missing frontmatter fields entirely. After reviewing CodeBuddy's official documentation, the correct format should use `description` and `argument-hint` fields with square bracket parameter format.
+
+## What Changes
+
+- Replace `category` and `tags` fields with `argument-hint` field in CodeBuddy frontmatter
+- Add missing frontmatter fields to the `proposal` command
+- Use correct square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- Ensure consistency with CodeBuddy's official documentation
+
+## Impact
+
+- Affected specs: cli-init, cli-update
+- Affected code: `src/core/configurators/slash/codebuddy.ts`
+- CodeBuddy users will get proper argument hints in the correct format for slash commands

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/specs/cli-init/spec.md

@@ -0,0 +1,75 @@
+## 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
+
+#### 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 that include CodeBuddy-compatible YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **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/workflows/openspec-proposal.md`, `.clinerules/workflows/openspec-apply.md`, and `.clinerules/workflows/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 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

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/specs/cli-update/spec.md

@@ -0,0 +1,56 @@
+## 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
+
+#### 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 CodeBuddy Code
+- **WHEN** `.codebuddy/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using the shared CodeBuddy templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **AND** preserve any user customizations outside the OpenSpec managed markers
+
+#### Scenario: Updating slash commands for Cline
+- **WHEN** `.clinerules/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Crush
+- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **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
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+#### 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
+- **AND** ensure templates include instructions for the relevant workflow stage

openspec/changes/archive/2026-01-09-fix-codebuddy-frontmatter-fields/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+
+- [x] 1.1 Update CodeBuddy frontmatter to use `argument-hint` instead of `category` and `tags`
+- [x] 1.2 Add missing frontmatter fields to the `proposal` command
+- [x] 1.3 Ensure all three commands (proposal, apply, archive) have consistent frontmatter structure
+- [x] 1.4 Test the changes by running `openspec init` and `openspec update`

openspec/changes/archive/2026-01-15-add-nix-ci-validation/design.md

@@ -0,0 +1,206 @@
+# Design: Nix CI Validation
+
+## Context
+
+OpenSpec recently added Nix flake support to enable Nix users to install the tool. This includes:
+- `flake.nix`: Nix package definition with pnpm dependency fetching
+- `scripts/update-flake.sh`: Automation script to update version and hash when releasing
+
+Currently, there is no CI validation ensuring these Nix artifacts remain functional. The existing CI workflow (.github/workflows/ci.yml) validates Node.js builds, tests, and linting across multiple platforms (Linux, macOS, Windows) but does not validate Nix builds.
+
+**Stakeholders**: Nix users, maintainers, contributors who need confidence that Nix support works.
+
+**Constraints**:
+- Must work in GitHub Actions Linux runners
+- Should minimize CI runtime impact (<5 minutes added)
+- Should support local testing with `act` for rapid iteration
+- Must integrate with existing required checks
+
+## Goals / Non-Goals
+
+**Goals**:
+- Validate `nix build` succeeds on every PR/push
+- Validate `scripts/update-flake.sh` executes without errors
+- Ensure Nix support doesn't regress silently
+- Support local testing with `act`
+- Optimize with caching to minimize CI time
+
+**Non-Goals**:
+- Testing on macOS (GitHub-hosted macOS runners are slower and more expensive; Nix flake already declares macOS support)
+- Building for all declared systems (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin) - focus on most common platform
+- Validating Nix flake quality/style (nixpkgs-fmt, etc.) - can be added later if needed
+- Running OpenSpec's full test suite through Nix build - existing CI already does this
+
+## Decisions
+
+### Decision 1: Use DeterminateSystems nix-installer-action
+
+**What**: Use `determinatesystems/nix-installer-action` for installing Nix in CI.
+
+**Why**:
+- Official GitHub Action maintained by Determinate Systems (Nix experts)
+- Handles GitHub Actions environment quirks automatically
+- Includes automatic caching configuration
+- More reliable than curl | sh installation script
+- Better error messages and diagnostics
+
+**Alternatives considered**:
+- Official Nix installer (`curl -L https://nixos.org/nix/install | sh`): Works but requires manual setup of flakes, caching, and CI-specific configuration
+- `cachix/install-nix-action`: Popular alternative but determinatesystems is more actively maintained and has better GHA integration
+
+### Decision 2: Use Magic Nix Cache for performance
+
+**What**: Use `determinatesystems/magic-nix-cache-action` for automatic binary caching.
+
+**Why**:
+- Zero-configuration caching for Nix store
+- Significantly reduces CI time on subsequent runs (from ~5min to ~1-2min)
+- Free for public repositories
+- Handles cache keys automatically
+
+**Alternatives considered**:
+- Manual Nix store caching with GitHub Actions cache: More complex, requires manual cache key management
+- Cachix: Excellent tool but requires account setup and token management
+- No caching: Acceptable for initial implementation, but poor developer experience
+
+### Decision 3: Separate job for Nix validation
+
+**What**: Create a dedicated `nix-validate` job in .github/workflows/ci.yml that runs in parallel with other jobs.
+
+**Why**:
+- Keeps Nix validation isolated from Node.js validation
+- Allows parallel execution for faster CI
+- Easier to debug when Nix-specific issues occur
+- Can be marked as required check independently
+
+**Alternatives considered**:
+- Add Nix steps to existing jobs: Creates coupling between Node.js and Nix validation, harder to maintain
+- Separate workflow file: Overkill for a single job, harder to manage required checks
+
+### Decision 4: Validate update script by executing it
+
+**What**: Run `scripts/update-flake.sh` as part of CI validation.
+
+**Why**:
+- Ensures the script doesn't break due to changes in package.json format, nix build output, or dependencies
+- Tests the full workflow users will follow when releasing
+- Catches errors early
+
+**Implementation approach**:
+- Execute script in a way that doesn't modify git state (or discard changes after)
+- Verify script exits with code 0
+- Optionally validate that flake.nix contains expected patterns after execution
+
+**Alternatives considered**:
+- Mock/dry-run mode: Would require modifying the script significantly
+- Skip validation: Risky - script could break and only be discovered at release time
+- Only run on release branches: Misses issues early in development
+
+### Decision 5: Run on pull_request and push to main
+
+**What**: Configure Nix validation job to run on:
+- `pull_request` events (any PR to main)
+- `push` events (direct pushes to main)
+- `workflow_dispatch` (manual trigger for testing)
+
+**Why**:
+- Catches issues before merge (pull_request)
+- Validates main branch stays healthy (push)
+- Allows manual testing without creating PRs (workflow_dispatch)
+
+### Decision 6: Support act for local testing
+
+**What**: Ensure workflow is compatible with `act` tool for local CI testing.
+
+**Why**:
+- Faster iteration when developing CI changes
+- Allows testing without pushing to GitHub
+- Reduces commit noise from CI debugging
+
+**Requirements**:
+- Use standard GitHub Actions syntax
+- Document any act-specific configuration needed
+- Test that Nix can be installed in act's Docker containers
+
+**Limitations**:
+- act may not perfectly replicate GitHub's runners, but close enough for validation
+
+## Risks / Trade-offs
+
+### Risk: CI runtime increase
+
+**Impact**: Adding Nix validation will increase total CI time by 2-5 minutes per run.
+
+**Mitigation**:
+- Run Nix job in parallel with existing jobs (no blocking delay)
+- Use magic-nix-cache for subsequent runs (~1-2 min with cache)
+- Configure appropriate timeout (10 minutes max)
+
+**Acceptance**: The benefit of preventing Nix regressions outweighs the cost.
+
+### Risk: Nix installer failures in CI
+
+**Impact**: Transient failures in Nix installation could block PRs.
+
+**Mitigation**:
+- Use determinatesystems action which has retry logic
+- Monitor for flaky failures and adjust if needed
+- Document troubleshooting steps
+
+**Acceptance**: Nix installation is generally stable in GHA; this is low risk.
+
+### Risk: Update script modifies git state
+
+**Impact**: Running update-flake.sh modifies flake.nix, which could cause CI to fail if git state is checked.
+
+**Mitigation**:
+- Run script in isolation without committing changes
+- Add `git checkout -- flake.nix` after validation
+- Or accept dirty git state in CI (doesn't affect build validation)
+
+**Acceptance**: Script validation is important enough to handle this carefully.
+
+### Risk: act compatibility issues
+
+**Impact**: Workflow might not work perfectly with act due to Docker environment differences.
+
+**Mitigation**:
+- Document known limitations
+- Focus on GitHub Actions as primary validation target
+- Use act as best-effort local testing
+
+**Acceptance**: act support is nice-to-have, not required.
+
+## Migration Plan
+
+### Phase 1: Add Nix job (new, non-required)
+1. Add `nix-validate` job to .github/workflows/ci.yml
+2. Configure to run in parallel with existing jobs
+3. Do NOT mark as required check initially
+4. Monitor for ~1 week to ensure stability
+
+### Phase 2: Make required
+1. After validation is stable, add to required checks
+2. Update branch protection rules in GitHub settings
+3. Document in CONTRIBUTING.md or README
+
+### Rollback Plan
+If Nix validation causes issues:
+1. Remove job from required checks in GitHub settings (immediate)
+2. Comment out or remove job from workflow (permanent fix)
+3. Investigate and fix issues
+4. Re-enable following same phased approach
+
+## Open Questions
+
+- **Q**: Should we test update-flake.sh on every CI run, or only when package.json or pnpm-lock.yaml changes?
+  - **A**: Test on every run for simplicity. The script is fast (<30 seconds) and catching regressions is valuable.
+
+- **Q**: Should we validate on macOS as well?
+  - **A**: No for initial implementation. Linux validation is sufficient and macOS runners are slower/more expensive. Can add later if users report macOS-specific issues.
+
+- **Q**: Should we run full OpenSpec tests through the Nix build?
+  - **A**: No. The Nix build already runs `pnpm test` as part of its build phase. Existing CI jobs cover testing thoroughly. Nix validation focuses on build success.
+
+- **Q**: What timeout should we use for the Nix validation job?
+  - **A**: Start with 10 minutes. With caching, jobs should complete in 1-3 minutes. Without cache (first run), 5-7 minutes is expected.

openspec/changes/archive/2026-01-15-add-nix-ci-validation/proposal.md

@@ -0,0 +1,21 @@
+# Add Nix CI Validation
+
+## Why
+
+The project recently added Nix flake support (flake.nix) and an automated update script (scripts/update-flake.sh) to enable Nix users to install OpenSpec. However, there is no CI validation ensuring these Nix artifacts continue to work as the project evolves. This creates risk that breaking changes could be merged without detection.
+
+## What Changes
+
+- Add a new GitHub Actions workflow job to validate Nix flake builds successfully
+- Add validation that the update-flake.sh script executes without errors
+- Test on Linux (where Nix support is most common)
+- Ensure CI fails if Nix build or update script breaks
+- Enable local testing with `act` for developers
+
+## Impact
+
+- Affected specs: New capability `ci-nix-validation`
+- Affected code: `.github/workflows/ci.yml` (add new job)
+- Affected infrastructure: GitHub Actions runners with Nix installed
+- Benefits: Prevents regressions in Nix support, gives confidence to Nix users
+- Trade-offs: Adds ~2-3 minutes to CI runtime

openspec/changes/archive/2026-01-15-add-nix-ci-validation/specs/ci-nix-validation/spec.md

@@ -0,0 +1,104 @@
+# CI Nix Validation Specification
+
+## ADDED Requirements
+
+### Requirement: Nix Flake Build Validation
+
+The CI system SHALL validate that the Nix flake builds successfully on every pull request and push to main.
+
+#### Scenario: Successful flake build
+
+- **WHEN** a pull request or push to main is made
+- **THEN** the CI SHALL execute `nix build` and verify it completes with exit code 0
+- **AND** the build output SHALL contain the openspec binary
+
+#### Scenario: Flake build failure
+
+- **WHEN** the Nix flake configuration is broken
+- **THEN** the CI job SHALL fail with a non-zero exit code
+- **AND** the CI SHALL prevent merging of the pull request
+
+#### Scenario: Multi-platform support check
+
+- **WHEN** the flake declares support for multiple systems
+- **THEN** the CI SHALL validate the flake builds on at least Linux (x86_64-linux)
+
+### Requirement: Update Script Validation
+
+The CI system SHALL validate that the update-flake.sh script executes successfully and produces valid output.
+
+#### Scenario: Update script execution
+
+- **WHEN** the CI runs the update script validation
+- **THEN** the script SHALL execute without errors
+- **AND** the script SHALL correctly extract the version from package.json
+- **AND** the script SHALL update flake.nix with the correct version
+
+#### Scenario: Update script with mock hash
+
+- **WHEN** validating the update script in CI
+- **THEN** the script SHALL be able to detect and extract the correct pnpm dependency hash
+- **AND** the flake.nix SHALL be updated with a valid sha256 hash
+
+### Requirement: CI Job Integration
+
+The Nix validation jobs SHALL be integrated into the existing GitHub Actions workflow and required for merge.
+
+#### Scenario: PR merge requirements
+
+- **WHEN** a pull request is created
+- **THEN** the Nix validation job SHALL be included in required checks
+- **AND** the PR SHALL NOT be mergeable until Nix validation passes
+
+#### Scenario: Job execution triggers
+
+- **WHEN** code is pushed to a pull request OR pushed to main OR manually triggered
+- **THEN** the Nix validation job SHALL execute automatically
+
+### Requirement: Local Testing Support
+
+The CI workflow SHALL be testable locally using the `act` tool to enable rapid iteration.
+
+#### Scenario: Local CI execution with act
+
+- **WHEN** a developer runs `act` with the Nix validation workflow
+- **THEN** the workflow SHALL execute in the local Docker environment
+- **AND** the developer SHALL receive feedback on Nix build status without pushing to GitHub
+
+#### Scenario: Act configuration compatibility
+
+- **WHEN** the workflow is designed
+- **THEN** it SHALL use standard GitHub Actions syntax compatible with `act`
+- **AND** any Nix-specific setup SHALL work in the act Docker environment
+
+### Requirement: Nix Installation in CI
+
+The CI environment SHALL have Nix properly installed and configured before running validation.
+
+#### Scenario: Nix installation step
+
+- **WHEN** the Nix validation job starts
+- **THEN** Nix SHALL be installed using the official Nix installer or determinatesystems/nix-installer-action
+- **AND** the Nix installation SHALL be cached for subsequent runs to improve performance
+
+#### Scenario: Nix configuration for CI
+
+- **WHEN** Nix is installed in CI
+- **THEN** it SHALL be configured to work in the GitHub Actions environment
+- **AND** experimental features (flakes, nix-command) SHALL be enabled
+
+### Requirement: CI Performance Optimization
+
+The Nix validation SHALL be optimized to minimize CI runtime impact.
+
+#### Scenario: Acceptable runtime
+
+- **WHEN** the Nix validation job runs
+- **THEN** it SHALL complete in under 5 minutes on a clean run
+- **AND** with caching, it SHALL complete in under 3 minutes on subsequent runs
+
+#### Scenario: Parallel execution
+
+- **WHEN** multiple CI jobs are running
+- **THEN** the Nix validation job SHALL run in parallel with other validation jobs (tests, lint)
+- **AND** SHALL NOT block other independent checks

openspec/changes/archive/2026-01-15-add-nix-ci-validation/tasks.md

@@ -0,0 +1,49 @@
+# Implementation Tasks
+
+## 1. Add Nix Installation to CI
+
+- [x] 1.1 Research Nix installation options for GitHub Actions (nix-installer-action vs manual install)
+- [x] 1.2 Add Nix installation step to .github/workflows/ci.yml
+- [x] 1.3 Configure Nix with experimental features enabled (flakes, nix-command)
+- [x] 1.4 Add Nix store caching to improve CI performance
+
+## 2. Create Nix Build Validation Job
+
+- [x] 2.1 Add new `nix-flake-validate` job to .github/workflows/ci.yml
+- [x] 2.2 Implement `nix build` step with proper error handling
+- [x] 2.3 Add verification step to confirm binary exists in build output
+- [x] 2.4 Add step to test binary execution (`nix run . -- --version`)
+
+## 3. Add Update Script Validation
+
+- [x] 3.1 Add job step to run scripts/update-flake.sh in dry-run or test mode
+- [x] 3.2 Verify script executes without errors
+- [x] 3.3 Add validation that version is correctly extracted from package.json
+- [x] 3.4 Verify flake.nix is updated with correct format (version and hash)
+
+## 4. Configure Job Dependencies and Requirements
+
+- [x] 4.1 Configure Nix validation job to run on pull_request and push events
+- [x] 4.2 Add Nix validation to required checks list
+- [x] 4.3 Configure job to run in parallel with existing test/lint jobs
+- [x] 4.4 Set appropriate timeout (5-10 minutes)
+
+## 5. Test with act Locally
+
+- [x] 5.1 Install act locally if not already available
+- [x] 5.2 Test Nix validation job using `act pull_request`
+- [x] 5.3 Verify act can run the workflow with Nix installed
+- [x] 5.4 Document any act-specific configuration needed in .actrc or README
+
+## 6. Documentation and Finalization
+
+- [x] 6.1 Add documentation about Nix CI validation to README or CONTRIBUTING.md
+- [x] 6.2 Document how to test CI locally with act
+- [ ] 6.3 Update CI badge or status indicators if needed
+- [ ] 6.4 Test end-to-end by creating a test PR
+
+## 7. Archive Change
+
+- [x] 7.1 After merge and verification, create new spec file at openspec/specs/ci-nix-validation/spec.md
+- [x] 7.2 Move change directory to openspec/changes/archive/[date]-add-nix-ci-validation/
+- [x] 7.3 Run `openspec validate --strict` to confirm archived change passes

openspec/changes/fix-cline-workflows-implementation/specs/cli-init/spec.md

@@ -1,11 +0,0 @@
-# Delta for CLI Init
-
-## MODIFIED Requirements
-### Requirement: Slash Command Configuration
-
-#### Scenario: Generating slash commands for Cline
-- **WHEN** the user selects Cline during initialization
-- **THEN** create `.clinerules/workflows/openspec-proposal.md`, `.clinerules/workflows/openspec-apply.md`, and `.clinerules/workflows/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

openspec/changes/make-validation-scope-aware/proposal.md

@@ -1,12 +0,0 @@
-## Why
-Validation currently errors on changes without spec deltas, even when the change is intentionally proposal-only or tooling-only. This creates false negatives and noisy CI.
-
-## What Changes
-- Make change validation scope-aware: validate only artifacts that exist.
-- Only error on "No deltas found" if spec delta files exist but parse to zero deltas.
-- Keep archive stricter: if specs exist but parse to zero deltas, fail; allow `--skip-specs` for tooling-only changes.
-
-## Impact
-- Affected specs: cli-validate
-- Affected code: `src/commands/validate.ts`, `src/core/validation/validator.ts`
-

openspec/changes/make-validation-scope-aware/specs/cli-validate/spec.md

@@ -1,25 +0,0 @@
-## ADDED Requirements
-### Requirement: Scope-Aware Change Validation
-The validator SHALL validate only artifacts that exist for a change, avoiding errors for proposal-only or tooling-only changes.
-
-#### Scenario: Proposal-only change
-- **WHEN** a change contains `proposal.md` but has no `specs/` directory or contains no `*/spec.md` files
-- **THEN** validate the proposal (Why/What sections)
-- **AND** do not require or validate spec deltas
-
-#### Scenario: Delta validation when specs exist
-- **WHEN** a change contains one or more `specs/<capability>/spec.md` files
-- **THEN** validate delta-formatted specs with existing rules (SHALL/MUST, scenarios, duplicates, conflicts)
-
-## MODIFIED Requirements
-### Requirement: Validation SHALL provide actionable remediation steps
-Validation output SHALL include specific guidance to fix each error, including expected structure, example headers, and suggested commands to verify fixes.
-
-#### Scenario: No deltas found in change
-- **WHEN** validating a change that contains `specs/` with one or more `*/spec.md` files but the parser finds zero deltas
-- **THEN** show error "No deltas found" with guidance:
-  - Ensure `openspec/changes/{id}/specs/` has `.md` files that include delta headers
-  - Use delta headers: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, `## RENAMED Requirements`
-  - Each requirement must include at least one `#### Scenario:` block
-  - Try: `openspec change show {id} --json --deltas-only` to inspect parsed deltas
-

openspec/changes/make-validation-scope-aware/tasks.md

@@ -1,16 +0,0 @@
-## 1. Validator changes
-- [ ] 1.1 Change `validateChangeDeltaSpecs` to only emit "Change must have at least one delta" when `specs/` exists and contains at least one `*/spec.md` but parsed total deltas is 0
-- [ ] 1.2 Return valid (no error) when `specs/` directory is missing or has no `spec.md` files
-
-## 2. CLI changes
-- [ ] 2.1 In bulk validation, keep current behavior (call delta validator). Behavior remains correct after 1.1
-- [ ] 2.2 Add a short INFO log in human-readable mode when a change has no `specs/` (optional)
-
-## 3. Documentation
-- [ ] 3.1 Update README and template: "Validation checks only existing artifacts. Proposal-only changes are valid without spec deltas."
-
-## 4. Tests
-- [ ] 4.1 Add test: proposal-only change passes validation without deltas
-- [ ] 4.2 Add test: specs present but zero parsed deltas → ERROR
-- [ ] 4.3 Add test: specs present with proper deltas → valid
-

openspec/changes/project-config/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: "2025-01-13"

openspec/changes/project-config/design.md

@@ -0,0 +1,665 @@
+# Design: Project Config
+
+## Context
+
+OpenSpec currently has a fixed schema resolution order:
+1. `--schema` CLI flag
+2. `.openspec.yaml` in change directory
+3. Hardcoded default: `"spec-driven"`
+
+This forces users who want project-level customization to fork entire schemas, even for simple additions like injecting tech stack context or adding artifact-specific rules.
+
+The proposal introduces `openspec/config.yaml` as a lightweight customization layer that sits between preset schemas and full forking. It allows teams to:
+- Set a default schema
+- Inject project context into all artifacts
+- Add per-artifact rules
+
+**Constraints:**
+- Must not break existing changes that lack config
+- Must maintain clean separation between "configure" (this) and "fork" (project-local-schemas)
+- Config is project-level only (no global/user-level config)
+
+**Key stakeholders:**
+- OpenSpec users who need light customization without forking
+- Teams sharing workflow conventions via committed config
+
+## Goals / Non-Goals
+
+**Goals:**
+- Load and parse `openspec/config.yaml` using Zod schema
+- Use config's `schema` field as default in schema resolution
+- Inject `context` into all artifact instructions
+- Inject `rules` into matching artifact instructions only
+- Gracefully handle missing or invalid config (fallback to defaults)
+
+**Non-Goals:**
+- Structural changes to schemas (`skip`, `add`, inheritance) - those belong in fork path
+- File references for context (`context: ./file.md`) - start with strings
+- Global user-level config (XDG dirs, etc.)
+- Config management commands (`openspec config init`) - manual creation for now
+- Migration from old setups (no existing config to migrate from)
+
+## Decisions
+
+### 1. Config File Format: YAML vs JSON
+
+**Decision:** Use YAML (`.yaml` extension, support `.yml` alias)
+
+**Rationale:**
+- YAML supports multi-line strings naturally (`context: |`)
+- More readable for documentation-heavy content
+- Consistent with `.openspec.yaml` used in changes
+- Easy to parse with existing `yaml` library
+
+**Alternatives considered:**
+- JSON: More strict, but poor multi-line string UX
+- TOML: Less familiar to most users
+
+### 2. Config Location: Project Root vs openspec/ Directory
+
+**Decision:** `./openspec/config.yaml` (inside openspec directory)
+
+**Rationale:**
+- Co-located with `openspec/schemas/` (project-local-schemas)
+- Keeps project root clean
+- Natural namespace for OpenSpec configuration
+- Mirrors structure used by other tools (e.g., `.github/`)
+
+**Alternatives considered:**
+- `./openspec.config.yaml` in root: Pollutes root, less clear ownership
+- XDG config directories: Out of scope, no global config yet
+
+### 3. Context Injection: XML Tags vs Markdown Sections
+
+**Decision:** Use XML-style tags `<context>` and `<rules>`
+
+**Rationale:**
+- Clear delimiters that don't conflict with Markdown
+- Agents can easily parse structure
+- Matches existing patterns in the codebase for special sections
+
+**Example:**
+```xml
+<context>
+Tech stack: TypeScript, React
+</context>
+
+<rules>
+- Include rollback plan
+</rules>
+
+<template>
+## Summary
+...
+</template>
+```
+
+**Alternatives considered:**
+- Markdown headers: Conflicts with template content
+- Comments: Less visible to agents
+
+### 4. Schema Resolution: Insert Position
+
+**Decision:** Config's `schema` field goes between change metadata and hardcoded default
+
+**New resolution order:**
+1. `--schema` CLI flag (explicit override)
+2. `.openspec.yaml` in change directory (change-specific binding)
+3. **`openspec/config.yaml` schema field** (NEW - project default)
+4. `"spec-driven"` (hardcoded fallback)
+
+**Rationale:**
+- Preserves CLI and change-level overrides (most specific wins)
+- Makes config act as a "project default"
+- Backwards compatible (no existing configs to conflict with)
+
+### 5. Rules Validation: Strict vs Permissive
+
+**Decision:** Warn on unknown artifact IDs, don't error
+
+**Rationale:**
+- Future-proof: If schema adds new artifacts, old configs don't break
+- Dev experience: Typos show warnings, but don't halt workflow
+- User can fix incrementally
+
+**Example:**
+```yaml
+rules:
+  proposal: [...]
+  testplan: [...]  # Schema doesn't have this artifact → WARN, not ERROR
+```
+
+### 6. Error Handling: Config Parse Failures
+
+**Decision:** Log warning and fall back to defaults (don't halt commands)
+
+**Rationale:**
+- Syntax errors in config shouldn't break all of OpenSpec
+- User can fix config incrementally
+- Commands remain usable during config development
+
+**Warning message:**
+```
+⚠️  Failed to parse openspec/config.yaml: [error details]
+    Falling back to default schema (spec-driven)
+```
+
+## Implementation Plan
+
+### Phase 1: Core Types and Loading
+
+**File: `src/core/project-config.ts` (NEW)**
+
+```typescript
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'fs';
+import { parse as parseYaml } from 'yaml';
+import { findProjectRoot } from '../utils/path-utils';
+
+/**
+ * Zod schema for project configuration.
+ *
+ * Purpose:
+ * 1. Documentation - clearly defines the config file structure
+ * 2. Type safety - TypeScript infers ProjectConfig type from schema
+ * 3. Runtime validation - uses safeParse() for resilient field-by-field validation
+ *
+ * Why Zod over manual validation:
+ * - Helps understand OpenSpec's data interfaces at a glance
+ * - Single source of truth for type and validation
+ * - Consistent with other OpenSpec schemas
+ */
+export const ProjectConfigSchema = z.object({
+  schema: z.string().min(1).describe('The workflow schema to use (e.g., "spec-driven", "tdd")'),
+  context: z.string().optional().describe('Project context injected into all artifact instructions'),
+  rules: z.record(
+    z.string(),
+    z.array(z.string())
+  ).optional().describe('Per-artifact rules, keyed by artifact ID'),
+});
+
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+
+const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit
+
+/**
+ * Read and parse openspec/config.yaml from project root.
+ * Uses resilient parsing - validates each field independently using Zod safeParse.
+ * Returns null if file doesn't exist.
+ * Returns partial config if some fields are invalid (with warnings).
+ */
+export function readProjectConfig(): ProjectConfig | null {
+  const projectRoot = findProjectRoot();
+
+  // Try both .yaml and .yml, prefer .yaml
+  let configPath = path.join(projectRoot, 'openspec', 'config.yaml');
+  if (!existsSync(configPath)) {
+    configPath = path.join(projectRoot, 'openspec', 'config.yml');
+    if (!existsSync(configPath)) {
+      return null; // No config is OK
+    }
+  }
+
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const raw = parseYaml(content);
+
+    if (!raw || typeof raw !== 'object') {
+      console.warn(`⚠️  openspec/config.yaml is not a valid YAML object`);
+      return null;
+    }
+
+    const config: Partial<ProjectConfig> = {};
+
+    // Parse schema field using Zod
+    const schemaField = z.string().min(1);
+    const schemaResult = schemaField.safeParse(raw.schema);
+    if (schemaResult.success) {
+      config.schema = schemaResult.data;
+    } else if (raw.schema !== undefined) {
+      console.warn(`⚠️  Invalid 'schema' field in config (must be non-empty string)`);
+    }
+
+    // Parse context field with size limit
+    if (raw.context !== undefined) {
+      const contextField = z.string();
+      const contextResult = contextField.safeParse(raw.context);
+
+      if (contextResult.success) {
+        const contextSize = Buffer.byteLength(contextResult.data, 'utf-8');
+        if (contextSize > MAX_CONTEXT_SIZE) {
+          console.warn(
+            `⚠️  Context too large (${(contextSize / 1024).toFixed(1)}KB, limit: ${MAX_CONTEXT_SIZE / 1024}KB)`
+          );
+          console.warn(`   Ignoring context field`);
+        } else {
+          config.context = contextResult.data;
+        }
+      } else {
+        console.warn(`⚠️  Invalid 'context' field in config (must be string)`);
+      }
+    }
+
+    // Parse rules field using Zod
+    if (raw.rules !== undefined) {
+      const rulesField = z.record(z.string(), z.array(z.string()));
+
+      // First check if it's an object structure
+      if (typeof raw.rules === 'object' && !Array.isArray(raw.rules)) {
+        const parsedRules: Record<string, string[]> = {};
+        let hasValidRules = false;
+
+        for (const [artifactId, rules] of Object.entries(raw.rules)) {
+          const rulesArrayResult = z.array(z.string()).safeParse(rules);
+
+          if (rulesArrayResult.success) {
+            // Filter out empty strings
+            const validRules = rulesArrayResult.data.filter(r => r.length > 0);
+            if (validRules.length > 0) {
+              parsedRules[artifactId] = validRules;
+              hasValidRules = true;
+            }
+            if (validRules.length < rulesArrayResult.data.length) {
+              console.warn(
+                `⚠️  Some rules for '${artifactId}' are empty strings, ignoring them`
+              );
+            }
+          } else {
+            console.warn(
+              `⚠️  Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`
+            );
+          }
+        }
+
+        if (hasValidRules) {
+          config.rules = parsedRules;
+        }
+      } else {
+        console.warn(`⚠️  Invalid 'rules' field in config (must be object)`);
+      }
+    }
+
+    // Return partial config even if some fields failed
+    return Object.keys(config).length > 0 ? (config as ProjectConfig) : null;
+
+  } catch (error) {
+    console.warn(`⚠️  Failed to parse openspec/config.yaml:`, error);
+    return null;
+  }
+}
+
+/**
+ * Validate artifact IDs in rules against a schema's artifacts.
+ * Called during instruction loading (when schema is known).
+ * Returns warnings for unknown artifact IDs.
+ */
+export function validateConfigRules(
+  rules: Record<string, string[]>,
+  validArtifactIds: Set<string>,
+  schemaName: string
+): string[] {
+  const warnings: string[] = [];
+
+  for (const artifactId of Object.keys(rules)) {
+    if (!validArtifactIds.has(artifactId)) {
+      const validIds = Array.from(validArtifactIds).sort().join(', ');
+      warnings.push(
+        `Unknown artifact ID in rules: "${artifactId}". ` +
+        `Valid IDs for schema "${schemaName}": ${validIds}`
+      );
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Suggest valid schema names when user provides invalid schema.
+ * Uses fuzzy matching to find similar names.
+ */
+export function suggestSchemas(
+  invalidSchemaName: string,
+  availableSchemas: { name: string; isBuiltIn: boolean }[]
+): string {
+  // Simple fuzzy match: Levenshtein distance
+  function levenshtein(a: string, b: string): number {
+    const matrix: number[][] = [];
+    for (let i = 0; i <= b.length; i++) {
+      matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+      matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+      for (let j = 1; j <= a.length; j++) {
+        if (b.charAt(i - 1) === a.charAt(j - 1)) {
+          matrix[i][j] = matrix[i - 1][j - 1];
+        } else {
+          matrix[i][j] = Math.min(
+            matrix[i - 1][j - 1] + 1,
+            matrix[i][j - 1] + 1,
+            matrix[i - 1][j] + 1
+          );
+        }
+      }
+    }
+    return matrix[b.length][a.length];
+  }
+
+  // Find closest matches (distance <= 3)
+  const suggestions = availableSchemas
+    .map(s => ({ ...s, distance: levenshtein(invalidSchemaName, s.name) }))
+    .filter(s => s.distance <= 3)
+    .sort((a, b) => a.distance - b.distance)
+    .slice(0, 3);
+
+  const builtIn = availableSchemas.filter(s => s.isBuiltIn).map(s => s.name);
+  const projectLocal = availableSchemas.filter(s => !s.isBuiltIn).map(s => s.name);
+
+  let message = `❌ Schema '${invalidSchemaName}' not found in openspec/config.yaml\n\n`;
+
+  if (suggestions.length > 0) {
+    message += `Did you mean one of these?\n`;
+    suggestions.forEach(s => {
+      const type = s.isBuiltIn ? 'built-in' : 'project-local';
+      message += `  - ${s.name} (${type})\n`;
+    });
+    message += '\n';
+  }
+
+  message += `Available schemas:\n`;
+  if (builtIn.length > 0) {
+    message += `  Built-in: ${builtIn.join(', ')}\n`;
+  }
+  if (projectLocal.length > 0) {
+    message += `  Project-local: ${projectLocal.join(', ')}\n`;
+  } else {
+    message += `  Project-local: (none found)\n`;
+  }
+
+  message += `\nFix: Edit openspec/config.yaml and change 'schema: ${invalidSchemaName}' to a valid schema name`;
+
+  return message;
+}
+```
+
+### Phase 2: Schema Resolution
+
+**File: `src/utils/change-metadata.ts`**
+
+Update `resolveSchemaForChange()` to check config:
+
+```typescript
+export function resolveSchemaForChange(
+  changeName: string,
+  cliSchema?: string
+): string {
+  // 1. CLI flag wins
+  if (cliSchema) {
+    return cliSchema;
+  }
+
+  // 2. Change metadata (.openspec.yaml)
+  const metadata = readChangeMetadata(changeName);
+  if (metadata?.schema) {
+    return metadata.schema;
+  }
+
+  // 3. Project config (NEW)
+  const projectConfig = readProjectConfig();
+  if (projectConfig?.schema) {
+    return projectConfig.schema;
+  }
+
+  // 4. Hardcoded default
+  return 'spec-driven';
+}
+```
+
+**File: `src/utils/change-utils.ts`**
+
+Update `createNewChange()` to use config schema:
+
+```typescript
+export function createNewChange(
+  changeName: string,
+  schema?: string
+): void {
+  // Use schema from config if not specified
+  const resolvedSchema = schema ?? readProjectConfig()?.schema ?? 'spec-driven';
+
+  // ... rest of change creation logic
+}
+```
+
+### Phase 3: Instruction Injection and Validation
+
+**File: `src/core/artifact-graph/instruction-loader.ts`**
+
+Update `loadInstructions()` to inject context, rules, and validate artifact IDs:
+
+```typescript
+// Session-level cache for validation warnings (avoid repeating same warnings)
+const shownWarnings = new Set<string>();
+
+export function loadInstructions(
+  changeName: string,
+  artifactId: string
+): InstructionOutput {
+  const projectConfig = readProjectConfig();
+
+  // Load base instructions from schema
+  const baseInstructions = loadSchemaInstructions(changeName, artifactId);
+  const schema = getSchemaForChange(changeName); // Assumes we have schema loaded
+
+  // Validate rules artifact IDs (only once per session)
+  if (projectConfig?.rules) {
+    const validArtifactIds = new Set(schema.artifacts.map(a => a.id));
+    const warnings = validateConfigRules(
+      projectConfig.rules,
+      validArtifactIds,
+      schema.name
+    );
+
+    // Show each unique warning only once per session
+    for (const warning of warnings) {
+      if (!shownWarnings.has(warning)) {
+        console.warn(`⚠️  ${warning}`);
+        shownWarnings.add(warning);
+      }
+    }
+  }
+
+  // Build enriched instruction with XML sections
+  let enrichedInstruction = '';
+
+  // Add context (all artifacts)
+  if (projectConfig?.context) {
+    enrichedInstruction += `<context>\n${projectConfig.context}\n</context>\n\n`;
+  }
+
+  // Add rules (only for matching artifact)
+  const rulesForArtifact = projectConfig?.rules?.[artifactId];
+  if (rulesForArtifact && rulesForArtifact.length > 0) {
+    enrichedInstruction += `<rules>\n`;
+    for (const rule of rulesForArtifact) {
+      enrichedInstruction += `- ${rule}\n`;
+    }
+    enrichedInstruction += `</rules>\n\n`;
+  }
+
+  // Add original template
+  enrichedInstruction += `<template>\n${baseInstructions.template}\n</template>`;
+
+  return {
+    ...baseInstructions,
+    instruction: enrichedInstruction,
+  };
+}
+```
+
+**Note on validation timing:** Rules are validated lazily during instruction loading (not at config load time) because:
+1. Schema isn't known at config load time (circular dependency)
+2. Warnings shown when user actually uses the feature (better UX)
+3. Validation warnings cached per session to avoid spam
+
+### Phase 4: Performance and Caching
+
+**Why config is read multiple times:**
+
+```typescript
+// Example: "openspec instructions proposal --change my-feature"
+
+// 1. Schema resolution (to know which schema to use)
+resolveSchemaForChange('my-feature')
+  → readProjectConfig()  // Read #1
+
+// 2. Instruction loading (to inject context and rules)
+loadInstructions('my-feature', 'proposal')
+  → readProjectConfig()  // Read #2
+
+// Result: Config read twice per command
+// More complex commands may read 3-5 times
+```
+
+**Performance Strategy:**
+
+V1 approach: No caching, read config fresh each time
+- Simpler implementation
+- No cache invalidation complexity
+- Acceptable if config reads are fast enough
+
+**Benchmark targets:**
+- Typical config (1KB context, 5 artifact rules): **< 10ms** per read (imperceptible even 5x)
+- Large config (50KB context limit): **< 50ms** per read (acceptable for rare case)
+
+**If benchmarks fail:** Add simple caching:
+
+```typescript
+// Simple in-memory cache with no invalidation
+let cachedConfig: { mtime: number; config: ProjectConfig | null } | null = null;
+
+export function readProjectConfig(): ProjectConfig | null {
+  const projectRoot = findProjectRoot();
+  const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
+
+  if (!existsSync(configPath)) {
+    return null;
+  }
+
+  const stats = statSync(configPath);
+  const mtime = stats.mtimeMs;
+
+  // Return cached config if file hasn't changed
+  if (cachedConfig && cachedConfig.mtime === mtime) {
+    return cachedConfig.config;
+  }
+
+  // Read and parse config
+  const config = parseConfigFile(configPath); // Extracted logic
+
+  // Cache result
+  cachedConfig = { mtime, config };
+  return config;
+}
+```
+
+**Performance testing task:** Add to Phase 6 (Testing)
+- Measure typical config read time (1KB context)
+- Measure large config read time (50KB context limit)
+- Measure repeated reads within single command
+- Document results, add caching only if needed
+
+## Data Flow
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                                                              │
+│  User runs: openspec instructions proposal --change foo     │
+│                                                              │
+└────────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+┌──────────────────────────────────────────────────────────────┐
+│  resolveSchemaForChange("foo")                               │
+│                                                              │
+│  1. Check CLI flag ✗                                         │
+│  2. Check .openspec.yaml ✗                                   │
+│  3. Check openspec/config.yaml ✓ → "spec-driven"             │
+│                                                              │
+└────────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+┌──────────────────────────────────────────────────────────────┐
+│  loadInstructions("foo", "proposal")                         │
+│                                                              │
+│  1. Load spec-driven/artifacts/proposal.yaml                 │
+│  2. Read openspec/config.yaml                                │
+│  3. Build enriched instruction:                              │
+│     - <context>...</context>                                 │
+│     - <rules>...</rules>  (if rules.proposal exists)         │
+│     - <template>...</template>                               │
+│                                                              │
+└────────────────────────────┬─────────────────────────────────┘
+                             │
+                             ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Return InstructionOutput with enriched content              │
+│                                                              │
+│  Agent sees project context + rules + schema template        │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Risks / Trade-offs
+
+**[Risk]** Config typos silently ignored (e.g., wrong artifact ID in rules)
+→ **Mitigation:** Validate and warn on unknown artifact IDs during config load. Don't error to allow forward compatibility.
+
+**[Risk]** Context grows too large, pollutes all artifact instructions
+→ **Mitigation:** Document recommended size (< 500 chars). If this becomes an issue, add per-artifact context override later.
+
+**[Risk]** YAML parsing errors break OpenSpec commands
+→ **Mitigation:** Catch parse errors, log warning, fall back to defaults. Commands remain functional.
+
+**[Risk]** Config cached incorrectly across commands
+→ **Mitigation:** Read config fresh on each `readProjectConfig()` call. No caching layer for v1 (simplicity over perf).
+
+**[Trade-off]** Context is injected into ALL artifacts
+→ **Benefit:** Consistent project knowledge across workflow
+→ **Cost:** Can't scope context to specific artifacts (yet)
+→ **Future:** Add `context: { global: "...", proposal: "..." }` if needed
+
+**[Trade-off]** Rules use artifact IDs, not human names
+→ **Benefit:** Stable identifiers (IDs don't change)
+→ **Cost:** User needs to know artifact IDs from schema
+→ **Mitigation:** Document common artifact IDs, show in `openspec status` output
+
+## Migration Plan
+
+**No migration needed** - this is a new feature with no existing state.
+
+**Rollout steps:**
+1. Deploy with config loading behind feature flag (optional, for safety)
+2. Test with internal project (this repo)
+3. Document in README with examples
+4. Remove feature flag if used
+
+**Rollback strategy:**
+- Config is additive only (doesn't break existing changes)
+- If bugs found, config parsing can be disabled with env var
+- Users can delete config file to restore old behavior
+
+## Open Questions
+
+**Q: Should context support file references (`context: ./CONTEXT.md`)?**
+**A (deferred):** Start with string-only. Add file reference later if users request it. Keeps v1 simple.
+
+**Q: Should we support `.yml` alias in addition to `.yaml`?**
+**A:** Yes, check both extensions. Prefer `.yaml` in docs, but accept `.yml` for users who prefer it.
+
+**Q: What if config's schema field references a non-existent schema?**
+**A:** Schema resolution will fail downstream. Show error when trying to load schema, suggest valid schema names.
+
+**Q: Should rules be validated against the resolved schema's artifact IDs?**
+**A:** Yes, validate and warn, but don't halt. This allows forward compatibility if schema evolves.

openspec/changes/project-config/proposal.md

@@ -0,0 +1,774 @@
+# Project Config
+
+## Summary
+
+Add `openspec/config.yaml` support for project-level configuration. This enables teams to customize OpenSpec behavior without forking schemas, by providing context and rules that are injected into artifact generation.
+
+## Motivation
+
+Currently, customizing OpenSpec requires forking entire schemas:
+- Must copy all files even to add one rule
+- Lose updates when openspec upgrades
+- High friction for simple customizations
+
+Most users don't need different workflow structure. They need to:
+- Provide project context (tech stack, conventions, constraints)
+- Add rules for specific artifacts (requirements, formatting preferences)
+
+## Design Decisions
+
+### Two-Path Model
+
+OpenSpec customization follows two distinct paths:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│   CONFIGURE (this change)         FORK (project-local-schemas)  │
+│   ─────────────────────           ────────────────────────────  │
+│                                                                 │
+│   Use a preset schema             Define your own schema        │
+│   + add context                   from scratch                  │
+│   + add rules                                                   │
+│                                                                 │
+│   openspec/config.yaml            openspec/schemas/my-flow/     │
+│                                                                 │
+│   ✓ Simple                        ✓ Full control                │
+│   ✓ Get updates                   ✗ You maintain everything     │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Config Schema
+
+```yaml
+# openspec/config.yaml
+
+# Required: which workflow schema to use
+schema: spec-driven
+
+# Optional: project context injected into all artifact prompts
+context: |
+  Tech stack: TypeScript, React, Node.js, PostgreSQL
+  API style: RESTful, documented in docs/api-conventions.md
+  Testing: Jest + React Testing Library
+  We value backwards compatibility for all public APIs
+
+# Optional: per-artifact rules (additive)
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams and notify in #platform-changes
+  specs:
+    - Use Given/When/Then format
+    - Reference existing patterns before inventing new ones
+  tasks:
+    - Each task should be completable in < 2 hours
+    - Include acceptance criteria
+```
+
+### What's NOT in Config
+
+The following were explicitly excluded to keep the model simple:
+
+| Feature | Decision | Rationale |
+|---------|----------|-----------|
+| `skip: [artifact]` | Not supported | Structural changes belong in fork path |
+| `add: [{...}]` | Not supported | Structural changes belong in fork path |
+| `extends: base` | Not supported | No inheritance, fork is full copy |
+| `context: ./file.md` | Not supported (yet) | Start with string, add file reference later if needed |
+
+### Field Definitions
+
+#### `schema` (required)
+
+Which workflow schema to use. Can be:
+- Built-in name: `spec-driven`, `tdd`
+- Project-local schema name: `my-workflow` (requires project-local-schemas change)
+
+This becomes the default schema for:
+- New changes created without `--schema` flag
+- Commands run on changes without `.openspec.yaml` metadata
+
+#### `context` (optional)
+
+A string containing project context. Injected into ALL artifact prompts.
+
+Use cases:
+- Tech stack description
+- Link to conventions/style guides
+- Team constraints or preferences
+- Domain-specific context
+
+#### `rules` (optional)
+
+Per-artifact rules, keyed by artifact ID. Additive to schema's built-in guidance.
+
+```yaml
+rules:
+  <artifact-id>:
+    - Rule 1
+    - Rule 2
+```
+
+Rules are injected into the specific artifact's prompt, not all prompts.
+
+### Injection Format
+
+When generating instructions for an artifact:
+
+```xml
+<context>
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+API style: RESTful, documented in docs/api-conventions.md
+...
+</context>
+
+<rules>
+- Include rollback plan
+- Identify affected teams and notify in #platform-changes
+</rules>
+
+<template>
+[Schema's built-in template content]
+</template>
+```
+
+Context appears for all artifacts. Rules only appear for the matching artifact.
+
+### Config Creation Strategy
+
+**Why integrate with `artifact-experimental-setup`?**
+
+This feature targets **experimental workflow users**. The decision to create config during experimental setup (rather than providing standalone commands) is intentional:
+
+**Rationale:**
+1. **Single entry point** - Users setting up experimental features are already in "configuration mode"
+2. **Contextual timing** - Natural to configure project defaults when setting up workflow
+3. **Avoids premature API surface** - No standalone `openspec config init` until feature graduates
+4. **Experimental scope** - Keeps config as experimental feature, not stable API
+5. **Progressive disclosure** - Users can skip and create manually later if needed
+
+**Evolution path:**
+
+```
+Today (Experimental):
+  openspec artifact-experimental-setup
+    → prompts for config creation
+    → creates .claude/skills/
+    → creates openspec/config.yaml
+
+Future (When graduating):
+  openspec init
+    → prompts for config creation
+    → creates openspec/ directory
+    → creates openspec/config.yaml
+
+  + standalone commands:
+    openspec config init
+    openspec config validate
+    openspec config set <key> <value>
+```
+
+**Why optional?**
+
+Config is **additive**, not required:
+- OpenSpec works without config (uses defaults)
+- Users can skip during setup and add manually later
+- Teams can start simple and add config when they feel friction
+- No config file in git = no problem, everyone gets defaults
+
+**Design principle:** The system never *requires* config, but makes it easy to create when users want customization.
+
+## Scope
+
+### In Scope
+
+**Core Config System:**
+- Define `ProjectConfig` type with Zod schema
+- Add `readProjectConfig()` function with graceful error handling
+- Update instruction generation to inject context (all artifacts)
+- Update instruction generation to inject rules (per-artifact)
+- Update schema resolution to use config's `schema` field as default
+- Update `openspec new change` to use config's schema as default
+
+**Config Creation (Experimental Setup):**
+- Extend `artifact-experimental-setup` command to optionally create config
+- Interactive prompts for schema selection (with description of each schema)
+- Interactive prompts for project context (optional multi-line input)
+- Interactive prompts for per-artifact rules (optional)
+- Validate config immediately after creation
+- Show clear "skip" option for users who want to create config manually later
+- Display created config location and usage examples
+
+### Out of Scope
+
+- `skip` / `add` for structural changes (use fork path for structural changes)
+- File reference for context (`context: ./CONTEXT.md`) - start with string, add later if needed
+- Global user-level config (XDG directories, etc.)
+- Integration with standard `openspec init` (will add when experimental graduates)
+- Standalone `openspec config init` command (may add in future change)
+- `openspec config validate` command (may add in future change)
+- Config editing/updating commands (users edit YAML directly)
+
+## User Experience
+
+### Setting Up Config (Experimental Workflow)
+
+When users set up the experimental workflow, they're prompted to optionally create config:
+
+```bash
+$ openspec artifact-experimental-setup
+
+Setting up experimental artifact workflow...
+
+✓ Created .claude/skills/openspec-explore/SKILL.md
+✓ Created .claude/skills/openspec-new-change/SKILL.md
+✓ Created .claude/skills/openspec-continue-change/SKILL.md
+✓ Created .claude/skills/openspec-apply-change/SKILL.md
+✓ Created .claude/skills/openspec-ff-change/SKILL.md
+✓ Created .claude/skills/openspec-sync-specs/SKILL.md
+✓ Created .claude/skills/openspec-archive-change/SKILL.md
+
+✓ Created .claude/commands/opsx/explore.md
+✓ Created .claude/commands/opsx/new.md
+✓ Created .claude/commands/opsx/continue.md
+✓ Created .claude/commands/opsx/apply.md
+✓ Created .claude/commands/opsx/ff.md
+✓ Created .claude/commands/opsx/sync.md
+✓ Created .claude/commands/opsx/archive.md
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Project Configuration (Optional)
+
+Configure project defaults for OpenSpec workflows.
+
+? Create openspec/config.yaml? (Y/n) Y
+
+? Default schema for new changes?
+  ❯ spec-driven (proposal → specs → design → tasks)
+    tdd (spec → tests → implementation → docs)
+
+? Add project context? (optional)
+  Context is shown to AI when creating artifacts.
+  Examples: tech stack, conventions, style guides, domain knowledge
+
+  Press Enter to skip, or type/paste context:
+  │ Tech stack: TypeScript, React, Node.js, PostgreSQL
+  │ API style: RESTful, documented in docs/api-conventions.md
+  │ Testing: Jest + React Testing Library
+  │ We value backwards compatibility for all public APIs
+  │
+  [Press Enter when done]
+
+? Add per-artifact rules? (optional) (Y/n) Y
+
+  Which artifacts should have custom rules?
+  [Space to select, Enter when done]
+  ◯ proposal
+  ◉ specs
+  ◯ design
+  ◯ tasks
+
+? Rules for specs artifact:
+  Enter rules one per line, press Enter on empty line to finish:
+  │ Use Given/When/Then format for scenarios
+  │ Reference existing patterns before inventing new ones
+  │
+  [Empty line to finish]
+
+✓ Created openspec/config.yaml
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎉 Setup Complete!
+
+📖 Config created at: openspec/config.yaml
+   • Default schema: spec-driven
+   • Project context: Added (4 lines)
+   • Rules: 1 artifact configured
+
+Usage:
+  • New changes automatically use 'spec-driven' schema
+  • Context injected into all artifact instructions
+  • Rules applied to matching artifacts
+
+To share with team:
+  git add openspec/config.yaml .claude/
+  git commit -m "Setup OpenSpec experimental workflow with project config"
+
+[Rest of experimental setup output...]
+```
+
+**Key UX decisions:**
+
+1. **Prompted during setup** - Natural place since users are already configuring experimental features
+2. **Optional at every step** - Clear skip options, no forced configuration
+3. **Guided prompts** - Schema descriptions, example context, artifact selection
+4. **Immediate validation** - Config is validated after creation, errors shown immediately
+5. **Clear output** - Shows exactly what was created and how it affects workflow
+
+### Setting Up Config (Manual Creation)
+
+Users can also create config manually (or skip during setup and add later):
+
+```bash
+# Create config file manually
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  We follow REST conventions documented in docs/api.md
+  All changes require backwards compatibility consideration
+
+rules:
+  proposal:
+    - Must include rollback plan
+    - Must identify affected teams
+  specs:
+    - Use Given/When/Then format
+EOF
+```
+
+### Effect on Workflow
+
+Once config is created, it affects the experimental workflow in three ways:
+
+**1. Default Schema Selection**
+
+```bash
+# Before config: must specify schema
+/opsx:new my-feature --schema spec-driven
+
+# After config (with schema: spec-driven): schema is automatic
+/opsx:new my-feature
+# Automatically uses spec-driven from config
+
+# Override still works
+/opsx:new my-feature --schema tdd
+# Uses tdd, ignoring config
+```
+
+**2. Context Injection (All Artifacts)**
+
+```bash
+# Get instructions for any artifact
+openspec instructions proposal --change my-feature
+
+# Output now includes project context:
+<context>
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+API style: RESTful, documented in docs/api-conventions.md
+Testing: Jest + React Testing Library
+We value backwards compatibility for all public APIs
+</context>
+
+<template>
+[Schema's proposal template]
+</template>
+```
+
+Context appears in instructions for **all artifacts** (proposal, specs, design, tasks).
+
+**3. Rules Injection (Per-Artifact)**
+
+```bash
+# Get instructions for artifact with rules configured
+openspec instructions specs --change my-feature
+
+# Output includes artifact-specific rules:
+<context>
+[Project context]
+</context>
+
+<rules>
+- Use Given/When/Then format for scenarios
+- Reference existing patterns before inventing new ones
+</rules>
+
+<template>
+[Schema's specs template]
+</template>
+```
+
+Rules only appear for the **specific artifact** they're configured for.
+
+**Artifacts without rules** (e.g., design, tasks) don't get a `<rules>` section:
+
+```bash
+openspec instructions design --change my-feature
+# Output: <context> then <template> only (no rules)
+```
+
+### Team Sharing
+
+```bash
+# Commit config
+git add openspec/config.yaml
+git commit -m "Add project config with context and rules"
+
+# Everyone gets the same context and rules automatically
+```
+
+## Implementation Notes
+
+### Files to Modify/Create
+
+| File | Changes |
+|------|---------|
+| `src/core/project-config.ts` | **NEW FILE:** Types, parsing, reading, validation helpers |
+| `src/core/artifact-graph/instruction-loader.ts` | Inject context (all artifacts) and rules (per-artifact) |
+| `src/utils/change-utils.ts` | Use config schema as default in `createChange()` |
+| `src/utils/change-metadata.ts` | Update `resolveSchemaForChange()` to check config |
+| `src/commands/artifact-workflow.ts` | Extend `artifactExperimentalSetupCommand()` to prompt for config creation |
+| `src/core/config-prompts.ts` | **NEW FILE:** Interactive prompts for config creation (reusable) |
+
+### Config Location
+
+Always at `./openspec/config.yaml` relative to project root. No XDG/global config for simplicity.
+
+### Resolution Order Update
+
+Schema selection order becomes:
+
+```
+1. --schema CLI flag                    # Explicit override
+2. .openspec.yaml in change directory   # Change-specific binding
+3. openspec/config.yaml schema field    # Project default (NEW)
+4. "spec-driven"                        # Hardcoded fallback
+```
+
+### Validation
+
+- `schema` must be a valid schema name (exists in resolution)
+- `context` must be string
+- `rules` must be object with string keys (artifact IDs) and array values
+- Unknown artifact IDs in `rules` should warn, not error (allows forward compat)
+
+### Experimental Setup Integration
+
+**Changes to `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts`:**
+
+After creating skills and commands, the setup command will:
+
+1. **Display section header:**
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   📋 Project Configuration (Optional)
+   Configure project defaults for OpenSpec workflows.
+   ```
+
+2. **Prompt: Create config?**
+   - Yes/No prompt with default "Yes"
+   - If No → skip entire config section, show usage instructions
+   - If Yes → continue to detailed prompts
+
+3. **Prompt: Schema selection**
+   - Use `listSchemasWithInfo()` to get available schemas
+   - Display each with description and artifact flow
+   - Default to first schema (likely "spec-driven")
+
+4. **Prompt: Project context**
+   - Multi-line input (or editor if available)
+   - Show examples: "tech stack, conventions, style guides"
+   - Allow empty (skip)
+
+5. **Prompt: Per-artifact rules**
+   - Yes/No prompt, default "No" (rules are less common)
+   - If Yes:
+     - Show checklist of artifacts from selected schema
+     - For each selected artifact, prompt for rules (line-by-line input)
+     - Allow empty line to finish each artifact's rules
+
+6. **Create and validate config:**
+   - Build `ProjectConfig` object from inputs
+   - Validate with Zod schema
+   - Write to `openspec/config.yaml` using YAML serializer
+   - If validation fails, show error and ask to retry or skip
+
+7. **Display success summary:**
+   - Path to created config
+   - Summary: schema used, context added (line count), rules count
+   - Usage examples showing how config affects workflow
+   - Suggestion to commit config to git
+
+**Error handling:**
+- Invalid schema selection → show available schemas with fuzzy match suggestions, retry
+- Context too large (>50KB) → reject with error, ask to reduce size
+- Rules reference invalid artifact → warn but continue (forward compat)
+- File write fails → show error, suggest manual creation
+- Config already exists → show message, skip config section, continue with setup
+- User cancellation (Ctrl+C) → log "Config creation cancelled", continue with rest of setup (skills/commands already created)
+
+**If config already exists:**
+
+When `openspec/config.yaml` already exists:
+
+```bash
+$ openspec artifact-experimental-setup
+
+[Skills and commands created...]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Project Configuration
+
+ℹ️  openspec/config.yaml already exists. Skipping config creation.
+
+   To update config, edit openspec/config.yaml manually or:
+   1. Delete openspec/config.yaml
+   2. Run openspec artifact-experimental-setup again
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Rest of setup output...]
+```
+
+This prevents accidentally overwriting user's config.
+
+**Implementation approach:**
+
+Create separate `src/core/config-prompts.ts` module:
+
+```typescript
+export interface ConfigPromptResult {
+  createConfig: boolean;
+  schema?: string;
+  context?: string;
+  rules?: Record<string, string[]>;
+}
+
+export async function promptForConfig(): Promise<ConfigPromptResult> {
+  // Prompt logic using inquirer or similar
+  // Returns structured result for config creation
+  // Throws ExitPromptError on Ctrl+C (handled by caller)
+}
+```
+
+**Ctrl+C handling in setup command:**
+
+```typescript
+try {
+  const configResult = await promptForConfig();
+  if (configResult.createConfig) {
+    writeConfigFile(configResult);
+    console.log('✓ Created openspec/config.yaml');
+  }
+} catch (error) {
+  if (error.name === 'ExitPromptError') {
+    console.log('\nℹ️  Config creation cancelled');
+    console.log('   Skills and commands already created');
+    console.log('   Run setup again to create config later');
+    // Continue with rest of setup (not a fatal error)
+  } else {
+    throw error; // Re-throw unexpected errors
+  }
+}
+```
+
+This keeps prompts reusable and testable separately from the setup command.
+
+### Dependencies
+
+**Interactive Prompting Library:**
+
+The experimental setup command will need an interactive prompting library for the config creation flow. Options:
+
+1. **@inquirer/prompts** (recommended)
+   - Modern, tree-shakeable, TypeScript-first
+   - Individual imports: `@inquirer/input`, `@inquirer/confirm`, `@inquirer/checkbox`, `@inquirer/editor`
+   - Already used in OpenSpec (if not, lightweight addition)
+
+2. **inquirer** (classic)
+   - More established, larger ecosystem
+   - Heavier bundle size
+   - Single package with all prompt types
+
+**Prompts needed:**
+- `confirm` - "Create config?" "Add rules?"
+- `select` - Schema selection with descriptions
+- `editor` or multi-line `input` - Project context
+- `checkbox` - Artifact selection for rules
+- `input` (repeated) - Rule entry (line-by-line)
+
+**Alternative (no dependency):**
+
+Use Node's built-in `readline` for basic prompts:
+- More code to write
+- Less polished UX (no arrow key navigation, checkbox selection)
+- Zero dependency cost
+
+**Recommendation:** Use `@inquirer/prompts` for best UX. Config setup is a one-time operation where UX matters.
+
+### YAML Serialization
+
+Config creation needs YAML serialization:
+
+- **yaml** package (already a dependency)
+- Use `yaml.stringify()` to write config
+- Preserve multi-line strings with `|` literal style
+- Format: 2-space indent, no quotes unless needed
+
+Example:
+```typescript
+import { stringify } from 'yaml';
+
+const config = {
+  schema: 'spec-driven',
+  context: 'Multi-line\ncontext\nhere',
+  rules: { proposal: ['Rule 1', 'Rule 2'] }
+};
+
+const yamlContent = stringify(config, {
+  indent: 2,
+  defaultStringType: 'QUOTE_DOUBLE',
+  defaultKeyType: 'PLAIN',
+});
+// context will use | literal style automatically for multi-line
+```
+
+## Testing Considerations
+
+**Core Config Functionality:**
+- Create config with all fields (schema, context, rules), verify parsing
+- Create minimal config (schema only), verify parsing
+- Verify context appears in instruction output for all artifacts
+- Verify rules appear only for matching artifact (not all artifacts)
+- Verify schema from config is used for new changes
+- Verify CLI `--schema` flag overrides config
+- Verify change's `.openspec.yaml` overrides config
+- Verify graceful handling of missing config (fallback to defaults)
+- Verify graceful handling of invalid YAML syntax (warning, fallback)
+- Verify graceful handling of invalid schema (warning, show valid schemas)
+- Verify unknown artifact IDs in rules emit warnings but don't halt
+
+**Schema Resolution Precedence:**
+- Test all four levels of schema resolution:
+  1. CLI flag `--schema` (highest priority)
+  2. Change metadata `.openspec.yaml`
+  3. Project config `openspec/config.yaml`
+  4. Hardcoded default "spec-driven" (lowest priority)
+- Verify each level correctly overrides lower levels
+
+**Context and Rules Injection:**
+- Verify context injection uses `<context>` XML-style tags
+- Verify rules injection uses `<rules>` XML-style tags with bullets
+- Verify injection order: `<context>` → `<rules>` → `<template>`
+- Verify multi-line context is preserved
+- Verify special characters in context/rules are not escaped
+- Verify empty context/rules don't create tags
+
+**Experimental Setup Integration:**
+- Test `artifact-experimental-setup` with user skipping config creation
+- Test `artifact-experimental-setup` with minimal config (schema only)
+- Test `artifact-experimental-setup` with full config (schema + context + rules)
+- Test schema selection from available schemas
+- Test multi-line context input
+- Test per-artifact rules prompts
+- Test artifact selection (checkboxes)
+- Test validation errors during config creation
+- Test file write errors (permissions, etc.)
+- Verify created config can be parsed by `readProjectConfig()`
+- Verify success summary shows correct information
+
+**Edge Cases:**
+- Config file exists but is empty → treat as invalid, warn
+- Config has `.yml` extension instead of `.yaml` → accept both
+- Both `.yaml` and `.yml` exist → prefer `.yaml`
+- Context contains YAML-significant characters → properly escape in output
+- Rules array contains empty strings → filter out or warn
+- Schema references non-existent schema → error with suggestions
+- Config in subdirectory (not project root) → not found, use defaults
+
+**Backward Compatibility:**
+- Existing projects without config continue to work
+- Existing changes with `.openspec.yaml` metadata aren't affected by config
+- Adding config to existing project doesn't break in-progress changes
+
+**Integration Tests:**
+- Create config → create change → verify schema used
+- Create config → get instructions → verify context injected
+- Create config → get instructions → verify rules injected
+- Update config → verify changes reflected immediately (no caching)
+- Run `artifact-experimental-setup` → create config → create change → verify flow
+
+## Related Changes
+
+- **project-local-schemas**: Enables `schema: my-workflow` to reference project-local schemas
+
+## Appendix: Full Config Schema
+
+```typescript
+import { z } from 'zod';
+
+// Zod schema serves as both runtime validation and documentation
+// Type is inferred from schema for type safety
+export const ProjectConfigSchema = z.object({
+  // Required: which schema to use (e.g., "spec-driven", "tdd", or project-local schema name)
+  schema: z.string().min(1).describe('The workflow schema to use (e.g., "spec-driven", "tdd")'),
+
+  // Optional: project context (injected into all artifact instructions)
+  // Max size: 50KB (enforced during parsing)
+  context: z.string().optional().describe('Project context injected into all artifact instructions'),
+
+  // Optional: per-artifact rules (additive to schema's built-in guidance)
+  rules: z.record(
+    z.string(),           // artifact ID
+    z.array(z.string())   // list of rules
+  ).optional().describe('Per-artifact rules, keyed by artifact ID'),
+});
+
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+
+// Note: Parsing uses safeParse() on individual fields for resilient error handling
+// Invalid fields are warned about but don't prevent other fields from being loaded
+```
+
+## Appendix: Visual Summary
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                 │
+│   User provides:                                                │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ openspec/config.yaml                                    │   │
+│   │                                                         │   │
+│   │ schema: spec-driven                                     │   │
+│   │ context: "We use React, TypeScript..."                  │   │
+│   │ rules:                                                  │   │
+│   │   proposal: [...]                                       │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                              │                                  │
+│                              ▼                                  │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ OpenSpec merges:                                        │   │
+│   │                                                         │   │
+│   │   Schema (spec-driven)                                  │   │
+│   │   + User's context                                      │   │
+│   │   + User's rules                                        │   │
+│   │   ─────────────────────────                             │   │
+│   │   = Enriched instructions                               │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                              │                                  │
+│                              ▼                                  │
+│   ┌─────────────────────────────────────────────────────────┐   │
+│   │ Agent sees (for proposal artifact):                     │   │
+│   │                                                         │   │
+│   │ <context>                                               │   │
+│   │ We use React, TypeScript...                             │   │
+│   │ </context>                                              │   │
+│   │                                                         │   │
+│   │ <rules>                                                 │   │
+│   │ - Include rollback plan                                 │   │
+│   │ - Identify affected teams                               │   │
+│   │ </rules>                                                │   │
+│   │                                                         │   │
+│   │ <template>                                              │   │
+│   │ [Built-in proposal template]                            │   │
+│   │ </template>                                             │   │
+│   └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```

openspec/changes/project-config/specs/config-loading/spec.md

@@ -0,0 +1,119 @@
+# Spec: Config Loading
+
+## ADDED Requirements
+
+### Requirement: Load project config from openspec/config.yaml
+
+The system SHALL read and parse the project configuration file located at `openspec/config.yaml` relative to the project root.
+
+#### Scenario: Valid config file exists
+- **WHEN** `openspec/config.yaml` exists with valid YAML content
+- **THEN** system parses the file and returns a ProjectConfig object
+
+#### Scenario: Config file does not exist
+- **WHEN** `openspec/config.yaml` does not exist
+- **THEN** system returns null without error
+
+#### Scenario: Config file has invalid YAML syntax
+- **WHEN** `openspec/config.yaml` contains malformed YAML
+- **THEN** system logs a warning message and returns null
+
+#### Scenario: Config file has valid YAML but invalid schema
+- **WHEN** `openspec/config.yaml` contains valid YAML that fails Zod schema validation
+- **THEN** system logs a warning message with validation details and returns null
+
+### Requirement: Support .yml file extension alias
+
+The system SHALL accept both `.yaml` and `.yml` file extensions for the config file.
+
+#### Scenario: Config file uses .yml extension
+- **WHEN** `openspec/config.yml` exists and `openspec/config.yaml` does not exist
+- **THEN** system reads from `openspec/config.yml`
+
+#### Scenario: Both .yaml and .yml exist
+- **WHEN** both `openspec/config.yaml` and `openspec/config.yml` exist
+- **THEN** system prefers `openspec/config.yaml`
+
+### Requirement: Use resilient field-by-field parsing
+
+The system SHALL parse each config field independently, collecting valid fields and warning about invalid ones without rejecting the entire config.
+
+#### Scenario: Schema field is valid
+- **WHEN** config contains `schema: "spec-driven"`
+- **THEN** schema field is included in returned config
+
+#### Scenario: Schema field is missing
+- **WHEN** config lacks the `schema` field
+- **THEN** no warning is logged (field is optional at parse level)
+
+#### Scenario: Schema field is empty string
+- **WHEN** config contains `schema: ""`
+- **THEN** warning is logged and schema field is not included in returned config
+
+#### Scenario: Schema field is invalid type
+- **WHEN** config contains `schema: 123` (number instead of string)
+- **THEN** warning is logged and schema field is not included in returned config
+
+#### Scenario: Context field is valid
+- **WHEN** config contains `context: "Tech stack: TypeScript"`
+- **THEN** context field is included in returned config
+
+#### Scenario: Context field is invalid type
+- **WHEN** config contains `context: 123` (number instead of string)
+- **THEN** warning is logged and context field is not included in returned config
+
+#### Scenario: Rules field has valid structure
+- **WHEN** config contains `rules: { proposal: ["Rule 1"], specs: ["Rule 2"] }`
+- **THEN** rules field is included in returned config with valid rules
+
+#### Scenario: Rules field has non-array value for artifact
+- **WHEN** config contains `rules: { proposal: "not an array", specs: ["Valid"] }`
+- **THEN** warning is logged for proposal, but specs rules are still included in returned config
+
+#### Scenario: Rules array contains non-string elements
+- **WHEN** config contains `rules: { proposal: ["Valid rule", 123, ""] }`
+- **THEN** only "Valid rule" is included, warning logged about invalid elements
+
+#### Scenario: Mix of valid and invalid fields
+- **WHEN** config contains valid schema, invalid context type, valid rules
+- **THEN** config is returned with schema and rules fields, warning logged about context
+
+### Requirement: Enforce context size limit
+
+The system SHALL reject context fields exceeding 50KB and log a warning.
+
+#### Scenario: Context within size limit
+- **WHEN** config contains context of 1KB
+- **THEN** context is included in returned config
+
+#### Scenario: Context at size limit
+- **WHEN** config contains context of exactly 50KB
+- **THEN** context is included in returned config
+
+#### Scenario: Context exceeds size limit
+- **WHEN** config contains context of 51KB
+- **THEN** warning is logged with size and limit, context field is not included in returned config
+
+### Requirement: Defer artifact ID validation to instruction loading
+
+The system SHALL NOT validate artifact IDs in rules during config load time. Validation happens during instruction loading when schema is known.
+
+#### Scenario: Config with rules is loaded
+- **WHEN** config contains `rules: { unknownartifact: [...] }`
+- **THEN** config is loaded successfully without validation errors
+
+#### Scenario: Validation happens at instruction load time
+- **WHEN** instructions are loaded for any artifact and config has unknown artifact IDs in rules
+- **THEN** warnings are emitted about unknown artifact IDs (see rules-injection spec for details)
+
+### Requirement: Gracefully handle config errors without halting
+
+The system SHALL continue operation with default values when config loading or parsing fails.
+
+#### Scenario: Config parse failure during command execution
+- **WHEN** config file has syntax errors and user runs `openspec new change`
+- **THEN** command executes using default schema "spec-driven"
+
+#### Scenario: Warning is visible to user
+- **WHEN** config loading fails
+- **THEN** system outputs warning message to stderr with details about the failure

openspec/changes/project-config/specs/context-injection/spec.md

@@ -0,0 +1,51 @@
+# Spec: Context Injection
+
+## ADDED Requirements
+
+### Requirement: Inject context into all artifact instructions
+
+The system SHALL inject the context field from project config into instructions for all artifacts, wrapped in XML-style `<context>` tags.
+
+#### Scenario: Config has context field
+- **WHEN** config contains `context: "Tech stack: TypeScript, React"`
+- **THEN** instruction output includes `<context>\nTech stack: TypeScript, React\n</context>`
+
+#### Scenario: Config has no context field
+- **WHEN** config omits the context field or context is undefined
+- **THEN** instruction output does not include `<context>` tags
+
+#### Scenario: Context is multi-line string
+- **WHEN** config contains context with multiple lines
+- **THEN** instruction output preserves line breaks within `<context>` tags
+
+#### Scenario: Context applied to all artifacts
+- **WHEN** instructions are loaded for any artifact (proposal, specs, design, tasks)
+- **THEN** context section appears in all instruction outputs
+
+### Requirement: Format context with XML-style tags
+
+The system SHALL wrap context content in `<context>` opening and `</context>` closing tags with content on separate lines.
+
+#### Scenario: Context tag structure
+- **WHEN** context is injected into instructions
+- **THEN** format is exactly `<context>\n{content}\n</context>\n\n`
+
+#### Scenario: Context appears before template
+- **WHEN** instructions are generated with context
+- **THEN** `<context>` section appears before the `<template>` section
+
+### Requirement: Preserve context content exactly as provided
+
+The system SHALL inject context content without modification, escaping, or interpretation.
+
+#### Scenario: Context contains special characters
+- **WHEN** context includes characters like `<`, `>`, `&`, quotes
+- **THEN** characters are preserved exactly as written in the config
+
+#### Scenario: Context contains URLs
+- **WHEN** context includes URLs like "docs at https://example.com"
+- **THEN** URLs are preserved exactly in the injected content
+
+#### Scenario: Context contains markdown
+- **WHEN** context includes markdown formatting like `**bold**` or `[links](url)`
+- **THEN** markdown is preserved without rendering or escaping

openspec/changes/project-config/specs/rules-injection/spec.md

@@ -0,0 +1,99 @@
+# Spec: Rules Injection
+
+## ADDED Requirements
+
+### Requirement: Inject rules only for matching artifact
+
+The system SHALL inject rules from config into instructions only when the artifact ID matches a key in the rules object.
+
+#### Scenario: Rules exist for the artifact
+- **WHEN** loading instructions for "proposal" and config has `rules: { proposal: ["Rule 1", "Rule 2"] }`
+- **THEN** instruction output includes rules section with both rules
+
+#### Scenario: No rules for the artifact
+- **WHEN** loading instructions for "design" and config has `rules: { proposal: [...] }`
+- **THEN** instruction output does not include `<rules>` tags
+
+#### Scenario: Rules object is undefined
+- **WHEN** config omits the rules field or rules is undefined
+- **THEN** instruction output does not include `<rules>` tags for any artifact
+
+#### Scenario: Rules array is empty for artifact
+- **WHEN** config has `rules: { proposal: [] }`
+- **THEN** instruction output does not include `<rules>` tags
+
+### Requirement: Format rules with XML-style tags and bullet list
+
+The system SHALL wrap rules in `<rules>` tags with each rule as a bulleted list item.
+
+#### Scenario: Single rule for artifact
+- **WHEN** config has `rules: { proposal: ["Include rollback plan"] }`
+- **THEN** instruction output includes `<rules>\n- Include rollback plan\n</rules>\n\n`
+
+#### Scenario: Multiple rules for artifact
+- **WHEN** config has `rules: { proposal: ["Rule 1", "Rule 2", "Rule 3"] }`
+- **THEN** instruction output includes each rule as separate bullet point
+
+#### Scenario: Rules appear after context and before template
+- **WHEN** instructions are generated with both context and rules
+- **THEN** order is `<context>` then `<rules>` then `<template>`
+
+### Requirement: Preserve rule text exactly as provided
+
+The system SHALL inject rule text without modification, escaping, or interpretation.
+
+#### Scenario: Rule contains markdown
+- **WHEN** rule includes markdown like "Use **Given/When/Then** format"
+- **THEN** markdown is preserved in the injected content
+
+#### Scenario: Rule contains special characters
+- **WHEN** rule includes characters like `<`, `>`, quotes
+- **THEN** characters are preserved exactly as written
+
+#### Scenario: Rule is multi-line string
+- **WHEN** rule text contains line breaks
+- **THEN** line breaks are preserved within the bullet point
+
+### Requirement: Support multiple artifacts with different rules
+
+The system SHALL allow different rule sets for different artifacts in the same config.
+
+#### Scenario: Multiple artifacts have rules
+- **WHEN** config has `rules: { proposal: ["P1"], specs: ["S1", "S2"], tasks: ["T1"] }`
+- **THEN** proposal instructions show only ["P1"], specs show only ["S1", "S2"], tasks show only ["T1"]
+
+#### Scenario: Some artifacts have rules, others do not
+- **WHEN** config has rules for proposal and specs only
+- **THEN** design and tasks instructions have no `<rules>` section
+
+### Requirement: Rules are additive to schema guidance
+
+The system SHALL add config rules to the schema's built-in artifact instruction, not replace it.
+
+#### Scenario: Artifact has schema instruction and config rules
+- **WHEN** artifact has built-in instruction from schema and config provides rules
+- **THEN** final instruction contains both schema guidance and config rules
+
+#### Scenario: Rules provide additional constraints
+- **WHEN** schema says "create proposal" and config rules say "include rollback plan"
+- **THEN** agent sees both the schema template and the additional rule
+
+### Requirement: Validate artifact IDs during instruction loading
+
+The system SHALL validate artifact IDs in rules against the schema when instructions are loaded and emit warnings for unknown IDs.
+
+#### Scenario: All artifact IDs are valid
+- **WHEN** instructions loaded and config has `rules: { proposal: [...], specs: [...] }` for schema with those artifacts
+- **THEN** no validation warnings are emitted
+
+#### Scenario: Unknown artifact ID in rules
+- **WHEN** instructions loaded and config has `rules: { unknownartifact: [...] }`
+- **THEN** warning emitted: "Unknown artifact ID in rules: 'unknownartifact'. Valid IDs for schema 'spec-driven': design, proposal, specs, tasks"
+
+#### Scenario: Multiple unknown artifact IDs
+- **WHEN** instructions loaded and config has multiple unknown artifact IDs
+- **THEN** separate warning emitted for each unknown artifact ID
+
+#### Scenario: Validation warnings shown once per session
+- **WHEN** instructions loaded multiple times in same CLI session
+- **THEN** each unique validation warning is shown only once (cached)

openspec/changes/project-config/specs/schema-resolution/spec.md

@@ -0,0 +1,83 @@
+# Spec: Schema Resolution with Config
+
+## ADDED Requirements
+
+### Requirement: Use config schema as default for new changes
+
+The system SHALL use the schema field from `openspec/config.yaml` as the default when creating new changes without explicit `--schema` flag.
+
+#### Scenario: Create change without --schema flag and config exists
+- **WHEN** user runs `openspec new change foo` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "tdd"
+
+#### Scenario: Create change without --schema flag and no config
+- **WHEN** user runs `openspec new change foo` and no config file exists
+- **THEN** system creates change with default schema "spec-driven"
+
+#### Scenario: Create change with explicit --schema flag
+- **WHEN** user runs `openspec new change foo --schema custom` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "custom" (CLI flag overrides config)
+
+### Requirement: Resolve schema with updated precedence order
+
+The system SHALL resolve the schema for a change using the following precedence order: CLI flag, change metadata, project config, hardcoded default.
+
+#### Scenario: CLI flag is provided
+- **WHEN** user runs command with `--schema custom`
+- **THEN** system uses "custom" regardless of change metadata or config
+
+#### Scenario: Change metadata specifies schema
+- **WHEN** change has `.openspec.yaml` with `schema: bound` and config has `schema: tdd`
+- **THEN** system uses "bound" from change metadata
+
+#### Scenario: Only project config specifies schema
+- **WHEN** no CLI flag or change metadata, but config has `schema: tdd`
+- **THEN** system uses "tdd" from project config
+
+#### Scenario: No schema specified anywhere
+- **WHEN** no CLI flag, change metadata, or project config
+- **THEN** system uses hardcoded default "spec-driven"
+
+### Requirement: Support project-local schema names in config
+
+The system SHALL allow the config schema field to reference project-local schemas defined in `openspec/schemas/`.
+
+#### Scenario: Config references project-local schema
+- **WHEN** config contains `schema: "my-workflow"` and `openspec/schemas/my-workflow/` exists
+- **THEN** system resolves to the project-local schema
+
+#### Scenario: Config references non-existent schema
+- **WHEN** config contains `schema: "nonexistent"` and that schema does not exist
+- **THEN** system shows error when attempting to load the schema with fuzzy match suggestions and list of all valid schemas
+
+### Requirement: Provide helpful error message for invalid schema
+
+The system SHALL display schema error with fuzzy match suggestions, list of available schemas, and fix instructions.
+
+#### Scenario: Schema name with typo (close match)
+- **WHEN** config contains `schema: "spce-driven"` (typo)
+- **THEN** error message includes "Did you mean: spec-driven (built-in)" as suggestion
+
+#### Scenario: Schema name with no close matches
+- **WHEN** config contains `schema: "completely-wrong"`
+- **THEN** error message shows list of all available built-in and project-local schemas
+
+#### Scenario: Error message includes fix instructions
+- **WHEN** config references invalid schema
+- **THEN** error message includes "Fix: Edit openspec/config.yaml and change 'schema: X' to a valid schema name"
+
+#### Scenario: Error distinguishes built-in vs project-local schemas
+- **WHEN** error lists available schemas
+- **THEN** output clearly labels each as "built-in" or "project-local"
+
+### Requirement: Maintain backwards compatibility for existing changes
+
+The system SHALL continue to work with existing changes that do not have project config.
+
+#### Scenario: Existing change without config
+- **WHEN** change was created before config feature and no config file exists
+- **THEN** system resolves schema using existing logic (change metadata or hardcoded default)
+
+#### Scenario: Existing change with config added later
+- **WHEN** config file is added to project with existing changes
+- **THEN** existing changes continue to use their bound schema from `.openspec.yaml`

openspec/changes/project-config/tasks.md

@@ -0,0 +1,72 @@
+## 1. Core Config System
+
+- [x] 1.1 Create `src/core/project-config.ts` with ProjectConfigSchema using Zod (for docs and type inference)
+- [x] 1.2 Implement `readProjectConfig()` with resilient field-by-field parsing using Zod's `safeParse()`
+- [x] 1.3 Add support for both .yaml and .yml extensions (prefer .yaml)
+- [x] 1.4 Add 50KB hard limit for context field with size check and warning
+- [x] 1.5 Implement `validateConfigRules()` to validate artifact IDs against schema (called during instruction loading)
+- [x] 1.6 Implement `suggestSchemas()` with Levenshtein distance fuzzy matching for helpful error messages
+- [x] 1.7 Add unit tests for resilient parsing (partial configs, field-level errors with Zod safeParse)
+- [x] 1.8 Add unit tests for context size limit enforcement
+- [x] 1.9 Add unit tests for .yml/.yaml precedence
+- [x] 1.10 Add unit tests for fuzzy schema matching with typos
+
+## 2. Schema Resolution Integration
+
+- [x] 2.1 Update `resolveSchemaForChange()` in `src/utils/change-metadata.ts` to check project config (3rd in precedence)
+- [x] 2.2 Update `createNewChange()` in `src/utils/change-utils.ts` to use config schema as default
+- [x] 2.3 Add integration tests for schema resolution precedence (CLI → change metadata → config → default)
+- [x] 2.4 Add test for project-local schema names in config
+- [x] 2.5 Add test for non-existent schema error handling with suggestions
+
+## 3. Context and Rules Injection
+
+- [x] 3.1 Update `loadInstructions()` in `src/core/artifact-graph/instruction-loader.ts` to inject context for all artifacts
+- [x] 3.2 Add rules injection logic for matching artifacts only with XML tags and bullet formatting
+- [x] 3.3 Add validation call during instruction loading to check artifact IDs in rules
+- [x] 3.4 Implement session-level warning cache to avoid repeating same validation warnings
+- [x] 3.5 Implement proper ordering: `<context>` → `<rules>` → `<template>`
+- [x] 3.6 Preserve multi-line strings and special characters without escaping
+- [x] 3.7 Add unit tests for context injection (present, absent, multi-line, special chars)
+- [x] 3.8 Add unit tests for rules injection (matching artifact, non-matching, empty array, multiple artifacts)
+- [x] 3.9 Add unit tests for validation timing (warnings during instruction load, not config load)
+- [x] 3.10 Add unit tests for warning deduplication (same warning shown once per session)
+- [x] 3.11 Add integration test verifying full instruction output with context + rules + template
+
+## 4. Interactive Config Creation
+
+- [x] 4.1 Add @inquirer/prompts dependency to package.json
+- [x] 4.2 Create `src/core/config-prompts.ts` with ConfigPromptResult interface
+- [x] 4.3 Implement `promptForConfig()` function with schema selection prompt
+- [x] 4.4 Add multi-line context input prompt with examples and skip option
+- [x] 4.5 Add per-artifact rules prompts with checkbox selection and line-by-line input
+- [x] 4.6 Implement YAML serialization with proper multi-line string formatting
+- [x] 4.7 Add validation and retry logic for prompt errors
+
+## 5. Experimental Setup Integration
+
+- [x] 5.1 Update `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts` to check for existing config
+- [x] 5.2 Add config creation section after skills/commands creation with header and description
+- [x] 5.3 Integrate `promptForConfig()` calls with proper flow control
+- [x] 5.4 Add Ctrl+C (ExitPromptError) handling - log cancellation message, continue with setup (non-fatal)
+- [x] 5.5 Write created config to `openspec/config.yaml` using YAML stringify
+- [x] 5.6 Display success summary showing path, schema, context lines, rules count
+- [x] 5.7 Show usage examples and git commit suggestion
+- [x] 5.8 Handle existing config case with skip message and manual update instructions
+- [x] 5.9 Add error handling for file write failures with fallback suggestions
+- [x] 5.10 Add test for cancellation behavior (skills/commands preserved, config not created)
+
+## 6. Testing and Documentation
+
+- [x] 6.1 Add end-to-end test: run experimental setup → create config → create change → verify schema used
+- [x] 6.2 Add end-to-end test: create config → get instructions → verify context and rules injected
+- [x] 6.3 Test backwards compatibility: existing changes work without config
+- [x] 6.4 Test config changes are reflected immediately (no stale cache)
+- [x] 6.5 Add performance benchmark: measure config read time with typical config (1KB context)
+- [x] 6.6 Add performance benchmark: measure config read time with large config (50KB context)
+- [x] 6.7 Add performance benchmark: measure repeated reads within single command
+- [x] 6.8 Document benchmark results and decide if caching is needed (target: <10ms typical, <50ms acceptable)
+- [x] 6.9 If benchmarks fail: implement mtime-based caching with cache invalidation
+- [x] 6.10 Update README or docs with config feature examples and schema
+- [x] 6.11 Document common artifact IDs for different schemas
+- [x] 6.12 Add troubleshooting section for config validation errors

openspec/changes/project-local-schemas/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: "2025-01-13"

openspec/changes/project-local-schemas/design.md

@@ -0,0 +1,117 @@
+## Context
+
+OpenSpec currently resolves schemas from two locations:
+1. User override: `~/.local/share/openspec/schemas/<name>/`
+2. Package built-in: `<npm-package>/schemas/<name>/`
+
+This change adds a third, highest-priority level: project-local schemas at `./openspec/schemas/<name>/`.
+
+The resolver functions in `src/core/artifact-graph/resolver.ts` currently don't take a `projectRoot` parameter because user and package paths are absolute. To support project-local schemas, we need to pass project root context into the resolver.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Enable version-controlled custom workflow schemas
+- Allow teams to share schemas via git without per-machine setup
+- Maintain backward compatibility with existing resolver API
+- Integrate with `config.yaml`'s `schema` field (from project-config change)
+
+**Non-Goals:**
+- Schema inheritance or `extends` keyword
+- Template-level overrides (partial forks)
+- Schema management CLI commands (`openspec schema copy/which/diff/reset`)
+- Validation that project-local schema names don't conflict with built-ins (shadowing is intentional)
+
+## Decisions
+
+### Decision 1: Add optional `projectRoot` parameter to resolver functions
+
+**Choice:** Add optional `projectRoot?: string` parameter to resolver functions rather than using `process.cwd()` internally.
+
+**Alternatives considered:**
+- Use `process.cwd()` internally: Simpler API but implicit, harder to test, doesn't match existing codebase patterns
+- Create separate project-aware functions: No breaking changes but awkward API, callers must compose
+
+**Rationale:** The codebase already follows a pattern where CLI commands get project root via `process.cwd()` and pass it down to functions that need it. Adding an optional parameter maintains backward compatibility while enabling explicit, testable behavior.
+
+**Affected functions:**
+```typescript
+getSchemaDir(name: string, projectRoot?: string): string | null
+listSchemas(projectRoot?: string): string[]
+listSchemasWithInfo(projectRoot?: string): SchemaInfo[]
+resolveSchema(name: string, projectRoot?: string): SchemaYaml
+```
+
+### Decision 2: Resolution order is project → user → package
+
+**Choice:** Project-local schemas have highest priority, then user overrides, then package built-ins.
+
+**Rationale:**
+- Project-local should win because it represents team intent (version controlled, shared)
+- User overrides still useful for personal experimentation without affecting team
+- Package built-ins are the fallback defaults
+
+```
+1. ./openspec/schemas/<name>/              # Project-local (highest)
+2. ~/.local/share/openspec/schemas/<name>/ # User override
+3. <npm-package>/schemas/<name>/           # Package built-in (lowest)
+```
+
+### Decision 3: Add `getProjectSchemasDir()` helper function
+
+**Choice:** Create a dedicated function to get the project schemas directory path.
+
+```typescript
+function getProjectSchemasDir(projectRoot: string): string {
+  return path.join(projectRoot, 'openspec', 'schemas');
+}
+```
+
+**Rationale:** Matches existing pattern with `getPackageSchemasDir()` and `getUserSchemasDir()`. Keeps path logic centralized.
+
+### Decision 4: Extend `SchemaInfo.source` to include `'project'`
+
+**Choice:** Update the source type from `'package' | 'user'` to `'project' | 'user' | 'package'`.
+
+**Rationale:** Consumers need to distinguish project-local schemas for display purposes (e.g., `schemasCommand` output).
+
+### Decision 5: No special handling for schema name conflicts
+
+**Choice:** If a project-local schema has the same name as a built-in (e.g., `spec-driven`), the project-local version wins. No warning, no error.
+
+**Rationale:** This is intentional shadowing. Teams may want to customize a built-in schema while keeping the same name for familiarity.
+
+## Risks / Trade-offs
+
+### Risk: Confusion when project schema shadows built-in
+A team could create `openspec/schemas/spec-driven/` that shadows the built-in, causing confusion when someone expects default behavior.
+
+**Mitigation:** The `openspec schemas` command shows the source of each schema. Users can see `spec-driven (project)` vs `spec-driven (package)`.
+
+### Risk: Missing projectRoot parameter
+If callers forget to pass `projectRoot`, project-local schemas won't be found.
+
+**Mitigation:**
+- Make the change incrementally, updating call sites that need project-local support
+- Existing behavior (user + package only) is preserved when `projectRoot` is undefined
+
+### Trade-off: Optional parameter vs required
+Making `projectRoot` optional maintains backward compatibility but means some code paths may silently skip project-local resolution.
+
+**Accepted:** Backward compatibility is more important. The main entry points (CLI commands) will always pass `projectRoot`.
+
+## Implementation Approach
+
+1. **Update `resolver.ts`:**
+   - Add `getProjectSchemasDir(projectRoot: string)` function
+   - Update `getSchemaDir()` to check project-local first when `projectRoot` provided
+   - Update `listSchemas()` to include project schemas when `projectRoot` provided
+   - Update `listSchemasWithInfo()` to return `source: 'project'` for project schemas
+   - Update `SchemaInfo` type to include `'project'` in source union
+
+2. **Update `artifact-workflow.ts`:**
+   - Update `schemasCommand` to pass `projectRoot` and display source labels
+
+3. **Update call sites:**
+   - Any existing code that needs project-local resolution should pass `projectRoot`
+   - `config.yaml` schema resolution already has access to `projectRoot`