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.
2026-10-04 14:38:54 +08:00 · 2026-01-20 00:55:26 -08:00
602 changed files with 15714 additions and 84691 deletions
@@ -12,12 +12,11 @@ Follow the prompts to select version bump type and describe your changes.

 ## Workflow

-1. **Choose the release path**: Maintainers decide whether a PR follows the normal release cadence or gets dedicated release tracking.
-2. **Add dedicated release tracking**: When a maintainer asks for a changeset, run `pnpm changeset` locally before or after your PR.
-3. **Version PR**: CI opens/updates a "Version Packages" PR when changesets merge to main.
-4. **Release**: Merging the Version PR triggers npm publish and GitHub Release.
+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:** The default path is the normal release cadence. Add a changeset when a maintainer or release owner wants dedicated release notes and version tracking for the PR. Versioning (`changeset version`) and publishing happen automatically in CI.
+> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI.

 ## Template

@@ -55,23 +54,22 @@ Include only the sections relevant to your change.

 | Type | When to use | Example |
 |------|-------------|---------|
-| `patch` | Release-tracked bug fixes, small improvements | Fixed crash when config missing |
+| `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

-**Use dedicated release tracking for:**
- New features or commands selected for release
- Notable bug fixes or hotfixes requested by a maintainer/release owner
+**Create one for:**
+- New features or commands
+- Bug fixes that affect users
 - Breaking changes or deprecations
- Performance improvements users would notice and that are planned for release
+- Performance improvements users would notice

-**Use the normal release cadence for:**
- Routine bug fixes that fit the normal release cadence
+**Skip for:**
 - Documentation-only changes
 - Test additions/fixes
- Internal refactoring that preserves user behavior
+- Internal refactoring with no user impact
 - CI/tooling changes

 ## Writing Good Descriptions
@@ -3,8 +3,6 @@ name: CI
 on:
  pull_request:
    branches: [main]
-  merge_group:
-    branches: [main]
  push:
    branches: [main]
  workflow_dispatch:
@@ -44,7 +42,7 @@ jobs:
    name: Test
    runs-on: ubuntu-latest
    timeout-minutes: 10
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    if: github.event_name == 'pull_request'

    steps:
      - name: Checkout code
@@ -60,7 +58,7 @@ jobs:
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
@@ -83,7 +81,7 @@ jobs:
    name: Test (${{ matrix.label }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
-    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    if: github.event_name != 'pull_request'
    strategy:
      fail-fast: false
      matrix:
@@ -116,7 +114,7 @@ jobs:
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Print environment diagnostics
@@ -155,7 +153,7 @@ jobs:
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
@@ -192,10 +190,10 @@ jobs:
        uses: actions/checkout@v4

      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@v21
+        uses: DeterminateSystems/nix-installer-action@v13

      - name: Setup Nix cache
-        uses: DeterminateSystems/magic-nix-cache-action@v13
+        uses: DeterminateSystems/magic-nix-cache-action@v8

      - name: Build with Nix
        run: nix build
@@ -231,7 +229,7 @@ jobs:
      - name: Check flake.nix modifications
        run: |
          if git diff --quiet flake.nix; then
-            echo "ℹ️  flake.nix unchanged (hash already up-to-date)"
+            echo "⚠️  Warning: flake.nix was not modified by update script"
          else
            echo "✅ flake.nix was updated by script"
            git diff flake.nix
@@ -242,62 +240,42 @@ jobs:
        run: git checkout -- flake.nix || true

  validate-changesets:
-    name: Validate Release Tracking
+    name: Validate Changesets
    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

-      - name: Determine release tracking
-        id: changed-changesets
-        run: |
-          changed_changesets="$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD -- '.changeset/*.md' ':!.changeset/README.md')"
-          if [[ -n "$changed_changesets" ]]; then
-            echo "has_changesets=true" >> "$GITHUB_OUTPUT"
-            {
-              echo "files<<EOF"
-              echo "$changed_changesets"
-              echo "EOF"
-            } >> "$GITHUB_OUTPUT"
-          else
-            echo "has_changesets=false" >> "$GITHUB_OUTPUT"
-            echo "This PR follows the normal release cadence; continuing with standard validation"
-          fi
-
      - name: Setup pnpm
-        if: steps.changed-changesets.outputs.has_changesets == 'true'
        uses: pnpm/action-setup@v4
        with:
          version: 9

      - name: Setup Node.js
-        if: steps.changed-changesets.outputs.has_changesets == 'true'
        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
-        if: steps.changed-changesets.outputs.has_changesets == 'true'
        run: pnpm install --frozen-lockfile

-      - name: Validate release-tracked changesets
-        if: steps.changed-changesets.outputs.has_changesets == 'true'
-        env:
-          CHANGESET_FILES: ${{ steps.changed-changesets.outputs.files }}
+      - name: Validate changesets
        run: |
-          echo "Validating changed changesets:"
-          printf '%s\n' "$CHANGESET_FILES"
-          pnpm exec changeset status --since=origin/main
+          if command -v changeset &> /dev/null; then
+            pnpm exec changeset status --since=origin/main
+          else
+            echo "Changesets not configured, skipping validation"
+          fi

  required-checks-pr:
    name: All checks passed
    runs-on: ubuntu-latest
    needs: [test_pr, lint, nix-flake-validate]
-    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
+    if: always() && github.event_name == 'pull_request'
    steps:
      - name: Verify all checks passed
        run: |
@@ -323,7 +301,7 @@ jobs:
    name: All checks passed
    runs-on: ubuntu-latest
    needs: [test_matrix, lint, nix-flake-validate]
-    if: always() && github.event_name == 'push'
+    if: always() && github.event_name != 'pull_request'
    steps:
      - name: Verify all checks passed
        run: |
@@ -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
@@ -58,3 +58,14 @@ jobs:
        env:
          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"
@@ -149,13 +149,3 @@ CLAUDE.md
 # Pnpm
 .pnpm-store/
 result
-
-# OpenCode
-.opencode/
-opencode.json
-
-# Codex
-.codex/
-
-# Bob
-.bob/
@@ -0,0 +1,18 @@
+<!-- OPENSPEC:START -->
+# OpenSpec Instructions
+
+These instructions are for AI assistants working in this project.
+
+Always open `@/openspec/AGENTS.md` when the request:
+- Mentions planning or proposals (words like proposal, spec, change, plan)
+- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
+- Sounds ambiguous and you need the authoritative spec before coding
+
+Use `@/openspec/AGENTS.md` to learn:
+- How to create and apply change proposals
+- Spec format and conventions
+- Project structure and guidelines
+
+Keep this managed block so 'openspec update' can refresh the instructions.
+
+<!-- OPENSPEC:END -->
@@ -1,265 +1,5 @@
 # @fission-ai/openspec

-## 1.5.0
-
-### Minor Changes
-
- [#1267](https://github.com/Fission-AI/OpenSpec/pull/1267) [`96f6cac`](https://github.com/Fission-AI/OpenSpec/commit/96f6cacb206c65bee30066f6a1f4e9b855a0d783) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - **Stores (very early beta)** — Introduces stores as a simpler way to organize specs and changes, replacing the workspace and initiative model. This feature is in very early beta — expect rough edges and breaking changes in upcoming releases.
-
-  ### Bug Fixes
-
-  - **Config parsing** — Configuration values wrapped in JSON containers are now parsed correctly.
-
-### Patch Changes
-
- [#1240](https://github.com/Fission-AI/OpenSpec/pull/1240) [`cbf386b`](https://github.com/Fission-AI/OpenSpec/commit/cbf386bd6888f103f8ff7d59b3eab98ce5b57998) Thanks [@zied-jlassi](https://github.com/zied-jlassi)! - fix(adapters): escape carriage returns in generated YAML frontmatter
-
-  `escapeYamlValue` flagged `\r` as a character requiring quoting but never escaped it, leaving a literal carriage return inside the double-quoted scalar where YAML line folding/normalization could silently corrupt the value (realistic with CRLF-authored command descriptions). Carriage returns are now escaped as `\r`. The helper — previously duplicated verbatim across five adapters (bob, claude, cursor, pi, windsurf) — is extracted into a shared `command-generation/yaml.ts` module so the behavior stays consistent and is fixed in one place.
-
-## 1.4.1
-
-### Patch Changes
-
- [#1165](https://github.com/Fission-AI/OpenSpec/pull/1165) [`0a01146`](https://github.com/Fission-AI/OpenSpec/commit/0a01146c181a3af8dbf645547bcbe20c0d48d615) Thanks [@TabishB](https://github.com/TabishB)! - Move beta workspace view state to `.openspec-workspace/view.yaml`, stop top-level `openspec update` from routing into workspace updates, and ignore foreign root `workspace.yaml` files so Dagster projects keep updating normally.
-
-## 1.4.0
-
-### Minor Changes
-
- [#1003](https://github.com/Fission-AI/OpenSpec/pull/1003) [`342ed43`](https://github.com/Fission-AI/OpenSpec/commit/342ed43e694abba65a3ea275f94ba3b77df85da3) Thanks [@Miss-you](https://github.com/Miss-you)! - ### New Features
-
-  - **Kimi CLI support** — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using `.kimi/skills/`
-
-  ### Other
-
-  - Added Kimi-specific docs and init coverage aligned with skill-based `/skill:openspec-*` usage
-
- [#1154](https://github.com/Fission-AI/OpenSpec/pull/1154) [`aa16080`](https://github.com/Fission-AI/OpenSpec/commit/aa16080d16b70f7b26cebd465334b2e16c0e7a43) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - **Mistral Vibe support** — OpenSpec can now initialize Mistral Vibe as a supported skills-only tool using `.vibe/skills/`
-
-  ### Bug Fixes
-
-  - **Case-insensitive requirement headers** — Requirement headers are now parsed regardless of capitalization, so specs no longer fail to parse over header casing
-  - **Zsh completions on oh-my-zsh** — Fixed shell completion setup so tab completion installs correctly under oh-my-zsh's `compinit`
-
-  ### Other
-
-  - **Clearer validation hints** — When a requirement has SHALL/MUST only in its header, `openspec validate` now points you to move the keyword onto the requirement body line instead of showing the generic error
-
- [#1030](https://github.com/Fission-AI/OpenSpec/pull/1030) [`485c97e`](https://github.com/Fission-AI/OpenSpec/commit/485c97e97d766e35dd16c02370baee2044abc4f4) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - Include the sync workflow in the default core profile so new installs generate `/opsx:sync` skills and commands by default.
-
-### Patch Changes
-
- [#1111](https://github.com/Fission-AI/OpenSpec/pull/1111) [`7fdb177`](https://github.com/Fission-AI/OpenSpec/commit/7fdb1771585b1688597d73dde5a8bc906084d0de) Thanks [@TabishB](https://github.com/TabishB)! - ### Fixed
-
-  - Preserve workspace planning detection when Windows short paths or symlink aliases resolve to a canonical workspace root.
-
-## 1.3.1
-
-### Patch Changes
-
- [#995](https://github.com/Fission-AI/OpenSpec/pull/995) [`d1f3861`](https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
-
-  - **Canonical artifact paths** — Workflow artifact paths are now resolved via the native `realpath`, so symlinks and case-insensitive filesystems no longer cause path mismatches during apply and archive.
-  - **Glob apply instructions** — Apply instructions with glob artifact outputs now resolve correctly, and literal artifact outputs are enforced to be file paths.
-  - **Hidden main spec requirements** — Requirements nested inside fenced code blocks or otherwise hidden in main specs are now detected during validation.
-  - **Clean `--json` output** — Spinner progress text no longer leaks into stderr when `--json` is passed, so AI agents that combine stdout and stderr can parse the JSON reliably.
-  - **Silent telemetry in firewalled environments** — PostHog network errors are now swallowed with a 1s timeout and retries/remote config disabled, so OpenSpec no longer surfaces `PostHogFetchNetworkError` in locked-down networks. Telemetry opt-out is documented earlier in the README, installation guide, and CLI reference.
-
-## 1.3.0
-
-### Minor Changes
-
- [#952](https://github.com/Fission-AI/OpenSpec/pull/952) [`cce787e`](https://github.com/Fission-AI/OpenSpec/commit/cce787ec4083da2b27781f6786f5ce0002909a7b) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - **Junie support** — Added tool and command generation for JetBrains Junie
-  - **Lingma IDE support** — Added configuration support for Lingma IDE
-  - **ForgeCode support** — Added tool support for ForgeCode
-  - **IBM Bob support** — Added support for IBM Bob coding assistant
-
-  ### Bug Fixes
-
-  - **Shell completions opt-in** — Completion install is now opt-in, fixing PowerShell encoding corruption
-  - **Copilot auto-detection** — Prevented false GitHub Copilot detection from a bare `.github/` directory
-  - **pi.dev command generation** — Fixed command reference transforms and template argument passing
-
-### Patch Changes
-
- [#760](https://github.com/Fission-AI/OpenSpec/pull/760) [`61eb999`](https://github.com/Fission-AI/OpenSpec/commit/61eb999f7c6c0fc98d2e7f3678756fce6a3f4378) Thanks [@fsilvaortiz](https://github.com/fsilvaortiz)! - fix: OpenCode adapter now uses `.opencode/commands/` (plural) to match OpenCode's official directory convention. Fixes #748.
-
- [#759](https://github.com/Fission-AI/OpenSpec/pull/759) [`afdca0d`](https://github.com/Fission-AI/OpenSpec/commit/afdca0d5dab1aa109cfd8848b2512333ccad60c3) Thanks [@fsilvaortiz](https://github.com/fsilvaortiz)! - fix: `openspec status` now exits gracefully when no changes exist instead of throwing a fatal error. Fixes #714.
-
-## 1.2.0
-
-### Minor Changes
-
- [#747](https://github.com/Fission-AI/OpenSpec/pull/747) [`1e94443`](https://github.com/Fission-AI/OpenSpec/commit/1e94443a3551b228eecbc89e95d96d3b9600a192) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - **Profile system** — Choose between `core` (4 essential workflows) and `custom` (pick any subset) profiles to control which skills get installed. Manage profiles with the new `openspec config profile` command
-  - **Propose workflow** — New one-step workflow creates a complete change proposal with design, specs, and tasks from a single request — no need to run `new` then `ff` separately
-  - **AI tool auto-detection** — `openspec init` now scans your project for existing tool directories (`.claude/`, `.cursor/`, etc.) and pre-selects detected tools
-  - **Pi (pi.dev) support** — Pi coding agent is now a supported tool with prompt and skill generation
-  - **Kiro support** — AWS Kiro IDE is now a supported tool with prompt and skill generation
-  - **Sync prunes deselected workflows** — `openspec update` now removes command files and skill directories for workflows you've deselected, keeping your project clean
-  - **Config drift warning** — `openspec config list` warns when global config is out of sync with the current project
-
-  ### Bug Fixes
-
-  - Fixed onboard preflight giving a false "not initialized" error on freshly initialized projects
-  - Fixed archive workflow stopping mid-way when syncing — it now properly resumes after sync completes
-  - Added Windows PowerShell alternatives for onboard shell commands
-
-## 1.1.1
-
-### Patch Changes
-
- [#627](https://github.com/Fission-AI/OpenSpec/pull/627) [`afb73cf`](https://github.com/Fission-AI/OpenSpec/commit/afb73cf9ec59c6f8b26d0c538c0218c203ba3c56) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
-
-  - **OpenCode command references** — Command references in generated files now use the correct `/opsx-` hyphen format instead of `/opsx:` colon format, ensuring commands work properly in OpenCode
-
-## 1.1.0
-
-### Minor Changes
-
- [#625](https://github.com/Fission-AI/OpenSpec/pull/625) [`53081fb`](https://github.com/Fission-AI/OpenSpec/commit/53081fb2a26ec66d2950ae0474b9a56cbc5b5a76) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
-
-  - **Codex global path support** — Codex adapter now resolves global paths correctly, fixing workflow file generation when run outside the project directory (#622)
-  - **Archive operations on cross-device or restricted paths** — Archive now falls back to copy+remove when rename fails with EPERM or EXDEV errors, fixing failures on networked/external drives (#605)
-  - **Slash command hints in workflow messages** — Workflow completion messages now display helpful slash command hints for next steps (#603)
-  - **Windsurf workflow file path** — Updated Windsurf adapter to use the correct `workflows` directory instead of the legacy `commands` path (#610)
-
-### Patch Changes
-
- [#550](https://github.com/Fission-AI/OpenSpec/pull/550) [`86d2e04`](https://github.com/Fission-AI/OpenSpec/commit/86d2e04cae76a999dbd1b4571f52fa720036be0c) Thanks [@jerome-benoit](https://github.com/jerome-benoit)! - ### Improvements
-
-  - **Nix flake maintenance** — Version now read dynamically from package.json, reducing manual sync issues
-  - **Nix build optimization** — Source filtering excludes node_modules and artifacts, improving build times
-  - **update-flake.sh script** — Detects when hash is already correct, skipping unnecessary rebuilds
-
-  ### Other
-
-  - Updated Nix CI actions to latest versions (nix-installer v21, magic-nix-cache v13)
-
-## 1.0.2
-
-### Patch Changes
-
- [#596](https://github.com/Fission-AI/OpenSpec/pull/596) [`e91568d`](https://github.com/Fission-AI/OpenSpec/commit/e91568deb948073f3e9d9bb2d2ab5bf8080d6cf4) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
-
-  - Clarified spec naming convention — Specs should be named after capabilities (`specs/<capability>/spec.md`), not changes
-  - Fixed task checkbox format guidance — Tasks now clearly require `- [ ]` checkbox format for apply phase tracking
-
-## 1.0.1
-
-### Patch Changes
-
- [#587](https://github.com/Fission-AI/OpenSpec/pull/587) [`943e0d4`](https://github.com/Fission-AI/OpenSpec/commit/943e0d41026d034de66b9442d1276c01b293eb2b) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
-
-  - Fixed incorrect archive path in onboarding documentation — the template now shows the correct path `openspec/changes/archive/YYYY-MM-DD-<name>/` instead of the incorrect `openspec/archive/YYYY-MM-DD--<name>/`
-
-## 1.0.0
-
-### Major Changes
-
- [#578](https://github.com/Fission-AI/OpenSpec/pull/578) [`0cc9d90`](https://github.com/Fission-AI/OpenSpec/commit/0cc9d9025af367faa1688a7b2606a2549053cd3f) Thanks [@TabishB](https://github.com/TabishB)! - ## OpenSpec 1.0 — The OPSX Release
-
-  The workflow has been rebuilt from the ground up. OPSX replaces the old phase-locked `/openspec:*` commands with an action-based system where AI understands what artifacts exist, what's ready to create, and what each action unlocks.
-
-  ### Breaking Changes
-
-  - **Old commands removed** — `/openspec:proposal`, `/openspec:apply`, and `/openspec:archive` no longer exist
-  - **Config files removed** — Tool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated
-  - **Migration** — Run `openspec init` to upgrade. Legacy artifacts are detected and cleaned up with confirmation.
-
-  ### From Static Prompts to Dynamic Instructions
-
-  **Before:** AI received the same static instructions every time, regardless of project state.
-
-  **Now:** Instructions are dynamically assembled from three layers:
-
-  1. **Context** — Project background from `config.yaml` (tech stack, conventions)
-  2. **Rules** — Artifact-specific constraints (e.g., "propose spike tasks for unknowns")
-  3. **Template** — The actual structure for the output file
-
-  AI queries the CLI for real-time state: which artifacts exist, what's ready to create, what dependencies are satisfied, and what each action unlocks.
-
-  ### From Phase-Locked to Action-Based
-
-  **Before:** Linear workflow — proposal → apply → archive. Couldn't easily go back or iterate.
-
-  **Now:** Flexible actions on a change. Edit any artifact anytime. The artifact graph tracks state automatically.
-
-  | Command              | What it does                                         |
-  | -------------------- | ---------------------------------------------------- |
-  | `/opsx:explore`      | Think through ideas before committing to a change    |
-  | `/opsx:new`          | Start a new change                                   |
-  | `/opsx:continue`     | Create one artifact at a time (step-through)         |
-  | `/opsx:ff`           | Create all planning artifacts at once (fast-forward) |
-  | `/opsx:apply`        | Implement tasks                                      |
-  | `/opsx:verify`       | Validate implementation matches artifacts            |
-  | `/opsx:sync`         | Sync delta specs to main specs                       |
-  | `/opsx:archive`      | Archive completed change                             |
-  | `/opsx:bulk-archive` | Archive multiple changes with conflict detection     |
-  | `/opsx:onboard`      | Guided 15-minute walkthrough of complete workflow    |
-
-  ### From Text Merging to Semantic Spec Syncing
-
-  **Before:** Spec updates required manual merging or wholesale file replacement.
-
-  **Now:** Delta specs use semantic markers that AI understands:
-
-  - `## ADDED Requirements` — New requirements to add
-  - `## MODIFIED Requirements` — Partial updates (add scenario without copying existing ones)
-  - `## REMOVED Requirements` — Delete with reason and migration notes
-  - `## RENAMED Requirements` — Rename preserving content
-
-  Archive parses these at the requirement level, not brittle header matching.
-
-  ### From Scattered Files to Agent Skills
-
-  **Before:** 8+ config files at project root + slash commands scattered across 21 tool-specific locations with different formats.
-
-  **Now:** Single `.claude/skills/` directory with YAML-fronted markdown files. Auto-detected by Claude Code, Cursor, Windsurf. Cross-editor compatible.
-
-  ### New Features
-
-  - **Onboarding skill** — `/opsx:onboard` walks new users through their first complete change with codebase-aware task suggestions and step-by-step narration (11 phases, ~15 minutes)
-
-  - **21 AI tools supported** — Claude Code, Cursor, Windsurf, Continue, Gemini CLI, GitHub Copilot, Amazon Q, Cline, RooCode, Kilo Code, Auggie, CodeBuddy, Qoder, Qwen, CoStrict, Crush, Factory, OpenCode, Antigravity, iFlow, and Codex
-
-  - **Interactive setup** — `openspec init` shows animated welcome screen and searchable multi-select for choosing tools. Pre-selects already-configured tools for easy refresh.
-
-  - **Customizable schemas** — Define custom artifact workflows in `openspec/schemas/` without touching package code. Teams can share workflows via version control.
-
-  ### Bug Fixes
-
-  - Fixed Claude Code YAML parsing failure when command names contained colons
-  - Fixed task file parsing to handle trailing whitespace on checkbox lines
-  - Fixed JSON instruction output to separate context/rules from template — AI was copying constraint blocks into artifact files
-
-  ### Documentation
-
-  - New getting-started guide, CLI reference, concepts documentation
-  - Removed misleading "edit mid-flight and continue" claims that weren't implemented
-  - Added migration guide for upgrading from pre-OPSX versions
-
-## 0.23.0
-
-### Minor Changes
-
- [#540](https://github.com/Fission-AI/OpenSpec/pull/540) [`c4cfdc7`](https://github.com/Fission-AI/OpenSpec/commit/c4cfdc7c499daef30d8a218f5f59b8d9e5adb754) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
-
-  - **Bulk archive skill** — Archive multiple completed changes in a single operation with `/opsx:bulk-archive`. Includes batch validation, spec conflict detection, and consolidated confirmation
-
-  ### Other
-
-  - **Simplified setup** — Config creation now uses sensible defaults with helpful comments instead of interactive prompts
-
 ## 0.22.0

 ### Minor Changes
@@ -1,211 +1,453 @@
 <p align="center">
  <a href="https://github.com/Fission-AI/OpenSpec">
    <picture>
-      <source srcset="assets/openspec_bg.png">
-      <img src="assets/openspec_bg.png" alt="OpenSpec logo">
+      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
    </picture>
  </a>
+  
 </p>
-
+<p align="center">Spec-driven development for AI coding assistants.</p>
 <p align="center">
  <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
  <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
+  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
-  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/discord/1411657095639601154?style=flat-square&logo=discord&logoColor=white&label=Discord&suffix=%20online" /></a>
+  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
+  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>

-<details>
-<summary><strong>The most loved spec framework.</strong></summary>
-
-[![Stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars)](https://github.com/Fission-AI/OpenSpec/stargazers)
-[![Downloads](https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo)](https://www.npmjs.com/package/@fission-ai/openspec)
-[![Contributors](https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors)](https://github.com/Fission-AI/OpenSpec/graphs/contributors)
-
-</details>
-<p></p>
-Our philosophy:
-
-```text
-→ fluid not rigid
-→ iterative not waterfall
-→ easy not complex
-→ built for brownfield not just greenfield
-→ scalable from personal projects to enterprises
-```
-
-> [!TIP]
-> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
->
-> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
-
-<p align="center">
-  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>
-
-<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
-
-## See it in action
-
-```text
-You: /opsx:explore
-AI:  What would you like to explore?
-You: I want dark mode but I'm not sure how to do it cleanly.
-AI:  Let me look at your styling setup...
-     Cleanest path here: CSS variables + a small theme context,
-     with system-preference detection. No new dependencies. Scope it?
-You: Yes, let's do it.
-
-You: /opsx:propose add-dark-mode
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md — why we're doing this, what's changing
-     ✓ specs/       — requirements and scenarios
-     ✓ design.md    — technical approach
-     ✓ tasks.md     — implementation checklist
-     Ready for implementation!
-
-You: /opsx:apply
-AI:  Implementing tasks...
-     ✓ 1.1 Add theme context provider
-     ✓ 1.2 Create toggle component
-     ✓ 2.1 Add CSS variables
-     ✓ 2.2 Wire up localStorage
-     All tasks complete!
-
-You: /opsx:archive
-AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
-     Specs updated. Ready for the next feature.
-```
-
-<details>
-<summary><strong>OpenSpec Dashboard</strong></summary>
-
 <p align="center">
  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
 </p>

-</details>
+<p align="center">
+  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>

-## Quick Start
+<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>

-**Requires Node.js 20.19.0 or higher.**
-
-Install OpenSpec globally:
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-Then navigate to your project directory and initialize:
-
-```bash
-cd your-project
-openspec init
-```
-
-Now talk to your AI:
-
- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
-
-Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
-
-> [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
->
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
-
-## Docs
-
-**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
-
-→ **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
-→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
-→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
-→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
-→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
-→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
-→ **[Commands](docs/commands.md)**: slash commands & skills<br>
-→ **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
-→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
-→ **[Concepts](docs/concepts.md)**: how it all fits<br>
-→ **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours<br>
-→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
-
-
-## Community schemas
-
-Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) handles tool integrations.
-
-→ **[Browse the catalog](docs/customization.md#community-schemas)** in the customization docs.
+# 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.**

 ## Why OpenSpec?

-AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.
+AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.

- **Agree before you build** — human and AI align on specs before code gets written
- **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
- **Work fluidly** — update any artifact anytime, no rigid phase gates
- **Use your tools** — works with 20+ AI assistants via slash commands
+Key outcomes:
+- Human and AI stakeholders agree on specs before work begins.
+- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
+- Shared visibility into what's proposed, active, or archived.
+- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.

-### How we compare
+## How OpenSpec compares (at a glance)

-**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
+- **Lightweight**: simple workflow, no API keys, minimal setup.
+- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
+- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
+- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.

-**vs. [Kiro](https://kiro.dev)** (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.
+See the full comparison in [How OpenSpec Compares](#how-openspec-compares).

-**vs. nothing** — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.
+## How It Works

-## Updating OpenSpec
+```
+┌────────────────────┐
+│ Draft Change       │
+│ Proposal           │
+└────────┬───────────┘
+         │ share intent with your AI
+         ▼
+┌────────────────────┐
+│ Review & Align     │
+│ (edit specs/tasks) │◀──── feedback loop ──────┐
+└────────┬───────────┘                          │
+         │ approved plan                        │
+         ▼                                      │
+┌────────────────────┐                          │
+│ Implement Tasks    │──────────────────────────┘
+│ (AI writes code)   │
+└────────┬───────────┘
+         │ ship the change
+         ▼
+┌────────────────────┐
+│ Archive & Update   │
+│ Specs (source)     │
+└────────────────────┘

-**Upgrade the package**
+1. Draft a change proposal that captures the spec updates you want.
+2. Review the proposal with your AI assistant until everyone agrees.
+3. Implement tasks that reference the agreed specs.
+4. Archive the change to merge the approved updates back into the source-of-truth specs.
+```
+
+## Getting Started
+
+### Supported AI Tools
+
+<details>
+<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
+
+These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
+
+| Tool | Commands |
+|------|----------|
+| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
+| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
+| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
+| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **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` |
+| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
+| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
+| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
+| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
+| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
+| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
+
+Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
+
+</details>
+
+<details>
+<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+
+These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
+
+| Tools |
+|-------|
+| Amp • Jules • Others |
+
+</details>
+
+### Install & Initialize
+
+#### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
+
+#### Step 1: Install the CLI globally
+
+**Option A: Using npm**

 ```bash
 npm install -g @fission-ai/openspec@latest
 ```

-**Refresh agent instructions**
-
-Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
-
+Verify installation:
 ```bash
-openspec update
+openspec --version
 ```

-## Usage Notes
+**Option B: Using Nix (NixOS and Nix package manager)**

-**Model selection**: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.
+Run OpenSpec directly without installation:
+```bash
+nix run github:Fission-AI/OpenSpec -- init
+```

-**Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
+Or install to your profile:
+```bash
+nix profile install github:Fission-AI/OpenSpec
+```

-## Contributing
+Or add to your development environment in `flake.nix`:
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    openspec.url = "github:Fission-AI/OpenSpec";
+  };

-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+  outputs = { nixpkgs, openspec, ... }: {
+    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
+      buildInputs = [ openspec.packages.x86_64-linux.default ];
+    };
+  };
+}
+```

-**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
+Verify installation:
+```bash
+openspec --version
+```

-When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
+#### Step 2: Initialize OpenSpec in your project

-**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
+Navigate to your project directory:
+```bash
+cd my-project
+```

-### Development
+Run the initialization:
+```bash
+openspec init
+```

- Install dependencies: `pnpm install`
- Build: `pnpm run build`
- Test: `pnpm test`
- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
- Conventional commits (one-line): `type(scope): subject`
+**What happens during initialization:**
+- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
+- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
+- A new `openspec/` directory structure is created in your project

-## Other
+**After setup:**
+- Primary AI tools can trigger `/openspec` workflows without additional configuration
+- Run `openspec list` to verify the setup and view any active changes
+- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
+  so a fresh launch ensures they appear
+
+### Optional: Populate Project Context
+
+After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
+
+```text
+Populate your project context:
+"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
+```
+
+Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
+
+### Create Your First Change
+
+Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
+
+#### 1. Draft the Proposal
+Start by asking your AI to create a change proposal:
+
+```text
+You: Create an OpenSpec change proposal for adding profile search filters by role and team
+     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
+
+AI:  I'll create an OpenSpec change proposal for profile filters.
+     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
+```
+
+#### 2. Verify & Review
+Check that the change was created correctly and review the proposal:
+
+```bash
+$ openspec list                             # Confirm the change folder exists
+$ openspec validate add-profile-filters     # Validate spec formatting
+$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
+```
+
+#### 3. Refine the Specs
+Iterate on the specifications until they match your needs:
+
+```text
+You: Can you add acceptance criteria for the role and team filters?
+
+AI:  I'll update the spec delta with scenarios for role and team filters.
+     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
+```
+
+#### 4. Implement the Change
+Once specs look good, start implementation:
+
+```text
+You: The specs look good. Let's implement this change.
+     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+
+AI:  I'll work through the tasks in the add-profile-filters change.
+     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
+     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
+```
+
+#### 5. Archive the Completed Change
+After implementation is complete, archive the change:
+
+```text
+AI:  All tasks are complete. The implementation is ready.
+
+You: Please archive the change
+     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
+
+AI:  I'll archive the add-profile-filters change.
+    *Runs: openspec archive add-profile-filters --yes*
+     ✓ Change archived successfully. Specs updated. Ready for the next feature!
+```
+
+Or run the command yourself in terminal:
+```bash
+$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
+```
+
+**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
+
+## Command Reference
+
+```bash
+openspec list               # View active change folders
+openspec view               # Interactive dashboard of specs and changes
+openspec show <change>      # Display change details (proposal, tasks, spec updates)
+openspec validate <change>  # Check spec formatting and structure
+openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
+```
+
+## Example: How AI Creates OpenSpec Files
+
+When you ask your AI assistant to "add two-factor authentication", it creates:
+
+```
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md           # Current auth spec (if exists)
+└── changes/
+    └── add-2fa/              # AI creates this entire structure
+        ├── proposal.md       # Why and what changes
+        ├── tasks.md          # Implementation checklist
+        ├── design.md         # Technical decisions (optional)
+        └── specs/
+            └── auth/
+                └── spec.md   # Delta showing additions
+```
+
+### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management.
+
+## Requirements
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN a JWT is returned
+```
+
+### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required
+```
+
+### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column to users table
+- [ ] 1.2 Create OTP verification logs table
+
+## 2. Backend Implementation  
+- [ ] 2.1 Add OTP generation endpoint
+- [ ] 2.2 Modify login flow to require OTP
+- [ ] 2.3 Add OTP verification endpoint
+
+## 3. Frontend Updates
+- [ ] 3.1 Create OTP input component
+- [ ] 3.2 Update login flow UI
+```
+
+**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
+
+## Understanding OpenSpec Files
+
+### Delta Format
+
+Deltas are "patches" that show how specs change:
+
+- **`## ADDED Requirements`** - New capabilities
+- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
+- **`## REMOVED Requirements`** - Deprecated features
+
+**Format requirements:**
+- Use `### Requirement: <name>` for headers
+- Every requirement needs at least one `#### Scenario:` block
+- Use SHALL/MUST in requirement text
+
+## How OpenSpec Compares
+
+### vs. spec-kit
+OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
+
+### vs. Kiro.dev
+OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
+
+### vs. No Specs
+Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
+
+## Team Adoption
+
+1. **Initialize OpenSpec** – Run `openspec init` in your repo.
+2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
+3. **Grow incrementally** – Each change archives into living specs that document your system.
+4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
+
+Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
+
+## Updating OpenSpec
+
+1. **Upgrade the package**
+   ```bash
+   npm install -g @fission-ai/openspec@latest
+   ```
+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>Telemetry</strong></summary>
+<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>

-OpenSpec collects anonymous usage stats.
+**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.

@@ -213,6 +455,14 @@ We collect only command names and version to understand usage patterns. No argum

 </details>

+## Contributing
+
+- Install dependencies: `pnpm install`
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- 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>

@@ -220,8 +470,6 @@ See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and adviso

 </details>

-
-
 ## License

 MIT
@@ -1,475 +0,0 @@
-<p align="center">
-  <a href="https://github.com/Fission-AI/OpenSpec">
-    <picture>
-      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
-      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
-      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
-    </picture>
-  </a>
-  
-</p>
-<p align="center">Spec-driven development for AI coding assistants.</p>
-<p align="center">
-  <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
-  <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
-  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
-  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
-</p>
-
-<p align="center">
-  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
-</p>
-
-<p align="center">
-  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/opsx.md">OPSX Workflow</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.**
-
-## Why OpenSpec?
-
-AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
-
-Key outcomes:
- Human and AI stakeholders agree on specs before work begins.
- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
- Shared visibility into what's proposed, active, or archived.
- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
-
-## How OpenSpec compares (at a glance)
-
- **Lightweight**: simple workflow, no API keys, minimal setup.
- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
-
-See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
-
-## How It Works
-
-```
-┌────────────────────┐
-│ Draft Change       │
-│ Proposal           │
-└────────┬───────────┘
-         │ share intent with your AI
-         ▼
-┌────────────────────┐
-│ Review & Align     │
-│ (edit specs/tasks) │◀──── feedback loop ──────┐
-└────────┬───────────┘                          │
-         │ approved plan                        │
-         ▼                                      │
-┌────────────────────┐                          │
-│ Implement Tasks    │──────────────────────────┘
-│ (AI writes code)   │
-└────────┬───────────┘
-         │ ship the change
-         ▼
-┌────────────────────┐
-│ Archive & Update   │
-│ Specs (source)     │
-└────────────────────┘
-
-1. Draft a change proposal that captures the spec updates you want.
-2. Review the proposal with your AI assistant until everyone agrees.
-3. Implement tasks that reference the agreed specs.
-4. Archive the change to merge the approved updates back into the source-of-truth specs.
-```
-
-## Getting Started
-
-### Supported AI Tools
-
-<details>
-<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
-
-These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
-
-| Tool | Commands |
-|------|----------|
-| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
-| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
-| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
-| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
-| **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` |
-| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
-| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
-| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
-| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
-| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Qoder** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com) |
-| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
-| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-
-Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
-
-</details>
-
-<details>
-<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
-
-These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
-
-| Tools |
-|-------|
-| Amp • Jules • Others |
-
-</details>
-
-### Install & Initialize
-
-#### Prerequisites
- **Node.js >= 20.19.0** - Check your version with `node --version`
-
-#### Step 1: Install the CLI globally
-
-**Option A: Using npm**
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-Verify installation:
-```bash
-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:
-```bash
-cd my-project
-```
-
-Run the initialization:
-```bash
-openspec init
-```
-
-**What happens during initialization:**
- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
- A new `openspec/` directory structure is created in your project
-
-**After setup:**
- Primary AI tools can trigger `/openspec` workflows without additional configuration
- Run `openspec list` to verify the setup and view any active changes
- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
-  so a fresh launch ensures they appear
-
-### Optional: Populate Project Context
-
-After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
-
-```text
-Populate your project context:
-"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
-```
-
-Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
-
-### Create Your First Change
-
-Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
-
-#### 1. Draft the Proposal
-Start by asking your AI to create a change proposal:
-
-```text
-You: Create an OpenSpec change proposal for adding profile search filters by role and team
-     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
-
-AI:  I'll create an OpenSpec change proposal for profile filters.
-     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
-```
-
-#### 2. Verify & Review
-Check that the change was created correctly and review the proposal:
-
-```bash
-$ openspec list                             # Confirm the change folder exists
-$ openspec validate add-profile-filters     # Validate spec formatting
-$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
-```
-
-#### 3. Refine the Specs
-Iterate on the specifications until they match your needs:
-
-```text
-You: Can you add acceptance criteria for the role and team filters?
-
-AI:  I'll update the spec delta with scenarios for role and team filters.
-     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
-```
-
-#### 4. Implement the Change
-Once specs look good, start implementation:
-
-```text
-You: The specs look good. Let's implement this change.
-     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
-
-AI:  I'll work through the tasks in the add-profile-filters change.
-     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
-     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
-```
-
-#### 5. Archive the Completed Change
-After implementation is complete, archive the change:
-
-```text
-AI:  All tasks are complete. The implementation is ready.
-
-You: Please archive the change
-     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
-
-AI:  I'll archive the add-profile-filters change.
-    *Runs: openspec archive add-profile-filters --yes*
-     ✓ Change archived successfully. Specs updated. Ready for the next feature!
-```
-
-Or run the command yourself in terminal:
-```bash
-$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
-```
-
-**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
-
-## Command Reference
-
-```bash
-openspec list               # View active change folders
-openspec view               # Interactive dashboard of specs and changes
-openspec show <change>      # Display change details (proposal, tasks, spec updates)
-openspec validate <change>  # Check spec formatting and structure
-openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
-```
-
-## Example: How AI Creates OpenSpec Files
-
-When you ask your AI assistant to "add two-factor authentication", it creates:
-
-```
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md           # Current auth spec (if exists)
-└── changes/
-    └── add-2fa/              # AI creates this entire structure
-        ├── proposal.md       # Why and what changes
-        ├── tasks.md          # Implementation checklist
-        ├── design.md         # Technical decisions (optional)
-        └── specs/
-            └── auth/
-                └── spec.md   # Delta showing additions
-```
-
-### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
-
-```markdown
-# Auth Specification
-
-## Purpose
-Authentication and session management.
-
-## Requirements
-### Requirement: User Authentication
-The system SHALL issue a JWT on successful login.
-
-#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned
-```
-
-### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
-
-#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required
-```
-
-### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
-
-```markdown
-## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table
-
-## 2. Backend Implementation  
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint
-
-## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI
-```
-
-**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
-
-## Understanding OpenSpec Files
-
-### Delta Format
-
-Deltas are "patches" that show how specs change:
-
- **`## ADDED Requirements`** - New capabilities
- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
- **`## REMOVED Requirements`** - Deprecated features
-
-**Format requirements:**
- Use `### Requirement: <name>` for headers
- Every requirement needs at least one `#### Scenario:` block
- Use SHALL/MUST in requirement text
-
-## How OpenSpec Compares
-
-### vs. spec-kit
-OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
-
-### vs. Kiro.dev
-OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
-
-### vs. No Specs
-Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
-
-## Team Adoption
-
-1. **Initialize OpenSpec** – Run `openspec init` in your repo.
-2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
-3. **Grow incrementally** – Each change archives into living specs that document your system.
-4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
-
-Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
-
-## Updating OpenSpec
-
-1. **Upgrade the package**
-   ```bash
-   npm install -g @fission-ai/openspec@latest
-   ```
-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 experimental`
-
-[Full documentation →](docs/opsx.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`
- Build: `pnpm run build`
- Test: `pnpm test`
- 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
@@ -1,5 +1,3 @@
 #!/usr/bin/env node

-import { runCli } from '../dist/cli/index.js';
-
-runCli();
+import '../dist/cli/index.js';
@@ -1,107 +0,0 @@
-# OpenSpec Documentation
-
-Welcome. This is the home for everything OpenSpec.
-
-OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.
-
-If you read nothing else, read these two pages:
-
-1. [Getting Started](getting-started.md): install, initialize, and ship your first change.
-2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once.
-
-That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
-
-> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
-
-## Pick your path
-
-**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby.
-
-**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything.
-
-**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean.
-
-**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place.
-
-**I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration.
-
-**I'm coming from the old workflow.** The [Migration Guide](migration-guide.md) explains what changed and why, and promises your existing work is safe.
-
-**I want to bend it to my team's process.** [Customization](customization.md) covers project config, custom schemas, and shared context.
-
-**Something's broken.** [Troubleshooting](troubleshooting.md) collects the failures people actually hit, with fixes.
-
-## The whole map
-
-### Start here
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end |
-| [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit |
-| [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat |
-| [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive |
-| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked |
-
-### Use it day to day
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [Workflows](workflows.md) | Common patterns and when to reach for each command |
-| [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable |
-| [Using OpenSpec in an Existing Project](existing-projects.md) | Adopting OpenSpec on a large brownfield codebase |
-| [Editing & Iterating on a Change](editing-changes.md) | Update artifacts, go back, reconcile manual edits |
-| [Commands](commands.md) | Reference for every `/opsx:*` slash command |
-| [CLI](cli.md) | Reference for every `openspec` terminal command |
-
-### Understand it deeply
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [Concepts](concepts.md) | The long-form explanation of specs, changes, artifacts, schemas, and archive |
-| [OPSX Workflow](opsx.md) | Why the workflow is fluid instead of phase-locked, plus an architecture deep dive |
-| [Glossary](glossary.md) | Every term defined in one place |
-
-### Make it yours
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [Customization](customization.md) | Project config, custom schemas, shared context |
-| [Multi-Language](multi-language.md) | Generate artifacts in languages other than English |
-| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land |
-
-### When you need help
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [FAQ](faq.md) | Quick answers to the questions people ask most |
-| [Troubleshooting](troubleshooting.md) | Concrete fixes for concrete failures |
-| [Migration Guide](migration-guide.md) | Moving from the legacy workflow to OPSX |
-
-### Coordinate across repos (beta)
-
-| Doc | What it gives you |
-|-----|-------------------|
-| [Stores: User Guide](stores-beta/user-guide.md) | Plan in its own repo when your work spans repos or teams |
-| [Agent Contract](agent-contract.md) | The machine-readable CLI surfaces agents drive |
-
-## The thirty-second version
-
-```text
-1. Install        npm install -g @fission-ai/openspec@latest
-2. Initialize     cd your-project && openspec init
-3. Explore        (in your AI chat)  /opsx:explore           ← optional, but a great habit
-4. Propose        (in your AI chat)  /opsx:propose add-dark-mode
-5. Build          (in your AI chat)  /opsx:apply
-6. Archive        (in your AI chat)  /opsx:archive
-```
-
-Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
-
-## Where else to get help
-
- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help.
- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) for bugs and feature requests.
- **`openspec feedback "your message"`** sends feedback straight from your terminal (it opens a GitHub issue).
-
-Found something in these docs that's wrong, stale, or confusing? That's a bug. Open an issue or a PR. Documentation improvements are some of the most valuable contributions you can make.
@@ -1,137 +0,0 @@
-# OpenSpec Agent Contract
-
-Machine-readable surfaces of the `openspec` CLI, verified against `src/` (capstone audit, 2026-06-11). Every shape below is documented from the emitting code.
-
-## 1. General conventions
-
- **One JSON document per invocation.** In `--json` mode, stdout carries exactly one JSON document (2-space pretty-printed). Human prose, spinners, and the store banner go to stderr.
- **Store banner.** In human mode, a store-selected root prints `Using OpenSpec root: <id> (<path>)` to stderr. Never printed in JSON mode.
- **Key casing is surface-dependent** (see Known inconsistencies): store/doctor/context payloads use `snake_case`; workflow payloads (`status`, `instructions`, `new change`, `validate`, `list`) use `camelCase`, except the embedded `root` object, which always uses `store_id`.
- **Optional keys are omitted, not null**, in most payloads (e.g. `root.store_id`, `member.path`). Exceptions that use explicit `null` are called out per shape (store doctor `git.*`, failure payloads).
-
-## 2. The diagnostic envelope
-
-One envelope shape is shared by every machine-readable diagnostic (`StoreDiagnostic`):
-
-```json
-{
-  "severity": "error" | "warning" | "info",
-  "code": "snake_case_string",
-  "message": "human sentence",
-  "target": "dotted.surface (optional)",
-  "fix": "one actionable sentence/command (optional)"
-}
-```
-
-Diagnostics appear in two positions: **status arrays** (`status: StoreDiagnostic[]` at top level or per entry) for health findings, and **thrown errors** converted to a single-element `status` array on command failure.
-
-## 3. Root selection and `RootOutput`
-
-All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `new change`, `archive`, `doctor`, `context`) resolve one OpenSpec root with one precedence:
-
-1. `--store <id>` → the registered store's root (`source: "store"`).
-2. Otherwise, nearest ancestor with `openspec/`: planning shape → `source: "nearest"` (a `store:` pointer is ignored with a stderr warning); config-only dir with a valid `store:` pointer → that store, `source: "declared"`.
-3. No nearest root + registered stores exist → error `no_root_with_registered_stores`.
-4. No root, no stores: scaffolding commands treat the cwd as `source: "implicit"`; diagnostic commands (`doctor`, `context`) fail with `no_openspec_root` instead — they inspect, never scaffold.
-
-Successful JSON payloads embed the root:
-
-```json
-"root": { "path": "/abs/path", "source": "store" | "declared" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }
-```
-
-**Root-failure contract**: in JSON mode a resolution failure prints `{ ...commandNullShape, "status": [diagnostic] }` on stdout and exits 1.
-
-## 4. Command JSON shapes
-
-### 4.1 `list --json`
-`{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput }` — note the per-change `status` is a string enum here. `--specs`: `{ "specs": [ { "id", "requirementCount" } ], "root" }`.
-
-### 4.2 `show <item> --json`
-Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }`.
-
-### 4.3 `validate --json`
-`{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }`. Exit 1 when any item fails.
-
-### 4.4 `status --json`
-`{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"ready"|"blocked", missingDeps?} ], "root" }`. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
-
-### 4.5 `instructions <artifact> --json`
-`{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "template", "dependencies": [{id,done,path,description}], "unlocks", "root" }`.
-
-`ReferenceIndexEntry`: `{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] }` — resolved entries carry root/specs/fetch; unresolved carry store_id + warning status. Index capped at 50KB (`reference_index_truncated`).
-
-### 4.6 `instructions apply --json`
-`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "root" }`.
-
-### 4.7 `new change <name> --json`
-Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Failure: `{ "change": null, "status": [d] }`, exit 1.
-
-### 4.8 `archive <name> --json`
-Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
-
-### 4.9 `doctor --json`
-`{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "status": [] } | null, "references": [...], "status": [] }`. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
-
-### 4.10 `context --json`
-`{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }`. AVAILABLE = path present AND status empty. `--code-workspace <path>` writes `{folders:[{name,path}]}` (available referenced stores only, `ref:` prefixes); in JSON mode the write runs before printing so stdout holds exactly one document even on write failure. Failure: `{ "root": null, "members": [], "status": [d] }`, exit 1.
-
-### 4.11 `store ... --json`
-setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }`. unregister/remove: `{ "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }`. list: `{ "stores": [{id, root}], "status": [] }`. doctor: `{ "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] }` (`null` = unknown/not probed). Health findings exit 0; failures exit 1 with the matching null-shape. Prompt cancellation exits 130.
-
-### 4.12 `schemas --json` / `templates --json`
-`schemas`: bare array `[ {name, description, artifacts, source} ]`. `templates`: keyed object `{ "<artifactId>": {path, source} }`. Both cwd-based, no root/status keys.
-
-## 5. Exit-code contract
-
-| Situation | Exit | Stdout |
-|---|---|---|
-| Success, incl. health findings (doctor/context/store doctor) | 0 | the payload |
-| Command failure in `--json` mode | 1 | one JSON document with `status: [d]` and the command's null-shape |
-| `validate` with failing items | 1 | full report |
-| Prompt cancellation (`store` group, human mode) | 130 | stderr only |
-
-## 6. Diagnostic code catalog
-
-### Resolution
-`no_openspec_root`, `no_root_with_registered_stores`, `no_registered_stores`, `unknown_store`, `store_identity_mismatch`, `unhealthy_store_root`, `store_path_not_supported`, `invalid_store_pointer`, `initiative_option_removed`, `areas_option_removed`; pass-through: `invalid_store_id`, `invalid_store_registry`, `invalid_store_metadata`.
-
-### OpenSpec-root health (error, no fix)
-`openspec_store_root_missing`, `openspec_root_missing`, `openspec_config_missing`, `openspec_specs_missing`, `openspec_changes_missing`, `openspec_archive_missing`, plus `_not_directory` variants of each.
-
-### Store registry/identity/state
-`invalid_store_id`, `invalid_store_registry`, `invalid_store_metadata`, `store_registry_busy`, `store_not_found`, `no_store_registry`, `store_registry_changed`, `store_metadata_missing`, `store_metadata_id_mismatch`, `store_metadata_invalid`, `store_id_conflict`, `store_path_conflict`, `store_already_registered` (info).
-
-### Store setup/register/remove
-`store_setup_id_required`, `store_setup_path_required`, `store_setup_path_not_directory`, `store_setup_inside_git_repo`, `store_setup_non_empty_directory`, `store_setup_cancelled`, `store_path_required`, `store_path_missing`, `store_path_not_directory`, `store_register_root_unhealthy`, `store_register_identity_confirmation_required`, `store_register_cancelled`, `store_remote_empty`, `store_remote_requires_hand_edit`, `store_remove_confirmation_required`, `store_remove_cancelled`, `store_remove_path_not_directory`, `store_remove_metadata_missing`, `store_root_missing` (warning in remove, error in doctor), `store_root_not_directory`.
-
-### Store git
-`store_git_init_failed`, `store_git_identity_missing`, `store_git_commit_failed`, `store_git_no_commits` (warning), `store_clone_fragile_directories` (warning), `store_remote_divergence` (info, doctor).
-
-### References (warning)
-`reference_invalid_id`, `reference_registry_unreadable`, `reference_unresolved`, `reference_root_unhealthy`, `reference_index_truncated`.
-
-### Relationships (warning; doctor; context keeps only the registry one)
-`relationship_registry_unreadable`, `root_pointer_ignored`, `root_pointer_invalid`, `pointer_declarations_inert`.
-
-### Archive (JSON mode)
-`archive_change_name_required`, `archive_change_not_found`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_error`.
-
-### Context writes
-`context_file_exists`, `context_output_dir_missing`.
-
-### Fallbacks
-`doctor_failed`, `context_failed`, `store_error`, `change_error`, `archive_error`.
-
-## Known inconsistencies
-
-Recorded by the capstone audit; published-key renames are product decisions deferred past this release:
-
-1. ~~In `--json` mode, several failure paths printed stderr only with no JSON document.~~ Fixed in the capstone gauntlet round: `show`/`validate` unknown and ambiguous items emit `{status:[{code: unknown_item | ambiguous_item, ...}]}`; thrown errors in `status`/`instructions`/`list`/`show`/`validate` route through the JSON-aware failure helper (the command's null-shape + `status`); `store <unknown subcommand> --json` emits `{status:[{code: unknown_store_subcommand}]}`; `list` carries its `{changes|specs: [], root: null}` null-shape on resolution failures.
-2. `store_root_missing` is emitted with two severities (warning in remove, error in store doctor) — context-dependent, documented above.
-3. snake_case (store family) vs camelCase (workflow family) key casing; `root.store_id` is snake_case everywhere.
-4. Four parallel envelope type declarations exist in src; archive diagnostics never carry `target`.
-5. `list --json` reuses the `status` key as a string enum per change.
-6. Only `validate` output carries a `version` field.
-7. `schemas`/`templates` ignore root selection (cwd-based, no `--store`).
-8. Deprecated noun forms (`change`/`spec` subcommands) emit unenveloped payloads without `root`/`status`.
@@ -0,0 +1,597 @@
+# POC-OpenSpec-Core Analysis
+
+---
+
+## Design Decisions & Terminology
+
+### Philosophy: Not a Workflow System
+
+This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
+
+| What it's NOT | What it IS |
+|---------------|------------|
+| Linear step-by-step progression | Exploratory, iterative planning |
+| Bureaucratic checkpoints | Enablers that unlock possibilities |
+| "You must complete step 1 first" | "Here's what you could create now" |
+| Form-filling | Fluid document creation |
+
+**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
+
+### Terminology
+
+| Term | Definition | Example |
+|------|------------|---------|
+| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
+| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
+| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
+| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
+
+### Hierarchy
+
+```
+Schema (defines) ──→ Artifacts (guided by) ──→ Templates
+```
+
+- **Schema** = the artifact graph (what exists, dependencies)
+- **Artifact** = a document to produce
+- **Template** = instructions for creating that artifact
+
+### Schema Variations
+
+Schemas can vary across multiple dimensions:
+
+| Dimension | Examples |
+|-----------|----------|
+| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
+| Version | `v1`, `v2`, `v3` |
+| Language | `en`, `zh`, `es` |
+| Custom | `team-alpha`, `experimental` |
+
+### Schema Resolution (XDG Standard)
+
+Schemas follow the XDG Base Directory Specification with a 2-level resolution:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # Global user override
+2. <package>/schemas/<name>/schema.yaml                    # Built-in defaults
+```
+
+**Platform-specific paths:**
+- Unix/macOS: `~/.local/share/openspec/schemas/`
+- Windows: `%LOCALAPPDATA%/openspec/schemas/`
+- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set)
+
+**Why XDG?**
+- Schemas are workflow definitions (data), not user preferences (config)
+- Built-ins baked into package, never auto-copied
+- Users customize by creating files in global data dir
+- Consistent with modern CLI tooling standards
+
+### Template Inheritance (2 Levels Max)
+
+Templates are co-located with schemas in a `templates/` subdirectory:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+2. <package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+```
+
+**Rules:**
+- User overrides take precedence over package built-ins
+- A CLI command shows resolved paths (no guessing)
+- No inheritance between schemas (copy if you need to diverge)
+- Templates are always co-located with their schema
+
+**Why this matters:**
+- Avoids "where does this come from?" debugging
+- No implicit magic that works until it doesn't
+- Schema + templates form a cohesive unit
+
+---
+
+## Executive Summary
+
+This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+
+The system answers:
+- "What artifacts exist for this change?"
+- "What could I create next?" (not "what must I create")
+- "What's blocking X?" (informational, not prescriptive)
+
+---
+
+## Core Components
+
+### 1. ArtifactGraph (Slice 1 - COMPLETE)
+
+The dependency graph engine with XDG-compliant schema resolution.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Model artifacts as a DAG | Artifact with `requires: string[]` |
+| Track completion state | `Set<string>` for completed artifacts |
+| Calculate build order | Kahn's algorithm (topological sort) |
+| Find ready artifacts | Check if all dependencies are in `completed` set |
+| Resolve schemas | XDG global → package built-ins |
+
+**Key Data Structures (Zod-validated):**
+
+```typescript
+// Zod schemas define types + validation
+const ArtifactSchema = z.object({
+  id: z.string().min(1),
+  generates: z.string().min(1),      // e.g., "proposal.md" or "specs/*.md"
+  description: z.string(),
+  template: z.string(),              // path to template file
+  requires: z.array(z.string()).default([]),
+});
+
+const SchemaYamlSchema = z.object({
+  name: z.string().min(1),
+  version: z.number().int().positive(),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1),
+});
+
+// Derived types
+type Artifact = z.infer<typeof ArtifactSchema>;
+type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+```
+
+**Key Methods:**
+- `resolveSchema(name)` - Load schema with XDG fallback
+- `ArtifactGraph.fromSchema(schema)` - Build graph from schema
+- `detectState(graph, changeDir)` - Scan filesystem for completion
+- `getNextArtifacts(graph, completed)` - Find artifacts ready to create
+- `getBuildOrder(graph)` - Topological sort of all artifacts
+- `getBlocked(graph, completed)` - Artifacts with unmet dependencies
+
+---
+
+### 2. Change Utilities (Slice 2)
+
+Simple utility functions for programmatic change creation. No class, no abstraction layer.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Create changes | Create dirs under `openspec/changes/<name>/` with README |
+| Name validation | Enforce kebab-case naming |
+
+**Key Paths:**
+
+```
+openspec/changes/<name>/   → Change instances with artifacts (project-level)
+```
+
+**Key Functions** (`src/utils/change-utils.ts`):
+- `createChange(projectRoot, name, description?)` - Create new change directory + README
+- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }`
+
+**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is.
+
+---
+
+### 3. InstructionLoader (Slice 3)
+
+Template resolution and instruction enrichment.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) |
+| Build dynamic context | Gather dependency status, change info |
+| Enrich templates | Inject context into base templates |
+| Generate status reports | Formatted markdown with progress |
+
+**Key Class - ChangeState:**
+
+```
+ChangeState {
+  changeName: string
+  changeDir: string
+  graph: ArtifactGraph
+  completed: Set<string>
+
+  // Methods
+  getNextSteps(): string[]
+  getStatus(artifactId): ArtifactStatus
+  isComplete(): boolean
+}
+```
+
+**Key Functions:**
+- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
+- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
+
+---
+
+### 4. CLI (Slice 4)
+
+User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
+
+| Command | Function | Status |
+|---------|----------|--------|
+| `status --change <id>` | Show change progress (artifact graph) | **NEW** |
+| `next --change <id>` | Show artifacts ready to create | **NEW** |
+| `instructions <artifact> --change <id>` | Get enriched instructions for artifact | **NEW** |
+| `list` | List all changes | EXISTS (`openspec change list`) |
+| `new <name>` | Create change | **NEW** (uses `createChange()`) |
+| `init` | Initialize structure | EXISTS (`openspec init`) |
+| `templates --change <id>` | Show resolved template paths | **NEW** |
+
+**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
+
+**Existing CLI commands** (not part of this slice):
+- `openspec change list` / `openspec change show <id>` / `openspec change validate <id>`
+- `openspec list --changes` / `openspec list --specs`
+- `openspec view` (dashboard)
+- `openspec init` / `openspec archive <change>`
+
+---
+
+### 5. Claude Commands
+
+Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
+
+| Command | Purpose |
+|---------|---------|
+| `/status` | Show change progress |
+| `/next` | Show what's ready to create |
+| `/run [artifact]` | Execute a specific step (power users) |
+| `/list` | List all changes |
+| `/new <name>` | Create a new change |
+| `/init` | Initialize structure |
+
+**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
+1. Infers change from conversation (confirms if uncertain)
+2. Infers artifact from request
+3. Calls CLI with explicit `--change` parameter
+4. Creates artifact following instructions
+
+This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
+
+**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
+
+---
+
+## Component Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PRESENTATION LAYER                       │
+│  ┌──────────────┐                    ┌────────────────────┐ │
+│  │     CLI      │ ←─shell exec───────│ Claude Commands    │ │
+│  └──────┬───────┘                    └────────────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+          │ imports
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    ORCHESTRATION LAYER                       │
+│  ┌────────────────────┐        ┌──────────────────────────┐ │
+│  │ InstructionLoader  │        │  change-utils (Slice 2)  │ │
+│  │    (Slice 3)       │        │  createChange()          │ │
+│  └─────────┬──────────┘        │  validateChangeName()    │ │
+│            │                   └──────────────────────────┘ │
+└────────────┼────────────────────────────────────────────────┘
+             │ uses
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CORE LAYER                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │               ArtifactGraph (Slice 1)                │   │
+│  │                                                      │   │
+│  │  Schema Resolution (XDG) ──→ Graph ──→ State Detection│   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+             ▲
+             │ reads from
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   PERSISTENCE LAYER                          │
+│  ┌──────────────────┐   ┌────────────────────────────────┐  │
+│  │  XDG Schemas     │   │  Project Artifacts             │  │
+│  │  ~/.local/share/ │   │  openspec/changes/<name>/      │  │
+│  │  openspec/       │   │  - proposal.md, design.md      │  │
+│  │  schemas/        │   │  - specs/*.md, tasks.md        │  │
+│  └──────────────────┘   └────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Design Patterns
+
+### 1. Filesystem as Database
+
+No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
+
+```
+// State detection is just file existence checking
+if (exists(artifactPath)) {
+  completed.add(artifactId)
+}
+```
+
+### 2. Deterministic CLI, Inferring Agent
+
+**CLI layer:** Always deterministic - requires explicit `--change` parameter.
+
+```
+openspec status --change add-auth     # explicit, works
+openspec status                        # error: "No change specified"
+```
+
+**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
+
+This separation means:
+- CLI is pure, testable, no state to corrupt
+- Agent handles all "smartness"
+- No config.yaml tracking of "active change"
+
+### 3. XDG-Compliant Schema Resolution
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
+    ↓ (not found)
+<package>/schemas/<name>/schema.yaml                    # Built-in
+    ↓ (not found)
+Error (schema not found)
+```
+
+### 4. Two-Level Template Fallback
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+    ↓ (not found)
+<package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+    ↓ (not found)
+Error (no silent fallback to avoid confusion)
+```
+
+### 5. Glob Pattern Support
+
+`specs/*.md` allows multiple files to satisfy a single artifact:
+
+```
+if (artifact.generates.includes("*")) {
+  const parentDir = changeDir / patternParts[0]
+  if (exists(parentDir) && hasFiles(parentDir)) {
+    completed.add(artifactId)
+  }
+}
+```
+
+### 6. Stateless State Detection
+
+Every command re-scans the filesystem. No cached state to corrupt.
+
+---
+
+## Artifact Pipeline (Default Schema)
+
+The default `spec-driven` schema:
+
+```
+┌──────────┐
+│ proposal │  (no dependencies)
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  specs   │  (requires: proposal)
+└────┬─────┘
+     │
+     ├──────────────┐
+     ▼              ▼
+┌──────────┐   ┌──────────┐
+│  design  │   │          │
+│          │◄──┤ proposal │
+└────┬─────┘   └──────────┘
+     │         (requires: proposal, specs)
+     ▼
+┌──────────┐
+│  tasks   │  (requires: design)
+└──────────┘
+```
+
+Other schemas (TDD, prototype-first) would have different graphs.
+
+---
+
+## Implementation Order
+
+Structured as **vertical slices** - each slice is independently testable.
+
+---
+
+### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE
+
+**Delivers:** Types + Graph + State Detection + Schema Resolution
+
+**Implementation:** `src/core/artifact-graph/`
+- `types.ts` - Zod schemas and derived TypeScript types
+- `schema.ts` - YAML parsing with Zod validation
+- `graph.ts` - ArtifactGraph class with topological sort
+- `state.ts` - Filesystem-based state detection
+- `resolver.ts` - XDG-compliant schema resolution
+- `builtin-schemas.ts` - Package-bundled default schemas
+
+**Key decisions made:**
+- Zod for schema validation (consistent with project)
+- XDG for global schema overrides
+- `Set<string>` for completion state (immutable, functional)
+- `inProgress` and `failed` states deferred (require external tracking)
+
+---
+
+### Slice 2: "Change Creation Utilities"
+
+**Delivers:** Utility functions for programmatic change creation
+
+**Scope:**
+- `createChange(projectRoot, name, description?)` → creates directory + README
+- `validateChangeName(name)` → kebab-case pattern enforcement
+
+**Not in scope (already exists in CLI commands):**
+- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()`
+- `getChangePath()` → simple `path.join()` inline
+- `changeExists()` → simple `fs.access()` inline
+- `isInitialized()` → simple directory check inline
+
+**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation.
+
+---
+
+### Slice 3: "Get Instructions" (Enrichment)
+
+**Delivers:** Template resolution + context injection
+
+**Testable behaviors:**
+- Template fallback: schema-specific → shared → built-in → error
+- Context injection: completed deps show ✓, missing show ✗
+- Output path shown correctly based on change directory
+
+---
+
+### Slice 4: "CLI + Integration"
+
+**Delivers:** New artifact graph commands (builds on existing CLI)
+
+**New commands:**
+- `status --change <id>` - Show artifact completion state
+- `next --change <id>` - Show ready-to-create artifacts
+- `instructions <artifact> --change <id>` - Get enriched template
+- `templates --change <id>` - Show resolved paths
+- `new <name>` - Create change (wrapper for `createChange()`)
+
+**Already exists (not in scope):**
+- `openspec change list/show/validate` - change management
+- `openspec list --changes/--specs` - listing
+- `openspec view` - dashboard
+- `openspec init` - initialization
+
+**Testable behaviors:**
+- Each new command produces expected output
+- Commands compose correctly (status → next → instructions flow)
+- Error handling for missing changes, invalid artifacts, etc.
+
+---
+
+## Directory Structure
+
+```
+# Global (XDG paths - user overrides)
+~/.local/share/openspec/           # Unix/macOS ($XDG_DATA_HOME/openspec/)
+%LOCALAPPDATA%/openspec/           # Windows
+└── schemas/                       # Schema overrides
+    └── custom-workflow/           # User-defined schema directory
+        ├── schema.yaml            # Schema definition
+        └── templates/             # Co-located templates
+            └── proposal.md
+
+# Package (built-in defaults)
+<package>/
+└── schemas/                       # Built-in schema definitions
+    ├── spec-driven/               # Default: proposal → specs → design → tasks
+    │   ├── schema.yaml
+    │   └── templates/
+    │       ├── proposal.md
+    │       ├── design.md
+    │       ├── spec.md
+    │       └── tasks.md
+    └── tdd/                       # TDD: tests → implementation → docs
+        ├── schema.yaml
+        └── templates/
+            ├── test.md
+            ├── implementation.md
+            ├── spec.md
+            └── docs.md
+
+# Project (change instances)
+openspec/
+└── changes/                       # Change instances
+    ├── add-auth/
+    │   ├── README.md              # Auto-generated on creation
+    │   ├── proposal.md            # Created artifacts
+    │   ├── design.md
+    │   └── specs/
+    │       └── *.md
+    ├── refactor-db/
+    │   └── ...
+    └── archive/                   # Completed changes
+        └── 2025-01-01-add-auth/
+
+.claude/
+├── settings.local.json            # Permissions
+└── commands/                      # Slash commands
+    └── *.md
+```
+
+---
+
+## Schema YAML Format
+
+```yaml
+# Built-in: <package>/schemas/spec-driven/schema.yaml
+# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
+name: spec-driven
+version: 1
+description: Specification-driven development
+
+artifacts:
+  - id: proposal
+    generates: "proposal.md"
+    description: "Create project proposal document"
+    template: "proposal.md"          # resolves from co-located templates/ directory
+    requires: []
+
+  - id: specs
+    generates: "specs/*.md"          # glob pattern
+    description: "Create technical specification documents"
+    template: "specs.md"
+    requires:
+      - proposal
+
+  - id: design
+    generates: "design.md"
+    description: "Create design document"
+    template: "design.md"
+    requires:
+      - proposal
+      - specs
+
+  - id: tasks
+    generates: "tasks.md"
+    description: "Create tasks breakdown document"
+    template: "tasks.md"
+    requires:
+      - design
+```
+
+---
+
+## Summary
+
+| Layer | Component | Responsibility | Status |
+|-------|-----------|----------------|--------|
+| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
+| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
+| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
+| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
+| Integration | Claude Commands | AI assistant glue | Slice 4 |
+
+**What already exists (not in this proposal):**
+- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
+- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
+- `ListCommand.execute()` in `src/core/list.ts`
+- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
+- `src/core/init.ts` - initialization
+- `src/core/archive.ts` - archiving
+
+**Key Principles:**
+- **Filesystem IS the database** - stateless, version-control friendly
+- **Dependencies are enablers** - show what's possible, don't force order
+- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
+- **XDG-compliant paths** - schemas and templates use standard user data directories
+- **2-level inheritance** - user override → package built-in (no deeper)
+- **Schemas are versioned** - support variations by philosophy, version, language
@@ -1,707 +0,0 @@
-# Commands
-
-This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Windsurf).
-
-For workflow patterns and when to use each command, see [Workflows](workflows.md). For CLI commands, see [CLI](cli.md).
-
-## Quick Reference
-
-### Default Quick Path (`core` profile)
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step |
-| `/opsx:explore` | Think through ideas before committing to a change |
-| `/opsx:apply` | Implement tasks from the change |
-| `/opsx:sync` | Merge delta specs into main specs |
-| `/opsx:archive` | Archive a completed change |
-
-### Expanded Workflow Commands (custom workflow selection)
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:new` | Start a new change scaffold |
-| `/opsx:continue` | Create the next artifact based on dependencies |
-| `/opsx:ff` | Fast-forward: create all planning artifacts at once |
-| `/opsx:verify` | Validate implementation matches artifacts |
-| `/opsx:bulk-archive` | Archive multiple changes at once |
-| `/opsx:onboard` | Guided tutorial through the complete workflow |
-
-The default global profile is `core`. To enable expanded workflow commands, run `openspec config profile`, select workflows, then run `openspec update` in your project.
-
---
-
-## Command Reference
-
-### `/opsx:propose`
-
-Create a new change and generate planning artifacts in one step. This is the default start command in the `core` profile.
-
-**Syntax:**
-```text
-/opsx:propose [change-name-or-description]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name-or-description` | No | Kebab-case name or plain-language change description |
-
-**What it does:**
- Creates `openspec/changes/<change-name>/`
- Generates artifacts needed before implementation (for `spec-driven`: proposal, specs, design, tasks)
- Stops when the change is ready for `/opsx:apply`
-
-**Example:**
-```text
-You: /opsx:propose add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md
-     ✓ specs/ui/spec.md
-     ✓ design.md
-     ✓ tasks.md
-     Ready for implementation. Run /opsx:apply.
-```
-
-**Tips:**
- Use this for the fastest end-to-end path
- If you want step-by-step artifact control, enable expanded workflows and use `/opsx:new` + `/opsx:continue`
-
---
-
-### `/opsx:explore`
-
-> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
-
-Think through ideas, investigate problems, and clarify requirements before committing to a change.
-
-**Syntax:**
-```
-/opsx:explore [topic]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `topic` | No | What you want to explore or investigate |
-
-**What it does:**
- Opens an exploratory conversation with no structure required
- Investigates the codebase to answer questions
- Compares options and approaches
- Creates visual diagrams to clarify thinking
- Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
-
-**Example:**
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: How should we handle authentication for the mobile app?
-
-AI:  Let me investigate your current auth setup...
-     [Analyzes codebase]
-
-     I see you're using session-based auth for the web app.
-     For mobile, we have three main options:
-
-     1. JWT tokens (stateless, works offline)
-     2. OAuth2 (if you need third-party login)
-     3. Extend current sessions (simpler, but requires connectivity)
-
-     Your API already has CORS configured. Which direction interests you?
-
-You: Let's go with JWT. Can we start a change for that?
-
-AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
-```
-
-**Tips:**
- Use when requirements are unclear or you need to investigate
- No artifacts are created during exploration
- Good for comparing multiple approaches before deciding
- Can read files and search the codebase
-
---
-
-### `/opsx:new`
-
-Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with `/opsx:continue` or `/opsx:ff`.
-
-This command is part of the expanded workflow set (not included in the default `core` profile).
-
-**Syntax:**
-```
-/opsx:new [change-name] [--schema <schema-name>]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Name for the change folder (prompted if not provided) |
-| `--schema` | No | Workflow schema to use (default: from config or `spec-driven`) |
-
-**What it does:**
- Creates `openspec/changes/<change-name>/` directory
- Creates `.openspec.yaml` metadata file in the change folder
- Shows the first artifact template ready for creation
- Prompts for change name and schema if not provided
-
-**What it creates:**
-```
-openspec/changes/<change-name>/
-└── .openspec.yaml    # Change metadata (schema, created date)
-```
-
-**Example:**
-```
-You: /opsx:new add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     Schema: spec-driven
-
-     Ready to create: proposal
-     Use /opsx:continue to create it, or /opsx:ff to create all artifacts.
-```
-
-**Tips:**
- Use descriptive names: `add-feature`, `fix-bug`, `refactor-module`
- Avoid generic names like `update`, `changes`, `wip`
- Schema can also be set in project config (`openspec/config.yaml`)
-
---
-
-### `/opsx:continue`
-
-Create the next artifact in the dependency chain. Creates one artifact at a time for incremental progress.
-
-**Syntax:**
-```
-/opsx:continue [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to continue (inferred from context if not provided) |
-
-**What it does:**
- Queries the artifact dependency graph
- Shows which artifacts are ready vs blocked
- Creates the first ready artifact
- Reads dependency files for context
- Shows what becomes available after creation
-
-**Example:**
-```
-You: /opsx:continue
-
-AI:  Change: add-dark-mode
-
-     Artifact status:
-     ✓ proposal    (done)
-     ◆ specs       (ready)
-     ◆ design      (ready)
-     ○ tasks       (blocked - needs: specs)
-
-     Creating specs...
-
-     [Reads proposal.md, creates specs based on requirements]
-
-     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
-
-     Now available: tasks
-     Run /opsx:continue to create the next artifact.
-```
-
-**Tips:**
- Use when you want to review each artifact before proceeding
- Good for complex changes where you want control
- Multiple artifacts may become ready simultaneously
- You can edit created artifacts before continuing
-
---
-
-### `/opsx:ff`
-
-Fast-forward through artifact creation. Creates all planning artifacts at once.
-
-**Syntax:**
-```
-/opsx:ff [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to fast-forward (inferred from context if not provided) |
-
-**What it does:**
- Creates all artifacts in dependency order
- Tracks progress via todo list
- Stops when all `apply-required` artifacts are complete
- Reads each dependency before creating the next artifact
-
-**Example:**
-```
-You: /opsx:ff add-dark-mode
-
-AI:  Fast-forwarding add-dark-mode...
-
-     ✓ Creating proposal.md
-     ✓ Creating specs/ui/spec.md
-     ✓ Creating design.md
-     ✓ Creating tasks.md
-
-     All planning artifacts complete!
-     Ready for implementation. Run /opsx:apply to begin.
-```
-
-**Tips:**
- Use when you have a clear picture of what you're building
- Faster than `/opsx:continue` for straightforward changes
- You can still edit artifacts afterward
- Good for small to medium features
-
---
-
-### `/opsx:apply`
-
-Implement tasks from the change. Works through the task list, writing code and checking off items.
-
-**Syntax:**
-```
-/opsx:apply [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to implement (inferred from context if not provided) |
-
-**What it does:**
- Reads `tasks.md` and identifies incomplete tasks
- Works through tasks one by one
- Writes code, creates files, runs tests as needed
- Marks tasks complete with checkboxes `[x]`
-
-**Example:**
-```
-You: /opsx:apply
-
-AI:  Implementing add-dark-mode...
-
-     Reading tasks.md:
-     - [ ] 1.1 Create ThemeContext
-     - [ ] 1.2 Add CSS custom properties
-     - [ ] 1.3 Implement localStorage persistence
-
-     Working on 1.1: Create ThemeContext...
-     [Creates src/context/ThemeContext.tsx]
-
-     ✓ 1.1 Complete
-
-     Working on 1.2: Add CSS custom properties...
-     [Updates src/styles/globals.css]
-
-     ✓ 1.2 Complete
-     ...
-```
-
-**Tips:**
- Can resume where you left off if interrupted
- Use for parallel changes by specifying the change name
- Completion state is tracked in `tasks.md` checkboxes
-
---
-
-### `/opsx:verify`
-
-Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.
-
-**Syntax:**
-```
-/opsx:verify [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to verify (inferred from context if not provided) |
-
-**What it does:**
- Checks three dimensions of implementation quality
- Searches codebase for implementation evidence
- Reports issues categorized as CRITICAL, WARNING, or SUGGESTION
- Does not block archive, but surfaces issues
-
-**Verification dimensions:**
-
-| Dimension | What it validates |
-|-----------|-------------------|
-| **Completeness** | All tasks done, all requirements implemented, scenarios covered |
-| **Correctness** | Implementation matches spec intent, edge cases handled |
-| **Coherence** | Design decisions reflected in code, patterns consistent |
-
-**Example:**
-```
-You: /opsx:verify
-
-AI:  Verifying add-dark-mode...
-
-     COMPLETENESS
-     ✓ All 8 tasks in tasks.md are checked
-     ✓ All requirements in specs have corresponding code
-     ⚠ Scenario "System preference detection" has no test coverage
-
-     CORRECTNESS
-     ✓ Implementation matches spec intent
-     ✓ Edge cases from scenarios are handled
-     ✓ Error states match spec definitions
-
-     COHERENCE
-     ✓ Design decisions reflected in code structure
-     ✓ Naming conventions consistent with design.md
-     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes
-
-     SUMMARY
-     ─────────────────────────────
-     Critical issues: 0
-     Warnings: 2
-     Ready to archive: Yes (with warnings)
-
-     Recommendations:
-     1. Add test for system preference detection
-     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables
-```
-
-**Tips:**
- Run before archiving to catch mismatches early
- Warnings don't block archive but indicate potential issues
- Good for reviewing AI's work before committing
- Can reveal drift between artifacts and implementation
-
---
-
-### `/opsx:sync`
-
-**Optional command.** Merge delta specs from a change into main specs. Archive will prompt to sync if needed, so you typically don't need to run this manually.
-
-**Syntax:**
-```
-/opsx:sync [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to sync (inferred from context if not provided) |
-
-**What it does:**
- Reads delta specs from change folder
- Parses ADDED/MODIFIED/REMOVED/RENAMED sections
- Merges changes into main `openspec/specs/` directory
- Preserves existing content not mentioned in delta
- Does not archive the change (remains active)
-
-**Example:**
-```text
-You: /opsx:sync
-
-AI:  Syncing add-dark-mode delta specs...
-
-     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
-     Target:  openspec/specs/ui/spec.md
-
-     Changes to apply:
-     ✓ ADDED: Theme Selection requirement (2 scenarios)
-     ✓ ADDED: Accessibility requirement (1 scenario)
-
-     Merging...
-     ✓ openspec/specs/ui/spec.md updated
-
-     Change remains active. Run /opsx:archive when ready to complete.
-```
-
-**When to use manually:**
-
-| Scenario | Use sync? |
-|----------|-----------|
-| Long-running change, want specs in main before archiving | Yes |
-| Multiple parallel changes need the updated base specs | Yes |
-| Want to preview/review the merge separately | Yes |
-| Quick change, going straight to archive | No (archive handles it) |
-
-**Tips:**
- Sync is intelligent, not copy-paste
- Can add scenarios to existing requirements without duplicating
- Change stays active after sync (not archived)
- Most users will never need to call this directly—archive prompts if needed
-
---
-
-### `/opsx:archive`
-
-Archive a completed change. Finalizes the change and moves it to the archive folder.
-
-**Syntax:**
-```
-/opsx:archive [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to archive (inferred from context if not provided) |
-
-**What it does:**
- Checks artifact completion status
- Checks task completion (warns if incomplete)
- Offers to sync delta specs if not already synced
- Moves change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
- Preserves all artifacts for audit trail
-
-**Example:**
-```text
-You: /opsx:archive
-
-AI:  Archiving add-dark-mode...
-
-     Artifact status:
-     ✓ proposal.md exists
-     ✓ specs/ exists
-     ✓ design.md exists
-     ✓ tasks.md exists (8/8 tasks complete)
-
-     Delta specs: Not yet synced
-     → Sync now? (recommended)
-
-You: Yes
-
-AI:  ✓ Synced specs to openspec/specs/ui/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
-
-     Change archived successfully.
-```
-
-**Tips:**
- Archive won't block on incomplete tasks, but will warn
- Delta specs can be synced during archive or beforehand
- Archived changes are preserved for history
- Use `/opsx:verify` first to catch issues
-
---
-
-### `/opsx:bulk-archive`
-
-Archive multiple completed changes at once. Handles spec conflicts between changes.
-
-**Syntax:**
-```
-/opsx:bulk-archive [change-names...]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-names` | No | Specific changes to archive (prompts to select if not provided) |
-
-**What it does:**
- Lists all completed changes
- Validates each change before archiving
- Detects spec conflicts across changes
- Resolves conflicts by checking what's actually implemented
- Archives in chronological order
-
-**Example:**
-```
-You: /opsx:bulk-archive
-
-AI:  Found 3 completed changes:
-     - add-dark-mode (8/8 tasks complete)
-     - fix-login-bug (3/3 tasks complete)
-     - update-footer (2/2 tasks complete)
-
-     Checking for spec conflicts...
-     ⚠ add-dark-mode and update-footer both touch specs/ui/
-
-     Inspecting codebase to resolve...
-     Both changes are implemented. Will merge in chronological order:
-     1. add-dark-mode (created Jan 20)
-     2. update-footer (created Jan 22)
-
-     Archive all 3 changes?
-
-You: Yes
-
-AI:  ✓ Archived add-dark-mode
-     ✓ Archived fix-login-bug
-     ✓ Archived update-footer
-     Specs merged: add-dark-mode → update-footer
-```
-
-**Tips:**
- Good for parallel work streams
- Conflict resolution is agentic (checks codebase)
- Changes are archived in order of creation
- Prompts before overwriting spec content
-
---
-
-### `/opsx:onboard`
-
-Guided onboarding through the complete OpenSpec workflow. An interactive tutorial using your actual codebase.
-
-**Syntax:**
-```
-/opsx:onboard
-```
-
-**What it does:**
- Walks through a complete workflow cycle with narration
- Scans your codebase for real improvement opportunities
- Creates an actual change with real artifacts
- Implements actual work (small, safe changes)
- Archives the completed change
- Explains each step as it happens
-
-**Phases:**
-1. Welcome and codebase analysis
-2. Finding an improvement opportunity
-3. Creating a change (`/opsx:new`)
-4. Writing the proposal
-5. Creating specs
-6. Writing the design
-7. Creating tasks
-8. Implementing tasks (`/opsx:apply`)
-9. Verifying implementation
-10. Archiving the change
-11. Summary and next steps
-
-**Example:**
-```
-You: /opsx:onboard
-
-AI:  Welcome to OpenSpec!
-
-     I'll walk you through the complete workflow using your actual codebase.
-     We'll find something small to improve, create a proper change for it,
-     implement it, and archive it.
-
-     Let me scan your codebase for opportunities...
-
-     [Analyzes codebase]
-
-     I found a few things we could work on:
-     1. Add input validation to the contact form
-     2. Improve error messages in the auth flow
-     3. Add loading states to async buttons
-
-     Which interests you? (or suggest something else)
-```
-
-**Tips:**
- Best for new users learning the workflow
- Uses real code, not toy examples
- Creates a real change you can keep or discard
- Takes 15-30 minutes to complete
-
---
-
-## Command Syntax by AI Tool
-
-Different AI tools use slightly different command syntax. Use the format that matches your tool:
-
-| Tool | Syntax Example |
-|------|----------------|
-| Claude Code | `/opsx:propose`, `/opsx:apply` |
-| Cursor | `/opsx-propose`, `/opsx-apply` |
-| Windsurf | `/opsx-propose`, `/opsx-apply` |
-| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
-| Kimi CLI | Skill-based invocations such as `/skill:openspec-propose`, `/skill:openspec-apply-change` (no generated `opsx-*` command files) |
-| Trae | Skill-based invocations such as `/openspec-propose`, `/openspec-apply-change` (no generated `opsx-*` command files) |
-
-The intent is the same across tools, but how commands are surfaced can differ by integration.
-
-> **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds.
-
---
-
-## Legacy Commands
-
-These commands use the older "all-at-once" workflow. They still work but OPSX commands are recommended.
-
-| Command | What it does |
-|---------|--------------|
-| `/openspec:proposal` | Create all artifacts at once (proposal, specs, design, tasks) |
-| `/openspec:apply` | Implement the change |
-| `/openspec:archive` | Archive the change |
-
-**When to use legacy commands:**
- Existing projects using the old workflow
- Simple changes where you don't need incremental artifact creation
- Preference for the all-or-nothing approach
-
-**Migrating to OPSX:**
-Legacy changes can be continued with OPSX commands. The artifact structure is compatible.
-
---
-
-## Troubleshooting
-
-### "Change not found"
-
-The command couldn't identify which change to work on.
-
-**Solutions:**
- Specify the change name explicitly: `/opsx:apply add-dark-mode`
- Check that the change folder exists: `openspec list`
- Verify you're in the right project directory
-
-### "No artifacts ready"
-
-All artifacts are either complete or blocked by missing dependencies.
-
-**Solutions:**
- Run `openspec status --change <name>` to see what's blocking
- Check if required artifacts exist
- Create missing dependency artifacts first
-
-### "Schema not found"
-
-The specified schema doesn't exist.
-
-**Solutions:**
- List available schemas: `openspec schemas`
- Check spelling of schema name
- Create the schema if it's custom: `openspec schema init <name>`
-
-### Commands not recognized
-
-The AI tool doesn't recognize OpenSpec commands.
-
-**Solutions:**
- Ensure OpenSpec is initialized: `openspec init`
- Regenerate skills: `openspec update`
- Check that `.claude/skills/` directory exists (for Claude Code)
- Restart your AI tool to pick up new skills
-
-### Artifacts not generating properly
-
-The AI creates incomplete or incorrect artifacts.
-
-**Solutions:**
- Add project context in `openspec/config.yaml`
- Add per-artifact rules for specific guidance
- Provide more detail in your change description
- Use `/opsx:continue` instead of `/opsx:ff` for more control
-
---
-
-## Next Steps
-
- [Workflows](workflows.md) - Common patterns and when to use each command
- [CLI](cli.md) - Terminal commands for management and validation
- [Customization](customization.md) - Create custom schemas and workflows
@@ -1,628 +0,0 @@
-# Concepts
-
-This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see [Getting Started](getting-started.md) and [Workflows](workflows.md).
-
-## Philosophy
-
-OpenSpec is built around four principles:
-
-```
-fluid not rigid         — no phase gates, work on what makes sense
-iterative not waterfall — learn as you build, refine as you go
-easy not complex        — lightweight setup, minimal ceremony
-brownfield-first        — works with existing codebases, not just greenfield
-```
-
-### Why These Principles Matter
-
-**Fluid not rigid.** Traditional spec systems lock you into phases: first you plan, then you implement, then you're done. OpenSpec is more flexible — you can create artifacts in any order that makes sense for your work.
-
-**Iterative not waterfall.** Requirements change. Understanding deepens. What seemed like a good approach at the start might not hold up after you see the codebase. OpenSpec embraces this reality.
-
-**Easy not complex.** Some spec frameworks require extensive setup, rigid formats, or heavyweight processes. OpenSpec stays out of your way. Initialize in seconds, start working immediately, customize only if you need to.
-
-**Brownfield-first.** Most software work isn't building from scratch — it's modifying existing systems. OpenSpec's delta-based approach makes it easy to specify changes to existing behavior, not just describe new systems.
-
-## The Big Picture
-
-OpenSpec organizes your work into two main areas:
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│                        openspec/                                   │
-│                                                                    │
-│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
-│   │       specs/        │      │         changes/              │   │
-│   │                     │      │                               │   │
-│   │  Source of truth    │◄─────│  Proposed modifications       │   │
-│   │  How your system    │ merge│  Each change = one folder     │   │
-│   │  currently works    │      │  Contains artifacts + deltas  │   │
-│   │                     │      │                               │   │
-│   └─────────────────────┘      └───────────────────────────────┘   │
-│                                                                    │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-**Specs** are the source of truth — they describe how your system currently behaves.
-
-**Changes** are proposed modifications — they live in separate folders until you're ready to merge them.
-
-This separation is key. You can work on multiple changes in parallel without conflicts. You can review a change before it affects the main specs. And when you archive a change, its deltas merge cleanly into the source of truth.
-
-## Specs
-
-Specs describe your system's behavior using structured requirements and scenarios.
-
-### Structure
-
-```
-openspec/specs/
-├── auth/
-│   └── spec.md           # Authentication behavior
-├── payments/
-│   └── spec.md           # Payment processing
-├── notifications/
-│   └── spec.md           # Notification system
-└── ui/
-    └── spec.md           # UI behavior and themes
-```
-
-Organize specs by domain — logical groupings that make sense for your system. Common patterns:
-
- **By feature area**: `auth/`, `payments/`, `search/`
- **By component**: `api/`, `frontend/`, `workers/`
- **By bounded context**: `ordering/`, `fulfillment/`, `inventory/`
-
-### Spec Format
-
-A spec contains requirements, and each requirement has scenarios:
-
-```markdown
-# Auth Specification
-
-## Purpose
-Authentication and session management for the application.
-
-## Requirements
-
-### Requirement: User Authentication
-The system SHALL issue a JWT token upon successful login.
-
-#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
-
-#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
-
-### Requirement: Session Expiration
-The system MUST expire sessions after 30 minutes of inactivity.
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate
-```
-
-**Key elements:**
-
-| Element | Purpose |
-|---------|---------|
-| `## Purpose` | High-level description of this spec's domain |
-| `### Requirement:` | A specific behavior the system must have |
-| `#### Scenario:` | A concrete example of the requirement in action |
-| SHALL/MUST/SHOULD | RFC 2119 keywords indicating requirement strength |
-
-### Why Structure Specs This Way
-
-**Requirements are the "what"** — they state what the system should do without specifying implementation.
-
-**Scenarios are the "when"** — they provide concrete examples that can be verified. Good scenarios:
- Are testable (you could write an automated test for them)
- Cover both happy path and edge cases
- Use Given/When/Then or similar structured format
-
-**RFC 2119 keywords** (SHALL, MUST, SHOULD, MAY) communicate intent:
- **MUST/SHALL** — absolute requirement
- **SHOULD** — recommended, but exceptions exist
- **MAY** — optional
-
-### What a Spec Is (and Is Not)
-
-A spec is a **behavior contract**, not an implementation plan.
-
-Good spec content:
- Observable behavior users or downstream systems rely on
- Inputs, outputs, and error conditions
- External constraints (security, privacy, reliability, compatibility)
- Scenarios that can be tested or explicitly validated
-
-Avoid in specs:
- Internal class/function names
- Library or framework choices
- Step-by-step implementation details
- Detailed execution plans (those belong in `design.md` or `tasks.md`)
-
-Quick test:
- If implementation can change without changing externally visible behavior, it likely does not belong in the spec.
-
-### Keep It Lightweight: Progressive Rigor
-
-OpenSpec aims to avoid bureaucracy. Use the lightest level that still makes the change verifiable.
-
-**Lite spec (default):**
- Short behavior-first requirements
- Clear scope and non-goals
- A few concrete acceptance checks
-
-**Full spec (for higher risk):**
- Cross-team or cross-repo changes
- API/contract changes, migrations, security/privacy concerns
- Changes where ambiguity is likely to cause expensive rework
-
-Most changes should stay in Lite mode.
-
-### Human + Agent Collaboration
-
-In many teams, humans explore and agents draft artifacts. The intended loop is:
-
-1. Human provides intent, context, and constraints.
-2. Agent converts this into behavior-first requirements and scenarios.
-3. Agent keeps implementation detail in `design.md` and `tasks.md`, not `spec.md`.
-4. Validation confirms structure and clarity before implementation.
-
-This keeps specs readable for humans and consistent for agents.
-
-## Changes
-
-A change is a proposed modification to your system, packaged as a folder with everything needed to understand and implement it.
-
-### Change Structure
-
-```
-openspec/changes/add-dark-mode/
-├── proposal.md           # Why and what
-├── design.md             # How (technical approach)
-├── tasks.md              # Implementation checklist
-├── .openspec.yaml        # Change metadata (optional)
-└── specs/                # Delta specs
-    └── ui/
-        └── spec.md       # What's changing in ui/spec.md
-```
-
-Each change is self-contained. It has:
- **Artifacts** — documents that capture intent, design, and tasks
- **Delta specs** — specifications for what's being added, modified, or removed
- **Metadata** — optional configuration for this specific change
-
-### Why Changes Are Folders
-
-Packaging a change as a folder has several benefits:
-
-1. **Everything together.** Proposal, design, tasks, and specs live in one place. No hunting through different locations.
-
-2. **Parallel work.** Multiple changes can exist simultaneously without conflicting. Work on `add-dark-mode` while `fix-auth-bug` is also in progress.
-
-3. **Clean history.** When archived, changes move to `changes/archive/` with their full context preserved. You can look back and understand not just what changed, but why.
-
-4. **Review-friendly.** A change folder is easy to review — open it, read the proposal, check the design, see the spec deltas.
-
-## Artifacts
-
-Artifacts are the documents within a change that guide the work.
-
-### The Artifact Flow
-
-```
-proposal ──────► specs ──────► design ──────► tasks ──────► implement
-    │               │             │              │
-   why            what           how          steps
- + scope        changes       approach      to take
-```
-
-Artifacts build on each other. Each artifact provides context for the next.
-
-### Artifact Types
-
-#### Proposal (`proposal.md`)
-
-The proposal captures **intent**, **scope**, and **approach** at a high level.
-
-```markdown
-# Proposal: Add Dark Mode
-
-## Intent
-Users have requested a dark mode option to reduce eye strain
-during nighttime usage and match system preferences.
-
-## Scope
-In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
-
-Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
-
-## Approach
-Use CSS custom properties for theming with a React context
-for state management. Detect system preference on first load,
-allow manual override.
-```
-
-**When to update the proposal:**
- Scope changes (narrowing or expanding)
- Intent clarifies (better understanding of the problem)
- Approach fundamentally shifts
-
-#### Specs (delta specs in `specs/`)
-
-Delta specs describe **what's changing** relative to the current specs. See [Delta Specs](#delta-specs) below.
-
-#### Design (`design.md`)
-
-The design captures **technical approach** and **architecture decisions**.
-
-````markdown
-# Design: Add Dark Mode
-
-## Technical Approach
-Theme state managed via React Context to avoid prop drilling.
-CSS custom properties enable runtime switching without class toggling.
-
-## Architecture Decisions
-
-### Decision: Context over Redux
-Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
-
-### Decision: CSS Custom Properties
-Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
-
-## Data Flow
-```
-ThemeProvider (context)
-       │
-       ▼
-ThemeToggle ◄──► localStorage
-       │
-       ▼
-CSS Variables (applied to :root)
-```
-
-## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)
-````
-
-**When to update the design:**
- Implementation reveals the approach won't work
- Better solution discovered
- Dependencies or constraints change
-
-#### Tasks (`tasks.md`)
-
-Tasks are the **implementation checklist** — concrete steps with checkboxes.
-
-```markdown
-# Tasks
-
-## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
-
-## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
-
-## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibility
-```
-
-**Task best practices:**
- Group related tasks under headings
- Use hierarchical numbering (1.1, 1.2, etc.)
- Keep tasks small enough to complete in one session
- Check tasks off as you complete them
-
-## Delta Specs
-
-Delta specs are the key concept that makes OpenSpec work for brownfield development. They describe **what's changing** rather than restating the entire spec.
-
-### The Format
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-
-### Requirement: Two-Factor Authentication
-The system MUST support TOTP-based two-factor authentication.
-
-#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
-
-#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
-
-## MODIFIED Requirements
-
-### Requirement: Session Expiration
-The system MUST expire sessions after 15 minutes of inactivity.
-(Previously: 30 minutes)
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
-
-## REMOVED Requirements
-
-### Requirement: Remember Me
-(Deprecated in favor of 2FA. Users should re-authenticate each session.)
-```
-
-### Delta Sections
-
-| Section | Meaning | What Happens on Archive |
-|---------|---------|------------------------|
-| `## ADDED Requirements` | New behavior | Appended to main spec |
-| `## MODIFIED Requirements` | Changed behavior | Replaces existing requirement |
-| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec |
-
-### Why Deltas Instead of Full Specs
-
-**Clarity.** A delta shows exactly what's changing. Reading a full spec, you'd have to diff it mentally against the current version.
-
-**Conflict avoidance.** Two changes can touch the same spec file without conflicting, as long as they modify different requirements.
-
-**Review efficiency.** Reviewers see the change, not the unchanged context. Focus on what matters.
-
-**Brownfield fit.** Most work modifies existing behavior. Deltas make modifications first-class, not an afterthought.
-
-## Schemas
-
-Schemas define the artifact types and their dependencies for a workflow.
-
-### How Schemas Work
-
-```yaml
-# openspec/schemas/spec-driven/schema.yaml
-name: spec-driven
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    requires: []              # No dependencies, can create first
-
-  - id: specs
-    generates: specs/**/*.md
-    requires: [proposal]      # Needs proposal before creating
-
-  - id: design
-    generates: design.md
-    requires: [proposal]      # Can create in parallel with specs
-
-  - id: tasks
-    generates: tasks.md
-    requires: [specs, design] # Needs both specs and design first
-```
-
-**Artifacts form a dependency graph:**
-
-```
-                    proposal
-                   (root node)
-                       │
-         ┌─────────────┴─────────────┐
-         │                           │
-         ▼                           ▼
-      specs                       design
-   (requires:                  (requires:
-    proposal)                   proposal)
-         │                           │
-         └─────────────┬─────────────┘
-                       │
-                       ▼
-                    tasks
-                (requires:
-                specs, design)
-```
-
-**Dependencies are enablers, not gates.** They show what's possible to create, not what you must create next. You can skip design if you don't need it. You can create specs before or after design — both depend only on proposal.
-
-### Built-in Schemas
-
-**spec-driven** (default)
-
-The standard workflow for spec-driven development:
-
-```
-proposal → specs → design → tasks → implement
-```
-
-Best for: Most feature work where you want to agree on specs before implementation.
-
-### Custom Schemas
-
-Create custom schemas for your team's workflow:
-
-```bash
-# Create from scratch
-openspec schema init research-first
-
-# Or fork an existing one
-openspec schema fork spec-driven research-first
-```
-
-**Example custom schema:**
-
-```yaml
-# openspec/schemas/research-first/schema.yaml
-name: research-first
-artifacts:
-  - id: research
-    generates: research.md
-    requires: []           # Do research first
-
-  - id: proposal
-    generates: proposal.md
-    requires: [research]   # Proposal informed by research
-
-  - id: tasks
-    generates: tasks.md
-    requires: [proposal]   # Skip specs/design, go straight to tasks
-```
-
-See [Customization](customization.md) for full details on creating and using custom schemas.
-
-## Archive
-
-Archiving completes a change by merging its delta specs into the main specs and preserving the change for history.
-
-### What Happens When You Archive
-
-```
-Before archive:
-
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md ◄────────────────┐
-└── changes/                         │
-    └── add-2fa/                     │
-        ├── proposal.md              │
-        ├── design.md                │ merge
-        ├── tasks.md                 │
-        └── specs/                   │
-            └── auth/                │
-                └── spec.md ─────────┘
-
-
-After archive:
-
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md        # Now includes 2FA requirements
-└── changes/
-    └── archive/
-        └── 2025-01-24-add-2fa/    # Preserved for history
-            ├── proposal.md
-            ├── design.md
-            ├── tasks.md
-            └── specs/
-                └── auth/
-                    └── spec.md
-```
-
-### The Archive Process
-
-1. **Merge deltas.** Each delta spec section (ADDED/MODIFIED/REMOVED) is applied to the corresponding main spec.
-
-2. **Move to archive.** The change folder moves to `changes/archive/` with a date prefix for chronological ordering.
-
-3. **Preserve context.** All artifacts remain intact in the archive. You can always look back to understand why a change was made.
-
-### Why Archive Matters
-
-**Clean state.** Active changes (`changes/`) shows only work in progress. Completed work moves out of the way.
-
-**Audit trail.** The archive preserves the full context of every change — not just what changed, but the proposal explaining why, the design explaining how, and the tasks showing the work done.
-
-**Spec evolution.** Specs grow organically as changes are archived. Each archive merges its deltas, building up a comprehensive specification over time.
-
-## How It All Fits Together
-
-```
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                              OPENSPEC FLOW                                   │
-│                                                                              │
-│   ┌────────────────┐                                                         │
-│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
-│   │     CHANGE     │                                                         │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
-│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
-│   │                │  (based on schema dependencies)                         │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  3. IMPLEMENT  │  /opsx:apply                                            │
-│   │     TASKS      │  Work through tasks, checking them off                  │
-│   │                │◄──── Update artifacts as you learn                      │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  4. VERIFY     │  /opsx:verify (optional)                                │
-│   │     WORK       │  Check implementation matches specs                     │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
-│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
-│   │     CHANGE     │     │  Change folder moves to archive/             │    │
-│   └────────────────┘     │  Specs are now the updated source of truth   │    │
-│                          └──────────────────────────────────────────────┘    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
-
-**The virtuous cycle:**
-
-1. Specs describe current behavior
-2. Changes propose modifications (as deltas)
-3. Implementation makes the changes real
-4. Archive merges deltas into specs
-5. Specs now describe the new behavior
-6. Next change builds on updated specs
-
-## Glossary
-
-| Term | Definition |
-|------|------------|
-| **Artifact** | A document within a change (proposal, design, tasks, or delta specs) |
-| **Archive** | The process of completing a change and merging its deltas into main specs |
-| **Change** | A proposed modification to the system, packaged as a folder with artifacts |
-| **Delta spec** | A spec that describes changes (ADDED/MODIFIED/REMOVED) relative to current specs |
-| **Domain** | A logical grouping for specs (e.g., `auth/`, `payments/`) |
-| **Requirement** | A specific behavior the system must have |
-| **Scenario** | A concrete example of a requirement, typically in Given/When/Then format |
-| **Schema** | A definition of artifact types and their dependencies |
-| **Spec** | A specification describing system behavior, containing requirements and scenarios |
-| **Source of truth** | The `openspec/specs/` directory, containing the current agreed-upon behavior |
-
-## Next Steps
-
- [Getting Started](getting-started.md) - Practical first steps
- [Workflows](workflows.md) - Common patterns and when to use each
- [Commands](commands.md) - Full command reference
- [Customization](customization.md) - Create custom schemas and configure your project
@@ -1,356 +0,0 @@
-# Customization
-
-OpenSpec provides three levels of customization:
-
-| Level | What it does | Best for |
-|-------|--------------|----------|
-| **Project Config** | Set defaults, inject context/rules | Most teams |
-| **Custom Schemas** | Define your own workflow artifacts | Teams with unique processes |
-| **Global Overrides** | Share schemas across all projects | Power users |
-
---
-
-## Project Configuration
-
-The `openspec/config.yaml` file is the easiest way to customize OpenSpec for your team. It lets you:
-
- **Set a default schema** - Skip `--schema` on every command
- **Inject project context** - AI sees your tech stack, conventions, etc.
- **Add per-artifact rules** - Custom rules for specific artifacts
-
-### Quick Setup
-
-```bash
-openspec init
-```
-
-This walks you through creating a config interactively. Or create one manually:
-
-```yaml
-# openspec/config.yaml
-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
-  specs:
-    - Use Given/When/Then format
-    - Reference existing patterns before inventing new ones
-```
-
-### How It Works
-
-**Default schema:**
-
-```bash
-# Without config
-openspec new change my-feature --schema spec-driven
-
-# With config - schema is automatic
-openspec new change my-feature
-```
-
-**Context and rules injection:**
-
-When generating any artifact, your context and rules are injected into the AI prompt:
-
-```xml
-<context>
-Tech stack: TypeScript, React, Node.js, PostgreSQL
-...
-</context>
-
-<rules>
- Include rollback plan
- Identify affected teams
-</rules>
-
-<template>
-[Schema's built-in template]
-</template>
-```
-
- **Context** appears in ALL artifacts
- **Rules** ONLY appear for the matching artifact
-
-### Schema Resolution Order
-
-When OpenSpec needs a schema, it checks in this order:
-
-1. CLI flag: `--schema <name>`
-2. Change metadata (`.openspec.yaml` in the change folder)
-3. Project config (`openspec/config.yaml`)
-4. Default (`spec-driven`)
-
---
-
-## Custom Schemas
-
-When project config isn't enough, create your own schema with a completely custom workflow. Custom schemas live in your project's `openspec/schemas/` directory and are version-controlled with your code.
-
-```text
-your-project/
-├── openspec/
-│   ├── config.yaml        # Project config
-│   ├── schemas/           # Custom schemas live here
-│   │   └── my-workflow/
-│   │       ├── schema.yaml
-│   │       └── templates/
-│   └── changes/           # Your changes
-└── src/
-```
-
-### Fork an Existing Schema
-
-The fastest way to customize is to fork a built-in schema:
-
-```bash
-openspec schema fork spec-driven my-workflow
-```
-
-This copies the entire `spec-driven` schema to `openspec/schemas/my-workflow/` where you can edit it freely.
-
-**What you get:**
-
-```text
-openspec/schemas/my-workflow/
-├── schema.yaml           # Workflow definition
-└── templates/
-    ├── proposal.md       # Template for proposal artifact
-    ├── spec.md           # Template for specs
-    ├── design.md         # Template for design
-    └── tasks.md          # Template for tasks
-```
-
-Now edit `schema.yaml` to change the workflow, or edit templates to change what AI generates.
-
-### Create a Schema from Scratch
-
-For a completely fresh workflow:
-
-```bash
-# Interactive
-openspec schema init research-first
-
-# Non-interactive
-openspec schema init rapid \
-  --description "Rapid iteration workflow" \
-  --artifacts "proposal,tasks" \
-  --default
-```
-
-### Schema Structure
-
-A schema defines the artifacts in your workflow and how they depend on each other:
-
-```yaml
-# openspec/schemas/my-workflow/schema.yaml
-name: my-workflow
-version: 1
-description: My team's custom workflow
-
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Initial proposal document
-    template: proposal.md
-    instruction: |
-      Create a proposal that explains WHY this change is needed.
-      Focus on the problem, not the solution.
-    requires: []
-
-  - id: design
-    generates: design.md
-    description: Technical design
-    template: design.md
-    instruction: |
-      Create a design document explaining HOW to implement.
-    requires:
-      - proposal    # Can't create design until proposal exists
-
-  - id: tasks
-    generates: tasks.md
-    description: Implementation checklist
-    template: tasks.md
-    requires:
-      - design
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-```
-
-**Key fields:**
-
-| Field | Purpose |
-|-------|---------|
-| `id` | Unique identifier, used in commands and rules |
-| `generates` | Output filename (supports globs like `specs/**/*.md`) |
-| `template` | Template file in `templates/` directory |
-| `instruction` | AI instructions for creating this artifact |
-| `requires` | Dependencies - which artifacts must exist first |
-
-### Templates
-
-Templates are markdown files that guide the AI. They're injected into the prompt when creating that artifact.
-
-```markdown
-<!-- templates/proposal.md -->
-## Why
-
-<!-- Explain the motivation for this change. What problem does this solve? -->
-
-## What Changes
-
-<!-- Describe what will change. Be specific about new capabilities or modifications. -->
-
-## Impact
-
-<!-- Affected code, APIs, dependencies, systems -->
-```
-
-Templates can include:
- Section headers the AI should fill in
- HTML comments with guidance for the AI
- Example formats showing expected structure
-
-### Validate Your Schema
-
-Before using a custom schema, validate it:
-
-```bash
-openspec schema validate my-workflow
-```
-
-This checks:
- `schema.yaml` syntax is correct
- All referenced templates exist
- No circular dependencies
- Artifact IDs are valid
-
-### Use Your Custom Schema
-
-Once created, use your schema with:
-
-```bash
-# Specify on command
-openspec new change feature --schema my-workflow
-
-# Or set as default in config.yaml
-schema: my-workflow
-```
-
-### Debug Schema Resolution
-
-Not sure which schema is being used? Check with:
-
-```bash
-# See where a specific schema resolves from
-openspec schema which my-workflow
-
-# List all available schemas
-openspec schema which --all
-```
-
-Output shows whether it's from your project, user directory, or the package:
-
-```text
-Schema: my-workflow
-Source: project
-Path: /path/to/project/openspec/schemas/my-workflow
-```
-
---
-
-> **Note:** OpenSpec also supports user-level schemas at `~/.local/share/openspec/schemas/` for sharing across projects, but project-level schemas in `openspec/schemas/` are recommended since they're version-controlled with your code.
-
---
-
-## Examples
-
-### Rapid Iteration Workflow
-
-A minimal workflow for quick iterations:
-
-```yaml
-# openspec/schemas/rapid/schema.yaml
-name: rapid
-version: 1
-description: Fast iteration with minimal overhead
-
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Quick proposal
-    template: proposal.md
-    instruction: |
-      Create a brief proposal for this change.
-      Focus on what and why, skip detailed specs.
-    requires: []
-
-  - id: tasks
-    generates: tasks.md
-    description: Implementation checklist
-    template: tasks.md
-    requires: [proposal]
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-```
-
-### Adding a Review Artifact
-
-Fork the default and add a review step:
-
-```bash
-openspec schema fork spec-driven with-review
-```
-
-Then edit `schema.yaml` to add:
-
-```yaml
-  - id: review
-    generates: review.md
-    description: Pre-implementation review checklist
-    template: review.md
-    instruction: |
-      Create a review checklist based on the design.
-      Include security, performance, and testing considerations.
-    requires:
-      - design
-
-  - id: tasks
-    # ... existing tasks config ...
-    requires:
-      - specs
-      - design
-      - review    # Now tasks require review too
-```
-
---
-
-## Community Schemas
-
-OpenSpec also supports community-maintained schemas distributed via standalone repositories. These provide opinionated workflows that integrate OpenSpec with other tools or systems, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) works for spec-kit.
-
-Community schemas are not vendored into OpenSpec core — they live in their own repositories with their own release cadence. To use one, copy the schema bundle into your project's `openspec/schemas/<schema-name>/` directory (each repo's README has install instructions).
-
-| Schema | Maintainer | Repository | Description |
-|--------|-----------|-----------|-------------|
-| `superpowers-bridge` | @JiangWay | [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) | Integrates OpenSpec's artifact governance with [obra/superpowers](https://github.com/obra/superpowers) execution skills (brainstorming, writing-plans, TDD via subagents, code review, finishing). Adds an evidence-first `retrospective` artifact filling a gap Superpowers does not natively cover. |
-
-> Want to contribute a community schema? Open an issue with a link to your repository, or submit a PR adding a row to this table.
-
---
-
-## See Also
-
- [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation
@@ -1,90 +0,0 @@
-# Editing & Iterating on a Change
-
-**Every artifact in a change is just a Markdown file you can edit at any time.** There is no locked "planning phase," no approval gate, no special edit mode to enter. Want to change the proposal after you've started building? Open `proposal.md` and change it. Realized the design is wrong mid-implementation? Fix `design.md` and keep going. That's the whole answer, and it's by design.
-
-This page is for the moment you think "wait, can I go back and change that?" Yes. Here's how, for each common case.
-
-## Two ways to edit anything
-
-You always have both:
-
-1. **Edit the file directly.** Artifacts are plain Markdown in `openspec/changes/<name>/`. Open `proposal.md`, `design.md`, `tasks.md`, or a delta spec under `specs/` in your editor and change it. Nothing else is required.
-
-2. **Ask your AI to revise it.** In chat, just say what you want: "Update the proposal to drop the caching idea and add a rate-limit section," or "the design should use a queue, not polling." The AI edits the artifact for you, using the rest of the change as context.
-
-Use whichever fits the moment. Small wording tweak? Edit the file. Substantive rethink? Let the AI revise with full context.
-
-## "How do I update the proposal (or specs) after I've started?"
-
-Just update it. Same change, refined.
-
-If you're using the expanded commands, the natural flow is: edit the artifact, then run `/opsx:continue` to pick up from the new state, or `/opsx:apply` to keep implementing against the updated plan. If you're on the default `core` commands, edit the artifact and run `/opsx:apply`; it reads the current files, so it builds against whatever the artifacts now say.
-
-The mental model: artifacts are the live plan, not a signed contract. The AI always works from their current contents, so editing them steers the work.
-
-```text
-You: I want to change the approach in this change.
-
-You: [edit design.md, or tell the AI:]
-     Update design.md to use a background job instead of a synchronous call.
-
-AI:  Updated design.md. The task list still fits; want me to continue applying?
-
-You: /opsx:apply
-```
-
-This answers a very common question: there's no separate "update proposal" command because you don't need one. The file is the source of truth, and editing it (by hand or via the AI) is the update.
-
-## "How do I go back to review after implementing?"
-
-You don't have to "go back," because you never left. The workflow is fluid: review, edit, and implementation aren't sequential phases you're trapped in.
-
-Concretely, after some `/opsx:apply` work:
-
- Want to re-examine the plan? Open the artifacts and read them, or run `openspec show <change>` in your terminal for a consolidated view.
- Found something to change? Edit the artifact (or ask the AI to), then continue.
- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
-
-There's no "review phase" to return to, because review is something you can do at any point, including after implementation.
-
-## "I edited the code by hand. How do I reconcile that with OpenSpec?"
-
-This happens constantly and it's fine. You tweaked something in your editor, and now the code and the artifacts disagree. Bring them back in sync in whichever direction is true:
-
- **The code is now correct, the spec is stale.** Update the delta spec (and tasks, if relevant) to describe the behavior you actually shipped. The spec should match reality before you archive, because archiving merges the spec into your source of truth.
- **The spec is correct, the code drifted.** Keep building or fixing until the code matches the spec.
-
-A fast way to surface mismatches is `/opsx:verify`: it reads your artifacts and your code and tells you where they diverge. Treat its output as a to-do list for reconciliation, then archive once they agree.
-
-The principle: at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does. Manual edits are welcome; just don't let them quietly desync the spec.
-
-## Refining a proposal you're not happy with
-
-If a generated proposal misses the mark, you have three good moves:
-
- **Iterate in place.** Tell the AI what's off ("the scope is too broad, drop the admin features") and let it revise. Cheapest and usually right.
- **Explore first, then re-propose.** If the problem is that the idea itself is unclear, step back to `/opsx:explore`, think it through, and let a sharper proposal come out of that. See [Explore First](explore.md).
- **Start fresh.** If the intent has fundamentally changed, a new change can be clearer than patching the old one.
-
-That last move has its own decision guide, next.
-
-## When to update vs. start a new change
-
-Short version: **update when it's the same work refined; start new when the intent fundamentally changed or the scope exploded into different work.**
-
- Same goal, better approach? Update.
- Scope narrowing (ship the MVP now, more later)? Update, then archive, then a new change for phase two.
- The problem itself changed ("add dark mode" became "build a full theming system")? New change.
-
-There's a full flowchart and worked examples in [Workflows: When to Update vs Start Fresh](workflows.md#when-to-update-vs-start-fresh) and a deeper treatment in [OPSX: When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh).
-
-## A note on tasks
-
-`tasks.md` is a living checklist, not a frozen plan. As you implement, you can add tasks you discover, remove ones that turned out unnecessary, or reorder them. The AI checks items off as it completes them during `/opsx:apply`, and it resumes from the first unchecked task if you come back later. Editing the list mid-flight is expected.
-
-## Where to go next
-
- [Workflows](workflows.md) - patterns, plus the update-vs-new decision guide
- [Explore First](explore.md) - the place to step back to when an idea needs rethinking
- [Commands](commands.md) - `/opsx:continue`, `/opsx:apply`, and `/opsx:verify` in detail
- [Concepts: Artifacts](concepts.md#artifacts) - what each artifact is for
@@ -1,215 +0,0 @@
-# Examples & Recipes
-
-Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `sync`, `archive`); where the expanded set helps, it's noted.
-
-A reminder before you start: slash commands like `/opsx:propose` go in your **AI assistant's chat**, and `openspec` commands go in your **terminal**. If that's new, read [How Commands Work](how-commands-work.md) first. In the transcripts below, `You:` and `AI:` are the chat, and lines starting with `$` are the terminal.
-
-> **Not sure what you're building yet?** Most of these recipes are sharper if you start with `/opsx:explore` to think it through first. [Recipe 3](#recipe-3-exploring-before-you-commit) shows it in action, and the [Explore First](explore.md) guide makes the full case.
-
-## Recipe 1: A small feature, the fast path
-
-**When to use it:** you know what you want, and it's a contained piece of work. This is the most common recipe.
-
-The whole thing is three commands. Propose, build, archive.
-
-```text
-You: /opsx:propose add-logout-button
-
-AI:  Created openspec/changes/add-logout-button/
-     ✓ proposal.md — why and what
-     ✓ specs/      — the new requirement and its scenarios
-     ✓ design.md   — technical approach
-     ✓ tasks.md    — implementation checklist
-     Ready for implementation. Run /opsx:apply.
-```
-
-Now read the plan. Open the proposal and the delta spec. This is the moment OpenSpec is built for: catching a wrong assumption while it's still one paragraph, not 400 lines of code. Edit any artifact directly if something's off, then continue.
-
-```text
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ 1.1 Add logout button to header
-     ✓ 1.2 Clear session on click
-     ✓ 1.3 Add confirmation dialog
-     All tasks complete!
-
-You: /opsx:archive
-
-AI:  Archiving add-logout-button...
-     ✓ Merged specs into openspec/specs/auth/spec.md
-     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
-     Done. Ready for the next change.
-```
-
-That's it. The logout behavior is now part of your specs, and the change is filed away with its full context.
-
-## Recipe 2: A bug fix
-
-**When to use it:** something is broken and you want the fix recorded as a deliberate change to behavior, not a mystery commit.
-
-Bug fixes work exactly like features. The difference is in how you frame the proposal: describe the *correct* behavior, not just "fix the bug."
-
-```text
-You: /opsx:propose fix-login-redirect-loop
-
-AI:  Created openspec/changes/fix-login-redirect-loop/
-     The proposal captures the current broken behavior and the
-     intended behavior. The delta spec MODIFIES the redirect
-     requirement so it's now precise and testable.
-     Ready for implementation.
-```
-
-Because the fix lands as a `MODIFIED` requirement with a fresh scenario, the next person (or the next AI session) sees not just that you fixed it, but what "correct" means. Then `/opsx:apply` and `/opsx:archive` as usual.
-
-Tip: for a fix, a good scenario is the regression test in prose. "GIVEN a logged-out user, WHEN they submit valid credentials, THEN they land on the dashboard and are not redirected again." Write that, and the implementation has a clear target.
-
-## Recipe 3: Exploring before you commit
-
-**When to use it:** you have a problem but not yet a plan. You're not sure what to build, or which approach is right.
-
-Start with `/opsx:explore`. It's a thinking partner with no structure and no artifacts created. It reads your codebase and helps you decide.
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: Page loads feel slow but I don't know where the time goes.
-
-AI:  Let me look... I found three likely culprits:
-     1. Large unoptimized images on the product list
-     2. Synchronous data fetching that blocks render
-     3. Re-renders triggered by context changes
-     Which should we tackle first?
-
-You: The data fetching one.
-
-You: /opsx:propose optimize-product-list-fetching
-
-AI:  Created the change, with a proposal informed by what we just
-     found. Ready for implementation.
-```
-
-Exploration clarifies your thinking *before* you spend a change on it. When the insight crystallizes, propose, and the AI carries the context forward.
-
-## Recipe 4: Juggling two changes at once
-
-**When to use it:** you're mid-feature and an urgent fix jumps the queue.
-
-Changes are independent folders, so parallel work doesn't conflict. Start the fix, ship it, then return to the feature right where you left off.
-
-```text
-You: I'm partway through add-dark-mode, but I need to fix a login bug now.
-
-You: /opsx:propose fix-login-redirect
-
-AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.
-
-You: /opsx:apply
-
-AI:  Implemented the fix. All tasks complete.
-
-You: /opsx:archive
-
-AI:  ✓ Archived fix-login-redirect.
-
-You: Back to dark mode.
-
-You: /opsx:apply add-dark-mode
-
-AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...
-```
-
-Naming the change in `/opsx:apply add-dark-mode` is how you point the AI at a specific change when more than one is active. Because tasks track completion in `tasks.md`, the AI knows exactly where you stopped.
-
-When several changes are done at once, the expanded `/opsx:bulk-archive` files them together and resolves spec conflicts by checking what's actually implemented. See [Workflows](workflows.md#parallel-changes).
-
-## Recipe 5: A refactor with no behavior change
-
-**When to use it:** you're restructuring code, and externally visible behavior should stay identical.
-
-This is the interesting case, because a pure refactor has *nothing to add to your specs*. The behavior contract doesn't change; only the implementation does. So the work lives in the design and tasks, and the spec delta is empty or absent.
-
-```text
-You: /opsx:propose refactor-payment-module
-
-AI:  Created the change. The proposal states the goal (split the
-     payment module, no behavior change) and the design captures
-     the new structure. No spec changes, since behavior is identical.
-     Ready for implementation.
-```
-
-When you archive a change that doesn't touch specs, you can tell the terminal command to skip the spec step:
-
-```bash
-$ openspec archive refactor-payment-module --skip-specs
-```
-
-The same flag is handy for tooling, CI, and docs-only changes. The principle: specs describe behavior, so if behavior didn't change, the spec shouldn't either. See [Concepts](concepts.md#what-a-spec-is-and-is-not).
-
-## Recipe 6: Step-by-step control (expanded commands)
-
-**When to use it:** a complex or risky change where you want to review each artifact before moving on.
-
-The core `/opsx:propose` drafts everything at once. When you'd rather go one step at a time, turn on the expanded commands:
-
-```bash
-$ openspec config profile      # select the expanded workflows
-$ openspec update              # apply them to this project
-```
-
-Now you can scaffold and build incrementally:
-
-```text
-You: /opsx:new add-2fa
-
-AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.
-
-You: /opsx:continue
-
-AI:  Created proposal.md. Now available: specs, design.
-
-You: /opsx:continue
-
-AI:  Created specs/auth/spec.md. Now available: design.
-```
-
-Review each artifact as it lands, edit freely, and continue when you're happy. When you want the rest drafted in one go, `/opsx:ff` fast-forwards through the remaining planning artifacts. Before archiving, `/opsx:verify` checks that the implementation actually matches the specs. See [Workflows](workflows.md#opsxff-vs-opsxcontinue).
-
-## Recipe 7: Learning the whole loop hands-on
-
-**When to use it:** you've installed OpenSpec and want to *feel* the workflow on your own code, not a toy example.
-
-Turn on the expanded commands (see Recipe 6), then:
-
-```text
-You: /opsx:onboard
-
-AI:  Welcome to OpenSpec! I'll walk you through a complete change
-     using your actual codebase. Let me scan for a small, safe
-     improvement we can make together...
-```
-
-`/opsx:onboard` finds a real (small) improvement, creates a change for it, implements it, and archives it, narrating every step. It takes 15 to 30 minutes and leaves you with a real change you can keep or discard. It's the gentlest way to learn. See [Commands](commands.md#opsxonboard).
-
-## Checking your work from the terminal
-
-Any time, from your terminal, you can inspect the state of things:
-
-```bash
-$ openspec list                      # active changes
-$ openspec show add-dark-mode        # one change in detail
-$ openspec validate add-dark-mode    # check structure
-$ openspec view                      # interactive dashboard
-```
-
-These are read-and-inspect tools. The proposing and building still happen through slash commands in chat. Full details in the [CLI reference](cli.md).
-
-## Where to go next
-
- [Explore First](explore.md): the recommended way to start when you're unsure
- [Workflows](workflows.md): the patterns above, with decision guidance on when to use each
- [Commands](commands.md): every slash command in detail
- [Getting Started](getting-started.md): the canonical first-change walkthrough
- [Concepts](concepts.md): why the pieces fit together the way they do
@@ -1,134 +0,0 @@
-# Using OpenSpec in an Existing Project
-
-**You do not document your whole codebase to start. You write specs only for what you're about to change.** That's the single most important thing to know about adopting OpenSpec on an existing project, and it's why OpenSpec is built brownfield-first.
-
-A common worry sounds like this: "My app is 80,000 lines old. Do I have to write specs for all of it before OpenSpec is useful?" No. You'd hate that, and so would we. OpenSpec grows your specs one change at a time. Your first change documents the slice it touches, the next change documents its slice, and over months your specs fill in naturally around the work you actually do.
-
-This guide shows how to start on day one without boiling the ocean.
-
-## The thirty-second version
-
-```bash
-$ cd your-existing-project
-$ openspec init          # adds openspec/ and your AI tool's commands
-```
-
-Then, in your AI chat:
-
-```text
-/opsx:explore            # optional: have the AI read the area you'll touch
-/opsx:propose <a real, small change you actually need>
-/opsx:apply
-/opsx:archive
-```
-
-Your specs now describe exactly the part of the system that change touched, and nothing more. That's correct. You're done worrying about the other 80,000 lines.
-
-## Why delta-first is the whole trick
-
-OpenSpec changes are written as **deltas**: `ADDED`, `MODIFIED`, `REMOVED`. A delta describes what's changing relative to current behavior, not the entire system.
-
-This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.
-
-So your `openspec/specs/` directory doesn't start full and complete. It starts nearly empty and accumulates. Each archived change merges its delta in. The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough.
-
-If you want the deeper mechanics, see [Concepts: Delta Specs](concepts.md#delta-specs).
-
-## Your first change on a real codebase
-
-Pick something small and real. Not a toy, not a rewrite. A change you were going to make this week anyway. Small first changes teach you the workflow with low stakes.
-
-**Step 1: Let the AI read the relevant area.** This is where `/opsx:explore` earns its keep on an unfamiliar or large codebase. Point it at the part you're about to touch and let it map how things work before proposing anything.
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: I need to add rate limiting to our public API, but I'm not sure
-     how requests currently flow through the middleware.
-
-AI:  Let me trace it... [reads the router, middleware stack, and config]
-     Requests hit Express, pass through auth middleware, then your
-     controllers. There's no rate-limiting layer today. The cleanest
-     insertion point is a middleware right after auth. Want me to scope it?
-```
-
-Notice the AI now understands your actual structure, so the proposal it writes will fit your code, not a generic template. On a big codebase, this single habit saves the most pain. See [Explore First](explore.md).
-
-**Step 2: Propose the change.** The proposal and its delta spec capture just this change.
-
-```text
-You: /opsx:propose add-api-rate-limiting
-```
-
-**Step 3: Build and archive** with `/opsx:apply` and `/opsx:archive`, same as any change. After archiving, you have a real spec for your rate-limiting behavior, born from a change you needed anyway.
-
-## Prefer a guided tour? Use onboard
-
-If you'd rather watch the whole loop happen on your own code with narration, the expanded command `/opsx:onboard` does exactly that: it scans your codebase for a small, safe improvement, then walks you through proposing, building, and archiving it, explaining each step.
-
-Turn on the expanded commands first:
-
-```bash
-$ openspec config profile      # select the expanded workflows
-$ openspec update              # apply them to this project
-```
-
-Then in chat:
-
-```text
-/opsx:onboard
-```
-
-It's the gentlest possible introduction on a real project, and it leaves you with a genuine (small) change you can keep or discard. See [Commands: `/opsx:onboard`](commands.md#opsxonboard).
-
-## "But I already have requirements docs"
-
-Maybe you have a PRD, an SRS, a formal spec, even TLA+ models. Good. You don't import them wholesale, and you don't throw them away either.
-
-Treat existing docs as **source material for exploration**, not as specs to convert. When you start a change, paste or point the AI at the relevant section, and let it shape a focused OpenSpec delta from it. The delta captures the behavior you're changing now, in OpenSpec's testable requirement-and-scenario form. Your original documents stay where they are as background.
-
-The honest reason: OpenSpec specs are deliberately behavior-first and scoped to changes. A 40-page PRD is a different artifact with a different job. Forcing a one-time bulk conversion tends to produce a large, stale spec nobody trusts. Letting specs grow from real changes keeps them accurate.
-
-```text
-You: /opsx:explore
-You: Here's the section of our PRD about checkout. I'm implementing the
-     "guest checkout" requirement next.
-     [paste the relevant requirement]
-AI:  [reads it, asks clarifying questions, then helps scope a change]
-You: /opsx:propose add-guest-checkout
-```
-
-## Organizing specs in a big codebase
-
-Specs live under `openspec/specs/`, grouped by **domain**: a logical area that matches how your team thinks about the system. You don't have to design the whole taxonomy up front. Create a domain folder when your first change in that area needs one.
-
-Common ways to slice domains:
-
- **By feature area:** `auth/`, `payments/`, `search/`
- **By component:** `api/`, `frontend/`, `workers/`
- **By bounded context:** `ordering/`, `fulfillment/`, `inventory/`
-
-Pick whatever makes a newcomer nod. You can refine later. See [Concepts: Specs](concepts.md#specs).
-
-## Monorepos and work that spans repos
-
-For a monorepo, the simplest model is one `openspec/` directory at the repo root, with domains that map to your packages or services. That covers most teams.
-
-If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **stores** feature: planning lives in its own standalone repo that any of your code repos can reference, so the plan does not have to live inside one repo's `openspec/` folder. It's beta, so treat its commands and state as evolving. Start with the [Stores User Guide](stores-beta/user-guide.md) for the mental model and the smallest useful path.
-
-## A few honest cautions
-
- **Resist the urge to back-fill everything.** Writing specs for code you aren't changing feels productive and usually isn't. Those specs go stale, because nothing forces them to track reality. Let real changes drive your specs.
- **Keep early changes small.** Your first few changes are as much about learning the rhythm as shipping. A tight scope makes the loop fast and the lessons cheap.
- **Commit `openspec/` to git.** Your specs and archive belong in version control alongside the code they describe.
- **Give the AI context.** On a large codebase with strong conventions, fill in `openspec/config.yaml`'s `context:` so every proposal respects your stack and patterns. See [Customization](customization.md#project-configuration).
-
-## Where to go next
-
- [Explore First](explore.md) - the key habit for understanding code before you change it
- [Getting Started](getting-started.md) - the full first-change walkthrough
- [Editing & Iterating on a Change](editing-changes.md) - adjusting a change as you learn
- [Concepts: Delta Specs](concepts.md#delta-specs) - why deltas make brownfield work clean
- [Customization](customization.md) - teach OpenSpec your project's conventions
@@ -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
@@ -1,16 +1,16 @@
-# OPSX Workflow
+# Experimental Workflow (OPSX)

-> Feedback welcome on [Discord](https://discord.gg/YctCnvvshC).
+> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/BYjPaKbqMt).
+>
+> **Compatibility:** Claude Code only (for now)

 ## What Is It?

-OPSX is now the standard workflow for OpenSpec.
-
-It's a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
+OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.

 ## Why This Exists

-The legacy OpenSpec workflow works, but it's **locked down**:
+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
@@ -25,7 +25,7 @@ The legacy OpenSpec workflow works, but it's **locked down**:
 4. **Iterate quickly** — change a template, test immediately, no rebuild

 ```
-Legacy workflow:                      OPSX:
+Standard workflow:                    OPSX:
 ┌────────────────────────┐           ┌────────────────────────┐
 │  Hardcoded in package  │           │  schema.yaml           │◄── You edit this
 │  (can't change)        │           │  templates/*.md        │◄── Or this
@@ -51,21 +51,32 @@ You're "in planning phase", then "in implementation phase", then "done". But rea
 **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
-# Make sure you have openspec installed — skills are automatically generated
+# 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/` (or equivalent) that AI coding assistants auto-detect.
-
-By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`.
+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.

@@ -75,7 +86,7 @@ Project config lets you set defaults and inject project-specific context into al

 ### Creating Config

-Config is created during `openspec init`, or manually:
+Config is created during `artifact-experimental-setup`, or manually:

 ```yaml
 # openspec/config.yaml
@@ -101,14 +112,14 @@ rules:

 | Field | Type | Description |
 |-------|------|-------------|
-| `schema` | string | Default schema for new changes (e.g., `spec-driven`) |
+| `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 <name>`)
+1. CLI flag (`--schema tdd`)
 2. Change metadata (`.openspec.yaml` in change directory)
 3. Project config (`openspec/config.yaml`)
 4. Default (`spec-driven`)
@@ -131,6 +142,12 @@ rules:
 - `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
@@ -157,17 +174,13 @@ rules:

 | Command | What it does |
 |---------|--------------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step (default quick path) |
 | `/opsx:explore` | Think through ideas, investigate problems, clarify requirements |
-| `/opsx:new` | Start a new change scaffold (expanded workflow) |
-| `/opsx:continue` | Create the next artifact (expanded workflow) |
-| `/opsx:ff` | Fast-forward planning artifacts (expanded workflow) |
+| `/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:verify` | Validate implementation against artifacts (expanded workflow) |
-| `/opsx:sync` | Sync delta specs to main (default workflow, optional) |
+| `/opsx:sync` | Sync delta specs to main specs |
 | `/opsx:archive` | Archive when done |
-| `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) |
-| `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) |

 ## Usage

@@ -175,21 +188,13 @@ rules:
 ```
 /opsx:explore
 ```
-Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:propose` (default) or `/opsx:new`/`/opsx:ff` (expanded).
+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:propose
-```
-Creates the change and generates planning artifacts needed before implementation.
-
-If you've enabled expanded workflows, you can instead use:
-
-```text
-/opsx:new        # scaffold only
-/opsx:continue   # create one artifact at a time
-/opsx:ff         # create all planning artifacts at once
+/opsx:new
 ```
+You'll be asked what you want to build and which workflow schema to use.

 ### Create artifacts
 ```
@@ -206,16 +211,17 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 /opsx:apply
 ```
-Works through tasks, checking them off as you go. 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.
+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:archive   # Move to archive when done (prompts to sync specs if needed)
+/opsx:sync      # Update main specs with your delta specs
+/opsx:archive   # Move to archive when done
 ```

 ## When to Update vs. Start Fresh

-You can always edit your proposal or specs before implementation. But when does refining become "this is different work"?
+OPSX lets you update artifacts anytime. But when does "update as you learn" become "this is different work"?

 ### What a Proposal Captures

@@ -301,7 +307,7 @@ Think of it like git branches:

 ## What's Different?

-| | Legacy (`/openspec:proposal`) | OPSX (`/opsx:*`) |
+| | 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 |
@@ -312,14 +318,13 @@ Think of it like git branches:

 ## Architecture Deep Dive

-This section explains how OPSX works under the hood and how it compares to the legacy workflow.
-Examples in this section use the expanded command set (`new`, `continue`, etc.); default `core` users can map the same flow to `propose → apply → sync → archive`.
+This section explains how OPSX works under the hood and how it compares to the standard workflow.

 ### Philosophy: Phases vs Actions

 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                         LEGACY WORKFLOW                                      │
+│                         STANDARD WORKFLOW                                    │
 │                    (Phase-Locked, All-or-Nothing)                           │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                             │
@@ -346,9 +351,9 @@ Examples in this section use the expanded command set (`new`, `continue`, etc.);
 │              ┌────────────────────────────────────────────┐                 │
 │              │           ACTIONS (not phases)             │                 │
 │              │                                            │                 │
-│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
-│              │    │          │           │           │    │                 │
-│              │    └──────────┴───────────┴───────────┘    │                 │
+│              │   new ◄──► continue ◄──► apply ◄──► sync   │                 │
+│              │    │          │           │          │     │                 │
+│              │    └──────────┴───────────┴──────────┘     │                 │
 │              │              any order                     │                 │
 │              └────────────────────────────────────────────┘                 │
 │                                                                             │
@@ -361,17 +366,17 @@ Examples in this section use the expanded command set (`new`, `continue`, etc.);

 ### Component Architecture

-**Legacy workflow** uses hardcoded templates in TypeScript:
+**Standard workflow** uses hardcoded templates in TypeScript:

 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                      LEGACY WORKFLOW COMPONENTS                              │
+│                      STANDARD WORKFLOW COMPONENTS                            │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                             │
 │   Hardcoded Templates (TypeScript strings)                                  │
 │                    │                                                        │
 │                    ▼                                                        │
-│   Tool-specific configurators/adapters                                      │
+│   Configurators (18+ classes, one per editor)                               │
 │                    │                                                        │
 │                    ▼                                                        │
 │   Generated Command Files (.claude/commands/openspec/*.md)                  │
@@ -460,7 +465,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no

 ### Information Flow

-**Legacy workflow** — agent receives static instructions:
+**Standard workflow** — agent receives static instructions:

 ```
  User: "/openspec:proposal"
@@ -471,7 +476,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
  │  • Create proposal.md                   │
  │  • Create tasks.md                      │
  │  • Create design.md                     │
-  │  • Create specs/<capability>/spec.md    │
+  │  • Create specs/*.md                    │
  │                                         │
  │  No awareness of what exists or         │
  │  dependencies between artifacts         │
@@ -519,7 +524,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no

 ### Iteration Model

-**Legacy workflow** — awkward to iterate:
+**Standard workflow** — awkward to iterate:

 ```
  ┌─────────┐     ┌─────────┐     ┌─────────┐
@@ -612,20 +617,21 @@ artifacts:

 ### Summary

-| Aspect | Legacy | OPSX |
+| 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** | Tool-specific configurator/adapters | Single skills directory |
+| **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
@@ -656,4 +662,4 @@ openspec schema validate my-workflow

 This is rough. That's intentional — we're learning what works.

-Found a bug? Have ideas? Join us on [Discord](https://discord.gg/YctCnvvshC) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).
+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).
@@ -1,121 +0,0 @@
-# Explore First
-
-**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a single artifact or line of code is created. When the picture is clear, it hands off to `/opsx:propose`.
-
-If you take one habit from these docs, take this one: **when you're not sure, explore before you propose.**
-
-Here's why that matters. AI coding assistants are eager. Ask vaguely and they'll confidently build *something*, just maybe not the thing you needed. Explore is the cure. It's a no-stakes conversation where you and the AI figure out the right move together, so that by the time you propose, you're proposing the right thing.
-
-## When to explore
-
-Explore is the right first step more often than people expect. Use it when any of these is true:
-
- You know the *problem* but not the *solution*. ("Pages feel slow." "Auth is a mess." "We keep getting duplicate orders.")
- You're choosing between approaches and want the tradeoffs laid out against your actual code.
- You're new to a codebase and need to understand how something works before you change it.
- The requirements are fuzzy and you want to sharpen them before committing.
- You suspect the work is bigger or smaller than it looks and want to scope it honestly.
-
-Skip explore only when you already know exactly what you want and how. In that case go straight to [`/opsx:propose`](commands.md#opsxpropose).
-
-## What it does (and doesn't)
-
-Explore is a **conversation**, not a generator.
-
-**It does:**
- Read and search your codebase to answer real questions.
- Compare options and name the tradeoffs of each.
- Draw diagrams to make a design legible.
- Help you narrow a vague idea into a concrete, buildable scope.
- Transition to `/opsx:propose` when you're ready.
-
-**It does not:**
- Create a change folder.
- Write any artifacts (no proposal, specs, design, or tasks).
- Write or modify code.
-
-That's the point. Exploring costs you nothing and commits you to nothing. You can explore three dead ends, learn something from each, and only then propose the path that survived.
-
-## It's already installed
-
-Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `sync`, and `archive`. You don't need to enable anything. If OpenSpec is set up in your project, explore is ready in your AI chat. (As with all `/opsx:*` commands, you type it in your assistant's chat, not the terminal. See [How Commands Work](how-commands-work.md).)
-
-## A full example
-
-Watch how a vague worry becomes a sharp, buildable change.
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: Our checkout sometimes creates duplicate orders. I don't know why
-     and I don't know how to fix it safely.
-
-AI:  Let me dig into the checkout path...
-     [reads the order service, the payment webhook handler, and the
-      client submit logic]
-
-     Here's what I found. There are two ways a duplicate can happen:
-
-     1. The client can submit twice (double-click, retry on slow network).
-        Nothing debounces it.
-     2. The payment webhook can fire more than once, and the handler
-        creates an order each time. There's no idempotency key.
-
-     Cause #2 is the dangerous one: it can charge and fulfill twice.
-
-     Three ways to fix it, roughly in order of robustness:
-     - Idempotency key on the order-creation endpoint (handles both causes)
-     - Dedup on the webhook by payment-intent id (handles #2 only)
-     - Client-side debounce (handles #1 only, papers over the real bug)
-
-     Given your code already stores the payment-intent id, the
-     idempotency-key approach is a small change with the biggest payoff.
-     Want me to scope that?
-
-You: Yes, let's do the idempotency key.
-
-You: /opsx:propose add-order-idempotency-key
-
-AI:  Created openspec/changes/add-order-idempotency-key/, with a proposal
-     and delta spec grounded in what we just found. Ready for implementation.
-```
-
-Notice what happened. The starting point was "something is wrong and I'm scared to touch it." Twenty seconds of exploration turned that into a named root cause, three ranked options, a recommendation tied to the existing code, and a precise change. The proposal that follows is sharp because the thinking happened first.
-
-## Handing off to propose
-
-Explore doesn't archive into anything. When you're ready, you simply start a change, and the AI carries the context from your conversation into the artifacts.
-
-```text
-explore  ──►  propose  ──►  apply  ──►  archive
- (think)     (agree)       (build)     (record)
-```
-
-You can say it in plain language ("let's turn this into a change") or run `/opsx:propose <name>` directly. Either way, the exploration you just did becomes the foundation of the proposal, not throwaway chat.
-
-If you use the expanded command set, explore can hand off to `/opsx:new` instead, for step-by-step artifact creation. See [Workflows](workflows.md).
-
-## Tips for a good exploration
-
- **Bring the problem, not the solution.** "Logins feel slow" gives the AI room to investigate. "Add a Redis cache" pre-commits you to an answer you haven't tested yet.
- **Ask for the tradeoffs out loud.** "What are the downsides of each option?" gets you a more honest comparison.
- **Let it read first.** The best explorations start with the AI actually looking at your code, not guessing. Point it at the relevant area if it helps.
- **It's okay to bail.** If exploration reveals the idea isn't worth it, that's a win. You learned it cheaply.
- **Explore again mid-change.** Stuck during `/opsx:apply`? You can step back and explore a sub-problem, then return.
-
-## The honest tradeoffs
-
-**What you gain:** explore catches wrong turns at the cheapest possible moment, before any artifact exists. It's especially powerful in unfamiliar code, where the AI's ability to read and summarize the system saves you an afternoon of spelunking.
-
-**What it costs:** a little patience. Explore is a conversation, so it's slower than firing off `/opsx:propose` and hoping. For work you genuinely understand already, that extra step is pure overhead, and you should skip it.
-
-The rule of thumb: the fuzzier the task, the more explore pays off. The clearer the task, the more you can skip straight to proposing.
-
-## Where to go next
-
- [Commands: `/opsx:explore`](commands.md#opsxexplore): the precise reference
- [Workflows](workflows.md): explore as part of the everyday loop
- [Examples & Recipes](examples.md#recipe-3-exploring-before-you-commit): explore in a full walkthrough
- [Getting Started](getting-started.md): the first-change guide, exploration included
@@ -1,155 +0,0 @@
-# FAQ
-
-Quick answers to the questions people ask most. If your question is really a "something is broken" question, [Troubleshooting](troubleshooting.md) is the better page. If you want a term defined, see the [Glossary](glossary.md).
-
-## The basics
-
-### What is OpenSpec, in one sentence?
-
-A lightweight layer that gets you and your AI coding assistant to agree on what to build, in writing, before any code is written.
-
-### Why would I want that?
-
-Because AI assistants are confident even when they're wrong. When the requirements live only in a chat thread, the AI fills gaps with guesses, and you find out after the code exists. OpenSpec moves the agreement earlier, where mistakes are cheap to fix. See [Core Concepts at a Glance](overview.md) for the full case.
-
-### Do I have to use it for everything?
-
-No. Use it where agreement matters, which is most non-trivial work. For a one-character typo fix, the ceremony probably isn't worth it, and that's fine.
-
-### Can I use it on a big existing codebase, or only new projects?
-
-Existing codebases are the main event. OpenSpec is brownfield-first: you do not document your whole app up front. You write specs only for what each change touches, and your specs fill in over time around the work you actually do. There's a dedicated guide: [Using OpenSpec in an Existing Project](existing-projects.md).
-
-### Is it tied to one AI tool?
-
-No. OpenSpec works with 25+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md).
-
-## Running commands
-
-### Where do I type `/opsx:propose`?
-
-In your AI assistant's chat, not your terminal. This is the single most common point of confusion, so it has its own page: [How Commands Work](how-commands-work.md). Short version: `openspec ...` runs in the terminal, `/opsx:...` runs in chat.
-
-### How do I "start interactive mode"?
-
-There isn't a separate mode to start. You open your AI assistant like normal and type a slash command into its chat. The slash command is how you "enter" OpenSpec. (The one genuinely interactive terminal feature is `openspec view`, a dashboard for browsing specs and changes.) Full explanation in [How Commands Work](how-commands-work.md).
-
-### I typed a slash command and nothing happened. Why?
-
-Most likely you typed it in the terminal instead of your AI chat, or the commands aren't installed yet. Run `openspec update` in your project, restart your assistant, then try typing `/opsx` in chat and watch for autocomplete. [Troubleshooting](troubleshooting.md#commands-dont-show-up) has the full checklist.
-
-### Why is the syntax `/opsx:propose` in one tool and `/opsx-propose` in another?
-
-Each AI tool surfaces custom commands a little differently. The intent is identical; only the punctuation changes. Type a slash in your chat and the autocomplete shows you the form your tool expects. The per-tool table is in [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool).
-
-### What's the difference between a skill and a command?
-
-Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever your tool uses.
-
-## The workflow
-
-### Where should I start if I'm not sure what to build?
-
-With `/opsx:explore`. It's a no-stakes thinking partner that reads your codebase, lays out options, and turns a fuzzy problem into a concrete plan, all before any change or code exists. It's in the default profile, so it's always available. When the plan is clear, it hands off to `/opsx:propose`. This is the single best habit to form, because it stops an eager AI from confidently building the wrong thing. See [Explore First](explore.md).
-
-### What's the simplest possible flow?
-
-```text
-/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive
-```
-
-Explore to think it through, propose to draft the plan, apply to build it, archive to file it away. Skip explore when you already know exactly what you want.
-
-### What's the difference between `/opsx:propose` and `/opsx:new`?
-
-`/opsx:propose` is the default one-step command: it creates the change and drafts all the planning artifacts at once. `/opsx:new` is part of the expanded command set and only scaffolds an empty change, leaving you to create artifacts one at a time with `/opsx:continue` (or all at once with `/opsx:ff`). Use propose unless you want step-by-step control. See [Commands](commands.md).
-
-### What are `core` and expanded profiles?
-
-A profile decides which slash commands get installed. **Core** (the default) gives you `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, and `onboard` for finer control. Switch with `openspec config profile`, then apply with `openspec update`.
-
-### Do I need to run `/opsx:sync`?
-
-Usually not. Sync merges a change's delta specs into your main specs, and `/opsx:archive` will offer to do it for you. Run sync manually only when you want the specs merged before archiving, for example on a long-running change. See [Commands](commands.md#opsxsync).
-
-### How do I edit a proposal, spec, or task after I've started?
-
-Just edit the file. Every artifact is plain Markdown in `openspec/changes/<name>/`, and there's no locked phase or special edit mode. Change it by hand, or ask your AI to revise it ("update the design to use a queue"), then keep going. The AI always works from the current file contents. Full guide: [Editing & Iterating on a Change](editing-changes.md).
-
-### Can I go back and change the plan after implementing some of it?
-
-Yes, at any time. The workflow is fluid, so review and editing aren't phases you get locked out of. Edit the artifact, then continue. If you want a structured check that the code still matches the plan, run `/opsx:verify`. See [Editing & Iterating on a Change](editing-changes.md#how-do-i-go-back-to-review-after-implementing).
-
-### I edited the code by hand. How do I reconcile it with the spec?
-
-Bring them back in sync before you archive, since archiving makes your specs the record of truth. If the code is now correct, update the delta spec to match what you shipped; if the spec is correct, keep building until the code agrees. `/opsx:verify` surfaces the mismatches. See [Editing & Iterating on a Change](editing-changes.md#i-edited-the-code-by-hand-how-do-i-reconcile-that-with-openspec).
-
-### When should I update an existing change versus start a new one?
-
-Update when it's the same work, refined. Start fresh when the intent fundamentally changed or the scope exploded into different work. There's a decision flowchart and examples in [Workflows](workflows.md#when-to-update-vs-start-fresh).
-
-### What if my session runs out of context, or requirements change mid-implementation?
-
-This is where specs earn their keep. Because the plan lives in files (not only in chat history), you can clear your context, start a fresh AI session, and pick up with `/opsx:apply`; it reads the artifacts and resumes from the first unchecked task. If requirements change, edit the artifacts to match the new reality and continue. Keeping a clean context window also produces better results; clear it before implementation.
-
-### Should I commit the `openspec/` folder to git?
-
-Yes. Your specs, active changes, and archive are part of your project's history. Commit them like any other source. The archive in particular becomes a durable record of why your system works the way it does.
-
-## Specs and changes
-
-### What goes in a spec versus a design?
-
-A spec describes observable behavior: what the system does, its inputs, outputs, and error conditions. A design describes how you'll build it: the technical approach, architecture decisions, file changes. If implementation could change without changing externally visible behavior, it belongs in the design, not the spec. [Concepts](concepts.md#what-a-spec-is-and-is-not) goes deeper.
-
-### What's a delta spec?
-
-A spec that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the whole spec. It's how OpenSpec handles edits to existing systems cleanly. See [Concepts](concepts.md#delta-specs).
-
-### Where do archived changes go?
-
-To `openspec/changes/archive/YYYY-MM-DD-<name>/`, with all artifacts preserved. Nothing is deleted; the change just moves out of your active list.
-
-## Configuration and customization
-
-### How do I tell the AI about my tech stack?
-
-Put it in `openspec/config.yaml` under `context:`. That text is injected into every planning request, so the AI always knows your stack and conventions. See [Customization](customization.md#project-configuration).
-
-### Can I generate specs in a language other than English?
-
-Yes. Add a language instruction to your config's `context:`. [Multi-Language](multi-language.md) has copy-paste snippets for several languages.
-
-### Can I change the workflow itself?
-
-Yes, with custom schemas. A schema defines which artifacts exist and how they depend on each other. Fork the default with `openspec schema fork spec-driven my-workflow`, then edit it. See [Customization](customization.md#custom-schemas).
-
-## Models, privacy, and upgrades
-
-### Which AI model should I use?
-
-OpenSpec works best with high-reasoning models. The README recommends models like Codex 5.5 and Opus 4.7 for both planning and implementation. Also keep your context window clean: clear it before implementation for best results.
-
-### Does OpenSpec collect data?
-
-It collects anonymous usage stats: command names and version only. No arguments, paths, content, or personal data, and it's off automatically in CI. Opt out with `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`.
-
-### How do I upgrade?
-
-Two steps. Upgrade the package (`npm install -g @fission-ai/openspec@latest`), then run `openspec update` inside each project to refresh the generated skills and commands.
-
-### How do I uninstall OpenSpec?
-
-There's no uninstall command, because it's just a global package plus files in your project. Remove the package (`npm uninstall -g @fission-ai/openspec`), and optionally delete the `openspec/` directory and the generated tool files. Step-by-step, including what's safe to keep, is in [Installation: Uninstalling](installation.md#uninstalling).
-
-## Getting help
-
-### Where do I ask questions or report bugs?
-
- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
- **From your terminal:** `openspec feedback "your message"` opens a GitHub issue for you.
-
-### These docs are wrong or confusing. What do I do?
-
-Tell us, or fix it. Documentation PRs are welcome and valued. Open an issue or send a pull request.
@@ -1,287 +0,0 @@
-# Getting Started
-
-This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start) or the [Installation guide](installation.md). New to the whole docs set? The [documentation home](README.md) maps everything.
-
-> **Where do I type these commands?** Two places, and mixing them up is the most common early stumble.
->
-> - `openspec ...` commands (like `openspec init`) run in your **terminal**.
-> - `/opsx:...` commands (like `/opsx:propose`) run in your **AI assistant's chat**, the same box where you'd ask it to write code.
->
-> There's no separate "interactive mode" to start. You just type the slash command in chat and your assistant takes it from there. Full explanation: [How Commands Work](how-commands-work.md).
-
-## Your First Five Minutes
-
-The whole loop, with each step labeled by where it happens:
-
-```text
-TERMINAL   $ npm install -g @fission-ai/openspec@latest
-TERMINAL   $ cd your-project && openspec init
-AI CHAT      /opsx:explore                    (optional: think it through first)
-AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
-AI CHAT      /opsx:apply                      (AI builds it)
-AI CHAT      /opsx:archive                    (specs updated, change filed away)
-```
-
-Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see.
-
-> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md).
-
-## How It Works
-
-OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
-
-**Default quick path (core profile):**
-
-```text
-/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-   (optional)
-```
-
-Start with `/opsx:explore` when you're figuring out what to do, or jump straight to `/opsx:propose` when you already know. Explore is in the default profile, so it's always there when you want it.
-
-**Expanded path (custom workflow selection):**
-
-```text
-/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
-```
-
-The default global profile is `core`, which includes `propose`, `explore`, `apply`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`.
-
-## What OpenSpec Creates
-
-After running `openspec init`, your project has this structure:
-
-```
-openspec/
-├── specs/              # Source of truth (your system's behavior)
-│   └── <domain>/
-│       └── spec.md
-├── changes/            # Proposed updates (one folder per change)
-│   └── <change-name>/
-│       ├── proposal.md
-│       ├── design.md
-│       ├── tasks.md
-│       └── specs/      # Delta specs (what's changing)
-│           └── <domain>/
-│               └── spec.md
-└── config.yaml         # Project configuration (optional)
-```
-
-**Two key directories:**
-
- **`specs/`** - The source of truth. These specs describe how your system currently behaves. Organized by domain (e.g., `specs/auth/`, `specs/payments/`).
-
- **`changes/`** - Proposed modifications. Each change gets its own folder with all related artifacts. When a change is complete, its specs merge into the main `specs/` directory.
-
-## Understanding Artifacts
-
-Each change folder contains artifacts that guide the work:
-
-| Artifact | Purpose |
-|----------|---------|
-| `proposal.md` | The "why" and "what" - captures intent, scope, and approach |
-| `specs/` | Delta specs showing ADDED/MODIFIED/REMOVED requirements |
-| `design.md` | The "how" - technical approach and architecture decisions |
-| `tasks.md` | Implementation checklist with checkboxes |
-
-**Artifacts build on each other:**
-
-```
-proposal ──► specs ──► design ──► tasks ──► implement
-   ▲           ▲          ▲                    │
-   └───────────┴──────────┴────────────────────┘
-            update as you learn
-```
-
-You can always go back and refine earlier artifacts as you learn more during implementation.
-
-## How Delta Specs Work
-
-Delta specs are the key concept in OpenSpec. They show what's changing relative to your current specs.
-
-### The Format
-
-Delta specs use sections to indicate the type of change:
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
-
-#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
-
-## MODIFIED Requirements
-
-### Requirement: Session Timeout
-The system SHALL expire sessions after 30 minutes of inactivity.
-(Previously: 60 minutes)
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
-
-## REMOVED Requirements
-
-### Requirement: Remember Me
-(Deprecated in favor of 2FA)
-```
-
-### What Happens on Archive
-
-When you archive a change:
-
-1. **ADDED** requirements are appended to the main spec
-2. **MODIFIED** requirements replace the existing version
-3. **REMOVED** requirements are deleted from the main spec
-
-The change folder moves to `openspec/changes/archive/` for audit history.
-
-## Example: Your First Change
-
-Let's walk through adding dark mode to an application.
-
-### 1. Start the Change (Default)
-
-```text
-You: /opsx:propose add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md — why we're doing this, what's changing
-     ✓ specs/       — requirements and scenarios
-     ✓ design.md    — technical approach
-     ✓ tasks.md     — implementation checklist
-     Ready for implementation!
-```
-
-If you've enabled the expanded workflow profile, you can also do this as two steps: `/opsx:new` then `/opsx:ff` (or `/opsx:continue` incrementally).
-
-### 2. What Gets Created
-
-**proposal.md** - Captures the intent:
-
-```markdown
-# Proposal: Add Dark Mode
-
-## Intent
-Users have requested a dark mode option to reduce eye strain
-during nighttime usage.
-
-## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage
-
-## Approach
-Use CSS custom properties for theming with a React context
-for state management.
-```
-
-**specs/ui/spec.md** - Delta showing new requirements:
-
-```markdown
-# Delta for UI
-
-## ADDED Requirements
-
-### Requirement: Theme Selection
-The system SHALL allow users to choose between light and dark themes.
-
-#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions
-
-#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used
-```
-
-**tasks.md** - Implementation checklist:
-
-```markdown
-# Tasks
-
-## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
-
-## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
-
-## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
-```
-
-### 3. Implement
-
-```
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ 1.1 Created ThemeContext with light/dark state
-     ✓ 1.2 Added CSS custom properties to globals.css
-     ✓ 1.3 Implemented localStorage persistence
-     ✓ 2.1 Created ThemeToggle component
-     ...
-     All tasks complete!
-```
-
-During implementation, if you discover the design needs adjustment, just update the artifact and continue.
-
-### 4. Archive
-
-```
-You: /opsx:archive
-
-AI:  Archiving add-dark-mode...
-     ✓ Merged specs into openspec/specs/ui/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
-     Done! Ready for the next feature.
-```
-
-Your delta specs are now part of the main specs, documenting how your system works.
-
-## Verifying and Reviewing
-
-Use the CLI to check on your changes:
-
-```bash
-# List active changes
-openspec list
-
-# View change details
-openspec show add-dark-mode
-
-# Validate spec formatting
-openspec validate add-dark-mode
-
-# Interactive dashboard
-openspec view
-```
-
-## Next Steps
-
- [Explore First](explore.md) - Use `/opsx:explore` to think through an idea before you commit
- [Using OpenSpec in an Existing Project](existing-projects.md) - Start on a large brownfield codebase
- [Editing & Iterating on a Change](editing-changes.md) - Update artifacts, go back, reconcile manual edits
- [Core Concepts at a Glance](overview.md) - The whole mental model on one page
- [Examples & Recipes](examples.md) - Real changes, start to finish
- [Workflows](workflows.md) - Common patterns and when to use each command
- [Commands](commands.md) - Full reference for all slash commands
- [Concepts](concepts.md) - Deeper understanding of specs, changes, and schemas
- [Customization](customization.md) - Make OpenSpec work your way
- [Stores](stores-beta/user-guide.md) - Planning that spans repos or teams? Keep it in its own repo (beta)
- [FAQ](faq.md) and [Troubleshooting](troubleshooting.md) - When you get stuck
@@ -1,91 +0,0 @@
-# Glossary
-
-Every OpenSpec term in one place, defined in plain language. Skim it once and the rest of the docs read faster.
-
-Terms are grouped by topic, then alphabetized within each group.
-
-## The core nouns
-
-**Spec.** A document describing how part of your system behaves. Specs live in `openspec/specs/`, are organized by domain, and are made of requirements and scenarios. The spec is the agreed-upon answer to "what does this software do?" See [Concepts](concepts.md#specs).
-
-**Source of truth.** The `openspec/specs/` directory as a whole. It holds the current, agreed-upon behavior of your system. Changes propose edits to it; archiving applies them.
-
-**Change.** One unit of work, packaged as a folder under `openspec/changes/<name>/`. A change holds everything about that work: its proposal, design, tasks, and the spec edits it introduces. One change, one feature or fix.
-
-**Artifact.** A document inside a change. The standard artifacts are the proposal, the delta specs, the design, and the tasks. They're created in dependency order and feed into each other.
-
-**Delta spec.** A spec inside a change that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the entire spec. This is what lets OpenSpec edit existing systems cleanly. See [Concepts](concepts.md#delta-specs).
-
-**Domain.** A logical grouping for specs, like `auth/`, `payments/`, or `ui/`. You choose domains that match how you think about your system.
-
-## Inside a spec
-
-**Requirement.** A single behavior the system must have, usually written with an RFC 2119 keyword: "The system SHALL expire sessions after 30 minutes." Requirements state the *what*, not the *how*.
-
-**Scenario.** A concrete, testable example of a requirement in action, typically in Given/When/Then form. Scenarios make a requirement verifiable: you could write an automated test from one.
-
-**RFC 2119 keywords.** The words MUST, SHALL, SHOULD, and MAY, which carry standardized meaning about how strict a requirement is. MUST and SHALL are absolute. SHOULD is recommended with room for exceptions. MAY is optional. The name comes from the internet standards document that defined them.
-
-## The artifacts
-
-**Proposal (`proposal.md`).** The *why* and *what* of a change: its intent, scope, and high-level approach. The first artifact you create.
-
-**Design (`design.md`).** The *how*: technical approach, architecture decisions, and the files you expect to touch. Optional for simple changes.
-
-**Tasks (`tasks.md`).** The implementation checklist, with checkboxes. The AI works through it during `/opsx:apply` and checks items off as it goes.
-
-## The lifecycle
-
-**Archive.** The act of finishing a change. Its delta specs merge into the main specs, and the change folder moves to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After archiving, your specs describe the new reality. See [Concepts](concepts.md#archive).
-
-**Sync.** Merging a change's delta specs into the main specs *without* archiving the change. Usually automatic (archive offers to do it), but available on its own as `/opsx:sync` for long-running changes. See [Commands](commands.md#opsxsync).
-
-## Workflow and commands
-
-**OPSX.** The current standard OpenSpec workflow, built around fluid actions instead of rigid phases. Its slash commands all start with `/opsx:`. See [OPSX Workflow](opsx.md).
-
-**Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md).
-
-**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan, creating no artifacts and writing no code. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md).
-
-**CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md).
-
-**Skill.** A folder of instructions (`.../skills/openspec-*/SKILL.md`) that your AI assistant auto-detects and follows. Skills are the emerging cross-tool standard for delivering the OpenSpec workflow to your assistant.
-
-**Command file.** A per-tool slash command file (`.../commands/opsx-*`). The older delivery mechanism, still supported alongside skills. You rarely touch these directly.
-
-**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`. Change it with `openspec config profile`.
-
-**Delivery.** Whether OpenSpec installs skills, command files, or both for your tools. Configured globally and applied with `openspec update`.
-
-## Customization
-
-**Schema.** The definition of which artifacts a workflow has and how they depend on one another. The built-in default is `spec-driven` (proposal → specs → design → tasks). You can fork it or write your own. See [Customization](customization.md#custom-schemas).
-
-**Template.** A Markdown file inside a schema that shapes what the AI generates for a given artifact. Editing a template changes the AI's output immediately, with no rebuild.
-
-**Project config (`openspec/config.yaml`).** Per-project settings: the default schema, the `context:` injected into every planning request, and per-artifact `rules:`. The easiest way to teach OpenSpec about your stack and conventions. See [Customization](customization.md#project-configuration).
-
-**Context injection.** Putting project background in `config.yaml`'s `context:` field so it's automatically added to every artifact the AI generates. More reliable than hoping the AI reads a separate file.
-
-**Dependency graph.** The directed graph formed by artifact `requires:` relationships. It's a DAG (directed acyclic graph: arrows only point forward, never in a loop), and OpenSpec uses it to know what you can create next.
-
-**Enablers, not gates.** The principle that artifact dependencies show what becomes *possible* next, not what's *required* next. You can revisit and edit any artifact at any time. See [Core Concepts at a Glance](overview.md#enablers-not-gates).
-
-## Coordination across repos (beta)
-
-These terms apply only if your planning spans more than one repo. They're in beta. Most users can ignore them. See the [Stores User Guide](stores-beta/user-guide.md).
-
-**Store.** A standalone repo whose whole job is planning. It has the same `openspec/` shape you already know (specs and changes) plus a small identity file. You register it on your machine once, by name, and then any OpenSpec command can work in it from anywhere.
-
-**Reference.** A declaration, in a code repo's `openspec/config.yaml`, of a store that repo draws on. References are read-only: the repo keeps its own root, and `openspec instructions` gains an index of the referenced store's specs, each with the exact command to fetch it.
-
-**Working context.** What `openspec context` assembles for the current repo: its OpenSpec root plus every store it references, each with how to fetch it. The answer to "what am I working with?"
-
-**Workset.** A personal, machine-local set of folders you open together (a store alongside the code repos you work on). Created explicitly with `openspec workset create`; nothing about those local paths is committed to the shared planning repo.
-
-## See also
-
- [Core Concepts at a Glance](overview.md): the five ideas, on one page
- [Concepts](concepts.md): the long-form explanation
- [How Commands Work](how-commands-work.md): slash commands versus the CLI
@@ -1,159 +0,0 @@
-# How Commands Work
-
-**The one thing to know: OpenSpec has two kinds of commands, and they run in two different places.**
-
- `openspec ...` commands run in your **terminal**. (Example: `openspec init`.)
- `/opsx:...` commands run in your **AI assistant's chat**. (Example: `/opsx:propose`.)
-
-If you ever type `/opsx:propose` into your terminal and nothing happens, this page is why. You are talking to the wrong half of OpenSpec. Slash commands are not terminal commands. They are instructions you give to your AI coding assistant, in the same chat box where you'd normally type "add a login form."
-
-That single distinction is the most common stumbling block for new users, so let's make it crystal clear.
-
-## The two halves
-
-OpenSpec is one project wearing two hats.
-
-**The CLI (terminal half).** A program named `openspec` that you install and run from your shell. It sets up your project, lists and validates changes, shows a dashboard, and archives finished work. You type these into iTerm, the VS Code terminal, PowerShell, anywhere you'd run `git` or `npm`.
-
-```bash
-openspec init        # set up OpenSpec in this project
-openspec list        # see active changes
-openspec view        # open the interactive dashboard
-```
-
-**The slash commands (chat half).** Short commands like `/opsx:propose` and `/opsx:apply` that you type into your AI assistant. These tell the AI to follow the OpenSpec workflow: draft a proposal, write specs, build from the task list, archive when done. You type these into Claude Code, Cursor, Windsurf, Copilot, or whichever assistant you use.
-
-```text
-/opsx:propose add-dark-mode    (typed in your AI chat)
-/opsx:apply                    (typed in your AI chat)
-/opsx:archive                  (typed in your AI chat)
-```
-
-Here's the mental model in one picture:
-
-```text
-        YOUR TERMINAL                         YOUR AI ASSISTANT'S CHAT
-   ┌──────────────────────┐               ┌──────────────────────────────┐
-   │  $ openspec init     │   installs    │  /opsx:propose add-dark-mode  │
-   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
-   │  $ openspec view     │   commands    │  /opsx:archive                │
-   └──────────────────────┘    & skills   └──────────────────────────────┘
-        run openspec here                       run /opsx:* here
-```
-
-Notice the arrow. Running `openspec init` in your terminal is what *installs* the slash commands into your AI tool. The terminal half sets up the chat half. After that, day-to-day driving mostly happens in chat.
-
-## "How do I start interactive mode?"
-
-**There is no separate interactive mode to start.** This question comes up a lot, so it deserves a plain answer.
-
-You don't enter a special OpenSpec mode. You just open your AI coding assistant like you always do, and type a slash command into the chat. The slash command *is* how you "enter" OpenSpec. Your assistant recognizes it, loads the matching OpenSpec skill, and starts following the workflow.
-
-So the real instructions are:
-
-1. Open your AI coding assistant (Claude Code, Cursor, Windsurf, and so on) in your project.
-2. Type `/opsx:propose` in its chat, the same place you type any other request.
-3. Watch the autocomplete: if OpenSpec is installed, you'll see `/opsx:propose`, `/opsx:apply`, and friends appear as you type the slash.
-
-That's it. No mode to toggle, no daemon to launch, no separate window.
-
-One thing that *is* genuinely interactive lives in the terminal: `openspec view`. It opens a dashboard for browsing your specs and changes. But that's a viewer, not the thing you propose and build with. The building happens through slash commands in chat.
-
-## Why this split exists
-
-It's worth understanding, because it explains why OpenSpec works with 25+ different AI tools.
-
-The CLI is the **engine**. It knows the rules: what a change folder looks like, which artifacts depend on which, how to merge a delta spec into your source of truth. It's the same everywhere.
-
-The slash commands are the **steering wheel**, and every AI tool has a slightly different one. Claude Code calls them commands. Cursor and Windsurf have their own formats. Some tools call them skills. When you run `openspec init`, OpenSpec generates the right kind of file for each tool you selected, so the same `/opsx:propose` intent works no matter which assistant you prefer.
-
-The strength of this design: you learn the workflow once and carry it across tools. The tradeoff: the exact syntax of a command can differ slightly between tools, which is the next section.
-
-## Slash command syntax by tool
-
-The intent is identical everywhere. The punctuation differs. Use the form that matches your assistant.
-
-| Tool | How you type it |
-|------|-----------------|
-| Claude Code | `/opsx:propose`, `/opsx:apply` |
-| Cursor | `/opsx-propose`, `/opsx-apply` |
-| Windsurf | `/opsx-propose`, `/opsx-apply` |
-| GitHub Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
-| Kimi CLI | skill-style, e.g. `/skill:openspec-propose` |
-| Trae | skill-style, e.g. `/openspec-propose` |
-
-Most tools use either the colon form (`/opsx:propose`) or the dash form (`/opsx-propose`). A few tools surface OpenSpec as named skills instead of slash commands; for those you invoke the skill by name. The full per-tool list, including exactly which files get written where, lives in [Supported Tools](supported-tools.md).
-
-When in doubt, type a slash in your AI chat and look at the autocomplete. Your tool will show you the form it expects.
-
-## How the commands got there: skills and commands
-
-When you run `openspec init` (or `openspec update`), OpenSpec writes small files into your project so your AI tool can find the workflow. Depending on your tool and settings, these are **skills**, **commands**, or both.
-
- **Skills** live in places like `.claude/skills/openspec-*/SKILL.md`. They're the emerging cross-tool standard: a folder of instructions your assistant auto-detects.
- **Commands** live in places like `.claude/commands/opsx/<id>.md`. They're the older per-tool slash command files.
-
-You don't have to care which one your tool uses. You just type the slash command and it works. But knowing these files exist helps when something goes wrong: if your commands vanish, it usually means these files are missing or stale, and `openspec update` regenerates them.
-
-See [Supported Tools](supported-tools.md) for the exact paths per tool, and [Migration Guide](migration-guide.md) for how skills replaced the older command-only approach.
-
-## Confirming it's installed
-
-Quick checks, fastest first:
-
-1. **Type a slash in your AI chat.** Start typing `/opsx` and watch for autocomplete suggestions. If they appear, you're set.
-2. **Look for the files.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories ([Supported Tools](supported-tools.md) lists them).
-3. **Re-run setup.** From your project root, run `openspec update`. This regenerates the skill and command files for whatever tools you configured.
-4. **Restart your assistant.** Many tools scan for skills and commands at startup, so a fresh window can be the missing step.
-
-## Which commands do I even have?
-
-By default, OpenSpec installs the **core** set of slash commands:
-
- `/opsx:explore`: think through an idea with the AI before committing to a change (great first step when you're unsure)
- `/opsx:propose`: create a change and draft all its planning artifacts in one step
- `/opsx:apply`: build the change by working through its task list
- `/opsx:sync`: merge a change's spec updates into your main specs (usually automatic)
- `/opsx:archive`: finish a change and file it away
-
-A good default rhythm: `explore` when you're figuring out what to do, then `propose`, `apply`, `archive`. The [Explore First](explore.md) guide explains why that opening step pays off.
-
-There's also an **expanded** set for people who want finer control (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`). You turn it on with `openspec config profile`, then apply it with `openspec update`.
-
-New to all of this? `/opsx:onboard` (in the expanded set) walks you through a complete change on your own codebase, narrating each step. It's the friendliest possible introduction.
-
-For what each command does in detail, see [Commands](commands.md). For when to reach for which, see [Workflows](workflows.md).
-
-## A clean first run
-
-Putting it together, here is the whole sequence with each step labeled by where it happens.
-
-```text
-TERMINAL   $ npm install -g @fission-ai/openspec@latest
-TERMINAL   $ cd your-project
-TERMINAL   $ openspec init
-              (installs slash commands into your AI tool)
-
-AI CHAT      /opsx:explore
-              (optional: think the idea through with the AI first)
-
-AI CHAT      /opsx:propose add-dark-mode
-              (AI drafts proposal, specs, design, tasks)
-
-AI CHAT      /opsx:apply
-              (AI builds it, checking off tasks)
-
-AI CHAT      /opsx:archive
-              (change is merged into your specs and filed away)
-```
-
-Two terminal steps to set up. Then you live in chat. That's the rhythm.
-
-## Related
-
- [Getting Started](getting-started.md): the full first-change walkthrough
- [Commands](commands.md): every slash command in detail
- [CLI](cli.md): every terminal command in detail
- [Supported Tools](supported-tools.md): per-tool syntax and file locations
- [FAQ](faq.md): more quick answers
- [Troubleshooting](troubleshooting.md): fixes when commands don't show up
@@ -1,115 +0,0 @@
-# Installation
-
-## Prerequisites
-
- **Node.js 20.19.0 or higher** — Check your version: `node --version`
-
-## Package Managers
-
-### npm
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-### pnpm
-
-```bash
-pnpm add -g @fission-ai/openspec@latest
-```
-
-### yarn
-
-```bash
-yarn global add @fission-ai/openspec@latest
-```
-
-### bun
-
-Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
-You still need Node.js 20.19.0 or higher available on `PATH`.
-
-```bash
-bun add -g @fission-ai/openspec@latest
-```
-
-## Nix
-
-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
-```
-
-## Updating
-
-Upgrade the package, then refresh each project's generated files:
-
-```bash
-npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
-openspec update                              # run inside each project
-```
-
-`openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version.
-
-## Uninstalling
-
-There's no `openspec uninstall` command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
-
-**1. Remove the global package:**
-
-```bash
-npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
-```
-
-**2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
-
-```bash
-rm -rf openspec/
-```
-
-Think before you do this: `openspec/specs/` and `openspec/changes/archive/` are your record of how the system behaves and why it changed. If you might want that history, keep the folder (or keep it in git) even after uninstalling.
-
-**3. Remove generated AI tool files (optional).** OpenSpec writes skill and command files into per-tool directories like `.claude/skills/openspec-*/`, `.cursor/commands/opsx-*`, and so on. Delete the `openspec-*` skills and `opsx-*` commands for whichever tools you configured. The exact paths per tool are listed in [Supported Tools](supported-tools.md).
-
-If you also have OpenSpec marker blocks in files like `CLAUDE.md` or `AGENTS.md`, remove those blocks by hand; your own content in those files is yours to keep.
-
-## Next Steps
-
-After installing, initialize OpenSpec in your project:
-
-```bash
-cd your-project
-openspec init
-```
-
-See [Getting Started](getting-started.md) for a full walkthrough.
@@ -1,596 +0,0 @@
-# Migrating to OPSX
-
-This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility.
-
-## What's Changing?
-
-OPSX replaces the old phase-locked workflow with a fluid, action-based approach. Here's the key shift:
-
-| Aspect | Legacy | OPSX |
-|--------|--------|------|
-| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
-| **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice |
-| **Going back** | Awkward phase gates | Natural—update any artifact anytime |
-| **Customization** | Fixed structure | Schema-driven, fully hackable |
-| **Configuration** | `CLAUDE.md` with markers + `project.md` | Clean config in `openspec/config.yaml` |
-
-**The philosophy change:** Work isn't linear. OPSX stops pretending it is.
-
---
-
-## Before You Begin
-
-### Your Existing Work Is Safe
-
-The migration process is designed with preservation in mind:
-
- **Active changes in `openspec/changes/`** — Completely preserved. You can continue them with OPSX commands.
- **Archived changes** — Untouched. Your history remains intact.
- **Main specs in `openspec/specs/`** — Untouched. These are your source of truth.
- **Your content in CLAUDE.md, AGENTS.md, etc.** — Preserved. Only the OpenSpec marker blocks are removed; everything you wrote stays.
-
-### What Gets Removed
-
-Only OpenSpec-managed files that are being replaced:
-
-| What | Why |
-|------|-----|
-| Legacy slash command directories/files | Replaced by the new skills system |
-| `openspec/AGENTS.md` | Obsolete workflow trigger |
-| OpenSpec markers in `CLAUDE.md`, `AGENTS.md`, etc. | No longer needed |
-
-**Legacy command locations by tool** (examples—your tool may vary):
-
- Claude Code: `.claude/commands/openspec/`
- Cursor: `.cursor/commands/openspec-*.md`
- Windsurf: `.windsurf/workflows/openspec-*.md`
- Cline: `.clinerules/workflows/openspec-*.md`
- Roo: `.roo/commands/openspec-*.md`
- GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
- And others (Augment, Continue, Amazon Q, etc.)
-
-The migration detects whichever tools you have configured and cleans up their legacy files.
-
-The removal list may seem long, but these are all files that OpenSpec originally created. Your own content is never deleted.
-
-### What Needs Your Attention
-
-One file requires manual migration:
-
-**`openspec/project.md`** — This file isn't deleted automatically because it may contain project context you've written. You'll need to:
-
-1. Review its contents
-2. Move useful context to `openspec/config.yaml` (see guidance below)
-3. Delete the file when ready
-
-**Why we made this change:**
-
-The old `project.md` was passive—agents might read it, might not, might forget what they read. We found reliability was inconsistent.
-
-The new `config.yaml` context is **actively injected into every OpenSpec planning request**. This means your project conventions, tech stack, and rules are always present when the AI is creating artifacts. Higher reliability.
-
-**The tradeoff:**
-
-Because context is injected into every request, you'll want to be concise. Focus on what really matters:
- Tech stack and key conventions
- Non-obvious constraints the AI needs to know
- Rules that frequently got ignored before
-
-Don't worry about getting it perfect. We're still learning what works best here, and we'll be improving how context injection works as we experiment.
-
---
-
-## Running the Migration
-
-Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation:
-
- New installs default to profile `core` (`propose`, `explore`, `apply`, `sync`, `archive`).
- Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed.
-
-### Using `openspec init`
-
-Run this if you want to add new tools or reconfigure which tools are set up:
-
-```bash
-openspec init
-```
-
-The init command detects legacy files and guides you through cleanup:
-
-```
-Upgrading to the new OpenSpec
-
-OpenSpec now uses agent skills, the emerging standard across coding
-agents. This simplifies your setup while keeping everything working
-as before.
-
-Files to remove
-No user content to preserve:
-  • .claude/commands/openspec/
-  • openspec/AGENTS.md
-
-Files to update
-OpenSpec markers will be removed, your content preserved:
-  • CLAUDE.md
-  • AGENTS.md
-
-Needs your attention
-  • openspec/project.md
-    We won't delete this file. It may contain useful project context.
-
-    The new openspec/config.yaml has a "context:" section for planning
-    context. This is included in every OpenSpec request and works more
-    reliably than the old project.md approach.
-
-    Review project.md, move any useful content to config.yaml's context
-    section, then delete the file when ready.
-
-? Upgrade and clean up legacy files? (Y/n)
-```
-
-**What happens when you say yes:**
-
-1. Legacy slash command directories are removed
-2. OpenSpec markers are stripped from `CLAUDE.md`, `AGENTS.md`, etc. (your content stays)
-3. `openspec/AGENTS.md` is deleted
-4. New skills are installed in `.claude/skills/`
-5. `openspec/config.yaml` is created with a default schema
-
-### Using `openspec update`
-
-Run this if you just want to migrate and refresh your existing tools to the latest version:
-
-```bash
-openspec update
-```
-
-The update command also detects and cleans up legacy artifacts, then refreshes generated skills/commands to match your current profile and delivery settings.
-
-### Non-Interactive / CI Environments
-
-For scripted migrations:
-
-```bash
-openspec init --force --tools claude
-```
-
-The `--force` flag skips prompts and auto-accepts cleanup.
-
---
-
-## Migrating project.md to config.yaml
-
-The old `openspec/project.md` was a freeform markdown file for project context. The new `openspec/config.yaml` is structured and—critically—**injected into every planning request** so your conventions are always present when the AI works.
-
-### Before (project.md)
-
-```markdown
-# Project Context
-
-This is a TypeScript monorepo using React and Node.js.
-We use Jest for testing and follow strict ESLint rules.
-Our API is RESTful and documented in docs/api.md.
-
-## Conventions
-
- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications
-```
-
-### After (config.yaml)
-
-```yaml
-schema: spec-driven
-
-context: |
-  Tech stack: TypeScript, React, Node.js
-  Testing: Jest with React Testing Library
-  API: RESTful, documented in docs/api.md
-  We maintain backwards compatibility for all public APIs
-
-rules:
-  proposal:
-    - Include rollback plan for risky changes
-  specs:
-    - Use Given/When/Then format for scenarios
-    - Reference existing patterns before inventing new ones
-  design:
-    - Include sequence diagrams for complex flows
-```
-
-### Key Differences
-
-| project.md | config.yaml |
-|------------|-------------|
-| Freeform markdown | Structured YAML |
-| One blob of text | Separate context and per-artifact rules |
-| Unclear when it's used | Context appears in ALL artifacts; rules appear in matching artifacts only |
-| No schema selection | Explicit `schema:` field sets default workflow |
-
-### What to Keep, What to Drop
-
-When migrating, be selective. Ask yourself: "Does the AI need this for *every* planning request?"
-
-**Good candidates for `context:`**
- Tech stack (languages, frameworks, databases)
- Key architectural patterns (monorepo, microservices, etc.)
- Non-obvious constraints ("we can't use library X because...")
- Critical conventions that often get ignored
-
-**Move to `rules:` instead**
- Artifact-specific formatting ("use Given/When/Then in specs")
- Review criteria ("proposals must include rollback plans")
- These only appear for the matching artifact, keeping other requests lighter
-
-**Leave out entirely**
- General best practices the AI already knows
- Verbose explanations that could be summarized
- Historical context that doesn't affect current work
-
-### Migration Steps
-
-1. **Create config.yaml** (if not already created by init):
-   ```yaml
-   schema: spec-driven
-   ```
-
-2. **Add your context** (be concise—this goes into every request):
-   ```yaml
-   context: |
-     Your project background goes here.
-     Focus on what the AI genuinely needs to know.
-   ```
-
-3. **Add per-artifact rules** (optional):
-   ```yaml
-   rules:
-     proposal:
-       - Your proposal-specific guidance
-     specs:
-       - Your spec-writing rules
-   ```
-
-4. **Delete project.md** once you've moved everything useful.
-
-**Don't overthink it.** Start with the essentials and iterate. If you notice the AI missing something important, add it. If context feels bloated, trim it. This is a living document.
-
-### Need Help? Use This Prompt
-
-If you're unsure how to distill your project.md, ask your AI assistant:
-
-```
-I'm migrating from OpenSpec's old project.md to the new config.yaml format.
-
-Here's my current project.md:
-[paste your project.md content]
-
-Please help me create a config.yaml with:
-1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
-2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)
-
-Leave out anything generic that AI models already know. Be ruthless about brevity.
-```
-
-The AI will help you identify what's essential vs. what can be trimmed.
-
---
-
-## The New Commands
-
-Command availability is profile-dependent:
-
-**Default (`core` profile):**
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step |
-| `/opsx:explore` | Think through ideas with no structure |
-| `/opsx:apply` | Implement tasks from tasks.md |
-| `/opsx:archive` | Finalize and archive the change |
-
-**Expanded workflow (custom selection):**
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:new` | Start a new change scaffold |
-| `/opsx:continue` | Create the next artifact (one at a time) |
-| `/opsx:ff` | Fast-forward—create planning artifacts at once |
-| `/opsx:verify` | Validate implementation matches specs |
-| `/opsx:sync` | Merge delta specs into main specs |
-| `/opsx:bulk-archive` | Archive multiple changes at once |
-| `/opsx:onboard` | Guided end-to-end onboarding workflow |
-
-Enable expanded commands with `openspec config profile`, then run `openspec update`.
-
-### Command Mapping from Legacy
-
-| Legacy | OPSX Equivalent |
-|--------|-----------------|
-| `/openspec:proposal` | `/opsx:propose` (default) or `/opsx:new` then `/opsx:ff` (expanded) |
-| `/openspec:apply` | `/opsx:apply` |
-| `/openspec:archive` | `/opsx:archive` |
-
-### New Capabilities
-
-These capabilities are part of the expanded workflow command set.
-
-**Granular artifact creation:**
-```
-/opsx:continue
-```
-Creates one artifact at a time based on dependencies. Use this when you want to review each step.
-
-**Exploration mode:**
-```
-/opsx:explore
-```
-Think through ideas with a partner before committing to a change.
-
---
-
-## Understanding the New Architecture
-
-### From Phase-Locked to Fluid
-
-The legacy workflow forced linear progression:
-
-```
-┌──────────────┐      ┌──────────────┐      ┌──────────────┐
-│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
-│    PHASE     │      │    PHASE     │      │    PHASE     │
-└──────────────┘      └──────────────┘      └──────────────┘
-
-If you're in implementation and realize the design is wrong?
-Too bad. Phase gates don't let you go back easily.
-```
-
-OPSX uses actions, not phases:
-
-```
-         ┌───────────────────────────────────────────────┐
-         │           ACTIONS (not phases)                │
-         │                                               │
-         │     new ◄──► continue ◄──► apply ◄──► archive │
-         │      │          │           │             │   │
-         │      └──────────┴───────────┴─────────────┘   │
-         │                    any order                  │
-         └───────────────────────────────────────────────┘
-```
-
-### Dependency Graph
-
-Artifacts form a directed graph. Dependencies are enablers, not gates:
-
-```
-                        proposal
-                       (root node)
-                            │
-              ┌─────────────┴─────────────┐
-              │                           │
-              ▼                           ▼
-           specs                       design
-        (requires:                  (requires:
-         proposal)                   proposal)
-              │                           │
-              └─────────────┬─────────────┘
-                            │
-                            ▼
-                         tasks
-                     (requires:
-                     specs, design)
-```
-
-When you run `/opsx:continue`, it checks what's ready and offers the next artifact. You can also create multiple ready artifacts in any order.
-
-### Skills vs Commands
-
-The legacy system used tool-specific command files:
-
-```
-.claude/commands/openspec/
-├── proposal.md
-├── apply.md
-└── archive.md
-```
-
-OPSX uses the emerging **skills** standard:
-
-```
-.claude/skills/
-├── openspec-explore/SKILL.md
-├── openspec-new-change/SKILL.md
-├── openspec-continue-change/SKILL.md
-├── openspec-apply-change/SKILL.md
-└── ...
-```
-
-Skills are recognized across multiple AI coding tools and provide richer metadata.
-
---
-
-## Continuing Existing Changes
-
-Your in-progress changes work seamlessly with OPSX commands.
-
-**Have an active change from the legacy workflow?**
-
-```
-/opsx:apply add-my-feature
-```
-
-OPSX reads the existing artifacts and continues from where you left off.
-
-**Want to add more artifacts to an existing change?**
-
-```
-/opsx:continue add-my-feature
-```
-
-Shows what's ready to create based on what already exists.
-
-**Need to see status?**
-
-```bash
-openspec status --change add-my-feature
-```
-
---
-
-## The New Config System
-
-### config.yaml Structure
-
-```yaml
-# Required: Default schema for new changes
-schema: spec-driven
-
-# Optional: Project context (max 50KB)
-# Injected into ALL artifact instructions
-context: |
-  Your project background, tech stack,
-  conventions, and constraints.
-
-# Optional: Per-artifact rules
-# Only injected into matching artifacts
-rules:
-  proposal:
-    - Include rollback plan
-  specs:
-    - Use Given/When/Then format
-  design:
-    - Document fallback strategies
-  tasks:
-    - Break into 2-hour maximum chunks
-```
-
-### Schema Resolution
-
-When determining which schema to use, OPSX checks in order:
-
-1. **CLI flag**: `--schema <name>` (highest priority)
-2. **Change metadata**: `.openspec.yaml` in the change directory
-3. **Project config**: `openspec/config.yaml`
-4. **Default**: `spec-driven`
-
-### Available Schemas
-
-| Schema | Artifacts | Best For |
-|--------|-----------|----------|
-| `spec-driven` | proposal → specs → design → tasks | Most projects |
-
-List all available schemas:
-
-```bash
-openspec schemas
-```
-
-### Custom Schemas
-
-Create your own workflow:
-
-```bash
-openspec schema init my-workflow
-```
-
-Or fork an existing one:
-
-```bash
-openspec schema fork spec-driven my-workflow
-```
-
-See [Customization](customization.md) for details.
-
---
-
-## Troubleshooting
-
-### "Legacy files detected in non-interactive mode"
-
-You're running in a CI or non-interactive environment. Use:
-
-```bash
-openspec init --force
-```
-
-### Commands not appearing after migration
-
-Restart your IDE. Skills are detected at startup.
-
-### "Unknown artifact ID in rules"
-
-Check that your `rules:` keys match your schema's artifact IDs:
-
- **spec-driven**: `proposal`, `specs`, `design`, `tasks`
-
-Run this to see valid artifact IDs:
-
-```bash
-openspec schemas --json
-```
-
-### Config not being applied
-
-1. Ensure the file is at `openspec/config.yaml` (not `.yml`)
-2. Validate YAML syntax
-3. Config changes take effect immediately—no restart needed
-
-### project.md not migrated
-
-The system intentionally preserves `project.md` because it may contain your custom content. Review it manually, move useful parts to `config.yaml`, then delete it.
-
-### Want to see what would be cleaned up?
-
-Run init and decline the cleanup prompt—you'll see the full detection summary without any changes being made.
-
---
-
-## Quick Reference
-
-### Files After Migration
-
-```
-project/
-├── openspec/
-│   ├── specs/                    # Unchanged
-│   ├── changes/                  # Unchanged
-│   │   └── archive/              # Unchanged
-│   └── config.yaml               # NEW: Project configuration
-├── .claude/
-│   └── skills/                   # NEW: OPSX skills
-│       ├── openspec-propose/     # default core profile
-│       ├── openspec-explore/
-│       ├── openspec-apply-change/
-│       ├── openspec-sync-specs/
-│       └── ...                   # expanded profile adds new/continue/ff/etc.
-├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
-└── AGENTS.md                     # OpenSpec markers removed, your content preserved
-```
-
-### What's Gone
-
- `.claude/commands/openspec/` — replaced by `.claude/skills/`
- `openspec/AGENTS.md` — obsolete
- `openspec/project.md` — migrate to `config.yaml`, then delete
- OpenSpec marker blocks in `CLAUDE.md`, `AGENTS.md`, etc.
-
-### Command Cheatsheet
-
-```text
-/opsx:propose      Start quickly (default core profile)
-/opsx:apply        Implement tasks
-/opsx:archive      Finish and archive
-
-# Expanded workflow (if enabled):
-/opsx:new          Scaffold a change
-/opsx:continue     Create next artifact
-/opsx:ff           Create planning artifacts
-```
-
---
-
-## Getting Help
-
- **Discord**: [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
- **GitHub Issues**: [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
- **Documentation**: [docs/opsx.md](opsx.md) for the full OPSX reference
@@ -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
@@ -1,115 +0,0 @@
-# Multi-Language Guide
-
-Configure OpenSpec to generate artifacts in languages other than English.
-
-## Quick Setup
-
-Add a language instruction to your `openspec/config.yaml`:
-
-```yaml
-schema: spec-driven
-
-context: |
-  Language: Portuguese (pt-BR)
-  All artifacts must be written in Brazilian Portuguese.
-
-  # Your other project context below...
-  Tech stack: TypeScript, React, Node.js
-```
-
-That's it. All generated artifacts will now be in Portuguese.
-
-## Language Examples
-
-### Portuguese (Brazil)
-
-```yaml
-context: |
-  Language: Portuguese (pt-BR)
-  All artifacts must be written in Brazilian Portuguese.
-```
-
-### Spanish
-
-```yaml
-context: |
-  Idioma: Español
-  Todos los artefactos deben escribirse en español.
-```
-
-### Chinese (Simplified)
-
-```yaml
-context: |
-  语言：中文（简体）
-  所有产出物必须用简体中文撰写。
-```
-
-### Japanese
-
-```yaml
-context: |
-  言語：日本語
-  すべての成果物は日本語で作成してください。
-```
-
-### French
-
-```yaml
-context: |
-  Langue : Français
-  Tous les artefacts doivent être rédigés en français.
-```
-
-### German
-
-```yaml
-context: |
-  Sprache: Deutsch
-  Alle Artefakte müssen auf Deutsch verfasst werden.
-```
-
-## Tips
-
-### 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
-  - 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
-```
-
-## Verification
-
-To verify your language config is working:
-
-```bash
-# Check the instructions - should show your language context
-openspec instructions proposal --change my-change
-
-# Output will include your language context
-```
-
-## Related Documentation
-
- [Customization Guide](./customization.md) - Project configuration options
- [Workflows Guide](./workflows.md) - Full workflow documentation
@@ -1,91 +0,0 @@
-# Core Concepts at a Glance
-
-**OpenSpec is a lightweight agreement layer between you and your AI.** You write down what a change should do, the AI drafts the details, you both look at the same plan, and only then does code get written. This page is the whole mental model on one screen. When you want the long version, [Concepts](concepts.md) has it.
-
-Here's the entire idea in five words: **agree first, then build confidently.**
-
-## The five ideas
-
-Everything in OpenSpec is built from five concepts. Learn these and the rest is detail.
-
-**1. Specs are the truth.** A spec describes how your system behaves *right now*. It lives in `openspec/specs/`, organized by domain (`auth/`, `payments/`, `ui/`). Specs are made of requirements ("the system SHALL expire sessions after 30 minutes") and scenarios (concrete given/when/then examples). Think of specs as the single agreed-upon answer to "what does this software do?"
-
-**2. A change is one unit of work.** When you want to add, modify, or remove behavior, you create a change: a folder in `openspec/changes/` holding everything about that work in one place. A proposal, a design, a task list, and the spec edits. One change, one folder, one feature.
-
-**3. Delta specs describe what's changing, not the whole world.** Inside a change, you don't rewrite the entire spec. You write a small delta: `ADDED` this requirement, `MODIFIED` that one, `REMOVED` this other one. This is the trick that makes OpenSpec good at editing existing systems, not just green-field ones. You describe the diff, not the destination.
-
-**4. Artifacts build on each other.** A change contains a few documents, created in a natural order, each feeding the next:
-
-```text
-proposal ──► specs ──► design ──► tasks ──► implement
-   why        what       how       steps      do it
-```
-
-You can revisit any of them at any time. They're enablers, not gates. (More on that below.)
-
-**5. Archiving folds the change back into the truth.** When the work is done, you archive the change. Its delta specs merge into your main specs, and the change folder moves to `changes/archive/` with a date stamp. Now your specs describe the new reality, and you're ready for the next change. The cycle closes.
-
-## The picture
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                          openspec/                              │
-│                                                                 │
-│   ┌──────────────────┐         ┌──────────────────────────┐    │
-│   │     specs/       │         │        changes/          │    │
-│   │                  │ ◄─────  │                          │    │
-│   │ source of truth  │  merge  │ one folder per change    │    │
-│   │ how things work  │  on     │ proposal · design ·      │    │
-│   │ today            │ archive │ tasks · delta specs      │    │
-│   └──────────────────┘         └──────────────────────────┘    │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-Two folders. `specs/` is what's true. `changes/` is what you're proposing. Archiving moves a proposal into truth.
-
-## The loop you'll actually run
-
-In the default setup, your day looks like this. Optionally think it through first; then one command drafts the plan, you read it, the next builds it, and the last files it away.
-
-```text
-/opsx:explore                   →  (optional) think it through with the AI first
-/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
-        (you read and adjust the plan)
-/opsx:apply                     →  AI builds it, checking off tasks
-/opsx:archive                   →  specs updated, change archived
-```
-
-**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any artifact exists. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md).
-
-Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion.
-
-## "Enablers, not gates"
-
-This phrase shows up everywhere in OpenSpec, so here's what it means in plain terms.
-
-Old-school spec processes are waterfalls: finish planning, *then* you're allowed to implement, and going back is painful. OpenSpec refuses that. The order `proposal → specs → design → tasks` shows what becomes *possible* next, not what you're *forced* to do next.
-
-Discover during implementation that the design was wrong? Edit `design.md` and keep going. Realize the scope should shrink? Update the proposal. Nothing locks. The dependencies exist only so the AI has the context it needs (you can't write good tasks without specs to base them on), not to box you in.
-
-The strength here is honesty: real work is messy and iterative, and OpenSpec lets it be. The tradeoff is discipline: because nothing forces you forward, it's on you to keep a change focused rather than letting it sprawl. The [Workflows](workflows.md) guide has good habits for that.
-
-## Why this is worth the small overhead
-
-Plain truth: OpenSpec adds a step. You write a short plan before building. So what do you get for it?
-
- **You catch wrong turns before they cost you.** Fixing a misunderstanding in a one-paragraph proposal is free. Fixing it after the AI wrote 400 lines is not.
- **The plan and the code stay in the same repo.** Six months later, the spec tells you (and the next AI session) why the system works the way it does.
- **Changes are reviewable.** A change folder is a tidy package: read the proposal, skim the deltas, check the tasks. No archaeology through chat history.
- **It fits existing codebases.** Deltas mean you can specify a change to a 50,000-line app without first documenting the whole thing.
-
-And the honest tradeoff: for a truly trivial one-line fix, the ceremony may not pay off, and that's fine. OpenSpec is designed to be lightweight, but it isn't free. Use it where agreement matters, which turns out to be most of the time once you're working with an AI that will confidently build whatever you vaguely asked for.
-
-## Where to go next
-
- New here? [Getting Started](getting-started.md) walks the first change in full.
- Not sure what to build yet? [Explore First](explore.md) is the place to start.
- Confused about where commands run? [How Commands Work](how-commands-work.md).
- Want the deep version of everything above? [Concepts](concepts.md).
- Learn by example? [Examples & Recipes](examples.md).
- Need a term defined? [Glossary](glossary.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
@@ -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 |
@@ -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 |
@@ -1,341 +0,0 @@
-# Stores: Plan in Its Own Repo
-
-> **Beta.** Stores, references, working context, and worksets are
-> new. Command names, flags, file formats, and JSON output may still change
-> shape between releases. Every walkthrough below was run against the
-> current build, but re-read this guide after upgrading.
-
-## The problem this solves
-
-OpenSpec normally lives inside one code repo: an `openspec/` folder next to
-your code, holding specs and changes for that repo.
-
-That stops fitting the moment your planning is bigger than one repo:
-
- Your work spans several repos — one feature touches the API server, the
-  web app, and a shared library. Whose `openspec/` folder does the plan
-  live in?
- Your team plans before code exists, or plans things that never become
-  code in *this* repo.
- Requirements are owned by one team and consumed by others. The wiki
-  version drifts, and your coding agent can't read it anyway.
-
-A **store** is the answer: a standalone repo whose whole job is planning.
-It has the same `openspec/` shape you already know — specs and changes —
-plus a small identity file. You register it on your machine once, by name,
-and then every normal OpenSpec command can work in it from anywhere.
-
-## The shape
-
-```
-            team-plans  (a store: planning in its own repo)
-            ├── .openspec-store/store.yaml     identity: "I am team-plans"
-            └── openspec/
-                ├── specs/      what is true
-                └── changes/    what is in motion
-                      ▲
-                      │ registered on each machine by name;
-                      │ shared by pushing/cloning like any repo
-        ┌─────────────┼─────────────┐
-        │             │             │
-    web-app       api-server     mobile-app
-   (code repo)   (code repo)    (code repo)
-```
-
-Two rules keep this simple:
-
-1. **A store is just a git repo.** You commit, push, pull, and review it
-   yourself. OpenSpec never clones, syncs, or pushes anything on its own.
-2. **Declarations, not machinery.** Repos can *declare* how they relate to
-   stores (shown below). Declarations change what OpenSpec can tell you —
-   never where your commands act.
-
-## Five minutes to your first store
-
-Two commands take you from nothing to a working, store-scoped change:
-
-```bash
-openspec store setup team-plans --path ~/openspec/team-plans
-```
-
-```
-Store ready: team-plans
-Location: /Users/you/openspec/team-plans
-OpenSpec root: ready
-Registry: registered
-
-Next: run normal OpenSpec commands against this store, for example:
-  openspec new change <change-id> --store team-plans
-Share this store by committing and pushing it like any Git repo.
-```
-
-```bash
-openspec new change add-login --store team-plans
-```
-
-```
-Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
-Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
-Schema: spec-driven
-Next: openspec status --change add-login --store team-plans
-```
-
-That's the whole model. From here the lifecycle is exactly what you know —
-`status`, `instructions`, `validate`, `archive` — with `--store team-plans`
-on each command, and every printed hint carries the flag for you. The
-`Using OpenSpec root:` line always tells you where a command is acting.
-
-## Story: one team, one planning repo
-
-A team keeps its specs and changes in `team-plans` instead of scattering
-them across code repos.
-
-**Day one (whoever sets it up):**
-
-```bash
-openspec store setup team-plans --path ~/openspec/team-plans \
-  --remote git@github.com:acme/team-plans.git
-git -C ~/openspec/team-plans push -u origin main
-```
-
-Passing `--remote` records the clone URL inside the store's own identity
-file (`.openspec-store/store.yaml`), in the initial commit. Every future
-clone is born knowing where it came from, so health checks and error
-messages can print a complete, pasteable fix for teammates who don't have
-it yet.
-
-**Every teammate (once per machine):**
-
-```bash
-git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
-openspec store register ~/openspec/team-plans
-```
-
-From then on, everyone works in the same planning repo by name:
-
-```bash
-openspec status --store team-plans --change add-login
-openspec show add-login --store team-plans
-```
-
-**Sharing work is git, on purpose.** A change you create exists only in
-your checkout until you commit and push it — same as code. Plans get
-branches, pull requests, and review for free, because a store is an
-ordinary repo.
-
-**Connecting the team's code repos.** A code repo whose planning is fully
-externalized needs exactly one line, in `openspec/config.yaml`:
-
-```yaml
-# web-app/openspec/config.yaml
-store: team-plans
-```
-
-Now every OpenSpec command run inside `web-app` acts on `team-plans` with
-no flags at all:
-
-```bash
-cd ~/src/web-app
-openspec status --change add-login
-```
-
-```
-Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
-...
-```
-
-The pointer is a fallback, never an override: an explicit `--store` always
-wins, and if the repo grows real planning folders of its own, those win
-(with a warning to remove the stale pointer).
-
-## Story: requirements that cross team lines
-
-A platform team owns the requirements. Product teams build against them,
-in their own repos, with their own designs. A reference describes that
-relationship without moving anyone's work.
-
-```
-   platform-reqs (store)                 api-server (code repo)
-   owned by the platform team            owned by a product team
-   ┌──────────────────────────┐          ┌──────────────────────────┐
-   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
-   │   payments/spec.md       │ reads    │   references:            │
-   │   auth/spec.md           │          │     - platform-reqs      │
-   │                          │          │ openspec/specs/          │
-   │ openspec/changes/        │          │   (their own designs)    │
-   │   platform work          │          │ openspec/changes/        │
-   │                          │          │   (their own work)       │
-   │                          │          └──────────────────────────┘
-   └──────────────────────────┘
-```
-
-**The product team declares what it draws on** in its repo's
-`openspec/config.yaml`:
-
-```yaml
-references:
-  - platform-reqs
-```
-
-References are read-only context. The repo keeps its own `openspec/` root;
-work stays there. What changes: `openspec instructions` in that repo now
-includes an index of the referenced store's specs — each with a one-line
-summary and the exact fetch command (`openspec show <spec-id> --type spec
--store platform-reqs`). An agent working in `api-server` can find the
-upstream payment requirements, cite them, and write its low-level design in
-the repo's own root — without anyone pasting context around.
-
-A reference can carry its clone source, so teammates who don't have the
-store yet get a complete fix instead of a dead end:
-
-```yaml
-references:
-  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }
-```
-
-**When you want the plan and code open together, make a workset.** This is
-personal and explicit: each person chooses the folders they actually work
-with on their machine. Nothing about those local checkout paths is
-committed to the shared planning repo.
-
-```bash
-openspec workset create platform \
-  --member ~/openspec/platform-reqs \
-  --member ~/src/api-server \
-  --member ~/src/web-app
-```
-
-## Two questions you can always ask
-
-**"Is my setup healthy?"** — `openspec doctor` checks the current root and
-its referenced stores, read-only, with a pasteable fix per finding:
-
-```
-Doctor
-
-Root
-  Location: /Users/you/src/api-server
-  OpenSpec root: ok
-
-References
-  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
-  - design-system: Referenced store 'design-system' is not registered on this machine.
-    Fix: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' && openspec store register '/Users/you/openspec/design-system' --id design-system
-
-```
-
-**"What am I working with?"** — `openspec context` assembles the working
-set from OpenSpec declarations: the root and the stores it references.
-
-```
-Working context for api-server (/Users/you/src/api-server)
-
-OpenSpec root
-  api-server  /Users/you/src/api-server
-
-Referenced stores
-  platform-reqs  /Users/you/openspec/platform-reqs
-    Fetch: openspec show <spec-id> --type spec --store platform-reqs
-```
-
-Both support `--json` for agents. `openspec context --code-workspace
-<path>` additionally writes a VS Code workspace file containing the whole
-set — the only write this command performs.
-
-## Worksets: reopen the folders you work on together
-
-Separate from all of the above: most people open the same few folders
-together every session — the planning repo plus two or three code repos.
-A **workset** is a personal, named view of exactly that, reopened with one
-command in your tool of choice.
-
-```
-  workset "platform"                 openspec workset open platform
-  ├── team-plans   ~/openspec/team-plans         │
-  ├── api-server   ~/src/api-server              ▼
-  └── web-app      ~/src/web-app       all three open in your tool
-```
-
-```bash
-openspec workset create platform \
-  --member ~/openspec/team-plans --member ~/src/api-server \
-  --tool code
-openspec workset list
-```
-
-```
-platform  (opens in VS Code)
-  team-plans  /Users/you/openspec/team-plans
-  api-server  /Users/you/src/api-server
-```
-
-`openspec workset open platform` then launches the saved tool: editors
-(VS Code, Cursor) open one window with every member and return. The first
-member is the primary. Override the tool any time with `--tool <id>`.
-
-Worksets are deliberately *not* shared state. They live on your machine,
-are never committed, and make no claims about the work — they only record
-what you like open together. Removing one never touches the member
-folders. New tools are configuration, not code: anything launched via a
-workspace file or per-folder attach flags can be added under the `openers`
-key in the global config (`openspec config edit`).
-
-## How commands decide where to act
-
-Every normal command resolves its root the same way, in this order:
-
-```
-1. --store <id>          you said so explicitly        → that store
-2. nearest openspec/     a real planning root here     → this repo
-   (walking up from cwd)
-3. store: pointer        config.yaml declares a store  → that store
-4. none of the above     stores registered on this     → error with a
-                         machine?                        selection hint
-                         no stores registered?         → the current
-                                                          directory
-                                                          (classic behavior)
-```
-
-The `Using OpenSpec root:` line (and the `root` block in `--json` output)
-tells you which case you're in.
-
-## Known limitations
-
- **Beta shape.** Everything on this page may change between releases —
-  names, flags, file formats, JSON keys.
- **One checkout per store id per machine.** Registering a second checkout
-  under the same id fails with a hint to `store unregister` first.
- **No sync, ever — by design.** OpenSpec never clones, pulls, or pushes.
-  A stale checkout shows stale specs until *you* pull; references are
-  indexed live from whatever is on disk.
- **Some commands stay where they are.** `view`, `templates`, `schemas`,
-  and the deprecated noun forms (`openspec change show`, ...) act on the
-  current directory only — no `--store`.
- **Per-machine state is per-machine.** The store registry and worksets
-  are local settings. Nothing about your machine's layout is
-  ever committed to shared planning.
- **Two launch styles for worksets.** A tool that can't be launched with a
-  workspace file or per-folder attach flags can't be added as an opener.
- **Agent JSON has a known casing split** (store-family keys are
-  snake_case, workflow-family camelCase). Documented in the
-  [agent contract](../agent-contract.md); unifying it is deferred to a
-  versioned release.
-
-## Where things live
-
-| What | Where | Shared? |
-|---|---|---|
-| A store's planning | `<store>/openspec/` (specs, changes) | Yes — commit and push it |
-| A store's identity | `<store>/.openspec-store/store.yaml` | Yes — committed with the store |
-| The store registry | `<data dir>/openspec/stores/registry.yaml` | No — this machine only |
-| Worksets | `<data dir>/openspec/worksets/` | No — this machine only |
-
-`<data dir>` is `~/.local/share/openspec` on macOS and Linux (or
-`$XDG_DATA_HOME/openspec` when set), and `%LOCALAPPDATA%\openspec` on
-Windows.
-
-## Reference
-
-Exact flags and JSON shapes for every command on this page:
-[CLI reference](../cli.md) (Stores, Doctor, Working context, Personal
-worksets) and the [agent contract](../agent-contract.md).
@@ -1,112 +0,0 @@
-# Supported Tools
-
-OpenSpec works with many AI coding assistants. When you run `openspec init`, OpenSpec configures selected tools using your active profile/workflow selection and delivery mode.
-
-## How It Works
-
-For each selected tool, OpenSpec can install:
-
-1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md`
-2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files
-
-By default, OpenSpec uses the `core` profile, which includes:
- `propose`
- `explore`
- `apply`
- `sync`
- `archive`
-
-You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`) via `openspec config profile`, then run `openspec update`.
-
-## Tool Directory Reference
-
-| Tool (ID) | Skills path pattern | Command path pattern |
-|-----------|---------------------|----------------------|
-| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-<id>.md` |
-| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-<id>.md` |
-| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-<id>.md` |
-| IBM Bob Shell (`bob`) | `.bob/skills/openspec-*/SKILL.md` | `.bob/commands/opsx-<id>.md` |
-| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
-| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
-| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
-| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
-| ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
-| Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
-| CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-<id>.md` |
-| Crush (`crush`) | `.crush/skills/openspec-*/SKILL.md` | `.crush/commands/opsx/<id>.md` |
-| Cursor (`cursor`) | `.cursor/skills/openspec-*/SKILL.md` | `.cursor/commands/opsx-<id>.md` |
-| Factory Droid (`factory`) | `.factory/skills/openspec-*/SKILL.md` | `.factory/commands/opsx-<id>.md` |
-| Gemini CLI (`gemini`) | `.gemini/skills/openspec-*/SKILL.md` | `.gemini/commands/opsx/<id>.toml` |
-| GitHub Copilot (`github-copilot`) | `.github/skills/openspec-*/SKILL.md` | `.github/prompts/opsx-<id>.prompt.md`\*\* |
-| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-<id>.md` |
-| Junie (`junie`) | `.junie/skills/openspec-*/SKILL.md` | `.junie/commands/opsx-<id>.md` |
-| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-<id>.md` |
-| Kimi CLI (`kimi`) | `.kimi/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
-| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
-| Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
-| Mistral Vibe (`vibe`) | `.vibe/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
-| OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/commands/opsx-<id>.md` |
-| Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-<id>.md` |
-| Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/<id>.md` |
-| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-<id>.toml` |
-| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
-| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
-| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-<id>.md` |
-
-\* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory.
-
-\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.
-
-## Non-Interactive Setup
-
-For CI/CD or scripted setup, use `--tools` (and optionally `--profile`):
-
-```bash
-# Configure specific tools
-openspec init --tools claude,cursor
-
-# Configure all supported tools
-openspec init --tools all
-
-# Skip tool configuration
-openspec init --tools none
-
-# Override profile for this init run
-openspec init --profile core
-```
-
-**Available tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `vibe`, `windsurf`
-
-## Workflow-Dependent Installation
-
-OpenSpec installs workflow artifacts based on selected workflows:
-
- **Core profile (default):** `propose`, `explore`, `apply`, `sync`, `archive`
- **Custom selection:** any subset of all workflow IDs:
-  `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`
-
-In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed.
-
-## Generated Skill Names
-
-When selected by profile/workflow config, OpenSpec generates these skills:
-
- `openspec-propose`
- `openspec-explore`
- `openspec-new-change`
- `openspec-continue-change`
- `openspec-apply-change`
- `openspec-ff-change`
- `openspec-sync-specs`
- `openspec-archive-change`
- `openspec-bulk-archive-change`
- `openspec-verify-change`
- `openspec-onboard`
-
-See [Commands](commands.md) for command behavior and [CLI](cli.md) for `init`/`update` options.
-
-## Related
-
- [CLI Reference](cli.md) — Terminal commands
- [Commands](commands.md) — Slash commands and skills
- [Getting Started](getting-started.md) — First-time setup
@@ -1,166 +0,0 @@
-# Troubleshooting
-
-Concrete fixes for concrete problems. Each entry names a symptom, explains the likely cause in a sentence, and gives you the fix. If you don't see your issue here, the [FAQ](faq.md) may help, and the [Discord](https://discord.gg/YctCnvvshC) definitely will.
-
-## Installation and setup
-
-### `openspec: command not found`
-
-The CLI isn't installed, or your shell can't find it. Install it globally and check:
-
-```bash
-npm install -g @fission-ai/openspec@latest
-openspec --version
-```
-
-If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm bin -g` to see where global binaries live, and make sure that path is in your shell profile.
-
-### "Requires Node.js 20.19.0 or higher"
-
-OpenSpec runs on Node 20.19.0+. Check your version and upgrade if needed:
-
-```bash
-node --version
-```
-
-If you use bun to install OpenSpec, note that OpenSpec still *runs* on Node, so you need Node 20.19.0+ available on your `PATH` regardless. See [Installation](installation.md).
-
-### `openspec init` didn't configure my AI tool
-
-Init asks which tools to set up. If you skipped your tool or want to add another, just run it again, or use the non-interactive form:
-
-```bash
-openspec init --tools claude,cursor
-```
-
-The full list of tool IDs is in [Supported Tools](supported-tools.md). Use `--tools all` for everything, `--tools none` to skip tool setup.
-
-## Commands don't show up
-
-If `/opsx:propose` (or your tool's equivalent) doesn't appear or doesn't do anything, work down this list. They're ordered fastest-to-check first.
-
-1. **You may be in the wrong place.** Slash commands go in your AI assistant's chat, not your terminal. If you typed `/opsx:propose` into your shell, that's the issue. See [How Commands Work](how-commands-work.md).
-
-2. **Regenerate the files.** From your project root:
-
-   ```bash
-   openspec update
-   ```
-
-   This rewrites the skill and command files for every tool you've configured.
-
-3. **Restart your assistant.** Most tools scan for skills and commands at startup. A fresh window often does it.
-
-4. **Confirm the files exist.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories, all listed in [Supported Tools](supported-tools.md).
-
-5. **Check you initialized this project.** Skills are written per project. If you cloned a repo or switched folders, run `openspec init` (or `openspec update`) there.
-
-6. **Confirm your tool supports command files.** A few tools (Kimi CLI, Trae, ForgeCode, Mistral Vibe) don't get generated `opsx-*` command files; they use skill-based invocations instead. The forms differ per tool: see [Supported Tools](supported-tools.md) and [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool).
-
-## Working with changes
-
-### "Change not found"
-
-The command couldn't tell which change you meant. Name it explicitly, or check what exists:
-
-```bash
-openspec list                    # see active changes
-/opsx:apply add-dark-mode        # name the change in chat
-```
-
-Also confirm you're in the right project directory.
-
-### "No artifacts ready"
-
-Every artifact is either already created or blocked waiting on a dependency. See what's blocking:
-
-```bash
-openspec status --change <name>
-```
-
-Then create the missing dependency first. Remember the order: proposal enables specs and design; specs and design together enable tasks.
-
-### `openspec validate` reports warnings or errors
-
-Validation checks your specs and changes for structural problems. Read the message: it names the file and the issue.
-
-```bash
-openspec validate <name>           # validate one item
-openspec validate --all            # validate everything
-openspec validate --all --strict   # stricter checks, good for CI
-```
-
-Common causes are a missing required section (like a spec with no scenarios) or a malformed delta header. Fix the file and re-run. The [CLI reference](cli.md#openspec-validate) documents the output format.
-
-### The AI created incomplete or wrong artifacts
-
-The AI didn't have enough context. A few levers help:
-
- Add project context in `openspec/config.yaml` so your stack and conventions are injected into every request. See [Customization](customization.md#project-configuration).
- Add per-artifact `rules:` for guidance that only applies to, say, specs.
- Give a more detailed description when you propose.
- Use the expanded `/opsx:continue` to create one artifact at a time and review each, instead of `/opsx:ff` doing them all at once.
-
-### Archive won't finish, or warns about incomplete tasks
-
-Archive won't *block* on incomplete tasks, but it warns you, because archiving usually means the work is done. If tasks remain on purpose (you're filing a partial change), proceed. Otherwise finish the tasks first. Archive will also offer to sync your delta specs into the main specs if you haven't synced yet; say yes unless you have a reason not to.
-
-## Configuration
-
-### My `config.yaml` isn't being applied
-
-Three usual suspects:
-
-1. **Wrong filename.** It must be `openspec/config.yaml`, not `.yml`.
-2. **Invalid YAML.** Run it through any YAML validator; the CLI also reports syntax errors with line numbers.
-3. **You expected a restart.** You don't need one. Config changes take effect immediately.
-
-### "Unknown artifact ID in rules: X"
-
-A key under `rules:` doesn't match any artifact in your schema. For the default `spec-driven` schema the valid IDs are `proposal`, `specs`, `design`, `tasks`. To see the IDs for any schema:
-
-```bash
-openspec schemas --json
-```
-
-### "Context too large"
-
-The `context:` field is capped at 50KB, on purpose, because it's injected into every request. Summarize it, or link out to longer docs instead of pasting them. Lean context also produces better, faster results.
-
-### "Schema not found"
-
-The schema name you referenced doesn't exist. List what's available and check spelling:
-
-```bash
-openspec schemas                    # list available schemas
-openspec schema which <name>        # see where a schema resolves from
-openspec schema init <name>         # create a custom one
-```
-
-See [Customization](customization.md#custom-schemas).
-
-## Migration from the legacy workflow
-
-### "Legacy files detected in non-interactive mode"
-
-You're in CI or a non-interactive shell, and OpenSpec found old files to clean up but can't prompt you. Approve automatically:
-
-```bash
-openspec init --force
-```
-
-### Commands didn't appear after migrating
-
-Restart your IDE. Skills are detected at startup. If they still don't appear, run `openspec update` and check the file locations in [Supported Tools](supported-tools.md).
-
-### My old `project.md` wasn't migrated
-
-That's intentional. OpenSpec never deletes `project.md` automatically because it may hold context you wrote. Move the useful parts into `config.yaml`'s `context:` section, then delete it yourself. The [Migration Guide](migration-guide.md#migrating-projectmd-to-configyaml) walks through this, including a prompt you can hand to your AI to do the distilling.
-
-## Still stuck?
-
- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
- **From your terminal:** `openspec feedback "what went wrong"` opens an issue for you.
-
-When you report a problem, include your OpenSpec version (`openspec --version`), your Node version (`node --version`), your AI tool, and the exact command and output. It makes help much faster.
@@ -1,479 +0,0 @@
-# Workflows
-
-This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see [Getting Started](getting-started.md). For command reference, see [Commands](commands.md).
-
-## Philosophy: Actions, Not Phases
-
-Traditional workflows force you through phases: planning, then implementation, then done. But real work doesn't fit neatly into boxes.
-
-OPSX takes a different approach:
-
-```text
-Traditional (phase-locked):
-
-  PLANNING ────────► IMPLEMENTING ────────► DONE
-      │                    │
-      │   "Can't go back"  │
-      └────────────────────┘
-
-OPSX (fluid actions):
-
-  proposal ──► specs ──► design ──► tasks ──► implement
-```
-
-**Key principles:**
-
- **Actions, not phases** - Commands are things you can do, not stages you're stuck in
- **Dependencies are enablers** - They show what's possible, not what's required next
-
-> **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
-
-## Two Modes
-
-### Default Quick Path (`core` profile)
-
-New installs default to `core`, which provides:
- `/opsx:explore`
- `/opsx:propose`
- `/opsx:apply`
- `/opsx:sync`
- `/opsx:archive`
-
-Typical flow:
-
-```text
-/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-  (optional)
-```
-
-#### Start by exploring (the habit worth forming)
-
-`/opsx:explore` is part of the default profile, not an advanced add-on. It's the move to make whenever you have a problem but not yet a plan, which, with an AI assistant, is most of the time.
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: Our search results feel stale. I'm not sure if it's caching,
-     indexing, or the query itself.
-
-AI:  Let me look... [reads the search service and cache layer]
-     It's the index: it only rebuilds nightly, so edits don't show
-     up until the next day. Two options: rebuild on write (simple,
-     more load) or a short-TTL cache invalidation (more moving parts,
-     less load). Given your write volume is low, rebuild-on-write is
-     the cleaner fix. Want to scope it?
-
-You: Yes.
-
-You: /opsx:propose rebuild-search-index-on-write
-```
-
-Explore creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md).
-
-### Expanded/Full Workflow (custom selection)
-
-If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with:
-
-```bash
-openspec config profile
-openspec update
-```
-
-## Workflow Patterns (Expanded Mode)
-
-### Quick Feature
-
-When you know what you want to build and just need to execute:
-
-```text
-/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
-```
-
-**Example conversation:**
-
-```text
-You: /opsx:new add-logout-button
-
-AI:  Created openspec/changes/add-logout-button/
-     Ready to create: proposal
-
-You: /opsx:ff
-
-AI:  Creating all planning artifacts...
-     ✓ proposal.md
-     ✓ specs/
-     ✓ design.md
-     ✓ tasks.md
-     Ready for implementation!
-
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ Added logout button to header
-     ✓ Implemented session clearing
-     ✓ Added confirmation dialog
-     All tasks complete!
-
-You: /opsx:archive
-
-AI:  ✓ Merged specs
-     ✓ Archived change
-```
-
-**Best for:** Small to medium features, bug fixes, straightforward changes.
-
-### Exploratory
-
-When requirements are unclear or you need to investigate first:
-
-```text
-/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
-```
-
-**Example conversation:**
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: I want to improve page load performance but I'm not sure
-     where the bottlenecks are.
-
-AI:  Let me help investigate...
-     [Analyzes bundle sizes, identifies slow queries, reviews
-     component render patterns]
-
-     I found three main bottlenecks:
-     1. Large unoptimized images
-     2. Synchronous data fetching in ProductList
-     3. Re-renders from context changes
-
-     Which would you like to address first?
-
-You: Let's tackle the data fetching issue.
-
-You: /opsx:new optimize-product-list-fetching
-
-AI:  Created change. Ready to create: proposal
-
-You: /opsx:continue
-
-AI:  Creating proposal based on our exploration...
-     [Writes proposal incorporating investigation insights]
-
-     Ready to create: specs, design
-     Which would you like next?
-
-You: /opsx:continue
-
-AI:  Creating specs...
-```
-
-**Best for:** Performance optimization, debugging, architectural decisions, unclear requirements.
-
-### Parallel Changes
-
-Work on multiple changes at once:
-
-```text
-Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
-                                         │
-                                    context switch
-                                         │
-Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply
-```
-
-**Example conversation:**
-
-```text
-You: I'm working on add-dark-mode but got pulled into a bug fix
-
-You: /opsx:new fix-login-redirect
-
-AI:  Created openspec/changes/fix-login-redirect/
-
-You: /opsx:ff
-
-AI:  ✓ Created planning artifacts
-
-You: /opsx:apply
-
-AI:  Working on fix-login-redirect...
-     [Implements the fix]
-     All tasks complete!
-
-You: /opsx:archive
-
-AI:  ✓ Archived fix-login-redirect
-
-You: Let's get back to dark mode
-
-You: /opsx:apply add-dark-mode
-
-AI:  Resuming add-dark-mode...
-     Picking up at task 2.3: Update Header...
-```
-
-**Best for:** Parallel work streams, urgent interrupts, team collaboration.
-
-When you have multiple completed changes, use `/opsx:bulk-archive`:
-
-```text
-You: /opsx:bulk-archive
-
-AI:  Found 3 completed changes:
-     - add-dark-mode (all tasks done)
-     - fix-login-redirect (all tasks done)
-     - update-footer (all tasks done)
-
-     Checking for spec conflicts...
-     ⚠ add-dark-mode and update-footer both touch specs/ui/
-
-     Inspecting codebase to resolve...
-     Both changes are implemented. Will apply in chronological order.
-
-     Archive all 3 changes?
-
-You: Yes
-
-AI:  ✓ Archived add-dark-mode
-     ✓ Archived fix-login-redirect
-     ✓ Archived update-footer
-     Specs merged in order: add-dark-mode → update-footer
-```
-
-Bulk archive detects when multiple changes touch the same specs and resolves conflicts by checking what's actually implemented.
-
-### Completing a Change
-
-The recommended completion flow:
-
-```text
-/opsx:apply ──► /opsx:verify ──► /opsx:archive
-                    │                 │
-              validates          prompts to sync
-              implementation     if needed
-```
-
-#### Verify: Check Your Work
-
-`/opsx:verify` validates implementation against your artifacts across three dimensions:
-
-```text
-You: /opsx:verify
-
-AI:  Verifying add-auth...
-
-     COMPLETENESS
-     ✓ All 12 tasks in tasks.md are checked
-     ✓ All requirements in specs have corresponding code
-     ⚠ Scenario "Session timeout after inactivity" not tested
-
-     CORRECTNESS
-     ✓ Implementation matches spec intent
-     ✓ Edge cases from scenarios are handled
-     ✓ Error states match spec definitions
-
-     COHERENCE
-     ✓ Design decisions reflected in code structure
-     ✓ Naming conventions consistent with design.md
-     ⚠ Design mentions "event-driven" but implementation uses polling
-
-     SUMMARY
-     ─────────────────────────────
-     Critical issues: 0
-     Warnings: 2
-     Ready to archive: Yes (with warnings)
-
-     Recommendations:
-     1. Add test for session timeout scenario
-     2. Consider refactoring to event-driven as designed, or update design.md
-```
-
-**What verify checks:**
-
-| Dimension | What it validates |
-|-----------|------------------|
-| Completeness | All tasks done, all requirements implemented, scenarios covered |
-| Correctness | Implementation matches spec intent, edge cases handled |
-| Coherence | Design decisions reflected in code, patterns consistent |
-
-Verify won't block archive, but it surfaces issues you might want to address first.
-
-#### Archive: Finalize the Change
-
-`/opsx:archive` completes the change and moves it to the archive:
-
-```text
-You: /opsx:archive
-
-AI:  Archiving add-auth...
-
-     Artifact status:
-     ✓ proposal.md exists
-     ✓ specs/ exists
-     ✓ design.md exists
-     ✓ tasks.md exists (12/12 tasks complete)
-
-     Delta specs: Not yet synced to main
-     → Would you like to sync now?
-
-You: Yes
-
-AI:  ✓ Synced specs to openspec/specs/auth/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/
-
-     Change archived successfully.
-```
-
-Archive will prompt if specs aren't synced. It won't block on incomplete tasks, but it will warn you.
-
-## When to Use What
-
-### `/opsx:ff` vs `/opsx:continue`
-
-| Situation | Use |
-|-----------|-----|
-| Clear requirements, ready to build | `/opsx:ff` |
-| Exploring, want to review each step | `/opsx:continue` |
-| Want to iterate on proposal before specs | `/opsx:continue` |
-| Time pressure, need to move fast | `/opsx:ff` |
-| Complex change, want control | `/opsx:continue` |
-
-**Rule of thumb:** If you can describe the full scope upfront, use `/opsx:ff`. If you're figuring it out as you go, use `/opsx:continue`.
-
-### When to Update vs Start Fresh
-
-A common question: when is updating an existing change okay, and when should you start a new one?
-
-**Update the existing change when:**
-
- Same intent, refined execution
- Scope narrows (MVP first, rest later)
- Learning-driven corrections (codebase isn't what you expected)
- Design tweaks based on implementation discoveries
-
-**Start a new change when:**
-
- Intent fundamentally changed
- Scope exploded to different work entirely
- Original change can be marked "done" standalone
- Patches would confuse more than clarify
-
-```text
-                     ┌─────────────────────────────────────┐
-                     │     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
-```
-
-**Example: "Add dark mode"**
-
- "Need to also support custom themes" → New change (scope exploded)
- "System preference detection is harder than expected" → Update (same intent)
- "Let's ship toggle first, add preferences later" → Update then archive, then new change
-
-## Best Practices
-
-### Keep Changes Focused
-
-One logical unit of work per change. If you're doing "add feature X and also refactor Y", consider two separate changes.
-
-**Why it matters:**
- Easier to review and understand
- Cleaner archive history
- Can ship independently
- Simpler rollback if needed
-
-### Use `/opsx:explore` for Unclear Requirements
-
-Before committing to a change, explore the problem space:
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: How should we handle rate limiting for our API?
-
-AI:  Let me investigate your current setup and options...
-     [Researches codebase, considers patterns]
-
-     I see three approaches we could take:
-     1. Middleware-based (simple, per-endpoint)
-     2. Redis-backed (scalable, shared state)
-     3. Token bucket per user (fair, complex)
-
-     Your current stack suggests #1 or #2. What's your scale?
-```
-
-Exploration clarifies thinking before you create artifacts.
-
-### Verify Before Archiving
-
-Use `/opsx:verify` to check implementation matches artifacts:
-
-```text
-You: /opsx:verify
-
-AI:  Verifying add-dark-mode...
-
-     ✓ All tasks in tasks.md are checked
-     ✓ Requirements in specs have corresponding code
-     ✓ Design decisions are reflected in implementation
-
-     Ready to archive!
-```
-
-Catches mismatches before you close out the change.
-
-### Name Changes Clearly
-
-Good names make `openspec list` useful:
-
-```text
-Good:                          Avoid:
-add-dark-mode                  feature-1
-fix-login-redirect             update
-optimize-product-query         changes
-implement-2fa                  wip
-```
-
-## Command Quick Reference
-
-For full command details and options, see [Commands](commands.md).
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/opsx:propose` | Create change + planning artifacts | Fast default path (`core` profile) |
-| `/opsx:explore` | Think through ideas with the AI | Start here when unsure: unclear requirements, investigation, comparing options |
-| `/opsx:new` | Start a change scaffold | Expanded mode, explicit artifact control |
-| `/opsx:continue` | Create next artifact | Expanded mode, step-by-step artifact creation |
-| `/opsx:ff` | Create all planning artifacts | Expanded mode, clear scope |
-| `/opsx:apply` | Implement tasks | Ready to write code |
-| `/opsx:verify` | Validate implementation | Expanded mode, before archiving |
-| `/opsx:sync` | Merge delta specs | Expanded mode, optional |
-| `/opsx:archive` | Complete the change | All work finished |
-| `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work |
-
-## Next Steps
-
- [Commands](commands.md) - Full command reference with options
- [Concepts](concepts.md) - Deep dive into specs, artifacts, and schemas
- [Customization](customization.md) - Create custom workflows
@@ -5,53 +5,29 @@
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };

-  outputs =
-    { self, nixpkgs }:
+  outputs = { self, nixpkgs }:
    let
-      supportedSystems = [
-        "x86_64-linux"
-        "aarch64-linux"
-        "x86_64-darwin"
-        "aarch64-darwin"
-      ];
+      supportedSystems = [ "x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin" ];

      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
    in
    {
-      packages = forAllSystems (
-        system:
+      packages = forAllSystems (system:
        let
          pkgs = nixpkgs.legacyPackages.${system};
-          inherit (pkgs) lib;
        in
        {
          default = pkgs.stdenv.mkDerivation (finalAttrs: {
            pname = "openspec";
-            version = (builtins.fromJSON (builtins.readFile ./package.json)).version;
+            version = "0.20.0";

-            src = lib.fileset.toSource {
-              root = ./.;
-              fileset = lib.fileset.unions [
-                ./src
-                ./bin
-                ./schemas
-                ./scripts
-                ./test
-                ./package.json
-                ./pnpm-lock.yaml
-                ./tsconfig.json
-                ./build.js
-                ./vitest.config.ts
-                ./vitest.setup.ts
-                ./eslint.config.js
-              ];
-            };
+            src = ./.;

            pnpmDeps = pkgs.fetchPnpmDeps {
              inherit (finalAttrs) pname version src;
              pnpm = pkgs.pnpm_9;
              fetcherVersion = 3;
-              hash = "sha256-cFY6phUPK4IOthG/aOtMenyQlLYCCilcOIG+G+v/q04=";
+              hash = "sha256-m/7IdY1ou9ljjYAcx3W8AyEJvIZfCBWIWxproQ/INPA=";
            };

            nativeBuildInputs = with pkgs; [
@@ -79,8 +55,7 @@
              mainProgram = "openspec";
            };
          });
-        }
-      );
+        });

      apps = forAllSystems (system: {
        default = {
@@ -89,8 +64,7 @@
        };
      });

-      devShells = forAllSystems (
-        system:
+      devShells = forAllSystems (system:
        let
          pkgs = nixpkgs.legacyPackages.${system};
        in
@@ -108,7 +82,6 @@
              echo "Run 'pnpm install' to install dependencies"
            '';
          };
-        }
-      );
+        });
    };
 }
@@ -0,0 +1,456 @@
+# OpenSpec Instructions
+
+Instructions for AI coding assistants using OpenSpec for spec-driven development.
+
+## TL;DR Quick Checklist
+
+- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
+- Decide scope: new capability vs modify existing capability
+- 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 --no-interactive` and fix issues
+- Request approval: Do not start implementation until proposal is approved
+
+## Three-Stage Workflow
+
+### Stage 1: Creating Changes
+Create proposal when you need to:
+- Add features or functionality
+- Make breaking changes (API, schema)
+- Change architecture or patterns  
+- Optimize performance (changes behavior)
+- Update security patterns
+
+Triggers (examples):
+- "Help me create a change proposal"
+- "Help me plan a change"
+- "Help me create a proposal"
+- "I want to create a spec proposal"
+- "I want to create a spec"
+
+Loose matching guidance:
+- Contains one of: `proposal`, `change`, `spec`
+- With one of: `create`, `plan`, `make`, `start`, `help`
+
+Skip proposal for:
+- Bug fixes (restore intended behavior)
+- Typos, formatting, comments
+- Dependency updates (non-breaking)
+- Configuration changes
+- Tests for existing behavior
+
+**Workflow**
+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 --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.
+1. **Read proposal.md** - Understand what's being built
+2. **Read design.md** (if exists) - Review technical decisions
+3. **Read tasks.md** - Get implementation checklist
+4. **Implement tasks sequentially** - Complete in order
+5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
+6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
+7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
+
+### Stage 3: Archiving Changes
+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 --no-interactive` to confirm the archived change passes checks
+
+## Before Any Task
+
+**Context Checklist:**
+- [ ] Read relevant specs in `specs/[capability]/spec.md`
+- [ ] Check pending changes in `changes/` for conflicts
+- [ ] Read `openspec/project.md` for conventions
+- [ ] Run `openspec list` to see active changes
+- [ ] Run `openspec list --specs` to see existing capabilities
+
+**Before Creating Specs:**
+- Always check if capability already exists
+- Prefer modifying existing specs over creating duplicates
+- Use `openspec show [spec]` to review current state
+- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
+
+### Search Guidance
+- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
+- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
+- Show details:
+  - Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
+  - Change: `openspec show <change-id> --json --deltas-only`
+- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
+
+## Quick Start
+
+### CLI Commands
+
+```bash
+# Essential commands
+openspec list                  # List active changes
+openspec list --specs          # List specifications
+openspec show [item]           # Display change or spec
+openspec validate [item]       # Validate changes or specs
+openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)
+
+# Project management
+openspec init [path]           # Initialize OpenSpec
+openspec update [path]         # Update instruction files
+
+# Interactive mode
+openspec show                  # Prompts for selection
+openspec validate              # Bulk validation mode
+
+# Debugging
+openspec show [change] --json --deltas-only
+openspec validate [change] --strict --no-interactive
+```
+
+### Command Flags
+
+- `--json` - Machine-readable output
+- `--type change|spec` - Disambiguate items
+- `--strict` - Comprehensive validation
+- `--no-interactive` - Disable prompts
+- `--skip-specs` - Archive without spec updates
+- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
+
+## Directory Structure
+
+```
+openspec/
+├── project.md              # Project conventions
+├── specs/                  # Current truth - what IS built
+│   └── [capability]/       # Single focused capability
+│       ├── spec.md         # Requirements and scenarios
+│       └── design.md       # Technical patterns
+├── changes/                # Proposals - what SHOULD change
+│   ├── [change-name]/
+│   │   ├── proposal.md     # Why, what, impact
+│   │   ├── tasks.md        # Implementation checklist
+│   │   ├── design.md       # Technical decisions (optional; see criteria)
+│   │   └── specs/          # Delta changes
+│   │       └── [capability]/
+│   │           └── spec.md # ADDED/MODIFIED/REMOVED
+│   └── archive/            # Completed changes
+```
+
+## Creating Change Proposals
+
+### Decision Tree
+
+```
+New request?
+├─ Bug fix restoring spec behavior? → Fix directly
+├─ Typo/format/comment? → Fix directly  
+├─ New feature/capability? → Create proposal
+├─ Breaking change? → Create proposal
+├─ Architecture change? → Create proposal
+└─ Unclear? → Create proposal (safer)
+```
+
+### Proposal Structure
+
+1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
+
+2. **Write proposal.md:**
+```markdown
+# Change: [Brief description of change]
+
+## Why
+[1-2 sentences on problem/opportunity]
+
+## What Changes
+- [Bullet list of changes]
+- [Mark breaking changes with **BREAKING**]
+
+## Impact
+- Affected specs: [list capabilities]
+- Affected code: [key files/systems]
+```
+
+3. **Create spec deltas:** `specs/[capability]/spec.md`
+```markdown
+## ADDED Requirements
+### Requirement: New Feature
+The system SHALL provide...
+
+#### Scenario: Success case
+- **WHEN** user performs action
+- **THEN** expected result
+
+## MODIFIED Requirements
+### Requirement: Existing Feature
+[Complete modified requirement]
+
+## REMOVED Requirements
+### Requirement: Old Feature
+**Reason**: [Why removing]
+**Migration**: [How to handle]
+```
+If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
+
+4. **Create tasks.md:**
+```markdown
+## 1. Implementation
+- [ ] 1.1 Create database schema
+- [ ] 1.2 Implement API endpoint
+- [ ] 1.3 Add frontend component
+- [ ] 1.4 Write tests
+```
+
+5. **Create design.md when needed:**
+Create `design.md` if any of the following apply; otherwise omit it:
+- Cross-cutting change (multiple services/modules) or a new architectural pattern
+- New external dependency or significant data model changes
+- Security, performance, or migration complexity
+- Ambiguity that benefits from technical decisions before coding
+
+Minimal `design.md` skeleton:
+```markdown
+## Context
+[Background, constraints, stakeholders]
+
+## Goals / Non-Goals
+- Goals: [...]
+- Non-Goals: [...]
+
+## Decisions
+- Decision: [What and why]
+- Alternatives considered: [Options + rationale]
+
+## Risks / Trade-offs
+- [Risk] → Mitigation
+
+## Migration Plan
+[Steps, rollback]
+
+## Open Questions
+- [...]
+```
+
+## Spec File Format
+
+### Critical: Scenario Formatting
+
+**CORRECT** (use #### headers):
+```markdown
+#### Scenario: User login success
+- **WHEN** valid credentials provided
+- **THEN** return JWT token
+```
+
+**WRONG** (don't use bullets or bold):
+```markdown
+- **Scenario: User login**  ❌
+**Scenario**: User login     ❌
+### Scenario: User login      ❌
+```
+
+Every requirement MUST have at least one scenario.
+
+### Requirement Wording
+- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
+
+### Delta Operations
+
+- `## ADDED Requirements` - New capabilities
+- `## MODIFIED Requirements` - Changed behavior
+- `## REMOVED Requirements` - Deprecated features
+- `## RENAMED Requirements` - Name changes
+
+Headers matched with `trim(header)` - whitespace ignored.
+
+#### When to use ADDED vs MODIFIED
+- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
+- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
+- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
+
+Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
+
+Authoring a MODIFIED requirement correctly:
+1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
+2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
+3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
+4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
+
+Example for RENAMED:
+```markdown
+## RENAMED Requirements
+- FROM: `### Requirement: Login`
+- TO: `### Requirement: User Authentication`
+```
+
+## Troubleshooting
+
+### Common Errors
+
+**"Change must have at least one delta"**
+- Check `changes/[name]/specs/` exists with .md files
+- Verify files have operation prefixes (## ADDED Requirements)
+
+**"Requirement must have at least one scenario"**
+- Check scenarios use `#### Scenario:` format (4 hashtags)
+- Don't use bullet points or bold for scenario headers
+
+**Silent scenario parsing failures**
+- Exact format required: `#### Scenario: Name`
+- Debug with: `openspec show [change] --json --deltas-only`
+
+### Validation Tips
+
+```bash
+# Always use strict mode for comprehensive checks
+openspec validate [change] --strict --no-interactive
+
+# Debug delta parsing
+openspec show [change] --json | jq '.deltas'
+
+# Check specific requirement
+openspec show [spec] --json -r 1
+```
+
+## Happy Path Script
+
+```bash
+# 1) Explore current state
+openspec spec list --long
+openspec list
+# Optional full-text search:
+# rg -n "Requirement:|Scenario:" openspec/specs
+# rg -n "^#|Requirement:" openspec/changes
+
+# 2) Choose change id and scaffold
+CHANGE=add-two-factor-auth
+mkdir -p openspec/changes/$CHANGE/{specs/auth}
+printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
+printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
+
+# 3) Add deltas (example)
+cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+Users MUST provide a second factor during login.
+
+#### Scenario: OTP required
+- **WHEN** valid credentials are provided
+- **THEN** an OTP challenge is required
+EOF
+
+# 4) Validate
+openspec validate $CHANGE --strict --no-interactive
+```
+
+## Multi-Capability Example
+
+```
+openspec/changes/add-2fa-notify/
+├── proposal.md
+├── tasks.md
+└── specs/
+    ├── auth/
+    │   └── spec.md   # ADDED: Two-Factor Authentication
+    └── notifications/
+        └── spec.md   # ADDED: OTP email notification
+```
+
+auth/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+...
+```
+
+notifications/spec.md
+```markdown
+## ADDED Requirements
+### Requirement: OTP Email Notification
+...
+```
+
+## Best Practices
+
+### Simplicity First
+- Default to <100 lines of new code
+- Single-file implementations until proven insufficient
+- Avoid frameworks without clear justification
+- Choose boring, proven patterns
+
+### Complexity Triggers
+Only add complexity with:
+- Performance data showing current solution too slow
+- Concrete scale requirements (>1000 users, >100MB data)
+- Multiple proven use cases requiring abstraction
+
+### Clear References
+- Use `file.ts:42` format for code locations
+- Reference specs as `specs/auth/spec.md`
+- Link related changes and PRs
+
+### Capability Naming
+- Use verb-noun: `user-auth`, `payment-capture`
+- Single purpose per capability
+- 10-minute understandability rule
+- Split if description needs "AND"
+
+### Change ID Naming
+- Use kebab-case, short and descriptive: `add-two-factor-auth`
+- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
+- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
+
+## Tool Selection Guide
+
+| Task | Tool | Why |
+|------|------|-----|
+| Find files by pattern | Glob | Fast pattern matching |
+| Search code content | Grep | Optimized regex search |
+| Read specific files | Read | Direct file access |
+| Explore unknown scope | Task | Multi-step investigation |
+
+## Error Recovery
+
+### Change Conflicts
+1. Run `openspec list` to see active changes
+2. Check for overlapping specs
+3. Coordinate with change owners
+4. Consider combining proposals
+
+### Validation Failures
+1. Run with `--strict` flag
+2. Check JSON output for details
+3. Verify spec file format
+4. Ensure scenarios properly formatted
+
+### Missing Context
+1. Read project.md first
+2. Check related specs
+3. Review recent archives
+4. Ask for clarification
+
+## Quick Reference
+
+### Stage Indicators
+- `changes/` - Proposed, not yet built
+- `specs/` - Built and deployed
+- `archive/` - Completed changes
+
+### File Purposes
+- `proposal.md` - Why and what
+- `tasks.md` - Implementation steps
+- `design.md` - Technical decisions
+- `spec.md` - Requirements and behavior
+
+### CLI Essentials
+```bash
+openspec list              # What's in progress?
+openspec show [item]       # View details
+openspec validate --strict --no-interactive  # Is it correct?
+openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
+```
+
+Remember: Specs are truth. Changes are proposals. Keep them in sync.
@@ -1,136 +0,0 @@
-# Add Artifact Regeneration Support
-
-## Problem
-
-Currently, there is **no way to regenerate artifacts** in the OPSX workflow:
-
- `/opsx:apply` just reads whatever's on disk
- `/opsx:continue` only creates the NEXT artifact - won't touch existing ones
-
-If you edit `design.md` after `tasks.md` exists, your only options are:
-1. Delete tasks.md manually, then run `/opsx:continue`
-2. Edit tasks.md manually
-
-The documentation claims you can "update artifacts mid-flight and continue" but there's no mechanism that actually supports this.
-
-## Proposed Solution
-
-Two parts:
-
-### Part 1: Staleness Detection
-Add artifact staleness detection to `/opsx:apply`:
-
-1. **Track modification times**: When generating an artifact, record the mtime of its dependencies
-2. **Detect staleness**: When `/opsx:apply` runs, check if upstream artifacts (design.md, specs) have been modified since tasks.md was generated
-3. **Prompt user**: If stale, ask: "Design was modified after tasks were generated. Would you like to regenerate tasks with `/opsx:continue`?"
-
-## User Experience
-
-### Vision: Seamless Mid-Flight Correction
-
-This is the workflow we want to enable (currently documented but not supported):
-
-```
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ Task 1.1: Created caching layer
-     ✓ Task 1.2: Added cache invalidation
-
-     Working on 1.3: Implement TTL...
-     I noticed the design assumes Redis, but your project uses
-     in-memory caching. Should I update the design?
-
-You: Yes, update it to use the existing cache module.
-
-AI:  Updated design.md to use CacheManager from src/cache/
-     Updated tasks.md with revised implementation steps
-     Continuing implementation...
-     ✓ Task 1.3: Implemented TTL using CacheManager
-     ...
-```
-
-**No restart needed.** Just update the artifact and continue.
-
-### Staleness Warning UX
-
-When user manually edits an upstream artifact:
-
-```
-$ /opsx:apply
-
-⚠️  Detected changes to upstream artifacts:
-    - design.md modified 5 minutes ago (after tasks.md was generated)
-
-Options:
-1. Regenerate tasks (recommended)
-2. Continue anyway with current tasks
-3. Cancel
-
->
-```
-
-### Part 2: Regeneration Capability
-
-Add a way to regenerate specific artifacts:
-
-```bash
-# Option A: Flag on continue
-/opsx:continue --regenerate tasks
-
-# Option B: Separate command
-/opsx:regenerate tasks
-
-# Option C: Interactive prompt when staleness detected
-/opsx:apply
-# "Design changed. Regenerate tasks? [y/N]"
-```
-
-## Technical Approach
-
-### Option A: Metadata File
-Store `.openspec-meta.json` in change directory:
-```json
-{
-  "tasks.md": {
-    "generated_at": "2025-01-24T10:00:00Z",
-    "dependencies": {
-      "design.md": "2025-01-24T09:55:00Z",
-      "specs/feature/spec.md": "2025-01-24T09:50:00Z"
-    }
-  }
-}
-```
-
-### Option B: Frontmatter
-Add YAML frontmatter to generated artifacts:
-```markdown
---
-generated_at: 2025-01-24T10:00:00Z
-depends_on:
-  - design.md@2025-01-24T09:55:00Z
---
-# Tasks
-...
-```
-
-### Option C: Git-based
-Use git to detect if upstream files changed since downstream was last modified. No extra metadata needed but requires git.
-
-## Non-Goals
-
- Automatic regeneration (user should always choose)
- Blocking apply entirely (just warn)
- Tracking code file changes (only artifact dependencies)
-
-## Dependencies
-
- Should be implemented after `fix-midflight-update-docs` so docs are accurate first
- Could be combined with that change if desired
-
-## Success Criteria
-
- User is warned when applying with stale artifacts
- Clear path to regenerate if needed
- No false positives (only warn when genuinely stale)
- Documentation claims become actually true
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-21
@@ -1,93 +0,0 @@
-## Why
-
-Parallel changes often touch the same capabilities and `cli-init`/`cli-update` behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order.
-
-This creates three recurring problems:
-
- teams cannot tell which change should land first
- large changes are hard to split into safe mergeable slices
- parallel work can accidentally reintroduce assumptions already removed by another change
-
-We need lightweight planning metadata and CLI guidance so contributors can safely stack plans on top of each other.
-
-## What Changes
-
-### 1. Add lightweight stack metadata for changes
-
-Extend change metadata to support sequencing and decomposition context, for example:
-
- `dependsOn`: changes that must land first
- `provides`: capability markers exposed by this change
- `requires`: capability markers needed by this change
- `touches`: capability/spec areas likely affected (advisory only; warning signal, not a hard dependency)
- `parent`: optional parent change for split work
-
-Metadata is optional and backward compatible for existing changes.
-
-Ordering semantics:
-
- `dependsOn` is the source of truth for execution/archive ordering
- `provides`/`requires` are capability contracts for validation and planning visibility
- `provides`/`requires` do not create implicit dependency edges; authors must still declare required ordering via `dependsOn`
-
-### 2. Add stack-aware validation
-
-Enhance change validation to detect planning issues early:
-
- missing dependencies
- dependency cycles
- archive ordering violations (for example, attempting to archive a change before all `dependsOn` predecessors are archived)
- unmatched capability markers (for example, `requires` marker with no provider in active history emits non-blocking warning)
- overlap warnings when active changes touch the same capability
-
-Validation should fail only for deterministic blockers (for example cycles or missing required dependencies), and keep overlap checks as actionable warnings.
-
-### 3. Add sequencing visibility commands
-
-Add lightweight CLI support to inspect and execute plan order:
-
- `openspec change graph` to show dependency DAG/order
- `openspec change graph` validates for cycles first; when cycles are present it fails with the same deterministic cycle error as stack-aware validation
- `openspec change next` to suggest unblocked changes ready to implement/archive
-
-### 4. Add split scaffolding for large changes
-
-Add helper workflow to decompose large proposals into stackable slices:
-
- `openspec change split <change-id>` scaffolds child changes with `parent` + `dependsOn`
- generates minimal proposal/tasks stubs for each child slice
- converts the source change into a parent planning container (no duplicate child implementation tasks)
- re-running split for an already-split source change returns a deterministic actionable error unless `--overwrite` (alias `--force`) is passed
- `--overwrite` / `--force` fully regenerates managed child scaffold stubs and metadata links for the split, replacing prior scaffold content
-
-### 5. Document stack-first workflow
-
-Update docs to describe:
-
- how to model dependencies and parent/child slices
- when to split a large change
- how to use graph/next validation signals during parallel development
- migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md`:
-  - machine-readable change metadata becomes the normative dependency source
-  - `IMPLEMENTATION_ORDER.md` remains optional narrative context during transition
-
-## Capabilities
-
-### New Capabilities
-
- `change-stacking-workflow`: Dependency-aware sequencing and split scaffolding for change planning
-
-### Modified Capabilities
-
- `cli-change`: Adds graph/next/split planning commands and stack-aware validation messaging
- `change-creation`: Supports parent/dependency metadata when creating or splitting changes
- `openspec-conventions`: Defines optional stack metadata conventions for change proposals
-
-## Impact
-
- `src/core/project-config.ts` and related parsing/validation utilities for change metadata loading
- `src/core/config-schema.ts` (or dedicated change schema) for stack metadata validation
- `src/commands/change.ts` and/or `src/core/list.ts` for graph/next/split command behavior
- `src/core/validation/*` for dependency cycle and overlap checks
- `docs/cli.md`, `docs/concepts.md`, and contributor guidance for stack-aware workflows
- tests for metadata parsing, graph ordering, next-item suggestions, and split scaffolding
@@ -1,15 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Metadata Scaffolding
-Change creation workflows SHALL support optional dependency metadata for new or split changes.
-
-#### Scenario: Create change with stack metadata
- **WHEN** a change is created with stack metadata inputs
- **THEN** creation SHALL persist metadata fields in change configuration
- **AND** persisted metadata SHALL be validated against change metadata schema rules
-
-#### Scenario: Split-generated child metadata
- **WHEN** child changes are generated from a split workflow
- **THEN** each child SHALL include a `parent` link to the source change
- **AND** SHALL include dependency metadata needed for deterministic sequencing
-
@@ -1,65 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Metadata Model
-The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships.
-
-#### Scenario: Optional stack metadata is present
- **WHEN** a change includes stack metadata fields
- **THEN** the system SHALL parse and expose `dependsOn`, `provides`, `requires`, `touches`, and `parent`
- **AND** validation SHALL enforce normalized field shapes and value types (`dependsOn`/`provides`/`requires`/`touches` as string arrays, `parent` as string when present)
-
-#### Scenario: Backward compatibility without stack metadata
- **WHEN** a change does not include stack metadata
- **THEN** existing behavior SHALL continue without migration steps
- **AND** validation SHALL not fail solely because stack metadata is absent
-
-### Requirement: Change Dependency Graph
-The system SHALL provide dependency-aware ordering for active changes.
-
-#### Scenario: Build dependency order
- **WHEN** users request stack planning output
- **THEN** the system SHALL compute a dependency graph across active changes
- **AND** SHALL return a deterministic topological order for unblocked changes
-
-#### Scenario: Tie-breaking within the same dependency depth
- **WHEN** multiple unblocked changes share the same topological dependency depth
- **THEN** ordering SHALL break ties lexicographically by change ID
- **AND** repeated runs over the same input SHALL return the same order
-
-#### Scenario: Dependency cycle detection
- **WHEN** active changes contain a dependency cycle
- **THEN** validation SHALL fail with cycle details before archive or sequencing actions proceed
- **AND** output SHALL include actionable guidance to break the cycle
-
-### Requirement: Capability marker and overlap semantics
-The system SHALL treat capability markers as validation contracts and `touches` as advisory overlap signals.
-
-#### Scenario: Required capability provided by an active change
- **WHEN** change B declares `requires` marker `X`
- **AND** active change A declares `provides` marker `X`
- **THEN** validation SHALL require B to declare an explicit ordering edge in `dependsOn` to at least one active provider of `X`
- **AND** validation SHALL fail if no explicit dependency is declared
-
-#### Scenario: Requires marker without active provider
- **WHEN** a change declares a `requires` marker
- **AND** no active change declares the corresponding `provides` marker
- **THEN** validation SHALL NOT infer an implicit dependency edge
- **AND** ordering SHALL continue to be determined solely by explicit `dependsOn` relationships
-
-#### Scenario: Requires marker satisfied by archived history
- **WHEN** a change declares a `requires` marker
- **AND** no active change provides that marker
- **AND** at least one archived change in history provides that marker
- **THEN** validation SHALL NOT warn solely about missing provider
- **AND** SHALL continue to use explicit `dependsOn` for active ordering
-
-#### Scenario: Requires marker missing in full history
- **WHEN** a change declares a `requires` marker
- **AND** no active or archived change in history provides that marker
- **THEN** validation SHALL emit a non-blocking warning naming the change and missing marker
- **AND** SHALL NOT infer an implicit dependency edge
-
-#### Scenario: Overlap warning for shared touches
- **WHEN** multiple active changes declare overlapping `touches` values
- **THEN** validation SHALL emit a warning listing the overlapping changes and touched areas
- **AND** validation SHALL NOT fail solely on overlap
@@ -1,27 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Planning Commands
-The change CLI SHALL provide commands for dependency-aware sequencing of active changes.
-
-#### Scenario: Show dependency graph
- **WHEN** a user runs `openspec change graph`
- **THEN** the CLI SHALL display dependency relationships for active changes
- **AND** SHALL include a deterministic recommended order for execution
-
-#### Scenario: Show next unblocked changes
- **WHEN** a user runs `openspec change next`
- **THEN** the CLI SHALL list changes that are not blocked by unresolved dependencies
- **AND** SHALL use deterministic tie-breaking when multiple options are available
-
-### Requirement: Split Large Change Scaffolding
-The change CLI SHALL support scaffolding child slices from an existing large change.
-
-#### Scenario: Split command scaffolds child changes
- **WHEN** a user runs `openspec change split <change-id>`
- **THEN** the CLI SHALL create child change directories with proposal/tasks stubs
- **AND** generated metadata SHALL include `parent` and dependency links back to the source change
-
-#### Scenario: Re-running split on an already-split change
- **WHEN** a user runs `openspec change split <change-id>` for a parent whose generated child directories already exist
- **THEN** the CLI SHALL fail with a deterministic, actionable error
- **AND** SHALL NOT mutate existing child change content unless an explicit overwrite mode is requested
@@ -1,29 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack-Aware Change Planning Conventions
-OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes.
-
-#### Scenario: Declaring change dependencies
- **WHEN** authors need to sequence related changes
- **THEN** conventions SHALL define how to declare dependencies and provided/required capability markers
- **AND** validation guidance SHALL distinguish hard blockers from soft overlap warnings
-
-#### Scenario: Dependency source of truth during migration
- **WHEN** both stack metadata and `openspec/changes/IMPLEMENTATION_ORDER.md` are present
- **THEN** conventions SHALL treat per-change stack metadata as the normative dependency source
- **AND** `IMPLEMENTATION_ORDER.md` SHALL be treated as optional narrative guidance
-
-#### Scenario: Explicit ordering remains required for capability markers
- **WHEN** authors use `provides` and `requires` markers to describe capability contracts
- **THEN** conventions SHALL require explicit `dependsOn` edges for ordering relationships
- **AND** conventions SHALL prohibit treating `requires` as an implicit dependency edge
-
-#### Scenario: Declaring advisory overlap via touches
- **WHEN** a change may affect capability/spec areas shared by concurrent changes without requiring ordering
- **THEN** conventions SHALL allow authors to declare `touches` with advisory area identifiers (for example capability IDs, spec area names, or paths)
- **AND** tooling SHALL treat `touches` as informational only (no implicit dependency edge, non-blocking validation signal)
-
-#### Scenario: Declaring parent-child split structure
- **WHEN** a large change is decomposed into smaller slices
- **THEN** conventions SHALL define parent-child metadata and expected ordering semantics
- **AND** docs SHALL describe when to split versus keep a single change
@@ -1,39 +0,0 @@
-## 1. Metadata Model
-
- [ ] 1.1 Add optional stack metadata fields (`dependsOn`, `provides`, `requires`, `touches`, `parent`) to change metadata schema
- [ ] 1.2 Keep metadata backward compatible for existing changes without new fields
- [ ] 1.3 Add tests for valid/invalid metadata and schema evolution behavior
-
-## 2. Stack-Aware Validation
-
- [ ] 2.1 Detect dependency cycles and fail validation with deterministic errors
- [ ] 2.2 Detect missing `dependsOn` targets (referenced change ID does not exist) and detect changes transitively blocked by unresolved/cyclic dependency paths
- [ ] 2.3 Add overlap warnings for active changes that touch the same capability/spec areas
- [ ] 2.4 Emit advisory warnings for unmatched `requires` markers when no provider exists in active history
- [ ] 2.5 Add tests for cycle, missing dependency, overlap warning, and unmatched `requires` cases
-
-## 3. Sequencing Commands
-
- [ ] 3.1 Add `openspec change graph` to display dependency order for active changes
- [ ] 3.2 Add `openspec change next` to suggest unblocked changes in recommended order
- [ ] 3.3 Add tests for topological ordering and deterministic tie-breaking (lexicographic by change ID at equal depth)
-
-## 4. Split Scaffolding
-
- [ ] 4.1 Add `openspec change split <change-id>` to scaffold child slices
- [ ] 4.2 Ensure generated children include parent/dependency metadata and stub proposal/tasks files
- [ ] 4.3 Convert the source change into a parent planning container as part of split (no duplicate child implementation tasks)
- [ ] 4.4 Add tests for split output structure, source-change parent conversion, and deterministic re-split error behavior when overwrite mode is not requested
- [ ] 4.5 Implement and test explicit overwrite mode for `openspec change split` (`--overwrite` / `--force`) for controlled re-splitting
-
-## 5. Documentation
-
- [ ] 5.1 Document stack metadata and sequencing workflow in `docs/concepts.md`
- [ ] 5.2 Document new change commands and usage examples in `docs/cli.md`
- [ ] 5.3 Add guidance for breaking large changes into independently mergeable slices
- [ ] 5.4 Document migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md` as optional narrative, not dependency source of truth
-
-## 6. Verification
-
- [ ] 6.1 Run targeted tests for change parsing, validation, and CLI commands
- [ ] 6.2 Run full test suite (`pnpm test`) and resolve regressions
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-21
@@ -1,161 +0,0 @@
-## Context
-
-OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable.
-
-The requested change is to support user-selectable install scope (`global` or `project`) for tool skills/commands, defaulting to `global` for new configurations while preserving legacy project-local behavior until explicit migration.
-
-## Goals / Non-Goals
-
-**Goals:**
-
- Provide a single scope preference that users can set globally and override per run
- Default new users to `global` scope
- Make install path resolution deterministic and explicit across tools/surfaces
- Preserve current behavior for users with older config files that do not yet define `installScope`
- Avoid silent partial installs; surface effective scope decisions in output
-
-**Non-Goals:**
-
- Implementing project-local config file support for global settings
- Defining global install paths for tools where upstream location conventions are unknown
- Changing workflow/profile semantics (`core`, `custom`, `delivery`) in this change
-
-## Decisions
-
-### 1. Scope model in global config
-
-Add install scope preference to global config:
-
-```ts
-type InstallScope = 'global' | 'project';
-
-interface GlobalConfig {
-  // existing fields...
-  installScope?: InstallScope;
-}
-```
-
-Defaults:
-
- New configs SHOULD write `installScope: global` explicitly.
- Existing configs without this field continue to load safely through schema evolution and SHALL resolve effective default as `project` until users explicitly set `installScope`.
-
-### 2. Explicit tool scope support metadata
-
-Extend `AI_TOOLS` metadata with optional scope support declarations per surface:
-
-```ts
-interface ToolInstallScopeSupport {
-  skills?: InstallScope[];
-  commands?: InstallScope[];
-}
-```
-
-Resolution rules:
-
-1. If scope support metadata is absent for a tool surface, treat it as project-only support for conservative backward compatibility.
-2. Try preferred scope.
-3. If unsupported, use alternate scope when supported.
-4. If neither is supported, fail with actionable error.
-
-This enables default-global behavior while remaining safe for tools that only support project-local paths.
-
-### 3. Scope-aware install target resolver
-
-Introduce shared resolver utilities to compute effective target paths for:
-
- skills root directory
- command output files
-
-Resolver input:
-
- tool id
- requested scope
- project root
- environment context (`CODEX_HOME`, etc.)
-
-Resolver output:
-
- effective scope per surface
- concrete target paths
- optional fallback reasons for user-facing output
-
-Platform behavior:
-
- Resolver outputs are OS-aware and normalized for the current platform.
- Windows global targets MUST use Windows path conventions (for example `%USERPROFILE%\.codex\prompts` fallback for Codex when `CODEX_HOME` is unset), not POSIX defaults.
-
-### 4. Context-aware command adapter paths
-
-Update command generation contract so adapters receive install context for path resolution. This avoids hardcoded absolute/relative assumptions and centralizes scope decisions.
-
-Example direction:
-
-```ts
-getFilePath(commandId: string, context: InstallContext): string
-```
-
-### 5. CLI behavior and UX
-
-`init`:
-
- Uses configured install scope by default; if absent in a legacy config, uses migration-safe effective default (`project`).
- Supports explicit override flag (`--scope global|project`).
- In interactive mode, displays chosen scope and any per-tool fallback decisions before writing files.
-
-`update`:
-
- Applies current scope preference (or override); if absent in a legacy config, uses migration-safe effective default (`project`).
- Performs drift detection using effective scoped paths and last-applied scope state.
- Reports effective scope decisions in summary output.
-
-`config`:
-
- `openspec config profile` interactive flow includes install scope selection.
- `openspec config list` shows `installScope` with source annotation (`explicit`, `new-default`, or `legacy-default`).
-
-### 6. Cleanup safety during scope changes
-
-When scope changes:
-
- Writes occur in the new effective targets.
- Cleanup/removal is limited to OpenSpec-managed files for the relevant tool/workflow IDs.
- Output explicitly states which scope locations were updated and which were cleaned.
-
-### 7. Scope drift state tracking
-
-Track last successful effective scope per tool/surface in project-managed state.
-
-Rules:
-
-1. Drift is detected when current resolved scope differs from last successful scope for a configured tool/surface.
-2. Scope support MUST be validated for all configured tools/surfaces before any write starts.
-3. Update writes to newly resolved targets first, verifies completeness, then removes managed files at previous targets.
-4. If new-target writes are partial or verification fails, command SHALL abort old-target cleanup and report actionable failure with incomplete/new and preserved/old paths.
-5. Cleanup failures do not rollback new writes; command returns actionable failure with leftover paths to resolve.
-
-### 8. Coordination with command-surface capability changes
-
-If `add-tool-command-surface-capabilities` lands, planning logic must evaluate scope resolution and delivery/capability behavior together (scope × delivery × command surface).
-
-## Risks / Trade-offs
-
-**Risk: Cross-project shared global state**
-Global installs are shared across projects. Updating global artifacts from one project affects all projects using that tool scope.
-→ Mitigation: make scope explicit in output; keep profile/delivery global and deterministic.
-
-**Risk: Tool-specific unknown global conventions**
-Not all tools document a stable global install location.
-→ Mitigation: use explicit scope support metadata; fallback or fail instead of guessing.
-
-**Risk: Adapter API churn**
-Changing adapter path contracts touches many files/tests.
-→ Mitigation: migrate in one pass with adapter contract tests and existing end-to-end generation tests.
-
-## Rollout Plan
-
-1. Add config schema + defaults for install scope.
-2. Add tool scope capability metadata and resolver utilities.
-3. Upgrade command adapter contract and generator path plumbing.
-4. Integrate scope-aware behavior into init/update.
-5. Add documentation and test coverage.
@@ -1,101 +0,0 @@
-## Why
-
-OpenSpec installation paths are currently inconsistent:
-
- Most skills and commands are written to project-local directories.
- Codex commands are already global (`$CODEX_HOME/prompts` or `~/.codex/prompts`).
- Users cannot choose a consistent install scope strategy across tools.
-
-This creates friction for users who prefer user-level setup and expect tool artifacts to be managed globally by default.
-
-## What Changes
-
-### 1. Add install scope preference with legacy-safe defaults
-
-Introduce a global install scope setting with two modes:
-
- `global` (default for newly created configs)
- `project`
-
-The setting is stored in global config and can be overridden per command run.
-For schema-evolved legacy configs where `installScope` is absent, effective default remains `project` until users opt in to global scope.
-
-### 2. Add scope-aware path resolution for skills and commands
-
-Refactor path resolution so both `init` and `update` compute install targets from:
-
- selected scope preference (`global` or `project`)
- tool capability metadata (which scopes each tool/surface supports)
- runtime context (project root, home directories, env overrides)
-
-### 3. Add per-tool capability metadata for scope support
-
-Extend tool metadata to explicitly declare scope support per surface:
-
- skills scope support
- commands scope support
-
-When preferred scope is unsupported for a tool/surface, the system uses deterministic fallback rules and reports the effective scope in output.
-
-### 4. Make command generation context-aware
-
-Extend command adapter path resolution so adapters receive install context (scope + environment context), instead of only command ID. This removes special-case handling and allows consistent scope behavior across tools.
-
-### 5. Update init/update UX and behavior
-
- `openspec init`:
-  - accepts scope override flag
-  - uses configured scope or migration-aware default (new configs default global; legacy configs preserve project until migration)
-  - applies scope-aware generation and cleanup planning
- `openspec update`:
-  - applies current scope preference
-  - syncs artifacts in effective scope per tool/surface
-  - tracks last successful effective scope per tool/surface for deterministic scope-drift detection
-  - reports effective scope decisions clearly
-
-### 6. Extend config UX and docs
-
- Add install scope control in `openspec config profile` interactive flow.
- Extend `openspec config list` output with install scope source (`explicit`, `new-default`, `legacy-default`).
- Add explicit migration guidance and prompt path so legacy users can opt into `global` scope.
- Update supported tools and CLI docs to explain scope behavior and fallback rules.
-
-### 7. Coordinate with command-surface capability delivery rules
-
-`cli-init` and `cli-update` planning SHALL compose:
-
- install scope (`global | project`)
- delivery mode (`both | skills | commands`)
- command surface capability (`adapter | skills-invocable | none`)
-
-This proposal remains focused on scope resolution, but implementation and test coverage should include mixed-tool cases to avoid regressions when combined with `add-tool-command-surface-capabilities`.
-
-## Capabilities
-
-### New Capabilities
-
- `installation-scope`: Scope preference model and effective scope resolution for tool artifact installation.
-
-### Modified Capabilities
-
- `global-config`: Persist install scope preference with schema evolution defaults.
- `cli-config`: Configure and inspect install scope preferences.
- `ai-tool-paths`: Add tool-level scope support metadata and path strategy.
- `command-generation`: Scope-aware adapter path resolution via install context.
- `cli-init`: Scope-aware initialization planning and output.
- `cli-update`: Scope-aware update sync, drift detection, and output.
- `migration`: Scope-aware migration scanning with install-scope-aware workflow lookup.
-
-## Impact
-
- `src/core/global-config.ts` - new install scope fields and defaults
- `src/core/config-schema.ts` - validation support for install scope config keys
- `src/commands/config.ts` - interactive profile/config UX additions for install scope
- `src/core/config.ts` - tool scope capability metadata
- `src/core/available-tools.ts` and `src/core/shared/tool-detection.ts` - scope-aware configured detection
- `src/core/command-generation/types.ts` and adapter implementations - context-aware file path resolution
- `src/core/init.ts` - scope-aware generation/removal planning
- `src/core/update.ts` - scope-aware sync/removal/drift planning
- `src/core/migration.ts` - scope-aware workflow scanning support
- `docs/supported-tools.md` and `docs/cli.md` - install scope behavior documentation
- `test/core/init.test.ts`, `test/core/update.test.ts`, adapter tests, config tests - scope coverage
@@ -1,35 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: AIToolOption skillsDir field
-The `AIToolOption` interface SHALL include scope support metadata in addition to path metadata.
-
-#### Scenario: Scope support metadata present
- **WHEN** a tool entry is defined in `AI_TOOLS`
- **THEN** it MAY declare supported install scopes for skills and commands
- **AND** this metadata SHALL be used for effective scope resolution
-
-#### Scenario: Scope support metadata absent
- **WHEN** a tool entry in `AI_TOOLS` omits scope support metadata for a surface
- **THEN** resolver behavior SHALL default that surface to project-only support
- **AND** effective scope resolution SHALL apply normal preferred/fallback rules against that default
-
-### Requirement: Path configuration for supported tools
-Path metadata SHALL support both project and global install targets via resolver logic.
-
-#### Scenario: Project scope path
- **WHEN** effective scope is `project` for skills
- **THEN** `skillsDir` SHALL be treated as a tool-specific container path under project root
- **AND** managed skill artifacts SHALL be written under `<projectRoot>/<skillsDir>/skills/`
- **AND** tool definitions SHALL set `skillsDir` accordingly (for example `.openspec` -> `.openspec/skills/`)
-
-#### Scenario: Global scope path
- **WHEN** effective scope is `global` for a supported tool/surface
- **THEN** paths SHALL resolve to tool-specific global directories
- **AND** environment overrides (for example `CODEX_HOME`) SHALL be respected where applicable
-
-#### Scenario: Windows global path resolution for Codex commands
- **WHEN** effective scope is `global`
- **AND** tool is Codex
- **AND** platform is Windows
- **THEN** command targets SHALL resolve to `%CODEX_HOME%\prompts` when `CODEX_HOME` is set
- **AND** SHALL otherwise resolve to `%USERPROFILE%\.codex\prompts`
@@ -1,21 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Install scope configuration via profile flow
-The config profile workflow SHALL allow users to configure install scope preference.
-
-#### Scenario: Interactive profile includes install scope
- **WHEN** user runs `openspec config profile`
- **THEN** the interactive flow SHALL include install scope selection with values `global` and `project`
- **AND** the currently configured value SHALL be pre-selected
-
-#### Scenario: Save install scope
- **WHEN** user confirms config profile changes
- **THEN** selected install scope SHALL be saved to global config
-
-### Requirement: Install scope visibility in config output
-The config command SHALL display install scope preference in human-readable output.
-
-#### Scenario: Config list shows install scope
- **WHEN** user runs `openspec config list`
- **THEN** output SHALL include current install scope value
- **AND** indicate whether value is default or explicit
@@ -1,28 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Init install scope selection
-The init command SHALL support install scope selection for generated artifacts.
-
-#### Scenario: Scope defaults to global
- **WHEN** user runs `openspec init` without explicit scope override
- **THEN** init SHALL use global config install scope
- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
-
-#### Scenario: Scope override via flag
- **WHEN** user runs `openspec init --scope project`
- **THEN** init SHALL use `project` as preferred scope for that run
- **AND** SHALL NOT mutate persisted global config unless user explicitly changes config
-
-### Requirement: Init uses effective scope resolution
-The init command SHALL resolve effective scope per tool surface before generating files.
-
-#### Scenario: Effective scope with fallback
- **WHEN** selected tool/surface does not support preferred scope
- **AND** supports alternate scope
- **THEN** init SHALL generate files at alternate effective scope
- **AND** SHALL display fallback note in summary
-
-#### Scenario: Unsupported scope selection
- **WHEN** selected tool/surface supports neither preferred nor alternate scope
- **THEN** init SHALL fail before writing files
- **AND** SHALL provide clear error guidance
@@ -1,34 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Update install scope selection
-The update command SHALL support install scope selection for sync operations.
-
-#### Scenario: Scope defaults to global config value
- **WHEN** user runs `openspec update` without explicit scope override
- **THEN** update SHALL use configured install scope
- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
-
-#### Scenario: Scope override via flag
- **WHEN** user runs `openspec update --scope project`
- **THEN** update SHALL use `project` as preferred scope for that run
-
-### Requirement: Scope-aware sync and drift detection
-The update command SHALL evaluate configured state and drift using effective scoped paths.
-
-#### Scenario: Scoped drift detection
- **WHEN** update evaluates whether tools are up-to-date
- **THEN** it SHALL inspect files at effective scoped targets for each tool/surface
- **AND** SHALL compare current resolved scope against last successful effective scope for each tool/surface
- **AND** SHALL treat a difference as sync-required drift
-
-#### Scenario: Scope fallback during update
- **WHEN** preferred scope is unsupported for a configured tool/surface
- **AND** alternate scope is supported
- **THEN** update SHALL apply fallback scope resolution
- **AND** SHALL report fallback in output
-
-#### Scenario: Unsupported scope during update
- **WHEN** configured tool/surface supports neither preferred nor alternate scope
- **THEN** scope support SHALL be validated for all configured tools/surfaces before any write
- **AND** update SHALL fail without performing file writes when incompatibilities are detected
- **AND** SHALL report incompatible tools with remediation steps
@@ -1,22 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: ToolCommandAdapter interface
-The system SHALL provide install-context-aware command path resolution.
-
-#### Scenario: Adapter interface structure
- **WHEN** implementing a tool adapter
- **THEN** command file path resolution SHALL receive install context (including effective scope and environment context)
- **AND** SHALL return the effective command output path for that context
-
-#### Scenario: Codex global path remains supported
- **WHEN** resolving Codex command paths in global scope
- **THEN** the adapter SHALL target `$CODEX_HOME/prompts` when `CODEX_HOME` is set
- **AND** SHALL otherwise target `~/.codex/prompts`
-
-### Requirement: Command generator function
-The command generator SHALL pass install context into adapter path resolution for all generated commands.
-
-#### Scenario: Scoped command generation
- **WHEN** generating commands for a tool with a resolved effective scope
- **THEN** generated command paths SHALL match that effective scope
- **AND** the formatted command body/frontmatter behavior SHALL remain tool-specific and unchanged
@@ -1,24 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Install scope field in global config
-The global config schema SHALL include install scope preference.
-
-#### Scenario: Config shape supports install scope
- **WHEN** reading or writing global config
- **THEN** config SHALL support `installScope` with allowed values `global` and `project`
-
-#### Scenario: Schema evolution default
- **WHEN** loading legacy config without `installScope`
- **THEN** the system SHALL preserve schema compatibility without mutating the file
- **AND** effective install scope SHALL resolve to `project` until user explicitly sets `installScope`
- **AND** preserve all other existing fields
-
-#### Scenario: New config default
- **WHEN** creating a new global config
- **THEN** the system SHALL persist `installScope: global` by default
- **AND** users MAY switch to `project` explicitly
-
-#### Scenario: Invalid install scope value
- **WHEN** config validation receives an invalid install scope value
- **THEN** the value SHALL be rejected
- **AND** the system SHALL preserve the existing valid configuration
@@ -1,71 +0,0 @@
-## Purpose
-
-Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics.
-
-## ADDED Requirements
-
-### Requirement: Install scope preference model
-The system SHALL support a user-level install scope preference with values `global` and `project`.
-
-#### Scenario: Default install scope
- **WHEN** install scope is not explicitly configured
- **THEN** the system SHALL resolve a migration-aware default:
- **AND** use `global` for newly created configs
- **AND** use `project` for legacy schema-evolved configs until explicit migration
-
-#### Scenario: Explicit install scope
- **WHEN** user configures install scope to `project`
- **THEN** generation and update flows SHALL use `project` as the preferred scope
-
-### Requirement: Effective scope resolution by tool surface
-The system SHALL compute effective scope per tool surface (skills, commands) based on preferred scope and tool capability support.
-
-#### Scenario: Preferred scope is supported
- **WHEN** preferred scope is supported for a tool surface
- **THEN** the system SHALL use that scope as the effective scope
-
-#### Scenario: Preferred scope is unsupported but alternate is supported
- **WHEN** preferred scope is not supported for a tool surface
- **AND** the alternate scope is supported
- **THEN** the system SHALL use the alternate scope as effective scope
- **AND** SHALL record a fallback note for user-facing output
-
-#### Scenario: No supported scope
- **WHEN** neither `global` nor `project` is supported for a tool surface
- **THEN** the command SHALL fail before writing files
- **AND** SHALL display actionable remediation
-
-### Requirement: Effective scope reporting
-The system SHALL report effective scope decisions in command output when they differ from the preferred scope.
-
-#### Scenario: Fallback reporting
- **WHEN** fallback resolution occurs for any selected/configured tool surface
- **THEN** init/update summaries SHALL include effective scope notes per affected tool
-
-### Requirement: Cross-platform path behavior
-Install scope resolution SHALL produce platform-correct target paths.
-
-#### Scenario: Global scope path on Windows
- **WHEN** effective scope is `global`
- **AND** the command runs on Windows
- **THEN** resolved target paths SHALL use Windows path conventions and separators
- **AND** SHALL NOT reuse POSIX-style home-relative defaults directly
-
-### Requirement: Cleanup safety for scope transitions
-Scope transitions SHALL update new targets first and clean old managed targets safely.
-
-#### Scenario: Automatic cleanup for managed files on scope change
- **WHEN** update or init applies a scope transition for a configured tool/surface
- **THEN** the system SHALL write new artifacts in the new effective scope before cleanup
- **AND** SHALL automatically remove only OpenSpec-managed files in the previous effective scope
-
-#### Scenario: Cleanup scope boundaries
- **WHEN** cleanup runs after a scope transition
- **THEN** the system SHALL leave non-managed files untouched
- **AND** SHALL limit removal scope to the affected tool/workflow-managed paths
-
-#### Scenario: Cleanup failure after successful writes
- **WHEN** new artifacts were written successfully in the new scope
- **AND** cleanup of old managed targets fails
- **THEN** the command SHALL report failure with leftover cleanup paths
- **AND** SHALL NOT rollback successfully written new-scope artifacts
@@ -1,61 +0,0 @@
-## 1. Global Config + Validation
-
- [ ] 1.1 Add `installScope` (`global` | `project`) to `GlobalConfig` with explicit `global` default for newly created configs
- [ ] 1.2 Update config schema validation and known-key checks to include install scope
- [ ] 1.3 Add schema-evolution tests ensuring missing `installScope` in legacy configs resolves to effective `project` until explicit migration
- [ ] 1.4 Extend `openspec config list` output to show install scope and source (`explicit`, `new-default`, `legacy-default`)
-
-## 2. Tool Capability Metadata + Resolvers
-
- [ ] 2.1 Extend `AI_TOOLS` metadata to declare scope support per surface (skills/commands)
- [ ] 2.2 Add shared install-target resolver for skills and commands using requested scope + tool support
- [ ] 2.3 Implement deterministic fallback/error behavior when preferred scope is unsupported, including default behavior when scope support metadata is absent
- [ ] 2.4 Add unit tests for scope resolution (preferred, fallback, and hard-fail paths)
-
-## 3. Command Generation Contract
-
- [ ] 3.1 Update `ToolCommandAdapter` path contract to accept install context
- [ ] 3.2 Update `generateCommand`/`generateCommands` to pass context through adapters
- [ ] 3.3 Migrate all command adapters to the new path contract
- [ ] 3.4 Update adapter tests for scoped path behavior (including Codex global path semantics)
-
-## 4. Init Command Scope Support
-
- [ ] 4.1 Add scope override flag to `openspec init` (`--scope global|project`)
- [ ] 4.2 Resolve effective scope per tool/surface before writing artifacts
- [ ] 4.3 Apply scope-aware generation/removal planning for skills and commands
- [ ] 4.4 Surface effective scope decisions and fallback notes in init summary output
- [ ] 4.5 Add init tests for global default, project override, and fallback/error scenarios
-
-## 5. Update Command Scope Support
-
- [ ] 5.1 Add scope override flag to `openspec update` (`--scope global|project`)
- [ ] 5.2 Make configured-tool detection and drift checks scope-aware
- [ ] 5.3 Persist and read last successful effective scope per tool/surface for deterministic scope-drift detection
- [ ] 5.4 Apply scope-aware sync/removal with consistent fallback/error behavior
- [ ] 5.5 Ensure scope changes update managed files in new targets and clean old managed targets safely
- [ ] 5.6 Add update tests for global/project/fallback/error and repeat-run idempotency
-
-## 6. Config UX
-
- [ ] 6.1 Extend `openspec config profile` interactive flow to select install scope
- [ ] 6.2 Preserve install scope when using preset shortcuts unless explicitly changed
- [ ] 6.3 Ensure non-interactive config behavior remains deterministic with clear errors
- [ ] 6.4 Add/adjust config command tests for install scope flows
- [ ] 6.5 Add migration UX for legacy users to opt into `global` scope explicitly
-
-## 7. Documentation
-
- [ ] 7.1 Update `docs/supported-tools.md` with scope behavior and effective-scope fallback notes
- [ ] 7.2 Update `docs/cli.md` examples for init/update scope options
- [ ] 7.3 Document cross-project implications of global installs
- [ ] 7.4 Add existing-user migration guide covering legacy-default behavior and explicit opt-in to `installScope: global`
-
-## 8. Verification
-
- [ ] 8.1 Run targeted tests for config, adapters, init, and update
- [ ] 8.2 Run full test suite (`pnpm test`) and resolve regressions
- [ ] 8.3 Manual smoke test: init/update with `installScope=global`
- [ ] 8.4 Manual smoke test: init/update with `--scope project`
- [ ] 8.5 Verify path resolution behavior on Windows CI (or cross-platform unit tests with mocked Windows paths)
- [ ] 8.6 Verify combined behavior matrix for mixed tools across scope × delivery × command-surface capability
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-20
@@ -1,45 +0,0 @@
-## Why
-
-We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX.
-
-Today, manual review is mostly ad hoc: each developer sets up state differently, runs a different command order, and checks outputs informally. This makes regressions easy to miss and slows iteration on CLI UX work.
-
-An 80/20 solution is to add a lightweight smoke harness for deterministic non-interactive flows, plus a short manual checklist for interactive prompt behavior.
-
-## What Changes
-
- Add a lightweight QA smoke harness for OpenSpec CLI behavior with isolated per-run sandbox state
- Use `Makefile` targets as the primary entrypoint:
-  - `make qa` (default local QA entrypoint)
-  - `make qa-smoke` (deterministic non-interactive suite)
-  - `make qa-interactive` (prints/opens manual interactive checklist)
- Implement smoke logic in a script (invoked by Make targets), not in Make itself
- Ensure each scenario runs in an isolated sandbox with temporary `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
- Capture scenario artifacts for inspection (command output, exit code, and before/after filesystem state)
- Add a focused scenario set for high-risk behavior:
-  - init core output generation
-  - non-interactive detected-tool behavior
-  - migration when profile is unset
-  - delivery cleanup (`both -> skills`, `both -> commands`)
-  - commands-only update detection
-  - new tool directory detection messaging
-  - invalid profile override validation
- Add a short interactive checklist for keypress/prompt UX verification (Space toggle, Enter confirm, detected pre-selection)
- Wire CI to run the smoke suite on Linux as a fast regression gate
-
-## Capabilities
-
-### New Capabilities
-
- `qa-smoke-harness`: Deterministic, sandboxed CLI smoke validation with a single developer entrypoint
-
-### Modified Capabilities
-
- `developer-qa-workflow`: Standardized local/CI QA flow for CLI behavior and migration-sensitive scenarios
-
-## Impact
-
- `Makefile` - Add `qa`, `qa-smoke`, and `qa-interactive` targets
- `scripts/qa-smoke.sh` (or equivalent) - Implement sandbox setup, scenario execution, and assertions
- `docs/` - Add/update contributor-facing QA instructions and interactive checklist usage
- CI workflow - Add smoke target execution as a lightweight regression gate
@@ -1,49 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Makefile QA Entry Point
-
-The repository SHALL provide Makefile targets as the primary developer entrypoint for CLI QA flows.
-
-#### Scenario: Default QA target runs smoke suite
-
- **WHEN** a developer runs `make qa`
- **THEN** the command SHALL execute the non-interactive smoke suite
- **AND** exit with status code 0 only when all smoke scenarios pass
-
-#### Scenario: Smoke suite target is directly invokable
-
- **WHEN** a developer runs `make qa-smoke`
- **THEN** the command SHALL execute the same smoke suite used by `make qa`
- **AND** return a non-zero exit code on assertion failure
-
-#### Scenario: Interactive checklist target exists
-
- **WHEN** a developer runs `make qa-interactive`
- **THEN** the command SHALL provide the manual interactive verification checklist
- **AND** SHALL NOT run interactive prompt automation by default
-
-### Requirement: Sandboxed Smoke Scenario Runner
-
-The smoke suite SHALL run CLI scenarios in isolated sandboxes so tests are repeatable and do not depend on machine-global state.
-
-#### Scenario: Scenario execution is environment-isolated
-
- **WHEN** a smoke scenario runs
- **THEN** it SHALL use temporary values for `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
- **AND** global config from the host machine SHALL NOT affect scenario outcomes
-
-#### Scenario: Scenario artifacts are captured for review
-
- **WHEN** a smoke scenario completes
- **THEN** the runner SHALL capture command output and exit status
- **AND** SHALL capture enough filesystem state to inspect before/after behavior
-
-#### Scenario: High-risk workflow coverage exists
-
- **WHEN** the smoke suite executes
- **THEN** it SHALL include scenarios covering profile/delivery behavior and migration-sensitive flows
- **AND** include at least:
-  - non-interactive tool detection
-  - migration when profile is unset
-  - delivery cleanup (`both -> skills`, `both -> commands`)
-  - commands-only update detection
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-19
@@ -1,111 +0,0 @@
-## Why
-
-OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools.
-
-Trae is a concrete example: it invokes OpenSpec workflows via skill entries (for example `/openspec-new-change`) rather than adapter-generated command files. In this model, skills are the command surface.
-
-Today, this creates a behavior gap:
-
- `delivery=commands` can remove skills
- tools without adapters skip command generation
- result: selected tools like Trae can end up with no invocable workflow artifacts
-
-This is more than a prompt UX issue because non-interactive and CI flows bypass interactive guidance. We need a capability-aware model in core generation logic.
-
-## What Changes
-
-### 1. Add explicit command-surface capability metadata
-
-Add an optional field in tool metadata to describe how a tool exposes commands:
-
- `adapter`: command files are generated through a command adapter
- `skills-invocable`: skills are directly invocable as commands
- `none`: no OpenSpec command surface
-
-Field should be optional. Default behavior is inferred from adapter registry presence: tools with a registered adapter resolve to `adapter`; tools with no adapter registration and no explicit annotation resolve to `none`.
-Capability values use kebab-case string tokens for consistency with serialized metadata conventions.
-
-Initial explicit override:
-
- Trae -> `skills-invocable`
-
-### 2. Make delivery behavior capability-aware
-
-Update `init` and `update` to compute effective artifact actions per tool from:
-
- global delivery (`both | skills | commands`)
- tool command surface capability
-
-Behavior matrix:
-
- `both`:
-  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
-  - generate command files only for `adapter` tools
-  - `none`: no artifact action; MAY emit compatibility warning
- `skills`:
-  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
-  - remove adapter-generated command files
-  - `none`: no artifact action; MAY emit compatibility warning
- `commands`:
-  - `adapter`: generate commands, remove skills
-  - `skills-invocable`: generate (or keep if up-to-date) skills as command surface; do not remove them
-  - `none`: fail fast with clear error
-
-### 3. Add preflight validation and clearer output
-
-Before writing/removing artifacts, validate selected/configured tools against delivery mode:
-
- interactive flow: show clear compatibility note before confirmation
- non-interactive flow: fail with deterministic error listing incompatible tools and supported alternatives
-
-Update summaries to show effective delivery outcomes per tool (for example, when commands mode still installs skills for skills-invocable tools).
-
-### 4. Update docs and tests
-
- document capability model and Trae behavior under delivery modes
- ensure CLI docs and supported-tools docs reflect effective behavior
- add test coverage for:
-  - `init --tools trae` with `delivery=commands`
-  - `update` with Trae configured under `delivery=commands`
-  - mixed selections (`claude + trae`) across all delivery modes
-  - explicit error path for tools with no command surface under `delivery=commands`
-
-### 5. Coordinate with install-scope behavior
-
-When combined with `add-global-install-scope`, init/update planning must compose:
-
- install scope (`global | project`)
- delivery mode (`both | skills | commands`)
- command surface capability (`adapter | skills-invocable | none`)
-
-Implementation tests should cover mixed-tool matrices to ensure deterministic behavior when both changes are active.
-
-## Capabilities
-
-### New Capabilities
-
- `tool-command-surface`: Capability model that classifies tools as `adapter`, `skills-invocable`, or `none` to drive delivery behavior
-
-### Modified Capabilities
-
- `cli-init`: Delivery handling becomes tool-capability-aware with preflight compatibility validation
- `cli-update`: Delivery sync becomes tool-capability-aware with consistent compatibility validation and messaging
- `supported-tools-docs`: Documents command-surface semantics for non-adapter tools
-
-## Impact
-
- `src/core/config.ts` - add optional command-surface metadata and Trae override
- `src/core/command-generation/registry.ts` (or shared helper) - capability inference from adapter presence
- `src/core/init.ts` - capability-aware generation/removal planning + compatibility validation + summary messaging
- `src/core/update.ts` - capability-aware sync/removal planning + compatibility validation + summary messaging
- `src/core/shared/tool-detection.ts` - include capability-aware detection so `skills-invocable` tools remain detectable under `delivery=commands`, and `none` tools are excluded from command-surface artifact detection
- `docs/supported-tools.md` and `docs/cli.md` - document delivery behavior and compatibility notes
- `test/core/init.test.ts` and `test/core/update.test.ts` - add coverage for skills-invocable behavior and mixed-tool delivery scenarios
-
-## Sequencing Notes
-
- This change is intended to stack safely with `simplify-skill-installation` by introducing additive, capability-specific requirements for init/update.
- If `simplify-skill-installation` merges first, this change should be rebased and keep the capability-aware rule as the source of truth for `delivery=commands` behavior on `skills-invocable` tools.
- If this change merges first, the `simplify-skill-installation` branch should be rebased to avoid re-introducing a global "commands-only means no skills for all tools" assumption.
- If `add-global-install-scope` merges first, this change should be rebased to compose capability-aware behavior on top of scope-resolved path decisions from that change.
- If this change merges first, `add-global-install-scope` should be rebased to preserve Section 5 composition rules (`install scope` + `delivery mode` + `command surface capability`) without overriding capability-aware command-surface outcomes.
@@ -1,121 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Command surface capability resolution
-The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference.
-
-#### Scenario: Explicit command surface override
- **WHEN** a tool declares an explicit command-surface capability
- **THEN** init SHALL use that explicit capability
- **AND** SHALL NOT override it based on adapter presence
-
-#### Scenario: Inferred command surface from adapter presence
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** a command adapter is registered for the tool
- **THEN** init SHALL infer `adapter` as the command surface
-
-#### Scenario: Inferred command surface for skills-only tool
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** no command adapter is registered for the tool
- **AND** the tool has a configured `skillsDir`
- **THEN** init SHALL infer `skills-invocable` as the command surface
-
-#### Scenario: Inferred command surface without adapter or skills
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** no command adapter is registered for the tool
- **AND** the tool has no `skillsDir`
- **THEN** init SHALL infer `none` as the command surface
-
-### Requirement: Delivery compatibility by tool command surface
-The init command SHALL apply delivery settings using each tool's command surface capability, not adapter presence alone.
-
-#### Scenario: Both delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `both`
- **THEN** the system SHALL generate command files for active workflows using that adapter
- **AND** SHALL generate or refresh managed skills when the tool has `skillsDir`
-
-#### Scenario: Both delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `both`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL NOT require adapter-generated command files for that tool
-
-#### Scenario: Both delivery for none command surface
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
- **AND** delivery is set to `both`
- **THEN** the system SHALL perform no command-surface artifact action for that tool
- **AND** MAY emit a compatibility note indicating no command surface is available
-
-#### Scenario: Skills delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `skills`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL remove managed adapter-generated command files for that tool
-
-#### Scenario: Skills delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `skills`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL NOT require adapter-generated command files for that tool
-
-#### Scenario: Skills delivery for none command surface
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
- **AND** delivery is set to `skills`
- **THEN** the system SHALL perform no command-surface artifact action for that tool
- **AND** MAY emit a compatibility note indicating no command surface is available
-
-#### Scenario: Commands delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `commands`
- **THEN** the system SHALL generate command files for active workflows using that adapter
- **AND** the system SHALL remove managed skill directories for that tool
-
-#### Scenario: Commands delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `commands`
- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
- **AND** the system SHALL NOT require a command adapter for that tool
-
-#### Scenario: Commands delivery for mixed tool selection
- **WHEN** user runs `openspec init` with multiple tools
- **AND** selected tools include both adapter-backed and skills-invocable command surfaces
- **AND** delivery is set to `commands`
- **THEN** the system SHALL apply commands-only behavior per tool capability
- **AND** the resulting install SHALL include command files for adapter-backed tools and skills for skills-invocable tools
-
-#### Scenario: Commands delivery for unsupported command surface
- **WHEN** user runs `openspec init` with a selected tool that has no command surface capability
- **AND** delivery is set to `commands`
- **THEN** the system SHALL fail before generating or deleting artifacts
- **AND** the error SHALL list incompatible tool IDs and explain supported alternatives (`both` or `skills`)
-
-#### Scenario: Interactive handling for unsupported command surface
- **WHEN** user runs `openspec init` interactively
- **AND** delivery is set to `commands`
- **AND** selected tools include one or more tools with command surface `none`
- **THEN** the CLI SHALL show a compatibility error and return to the interactive selection flow for correction
- **AND** SHALL not perform artifact writes until a valid selection is confirmed
-
-### Requirement: Init compatibility signaling
-The init command SHALL clearly signal command-surface compatibility outcomes in both interactive and non-interactive flows.
-
-#### Scenario: Interactive compatibility note
- **WHEN** init runs interactively
- **AND** delivery is `commands`
- **AND** selected tools include skills-invocable command surfaces
- **THEN** the system SHALL display a compatibility note before the confirmation prompt indicating those tools will use skills as their command surface
-
-#### Scenario: Non-interactive compatibility summary for skills-invocable tools
- **WHEN** init runs non-interactively (including `--tools` usage)
- **AND** delivery is `commands`
- **AND** selected tools include one or more `skills-invocable` command surfaces
- **THEN** the command SHALL proceed with exit code 0
- **AND** the command SHALL write deterministic compatibility summary lines to stdout indicating those tools will use managed skills as their command surface
-
-#### Scenario: Non-interactive compatibility failure
- **WHEN** init runs non-interactively (including `--tools` usage)
- **AND** delivery is `commands`
- **AND** selected tools include any tool with no command surface capability
- **THEN** the command SHALL exit with code 1
- **AND** the command SHALL write deterministic, actionable guidance for resolving the selection to stderr
@@ -1,48 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Delivery sync by command surface capability
-The update command SHALL synchronize artifacts using each configured tool's command surface capability.
-
-#### Scenario: Commands delivery for adapter-backed configured tool
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has an adapter-backed command surface
- **THEN** the system SHALL generate or refresh command files for active workflows
- **AND** the system SHALL remove managed skill directories for that tool
-
-#### Scenario: Commands delivery for skills-invocable configured tool
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has `skills-invocable` command surface capability
- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
- **AND** the system SHALL NOT attempt to require adapter-generated command files for that tool
-
-#### Scenario: Commands delivery with unsupported command surface
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has no command surface capability
- **THEN** the system SHALL fail with exit code 1 before applying partial updates
- **AND** the output SHALL identify incompatible tools and recommended remediation
-
-### Requirement: Configured-tool detection for skills-invocable command surfaces
-The update command SHALL treat tools with skills-invocable command surfaces as configured when managed skill artifacts are present, including under commands delivery.
-
-#### Scenario: Skills-invocable tool under commands delivery
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a tool has no adapter-generated command files
- **AND** that tool is marked `skills-invocable` and has managed skills installed
- **THEN** the system SHALL include the tool in configured-tool detection
- **AND** the system SHALL apply normal version/profile/delivery sync to that tool
-
-### Requirement: Update summary reflects effective per-tool delivery
-The update command SHALL report effective artifact behavior when delivery intent and artifact type differ due to tool capability.
-
-#### Scenario: Summary for skills-invocable tools in commands delivery
- **WHEN** update completes successfully
- **AND** delivery is `commands`
- **AND** at least one updated tool is `skills-invocable`
- **THEN** output SHALL include a clear note that those tools use skills as their command surface
- **AND** output SHALL avoid implying that command generation was skipped due to an error
-
@@ -1,53 +0,0 @@
-## 0. Stacking Coordination
-
- [ ] 0.1 Rebase this change on latest `main` before implementation
- [ ] 0.2 If `simplify-skill-installation` is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement
- [ ] 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket "commands = remove all skills" rule
- [ ] 0.4 If `add-global-install-scope` is merged, verify combined scope × delivery × command-surface behavior remains deterministic
-
-## 1. Tool Command-Surface Capability Model
-
- [ ] 1.1 Extend tool metadata in `src/core/config.ts` with an optional command-surface capability field
- [ ] 1.2 Define supported capability values: `adapter`, `skills-invocable`, `none`
- [ ] 1.3 Mark Trae as `skills-invocable`
- [ ] 1.4 Add a shared capability resolver (explicit metadata override first, inferred fallback from adapter presence second)
- [ ] 1.5 Add focused unit tests for capability resolution (explicit override, inferred adapter, inferred none)
-
-## 2. Init: Capability-Aware Delivery Planning
-
- [ ] 2.1 Refactor init generation logic to compute per-tool effective actions (generate/remove skills and commands) instead of using only global booleans
- [ ] 2.2 In `delivery=commands`, keep/generate skills for `skills-invocable` tools and do not remove those managed skill directories
- [ ] 2.3 In `delivery=commands`, fail fast before writes when any selected tool resolves to `none`
- [ ] 2.4 Update init output to clearly report effective behavior for `skills-invocable` tools (skills used as command surface)
- [ ] 2.5 Ensure init no longer reports "no adapter" for tools intentionally using `skills-invocable`
- [ ] 2.6 Add/adjust init tests for `delivery=commands` + `trae` (skills retained/generated, no adapter error), mixed tools (`claude,trae`) with per-tool expected outputs, and deterministic failure path for unsupported command surface (`none`)
-
-## 3. Update: Capability-Aware Sync and Drift Detection
-
- [ ] 3.1 Refactor update sync logic to apply delivery behavior per tool capability (not globally per run)
- [ ] 3.2 In `delivery=commands`, keep/generate managed skills for `skills-invocable` tools
- [ ] 3.3 In `delivery=commands`, fail before partial updates when configured tools include a `none` command surface
- [ ] 3.4 Update profile/delivery drift detection to avoid perpetual drift for `skills-invocable` tools under commands delivery
- [ ] 3.5 Ensure configured-tool detection still includes `skills-invocable` tools under commands delivery when managed skills exist
- [ ] 3.6 Update summary output so skills-invocable behavior is reported as expected behavior (not implicit skip/error)
- [ ] 3.7 Add/adjust update tests for `delivery=commands` + configured Trae (skills retained/generated), idempotent second update (no false drift loop), mixed configured tools (`claude` + `trae`), and deterministic preflight failure for unsupported command surface (`none`)
-
-## 4. UX and Error Messaging
-
- [ ] 4.1 Add interactive init compatibility note for `delivery=commands` when selected tools include `skills-invocable`
- [ ] 4.2 Add deterministic non-interactive error text with incompatible tool IDs and suggested alternatives (`both` or `skills`)
- [ ] 4.3 Align init and update wording so capability-related behavior/messages are consistent
-
-## 5. Documentation Updates
-
- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for Trae and clarify delivery interactions
- [ ] 5.2 Update `docs/cli.md` delivery guidance to explain capability-aware behavior for `delivery=commands`
- [ ] 5.3 Add a short troubleshooting note for "commands-only + unsupported tool" failures
-
-## 6. Verification
-
- [ ] 6.1 Run targeted tests: `test/core/init.test.ts` and `test/core/update.test.ts`
- [ ] 6.2 Run any new capability/unit test files added in this change
- [ ] 6.3 Run full test suite (`pnpm test`) and resolve regressions
- [ ] 6.4 Manual smoke check: `openspec init --tools trae` with `delivery=commands`
- [ ] 6.5 Manual smoke check: mixed tools (`claude,trae`) with `delivery=commands`
@@ -1,18 +1,17 @@
 ## ADDED Requirements

-### Requirement: Dynamic Version Support
-The script SHALL support flake.nix configurations that read version dynamically from package.json.
+### Requirement: Automatic Version Update
+The script SHALL automatically update the version in flake.nix to match package.json.

-#### Scenario: Version validation
+#### Scenario: Version extraction from package.json
 - **WHEN** script runs
 - **THEN** version is read from package.json using Node.js
- **AND** script verifies flake.nix uses dynamic version pattern
- **AND** warns if hardcoded version is detected
+- **AND** version field in flake.nix is updated to match

-#### Scenario: Version display
- **WHEN** script runs
- **THEN** script displays current package version
- **AND** indicates version is read dynamically by flake.nix
+#### 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.
@@ -30,8 +29,7 @@ The script SHALL automatically determine and update the correct pnpm dependency

 #### Scenario: Hash update failure
 - **WHEN** script cannot extract hash from build output
- **THEN** script restores original hash to flake.nix
- **AND** exits with error code 1
+- **THEN** script exits with error
 - **AND** displays build output for debugging

 ### Requirement: Build Verification
@@ -57,13 +55,8 @@ The script SHALL provide clear progress information and next steps.

 #### Scenario: Success summary
 - **WHEN** script completes successfully
- **THEN** summary shows version and hash changes
- **AND** next steps are displayed (test, verify, commit)
-
-#### Scenario: No changes needed
- **WHEN** hash is already up-to-date
- **THEN** script reports no changes needed
- **AND** exits with success code 0
+- **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.
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-30
@@ -1,3 +0,0 @@
-# opencode-command-references
-
-Transform /opsx: to /opsx- in both commands and skills for OpenCode
@@ -1,70 +0,0 @@
-## Context
-
-OpenCode is one of many supported AI tools. Each tool has:
- A **command adapter** (in `src/core/command-generation/adapters/`) for generating tool-specific command files
- **Skills** generated via `generateSkillContent()` in `src/core/shared/skill-generation.ts`
-
-Currently:
- Commands go through the adapter system which can transform content per-tool
- Skills use a single shared function with no tool-specific transformation
-
-The templates in `src/core/templates/skill-templates.ts` use Claude's colon-based format (`/opsx:new`) as the canonical format. Tools that use different formats need transformation at generation time.
-
-## Goals / Non-Goals
-
-**Goals:**
- Transform all `/opsx:` command references to `/opsx-` for OpenCode in both commands and skills
- Create a shared, reusable transformation utility
- Keep the transformation opt-in via a callback parameter (not hard-coded tool detection)
-
-**Non-Goals:**
- Modifying the canonical template format (templates stay with `/opsx:`)
- Applying transformation to other tools (only OpenCode for now)
- Creating a full adapter system for skills (overkill for current needs)
-
-## Decisions
-
-### Decision 1: Shared Utility Function
-
-**Choice**: Create `transformToHyphenCommands()` in `src/utils/command-references.ts`
-
-**Rationale**: 
- Single source of truth for the transformation logic
- Can be used by both command adapter and skill generation
- Easy to test in isolation
- Follows existing utils pattern in the codebase
-
-**Alternatives considered**:
- Inline the transformation in each location - Duplicates logic, harder to maintain
-
-### Decision 2: Callback Parameter for Skill Generation
-
-**Choice**: Add optional `transformInstructions?: (instructions: string) => string` parameter to `generateSkillContent()`
-
-**Rationale**:
- Flexible - callers define the transformation, not the generation function
- No coupling - `generateSkillContent()` doesn't need to know about tool formats
- Extensible - could support other transformations in the future
- Follows inversion of control principle
-
-**Alternatives considered**:
- Add tool ID parameter and switch on it - Creates coupling, harder to extend
- Create skill adapter system parallel to commands - Over-engineering for current needs
- Transform in templates directly - Breaks single-source-of-truth principle
-
-### Decision 3: Apply at Generation Sites
-
-**Choice**: Pass transformer in `init.ts` and `update.ts` when `tool.value === 'opencode'`
-
-**Rationale**:
- These are the only two places that generate skills
- Simple conditional check, no new abstractions needed
- Easy to extend to other tools if needed later
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| Other `/opsx:` patterns exist that shouldn't be transformed | All occurrences in templates are command invocations - verified by inspection |
-| Future tools may need same transformation | Utility is shared and easy to reuse; can add to other tools' generation |
-| Callback adds complexity to function signature | Optional parameter with sensible default (no transformation) |
@@ -1,32 +0,0 @@
-## Why
-
-OpenCode uses hyphen-based command syntax (`/opsx-new`) but our templates contain colon-based references (`/opsx:new`). This creates inconsistency where generated command files and skill files contain references that don't match the actual command invocation syntax, confusing both the AI and users.
-
-## What Changes
-
- Create a shared transformation utility (`transformToHyphenCommands`) for converting `/opsx:` to `/opsx-`
- Update the OpenCode command adapter to transform body text using this utility
- Add an optional `transformInstructions` callback parameter to `generateSkillContent()`
- Update `init.ts` and `update.ts` to pass the transformer when generating skills for OpenCode
-
-## Capabilities
-
-### New Capabilities
-
-None - this is a bug fix, not a new capability.
-
-### Modified Capabilities
-
-None - no spec-level behavior changes. This is an implementation fix in the OpenCode adapter and skill generation that doesn't change any external requirements or contracts.
-
-## Impact
-
- **Code**: 
-  - `src/utils/command-references.ts` (new file)
-  - `src/utils/index.ts` (export)
-  - `src/core/shared/skill-generation.ts` (add callback parameter)
-  - `src/core/command-generation/adapters/opencode.ts` (use transformer)
-  - `src/core/init.ts` (pass transformer for OpenCode)
-  - `src/core/update.ts` (pass transformer for OpenCode)
- **Users**: OpenCode users will see correct `/opsx-` command references in both generated command files AND skill files
- **Other tools**: No impact - transformation only applies to OpenCode
@@ -1,9 +0,0 @@
-# No Spec Changes
-
-This is a bug fix that doesn't modify any external requirements or contracts.
-
-The proposal's Capabilities section indicates:
- **New Capabilities**: None
- **Modified Capabilities**: None
-
-No spec files are needed for this implementation-only fix.
@@ -1,22 +0,0 @@
-## 1. Implementation
-
- [x] 1.1 Create `src/utils/command-references.ts` with `transformToHyphenCommands()` function
- [x] 1.2 Export `transformToHyphenCommands` from `src/utils/index.ts`
- [x] 1.3 Update `generateSkillContent()` in `src/core/shared/skill-generation.ts` to accept optional `transformInstructions` callback
- [x] 1.4 Update OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` to use `transformToHyphenCommands()` for body text
- [x] 1.5 Update `init.ts` to pass transformer when generating skills for OpenCode
- [x] 1.6 Update `update.ts` to pass transformer when generating skills for OpenCode
-
-## 2. Testing
-
- [x] 2.1 Create `test/utils/command-references.test.ts` with unit tests for `transformToHyphenCommands()`
- [x] 2.2 Add test to `test/core/command-generation/adapters.test.ts` for OpenCode body transformation
- [x] 2.3 Add test to `test/core/shared/skill-generation.test.ts` for transformer callback
-
-## 3. Verification
-
- [x] 3.1 Run `npx vitest run test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts test/core/shared/skill-generation.test.ts` to ensure tests pass
- [x] 3.2 Run `pnpm run build` to ensure no TypeScript errors
- [x] 3.3 Run `openspec init --tools opencode` in a temp directory and verify:
-  - Command files in `.opencode/command/` contain `/opsx-` references (not `/opsx:`)
-  - Skill files in `.opencode/skills/` contain `/opsx-` references (not `/opsx:`)
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-24
@@ -1,115 +0,0 @@
-## Context
-
-OpenSpec has a complete skill and slash command generation system. Skills are defined in `src/core/templates/skill-templates.ts` as functions that return `SkillTemplate` objects (for Agent Skills) and `CommandTemplate` objects (for slash commands). These are registered in `src/core/shared/skill-generation.ts` and generated during `openspec init` and `openspec update`.
-
-Existing skills follow a consistent pattern:
- `getXxxSkillTemplate()` returns the skill with name, description, instructions
- `getOpsxXxxCommandTemplate()` returns the slash command with name, description, category, tags, content
- Both are registered in their respective arrays in `skill-generation.ts`
-
-## Goals / Non-Goals
-
-**Goals:**
- Add `/opsx:onboard` skill that teaches the OpenSpec workflow through guided practice
- Follow existing patterns for skill/command template generation
- Provide comprehensive narration that explains each step
- Include codebase analysis to suggest real, appropriately-scoped tasks
-
-**Non-Goals:**
- Creating a separate "demo mode" or simulated workflow (we do real work)
- Adding new CLI commands (this is purely agent instructions)
- Modifying the init/update flow (just adding to the template arrays)
-
-## Decisions
-
-### Decision 1: Single Monolithic Skill
-
-The onboard skill will be a single comprehensive instruction set rather than composing existing skills with flags.
-
-**Rationale:**
- Slash commands don't support flags (they're just prompts)
- A monolithic skill gives complete control over narration and pacing
- Easier to maintain a single cohesive experience
- Users learn the real commands by seeing them mentioned in narration
-
-### Decision 2: Codebase Analysis Patterns
-
-The skill instructions will direct the agent to look for specific patterns when suggesting starter tasks:
-
-1. TODO/FIXME comments in code
-2. Missing error handling (`catch` blocks that swallow errors, no try-catch around risky operations)
-3. Functions without tests (cross-reference src/ with test files)
-4. Type: `any` in TypeScript files
-5. Console.log statements in non-debug code
-6. Missing input validation on user-facing inputs
-7. Recent git commits (for context on what user is working on)
-
-**Rationale:** These are universally applicable, easy to detect, and produce well-scoped tasks.
-
-### Decision 3: Narration Integration Style
-
-Each phase will follow a pattern:
-1. **EXPLAIN** what we're about to do and why (1-2 sentences)
-2. **DO** the action (run command, create artifact)
-3. **SHOW** what happened
-4. **PAUSE** at key transitions (not every step)
-
-Pauses occur at:
- After task selection (before creating change)
- After drafting proposal (before saving)
- After tasks are generated (before implementation)
- After archive (final recap)
-
-**Rationale:** Too many pauses becomes tedious. Too few loses the teaching opportunity. These are the natural "chapter breaks."
-
-### Decision 4: Scope Guardrail Approach
-
-When user selects a task that's too large, the skill will:
-1. Acknowledge the task is valuable
-2. Explain why smaller is better for first time
-3. Suggest a smaller slice or alternative
-4. Let user override if they insist
-
-**Rationale:** Soft guardrails teach without frustrating. Users learn scope calibration as part of the experience.
-
-### Decision 5: Template Structure
-
-The skill template will be ~400-600 lines of instruction text, structured as:
-
-```
- Preflight checks (init status)
- Phase 1: Welcome & Setup
- Phase 2: Task Selection (with codebase analysis instructions)
- Phase 3: Explore Demo (brief)
- Phase 4: Change Creation
- Phase 5: Proposal
- Phase 6: Specs
- Phase 7: Design
- Phase 8: Tasks
- Phase 9: Apply (Implementation)
- Phase 10: Archive
- Phase 11: Recap & Next Steps
- Edge cases & graceful exits
-```
-
-The command template will be identical to the skill template (same content, different wrapper).
-
-**Rationale:** Following the established pattern where skill and command share the same core instructions.
-
-## Risks / Trade-offs
-
-**Risk: Instruction length**
-The skill will be significantly longer than existing skills (~500 lines vs ~100-200).
-→ Mitigation: This is acceptable since onboarding is inherently comprehensive. Token cost is one-time per session.
-
-**Risk: Codebase analysis may find nothing**
-Some codebases (new projects, very clean code) may not have obvious improvement opportunities.
-→ Mitigation: Fall back to asking user what they want to build. Include "add a new feature" as an option.
-
-**Risk: Task suggestions may be inappropriate**
-Agent might suggest tasks that touch sensitive code or have hidden complexity.
-→ Mitigation: User always chooses; agent just suggests. Scope estimates help set expectations.
-
-**Risk: User abandons mid-way**
-Onboarding takes ~15 minutes; users may not complete it.
-→ Mitigation: Graceful exit handling - note the change is saved, explain how to continue later.
@@ -1,27 +0,0 @@
-## Why
-
-Users who run `openspec init` are left with files but no clear path to actually using the system. There's a gap between "I have OpenSpec set up" and "I understand the workflow." An onboarding skill would guide users through their first complete change cycle on a real task in their codebase, teaching the workflow by doing it.
-
-## What Changes
-
- Add new `/opsx:onboard` skill that guides users through their first OpenSpec change
- Add corresponding slash command template for editor integrations
- The skill will:
-  - Analyze the user's codebase to suggest appropriately-scoped starter tasks
-  - Walk through the full workflow (explore → new → proposal → specs → design → tasks → apply → archive)
-  - Provide narration explaining each step as it happens
-  - Result in a real, implemented change in the user's codebase
-
-## Capabilities
-
-### New Capabilities
- `opsx-onboard-skill`: The onboarding skill that guides users through their first complete OpenSpec workflow cycle with narration and codebase-aware task suggestions
-
-### Modified Capabilities
-<!-- No existing specs are being modified - this is purely additive -->
-
-## Impact
-
- `src/core/templates/skill-templates.ts`: Add `getOnboardSkillTemplate()` and `getOpsxOnboardCommandTemplate()` functions
- `src/core/shared/skill-generation.ts`: Register the new skill and command templates in `getSkillTemplates()` and `getCommandTemplates()`
- Users running `openspec init` or `openspec update` will get the new skill/command files generated
@@ -1,162 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OPSX Onboard Skill
-
-The system SHALL provide an `/opsx:onboard` skill that guides users through their first complete OpenSpec workflow cycle with narration and real codebase work.
-
-#### Scenario: Skill invocation
-
- **WHEN** user invokes `/opsx:onboard`
- **THEN** agent checks if OpenSpec is initialized
- **AND** if not initialized, prompts user to run `openspec init` first
- **AND** if initialized, proceeds with onboarding flow
-
-#### Scenario: Welcome and expectations
-
- **WHEN** onboarding begins
- **THEN** agent displays welcome message explaining what will happen
- **AND** sets expectation of ~15 minute duration
- **AND** explains the workflow phases: explore → new → artifacts → apply → archive
-
-### Requirement: Codebase Analysis for Task Suggestions
-
-The skill SHALL analyze the user's codebase to suggest appropriately-scoped starter tasks.
-
-#### Scenario: Codebase scanning
-
- **WHEN** onboarding reaches task selection phase
- **THEN** agent scans codebase for small improvement opportunities
- **AND** looks for: TODO/FIXME comments, missing error handling, functions without tests, outdated dependencies, type: any in TypeScript, console.log in production code, missing input validation
- **AND** checks recent git commits for context on current work
-
-#### Scenario: Task suggestion presentation
-
- **WHEN** agent has analyzed codebase
- **THEN** agent presents 3-4 specific task suggestions with scope estimates
- **AND** each suggestion includes: task description, estimated scope (files/lines), why it's a good starter
- **AND** offers option for user to specify their own task
-
-#### Scenario: Scope guardrail
-
- **WHEN** user selects or describes a task that is too large
- **THEN** agent gently redirects toward smaller scope
- **AND** suggests breaking down or deferring the large task
- **AND** offers appropriately-sized alternatives
-
-### Requirement: Explore Phase Demo
-
-The skill SHALL briefly demonstrate explore mode before creating a change.
-
-#### Scenario: Brief explore demonstration
-
- **WHEN** task is selected
- **THEN** agent briefly demonstrates `/opsx:explore` by investigating relevant code
- **AND** explains explore mode is for thinking before doing
- **AND** keeps this phase short (not a full exploration session)
- **AND** transitions to change creation
-
-### Requirement: Guided Artifact Creation
-
-The skill SHALL guide users through each artifact with narration explaining the purpose.
-
-#### Scenario: Change creation with narration
-
- **WHEN** creating the change directory
- **THEN** agent runs `openspec new change "<name>"` with derived kebab-case name
- **AND** explains what a "change" is (container for thinking and planning)
- **AND** shows the folder structure that was created
- **AND** pauses for user acknowledgment before proceeding
-
-#### Scenario: Proposal creation with narration
-
- **WHEN** creating proposal.md
- **THEN** agent explains proposals capture WHY we're making this change
- **AND** drafts proposal based on selected task
- **AND** shows draft to user for approval before saving
- **AND** explains the sections (Why, What Changes, Capabilities, Impact)
-
-#### Scenario: Specs creation with narration
-
- **WHEN** creating spec files
- **THEN** agent explains specs define WHAT we're building in detail
- **AND** explains the requirement/scenario format
- **AND** creates spec file(s) based on proposal capabilities
- **AND** notes that specs become documentation that stays in sync
-
-#### Scenario: Design creation with narration
-
- **WHEN** creating design.md
- **THEN** agent explains design captures HOW we'll build it
- **AND** notes this is where technical decisions and tradeoffs live
- **AND** for small changes, acknowledges design may be brief
- **AND** creates design based on proposal and specs
-
-#### Scenario: Tasks creation with narration
-
- **WHEN** creating tasks.md
- **THEN** agent explains tasks break work into checkboxes
- **AND** explains these drive the apply phase
- **AND** generates task list from design and specs
- **AND** shows tasks and asks if ready to implement
-
-### Requirement: Guided Implementation
-
-The skill SHALL implement tasks with narration connecting back to artifacts.
-
-#### Scenario: Implementation with narration
-
- **WHEN** implementing tasks
- **THEN** agent announces each task before working on it
- **AND** implements the change in the codebase
- **AND** occasionally references how specs/design informed decisions
- **AND** marks each task complete as it finishes
- **AND** keeps narration light (not over-explaining)
-
-#### Scenario: Implementation completion
-
- **WHEN** all tasks are complete
- **THEN** agent announces completion
- **AND** summarizes what was done
- **AND** transitions to archive phase
-
-### Requirement: Archive with Explanation
-
-The skill SHALL archive the completed change and explain what happened.
-
-#### Scenario: Archive with narration
-
- **WHEN** archiving the change
- **THEN** agent explains archive moves change to dated folder
- **AND** runs archive process
- **AND** shows where archived change lives
- **AND** explains the long-term value (finding decisions later)
-
-### Requirement: Recap and Next Steps
-
-The skill SHALL conclude with a recap and command reference.
-
-#### Scenario: Final recap
-
- **WHEN** onboarding is complete
- **THEN** agent summarizes the workflow phases completed
- **AND** emphasizes this rhythm works for any size change
- **AND** provides command reference table (/opsx:explore, /opsx:new, /opsx:ff, /opsx:continue, /opsx:apply, /opsx:verify, /opsx:archive)
- **AND** suggests next actions (try /opsx:new or /opsx:ff on something)
-
-### Requirement: Graceful Exit Handling
-
-The skill SHALL handle users who want to stop mid-way.
-
-#### Scenario: User wants to stop
-
- **WHEN** user indicates they want to stop during onboarding
- **THEN** agent acknowledges gracefully
- **AND** notes that the in-progress change is saved
- **AND** explains how to continue later with `/opsx:continue <name>`
- **AND** exits without pressure
-
-#### Scenario: User wants quick reference only
-
- **WHEN** user says they just want to see the commands
- **THEN** agent provides command cheat sheet
- **AND** exits gracefully with encouragement to try `/opsx:new`
@@ -1,21 +0,0 @@
-## 1. Add Skill Template
-
- [x] 1.1 Add `getOnboardSkillTemplate()` function to `src/core/templates/skill-templates.ts` with full onboarding instruction text covering all phases (preflight, welcome, task selection, explore demo, change creation, proposal, specs, design, tasks, apply, archive, recap)
- [x] 1.2 Include codebase analysis instructions for suggesting starter tasks (TODO/FIXME, missing error handling, missing tests, type:any, console.log, missing validation)
- [x] 1.3 Include narration pattern instructions (EXPLAIN → DO → SHOW → PAUSE at key transitions)
- [x] 1.4 Include scope guardrail instructions for redirecting users away from overly large tasks
- [x] 1.5 Include graceful exit handling instructions (user stops mid-way, user just wants command reference)
-
-## 2. Add Command Template
-
- [x] 2.1 Add `getOpsxOnboardCommandTemplate()` function to `src/core/templates/skill-templates.ts` returning CommandTemplate with same instruction content as skill
-
-## 3. Register Templates
-
- [x] 3.1 Add onboard skill to `getSkillTemplates()` array in `src/core/shared/skill-generation.ts` with dirName `openspec-onboard`
- [x] 3.2 Add onboard command to `getCommandTemplates()` array in `src/core/shared/skill-generation.ts` with id `onboard`
-
-## 4. Verify
-
- [x] 4.1 Run `pnpm run build` to ensure TypeScript compiles
- [x] 4.2 Test skill generation by running `openspec init` in a test directory and verifying onboard skill/command files are created
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-23
@@ -1,193 +0,0 @@
-## Context
-
-Currently `openspec init` and `openspec experimental` are separate commands with distinct purposes:
-
- **init**: Creates `openspec/` directory, generates `AGENTS.md`/`project.md`, configures tool config files (`CLAUDE.md`, etc.), generates old slash commands (`/openspec:proposal`, etc.)
- **experimental**: Generates skills (9 per tool), generates opsx slash commands (`/opsx:new`, etc.), creates `config.yaml`
-
-The skill-based workflow (experimental) is the direction we're going, so we're making it the default by merging into `init`.
-
-## Goals / Non-Goals
-
-**Goals:**
- Single `openspec init` command that sets up the complete skill-based workflow
- Clean migration path for existing users with legacy artifacts
- Remove all code related to config files and old slash commands
- Keep the polished UX from experimental (animated welcome, searchable multi-select)
-
-**Non-Goals:**
- Supporting both workflows simultaneously
- Providing options to use the old workflow
- Backward compatibility for `/openspec:*` commands (breaking change)
-
-## Decisions
-
-### Decision 1: Merge into init, not into experimental
-
-**Choice**: Rewrite `init` to do what `experimental` does, then delete `experimental`.
-
-**Rationale**: `init` is the canonical setup command. Users expect `init` to set up their project. `experimental` was always meant to be temporary.
-
-**Alternatives considered**:
- Keep `experimental` as the main command → confusing name for default behavior
- Create new command → unnecessary, `init` already exists
-
-### Decision 2: Legacy cleanup with Y/N prompt
-
-**Choice**: Detect legacy artifacts, show what was found, prompt `"Legacy files detected. Upgrade and clean up? [Y/n]"`, then remove if confirmed.
-
-**Rationale**: Users should know what's being removed. A single Y/N is simple and decisive. No need for multiple options.
-
-**Alternatives considered**:
- Multiple options (keep/remove/cancel) → overcomplicated
- Silent removal → users might be surprised
- Just warn without removing → leaves cruft
-
-### Decision 3: Surgical removal of legacy content
-
-**Choice**: For files with mixed content (OpenSpec markers + user content), only remove the OpenSpec marker block. For files that are 100% OpenSpec content, delete the entire file.
-
-**Rationale**: Respects user customizations. CLAUDE.md might have other instructions beyond OpenSpec.
-
-**Edge cases**:
- **Config files with mixed content**: Remove only `<!-- OPENSPEC:START -->` to `<!-- OPENSPEC:END -->` block
- **Config files that are 100% OpenSpec**: Delete file entirely (check if content outside markers is empty/whitespace)
- **Old slash command directories** (`.claude/commands/openspec/`): Delete entire directory (ours)
- **`openspec/AGENTS.md`**: Delete (ours)
- **Root `AGENTS.md`**: Only remove OpenSpec marker block, preserve rest
-
-### Decision 6: Preserve project.md with migration hint
-
-**Choice**: Do NOT auto-delete `openspec/project.md`. Preserve it and show a message directing users to manually migrate content to `config.yaml`'s `context:` field.
-
-**Rationale**:
- `project.md` may contain valuable user-written project documentation
- The new workflow uses `config.yaml.context` for the same purpose (auto-injected into artifacts)
- Auto-deleting would lose user content; auto-migrating is complex (needs LLM to compress)
- Users can migrate manually or use `/opsx:explore` to get AI assistance
-
-**Migration path**:
-1. During legacy cleanup, detect `openspec/project.md` but do not delete
-2. Show in output: "openspec/project.md still exists - migrate content to config.yaml's context: field, then delete"
-3. User migrates manually or asks Claude in explore mode: "help me migrate project.md to config.yaml"
-4. User deletes project.md when ready
-
-**Why not auto-migrate?**
- `project.md` is verbose (sections, headers, placeholders)
- `config.yaml.context` should be concise and dense
- LLM compression would be ideal but adds complexity and non-determinism to init
- Manual migration lets users decide what's actually important
-
-### Decision 4: Hidden alias for experimental
-
-**Choice**: Keep `openspec experimental` as a hidden command that delegates to `init`.
-
-**Rationale**: Users who learned `experimental` can still use it during transition. Hidden means it won't show in help.
-
-### Decision 5: Reuse existing infrastructure
-
-**Choice**: Reuse skill templates, command adapters, welcome screen, and multi-select from experimental.
-
-**Rationale**: Already built and working. Just needs to be called from init instead of experimental.
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| Users with custom `/openspec:*` commands lose them | Document in release notes; old commands are in git history |
-| Mixed-content detection might be imperfect | Conservative approach: if unsure, preserve the file and warn |
-| Users confused by missing config files | Clear messaging in init output about what changed |
-| `openspec update` might break | Review and update `update` command to work with new structure |
-
-## Architecture
-
-### What init creates (after merge)
-
-```
-openspec/
-  ├── config.yaml           # Schema settings (from experimental)
-  ├── specs/                # Empty, for user's specs
-  └── changes/              # Empty, for user's changes
-      └── archive/
-
-.<tool>/skills/             # 9 skills per selected tool
-  ├── openspec-explore/SKILL.md
-  ├── openspec-new-change/SKILL.md
-  ├── openspec-continue-change/SKILL.md
-  ├── openspec-apply-change/SKILL.md
-  ├── openspec-ff-change/SKILL.md
-  ├── openspec-verify-change/SKILL.md
-  ├── openspec-sync-specs/SKILL.md
-  ├── openspec-archive-change/SKILL.md
-  └── openspec-bulk-archive-change/SKILL.md
-
-.<tool>/commands/opsx/      # 9 slash commands per selected tool
-  ├── explore.md
-  ├── new.md
-  ├── continue.md
-  ├── apply.md
-  ├── ff.md
-  ├── verify.md
-  ├── sync.md
-  ├── archive.md
-  └── bulk-archive.md
-```
-
-### What init no longer creates
-
- `CLAUDE.md`, `.cursorrules`, `.windsurfrules`, etc. (config files)
- `openspec/AGENTS.md`
- `openspec/project.md`
- Root `AGENTS.md` stub
- `.claude/commands/openspec/` (old slash commands)
-
-### Legacy detection targets
-
-| Artifact Type | Detection Method | Removal Method |
-|--------------|------------------|----------------|
-| Config files (CLAUDE.md, etc.) | File exists AND contains OpenSpec markers | Remove marker block; delete file if empty after |
-| Old slash command dirs | Directory exists at `.<tool>/commands/openspec/` | Delete entire directory |
-| openspec/AGENTS.md | File exists at `openspec/AGENTS.md` | Delete file |
-| openspec/project.md | File exists at `openspec/project.md` | **Preserve** - show migration hint only |
-| Root AGENTS.md | File exists at `AGENTS.md` AND contains OpenSpec markers | Remove marker block; delete file if empty after |
-
-### Code to remove
-
- `src/core/configurators/` - entire directory (ToolRegistry, all config generators)
- `src/core/configurators/slash/` - entire directory (SlashCommandRegistry, old command generators)
- `src/core/templates/slash-command-templates.ts` - old `/openspec:*` content
- `src/core/templates/claude-template.ts`
- `src/core/templates/cline-template.ts`
- `src/core/templates/costrict-template.ts`
- `src/core/templates/agents-template.ts`
- `src/core/templates/agents-root-stub.ts`
- `src/core/templates/project-template.ts`
- `src/commands/experimental/` - entire directory (merged into init)
- Related test files
-
-### Code to migrate into init
-
- Animated welcome screen (`src/ui/welcome-screen.ts`) - keep, call from init
- Searchable multi-select (`src/prompts/searchable-multi-select.ts`) - keep, call from init
- Skill templates (`src/core/templates/skill-templates.ts`) - keep
- Command generation (`src/core/command-generation/`) - keep
- Tool states detection (from `experimental/setup.ts`) - move to init
-
-## Open Questions
-
-1. **What happens to `openspec update`?** - RESOLVED
-
-   **Current behavior**: Updates `openspec/AGENTS.md`, config files (`CLAUDE.md`, etc.) via `ToolRegistry`, and old slash commands (`/openspec:*`) via `SlashCommandRegistry`.
-
-   **New behavior**: Rewrite to refresh skills and opsx commands instead:
-   - Detect which tools have skills installed (check for `.claude/skills/openspec-*/`, etc.)
-   - Refresh all 9 skill files per installed tool using `skill-templates.ts`
-   - Refresh all 9 opsx command files per installed tool using `command-generation/` adapters
-   - Remove imports of `ToolRegistry`, `SlashCommandRegistry`, `agentsTemplate`
-   - Update output messaging to reflect skills/commands instead of config files
-
-   **Key principle**: Same as current update - only refresh existing tools, don't add new ones.
-
-2. **Should we keep `openspec schemas` and other experimental subcommands?** - RESOLVED
-
-   **Decision**: Yes, keep them. Remove "[Experimental]" label from all subcommands (status, instructions, schemas, etc.). See task 4.3.
@@ -1,32 +0,0 @@
-## Why
-
-The current setup has two separate commands (`openspec init` and `openspec experimental`) that configure different parts of the OpenSpec workflow. This creates confusion about which command to run, results in partial setups, and maintains two parallel systems (config files + old slash commands vs skills + opsx commands). Making the skill-based workflow the default simplifies onboarding and establishes a single, consistent way to use OpenSpec.
-
-## What Changes
-
- **BREAKING**: `openspec init` now generates skills and `/opsx:*` commands instead of config files and `/openspec:*` commands
- **BREAKING**: Config files (`CLAUDE.md`, `.cursorrules`, etc.) are no longer generated
- **BREAKING**: Old slash commands (`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`) are no longer generated
- **BREAKING**: `openspec/AGENTS.md` and `openspec/project.md` are no longer generated
- Merge `experimental` command functionality into `init`
- Add legacy detection and auto-cleanup with Y/N confirmation
- Keep `openspec experimental` as hidden alias for backward compatibility
- Use the animated welcome screen from experimental for the unified init
-
-## Capabilities
-
-### New Capabilities
-
- `legacy-cleanup`: Detect and remove legacy OpenSpec artifacts (config files, old slash commands, AGENTS.md) during init
-
-### Modified Capabilities
-
- `cli-init`: Complete rewrite - generates skills and opsx commands instead of config files and old slash commands; removes AGENTS.md/project.md generation; adds legacy cleanup; uses experimental's animated welcome screen
-
-## Impact
-
- **Code removal**: `ToolRegistry`, `SlashCommandRegistry`, config file generators, old slash command templates, AGENTS.md/project.md templates
- **Code migration**: Move skill generation and command adapter logic from `experimental/setup.ts` into `init.ts`
- **Commands affected**: `init` (rewritten), `experimental` (becomes hidden alias), `update` (may need adjustment)
- **User migration**: Existing users running `init` will be prompted to clean up legacy files
- **Breaking for**: Users relying on config files for passive triggering, users using `/openspec:*` commands
@@ -1,176 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: Directory Creation
-
-The command SHALL create the OpenSpec directory structure with config file.
-
-#### Scenario: Creating OpenSpec structure
-
- **WHEN** `openspec init` is executed
- **THEN** create the following directory structure:
-```
-openspec/
-├── config.yaml
-├── specs/
-└── changes/
-    └── archive/
-```
-
-### Requirement: AI Tool Configuration
-
-The command SHALL configure AI coding assistants with skills and slash commands using a searchable multi-select experience.
-
-#### Scenario: Prompting for AI tool selection
-
- **WHEN** run interactively
- **THEN** display animated welcome screen with OpenSpec logo
- **AND** present a searchable multi-select that shows all available tools
- **AND** mark already configured tools with "(configured ✓)" indicator
- **AND** pre-select configured tools for easy refresh
- **AND** sort configured tools to appear first in the list
- **AND** allow filtering by typing to search
-
-#### Scenario: Selecting tools to configure
-
- **WHEN** user selects tools and confirms
- **THEN** generate skills in `.<tool>/skills/` directory for each selected tool
- **AND** generate slash commands in `.<tool>/commands/opsx/` directory for each selected tool
- **AND** create `openspec/config.yaml` with default schema setting
-
-### Requirement: Skill Generation
-
-The command SHALL generate Agent Skills for selected AI tools.
-
-#### Scenario: Generating skills for a tool
-
- **WHEN** a tool is selected during initialization
- **THEN** create 9 skill directories under `.<tool>/skills/`:
-  - `openspec-explore/SKILL.md`
-  - `openspec-new-change/SKILL.md`
-  - `openspec-continue-change/SKILL.md`
-  - `openspec-apply-change/SKILL.md`
-  - `openspec-ff-change/SKILL.md`
-  - `openspec-verify-change/SKILL.md`
-  - `openspec-sync-specs/SKILL.md`
-  - `openspec-archive-change/SKILL.md`
-  - `openspec-bulk-archive-change/SKILL.md`
- **AND** each SKILL.md SHALL contain YAML frontmatter with name and description
- **AND** each SKILL.md SHALL contain the skill instructions
-
-### Requirement: Slash Command Generation
-
-The command SHALL generate opsx slash commands for selected AI tools.
-
-#### Scenario: Generating slash commands for a tool
-
- **WHEN** a tool is selected during initialization
- **THEN** create 9 slash command files using the tool's command adapter:
-  - `/opsx:explore`
-  - `/opsx:new`
-  - `/opsx:continue`
-  - `/opsx:apply`
-  - `/opsx:ff`
-  - `/opsx:verify`
-  - `/opsx:sync`
-  - `/opsx:archive`
-  - `/opsx:bulk-archive`
- **AND** use tool-specific path conventions (e.g., `.claude/commands/opsx/` for Claude)
- **AND** include tool-specific frontmatter format
-
-### Requirement: Success Output
-
-The command SHALL provide clear, actionable next steps upon successful initialization.
-
-#### Scenario: Displaying success message
-
- **WHEN** initialization completes successfully
- **THEN** display categorized summary:
-  - "Created: <tools>" for newly configured tools
-  - "Refreshed: <tools>" for already-configured tools that were updated
-  - Count of skills and commands generated
- **AND** display getting started section with:
-  - `/opsx:new` - Start a new change
-  - `/opsx:continue` - Create the next artifact
-  - `/opsx:apply` - Implement tasks
- **AND** display links to documentation and feedback
-
-#### Scenario: Displaying restart instruction
-
- **WHEN** initialization completes successfully and tools were created or refreshed
- **THEN** display instruction to restart IDE for slash commands to take effect
-
-### Requirement: Config File Generation
-
-The command SHALL create an OpenSpec config file with schema settings.
-
-#### Scenario: Creating config.yaml
-
- **WHEN** initialization completes
- **AND** config.yaml does not exist
- **THEN** create `openspec/config.yaml` with default schema setting
- **AND** display config location in output
-
-#### Scenario: Preserving existing config.yaml
-
- **WHEN** initialization runs in extend mode
- **AND** `openspec/config.yaml` already exists
- **THEN** preserve the existing config file
- **AND** display "(exists)" indicator in output
-
-### Requirement: Non-Interactive Mode
-
-The command SHALL support non-interactive operation through command-line options.
-
-#### Scenario: Select all tools non-interactively
-
- **WHEN** run with `--tools all`
- **THEN** automatically select every available AI tool without prompting
- **AND** proceed with skill and command generation
-
-#### Scenario: Select specific tools non-interactively
-
- **WHEN** run with `--tools claude,cursor`
- **THEN** parse the comma-separated tool IDs
- **AND** generate skills and commands for specified tools only
-
-#### Scenario: Skip tool configuration non-interactively
-
- **WHEN** run with `--tools none`
- **THEN** create only the openspec directory structure and config.yaml
- **AND** skip skill and command generation
-
-### Requirement: Experimental Command Alias
-
-The command SHALL maintain backward compatibility with the experimental command.
-
-#### Scenario: Running openspec experimental
-
- **WHEN** user runs `openspec experimental`
- **THEN** delegate to `openspec init`
- **AND** the command SHALL be hidden from help output
-
-## REMOVED Requirements
-
-### Requirement: File Generation
-
-**Reason**: AGENTS.md and project.md are no longer generated. Skills contain all necessary instructions.
-
-**Migration**: Skills in `.<tool>/skills/` provide all OpenSpec workflow instructions. No manual file needed.
-
-### Requirement: AI Tool Configuration Details
-
-**Reason**: Config files (CLAUDE.md, .cursorrules, etc.) are replaced by skills.
-
-**Migration**: Use skills in `.<tool>/skills/` instead of config files. Skills provide richer, tool-specific instructions.
-
-### Requirement: Slash Command Configuration
-
-**Reason**: Old `/openspec:*` slash commands are replaced by `/opsx:*` commands with richer functionality.
-
-**Migration**: Use `/opsx:new`, `/opsx:continue`, `/opsx:apply` instead of `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`.
-
-### Requirement: Root instruction stub
-
-**Reason**: Root AGENTS.md stub is no longer needed. Skills provide tool-specific instructions.
-
-**Migration**: Skills are loaded automatically by supporting tools. No root stub needed.
@@ -1,158 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Legacy artifact detection
-
-The system SHALL detect legacy OpenSpec artifacts from previous init versions.
-
-#### Scenario: Detecting legacy config files
-
- **WHEN** running `openspec init` on an existing project
- **THEN** the system SHALL check for config files with OpenSpec markers:
-  - `CLAUDE.md`
-  - `.cursorrules`
-  - `.windsurfrules`
-  - `.clinerules`
-  - `.kilocode_rules`
-  - `.github/copilot-instructions.md`
-  - `.amazonq/instructions.md`
-  - `CODEBUDDY.md`
-  - `IFLOW.md`
-  - And all other tool config files from the legacy ToolRegistry
-
-#### Scenario: Detecting legacy slash command directories
-
- **WHEN** running `openspec init` on an existing project
- **THEN** the system SHALL check for old slash command directories:
-  - `.claude/commands/openspec/`
-  - `.cursor/commands/openspec/` (note: old format used `openspec-*.md` in commands root)
-  - `.windsurf/workflows/openspec-*.md`
-  - And equivalent directories for all tools in the legacy SlashCommandRegistry
-
-#### Scenario: Detecting legacy OpenSpec structure files
-
- **WHEN** running `openspec init` on an existing project
- **THEN** the system SHALL check for:
-  - `openspec/AGENTS.md`
-  - `openspec/project.md` (for migration messaging only, not deleted)
-  - Root `AGENTS.md` with OpenSpec markers
-
-### Requirement: Legacy cleanup confirmation
-
-The system SHALL prompt for confirmation before removing legacy artifacts.
-
-#### Scenario: Prompting for cleanup when legacy detected
-
- **WHEN** legacy artifacts are detected
- **THEN** the system SHALL display what was found
- **AND** prompt: "Legacy files detected. Upgrade and clean up? [Y/n]"
- **AND** default to Yes if user presses Enter
-
-#### Scenario: User confirms cleanup
-
- **WHEN** user responds Y or presses Enter
- **THEN** the system SHALL remove legacy artifacts
- **AND** proceed with skill-based setup
-
-#### Scenario: User declines cleanup
-
- **WHEN** user responds N
- **THEN** the system SHALL abort initialization
- **AND** display message suggesting manual cleanup or using `--force` flag
-
-#### Scenario: Non-interactive mode
-
- **WHEN** running with `--no-interactive` or in CI environment
- **AND** legacy artifacts are detected
- **THEN** the system SHALL abort with exit code 1
- **AND** display detected legacy artifacts
- **AND** suggest running interactively or using `--force` flag
-
-### Requirement: Surgical removal of config file content
-
-The system SHALL preserve user content when removing OpenSpec markers from config files.
-
-#### Scenario: Config file with only OpenSpec content
-
- **WHEN** a config file contains only OpenSpec marker block (whitespace outside is acceptable)
- **THEN** the system SHALL remove the OpenSpec marker block
- **AND** preserve the file (even if empty or whitespace-only)
- **AND** NOT delete the file (config files belong to the user's project root)
-
-#### Scenario: Config file with mixed content
-
- **WHEN** a config file contains content outside OpenSpec markers
- **THEN** the system SHALL remove only the `<!-- OPENSPEC:START -->` to `<!-- OPENSPEC:END -->` block
- **AND** preserve all content before and after the markers
- **AND** clean up any resulting double blank lines
-
-#### Scenario: Root AGENTS.md with mixed content
-
- **WHEN** root `AGENTS.md` contains OpenSpec markers AND other content
- **THEN** the system SHALL remove only the OpenSpec marker block
- **AND** preserve the rest of the file
-
-### Requirement: Legacy directory removal
-
-The system SHALL remove legacy slash command directories entirely.
-
-#### Scenario: Removing old slash command directory
-
- **WHEN** a legacy slash command directory exists (e.g., `.claude/commands/openspec/`)
- **THEN** the system SHALL delete the entire directory and its contents
- **AND** NOT delete the parent directory (e.g., `.claude/commands/` remains)
-
-#### Scenario: Removing legacy AGENTS.md
-
- **WHEN** `openspec/AGENTS.md` exists
- **THEN** the system SHALL delete the file
- **AND** NOT delete the `openspec/` directory itself
-
-### Requirement: project.md migration hint
-
-The system SHALL preserve project.md and display a migration hint instead of deleting it.
-
-#### Scenario: project.md exists during upgrade
-
- **WHEN** `openspec/project.md` exists during legacy cleanup
- **THEN** the system SHALL NOT delete the file
- **AND** the system SHALL display a migration hint in the output:
-  ```
-  Manual migration needed:
-    → openspec/project.md still exists
-      Move useful content to config.yaml's "context:" field, then delete
-  ```
-
-#### Scenario: project.md migration rationale
-
- **GIVEN** project.md may contain user-written project documentation
- **AND** config.yaml's context field serves the same purpose (auto-injected into artifacts)
- **WHEN** displaying the migration hint
- **THEN** users can migrate manually or use `/opsx:explore` to get AI assistance
-
-### Requirement: Cleanup reporting
-
-The system SHALL report what was cleaned up.
-
-#### Scenario: Displaying cleanup summary
-
- **WHEN** legacy cleanup completes
- **THEN** the system SHALL display a summary section:
-  ```
-  Cleaned up legacy files:
-    ✓ Removed OpenSpec markers from CLAUDE.md
-    ✓ Removed .claude/commands/openspec/ (replaced by /opsx:*)
-    ✓ Removed openspec/AGENTS.md (no longer needed)
-  ```
- **AND IF** `openspec/project.md` exists
- **THEN** the system SHALL display a separate migration section:
-  ```
-  Manual migration needed:
-    → openspec/project.md still exists
-      Move useful content to config.yaml's "context:" field, then delete
-  ```
-
-#### Scenario: No legacy detected
-
- **WHEN** no legacy artifacts are found
- **THEN** the system SHALL NOT display the cleanup section
- **AND** proceed directly with skill setup
@@ -1,67 +0,0 @@
-## 1. Legacy Detection & Cleanup Module
-
- [x] 1.1 Create `src/core/legacy-cleanup.ts` with detection functions for all legacy artifact types
- [x] 1.2 Implement `detectLegacyConfigFiles()` - check for config files with OpenSpec markers
- [x] 1.3 Implement `detectLegacySlashCommands()` - check for old `/openspec:*` command directories
- [x] 1.4 Implement `detectLegacyStructureFiles()` - check for AGENTS.md (project.md detected separately for messaging)
- [x] 1.5 Implement `removeMarkerBlock()` - surgically remove OpenSpec marker blocks from files
- [x] 1.6 Implement `cleanupLegacyArtifacts()` - orchestrate removal with proper edge case handling (preserves project.md)
- [x] 1.7 Implement migration hint output for project.md - show message directing users to migrate to config.yaml
- [x] 1.8 Add unit tests for legacy detection and cleanup functions
-
-## 2. Rewrite Init Command
-
- [x] 2.1 Replace `src/core/init.ts` with new implementation using experimental's approach
- [x] 2.2 Import and use animated welcome screen from `src/ui/welcome-screen.ts`
- [x] 2.3 Import and use searchable multi-select from `src/prompts/searchable-multi-select.ts`
- [x] 2.4 Integrate legacy detection at start of init flow
- [x] 2.5 Add Y/N prompt for legacy cleanup confirmation
- [x] 2.6 Generate skills using existing `skill-templates.ts`
- [x] 2.7 Generate slash commands using existing `command-generation/` adapters
- [x] 2.8 Create `openspec/config.yaml` with default schema
- [x] 2.9 Update success output to match new workflow (skills, /opsx:* commands)
- [x] 2.10 Add `--force` flag to skip legacy cleanup prompt in non-interactive mode
-
-## 3. Remove Legacy Code
-
- [x] 3.1 Delete `src/core/configurators/` directory (ToolRegistry, all config generators)
- [x] 3.2 Delete `src/core/templates/slash-command-templates.ts`
- [x] 3.3 Delete `src/core/templates/claude-template.ts`
- [x] 3.4 Delete `src/core/templates/cline-template.ts`
- [x] 3.5 Delete `src/core/templates/costrict-template.ts`
- [x] 3.6 Delete `src/core/templates/agents-template.ts`
- [x] 3.7 Delete `src/core/templates/agents-root-stub.ts`
- [x] 3.8 Delete `src/core/templates/project-template.ts`
- [x] 3.9 Delete `src/commands/experimental/` directory
- [x] 3.10 Update `src/core/templates/index.ts` to remove deleted exports
- [x] 3.11 Delete related test files for removed modules (wizard.ts)
-
-## 4. Update CLI Registration
-
- [x] 4.1 Update `src/cli/index.ts` to remove `registerArtifactWorkflowCommands()` call
- [x] 4.2 Keep experimental subcommands (status, instructions, schemas, etc.) but register directly
- [x] 4.3 Remove "[Experimental]" labels from kept subcommands
- [x] 4.4 Add hidden `experimental` command as alias to `init`
-
-## 5. Update Related Commands
-
- [x] 5.1 Update `openspec update` command to refresh skills/commands instead of config files
- [x] 5.2 Remove config file refresh logic from update
- [x] 5.3 Add skill refresh logic to update
-
-## 6. Testing & Verification
-
- [x] 6.1 Add integration tests for new init flow (fresh install)
- [x] 6.2 Add integration tests for legacy detection and cleanup
- [x] 6.3 Add integration tests for extend mode (re-running init)
- [x] 6.4 Test non-interactive mode with `--tools` flag
- [x] 6.5 Test `--force` flag for CI environments
- [x] 6.6 Verify cross-platform path handling (use path.join throughout)
- [x] 6.7 Run full test suite and fix any broken tests
-
-## 7. Documentation & Cleanup
-
- [x] 7.1 Update README with new init behavior (skill-based workflow is self-documenting)
- [x] 7.2 Document breaking changes for release notes (in tasks file)
- [x] 7.3 Remove any orphaned imports/references to deleted modules (verified none exist)
- [x] 7.4 Run linter and fix any issues (passed)
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-22
@@ -1,144 +0,0 @@
-## Context
-
-The `artifact-experimental-setup` command generates skill files and opsx slash commands for AI coding assistants. Currently it hardcodes paths to `.claude/skills` and `.claude/commands/opsx`.
-
-The existing `AI_TOOLS` array in `config.ts` lists 22 AI tools but lacks path information. There's also an existing `SlashCommandConfigurator` system for the old workflow commands, but it's tightly coupled to the old 3 commands (proposal, apply, archive) and can't be easily extended for the 9 opsx commands.
-
-Each AI tool has:
- Different skill directory conventions (`.claude/skills/`, `.cursor/skills/`, etc.)
- Different command file paths (`.claude/commands/opsx/`, `.cursor/commands/`, etc.)
- Different frontmatter formats (YAML keys, structure varies by tool)
-
-## Goals / Non-Goals
-
-**Goals:**
- Support skill generation for any AI tool following the Agent Skills spec
- Support command generation with tool-specific formatting via adapters
- Require explicit tool selection (no defaults)
- Create a generic, extensible command generation system
-
-**Non-Goals:**
- Global path installation for tools other than Codex (Codex uses absolute adapter paths today)
- Multi-tool generation in single command (future enhancement)
- Unifying with existing SlashCommandConfigurator (separate systems for now)
-
-## Decisions
-
-### 1. Add `skillsDir` to `AIToolOption` interface
-
-**Decision**: Add single `skillsDir` field to existing interface. No `commandsDir` or `globalSkillsDir`.
-
-```typescript
-interface AIToolOption {
-  name: string;
-  value: string;
-  available: boolean;
-  successLabel?: string;
-  skillsDir?: string;  // e.g., '.claude' - /skills suffix per Agent Skills spec
-}
-```
-
-**Rationale**:
- Skills follow Agent Skills spec: `<toolDir>/skills/` - suffix is standard
- Commands need per-tool formatting, handled by adapters (not a simple path)
- Global paths supported — Codex adapter returns absolute paths via os.homedir()
-
-### 2. Strategy/Adapter pattern for command generation
-
-**Decision**: Create generic command generation with tool-specific adapters.
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                      CommandContent                              │
-│  (tool-agnostic: id, name, description, category, tags, body)   │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                   generateCommand(content, adapter)              │
-└─────────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              ▼               ▼               ▼
-        ┌──────────┐   ┌──────────┐   ┌──────────┐
-        │  Claude  │   │  Cursor  │   │ Windsurf │
-        │ Adapter  │   │ Adapter  │   │ Adapter  │
-        └──────────┘   └──────────┘   └──────────┘
-```
-
-**Interfaces:**
-
-```typescript
-// Tool-agnostic command data
-interface CommandContent {
-  id: string;           // e.g., 'explore', 'new', 'apply'
-  name: string;         // e.g., 'OpenSpec Explore'
-  description: string;  // e.g., 'Enter explore mode...'
-  category: string;     // e.g., 'OpenSpec'
-  tags: string[];       // e.g., ['openspec', 'explore']
-  body: string;         // The command instructions
-}
-
-// Per-tool formatting strategy
-interface ToolCommandAdapter {
-  toolId: string;
-  getFilePath(commandId: string): string;
-  formatFile(content: CommandContent): string;
-}
-```
-
-**Rationale**:
- Separates "what to generate" from "how to format it"
- Each tool's frontmatter quirks encapsulated in its adapter
- Easy to add new tools by implementing adapter interface
- Body content shared across all tools
-
-**Alternative considered**: Extend existing SlashCommandConfigurator
- Rejected: Tightly coupled to old 3 commands, significant refactor needed
-
-### 3. Adapter registry pattern
-
-**Decision**: Create `CommandAdapterRegistry` similar to existing `SlashCommandRegistry`.
-
-```typescript
-class CommandAdapterRegistry {
-  private static adapters: Map<string, ToolCommandAdapter> = new Map();
-
-  static get(toolId: string): ToolCommandAdapter | undefined;
-  static getAll(): ToolCommandAdapter[];
-}
-```
-
-**Rationale**:
- Consistent with existing codebase patterns
- Easy lookup by tool ID
- Centralized registration
-
-### 4. Required tool flag
-
-**Decision**: Require `--tool` flag - error if omitted.
-
-**Rationale**:
- Explicit tool selection avoids assumptions
- Consistent with project convention of not providing defaults
- Users must consciously choose their target tool
-
-## Risks / Trade-offs
-
-**[Risk] Adapter maintenance burden** → Each new tool needs an adapter. Mitigated by simple interface - most adapters are ~20 lines.
-
-**[Risk] Frontmatter format drift** → Tools may change their formats. Mitigated by encapsulating format in adapter - single place to update.
-
-**[Trade-off] Two command systems** → Old SlashCommandConfigurator and new CommandAdapterRegistry coexist. Acceptable for now - can unify later if needed.
-
-**[Trade-off] skillsDir optional** → Tools without skillsDir configured will error. Acceptable - we add paths as tools are tested.
-
-## Implementation Approach
-
-1. Add `skillsDir` to `AIToolOption` and populate for known tools
-2. Create `CommandContent` and `ToolCommandAdapter` interfaces
-3. Implement adapters for Claude, Cursor, Windsurf (start with 3)
-4. Create `CommandAdapterRegistry`
-5. Create `generateCommand()` function
-6. Update `artifact-experimental-setup` to use new system
-7. Add `--tool` flag with validation
@@ -1,36 +0,0 @@
-## Why
-
-The `artifact-experimental-setup` command currently hardcodes skill output paths to `.claude/skills` and `.claude/commands/opsx`. This prevents users of other AI coding tools (Cursor, Windsurf, Codex, etc.) from using OpenSpec's skill generation. We need to support the diverse ecosystem of AI coding assistants, each with their own conventions for skill/instruction file locations and command frontmatter formats.
-
-## What Changes
-
- Add `skillsDir` path configuration to the existing `AIToolOption` interface in `config.ts`
- Add required `--tool <tool-id>` flag to the `artifact-experimental-setup` command
- Create a generic command generation system using Strategy/Adapter pattern:
-  - `CommandContent`: tool-agnostic command data (id, name, description, body)
-  - `ToolCommandAdapter`: per-tool formatting (file paths, frontmatter format)
-  - `CommandGenerator`: orchestrates generation using content + adapter
- Require explicit tool selection (no default) for clarity
-
-## Capabilities
-
-### New Capabilities
-
- `ai-tool-paths`: Configuration mapping AI tool IDs to their project-local skill directory paths
- `command-generation`: Generic command generation system with tool adapters for formatting differences
-
-### Modified Capabilities
-
- `cli-artifact-workflow`: Adding `--tool` flag to setup command for provider selection
-
-## Impact
-
- **Files Modified**:
-  - `src/core/config.ts` - Extend `AIToolOption` interface with `skillsDir` field
-  - `src/commands/artifact-workflow.ts` - Add `--tool` flag, use provider paths and adapters
- **New Files**:
-  - `src/core/command-generation/types.ts` - CommandContent, ToolCommandAdapter interfaces
-  - `src/core/command-generation/generator.ts` - Generic command generator
-  - `src/core/command-generation/adapters/*.ts` - Per-tool adapters
- **Backward Compatibility**: Existing workflows unaffected - this is a new command setup feature
- **User-Facing**: Required `--tool` flag on `artifact-experimental-setup` command for explicit tool selection
@@ -1,63 +0,0 @@
-# ai-tool-paths Specification
-
-## Purpose
-
-Define the path configuration for AI coding tool skill directories, enabling skill generation to target different tools following the Agent Skills spec.
-
-## Requirements
-
-## ADDED Requirements
-
-### Requirement: AIToolOption skillsDir field
-
-The `AIToolOption` interface SHALL include an optional `skillsDir` field for skill generation path configuration.
-
-#### Scenario: Interface includes skillsDir field
-
- **WHEN** a tool entry is defined in `AI_TOOLS` that supports skill generation
- **THEN** it SHALL include a `skillsDir` field specifying the project-local base directory (e.g., `.claude`)
-
-#### Scenario: Skills path follows Agent Skills spec
-
- **WHEN** generating skills for a tool with `skillsDir: '.claude'`
- **THEN** skills SHALL be written to `<projectRoot>/<skillsDir>/skills/`
- **AND** the `/skills` suffix is appended per Agent Skills specification
-
-### Requirement: Path configuration for supported tools
-
-The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
-
-#### Scenario: Claude Code paths defined
-
- **WHEN** looking up the `claude` tool
- **THEN** `skillsDir` SHALL be `.claude`
-
-#### Scenario: Cursor paths defined
-
- **WHEN** looking up the `cursor` tool
- **THEN** `skillsDir` SHALL be `.cursor`
-
-#### Scenario: Windsurf paths defined
-
- **WHEN** looking up the `windsurf` tool
- **THEN** `skillsDir` SHALL be `.windsurf`
-
-#### Scenario: Tools without skillsDir
-
- **WHEN** a tool has no `skillsDir` defined
- **THEN** skill generation SHALL error with message indicating the tool is not supported
-
-### Requirement: Cross-platform path handling
-
-The system SHALL handle paths correctly across operating systems.
-
-#### Scenario: Path construction on Windows
-
- **WHEN** constructing skill paths on Windows
- **THEN** the system SHALL use `path.join()` for all path construction
- **AND** SHALL NOT hardcode forward slashes
-
-#### Scenario: Path construction on Unix
-
- **WHEN** constructing skill paths on macOS or Linux
- **THEN** the system SHALL use `path.join()` for consistency
@@ -1,60 +0,0 @@
-# cli-artifact-workflow Delta Specification
-
-## Purpose
-
-Add `--tool` flag to the `artifact-experimental-setup` command for multi-provider support.
-
-## ADDED Requirements
-
-### Requirement: Tool selection flag
-
-The `artifact-experimental-setup` command SHALL accept a `--tool <tool-id>` flag to specify the target AI tool.
-
-#### Scenario: Specify tool via flag
-
- **WHEN** user runs `openspec artifact-experimental-setup --tool cursor`
- **THEN** skill files are generated in `.cursor/skills/`
- **AND** command files are generated using Cursor's frontmatter format
-
-#### Scenario: Missing tool flag
-
- **WHEN** user runs `openspec artifact-experimental-setup` without `--tool`
- **THEN** the system displays an error requiring the `--tool` flag
- **AND** lists valid tool IDs in the error message
-
-#### Scenario: Unknown tool ID
-
- **WHEN** user runs `openspec artifact-experimental-setup --tool unknown-tool`
- **AND** the tool ID is not in `AI_TOOLS`
- **THEN** the system displays an error listing valid tool IDs
-
-#### Scenario: Tool without skillsDir
-
- **WHEN** user specifies a tool that has no `skillsDir` configured
- **THEN** the system displays an error indicating skill generation is not supported for that tool
-
-#### Scenario: Tool without command adapter
-
- **WHEN** user specifies a tool that has `skillsDir` but no command adapter registered
- **THEN** skill files are generated successfully
- **AND** command generation is skipped with informational message
-
-### Requirement: Output messaging
-
-The setup command SHALL display clear output about what was generated.
-
-#### Scenario: Show target tool in output
-
- **WHEN** setup command runs successfully
- **THEN** output includes the target tool name (e.g., "Setting up for Cursor...")
-
-#### Scenario: Show generated paths
-
- **WHEN** setup command completes
- **THEN** output lists all generated skill file paths
- **AND** lists all generated command file paths (if applicable)
-
-#### Scenario: Show skipped commands message
-
- **WHEN** command generation is skipped due to missing adapter
- **THEN** output includes message: "Command generation skipped - no adapter for <tool>"
@@ -1,98 +0,0 @@
-# command-generation Specification
-
-## Purpose
-
-Define a generic command generation system that supports multiple AI tools through a Strategy/Adapter pattern, separating command content from tool-specific formatting.
-
-## ADDED Requirements
-
-### Requirement: CommandContent interface
-
-The system SHALL define a tool-agnostic `CommandContent` interface for command data.
-
-#### Scenario: CommandContent structure
-
- **WHEN** defining a command to generate
- **THEN** `CommandContent` SHALL include:
-  - `id`: string identifier (e.g., 'explore', 'apply')
-  - `name`: human-readable name (e.g., 'OpenSpec Explore')
-  - `description`: brief description of command purpose
-  - `category`: grouping category (e.g., 'OpenSpec')
-  - `tags`: array of tag strings
-  - `body`: the command instruction content
-
-### Requirement: ToolCommandAdapter interface
-
-The system SHALL define a `ToolCommandAdapter` interface for per-tool formatting.
-
-#### Scenario: Adapter interface structure
-
- **WHEN** implementing a tool adapter
- **THEN** `ToolCommandAdapter` SHALL require:
-  - `toolId`: string identifier matching `AIToolOption.value`
-  - `getFilePath(commandId: string)`: returns file path for command (relative from project root, or absolute for global-scoped tools like Codex)
-  - `formatFile(content: CommandContent)`: returns complete file content with frontmatter
-
-#### Scenario: Claude adapter formatting
-
- **WHEN** formatting a command for Claude Code
- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
- **AND** file path SHALL follow pattern `.claude/commands/opsx/<id>.md`
-
-#### Scenario: Cursor adapter formatting
-
- **WHEN** formatting a command for Cursor
- **THEN** the adapter SHALL output YAML frontmatter with `name` as `/opsx-<id>`, `id`, `category`, `description` fields
- **AND** file path SHALL follow pattern `.cursor/commands/opsx-<id>.md`
-
-#### Scenario: Windsurf adapter formatting
-
- **WHEN** formatting a command for Windsurf
- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
- **AND** file path SHALL follow pattern `.windsurf/workflows/opsx-<id>.md`
-
-### Requirement: Command generator function
-
-The system SHALL provide a `generateCommand` function that combines content with adapter.
-
-#### Scenario: Generate command file
-
- **WHEN** calling `generateCommand(content, adapter)`
- **THEN** it SHALL return an object with:
-  - `path`: the file path from `adapter.getFilePath(content.id)`
-  - `fileContent`: the formatted content from `adapter.formatFile(content)`
-
-#### Scenario: Generate multiple commands
-
- **WHEN** generating all opsx commands for a tool
- **THEN** the system SHALL iterate over command contents and generate each using the tool's adapter
-
-### Requirement: CommandAdapterRegistry
-
-The system SHALL provide a registry for looking up tool adapters.
-
-#### Scenario: Get adapter by tool ID
-
- **WHEN** calling `CommandAdapterRegistry.get('cursor')`
- **THEN** it SHALL return the Cursor adapter or undefined if not registered
-
-#### Scenario: Get all adapters
-
- **WHEN** calling `CommandAdapterRegistry.getAll()`
- **THEN** it SHALL return array of all registered adapters
-
-#### Scenario: Adapter not found
-
- **WHEN** looking up an adapter for unregistered tool
- **THEN** `CommandAdapterRegistry.get()` SHALL return undefined
- **AND** caller SHALL handle missing adapter appropriately
-
-### Requirement: Shared command body content
-
-The body content of commands SHALL be shared across all tools.
-
-#### Scenario: Same instructions across tools
-
- **WHEN** generating the 'explore' command for Claude and Cursor
- **THEN** both SHALL use the same `body` content
- **AND** only the frontmatter and file path SHALL differ
--- a/Show More
+++ b/Show More