fix(view): keep archived changes off the dashboard (#2031)

* fix(view): keep archived changes off the dashboard

openspec view is a one-screen dashboard for a person reading a terminal.
#399 added every archived change to it, so projects with hundreds of
archived changes pushed active work off the screen (#2030). The dashboard
shows current work again; `openspec list --archived` still shows history.

To catch this class of mistake earlier, the cli-view spec now states who
the command serves and that it shows current work only, view.ts says the
same where the code lives, and CONTRIBUTING asks how a human view grows
as a project ages before anything is added to it.

* docs(view): describe archive exclusion without promising a screen height

* docs(view): keep internal rationale out of the user reference

The CLI reference describes what view prints, so it goes back to its
pre-#399 text. The why lives in the cli-view spec Purpose, the code
comment points there, and the CONTRIBUTING rule no longer names a PR.

* revert: drop bug-specific guardrails

The CONTRIBUTING section, the cli-view spec requirement, and the view.ts
comment each restated this one bug instead of guarding the general
mistake. The regression test stays as the guardrail.

.changeset/lazy-cli-commands.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+The CLI starts faster: each command now loads its implementation only when it runs. `openspec --version` and `--help` load 24 modules instead of 485, and commands such as `config list`, `store list` and `doctor` load only what they use, which matters most where Node loads modules slowly, such as Windows. Output, help text, shell completions, exit codes and telemetry are unchanged.

.changeset/requirement-length-strict.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+A requirement description over 500 characters is now a warning instead of an informational hint, so `openspec validate --strict` fails on it and CI can enforce the limit. The check also covers ADDED requirements in a change, so `openspec validate <change> --strict` catches a new overlong requirement before archive. Normal validation and archive are unchanged: they still pass when this is the only finding. The specs instruction now explains how to split an existing long requirement without losing its scenarios.

.changeset/sync-lifecycle-status.md

@@ -1,13 +0,0 @@
----
-"@fission-ai/openspec": minor
----
-
-Add `openspec sync`, which folds a change's delta specs into the main specs without archiving it, and an optional `status: proposed | shipped` field in a change's `.openspec.yaml`.
-
-`openspec sync --check` gates on one property: a change that claims to be shipped has its deltas in `specs/`. A proposed change passes for free, so the check is green as its resting state and red only on a real mistake — unlike a check for "is everything archived?", which is red for the whole life of every open pull request. It reads only files on disk, so a pre-commit hook, a pre-push hook and CI run the same command and agree.
-
-`openspec list --status <state>` filters changes by that field.
-
-Everything here is opt-in and inert by default. The `status` field is absent unless a project writes it, nothing generates it, and `archive` is unchanged.
-
-Designed by [@ixxie](https://github.com/ixxie) in [#1683](https://github.com/Fission-AI/OpenSpec/issues/1683) — the diagnosis that `archive` welds a state transition to a text merge, `shipped ⇒ folded` as a predicate over the working tree, and the standalone `sync` that makes it checkable. This ships a smaller, additive subset of that proposal.

.changeset/view-current-work-only.md

@@ -0,0 +1,5 @@
+---
+"@fission-ai/openspec": patch
+---
+
+`openspec view` no longer lists or counts archived changes. In projects with many archived changes, the list pushed active work off the screen. The dashboard shows current work again, and `openspec list --archived` still shows archived changes on request.

.github/CODEOWNERS

@@ -1,2 +1,5 @@
 # Default code ownership
 * @Fission-AI/openspec-maintainers
+
+# Route docs-lab changes to the docs owner for review
+/docs-lab/ @TabishB

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,68 @@
+name: Bug report
+description: Something in OpenSpec does not work the way it should.
+labels: ['bug', 'needs-triage']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting this.
+
+        You can also run `openspec feedback "your report"` to submit an issue
+        immediately with your version and platform, or get a submission link
+        if GitHub CLI is unavailable or unauthenticated.
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: The actual behavior. Paste the command you ran and its output if you have it.
+      placeholder: |
+        I ran `openspec archive add-login` and it exited 0 without writing the main spec.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected instead
+      placeholder: The main spec at openspec/specs/auth/spec.md should have been updated.
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal steps to reproduce
+      description: The shortest path from a fresh project to the problem. This is the single most useful thing you can give us.
+      placeholder: |
+        1. `openspec init` in an empty directory
+        2. ...
+        3. ...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: OpenSpec version
+      description: Output of `openspec --version`, or "unknown" if installation failed or the command cannot run.
+      placeholder: '1.11.0'
+    validations:
+      required: true
+
+  - type: input
+    id: agent
+    attributes:
+      label: Coding agent and model
+      description: Which agent and model were driving OpenSpec, if any. Behavior often differs between them.
+      placeholder: Claude Code, Opus 4.6
+    validations:
+      required: false
+
+  - type: input
+    id: environment
+    attributes:
+      label: OS and Node version
+      placeholder: macOS 15.6, Node 22.11.0
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,12 @@
+# Keep the prefilled blank-issue URL from `openspec feedback` working.
+blank_issues_enabled: true
+contact_links:
+  - name: Core design change
+    url: https://github.com/Fission-AI/OpenSpec/discussions/categories/ideas
+    about: Anything that changes how OpenSpec works at its core starts as a discussion, per CONTRIBUTING step 1.
+  - name: Question or help with your setup
+    url: https://github.com/Fission-AI/OpenSpec/discussions/categories/q-a
+    about: Not sure whether it is a bug? Ask here and we will help you narrow it down.
+  - name: Discord
+    url: https://discord.gg/YctCnvvshC
+    about: Chat with the community and the maintainers.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Something OpenSpec should do that it does not do yet.
+labels: ['enhancement', 'needs-triage']
+body:
+  - type: markdown
+    attributes:
+      value: |
+        If this would change OpenSpec's core design, open a
+        [discussion](https://github.com/Fission-AI/OpenSpec/discussions) instead — see
+        [CONTRIBUTING.md](https://github.com/Fission-AI/OpenSpec/blob/main/CONTRIBUTING.md).
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem, in one or two sentences
+      description: What you were trying to do, and where OpenSpec got in the way. Describe the problem, not the solution.
+      placeholder: There is no way to tell which change a spec came from after it is archived.
+    validations:
+      required: true
+
+  - type: textarea
+    id: who
+    attributes:
+      label: Who this affects
+      description: Just you, everyone on a particular agent, everyone using a particular workflow, or everyone. OpenSpec serves many agents and models, so this shapes whether a change fits.
+      placeholder: Anyone archiving more than a handful of changes.
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What you tried
+      description: Existing commands, flags, or workarounds you reached for, and why they fell short.
+    validations:
+      required: false
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: Optional. A sketch is fine — we will agree on the approach before anyone builds it.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+Closes #
+
+<!--
+No issue yet? Every change starts with one (CONTRIBUTING step 1).
+Run `openspec feedback "your report"` to submit immediately, or open one here:
+https://github.com/Fission-AI/OpenSpec/issues/new/choose
+
+Already discussed instead of filed? Replace the line above with a link to the discussion.
+-->
+
+## What this changes
+
+<!-- What was wrong or missing, and what the new behavior is. Plain language. -->
+
+## How you verified it
+
+<!--
+The failing-then-passing test, repro steps, or before/after output.
+Run the core checks for code changes:
+  pnpm build && pnpm test && pnpm exec tsc --noEmit && pnpm lint
+-->
+
+## Notes
+
+<!-- Optional: scope limits, follow-ups, anything non-blocking. -->
+
+---
+
+- [ ] Ran `pnpm changeset` if this affects users, and committed the file
+- [ ] If a coding agent wrote this, named the agent and model in the Notes section, and verified the result myself

.github/dependabot.yml

@@ -1,10 +1,14 @@
 version: 2
 
 # Dependabot does not manage two dependency surfaces in this repo:
-#   1. pnpm `overrides` (pnpm-workspace.yaml + package.json, root and website) —
-#      transitive version pins that remediate advisories Dependabot can't otherwise
-#      reach. It never bumps or removes these; each carries an inline advisory
-#      comment noting the removal condition (see pnpm-workspace.yaml).
+#   1. pnpm `overrides` (pnpm-workspace.yaml, root and website) — transitive
+#      version pins that remediate advisories Dependabot can't otherwise reach.
+#      It never bumps or removes these; each carries an inline advisory comment
+#      noting the removal condition (see pnpm-workspace.yaml). They live in
+#      pnpm-workspace.yaml only, because Dependabot *does* rewrite a plain-name
+#      override (`postcss: ^8.5.26`) mirrored under package.json's `pnpm.overrides`
+#      — and that block replaces the workspace list rather than merging with it,
+#      so the mirror displaces the real pins. See #1812.
 #   2. The Nix flake (flake.nix / flake.lock). Update nixpkgs manually with
 #      `nix flake update`; there is no Dependabot ecosystem for Nix. Note that the
 #      pnpmDeps FOD hash in flake.nix must be regenerated on any root lockfile change.

.github/workflows/ci.yml

@@ -42,6 +42,10 @@ jobs:
               - 'pnpm-workspace.yaml'
               - 'scripts/update-flake.sh'
               - '.github/workflows/ci.yml'
+              # The Nix build runs `openspec completion generate`, so a change to
+              # the generator can break packaging without touching flake.nix.
+              - 'src/commands/completion.ts'
+              - 'src/core/completions/**'
 
   test_matrix:
     name: Test (${{ matrix.label }})
@@ -77,7 +81,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -132,7 +136,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
@@ -176,10 +180,76 @@ jobs:
           persist-credentials: false
 
       - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+        uses: DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23
 
       - name: Setup Nix cache
-        uses: DeterminateSystems/magic-nix-cache-action@908b263ff629f4cc17666315b7fd3ec127c6244d # v14
+        uses: DeterminateSystems/magic-nix-cache-action@84c0677f58dcedf3b91f8223ce36a9ea5b3c84b7 # v15
+        with:
+          # Dependabot runs cannot access the FlakeHub credentials available to
+          # regular CI, so keep those runs on the GitHub Actions cache.
+          use-flakehub: ${{ github.event.pull_request.user.login == 'dependabot[bot]' && 'disabled' || 'no-preference' }}
+          use-gha-cache: ${{ github.event.pull_request.user.login == 'dependabot[bot]' && 'enabled' || 'no-preference' }}
+
+      # Run the update script before `nix build`, not after. The script recomputes
+      # the pnpmDeps hash from pnpm-lock.yaml and rewrites flake.nix in place, so a
+      # stale hash is reported here as the exact value to paste. Built first, the
+      # same staleness surfaces as pnpm's ERR_PNPM_NO_OFFLINE_TARBALL — which names
+      # a missing tarball, not the hash — and the script never runs to say otherwise.
+      # Every root lockfile change needs this value, and Dependabot cannot produce it.
+      - name: Verify pnpmDeps hash matches the lockfile
+        run: |
+          bash scripts/update-flake.sh
+          if git diff --quiet flake.nix; then
+            echo "✅ flake.nix pnpmDeps hash is up to date"
+            exit 0
+          fi
+          # Scoped to the pnpmDeps block: a bare first-match would report some other
+          # FOD's hash if one is ever added above it.
+          HASH=$(sed -n '/pnpmDeps = /,/};/p' flake.nix \
+            | sed -nE 's/.*hash = "(sha256-[^"]+)".*/\1/p' | head -1)
+          git diff flake.nix
+          echo "::error file=flake.nix::Stale pnpmDeps hash. Set pnpmDeps.hash to $HASH and push."
+          exit 1
+
+      - name: Restore flake.nix
+        if: always()
+        run: git checkout -- flake.nix || true
+
+      - name: Test downstream overlay composition
+        run: |
+          # Interpolation belongs to Nix, not the shell.
+          # shellcheck disable=SC2016
+          nix eval --impure --expr '
+            let
+              flake = builtins.getFlake (toString ./.);
+              system = builtins.currentSystem;
+              pkgs = import flake.inputs.nixpkgs {
+                inherit system;
+                overlays = [ flake.overlays.default ];
+              };
+              composed = import flake.inputs.nixpkgs {
+                inherit system;
+                overlays = [
+                  flake.overlays.default
+                  (_final: prev: {
+                    nodejs_22 = prev.nodejs_22.overrideAttrs (_: {
+                      pname = "openspec-test-nodejs";
+                    });
+                  })
+                ];
+              };
+              overridden = pkgs.openspec.overrideAttrs (_: { version = "0.0.0-test"; });
+            in
+            assert pkgs.openspec.drvPath == flake.packages.${system}.default.drvPath;
+            assert pkgs.openspec.drvPath == flake.packages.${system}.openspec.drvPath;
+            # stdenv selects the dev output of multi-output native build inputs.
+            assert builtins.any (input: input.drvPath == composed.nodejs_22.drvPath)
+              composed.openspec.nativeBuildInputs;
+            assert composed.openspec.drvPath != pkgs.openspec.drvPath;
+            assert overridden.version == "0.0.0-test";
+            assert overridden.pnpmDeps.version == "0.0.0-test";
+            true
+          '
 
       - name: Build with Nix
         run: nix build
@@ -194,6 +264,19 @@ jobs:
             echo "Error: openspec binary not found in build output"
             exit 1
           fi
+          for completion in \
+            "share/bash-completion/completions/openspec.bash" \
+            "share/fish/vendor_completions.d/openspec.fish" \
+            "share/zsh/site-functions/_openspec"; do
+            if [ ! -s "result/$completion" ]; then
+              echo "Error: completion script missing or empty: $completion"
+              exit 1
+            fi
+          done
+          if [ "$(head -1 result/share/zsh/site-functions/_openspec)" != "#compdef openspec" ]; then
+            echo "Error: zsh completion is not autoloadable (missing #compdef header)"
+            exit 1
+          fi
           echo "✅ Build output verified"
 
       - name: Test binary execution
@@ -206,25 +289,6 @@ jobs:
           fi
           echo "✅ Binary execution successful"
 
-      - name: Validate update script
-        run: |
-          echo "Testing update-flake.sh script..."
-          bash scripts/update-flake.sh
-          echo "✅ Update script executed successfully"
-
-      - name: Check flake.nix modifications
-        run: |
-          if git diff --quiet flake.nix; then
-            echo "ℹ️  flake.nix unchanged (hash already up-to-date)"
-          else
-            echo "✅ flake.nix was updated by script"
-            git diff flake.nix
-          fi
-
-      - name: Restore flake.nix
-        if: always()
-        run: git checkout -- flake.nix || true
-
   validate-changesets:
     name: Validate Release Tracking
     runs-on: ubuntu-latest
@@ -242,10 +306,14 @@ jobs:
           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"
+            # Run-unique delimiter: the value is a list of PR-authored paths, so a
+            # fixed "EOF" would let a crafted path close the block early and append
+            # its own key=value outputs.
+            delim="EOF_$(openssl rand -hex 16)"
             {
-              echo "files<<EOF"
+              echo "files<<$delim"
               echo "$changed_changesets"
-              echo "EOF"
+              echo "$delim"
             } >> "$GITHUB_OUTPUT"
           else
             echo "has_changesets=false" >> "$GITHUB_OUTPUT"
@@ -254,7 +322,7 @@ jobs:
 
       - name: Setup pnpm
         if: steps.changed-changesets.outputs.has_changesets == 'true'
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         if: steps.changed-changesets.outputs.has_changesets == 'true'

.github/workflows/release-prepare.yml

@@ -40,7 +40,7 @@ jobs:
           fetch-depth: 0
           token: ${{ steps.app-token.outputs.token }}
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
@@ -53,7 +53,7 @@ jobs:
       # Opens/updates the Version Packages PR; publishes when the Version PR merges
       - name: Create/Update Version PR
         id: changesets
-        uses: changesets/action@8488615a623b1b9c987934bb89eae8af6a946ac1 # v2.1.1
+        uses: changesets/action@ae32849d5ba541f9ae29e40e22a623bc13562f51 # v2.1.2
         with:
           github-token: ${{ steps.app-token.outputs.token }}
           pr-title: 'chore(release): version packages'
@@ -84,7 +84,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+      - uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:

.github/workflows/security.yml

@@ -51,7 +51,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       # No dependency cache: `pnpm audit` reads the lockfile, nothing is installed,
       # so a cache-save step would fail on the missing store path.
@@ -109,7 +109,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
 
       - name: Setup Node.js
         uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0

CHANGELOG.md

@@ -1,5 +1,267 @@
 # @fission-ai/openspec
 
+## 1.14.0
+
+### Minor Changes
+
+- [#883](https://github.com/Fission-AI/OpenSpec/pull/883) [`c879d13`](https://github.com/Fission-AI/OpenSpec/commit/c879d13d5f5d045c532a08523316d2d74f2db99a) Thanks [@Code-Studio-Team](https://github.com/Code-Studio-Team)! - Add Code Studio as an `init` and `update` target, with project skills and `.prompt.md` commands under `.codestudio/`.
+
+- [#1672](https://github.com/Fission-AI/OpenSpec/pull/1672) [`297092c`](https://github.com/Fission-AI/OpenSpec/commit/297092cb25d9831a408d2ce9bfd55daec1431b74) Thanks [@DarkskyX15](https://github.com/DarkskyX15)! - - **DeepSeek Harness** — `openspec init --tools dsh` (command-line id `dsh`) installs the OpenSpec workflow skills into `.dsh/skills/` for DeepSeek Harness. It is skills-only (no command adapter or command files): dsh discovers the generated `SKILL.md` files as its highest-priority project root and surfaces them through its skill catalog, `skill` tool, and `/openspec-*` user invocations.
+
+- [#1961](https://github.com/Fission-AI/OpenSpec/pull/1961) [`3c3e6e3`](https://github.com/Fission-AI/OpenSpec/commit/3c3e6e3d423625ffe554ff050c09bb530f17dc5e) Thanks [@fresh-fx59](https://github.com/fresh-fx59)! - Add GigaCode as a supported `--tools` target, with skills in `.gigacode/skills/openspec-*/SKILL.md` and Markdown commands in `.gigacode/commands/opsx-<id>.md`.
+
+- [#1211](https://github.com/Fission-AI/OpenSpec/pull/1211) [`3de7c72`](https://github.com/Fission-AI/OpenSpec/commit/3de7c72c267c40ff89809d2ae08b7bf6ac6faf8c) Thanks [@hu-qi](https://github.com/hu-qi)! - Add AtomCode support through `openspec init --tools atomcode`, with project skills in `.atomcode/skills/` and `/opsx-<id>` commands in `.atomcode/commands/`. Generated commands declare `args: optional` and receive `$ARGUMENTS` when the workflow reads invocation input, and `args: none` when it does not, so AtomCode runs them straight from the slash menu. Follows the selected workflow profile and delivery mode.
+
+- [#1082](https://github.com/Fission-AI/OpenSpec/pull/1082) [`a7f08b8`](https://github.com/Fission-AI/OpenSpec/commit/a7f08b8a462db5eeddae4e0b03f427987e3806a2) Thanks [@Storm-Chaser](https://github.com/Storm-Chaser)! - ### New Features
+  
+  - **GSD support**: Install OpenSpec workflows as project skills with `openspec init --tools gsd`.
+
+- [#420](https://github.com/Fission-AI/OpenSpec/pull/420) [`070de01`](https://github.com/Fission-AI/OpenSpec/commit/070de01dfac4ea343747fbd37b9bb9e77acdf7d0) Thanks [@jeanduplessis](https://github.com/jeanduplessis)! - ### New Features
+  
+  - **Amp support**: select `amp` during init to install OpenSpec workflows as project skills under `.agents/skills/`.
+
+- [#2001](https://github.com/Fission-AI/OpenSpec/pull/2001) [`56528ea`](https://github.com/Fission-AI/OpenSpec/commit/56528ea454a926159d05eb7c9ec1b687d7544b56) Thanks [@clay-good](https://github.com/clay-good)! - ### New Features
+  
+  - **Version reports** — Run `openspec version` to inspect the installed version and install type, or add `--check` and `--json` for structured update information that tools can consume.
+
+- [#1352](https://github.com/Fission-AI/OpenSpec/pull/1352) [`d1642cb`](https://github.com/Fission-AI/OpenSpec/commit/d1642cb58cb4ce2cda0a140cf2322aded53f4e46) Thanks [@redknox](https://github.com/redknox)! - Add EasyCode support to init and update, with project-local skills and TOML commands invoked as `/opsx:<id>`.
+
+- [#399](https://github.com/Fission-AI/OpenSpec/pull/399) [`ded99e2`](https://github.com/Fission-AI/OpenSpec/commit/ded99e27de71c32647ae7fc2f51112219420b5d5) Thanks [@ZEDce](https://github.com/ZEDce)! - Add `openspec list --archived` and `--all` to browse archived changes, including JSON output and sorting. Show archived changes separately in the `openspec view` dashboard.
+
+- [#848](https://github.com/Fission-AI/OpenSpec/pull/848) [`5a360c2`](https://github.com/Fission-AI/OpenSpec/commit/5a360c2088ad3094a092c34993eab97b43c25124) Thanks [@Columpio](https://github.com/Columpio)! - ### New Features
+  
+  - **Veai support**: select `veai` during init to install OpenSpec workflows as project skills under `.veai/skills/`.
+
+- [#1439](https://github.com/Fission-AI/OpenSpec/pull/1439) [`f197804`](https://github.com/Fission-AI/OpenSpec/commit/f197804a38057eee2272952b74d89884a9d3b7a4) Thanks [@jmuchovej](https://github.com/jmuchovej)! - Expose OpenSpec as a reusable Nix overlay through `overlays.default`.
+
+- [#1349](https://github.com/Fission-AI/OpenSpec/pull/1349) [`e232080`](https://github.com/Fission-AI/OpenSpec/commit/e232080d0943bd535388bdc2304b3301f1496226) Thanks [@0x6d6e647a](https://github.com/0x6d6e647a)! - Add Grok Build as a skills-only tool. Run `openspec init --tools grok` to install skills in `.grok/skills`, then invoke them with `/openspec-propose` and other skill names. Existing Grok installations are refreshed by `openspec update`.
+
+- [#1738](https://github.com/Fission-AI/OpenSpec/pull/1738) [`781c7f9`](https://github.com/Fission-AI/OpenSpec/commit/781c7f9447b4eeb6fdc69fa745ff46f6168f3edf) Thanks [@clay-good](https://github.com/clay-good)! - Add Warp support through project-local skills. Select `warp` during init to install OpenSpec workflows in `.warp/skills`, invoke them with `/openspec-*`, and refresh them with `openspec update`. Skills remain available in every delivery mode.
+
+- [#807](https://github.com/Fission-AI/OpenSpec/pull/807) [`c21d897`](https://github.com/Fission-AI/OpenSpec/commit/c21d897261b5daf0c61c49ccd0862288d4664db4) Thanks [@Million-mo](https://github.com/Million-mo)! - ### New Features
+  
+  - **Dashboard workflow status**: `openspec view` now shows each active change's schema and which artifacts are done, ready, blocked, or skipped. Task progress remains visible if a workflow cannot be loaded. Thanks to @Million-mo for the original contribution in [#807](https://github.com/Fission-AI/OpenSpec/issues/807).
+
+### Patch Changes
+
+- [#1977](https://github.com/Fission-AI/OpenSpec/pull/1977) [`7728194`](https://github.com/Fission-AI/OpenSpec/commit/772819417a2aa8a90cd50743139f402261628d21) Thanks [@clay-good](https://github.com/clay-good)! - The `openspec-archive-change` skill no longer tells the agent to run the `openspec-sync-specs` skill when that skill is not installed. It merges the delta specs into the main specs itself instead, as the `/opsx:archive` command already did ([#1975](https://github.com/Fission-AI/OpenSpec/issues/1975)).
+
+- [#1722](https://github.com/Fission-AI/OpenSpec/pull/1722) [`817cdb6`](https://github.com/Fission-AI/OpenSpec/commit/817cdb64be744d4ee65d1a9922b23edc0c4699b8) Thanks [@caseyg](https://github.com/caseyg)! - ### Bug Fixes
+  
+  - IBM Bob now appears by its full product name in the tool picker and success messages. Existing `bob` selections, configuration, skills, and slash-command paths continue to work unchanged.
+
+- [#1999](https://github.com/Fission-AI/OpenSpec/pull/1999) [`bda8556`](https://github.com/Fission-AI/OpenSpec/commit/bda85565ef974d07c1c202c0ac4b2613241dd184) Thanks [@clay-good](https://github.com/clay-good)! - Guide users through an AI-assisted migration from legacy `project.md` to `config.yaml`.
+
+- [#1997](https://github.com/Fission-AI/OpenSpec/pull/1997) [`e70dcc7`](https://github.com/Fission-AI/OpenSpec/commit/e70dcc7c82a3b100145795d32ea9930dca7b4073) Thanks [@clay-good](https://github.com/clay-good)! - Guide proposal authors toward durable, behavior-based capability names.
+
+- [#2018](https://github.com/Fission-AI/OpenSpec/pull/2018) [`81c2f9f`](https://github.com/Fission-AI/OpenSpec/commit/81c2f9fce30d103bd22377042af1d428453b0bbc) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **Apply edits the right task** — `openspec instructions apply --json` now gives each task its `sourcePath` and `line`. The apply workflow checks the checkbox at that location before marking the task done and rechecks progress afterward, so agents update the exact task, even when tasks span several files.
+  - **Archive stops on a failed spec sync** — When the spec sync inside `/opsx:archive` reports a blocking condition, such as a capability retirement it could not complete, the archive now stops and leaves the change in place instead of archiving it with the main specs unchanged. The same applies to bulk archive.
+  - **Aligned `openspec view` progress bars** — Active change names up to 48 characters now line up their progress bars instead of pushing each bar out of line.
+
+- [#1969](https://github.com/Fission-AI/OpenSpec/pull/1969) [`9557b43`](https://github.com/Fission-AI/OpenSpec/commit/9557b43aaff05af8bd9862c4755f7ac7b7f43cf1) Thanks [@flcrom](https://github.com/flcrom)! - ### Bug Fixes
+  
+  - Let store-only repositories run `openspec init` at the repo root to install integrations without changing the external-store config or creating local planning directories.
+
+- [#2004](https://github.com/Fission-AI/OpenSpec/pull/2004) [`d4e1c77`](https://github.com/Fission-AI/OpenSpec/commit/d4e1c77ebae0bd96a7c649fa35edef997989450a) Thanks [@clay-good](https://github.com/clay-good)! - Warn that files listed for legacy cleanup are deleted entirely and ask users to back up custom content first. The `openspec/AGENTS.md` check detects the file by existence alone.
+
+- [#1995](https://github.com/Fission-AI/OpenSpec/pull/1995) [`baad449`](https://github.com/Fission-AI/OpenSpec/commit/baad4494b48f1497ec2f73a457210c5567176942) Thanks [@clay-good](https://github.com/clay-good)! - Guide agents to keep project documentation and codebase facts out of `config.yaml` context.
+
+- [#1978](https://github.com/Fission-AI/OpenSpec/pull/1978) [`1872982`](https://github.com/Fission-AI/OpenSpec/commit/187298289dc5a7a63df87425151981586cbe5d7e) Thanks [@clay-good](https://github.com/clay-good)! - The specs instruction now tells agents the 500-character requirement length that `openspec validate` flags as an informational hint, and how to stay under it when writing new requirements without splitting existing ones. The validator's too-long message now explains how to split a requirement too.
+
+- [#1972](https://github.com/Fission-AI/OpenSpec/pull/1972) [`d28fb49`](https://github.com/Fission-AI/OpenSpec/commit/d28fb49c1ca901fe19fa443a56ede37ff8b8c61a) Thanks [@ryandemelo](https://github.com/ryandemelo)! - `show --json` now includes each requirement's and scenario's `name`, matching the header names archive uses, so JSON readers can cite a requirement without parsing the markdown again ([#1971](https://github.com/Fission-AI/OpenSpec/issues/1971)).
+
+- [#2014](https://github.com/Fission-AI/OpenSpec/pull/2014) [`cf2859a`](https://github.com/Fission-AI/OpenSpec/commit/cf2859a52089dd6dd37f9b3388db90c2ca3f06e7) Thanks [@clay-good](https://github.com/clay-good)! - Fix `status --json` for store-backed changes: `actionContext.allowedEditRoots` now lists the project on the current path that declares the store alongside the store, so apply no longer stops on a store-only edit scope. When no project on the current path declares the store, the constraint tells the agent to ask which repository to edit instead of naming the store.
+
+- [#1984](https://github.com/Fission-AI/OpenSpec/pull/1984) [`42671df`](https://github.com/Fission-AI/OpenSpec/commit/42671df890fab730058fee108a2090e7c1e491b9) Thanks [@Yi-111-a](https://github.com/Yi-111-a)! - Name the offending index when a `rules:` list is not an array of strings
+  
+  A rule item containing an unquoted `": "` is valid-looking YAML but parses as a
+  mapping, so the artifact's whole rule set is dropped with only a stderr warning
+  naming the artifact. The warning now also names the index and the shape YAML
+  produced there, plus the quoting fix, so the bad item can be found without
+  bisecting the list by hand.
+
+- [#1925](https://github.com/Fission-AI/OpenSpec/pull/1925) [`88692b3`](https://github.com/Fission-AI/OpenSpec/commit/88692b3bb42262d30172819936847ed10f42a98f) Thanks [@kevin9327](https://github.com/kevin9327)! - ### Bug Fixes
+  
+  - **Change metadata** — Warn when `.openspec.yaml` contains unrecognized keys such as `skip_design`. Those keys were stripped with no signal, so `status` still demanded the design artifact and `validate --strict` exited 0. `status`, `validate`, and `archive` now name the ignored keys; `validate --strict` fails.
+
+- [#2016](https://github.com/Fission-AI/OpenSpec/pull/2016) [`cd4f9e4`](https://github.com/Fission-AI/OpenSpec/commit/cd4f9e4a5f99e7b48f2c452ef0fa3769db4dde4a) Thanks [@huiq777](https://github.com/huiq777)! - Make `openspec completion uninstall zsh` hand `.zshrc` back exactly as `completion install zsh` found it. Uninstall stripped every blank line at the top of the file, so a `.zshrc` that started with blank lines lost them after an install/uninstall round trip, even when the OpenSpec block had been moved further down. Uninstall now drops only the separator line install added, and only when the block sits at the top of the file, matching the bash installer.
+
+## 1.13.2
+
+### Patch Changes
+
+- [#1940](https://github.com/Fission-AI/OpenSpec/pull/1940) [`0b5ce44`](https://github.com/Fission-AI/OpenSpec/commit/0b5ce44b55e0d793a312290ba5a41170a78e47c6) Thanks [@clay-good](https://github.com/clay-good)! - Keep fast-forward clarification guidance and onboarding task approval consistent across generated skills and commands. Fast-forward now asks only when context is critically unclear, while onboarding asks users to approve the task breakdown before saving it and separately asks whether to begin implementation.
+
+- [#1926](https://github.com/Fission-AI/OpenSpec/pull/1926) [`f2812f6`](https://github.com/Fission-AI/OpenSpec/commit/f2812f6d185f47cb577055f2fe243f12000d6cd2) Thanks [@kevin9327](https://github.com/kevin9327)! - ### Bug Fixes
+  
+  - **Archive** — When Windows `EPERM` blocks renaming a change directory that still has children, copy from the original source instead of requiring a staging rename that fails the same way. That lets archive finish instead of rolling back the spec write and leaving an empty capability directory git cannot see. A staging failure that is not `EPERM`/`EXDEV` still leaves the source untouched.
+  
+    The source of that unstaged copy is still the live change directory, which the archive claim does not cover, so cleanup removes only the entries it copied and verified rather than whatever is present when it runs. A file written in that window is left alone and the complete destination is retained for recovery, instead of being deleted without ever reaching the archive.
+  
+    An edit to a file that was already verified is covered too. Cleanup claims each entry with an atomic rename before reading it, then compares what it claimed against the copy. A rewrite that lands first is caught by that comparison and the file is put back; one that lands after creates a new file at the original path, which is never deleted. Either way the newer bytes stay on disk and archive reports the move as incomplete rather than succeeding with the older copy.
+  
+    Rollback of a newly created spec now also prunes the capability directory it created — and only that one. An empty capability directory that was already there is left in place with its own permissions.
+
+- [#1795](https://github.com/Fission-AI/OpenSpec/pull/1795) [`fb1b876`](https://github.com/Fission-AI/OpenSpec/commit/fb1b87613b7cdbe8d74e8147833904f46f0468c6) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Archive workflows now use schema-aware task progress from `openspec list --json`, so custom task files and globs still trigger incomplete-task warnings.
+
+- [#1885](https://github.com/Fission-AI/OpenSpec/pull/1885) [`fd56e12`](https://github.com/Fission-AI/OpenSpec/commit/fd56e12c9e7fdbbfdc2dcd0a5ef3fab04840909d) Thanks [@philo-x](https://github.com/philo-x)! - Fix artifact output resolution to recognize brace expansion and extglob patterns while preserving literal output filenames and confining brace-expanded paths to the change directory.
+
+- [#1964](https://github.com/Fission-AI/OpenSpec/pull/1964) [`7ac58dc`](https://github.com/Fission-AI/OpenSpec/commit/7ac58dc7905a4eeaaad7eff2b2b64cf971fd6ec7) Thanks [@clay-good](https://github.com/clay-good)! - Continue commands now open with an instruction to follow the active OpenSpec workflow directly, so local models no longer try to call a tool named after it ([#1944](https://github.com/Fission-AI/OpenSpec/issues/1944)).
+
+- [#1964](https://github.com/Fission-AI/OpenSpec/pull/1964) [`7ac58dc`](https://github.com/Fission-AI/OpenSpec/commit/7ac58dc7905a4eeaaad7eff2b2b64cf971fd6ec7) Thanks [@clay-good](https://github.com/clay-good)! - Generate Kilo Code commands in `.kilo/command/`, the directory Kilo Code reads, instead of `.kilocode/workflows/` ([#1938](https://github.com/Fission-AI/OpenSpec/issues/1938)). `openspec init` and legacy cleanup remove the workflow files OpenSpec generated there, matched by their known file names (including copies you edited), and leave files with other names in place.
+
+- [#1958](https://github.com/Fission-AI/OpenSpec/pull/1958) [`1d35e90`](https://github.com/Fission-AI/OpenSpec/commit/1d35e908804dbb3c4a1851516759c5de190aa4d5) Thanks [@clay-good](https://github.com/clay-good)! - Preserve a file's existing line endings when rewriting it, so Windows users no longer get whole-file diffs. Applying a delta to a CRLF spec (the default on a Windows checkout with `core.autocrlf=true`) rewrote the file to LF, turning a one-requirement change into a diff that touched every line. `openspec archive` now writes the spec back with the convention it already used; a spec that does not exist yet is still written with LF.
+  
+  The same fix covers marker-managed files: installing or updating shell completions in a CRLF `.bashrc` or `.zshrc` no longer leaves the file with mixed endings, which `bash` reports as `$'\r': command not found`.
+  
+  Removing a managed block is fixed the same way: the blank-line collapse in `removeMarkerBlock` rebuilt its separator as a bare LF, so cleaning up legacy artifacts left a lone LF inside an otherwise-CRLF `CLAUDE.md` or rc file. Both write paths now read the file the same way, by dominant ending, so one stray CRLF in an otherwise-LF file no longer pulls the whole rewrite to CRLF.
+  
+  `scripts/pack-version-check.mjs` now spawns `npm` through `cross-spawn`, so the release guard can run on Windows, where `npm` is `npm.cmd` and cannot be resolved by `execFile`.
+
+- [#1912](https://github.com/Fission-AI/OpenSpec/pull/1912) [`8826c0c`](https://github.com/Fission-AI/OpenSpec/commit/8826c0c4a17d3511947b7c5e0934257f153f0ed2) Thanks [@Tyagiquamar](https://github.com/Tyagiquamar)! - Fix `validate --strict` reporting `PURPOSE_IS_PLACEHOLDER` for a Purpose that opens with the ordinary word "Todo" followed by prose, as in Spanish ("Todo el…") and Portuguese ("Todo o…") specs ([#1897](https://github.com/Fission-AI/OpenSpec/issues/1897)).
+  
+  - Case now separates the marker from the word. `TBD`/`TODO` in capitals is still a placeholder marker whatever follows it, so `TODO write this later` is still reported.
+  - In any other case it counts as a marker only when followed by the end of the Purpose, a line break, or marker punctuation (`todo -`, `tbd.`), so an authored Spanish or Portuguese sentence is not reported.
+
+- [#1744](https://github.com/Fission-AI/OpenSpec/pull/1744) [`5b55263`](https://github.com/Fission-AI/OpenSpec/commit/5b5526377506c2f0179674a869c1ac64ca9ab72d) Thanks [@javigomez](https://github.com/javigomez)! - Clarify the Codex setup hint for CLI, IDE, and desktop app users.
+
+- [#1809](https://github.com/Fission-AI/OpenSpec/pull/1809) [`a5ceea3`](https://github.com/Fission-AI/OpenSpec/commit/a5ceea32cf110b6d8bbfea0bf1c65fe55abb133b) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Say what a `MODIFIED` block adds when the scenario-loss guard fires ([#1809](https://github.com/Fission-AI/OpenSpec/pull/1809)). `openspec validate` and `openspec archive` already named the scenarios a block omits. They now also print how many scenarios each side has and which ones the block introduces, capped at three names, so a rename and a truncation read differently without opening either file. The guard catches exactly what it did before, and no exit code changes.
+
+- [#1731](https://github.com/Fission-AI/OpenSpec/pull/1731) [`d6bdef6`](https://github.com/Fission-AI/OpenSpec/commit/d6bdef6577a077614382ef47b64100852182d6a6) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Stop workflows from displaying schema names that `openspec list --json` does not return. Update and continue no longer fabricate a `spec-driven` picker label, while bulk archive and explore describe only the change fields the list command actually provides.
+
+- [#1955](https://github.com/Fission-AI/OpenSpec/pull/1955) [`ed5d386`](https://github.com/Fission-AI/OpenSpec/commit/ed5d386a559c0215af1182d479d7f99b309fdcd2) Thanks [@clay-good](https://github.com/clay-good)! - Task guidance now requires each task group to land its own tests and documentation updates instead of deferring them to a trailing group. The onboarding walkthrough teaches the same rule, and the published schema reference no longer quotes stale instruction text.
+
+- [#1939](https://github.com/Fission-AI/OpenSpec/pull/1939) [`a64303f`](https://github.com/Fission-AI/OpenSpec/commit/a64303fe1e24f08dbf44f78032fadbeac3a6f7fa) Thanks [@clay-good](https://github.com/clay-good)! - Return a nonzero exit status when `openspec update --force` cannot replace a legacy-only Codex installation.
+
+- [#1733](https://github.com/Fission-AI/OpenSpec/pull/1733) [`72fbe4c`](https://github.com/Fission-AI/OpenSpec/commit/72fbe4c904707396151921a20b506d081a9dc024) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Let `/opsx:update` fill a missing file under an already-satisfied glob artifact. A glob artifact is complete once one file matches it, and `/opsx:continue` only picks up `ready` artifacts, so the previous "point the user to `/opsx:continue`" handoff was unreachable and the missing file could never be created through the documented flow.
+
+- [#1962](https://github.com/Fission-AI/OpenSpec/pull/1962) [`3364146`](https://github.com/Fission-AI/OpenSpec/commit/336414665f3f987ae424177ab1b6891a4304baeb) Thanks [@ryandemelo](https://github.com/ryandemelo)! - Stop `/opsx:verify` from reporting a correctly removed requirement as missing. Verify now reads which delta section each requirement sits under: ADDED and MODIFIED requirements are checked for an implementation as before, a REMOVED requirement passes once its behavior is gone and is flagged only while it is still present, and the old name of a RENAMED requirement is no longer reported as missing.
+
+- [#1732](https://github.com/Fission-AI/OpenSpec/pull/1732) [`072de6b`](https://github.com/Fission-AI/OpenSpec/commit/072de6bc39b1c47b9aacf4d484be16345ca4f38e) Thanks [@runsonmypc](https://github.com/runsonmypc)! - Stop `/opsx:verify` from reporting skipped checks as passing. Task completion now uses the schema-aware `tasks` and `progress` fields returned by apply instructions, while absent spec or design inputs are mapped to every check they prevent. Apply instructions aggregate every file matched by the configured task path or glob, regardless of the tracked artifact ID. Verification stays advisory and does not require optional or intentionally omitted artifacts. The scorecard identifies each skipped check, and the final assessment does not claim archive readiness when any check did not run.
+
+- [#1769](https://github.com/Fission-AI/OpenSpec/pull/1769) [`d3d7707`](https://github.com/Fission-AI/OpenSpec/commit/d3d770736fc01bb246b4f12a7cef7e3572ec1fb6) Thanks [@kikeprzn](https://github.com/kikeprzn)! - Fix `openspec archive` leaving `.openspec-archive.lock` behind on Windows. Node can report `dev: 0n` from a path stat while the open file handle reports the real volume id, so the claim-ownership check never matched and the stale lock blocked every later archive. The check now treats an absent device id as unavailable while still requiring the inode and the claim's contents to match before unlinking.
+
+## 1.13.1
+
+### Patch Changes
+
+- [#1864](https://github.com/Fission-AI/OpenSpec/pull/1864) [`767d63c`](https://github.com/Fission-AI/OpenSpec/commit/767d63c926ab1996170f2d101acac0bac6da0287) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archive adding a second copy of an existing requirement under a name that differs only in case or spacing. ADDED and the RENAMED target compared requirement names exactly, while REMOVED and the RENAMED source already treated a case or whitespace variant as a mistyped header, so an ADDED `late fees` beside an existing `Late Fees`, or a rename to `LATE FEES`, archived cleanly and left two contradicting requirements in the main spec, which `validate` then accepted. Both now refuse with an error naming the existing requirement, in the same form REMOVED already used. The exact-duplicate error is unchanged, a case-only rename of a requirement to its own name still works, and a variant of a requirement the same delta removes or renames away is still allowed, because ADDED is checked against the spec as it stands after the earlier operations, as the exact check already was.
+
+- [#1872](https://github.com/Fission-AI/OpenSpec/pull/1872) [`72bf760`](https://github.com/Fission-AI/OpenSpec/commit/72bf7600a5f7bdf74d6387e163577086fb4c68e0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Make `openspec completion uninstall bash` hand `.bashrc` back exactly as `completion install bash` found it. Install adds the OpenSpec block at the top of the file followed by a blank separator line; uninstall removed the block but kept that blank line at the top, then stripped every trailing blank line and wrote the file back without its final newline. The byte count happened to come out unchanged, but the next tool to append to `.bashrc` with `>>` (the nvm, conda and rustup installers all do) merged its first line into the user's last line and broke both. Uninstall now also drops the separator line install added when the block sits at the top of the file, and leaves the rest untouched: the final newline, trailing blank lines and CRLF line endings all survive the round trip. A block the user moved elsewhere in the file is still removed, and the zsh, fish and PowerShell installers are unchanged.
+
+- [#1829](https://github.com/Fission-AI/OpenSpec/pull/1829) [`e67ac47`](https://github.com/Fission-AI/OpenSpec/commit/e67ac47f3a164cf6d87ddcd9f50272b88f39ee0c) Thanks [@choi138](https://github.com/choi138)! - Fix bulk archive nesting a change inside an existing archive target. The workflow now checks every archive target before it writes any main spec, the same order `openspec archive` uses. A change whose target already exists, or that shares a target with another selected change, is reported as failed and is never synced or moved, while the rest of the batch continues. The check runs again just before each move.
+
+- [#1878](https://github.com/Fission-AI/OpenSpec/pull/1878) [`2ef6fbd`](https://github.com/Fission-AI/OpenSpec/commit/2ef6fbde3da95f6e471bcb504d13711308091be0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Let `openspec config edit` run an `EDITOR` or `VISUAL` that carries arguments. The whole value was passed to `spawn` as the program name, so common settings such as `code --wait`, `subl -w` or `emacsclient -t` failed with `spawn code --wait ENOENT`, and because that error was never caught the command died with a raw Node stack trace. The value is now split into a program and its arguments, honoring quoted paths with spaces, and the config path is appended as its own argument. No shell is involved, so shell metacharacters in the value are passed through literally. On Windows, `.cmd` shims such as `code.cmd` are found. A value that is itself the absolute path of an existing file is still run as-is, so an unquoted editor path containing spaces keeps working. An editor that cannot be started, exits non-zero or is killed is now reported as a one-line error naming the editor, with an install hint when the program was not found, and the command exits 1 instead of throwing. `EDITOR` still takes precedence over `VISUAL`, and the file is still validated after the editor closes.
+
+- [#1773](https://github.com/Fission-AI/OpenSpec/pull/1773) [`11a9691`](https://github.com/Fission-AI/OpenSpec/commit/11a9691524bad84a575854bf6dc5124f630479ba) Thanks [@clay-good](https://github.com/clay-good)! - Stop dropping checkbox lines whose marker the task parser does not recognise. A `tasks.md` whose remaining work used a marker other than `[ ]`/`[x]`/`[X]`, for example `- [~] 1.2 Deferred`, reported `✓ Complete` in `openspec list`/`status` and archived with no incomplete-task warning, because unmatched lines counted toward neither the numerator nor the denominator. An empty `[]` and a padded `[ x]` were lost the same way. Only a box holding `x` or `X` means done (spacing inside the brackets is ignored, so `[ x]` is done), and every other marker now reads as unfinished, across progress, the apply task list, archive's gate and validate's task-numbering check. The archive, bulk-archive and verify workflows now tell agents the same rule, so a hand-counted tally cannot disagree with the CLI, and the `tasks` instruction in the `spec-driven` schema states it where agents author the file. Markdown link bullets stay out of the count: `- [Some doc](./doc.md)` and the one-character `- [A](https://example.com)` are not tasks.
+
+- [#1701](https://github.com/Fission-AI/OpenSpec/pull/1701) [`92fb72d`](https://github.com/Fission-AI/OpenSpec/commit/92fb72d1dcd5fa6e43802c5b2f74b5e78416e545) Thanks [@clay-good](https://github.com/clay-good)! - Agent-driven archive and sync workflows now create a missing main spec from `ADDED` requirements instead of treating it as already synced. They block sync rather than inventing `MODIFIED` or `RENAMED` requirements or writing an empty spec for a `REMOVED`-only delta, while preserving the user's explicit choice to archive without syncing. A REMOVED-only delta with `retire_capabilities: true` remains already synced when its main spec is gone. Fixes [#1222](https://github.com/Fission-AI/OpenSpec/issues/1222) and [#1264](https://github.com/Fission-AI/OpenSpec/issues/1264).
+
+- [#1804](https://github.com/Fission-AI/OpenSpec/pull/1804) [`a5bf5c6`](https://github.com/Fission-AI/OpenSpec/commit/a5bf5c68447f03e4f99206e49e00b5d9111301a4) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Say so when a requirement in a delta sits outside every delta section. A well-formed `### Requirement:` block written under `## Notes`, under a misspelled header such as `## Add Requirements`, or above the first `## ` header was dropped with no diagnostic: `openspec validate` reported the change valid and `openspec archive` exited 0 without applying it. `openspec validate` now reports each one as a WARNING naming the section and line, and archive prints the same warning. Nothing else changes: the block is still not applied, the verdict stays valid outside `--strict`, and requirements shown inside a code fence are not reported. Fixes [#1803](https://github.com/Fission-AI/OpenSpec/issues/1803).
+
+- [#1832](https://github.com/Fission-AI/OpenSpec/pull/1832) [`4c369e0`](https://github.com/Fission-AI/OpenSpec/commit/4c369e022b1d397842d2b85675e34da6287f5801) Thanks [@clay-good](https://github.com/clay-good)! - Resolve the contradiction that left explore mode's capture branch without a governing rule. Explore states twice that the agent must ask a direct yes/no question and wait for confirmation in a separate user message before its first write-capable action, naming `openspec new change` as an example, while the capture branch tells the agent to transition "seamlessly" into running `openspec new change` and creating artifacts with no confirmation step. Both readings were defensible from the text, so the same "capture this as a change" request either wrote `.openspec.yaml` plus several artifacts immediately or stopped and asked, depending on which passage the agent weighed, which made the [#1715](https://github.com/Fission-AI/OpenSpec/issues/1715) guarantee unenforceable in the one explore path that writes files. An explicit capture request is now stated to be that confirmation, covering the change and the artifacts the request names and nothing else. The guardrail keeps its teeth for the case [#1715](https://github.com/Fission-AI/OpenSpec/issues/1715) actually reported: when the agent is the one proposing the capture, or when the work would go beyond the requested scope, it still asks first, and answers to design or clarifying questions are still never consent to write. Both explore delivery surfaces and the committed skill carry the same wording. Fixes [#1828](https://github.com/Fission-AI/OpenSpec/issues/1828).
+
+- [#1788](https://github.com/Fission-AI/OpenSpec/pull/1788) [`62106f4`](https://github.com/Fission-AI/OpenSpec/commit/62106f40e3b7b7364529a2f928717e23e37282eb) Thanks [@clay-good](https://github.com/clay-good)! - Name the workflow where explore hands off. Explore mode refuses to implement, but every place it said what to do instead described the next step as prose ("create a change proposal") without naming the workflow that does it: the refusal itself, the "flow into a proposal" ending, the closing summary, and the do-not-implement guardrail. Its seamless capture path was worse: it scaffolded a change, wrote artifacts, and then said nothing at all about what came next. With no named exit, agents finished the discovery questions and started writing code, which is the failure reported through GitHub Copilot in [#869](https://github.com/Fission-AI/OpenSpec/issues/869), and which the docs already promised would not happen ("when the picture is clear, it hands off to `/opsx:propose`").
+  
+  The explore skill and command now name `/opsx:propose` at all four prose handoffs, and the capture path ends by naming `/opsx:propose` for the remaining planning artifacts and `/opsx:apply` for implementation, with an explicit note that capturing artifacts is not permission to implement them. The references are written in the canonical `/opsx:<id>` form so each tool renders the invocation it actually registers (`/openspec-propose` for skills-only delivery, `/opsx-propose`, `/opsx:propose`, or `@opsx-propose` for command surfaces). The handoffs follow the installed workflow set: a custom profile without `propose` or `apply` gets explore's own capture path and the `openspec instructions apply` CLI instead of a command it never installed. Fixes [#869](https://github.com/Fission-AI/OpenSpec/issues/869).
+
+- [#1787](https://github.com/Fission-AI/OpenSpec/pull/1787) [`9827762`](https://github.com/Fission-AI/OpenSpec/commit/9827762d2d18d8076acf90be79d64894255099ea) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - Generated skills and commands no longer adopt a project that never ran `openspec init`. Every workflow now checks `root` from `openspec list --json` before its first write, and `"root": null` means the project is not set up. What happens next depends on how the workflow was reached. A skill the agent picked on its own drops OpenSpec and answers the request normally, without asking about setup. A workflow the user asked for by name, or ran as a slash command, stops and asks whether to initialize the project, target a store, or handle the request without OpenSpec. A project whose `openspec/config.yaml` names a store this machine cannot resolve (not registered, or a malformed `store:` line) is not mistaken for an uninitialized one: the workflow stops and shows the store error. Neither path lets `openspec new change` create `openspec/` in the current directory as a side effect. Skill descriptions now name OpenSpec so hosts stop offering these workflows in unrelated repositories. `openspec new change` also says when it had to create the root itself, so a directory that was never set up no longer picks up an `openspec/` directory in silence (human output only; `--json` is unchanged).
+
+- [#1902](https://github.com/Fission-AI/OpenSpec/pull/1902) [`eb03b9e`](https://github.com/Fission-AI/OpenSpec/commit/eb03b9e93320cf74a0df9043577d8023116cb1aa) Thanks [@clay-good](https://github.com/clay-good)! - Harden the CLI against repositories you have cloned but not yet read ([#1835](https://github.com/Fission-AI/OpenSpec/pull/1835)).
+  
+  - A `config.yaml` value can no longer close the project context block and inject its own directives into the instructions an agent receives.
+  - A crafted delta or skill file no longer stalls `openspec update` or `openspec archive` with catastrophic regex backtracking.
+  - A repository's `.npmrc` can no longer point the update check at a cleartext or attacker-controlled registry; a rejected registry now disables the check instead of falling back.
+  - `openspec update` now notices a generated `SKILL.md` that was edited by hand and restores it, instead of reporting every tool as up to date.
+  - `DO_NOT_TRACK=true` and other common spellings of an opt-out now turn telemetry off, and nothing is sent until the first-run notice has been shown.
+  - Shell-completion installs quote directory paths safely, git probes run with bounded time and output, and dependencies are cleared of known advisories.
+
+- [#1874](https://github.com/Fission-AI/OpenSpec/pull/1874) [`388d344`](https://github.com/Fission-AI/OpenSpec/commit/388d34473a40529320b2b7b9c5bb6723d18322b0) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop legacy cleanup deleting the user's own files. The six pre-skills tools that kept their commands in a `<tool>/commands/openspec/` folder (Claude Code, CodeBuddy, Qoder, Lingma, Crush and Gemini CLI) had that whole folder removed recursively whenever it existed, so a command the user kept there, such as a team review checklist, was deleted along with OpenSpec's files, and the summary named only the folder. Because `openspec init` cleans up automatically when there is no TTY, an agent or CI running plain `openspec init` did this without `--force` and without a prompt, and `openspec update --force` did the same. Cleanup now deletes only the files OpenSpec wrote there: `proposal`, `apply` and `archive` files that still carry the OpenSpec markers every legacy command was generated with, so a same-named file the user wrote is kept. It never follows a symlinked command folder, removes the folder only once nothing else is left in it, and lists each thing it kept. A folder holding nothing OpenSpec wrote is no longer reported as legacy at all. A folder holding only OpenSpec's files, or nothing, is still removed exactly as before, with the same summary line.
+
+- [#1866](https://github.com/Fission-AI/OpenSpec/pull/1866) [`8146be5`](https://github.com/Fission-AI/OpenSpec/commit/8146be5546918cdffce860f1e327d929c5a49bd3) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop one unresolvable file from breaking `openspec list`. To sort changes by recency, `list` stats every file inside each change, and any entry it could not stat failed the whole command: a dangling symlink, such as the `.#tasks.md` lock Emacs keeps beside every file with unsaved edits, or a symlink loop made `list` exit 1 and `list --json` report `"changes": []`, so agents discovering work through it saw no changes at all. An entry that no longer resolves (removed mid-walk, a dangling symlink, or a loop) is now skipped when computing a change's last-modified time. Valid symlinks are dated as before, and any other error, such as a permission failure, still fails the listing.
+
+- [#1849](https://github.com/Fission-AI/OpenSpec/pull/1849) [`09a999b`](https://github.com/Fission-AI/OpenSpec/commit/09a999bbb258c2ad6d7cdc33436c698c15d4eebe) Thanks [@clay-good](https://github.com/clay-good)! - Report a change directory nested in a namespace folder instead of silently listing the folder around it as a change. Specs can be nested by domain (`specs/mobile/tutorial-videos/spec.md`), so it looks reasonable to lay changes out the same way, but a change is only ever a directory directly under `changes/`: `changes/mobile/refresh-token/` left the real change invisible while `mobile` was reported as a task-less change everywhere. `openspec archive mobile` then moved the unfinished change into the archive under the namespace's name and applied none of its deltas. `openspec list` now marks the folder `not a change` and names the nested directories and a flat alternative, `openspec show`, `openspec status --change` and `openspec status --all` say the same instead of reporting a missing proposal or a full artifact plan, `openspec validate` reports it instead of "must have at least one delta", `openspec list --json` carries a `warnings` entry, and `openspec archive` refuses the folder outright. Detection looks up to three directory levels below `changes/`, which covers every namespace layout seen in practice; a change buried deeper than that behaves as it did before. Fixes [#1846](https://github.com/Fission-AI/OpenSpec/issues/1846).
+
+- [#1902](https://github.com/Fission-AI/OpenSpec/pull/1902) [`eb03b9e`](https://github.com/Fission-AI/OpenSpec/commit/eb03b9e93320cf74a0df9043577d8023116cb1aa) Thanks [@clay-good](https://github.com/clay-good)! - Install shell completions with the Nix flake package ([#1785](https://github.com/Fission-AI/OpenSpec/pull/1785)). The package now ships bash, zsh and fish completions in their standard `share/` locations, so Nix users get tab completion without running `openspec completion install` against their home directory.
+
+- [#1775](https://github.com/Fission-AI/OpenSpec/pull/1775) [`626269e`](https://github.com/Fission-AI/OpenSpec/commit/626269ed732250492d8bd220a83df23dd756ee5d) Thanks [@clay-good](https://github.com/clay-good)! - Generated skills and commands no longer point at workflows the active profile does not install. On the default `core` profile, the update workflow told agents to hand off to `/opsx:continue` for missing artifacts and to `/opsx:new` for a change of intent, neither of which `core` generates. Every cross-workflow handoff is now decided at generation time against the installed workflow set, and renders a concrete CLI fallback (`openspec status`, `openspec instructions`, `openspec archive`) when the workflow it would name is absent, rather than relying on a runtime availability check the agent had to perform. The onboarding tutorial's command tables are likewise built from the workflows you actually have.
+  
+  Also folds in [#1735](https://github.com/Fission-AI/OpenSpec/issues/1735), which fixed the same issue ([#1734](https://github.com/Fission-AI/OpenSpec/issues/1734)) by removing the optional handoffs outright. The CLI's own runtime instructions no longer name the `openspec-continue-change` skill either, since those strings are chosen at run time and cannot be resolved against a profile; and the blocked-state fallback now carries the full CLI recovery (select the next `ready` artifact from `openspec status`, read its rules with `openspec instructions`, keep the selected `--store`) rather than a one-line pointer.
+
+- [#1870](https://github.com/Fission-AI/OpenSpec/pull/1870) [`e01ed07`](https://github.com/Fission-AI/OpenSpec/commit/e01ed070f18e15529f82563d4c5af35d8124bad3) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archiving a change whose delta was written somewhere `archive` never reads. `validate` and `archive` read a change's deltas only from `specs/<capability-path>/spec.md`, but the spec-driven artifact graph counts any markdown file under `specs/` as the specs being written, so a delta at `specs/user-auth.md`, or in a second file beside a capability's `spec.md`, was reported done by `status` and ready by `instructions apply` with no warning, rejected by `validate` only as "no deltas found", and then archived with exit 0 and nothing merged into `openspec/specs/`. A markdown file that carries delta sections but is not a capability's `spec.md` is now a validation error naming the file and the `spec.md` its requirements belong in; `archive` runs that validation and refuses the change instead of archiving it unmerged, and `instructions apply` lists each such file in its `warnings`. `--no-validate` still archives as before, a change with no spec files still archives, and notes without delta sections under `specs/` are not affected.
+
+- [#1806](https://github.com/Fission-AI/OpenSpec/pull/1806) [`6e62b1d`](https://github.com/Fission-AI/OpenSpec/commit/6e62b1d522cfadb4b9836b63d5afa127bc950743) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Refuse a `## RENAMED Requirements` section whose `FROM:` and `TO:` lines do not pair up, instead of guessing. The reader kept one pending pair and dropped whatever did not fit: a `TO:` before its `FROM:`, a `FROM:` displaced by a second `FROM:`, or a trailing `FROM:` vanished with no diagnostic. Listing the old names and then the new ones paired the second `FROM:` with the first `TO:`, so `openspec archive` renamed a requirement the delta never named, under a name written for a different one, and exited 0. `openspec validate` now reports each unpaired line as an ERROR with its line number, and archive refuses the change until the pairing is fixed. Well-formed renames, including several consecutive pairs, are unchanged. A change that used to archive with a malformed RENAMED section is now rejected. Fixes [#1805](https://github.com/Fission-AI/OpenSpec/issues/1805).
+
+- [#1860](https://github.com/Fission-AI/OpenSpec/pull/1860) [`4b5c07a`](https://github.com/Fission-AI/OpenSpec/commit/4b5c07a0c2e5a4a1dcb3ed9f3a040f826eb7d457) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Read a requirement heading written with a CommonMark closing sequence, such as `### Requirement: Late Fees ###`, as the requirement it renders as. The trailing `#` run stayed in the name, so a REMOVED written that way looked for "Late Fees ###", missed the requirement, and archive exited 0 with a false "treating it as already removed" warning while the requirement stayed in the spec; a closed MODIFIED or RENAMED heading failed as "not found", and a closed and an open heading of one requirement were not reported as duplicates. Requirement names now drop the closing run wherever they are read, exactly as scenario names already did: only a run preceded by a space or tab counts, so a name such as `C#` keeps its `#`. Headings without a closing run are unaffected.
+
+- [#1868](https://github.com/Fission-AI/OpenSpec/pull/1868) [`7090e16`](https://github.com/Fission-AI/OpenSpec/commit/7090e16d74dfe588dad72bc4fda9bf124e71b0af) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Reject a schema whose `apply.requires` names an artifact that does not exist. `parseSchema` checked every artifact's `requires` but never `apply.requires`, so `openspec schema validate` passed a one-character typo there, and apply then skipped the unknown id: `apply.requires: [desgin]` turned the apply gate off and told the agent "Proceed with implementation" with only a proposal written. That is now a schema error, raised wherever the schema is loaded, exactly like an unknown artifact `requires`, and it names the bad id and the artifacts the schema declares. `openspec schema validate` also warns, without failing, when `apply.tracks` isn't exactly equal to some artifact's `generates` value, because OpenSpec finds the tracked artifact by comparing those two strings and can otherwise not tell which artifact's progress the file belongs to. That covers a typo such as `task.md` and also `tracks: tasks/main.md` against `generates: tasks/*.md`, where the glob does produce the file but the strings still differ. Apply reads that path as written either way, so schemas that track a hand-written file keep loading and working. Every built-in schema parses as before.
+
+- [#1856](https://github.com/Fission-AI/OpenSpec/pull/1856) [`46ff91f`](https://github.com/Fission-AI/OpenSpec/commit/46ff91f2d626ef2c3f9f55ff345aa23cd44a6e95) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Make `openspec show --json --deltas-only` report the deltas archive applies. `ChangeParser`, which backs `show --json`, the `change list` delta counts and archive's proposal warnings, read delta specs with its own section lookup instead of `parseDeltaSpec`, the reader archive uses, and the two disagreed. A REMOVED written in the bullet form (`` - `### Requirement: X` ``) was invisible to it, so it fell back to the proposal's "What Changes" prose and reported an invented MODIFIED while archive deleted the requirement; a repeated section header was read only once; and a RENAMED line written with `*` or `+` was dropped. The inspection command OpenSpec's own error text recommends therefore misreported a deletion. `ChangeParser` now derives every operation from `parseDeltaSpec`, and a change whose delta spec files carry a delta section is described by them alone, so proposal prose is never reported in place of what archive applies. Requirement text and scenarios are read exactly as before, header-form deltas produce the same output, and a change with no delta spec files, or a legacy change whose spec files carry no delta section, still falls back to the "What Changes" bullets.
+
+- [#1786](https://github.com/Fission-AI/OpenSpec/pull/1786) [`8b99c07`](https://github.com/Fission-AI/OpenSpec/commit/8b99c07bd0d455f72e746d3950f03e52a025d655) Thanks [@clay-good](https://github.com/clay-good)! - `openspec status` now names the command that moves the change forward.
+  
+  The text output reported state and stopped there, so picking a change back up (after a lost session, or on a change you did not start) meant already knowing which command came next. The JSON surface had carried that command all along in `nextSteps`; the text surface never printed it.
+  
+  Status now ends with a `Next:` line: the next ready artifact's `openspec instructions` command while planning is unfinished, and `openspec instructions apply` once every planning artifact exists. It carries `--store <id>` when the resolved root is a store, and it is built from the same source as the JSON `nextSteps` sentence, so the two surfaces cannot name different commands.
+
+- [#1882](https://github.com/Fission-AI/OpenSpec/pull/1882) [`208b5b5`](https://github.com/Fission-AI/OpenSpec/commit/208b5b55106fbeda2ed9f099671b8ce85a01cbaa) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop a store named `specs` or `changes` from taking over root selection. Stores are placed at `~/openspec/<id>`, so a store with one of those ids is itself `~/openspec/specs` or `~/openspec/changes`, and that made `$HOME` look like a planning root. Every command run anywhere under the home directory then resolved `$HOME` as the nearest root: the global `defaultStore` was never consulted, and `new change` wrote into `~/openspec/changes`, outside any store. A `specs/` or `changes/` directory that carries store metadata no longer counts as planning content of the directory above it, so these stores resolve like any other. A real project's `openspec/specs/` and `openspec/changes/` are unaffected.
+
+- [#1880](https://github.com/Fission-AI/OpenSpec/pull/1880) [`9f8dec5`](https://github.com/Fission-AI/OpenSpec/commit/9f8dec5dd937da78bbdaeff5e5dfd041bb43cf5c) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `openspec store remove` deleting a store the user did not name. Remove deletes the target's folder recursively, but it checked only the target's own metadata, so any other registered store living inside that folder was deleted with it, uncommitted planning work included, while its registry entry was left pointing at a path that no longer existed. The natural way to get there is a shared store vendored into another as a git submodule, a layout `store register` accepts. Remove now refuses when another registration points inside the folder, checked under the same registry lock that commits the removal, and the error names each nested store with the `openspec store unregister` command to run first. Removing a store whose other registrations are siblings is unchanged, and `store register` still accepts nested checkouts.
+
+- [#1884](https://github.com/Fission-AI/OpenSpec/pull/1884) [`5d22145`](https://github.com/Fission-AI/OpenSpec/commit/5d221456e57feb9277de40482fade427201b9bdb) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Let `openspec store setup --no-init-git` create a store inside an existing Git repository. Setup refuses a path inside another repository because initializing the store there would nest one repository in another, but it ran that check even with `--no-init-git`, which creates no repository at all. Users who keep their home directory as a dotfiles repository therefore could not set up a store at the recommended `~/openspec/<id>` path with any flag. With `--no-init-git` the check is now skipped, and the store never records the enclosing repository's remote. The default setup and an explicit `--init-git` still refuse a path inside another repository.
+
+- [#1862](https://github.com/Fission-AI/OpenSpec/pull/1862) [`8fc65b7`](https://github.com/Fission-AI/OpenSpec/commit/8fc65b7f70c4bd730a1dbe500cbe165d156f3c58) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Count task checkboxes under every CommonMark list marker. The task counter shared by `list`, `status`, `view`, `instructions apply`, `validate --archived` and archive's incomplete-task check recognized only `-` and `*` bullets, so a task written as an ordered item (`1. [ ]`, `1) [ ]`) or under a `+` bullet was invisible to all of them: a change with unfinished ordered tasks reported "✓ Complete", and `openspec archive` archived it without its incomplete-task warning. Task lines under `+` and ordered markers (`.` or `)`, up to nine digits, as CommonMark allows) now count exactly like `-` and `*` ones, including nested sub-tasks, CRLF files and the existing tolerance of a missing space after the marker, and task-numbering checks now see them too. Ordered and `+` items without a checkbox are still ignored, and `-` and `*` tasks count as before.
+
+- [#1777](https://github.com/Fission-AI/OpenSpec/pull/1777) [`3312af4`](https://github.com/Fission-AI/OpenSpec/commit/3312af4799eb162d3ddb7804d643ace5282c22cb) Thanks [@clay-good](https://github.com/clay-good)! - Start generated proposal, spec, design, and tasks files with a top-level heading, so artifacts are complete markdown documents instead of files whose first line is a section header. Editors that run markdownlint no longer flag every OpenSpec artifact with MD041. `openspec schema init` scaffolds custom templates the same way.
+  
+  `openspec show --json` and `openspec change list --json` keep naming a change by its id when its proposal opens with the template's bare `# Proposal` title.
+
+- [#1778](https://github.com/Fission-AI/OpenSpec/pull/1778) [`7de2404`](https://github.com/Fission-AI/OpenSpec/commit/7de24044ef4c635f634b78fa6bc4b5905967bfd8) Thanks [@clay-good](https://github.com/clay-good)! - Make the vendor-neutral tool target findable when your assistant is not on the list. `openspec init` now shows it as "Other / Universal (shared .agents skills)"; the picker's search box matches it on `universal`, `other`, `generic`, `custom`, `proprietary`, `unlisted`, `unsupported`, `vendor-neutral` and `agents.md`; a search that matches nothing points at it instead of ending at "No matches"; and `--tools <unknown>` names it in the error. The search box also accepts punctuation, so `.agents` and `amazon-q` filter instead of silently dropping their `.` and `-`.
+
+- [#1876](https://github.com/Fission-AI/OpenSpec/pull/1876) [`605d9e7`](https://github.com/Fission-AI/OpenSpec/commit/605d9e7a2bb5c1bab90268933f9b84ff1eb8807c) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop OpenSpec rewriting a global config file it cannot parse. After a hand edit left a typo such as a trailing comma in `config.json`, the next command of any kind, including read-only ones like `openspec list`, read the fallback defaults as telemetry consent, minted a new anonymous ID and wrote it back, replacing the whole file: a `telemetry.enabled false` opt-out, the chosen profile and the workflow list were all lost, and usage events were sent. A config file that exists but does not hold a JSON object, whether it failed to parse or its root is something else such as `null`, an array or a string, is now never written implicitly, and telemetry and the update check treat it as opted out. `config set`, `config unset` and `config profile` refuse with an error that names the file and points to `openspec config edit`, and `openspec config reset --all` still replaces it. The existing "Invalid JSON" warning is unchanged, and valid or missing config files behave exactly as before.
+
+- [#1840](https://github.com/Fission-AI/OpenSpec/pull/1840) [`fede536`](https://github.com/Fission-AI/OpenSpec/commit/fede536c27e03c1aaa3c17caffa837f483d9e9b9) Thanks [@clay-good](https://github.com/clay-good)! - Resolve the contradiction that left `/opsx:update`'s only write path without a governing rule. Step 4 told the agent to "Apply the requested edit", while step 5 and the guardrails told it to write only after the user confirms each revision, so the same `/opsx:update "the design now uses X"` either wrote immediately or stopped and showed the proposed revision first, depending on which passage the agent weighed. Step 4 now drafts the edit in the conversation and step 5 owns every artifact write, matching the workflow's own specified behavior: propose each revision and apply it only after user confirmation. Fixes [#1836](https://github.com/Fission-AI/OpenSpec/issues/1836).
+
+- [#1858](https://github.com/Fission-AI/OpenSpec/pull/1858) [`db560ae`](https://github.com/Fission-AI/OpenSpec/commit/db560ae33f565b76ebbc040782ec7007295e8133) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `validate` accepting a requirement whose only scenario is a bare header. The delta scenario counter counted every `####` header, while the spec path that archive uses to validate the rebuilt spec keeps a scenario only when its body has content, so `validate` called such a change valid and `archive` then refused it with a generic "Requirement must have at least one scenario" that did not name the requirement. Both paths now share one rule, `hasScenarioBody`, and read a scenario's body up to the same boundary, so `validate` rejects exactly what archive rejects, naming the requirement and saying that a header with no body under it does not count. A scenario whose body is only a fenced block or a deeper header still counts, a requirement with one real scenario is still accepted even when another is empty, and main-spec validation is unchanged.
+
+- [#1774](https://github.com/Fission-AI/OpenSpec/pull/1774) [`09984b8`](https://github.com/Fission-AI/OpenSpec/commit/09984b824254f9e35bcdf628fdb052a689a57f37) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+  
+  - **Task lists without checkboxes are now caught**: a `tasks.md` written as plain bullets or a numbered list counts as zero tasks, so `openspec list` and `openspec status` reported "No tasks" and `openspec archive` had no unfinished work to warn about. `openspec validate` now warns when a change's tracked task files contain list items but no checkbox at all, and points at the first offending line.
+
+- [#1852](https://github.com/Fission-AI/OpenSpec/pull/1852) [`5f5914e`](https://github.com/Fission-AI/OpenSpec/commit/5f5914e7f7a817262c7564ac92694db833564978) Thanks [@clay-good](https://github.com/clay-good)! - Match the natural "openspec <verb>" phrasing to the workflow it names. Users and agents say "openspec propose" or "do an openspec apply", but no workflow skill's description contained that phrasing (and a skill's description is what an agent matches on), so the phrase read as an invitation to hand-build the artifacts with the CLI instead of running the workflow. Every workflow skill's description now names the phrasings a user actually types ("openspec propose", "opsx apply", and so on). Run `openspec update` to pick it up. `openspec update` itself is deliberately left unclaimed: it is a real CLI command that refreshes generated files, unrelated to the update-change workflow, which claims "openspec update change" instead. Commands-only installs write no skills and are unchanged. Fixes [#1221](https://github.com/Fission-AI/OpenSpec/issues/1221).
+
+## 1.13.0
+
+### Minor Changes
+
+- [#1783](https://github.com/Fission-AI/OpenSpec/pull/1783) [`8ba4ac1`](https://github.com/Fission-AI/OpenSpec/commit/8ba4ac1b16a33830a766f0c03d224d516b6a90ce) Thanks [@clay-good](https://github.com/clay-good)! - Apply now says when a change has no delta specs. Apply gates on the schema's `apply.requires` alone, so a change whose `tasks.md` was written ahead of its specs read as ready to implement even though it had no spec deltas at all — the state `openspec validate` rejects. `openspec instructions apply` now reports that gap as a warning (text and `--json`), naming both ways out: write the specs, or declare `skip_specs: true`. Changes that have specs, declare `skip_specs`, or are still blocked on their own required artifacts are unaffected.
+  
+  A blocked apply also names the whole chain now, not just the first hop: a change holding only a proposal reported `Missing artifacts: tasks` while the specs that `tasks` depends on were missing too, which reads as an instruction to write the tracking file straight from the proposal. The full build order is reported as `missingPrerequisites` in `--json`. The remedies these messages give are CLI commands (`openspec instructions <artifact> --change <name>`) rather than the `openspec-continue-change` skill, which the `core` profile never installs.
+
+### Patch Changes
+
+- [#1798](https://github.com/Fission-AI/OpenSpec/pull/1798) [`aedf4d0`](https://github.com/Fission-AI/OpenSpec/commit/aedf4d0c64c4bdde2e21f199aee93fa0d598c33e) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop archive rewriting the inside of fenced code blocks. The final assembly in `buildUpdatedSpec` collapsed runs of blank lines across the whole rebuilt document to tidy the seams between the slices it rejoins, but the pass was not fence-aware, so a requirement documenting a sample with two or more consecutive blank lines had that sample silently edited on archive, and edited again on every later archive. That matters wherever whitespace carries meaning: YAML block scalars, Python, expected-output fixtures, Markdown inside Markdown. Blank runs are now collapsed only outside fenced blocks, using the same `buildCodeFenceMask` every other structural pass in the module already used. Behavior outside fences is unchanged, including that only a truly empty line counts as blank, so a line of spaces is still never a collapse boundary. Fixes [#1797](https://github.com/Fission-AI/OpenSpec/issues/1797).
+
+- [#1800](https://github.com/Fission-AI/OpenSpec/pull/1800) [`fadac3e`](https://github.com/Fission-AI/OpenSpec/commit/fadac3e1c927bf5180ce82c806435c61db5d5adb) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Read a removal or rename written with `*` or `+` as the operation it is. CommonMark opens a bullet list with `-`, `*` or `+`, but the bullet form of `## REMOVED Requirements` and the `FROM:`/`TO:` lines of `## RENAMED Requirements` both hardcoded `-`, so either other marker matched nothing at all. The operation then silently never happened: `openspec validate` reported the change valid, `openspec archive` exited 0 with "Specs updated successfully", and the requirement that was supposed to be deleted or renamed stayed exactly as it was. The change archived as complete, leaving the spec quietly disagreeing with the delta that was meant to update it. Both forms now accept `[-*+]`, the `FROM:`/`TO:` bullet stays optional, and the plain `### Requirement:` header form is unchanged. Fixes [#1799](https://github.com/Fission-AI/OpenSpec/issues/1799).
+
+- [#1802](https://github.com/Fission-AI/OpenSpec/pull/1802) [`8251763`](https://github.com/Fission-AI/OpenSpec/commit/8251763ecdc349a0a1484f09da85f7e5c33f4836) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Apply every delta section, not just one copy of each. A delta file that wrote the same header twice, two `## ADDED Requirements` sections say, silently kept one of them: sections were collected into a record keyed by title, so a repeated title overwrote the earlier body, and the case-insensitive lookup returned only the first entry that folded to the target, so `## ADDED Requirements` beside `## Added Requirements` left the second unread. Every requirement under the discarded copy was gone before validation or the merge could see it, so `openspec validate` reported zero issues and `openspec archive` exited 0 having applied less than the author wrote, then moved the change to the archive with the live spec quietly diverging from what was reviewed. Sections are now kept as a list and every body whose title matches is read, each keeping its own line numbers so diagnostics still point at the right copy. Rename pairs are read per section, so a `FROM:` in one copy of the header can never pair with a `TO:` in another. An author does not have to repeat a header on purpose to hit this: a delta documenting OpenSpec's own syntax inside a fenced example produces the duplicate on its own. Fixes [#1801](https://github.com/Fission-AI/OpenSpec/issues/1801).
+
+- [#1657](https://github.com/Fission-AI/OpenSpec/pull/1657) [`6d2dbe6`](https://github.com/Fission-AI/OpenSpec/commit/6d2dbe62d3386ac0df576136759775678102acf2) Thanks [@clay-good](https://github.com/clay-good)! - Load project context before proposal planning, using the selected project or store root and honoring config precedence and validation limits. When no root exists, stop without writing files and offer initialization instead of creating an implicit root.
+
+- [#1700](https://github.com/Fission-AI/OpenSpec/pull/1700) [`3915db7`](https://github.com/Fission-AI/OpenSpec/commit/3915db763ad5394b29cdd895c87a91c837313ae8) Thanks [@clay-good](https://github.com/clay-good)! - Teach the generated guidance how to find and read a project's specs. `openspec list --specs` appeared in no generated skill, command, or artifact instruction, while `openspec list --json` (the in-flight *change* list) appeared throughout, so an agent asked to read the existing specs first enumerated changes instead and reported the step complete against the wrong object. The explore skill and command now list the spec inventory alongside the change list and say which is which, and the spec-driven `proposal` and `specs` instructions name the command where they ask for existing capabilities to be researched and for a delta's path to match an existing one. Both steps carry `--store "<id>"`, and capabilities are read with `openspec show "<spec-id>" --type spec --json --no-scenarios` so the read resolves against the same root the listing came from. Fixes [#1689](https://github.com/Fission-AI/OpenSpec/issues/1689).
+  
+  The filtered read is only an overview. Agents read relevant specs in full, including scenarios, before deciding what is already covered or what should change.
+
+- [#1779](https://github.com/Fission-AI/OpenSpec/pull/1779) [`3c6d318`](https://github.com/Fission-AI/OpenSpec/commit/3c6d318b837f443d1aabf969ce368e78ae12e891) Thanks [@clay-good](https://github.com/clay-good)! - `openspec init` and `openspec update` now name the workflows your profile left out and how to add them, so a command that was never installed no longer reads as a broken setup.
+
+- [#1808](https://github.com/Fission-AI/OpenSpec/pull/1808) [`d9e1a28`](https://github.com/Fission-AI/OpenSpec/commit/d9e1a28c38927e6d649781976cd1a753e28973af) Thanks [@dwin-gharibi](https://github.com/dwin-gharibi)! - Stop `openspec update` reporting a tool up to date while a damaged command file sits on disk. The check read the `generatedBy` version marker in a tool's skill files alone, which proves only that the skill files came from this CLI and says nothing about the command files written beside them, so a hand-edited or truncated command file left update printing "All 1 tool(s) up to date" and repairing nothing; the file could be restored only by knowing to pass `--force`. A deleted command file was already detected, so the claim was false only for a damaged one. Update now also compares command-file content, using the comparison that already existed and was simply never consulted once a skill file supplied a version. Scoped to tools configured for both skills and commands, so the commands-only path is unchanged, and skipped when the delivery mode generates no commands for the tool. Fixes [#1807](https://github.com/Fission-AI/OpenSpec/issues/1807).
+
+- [#1782](https://github.com/Fission-AI/OpenSpec/pull/1782) [`c170dc7`](https://github.com/Fission-AI/OpenSpec/commit/c170dc77adbe868ce731e07df2806a7ca8fcb4ec) Thanks [@clay-good](https://github.com/clay-good)! - Fix `retire_capabilities` refusing any spec whose scenario bullets wrap onto a second line. The continuation line was counted as content the merge could not account for, which blocked the retirement and suppressed the hint that names the marker ([#1780](https://github.com/Fission-AI/OpenSpec/issues/1780)). A spec bulleted with `+` is covered too: naming only `-` and `*` as list markers reported every one of its scenario bullets as unaccounted content, so that capability could not be retired at all either.
+
 ## 1.12.0
 
 ### Minor Changes

CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Thanks for helping improve OpenSpec.
+
+## 1. Open a discussion or an issue first
+
+Every change starts here, including small ones.
+
+- [Start a discussion](https://github.com/Fission-AI/OpenSpec/discussions) if it affects OpenSpec's core design.
+- [Open an issue](https://github.com/Fission-AI/OpenSpec/issues) for bugs and everything else.
+
+This is so we can agree on the approach before you spend time building. PRs without a linked issue or a prior discussion may be closed.
+
+## 2. Decide whether it needs a change proposal
+
+A bug fix, a typo, or a small improvement goes straight to a PR.
+
+A new feature, a significant refactor, or anything that changes OpenSpec's architecture needs an OpenSpec change proposal first, so we can align on intent and goals before implementation begins. Open it as a PR containing only `openspec/changes/<name>/` and wait for it to be approved before you write the code.
+
+When writing a proposal, 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.
+
+If you are not sure which side of the line your change falls on, ask in the discussion or issue from step 1.
+
+## 3. Make your change
+
+You need Node 20.19+ and pnpm.
+
+```bash
+pnpm install
+pnpm build              # tests run against the build output
+pnpm test
+pnpm exec tsc --noEmit
+pnpm lint
+```
+
+Those four commands are what CI runs, so a green local run means a green CI run.
+
+Run `pnpm changeset` if your change affects users, and commit the file it generates.
+
+### Keep the CLI's startup fast
+
+Editors, agents and OpenSpec Desktop run the CLI many times, and each call pays for every module it loads before the command runs. Before this rule, `openspec --version` loaded 485 modules: about 0.5 s per call on a Windows machine. So a command loads only the command definitions and its own code:
+
+- **Definitions** (name, options, help text) go in `src/cli/index.ts` or `src/cli/commands/<name>.ts`. Import nothing heavy there: no zod, yaml, fast-glob, ora, and no other command's code.
+- **The command's code** goes in `src/commands/<name>.ts` or `src/core/`, loaded inside the action with `await import()`.
+
+`test/cli-e2e/startup-modules.test.ts` checks which modules each command loads, and fails if a definition starts pulling in an implementation. When you add a command, add it to that test's list.
+
+## 4. Open the PR
+
+- Branch off `main` in your fork.
+- Title it as a conventional commit: `type(scope): subject`, for example `fix(archive): keep authored Purpose`.
+- Link what you opened in step 1: `Closes #123` for an issue, or a link to the discussion when there is no issue.
+- If a coding agent wrote the code, say which agent and model, and confirm you tested it. AI-generated code is welcome when it has been verified.
+
+Maintainers are listed in [MAINTAINERS.md](MAINTAINERS.md).

README.md

@@ -122,7 +122,7 @@ Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the har
 
 ## Quick Start
 
-**Requires Node.js 20.19.0 or higher.**
+**Requires Node.js 20.19.0 or higher.** Homebrew installs it as a dependency.
 
 Install OpenSpec globally:
 
@@ -130,6 +130,12 @@ Install OpenSpec globally:
 npm install -g @fission-ai/openspec@latest
 ```
 
+Or install the official [Homebrew formula](https://formulae.brew.sh/formula/openspec) on macOS or Linux:
+
+```bash
+brew install openspec
+```
+
 Then navigate to your project directory and initialize:
 
 ```bash
@@ -137,11 +143,11 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 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))
+- **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 any code gets 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`.
@@ -151,7 +157,7 @@ Both are in the default profile. If you want the expanded workflow (`/opsx:new`,
 > [!NOTE]
 > Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
 >
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
 
 ## Docs
 
@@ -208,6 +214,12 @@ AI coding assistants are powerful but unpredictable when requirements live only
 npm install -g @fission-ai/openspec@latest
 ```
 
+If you installed OpenSpec with Homebrew:
+
+```bash
+brew upgrade openspec
+```
+
 **Refresh agent instructions**
 
 Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
@@ -224,21 +236,9 @@ openspec update
 
 ## Contributing
 
-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+Open a discussion (for core design changes) or an issue before you open a PR, and link the issue or discussion from the PR. New features, significant refactors, and architectural changes need an OpenSpec change proposal first.
 
-**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.
-
-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.
-
-**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").
-
-### Development
-
-- 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`
+→ **[CONTRIBUTING.md](CONTRIBUTING.md)**: the full process, from first issue to merged PR
 
 ## Other
 

docs-lab/README.md

@@ -96,7 +96,7 @@ the page or rewriting the goal in both places, never letting them drift.
 | [Overview](start/overview.md) | _TODO: emptied 2026-08-21 for a from-scratch rewrite and pulled from the site (`/docs` redirects to Installation meanwhile); the old goal line was dropped as too weak a pitch. Brief in Notes.md._ |
 | [Installation](start/installation.md) | Install the `openspec` CLI on your machine, update it, and uninstall it. |
 | [Set up your project](start/setup.md) | Add OpenSpec to a project: run init, see what it wrote, and adjust it. |
-| [Quickstart](start/quickstart.md) | Your first change on your existing repo, from idea to archived. |
+| [Quickstart](start/quickstart.md) | Your first change in a new or existing project, from idea to archived. |
 
 ### Guides: understand the system, use it well, bring it to your codebase and team
 

docs-lab/customize/project-config.md

@@ -35,8 +35,8 @@ For example, with a `context` field and the rule from the top of this page, here
 
   <!-- From your config.yaml: context -->
   <project_context>
-    Tech stack: TypeScript, Node.js
-    Domain: e-commerce platform
+    Designs and tasks must cover Windows, macOS, and Linux
+    Write all artifacts in Spanish
   </project_context>
 
   <!-- From your config.yaml: rules for tasks -->
@@ -58,8 +58,6 @@ For example, with a `context` field and the rule from the top of this page, here
 
 Your config arrives first, then OpenSpec's built-in instruction and template. Rules add to the built-ins and never replace them. Edits to config.yaml reach the agent on the next run.
 
-[Workflow runs](../reference/architecture/workflow-runs.md) covers the full run, from invocation to written artifacts.
-
 ## The fields
 
 Three fields shape what the agent receives. Each field's exact contract (types, limits, validation) is in [Project configuration (config.yaml)](../reference/configuration/config-yaml.md).
@@ -76,18 +74,17 @@ The last column is exact, so a field reaches only the steps listed there. In par
 
 ### context
 
-`context` is what the agent should know up front when planning a change, whether it's creating an artifact, applying tasks, or archiving:
+`context` is background the agent receives when it creates an artifact, applies tasks, or archives a change.
 
 ```yaml
 context: |
-  We ship cross-platform; designs and tasks must cover Windows, macOS, and Linux
-  Tech stack: TypeScript, Node.js, Commander.js
-  We use conventional commits
+  We ship cross-platform. Designs and tasks must cover Windows, macOS, and Linux
+  Write all artifacts in Spanish
 ```
 
-This is planning context, not project documentation. Add a fact when it should shape every plan, like the cross-platform line above. Leave out anything the agent can learn by reading the code.
+Use `context` for facts and constraints that should shape workflow output. Keep durable project documentation in the project's documentation files, and leave out anything the agent can learn by reading the code.
 
-**Another language**: because context reaches every artifact, it's also how you change the output language. One line, like `Write all artifacts in Spanish.`, switches every proposal, spec, and tasks file the workflows write.
+**Another language**: because context reaches every artifact, you can add `Write all artifacts in Spanish.` to instruct the agent to write proposal, spec, design, and tasks artifacts in Spanish.
 
 ### rules
 

docs-lab/customize/schemas.md

@@ -125,7 +125,7 @@ The scaffold is bare. Artifacts come from the built-in four ids only, and the ge
 
 A fork has two kinds of files to edit:
 
-- **templates/** change the skeleton of each document. Add a section to the tasks template and every new tasks.md starts with it.
+- **templates/** change the skeleton of each document. Add a section to the tasks template and every new tasks.md starts with it. Keep the `#` title on the first line: the artifact inherits it, so every generated file opens as a titled document.
 - **schema.yaml** changes the workflow itself: which artifacts exist, what each one requires first, and the instruction the agent gets when creating it.
 
 For example, to drop the design document for a leaner flow:
@@ -162,3 +162,9 @@ Sharing a schema means copying its folder.
 - **From the community**: the [community catalog](https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md#community-schemas) lists shared schemas. Copy one into `openspec/schemas/<name>` and it works like your own.
 
 We're working on a schema registry, public and private, so schemas can be installed by name instead of copied by hand.
+
+### Use OpenSpec with Superpowers
+
+The community-maintained [`superpowers-bridge`](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) schema connects OpenSpec artifacts to [Superpowers](https://github.com/obra/superpowers) execution skills. Follow the bridge's installation and compatibility notes before copying it into your project.
+
+The bridge is released outside OpenSpec. OpenSpec does not test or version its Superpowers integration.

docs-lab/guides/review-the-plan.md

@@ -2,7 +2,7 @@
 
 > The two-minute pass that catches wrong turns before they're code.
 
-<!-- Skeleton: headings only. -->
+<!-- Partial draft: the plan-review sections are still headings only. -->
 
 ## The two-minute pass
 
@@ -13,3 +13,24 @@
 ## Pushing back
 
 ## Advanced: verify after apply
+
+Before archiving, check that the code does what the scenarios describe. The optional
+[verify skill](../reference/skills.md#openspec-verify-change) can help find gaps.
+
+### Keep a record when checks are hard to track
+
+Use the change's `tasks.md` or an existing test report. For each check, record:
+
+- **Scenario**: the requirement and scenario it checks, with a link to that version of the spec.
+- **Check**: the test or manual check and what should happen.
+- **Result**: pass, fail, not run, or unknown. Link to the original run or dated observation.
+- **Tested version**: the code revision or build tested, and where it ran.
+
+### Review the results
+
+- **Open the source.** Confirm the result in the linked run or report. A checked task or an agent's summary alone does not prove the test passed.
+- **Look for gaps.** Check that every scenario has a result. A passing test on one device or environment does not cover another. Keep missing and failed checks visible.
+- **Check for changes.** Rerun checks affected by changes to the requirements, code, or environment. Unrelated documentation edits may leave earlier results valid.
+
+**Archiving does not enforce these checks.** If passing results are required for
+release, enforce that in your CI or release process.

docs-lab/help/faq.md

@@ -17,7 +17,8 @@ once the prose lands. -->
 
 If it has a row in the [support matrix](../reference/supported-tools.md), yes.
 Pick its id at init. If it isn't listed but reads the shared `.agents/skills/`
-folder, pick **Shared `.agents` skills** (`--tools agents`). If neither, request
-it in the [OpenSpec repo](https://github.com/Fission-AI/OpenSpec/issues).
+folder, pick **Other / Universal** (`--tools agents`), covered by the support
+matrix's Other / Universal section. If neither, request it in the
+[OpenSpec repo](https://github.com/Fission-AI/OpenSpec/issues).
 
 ## Where did the old /openspec:* commands go?

docs-lab/help/legacy/migration.md

@@ -15,4 +15,12 @@ once the prose lands. -->
 
 ## Migrating a project
 
+### Back up custom content before cleanup
+
+Files listed under **Files to remove** are deleted entirely. Back up any custom content before accepting cleanup.
+
+- **`openspec/AGENTS.md`**: detected by existence alone; cleanup does not inspect its contents.
+- **Root-level `AGENTS.md`, `CLAUDE.md`, and other config files**: cleanup removes OpenSpec marker blocks and preserves content outside those blocks.
+- **Legacy command directories**: cleanup preserves files it does not recognize as generated commands.
+
 ## Behavior differences

docs-lab/multi-repo/stores.md

@@ -223,6 +223,23 @@ No active changes. Create one with: openspec new change <name> --store team-plan
 - **Commit it**: teammates who clone your project get the line too. They still need the store registered on their machine ([step 3 of Set up a store](#set-up-a-store)), or OpenSpec errors and tells them to register it.
 - **Next to real folders**: if your project also has `specs/` or `changes/` folders, OpenSpec uses those and ignores the line, with a warning.
 
+### Install integrations in a store-only repo
+
+Run init from the code repo's root to install AI tool integration files without moving planning back into that repo:
+
+```bash
+# inside web-app, at the repository root
+openspec init --tools claude
+```
+
+- **Integration files**: written in the code repo.
+- **`openspec/config.yaml`**: preserved byte-for-byte, including the `store:` line.
+- **`openspec/specs/` and `openspec/changes/`**: not created in the code repo.
+
+OpenSpec refuses this command from a subdirectory of the code repo. Run it from the repository root.
+
+OpenSpec also refuses `--language` here because the language belongs in the external store's config. Run init in the store root or edit that config directly.
+
 ### `defaultStore` on your machine
 
 Set it once if every project you work in uses the same store. OpenSpec falls back to it when it finds no flag, no local `openspec/` folder, and no `store:` line:

docs-lab/reference/cli.md

@@ -22,7 +22,6 @@
 | [`openspec show`](#openspec-show) | Print a change or spec, as markdown or JSON. |
 | [`openspec view`](#openspec-view) | One-screen dashboard of specs and changes. |
 | [`openspec validate`](#openspec-validate) | Check changes and specs for structural issues. |
-| [`openspec sync`](#openspec-sync) | Fold a change's delta specs into the main specs, without archiving it. |
 | [`openspec archive`](#openspec-archive) | Move a completed change to the archive and update the main specs. |
 
 **Workflows and schemas**
@@ -51,6 +50,7 @@ Your agent runs most of these during the workflow.
 
 | Command | What it does |
 |---|---|
+| [`openspec version`](#openspec-version) | Report the installed version and optionally check for an update. |
 | [`openspec feedback`](#openspec-feedback) | Submit feedback about OpenSpec. |
 | [`openspec completion`](#openspec-completion) | Install or generate shell completions. |
 
@@ -78,6 +78,21 @@ openspec init --tools none           # openspec/ structure only, no tool files
 
 With no `--tools`, init prompts you to pick tools in an interactive terminal. Outside one, it sets up the tools it detects in the project. With none detected it exits 1 and lists the valid ids.
 
+**Store-only repositories**
+
+When `openspec/config.yaml` contains a `store:` line and the repo has no local specs or changes, run init from the repository root:
+
+```bash
+# install Claude Code integration files in the code repo
+openspec init --tools claude
+```
+
+- **Integration files**: written in the code repo.
+- **`openspec/config.yaml`**: preserved byte-for-byte.
+- **`openspec/specs/` and `openspec/changes/`**: not created in the code repo.
+
+Running init from a subdirectory exits 1 and tells you to run it from the repository root. `--language` also exits 1 because the language belongs in the external store's config. Run init in the store root or edit that config directly.
+
 **Arguments**
 
 | Argument | What it is |
@@ -89,6 +104,7 @@ With no `--tools`, init prompts you to pick tools in an interactive terminal. Ou
 | Flag | Effect |
 |---|---|
 | `--tools <tools>` | Comma-separated tool ids, `all`, or `none`. Skips the picker. Ids are listed in [Supported tools](supported-tools.md). |
+| `--language <language>` | Add a language instruction to a new project config. Rejected when the repo's `store:` line points to an external store. |
 | `--force` | Remove files from older OpenSpec layouts without asking. Interactive runs otherwise confirm the cleanup first. |
 | `--profile <profile>` | Override the global config profile for this run: `core` (the standard workflow set) or `custom` (the workflows saved in global config). |
 | `--no-animation` | Show a static welcome screen instead of the animated one. |
@@ -118,7 +134,7 @@ Restart your IDE for the new commands to take effect.
 **Exit codes**
 
 - `0`: setup completed.
-- `1`: invalid `--tools` or `--profile` value, or a non-interactive run with no tools detected and no `--tools`.
+- `1`: invalid `--tools` or `--profile` value, a non-interactive run with no tools detected and no `--tools`, or an invalid store-only invocation.
 
 ## openspec update
 
@@ -303,6 +319,15 @@ Pass --allow-unknown to bypass this check.
 Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"
 ```
 
+If the config file exists but does not hold a JSON object, whether because it is not valid JSON at all or because its root is something else such as `null` or an array, `config set`, `config unset` and `config profile` exit 1 and leave the file unchanged. Fix it with `openspec config edit`, or replace it with `openspec config reset --all`:
+
+```
+Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
+Fix it with "openspec config edit", or reset it with "openspec config reset --all".
+```
+
+Until it is fixed, telemetry and the update check stay off.
+
 ### openspec config unset
 
 ```bash
@@ -315,7 +340,7 @@ Removes the key so the default applies again. Keys with built-in defaults always
 Unset delivery (reverted to default)
 ```
 
-A key with no value at all prints `Key "featureFlags.nothere" was not set`. Both cases exit 0.
+A key with no value at all prints `Key "featureFlags.nothere" was not set`. Both cases exit 0. A config file that cannot be parsed exits 1 instead, as for `config set`.
 
 ### openspec config reset
 
@@ -351,7 +376,11 @@ Without `--all` it exits 1 and prints the usage line.
 openspec config edit
 ```
 
-Opens the config file in `$EDITOR` (falling back to `$VISUAL`), creating it with defaults first if missing. When the editor closes, the file is validated. Invalid JSON or an invalid config exits 1. With no editor configured it exits 1:
+Opens the config file in `$EDITOR` (falling back to `$VISUAL`), creating it with defaults first if missing. When the editor closes, the file is validated. Invalid JSON or an invalid config exits 1.
+
+The editor value may carry arguments and quoted paths, for example `code --wait` or `"/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w`. It is split into words without a shell, so `$VAR`, `~` and `;` are passed through literally. An editor that cannot start, or exits non-zero, prints a one-line error and exits 1.
+
+With no editor configured it exits 1:
 
 ```
 Error: No editor configured
@@ -397,12 +426,14 @@ Config updated. Run `openspec update` in your projects to apply.
 Lists changes, or specs with `--specs`.
 
 ```bash
-openspec list           # changes, most recently modified first
-openspec list --specs   # specs with requirement counts
-openspec list --json    # machine-readable, includes the resolved root
+openspec list                    # active changes, most recently modified first
+openspec list --archived         # archived changes
+openspec list --all              # active and archived changes
+openspec list --specs            # specs with requirement counts
+openspec list --json             # machine-readable, includes the resolved root
 ```
 
-Rows come from `openspec/changes/` and `openspec/specs/` under the resolved root. The `archive/` folder is skipped.
+Rows come from `openspec/changes/` and `openspec/specs/` under the resolved root. The default change listing skips `openspec/changes/archive/`.
 
 **Options**
 
@@ -410,8 +441,9 @@ Rows come from `openspec/changes/` and `openspec/specs/` under the resolved root
 |---|---|
 | `--specs` | List specs instead of changes. |
 | `--changes` | List changes. This is the default. |
+| `--archived` | List only archived changes. Can't be combined with `--specs`. |
+| `--all` | List active and archived changes. Can't be combined with `--specs`. Takes precedence over `--archived`. |
 | `--sort <order>` | `recent` (last modified first) or `name`. Default: `recent`. Specs always sort by name. |
-| `--status <state>` | Only list changes in this lifecycle state: `proposed` or `shipped`. A change with no `status` in its `.openspec.yaml` counts as `proposed`. |
 | `--json` | Print JSON instead of the table. |
 | `--store <id>` | Use a registered store as the OpenSpec root instead of the current project. |
 
@@ -424,6 +456,16 @@ Changes:
   add-rate-limit     No tasks      just now
 ```
 
+`--all` groups active and archived changes under separate headings. Each group uses the selected sort order:
+
+```
+Changes:
+  add-rate-limit     No tasks      just now
+
+Archived Changes:
+  2026-08-10-add-login     ✓ Complete    2d ago
+```
+
 ```
 Specs:
   api     requirements 1
@@ -449,7 +491,16 @@ Specs:
 }
 ```
 
-An empty listing prints `No active changes found.` or `No specs found.` and still exits 0.
+With `--archived` or `--all`, every change object includes an `archived` boolean. The combined array uses the selected sort order. An archived change can still have an `in-progress` status when its tracked task file has unchecked tasks. Without either flag, the JSON shape stays unchanged.
+
+An empty listing prints `No active changes found.`, `No archived changes found.`, `No changes found.`, or `No specs found.` and still exits 0.
+
+A change is a directory directly under `openspec/changes/`. Unlike specs, changes cannot be nested in a namespace folder. A folder like `changes/mobile/` that only wraps a change (`changes/mobile/refresh-token/`) is listed with the status `not a change`, followed by a warning that names the nested directories. `--json` marks that entry with a `nested` array and adds a top-level `warnings` array. `show`, `status`, `validate` and `archive` refuse the folder with the same message. To fix it, move the change up and fold the namespace into its name:
+
+```bash
+mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
+rmdir openspec/changes/mobile
+```
 
 **Exit codes**
 
@@ -523,9 +574,11 @@ A change with `--json` is delta-shaped:
       "operation": "ADDED",
       "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
       "requirement": {
+        "name": "Rate limit",
         "text": "The API SHALL limit each client to 100 requests per minute.",
         "scenarios": [
           {
+            "name": "Client exceeds the limit",
             "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
           }
         ]
@@ -540,9 +593,11 @@ A change with `--json` is delta-shaped:
 }
 ```
 
+Each requirement carries its `name`, the header text after `Requirement:`. This is the name archive matches MODIFIED, REMOVED and RENAMED entries against. Each scenario carries its `name`, the header text after `Scenario:`. A closing `#` run on either header is not part of the name.
+
 `--json --diff` keeps this top-level shape. A MODIFIED delta gains a `diff` string, a `warning` string, or both. Other operations are unchanged. An empty `diff` string means the main and delta blocks are textually identical.
 
-A spec with `--json` lists its requirements with scenarios:
+A spec with `--json` lists its requirements with scenarios. Requirements and scenarios carry the same `name` fields as change JSON:
 
 ```json
 {
@@ -552,9 +607,11 @@ A spec with `--json` lists its requirements with scenarios:
   "requirementCount": 1,
   "requirements": [
     {
+      "name": "Health endpoint",
       "text": "The API SHALL expose a health endpoint.",
       "scenarios": [
         {
+          "name": "Health check succeeds",
           "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
         }
       ]
@@ -621,6 +678,21 @@ Use openspec list --changes or openspec list --specs for detailed views
 
 A `Task Progress` summary line appears when any change has tasks underway.
 
+Each active change also shows its schema and artifact states below its task progress bar:
+
+```text
+    └─ [spec-driven] proposal✓ specs→ design→ tasks✓
+```
+
+| Marker | Artifact state |
+|---|---|
+| `✓` | Its output exists. An existing tasks artifact is done even when its checklist is unfinished. |
+| `→` | It is ready to create. |
+| No marker | It is blocked by a missing dependency. |
+| `(skipped)` | The change skips it. |
+
+If a workflow cannot be loaded, view prints a warning and keeps that change's task progress visible. Run `openspec status --change <name>` to inspect the workflow separately. After `openspec view --store <id>`, pass the same `--store <id>` to status.
+
 **Exit codes**
 
 - `0`: dashboard printed.
@@ -669,6 +741,18 @@ Bulk runs print one status line per item, followed by any findings, and end with
 Totals: 2 passed, 0 failed (2 items)
 ```
 
+**Task checkbox findings**
+
+Progress counts checkboxes and nothing else, so a task file written as plain bullets reads as zero tasks: `openspec list` and `openspec status` report no work, and `openspec archive` has nothing to flag as incomplete. Validate reports a `WARNING` on each tracked task file that lists work without a checkbox:
+
+```text
+⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".
+```
+
+The warning fires only when the change's whole tracked set holds no checkbox at all. One file of prose beside a real checklist is not reported, and a change mid-authoring keeps its progress the moment a single checkbox exists. `--strict` turns the warning into a failure. The line number is in the `--json` report.
+
+Fenced blocks, HTML comments, YAML front matter and indented code are not scanned, so a pasted terminal sample is never mistaken for a task list.
+
 **Archive merge findings**
 
 For changes, validate runs archive's merge builder against the current main specs without writing files. It reports merge conflicts, such as a missing `MODIFIED` target or a conflicting `ADDED` requirement, as `INFO`:
@@ -869,100 +953,6 @@ exit $validationExit
 
 These custom views keep the full report's keys but omit clean items. They are neither complete full-v1 reports nor the versioned `--report findings` shape.
 
-## openspec sync
-
-Folds a change's delta specs into the main specs, without archiving the change.
-
-```bash
-openspec sync add-rate-limit          # fold one change now; nothing moves
-openspec sync add-rate-limit --ship   # mark it shipped and fold it, in one set of changes
-openspec sync                         # fold every change declaring status: shipped
-openspec sync --check                 # exit 1 if a shipped change has unfolded deltas
-```
-
-`archive` folds and moves in one step, so the fold can only happen at the moment the
-change is finished. `sync` separates them: the specs can be brought up to date while
-the change is still open, and CI can check that they are.
-
-**Arguments**
-
-| Argument | What it is |
-|---|---|
-| `change-name` | The change to sync. Omitted, every change declaring `status: shipped` |
-
-**Options**
-
-| Flag | Effect |
-|---|---|
-| `--check` | Report shipped changes with unfolded deltas and exit 1. Writes nothing. |
-| `--ship` | Fold the named change, then set `status: shipped` on it. If the fold fails, the field is not set. |
-| `-y, --yes` | Sync even when the change has incomplete tasks. |
-| `--no-validate` | Skip validation. |
-| `--json` | Print a structured result instead of text. |
-| `--store <id>` | Use a registered store as the OpenSpec root. |
-
-**The lifecycle field**
-
-A change may declare where it sits, in its `.openspec.yaml`:
-
-```yaml
-schema: spec-driven
-status: shipped
-```
-
-Optional and absent by default. No `status` means `proposed`, which is what a change
-under `changes/` has always meant. Nothing writes the field on its own.
-
-**The gate**
-
-`openspec sync --check` asserts that a change claiming to be shipped has its deltas in
-`specs/`. A proposed change passes for free, so green is the resting state:
-
-```
-✓ 1 shipped change(s) are folded into the main specs.
-```
-
-and red names both the gap and the fix:
-
-```
-Sync check failed:
-
-  add-rate-limit
-    api: +1 not applied
-
-Run openspec sync to fold them, then commit the result.
-```
-
-It reads only files on disk — no VCS history, no timing — so a pre-commit hook, a
-pre-push hook and CI run the same command and agree.
-
-**Output**
-
-```
-Applying changes to openspec/specs/api/spec.md:
-  + 1 added
-Totals: + 1, ~ 0, - 0, → 0
-Specs updated successfully.
-```
-
-Running it again reports `Specs already in sync; no files changed.` — and so does
-`openspec archive` afterwards, because re-applying a folded delta is a no-op.
-
-**What it will not do**
-
-Sync never deletes a spec. When a change's `REMOVED` entries take a capability's last
-requirement, retiring it deletes the file, which stays with `openspec archive` behind
-the `retire_capabilities` marker. Sync reports the case and names archive instead.
-
-Sync also never examines archived changes: their deltas are history, superseded by
-whatever came after.
-
-**Exit codes**
-
-- `0`: the specs were folded, or `--check` found nothing wrong.
-- `1`: `--check` found an unfolded shipped change, validation failed, tasks were
-  incomplete, or the change was not found.
-
 ## openspec archive
 
 Moves a completed change to the archive and updates the main specs.
@@ -1095,7 +1085,20 @@ Schema: spec-driven
 Next: openspec status --change add-caching
 ```
 
-With `--json`:
+When no `openspec/` directory was found, `new change` creates one where you are and says so:
+
+```
+Created change 'add-caching' at openspec/changes/add-caching/
+Schema: spec-driven
+Next: openspec status --change add-caching
+
+Note: no OpenSpec root was found here, so one was created at openspec/.
+Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.
+```
+
+The notice goes to stdout with the rest of the human output, and never appears with `--json`.
+
+With `--json`, in a project that already has `openspec/`:
 
 ```json
 {
@@ -1112,6 +1115,15 @@ With `--json`:
 }
 ```
 
+When no `openspec/` directory was found and `new change` created one, the JSON has the same shape. `root.path` is the directory you ran it from, and `root.source` reads `implicit`:
+
+```json
+"root": {
+  "path": "/Users/you/projects/my-app",
+  "source": "implicit"
+}
+```
+
 **Exit codes**
 
 - `0`: change created.
@@ -1161,8 +1173,24 @@ Progress: 2/4 artifacts complete
 [x] specs
 [ ] design
 [-] tasks (blocked by: design)
+
+Next: openspec instructions design --change "add-rate-limit" --json
 ```
 
+The `Next:` line names the one command that moves the change forward, so `openspec status` is enough to pick a change back up in a fresh session. It names the next ready artifact while planning is unfinished, and `openspec instructions apply` once every planning artifact exists:
+
+```
+[x] proposal
+[x] specs
+[x] design
+[x] tasks
+
+All planning artifacts complete!
+Next: openspec instructions apply --change "add-rate-limit" --json
+```
+
+It carries `--store <id>` whenever the resolved root is a store, and names the same command as the JSON `nextSteps` sentence.
+
 `--json` adds per-artifact dependencies, resolved file paths, and a suggested next step. Trimmed:
 
 ```json
@@ -1314,7 +1342,11 @@ With `--json`, each form returns one object. The artifact form starts:
   ...
 ```
 
-and continues with `outputPath`, `existingOutputPaths`, the full `instruction` and `template` strings, `dependencies`, `unlocks`, and `root`. The `apply` form carries `contextFiles`, `progress`, `tasks`, `state` (`blocked`, `ready`, `all_done`), and `instruction`.
+and continues with `outputPath`, `existingOutputPaths`, the full `instruction` and `template` strings, `dependencies`, `unlocks`, and `root`. The `apply` form carries `contextFiles`, `progress`, `tasks`, `taskTrackingConfigured`, `state` (`blocked`, `ready`, `all_done`), and `instruction`.
+
+Each `tasks` entry carries `id`, `description`, `done`, `sourcePath`, and `line`. `sourcePath` is the absolute path to the tracked file that supplied the task. `line` is the task checkbox's one-based line number in that file.
+
+`taskTrackingConfigured` is always a boolean: `true` when the schema sets a non-null [`apply.tracks`](schemas/schema-yaml.md#tracks), even if no file matches, and `false` otherwise. If a matched tracking file cannot be read, `unavailableTrackingFiles` contains its absolute `path` and error `reason`. This field is omitted when every matched file is readable. Readable files still contribute to `tasks` and `progress`, but `state` cannot be `all_done` until every matched file is read.
 
 **Exit codes**
 
@@ -1506,7 +1538,7 @@ openspec schema validate spec-driven   # one schema, from any source
 openspec schema validate               # every project-local schema
 ```
 
-It verifies that `schema.yaml` exists and parses, that the structure matches the schema format, that every artifact's template file exists inside the schema's `templates/` directory, and that the dependency graph has no cycles or unknown references.
+It verifies that `schema.yaml` exists and parses, that the structure matches the schema format, that every artifact's template file exists inside the schema's `templates/` directory, and that the dependency graph has no cycles or unknown references, including in `apply.requires`. An `apply.tracks` value that isn't exactly equal to some artifact's `generates` value prints a `warning:` line but does not fail validation, because OpenSpec then can't tell which artifact's progress that file belongs to.
 
 **Options**
 
@@ -1655,6 +1687,8 @@ openspec store setup team-context --path ~/openspec/team-context
 
 In an interactive terminal, setup prompts for a missing name and location and confirms before creating anything. Outside one, a missing name or `--path` exits 1 with the flag to pass. Rerunning setup for a registered store reports `Registry: already registered`.
 
+Setup exits 1 with `store_setup_inside_git_repo` when `--path` is inside another Git repository, because initializing the store there would nest one repository in another. `--no-init-git` creates no repository, so it skips that check. Use it to keep a store at `~/openspec/<id>` when your home directory is itself a Git repository, such as a dotfiles repo.
+
 **Arguments**
 
 | Argument | What it is |
@@ -1778,6 +1812,8 @@ Error: Pass --yes to delete store files non-interactively.
 Fix: openspec store remove design-system --yes
 ```
 
+Remove exits 1 and deletes nothing when the folder lacks matching store metadata, or when it contains another registered store (for example a store vendored as a Git submodule). In that case the error is `store_remove_contains_registered_store`: run `openspec store unregister <nested-id>` first, or `openspec store unregister <id>` to forget the store without deleting files.
+
 **Options**
 
 | Flag | Effect |
@@ -2157,6 +2193,92 @@ In an interactive terminal, remove shows the workset and asks you to confirm. Wi
 Removed workset 'checkout'. Member folders were not touched.
 ```
 
+## openspec version
+
+Reports the running OpenSpec version and how this copy was installed.
+
+```bash
+openspec version                 # local version and install details
+openspec version --json          # structured local report
+openspec version --check         # also check the registry for an update
+openspec version --check --json  # structured local and update report
+```
+
+Without `--check`, this command is local and does not contact a registry. It works outside an OpenSpec project. The existing `openspec --version` flag remains the shortest form and prints only the bare version number.
+
+**Options**
+
+| Flag | Effect |
+|---|---|
+| `--json` | Print one versioned JSON document instead of text. |
+| `--check` | Check the configured registry for a newer release. |
+
+**Output**
+
+For a global npm install:
+
+```text
+OpenSpec 1.13.2 (npm, global)
+```
+
+The install scope is `global`, `project`, `temporary` for an ephemeral runner such as npx, or `source` for a checkout. OpenSpec omits details it cannot identify instead of guessing.
+
+`--json` keeps unknown details as explicit `null` values:
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "1.13.2",
+  "install": {
+    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
+    "packageManager": "npm",
+    "scope": "global"
+  }
+}
+```
+
+With `--check`, an available update adds the latest version and a command when OpenSpec can identify a safe command for that install:
+
+```text
+OpenSpec 1.13.2 (npm, global)
+Update available: 1.14.0
+  npm install -g @fission-ai/openspec@latest
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "1.13.2",
+  "install": {
+    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
+    "packageManager": "npm",
+    "scope": "global"
+  },
+  "update": {
+    "status": "available",
+    "latest": "1.14.0",
+    "command": "npm install -g @fission-ai/openspec@latest",
+    "canSelfUpgrade": true
+  }
+}
+```
+
+Update status values:
+
+| Status | Meaning |
+|---|---|
+| `available` | The registry returned a safe version newer than the running version. |
+| `current` | The check completed and found no newer version. |
+| `disabled` | An existing privacy or update-check setting blocked registry access. `latest` is `null`. |
+| `offline` | The registry was unavailable or returned an unusable response. `latest` is `null`. |
+
+`DO_NOT_TRACK`, telemetry opt-outs, `OPENSPEC_NO_UPDATE_CHECK`, CI detection, and rejected non-HTTPS registry overrides disable the check. Disabled and offline checks still exit 0 because update availability is advisory. This command never upgrades OpenSpec; `canSelfUpgrade` only reports whether the existing `openspec update` path could safely upgrade this copy.
+
+**Exit codes**
+
+- `0`: the local report printed, including disabled or offline update checks.
+- `1`: command syntax was invalid, such as the unsupported `--upgrade` option.
+
 ## openspec feedback
 
 Submits feedback about OpenSpec.
@@ -2214,6 +2336,8 @@ Supported shells: `zsh`, `bash`, `fish`, `powershell`. Every subcommand takes an
 | `install [shell]` | Write the script and configure your shell startup file. |
 | `uninstall [shell]` | Remove the script and the config block. |
 
+Installed with Nix, completions are already in place: the flake package ships the Bash, Fish, and Zsh scripts at the standard locations, so `install` is not needed ([Installation](../start/installation.md#nix)).
+
 ### openspec completion generate
 
 Prints the script and writes nothing.

docs-lab/reference/configuration/change-metadata.md

@@ -20,7 +20,7 @@ Each change keeps its metadata at `openspec/changes/<change-name>/.openspec.yaml
 
 ### schema
 
-The workflow schema this change follows. It is set when the change is created and wins over the project config, so a change keeps its schema even if `openspec/config.yaml` changes afterwards. Valid names are listed in [Schemas](../schemas/index.md).
+The workflow schema this change follows. It is set when the change is created and wins over the project config, so a change keeps its schema even if `openspec/config.yaml` changes afterwards. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
 
 ### initiative
 
@@ -36,11 +36,11 @@ Keys other than `store` and `id` are rejected. No command reads the link today.
 
 ### skip_specs
 
-Declares the change intentionally makes no spec deltas: a pure refactor, tooling, or docs change. With it set, validation accepts zero deltas, and artifacts that would generate spec files count as complete. Setting it while spec files exist under specs/ is a validation error. Its effect on deltas and archive is on [spec-driven](../schemas/spec-driven/index.md).
+Declares the change intentionally makes no spec deltas: a pure refactor, tooling, or docs change. With it set, validation accepts zero deltas, and artifacts that would generate spec files count as complete. Setting it while spec files exist under specs/ is a validation error.
 
 ### retire_capabilities
 
-Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call. The archive behavior is on [spec-driven](../schemas/spec-driven/index.md).
+Authorizes archive to retire a capability. When this change's REMOVED deltas take away the last requirement a capability has, archive deletes that capability's main spec instead of stopping. The flag exists because the deletion is only recoverable from git, so it stays the author's call.
 
 ## Example
 
@@ -59,4 +59,7 @@ affected_areas:
 
 The file is validated whenever a command writes or reads it. A write that fails validation throws and writes nothing. Reading an existing file fails on invalid YAML, a field that breaks its contract, or a schema name that is not available. A missing file is not an error, and the change is treated as having no metadata.
 
-Unlike [config.yaml](config-yaml.md), bad values are never dropped with a warning. A metadata error stops the command. The one exception is unknown top-level keys, which are ignored rather than rejected.
+Unlike [config.yaml](config-yaml.md), bad values are never dropped with a warning. A metadata error stops the command.
+
+- **Unknown top-level keys**: OpenSpec ignores them. `status`, `instructions`, `validate`, and `archive` report that they have no effect. JSON output carries the warning in its structured result.
+- **Strict validation**: `openspec validate --strict` treats an unknown-key warning as a failure.

docs-lab/reference/configuration/config-json.md

@@ -15,8 +15,8 @@ The CLI keeps its machine-level settings at `~/.config/openspec/config.json` on
 | `workflows` | list of strings | No | The workflow list a `custom` profile installs |
 | `featureFlags` | map: flag → boolean | No | Boolean feature toggles |
 | `defaultStore` | string | No | Machine-level fallback store for root resolution |
-| `openers` | list | No | The tools worksets open in, and how each is launched |
-| `telemetry` | map | No | State the CLI keeps: anonymous id and notice-seen |
+| `openers` | map: tool id → settings | No | The tools worksets open in, and how each is launched |
+| `telemetry` | map | No | Telemetry opt-out, anonymous id, and notice-seen state |
 
 ### profile
 
@@ -40,11 +40,45 @@ The machine-level fallback store id for root resolution, consulted only when no
 
 ### openers
 
-The tools a workset can open in, and how each is launched. Entries are hand-edited and validated on use. Each may set `style` (`workspace-file` or `attach-dirs`), `label`, `command`, `args`, and `attach_flag`, and is merged over the built-in defaults.
+The tools a workset can open in, keyed by tool id. Edit `openers` in the global `config.json` with `openspec config edit` in your terminal.
+
+| Field | Contract |
+| --- | --- |
+| `style` | `workspace-file` or `attach-dirs`. Required for a new tool; optional for a built-in. |
+| `label` | Non-empty string shown in the tool picker. Defaults to the id for a new tool. |
+| `command` | Non-empty executable name or path. Defaults to the id for a new tool. Put arguments in `args`, not in this string. |
+| `args` | Array of strings passed before the workspace file or attach flags. Defaults to `[]` for a new tool. |
+| `attach_flag` | Non-empty string paired with each member path for `attach-dirs`. Defaults to `--add-dir` for a new tool. Ignored for `workspace-file`. |
+
+**Built-in overrides:** `code`, `cursor`, `claude`, and `codex` retain any fields you omit. Setting `args` replaces the entire argument list; `[]` clears it.
+
+**Launch styles:** `workspace-file` passes the generated `.code-workspace` path to the executable. `attach-dirs` passes one flag/path pair per member, including the primary member.
+
+**Availability:** `attach-dirs` openers, including Claude Code and Codex, are disabled by default. You cannot select or save them with `--tool`, and OpenSpec refuses to open a workset that already names one. Configuration overrides do not enable the `attach-dirs` launch style.
+
+**Validation:** unknown fields, invalid types, and a new tool without `style` fail when a workset command reads the opener table.
+
+This example adds VS Code Insiders and passes `--new-window` whenever the built-in VS Code opener launches:
+
+```json
+{
+  "openers": {
+    "code-insiders": {
+      "style": "workspace-file",
+      "label": "VS Code Insiders"
+    },
+    "code": {
+      "args": ["--new-window"]
+    }
+  }
+}
+```
+
+The corresponding `code-insiders` or `code` executable must be installed and available on `PATH`.
 
 ### telemetry
 
-State the CLI writes for telemetry: your anonymous id and whether the first-run notice was shown. It is not the opt-out. Disabling telemetry is an environment variable, on [Environment variables](environment-variables.md).
+The CLI stores your anonymous id and whether the first-run notice was shown. Set `telemetry.enabled` to `false` to disable telemetry. You can also opt out with `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` in your environment.
 
 ## Example
 

docs-lab/reference/configuration/config-yaml.md

@@ -11,7 +11,7 @@ Each OpenSpec project keeps its config file at `openspec/config.yaml`, in the pr
 | Key | Type | Required | Effect |
 | --- | --- | --- | --- |
 | `schema` | string | Yes | The workflow schema this project's changes follow |
-| `context` | string | No | Injected into every artifact's instructions |
+| `context` | string | No | Injected into every artifact, apply, and archive |
 | `rules` | map: artifact ID → list of strings | No | Extra rules added to one artifact's built-in guidance |
 | `operations` | map: operation → guidance list | No | Advisory guidance for apply and archive work |
 | `store` | string | No | Fallback OpenSpec root when this openspec/ is config-only |
@@ -23,11 +23,11 @@ What to write in these fields is covered in [Project configuration](../../custom
 
 ### schema
 
-The workflow schema every change in this project follows. Valid values are `spec-driven` or a schema name the project defines. The names are listed in [Schemas](../schemas/index.md).
+The workflow schema every change in this project follows. Valid values are `spec-driven` or a schema name the project defines. Run [`openspec schemas`](../cli.md#openspec-schemas) to list the available schema names.
 
 ### context
 
-Free text injected into every artifact's instructions. The limit is 50KB, and a larger value is ignored with a warning.
+Free text injected into every artifact's instructions and supplied to apply and archive. The limit is 50KB, and a larger value is ignored with a warning.
 
 ### rules
 
@@ -77,14 +77,13 @@ A filled-in config.yaml:
 schema: spec-driven
 
 context: |
-  Tech stack: TypeScript, React, Node.js
-  We use conventional commits
-  Domain: e-commerce platform
+  Designs and tasks must cover Windows, macOS, and Linux
+  Write all artifacts in Spanish
 
 rules:
   proposal:
     - Keep proposals under 500 words
-    - Always include a "Non-goals" section
+    - Always state what is out of scope
   tasks:
     - Break tasks into chunks of max 2 hours
 

docs-lab/reference/configuration/index.md

@@ -7,5 +7,5 @@
 | [Project configuration (config.yaml)](config-yaml.md) | `openspec/config.yaml` | The schema, context, and rules this project plans with |
 | [Change metadata (.openspec.yaml)](change-metadata.md) | `openspec/changes/<name>/.openspec.yaml` | The workflow schema, goal, scope, and spec exceptions for one change |
 | [CLI settings (config.json)](config-json.md) | `~/.config/openspec/config.json` (Windows varies) | How the openspec CLI behaves on your machine |
-| [Environment variables](environment-variables.md) | Your shell or CI environment | Telemetry opt-out, and where the config and data directories live |
+| Environment variables | Your shell or CI environment | Telemetry opt-out, and where the config and data directories live |
 | Stores | `~/.local/share/openspec/stores/` (Windows varies) | The registry and metadata behind multi-repo stores |

docs-lab/reference/glossary.md

@@ -2,26 +2,26 @@
 
 > Every OpenSpec term, one line each.
 
-OpenSpec reuses words that mean something else in git, CI, and agent tooling. Each row gives the OpenSpec meaning, and the last column links to the page that teaches the term.
+OpenSpec reuses words that mean something else in git, CI, and agent tooling. Each row gives the OpenSpec meaning. The last column links to more detail where available.
 
 | Term | Definition | More |
 |---|---|---|
-| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](../guides/apply.md) |
+| **Apply** | Implement the tasks in a change proposal. Skill: `openspec-apply-change`. | [Apply a change](skills.md#openspec-apply-change) |
 | **Archive** | Complete a change proposal: merge its deltas into the main specs and move its folder to `openspec/changes/archive/`. | [Quickstart](../start/quickstart.md) |
-| **Artifact** | A planning document inside a change proposal: `proposal.md`, delta specs, `design.md`, `tasks.md`. Not a build output. | [Concepts](../guides/concepts.md) |
-| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
-| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Concepts](../guides/concepts.md) |
+| **Artifact** | A planning document inside a change proposal: `proposal.md`, delta specs, `design.md`, `tasks.md`. Not a build output. | [Artifacts](schemas/spec-driven/index.md#artifacts) |
+| **Capability** | One behavior area of your system. Each has one spec at `openspec/specs/<capability>/spec.md`. | [Capabilities](schemas/spec-driven/index.md#proposalmd) |
+| **Change proposal** | One unit of work: a folder under `openspec/changes/<name>/` holding its planning artifacts. Often shortened to "change". Not a git commit. | [Propose](../start/quickstart.md#step-2-propose) |
 | **Command** | A typed entry point for a workflow. Spelling varies per tool (`/opsx:propose`, `/opsx-propose`). The docs name workflows by skill instead. | [Supported tools](supported-tools.md) |
 | **Continue** | Create the next planning artifact for an existing change proposal. Skill: `openspec-continue-change`. | [Skills](skills.md) |
 | **Delivery** | How workflows are installed: as skills, commands, or both. | [Set up your project](../start/setup.md) |
 | **Delta spec** | A spec inside a change proposal listing only what changes, under `ADDED`, `MODIFIED`, `REMOVED`, and `RENAMED` headers. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
-| **Explore** | Think an idea through with the agent before proposing. Writes no code. Skill: `openspec-explore`. | [Explore an idea](../guides/explore.md) |
+| **Explore** | Think an idea through with the agent before proposing. Writes no code. Skill: `openspec-explore`. | [Explore an idea](skills.md#openspec-explore) |
 | **Fast-forward** | Create a change proposal with every planning artifact in one pass, ready to implement. Skill: `openspec-ff-change`. Not a git fast-forward. | [Skills](skills.md) |
-| **Legacy workflow** | The pre-OPSX `/openspec:*` commands. | [Migration](../help/legacy/migration.md) |
+| **Legacy workflow** | The pre-OPSX `/openspec:*` commands. |  |
 | **Loop** | The cycle a change proposal moves through: explore, propose, review, apply, archive. | [Quickstart](../start/quickstart.md) |
-| **Main specs** | The `openspec/specs/` tree: the current, agreed behavior of your system. Archiving merges deltas into it. | [Concepts](../guides/concepts.md) |
+| **Main specs** | The `openspec/specs/` tree: the current, agreed behavior of your system. Archiving merges deltas into it. A capability with no spec yet gets one from its `ADDED` requirements. | [Archive](../start/quickstart.md#step-5-archive) |
 | **OpenSpec root** | The `openspec/` tree a command resolves to and operates on: your repo's, or a store's. | [Stores](../multi-repo/stores.md#where-artifacts-get-created-when-using-stores) |
-| **OPSX** | The current OpenSpec workflow system, and the command prefix it installs (`/opsx:`). | [Architecture](architecture/index.md) |
+| **OPSX** | The current OpenSpec workflow system, and the command prefix it installs (`/opsx:`). |  |
 | **Profile** | Which workflows init installs: `core` or `custom`. | [Profiles](../customize/profiles.md) |
 | **Propose** | Create a change proposal and generate all its planning artifacts in one step. Skill: `openspec-propose`. | [Quickstart](../start/quickstart.md) |
 | **Registry** | The machine-level list of registered stores, in `registry.yaml`. Not a package registry. | [CLI](cli.md#openspec-store) |
@@ -29,12 +29,12 @@ OpenSpec reuses words that mean something else in git, CI, and agent tooling. Ea
 | **Scenario** | A testable example under a requirement, in WHEN/THEN form. | [Delta specs](schemas/spec-driven/index.md#delta-specs-specmd) |
 | **Schema** | The definition of which artifacts a change proposal produces, and in what order. Not JSON Schema. | [Schemas](schemas/index.md) |
 | **Skill** | A workflow's instructions, installed where your AI tool reads them (`.agents/skills/`, ...). | [Skills](skills.md) |
-| **Spec** | A file describing how one capability behaves today, at `openspec/specs/<capability>/spec.md`. | [Concepts](../guides/concepts.md) |
+| **Spec** | A file describing how one capability behaves today, at `openspec/specs/<capability>/spec.md`. | [Archive](../start/quickstart.md#step-5-archive) |
 | **spec-driven** | The default schema: proposal, then delta specs, then design, then tasks. | [spec-driven](schemas/spec-driven/index.md) |
 | **Store** | A standalone OpenSpec repo registered on your machine, for planning that spans repositories. Not a data store. | [Stores (beta)](../multi-repo/stores.md) |
 | **Sync** | Merge implemented deltas into the main specs without archiving. Skill: `openspec-sync-specs`. | [Skills](skills.md) |
 | **Template** | The starting content a schema gives each artifact. | [Schemas](../customize/schemas.md) |
-| **Update** | As a skill (`openspec-update-change`): revise a change proposal's planning artifacts. As a CLI command (`openspec update`): refresh OpenSpec's installed files. | [Change course](../guides/change-course.md), [CLI](cli.md) |
+| **Update** | As a skill (`openspec-update-change`): revise a change proposal's planning artifacts. As a CLI command (`openspec update`): refresh OpenSpec's installed files. | [Update a change](skills.md#openspec-update-change), [CLI](cli.md) |
 | **Verify** | Check the implementation matches a change proposal's artifacts before archiving. Skill: `openspec-verify-change`. | [Skills](skills.md) |
 | **Workflow** | A named OpenSpec action (propose, apply, archive, ...), installed into your AI tool as a skill or command. | [Set up your project](../start/setup.md) |
 | **Workset** | A personal, local group of folders opened together in one tool. Not a store, and nothing is shared. | [Worksets (beta)](../multi-repo/worksets.md) |

docs-lab/reference/schemas/schema-yaml.md

@@ -74,7 +74,15 @@ A glob can match several files:
 generates: specs/**/*.md
 ```
 
-This matches Markdown files below `openspec/changes/add-auth/specs/`. OpenSpec treats a value containing `*`, `?`, or `[` as a glob.
+This matches Markdown files below `openspec/changes/add-auth/specs/`.
+
+OpenSpec recognizes these glob forms in `generates`:
+
+- **Wildcards and character classes**: values containing `*`, `?`, or `[`, such as `specs/**/*.md` and `review-[ab].md`.
+- **Brace expansions**: alternatives such as `review-{api,ui}.md` and ranges such as `file-{1..3}.md`.
+- **Extglobs**: patterns such as `@(proposal|design).md`, `+(proposal|design).md`, and `!(proposal|design).md`.
+
+**Literal filenames**: a leading `!` alone does not make a glob. Use `generates: '!review.md'` to name that file. Plain parentheses such as `(proposal|design).md` and single-element braces such as `review-{api}.md` also remain literal.
 
 OpenSpec rejects absolute paths and paths containing a `..` segment.
 
@@ -119,7 +127,7 @@ OpenSpec rejects absolute paths and paths containing a `..` segment.
 | Field | Contract |
 |---|---|
 | `requires` | **Required.** A non-empty list of artifacts that must exist before apply instructions become ready. |
-| `tracks` | An optional relative path to a Markdown task file in the change folder. Default: `null`. |
+| `tracks` | An optional relative path or glob for Markdown task files in the change folder. Default: `null`. |
 | `instruction` | Optional guidance sent to the agent when apply is ready. OpenSpec uses built-in guidance by default. |
 
 Artifact `requires` controls planning order. `apply.requires` controls when apply instructions become ready.
@@ -132,21 +140,28 @@ The path starts from the change folder. For a change named `add-auth`, `tracks:
 openspec/changes/add-auth/tasks.md
 ```
 
-Apply stays blocked if that file is missing or contains no checkbox with task text. OpenSpec counts these checkbox forms:
+A glob such as `tracks: "**/tasks.md"` reads every matching file, such as `backend/tasks.md` and `frontend/tasks.md`. OpenSpec combines their tasks and progress. Use the same value for an artifact's `generates` field so status and list track the same files.
+
+Apply stays blocked if no file matches or the matched files contain no checkbox with task text. OpenSpec counts these checkbox forms:
 
 ```markdown
 - [ ] Pending task
 - [x] Completed task
 * [X] Completed task
++ [ ] Pending task
+1. [ ] Pending task
+2) [x] Completed task
 ```
 
-Leading spaces are allowed. The [tasks.md section of the spec-driven page](spec-driven/index.md#tasksmd) defines the stricter format produced by the default schema.
+Any Markdown list marker works: `-`, `*`, `+`, or a number of up to nine digits followed by `.` or `)`. Leading spaces are allowed. The [tasks.md section of the spec-driven page](spec-driven/index.md#tasksmd) defines the stricter format produced by the default schema.
 
-The tracked file drives the apply state:
+The tracked files drive the apply state:
 
-- **`blocked`**: the file is missing, or no checkbox has task text.
-- **`ready`**: at least one tracked task is pending.
-- **`all_done`**: every tracked task is checked.
+- **`blocked`**: no file matches, or no readable file has a checkbox with task text.
+- **`ready`**: at least one task is pending, or a matched file could not be read while another provides tasks.
+- **`all_done`**: every tracked task is checked and every matched file was read.
+
+If a matched file cannot be read, apply keeps the tasks and progress from readable files but does not mark the change `all_done`. [Apply JSON output](../cli.md#openspec-instructions) identifies each unavailable file and the reason.
 
 OpenSpec rejects absolute paths and paths containing a `..` segment.
 
@@ -198,12 +213,16 @@ apply:
 - Field types and required fields
 - Relative paths
 - Artifact IDs, dependencies, and cycles
+- `apply.requires` IDs: each must be an artifact in the schema
 - Template files
 
+A schema with an unknown `apply.requires` ID doesn't load, so every command that uses it reports the error.
+
+Validation warns, without failing, when `apply.tracks` isn't exactly equal to some artifact's `generates` value. OpenSpec finds the tracked artifact by comparing those two strings, so anything else leaves it unable to tell which artifact's progress the file belongs to. That includes a typo like `task.md`, and also `tracks: tasks/main.md` against `generates: tasks/*.md`, where the glob does produce the file but the strings still differ. Apply keeps reading the file either way, but `openspec list` and `openspec status` count `tasks.md` instead.
+
 Validation doesn't catch these mistakes:
 
 | Mistake | What happens |
 |---|---|
 | A field is misspelled, such as `instrution` | OpenSpec ignores it. Validation doesn't report the typo. |
-| `apply.requires` names an unknown artifact ID | Validation doesn't report the unknown ID. |
 | `name` differs from the schema directory | Validation passes. OpenSpec still uses the directory name for lookup. |

docs-lab/reference/schemas/spec-driven/index.md

@@ -54,6 +54,8 @@ Establishes why the change is needed.
 The template the agent receives as the output format ([templates/proposal.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/proposal.md)):
 
 ```md
+# Proposal
+
 ## Why
 
 <!-- Explain the motivation for this change. What problem does this solve? Why now? -->
@@ -65,9 +67,12 @@ The template the agent receives as the output format ([templates/proposal.md](ht
 ## Capabilities
 
 ### New Capabilities
-<!-- Capabilities being introduced. Use kebab-case for path segments you introduce
-     (e.g., user-auth or identity/user-auth) that follow the project's existing
-     spec organization. Each creates specs/<capability-path>/spec.md. -->
+<!-- Capabilities being introduced. Name each capability for a cohesive system
+     behavior that can own related requirements as the system evolves. Do not name
+     implementation tasks or proposal sections. Avoid broad catch-all names. Use
+     kebab-case for path segments you introduce (e.g., user-auth or identity/user-auth)
+     that follow the project's existing spec organization. Each creates
+     specs/<capability-path>/spec.md. -->
 - `<capability-path>`: <brief description of what this capability covers>
 
 ### Modified Capabilities
@@ -96,12 +101,24 @@ Sections:
 - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
 - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
 - **Capabilities**: Identify which specs will be created or modified:
-  - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
+  - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Name each capability for a durable system behavior (for example, `user-auth`), not the work in this change (for example, `add-login-endpoint`). Choose a cohesive boundary that can own related requirements as the system evolves; avoid broad catch-all capabilities. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
   - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
 - **Impact**: Affected code, APIs, dependencies, or systems.
 
 IMPORTANT: The Capabilities section is critical. It creates the contract between
-proposal and specs phases. Research existing specs before filling this in.
+proposal and specs phases. Research existing specs before filling this in:
+run `openspec list --specs` for the project's capability inventory, then
+`openspec show "<spec-id>" --type spec --json --no-scenarios` for any that
+look related - that returns a capability's purpose and requirement texts
+without pulling whole spec files into context. Append `--store "<id>"` to
+both commands only for a registered standalone store, and keep `--type
+spec`: a change and a spec sharing a name is otherwise an ambiguous-item
+error. `openspec list` without `--specs` lists in-flight changes, not
+specs - it never shows what the project already covers. Reuse an existing
+capability's exact path instead of introducing a near-duplicate name.
+The filtered read is only an overview. Before deciding what is already
+covered or what should change, read each relevant spec in full, including
+scenarios, with `openspec show "<spec-id>" --type spec` (same `--store` rule).
 Each capability listed here will need a corresponding spec file.
 
 Every change must either declare at least one capability (new or
@@ -122,11 +139,15 @@ This is the foundation - specs, design, and tasks all build on this.
 
 Defines what behavior changes, with one delta spec per capability the proposal lists.
 
+Each delta spec is the `spec.md` inside its capability folder. `openspec validate` and `openspec archive` reject delta sections written in any other file under `specs/`, such as `specs/user-auth.md`, because archive never merges them.
+
 ### Structure
 
 The template the agent receives as the output format ([templates/spec.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/spec.md)):
 
 ```md
+# Spec Delta
+
 ## Purpose
 <!-- New capabilities only: one or two sentences (50+ characters) on what this capability is for. Delete this section for an existing capability. -->
 
@@ -168,7 +189,7 @@ Create one spec file per capability listed in the proposal's Capabilities sectio
 `<capability-path>` is the spec directory relative to `specs/` (for example,
 `user-auth` or `identity/user-auth`). Preserve the full path:
 - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
-- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+- Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Run `openspec list --specs` to confirm that path before writing the delta, appending `--store "<id>"` only for a registered standalone store - a mistyped or invented path targets a capability that does not exist rather than the one you meant. Do not move or rename the capability.
 
 There must be at least one spec file unless the change's `.openspec.yaml`
 sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
@@ -187,8 +208,9 @@ Format requirements:
 - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
 - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
 - Every requirement MUST have at least one scenario.
+- Keep each requirement's description (the text between `### Requirement:` and its first scenario) to 500 characters or fewer. `openspec validate` flags longer descriptions in ADDED requirements and in the main spec. This is a warning: normal validation still passes, but `openspec validate --strict` fails on it. When writing a new requirement, state one behavior per requirement: move examples and edge cases into scenarios, and split a requirement that covers several behaviors into separate `### Requirement:` blocks, each with its own scenarios. Under MODIFIED, keep the existing requirement block whole; never split, trim or rewrite existing text just to meet the length. Split an existing long requirement only when the user asks for it, in a change made for that purpose: under MODIFIED, keep its header and every scenario and cut its description down to one behavior without changing its meaning, then add each behavior you removed as its own ADDED requirement with its own scenarios.
 
-New capabilities only: start the delta spec with a `## Purpose` section -
+New capabilities only: the delta spec's first section is `## Purpose` -
 one or two sentences (50+ characters, or `openspec validate --strict`
 reports it as too brief) describing what the capability is for. Archive
 copies it into the main spec it creates; without it the new main spec is
@@ -196,10 +218,16 @@ left with a `TBD ... Update Purpose after archive` placeholder to fill in
 by hand. Do NOT add `## Purpose` to a delta for an existing capability -
 that spec already has one and the delta's is ignored. To change an
 existing capability's Purpose - including a leftover `TBD` placeholder -
-edit `openspec/specs/<capability-path>/spec.md` directly.
+edit `<planningHome.root>/openspec/specs/<capability-path>/spec.md`
+directly. `planningHome.root` comes from the `openspec instructions ...
+--json` response. Always use it rather than a repo-relative path: it
+resolves to the store whenever the change lives in one - whether that
+came from `--store`, a project `store:` pointer, or a global default
+store - and to the current repository otherwise. Do not try to work out
+which case applies; the field already has.
 
 MODIFIED requirements workflow:
-1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
+1. Locate the existing requirement in `<planningHome.root>/openspec/specs/<capability-path>/spec.md` (the same store-aware root as above)
 2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
 3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
 4. Ensure header text matches exactly (whitespace-insensitive)
@@ -207,8 +235,10 @@ MODIFIED requirements workflow:
 Common pitfall: Using MODIFIED with partial content loses detail at archive time.
 If adding new concerns without changing existing behavior, use ADDED instead.
 
-Example (a new capability, so it opens with `## Purpose`):
+Example (a new capability, so its first section is `## Purpose`):
 ```
+# Spec Delta
+
 ## Purpose
 
 Lets users take their data out of the product in a portable format.
@@ -241,6 +271,8 @@ Explains how to implement the change. Drafted only when the change needs one.
 The template the agent receives as the output format ([templates/design.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/design.md)):
 
 ```md
+# Design
+
 ## Context
 
 <!-- Current state and constraints that shape the approach. See proposal.md for motivation - don't restate it -->
@@ -305,6 +337,8 @@ Breaks the implementation into checkable tasks. [apply](#apply) tracks progress
 The template the agent receives as the output format ([templates/tasks.md](https://github.com/Fission-AI/OpenSpec/blob/main/schemas/spec-driven/templates/tasks.md)):
 
 ```md
+# Tasks
+
 ## 1. <!-- Task Group Name -->
 
 - [ ] 1.1 <!-- Task description -->
@@ -327,30 +361,60 @@ Before writing tasks, check design.md for Open Questions. If any of them
 would change what gets built, resolve them with the user first - do not
 bake an unstated assumption into the task list.
 
-**IMPORTANT: Follow the template below exactly.** The apply phase parses
-checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+**IMPORTANT: Follow the template below for tracked tasks.** The apply phase parses
+checkbox format to track progress. A box holding only `x` counts as done,
+upper or lower case and with any spacing, so `- [ x]` is done too. Every
+other marker, including `- [~]`, `- [-]` and an empty `- []`, reads as
+unfinished. A line with no checkbox is not tracked at all.
 
 Guidelines:
-- Group related tasks under ## numbered headings
-- Each task MUST be a checkbox: `- [ ] X.Y Task description`
+- Group related tracked tasks under ## numbered headings
+- Each tracked task MUST be a checkbox: `- [ ] X.Y Task description`
 - Tasks should be small enough to complete in one session
 - Order tasks by dependency (what must be done first?)
+- Track implementation and verification work that can be completed before
+  archive. If the requested workflow includes archive or work that requires
+  this change to be archived, preserve those steps as plain bullets in an
+  optional `## Workflow follow-up` section at the end of tasks.md. These
+  bullets are reference information outside tracked task progress.
+- Each task MUST state how to verify completion (a test, command,
+  observable behavior, or delivered artifact). Put the verification in
+  that task's checkbox description. Use a separate verification task only
+  when it checks broader integration or system behavior that spans
+  multiple implementation tasks.
+- Each task group MUST land the tests and documentation its own work
+  calls for. Do NOT collect testing or documentation into a final group -
+  when a late group first exercises work from an early one, the failures
+  cascade back through every group in between and force rework. A group
+  whose work calls for neither, such as scaffolding or dependency setup,
+  carries neither. A final group is for integration checks only, not for
+  the tests and docs an earlier group owed.
 
 Example:
 ```
+# Tasks
+
 ## 1. Setup
 
-- [ ] 1.1 Create new module structure
-- [ ] 1.2 Add dependencies to package.json
+- [ ] 1.1 Create new module structure and verify expected files are present
+- [ ] 1.2 Add dependencies to package.json and verify package installation succeeds
 
 ## 2. Core Implementation
 
-- [ ] 2.1 Implement data export function
-- [ ] 2.2 Add CSV formatting utilities
+- [ ] 2.1 Implement data export function and verify the export test passes
+- [ ] 2.2 Add CSV formatting utilities and verify unit tests cover quoting and delimiters
+- [ ] 2.3 Document the export API in docs/export.md and verify the documented command runs as written
+```
+
+When applicable, append workflow follow-up as plain bullets, for example:
+```
+## Workflow follow-up
+
+- Archive the change after the project's review requirements are satisfied.
+- Verify the archived result.
 ```
 
 Reference specs for what needs to be built, design for how to build it.
-Each task should be verifiable - you know when it's done.
 ````
 
 ## Apply

docs-lab/reference/skills.md

@@ -39,6 +39,13 @@ The skills come in two sets:
 - **Core**: installed by default, the main planning loop.
 - **Optional**: installed only when you add them, via [Profiles](../customize/profiles.md).
 
+Every skill expects a project that already uses OpenSpec. Before its first step that writes anything, a skill checks for a resolved root. What happens when there is none depends on how the skill was reached:
+
+- **Auto-selected**: your agent picked the skill on its own, without you naming OpenSpec. It drops OpenSpec and answers your request normally, the way it would with OpenSpec not installed.
+- **Explicit OpenSpec request**: you named OpenSpec, named the skill, or ran its command. It stops before writing and asks how to proceed: run `openspec init` here, target a store with `--store <id>`, or continue without OpenSpec. It waits for your answer.
+
+Commands are always the second case. A project whose `openspec/config.yaml` names a store this machine cannot resolve (not registered, or a malformed `store:` line) is not treated as uninitialized: the skill stops and shows the store error with its fix. No skill creates an `openspec/` directory on its own in either case. The entries below describe what each skill does once a root is in place.
+
 | Skill | Job | Type |
 |---|---|---|
 | [openspec-explore](#openspec-explore) | Think through an idea before it becomes a change proposal | Core |
@@ -54,6 +61,8 @@ The skills come in two sets:
 | [openspec-bulk-archive-change](#openspec-bulk-archive-change) | Archive several change proposals at once | Optional |
 | [openspec-onboard](#openspec-onboard) | Learn the workflow by doing one real change proposal end to end | Optional |
 
+Each entry below names the skill that owns the next step. When your profile leaves that skill out, the installed files never name it: the handoff becomes the equivalent `openspec` command, or a plain request to you, and a line that exists only to point at a missing skill is not written at all. So the skills you have always hand off to skills you have. Which set you get is [Profiles](../customize/profiles.md).
+
 ## openspec-explore
 
 Think through an idea before it becomes a change proposal.
@@ -81,8 +90,8 @@ Implement a change proposal's tasks, working through the list until done or bloc
 | Contract | Description |
 |---|---|
 | **Arguments** | A change proposal name (`add-auth`), optional. If the target is ambiguous it lists the active change proposals and asks you to pick. |
-| **Creates** | Code: the minimal changes each task calls for, in your project files. In the change proposal it touches only the tasks file, checking off each finished task (`- [ ]` to `- [x]`). |
-| **Response** | Progress per task, then an overall count (N/M tasks complete). All done: suggests `openspec-archive-change`. Blocked by missing artifacts: points to `openspec-continue-change`. Unclear tasks or errors: pauses and asks. |
+| **Creates** | Code: the minimal changes each task calls for, in your project files. In the change proposal it checks off each finished task (`- [ ]` to `- [x]`) in the tracked file identified by `sourcePath` and one-based `line`. A schema may track tasks across multiple files. |
+| **Response** | Progress per task, then an overall count (N/M tasks complete). All done: suggests `openspec-archive-change`. Blocked by missing artifacts: points to `openspec-continue-change`, or to `openspec status` and `openspec instructions` when that skill is not installed (the core profile leaves it out). Unclear tasks or errors: pauses and asks. |
 
 ## openspec-update-change
 
@@ -92,7 +101,7 @@ other.
 | Contract | Description |
 |---|---|
 | **Arguments** | A change proposal name, optional, plus the revision you want. With no revision stated it runs a coherence review: artifacts checked against each other for contradictions, gaps, and duplication. |
-| **Creates** | Nothing new. Edits only artifact files that already exist. Missing artifacts are `openspec-continue-change`'s job. Never code. |
+| **Creates** | Edits artifact files that already exist. One exception: for an artifact written as a glob, such as `specs/**/*.md`, that already has at least one file, it can add a missing companion file once you confirm the path. An artifact with no files yet is `openspec-continue-change`'s job. Without that skill (the core profile leaves it out), it points to `openspec status` and `openspec instructions` instead. Never code. |
 | **Response** | Shows each proposed revision and writes it only after you confirm, one artifact at a time. Ends with what was revised and the next step; implementation waits for `openspec-apply-change`. |
 
 ## openspec-sync-specs
@@ -112,7 +121,7 @@ Move a finished change proposal to the archive.
 | Contract | Description |
 |---|---|
 | **Arguments** | A change proposal name, optional. |
-| **Creates** | Moves the change proposal folder to `openspec/changes/archive/YYYY-MM-DD-<name>/` (no date added if the name already starts with one). With your approval it first syncs outstanding delta specs via `openspec-sync-specs`. Never code. |
+| **Creates** | Moves the change proposal folder to `openspec/changes/archive/YYYY-MM-DD-<name>/` (no date added if the name already starts with one). With your approval it first syncs outstanding delta specs. When `openspec-sync-specs` is installed, it runs that workflow. Otherwise, it merges the delta specs into the main specs itself. Never code. |
 | **Response** | Warns and asks before archiving with incomplete artifacts or tasks, and asks whether to sync when delta specs exist. Ends with a summary: name, schema, archive location, spec sync status, and any warnings. |
 
 ## openspec-new-change

docs-lab/reference/supported-tools.md

@@ -15,27 +15,35 @@ The id goes to `openspec init --tools <id>` to skip the picker ([CLI](cli.md)).
 | Tool | `--tools` id | Skills | Skill invocation | Commands | Command invocation |
 |---|---|---|---|---|---|
 | Amazon Q Developer | `amazon-q` | `.amazonq/skills/` | `/openspec-apply-change` | `.amazonq/prompts/` | `@opsx-apply` |
+| Amp | `amp` | `.agents/skills/` | `/openspec-apply-change` | none | none |
 | Antigravity | `antigravity` | `.agents/skills/` | `/openspec-apply-change` | `.agents/workflows/` | `/opsx-apply` |
+| AtomCode | `atomcode` | `.atomcode/skills/` | `/openspec-apply-change` | `.atomcode/commands/` | `/opsx-apply` |
 | Auggie (Augment CLI) | `auggie` | `.augment/skills/` | `/openspec-apply-change` | `.augment/commands/` | `/opsx-apply` |
-| Bob Shell | `bob` | `.bob/skills/` | `/openspec-apply-change` | `.bob/commands/` | `/opsx-apply` |
+| IBM Bob | `bob` | `.bob/skills/` | `/openspec-apply-change` | `.bob/commands/` | `/opsx-apply` |
 | Claude Code | `claude` | `.claude/skills/` | `/openspec-apply-change` | `.claude/commands/opsx/` | `/opsx:apply` |
 | Cline | `cline` | `.cline/skills/` | `/openspec-apply-change` | `.clinerules/workflows/` | `/opsx-apply` |
 | CodeArts | `codeartsagent` | `.codeartsdoer/skills/` | `/openspec-apply-change` | none | none |
 | CodeBuddy Code (CLI) | `codebuddy` | `.codebuddy/skills/` | `/openspec-apply-change` | `.codebuddy/commands/opsx/` | `/opsx:apply` |
+| Code Studio | `codestudio` | `.codestudio/skills/` | `/openspec-apply-change` | `.codestudio/prompts/` | `/opsx-apply` |
 | Codex | `codex` | `.agents/skills/` | `$openspec-apply-change` | none | none |
 | Continue | `continue` | `.continue/skills/` | `/openspec-apply-change` | `.continue/prompts/` | `/opsx-apply` |
 | CoStrict | `costrict` | `.cospec/skills/` | `/openspec-apply-change` | `.cospec/openspec/commands/` | `/opsx-apply` |
 | Crush | `crush` | `.crush/skills/` | `/openspec-apply-change` | `.crush/commands/opsx/` | `/opsx:apply` |
 | Cursor | `cursor` | `.cursor/skills/` | `/openspec-apply-change` | `.cursor/commands/` | `/opsx-apply` |
+| DeepSeek Harness | `dsh` | `.dsh/skills/` | `/openspec-apply-change` | none | none |
 | Devin Desktop (formerly Windsurf) | `devin` | `.devin/skills/` | `/openspec-apply-change` | `.devin/workflows/` | `/opsx-apply` |
+| EasyCode | `easycode` | `.easycode/skills/` | `/openspec-apply-change` | `.easycode/commands/opsx/` | `/opsx:apply` |
 | Factory Droid | `factory` | `.factory/skills/` | `/openspec-apply-change` | `.factory/commands/` | `/opsx-apply` |
 | ForgeCode | `forgecode` | `.forge/skills/` | `/openspec-apply-change` | none | none |
 | Gemini CLI | `gemini` | `.gemini/skills/` | `/openspec-apply-change` | `.gemini/commands/opsx/` | `/opsx:apply` |
+| GigaCode | `gigacode` | `.gigacode/skills/` | `/openspec-apply-change` | `.gigacode/commands/` | `/opsx-apply` |
 | GitHub Copilot | `github-copilot` | `.github/skills/` | `/openspec-apply-change` | `.github/prompts/` | `/opsx-apply` |
+| Grok Build | `grok` | `.grok/skills/` | `/openspec-apply-change` | none | none |
+| GSD | `gsd` | `.agents/skills/` | ask for `openspec-apply-change` | none | none |
 | Hermes Agent | `hermes` | `.hermes/skills/` | `/openspec-apply-change` | none | none |
 | iFlow | `iflow` | `.iflow/skills/` | `/openspec-apply-change` | `.iflow/commands/` | `/opsx-apply` |
 | Junie | `junie` | `.junie/skills/` | `/openspec-apply-change` | `.junie/commands/` | `/opsx-apply` |
-| Kilo Code | `kilocode` | `.kilocode/skills/` | `/openspec-apply-change` | `.kilocode/workflows/` | `/opsx-apply` |
+| Kilo Code | `kilocode` | `.kilocode/skills/` | `/openspec-apply-change` | `.kilo/command/` | `/opsx-apply` |
 | Kimi Code | `kimi` | `.kimi-code/skills/` | `/skill:openspec-apply-change` | none | none |
 | Kiro | `kiro` | `.kiro/skills/` | `/openspec-apply-change` | `.kiro/prompts/` | `/opsx-apply` |
 | Lingma | `lingma` | `.lingma/skills/` | `/openspec-apply-change` | `.lingma/commands/opsx/` | `/opsx:apply` |
@@ -47,21 +55,30 @@ The id goes to `openspec init --tools <id>` to skip the picker ([CLI](cli.md)).
 | Qoder | `qoder` | `.qoder/skills/` | `/openspec-apply-change` | `.qoder/commands/opsx/` | `/opsx:apply` |
 | Qwen Code | `qwen` | `.qwen/skills/` | `/openspec-apply-change` | `.qwen/commands/` | `/opsx-apply` |
 | Trae | `trae` | `.trae/skills/` | `/openspec-apply-change` | `.trae/commands/` | `/opsx-apply` |
+| [Veai](https://veai.ru/docs/veai/download) | `veai` | `.veai/skills/` | `/openspec-apply-change` | none | none |
+| Warp | `warp` | `.warp/skills/` | `/openspec-apply-change` | none | none |
 | ZCode | `zcode` | `.zcode/skills/` | `/openspec-apply-change` | `.zcode/commands/opsx/` | `/opsx:apply` |
 | Zoo Code | `roocode` | `.roo/skills/` | `/openspec-apply-change` | `.roo/commands/` | `/opsx-apply` |
-| Shared `.agents` skills | `agents` | `.agents/skills/` | `/openspec-apply-change` | none | none |
+| Other / Universal | `agents` | `.agents/skills/` | `/openspec-apply-change` | none | none |
 
 - **Skill invocation**: whether a tool registers skills as typed entries is the tool's
   own behavior. The column shows the spelling OpenSpec uses in generated files and in
   the hint init prints. Check your tool's docs if typing it does nothing.
-- **Command file formats**: most tools take `.md` command files. Gemini CLI takes
-  `.toml`, Continue `.prompt`, Kiro and GitHub Copilot `.prompt.md`. The spelling you
-  type is the same either way.
+- **Command file formats**: most tools take `.md` command files. EasyCode and Gemini
+  CLI take `.toml`, Continue `.prompt`, and Code Studio, Kiro, and GitHub Copilot
+  `.prompt.md`. The spelling you type is the same either way.
 
 ## Per-tool notes
 
 A tool not listed here behaves exactly as its row reads.
 
+### Amp
+
+- **Project skills**: Amp reads OpenSpec skills from `.agents/skills/`.
+- **No command files**: Amp runs skills directly, so init skips command generation.
+- **Shared folder**: Amp shares `.agents/skills/` with Antigravity, Codex, Zed Agent,
+  and the `agents` target. OpenSpec writes the skill tree once.
+
 ### Antigravity
 
 - **Current folder**: Antigravity v1.20.5 and later read workspace skills and
@@ -69,8 +86,8 @@ A tool not listed here behaves exactly as its row reads.
 - **Legacy folder**: after OpenSpec writes replacements, it removes equivalent
   generated files from `.agent/`. Custom files and changed generated files stay in
   `.agent/` for you to review.
-- **Shared skills**: Antigravity shares `.agents/skills/` with Codex, Zed Agent, and
-  the `agents` target. OpenSpec writes that skill tree once while still writing
+- **Shared skills**: Antigravity shares `.agents/skills/` with Amp, Codex, Zed Agent,
+  and the `agents` target. OpenSpec writes that skill tree once while still writing
   Antigravity commands to `.agents/workflows/`.
 
 ### Cline
@@ -80,17 +97,34 @@ Skills stay in `.cline/skills/`.
 
 ### Codex
 
-- **Invocation**: type `$openspec-<skill>`. Codex does not recognize the
-  `/openspec-<skill>` form ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **CLI and IDE extension**: mention `$openspec-propose` with your idea, or run
+  `/skills` to select the skill. Codex does not recognize `/openspec-propose`
+  ([upstream issue](https://github.com/openai/codex/issues/11817)).
+- **Desktop app**: open Skills in the sidebar and select `openspec-propose`.
+  [OpenAI's skills documentation](https://learn.chatgpt.com/docs/build-skills)
+  describes both interfaces.
 - **No command files**: Codex runs skills directly, so init skips commands even when
   delivery includes them and prints `Commands skipped for: codex (uses skills)`.
-- **Shared folder**: Codex skills land in `.agents/skills/`, the same tree Antigravity,
-  Zed Agent, and the `agents` target use. Selecting more than one keeps a single
-  compatible tree, and its handoffs spell both `$openspec-*` and `/openspec-*` when
-  Codex owns it.
+- **Shared folder**: Codex skills land in `.agents/skills/`, the same tree Amp,
+  Antigravity, Zed Agent, and the `agents` target use. Selecting more than one keeps a
+  single compatible tree, and its handoffs spell both `$openspec-*` and `/openspec-*`
+  when Codex owns it.
 - **Legacy path**: skills installed under `.codex/skills/` by older versions are
   migrated on the next `openspec update`.
 
+### DeepSeek Harness
+
+- **Project root**: DSH uses the nearest `.git` ancestor, or the current directory
+  outside Git. Run `openspec init --tools dsh` there. For a nested OpenSpec project,
+  add the absolute path to its `.dsh/skills/` directory to DSH's `customSkillDirs`.
+  Git-root skills still win if names overlap
+  ([upstream discovery rules](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/skill/skill-filesystem)).
+- **Priority**: `.dsh/skills/` takes precedence over same-named skills in
+  `.agents/skills/`.
+- **Delivery**: use `skills` or `both`. With `commands`, no DSH workflows are
+  installed. Change delivery with `openspec config profile`, then rerun
+  `openspec init --tools dsh`.
+
 ### Devin Desktop (formerly Windsurf)
 
 - **Two agents**: command files in `.devin/workflows/` work only in Devin Desktop.
@@ -102,8 +136,22 @@ Skills stay in `.cline/skills/`.
 
 ### GitHub Copilot
 
-Prompt files register as slash commands in the Copilot IDE extensions (VS Code,
-JetBrains, Visual Studio). Copilot CLI does not read `.github/prompts/`.
+- **IDE extensions (command delivery)**: VS Code, JetBrains, and Visual Studio load
+  `.github/prompts/opsx-<id>.prompt.md` as `/opsx-<id>`. If a command disappears
+  while its file still exists, restart the IDE.
+- **Copilot CLI (skill delivery)**: the CLI ignores `.github/prompts/` and loads
+  `.github/skills/openspec-*/SKILL.md` instead. Invoke a skill as
+  `/openspec-<skill>`. If a skill disappears while its file still exists, run
+  `/skills reload`, then `/skills info openspec-propose` to confirm discovery.
+
+### GSD
+
+- **Project skills**: GSD reads OpenSpec workflows from
+  [`.agents/skills/`](https://github.com/open-gsd/gsd-pi/blob/main/docs/user-docs/skills.md).
+- **Invocation**: ask GSD to use the `openspec-<workflow>` skill. GSD can also select
+  a matching skill through its skill discovery setting.
+- **No subagent files**: [`.gsd/agents/`](https://github.com/open-gsd/gsd-pi/blob/main/docs/user-docs/subagents.md)
+  contains GSD subagent definitions. OpenSpec does not write workflow skills there.
 
 ### Hermes Agent
 
@@ -118,11 +166,21 @@ init prints this reminder after install.
 - **Safe across projects**: a commands-only delivery leaves the global skills in
   place, so one project's setting cannot remove skills another project uses.
 
-### Shared `.agents` skills
+### Warp
+
+- **Skills always**: skills go to `.warp/skills/` even when delivery is `commands`,
+  because Warp has no command files and invokes skills directly.
+- **What OpenSpec claims**: only `.warp/skills/`. Warp settings and `WARP.md` are
+  not created or edited.
+
+### Other / Universal (shared `.agents` skills)
 
 - **When it fits**: any tool that reads the shared `.agents/skills/` folder,
-  including tools with no row in the matrix.
-- **Alongside other targets**: Antigravity, Codex, Zed Agent, and this target share
+  including tools with no row in the matrix. It is the entry to pick when your
+  assistant is not listed. The init picker's search box finds it by `universal`,
+  `other`, `generic`, `custom`, `proprietary`, `unlisted`, `unsupported`,
+  `vendor-neutral`, or `agents.md`.
+- **Alongside other targets**: Amp, Antigravity, Codex, Zed Agent, and this target share
   one physical skill tree. OpenSpec records one writer in `.openspec-target` and
   writes the tree once per run. Each tool's separate command files are still
   generated.

docs-lab/start/installation.md

@@ -5,7 +5,9 @@
 
 ## Prerequisites
 
-OpenSpec is a Node.js CLI. You need version 20.19.0 or newer.
+OpenSpec runs on Node.js 20.19.0 or newer. Homebrew installs Node.js as a
+dependency, and the Nix package includes the runtime. Check your installed version
+before using another install method.
 
 In your terminal:
 
@@ -13,7 +15,9 @@ In your terminal:
 node --version
 ```
 
-If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from [nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf, volta).
+If that prints `v20.19.0` or higher, you're set. If not, install a newer Node from
+[nodejs.org](https://nodejs.org) or through your version manager (nvm, fnm, asdf,
+volta). You can skip this check when you install with Homebrew or Nix.
 
 The workflow itself runs inside an AI coding tool: Claude Code, Cursor, or any other tool on the [supported list](../reference/supported-tools.md).
 
@@ -53,6 +57,16 @@ In your terminal:
 npm install -g @fission-ai/openspec@latest
 ```
 
+### Homebrew
+
+Homebrew installs OpenSpec and its Node.js dependency on macOS or Linux. In your terminal:
+
+```bash
+brew install openspec
+```
+
+The formula is published in [homebrew-core](https://formulae.brew.sh/formula/openspec), so you don't need to add a tap.
+
 ### Yarn
 
 `yarn global add` is Yarn Classic (1.x) only. Modern Yarn removed global installs, so use npm, pnpm, or bun instead. A global CLI doesn't have to share your project's package manager.
@@ -94,6 +108,11 @@ That leaves nothing on your PATH, so there's no install to check afterward.
 
 To put OpenSpec in a project dev shell instead, add the flake as an input and use its default package; [flake.nix](https://github.com/Fission-AI/OpenSpec/blob/main/flake.nix) lists the outputs.
 
+The Nix package ships the Bash, Fish, and Zsh completion scripts at the standard
+locations (`share/bash-completion/completions`, `share/fish/vendor_completions.d`,
+`share/zsh/site-functions`), so they load with the package and there is no need to run
+`openspec completion install`.
+
 ### Check it worked
 
 Whichever method you used, in your terminal:
@@ -118,7 +137,7 @@ When a newer CLI is out, [`openspec update`](../reference/cli.md#openspec-update
 
 
 > [!WARNING]
-> On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
+> On Homebrew, run `brew upgrade openspec`. On Deno, re-run the [Deno install](#deno) with `-f`; it won't overwrite the installed command without it. On Nix, use `nix profile upgrade openspec`.
 
 > [!NOTE]
 > A global npm install belongs to one Node installation. Switch Node versions with nvm and the `openspec` command doesn't come along, so install it again under the new version.
@@ -139,7 +158,7 @@ openspec completion uninstall
 npm uninstall -g @fission-ai/openspec
 ```
 
-On Deno: `deno uninstall --global openspec`. On Nix: `nix profile remove openspec`. Your shell should no longer find `openspec`.
+On Homebrew: `brew uninstall openspec`. On Deno: `deno uninstall --global openspec`. On Nix: `nix profile remove openspec`. Your shell should no longer find `openspec`.
 
 **3. Delete what's left, or keep it.**
 

docs-lab/start/quickstart.md

@@ -1,9 +1,19 @@
 # Quickstart
 
-> Your first change on your existing repo, from idea to archived.
+> Your first change, from idea to archived, in a new or existing project.
 
 Before you start, you need the CLI on your machine ([Installation](installation.md)) and OpenSpec initialized in your project ([Set up your project](setup.md)).
 
+## Start from an empty project
+
+You can start without a chosen stack or a complete architecture. Initialize OpenSpec in your project folder, then ask your agent to explore the options with you. In your AI chat:
+
+```text
+Help me explore a task tracker from scratch. I have not picked a stack. Compare the options and help me choose the first behavior to build.
+```
+
+Decide what the first change needs and leave later architecture choices open. Ask your agent to propose that one change, then follow the steps below. You can revisit the architecture as the project grows.
+
 ## The loop at a glance
 
 Every change moves through the same five steps: you think the idea through with your agent, it drafts a plan, you correct the plan before any code exists, the agent builds from it, and archiving updates your specs with what shipped.
@@ -17,22 +27,22 @@ flowchart LR
     archive -. "next change" .-> explore
 ```
 
-Every prompt below goes in your AI chat, the same place you ask for code. Each invokes an OpenSpec skill by name, the same spelling in every tool. A plain ask works too ("propose a change to add rate limiting"). Some tools add shorter command aliases (`/opsx:propose` in Claude Code, [other tools vary](../reference/supported-tools.md)).
+Every prompt below goes in your AI chat, the same place you ask for code. The examples use plain language so they work across tools. You can also invoke a skill directly; the syntax varies by tool ([supported tools](../reference/supported-tools.md)).
 
 ## Step 1: Explore
 
 Think the idea through with your agent before you ask for a plan. In your AI chat:
 
 ```text
-/openspec-explore how rate limiting should work in this app
+Help me explore how rate limiting should work in this app.
 ```
 
-Explore is a thinking mode. The agent investigates your codebase, asks the questions that matter, sketches options, and challenges assumptions. It writes no code and no files. The output is a sharper idea.
+Explore is a thinking mode. The agent investigates your codebase, asks the questions that matter, sketches options, and challenges assumptions. It never writes code. It writes nothing else unless you ask it to capture what you decided, or say yes when it offers. The output is a sharper idea.
 
 Stay here as long as the problem needs. When the shape feels right, hand it off:
 
 ```text
-/openspec-propose
+Propose the change we just discussed.
 ```
 
 That line starts propose for you, carrying everything you settled. Skip the first prompt in step 2.
@@ -42,7 +52,7 @@ That line starts propose for you, carrying everything you settled. Skip the firs
 Propose turns the idea into a reviewable plan. Coming from explore, it's already running. Starting cold, when the change is clear in your head, ask directly. In your AI chat:
 
 ```text
-/openspec-propose add rate limiting
+Propose a change to add rate limiting.
 ```
 
 The agent asks what it needs to, then writes a change folder:
@@ -75,7 +85,7 @@ To fix something, either works:
 Apply turns the plan into code. Start a fresh chat session, since implementation goes better on a clean context window. In your AI chat:
 
 ```text
-/openspec-apply-change add-rate-limiting
+Apply the add-rate-limiting change.
 ```
 
 The agent reads the change folder, then works through `tasks.md`, checking off each task as it lands.
@@ -91,7 +101,7 @@ Archiving does two things: it updates your main specs with the change's requirem
 When every box in `tasks.md` is checked, in your AI chat:
 
 ```text
-/openspec-archive-change add-rate-limiting
+Archive the add-rate-limiting change.
 ```
 
 Step through what archiving does:
@@ -146,14 +156,24 @@ Step through what archiving does:
           └── 2026-08-08-add-rate-limiting/
 ```
 
-Git is a separate concern. Commit the change folder with the code, and nothing else about your workflow changes. When to archive relative to a PR is a team convention; the [Teams](../guides/teams.md) guide has the tradeoff.
+Git is a separate concern. Commit the change folder with the code, and nothing else about your workflow changes.
+
+### Keep or prune archived changes
+
+`openspec/changes/archive/` keeps the proposal, design, tasks, and delta for each finished change. In the archive flow above, the delta has already updated `openspec/specs/`.
+
+- **Keep the whole change folder** when you want a self-contained record in the current checkout.
+- **Remove an archived change's `specs/` folder** when Git is your spec history. Commit the archive first, then delete `openspec/changes/archive/<change>/specs/`. The proposal, design, and tasks remain in the checkout. `openspec validate --archived` still works because it checks task completion, not applied deltas.
+- **Remove the whole change folder** only when you no longer need its proposal, design, or task history in the checkout. The current specs do not change, but `openspec validate --archived` and searches of the checkout no longer include that change.
+
+> [!WARNING]
+> Keep the archive commit in your repository history if you want Git to retain the deleted files. Squashing the archive and cleanup commits together removes that intermediate snapshot.
+
+OpenSpec does not prune archived changes automatically or provide a retention setting.
 
 ## Going further
 
-- [Concepts](../guides/concepts.md): what the two artifacts are, and how a delta describes a change.
-- [Explore](../guides/explore.md): getting more out of explore mode.
-- [Apply](../guides/apply.md): pacing, context windows, resuming long changes.
-- [Review the plan](../guides/review-the-plan.md): what to look for in specs before you build.
+- [Delta specs](../reference/schemas/spec-driven/index.md#delta-specs-specmd): how to write the behavior changes in a delta spec.
 - [Profiles](../customize/profiles.md): optional workflows beyond the core set (verify before archive, incremental planning).
 
 ## Advanced guides

docs-lab/start/setup.md

@@ -34,6 +34,22 @@ Re-running init is safe:
 - Running init again with a new tool selected adds that tool.
 - The `--tools` flag skips the picker ([CLI reference](../reference/cli.md)).
 
+### Migrate an existing `project.md`
+
+Init does not copy legacy `openspec/project.md` into `config.yaml`. It keeps the file and prints an AI-assisted migration request.
+
+In your AI chat:
+
+```
+Review openspec/project.md and migrate its useful content to openspec/config.yaml.
+Keep context concise: include only project-wide facts needed during artifact creation, apply, and archive.
+Move artifact-specific guidance into rules for the matching artifacts.
+Move guidance for apply or archive into the matching operations entry.
+Leave out generic, outdated, or verbose material. Do not delete project.md.
+```
+
+Review `config.yaml`, then delete `project.md` when ready.
+
 ## What init installs
 
 Running init creates two things in your project:
@@ -41,7 +57,7 @@ Running init creates two things in your project:
 - An `openspec/` folder at the repo root
 - Workflow files (skills and commands) added to your AI tool's folder (`.agents/`, `.claude/`, etc.)
 
-Commit all of it like the rest of your source ([FAQ](../help/faq.md) covers why). Init changes nothing else in your repo (if it finds leftovers from an older OpenSpec version, it asks before cleaning them up).
+Commit all of it like the rest of your source. Init changes nothing else in your repo (if it finds leftovers from an older OpenSpec version, it asks before cleaning them up).
 
 ### The `openspec/` folder
 
@@ -55,7 +71,7 @@ openspec/
     └── archive/    completed changes move here
 ```
 
-[Concepts](../guides/concepts.md) explains both artifacts; [Project config](../customize/project-config.md) covers `config.yaml`.
+[Project config](../customize/project-config.md) covers `config.yaml`.
 
 ### The workflow files (skills and commands)
 
@@ -112,4 +128,26 @@ Config changes:
 
 Answering yes applies it to the current project on the spot. Other projects pick it up on their next `openspec update`. The setting is global, per machine.
 
+#### Claude Code doesn't show the workflows
+
+Claude Code loads OpenSpec workflows from one or both of these project paths, based on your delivery setting:
+
+- **Skills**: `.claude/skills/openspec-*/SKILL.md`
+- **Commands**: `.claude/commands/opsx/<id>.md`
+
+If the files are missing, refresh the project. In your terminal:
+
+```bash
+openspec update
+```
+
+If the command files exist but `/opsx:` shows no OpenSpec commands, update Claude Code and restart it. If commands still don't load, enable skills too. In your terminal:
+
+```bash
+openspec config set delivery both
+openspec update
+```
+
+Restart Claude Code, then run `/openspec-propose` in its chat. If only some workflows are missing, [change your profile](../customize/profiles.md#expanding-the-set-optional-workflows).
+
 Setup is done. The [Quickstart](quickstart.md) takes your first change from here.

docs/README.md

@@ -11,7 +11,7 @@ If you read nothing else, read these two pages:
 
 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.
+> **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 code gets written. The [Explore First](explore.md) guide makes the case.
 
 ## Pick your path
 

docs/agent-contract.md

@@ -47,16 +47,18 @@ deliberately remains the compatibility bare array documented in §4.13:
 ## 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" }`.
+`{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress", "nested"?: ["<area>/<name>", ...] } ], "warnings"?: [ { "code", "name", "nested", "message" } ], "root": RootOutput }` — note the per-change `status` is a string enum here. `--specs`: `{ "specs": [ { "id", "requirementCount" } ], "root" }`.
+
+`warnings` (omitted when empty) reports directories under `changes/` that are not changes. Today the only code is `nested_change_directory`: a namespace folder wrapping change directories, which OpenSpec cannot address because a change is always a directory directly under `changes/`. The same entry carries `nested` on the listed change, whose `status` is then meaningless. Do not treat such an entry as a change; report the message and leave the directories alone.
 
 ### 4.2 `show <item> --json`
-Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }`.
+Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }`. A requirement, in a spec or in a change delta's `requirement`/`requirements`, is `{ "name", "text", "scenarios": [ { "name", "rawText" } ] }`. A requirement `name` is its header without `Requirement:` and without a closing `#` run, the exact name archive matches MODIFIED/REMOVED/RENAMED entries against. A scenario `name` is its level-4 header without `Scenario:` and without a closing `#` run, the name the MODIFIED scenario-loss check compares.
 
 ### 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" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }`. `isPlanningComplete` means every non-skipped planning artifact exists; skipped artifacts count as satisfied without being created. It does not mean implementation tasks are complete. `isComplete` is retained as a compatibility alias with the same value. Each artifact's `requires` is its direct dependency ids (present for every status, so the transitive required set is computable even when the artifact is `done`); `missingDeps` appears only when `blocked`. The `artifacts` array is in dependency order, with the schema's `artifacts:` declaration order breaking ties between artifacts that become ready at the same time (never alphabetical), so the first `ready` entry is the artifact to write next; `missingDeps` uses that same order. `"skipped"` marks an artifact whose `generates` path is under `specs/` in a change whose `.openspec.yaml` declares `skip_specs: true`; it satisfies dependencies but must not be created. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
+`{ "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" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }`. For a store-selected root, `allowedEditRoots` is `[<declaring project>, <store>]` when the nearest project on the current path is a config-only root whose `store:` pointer names that store, and `[<store>]` otherwise (including a global `defaultStore`), with a constraint telling the agent to ask which repository to edit. OpenSpec does not route a store's tasks to repos, so the declaring project is the current one, not every repo the change touches. `isPlanningComplete` means every non-skipped planning artifact exists; skipped artifacts count as satisfied without being created. It does not mean implementation tasks are complete. `isComplete` is retained as a compatibility alias with the same value. Each artifact's `requires` is its direct dependency ids (present for every status, so the transitive required set is computable even when the artifact is `done`); `missingDeps` appears only when `blocked`. The `artifacts` array is in dependency order, with the schema's `artifacts:` declaration order breaking ties between artifacts that become ready at the same time (never alphabetical), so the first `ready` entry is the artifact to write next; `missingDeps` uses that same order. `"skipped"` marks an artifact whose `generates` path is under `specs/` in a change whose `.openspec.yaml` declares `skip_specs: true`; it satisfies dependencies but must not be created. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
 
 `--all` (batch, mutually exclusive with `--change` — combining them is an error with the `{ "changes": [], "root": null, "status": [d] }` null-shape): `{ "changes": [ <per-change status object, no per-change root>, ... ], "root" }`, sorted by change name. A change that fails to load contributes `{ "changeName", "status": [d] }` in place; the sweep continues, preserves the complete envelope, and exits 1 in both text and JSON modes. An invalid `--schema` fails the whole invocation with the null-shape, even when no changes exist.
 
@@ -66,7 +68,7 @@ Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id
 `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"?, "context"?, "operationGuidance"?, "root" }`. Both optional fields are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
+`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "missingPrerequisites"?, "warnings"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }`. `missingArtifacts` is what apply blocks on (the schema's `apply.requires`); `missingPrerequisites` is everything still to build before apply can run, in build order - the transitive closure of those requires, so it can be the longer list. `warnings` lists non-blocking problems with the change itself - today, a change that is ready to implement with no delta specs and no `skip_specs: true`, the state `openspec validate` rejects. Both optional root fields (`context`, `operationGuidance`) are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
 
 ### 4.7 `instructions archive --json`
 `{ "changeName", "context"?, "operationGuidance"?, "root" }`. Requires a valid `--change` in the resolved repo/store root and uses the same required-context/advisory-guidance semantics as apply. This is a read-only runtime-input surface: it does not return the static archive workflow, inspect or merge delta specs, write main specs, or move the change.
@@ -77,6 +79,10 @@ Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Fai
 ### 4.9 `archive <name> --json`
 Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. `specsUpdated` is true only when at least one spec file was written or retired (a capability whose last requirement the change removed has its spec deleted, which requires `retire_capabilities: true` in the change's `.openspec.yaml`; every retirement is named in `warnings`, with a pasteable Git recovery command only when the spec lived in the caller's checkout); an already-synced change archives with all-zero totals and the skips listed in `warnings`. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
 
+- **`archive: null`**: the command failed. This is not a guarantee that files are unchanged.
+- **`archive_retirement_cleanup_failed`**: the change was archived, but retirement backup verification or cleanup failed. A listed backup path may have changed or disappeared. The message can also report a staged source left by a failed fallback-copy cleanup. Inspect the current archive and all reported recovery paths before cleanup. Preserve any needed content. Retrying archive does not clean up these paths.
+- **`archive_error`**: the fallback diagnostic does not identify whether files changed. Inspect the change, archive, and affected specs before retrying.
+
 ### 4.10 `doctor --json`
 `{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }`. `drift` (present only for a git-backed store checkout that has an upstream tracking ref) is ahead/behind counts against the last-fetched upstream, not the live remote. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
 
@@ -110,7 +116,7 @@ setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, regis
 `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_root_pointer_declared`, `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_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_root_pointer_declared`, `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_remove_contains_registered_store`, `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), `store_checkout_drift` (info, doctor).
@@ -122,7 +128,7 @@ setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, regis
 `relationship_registry_unreadable`, `root_pointer_ignored`, `root_pointer_invalid`, `pointer_declarations_inert`.
 
 ### Archive (JSON mode)
-`archive_change_name_required`, `archive_change_not_found`, `archive_change_symlink`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_error`.
+`archive_change_name_required`, `archive_change_not_found`, `archive_change_symlink`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_retirement_cleanup_failed`, `archive_error`.
 
 ### Context writes
 `context_file_exists`, `context_output_dir_missing`.

docs/cli.md

@@ -13,7 +13,7 @@ The OpenSpec CLI (`openspec`) provides terminal commands for project setup, vali
 | **Personal worksets** | `workset create`, `workset list`, `workset open`, `workset remove` | Keep and open personal, local working views in your tool |
 | **Browsing** | `list`, `view`, `show` | Explore changes and specs |
 | **Validation** | `validate` | Check changes and specs for issues |
-| **Lifecycle** | `sync`, `archive` | Fold delta specs into the main specs, and finalize completed changes |
+| **Lifecycle** | `archive` | Finalize completed changes |
 | **Workflow** | `new change`, `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
 | **Schemas** | `schema init`, `schema fork`, `schema validate`, `schema which` | Create and manage custom workflows |
 | **Config** | `config` | View and modify settings |
@@ -443,7 +443,6 @@ openspec list [options]
 | `--specs` | List specs instead of changes |
 | `--changes` | List changes (default) |
 | `--sort <order>` | Sort by `recent` (default) or `name` |
-| `--status <state>` | Only list changes in this lifecycle state: `proposed` or `shipped`. A change whose `.openspec.yaml` has no `status` counts as `proposed` |
 | `--json` | Output as JSON |
 
 **Examples:**
@@ -627,107 +626,6 @@ Validating add-dark-mode...
 
 ## Lifecycle Commands
 
-### `openspec sync`
-
-Fold a change's delta specs into the main specs, without archiving the change.
-
-```
-openspec sync [change-name] [options]
-```
-
-`archive` does two things at once: it folds a change's deltas into `openspec/specs/`
-and it moves the change folder. `sync` does only the first, so the specs can be
-brought up to date while the change is still open for review — and so CI can check
-that they are.
-
-**Arguments:**
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Change to sync. Omitted, `sync` acts on every change that declares `status: shipped` |
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--check` | Report shipped changes whose deltas are not in the main specs and exit 1. Writes nothing |
-| `--ship` | Fold the named change, then set `status: shipped` on it — both land in one set of file changes for you to commit. If the fold fails, the field is not set |
-| `-y, --yes` | Sync even when the change still has incomplete tasks |
-| `--no-validate` | Skip validation (not recommended) |
-| `--json` | Structured output for hooks and CI |
-| `--store <id>` | Use a registered store as the OpenSpec root |
-
-**The lifecycle field.** A change's `.openspec.yaml` may declare where it sits:
-
-```yaml
-schema: spec-driven
-status: shipped   # or: proposed
-```
-
-The field is optional and absent by default. A change with no `status` is
-`proposed`, which is what every change under `changes/` has always meant, so a
-project that never opts in is unaffected. Nothing writes the field on its own —
-not `openspec new change`, not `archive`.
-
-If the fold fails — validation, incomplete tasks, a retirement, a write error —
-the field is not set. `--ship` writes `status: shipped` only after the specs are
-correct, so a failed run never leaves a change claiming to be shipped with its
-deltas absent.
-
-**The CI gate.** `openspec sync --check` asserts one property: *a change that
-claims to be shipped has its deltas in `specs/`*. A proposed change passes for
-free, so the check is green as its resting state and red only on a real mistake —
-unlike "is everything archived?", which is red for the entire life of every open
-PR. It reads only files on disk, so a pre-commit hook, a pre-push hook and CI run
-the same command and reach the same verdict.
-
-```bash
-# CI, pre-commit, pre-push — same command
-openspec sync --check
-```
-
-**Examples:**
-
-```bash
-# Fold one change's deltas now; the change stays where it is
-openspec sync add-rate-limit
-
-# Mark it shipped and fold it, so both land in one commit when you make it
-openspec sync add-rate-limit --ship
-
-# Fold every change that declares status: shipped
-openspec sync
-
-# Gate: exits 1 if any shipped change has unfolded deltas
-openspec sync --check
-
-# Which changes have claimed to be shipped but aren't archived yet
-openspec list --status shipped
-```
-
-**What it does:**
-
-1. Validates the change's delta specs (unless `--no-validate`)
-2. Refuses a change with incomplete tasks, unless `--yes` — folding a change
-   nothing implements yet writes requirements into `specs/` that aren't true
-3. Validates every rebuilt spec before writing any of them, so a late failure
-   leaves the whole tree unchanged
-4. Writes the updated main specs. Nothing moves; nothing is deleted
-
-**What it deliberately does not do:**
-
-- **It never deletes a spec.** When a change's `REMOVED` entries take a
-  capability's last requirement, retiring that capability deletes its `spec.md`.
-  That stays with `openspec archive`, behind the `retire_capabilities` marker.
-  `sync` reports the case and points you there.
-- **It never checks archived changes.** Archived deltas are history, and later
-  changes supersede them. `--check` looks only at active changes that declare
-  `status: shipped` — a set that drains itself as those changes archive.
-
-**Syncing early does not change archiving.** Re-applying a delta that is already
-in the main specs is a no-op, so `openspec archive` afterwards reports
-`Specs already in sync` and moves the folder exactly as it always did.
-
 ### `openspec archive`
 
 Archive a completed change and merge delta specs into main specs.

docs/commands.md

@@ -78,7 +78,7 @@ AI:  Created openspec/changes/add-dark-mode/
 
 ### `/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.
+> **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 code gets written. 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.
 
@@ -97,6 +97,7 @@ Think through ideas, investigate problems, and clarify requirements before commi
 - Investigates the codebase to answer questions
 - Compares options and approaches
 - Creates visual diagrams to clarify thinking
+- Captures the exploration when you ask, or when you say yes to its offer: scaffolds a change with `openspec new change` and writes the planning artifacts you name, or updates an existing change's artifacts
 - Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
 
 **Example:**
@@ -119,14 +120,20 @@ AI:  Let me investigate your current auth setup...
 
      Your API already has CORS configured. Which direction interests you?
 
-You: Let's go with JWT. Can we start a change for that?
+You: Let's go with JWT.
 
-AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
+AI:  That's a decision worth keeping. Want me to start a change called
+     add-jwt-auth? Just the change folder, nothing else yet.
+
+You: Yes.
+
+AI:  Started openspec/changes/add-jwt-auth/. Say the word and I'll
+     write the proposal, specs, and tasks from what we just worked out.
 ```
 
 **Tips:**
 - Use when requirements are unclear or you need to investigate
-- No artifacts are created during exploration
+- It never writes code, and writes nothing else unless you ask, or say yes when it offers
 - Good for comparing multiple approaches before deciding
 - Can read files and search the codebase
 
@@ -345,7 +352,13 @@ Revise a change's existing planning artifacts and keep them coherent with one an
 - Applies your requested revision, or reviews the artifacts for contradictions if you didn't name one
 - Reconciles the other existing artifacts in any direction (a design edit may ripple back to the proposal)
 - Confirms every edit with you before writing, one artifact at a time
-- Ends by recommending the next step: `/opsx:continue` (artifacts missing), `/opsx:apply` (carry a revised plan into code), or `/opsx:archive` (all done)
+- Ends by recommending the next step: `/opsx:continue` (unstarted artifacts), `/opsx:apply` (carry a revised plan into code), or `/opsx:archive` (all done)
+
+**Missing files:**
+
+- For a glob artifact such as `specs/**/*.md` with at least one existing file, update can propose a missing companion file. It uses the schema's instructions and asks you to confirm the concrete path before creating it.
+- Artifacts with no files yet remain with `/opsx:continue`. Intentionally skipped artifacts stay untouched.
+- New files must stay inside the change directory. If a file appears at the confirmed path before creation, update stops instead of overwriting it.
 
 **Example:**
 
@@ -366,7 +379,7 @@ AI:  Reading add-dark-mode artifacts...
 
 **Tips:**
 
-- It won't create missing artifacts - that's `/opsx:continue`
+- It won't start an artifact with no existing files. Enable `/opsx:continue` for that, or use `openspec status` and `openspec instructions` if that optional workflow isn't installed.
 - If the change was already implemented, follow up with `/opsx:apply` so the code matches the revised plan
 - If your revision changes the *intent* of the change, start fresh with a new change instead (see [When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh))
 
@@ -444,8 +457,6 @@ AI:  Verifying add-dark-mode...
 
 **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.
 
-> Not the same as the CLI's `openspec sync`. This one is the agent doing the merge in your session. `openspec sync` is a deterministic terminal command that does the same fold without a model, and carries the `--check` gate for CI — see [CLI](cli.md#openspec-sync).
-
 **Syntax:**
 ```
 /opsx:sync [change-name]

docs/community.md

@@ -6,7 +6,9 @@ Listed projects are maintained independently. Inclusion does not imply official
 
 ## Projects and resources
 
-- **[OpenSpec UI](https://github.com/VeryComplexAndLongName/OpenSpec-UI)**: A standalone web dashboard and VS Code extension for browsing OpenSpec changes, archives, specs, and tasks.
+- **[OpenSpec Workbench](https://github.com/VeryComplexAndLongName/OpenSpec-UI)**: Running and supervising agents on OpenSpec changes.
+- **[MySpec](https://myspec.dev)**: Cloud beta (account required) that conducts guided spec interviews and exports four-file bundles or OpenSpec-compatible changes. The service sends submitted content to third-party AI providers and is not designed for sensitive data.
+- **[openspec-guard](https://github.com/guillaume-flambard/spec-guard)**: CLI and GitHub Action that reports which OpenSpec scenarios are covered by a Vitest or Jest test, without running the tests.
 
 ## Add your project
 

docs/concepts.md

@@ -341,6 +341,8 @@ Tasks are the **implementation checklist** — concrete steps with checkboxes.
 - Group related tasks under headings
 - Use hierarchical numbering (1.1, 1.2, etc.)
 - Keep tasks small enough to complete in one session
+- State how each task is verified (a test, command, or observable result)
+- Land the tests and documentation each group's work calls for inside that group, not in a final catch-up group
 - Check tasks off as you complete them
 
 ## Delta Specs

docs/examples.md

@@ -68,7 +68,7 @@ Tip: for a fix, a good scenario is the regression test in prose. "GIVEN a logged
 
 **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.
+Start with `/opsx:explore`. It's a thinking partner with no structure. It never writes code, and writes nothing else unless you ask it to capture what you decided, or say yes when it offers. It reads your codebase and helps you decide.
 
 ```text
 You: /opsx:explore

docs/explore.md

@@ -1,6 +1,6 @@
 # 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`.
+**`/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 line of code is written. 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.**
 
@@ -27,14 +27,16 @@ Explore is a **conversation**, not a generator.
 - 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.
+- Capture the exploration when you ask, or when you accept its offer: it scaffolds the change with `openspec new change` and writes the planning artifacts you named, or updates an existing change's artifacts.
 - 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.
+- Write or modify code. Explore never writes code, on any path, capture included.
+- Design or edit your schemas or templates. Shaping those is a change, not thinking.
+- Start a change or write an artifact on its own. It writes nothing unless you ask, or say yes when it offers, and then only what you agreed to, plus the setup files starting a change needs (see below).
+- Push you toward capturing. It offers when the thinking crystallizes; you decide.
 
-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.
+That's the point. Exploring costs you nothing and commits you to nothing until you say so. You can explore three dead ends, learn something from each, and only then propose the path that survived.
 
 ## It's already installed
 
@@ -95,6 +97,10 @@ explore  ──►  propose  ──►  apply  ──►  archive
 
 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.
 
+You can also ask explore to capture the change itself, without leaving the conversation: "start a change for this" scaffolds the folder, and "write the proposal too" writes exactly the artifacts you named. Scaffolding also lays down the change's own metadata, and fills in anything your project is missing at the top level (`openspec/specs/`, `openspec/changes/archive/`, a `config.yaml`).
+
+That's the same destination as handing off, with one difference: propose writes the whole set your schema requires to reach implementation, while capture writes only the artifacts you named.
+
 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
@@ -107,7 +113,7 @@ If you use the expanded command set, explore can hand off to `/opsx:new` instead
 
 ## 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 you gain:** explore catches wrong turns at the cheapest possible moment, before you've committed to anything. 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.
 

docs/faq.md

@@ -50,7 +50,7 @@ Both are files OpenSpec writes so your assistant can run the workflow. Skills (`
 
 ### 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).
+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 code gets written. 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?
 

docs/getting-started.md

@@ -26,7 +26,7 @@ Two terminal steps to set up, then you live in chat. The rest of this guide unpa
 
 **Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created.
 
-> **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).
+> **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 code gets written. 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
 

docs/glossary.md

@@ -38,9 +38,7 @@ Terms are grouped by topic, then alphabetized within each group.
 
 **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). Available on its own two ways: `/opsx:sync`, where the agent does the merge ([Commands](commands.md#opsxsync)), and `openspec sync`, the deterministic CLI command ([CLI](cli.md#openspec-sync)).
-
-**Shipped / proposed.** A change may declare its lifecycle state as `status: proposed | shipped` in its `.openspec.yaml`. The field is optional and absent by default; no `status` means `proposed`. `openspec sync --check` gates on it — a change that claims to be shipped must have its deltas in the main specs — which makes the specs enforceable in CI without a check that is red for the whole life of every PR. See [OpenSpec on a Team](team-workflow.md#enforcing-it-in-ci).
+**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
 
@@ -48,7 +46,7 @@ Terms are grouped by topic, then alphabetized within each group.
 
 **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).
+**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan. It never writes code, and writes nothing else unless you ask it to capture the exploration as a change, or say yes when it offers. 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).
 

docs/opsx.md

@@ -213,7 +213,9 @@ Works through tasks, checking them off as you go. If you're juggling multiple ch
 ```
 /opsx:update add-dark-mode - we're storing the theme in a cookie now
 ```
-Revises the change's existing planning artifacts and keeps them coherent - in any direction (a design edit may ripple back to the proposal). Planning artifacts only: it never edits code, and it never creates missing artifacts (that's `/opsx:continue`). Every edit is confirmed with you first. If the change was already implemented, it recommends `/opsx:apply` so the code catches up with the revised plan. If your revision changes the change's *intent*, start fresh instead - see [When to Update vs. Start Fresh](#when-to-update-vs-start-fresh).
+Revises the change's existing planning artifacts and keeps them coherent in any direction (a design edit may ripple back to the proposal). It never edits code. Every edit is confirmed with you first. See [the update reference](commands.md#opsxupdate) for how it handles missing files without starting a new artifact.
+
+If the change was already implemented, it recommends `/opsx:apply` so the code catches up with the revised plan. If your revision changes the change's *intent*, start fresh instead. See [When to Update vs. Start Fresh](#when-to-update-vs-start-fresh).
 
 ### Sync delta specs
 ```text

docs/overview.md

@@ -56,7 +56,7 @@ In the default setup, your day looks like this. Optionally think it through firs
 /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).
+**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 code gets written. 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.
 

docs/supported-tools.md

@@ -86,7 +86,7 @@ to read the hint.
 | Hermes Agent (`hermes`) | `.hermes/skills/openspec-*/SKILL.md`\*\*\* | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | 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` |
+| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilo/command/opsx-<id>.md` |
 | Kimi Code (`kimi`) | `.kimi-code/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` |

docs/team-workflow.md

@@ -55,38 +55,6 @@ Archiving folds a change's deltas into your main `openspec/specs/` and moves the
 
 Pick one and be consistent. Either way, `/opsx:archive` checks that tasks are complete and offers to sync first, so nothing merges half-finished by accident.
 
-## Enforcing it in CI
-
-The obvious CI check — "nothing is left unarchived" — doesn't work, because it's red for the whole life of every PR. An open change sits in `changes/`, unarchived, precisely because it isn't finished. A gate that is red as its resting state is one everyone learns to ignore.
-
-`openspec sync --check` is the check that works. It asks a different question: **does anything that claims to be shipped still have deltas missing from `specs/`?** A change that hasn't made that claim passes for free, so green is the resting state and red means a real mistake.
-
-```yaml
-# .github/workflows/specs.yml
-- run: npx openspec sync --check
-```
-
-The claim is one line in the change's `.openspec.yaml`:
-
-```yaml
-schema: spec-driven
-status: shipped
-```
-
-The everyday shape of it:
-
-1. Open the PR. The change is `proposed` (the default — nothing to write). The gate is green.
-2. When the work is done and reviewed, mark it shipped and fold its deltas in one step:
-   ```bash
-   openspec sync add-rate-limit --ship
-   ```
-   That sets `status: shipped` and writes the deltas into `specs/` in one command, so both land in the same set of file changes for you to commit together. OpenSpec never runs git itself — commit the result as usual.
-3. Merge. Archive whenever you like afterwards — re-applying a delta that's already folded is a no-op, so `openspec archive` behaves exactly as it always did.
-
-The check is a pure function of the files on disk, so the same command works as a pre-commit hook, a pre-push hook, and the CI gate, and all three agree.
-
-`openspec list --status shipped` shows which changes have made the claim but aren't archived yet.
-
 ## Two people, parallel changes
 
 Because changes are separate folders, they don't collide:

docs/workflows.md

@@ -140,7 +140,7 @@ 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).
+Explore never writes code, and writes nothing else unless you ask, or say yes when it offers. 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)
 
@@ -493,7 +493,7 @@ AI:  Let me investigate your current setup and options...
      Your current stack suggests #1 or #2. What's your scale?
 ```
 
-Exploration clarifies thinking before you create artifacts.
+Exploration clarifies thinking before any code gets written.
 
 ### Verify Before Archiving
 

flake.nix

@@ -15,71 +15,98 @@
         "aarch64-darwin"
       ];
 
-      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
+      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems f;
+
+      pkgsFor =
+        system:
+        import nixpkgs {
+          inherit system;
+          overlays = [ self.overlays.default ];
+        };
     in
     {
+      overlays.default = final: _prev: {
+        openspec = final.stdenv.mkDerivation (finalAttrs: {
+          pname = "openspec";
+          version = (builtins.fromJSON (builtins.readFile ./package.json)).version;
+
+          src = final.lib.fileset.toSource {
+            root = ./.;
+            fileset = final.lib.fileset.unions [
+              ./src
+              ./bin
+              ./schemas
+              ./scripts
+              ./test
+              ./package.json
+              ./pnpm-lock.yaml
+              ./pnpm-workspace.yaml
+              ./tsconfig.json
+              ./build.js
+              ./vitest.config.ts
+              ./vitest.setup.ts
+              ./eslint.config.js
+            ];
+          };
+
+          pnpmDeps = final.fetchPnpmDeps {
+            inherit (finalAttrs) pname version src;
+            pnpm = final.pnpm_10;
+            fetcherVersion = 3;
+            hash = "sha256-gPGdwmj4oLb/j3D/BGNCaI0hFfrHKCjH4I71UYzmhfk=";
+          };
+
+          nativeBuildInputs = with final; [
+            installShellFiles
+            nodejs_22
+            npmHooks.npmInstallHook
+            pnpmConfigHook
+            pnpm_10
+          ];
+
+          buildPhase = ''
+            runHook preBuild
+
+            pnpm run build
+
+            runHook postBuild
+          '';
+
+          dontNpmPrune = true;
+
+          # `openspec completion generate` renders a static command registry, so it
+          # needs no project and no network. Opting out of telemetry also disables
+          # the update check, keeping the build offline.
+          postInstall = final.lib.optionalString (final.stdenv.buildPlatform.canExecute final.stdenv.hostPlatform) ''
+            export OPENSPEC_TELEMETRY=0
+            completions=$(mktemp -d)
+            for shell in bash fish zsh; do
+              $out/bin/openspec completion generate "$shell" > "$completions/openspec.$shell"
+            done
+            installShellCompletion --cmd openspec \
+              --bash "$completions/openspec.bash" \
+              --fish "$completions/openspec.fish" \
+              --zsh "$completions/openspec.zsh"
+          '';
+
+          meta = with final.lib; {
+            description = "AI-native system for spec-driven development";
+            homepage = "https://github.com/Fission-AI/OpenSpec";
+            license = licenses.mit;
+            maintainers = [ ];
+            mainProgram = "openspec";
+          };
+        });
+      };
+
       packages = forAllSystems (
         system:
         let
-          pkgs = nixpkgs.legacyPackages.${system};
-          inherit (pkgs) lib;
+          pkgs = pkgsFor system;
         in
         {
-          default = pkgs.stdenv.mkDerivation (finalAttrs: {
-            pname = "openspec";
-            version = (builtins.fromJSON (builtins.readFile ./package.json)).version;
-
-            src = lib.fileset.toSource {
-              root = ./.;
-              fileset = lib.fileset.unions [
-                ./src
-                ./bin
-                ./schemas
-                ./scripts
-                ./test
-                ./package.json
-                ./pnpm-lock.yaml
-                ./pnpm-workspace.yaml
-                ./tsconfig.json
-                ./build.js
-                ./vitest.config.ts
-                ./vitest.setup.ts
-                ./eslint.config.js
-              ];
-            };
-
-            pnpmDeps = pkgs.fetchPnpmDeps {
-              inherit (finalAttrs) pname version src;
-              pnpm = pkgs.pnpm_10;
-              fetcherVersion = 3;
-              hash = "sha256-SNPeEUa+amkZYRO5tHeUwDBT4betXYPKnfZiEyhN7fE=";
-            };
-
-            nativeBuildInputs = with pkgs; [
-              nodejs_22
-              npmHooks.npmInstallHook
-              pnpmConfigHook
-              pnpm_10
-            ];
-
-            buildPhase = ''
-              runHook preBuild
-
-              pnpm run build
-
-              runHook postBuild
-            '';
-
-            dontNpmPrune = true;
-
-            meta = with pkgs.lib; {
-              description = "AI-native system for spec-driven development";
-              homepage = "https://github.com/Fission-AI/OpenSpec";
-              license = licenses.mit;
-              maintainers = [ ];
-              mainProgram = "openspec";
-            };
-          });
+          default = pkgs.openspec;
+          inherit (pkgs) openspec;
         }
       );
 

openspec/changes/add-amp-support/.openspec.yaml

@@ -1,2 +1,2 @@
 schema: spec-driven
-created: 2026-09-07
+created: 2025-12-29

openspec/changes/add-amp-support/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+Amp reads project skills from `.agents/skills/`, but OpenSpec does not list Amp in its tool picker or accept `amp` through `--tools`. Amp users can select the universal `.agents` target, but only if they already know how Amp discovers skills.
+
+## What Changes
+
+- Add Amp as a supported skills-only tool with `amp` as its tool id.
+- Generate Amp's OpenSpec skills through the existing shared `.agents/skills/` pipeline.
+- Detect Amp projects from `.amp/` and recognize Amp-owned OpenSpec skill trees during update.
+- Document Amp's paths and invocation syntax in the docs-lab supported-tools reference.
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define Amp's shared Agent Skills path and skills-only behavior.
+
+## Impact
+
+- `src/core/config.ts`: add the Amp tool metadata.
+- `test/core/init.test.ts`, `test/core/update.test.ts`, and `test/core/available-tools.test.ts`: cover generation, refresh, and detection.
+- `docs-lab/reference/supported-tools.md`: add Amp to the support matrix and shared-folder notes.
+
+## Non-Goals
+
+- Adding an Amp command adapter. Amp's supported project extension surface is Agent Skills.
+- Adding a second Amp-specific skill generator or template set.

openspec/changes/add-amp-support/specs/ai-tool-paths/spec.md

@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Amp skills integration
+
+OpenSpec SHALL expose Amp as a supported skills-only tool that uses Amp's project Agent Skills directory.
+
+#### Scenario: Selecting Amp
+
+- **WHEN** the user selects Amp in `openspec init` or passes `--tools amp`
+- **THEN** OpenSpec SHALL generate the active profile's skills under `.agents/skills/`
+- **AND** the generated skills SHALL use `/openspec-<skill>` references
+- **AND** OpenSpec SHALL NOT generate command files for Amp
+
+#### Scenario: Detecting an Amp project
+
+- **WHEN** a project contains an `.amp/` directory
+- **THEN** OpenSpec SHALL detect Amp as an available tool
+
+#### Scenario: Updating an Amp-owned skill tree
+
+- **GIVEN** `.agents/skills/.openspec-target` names `amp`
+- **WHEN** `openspec update` runs
+- **THEN** OpenSpec SHALL refresh the Amp skill tree through the shared skill generator
+
+#### Scenario: Sharing the Agent Skills directory
+
+- **WHEN** Amp is selected with another tool that writes `.agents/skills/`
+- **THEN** OpenSpec SHALL write one compatible skill tree rather than letting the tools overwrite each other

openspec/changes/add-amp-support/tasks.md

@@ -0,0 +1,20 @@
+## 1. Tool support
+
+- [x] 1.1 Add Amp to `AI_TOOLS` as a skills-only `.agents` target.
+- [x] 1.2 Detect Amp projects from `.amp/` and preserve shared-root ownership.
+
+## 2. Documentation
+
+- [x] 2.1 Add Amp to the docs-lab supported-tools matrix.
+- [x] 2.2 Document Amp's skills-only and shared-folder behavior.
+
+## 3. Tests
+
+- [x] 3.1 Cover Amp detection from `.amp/` and `.openspec-target`.
+- [x] 3.2 Cover init generation, Agent Skills frontmatter, invocation syntax, and command skipping.
+- [x] 3.3 Cover update of an Amp-owned shared skill tree.
+
+## 4. Verification
+
+- [x] 4.1 Validate `add-amp-support` in strict mode.
+- [x] 4.2 Run targeted tests, lint, build, and the full test suite.

openspec/changes/add-standalone-spec-sync/proposal.md

@@ -1,74 +0,0 @@
-# Let a change's specs be folded before it is archived
-
-## Why
-
-`archive` does two separable jobs in one command. It folds a change's deltas into
-`openspec/specs/`, and it declares the change finished by moving its directory.
-Welding them means the fold can only happen at the moment the move happens, which
-on a team that reviews before merging is after the pull request closes.
-
-So a team that wants CI to assert "the specs describe what shipped" has nothing to
-assert during review. The only property expressible today is "nothing is left
-unarchived", and that is violated by design for the entire life of every open PR:
-the change sits in `changes/`, unarchived, precisely because it is not finished.
-A gate that is red as its resting state is one everyone learns to ignore, and it
-masks the real failures underneath (#1683).
-
-The fix is to make the check conditional on the change's own claim — not "is
-everything archived?" but "does anything claiming to be shipped still have deltas
-missing from the specs?" A proposed change passes for free, so green is the
-resting state and red means a real mistake.
-
-## What Changes
-
-- **`openspec sync [change]`** folds delta specs into the main specs without
-  archiving. The merge engine already supports this: re-applying a folded delta
-  is a no-op it names the "early-sync pattern", so `archive` afterwards behaves
-  exactly as it always did.
-- **`openspec sync --check`** asserts `shipped ⇒ folded` over the working tree and
-  exits 1 with the offending changes named. A pure function of files on disk, so
-  a pre-commit hook, a pre-push hook and CI run one command and agree.
-- **`status: proposed | shipped`** becomes an optional field in a change's
-  `.openspec.yaml`. Absent means `proposed`, which is what a change under
-  `changes/` has always meant. Nothing writes it: not `new change`, not `archive`.
-- **`openspec sync <change> --ship`** sets the field and folds in one working-tree
-  diff, so no intermediate commit claims a change is shipped while the specs say
-  otherwise.
-- **`openspec list --status <state>`** filters by the field, and renders a
-  lifecycle column only when some change in the root declares one.
-
-Two deliberate limits, both to keep this additive rather than a second lifecycle:
-
-- **Sync never deletes a spec.** Retiring a capability is the one irreversible
-  operation in the system; it stays with `archive`, behind the
-  `retire_capabilities` marker and its rollback-safe deletion. Sync reports the
-  case and names archive.
-- **Sync never examines archived changes.** Their deltas are history and later
-  changes supersede them; re-applying a months-old delta over everything that
-  came after is a merge conflict, not a drift check. The checked set is the
-  active changes declaring `shipped`, which drains itself as they archive.
-
-"Folded" is decided by running the merge builder and seeing that it applied zero
-operations — the same predicate `archive` uses to decide it has nothing to write.
-Not a byte-comparison of the rebuilt output: the rebuild normalizes blank lines,
-so a hand-formatted main spec would compare unequal while being perfectly in
-sync. Sharing archive's own predicate is also what stops the checker and the doer
-from drifting apart (#1112).
-
-## Impact
-
-- Affected specs: `cli-sync` (ADDED), `cli-list` (MODIFIED: filtering)
-- Affected code: `src/core/sync.ts` (new), `src/core/list.ts`,
-  `src/utils/change-metadata.ts`, `src/core/change-metadata/schema.ts`,
-  `src/cli/index.ts`, `src/core/completions/command-registry.ts`,
-  `src/core/archive.ts` (two helpers exported, no behavior change)
-- Affected docs: `docs/cli.md`, `docs/team-workflow.md`,
-  `docs-lab/reference/cli.md`
-
-Credit: the design is Matan Bendix Shenhav's, from #1683 and his implementation
-#1684. His: the diagnosis, `shipped ⇒ folded` as a tree predicate (V), the
-checker-versus-doer argument (IV), the standalone idempotent `sync` (III), status
-as data (I and II), and shipping in one working-tree diff (VI). This change takes
-a smaller, additive subset — no mode, no layout change, no migration — and
-decides folded-ness by archive's zero-operations predicate rather than his
-byte-identical regeneration.

openspec/changes/add-standalone-spec-sync/specs/cli-list/spec.md

@@ -1,29 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Lifecycle Status Filtering
-The command SHALL be able to filter changes by their declared lifecycle state, and
-SHALL surface that state without changing the output of a project that has never
-declared one.
-
-#### Scenario: Filtering by state
-- **WHEN** `openspec list --status shipped` is executed
-- **THEN** only changes declaring `status: shipped` SHALL be listed
-- **AND** `--status proposed` SHALL list every change that declares `proposed` or
-  declares no status at all
-
-#### Scenario: An unknown state is rejected
-- **WHEN** `--status` is given a value other than `proposed` or `shipped`
-- **THEN** the command SHALL exit 1 naming the accepted values
-- **AND** SHALL NOT list every change as though the filter matched nothing
-
-#### Scenario: No lifecycle output without a declaration
-- **WHEN** no change in the root declares a `status`
-- **THEN** the human listing SHALL render no lifecycle column
-- **AND** the JSON output SHALL carry no lifecycle key
-
-#### Scenario: The lifecycle appears once any change declares one
-- **WHEN** at least one change declares a `status`
-- **THEN** the human listing SHALL render a lifecycle column, showing `proposed`
-  for changes that declare nothing
-- **AND** the JSON output SHALL carry a `lifecycle` key for the declaring changes
-  only, leaving the existing `status` key meaning task progress

openspec/changes/add-standalone-spec-sync/specs/cli-sync/spec.md

@@ -1,142 +0,0 @@
-# Sync Command Specification
-
-## Purpose
-
-The `openspec sync` command SHALL fold a change's delta specs into the main specs
-without archiving the change, and SHALL provide a check that a change claiming to
-be shipped has its deltas present in the main specs.
-
-## ADDED Requirements
-
-### Requirement: Lifecycle Status Field
-A change SHALL be able to declare its lifecycle state as data in its
-`.openspec.yaml`, using an optional `status` field whose value is `proposed` or
-`shipped`. A change that does not declare one SHALL be treated as `proposed`.
-
-#### Scenario: Undeclared status reads as proposed
-- **WHEN** a change's `.openspec.yaml` has no `status` field, or the change has no
-  metadata file at all
-- **THEN** every reader SHALL treat the change as `proposed`
-- **AND** no command SHALL write the field on the change's behalf
-
-#### Scenario: A status that cannot be determined is not rounded to proposed
-- **WHEN** a change's metadata mentions `status` but cannot be honored, because the
-  file does not parse, carries an unknown value, or names a schema that does not
-  resolve
-- **THEN** the state SHALL be reported as undetermined with its reason
-- **AND** `openspec sync --check` SHALL fail rather than pass the change
-
-#### Scenario: Broken metadata that never mentions status is left alone
-- **WHEN** a change's metadata cannot be honored and does not mention `status`
-- **THEN** the change SHALL read as `proposed`
-- **AND** `openspec sync --check` SHALL NOT report it
-
-### Requirement: Folding Delta Specs
-The command SHALL apply a change's delta specs to the main specs, leaving the
-change directory where it is.
-
-#### Scenario: Folding a named change
-- **WHEN** `openspec sync <change>` is executed
-- **THEN** each delta under the change's `specs/` SHALL be applied to its main spec
-- **AND** the change directory SHALL NOT be moved
-- **AND** the change's declared status SHALL NOT affect whether it is folded
-
-#### Scenario: Folding every shipped change
-- **WHEN** `openspec sync` is executed with no change name
-- **THEN** every active change declaring `status: shipped` SHALL be folded
-- **AND** a change declaring no status SHALL NOT be folded
-
-#### Scenario: Folding is idempotent
-- **WHEN** `openspec sync` is run against a change whose deltas are already in the
-  main specs
-- **THEN** no file SHALL be written
-- **AND** the command SHALL report that the specs are already in sync
-
-#### Scenario: Archiving after a sync is unaffected
-- **WHEN** a change is folded by `openspec sync` and later archived
-- **THEN** `openspec archive` SHALL apply zero operations and write no spec file
-- **AND** the change SHALL be moved to the archive as it always was
-
-### Requirement: Shipped Changes Are Folded
-The command SHALL provide a check that asserts one property over the working tree:
-every change claiming to be shipped has its deltas present in the main specs.
-
-#### Scenario: A proposed change passes for free
-- **WHEN** `openspec sync --check` is executed and no active change declares
-  `status: shipped`
-- **THEN** the command SHALL exit 0
-- **AND** SHALL write no file
-
-#### Scenario: A shipped change with unfolded deltas fails the check
-- **WHEN** `openspec sync --check` is executed and an active change declaring
-  `status: shipped` has a delta that is not in its main spec
-- **THEN** the command SHALL exit 1
-- **AND** SHALL name the change and each capability whose delta is unapplied
-- **AND** SHALL name the command that folds them
-- **AND** SHALL write no file
-
-#### Scenario: Folded-ness is decided by the merge builder
-- **WHEN** deciding whether a change's deltas are present in the main specs
-- **THEN** the decision SHALL be that re-applying the delta produces zero applied
-  operations, which is the same predicate the archive command uses to decide it
-  has nothing to write
-- **AND** SHALL NOT be a byte comparison against a rebuilt spec
-
-#### Scenario: Archived changes are never examined
-- **WHEN** `openspec sync --check` is executed
-- **THEN** only active changes SHALL be examined
-- **AND** a change that has been archived SHALL NOT be checked
-
-### Requirement: Sync Never Deletes A Spec
-The command SHALL NOT delete a main spec under any circumstance. Retiring a
-capability remains the archive command's operation.
-
-#### Scenario: A retirement is handed to archive
-- **WHEN** a change's REMOVED entries would take a capability's last requirement
-- **THEN** `openspec sync` SHALL refuse to fold that change
-- **AND** SHALL name `openspec archive` as the command that performs a retirement
-- **AND** the main spec file SHALL remain on disk
-
-#### Scenario: The check reports a retirement without offering sync as the fix
-- **WHEN** `openspec sync --check` finds a shipped change that would retire a
-  capability
-- **THEN** the command SHALL exit 1 naming the retirement
-- **AND** SHALL NOT tell the user to run `openspec sync`
-
-### Requirement: Guards Before Writing
-The command SHALL run the same guards the archive command runs before it writes a
-main spec.
-
-#### Scenario: Delta specs are validated
-- **WHEN** a change's delta specs fail validation and `--no-validate` was not passed
-- **THEN** the command SHALL refuse the change and write no file
-
-#### Scenario: Incomplete tasks block the fold
-- **WHEN** a change has incomplete tasks and `--yes` was not passed
-- **THEN** the command SHALL refuse the change and write no file
-- **AND** SHALL name the rerun that proceeds anyway
-
-#### Scenario: Every rebuilt spec is validated before any is written
-- **WHEN** any rebuilt spec would fail validation
-- **THEN** no spec file SHALL be written at all
-
-#### Scenario: A fold that does not settle is named
-- **WHEN** two shipped changes claim the same requirement in ways that cannot both
-  hold, so re-evaluating after the write still reports unfolded deltas
-- **THEN** the command SHALL name the changes involved
-- **AND** SHALL NOT retry the fold
-
-### Requirement: Shipping In One Diff
-The command SHALL offer to set a change's status and fold it in a single run, so
-that no intermediate commit claims a change is shipped while its deltas are absent
-from the main specs.
-
-#### Scenario: Marking a change shipped and folding it
-- **WHEN** `openspec sync <change> --ship` is executed
-- **THEN** the change's `.openspec.yaml` SHALL be set to `status: shipped`
-- **AND** its deltas SHALL be folded in the same run
-- **AND** the metadata file's comments and key order SHALL be preserved
-
-#### Scenario: Ship is refused where it cannot apply
-- **WHEN** `--ship` is passed with `--check`, or with no change name
-- **THEN** the command SHALL refuse and say which flag combination is valid

openspec/changes/add-standalone-spec-sync/tasks.md

@@ -1,25 +0,0 @@
-## 1. Lifecycle field
-
-- [x] 1.1 Add optional `status: proposed | shipped` to `ChangeMetadataSchema`
-- [x] 1.2 Add `readChangeStatus`, failing closed on metadata it cannot honor
-- [x] 1.3 Add `writeChangeStatus`, preserving comments and key order
-
-## 2. Sync command
-
-- [x] 2.1 Add `src/core/sync.ts` with the fold and the `--check` predicate
-- [x] 2.2 Run archive's guards before writing: validation, task completion,
-      rebuilt-spec validation
-- [x] 2.3 Refuse retirements and name `openspec archive` instead
-- [x] 2.4 Re-evaluate after writing so a non-convergent pair is named, not looped on
-- [x] 2.5 Register the CLI command and its completion entry
-
-## 3. List filter
-
-- [x] 3.1 Add `--status <state>`, counting an undeclared change as `proposed`
-- [x] 3.2 Render the lifecycle column and the JSON `lifecycle` key only when declared
-
-## 4. Docs and verification
-
-- [x] 4.1 Document `openspec sync` and `list --status`
-- [x] 4.2 Add the CI section to the team workflow guide
-- [x] 4.3 Tests covering the gate, the guards, and the archive interaction

openspec/changes/add-status-next-step/.openspec.yaml

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

openspec/changes/add-status-next-step/proposal.md

@@ -0,0 +1,44 @@
+# Name the command that resumes a change
+
+## Why
+
+`openspec status` reported where a change stood and stopped there. The command
+that moves it forward was already computed: `buildNextSteps` derives it and
+`--json` publishes it as `nextSteps`. But the text surface never rendered it.
+
+So the surface a person actually reads ended on a checklist. `openspec new
+change` hands off with `Next: openspec status --change <name>`, and that next
+command then had no verb of its own. Picking a change back up after a lost
+session, or opening one somebody else started, meant already knowing which
+command came next (#906).
+
+The completion case was the worst of it. Once every planning artifact existed,
+status printed a lone green "All planning artifacts complete!", which reads as
+*you are done* even while `tasks.md` sits half-checked. That is what #906
+reports: every artifact showed `done` rather than `ready`, so the conclusion was
+that nothing was left to run.
+
+## What Changes
+
+- `openspec status` ends with a `Next:` line naming one command: the next ready
+  artifact's `openspec instructions` call while planning is unfinished, and
+  `openspec instructions apply` once every planning artifact exists.
+- The line carries `--store <id>` whenever the resolved root is a store. A
+  command without the flag would resolve against the pointer repo instead of the
+  store the status was read from.
+- `--all` gives every change in the sweep its own line, and gives none to an
+  entry that failed to load, since a failed entry has no artifact statuses to reason
+  about.
+- The line is built from the same resolution as the JSON `nextSteps` sentence,
+  so the two surfaces cannot name different commands. `nextSteps` itself is
+  unchanged, character for character.
+
+No new command, no new flag, no new JSON field. This renders a value the agent
+contract already publishes.
+
+## Impact
+
+- Affected specs: `cli-artifact-workflow` (MODIFIED: Next Artifact Discovery)
+- Affected code: `src/commands/workflow/status.ts`,
+  `src/core/change-status-policy.ts`
+- Affected docs: `docs/cli.md` (the status text output example)

openspec/changes/add-status-next-step/specs/cli-artifact-workflow/spec.md

@@ -0,0 +1,37 @@
+## MODIFIED Requirements
+
+### Requirement: Next Artifact Discovery
+
+The workflow SHALL use `openspec status` output to determine what can be created next, rather than a separate next-command surface.
+
+#### Scenario: Discover next artifacts from status output
+
+- **WHEN** a user needs to know which artifact to create next
+- **THEN** `openspec status --change <id>` identifies ready artifacts with `[ ]`
+- **AND** the first `[ ]` entry is the schema's recommended next artifact
+- **AND** no dedicated "next command" is required to continue the workflow
+
+#### Scenario: Status names the command that moves the change forward
+
+- **WHEN** a user runs `openspec status --change <id>` in text mode and a next step resolves
+- **THEN** the output ends with a `Next:` line naming exactly one command to run
+- **AND** that command is `openspec instructions <artifact> --change "<id>" --json` for the first ready artifact while any planning artifact is still ready
+- **AND** it is `openspec instructions apply --change "<id>" --json` once every planning artifact exists, printed after the completion line rather than in place of it, because that line alone reads as "you are done" while implementation tasks remain
+- **AND** the named artifact is never one the change skipped, which satisfies its dependents but must not be created
+- **AND** the artifact id comes from the resolved schema, so a project whose schema declares neither of the default artifact names still gets a usable command
+
+#### Scenario: The named command carries the store selection
+
+- **WHEN** the resolved root is a store
+- **THEN** the `Next:` command includes `--store <id>`, so it resolves against the same root the status was read from rather than the pointer repo
+
+#### Scenario: Both surfaces name the same command
+
+- **WHEN** a next step resolves
+- **THEN** the command printed on the `Next:` line and the command inside the JSON `nextSteps` sentence are derived from one resolution, so the two surfaces cannot name different commands
+- **AND** the `Next:` line never appears in `--json` output, which stays parseable
+
+#### Scenario: No next step resolves
+
+- **WHEN** no artifact is ready and planning is not complete, or a change in an `--all` sweep failed to load
+- **THEN** no `Next:` line is printed for it, rather than a guessed or shared command

openspec/changes/add-status-next-step/tasks.md

@@ -0,0 +1,17 @@
+# Tasks
+
+## 1. Resolve the next step once
+- [x] 1.1 Extract `resolveNextStep` returning the command and the sentence, leaving `buildNextSteps` returning exactly that sentence so the JSON contract is unchanged
+- [x] 1.2 Pin the published sentences verbatim in a unit test, so splitting command from sentence cannot reword the contract
+
+## 2. Render it on the text surface
+- [x] 2.1 Print a `Next:` line from the resolved command, after the completion line rather than in place of it
+- [x] 2.2 Thread the store selection into the renderer so the command carries `--store`
+- [x] 2.3 Give every change in an `--all` sweep its own line, and a failed entry none
+
+## 3. Cover the behavior
+- [x] 3.1 Assert the ready, planning-complete, skipped, and custom-schema cases end to end
+- [x] 3.2 Assert the printed command appears verbatim inside the JSON sentence, and that the line never leaks into `--json`
+
+## 4. Record it
+- [x] 4.1 Update the `cli-artifact-workflow` spec delta and the `docs/cli.md` status output example

openspec/changes/add-update-workflow/design.md

@@ -105,6 +105,12 @@ Review feedback flagged that "update" alone is generic — could it apply to any
 ### 6. Next-step guidance, especially for already-implemented changes
 A change can be revised after it was built — tasks checked off, `/opsx:apply` already run. The update itself behaves identically (planning artifacts only), but stopping silently would strand the user: the code and the revised plan now disagree. So the skill ends by reporting where the change stands (from the status JSON and the tasks checklist) and recommending the next command — `/opsx:continue` if artifacts are missing, `/opsx:apply` to carry a revised plan into code, `/opsx:archive` when everything is done. Guidance only: the skill never implements, mirroring the "All artifacts created! You can now implement this change with `/opsx:apply`" hand-off that `continue-change.ts` already uses.
 
+### 7. Companion-file correction (#1733)
+
+The original glob-file deferral was unreachable: one matching file marks an artifact `done`, while continue selects only `ready` artifacts. Update can therefore propose a missing companion file within an already populated glob. This corrects the unarchived spec's former blanket deferral without changing the graph's completion rule or starting another artifact.
+
+The exception uses existing status and instructions output, requires current dependency context and user confirmation, and preserves the change-only planning scope. Immediately before creation, it rechecks scope and the concrete path and uses an operation that refuses an existing target. Delegated creators must obey the same limits. No new CLI command, metadata, graph state, or automatic artifact writer is introduced.
+
 ## Risks / Trade-offs
 
 - **No deterministic staleness signal.** With no digest/ledger, the skill relies on the agent reading the artifacts to spot incoherence. Trade-off accepted: an agent that rewrites prose must read it anyway, and a content-blind signal earns its cost only for use cases this change excludes (Decision 3).

openspec/changes/add-update-workflow/specs/opsx-update-skill/spec.md

@@ -19,7 +19,7 @@ The system SHALL provide a `/opsx:update` workflow skill that revises a change's
 
 #### Scenario: Missing artifacts are deferred to continue
 
-- **WHEN** keeping the change coherent would require an artifact that has not been created yet
+- **WHEN** keeping the change coherent would require an artifact with no existing output files and status `ready` or `blocked`
 - **THEN** the skill revises only the artifacts that currently exist
 - **AND** it notes the not-yet-created artifacts and points the user to `/opsx:continue` to create them
 
@@ -53,7 +53,7 @@ The `/opsx:update` skill SHALL learn which artifacts exist and where they live b
 
 #### Scenario: Resolve artifact paths cross-platform
 
-- **WHEN** the skill reads or writes an artifact on macOS, Linux, or Windows
+- **WHEN** the skill reads or revises an existing artifact file on macOS, Linux, or Windows
 - **THEN** it uses the `existingOutputPaths` provided by the CLI status output
 - **AND** it does not assume forward-slash separators
 
@@ -63,11 +63,30 @@ The `/opsx:update` skill SHALL learn which artifacts exist and where they live b
 - **THEN** the skill edits the concrete files reported in that artifact's `existingOutputPaths`
 - **AND** it does not write to `resolvedOutputPath`, which for a glob artifact remains the glob pattern rather than a real file
 
-#### Scenario: A new file under a glob artifact is deferred to continue
+#### Scenario: A missing companion file under a populated glob artifact
 
-- **WHEN** keeping the change coherent would require a new file under a glob artifact that does not exist yet (for example a spec for a not-yet-captured capability)
-- **THEN** the skill revises only the files already present in `existingOutputPaths`
-- **AND** it points the user to `/opsx:continue`/`/opsx:propose` to create the new file rather than inventing a path from the glob
+- **WHEN** reconciliation identifies a missing companion file for a glob artifact with non-empty `existingOutputPaths`
+- **THEN** the skill MAY propose creating that file using the artifact's instructions, template, project context, rules, and current dependency files
+- **AND** it selects an unused concrete path matching the artifact's `outputPath` inside `changeRoot`, including after resolving linked parent directories
+- **AND** it creates the file only after user confirmation, refreshing status, instructions, and path checks immediately before creation
+- **AND** creation SHALL fail rather than overwrite a file that appeared in the meantime
+- **AND** it SHALL NOT start another artifact, write main specs, or edit implementation code
+
+#### Scenario: Required inputs are no longer available
+
+- **WHEN** a populated glob artifact remains `done` but a required non-skipped dependency is missing
+- **THEN** the skill SHALL stop new companion creation and ask the user to restore the dependency first
+
+#### Scenario: Schema delegates companion creation
+
+- **WHEN** the artifact instruction delegates creation to another skill or command
+- **THEN** the skill SHALL invoke it only if it can honor the confirmed concrete path and the update guardrails
+- **AND** otherwise it SHALL stop rather than invoke broader generation
+
+#### Scenario: Intentionally skipped artifact
+
+- **WHEN** status or instructions mark an artifact as skipped
+- **THEN** the skill SHALL leave it untouched and SHALL NOT treat its empty outputs as missing or send it to continue
 
 ### Requirement: Bidirectional Coherence Review
 
@@ -109,7 +128,7 @@ After applying confirmed revisions (or finding none needed), the `/opsx:update`
 
 #### Scenario: Next step when artifacts are incomplete
 
-- **WHEN** the update finishes and the change still has not-yet-created artifacts
+- **WHEN** the update finishes and the change still has artifacts with no outputs and status `ready` or `blocked`
 - **THEN** the skill recommends `/opsx:continue` to create them
 
 #### Scenario: Next step when the change is fully done

openspec/changes/add-version-command/.openspec.yaml

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

openspec/changes/add-version-command/design.md

@@ -0,0 +1,131 @@
+# Design: a read-only `openspec version` command
+
+## Context
+
+`openspec --version` is Commander's built-in version flag and intentionally prints only the package version. `src/core/version-check.ts` already knows how to locate the running package, classify several install layouts, select package-manager-specific update advice, enforce update-check privacy controls, and query a registry defensively. Those helpers currently serve `openspec update`, where a nullable return value is enough: either announce a newer release or continue silently.
+
+The new command has a different contract. It must explain why no update was reported, and external tools need a stable JSON shape rather than terminal prose. That requires an additive command and a structured result from the existing version-check core; it does not require a second detection or networking implementation.
+
+## Goals / Non-Goals
+
+**Goals**
+
+- Give people and tools one supported way to inspect the running version and install context.
+- Keep the default command local and instant; network access requires `--check`.
+- Return one stable JSON document suitable for editor extensions, GUIs, and scripts.
+- Reuse the existing install-detection and registry-safety rules.
+- Preserve `openspec --version` byte-for-byte for existing scripts.
+
+**Non-Goals**
+
+- Installing or upgrading OpenSpec; that work is tracked separately in #1989.
+- Release notes, channels, prerelease selection, or background checks.
+- Perfectly identifying every custom package-manager layout. Unknown values remain honest `null`s.
+- Changing `openspec update` or its interactive upgrade offer.
+
+## Decisions
+
+### 1. Add a command; do not extend `--version`
+
+`openspec --version` is a widely scripted, root-level flag whose bare output is useful precisely because it has no other fields. Commander also treats root flags differently from subcommands. A separate `openspec version` command creates room for options and structured output without changing the old contract.
+
+### 2. Separate local inspection from the network check
+
+`openspec version` and `openspec version --json` inspect only local process and package paths. `--check` is the sole trigger for registry access. This makes the default deterministic, fast, and safe in offline or air-gapped environments.
+
+The command remains successful when checking is disabled or unavailable. Update availability is advisory, so disabled privacy settings and network failure are data states rather than command failures.
+
+### 3. Use one versioned JSON envelope
+
+The JSON response always starts with the same base fields:
+
+```json
+{
+  "schemaVersion": 1,
+  "version": "1.13.2",
+  "install": {
+    "location": "/path/to/@fission-ai/openspec",
+    "packageManager": "npm",
+    "scope": "global"
+  }
+}
+```
+
+With `--check`, the response adds:
+
+```json
+{
+  "update": {
+    "status": "available",
+    "latest": "1.14.0",
+    "command": "npm install -g @fission-ai/openspec@latest",
+    "canSelfUpgrade": true
+  }
+}
+```
+
+`schemaVersion` versions the document independently of the OpenSpec package. The `update` object is absent unless requested, so local callers do not need to distinguish "not checked" from a check outcome. Nullable fields are explicit when detection has no defensible answer.
+
+Status values are deliberately small:
+
+- `available`: a safe newer registry version was found.
+- `current`: the check completed and found no newer version.
+- `disabled`: policy prevented a request, including privacy opt-outs or a rejected registry.
+- `offline`: a permitted request did not produce a usable answer, including timeouts and invalid responses.
+
+### 4. Classify ownership before naming a package manager
+
+Install scope is determined before package-manager ownership:
+
+1. A source checkout reports `scope: "source"` and `packageManager: null`.
+2. An ephemeral runner/cache reports `scope: "temporary"`.
+3. A dependency owned by the current project reports `scope: "project"`.
+4. A recognized global layout reports `scope: "global"`.
+5. If no classification is defensible, the field is `null` rather than guessing.
+
+The implementation should reuse `getInstallDir()`, `isSourceCheckout()`, `isEphemeralRunnerInstall()`, `isProjectLocalInstall()`, and `detectPackageManager()`, while adding one pure function that assembles the public install record. Detection stays separately unit-testable with POSIX and Windows paths.
+
+### 5. Return a structured check result from the existing core
+
+`getAvailableCliUpdate()` currently collapses four conditions into `null`: current, disabled, unreachable, and invalid response. Keep it as a compatibility wrapper for `openspec update`, but implement it over a new structured check function whose result maps directly to the four public statuses.
+
+The structured function must share the current request implementation. It must not duplicate registry selection, TLS-only configured-registry behavior, redirect limits, timeouts, response-size limits, or safe-version validation.
+
+### 6. Derive update guidance from existing decisions
+
+The reported command and `canSelfUpgrade` value come from the same install classification used by `openspec update`. Refactor terminal-line builders only as needed to expose a pure structured recommendation; do not parse human-readable strings back into JSON.
+
+`canSelfUpgrade` describes whether the existing safe self-upgrade mechanism could operate on this install. The version command never invokes that mechanism.
+
+### 7. Keep incidental output away from JSON
+
+The CLI already defers telemetry and completion notices for JSON runs. The command follows existing JSON error/output conventions and writes exactly one JSON document to stdout. Human-readable output may use multiple lines but remains uncolored when global color is disabled.
+
+## Security and Privacy
+
+- No network access occurs without `--check`.
+- Existing privacy opt-outs continue to block the request.
+- A rejected configured registry does not cause a fallback request to public npm.
+- Registry-provided versions pass the current strict validator before display.
+- Existing redirect, timeout, and response-size limits remain in force.
+- Install paths are printed only in direct response to the user's command and are never sent as telemetry by this change.
+- The command never executes the reported update command.
+
+## Documentation
+
+The implementation updates `docs-lab/reference/cli.md`, using the current docs-lab page structure and examples. It does not update the legacy `docs/cli.md` page.
+
+## Risks / Trade-offs
+
+- **Public schema commitment:** integrations may depend on field names and status values. `schemaVersion` and regression fixtures make future incompatible changes explicit.
+- **Install detection is heuristic:** custom layouts may remain unknown. Returning `null` is less convenient but safer than incorrect update guidance.
+- **Absolute path disclosure:** `install.location` can contain a user name. It appears only on explicit local invocation; callers that persist or transmit it are responsible for handling it as local environment data.
+- **Status vocabulary:** `offline` also covers unusable registry responses, not only literal network loss. It is intentionally user-facing shorthand for "no usable remote answer" while logs/tests retain the detailed cause internally if needed.
+
+## Migration Plan
+
+This change is additive. Existing flags and commands retain their behavior. No stored data, configuration, or generated files require migration.
+
+## Open Questions
+
+None required for implementation. Review may rename a JSON field or status before approval; after release, incompatible changes require a new `schemaVersion`.

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

@@ -0,0 +1,35 @@
+# Proposal
+
+## Why
+
+Editor extensions, GUIs, and scripts can read OpenSpec's bare version number, but they cannot ask how this copy was installed or whether an update is available. They must duplicate OpenSpec's install detection and update-check behavior, which produces inconsistent advice and makes integrations depend on human-oriented terminal output.
+
+## What Changes
+
+- Add `openspec version` as a read-only command that reports the installed version and install context without requiring an OpenSpec project.
+- Add `openspec version --json` with a versioned, machine-readable response for integrations.
+- Add an opt-in `--check` flag that queries the configured registry and reports whether an update is available, disabled, current, or temporarily unavailable.
+- Reuse the existing privacy opt-outs, registry safeguards, package-manager detection, and update-command selection.
+- Keep the existing `openspec --version` output and behavior unchanged for backward compatibility.
+- Document the command in `docs-lab/reference/cli.md`; the legacy `docs/` tree is not updated.
+
+## Capabilities
+
+### New Capabilities
+
+- `cli-version`: Report the installed OpenSpec version and install context, with an optional privacy-aware update check and stable JSON output.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- Public CLI: one additive `version` command with `--json` and `--check` options.
+- Public machine interface: a new JSON document identified by `schemaVersion: 1`.
+- Version-check core: separate update-check outcomes from the current nullable result so callers can distinguish disabled, current, and unavailable states.
+- Tests: unit coverage for install classification and update outcomes, plus CLI end-to-end coverage for text/JSON output and backward compatibility.
+- Documentation: `docs-lab/reference/cli.md` only, following the current docs-lab format.
+- No new dependency, background network request, telemetry field, or automatic upgrade behavior.
+
+Tracks [#1988](https://github.com/Fission-AI/OpenSpec/issues/1988); the issue remains open until implementation lands.

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

@@ -0,0 +1,120 @@
+## ADDED Requirements
+
+### Requirement: Report the installed version
+
+The system SHALL provide an `openspec version` command that reports the running OpenSpec version and install context without requiring an OpenSpec project or contacting the network.
+
+#### Scenario: Human-readable version report
+
+- **WHEN** a user runs `openspec version`
+- **THEN** the command reports the running OpenSpec version
+- **AND** identifies the install's package manager and scope when they can be determined
+- **AND** exits successfully without contacting a registry
+
+#### Scenario: Machine-readable version report
+
+- **WHEN** a user runs `openspec version --json`
+- **THEN** stdout contains one valid JSON document
+- **AND** the document contains `schemaVersion: 1`, `version`, and `install`
+- **AND** `install` contains `location`, `packageManager`, and `scope`
+- **AND** `scope` is one of `global`, `project`, `temporary`, or `source`
+- **AND** values that cannot be determined are represented as `null`
+
+#### Scenario: Source checkout
+
+- **WHEN** the running CLI is a source checkout
+- **THEN** the command reports `scope` as `source`
+- **AND** it does not claim that a package manager owns the checkout
+
+#### Scenario: Existing version flag remains compatible
+
+- **WHEN** a user runs `openspec --version`
+- **THEN** the command prints the same bare version string as before this capability was added
+- **AND** no JSON or install metadata is added to that output
+
+### Requirement: Check for an available update on request
+
+The system SHALL contact the configured package registry only when `openspec version` receives `--check`, and SHALL report the outcome without making command success depend on registry availability.
+
+#### Scenario: Update is available
+
+- **WHEN** a user runs `openspec version --check`
+- **AND** the registry reports a safe newer version
+- **THEN** the command reports the latest version
+- **AND** reports the appropriate update command only when one exists for this install
+- **AND** human-readable output omits package-manager guidance when no such command exists
+- **AND** reports whether the existing self-upgrade path can safely update this copy
+- **AND** exits successfully
+
+#### Scenario: Installed version is current
+
+- **WHEN** a user runs `openspec version --check`
+- **AND** the registry reports no version newer than the running version
+- **THEN** the command reports the update status as `current`
+- **AND** exits successfully
+
+#### Scenario: Update check is disabled
+
+- **WHEN** a user runs `openspec version --check`
+- **AND** an existing OpenSpec privacy or update-check opt-out disables registry access
+- **THEN** the command does not contact the registry
+- **AND** reports the update status as `disabled`
+- **AND** reports no latest version
+- **AND** exits successfully
+
+#### Scenario: Registry is unavailable
+
+- **WHEN** a user runs `openspec version --check`
+- **AND** the registry cannot be reached or returns an unusable response
+- **THEN** the command reports the update status as `offline`
+- **AND** reports no latest version
+- **AND** exits successfully
+
+#### Scenario: Machine-readable update result
+
+- **WHEN** a user runs `openspec version --check --json`
+- **THEN** the base version and install fields remain present
+- **AND** the document contains an `update` object with `status`, `latest`, `command`, and `canSelfUpgrade`
+- **AND** `status` is one of `available`, `current`, `disabled`, or `offline`
+- **AND** unavailable values are represented as `null`
+- **AND** stdout contains no text outside the JSON document
+
+### Requirement: Preserve update-check safeguards
+
+The version command SHALL use the same privacy, registry, timeout, response-size, redirect, and version-validation safeguards as OpenSpec's existing update check.
+
+#### Scenario: Explicit privacy opt-out
+
+- **WHEN** telemetry is disabled or `DO_NOT_TRACK`, `OPENSPEC_TELEMETRY`, or `OPENSPEC_NO_UPDATE_CHECK` disables outbound checks
+- **AND** a user runs `openspec version --check`
+- **THEN** the command performs no update-check request
+- **AND** reports the update status as `disabled`
+
+#### Scenario: Unsafe configured registry
+
+- **WHEN** the configured registry is rejected by the existing registry safeguards
+- **AND** a user runs `openspec version --check`
+- **THEN** the command does not fall back to the public registry
+- **AND** reports the update status as `disabled`
+
+#### Scenario: Untrusted version response
+
+- **WHEN** the registry response does not contain a version accepted by OpenSpec's existing version validator
+- **THEN** the command does not print the untrusted value
+- **AND** reports the update status as `offline`
+
+### Requirement: Version reporting is read-only
+
+The version command SHALL NOT install, upgrade, or modify OpenSpec, project files, or user configuration.
+
+#### Scenario: Update is available
+
+- **WHEN** `openspec version --check` reports an available update
+- **THEN** it reports guidance only
+- **AND** does not run a package manager or alter the installed copy
+
+#### Scenario: Upgrade option is rejected
+
+- **WHEN** a user runs `openspec version --upgrade`
+- **THEN** the command reports that `--upgrade` is not supported
+- **AND** does not attempt an upgrade

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

@@ -0,0 +1,35 @@
+# Tasks
+
+## 1. Model version and install information
+
+- [x] 1.1 Add typed, pure install classification that reports location, package manager, and scope without guessing ownership for source or unknown layouts.
+- [x] 1.2 Add POSIX and Windows unit cases for global, project, temporary, source, and unknown installs.
+
+## 2. Expose structured update-check outcomes
+
+- [x] 2.1 Refactor the existing update check to return `available`, `current`, `disabled`, or `offline` with structured latest-version and update-guidance fields.
+- [x] 2.2 Keep `getAvailableCliUpdate()` as a compatibility wrapper so `openspec update` behavior does not change.
+- [x] 2.3 Cover privacy opt-outs, rejected registries, timeouts, invalid responses, current versions, and available updates without weakening existing network safeguards.
+
+## 3. Add the version command
+
+- [x] 3.1 Add `openspec version` with `--json` and `--check` options and no project-root prerequisite.
+- [x] 3.2 Emit one schema-versioned JSON document with explicit nulls for unknown values and no incidental stdout.
+- [x] 3.3 Add human-readable output for local information and each update-check status.
+- [x] 3.4 Reject `--upgrade` and other unsupported options without running an installer.
+
+## 4. Verify compatibility and behavior
+
+- [x] 4.1 Add CLI end-to-end coverage for text output, JSON output, `--check`, and execution outside an OpenSpec project.
+- [x] 4.2 Prove `openspec --version` still emits only the bare version string.
+- [x] 4.3 Prove JSON runs emit no telemetry notice, completion tip, color sequence, or extra stdout text.
+
+## 5. Document and release
+
+- [x] 5.1 Document `openspec version`, `--json`, and `--check` in `docs-lab/reference/cli.md` using the current docs-lab format; do not update the legacy `docs/` tree.
+- [x] 5.2 Add a minor changeset for `@fission-ai/openspec`.
+
+## 6. Final verification
+
+- [x] 6.1 Run `pnpm build`, the focused version-check and CLI tests, `pnpm test`, `pnpm exec tsc --noEmit`, and `pnpm lint`.
+- [x] 6.2 Run `openspec validate add-version-command --strict` and confirm every planning artifact is complete.

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/.openspec.yaml

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

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/design.md

@@ -0,0 +1,109 @@
+## Context
+
+Grok Build (CLI binary `grok`) is not a Claude/Codex-style command-file adapter target. Its documented extension model is skill-centric:
+
+- project skills from `./.grok/skills/` (walked up to the repo root)
+- user skills from `~/.grok/skills/`
+- plugin skills and optional `[skills] paths` in config
+- user-invocable skills appear as slash commands: `/<skill-name>`
+- core TUI commands (`/plan`, `/model`, `/skills`, …) are built-in, not project-generated files
+- no documented project-local `.grok/commands/` layout for custom OpenSpec command generation
+
+Grok also has Claude/Cursor compatibility scanners that can free-ride existing `.claude/skills` or `.cursor/skills`. That is a personal workaround, not the product integration: OpenSpec should own a native `.grok` skills install so pure-Grok users and multi-tool projects get first-class init/update behavior.
+
+OpenSpec already represents this shape:
+
+- `AI_TOOLS` can advertise a `skillsDir`
+- `init`/`update` install skills for any selected tool with `skillsDir`
+- when command generation is attempted for a tool without an adapter, OpenSpec records `commandsSkipped`
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add Grok Build using the same narrow skills-only pattern as Kimi CLI / ForgeCode / Mistral Vibe
+- Keep the implementation small: metadata, docs, focused regression test, changeset
+- Align specs with the existing adapterless code path
+
+**Non-Goals:**
+
+- designing a Grok-specific command adapter without a documented project command-file surface
+- relying on Claude/Cursor free-ride as the supported integration
+- changing tool capability modeling or `delivery=commands` behavior for all adapterless tools (tracked in `add-tool-command-surface-capabilities`)
+
+## Decisions
+
+### 1. Represent Grok Build as an adapterless tool with `.grok`
+
+Add a new `AI_TOOLS` entry:
+
+```ts
+{ name: 'Grok Build', value: 'grok', available: true, successLabel: 'Grok Build', skillsDir: '.grok' }
+```
+
+Rationale for IDs:
+
+- `value: 'grok'` matches the CLI binary and the project directory `.grok` (same pattern as `claude` → `.claude`, `kimi` → `.kimi`)
+- display name `Grok Build` matches xAI product naming
+- alternatives considered: `grok-build` (product-accurate but inconsistent with other short tool IDs)
+
+### 2. Do not add a Grok command adapter
+
+No `src/core/command-generation/adapters/grok.ts`, and no registry change.
+
+Rationale:
+
+- skills are the documented custom extension surface and already become slash commands
+- inventing `.grok/commands/...` would create OpenSpec behavior that cannot be justified against xAI docs
+- existing adapterless path already skips command generation with an informational message
+
+### 3. Document Grok by its real invocation surface
+
+Grok docs in OpenSpec must use skill-name slash form:
+
+- supported-tools: no generated command files; use skill-based `/openspec-*` invocations
+- commands / how-commands-work: examples such as `/openspec-propose`, `/openspec-apply-change`
+
+Do not claim generated `opsx-*` files or Claude-style `/opsx:propose` as Grok's primary surface.
+
+### 4. Treat Claude free-ride as out-of-scope workaround, not design
+
+Grok can discover Claude skills when compat scanners are enabled. Native `.grok` support remains required because:
+
+- pure Grok users may never select Claude
+- free-ride couples Grok to Claude layout and can be disabled via Grok config/env
+- OpenSpec update tracks configured tools by skillsDir presence; free-ride never registers Grok
+
+If both Claude and Grok are configured, duplicate skill discovery is acceptable; `.grok` remains the canonical OpenSpec target for Grok Build.
+
+### 5. Keep behavior aligned with current adapterless tools
+
+- skills are created whenever delivery includes skills
+- command generation is skipped when no adapter exists
+- init output reports `Commands skipped for: grok (no adapter)`
+- update refreshes Grok when `.grok/skills/openspec-*` exists
+
+## Test Strategy
+
+Add one focused regression test in `test/core/init.test.ts`:
+
+- configure `delivery=both`
+- run init with `--tools grok`
+- verify skills under `.grok/skills/...` (use `path.join` for expectations)
+- verify no `.grok/commands` directory is created
+- verify init log includes skipped command generation for `grok` with `(no adapter)` (use relaxed `.some()` matching, as in the Kimi follow-up commit)
+
+That is enough because:
+
+- adapterless update behavior already has generic coverage
+- CLI tool-id rendering is derived from `AI_TOOLS`
+- no command adapter or path-formatting logic is introduced
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Users confuse Claude free-ride with native support | Document native `.grok` path; optional brief note that Claude compat is separate |
+| `delivery=commands` still not capability-aware for skills-only tools | Accept same limitation as Kimi/ForgeCode/Vibe; capability work is separate |
+| Duplicate skills when both Claude and Grok selected | Acceptable; document that Grok may see both trees |
+| xAI later documents project command files | Skills-only remains correct today; adapter can be added later without breaking skills |

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/proposal.md

@@ -0,0 +1,40 @@
+## Why
+
+xAI Grok Build is a coding agent with a documented project skills root at `.grok/skills/`, and user-invocable skills surface as slash commands (`/<skill-name>`). OpenSpec does not yet list Grok Build as a supported tool, so users must free-ride on Claude/Cursor compat scanners or configure extra skill paths manually.
+
+OpenSpec already supports adapterless skills-only tools (Kimi CLI, ForgeCode, Mistral Vibe). Grok Build should follow that pattern: install skills under `.grok/skills/` without inventing a command adapter for a project command-file surface that xAI docs do not define.
+
+## What Changes
+
+- Add Grok Build as a supported tool in `AI_TOOLS` with `value: 'grok'` and `skillsDir: '.grok'`
+- Document Grok Build as a skills-only integration (no generated `opsx-*` command files; invoke via `/openspec-*` skill names)
+- Align specs so `ai-tool-paths` and `cli-init` cover the Grok Build path and adapterless init behavior
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define the `.grok` skills root for Grok Build
+- `cli-init`: treat Grok Build as a supported adapterless selection that still generates skills and skips command-file generation
+
+## Impact
+
+- `src/core/config.ts` - add Grok Build tool metadata
+- `docs/supported-tools.md` - add Grok Build row and tool id
+- `docs/commands.md` - document `/openspec-*` skill invocations for Grok Build
+- `docs/how-commands-work.md` - include Grok Build in slash-syntax table
+- `docs/cli.md` - include `grok` in the supported `--tools` list
+- `docs/troubleshooting.md` - list Grok Build among skills-only tools
+- `test/core/init.test.ts` - cover Grok Build as an adapterless tool during init
+- `.changeset/` - minor release note for the new tool
+
+## Non-Goals
+
+- Adding `src/core/command-generation/adapters/grok.ts`
+- Defining a `.grok/commands/...` output path
+- Relying on Claude/Cursor free-ride as the product integration
+- Changing the broader delivery model for adapterless tools under `delivery=commands` (tracked separately in `add-tool-command-surface-capabilities`)

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/specs/ai-tool-paths/spec.md

@@ -0,0 +1,37 @@
+# ai-tool-paths Delta Specification
+
+## MODIFIED Requirements
+
+### 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: Kimi CLI paths defined
+
+- **WHEN** looking up the `kimi` tool
+- **THEN** `skillsDir` SHALL be `.kimi`
+
+#### Scenario: Grok Build paths defined
+
+- **WHEN** looking up the `grok` tool
+- **THEN** `skillsDir` SHALL be `.grok`
+
+#### Scenario: Tools without skillsDir
+
+- **WHEN** a tool has no `skillsDir` defined
+- **THEN** skill generation SHALL error with message indicating the tool is not supported

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/specs/cli-init/spec.md

@@ -0,0 +1,43 @@
+# cli-init Delta Specification
+
+## MODIFIED Requirements
+
+### Requirement: Slash Command Generation
+
+The command SHALL generate opsx slash commands only for selected tools that have a registered command adapter, while keeping adapterless tools valid for skill generation.
+
+#### Scenario: Generating slash commands for a tool with a registered adapter
+
+- **WHEN** a tool with a registered command adapter 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
+
+#### Scenario: Selected tool has no command adapter
+
+- **GIVEN** a selected tool has `skillsDir` configured but no registered command adapter
+- **WHEN** initialization includes command generation
+- **THEN** skill generation for that tool SHALL still remain valid
+- **AND** command-file generation SHALL be skipped for that tool
+- **AND** the command output SHALL include `Commands skipped for: <tool-id> (no adapter)`
+
+#### Scenario: Kimi CLI skips command-file generation
+
+- **WHEN** the user selects Kimi CLI during initialization
+- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi'`
+- **AND** command-file generation SHALL be skipped because no Kimi adapter is registered
+
+#### Scenario: Grok Build skips command-file generation
+
+- **WHEN** the user selects Grok Build during initialization
+- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.grok'`
+- **AND** command-file generation SHALL be skipped because no Grok adapter is registered

openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/tasks.md

@@ -0,0 +1,24 @@
+## 1. Tool Metadata
+
+- [x] 1.1 Add `Grok Build` to `src/core/config.ts` with `value: 'grok'`, `successLabel: 'Grok Build'`, and `skillsDir: '.grok'` (alphabetically near related tools)
+
+## 2. Documentation
+
+- [x] 2.1 Update `docs/supported-tools.md` with a Grok Build row (`skillsDir` `.grok`, no command adapter; skill-based `/openspec-*` invocations) and add `grok` to the `--tools` list
+- [x] 2.2 Update `docs/commands.md` to document Grok Build skill invocations such as `/openspec-propose`, `/openspec-apply-change`
+- [x] 2.3 Update `docs/how-commands-work.md` slash-syntax table to include Grok Build (`/openspec-*` skill form)
+- [x] 2.4 Update `docs/cli.md` so the supported `--tools` list includes `grok`
+- [x] 2.5 Update `docs/troubleshooting.md` skills-only tool list to include Grok Build
+
+## 3. Tests
+
+- [x] 3.1 Add a targeted init regression test for `--tools grok` with `delivery=both`: skills under `.grok/skills/...`, no `.grok/commands`, and commands-skipped log for `grok` `(no adapter)` using relaxed log matching and `path.join` expectations
+
+## 4. Release Notes
+
+- [x] 4.1 Add a changeset noting Grok Build as a supported skills-only tool via `.grok/skills/`
+
+## 5. Validation
+
+- [x] 5.1 Validate the change artifacts with `openspec validate add-grok-build-skills-only-support --strict` (or project-equivalent)
+- [x] 5.2 Run targeted tests (`test/core/init.test.ts` Grok case) and fix any regressions

openspec/changes/archive/2026-08-15-add-dsh-support/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-15

openspec/changes/archive/2026-08-15-add-dsh-support/design.md

@@ -0,0 +1,86 @@
+## Context
+
+See [proposal.md](proposal.md#why).
+
+OpenSpec already routes every skill-capable tool through one pipeline: `AI_TOOLS` metadata in `src/core/config.ts` drives tool detection (`available-tools.ts`), selection and validation (`init.ts`), skill path resolution (`shared/skill-paths.ts`), generation, version drift, and update. Tools that expose no custom command files simply have no `ToolCommandAdapter`, which `command-surface.ts` classifies as capability `none`.
+
+DeepSeek Harness parses skills from fixed local roots (see the [upstream filesystem provider](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/skill/skill-filesystem)): `<project>/.dsh/skills` (rank 100), `<project>/.agents/skills` (rank 200), and user-level `~/.dsh/skills` (rank 400). It discovers only one level (`<root>/<name>/SKILL.md` or `<root>/<name>.md`), requires `name` (kebab-case) and non-empty `description` frontmatter, tolerates extra fields, and exposes skills to the model through `<available_skills>` plus a `skill` tool; users can also trigger them with the `/name` gesture. OpenSpec's generated `SKILL.md` files already satisfy every dsh constraint, so no template or frontmatter changes are needed.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Add one `dsh` entry to `AI_TOOLS` that opts into the existing project-local skills pipeline.
+- Make first-time setup, auto-detection, refresh, and profile/delivery drift work through existing generic code.
+- Lock the dsh path and invocation behavior with focused tests.
+
+**Non-Goals:**
+
+- A dsh command adapter or any `.dsh/commands/` output — dsh has no file-based command surface.
+- A global `~/.dsh/skills` install target — dsh has a higher-priority project root and OpenSpec manages per-project artifacts.
+- Reclassifying dsh as `skills-invocable` in `command-surface.ts`; that belongs to the in-flight `add-tool-command-surface-capabilities` work. Until then dsh shares the current adapterless behavior of Rovo Dev CLI and Kimi Code.
+- Changing generated skill templates or frontmatter.
+
+## Decisions
+
+### 1. Represent dsh as an adapterless, project-local tool entry
+
+Add to `src/core/config.ts`:
+
+```ts
+{
+  name: 'DeepSeek Harness',
+  value: 'dsh',
+  available: true,
+  successLabel: 'DeepSeek Harness',
+  skillsDir: '.dsh',
+},
+```
+
+`resolveToolSkillsDir()` then resolves to `<projectRoot>/.dsh/skills`, which is dsh's rank-100 project root. Nothing else in init/update/selection needs a code change because those paths derive from `AI_TOOLS`.
+
+Alternative considered: write to `~/.dsh/skills` via `globalSkillsDir`. Rejected because the project root outranks the user root, keeps artifacts repo-local and reviewable, and matches OpenSpec's project-scoped update/removal semantics (MiniMax Code's global-only design exists to work around a tool that only reads the user root, which is not dsh's case).
+
+### 2. Detect dsh from its `.dsh` directory
+
+Use the existing `skillsDir` detection, which requires a directory. This recognizes both a bare `.dsh` project root and a populated `.dsh/skills` tree, but rejects a regular file named `.dsh`.
+
+Explicit `detectionPaths` are unnecessary: `.dsh/skills` already implies a `.dsh` directory, and overrides accept file signals for tools that need them. Auto-detection identifies a tool root; it does not guarantee every child path is writable. A regular file at `.dsh/skills` remains a filesystem conflict reported during generation, as for other directory-based tools.
+
+### 3. No command adapter; inherit capability `none`
+
+`resolveCommandSurfaceCapability('dsh')` returns `none` because no adapter is registered. Consequences, all existing generic behavior:
+
+- `delivery=both` / `skills`: skills generated; init reports `Commands skipped for: dsh (no adapter)`.
+- `delivery=commands`: no dsh artifacts and the existing zero-artifact correction is printed.
+
+Alternative considered: special-case dsh as `skills-invocable` like Codex so commands-only delivery keeps skills. Semantically dsh's skill tool + `/name` gesture are invocable, but the current shipped model only special-cases Codex; widening it here would duplicate the open `add-tool-command-surface-capabilities` change and expand this change's test matrix. Deferred deliberately.
+
+### 4. Use the default `/openspec-*` skill reference spelling
+
+dsh's user-facing `/name` gesture makes `/openspec-propose` a real, typeable invocation, so the default transformer (`getSkillReferenceTransformer` fallback) is correct. The model side can call the `skill` tool by name regardless.
+
+Alternative considered: add `dsh` to `NATURAL_LANGUAGE_SKILL_TOOLS` (like Rovo). Rejected because Rovo has no slash-like gesture at all, while dsh documents `/name`.
+
+### 5. No shared-root ownership work
+
+`.dsh/skills` is used by no other `AI_TOOLS` entry, so `shared-skill-target.ts` marker/reconciliation logic does not apply. If the same repo also generates the `.agents` target, dsh will prefer its rank-100 `.dsh/skills` tree and there is no single-writer conflict to resolve.
+
+### 6. No frontmatter or template changes
+
+OpenSpec writes `---` first line, kebab-case `name`, non-empty `description`, one-level `<name>/SKILL.md`, and extra fields such as `license`, `compatibility`, and `metadata`. The upstream parser accepts these extra fields. Tests parse every generated skill's YAML frontmatter and check required names and descriptions.
+
+## Risks / Trade-offs
+
+- [Commands-only delivery leaves dsh with zero artifacts] → Mitigation: init/update already print the existing `delivery` correction for capability-`none` tools; docs list dsh as skills-only, and the deferred capability work is the real fix.
+- [`.dsh` detection can fire on a stale empty directory after commands-only removal] → Mitigation: interactive init shows detected-but-unconfigured tools as unselected in extend mode; behavior matches Rovo and is a cosmetic pre-selection, never a forced write.
+- [dsh fail-closed parsing could silently drop skills] → Mitigation: generated files already comply; the init regression test checks frontmatter shape, and manual smoke testing against a real dsh session is in tasks.
+- [Same-name skills under `.dsh/skills` and `.agents/skills`] → Mitigation: dsh's rank ordering (100 < 200) deterministically prefers `.dsh/skills`; this is upstream behavior, documented in supported-tools.
+
+## Migration Plan
+
+No data migration is required. Reverting the entry stops future dsh detection and generation but leaves existing `.dsh/skills` files in user projects. Remove the generated `openspec-*` folders separately if rollback is needed; preserve user-authored skills. Projects using the shared `.agents` target today keep working; selecting `dsh` on a later `openspec init` writes the dedicated higher-priority root without touching `.agents`.
+
+## Open Questions
+
+_None._

openspec/changes/archive/2026-08-15-add-dsh-support/proposal.md

@@ -0,0 +1,31 @@
+## Why
+
+DeepSeek Harness discovers skills from fixed local roots, with `<project>/.dsh/skills` as its highest-priority project root. OpenSpec supports many assistants but has no dedicated target for it today, so dsh users can only use the vendor-neutral shared `.agents` target or hand-place skills — losing the dedicated `.dsh` integration.
+
+## What Changes
+
+- Add DeepSeek Harness as a supported tool with id `dsh`, `skillsDir: '.dsh'`, and directory-based auto-detection from `.dsh`.
+- Generate the OpenSpec workflow skills into `.dsh/skills/openspec-*/SKILL.md` for dsh via `openspec init --tools dsh` and `openspec update`.
+- Keep dsh skills-only: no command adapter and no `.dsh/commands/` files, because dsh has no file-based custom command surface.
+- Spell dsh skill references as `/openspec-*` (dsh supports the user `/name` gesture), matching the existing skills-only tool pattern.
+- Document dsh in the supported tools and command syntax docs.
+- Add regression tests for detection, path resolution, init, update, and invocation spelling.
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define the `.dsh` skills root and directory-based detection for DeepSeek Harness.
+
+## Impact
+
+- `src/core/config.ts` — add the `dsh` entry to `AI_TOOLS`
+- `docs/supported-tools.md` — tool row, invocation table, and `--tools` id list
+- `docs/cli.md` — supported `--tools` id list
+- `docs/commands.md`, `docs/how-commands-work.md`, `docs/troubleshooting.md` — skills-only invocation tables and notes
+- `test/core/available-tools.test.ts`, `test/core/shared/skill-paths.test.ts`, `test/core/shared/tool-detection.test.ts`, `test/core/init.test.ts`, `test/core/update.test.ts`, `test/utils/command-references.test.ts`, `test/core/command-generation/registry.test.ts` — targeted dsh coverage
+- `.changeset/add-dsh-support.md` — release note

openspec/changes/archive/2026-08-15-add-dsh-support/specs/ai-tool-paths/spec.md

@@ -0,0 +1,47 @@
+# ai-tool-paths Delta Specification
+
+## MODIFIED Requirements
+
+### 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: Kimi Code paths defined
+
+- **WHEN** looking up the `kimi` tool
+- **THEN** `skillsDir` SHALL be `.kimi-code`
+- **AND** OpenSpec-managed skills remaining under the legacy `.kimi/skills` directory SHALL be migrated to `.kimi-code/skills` during init and update, preserving user files
+
+#### Scenario: Hermes Agent paths defined
+
+- **WHEN** looking up the `hermes` tool
+- **THEN** `skillsDir` SHALL be `.hermes`
+- **AND** `setupNote` SHALL explain that project `.hermes/skills` must be added to `skills.external_dirs` in `~/.hermes/config.yaml`
+- **AND** `openspec init` and `openspec update` SHALL display the note whenever `hermes` is configured
+
+#### Scenario: DeepSeek Harness paths defined
+
+- **WHEN** looking up the `dsh` tool
+- **THEN** `skillsDir` SHALL be `.dsh`
+- **AND** auto-detection SHALL require `.dsh` to be a directory
+- **AND** OpenSpec SHALL write dsh skills under `<projectRoot>/.dsh/skills/` using platform-native path joining
+
+#### Scenario: Tools without skillsDir
+
+- **WHEN** a tool has no `skillsDir` defined
+- **THEN** skill generation SHALL error with message indicating the tool is not supported

openspec/changes/archive/2026-08-15-add-dsh-support/tasks.md

@@ -0,0 +1,30 @@
+## 1. Tool Metadata
+
+- [x] 1.1 Add the `DeepSeek Harness` entry to `AI_TOOLS` in `src/core/config.ts` with `value: 'dsh'` and `skillsDir: '.dsh'`, using the existing directory-based detection
+- [x] 1.2 Verify no other production code changes are required: init selection, `--tools` help, command surface capability, update drift, and shared-root handling must all derive from the new metadata
+
+## 2. Detection and Path Tests
+
+- [x] 2.1 Add `test/core/available-tools.test.ts` cases: detect `dsh` from `.dsh/skills` and from a bare `.dsh` directory; do not detect when neither exists or `.dsh` is a regular file
+- [x] 2.2 Add a `test/core/shared/skill-paths.test.ts` case resolving `dsh` to `path.join(root, '.dsh', 'skills')`
+- [x] 2.3 Add `test/core/shared/tool-detection.test.ts` cases: `getToolsWithSkillsDir()` includes `dsh`; skill status and configured-tool detection work for `.dsh/skills/openspec-*/SKILL.md`
+
+## 3. Generation and Update Tests
+
+- [x] 3.1 Add an `InitCommand` regression in `test/core/init.test.ts`: `--tools dsh` writes `.dsh/skills/openspec-explore/SKILL.md`, creates no `.dsh/commands`, logs the no-adapter skip, uses `/openspec-*` references in skill bodies and the getting-started hint, and the generated frontmatter satisfies dsh parsing (leading `---`, kebab-case name, non-empty description)
+- [x] 3.2 Add an `UpdateCommand` regression in `test/core/update.test.ts`: refresh a stale dsh skill and verify a second update is idempotent
+- [x] 3.3 Add `test/utils/command-references.test.ts` coverage that dsh uses the default `/openspec-*` form, and `test/core/command-generation/registry.test.ts` coverage that dsh has no command adapter
+
+## 4. Documentation
+
+- [x] 4.1 Update `docs/supported-tools.md`: add the dsh tool row, add dsh to the skills-only invocation row and the `--tools` id list, and explain that dsh reads `.dsh/skills` at higher priority than `.agents/skills`
+- [x] 4.2 Update the supported `--tools` id list in `docs/cli.md`
+- [x] 4.3 Update the skills-only syntax tables in `docs/commands.md` and `docs/how-commands-work.md`, and the skills-only tool list in `docs/troubleshooting.md`
+
+## 5. Release and Validation
+
+- [x] 5.1 Add `.changeset/add-dsh-support.md` with a minor bump describing `openspec init --tools dsh`
+- [x] 5.2 Run `pnpm run lint`, `pnpm run build`, and the targeted vitest files for detection, paths, init, update, and command references
+- [x] 5.3 Run the full test suite (`pnpm test`) and confirm cross-platform path assertions pass on Windows (no hardcoded separators in new tests)
+- [x] 5.4 Run `openspec validate` for this change and fix any spec or change validation issues
+- [x] 5.5 Manual smoke test in a temporary git project: `openspec init --tools dsh`, confirm `.dsh/skills/openspec-*/SKILL.md` files, start a dsh session and confirm the skills appear in the catalog and load via the skill tool or `/openspec-propose`

openspec/changes/fix-windows-archive-claim-release/.openspec.yaml

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

openspec/changes/fix-windows-archive-claim-release/proposal.md

@@ -0,0 +1,28 @@
+# Release archive claims on Windows
+
+## Why
+
+`openspec archive` creates `.openspec-archive.lock` before moving a change into
+the archive. On Windows, a successful archive can leave that lock behind because
+the cleanup check compares the device id returned by the open file handle with
+the one returned by `fs.lstat()`. Node reports a real device id from the handle
+and `0n` from the path stat on the affected Windows/NTFS setup, so the ownership
+check never passes.
+
+The archive itself succeeds, but the next archive is blocked by the stale claim
+and the user has to delete `.openspec-archive.lock` by hand.
+
+## What Changes
+
+- Treat an inode match plus matching claim contents as sufficient when either
+  side reports `dev: 0n`, while still requiring the two path stats around the
+  read to match.
+- Keep the existing protection against deleting a claim that was replaced by
+  another process.
+- Add a regression test that simulates the Windows path-stat device id behavior.
+
+## Impact
+
+- Affected spec: `cli-archive`
+- Affected code: `src/core/archive.ts`
+- Affected tests: `test/core/archive.test.ts`

openspec/changes/fix-windows-archive-claim-release/specs/cli-archive/spec.md

@@ -0,0 +1,36 @@
+## MODIFIED Requirements
+
+### Requirement: Archive Process
+
+The archive operation SHALL follow a structured process to safely move changes to the archive.
+
+#### Scenario: Performing archive
+
+- **WHEN** archiving a change
+- **THEN** execute these steps:
+  1. Create archive/ directory if it doesn't exist
+  2. Generate target name as `YYYY-MM-DD-[change-name]` using current date, keeping the name as-is when it already starts with a `YYYY-MM-DD-` prefix
+  3. Claim the target and verify that it does not already exist
+  4. Prepare and validate spec updates from the active change's delta specs
+  5. Apply the spec updates as a rollback-capable transaction
+  6. Move the entire change directory to the archive location
+  7. If a spec mutation or final move fails before a complete archive is secured, restore the spec transaction and leave or return the change at its active path
+  8. If a verified fallback copy completes but staged-source cleanup fails, retain the complete archive and committed spec state for recovery instead of risking the only complete copy
+
+#### Scenario: Archive already exists
+
+- **WHEN** target archive already exists
+- **THEN** fail with error message
+- **AND** do not overwrite existing archive
+
+#### Scenario: Successful archive
+
+- **WHEN** move succeeds
+- **THEN** display success message with archived name and list of updated specs
+
+#### Scenario: Successful archive releases its own claim
+
+- **WHEN** an archive run successfully moves a change to its archive destination
+- **THEN** remove the temporary archive claim it created
+- **AND** do so on supported platforms even when a path stat does not report a device id
+- **AND** never remove a claim whose path identity or contents changed before cleanup

openspec/changes/fix-windows-archive-claim-release/tasks.md

@@ -0,0 +1,12 @@
+# Tasks
+
+## 1. Release owned claims cross-platform
+- [x] 1.1 Compare archive claim files by inode and tolerate a missing device id from either stat result
+- [x] 1.2 Preserve the content and repeated-path-stat checks before unlinking
+
+## 2. Verify behavior
+- [x] 2.1 Add regression coverage for the Windows `dev: 0n` path-stat case
+- [x] 2.2 Run the focused archive regression test
+
+## 3. Record behavior
+- [x] 3.1 Add a `cli-archive` spec delta for successful claim cleanup

openspec/changes/rename-bob-to-ibm-bob/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-25

openspec/changes/rename-bob-to-ibm-bob/proposal.md

@@ -0,0 +1,25 @@
+## Why
+
+OpenSpec labels the `bob` integration as "Bob Shell," but the same `.bob` configuration root serves the IBM Bob product. The narrower name makes the tool picker and status output look limited to the CLI.
+
+## What Changes
+
+- Rename the `bob` tool entry and success label to "IBM Bob."
+- Update the supported-tools reference to use the product name.
+- Preserve `.bob/commands/` generation for Bob Shell, which still supports custom slash commands.
+
+## Capabilities
+
+### New Capabilities
+
+- None.
+
+### Modified Capabilities
+
+- `ai-tool-paths`: Use "IBM Bob" as the user-facing name for the `bob` integration.
+
+## Impact
+
+- Affected code: `src/core/config.ts` and its tool-detection test.
+- Affected docs: `docs-lab/reference/supported-tools.md`.
+- Command and skill paths do not change.

openspec/changes/rename-bob-to-ibm-bob/specs/ai-tool-paths/spec.md

@@ -0,0 +1,12 @@
+## ADDED Requirements
+
+### Requirement: IBM Bob tool identity
+
+The `AI_TOOLS` entry for `bob` SHALL use the IBM Bob product name without changing its skill or command paths.
+
+#### Scenario: IBM Bob paths and display name
+
+- **WHEN** looking up the `bob` tool
+- **THEN** `name` and `successLabel` SHALL be `IBM Bob`
+- **AND** `skillsDir` SHALL be `.bob`
+- **AND** generated commands SHALL remain under `.bob/commands/`

openspec/changes/rename-bob-to-ibm-bob/tasks.md

@@ -0,0 +1,6 @@
+## 1. Implementation
+
+- [x] 1.1 Rename the `bob` tool entry and success label to "IBM Bob."
+- [x] 1.2 Keep the Bob command adapter and existing command paths unchanged.
+- [x] 1.3 Update the docs-lab supported-tools reference.
+- [x] 1.4 Cover the user-facing name in a tool-detection test.

openspec/specs/ai-tool-paths/spec.md

@@ -56,6 +56,31 @@ The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent
 - **AND** `setupNote` SHALL explain that project `.hermes/skills` must be added to `skills.external_dirs` in `~/.hermes/config.yaml`
 - **AND** `openspec init` and `openspec update` SHALL display the note whenever `hermes` is configured
 
+#### Scenario: DeepSeek Harness paths defined
+
+- **WHEN** looking up the `dsh` tool
+- **THEN** `skillsDir` SHALL be `.dsh`
+- **AND** auto-detection SHALL require `.dsh` to be a directory
+- **AND** OpenSpec SHALL write dsh skills under `<projectRoot>/.dsh/skills/` using platform-native path joining
+
+#### Scenario: Grok Build paths defined
+
+- **WHEN** looking up the `grok` tool
+- **THEN** `skillsDir` SHALL be `.grok`
+
+#### Scenario: Warp paths and detection defined
+
+- **WHEN** looking up the `warp` tool
+- **THEN** `skillsDir` SHALL be `.warp`
+- **AND** `detectionPaths` SHALL include `.warp` and `WARP.md`
+
+#### Scenario: Warp invokes skills without command files
+
+- **WHEN** generating workflows for the `warp` tool with delivery set to `commands`
+- **THEN** skills SHALL remain installed in `.warp/skills/`
+- **AND** no command adapter or command files SHALL be required
+- **AND** each skill SHALL be directly invocable by its `/openspec-*` name
+
 #### Scenario: Tools without skillsDir
 
 - **WHEN** a tool has no `skillsDir` defined

openspec/specs/artifact-graph/spec.md

@@ -53,6 +53,10 @@ The system SHALL compute a valid topological build order for artifacts.
 ### Requirement: State Detection
 The system SHALL detect artifact completion state by scanning the filesystem.
 
+The system SHALL recognize `generates` values containing `*`, `?`, or `[` as glob patterns. It SHALL also support brace alternatives, brace ranges, and the `@()`, `+()`, `!()`, `*()`, and `?()` extglob forms. An artifact with a glob output SHALL be completed when at least one matching file exists.
+
+The system SHALL preserve literal filenames with a bare leading `!`, plain parentheses, or single-element braces when no supported glob syntax is present. Brace expansion SHALL preserve literal brace groups and recognize later and nested expansion groups. Expanded output paths and traversed symbolic links SHALL remain within the change directory.
+
 #### Scenario: Simple file exists
 - **WHEN** an artifact generates "proposal.md" and the file exists
 - **THEN** the artifact is marked as completed
@@ -73,6 +77,48 @@ The system SHALL detect artifact completion state by scanning the filesystem.
 - **WHEN** the change directory does not exist
 - **THEN** all artifacts are marked as not completed (empty state)
 
+#### Scenario: Brace alternatives with matching files
+- **WHEN** an artifact generates "review-{api,ui}.md" and "review-api.md" exists
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Brace range after a literal brace group
+- **WHEN** an artifact generates "report-{draft}-{1..3}.md"
+- **AND** "report-{draft}-1.md", "report-{draft}-2.md", "report-{draft}-3.md", and "report-{draft}-4.md" exist
+- **THEN** its resolved outputs contain exactly the first three files
+- **AND** the artifact is marked as completed
+
+#### Scenario: Later and nested brace alternatives
+- **WHEN** an artifact generates "report-{draft}-{{api},ui}.md" and "report-{draft}-{api}.md" exists
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Extglob alternatives with matching files
+- **WHEN** an artifact generates "@(proposal|design).md" or "+(proposal|design).md" and "proposal.md" exists
+- **THEN** the artifact is marked as completed
+
+#### Scenario: Negative extglob excludes its alternatives
+- **WHEN** an artifact generates "!(proposal|design).md"
+- **AND** "proposal.md", "design.md", and "notes.md" exist
+- **THEN** its resolved outputs contain only "notes.md"
+- **AND** the artifact is marked as completed
+
+#### Scenario: Brace or extglob pattern without matching files
+- **WHEN** an artifact generates "review-{api,ui}.md" or "@(proposal|design).md" and no matching files exist
+- **THEN** the artifact is not marked as completed
+
+#### Scenario: Literal output names remain literal
+- **WHEN** an artifact generates "!review.md", "(proposal|design).md", or "review-{api}.md"
+- **THEN** completion depends on the existence of a file with that exact name
+
+#### Scenario: Brace expansion escapes the change directory
+- **WHEN** an artifact generates "{safe,../outside}/review.md"
+- **THEN** output resolution rejects the expanded path outside the change directory before matching files
+- **AND** rejection does not depend on whether the outside file exists
+
+#### Scenario: Expanded directory pattern reaches an outbound symbolic link
+- **WHEN** an artifact generates "content/{safe,linked}/review.md" or "content/@(safe|linked)/review.md"
+- **AND** "content/linked" is a symbolic link to a directory outside the change directory
+- **THEN** output resolution rejects traversal through that link even when no matching files exist
+
 ### Requirement: Ready Artifact Query
 The system SHALL identify which artifacts are ready to be created based on dependency completion.
 
@@ -137,4 +183,3 @@ The system SHALL support self-contained schema directories with co-located templ
 #### Scenario: List available schemas
 - **WHEN** listing schemas
 - **THEN** the system returns schema names from both user and package directories
-

openspec/specs/cli-artifact-workflow/spec.md

@@ -183,17 +183,6 @@ The system SHALL provide consistent output formatting.
 - **WHEN** loading change state takes time
 - **THEN** the system displays a spinner during loading
 
-### Requirement: Experimental Isolation
-The system SHALL implement artifact workflow commands in isolation for easy removal.
-
-#### Scenario: Single file implementation
-- **WHEN** artifact workflow feature is implemented
-- **THEN** all commands are in `src/commands/artifact-workflow.ts`
-
-#### Scenario: Help text marking
-- **WHEN** user runs `--help` on any artifact workflow command
-- **THEN** help text indicates the command is experimental
-
 ### Requirement: Schema Apply Block
 
 The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.

openspec/specs/cli-config/spec.md

@@ -182,9 +182,9 @@ The `openspec config profile` command SHALL provide an action-first interactive
 
 - **WHEN** user runs `openspec config profile` interactively
 - **THEN** the first prompt SHALL offer:
-  - `Change delivery + workflows`
-  - `Change delivery only`
-  - `Change workflows only`
+  - `Delivery and workflows`
+  - `Delivery only`
+  - `Workflows only`
   - `Keep current settings (exit)`
 
 #### Scenario: Delivery prompt marks current selection

openspec/specs/cli-init/spec.md

@@ -231,6 +231,12 @@ The command SHALL generate opsx slash commands only for selected tools that have
 - **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi-code'`
 - **AND** command-file generation SHALL be skipped because no Kimi adapter is registered
 
+#### Scenario: Grok Build skips command-file generation
+
+- **WHEN** the user selects Grok Build during initialization
+- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.grok'`
+- **AND** command-file generation SHALL be skipped because no Grok adapter is registered
+
 ### Requirement: Config File Generation
 
 The command SHALL create an OpenSpec config file with schema settings.

openspec/specs/cli-update/spec.md

@@ -117,7 +117,7 @@ The update command SHALL refresh existing slash command files for configured too
 - **AND** skip creating missing files (the update command only refreshes what already exists)
 
 #### Scenario: Updating slash commands for Kilo Code
-- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** `.kilo/command/` contains OpenSpec-managed `opsx-*.md` command files for the configured profile
 - **THEN** refresh each file using shared templates wrapped in OpenSpec markers
 - **AND** ensure templates include instructions for the relevant workflow stage
 - **AND** skip creating missing files (the update command only refreshes what already exists)

openspec/specs/cli-view/spec.md

@@ -45,6 +45,35 @@ The dashboard SHALL show active changes with visual progress indicators.
 - **AND** treat missing progress values as 0% for ordering
 - **AND** break ties by change identifier in ascending alphabetical order to keep output deterministic
 
+### Requirement: Active Change Workflow Status
+
+The dashboard SHALL show each active change's schema and artifact states beneath its task progress, using the same workflow resolution as `openspec status`. Workflow status SHALL NOT change task progress, change categories, or sorting.
+
+#### Scenario: Workflow states
+
+- **WHEN** an active change's workflow can be loaded
+- **THEN** show the schema name and artifacts in dependency order
+- **AND** mark existing artifact outputs with `✓`, ready artifacts with `→`, blocked artifacts with no symbol, and skipped artifacts with `(skipped)`
+- **AND** treat an existing tasks artifact as done even when its implementation checklist is unfinished
+
+#### Scenario: Store-local workflow
+
+- **WHEN** the dashboard targets a store through `--store` or a project store pointer
+- **THEN** resolve workflow schemas and artifact files from that store
+- **AND** use the store's default schema for changes without a schema in their metadata
+
+#### Scenario: Invalid workflow
+
+- **WHEN** an active change's metadata or schema cannot be loaded
+- **THEN** print a warning identifying the change and the error
+- **AND** omit only that change's workflow status while retaining its task progress and rendering other changes
+
+#### Scenario: Terminal controls in workflow text
+
+- **WHEN** schema names, artifact identifiers, or workflow errors contain terminal control characters
+- **THEN** replace those characters with inert text in the dashboard output
+- **AND** preserve the underlying identifiers and workflow states
+
 ### Requirement: Completed Changes Display
 
 The dashboard SHALL list completed changes in a separate section, only showing changes with ALL tasks completed.
@@ -126,4 +155,3 @@ The dashboard SHALL display changes without tasks in a separate "Draft" section.
 
 - **WHEN** multiple draft changes exist
 - **THEN** system sorts them alphabetically by name
-

openspec/specs/legacy-cleanup/spec.md

@@ -32,6 +32,13 @@ The system SHALL detect legacy OpenSpec artifacts from previous init versions.
   - `.windsurf/workflows/openspec-*.md`
   - And equivalent directories for all tools in the legacy SlashCommandRegistry
 
+#### Scenario: Detecting legacy Kilo Code workflows
+
+- **WHEN** `.kilocode/workflows/` contains OpenSpec-managed `opsx-*.md` or `openspec-*.md` workflow files
+- **THEN** `openspec init` or legacy cleanup SHALL remove those files
+- **AND** Kilo Code commands SHALL be generated under `.kilo/command/`
+- **AND** `openspec update` SHALL NOT refresh files that remain only under `.kilocode/workflows/`
+
 #### Scenario: Detecting legacy OpenSpec structure files
 
 - **WHEN** running `openspec init` on an existing project
@@ -160,4 +167,3 @@ The system SHALL report what was cleaned up.
 - **WHEN** no legacy artifacts are found
 - **THEN** the system SHALL NOT display the cleanup section
 - **AND** proceed directly with skill setup
-

openspec/specs/openspec-conventions/spec.md

@@ -99,8 +99,8 @@ Requirement headers SHALL serve as unique identifiers for programmatic matching
 
 - **WHEN** processing delta changes
 - **THEN** use the `### Requirement: [Name]` header as the unique identifier
-- **AND** match using normalized headers: `normalize(header) = trim(header)`
-- **AND** compare headers with case-sensitive equality after normalization
+- **AND** strip a closing run of `#` characters when a space or tab precedes it and only spaces or tabs follow it, then trim surrounding whitespace
+- **AND** compare normalized requirement names with case-sensitive equality
 
 #### Scenario: Handling requirement renames