Version Packages (#1295)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.changeset/README.md

@@ -12,11 +12,12 @@ Follow the prompts to select version bump type and describe your changes.
 
 ## Workflow
 
-1. **Add a changeset** — Run `pnpm changeset` locally before or after your PR
-2. **Version PR** — CI opens/updates a "Version Packages" PR when changesets merge to main
-3. **Release** — Merging the Version PR triggers npm publish and GitHub Release
+1. **Choose the release path**: Maintainers decide whether a PR follows the normal release cadence or gets dedicated release tracking.
+2. **Add dedicated release tracking**: When a maintainer asks for a changeset, run `pnpm changeset` locally before or after your PR.
+3. **Version PR**: CI opens/updates a "Version Packages" PR when changesets merge to main.
+4. **Release**: Merging the Version PR triggers npm publish and GitHub Release.
 
-> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI.
+> **Note:** The default path is the normal release cadence. Add a changeset when a maintainer or release owner wants dedicated release notes and version tracking for the PR. Versioning (`changeset version`) and publishing happen automatically in CI.
 
 ## Template
 
@@ -54,22 +55,23 @@ Include only the sections relevant to your change.
 
 | Type | When to use | Example |
 |------|-------------|---------|
-| `patch` | Bug fixes, small improvements | Fixed crash when config missing |
+| `patch` | Release-tracked bug fixes, small improvements | Fixed crash when config missing |
 | `minor` | New features, non-breaking additions | Added `--verbose` flag |
 | `major` | Breaking changes, removed features | Renamed `init` to `setup` |
 
 ## When to Create a Changeset
 
-**Create one for:**
-- New features or commands
-- Bug fixes that affect users
+**Use dedicated release tracking for:**
+- New features or commands selected for release
+- Notable bug fixes or hotfixes requested by a maintainer/release owner
 - Breaking changes or deprecations
-- Performance improvements users would notice
+- Performance improvements users would notice and that are planned for release
 
-**Skip for:**
+**Use the normal release cadence for:**
+- Routine bug fixes that fit the normal release cadence
 - Documentation-only changes
 - Test additions/fixes
-- Internal refactoring with no user impact
+- Internal refactoring that preserves user behavior
 - CI/tooling changes
 
 ## Writing Good Descriptions

.changeset/nix-flake-improvements.md

@@ -1,13 +0,0 @@
----
-"@fission-ai/openspec": patch
----
-
-### Improvements
-
-- **Nix flake maintenance** — Version now read dynamically from package.json, reducing manual sync issues
-- **Nix build optimization** — Source filtering excludes node_modules and artifacts, improving build times
-- **update-flake.sh script** — Detects when hash is already correct, skipping unnecessary rebuilds
-
-### Other
-
-- Updated Nix CI actions to latest versions (nix-installer v21, magic-nix-cache v13)

.github/workflows/ci.yml

@@ -3,6 +3,8 @@ name: CI
 on:
   pull_request:
     branches: [main]
+  merge_group:
+    branches: [main]
   push:
     branches: [main]
   workflow_dispatch:
@@ -38,50 +40,11 @@ jobs:
               - 'scripts/update-flake.sh'
               - '.github/workflows/ci.yml'
 
-  test_pr:
-    name: Test
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    if: github.event_name == 'pull_request'
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build project
-        run: pnpm run build
-
-      - name: Run tests
-        run: pnpm test
-
-      - name: Upload test coverage
-        uses: actions/upload-artifact@v4
-        with:
-          name: coverage-report-pr
-          path: coverage/
-          retention-days: 7
-
   test_matrix:
     name: Test (${{ matrix.label }})
     runs-on: ${{ matrix.os }}
     timeout-minutes: 15
-    if: github.event_name != 'pull_request'
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group' || github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     strategy:
       fail-fast: false
       matrix:
@@ -89,12 +52,15 @@ jobs:
           - os: ubuntu-latest
             shell: bash
             label: linux-bash
+            vitest_workers: 4
           - os: macos-latest
             shell: bash
             label: macos-bash
+            vitest_workers: 4
           - os: windows-latest
             shell: pwsh
             label: windows-pwsh
+            vitest_workers: 2
 
     defaults:
       run:
@@ -108,13 +74,11 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '20.19.0'
           cache: 'pnpm'
 
       - name: Print environment diagnostics
@@ -128,16 +92,32 @@ jobs:
         run: pnpm run build
 
       - name: Run tests
+        env:
+          VITEST_MAX_WORKERS: ${{ matrix.vitest_workers }}
         run: pnpm test
 
       - name: Upload test coverage
         if: matrix.os == 'ubuntu-latest'
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-report-main
+          name: coverage-report-${{ github.event_name }}
           path: coverage/
           retention-days: 7
 
+  test_pr_required:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [test_matrix]
+    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
+    steps:
+      - name: Verify matrix tests passed
+        run: |
+          if [[ "${{ needs.test_matrix.result }}" != "success" ]]; then
+            echo "Matrix test job failed"
+            exit 1
+          fi
+          echo "All matrix tests passed!"
+
   lint:
     name: Lint & Type Check
     runs-on: ubuntu-latest
@@ -147,13 +127,11 @@ jobs:
 
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '20.19.0'
           cache: 'pnpm'
 
       - name: Install dependencies
@@ -240,68 +218,86 @@ jobs:
         run: git checkout -- flake.nix || true
 
   validate-changesets:
-    name: Validate Changesets
+    name: Validate Release Tracking
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
+      - name: Determine release tracking
+        id: changed-changesets
+        run: |
+          changed_changesets="$(git diff --name-only --diff-filter=ACMRT origin/main...HEAD -- '.changeset/*.md' ':!.changeset/README.md')"
+          if [[ -n "$changed_changesets" ]]; then
+            echo "has_changesets=true" >> "$GITHUB_OUTPUT"
+            {
+              echo "files<<EOF"
+              echo "$changed_changesets"
+              echo "EOF"
+            } >> "$GITHUB_OUTPUT"
+          else
+            echo "has_changesets=false" >> "$GITHUB_OUTPUT"
+            echo "This PR follows the normal release cadence; continuing with standard validation"
+          fi
+
       - name: Setup pnpm
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
         uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - name: Setup Node.js
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '20.19.0'
           cache: 'pnpm'
 
       - name: Install dependencies
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
         run: pnpm install --frozen-lockfile
 
-      - name: Validate changesets
+      - name: Validate release-tracked changesets
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
+        env:
+          CHANGESET_FILES: ${{ steps.changed-changesets.outputs.files }}
         run: |
-          if command -v changeset &> /dev/null; then
-            pnpm exec changeset status --since=origin/main
-          else
-            echo "Changesets not configured, skipping validation"
-          fi
+          echo "Validating changed changesets:"
+          printf '%s\n' "$CHANGESET_FILES"
+          pnpm exec changeset status --since=origin/main
 
   required-checks-pr:
-    name: All checks passed
-    runs-on: ubuntu-latest
-    needs: [test_pr, lint, nix-flake-validate]
-    if: always() && github.event_name == 'pull_request'
-    steps:
-      - name: Verify all checks passed
-        run: |
-          if [[ "${{ needs.test_pr.result }}" != "success" ]]; then
-            echo "Test job failed"
-            exit 1
-          fi
-          if [[ "${{ needs.lint.result }}" != "success" ]]; then
-            echo "Lint job failed"
-            exit 1
-          fi
-          # Nix validation may be skipped if no Nix-related files changed
-          if [[ "${{ needs.nix-flake-validate.result }}" != "success" && "${{ needs.nix-flake-validate.result }}" != "skipped" ]]; then
-            echo "Nix flake validation job failed"
-            exit 1
-          fi
-          if [[ "${{ needs.nix-flake-validate.result }}" == "skipped" ]]; then
-            echo "Nix flake validation skipped (no Nix-related changes)"
-          fi
-          echo "All required checks passed!"
-
-  required-checks-main:
     name: All checks passed
     runs-on: ubuntu-latest
     needs: [test_matrix, lint, nix-flake-validate]
-    if: always() && github.event_name != 'pull_request'
+    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
+    steps:
+      - name: Verify all checks passed
+        run: |
+          if [[ "${{ needs.test_matrix.result }}" != "success" ]]; then
+            echo "Matrix test job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.lint.result }}" != "success" ]]; then
+            echo "Lint job failed"
+            exit 1
+          fi
+          # Nix validation may be skipped if no Nix-related files changed
+          if [[ "${{ needs.nix-flake-validate.result }}" != "success" && "${{ needs.nix-flake-validate.result }}" != "skipped" ]]; then
+            echo "Nix flake validation job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.nix-flake-validate.result }}" == "skipped" ]]; then
+            echo "Nix flake validation skipped (no Nix-related changes)"
+          fi
+          echo "All required checks passed!"
+
+  required-checks-main:
+    name: All checks passed
+    runs-on: ubuntu-latest
+    needs: [test_matrix, lint, nix-flake-validate]
+    if: always() && github.event_name == 'push'
     steps:
       - name: Verify all checks passed
         run: |

.github/workflows/deploy-docs.yml

@@ -0,0 +1,76 @@
+name: Docs site
+
+# The documentation site (website/) mirrors docs/*.md via scripts/sync-docs.mjs,
+# which runs as the first step of `pnpm run build`. This workflow rebuilds that
+# mirror:
+#   - on every push to main that touches docs/ or website/,
+#   - manually via the Actions tab,
+#   - and as a build-only check on pull requests.
+#
+# The Cloudflare Pages deploy step is temporarily disabled until setup is ready.
+# When re-enabled, deploys require two repository secrets: CLOUDFLARE_API_TOKEN
+# and CLOUDFLARE_ACCOUNT_ID. Set the site's public URL via the DOCS_SITE_URL
+# repository variable (used for OG/sitemap absolute URLs).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - '.github/workflows/deploy-docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+# Never run two docs site jobs at once; let an in-flight job finish.
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    # Keep enabled forks from spending CI on their own copy of this workflow.
+    # PRs from forks into Fission-AI/OpenSpec still run in the base repository.
+    if: ${{ github.repository == 'Fission-AI/OpenSpec' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: pnpm
+          cache-dependency-path: website/pnpm-lock.yaml
+
+      - name: Install dependencies
+        working-directory: website
+        run: pnpm install --frozen-lockfile
+
+      - name: Build site (mirrors docs/*.md, then next build)
+        working-directory: website
+        env:
+          NEXT_PUBLIC_SITE_URL: ${{ vars.DOCS_SITE_URL }}
+        run: pnpm run build
+
+      # Temporarily disabled until Cloudflare setup is ready.
+      # - name: Deploy to Cloudflare Pages
+      #   # Only deploy from main on the canonical repo. This keeps PRs build-only,
+      #   # keeps forks (no secrets) build-only, and because the wrangler command
+      #   # below hardcodes `--branch=main` (a *production* deploy) prevents a
+      #   # `workflow_dispatch` on a feature branch from overwriting the live site.
+      #   if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' && github.repository == 'Fission-AI/OpenSpec' }}
+      #   uses: cloudflare/wrangler-action@v3
+      #   with:
+      #     apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      #     accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+      #     workingDirectory: website
+      #     command: pages deploy out --project-name=openspec-docs --branch=main

.github/workflows/release-prepare.yml

@@ -1,8 +1,9 @@
-name: Release (prepare)
+name: Release
 
 on:
   push:
     branches: [main]
+  workflow_dispatch: # manually cut a beta prerelease from main
 
 permissions:
   contents: write
@@ -15,7 +16,7 @@ concurrency:
 
 jobs:
   prepare:
-    if: github.repository == 'Fission-AI/OpenSpec'
+    if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'push'
     runs-on: ubuntu-latest
     steps:
       # Generate GitHub App token first - used for checkout and changesets
@@ -34,8 +35,6 @@ jobs:
           token: ${{ steps.app-token.outputs.token }}
 
       - uses: pnpm/action-setup@v4
-        with:
-          version: 9
 
       - uses: actions/setup-node@v4
         with:
@@ -58,3 +57,126 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           # npm authentication handled via OIDC trusted publishing (no token needed)
+
+  # Manually-dispatched beta prerelease from main: version is the next stable
+  # release per pending changesets with a -beta.N suffix (e.g. v1.6.0-beta.1),
+  # published to npm under the `beta` dist-tag and posted as a prerelease-flagged
+  # GitHub Release. Changesets are left unconsumed, so the stable flow above is
+  # unaffected. This job lives in this file because npm trusted publishing
+  # authorizes a single workflow file per package.
+  #
+  # Users opt in with: npm install -g @fission-ai/openspec@beta
+  beta:
+    if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24' # Node 24 includes npm 11.5.1+ required for OIDC
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: pnpm install --frozen-lockfile
+
+      # Beta version = next stable version per pending changesets, plus a
+      # -beta.N suffix that increments over existing beta tags for that version.
+      - name: Compute beta version
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          git fetch --tags --force origin
+          pnpm exec changeset status --output=changeset-status.json
+          NEXT=$(node -p "JSON.parse(require('fs').readFileSync('changeset-status.json','utf8')).releases[0]?.newVersion ?? ''")
+          rm changeset-status.json
+          if [ -z "$NEXT" ]; then
+            echo "No pending changesets on main - nothing to cut a beta from."
+            exit 1
+          fi
+          N=1
+          while true; do
+            VERSION="${NEXT}-beta.${N}"
+            TAG="v${VERSION}"
+            TAG_EXISTS=false
+            NPM_EXISTS=false
+            RELEASE_EXISTS=false
+
+            if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+              TAG_EXISTS=true
+            fi
+            if npm view "@fission-ai/openspec@${VERSION}" version >/dev/null 2>&1; then
+              NPM_EXISTS=true
+            fi
+            if gh release view "${TAG}" >/dev/null 2>&1; then
+              RELEASE_EXISTS=true
+            fi
+
+            if [ "$TAG_EXISTS" = false ] && [ "$NPM_EXISTS" = false ] && [ "$RELEASE_EXISTS" = false ]; then
+              break
+            fi
+            if [ "$RELEASE_EXISTS" = false ]; then
+              echo "Resuming incomplete beta ${TAG}"
+              break
+            fi
+
+            N=$((N + 1))
+          done
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Cutting ${TAG}"
+
+      - name: Set package version
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: npm version "$VERSION" --no-git-tag-version
+
+      # prepublishOnly runs the build. npm authentication handled via OIDC
+      # trusted publishing (no token needed).
+      - name: Publish to npm under the beta dist-tag
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          if npm view "@fission-ai/openspec@${VERSION}" version >/dev/null 2>&1; then
+            echo "@fission-ai/openspec@${VERSION} is already on npm; skipping publish."
+            exit 0
+          fi
+          npm publish --tag beta
+
+      - name: Tag and create GitHub prerelease
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          TAG="v${VERSION}"
+          HEAD_SHA=$(git rev-parse HEAD)
+
+          if git rev-parse -q --verify "refs/tags/${TAG}" >/dev/null; then
+            TAG_SHA=$(git rev-list -n 1 "${TAG}")
+            if [ "$TAG_SHA" != "$HEAD_SHA" ]; then
+              echo "${TAG} already exists at ${TAG_SHA}, not current HEAD ${HEAD_SHA}."
+              exit 1
+            fi
+          else
+            git tag "${TAG}"
+          fi
+
+          if git ls-remote --exit-code --tags origin "refs/tags/${TAG}" >/dev/null 2>&1; then
+            echo "${TAG} already exists on origin; skipping tag push."
+          else
+            git push origin "${TAG}"
+          fi
+
+          if gh release view "${TAG}" >/dev/null 2>&1; then
+            echo "GitHub Release ${TAG} already exists; skipping release creation."
+          else
+            gh release create "${TAG}" \
+              --prerelease \
+              --generate-notes \
+              --title "${TAG}" \
+              --notes "Beta prerelease. Install with \`npm install -g @fission-ai/openspec@beta\`."
+          fi

.gitignore

@@ -148,4 +148,18 @@ CLAUDE.md
 
 # Pnpm
 .pnpm-store/
+/package-lock.json
 result
+
+# OpenCode
+.opencode/
+opencode.json
+
+# Codex
+.codex/
+
+# Bob
+.bob/
+
+# Trae
+.trae/

CHANGELOG.md

@@ -1,5 +1,198 @@
 # @fission-ai/openspec
 
+## 1.6.0
+
+### Minor Changes
+
+- [#1090](https://github.com/Fission-AI/OpenSpec/pull/1090) [`3f0ca3f`](https://github.com/Fission-AI/OpenSpec/commit/3f0ca3f6ce6f2ec41260c5cbe7954b7e46adcf43) Thanks [@jjxyxsjr](https://github.com/jjxyxsjr)! - ### New Features
+
+  - **TRAE command adapter** — Added command adapter for Trae IDE, enabling generation of `.trae/commands/opsx-<id>.md` files for custom slash commands
+
+- [#1340](https://github.com/Fission-AI/OpenSpec/pull/1340) [`1552731`](https://github.com/Fission-AI/OpenSpec/commit/15527310f9be13cc9a4035ea01b93ba85873d956) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Oh My Pi support** — Generate native OPSX commands and skills for Oh My Pi projects, including tool detection and the expected `.omp` directory layout.
+  - **Update planning artifacts in place** — Use `/opsx:update` to revise an existing change's planning artifacts, reconcile related artifacts, and keep implementation work delegated to `/opsx:apply`.
+
+  ### Bug Fixes
+
+  - **Fresh store registration** — Register and use newly created stores before their empty changes, specs, or archive directories have been committed.
+  - **Safer requirement archiving** — Stop stale `MODIFIED` requirements from silently deleting scenarios that were added by an earlier archive.
+
+### Patch Changes
+
+- [#1300](https://github.com/Fission-AI/OpenSpec/pull/1300) [`a5bfeda`](https://github.com/Fission-AI/OpenSpec/commit/a5bfedafc8b3d914fe01d05eb36ad9ad3fbe35a2) Thanks [@clay-good](https://github.com/clay-good)! - ### Features
+
+  - **Auto-approve the OpenSpec CLI in generated skills and commands** — every generated `SKILL.md` (all tools) and every Claude Code `/opsx:*` slash command now carries `allowed-tools: Bash(openspec:*)` in its frontmatter, so agents that honor the Agent Skills standard run `openspec` commands without prompting for approval on each call; tools that don't recognize the field ignore it. Scope is limited to the `openspec` CLI; because `allowed-tools` pre-approves rather than restricts, every other tool a skill or command uses stays available under your normal permission settings.
+
+- [#1311](https://github.com/Fission-AI/OpenSpec/pull/1311) [`5956a8e`](https://github.com/Fission-AI/OpenSpec/commit/5956a8e872f41a8f690922b5c9b6927970252b2a) Thanks [@danilopopeye](https://github.com/danilopopeye)! - ### Bug Fixes
+
+  - **`archive` exits non-zero when blocked in human mode** — `openspec archive <change> -y` (and any non-`--json` invocation) no longer returns exit code 0 when validation fails and nothing is archived. The three blocking paths in human mode — delta-spec validation failure, spec rebuild failure, and rebuilt-spec validation failure — now set `process.exitCode = 1`, matching the existing `--json` behavior. Previously the command printed "Validation failed" (or "Aborted. No files were changed.") and exited 0, letting scripts and CI believe the archive succeeded. Aligns `archive` with the same exit-code guarantee already approved for `apply` instructions (#1250).
+
+- [#1280](https://github.com/Fission-AI/OpenSpec/pull/1280) [`a325305`](https://github.com/Fission-AI/OpenSpec/commit/a3253051ea1934fd0d76620addb855dfce801742) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **`validate` resolves changes like `status`** — `openspec validate <change>` (and `--all`/`--changes` and the interactive selector) now resolves a change by directory existence, matching `status`/`instructions`, instead of requiring `proposal.md`. A scaffolded or still-authoring change is validated rather than reported as `Unknown item`, and a resolved-but-invalid change now exits non-zero. Delta discovery also recurses the nested `specs/<area>/<capability>/spec.md` layout. (#1182)
+  - **Task progress reads nested/glob `tasks.md`** — `openspec view`, `list`, and the `archive` incomplete-task gate now resolve task progress through the tracked-tasks artifact's `generates` glob (the same file-resolution `status` uses), so a change whose tasks live in nested `tasks.md` files is classified correctly and can no longer archive while unfinished. (#1202)
+  - **SHALL/MUST body-keyword hint applies to main specs** — A main-spec requirement whose normative keyword sits only in the `### Requirement:` header now receives the same targeted "move it to the body line" remediation as a change delta, emitted exactly once. (#1156)
+
+- [#1281](https://github.com/Fission-AI/OpenSpec/pull/1281) [`9a0dfb5`](https://github.com/Fission-AI/OpenSpec/commit/9a0dfb5cd136b423c9f13c0b29ec3ea69761b4e6) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Requirement reading fidelity** — The requirement reader used by `validate <change>`, `validate <spec>`, and `archive` is now unified into one fence-, metadata-, and multi-line-aware extraction, closing the known divergences between the change-delta path and the main-spec path (the remaining ones are documented in the change's design doc):
+
+    - A `SHALL`/`MUST` keyword that wraps onto a later body line is detected instead of dropped (#361).
+    - Metadata lines (`**ID**:`, `**Priority**:`) before the description are skipped on the spec path, matching the change path (#418). A requirement written entirely as metadata (e.g. `**Constraint**: The system MUST ...`) keeps that line as its text instead of being emptied.
+    - A fenced code block before the prose line no longer becomes the requirement text (#312).
+    - A `#### Scenario:` inside a fenced example no longer counts as a real scenario in `validate <change>`, matching `validate <spec>`.
+    - `SHALL`/`MUST` detection uses one whole-word predicate across all readers, and a requirement with no body text falls back to its header title on both paths.
+
+    Displayed requirement text (e.g. in JSON output and delta descriptions) now reflects the full requirement body rather than only its first line. Archived spec content is unchanged — the archive rebuild reads raw `### Requirement:` blocks, not the parsed text.
+
+  - **Surface non-canonical delta headers** — `validate <change>` now emits an INFO note when an `## ADDED`/`## MODIFIED Requirements` section contains a level-3 header that is not a canonical `### Requirement:` header (one the delta reader silently skips, such as a stray `### Documentation Requirements` divider). The note never changes the `valid` result, including under `--strict` (#498).
+
+## 1.5.0
+
+### Minor Changes
+
+- [#1267](https://github.com/Fission-AI/OpenSpec/pull/1267) [`96f6cac`](https://github.com/Fission-AI/OpenSpec/commit/96f6cacb206c65bee30066f6a1f4e9b855a0d783) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Stores (very early beta)** — Introduces stores as a simpler way to organize specs and changes, replacing the workspace and initiative model. This feature is in very early beta — expect rough edges and breaking changes in upcoming releases.
+
+  ### Bug Fixes
+
+  - **Config parsing** — Configuration values wrapped in JSON containers are now parsed correctly.
+
+### Patch Changes
+
+- [#1240](https://github.com/Fission-AI/OpenSpec/pull/1240) [`cbf386b`](https://github.com/Fission-AI/OpenSpec/commit/cbf386bd6888f103f8ff7d59b3eab98ce5b57998) Thanks [@zied-jlassi](https://github.com/zied-jlassi)! - fix(adapters): escape carriage returns in generated YAML frontmatter
+
+  `escapeYamlValue` flagged `\r` as a character requiring quoting but never escaped it, leaving a literal carriage return inside the double-quoted scalar where YAML line folding/normalization could silently corrupt the value (realistic with CRLF-authored command descriptions). Carriage returns are now escaped as `\r`. The helper — previously duplicated verbatim across five adapters (bob, claude, cursor, pi, windsurf) — is extracted into a shared `command-generation/yaml.ts` module so the behavior stays consistent and is fixed in one place.
+
+## 1.4.1
+
+### Patch Changes
+
+- [#1165](https://github.com/Fission-AI/OpenSpec/pull/1165) [`0a01146`](https://github.com/Fission-AI/OpenSpec/commit/0a01146c181a3af8dbf645547bcbe20c0d48d615) Thanks [@TabishB](https://github.com/TabishB)! - Move beta workspace view state to `.openspec-workspace/view.yaml`, stop top-level `openspec update` from routing into workspace updates, and ignore foreign root `workspace.yaml` files so Dagster projects keep updating normally.
+
+## 1.4.0
+
+### Minor Changes
+
+- [#1003](https://github.com/Fission-AI/OpenSpec/pull/1003) [`342ed43`](https://github.com/Fission-AI/OpenSpec/commit/342ed43e694abba65a3ea275f94ba3b77df85da3) Thanks [@Miss-you](https://github.com/Miss-you)! - ### New Features
+
+  - **Kimi CLI support** — OpenSpec can now initialize Kimi CLI as a supported skills-only tool using `.kimi/skills/`
+
+  ### Other
+
+  - Added Kimi-specific docs and init coverage aligned with skill-based `/skill:openspec-*` usage
+
+- [#1154](https://github.com/Fission-AI/OpenSpec/pull/1154) [`aa16080`](https://github.com/Fission-AI/OpenSpec/commit/aa16080d16b70f7b26cebd465334b2e16c0e7a43) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Mistral Vibe support** — OpenSpec can now initialize Mistral Vibe as a supported skills-only tool using `.vibe/skills/`
+
+  ### Bug Fixes
+
+  - **Case-insensitive requirement headers** — Requirement headers are now parsed regardless of capitalization, so specs no longer fail to parse over header casing
+  - **Zsh completions on oh-my-zsh** — Fixed shell completion setup so tab completion installs correctly under oh-my-zsh's `compinit`
+
+  ### Other
+
+  - **Clearer validation hints** — When a requirement has SHALL/MUST only in its header, `openspec validate` now points you to move the keyword onto the requirement body line instead of showing the generic error
+
+- [#1030](https://github.com/Fission-AI/OpenSpec/pull/1030) [`485c97e`](https://github.com/Fission-AI/OpenSpec/commit/485c97e97d766e35dd16c02370baee2044abc4f4) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - Include the sync workflow in the default core profile so new installs generate `/opsx:sync` skills and commands by default.
+
+### Patch Changes
+
+- [#1111](https://github.com/Fission-AI/OpenSpec/pull/1111) [`7fdb177`](https://github.com/Fission-AI/OpenSpec/commit/7fdb1771585b1688597d73dde5a8bc906084d0de) Thanks [@TabishB](https://github.com/TabishB)! - ### Fixed
+
+  - Preserve workspace planning detection when Windows short paths or symlink aliases resolve to a canonical workspace root.
+
+## 1.3.1
+
+### Patch Changes
+
+- [#995](https://github.com/Fission-AI/OpenSpec/pull/995) [`d1f3861`](https://github.com/Fission-AI/OpenSpec/commit/d1f3861d9ec694cc924b042b5da01963dcf93137) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
+
+  - **Canonical artifact paths** — Workflow artifact paths are now resolved via the native `realpath`, so symlinks and case-insensitive filesystems no longer cause path mismatches during apply and archive.
+  - **Glob apply instructions** — Apply instructions with glob artifact outputs now resolve correctly, and literal artifact outputs are enforced to be file paths.
+  - **Hidden main spec requirements** — Requirements nested inside fenced code blocks or otherwise hidden in main specs are now detected during validation.
+  - **Clean `--json` output** — Spinner progress text no longer leaks into stderr when `--json` is passed, so AI agents that combine stdout and stderr can parse the JSON reliably.
+  - **Silent telemetry in firewalled environments** — PostHog network errors are now swallowed with a 1s timeout and retries/remote config disabled, so OpenSpec no longer surfaces `PostHogFetchNetworkError` in locked-down networks. Telemetry opt-out is documented earlier in the README, installation guide, and CLI reference.
+
+## 1.3.0
+
+### Minor Changes
+
+- [#952](https://github.com/Fission-AI/OpenSpec/pull/952) [`cce787e`](https://github.com/Fission-AI/OpenSpec/commit/cce787ec4083da2b27781f6786f5ce0002909a7b) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Junie support** — Added tool and command generation for JetBrains Junie
+  - **Lingma IDE support** — Added configuration support for Lingma IDE
+  - **ForgeCode support** — Added tool support for ForgeCode
+  - **IBM Bob support** — Added support for IBM Bob coding assistant
+
+  ### Bug Fixes
+
+  - **Shell completions opt-in** — Completion install is now opt-in, fixing PowerShell encoding corruption
+  - **Copilot auto-detection** — Prevented false GitHub Copilot detection from a bare `.github/` directory
+  - **pi.dev command generation** — Fixed command reference transforms and template argument passing
+
+### Patch Changes
+
+- [#760](https://github.com/Fission-AI/OpenSpec/pull/760) [`61eb999`](https://github.com/Fission-AI/OpenSpec/commit/61eb999f7c6c0fc98d2e7f3678756fce6a3f4378) Thanks [@fsilvaortiz](https://github.com/fsilvaortiz)! - fix: OpenCode adapter now uses `.opencode/commands/` (plural) to match OpenCode's official directory convention. Fixes #748.
+
+- [#759](https://github.com/Fission-AI/OpenSpec/pull/759) [`afdca0d`](https://github.com/Fission-AI/OpenSpec/commit/afdca0d5dab1aa109cfd8848b2512333ccad60c3) Thanks [@fsilvaortiz](https://github.com/fsilvaortiz)! - fix: `openspec status` now exits gracefully when no changes exist instead of throwing a fatal error. Fixes #714.
+
+## 1.2.0
+
+### Minor Changes
+
+- [#747](https://github.com/Fission-AI/OpenSpec/pull/747) [`1e94443`](https://github.com/Fission-AI/OpenSpec/commit/1e94443a3551b228eecbc89e95d96d3b9600a192) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Profile system** — Choose between `core` (4 essential workflows) and `custom` (pick any subset) profiles to control which skills get installed. Manage profiles with the new `openspec config profile` command
+  - **Propose workflow** — New one-step workflow creates a complete change proposal with design, specs, and tasks from a single request — no need to run `new` then `ff` separately
+  - **AI tool auto-detection** — `openspec init` now scans your project for existing tool directories (`.claude/`, `.cursor/`, etc.) and pre-selects detected tools
+  - **Pi (pi.dev) support** — Pi coding agent is now a supported tool with prompt and skill generation
+  - **Kiro support** — AWS Kiro IDE is now a supported tool with prompt and skill generation
+  - **Sync prunes deselected workflows** — `openspec update` now removes command files and skill directories for workflows you've deselected, keeping your project clean
+  - **Config drift warning** — `openspec config list` warns when global config is out of sync with the current project
+
+  ### Bug Fixes
+
+  - Fixed onboard preflight giving a false "not initialized" error on freshly initialized projects
+  - Fixed archive workflow stopping mid-way when syncing — it now properly resumes after sync completes
+  - Added Windows PowerShell alternatives for onboard shell commands
+
+## 1.1.1
+
+### Patch Changes
+
+- [#627](https://github.com/Fission-AI/OpenSpec/pull/627) [`afb73cf`](https://github.com/Fission-AI/OpenSpec/commit/afb73cf9ec59c6f8b26d0c538c0218c203ba3c56) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
+
+  - **OpenCode command references** — Command references in generated files now use the correct `/opsx-` hyphen format instead of `/opsx:` colon format, ensuring commands work properly in OpenCode
+
+## 1.1.0
+
+### Minor Changes
+
+- [#625](https://github.com/Fission-AI/OpenSpec/pull/625) [`53081fb`](https://github.com/Fission-AI/OpenSpec/commit/53081fb2a26ec66d2950ae0474b9a56cbc5b5a76) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
+
+  - **Codex global path support** — Codex adapter now resolves global paths correctly, fixing workflow file generation when run outside the project directory (#622)
+  - **Archive operations on cross-device or restricted paths** — Archive now falls back to copy+remove when rename fails with EPERM or EXDEV errors, fixing failures on networked/external drives (#605)
+  - **Slash command hints in workflow messages** — Workflow completion messages now display helpful slash command hints for next steps (#603)
+  - **Windsurf workflow file path** — Updated Windsurf adapter to use the correct `workflows` directory instead of the legacy `commands` path (#610)
+
+### Patch Changes
+
+- [#550](https://github.com/Fission-AI/OpenSpec/pull/550) [`86d2e04`](https://github.com/Fission-AI/OpenSpec/commit/86d2e04cae76a999dbd1b4571f52fa720036be0c) Thanks [@jerome-benoit](https://github.com/jerome-benoit)! - ### Improvements
+
+  - **Nix flake maintenance** — Version now read dynamically from package.json, reducing manual sync issues
+  - **Nix build optimization** — Source filtering excludes node_modules and artifacts, improving build times
+  - **update-flake.sh script** — Detects when hash is already correct, skipping unnecessary rebuilds
+
+  ### Other
+
+  - Updated Nix CI actions to latest versions (nix-installer v21, magic-nix-cache v13)
+
 ## 1.0.2
 
 ### Patch Changes

README.md

@@ -36,27 +36,28 @@ Our philosophy:
 > [!TIP]
 > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
 >
-> Run `/opsx:onboard` to get started. → [Learn more here](docs/opsx.md)
+> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
 
 <p align="center">
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
-### Teams
-
-Using OpenSpec in a team? [Email here](mailto:teams@openspec.dev) for access to our Slack channel.
-
-<!-- TODO: Add GIF demo of /opsx:new → /opsx:archive workflow -->
+<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
 
 ## See it in action
 
 ```text
-You: /opsx:new add-dark-mode
-AI:  Created openspec/changes/add-dark-mode/
-     Ready to create: proposal
+You: /opsx:explore
+AI:  What would you like to explore?
+You: I want dark mode but I'm not sure how to do it cleanly.
+AI:  Let me look at your styling setup...
+     Cleanest path here: CSS variables + a small theme context,
+     with system-preference detection. No new dependencies. Scope it?
+You: Yes, let's do it.
 
-You: /opsx:ff   # "fast-forward" - generate all planning docs
-AI:  ✓ proposal.md — why we're doing this, what's changing
+You: /opsx:propose add-dark-mode
+AI:  Created openspec/changes/add-dark-mode/
+     ✓ proposal.md — why we're doing this, what's changing
      ✓ specs/       — requirements and scenarios
      ✓ design.md    — technical approach
      ✓ tasks.md     — implementation checklist
@@ -84,6 +85,18 @@ AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
 
 </details>
 
+## Why teams adopt OpenSpec
+
+Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
+
+**[Stores](docs/stores-beta/user-guide.md)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
+
+- **Cross-repo features** — one change, one plan, even when the code lands in three repos.
+- **Shared requirements** — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
+- **Plan before code** — capture the plan in the store now; the code repos catch up later.
+
+> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
+
 ## Quick Start
 
 **Requires Node.js 20.19.0 or higher.**
@@ -101,23 +114,45 @@ cd your-project
 openspec init
 ```
 
-Now tell your AI: `/opsx:new <what-you-want-to-build>`
+Now talk to your AI:
+
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
+- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
+
+Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing.
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
 >
 > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
 
 ## Docs
 
+**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
+
 → **[Getting Started](docs/getting-started.md)**: first steps<br>
+→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
+→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
+→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
+→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
 → **[Workflows](docs/workflows.md)**: combos and patterns<br>
+→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
+→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
 → **[Commands](docs/commands.md)**: slash commands & skills<br>
 → **[CLI](docs/cli.md)**: terminal reference<br>
+→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
 → **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours
+→ **[Customization](docs/customization.md)**: make it yours<br>
+→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
+
+
+## Community schemas
+
+Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) handles tool integrations.
+
+→ **[Browse the catalog](docs/customization.md#community-schemas)** in the customization docs.
 
 
 ## Why OpenSpec?
@@ -127,7 +162,7 @@ AI coding assistants are powerful but unpredictable when requirements live only
 - **Agree before you build** — human and AI align on specs before code gets written
 - **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
 - **Work fluidly** — update any artifact anytime, no rigid phase gates
-- **Use your tools** — works with 20+ AI assistants via slash commands
+- **Use your tools** — works with 30+ AI assistants via slash commands
 
 ### How we compare
 
@@ -155,7 +190,7 @@ openspec update
 
 ## Usage Notes
 
-**Model selection**: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.
+**Model selection**: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.
 
 **Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
 

bin/openspec.js

@@ -1,3 +1,5 @@
 #!/usr/bin/env node
 
-import '../dist/cli/index.js';
+import { runCli } from '../dist/cli/index.js';
+
+runCli();

docs/README.md

@@ -0,0 +1,114 @@
+# OpenSpec Documentation
+
+Welcome. This is the home for everything OpenSpec.
+
+OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.
+
+If you read nothing else, read these two pages:
+
+1. [Getting Started](getting-started.md): install, initialize, and ship your first change.
+2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once.
+
+That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
+
+> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
+
+## Pick your path
+
+**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby.
+
+**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything.
+
+**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean.
+
+**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place.
+
+**I learn by example.** The [Examples & Recipes](examples.md) page walks through real changes start to finish: a small feature, a bug fix, a refactor, an exploration.
+
+**The AI just drafted a plan — now what?** Read it. [Reviewing a Change](reviewing-changes.md) shows the two-minute pass that catches a wrong turn while it's still cheap, and [Writing Good Specs](writing-specs.md) covers what a plan worth approving is made of.
+
+**I work on a team.** [OpenSpec on a Team](team-workflow.md) shows how a change maps onto a branch and a pull request, and how teammates review a plan before the code.
+
+**I'm coming from the old workflow.** The [Migration Guide](migration-guide.md) explains what changed and why, and promises your existing work is safe.
+
+**I want to bend it to my team's process.** [Customization](customization.md) covers project config, custom schemas, and shared context.
+
+**Something's broken.** [Troubleshooting](troubleshooting.md) collects the failures people actually hit, with fixes.
+
+## The whole map
+
+### Start here
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Getting Started](getting-started.md) | Install, initialize, and run your first change end to end |
+| [Explore First](explore.md) | Use `/opsx:explore` to think through an idea before you commit |
+| [How Commands Work](how-commands-work.md) | Where slash commands run, what "interactive mode" means, terminal vs chat |
+| [Core Concepts at a Glance](overview.md) | The whole mental model on one page: specs, changes, deltas, archive |
+| [Installation](installation.md) | npm, pnpm, yarn, bun, Nix, and how to verify it worked |
+
+### Use it day to day
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Workflows](workflows.md) | Common patterns and when to reach for each command |
+| [Examples & Recipes](examples.md) | Full walkthroughs of real changes, copy-pasteable |
+| [Writing Good Specs](writing-specs.md) | What a strong requirement and scenario look like, and how to right-size a change |
+| [Reviewing a Change](reviewing-changes.md) | The two-minute pass on a drafted plan before any code is written |
+| [OpenSpec on a Team](team-workflow.md) | How changes fit branches, pull requests, and review |
+| [Using OpenSpec in an Existing Project](existing-projects.md) | Adopting OpenSpec on a large brownfield codebase |
+| [Editing & Iterating on a Change](editing-changes.md) | Update artifacts, go back, reconcile manual edits |
+| [Commands](commands.md) | Reference for every `/opsx:*` slash command |
+| [CLI](cli.md) | Reference for every `openspec` terminal command |
+
+### Understand it deeply
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Concepts](concepts.md) | The long-form explanation of specs, changes, artifacts, schemas, and archive |
+| [OPSX Workflow](opsx.md) | Why the workflow is fluid instead of phase-locked, plus an architecture deep dive |
+| [Glossary](glossary.md) | Every term defined in one place |
+
+### Make it yours
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Customization](customization.md) | Project config, custom schemas, shared context |
+| [Multi-Language](multi-language.md) | Generate artifacts in languages other than English |
+| [Supported Tools](supported-tools.md) | The 25+ AI tools OpenSpec integrates with, and where files land |
+
+### When you need help
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [FAQ](faq.md) | Quick answers to the questions people ask most |
+| [Troubleshooting](troubleshooting.md) | Concrete fixes for concrete failures |
+| [Migration Guide](migration-guide.md) | Moving from the legacy workflow to OPSX |
+
+### Coordinate across repos (beta)
+
+| Doc | What it gives you |
+|-----|-------------------|
+| [Stores: User Guide](stores-beta/user-guide.md) | Plan in its own repo when your work spans repos or teams |
+| [Agent Contract](agent-contract.md) | The machine-readable CLI surfaces agents drive |
+
+## The thirty-second version
+
+```text
+1. Install        npm install -g @fission-ai/openspec@latest
+2. Initialize     cd your-project && openspec init
+3. Explore        (in your AI chat)  /opsx:explore           ← optional, but a great habit
+4. Propose        (in your AI chat)  /opsx:propose add-dark-mode
+5. Build          (in your AI chat)  /opsx:apply
+6. Archive        (in your AI chat)  /opsx:archive
+```
+
+Steps 1 and 2 happen in your terminal. The rest happen in your AI assistant's chat. That split is the one thing worth memorizing, and [How Commands Work](how-commands-work.md) explains exactly why. Step 3 is optional, but starting with `/opsx:explore` when you're unsure is the habit most worth forming.
+
+## Where else to get help
+
+- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help.
+- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) for bugs and feature requests.
+- **`openspec feedback "your message"`** sends feedback straight from your terminal (it opens a GitHub issue).
+
+Found something in these docs that's wrong, stale, or confusing? That's a bug. Open an issue or a PR. Documentation improvements are some of the most valuable contributions you can make.

docs/agent-contract.md

@@ -0,0 +1,137 @@
+# OpenSpec Agent Contract
+
+Machine-readable surfaces of the `openspec` CLI, verified against `src/` (capstone audit, 2026-06-11). Every shape below is documented from the emitting code.
+
+## 1. General conventions
+
+- **One JSON document per invocation.** In `--json` mode, stdout carries exactly one JSON document (2-space pretty-printed). Human prose, spinners, and the store banner go to stderr.
+- **Store banner.** In human mode, a store-selected root prints `Using OpenSpec root: <id> (<path>)` to stderr. Never printed in JSON mode.
+- **Key casing is surface-dependent** (see Known inconsistencies): store/doctor/context payloads use `snake_case`; workflow payloads (`status`, `instructions`, `new change`, `validate`, `list`) use `camelCase`, except the embedded `root` object, which always uses `store_id`.
+- **Optional keys are omitted, not null**, in most payloads (e.g. `root.store_id`, `member.path`). Exceptions that use explicit `null` are called out per shape (store doctor `git.*`, failure payloads).
+
+## 2. The diagnostic envelope
+
+One envelope shape is shared by every machine-readable diagnostic (`StoreDiagnostic`):
+
+```json
+{
+  "severity": "error" | "warning" | "info",
+  "code": "snake_case_string",
+  "message": "human sentence",
+  "target": "dotted.surface (optional)",
+  "fix": "one actionable sentence/command (optional)"
+}
+```
+
+Diagnostics appear in two positions: **status arrays** (`status: StoreDiagnostic[]` at top level or per entry) for health findings, and **thrown errors** converted to a single-element `status` array on command failure.
+
+## 3. Root selection and `RootOutput`
+
+All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `new change`, `archive`, `doctor`, `context`) resolve one OpenSpec root with one precedence:
+
+1. `--store <id>` → the registered store's root (`source: "store"`).
+2. Otherwise, nearest ancestor with `openspec/`: planning shape → `source: "nearest"` (a `store:` pointer is ignored with a stderr warning); config-only dir with a valid `store:` pointer → that store, `source: "declared"`.
+3. No nearest root + registered stores exist → error `no_root_with_registered_stores`.
+4. No root, no stores: scaffolding commands treat the cwd as `source: "implicit"`; diagnostic commands (`doctor`, `context`) fail with `no_openspec_root` instead — they inspect, never scaffold.
+
+Successful JSON payloads embed the root:
+
+```json
+"root": { "path": "/abs/path", "source": "store" | "declared" | "nearest" | "implicit", "store_id": "id (only when store-selected)" }
+```
+
+**Root-failure contract**: in JSON mode a resolution failure prints `{ ...commandNullShape, "status": [diagnostic] }` on stdout and exits 1.
+
+## 4. Command JSON shapes
+
+### 4.1 `list --json`
+`{ "changes": [ { "name", "completedTasks", "totalTasks", "lastModified", "status": "no-tasks"|"complete"|"in-progress" } ], "root": RootOutput }` — note the per-change `status` is a string enum here. `--specs`: `{ "specs": [ { "id", "requirementCount" } ], "root" }`.
+
+### 4.2 `show <item> --json`
+Change: `{ "id", "title", "deltaCount", "deltas": [...], "root" }`. Spec: `{ "id", "title", "overview", "requirementCount", "requirements": [...], "metadata": { "version", "format", "sourcePath"? }, "root" }`.
+
+### 4.3 `validate --json`
+`{ "items": [ { "id", "type": "change"|"spec", "valid", "issues": [ { "level", "path", "message", "line"?, "column"? } ], "durationMs" } ], "summary": { "totals": {items,passed,failed}, "byType": {...} }, "version": "1.0", "root" }`. Exit 1 when any item fails.
+
+### 4.4 `status --json`
+`{ "changeName", "schemaName", "planningHome"?: { "kind", "root", "changesDir", "defaultSchema" }, "changeRoot", "artifactPaths": { "<id>": {outputPath, resolvedOutputPath, existingOutputPaths} }, "nextSteps": ["..."], "actionContext": { "mode": "repo-local", "sourceOfTruth": "repo", "planningArtifacts", "linkedContext", "allowedEditRoots", "requiresAffectedAreaSelection", "constraints" }, "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"ready"|"blocked", missingDeps?} ], "root" }`. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
+
+### 4.5 `instructions <artifact> --json`
+`{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "template", "dependencies": [{id,done,path,description}], "unlocks", "root" }`.
+
+`ReferenceIndexEntry`: `{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] }` — resolved entries carry root/specs/fetch; unresolved carry store_id + warning status. Index capped at 50KB (`reference_index_truncated`).
+
+### 4.6 `instructions apply --json`
+`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "root" }`.
+
+### 4.7 `new change <name> --json`
+Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Failure: `{ "change": null, "status": [d] }`, exit 1.
+
+### 4.8 `archive <name> --json`
+Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
+
+### 4.9 `doctor --json`
+`{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "status": [] } | null, "references": [...], "status": [] }`. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
+
+### 4.10 `context --json`
+`{ "root": { "path", "source", "store_id"?, "role": "openspec_root" }, "members": [ { "role": "referenced_store", "id", "path"?, "remote"?, "fetch"?, "status": [] } ], "status": [] }`. AVAILABLE = path present AND status empty. `--code-workspace <path>` writes `{folders:[{name,path}]}` (available referenced stores only, `ref:` prefixes); in JSON mode the write runs before printing so stdout holds exactly one document even on write failure. Failure: `{ "root": null, "members": [], "status": [d] }`, exit 1.
+
+### 4.11 `store ... --json`
+setup/register: `{ "store": {id, root, metadata_path?}, "registry": {path, registered, already_registered}, "git": {is_repository, initialized, committed}, "created_files": [], "status": [] }`. unregister/remove: `{ "store", "registry": {path, removed}, "files": {deleted, deleted_path, left_on_disk}, "status": [] }`. list: `{ "stores": [{id, root}], "status": [] }`. doctor: `{ "stores": [ { id, root, metadata_path?, openspec_root: {...healthy, status}, metadata: {present, valid, id?, remote}, git: {is_repository, has_commits, has_uncommitted_changes, has_remote, origin_url}, status } ], "status": [] }` (`null` = unknown/not probed). Health findings exit 0; failures exit 1 with the matching null-shape. Prompt cancellation exits 130.
+
+### 4.12 `schemas --json` / `templates --json`
+`schemas`: bare array `[ {name, description, artifacts, source} ]`. `templates`: keyed object `{ "<artifactId>": {path, source} }`. Both cwd-based, no root/status keys.
+
+## 5. Exit-code contract
+
+| Situation | Exit | Stdout |
+|---|---|---|
+| Success, incl. health findings (doctor/context/store doctor) | 0 | the payload |
+| Command failure in `--json` mode | 1 | one JSON document with `status: [d]` and the command's null-shape |
+| `validate` with failing items | 1 | full report |
+| Prompt cancellation (`store` group, human mode) | 130 | stderr only |
+
+## 6. Diagnostic code catalog
+
+### Resolution
+`no_openspec_root`, `no_root_with_registered_stores`, `no_registered_stores`, `unknown_store`, `store_identity_mismatch`, `unhealthy_store_root`, `store_path_not_supported`, `invalid_store_pointer`, `initiative_option_removed`, `areas_option_removed`; pass-through: `invalid_store_id`, `invalid_store_registry`, `invalid_store_metadata`.
+
+### OpenSpec-root health (error, no fix)
+`openspec_store_root_missing`, `openspec_store_root_not_directory`, `openspec_root_missing`, `openspec_root_not_directory`, `openspec_config_missing`, `openspec_config_not_file`, `openspec_specs_not_directory`, `openspec_changes_not_directory`, `openspec_archive_not_directory`. During the stores beta, `openspec/specs/`, `openspec/changes/`, and `openspec/changes/archive/` may be absent in a healthy root; they are only health errors when present but not directories.
+
+### Store registry/identity/state
+`invalid_store_id`, `invalid_store_registry`, `invalid_store_metadata`, `store_registry_busy`, `store_not_found`, `no_store_registry`, `store_registry_changed`, `store_metadata_missing`, `store_metadata_id_mismatch`, `store_metadata_invalid`, `store_id_conflict`, `store_path_conflict`, `store_already_registered` (info).
+
+### Store setup/register/remove
+`store_setup_id_required`, `store_setup_path_required`, `store_setup_path_not_directory`, `store_setup_inside_git_repo`, `store_setup_non_empty_directory`, `store_setup_cancelled`, `store_path_required`, `store_path_missing`, `store_path_not_directory`, `store_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 git
+`store_git_init_failed`, `store_git_identity_missing`, `store_git_commit_failed`, `store_git_no_commits` (warning), `store_clone_fragile_directories` (warning), `store_remote_divergence` (info, doctor).
+
+### References (warning)
+`reference_invalid_id`, `reference_registry_unreadable`, `reference_unresolved`, `reference_root_unhealthy`, `reference_index_truncated`.
+
+### Relationships (warning; doctor; context keeps only the registry one)
+`relationship_registry_unreadable`, `root_pointer_ignored`, `root_pointer_invalid`, `pointer_declarations_inert`.
+
+### Archive (JSON mode)
+`archive_change_name_required`, `archive_change_not_found`, `archive_validation_failed`, `archive_confirmation_required`, `archive_tasks_incomplete`, `archive_spec_update_failed`, `archive_spec_validation_failed`, `archive_target_exists`, `archive_error`.
+
+### Context writes
+`context_file_exists`, `context_output_dir_missing`.
+
+### Fallbacks
+`doctor_failed`, `context_failed`, `store_error`, `change_error`, `archive_error`.
+
+## Known inconsistencies
+
+Recorded by the capstone audit; published-key renames are product decisions deferred past this release:
+
+1. ~~In `--json` mode, several failure paths printed stderr only with no JSON document.~~ Fixed in the capstone gauntlet round: `show`/`validate` unknown and ambiguous items emit `{status:[{code: unknown_item | ambiguous_item, ...}]}`; thrown errors in `status`/`instructions`/`list`/`show`/`validate` route through the JSON-aware failure helper (the command's null-shape + `status`); `store <unknown subcommand> --json` emits `{status:[{code: unknown_store_subcommand}]}`; `list` carries its `{changes|specs: [], root: null}` null-shape on resolution failures.
+2. `store_root_missing` is emitted with two severities (warning in remove, error in store doctor) — context-dependent, documented above.
+3. snake_case (store family) vs camelCase (workflow family) key casing; `root.store_id` is snake_case everywhere.
+4. Four parallel envelope type declarations exist in src; archive diagnostics never carry `target`.
+5. `list --json` reuses the `status` key as a string enum per change.
+6. Only `validate` output carries a `version` field.
+7. `schemas`/`templates` ignore root selection (cwd-based, no `--store`).
+8. Deprecated noun forms (`change`/`spec` subcommands) emit unenveloped payloads without `root`/`status`.

docs/cli.md

@@ -1,16 +1,20 @@
 # CLI Reference
 
-The OpenSpec CLI (`openspec`) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like `/opsx:new`) documented in [Commands](commands.md).
+The OpenSpec CLI (`openspec`) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like `/opsx:propose`) documented in [Commands](commands.md).
 
 ## Summary
 
 | Category | Commands | Purpose |
 |----------|----------|---------|
 | **Setup** | `init`, `update` | Initialize and update OpenSpec in your project |
+| **Stores (standalone OpenSpec repos)** | `store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor` | Manage stores — standalone OpenSpec repos you've registered |
+| **Health** | `doctor` | Report relationship health for the resolved root |
+| **Working context** | `context` | Assemble the working set (root + referenced stores) |
+| **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** | `archive` | Finalize completed changes |
-| **Workflow** | `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
+| **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 |
 | **Utility** | `feedback`, `completion` | Feedback and shell integration |
@@ -29,6 +33,7 @@ These commands are interactive and designed for terminal use:
 |---------|---------|
 | `openspec init` | Initialize project (interactive prompts) |
 | `openspec view` | Interactive dashboard |
+| `openspec workset open <name>` | Open a saved workset (editor window or terminal agent session) |
 | `openspec config edit` | Open config in editor |
 | `openspec feedback` | Submit feedback via GitHub |
 | `openspec completion install` | Install shell completions |
@@ -46,6 +51,16 @@ These commands support `--json` output for programmatic use by AI agents and scr
 | `openspec instructions` | Get next steps | `--json` for agent instructions |
 | `openspec templates` | Find template paths | `--json` for path resolution |
 | `openspec schemas` | List available schemas | `--json` for schema discovery |
+| `openspec store setup <id>` | Create and register a local store | `--json` with explicit inputs for structured setup output |
+| `openspec store register <path>` | Register an existing store | `--json` for structured registration output |
+| `openspec store unregister <id>` | Forget a local store registration | `--json` for structured cleanup output |
+| `openspec store remove <id>` | Delete a registered local store folder | `--yes --json` for non-interactive deletion |
+| `openspec store list` | Browse registered stores | `--json` for structured registrations |
+| `openspec store doctor` | Check local store setup | `--json` for structured diagnostics |
+| `openspec new change <id>` | Create repo-local change scaffolding | `--json`, plus `--store <id>` to use a registered store as the OpenSpec root |
+| `openspec workset create [name]` | Compose a personal working view | `--member <path> --json` for non-interactive composition |
+| `openspec workset list` | Browse saved worksets | `--json` for structured views |
+| `openspec workset remove <name>` | Delete a saved view | `--yes --json` for non-interactive removal |
 
 ---
 
@@ -67,6 +82,8 @@ These options work with all commands:
 
 Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations.
 
+Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, sync, archive`.
+
 ```
 openspec init [path] [options]
 ```
@@ -83,8 +100,13 @@ openspec init [path] [options]
 |--------|-------------|
 | `--tools <list>` | Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list |
 | `--force` | Auto-cleanup legacy files without prompting |
+| `--profile <profile>` | Override global profile for this init run (`core` or `custom`) |
 
-**Supported tools:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`, `qwen`, `roocode`, `windsurf`
+`--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`).
+
+**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf`
+
+> This list mirrors `AI_TOOLS` in `src/core/config.ts`. See [Supported Tools](supported-tools.md) for each tool's skill and command paths.
 
 **Examples:**
 
@@ -101,6 +123,9 @@ openspec init --tools claude,cursor
 # Configure for all supported tools
 openspec init --tools all
 
+# Override profile for this run
+openspec init --profile core
+
 # Skip prompts and auto-cleanup legacy files
 openspec init --force
 ```
@@ -113,8 +138,9 @@ openspec/
 ├── changes/            # Proposed changes
 └── config.yaml         # Project configuration
 
-.claude/skills/         # Claude Code skill files (if claude selected)
-.cursor/rules/          # Cursor rules (if cursor selected)
+.claude/skills/         # Claude Code skills (if claude selected)
+.cursor/skills/         # Cursor skills (if cursor selected)
+.cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
 ... (other tool configs)
 ```
 
@@ -122,7 +148,7 @@ openspec/
 
 ### `openspec update`
 
-Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files.
+Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files using your current global profile, selected workflows, and delivery mode.
 
 ```
 openspec update [path] [options]
@@ -150,6 +176,204 @@ openspec update
 
 ---
 
+## Stores (standalone OpenSpec repos)
+
+> **Beta.** Stores and the features built on them (references, working context, worksets) are new; command names, flags, file formats, and JSON output may change shape between releases. For the problem-first walkthrough, see the [stores guide](stores-beta/user-guide.md).
+
+A store is a standalone OpenSpec repo you've registered on this machine — for example a planning repo or a contracts repo. Registering a store lets normal commands (`list`, `show`, `status`, `validate`, `new change`, `archive`, ...) act in it from anywhere by passing `--store <id>`.
+
+### `openspec store setup`
+
+Create and register a local store. With no arguments in a terminal,
+OpenSpec guides the user through setup. Agents and scripts should pass explicit
+inputs and use `--json`.
+
+```bash
+openspec store setup [id] [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--path <path>` | Folder where the store should live (for example `~/openspec/<id>`) |
+| `--remote <url>` | Record the canonical remote in the new store's `store.yaml` |
+| `--init-git` | Initialize a Git repository with an initial commit (default) |
+| `--no-init-git` | Skip every Git action: no init, no initial commit |
+| `--json` | Output JSON |
+
+Non-interactive runs (`--json`, scripts, agents) must pass both the store id and `--path`. In an interactive terminal, setup prompts for the location with an editable suggestion in a visible, user-owned place (for example `~/openspec/<id>`); it never defaults to OpenSpec's managed data directory.
+
+Examples:
+
+```bash
+openspec store setup
+openspec store setup team-context
+openspec store setup team-context --path ~/openspec/team-context --no-init-git
+openspec store setup team-context --path ~/openspec/team-context --no-init-git --json
+```
+
+### `openspec store register`
+
+Register an existing local store folder. During the stores beta, a root may be
+registered before any changes exist, specs have been applied, or changes have
+been archived; in that case `openspec/changes/`, `openspec/specs/`, and
+`openspec/changes/archive/` may be absent until normal commands create them.
+A config-only repo that declares `store: <id>` remains a pointer to another
+store and is not registered as a store root unless that pointer is removed.
+
+```bash
+openspec store register [path] [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--id <id>` | Store id; defaults to store metadata or folder name |
+| `--yes` | Confirm creating store identity metadata for a healthy OpenSpec root |
+| `--json` | Output JSON |
+
+### `openspec store unregister`
+
+Forget a local store registration without deleting files.
+
+```bash
+openspec store unregister <id> [--json]
+```
+
+Use this when a store was moved, cloned somewhere else, or should no longer be
+shown by OpenSpec on this machine.
+
+### `openspec store remove`
+
+Forget a local store registration and delete its local folder.
+
+```bash
+openspec store remove <id> [--yes] [--json]
+```
+
+`remove` shows the exact folder before deleting in an interactive terminal.
+Agents, scripts, and JSON callers must pass `--yes` to confirm deletion.
+OpenSpec refuses to delete a folder that does not contain matching
+store metadata.
+
+### `openspec store list`
+
+List locally registered stores.
+
+```bash
+openspec store list [--json]
+openspec store ls [--json]
+```
+
+### `openspec store doctor`
+
+Check local store registration, metadata, and Git presence.
+
+```bash
+openspec store doctor [id] [--json]
+```
+
+Doctor is diagnostic-only; it reports missing roots, metadata mismatches, and invalid local registry state without modifying the store.
+
+### Referencing stores from a project
+
+A project repo can declare which stores its work draws on in `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+references:
+  - team-context
+```
+
+From then on, `openspec instructions` output in that repo (both the per-artifact and `apply` surfaces, JSON and human modes) carries an index of each referenced store's specs — spec ids, a one-line summary from each spec's Purpose section, and the fetch command (`openspec show <spec-id> --type spec --store <id>`). The index is built live from the registered checkout on every run; spec content is never copied into the output.
+
+References are read-only context. They never change where commands act: work stays in the repo's own root, and writing to a referenced store remains an explicit `--store` action. A reference that cannot be resolved (for example, a store not registered on this machine) degrades to a warning in the index with the exact fix, and instructions still generate. `openspec doctor` reports reference health in one place.
+
+### Recording where a store is cloned from
+
+A store can record its canonical clone source in its committed identity file, so onboarding never dead-ends at "register the store":
+
+```bash
+openspec store setup team-context --path ~/openspec/team-context \
+  --remote git@github.com:acme/team-context.git
+```
+
+The remote lands in `.openspec-store/store.yaml` inside the initial commit, so every clone is born knowing it. For an existing store, edit `store.yaml` by hand and commit. `store doctor` shows the recorded remote (and the checkout's observed Git origin); setup/register sharing guidance names it; and register records the checkout's origin in the machine-local registry.
+
+A reference declaration can carry the clone source too, so a teammate who doesn't have the store yet gets a complete, pasteable fix (`git clone <remote> <path> && openspec store register <path> --id <id>`):
+
+```yaml
+references:
+  - { id: team-context, remote: "git@github.com:acme/team-context.git" }
+```
+
+Recording a remote is not sync: OpenSpec never clones, pulls, or pushes on its own.
+
+### Declaring a default store
+
+A repo whose planning is fully externalized — no local `openspec/specs/` or `openspec/changes/` — can declare its store once instead of passing `--store` on every command:
+
+```yaml
+# openspec/config.yaml (the only file under openspec/)
+store: team-context
+```
+
+Normal commands then resolve to the declared store automatically; the root banner and JSON `root` block report `source: "declared"` with the store id, and printed hints still carry `--store <id>`. The declaration is a fallback, never an override: explicit `--store` always wins, and a directory with real planning folders ignores the pointer (with a warning). To convert a pointer repo into a local OpenSpec root, remove the `store:` line and run `openspec init` — init refuses to scaffold while the declaration is present.
+
+## Doctor (relationship health)
+
+One read-only question, one place: is the OpenSpec root healthy, and are the stores it references available on this machine?
+
+```bash
+openspec doctor [--store <id>] [--json]
+```
+
+The report separates root health, store metadata health (including a note when the recorded remote and the checkout's origin diverge), and reference health (the same diagnostics instructions show, with clone fixes for unresolved references). Health findings of any severity exit 0 — agents read the `status` arrays; only command failures (no root, unknown store) exit 1. Doctor never clones, syncs, or repairs. To get the assembled set itself rather than its health, use `openspec context`.
+
+## Working context (the assembled set)
+
+Everything this work relates to through OpenSpec declarations, in one working set: the OpenSpec root and the stores it references.
+
+```bash
+openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]
+```
+
+The JSON brief is agent-consumable (each available referenced store carries its fetch recipe; unresolved members carry the same fixes instructions and doctor show). `--code-workspace` additionally writes a VS Code workspace file containing the root plus the available referenced stores (`ref:<id>` folders) — the one write this command performs, refused without `--force` if the file exists. Unavailable members are reported, never guessed at.
+
+"Working context" is the assembled set; the `context:` field in `openspec/config.yaml` is project background injected into instructions — two different things. `openspec doctor` answers whether the set is healthy; `openspec context` answers what the set is.
+
+## Personal worksets
+
+> **Beta.** Worksets are part of the new beta surface; commands, flags, and file formats may change shape between releases. For the walkthrough, see the [stores guide](stores-beta/user-guide.md#worksets-reopen-the-folders-you-work-on-together).
+
+A workset is a personal, named view of the folders you work on together — a planning root plus whatever else you choose — kept on your machine and reopened by name in your tool. It is purely local: never committed, never shared, never derived from declarations, and removing one never touches a member folder.
+
+```bash
+openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
+openspec workset list [--json]
+openspec workset open <name> [--tool <id>]
+openspec workset remove <name> [--yes] [--json]
+```
+
+`create` runs a short guided flow (or takes `--member` flags non-interactively; the first member is the primary — sessions start there). `open` launches the chosen tool: editors (VS Code, Cursor) open a window with every member and return; CLI agents (Claude Code, codex) take over this terminal as a session with every member attached and no prompt pre-filled, ending when you exit. A member folder missing at open time is skipped with a note; the rest opens. The saved tool preference is overridable per open with `--tool`.
+
+Supporting a new tool is configuration, not code. Every tool is one of two launch styles — `workspace-file` (launched with the generated `.code-workspace`) or `attach-dirs` (one attach flag per member) — and the `openers` key in the global `config.json` (open it with `openspec config edit`) adds tools or adjusts built-ins per field:
+
+```json
+{
+  "openers": {
+    "zed": { "style": "workspace-file" },
+    "claude": { "attach_flag": "--dir" }
+  }
+}
+```
+
+All workset state lives under the global data dir's `worksets/` folder (the saved views plus the generated `<name>.code-workspace` files, regenerated on every open); deleting that folder removes every trace.
+
+---
+
 ## Browsing Commands
 
 ### `openspec list`
@@ -185,9 +409,8 @@ openspec list --json
 **Output (text):**
 
 ```
-Active changes:
-  add-dark-mode     UI theme switching support
-  fix-login-bug     Session timeout handling
+Changes:
+  add-dark-mode     No tasks      just now
 ```
 
 ---
@@ -394,6 +617,38 @@ openspec archive update-ci-config --skip-specs
 
 These commands support the artifact-driven OPSX workflow. They're useful for both humans checking progress and agents determining next steps.
 
+### `openspec new change`
+
+Create a change directory and optional checked-in metadata in the resolved OpenSpec root.
+
+```bash
+openspec new change <name> [options]
+```
+
+Change names must use lowercase kebab-case. They start with a lowercase letter,
+then contain lowercase letters, numbers, and single hyphens. They cannot start
+with a number, contain spaces, underscores, uppercase letters, consecutive
+hyphens, or leading/trailing hyphens. When including an external ticket ID,
+prefix it with a word, for example `ticket-123-add-notifications` instead of
+`123-add-notifications`.
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--description <text>` | Description to add to `README.md` |
+| `--goal <text>` | Optional goal metadata to store with the change |
+| `--schema <name>` | Workflow schema to use |
+| `--store <id>` | Store id to use as the OpenSpec root (a store is a standalone OpenSpec repo you've registered) |
+| `--json` | Output JSON |
+
+Examples:
+
+```bash
+openspec new change add-billing-api
+openspec new change add-billing-api --store team-context --json
+```
+
 ### `openspec status`
 
 Display artifact completion status for a change.
@@ -428,29 +683,28 @@ openspec status --change add-dark-mode --json
 ```
 Change: add-dark-mode
 Schema: spec-driven
+Progress: 2/4 artifacts complete
 
-Artifacts:
-  ✓ proposal     proposal.md exists
-  ✓ specs        specs/ exists
-  ◆ design       ready (requires: specs)
-  ○ tasks        blocked (requires: design)
-
-Next: Create design using /opsx:continue
+[x] proposal
+[ ] design
+[x] specs
+[-] tasks (blocked by: design)
 ```
 
 **Output (JSON):**
 
 ```json
 {
-  "change": "add-dark-mode",
-  "schema": "spec-driven",
+  "changeName": "add-dark-mode",
+  "schemaName": "spec-driven",
+  "isComplete": false,
+  "applyRequires": ["tasks"],
   "artifacts": [
-    {"id": "proposal", "status": "complete", "path": "proposal.md"},
-    {"id": "specs", "status": "complete", "path": "specs/"},
-    {"id": "design", "status": "ready", "requires": ["specs"]},
-    {"id": "tasks", "status": "blocked", "requires": ["design"]}
-  ],
-  "next": "design"
+    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
+    {"id": "design", "outputPath": "design.md", "status": "ready"},
+    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
+    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
+  ]
 }
 ```
 
@@ -767,6 +1021,7 @@ openspec config <subcommand> [options]
 | `unset <key>` | Remove a key |
 | `reset` | Reset to defaults |
 | `edit` | Open in `$EDITOR` |
+| `profile [preset]` | Configure workflow profile interactively or via preset |
 
 **Examples:**
 
@@ -794,6 +1049,37 @@ openspec config reset --all --yes
 
 # Edit config in your editor
 openspec config edit
+
+# Configure profile with action-based wizard
+openspec config profile
+
+# Fast preset: switch workflows to core (keeps delivery mode)
+openspec config profile core
+```
+
+`openspec config profile` starts with a current-state summary, then lets you choose:
+- Change delivery + workflows
+- Change delivery only
+- Change workflows only
+- Keep current settings (exit)
+
+If you keep current settings, no changes are written and no update prompt is shown.
+If there are no config changes but the current project files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest `openspec update`.
+Pressing `Ctrl+C` also cancels the flow cleanly (no stack trace) and exits with code `130`.
+In the workflow checklist, `[x]` means the workflow is selected in global config. To apply those selections to project files, run `openspec update` (or choose `Apply changes to this project now?` when prompted inside a project).
+
+**Interactive examples:**
+
+```bash
+# Delivery-only update
+openspec config profile
+# choose: Change delivery only
+# choose delivery: Skills only
+
+# Workflows-only update
+openspec config profile
+# choose: Change workflows only
+# toggle workflows in the checklist, then confirm
 ```
 
 ---
@@ -880,6 +1166,8 @@ openspec completion uninstall
 
 | Variable | Description |
 |----------|-------------|
+| `OPENSPEC_TELEMETRY` | Set to `0` to disable telemetry |
+| `DO_NOT_TRACK` | Set to `1` to disable telemetry (standard DNT signal) |
 | `OPENSPEC_CONCURRENCY` | Default concurrency for bulk validation (default: 6) |
 | `EDITOR` or `VISUAL` | Editor for `openspec config edit` |
 | `NO_COLOR` | Disable color output when set |
@@ -888,7 +1176,7 @@ openspec completion uninstall
 
 ## Related Documentation
 
-- [Commands](commands.md) - AI slash commands (`/opsx:new`, `/opsx:apply`, etc.)
+- [Commands](commands.md) - AI slash commands (`/opsx:propose`, `/opsx:apply`, etc.)
 - [Workflows](workflows.md) - Common patterns and when to use each command
 - [Customization](customization.md) - Create custom schemas and templates
 - [Getting Started](getting-started.md) - First-time setup guide

docs/commands.md

@@ -6,25 +6,75 @@ For workflow patterns and when to use each command, see [Workflows](workflows.md
 
 ## Quick Reference
 
+### Default Quick Path (`core` profile)
+
 | Command | Purpose |
 |---------|---------|
+| `/opsx:propose` | Create a change and generate planning artifacts in one step |
 | `/opsx:explore` | Think through ideas before committing to a change |
-| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact based on dependencies |
-| `/opsx:ff` | Fast-forward: create all planning artifacts at once |
 | `/opsx:apply` | Implement tasks from the change |
-| `/opsx:verify` | Validate implementation matches artifacts |
+| `/opsx:update` | Revise a change's planning artifacts and keep them coherent |
 | `/opsx:sync` | Merge delta specs into main specs |
 | `/opsx:archive` | Archive a completed change |
+
+### Expanded Workflow Commands (custom workflow selection)
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:new` | Start a new change scaffold |
+| `/opsx:continue` | Create the next artifact based on dependencies |
+| `/opsx:ff` | Fast-forward: create all planning artifacts at once |
+| `/opsx:verify` | Validate implementation matches artifacts |
 | `/opsx:bulk-archive` | Archive multiple changes at once |
 | `/opsx:onboard` | Guided tutorial through the complete workflow |
 
+The default global profile is `core`. To enable expanded workflow commands, run `openspec config profile`, select workflows, then run `openspec update` in your project.
+
 ---
 
 ## Command Reference
 
+### `/opsx:propose`
+
+Create a new change and generate planning artifacts in one step. This is the default start command in the `core` profile.
+
+**Syntax:**
+```text
+/opsx:propose [change-name-or-description]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name-or-description` | No | Kebab-case name or plain-language change description |
+
+**What it does:**
+- Creates `openspec/changes/<change-name>/`
+- Generates artifacts needed before implementation (for `spec-driven`: proposal, specs, design, tasks)
+- Stops when the change is ready for `/opsx:apply`
+
+**Example:**
+```text
+You: /opsx:propose add-dark-mode
+
+AI:  Created openspec/changes/add-dark-mode/
+     ✓ proposal.md
+     ✓ specs/ui/spec.md
+     ✓ design.md
+     ✓ tasks.md
+     Ready for implementation. Run /opsx:apply.
+```
+
+**Tips:**
+- Use this for the fastest end-to-end path
+- If you want step-by-step artifact control, enable expanded workflows and use `/opsx:new` + `/opsx:continue`
+
+---
+
 ### `/opsx:explore`
 
+> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
+
 Think through ideas, investigate problems, and clarify requirements before committing to a change.
 
 **Syntax:**
@@ -42,7 +92,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
-- Can transition to `/opsx:new` when insights crystallize
+- Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
 
 **Example:**
 ```text
@@ -66,7 +116,7 @@ AI:  Let me investigate your current auth setup...
 
 You: Let's go with JWT. Can we start a change for that?
 
-AI:  Ready when you are. Run /opsx:new add-jwt-auth to begin.
+AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
 ```
 
 **Tips:**
@@ -79,7 +129,9 @@ AI:  Ready when you are. Run /opsx:new add-jwt-auth to begin.
 
 ### `/opsx:new`
 
-Start a new change. Creates the change folder structure and scaffolds it with the selected schema.
+Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with `/opsx:continue` or `/opsx:ff`.
+
+This command is part of the expanded workflow set (not included in the default `core` profile).
 
 **Syntax:**
 ```
@@ -266,6 +318,55 @@ AI:  Implementing add-dark-mode...
 
 ---
 
+### `/opsx:update`
+
+Revise a change's existing planning artifacts and keep them coherent with one another. Planning artifacts only - it never edits code.
+
+**Syntax:**
+
+```text
+/opsx:update [change-name]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to update (inferred from context if not provided) |
+
+**What it does:**
+
+- Reads the change's artifacts via `openspec status --change <name> --json`
+- 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)
+
+**Example:**
+
+```text
+You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage
+
+AI:  Reading add-dark-mode artifacts...
+
+     The design references localStorage in two places; tasks 1.3 covers
+     localStorage persistence; the proposal doesn't mention storage.
+
+     Proposed revisions:
+     1. design.md - swap localStorage decision for cookie storage
+     2. tasks.md - reword task 1.3 to cookie persistence
+
+     Apply revision 1? (design.md)
+```
+
+**Tips:**
+
+- It won't create missing artifacts - that's `/opsx:continue`
+- 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))
+
+---
+
 ### `/opsx:verify`
 
 Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.
@@ -565,13 +666,17 @@ Different AI tools use slightly different command syntax. Use the format that ma
 
 | Tool | Syntax Example |
 |------|----------------|
-| Claude Code | `/opsx:new`, `/opsx:apply` |
-| Cursor | `/opsx-new`, `/opsx-apply` |
-| Windsurf | `/opsx-new`, `/opsx-apply` |
-| Copilot | `/opsx-new`, `/opsx-apply` |
-| Trae | `/openspec-new-change`, `/openspec-apply-change` |
+| Claude Code | `/opsx:propose`, `/opsx:apply` |
+| Cursor | `/opsx-propose`, `/opsx-apply` |
+| Windsurf | `/opsx-propose`, `/opsx-apply` |
+| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
+| Oh My Pi | `/opsx-propose`, `/opsx-apply` |
+| Kimi CLI | Skill-based invocations such as `/skill:openspec-propose`, `/skill:openspec-apply-change` (no generated `opsx-*` command files) |
+| Trae | `/opsx-propose`, `/opsx-apply` |
 
-The functionality is identical regardless of syntax.
+The intent is the same across tools, but how commands are surfaced can differ by integration.
+
+> **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds.
 
 ---
 

docs/concepts.md

@@ -7,10 +7,10 @@ This guide explains the core ideas behind OpenSpec and how they fit together. Fo
 OpenSpec is built around four principles:
 
 ```
-fluid not rigid       — no phase gates, work on what makes sense
+fluid not rigid         — no phase gates, work on what makes sense
 iterative not waterfall — learn as you build, refine as you go
-easy not complex      — lightweight setup, minimal ceremony
-brownfield-first      — works with existing codebases, not just greenfield
+easy not complex        — lightweight setup, minimal ceremony
+brownfield-first        — works with existing codebases, not just greenfield
 ```
 
 ### Why These Principles Matter
@@ -28,19 +28,19 @@ brownfield-first      — works with existing codebases, not just greenfield
 OpenSpec organizes your work into two main areas:
 
 ```
-┌─────────────────────────────────────────────────────────────────┐
-│                        openspec/                                 │
-│                                                                  │
-│   ┌─────────────────────┐      ┌──────────────────────────────┐ │
-│   │       specs/        │      │         changes/              │ │
-│   │                     │      │                               │ │
-│   │  Source of truth    │◄─────│  Proposed modifications       │ │
-│   │  How your system    │ merge│  Each change = one folder     │ │
-│   │  currently works    │      │  Contains artifacts + deltas  │ │
-│   │                     │      │                               │ │
-│   └─────────────────────┘      └──────────────────────────────┘ │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────┐
+│                        openspec/                                   │
+│                                                                    │
+│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
+│   │       specs/        │      │         changes/              │   │
+│   │                     │      │                               │   │
+│   │  Source of truth    │◄─────│  Proposed modifications       │   │
+│   │  How your system    │ merge│  Each change = one folder     │   │
+│   │  currently works    │      │  Contains artifacts + deltas  │   │
+│   │                     │      │                               │   │
+│   └─────────────────────┘      └───────────────────────────────┘   │
+│                                                                    │
+└────────────────────────────────────────────────────────────────────┘
 ```
 
 **Specs** are the source of truth — they describe how your system currently behaves.
@@ -133,6 +133,52 @@ The system MUST expire sessions after 30 minutes of inactivity.
 - **SHOULD** — recommended, but exceptions exist
 - **MAY** — optional
 
+### What a Spec Is (and Is Not)
+
+A spec is a **behavior contract**, not an implementation plan.
+
+Good spec content:
+- Observable behavior users or downstream systems rely on
+- Inputs, outputs, and error conditions
+- External constraints (security, privacy, reliability, compatibility)
+- Scenarios that can be tested or explicitly validated
+
+Avoid in specs:
+- Internal class/function names
+- Library or framework choices
+- Step-by-step implementation details
+- Detailed execution plans (those belong in `design.md` or `tasks.md`)
+
+Quick test:
+- If implementation can change without changing externally visible behavior, it likely does not belong in the spec.
+
+### Keep It Lightweight: Progressive Rigor
+
+OpenSpec aims to avoid bureaucracy. Use the lightest level that still makes the change verifiable.
+
+**Lite spec (default):**
+- Short behavior-first requirements
+- Clear scope and non-goals
+- A few concrete acceptance checks
+
+**Full spec (for higher risk):**
+- Cross-team or cross-repo changes
+- API/contract changes, migrations, security/privacy concerns
+- Changes where ambiguity is likely to cause expensive rework
+
+Most changes should stay in Lite mode.
+
+### Human + Agent Collaboration
+
+In many teams, humans explore and agents draft artifacts. The intended loop is:
+
+1. Human provides intent, context, and constraints.
+2. Agent converts this into behavior-first requirements and scenarios.
+3. Agent keeps implementation detail in `design.md` and `tasks.md`, not `spec.md`.
+4. Validation confirms structure and clarity before implementation.
+
+This keeps specs readable for humans and consistent for agents.
+
 ## Changes
 
 A change is a proposed modification to your system, packaged as a folder with everything needed to understand and implement it.
@@ -224,7 +270,7 @@ Delta specs describe **what's changing** relative to the current specs. See [Del
 
 The design captures **technical approach** and **architecture decisions**.
 
-```markdown
+````markdown
 # Design: Add Dark Mode
 
 ## Technical Approach
@@ -260,7 +306,7 @@ CSS Variables (applied to :root)
 - `src/contexts/ThemeContext.tsx` (new)
 - `src/components/ThemeToggle.tsx` (new)
 - `src/styles/globals.css` (modified)
-```
+````
 
 **When to update the design:**
 - Implementation reveals the approach won't work
@@ -512,17 +558,17 @@ openspec/
 ## How It All Fits Together
 
 ```
-┌─────────────────────────────────────────────────────────────────────────────┐
+┌──────────────────────────────────────────────────────────────────────────────┐
 │                              OPENSPEC FLOW                                   │
 │                                                                              │
 │   ┌────────────────┐                                                         │
-│   │  1. START      │  /opsx:new creates a change folder                      │
+│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
 │   │     CHANGE     │                                                         │
 │   └───────┬────────┘                                                         │
 │           │                                                                  │
 │           ▼                                                                  │
 │   ┌────────────────┐                                                         │
-│   │  2. CREATE     │  /opsx:ff or /opsx:continue                             │
+│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
 │   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
 │   │                │  (based on schema dependencies)                         │
 │   └───────┬────────┘                                                         │
@@ -541,13 +587,13 @@ openspec/
 │   └───────┬────────┘                                                         │
 │           │                                                                  │
 │           ▼                                                                  │
-│   ┌────────────────┐     ┌──────────────────────────────────────────────┐   │
-│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │   │
-│   │     CHANGE     │     │  Change folder moves to archive/             │   │
-│   └────────────────┘     │  Specs are now the updated source of truth   │   │
-│                          └──────────────────────────────────────────────┘   │
+│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
+│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
+│   │     CHANGE     │     │  Change folder moves to archive/             │    │
+│   └────────────────┘     │  Specs are now the updated source of truth   │    │
+│                          └──────────────────────────────────────────────┘    │
 │                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 **The virtuous cycle:**

docs/customization.md

@@ -337,6 +337,20 @@ Then edit `schema.yaml` to add:
 
 ---
 
+## Community Schemas
+
+OpenSpec also supports community-maintained schemas distributed via standalone repositories. These provide opinionated workflows that integrate OpenSpec with other tools or systems, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) works for spec-kit.
+
+Community schemas are not vendored into OpenSpec core — they live in their own repositories with their own release cadence. To use one, copy the schema bundle into your project's `openspec/schemas/<schema-name>/` directory (each repo's README has install instructions).
+
+| Schema | Maintainer | Repository | Description |
+|--------|-----------|-----------|-------------|
+| `superpowers-bridge` | @JiangWay | [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) | Integrates OpenSpec's artifact governance with [obra/superpowers](https://github.com/obra/superpowers) execution skills (brainstorming, writing-plans, TDD via subagents, code review, finishing). Adds an evidence-first `retrospective` artifact filling a gap Superpowers does not natively cover. |
+
+> Want to contribute a community schema? Open an issue with a link to your repository, or submit a PR adding a row to this table.
+
+---
+
 ## See Also
 
 - [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation

docs/editing-changes.md

@@ -0,0 +1,91 @@
+# Editing & Iterating on a Change
+
+**Every artifact in a change is just a Markdown file you can edit at any time.** There is no locked "planning phase," no approval gate, no special edit mode to enter. Want to change the proposal after you've started building? Open `proposal.md` and change it. Realized the design is wrong mid-implementation? Fix `design.md` and keep going. That's the whole answer, and it's by design.
+
+This page is for the moment you think "wait, can I go back and change that?" Yes. Here's how, for each common case.
+
+## Two ways to edit anything
+
+You always have both:
+
+1. **Edit the file directly.** Artifacts are plain Markdown in `openspec/changes/<name>/`. Open `proposal.md`, `design.md`, `tasks.md`, or a delta spec under `specs/` in your editor and change it. Nothing else is required.
+
+2. **Ask your AI to revise it.** In chat, just say what you want: "Update the proposal to drop the caching idea and add a rate-limit section," or "the design should use a queue, not polling." The AI edits the artifact for you, using the rest of the change as context.
+
+Use whichever fits the moment. Small wording tweak? Edit the file. Substantive rethink? Let the AI revise with full context.
+
+## "How do I update the proposal (or specs) after I've started?"
+
+Just update it. Same change, refined.
+
+If you're using the expanded commands, the natural flow is: edit the artifact, then run `/opsx:continue` to pick up from the new state, or `/opsx:apply` to keep implementing against the updated plan. If you're on the default `core` commands, edit the artifact and run `/opsx:apply`; it reads the current files, so it builds against whatever the artifacts now say.
+
+The mental model: artifacts are the live plan, not a signed contract. The AI always works from their current contents, so editing them steers the work.
+
+```text
+You: I want to change the approach in this change.
+
+You: [edit design.md, or tell the AI:]
+     Update design.md to use a background job instead of a synchronous call.
+
+AI:  Updated design.md. The task list still fits; want me to continue applying?
+
+You: /opsx:apply
+```
+
+This answers a very common question: there's no separate "update proposal" command because you don't need one. The file is the source of truth, and editing it (by hand or via the AI) is the update.
+
+## "How do I go back to review after implementing?"
+
+You don't have to "go back," because you never left. The workflow is fluid: review, edit, and implementation aren't sequential phases you're trapped in.
+
+Concretely, after some `/opsx:apply` work:
+
+- Want to re-examine the plan? Open the artifacts and read them, or run `openspec show <change>` in your terminal for a consolidated view.
+- Found something to change? Edit the artifact (or ask the AI to), then continue.
+- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
+
+There's no "review phase" to return to, because review is something you can do at any point, including after implementation.
+
+## "I edited the code by hand. How do I reconcile that with OpenSpec?"
+
+This happens constantly and it's fine. You tweaked something in your editor, and now the code and the artifacts disagree. Bring them back in sync in whichever direction is true:
+
+- **The code is now correct, the spec is stale.** Update the delta spec (and tasks, if relevant) to describe the behavior you actually shipped. The spec should match reality before you archive, because archiving merges the spec into your source of truth.
+- **The spec is correct, the code drifted.** Keep building or fixing until the code matches the spec.
+
+A fast way to surface mismatches is `/opsx:verify`: it reads your artifacts and your code and tells you where they diverge. Treat its output as a to-do list for reconciliation, then archive once they agree.
+
+The principle: at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does. Manual edits are welcome; just don't let them quietly desync the spec.
+
+## Refining a proposal you're not happy with
+
+If a generated proposal misses the mark, you have three good moves:
+
+- **Iterate in place.** Tell the AI what's off ("the scope is too broad, drop the admin features") and let it revise. Cheapest and usually right.
+- **Explore first, then re-propose.** If the problem is that the idea itself is unclear, step back to `/opsx:explore`, think it through, and let a sharper proposal come out of that. See [Explore First](explore.md).
+- **Start fresh.** If the intent has fundamentally changed, a new change can be clearer than patching the old one.
+
+That last move has its own decision guide, next.
+
+## When to update vs. start a new change
+
+Short version: **update when it's the same work refined; start new when the intent fundamentally changed or the scope exploded into different work.**
+
+- Same goal, better approach? Update.
+- Scope narrowing (ship the MVP now, more later)? Update, then archive, then a new change for phase two.
+- The problem itself changed ("add dark mode" became "build a full theming system")? New change.
+
+There's a full flowchart and worked examples in [Workflows: When to Update vs Start Fresh](workflows.md#when-to-update-vs-start-fresh) and a deeper treatment in [OPSX: When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh).
+
+## A note on tasks
+
+`tasks.md` is a living checklist, not a frozen plan. As you implement, you can add tasks you discover, remove ones that turned out unnecessary, or reorder them. The AI checks items off as it completes them during `/opsx:apply`, and it resumes from the first unchecked task if you come back later. Editing the list mid-flight is expected.
+
+## Where to go next
+
+- [Workflows](workflows.md) - patterns, plus the update-vs-new decision guide
+- [Reviewing a Change](reviewing-changes.md) - the two-minute pass on a plan before you build it
+- [Explore First](explore.md) - the place to step back to when an idea needs rethinking
+- [Commands](commands.md) - `/opsx:continue`, `/opsx:apply`, and `/opsx:verify` in detail
+- [Concepts: Artifacts](concepts.md#artifacts) - what each artifact is for

docs/examples.md

@@ -0,0 +1,215 @@
+# Examples & Recipes
+
+Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `sync`, `archive`); where the expanded set helps, it's noted.
+
+A reminder before you start: slash commands like `/opsx:propose` go in your **AI assistant's chat**, and `openspec` commands go in your **terminal**. If that's new, read [How Commands Work](how-commands-work.md) first. In the transcripts below, `You:` and `AI:` are the chat, and lines starting with `$` are the terminal.
+
+> **Not sure what you're building yet?** Most of these recipes are sharper if you start with `/opsx:explore` to think it through first. [Recipe 3](#recipe-3-exploring-before-you-commit) shows it in action, and the [Explore First](explore.md) guide makes the full case.
+
+## Recipe 1: A small feature, the fast path
+
+**When to use it:** you know what you want, and it's a contained piece of work. This is the most common recipe.
+
+The whole thing is three commands. Propose, build, archive.
+
+```text
+You: /opsx:propose add-logout-button
+
+AI:  Created openspec/changes/add-logout-button/
+     ✓ proposal.md — why and what
+     ✓ specs/      — the new requirement and its scenarios
+     ✓ design.md   — technical approach
+     ✓ tasks.md    — implementation checklist
+     Ready for implementation. Run /opsx:apply.
+```
+
+Now read the plan. Open the proposal and the delta spec. This is the moment OpenSpec is built for: catching a wrong assumption while it's still one paragraph, not 400 lines of code. Edit any artifact directly if something's off, then continue.
+
+```text
+You: /opsx:apply
+
+AI:  Working through tasks...
+     ✓ 1.1 Add logout button to header
+     ✓ 1.2 Clear session on click
+     ✓ 1.3 Add confirmation dialog
+     All tasks complete!
+
+You: /opsx:archive
+
+AI:  Archiving add-logout-button...
+     ✓ Merged specs into openspec/specs/auth/spec.md
+     ✓ Moved to openspec/changes/archive/2026-06-22-add-logout-button/
+     Done. Ready for the next change.
+```
+
+That's it. The logout behavior is now part of your specs, and the change is filed away with its full context.
+
+## Recipe 2: A bug fix
+
+**When to use it:** something is broken and you want the fix recorded as a deliberate change to behavior, not a mystery commit.
+
+Bug fixes work exactly like features. The difference is in how you frame the proposal: describe the *correct* behavior, not just "fix the bug."
+
+```text
+You: /opsx:propose fix-login-redirect-loop
+
+AI:  Created openspec/changes/fix-login-redirect-loop/
+     The proposal captures the current broken behavior and the
+     intended behavior. The delta spec MODIFIES the redirect
+     requirement so it's now precise and testable.
+     Ready for implementation.
+```
+
+Because the fix lands as a `MODIFIED` requirement with a fresh scenario, the next person (or the next AI session) sees not just that you fixed it, but what "correct" means. Then `/opsx:apply` and `/opsx:archive` as usual.
+
+Tip: for a fix, a good scenario is the regression test in prose. "GIVEN a logged-out user, WHEN they submit valid credentials, THEN they land on the dashboard and are not redirected again." Write that, and the implementation has a clear target.
+
+## Recipe 3: Exploring before you commit
+
+**When to use it:** you have a problem but not yet a plan. You're not sure what to build, or which approach is right.
+
+Start with `/opsx:explore`. It's a thinking partner with no structure and no artifacts created. It reads your codebase and helps you decide.
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: Page loads feel slow but I don't know where the time goes.
+
+AI:  Let me look... I found three likely culprits:
+     1. Large unoptimized images on the product list
+     2. Synchronous data fetching that blocks render
+     3. Re-renders triggered by context changes
+     Which should we tackle first?
+
+You: The data fetching one.
+
+You: /opsx:propose optimize-product-list-fetching
+
+AI:  Created the change, with a proposal informed by what we just
+     found. Ready for implementation.
+```
+
+Exploration clarifies your thinking *before* you spend a change on it. When the insight crystallizes, propose, and the AI carries the context forward.
+
+## Recipe 4: Juggling two changes at once
+
+**When to use it:** you're mid-feature and an urgent fix jumps the queue.
+
+Changes are independent folders, so parallel work doesn't conflict. Start the fix, ship it, then return to the feature right where you left off.
+
+```text
+You: I'm partway through add-dark-mode, but I need to fix a login bug now.
+
+You: /opsx:propose fix-login-redirect
+
+AI:  Created openspec/changes/fix-login-redirect/. Ready for implementation.
+
+You: /opsx:apply
+
+AI:  Implemented the fix. All tasks complete.
+
+You: /opsx:archive
+
+AI:  ✓ Archived fix-login-redirect.
+
+You: Back to dark mode.
+
+You: /opsx:apply add-dark-mode
+
+AI:  Resuming add-dark-mode. Picking up at task 2.3: Update Header...
+```
+
+Naming the change in `/opsx:apply add-dark-mode` is how you point the AI at a specific change when more than one is active. Because tasks track completion in `tasks.md`, the AI knows exactly where you stopped.
+
+When several changes are done at once, the expanded `/opsx:bulk-archive` files them together and resolves spec conflicts by checking what's actually implemented. See [Workflows](workflows.md#parallel-changes).
+
+## Recipe 5: A refactor with no behavior change
+
+**When to use it:** you're restructuring code, and externally visible behavior should stay identical.
+
+This is the interesting case, because a pure refactor has *nothing to add to your specs*. The behavior contract doesn't change; only the implementation does. So the work lives in the design and tasks, and the spec delta is empty or absent.
+
+```text
+You: /opsx:propose refactor-payment-module
+
+AI:  Created the change. The proposal states the goal (split the
+     payment module, no behavior change) and the design captures
+     the new structure. No spec changes, since behavior is identical.
+     Ready for implementation.
+```
+
+When you archive a change that doesn't touch specs, you can tell the terminal command to skip the spec step:
+
+```bash
+$ openspec archive refactor-payment-module --skip-specs
+```
+
+The same flag is handy for tooling, CI, and docs-only changes. The principle: specs describe behavior, so if behavior didn't change, the spec shouldn't either. See [Concepts](concepts.md#what-a-spec-is-and-is-not).
+
+## Recipe 6: Step-by-step control (expanded commands)
+
+**When to use it:** a complex or risky change where you want to review each artifact before moving on.
+
+The core `/opsx:propose` drafts everything at once. When you'd rather go one step at a time, turn on the expanded commands:
+
+```bash
+$ openspec config profile      # select the expanded workflows
+$ openspec update              # apply them to this project
+```
+
+Now you can scaffold and build incrementally:
+
+```text
+You: /opsx:new add-2fa
+
+AI:  Created openspec/changes/add-2fa/. Ready to create: proposal.
+
+You: /opsx:continue
+
+AI:  Created proposal.md. Now available: specs, design.
+
+You: /opsx:continue
+
+AI:  Created specs/auth/spec.md. Now available: design.
+```
+
+Review each artifact as it lands, edit freely, and continue when you're happy. When you want the rest drafted in one go, `/opsx:ff` fast-forwards through the remaining planning artifacts. Before archiving, `/opsx:verify` checks that the implementation actually matches the specs. See [Workflows](workflows.md#opsxff-vs-opsxcontinue).
+
+## Recipe 7: Learning the whole loop hands-on
+
+**When to use it:** you've installed OpenSpec and want to *feel* the workflow on your own code, not a toy example.
+
+Turn on the expanded commands (see Recipe 6), then:
+
+```text
+You: /opsx:onboard
+
+AI:  Welcome to OpenSpec! I'll walk you through a complete change
+     using your actual codebase. Let me scan for a small, safe
+     improvement we can make together...
+```
+
+`/opsx:onboard` finds a real (small) improvement, creates a change for it, implements it, and archives it, narrating every step. It takes 15 to 30 minutes and leaves you with a real change you can keep or discard. It's the gentlest way to learn. See [Commands](commands.md#opsxonboard).
+
+## Checking your work from the terminal
+
+Any time, from your terminal, you can inspect the state of things:
+
+```bash
+$ openspec list                      # active changes
+$ openspec show add-dark-mode        # one change in detail
+$ openspec validate add-dark-mode    # check structure
+$ openspec view                      # interactive dashboard
+```
+
+These are read-and-inspect tools. The proposing and building still happen through slash commands in chat. Full details in the [CLI reference](cli.md).
+
+## Where to go next
+
+- [Explore First](explore.md): the recommended way to start when you're unsure
+- [Workflows](workflows.md): the patterns above, with decision guidance on when to use each
+- [Commands](commands.md): every slash command in detail
+- [Getting Started](getting-started.md): the canonical first-change walkthrough
+- [Concepts](concepts.md): why the pieces fit together the way they do

docs/existing-projects.md

@@ -0,0 +1,134 @@
+# Using OpenSpec in an Existing Project
+
+**You do not document your whole codebase to start. You write specs only for what you're about to change.** That's the single most important thing to know about adopting OpenSpec on an existing project, and it's why OpenSpec is built brownfield-first.
+
+A common worry sounds like this: "My app is 80,000 lines old. Do I have to write specs for all of it before OpenSpec is useful?" No. You'd hate that, and so would we. OpenSpec grows your specs one change at a time. Your first change documents the slice it touches, the next change documents its slice, and over months your specs fill in naturally around the work you actually do.
+
+This guide shows how to start on day one without boiling the ocean.
+
+## The thirty-second version
+
+```bash
+$ cd your-existing-project
+$ openspec init          # adds openspec/ and your AI tool's commands
+```
+
+Then, in your AI chat:
+
+```text
+/opsx:explore            # optional: have the AI read the area you'll touch
+/opsx:propose <a real, small change you actually need>
+/opsx:apply
+/opsx:archive
+```
+
+Your specs now describe exactly the part of the system that change touched, and nothing more. That's correct. You're done worrying about the other 80,000 lines.
+
+## Why delta-first is the whole trick
+
+OpenSpec changes are written as **deltas**: `ADDED`, `MODIFIED`, `REMOVED`. A delta describes what's changing relative to current behavior, not the entire system.
+
+This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.
+
+So your `openspec/specs/` directory doesn't start full and complete. It starts nearly empty and accumulates. Each archived change merges its delta in. The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough.
+
+If you want the deeper mechanics, see [Concepts: Delta Specs](concepts.md#delta-specs).
+
+## Your first change on a real codebase
+
+Pick something small and real. Not a toy, not a rewrite. A change you were going to make this week anyway. Small first changes teach you the workflow with low stakes.
+
+**Step 1: Let the AI read the relevant area.** This is where `/opsx:explore` earns its keep on an unfamiliar or large codebase. Point it at the part you're about to touch and let it map how things work before proposing anything.
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: I need to add rate limiting to our public API, but I'm not sure
+     how requests currently flow through the middleware.
+
+AI:  Let me trace it... [reads the router, middleware stack, and config]
+     Requests hit Express, pass through auth middleware, then your
+     controllers. There's no rate-limiting layer today. The cleanest
+     insertion point is a middleware right after auth. Want me to scope it?
+```
+
+Notice the AI now understands your actual structure, so the proposal it writes will fit your code, not a generic template. On a big codebase, this single habit saves the most pain. See [Explore First](explore.md).
+
+**Step 2: Propose the change.** The proposal and its delta spec capture just this change.
+
+```text
+You: /opsx:propose add-api-rate-limiting
+```
+
+**Step 3: Build and archive** with `/opsx:apply` and `/opsx:archive`, same as any change. After archiving, you have a real spec for your rate-limiting behavior, born from a change you needed anyway.
+
+## Prefer a guided tour? Use onboard
+
+If you'd rather watch the whole loop happen on your own code with narration, the expanded command `/opsx:onboard` does exactly that: it scans your codebase for a small, safe improvement, then walks you through proposing, building, and archiving it, explaining each step.
+
+Turn on the expanded commands first:
+
+```bash
+$ openspec config profile      # select the expanded workflows
+$ openspec update              # apply them to this project
+```
+
+Then in chat:
+
+```text
+/opsx:onboard
+```
+
+It's the gentlest possible introduction on a real project, and it leaves you with a genuine (small) change you can keep or discard. See [Commands: `/opsx:onboard`](commands.md#opsxonboard).
+
+## "But I already have requirements docs"
+
+Maybe you have a PRD, an SRS, a formal spec, even TLA+ models. Good. You don't import them wholesale, and you don't throw them away either.
+
+Treat existing docs as **source material for exploration**, not as specs to convert. When you start a change, paste or point the AI at the relevant section, and let it shape a focused OpenSpec delta from it. The delta captures the behavior you're changing now, in OpenSpec's testable requirement-and-scenario form. Your original documents stay where they are as background.
+
+The honest reason: OpenSpec specs are deliberately behavior-first and scoped to changes. A 40-page PRD is a different artifact with a different job. Forcing a one-time bulk conversion tends to produce a large, stale spec nobody trusts. Letting specs grow from real changes keeps them accurate.
+
+```text
+You: /opsx:explore
+You: Here's the section of our PRD about checkout. I'm implementing the
+     "guest checkout" requirement next.
+     [paste the relevant requirement]
+AI:  [reads it, asks clarifying questions, then helps scope a change]
+You: /opsx:propose add-guest-checkout
+```
+
+## Organizing specs in a big codebase
+
+Specs live under `openspec/specs/`, grouped by **domain**: a logical area that matches how your team thinks about the system. You don't have to design the whole taxonomy up front. Create a domain folder when your first change in that area needs one.
+
+Common ways to slice domains:
+
+- **By feature area:** `auth/`, `payments/`, `search/`
+- **By component:** `api/`, `frontend/`, `workers/`
+- **By bounded context:** `ordering/`, `fulfillment/`, `inventory/`
+
+Pick whatever makes a newcomer nod. You can refine later. See [Concepts: Specs](concepts.md#specs).
+
+## Monorepos and work that spans repos
+
+For a monorepo, the simplest model is one `openspec/` directory at the repo root, with domains that map to your packages or services. That covers most teams.
+
+If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **stores** feature: planning lives in its own standalone repo that any of your code repos can reference, so the plan does not have to live inside one repo's `openspec/` folder. It's beta, so treat its commands and state as evolving. Start with the [Stores User Guide](stores-beta/user-guide.md) for the mental model and the smallest useful path.
+
+## A few honest cautions
+
+- **Resist the urge to back-fill everything.** Writing specs for code you aren't changing feels productive and usually isn't. Those specs go stale, because nothing forces them to track reality. Let real changes drive your specs.
+- **Keep early changes small.** Your first few changes are as much about learning the rhythm as shipping. A tight scope makes the loop fast and the lessons cheap.
+- **Commit `openspec/` to git.** Your specs and archive belong in version control alongside the code they describe.
+- **Give the AI context.** On a large codebase with strong conventions, fill in `openspec/config.yaml`'s `context:` so every proposal respects your stack and patterns. See [Customization](customization.md#project-configuration).
+
+## Where to go next
+
+- [Explore First](explore.md) - the key habit for understanding code before you change it
+- [Getting Started](getting-started.md) - the full first-change walkthrough
+- [Editing & Iterating on a Change](editing-changes.md) - adjusting a change as you learn
+- [Concepts: Delta Specs](concepts.md#delta-specs) - why deltas make brownfield work clean
+- [Customization](customization.md) - teach OpenSpec your project's conventions

docs/explore.md

@@ -0,0 +1,121 @@
+# Explore First
+
+**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a single artifact or line of code is created. When the picture is clear, it hands off to `/opsx:propose`.
+
+If you take one habit from these docs, take this one: **when you're not sure, explore before you propose.**
+
+Here's why that matters. AI coding assistants are eager. Ask vaguely and they'll confidently build *something*, just maybe not the thing you needed. Explore is the cure. It's a no-stakes conversation where you and the AI figure out the right move together, so that by the time you propose, you're proposing the right thing.
+
+## When to explore
+
+Explore is the right first step more often than people expect. Use it when any of these is true:
+
+- You know the *problem* but not the *solution*. ("Pages feel slow." "Auth is a mess." "We keep getting duplicate orders.")
+- You're choosing between approaches and want the tradeoffs laid out against your actual code.
+- You're new to a codebase and need to understand how something works before you change it.
+- The requirements are fuzzy and you want to sharpen them before committing.
+- You suspect the work is bigger or smaller than it looks and want to scope it honestly.
+
+Skip explore only when you already know exactly what you want and how. In that case go straight to [`/opsx:propose`](commands.md#opsxpropose).
+
+## What it does (and doesn't)
+
+Explore is a **conversation**, not a generator.
+
+**It does:**
+- Read and search your codebase to answer real questions.
+- Compare options and name the tradeoffs of each.
+- Draw diagrams to make a design legible.
+- Help you narrow a vague idea into a concrete, buildable scope.
+- Transition to `/opsx:propose` when you're ready.
+
+**It does not:**
+- Create a change folder.
+- Write any artifacts (no proposal, specs, design, or tasks).
+- Write or modify code.
+
+That's the point. Exploring costs you nothing and commits you to nothing. You can explore three dead ends, learn something from each, and only then propose the path that survived.
+
+## It's already installed
+
+Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `sync`, and `archive`. You don't need to enable anything. If OpenSpec is set up in your project, explore is ready in your AI chat. (As with all `/opsx:*` commands, you type it in your assistant's chat, not the terminal. See [How Commands Work](how-commands-work.md).)
+
+## A full example
+
+Watch how a vague worry becomes a sharp, buildable change.
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: Our checkout sometimes creates duplicate orders. I don't know why
+     and I don't know how to fix it safely.
+
+AI:  Let me dig into the checkout path...
+     [reads the order service, the payment webhook handler, and the
+      client submit logic]
+
+     Here's what I found. There are two ways a duplicate can happen:
+
+     1. The client can submit twice (double-click, retry on slow network).
+        Nothing debounces it.
+     2. The payment webhook can fire more than once, and the handler
+        creates an order each time. There's no idempotency key.
+
+     Cause #2 is the dangerous one: it can charge and fulfill twice.
+
+     Three ways to fix it, roughly in order of robustness:
+     - Idempotency key on the order-creation endpoint (handles both causes)
+     - Dedup on the webhook by payment-intent id (handles #2 only)
+     - Client-side debounce (handles #1 only, papers over the real bug)
+
+     Given your code already stores the payment-intent id, the
+     idempotency-key approach is a small change with the biggest payoff.
+     Want me to scope that?
+
+You: Yes, let's do the idempotency key.
+
+You: /opsx:propose add-order-idempotency-key
+
+AI:  Created openspec/changes/add-order-idempotency-key/, with a proposal
+     and delta spec grounded in what we just found. Ready for implementation.
+```
+
+Notice what happened. The starting point was "something is wrong and I'm scared to touch it." Twenty seconds of exploration turned that into a named root cause, three ranked options, a recommendation tied to the existing code, and a precise change. The proposal that follows is sharp because the thinking happened first.
+
+## Handing off to propose
+
+Explore doesn't archive into anything. When you're ready, you simply start a change, and the AI carries the context from your conversation into the artifacts.
+
+```text
+explore  ──►  propose  ──►  apply  ──►  archive
+ (think)     (agree)       (build)     (record)
+```
+
+You can say it in plain language ("let's turn this into a change") or run `/opsx:propose <name>` directly. Either way, the exploration you just did becomes the foundation of the proposal, not throwaway chat.
+
+If you use the expanded command set, explore can hand off to `/opsx:new` instead, for step-by-step artifact creation. See [Workflows](workflows.md).
+
+## Tips for a good exploration
+
+- **Bring the problem, not the solution.** "Logins feel slow" gives the AI room to investigate. "Add a Redis cache" pre-commits you to an answer you haven't tested yet.
+- **Ask for the tradeoffs out loud.** "What are the downsides of each option?" gets you a more honest comparison.
+- **Let it read first.** The best explorations start with the AI actually looking at your code, not guessing. Point it at the relevant area if it helps.
+- **It's okay to bail.** If exploration reveals the idea isn't worth it, that's a win. You learned it cheaply.
+- **Explore again mid-change.** Stuck during `/opsx:apply`? You can step back and explore a sub-problem, then return.
+
+## The honest tradeoffs
+
+**What you gain:** explore catches wrong turns at the cheapest possible moment, before any artifact exists. It's especially powerful in unfamiliar code, where the AI's ability to read and summarize the system saves you an afternoon of spelunking.
+
+**What it costs:** a little patience. Explore is a conversation, so it's slower than firing off `/opsx:propose` and hoping. For work you genuinely understand already, that extra step is pure overhead, and you should skip it.
+
+The rule of thumb: the fuzzier the task, the more explore pays off. The clearer the task, the more you can skip straight to proposing.
+
+## Where to go next
+
+- [Commands: `/opsx:explore`](commands.md#opsxexplore): the precise reference
+- [Workflows](workflows.md): explore as part of the everyday loop
+- [Examples & Recipes](examples.md#recipe-3-exploring-before-you-commit): explore in a full walkthrough
+- [Getting Started](getting-started.md): the first-change guide, exploration included

docs/faq.md

@@ -0,0 +1,155 @@
+# FAQ
+
+Quick answers to the questions people ask most. If your question is really a "something is broken" question, [Troubleshooting](troubleshooting.md) is the better page. If you want a term defined, see the [Glossary](glossary.md).
+
+## The basics
+
+### What is OpenSpec, in one sentence?
+
+A lightweight layer that gets you and your AI coding assistant to agree on what to build, in writing, before any code is written.
+
+### Why would I want that?
+
+Because AI assistants are confident even when they're wrong. When the requirements live only in a chat thread, the AI fills gaps with guesses, and you find out after the code exists. OpenSpec moves the agreement earlier, where mistakes are cheap to fix. See [Core Concepts at a Glance](overview.md) for the full case.
+
+### Do I have to use it for everything?
+
+No. Use it where agreement matters, which is most non-trivial work. For a one-character typo fix, the ceremony probably isn't worth it, and that's fine.
+
+### Can I use it on a big existing codebase, or only new projects?
+
+Existing codebases are the main event. OpenSpec is brownfield-first: you do not document your whole app up front. You write specs only for what each change touches, and your specs fill in over time around the work you actually do. There's a dedicated guide: [Using OpenSpec in an Existing Project](existing-projects.md).
+
+### Is it tied to one AI tool?
+
+No. OpenSpec works with 25+ assistants, including Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, Codex, and more. The full list and per-tool details are in [Supported Tools](supported-tools.md).
+
+## Running commands
+
+### Where do I type `/opsx:propose`?
+
+In your AI assistant's chat, not your terminal. This is the single most common point of confusion, so it has its own page: [How Commands Work](how-commands-work.md). Short version: `openspec ...` runs in the terminal, `/opsx:...` runs in chat.
+
+### How do I "start interactive mode"?
+
+There isn't a separate mode to start. You open your AI assistant like normal and type a slash command into its chat. The slash command is how you "enter" OpenSpec. (The one genuinely interactive terminal feature is `openspec view`, a dashboard for browsing specs and changes.) Full explanation in [How Commands Work](how-commands-work.md).
+
+### I typed a slash command and nothing happened. Why?
+
+Most likely you typed it in the terminal instead of your AI chat, or the commands aren't installed yet. Run `openspec update` in your project, restart your assistant, then try typing `/opsx` in chat and watch for autocomplete. [Troubleshooting](troubleshooting.md#commands-dont-show-up) has the full checklist.
+
+### Why is the syntax `/opsx:propose` in one tool and `/opsx-propose` in another?
+
+Each AI tool surfaces custom commands a little differently. The intent is identical; only the punctuation changes. Type a slash in your chat and the autocomplete shows you the form your tool expects. The per-tool table is in [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool).
+
+### What's the difference between a skill and a command?
+
+Both are files OpenSpec writes so your assistant can run the workflow. Skills (`.../skills/openspec-*/SKILL.md`) are the newer cross-tool standard; commands (`.../commands/opsx-*`) are the older per-tool slash files. You don't need to pick. You just type the slash command, and OpenSpec installs whichever your tool uses.
+
+## The workflow
+
+### Where should I start if I'm not sure what to build?
+
+With `/opsx:explore`. It's a no-stakes thinking partner that reads your codebase, lays out options, and turns a fuzzy problem into a concrete plan, all before any change or code exists. It's in the default profile, so it's always available. When the plan is clear, it hands off to `/opsx:propose`. This is the single best habit to form, because it stops an eager AI from confidently building the wrong thing. See [Explore First](explore.md).
+
+### What's the simplest possible flow?
+
+```text
+/opsx:explore (optional)   then   /opsx:propose <what you want>   then   /opsx:apply   then   /opsx:archive
+```
+
+Explore to think it through, propose to draft the plan, apply to build it, archive to file it away. Skip explore when you already know exactly what you want.
+
+### What's the difference between `/opsx:propose` and `/opsx:new`?
+
+`/opsx:propose` is the default one-step command: it creates the change and drafts all the planning artifacts at once. `/opsx:new` is part of the expanded command set and only scaffolds an empty change, leaving you to create artifacts one at a time with `/opsx:continue` (or all at once with `/opsx:ff`). Use propose unless you want step-by-step control. See [Commands](commands.md).
+
+### What are `core` and expanded profiles?
+
+A profile decides which slash commands get installed. **Core** (the default) gives you `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, and `onboard` for finer control. Switch with `openspec config profile`, then apply with `openspec update`.
+
+### Do I need to run `/opsx:sync`?
+
+Usually not. Sync merges a change's delta specs into your main specs, and `/opsx:archive` will offer to do it for you. Run sync manually only when you want the specs merged before archiving, for example on a long-running change. See [Commands](commands.md#opsxsync).
+
+### How do I edit a proposal, spec, or task after I've started?
+
+Just edit the file. Every artifact is plain Markdown in `openspec/changes/<name>/`, and there's no locked phase or special edit mode. Change it by hand, or ask your AI to revise it ("update the design to use a queue"), then keep going. The AI always works from the current file contents. Full guide: [Editing & Iterating on a Change](editing-changes.md).
+
+### Can I go back and change the plan after implementing some of it?
+
+Yes, at any time. The workflow is fluid, so review and editing aren't phases you get locked out of. Edit the artifact, then continue. If you want a structured check that the code still matches the plan, run `/opsx:verify`. See [Editing & Iterating on a Change](editing-changes.md#how-do-i-go-back-to-review-after-implementing).
+
+### I edited the code by hand. How do I reconcile it with the spec?
+
+Bring them back in sync before you archive, since archiving makes your specs the record of truth. If the code is now correct, update the delta spec to match what you shipped; if the spec is correct, keep building until the code agrees. `/opsx:verify` surfaces the mismatches. See [Editing & Iterating on a Change](editing-changes.md#i-edited-the-code-by-hand-how-do-i-reconcile-that-with-openspec).
+
+### When should I update an existing change versus start a new one?
+
+Update when it's the same work, refined. Start fresh when the intent fundamentally changed or the scope exploded into different work. There's a decision flowchart and examples in [Workflows](workflows.md#when-to-update-vs-start-fresh).
+
+### What if my session runs out of context, or requirements change mid-implementation?
+
+This is where specs earn their keep. Because the plan lives in files (not only in chat history), you can clear your context, start a fresh AI session, and pick up with `/opsx:apply`; it reads the artifacts and resumes from the first unchecked task. If requirements change, edit the artifacts to match the new reality and continue. Keeping a clean context window also produces better results; clear it before implementation.
+
+### Should I commit the `openspec/` folder to git?
+
+Yes. Your specs, active changes, and archive are part of your project's history. Commit them like any other source. The archive in particular becomes a durable record of why your system works the way it does.
+
+## Specs and changes
+
+### What goes in a spec versus a design?
+
+A spec describes observable behavior: what the system does, its inputs, outputs, and error conditions. A design describes how you'll build it: the technical approach, architecture decisions, file changes. If implementation could change without changing externally visible behavior, it belongs in the design, not the spec. [Concepts](concepts.md#what-a-spec-is-and-is-not) goes deeper.
+
+### What's a delta spec?
+
+A spec that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the whole spec. It's how OpenSpec handles edits to existing systems cleanly. See [Concepts](concepts.md#delta-specs).
+
+### Where do archived changes go?
+
+To `openspec/changes/archive/YYYY-MM-DD-<name>/`, with all artifacts preserved. Nothing is deleted; the change just moves out of your active list.
+
+## Configuration and customization
+
+### How do I tell the AI about my tech stack?
+
+Put it in `openspec/config.yaml` under `context:`. That text is injected into every planning request, so the AI always knows your stack and conventions. See [Customization](customization.md#project-configuration).
+
+### Can I generate specs in a language other than English?
+
+Yes. Add a language instruction to your config's `context:`. [Multi-Language](multi-language.md) has copy-paste snippets for several languages.
+
+### Can I change the workflow itself?
+
+Yes, with custom schemas. A schema defines which artifacts exist and how they depend on each other. Fork the default with `openspec schema fork spec-driven my-workflow`, then edit it. See [Customization](customization.md#custom-schemas).
+
+## Models, privacy, and upgrades
+
+### Which AI model should I use?
+
+OpenSpec works best with high-reasoning models. The README recommends models like Codex 5.5 and Opus 4.7 for both planning and implementation. Also keep your context window clean: clear it before implementation for best results.
+
+### Does OpenSpec collect data?
+
+It collects anonymous usage stats: command names and version only. No arguments, paths, content, or personal data, and it's off automatically in CI. Opt out with `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`.
+
+### How do I upgrade?
+
+Two steps. Upgrade the package (`npm install -g @fission-ai/openspec@latest`), then run `openspec update` inside each project to refresh the generated skills and commands.
+
+### How do I uninstall OpenSpec?
+
+There's no uninstall command, because it's just a global package plus files in your project. Remove the package (`npm uninstall -g @fission-ai/openspec`), and optionally delete the `openspec/` directory and the generated tool files. Step-by-step, including what's safe to keep, is in [Installation: Uninstalling](installation.md#uninstalling).
+
+## Getting help
+
+### Where do I ask questions or report bugs?
+
+- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
+- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
+- **From your terminal:** `openspec feedback "your message"` opens a GitHub issue for you.
+
+### These docs are wrong or confusing. What do I do?
+
+Tell us, or fix it. Documentation PRs are welcome and valued. Open an issue or send a pull request.

docs/getting-started.md

@@ -1,36 +1,52 @@
 # Getting Started
 
-This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start).
+This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start) or the [Installation guide](installation.md). New to the whole docs set? The [documentation home](README.md) maps everything.
+
+> **Where do I type these commands?** Two places, and mixing them up is the most common early stumble.
+>
+> - `openspec ...` commands (like `openspec init`) run in your **terminal**.
+> - `/opsx:...` commands (like `/opsx:propose`) run in your **AI assistant's chat**, the same box where you'd ask it to write code.
+>
+> There's no separate "interactive mode" to start. You just type the slash command in chat and your assistant takes it from there. Full explanation: [How Commands Work](how-commands-work.md).
+
+## Your First Five Minutes
+
+The whole loop, with each step labeled by where it happens:
+
+```text
+TERMINAL   $ npm install -g @fission-ai/openspec@latest
+TERMINAL   $ cd your-project && openspec init
+AI CHAT      /opsx:explore                    (optional: think it through first)
+AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
+AI CHAT      /opsx:apply                      (AI builds it)
+AI CHAT      /opsx:archive                    (specs updated, change filed away)
+```
+
+Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see.
+
+> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md).
 
 ## How It Works
 
-OpenSpec helps you and your AI coding assistant agree on what to build before any code is written. The workflow follows a simple pattern:
+OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
 
+**Default quick path (core profile):**
+
+```text
+/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
+   (optional)
 ```
-┌────────────────────┐
-│ Start a Change     │  /opsx:new
-└────────┬───────────┘
-         │
-         ▼
-┌────────────────────┐
-│ Create Artifacts   │  /opsx:ff or /opsx:continue
-│ (proposal, specs,  │
-│  design, tasks)    │
-└────────┬───────────┘
-         │
-         ▼
-┌────────────────────┐
-│ Implement Tasks    │  /opsx:apply
-│ (AI writes code)   │
-└────────┬───────────┘
-         │
-         ▼
-┌────────────────────┐
-│ Archive & Merge    │  /opsx:archive
-│ Specs              │
-└────────────────────┘
+
+Start with `/opsx:explore` when you're figuring out what to do, or jump straight to `/opsx:propose` when you already know. Explore is in the default profile, so it's always there when you want it.
+
+**Expanded path (custom workflow selection):**
+
+```text
+/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
 ```
 
+The default global profile is `core`, which includes `propose`, `explore`, `apply`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`.
+
 ## What OpenSpec Creates
 
 After running `openspec init`, your project has this structure:
@@ -131,23 +147,12 @@ The change folder moves to `openspec/changes/archive/` for audit history.
 
 Let's walk through adding dark mode to an application.
 
-### 1. Start the Change
+### 1. Start the Change (Default)
 
-```
-You: /opsx:new add-dark-mode
+```text
+You: /opsx:propose add-dark-mode
 
 AI:  Created openspec/changes/add-dark-mode/
-     Ready to create: proposal
-```
-
-### 2. Create Artifacts
-
-Use `/opsx:ff` (fast-forward) to create all planning artifacts at once:
-
-```
-You: /opsx:ff
-
-AI:  Creating artifacts for add-dark-mode...
      ✓ proposal.md — why we're doing this, what's changing
      ✓ specs/       — requirements and scenarios
      ✓ design.md    — technical approach
@@ -155,7 +160,9 @@ AI:  Creating artifacts for add-dark-mode...
      Ready for implementation!
 ```
 
-### 3. What Gets Created
+If you've enabled the expanded workflow profile, you can also do this as two steps: `/opsx:new` then `/opsx:ff` (or `/opsx:continue` incrementally).
+
+### 2. What Gets Created
 
 **proposal.md** - Captures the intent:
 
@@ -218,7 +225,7 @@ The system SHALL allow users to choose between light and dark themes.
 - [ ] 3.2 Update components to use CSS variables
 ```
 
-### 4. Implement
+### 3. Implement
 
 ```
 You: /opsx:apply
@@ -234,7 +241,7 @@ AI:  Working through tasks...
 
 During implementation, if you discover the design needs adjustment, just update the artifact and continue.
 
-### 5. Archive
+### 4. Archive
 
 ```
 You: /opsx:archive
@@ -267,7 +274,16 @@ openspec view
 
 ## Next Steps
 
+- [Explore First](explore.md) - Use `/opsx:explore` to think through an idea before you commit
+- [Reviewing a Change](reviewing-changes.md) - What to check in the plan the AI drafts, before any code
+- [Writing Good Specs](writing-specs.md) - What a strong requirement and scenario look like
+- [Using OpenSpec in an Existing Project](existing-projects.md) - Start on a large brownfield codebase
+- [Editing & Iterating on a Change](editing-changes.md) - Update artifacts, go back, reconcile manual edits
+- [Core Concepts at a Glance](overview.md) - The whole mental model on one page
+- [Examples & Recipes](examples.md) - Real changes, start to finish
 - [Workflows](workflows.md) - Common patterns and when to use each command
 - [Commands](commands.md) - Full reference for all slash commands
 - [Concepts](concepts.md) - Deeper understanding of specs, changes, and schemas
 - [Customization](customization.md) - Make OpenSpec work your way
+- [Stores](stores-beta/user-guide.md) - Planning that spans repos or teams? Keep it in its own repo (beta)
+- [FAQ](faq.md) and [Troubleshooting](troubleshooting.md) - When you get stuck

docs/glossary.md

@@ -0,0 +1,91 @@
+# Glossary
+
+Every OpenSpec term in one place, defined in plain language. Skim it once and the rest of the docs read faster.
+
+Terms are grouped by topic, then alphabetized within each group.
+
+## The core nouns
+
+**Spec.** A document describing how part of your system behaves. Specs live in `openspec/specs/`, are organized by domain, and are made of requirements and scenarios. The spec is the agreed-upon answer to "what does this software do?" See [Concepts](concepts.md#specs).
+
+**Source of truth.** The `openspec/specs/` directory as a whole. It holds the current, agreed-upon behavior of your system. Changes propose edits to it; archiving applies them.
+
+**Change.** One unit of work, packaged as a folder under `openspec/changes/<name>/`. A change holds everything about that work: its proposal, design, tasks, and the spec edits it introduces. One change, one feature or fix.
+
+**Artifact.** A document inside a change. The standard artifacts are the proposal, the delta specs, the design, and the tasks. They're created in dependency order and feed into each other.
+
+**Delta spec.** A spec inside a change that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the entire spec. This is what lets OpenSpec edit existing systems cleanly. See [Concepts](concepts.md#delta-specs).
+
+**Domain.** A logical grouping for specs, like `auth/`, `payments/`, or `ui/`. You choose domains that match how you think about your system.
+
+## Inside a spec
+
+**Requirement.** A single behavior the system must have, usually written with an RFC 2119 keyword: "The system SHALL expire sessions after 30 minutes." Requirements state the *what*, not the *how*.
+
+**Scenario.** A concrete, testable example of a requirement in action, typically in Given/When/Then form. Scenarios make a requirement verifiable: you could write an automated test from one.
+
+**RFC 2119 keywords.** The words MUST, SHALL, SHOULD, and MAY, which carry standardized meaning about how strict a requirement is. MUST and SHALL are absolute. SHOULD is recommended with room for exceptions. MAY is optional. The name comes from the internet standards document that defined them.
+
+## The artifacts
+
+**Proposal (`proposal.md`).** The *why* and *what* of a change: its intent, scope, and high-level approach. The first artifact you create.
+
+**Design (`design.md`).** The *how*: technical approach, architecture decisions, and the files you expect to touch. Optional for simple changes.
+
+**Tasks (`tasks.md`).** The implementation checklist, with checkboxes. The AI works through it during `/opsx:apply` and checks items off as it goes.
+
+## The lifecycle
+
+**Archive.** The act of finishing a change. Its delta specs merge into the main specs, and the change folder moves to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After archiving, your specs describe the new reality. See [Concepts](concepts.md#archive).
+
+**Sync.** Merging a change's delta specs into the main specs *without* archiving the change. Usually automatic (archive offers to do it), but available on its own as `/opsx:sync` for long-running changes. See [Commands](commands.md#opsxsync).
+
+## Workflow and commands
+
+**OPSX.** The current standard OpenSpec workflow, built around fluid actions instead of rigid phases. Its slash commands all start with `/opsx:`. See [OPSX Workflow](opsx.md).
+
+**Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md).
+
+**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan, creating no artifacts and writing no code. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md).
+
+**CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md).
+
+**Skill.** A folder of instructions (`.../skills/openspec-*/SKILL.md`) that your AI assistant auto-detects and follows. Skills are the emerging cross-tool standard for delivering the OpenSpec workflow to your assistant.
+
+**Command file.** A per-tool slash command file (`.../commands/opsx-*`). The older delivery mechanism, still supported alongside skills. You rarely touch these directly.
+
+**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `sync`, `archive`. The **expanded** set adds `new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`. Change it with `openspec config profile`.
+
+**Delivery.** Whether OpenSpec installs skills, command files, or both for your tools. Configured globally and applied with `openspec update`.
+
+## Customization
+
+**Schema.** The definition of which artifacts a workflow has and how they depend on one another. The built-in default is `spec-driven` (proposal → specs → design → tasks). You can fork it or write your own. See [Customization](customization.md#custom-schemas).
+
+**Template.** A Markdown file inside a schema that shapes what the AI generates for a given artifact. Editing a template changes the AI's output immediately, with no rebuild.
+
+**Project config (`openspec/config.yaml`).** Per-project settings: the default schema, the `context:` injected into every planning request, and per-artifact `rules:`. The easiest way to teach OpenSpec about your stack and conventions. See [Customization](customization.md#project-configuration).
+
+**Context injection.** Putting project background in `config.yaml`'s `context:` field so it's automatically added to every artifact the AI generates. More reliable than hoping the AI reads a separate file.
+
+**Dependency graph.** The directed graph formed by artifact `requires:` relationships. It's a DAG (directed acyclic graph: arrows only point forward, never in a loop), and OpenSpec uses it to know what you can create next.
+
+**Enablers, not gates.** The principle that artifact dependencies show what becomes *possible* next, not what's *required* next. You can revisit and edit any artifact at any time. See [Core Concepts at a Glance](overview.md#enablers-not-gates).
+
+## Coordination across repos (beta)
+
+These terms apply only if your planning spans more than one repo. They're in beta. Most users can ignore them. See the [Stores User Guide](stores-beta/user-guide.md).
+
+**Store.** A standalone repo whose whole job is planning. It has the same `openspec/` shape you already know (specs and changes) plus a small identity file. You register it on your machine once, by name, and then any OpenSpec command can work in it from anywhere.
+
+**Reference.** A declaration, in a code repo's `openspec/config.yaml`, of a store that repo draws on. References are read-only: the repo keeps its own root, and `openspec instructions` gains an index of the referenced store's specs, each with the exact command to fetch it.
+
+**Working context.** What `openspec context` assembles for the current repo: its OpenSpec root plus every store it references, each with how to fetch it. The answer to "what am I working with?"
+
+**Workset.** A personal, machine-local set of folders you open together (a store alongside the code repos you work on). Created explicitly with `openspec workset create`; nothing about those local paths is committed to the shared planning repo.
+
+## See also
+
+- [Core Concepts at a Glance](overview.md): the five ideas, on one page
+- [Concepts](concepts.md): the long-form explanation
+- [How Commands Work](how-commands-work.md): slash commands versus the CLI

docs/how-commands-work.md

@@ -0,0 +1,160 @@
+# How Commands Work
+
+**The one thing to know: OpenSpec has two kinds of commands, and they run in two different places.**
+
+- `openspec ...` commands run in your **terminal**. (Example: `openspec init`.)
+- `/opsx:...` commands run in your **AI assistant's chat**. (Example: `/opsx:propose`.)
+
+If you ever type `/opsx:propose` into your terminal and nothing happens, this page is why. You are talking to the wrong half of OpenSpec. Slash commands are not terminal commands. They are instructions you give to your AI coding assistant, in the same chat box where you'd normally type "add a login form."
+
+That single distinction is the most common stumbling block for new users, so let's make it crystal clear.
+
+## The two halves
+
+OpenSpec is one project wearing two hats.
+
+**The CLI (terminal half).** A program named `openspec` that you install and run from your shell. It sets up your project, lists and validates changes, shows a dashboard, and archives finished work. You type these into iTerm, the VS Code terminal, PowerShell, anywhere you'd run `git` or `npm`.
+
+```bash
+openspec init        # set up OpenSpec in this project
+openspec list        # see active changes
+openspec view        # open the interactive dashboard
+```
+
+**The slash commands (chat half).** Short commands like `/opsx:propose` and `/opsx:apply` that you type into your AI assistant. These tell the AI to follow the OpenSpec workflow: draft a proposal, write specs, build from the task list, archive when done. You type these into Claude Code, Cursor, Windsurf, Copilot, or whichever assistant you use.
+
+```text
+/opsx:propose add-dark-mode    (typed in your AI chat)
+/opsx:apply                    (typed in your AI chat)
+/opsx:archive                  (typed in your AI chat)
+```
+
+Here's the mental model in one picture:
+
+```text
+        YOUR TERMINAL                         YOUR AI ASSISTANT'S CHAT
+   ┌──────────────────────┐               ┌──────────────────────────────┐
+   │  $ openspec init     │   installs    │  /opsx:propose add-dark-mode  │
+   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
+   │  $ openspec view     │   commands    │  /opsx:archive                │
+   └──────────────────────┘    & skills   └──────────────────────────────┘
+        run openspec here                       run /opsx:* here
+```
+
+Notice the arrow. Running `openspec init` in your terminal is what *installs* the slash commands into your AI tool. The terminal half sets up the chat half. After that, day-to-day driving mostly happens in chat.
+
+## "How do I start interactive mode?"
+
+**There is no separate interactive mode to start.** This question comes up a lot, so it deserves a plain answer.
+
+You don't enter a special OpenSpec mode. You just open your AI coding assistant like you always do, and type a slash command into the chat. The slash command *is* how you "enter" OpenSpec. Your assistant recognizes it, loads the matching OpenSpec skill, and starts following the workflow.
+
+So the real instructions are:
+
+1. Open your AI coding assistant (Claude Code, Cursor, Windsurf, and so on) in your project.
+2. Type `/opsx:propose` in its chat, the same place you type any other request.
+3. Watch the autocomplete: if OpenSpec is installed, you'll see `/opsx:propose`, `/opsx:apply`, and friends appear as you type the slash.
+
+That's it. No mode to toggle, no daemon to launch, no separate window.
+
+One thing that *is* genuinely interactive lives in the terminal: `openspec view`. It opens a dashboard for browsing your specs and changes. But that's a viewer, not the thing you propose and build with. The building happens through slash commands in chat.
+
+## Why this split exists
+
+It's worth understanding, because it explains why OpenSpec works with 25+ different AI tools.
+
+The CLI is the **engine**. It knows the rules: what a change folder looks like, which artifacts depend on which, how to merge a delta spec into your source of truth. It's the same everywhere.
+
+The slash commands are the **steering wheel**, and every AI tool has a slightly different one. Claude Code calls them commands. Cursor and Windsurf have their own formats. Some tools call them skills. When you run `openspec init`, OpenSpec generates the right kind of file for each tool you selected, so the same `/opsx:propose` intent works no matter which assistant you prefer.
+
+The strength of this design: you learn the workflow once and carry it across tools. The tradeoff: the exact syntax of a command can differ slightly between tools, which is the next section.
+
+## Slash command syntax by tool
+
+The intent is identical everywhere. The punctuation differs. Use the form that matches your assistant.
+
+| Tool | How you type it |
+|------|-----------------|
+| Claude Code | `/opsx:propose`, `/opsx:apply` |
+| Cursor | `/opsx-propose`, `/opsx-apply` |
+| Windsurf | `/opsx-propose`, `/opsx-apply` |
+| GitHub Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
+| Oh My Pi | `/opsx-propose`, `/opsx-apply` |
+| Kimi CLI | skill-style, e.g. `/skill:openspec-propose` |
+| Trae | `/opsx-propose`, `/opsx-apply` |
+
+Most tools use either the colon form (`/opsx:propose`) or the dash form (`/opsx-propose`). A few tools surface OpenSpec as named skills instead of slash commands; for those you invoke the skill by name. The full per-tool list, including exactly which files get written where, lives in [Supported Tools](supported-tools.md).
+
+When in doubt, type a slash in your AI chat and look at the autocomplete. Your tool will show you the form it expects.
+
+## How the commands got there: skills and commands
+
+When you run `openspec init` (or `openspec update`), OpenSpec writes small files into your project so your AI tool can find the workflow. Depending on your tool and settings, these are **skills**, **commands**, or both.
+
+- **Skills** live in places like `.claude/skills/openspec-*/SKILL.md`. They're the emerging cross-tool standard: a folder of instructions your assistant auto-detects.
+- **Commands** live in places like `.claude/commands/opsx/<id>.md`. They're the older per-tool slash command files.
+
+You don't have to care which one your tool uses. You just type the slash command and it works. But knowing these files exist helps when something goes wrong: if your commands vanish, it usually means these files are missing or stale, and `openspec update` regenerates them.
+
+See [Supported Tools](supported-tools.md) for the exact paths per tool, and [Migration Guide](migration-guide.md) for how skills replaced the older command-only approach.
+
+## Confirming it's installed
+
+Quick checks, fastest first:
+
+1. **Type a slash in your AI chat.** Start typing `/opsx` and watch for autocomplete suggestions. If they appear, you're set.
+2. **Look for the files.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories ([Supported Tools](supported-tools.md) lists them).
+3. **Re-run setup.** From your project root, run `openspec update`. This regenerates the skill and command files for whatever tools you configured.
+4. **Restart your assistant.** Many tools scan for skills and commands at startup, so a fresh window can be the missing step.
+
+## Which commands do I even have?
+
+By default, OpenSpec installs the **core** set of slash commands:
+
+- `/opsx:explore`: think through an idea with the AI before committing to a change (great first step when you're unsure)
+- `/opsx:propose`: create a change and draft all its planning artifacts in one step
+- `/opsx:apply`: build the change by working through its task list
+- `/opsx:sync`: merge a change's spec updates into your main specs (usually automatic)
+- `/opsx:archive`: finish a change and file it away
+
+A good default rhythm: `explore` when you're figuring out what to do, then `propose`, `apply`, `archive`. The [Explore First](explore.md) guide explains why that opening step pays off.
+
+There's also an **expanded** set for people who want finer control (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`). You turn it on with `openspec config profile`, then apply it with `openspec update`.
+
+New to all of this? `/opsx:onboard` (in the expanded set) walks you through a complete change on your own codebase, narrating each step. It's the friendliest possible introduction.
+
+For what each command does in detail, see [Commands](commands.md). For when to reach for which, see [Workflows](workflows.md).
+
+## A clean first run
+
+Putting it together, here is the whole sequence with each step labeled by where it happens.
+
+```text
+TERMINAL   $ npm install -g @fission-ai/openspec@latest
+TERMINAL   $ cd your-project
+TERMINAL   $ openspec init
+              (installs slash commands into your AI tool)
+
+AI CHAT      /opsx:explore
+              (optional: think the idea through with the AI first)
+
+AI CHAT      /opsx:propose add-dark-mode
+              (AI drafts proposal, specs, design, tasks)
+
+AI CHAT      /opsx:apply
+              (AI builds it, checking off tasks)
+
+AI CHAT      /opsx:archive
+              (change is merged into your specs and filed away)
+```
+
+Two terminal steps to set up. Then you live in chat. That's the rhythm.
+
+## Related
+
+- [Getting Started](getting-started.md): the full first-change walkthrough
+- [Commands](commands.md): every slash command in detail
+- [CLI](cli.md): every terminal command in detail
+- [Supported Tools](supported-tools.md): per-tool syntax and file locations
+- [FAQ](faq.md): more quick answers
+- [Troubleshooting](troubleshooting.md): fixes when commands don't show up

docs/installation.md

@@ -26,6 +26,9 @@ yarn global add @fission-ai/openspec@latest
 
 ### bun
 
+Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
+You still need Node.js 20.19.0 or higher available on `PATH`.
+
 ```bash
 bun add -g @fission-ai/openspec@latest
 ```
@@ -67,6 +70,39 @@ Or add to your development environment in `flake.nix`:
 openspec --version
 ```
 
+## Updating
+
+Upgrade the package, then refresh each project's generated files:
+
+```bash
+npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
+openspec update                              # run inside each project
+```
+
+`openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version.
+
+## Uninstalling
+
+There's no `openspec uninstall` command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
+
+**1. Remove the global package:**
+
+```bash
+npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
+```
+
+**2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
+
+```bash
+rm -rf openspec/
+```
+
+Think before you do this: `openspec/specs/` and `openspec/changes/archive/` are your record of how the system behaves and why it changed. If you might want that history, keep the folder (or keep it in git) even after uninstalling.
+
+**3. Remove generated AI tool files (optional).** OpenSpec writes skill and command files into per-tool directories like `.claude/skills/openspec-*/`, `.cursor/commands/opsx-*`, and so on. Delete the `openspec-*` skills and `opsx-*` commands for whichever tools you configured. The exact paths per tool are listed in [Supported Tools](supported-tools.md).
+
+If you also have OpenSpec marker blocks in files like `CLAUDE.md` or `AGENTS.md`, remove those blocks by hand; your own content in those files is yours to keep.
+
 ## Next Steps
 
 After installing, initialize OpenSpec in your project:

docs/migration-guide.md

@@ -8,7 +8,7 @@ OPSX replaces the old phase-locked workflow with a fluid, action-based approach.
 
 | Aspect | Legacy | OPSX |
 |--------|--------|------|
-| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | `/opsx:new`, `/opsx:continue`, `/opsx:apply`, and more |
+| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
 | **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice |
 | **Going back** | Awkward phase gates | Natural—update any artifact anytime |
 | **Customization** | Fixed structure | Schema-driven, fully hackable |
@@ -46,7 +46,7 @@ Only OpenSpec-managed files that are being replaced:
 - Windsurf: `.windsurf/workflows/openspec-*.md`
 - Cline: `.clinerules/workflows/openspec-*.md`
 - Roo: `.roo/commands/openspec-*.md`
-- GitHub Copilot: `.github/prompts/openspec-*.prompt.md`
+- GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
 - And others (Augment, Continue, Amazon Q, etc.)
 
 The migration detects whichever tools you have configured and cleans up their legacy files.
@@ -84,6 +84,9 @@ Don't worry about getting it perfect. We're still learning what works best here,
 
 Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation:
 
+- New installs default to profile `core` (`propose`, `explore`, `apply`, `sync`, `archive`).
+- Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed.
+
 ### Using `openspec init`
 
 Run this if you want to add new tools or reconfigure which tools are set up:
@@ -141,7 +144,7 @@ Run this if you just want to migrate and refresh your existing tools to the late
 openspec update
 ```
 
-The update command also detects and cleans up legacy artifacts, then refreshes your skills to the latest version.
+The update command also detects and cleans up legacy artifacts, then refreshes generated skills/commands to match your current profile and delivery settings.
 
 ### Non-Interactive / CI Environments
 
@@ -275,30 +278,43 @@ The AI will help you identify what's essential vs. what can be trimmed.
 
 ## The New Commands
 
-After migration, you have 9 OPSX commands instead of 3:
+Command availability is profile-dependent:
+
+**Default (`core` profile):**
 
 | Command | Purpose |
 |---------|---------|
+| `/opsx:propose` | Create a change and generate planning artifacts in one step |
 | `/opsx:explore` | Think through ideas with no structure |
-| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact (one at a time) |
-| `/opsx:ff` | Fast-forward—create all planning artifacts at once |
 | `/opsx:apply` | Implement tasks from tasks.md |
-| `/opsx:verify` | Validate implementation matches specs |
-| `/opsx:sync` | Preview spec merge (optional—archive prompts if needed) |
 | `/opsx:archive` | Finalize and archive the change |
+
+**Expanded workflow (custom selection):**
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:new` | Start a new change scaffold |
+| `/opsx:continue` | Create the next artifact (one at a time) |
+| `/opsx:ff` | Fast-forward—create planning artifacts at once |
+| `/opsx:verify` | Validate implementation matches specs |
+| `/opsx:sync` | Merge delta specs into main specs |
 | `/opsx:bulk-archive` | Archive multiple changes at once |
+| `/opsx:onboard` | Guided end-to-end onboarding workflow |
+
+Enable expanded commands with `openspec config profile`, then run `openspec update`.
 
 ### Command Mapping from Legacy
 
 | Legacy | OPSX Equivalent |
 |--------|-----------------|
-| `/openspec:proposal` | `/opsx:new` then `/opsx:ff` |
+| `/openspec:proposal` | `/opsx:propose` (default) or `/opsx:new` then `/opsx:ff` (expanded) |
 | `/openspec:apply` | `/opsx:apply` |
 | `/openspec:archive` | `/opsx:archive` |
 
 ### New Capabilities
 
+These capabilities are part of the expanded workflow command set.
+
 **Granular artifact creation:**
 ```
 /opsx:continue
@@ -332,14 +348,14 @@ Too bad. Phase gates don't let you go back easily.
 OPSX uses actions, not phases:
 
 ```
-         ┌────────────────────────────────────────┐
-         │           ACTIONS (not phases)         │
-         │                                        │
+         ┌───────────────────────────────────────────────┐
+         │           ACTIONS (not phases)                │
+         │                                               │
          │     new ◄──► continue ◄──► apply ◄──► archive │
-         │      │          │           │           │   │
-         │      └──────────┴───────────┴───────────┘   │
-         │              any order                     │
-         └────────────────────────────────────────┘
+         │      │          │           │             │   │
+         │      └──────────┴───────────┴─────────────┘   │
+         │                    any order                  │
+         └───────────────────────────────────────────────┘
 ```
 
 ### Dependency Graph
@@ -542,9 +558,11 @@ project/
 │   └── config.yaml               # NEW: Project configuration
 ├── .claude/
 │   └── skills/                   # NEW: OPSX skills
+│       ├── openspec-propose/     # default core profile
 │       ├── openspec-explore/
-│       ├── openspec-new-change/
-│       └── ...
+│       ├── openspec-apply-change/
+│       ├── openspec-sync-specs/
+│       └── ...                   # expanded profile adds new/continue/ff/etc.
 ├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
 └── AGENTS.md                     # OpenSpec markers removed, your content preserved
 ```
@@ -558,12 +576,15 @@ project/
 
 ### Command Cheatsheet
 
-```
-/opsx:new          Start a change
-/opsx:continue     Create next artifact
-/opsx:ff           Create all planning artifacts
+```text
+/opsx:propose      Start quickly (default core profile)
 /opsx:apply        Implement tasks
 /opsx:archive      Finish and archive
+
+# Expanded workflow (if enabled):
+/opsx:new          Scaffold a change
+/opsx:continue     Create next artifact
+/opsx:ff           Create planning artifacts
 ```
 
 ---

docs/opsx.md

@@ -65,6 +65,8 @@ openspec init
 
 This creates skills in `.claude/skills/` (or equivalent) that AI coding assistants auto-detect.
 
+By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`.
+
 During setup, you'll be prompted to create a **project config** (`openspec/config.yaml`). This is optional but recommended.
 
 ## Project Configuration
@@ -155,13 +157,18 @@ rules:
 
 | Command | What it does |
 |---------|--------------|
+| `/opsx:propose` | Create a change and generate planning artifacts in one step (default quick path) |
 | `/opsx:explore` | Think through ideas, investigate problems, clarify requirements |
-| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact (based on what's ready) |
-| `/opsx:ff` | Fast-forward — create all planning artifacts at once |
+| `/opsx:new` | Start a new change scaffold (expanded workflow) |
+| `/opsx:continue` | Create the next artifact (expanded workflow) |
+| `/opsx:ff` | Fast-forward planning artifacts (expanded workflow) |
 | `/opsx:apply` | Implement tasks, updating artifacts as needed |
-| `/opsx:sync` | Sync delta specs to main (optional—archive prompts if needed) |
+| `/opsx:update` | Revise a change's planning artifacts and keep them coherent |
+| `/opsx:verify` | Validate implementation against artifacts (expanded workflow) |
+| `/opsx:sync` | Sync delta specs to main (default workflow, optional) |
 | `/opsx:archive` | Archive when done |
+| `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) |
+| `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) |
 
 ## Usage
 
@@ -169,13 +176,21 @@ rules:
 ```
 /opsx:explore
 ```
-Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:new` or `/opsx:ff`.
+Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:propose` (default) or `/opsx:new`/`/opsx:ff` (expanded).
 
 ### Start a new change
 ```
-/opsx:new
+/opsx:propose
+```
+Creates the change and generates planning artifacts needed before implementation.
+
+If you've enabled expanded workflows, you can instead use:
+
+```text
+/opsx:new        # scaffold only
+/opsx:continue   # create one artifact at a time
+/opsx:ff         # create all planning artifacts at once
 ```
-You'll be asked what you want to build and which workflow schema to use.
 
 ### Create artifacts
 ```
@@ -194,6 +209,12 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 Works through tasks, checking them off as you go. If you're juggling multiple changes, you can run `/opsx:apply <name>`; otherwise it should infer from the conversation and prompt you to choose if it can't tell.
 
+### Updating a change
+```
+/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).
+
 ### Finish up
 ```
 /opsx:archive   # Move to archive when done (prompts to sync specs if needed)
@@ -299,6 +320,7 @@ Think of it like git branches:
 ## Architecture Deep Dive
 
 This section explains how OPSX works under the hood and how it compares to the legacy workflow.
+Examples in this section use the expanded command set (`new`, `continue`, etc.); default `core` users can map the same flow to `propose → apply → sync → archive`.
 
 ### Philosophy: Phases vs Actions
 
@@ -356,7 +378,7 @@ This section explains how OPSX works under the hood and how it compares to the l
 │   Hardcoded Templates (TypeScript strings)                                  │
 │                    │                                                        │
 │                    ▼                                                        │
-│   Configurators (18+ classes, one per editor)                               │
+│   Tool-specific configurators/adapters                                      │
 │                    │                                                        │
 │                    ▼                                                        │
 │   Generated Command Files (.claude/commands/openspec/*.md)                  │
@@ -604,7 +626,7 @@ artifacts:
 | **State** | Phase-based mental model | Filesystem existence |
 | **Customization** | Edit source, rebuild | Create schema.yaml |
 | **Iteration** | Phase-locked | Fluid, edit anything |
-| **Editor Support** | 18+ configurator classes | Single skills directory |
+| **Editor Support** | Tool-specific configurator/adapters | Single skills directory |
 
 ## Schemas
 

docs/overview.md

@@ -0,0 +1,91 @@
+# Core Concepts at a Glance
+
+**OpenSpec is a lightweight agreement layer between you and your AI.** You write down what a change should do, the AI drafts the details, you both look at the same plan, and only then does code get written. This page is the whole mental model on one screen. When you want the long version, [Concepts](concepts.md) has it.
+
+Here's the entire idea in five words: **agree first, then build confidently.**
+
+## The five ideas
+
+Everything in OpenSpec is built from five concepts. Learn these and the rest is detail.
+
+**1. Specs are the truth.** A spec describes how your system behaves *right now*. It lives in `openspec/specs/`, organized by domain (`auth/`, `payments/`, `ui/`). Specs are made of requirements ("the system SHALL expire sessions after 30 minutes") and scenarios (concrete given/when/then examples). Think of specs as the single agreed-upon answer to "what does this software do?"
+
+**2. A change is one unit of work.** When you want to add, modify, or remove behavior, you create a change: a folder in `openspec/changes/` holding everything about that work in one place. A proposal, a design, a task list, and the spec edits. One change, one folder, one feature.
+
+**3. Delta specs describe what's changing, not the whole world.** Inside a change, you don't rewrite the entire spec. You write a small delta: `ADDED` this requirement, `MODIFIED` that one, `REMOVED` this other one. This is the trick that makes OpenSpec good at editing existing systems, not just green-field ones. You describe the diff, not the destination.
+
+**4. Artifacts build on each other.** A change contains a few documents, created in a natural order, each feeding the next:
+
+```text
+proposal ──► specs ──► design ──► tasks ──► implement
+   why        what       how       steps      do it
+```
+
+You can revisit any of them at any time. They're enablers, not gates. (More on that below.)
+
+**5. Archiving folds the change back into the truth.** When the work is done, you archive the change. Its delta specs merge into your main specs, and the change folder moves to `changes/archive/` with a date stamp. Now your specs describe the new reality, and you're ready for the next change. The cycle closes.
+
+## The picture
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                          openspec/                              │
+│                                                                 │
+│   ┌──────────────────┐         ┌──────────────────────────┐    │
+│   │     specs/       │         │        changes/          │    │
+│   │                  │ ◄─────  │                          │    │
+│   │ source of truth  │  merge  │ one folder per change    │    │
+│   │ how things work  │  on     │ proposal · design ·      │    │
+│   │ today            │ archive │ tasks · delta specs      │    │
+│   └──────────────────┘         └──────────────────────────┘    │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+Two folders. `specs/` is what's true. `changes/` is what you're proposing. Archiving moves a proposal into truth.
+
+## The loop you'll actually run
+
+In the default setup, your day looks like this. Optionally think it through first; then one command drafts the plan, you read it, the next builds it, and the last files it away.
+
+```text
+/opsx:explore                   →  (optional) think it through with the AI first
+/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
+        (you read and adjust the plan)
+/opsx:apply                     →  AI builds it, checking off tasks
+/opsx:archive                   →  specs updated, change archived
+```
+
+**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any artifact exists. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md).
+
+Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion.
+
+## "Enablers, not gates"
+
+This phrase shows up everywhere in OpenSpec, so here's what it means in plain terms.
+
+Old-school spec processes are waterfalls: finish planning, *then* you're allowed to implement, and going back is painful. OpenSpec refuses that. The order `proposal → specs → design → tasks` shows what becomes *possible* next, not what you're *forced* to do next.
+
+Discover during implementation that the design was wrong? Edit `design.md` and keep going. Realize the scope should shrink? Update the proposal. Nothing locks. The dependencies exist only so the AI has the context it needs (you can't write good tasks without specs to base them on), not to box you in.
+
+The strength here is honesty: real work is messy and iterative, and OpenSpec lets it be. The tradeoff is discipline: because nothing forces you forward, it's on you to keep a change focused rather than letting it sprawl. The [Workflows](workflows.md) guide has good habits for that.
+
+## Why this is worth the small overhead
+
+Plain truth: OpenSpec adds a step. You write a short plan before building. So what do you get for it?
+
+- **You catch wrong turns before they cost you.** Fixing a misunderstanding in a one-paragraph proposal is free. Fixing it after the AI wrote 400 lines is not.
+- **The plan and the code stay in the same repo.** Six months later, the spec tells you (and the next AI session) why the system works the way it does.
+- **Changes are reviewable.** A change folder is a tidy package: read the proposal, skim the deltas, check the tasks. No archaeology through chat history.
+- **It fits existing codebases.** Deltas mean you can specify a change to a 50,000-line app without first documenting the whole thing.
+
+And the honest tradeoff: for a truly trivial one-line fix, the ceremony may not pay off, and that's fine. OpenSpec is designed to be lightweight, but it isn't free. Use it where agreement matters, which turns out to be most of the time once you're working with an AI that will confidently build whatever you vaguely asked for.
+
+## Where to go next
+
+- New here? [Getting Started](getting-started.md) walks the first change in full.
+- Not sure what to build yet? [Explore First](explore.md) is the place to start.
+- Confused about where commands run? [How Commands Work](how-commands-work.md).
+- Want the deep version of everything above? [Concepts](concepts.md).
+- Learn by example? [Examples & Recipes](examples.md).
+- Need a term defined? [Glossary](glossary.md).

docs/reviewing-changes.md

@@ -0,0 +1,143 @@
+# Reviewing a Change
+
+OpenSpec's whole promise is that you and your AI **agree on what to build before any code is written.** That agreement only means something if you actually read what the AI drafted. This page is about the two minutes where you do that — what to open, in what order, and what to look for.
+
+The bet is simple: catching a wrong turn in a one-paragraph plan is nearly free. Catching the same wrong turn in 300 lines of code is not. Review is where you collect on that bet.
+
+## The two moments you review
+
+There are exactly two:
+
+```
+/opsx:propose ──► REVIEW THE PLAN ──► /opsx:apply ──► REVIEW THE CODE ──► /opsx:archive
+                  (before any code)                    (/opsx:verify)
+```
+
+1. **After `/opsx:propose`** (or `/opsx:ff`), before `/opsx:apply` — read the plan while it's still just words.
+2. **After building**, with `/opsx:verify` — check that the code actually did what the plan said.
+
+The first review is the one that saves you the most, and the one people skip. This page spends most of its time there.
+
+## Read it in this order
+
+A change is a folder of plain Markdown in `openspec/changes/<name>/`. Read the files in the order that lets you quit earliest if something's wrong:
+
+```
+openspec/changes/add-dark-mode/
+├── proposal.md      1. the intent and scope   ← if this is wrong, stop here
+├── specs/…/spec.md  2. the requirements       ← the heart of the review
+├── design.md        (only for bigger changes) — the technical approach
+└── tasks.md         3. the plan of work
+```
+
+You don't need to read every line. You need to answer three questions, one per file.
+
+## The proposal: is this the right problem?
+
+Open `proposal.md` first. It captures the "why" and "what" — the intent, the scope, the approach in a paragraph or two.
+
+**What good looks like:** one clear intent, a scope you recognize, and a reason this is worth doing now.
+
+**Red flags:**
+
+- It solves a slightly *different* problem than the one you asked for.
+- The scope has grown — you asked for a theme toggle and the proposal also touches auth "while we're in there."
+- It's vague. "Improve the settings page" is not a scope; "add a dark-mode toggle that respects the OS preference" is.
+
+**The question to answer:** *Does this match what I actually asked for, and is anything sneaking in?* If the answer is no, stop — don't read further, fix the proposal (see [Pushing back](#pushing-back-is-cheap)).
+
+## The spec deltas: is "done" defined correctly?
+
+This is the heart of the review. The delta specs under `specs/` say what will be *true* when the change ships — as requirements and the scenarios that prove them:
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Dark Mode Toggle
+The system SHALL let a user switch between light and dark themes.
+
+#### Scenario: Respects the OS preference on first load
+- GIVEN a user who has never set a theme
+- WHEN they open the app on a device set to dark mode
+- THEN the app renders in dark mode
+```
+
+**What a good requirement looks like:** one clear `SHALL`/`MUST` statement you could hand to a tester, and at least one scenario whose GIVEN/WHEN/THEN actually exercises that statement.
+
+**Red flags:**
+
+- **A vague requirement.** "The system SHALL be fast" can't be built or tested. What's fast?
+- **A requirement with no scenario**, or a scenario that doesn't test the requirement it sits under.
+- **The most valuable catch of all: what's missing.** The AI faithfully writes down what you *said*. Your job is to notice what you *forgot* to say. If you cared most about the OS-preference case and no scenario mentions it, that's the review paying for itself.
+
+Read the deltas asking *would I be happy if the system did exactly — and only — this?* Nothing here is about code yet, so it stays cheap to change.
+
+## The tasks: is the plan of work sane?
+
+Open `tasks.md` last. It's the implementation checklist the AI will work through.
+
+**What good looks like:** ordered steps, each traceable to a requirement, nothing mysterious.
+
+**Red flags:**
+
+- A task with no matching requirement (where did that come from?).
+- One giant "implement the feature" task that hides all the real decisions.
+- A task that touches something outside the scope you just approved.
+
+You're not estimating or micromanaging here — you're checking that the plan matches the requirements you already accepted.
+
+## Pushing back is cheap
+
+If any of the three questions came back wrong, say so. There are no phases and nothing is locked — you fix it and move on. Two ways, exactly as in [Editing a change](editing-changes.md):
+
+- **Edit the file yourself.** It's plain Markdown; change the scope line, tighten a requirement, delete a task.
+- **Tell the AI what's wrong** and let it revise: *"drop the auth changes — out of scope,"* *"add a scenario for when the user has already picked a theme,"* *"split task 3 into schema and UI."*
+
+Then re-read the part you changed. Re-draft until it's a plan you'd sign your name to. That back-and-forth *is* the product working.
+
+## After the code: verify
+
+Once the work is built, `/opsx:verify` is your second review. It re-reads the artifacts and the code and reports mismatches across three dimensions:
+
+| Dimension | What it checks |
+|-----------|----------------|
+| **Completeness** | Every task done, every requirement implemented, scenarios covered |
+| **Correctness** | The implementation matches the spec's intent, edge cases handled |
+| **Coherence** | Design decisions actually show up in the code |
+
+```
+You: /opsx:verify
+
+AI:  Verifying add-dark-mode...
+
+     COMPLETENESS
+     ✓ All 8 tasks in tasks.md are checked
+     ✓ All requirements in specs have corresponding code
+     ⚠ Scenario "Respects the OS preference on first load" has no test coverage
+```
+
+It flags issues as CRITICAL, WARNING, or SUGGESTION, and it does **not** block archiving — it surfaces the gaps and leaves the call to you. This is the difference between "did the AI write code" and "did it build what we agreed."
+
+`/opsx:verify` is in the expanded profile. If you don't have it, turn it on with `openspec config profile` (then `openspec update`), or just re-read the change and the diff yourself.
+
+## Right-size the review
+
+Not every change earns the full pass. A one-file typo fix deserves a twenty-second skim. A change that touches auth, payments, or data you can't recover deserves every question above. The point was never ceremony — it's spending your attention where a mistake would be expensive, and skimming where it wouldn't.
+
+## The two-minute checklist
+
+- [ ] The proposal's intent matches what I asked for.
+- [ ] Nothing extra has crept into the scope.
+- [ ] Every requirement is specific enough to test.
+- [ ] Every requirement has a scenario that actually exercises it.
+- [ ] The case I care about most is covered.
+- [ ] Tasks map to requirements; nothing is mysterious or out of scope.
+- [ ] I'd be comfortable if the AI built exactly this and nothing more.
+
+If all seven pass, run `/opsx:apply` with confidence. If any fail, that's not a setback — it's the two minutes doing its job.
+
+## Where to go next
+
+- [Writing Good Specs](writing-specs.md) — the flip side: how to draft requirements and scenarios worth approving.
+- [Editing & Iterating on a Change](editing-changes.md) — the mechanics of changing a plan after you've started.
+- [Workflows](workflows.md) — where review fits in the larger loop.

docs/stores-beta/user-guide.md

@@ -0,0 +1,349 @@
+# Stores: Plan in Its Own Repo
+
+> **Beta.** Stores, references, working context, and worksets are
+> new. Command names, flags, file formats, and JSON output may still change
+> shape between releases. Every walkthrough below was run against the
+> current build, but re-read this guide after upgrading.
+
+## The problem this solves
+
+OpenSpec normally lives inside one code repo: an `openspec/` folder next to
+your code, holding specs and changes for that repo.
+
+That stops fitting the moment your planning is bigger than one repo:
+
+- Your work spans several repos — one feature touches the API server, the
+  web app, and a shared library. Whose `openspec/` folder does the plan
+  live in?
+- Your team plans before code exists, or plans things that never become
+  code in *this* repo.
+- Requirements are owned by one team and consumed by others. The wiki
+  version drifts, and your coding agent can't read it anyway.
+
+A **store** is the answer: a standalone repo whose whole job is planning.
+It has the same `openspec/` shape you already know — specs and changes —
+plus a small identity file. You register it on your machine once, by name,
+and then every normal OpenSpec command can work in it from anywhere.
+
+## The shape
+
+```
+            team-plans  (a store: planning in its own repo)
+            ├── .openspec-store/store.yaml     identity: "I am team-plans"
+            └── openspec/
+                ├── specs/      what is true
+                └── changes/    what is in motion
+                      ▲
+                      │ registered on each machine by name;
+                      │ shared by pushing/cloning like any repo
+        ┌─────────────┼─────────────┐
+        │             │             │
+    web-app       api-server     mobile-app
+   (code repo)   (code repo)    (code repo)
+```
+
+Two rules keep this simple:
+
+1. **A store is just a git repo.** You commit, push, pull, and review it
+   yourself. OpenSpec never clones, syncs, or pushes anything on its own.
+2. **Declarations, not machinery.** Repos can *declare* how they relate to
+   stores (shown below). Declarations change what OpenSpec can tell you —
+   never where your commands act.
+
+## Five minutes to your first store
+
+Two commands take you from nothing to a working, store-scoped change:
+
+```bash
+openspec store setup team-plans --path ~/openspec/team-plans
+```
+
+```
+Store ready: team-plans
+Location: /Users/you/openspec/team-plans
+OpenSpec root: ready
+Registry: registered
+
+Next: run normal OpenSpec commands against this store, for example:
+  openspec new change <change-id> --store team-plans
+Share this store by committing and pushing it like any Git repo.
+```
+
+```bash
+openspec new change add-login --store team-plans
+```
+
+```
+Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
+Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
+Schema: spec-driven
+Next: openspec status --change add-login --store team-plans
+```
+
+That's the whole model. From here the lifecycle is exactly what you know —
+`status`, `instructions`, `validate`, `archive` — with `--store team-plans`
+on each command, and every printed hint carries the flag for you. The
+`Using OpenSpec root:` line always tells you where a command is acting.
+
+## Story: one team, one planning repo
+
+A team keeps its specs and changes in `team-plans` instead of scattering
+them across code repos.
+
+**Day one (whoever sets it up):**
+
+```bash
+openspec store setup team-plans --path ~/openspec/team-plans \
+  --remote git@github.com:acme/team-plans.git
+git -C ~/openspec/team-plans push -u origin main
+```
+
+Passing `--remote` records the clone URL inside the store's own identity
+file (`.openspec-store/store.yaml`), in the initial commit. Every future
+clone is born knowing where it came from, so health checks and error
+messages can print a complete, pasteable fix for teammates who don't have
+it yet.
+
+**Every teammate (once per machine):**
+
+```bash
+git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
+openspec store register ~/openspec/team-plans
+```
+
+From then on, everyone works in the same planning repo by name:
+
+```bash
+openspec status --store team-plans --change add-login
+openspec show add-login --store team-plans
+```
+
+**Sharing work is git, on purpose.** A change you create exists only in
+your checkout until you commit and push it — same as code. Plans get
+branches, pull requests, and review for free, because a store is an
+ordinary repo.
+
+**Connecting the team's code repos.** A code repo whose planning is fully
+externalized needs exactly one line, in `openspec/config.yaml`:
+
+```yaml
+# web-app/openspec/config.yaml
+store: team-plans
+```
+
+Now every OpenSpec command run inside `web-app` acts on `team-plans` with
+no flags at all:
+
+```bash
+cd ~/src/web-app
+openspec status --change add-login
+```
+
+```
+Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
+...
+```
+
+The pointer is a fallback, never an override: an explicit `--store` always
+wins, and if the repo grows real planning folders of its own, those win
+(with a warning to remove the stale pointer).
+
+## Story: requirements that cross team lines
+
+A platform team owns the requirements. Product teams build against them,
+in their own repos, with their own designs. A reference describes that
+relationship without moving anyone's work.
+
+```
+   platform-reqs (store)                 api-server (code repo)
+   owned by the platform team            owned by a product team
+   ┌──────────────────────────┐          ┌──────────────────────────┐
+   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
+   │   payments/spec.md       │ reads    │   references:            │
+   │   auth/spec.md           │          │     - platform-reqs      │
+   │                          │          │ openspec/specs/          │
+   │ openspec/changes/        │          │   (their own designs)    │
+   │   platform work          │          │ openspec/changes/        │
+   │                          │          │   (their own work)       │
+   │                          │          └──────────────────────────┘
+   └──────────────────────────┘
+```
+
+**The product team declares what it draws on** in its repo's
+`openspec/config.yaml`:
+
+```yaml
+references:
+  - platform-reqs
+```
+
+References are read-only context. The repo keeps its own `openspec/` root;
+work stays there. What changes: `openspec instructions` in that repo now
+includes an index of the referenced store's specs — each with a one-line
+summary and the exact fetch command (`openspec show <spec-id> --type spec
+--store platform-reqs`). An agent working in `api-server` can find the
+upstream payment requirements, cite them, and write its low-level design in
+the repo's own root — without anyone pasting context around.
+
+A reference can carry its clone source, so teammates who don't have the
+store yet get a complete fix instead of a dead end:
+
+```yaml
+references:
+  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }
+```
+
+**When you want the plan and code open together, make a workset.** This is
+personal and explicit: each person chooses the folders they actually work
+with on their machine. Nothing about those local checkout paths is
+committed to the shared planning repo.
+
+```bash
+openspec workset create platform \
+  --member ~/openspec/platform-reqs \
+  --member ~/src/api-server \
+  --member ~/src/web-app
+```
+
+## Two questions you can always ask
+
+**"Is my setup healthy?"** — `openspec doctor` checks the current root and
+its referenced stores, read-only, with a pasteable fix per finding:
+
+```
+Doctor
+
+Root
+  Location: /Users/you/src/api-server
+  OpenSpec root: ok
+
+References
+  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
+  - design-system: Referenced store 'design-system' is not registered on this machine.
+    Fix: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' && openspec store register '/Users/you/openspec/design-system' --id design-system
+
+```
+
+**"What am I working with?"** — `openspec context` assembles the working
+set from OpenSpec declarations: the root and the stores it references.
+
+```
+Working context for api-server (/Users/you/src/api-server)
+
+OpenSpec root
+  api-server  /Users/you/src/api-server
+
+Referenced stores
+  platform-reqs  /Users/you/openspec/platform-reqs
+    Fetch: openspec show <spec-id> --type spec --store platform-reqs
+```
+
+Both support `--json` for agents. `openspec context --code-workspace
+<path>` additionally writes a VS Code workspace file containing the whole
+set — the only write this command performs.
+
+## Worksets: reopen the folders you work on together
+
+Separate from all of the above: most people open the same few folders
+together every session — the planning repo plus two or three code repos.
+A **workset** is a personal, named view of exactly that, reopened with one
+command in your tool of choice.
+
+```
+  workset "platform"                 openspec workset open platform
+  ├── team-plans   ~/openspec/team-plans         │
+  ├── api-server   ~/src/api-server              ▼
+  └── web-app      ~/src/web-app       all three open in your tool
+```
+
+```bash
+openspec workset create platform \
+  --member ~/openspec/team-plans --member ~/src/api-server \
+  --tool code
+openspec workset list
+```
+
+```
+platform  (opens in VS Code)
+  team-plans  /Users/you/openspec/team-plans
+  api-server  /Users/you/src/api-server
+```
+
+`openspec workset open platform` then launches the saved tool: editors
+(VS Code, Cursor) open one window with every member and return. The first
+member is the primary. Override the tool any time with `--tool <id>`.
+
+Worksets are deliberately *not* shared state. They live on your machine,
+are never committed, and make no claims about the work — they only record
+what you like open together. Removing one never touches the member
+folders. New tools are configuration, not code: anything launched via a
+workspace file or per-folder attach flags can be added under the `openers`
+key in the global config (`openspec config edit`).
+
+## How commands decide where to act
+
+Every normal command resolves its root the same way, in this order:
+
+```
+1. --store <id>          you said so explicitly        → that store
+2. nearest openspec/     a real planning root here     → this repo
+   (walking up from cwd)
+3. store: pointer        config.yaml declares a store  → that store
+4. none of the above     stores registered on this     → error with a
+                         machine?                        selection hint
+                         no stores registered?         → the current
+                                                          directory
+                                                          (classic behavior)
+```
+
+The `Using OpenSpec root:` line (and the `root` block in `--json` output)
+tells you which case you're in.
+
+## Known limitations
+
+- **Beta shape.** Everything on this page may change between releases —
+  names, flags, file formats, JSON keys.
+- **One checkout per store id per machine.** Registering a second checkout
+  under the same id fails with a hint to `store unregister` first.
+- **No sync, ever — by design.** OpenSpec never clones, pulls, or pushes.
+  A stale checkout shows stale specs until *you* pull; references are
+  indexed live from whatever is on disk.
+- **Empty planning folders can be absent.** A new store may not have
+  `openspec/changes/`, `openspec/specs/`, or `openspec/changes/archive/` in Git
+  yet. That is accepted during the beta; those folders appear once normal
+  commands create files for them.
+- **Pointer repos stay pointers.** A config-only repo whose
+  `openspec/config.yaml` declares `store: <id>` is treated as externalized
+  planning, not as a store checkout to register. Remove the `store:` line first
+  if you intentionally want to convert that repo into a local store root.
+- **Some commands stay where they are.** `view`, `templates`, `schemas`,
+  and the deprecated noun forms (`openspec change show`, ...) act on the
+  current directory only — no `--store`.
+- **Per-machine state is per-machine.** The store registry and worksets
+  are local settings. Nothing about your machine's layout is
+  ever committed to shared planning.
+- **Two launch styles for worksets.** A tool that can't be launched with a
+  workspace file or per-folder attach flags can't be added as an opener.
+- **Agent JSON has a known casing split** (store-family keys are
+  snake_case, workflow-family camelCase). Documented in the
+  [agent contract](../agent-contract.md); unifying it is deferred to a
+  versioned release.
+
+## Where things live
+
+| What | Where | Shared? |
+|---|---|---|
+| A store's planning | `<store>/openspec/` (specs, changes) | Yes — commit and push it |
+| A store's identity | `<store>/.openspec-store/store.yaml` | Yes — committed with the store |
+| The store registry | `<data dir>/openspec/stores/registry.yaml` | No — this machine only |
+| Worksets | `<data dir>/openspec/worksets/` | No — this machine only |
+
+`<data dir>` is `~/.local/share/openspec` on macOS and Linux (or
+`$XDG_DATA_HOME/openspec` when set), and `%LOCALAPPDATA%\openspec` on
+Windows.
+
+## Reference
+
+Exact flags and JSON shapes for every command on this page:
+[CLI reference](../cli.md) (Stores, Doctor, Working context, Personal
+worksets) and the [agent contract](../agent-contract.md).

docs/supported-tools.md

@@ -1,44 +1,66 @@
 # Supported Tools
 
-OpenSpec works with 20+ AI coding assistants. When you run `openspec init`, you'll be prompted to select which tools you use, and OpenSpec will configure the appropriate integrations.
+OpenSpec works with many AI coding assistants. When you run `openspec init`, OpenSpec configures selected tools using your active profile/workflow selection and delivery mode.
 
 ## How It Works
 
-For each tool you select, OpenSpec installs:
+For each selected tool, OpenSpec can install:
 
-1. **Skills** — Reusable instruction files that power the `/opsx:*` workflow commands
-2. **Commands** — Tool-specific slash command bindings
+1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md`
+2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files
+
+By default, OpenSpec uses the `core` profile, which includes:
+- `propose`
+- `explore`
+- `apply`
+- `sync`
+- `archive`
+
+You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`) via `openspec config profile`, then run `openspec update`.
 
 ## Tool Directory Reference
 
-| Tool | Skills Location | Commands Location |
-|------|-----------------|-------------------|
-| Amazon Q Developer | `.amazonq/skills/` | `.amazonq/prompts/` |
-| Antigravity | `.agent/skills/` | `.agent/workflows/` |
-| Auggie (Augment CLI) | `.augment/skills/` | `.augment/commands/` |
-| Claude Code | `.claude/skills/` | `.claude/commands/opsx/` |
-| Cline | `.cline/skills/` | `.clinerules/workflows/` |
-| CodeBuddy | `.codebuddy/skills/` | `.codebuddy/commands/opsx/` |
-| Codex | `.codex/skills/` | `.codex/prompts/` |
-| Continue | `.continue/skills/` | `.continue/prompts/` |
-| CoStrict | `.cospec/skills/` | `.cospec/openspec/commands/` |
-| Crush | `.crush/skills/` | `.crush/commands/opsx/` |
-| Cursor | `.cursor/skills/` | `.cursor/commands/` |
-| Factory Droid | `.factory/skills/` | `.factory/commands/` |
-| Gemini CLI | `.gemini/skills/` | `.gemini/commands/opsx/` |
-| GitHub Copilot | `.github/skills/` | `.github/prompts/` |
-| iFlow | `.iflow/skills/` | `.iflow/commands/` |
-| Kilo Code | `.kilocode/skills/` | `.kilocode/workflows/` |
-| OpenCode | `.opencode/skills/` | `.opencode/command/` |
-| Qoder | `.qoder/skills/` | `.qoder/commands/opsx/` |
-| Qwen Code | `.qwen/skills/` | `.qwen/commands/` |
-| RooCode | `.roo/skills/` | `.roo/commands/` |
-| Trae | `.trae/skills/` | `.trae/skills/` (via `/openspec-*`) |
-| Windsurf | `.windsurf/skills/` | `.windsurf/commands/opsx/` |
+| Tool (ID) | Skills path pattern | Command path pattern |
+|-----------|---------------------|----------------------|
+| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-<id>.md` |
+| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-<id>.md` |
+| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-<id>.md` |
+| IBM Bob Shell (`bob`) | `.bob/skills/openspec-*/SKILL.md` | `.bob/commands/opsx-<id>.md` |
+| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
+| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
+| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
+| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
+| ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+| Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
+| CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-<id>.md` |
+| Crush (`crush`) | `.crush/skills/openspec-*/SKILL.md` | `.crush/commands/opsx/<id>.md` |
+| Cursor (`cursor`) | `.cursor/skills/openspec-*/SKILL.md` | `.cursor/commands/opsx-<id>.md` |
+| Factory Droid (`factory`) | `.factory/skills/openspec-*/SKILL.md` | `.factory/commands/opsx-<id>.md` |
+| Gemini CLI (`gemini`) | `.gemini/skills/openspec-*/SKILL.md` | `.gemini/commands/opsx/<id>.toml` |
+| GitHub Copilot (`github-copilot`) | `.github/skills/openspec-*/SKILL.md` | `.github/prompts/opsx-<id>.prompt.md`\*\* |
+| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-<id>.md` |
+| Junie (`junie`) | `.junie/skills/openspec-*/SKILL.md` | `.junie/commands/opsx-<id>.md` |
+| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-<id>.md` |
+| Kimi CLI (`kimi`) | `.kimi/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
+| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
+| Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
+| Mistral Vibe (`vibe`) | `.vibe/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+| Oh My Pi (`oh-my-pi`) | `.omp/skills/openspec-*/SKILL.md` | `.omp/commands/opsx-<id>.md` |
+| OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/commands/opsx-<id>.md` |
+| Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-<id>.md` |
+| Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/<id>.md` |
+| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-<id>.toml` |
+| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
+| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | `.trae/commands/opsx-<id>.md` |
+| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-<id>.md` |
+
+\* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory.
+
+\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.
 
 ## Non-Interactive Setup
 
-For CI/CD or scripted setup, use the `--tools` flag:
+For CI/CD or scripted setup, use `--tools` (and optionally `--profile`):
 
 ```bash
 # Configure specific tools
@@ -49,34 +71,41 @@ openspec init --tools all
 
 # Skip tool configuration
 openspec init --tools none
+
+# Override profile for this init run
+openspec init --profile core
 ```
 
-**Available tool IDs:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codebuddy`, `codex`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf`
+**Available tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `windsurf`
 
-## What Gets Installed
+## Workflow-Dependent Installation
 
-For each tool, OpenSpec generates 10 skill files that power the OPSX workflow:
+OpenSpec installs workflow artifacts based on selected workflows:
 
-| Skill | Purpose |
-|-------|---------|
-| `openspec-explore` | Thinking partner for exploring ideas |
-| `openspec-new-change` | Start a new change |
-| `openspec-continue-change` | Create the next artifact |
-| `openspec-ff-change` | Fast-forward through all planning artifacts |
-| `openspec-apply-change` | Implement tasks |
-| `openspec-verify-change` | Verify implementation completeness |
-| `openspec-sync-specs` | Sync delta specs to main (optional—archive prompts if needed) |
-| `openspec-archive-change` | Archive a completed change |
-| `openspec-bulk-archive-change` | Archive multiple changes at once |
-| `openspec-onboard` | Guided onboarding through a complete workflow cycle |
+- **Core profile (default):** `propose`, `explore`, `apply`, `sync`, `archive`
+- **Custom selection:** any subset of all workflow IDs:
+  `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`
 
-These skills are invoked via slash commands like `/opsx:new`, `/opsx:apply`, etc. See [Commands](commands.md) for the full list.
+In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed.
 
-## Adding a New Tool
+## Generated Skill Names
 
-Want to add support for another AI coding assistant? Check out the [command adapter pattern](../CONTRIBUTING.md) or open an issue on GitHub.
+When selected by profile/workflow config, OpenSpec generates these skills:
 
----
+- `openspec-propose`
+- `openspec-explore`
+- `openspec-new-change`
+- `openspec-continue-change`
+- `openspec-apply-change`
+- `openspec-update-change`
+- `openspec-ff-change`
+- `openspec-sync-specs`
+- `openspec-archive-change`
+- `openspec-bulk-archive-change`
+- `openspec-verify-change`
+- `openspec-onboard`
+
+See [Commands](commands.md) for command behavior and [CLI](cli.md) for `init`/`update` options.
 
 ## Related
 

docs/team-workflow.md

@@ -0,0 +1,74 @@
+# OpenSpec on a Team
+
+Everything in the other guides works the same whether you're solo or on a team of twenty. What changes on a team is the questions around the edges: where do the specs live, how do teammates review a plan, and how does any of this fit the pull-request flow we already have?
+
+The short answer: a change is just files, and OpenSpec never touches git. So it fits your existing workflow instead of replacing it. This page spells out the conventions that work well.
+
+## One rule: OpenSpec doesn't touch git
+
+OpenSpec reads and writes plain Markdown under `openspec/`. It never commits, branches, pushes, or pulls in your project — and it never clones or syncs a [store](stores-beta/user-guide.md) on its own. That means:
+
+- **You commit `openspec/` like any source.** Specs, active changes, and the archive are part of your project's history. (Yes, commit the whole folder — see the [FAQ](faq.md#should-i-commit-the-openspec-folder-to-git).)
+- **A change is a folder you version like code.** `openspec/changes/add-dark-mode/` is just files on a branch.
+- **Everything below is convention, not enforcement.** OpenSpec won't make you do it this way; it just fits cleanly.
+
+## The everyday loop
+
+The workflow that works well maps a change onto a branch and a pull request:
+
+```
+git switch -c add-dark-mode        start a branch, as usual
+   │
+/opsx:propose add-dark-mode        draft the plan (proposal + specs + tasks)
+   │
+REVIEW THE PLAN                    you read it before any code — see Reviewing a Change
+   │
+/opsx:apply                        build it; artifacts + code change together
+   │
+git commit && open a PR            the PR contains the spec delta AND the code
+   │
+teammate reviews, merges
+   │
+/opsx:archive                      fold the delta into specs/, move the change to archive/
+```
+
+The plan and the code live side by side in the same branch, so your teammates review both together, and six months later the archived spec still explains why the code looks the way it does.
+
+## Reviewing specs in a pull request
+
+This is where a team feels the payoff. When a PR includes the change's delta spec, the reviewer gets something a raw diff never gives them: **a plain-language statement of what this change is supposed to do**, before they read a single line of code.
+
+A good review order for the reviewer:
+
+1. **Read `proposal.md`** — is this the right problem and scope?
+2. **Read the delta under `specs/`** — is "done" defined correctly? (This is the [Reviewing a Change](reviewing-changes.md) two-minute pass, now happening in the PR.)
+3. **Then read the code diff** — does it deliver exactly those requirements?
+
+A reviewer who disagrees with the *approach* can say so against the proposal, cheaply, instead of relitigating it across 300 lines of code. Put the delta spec near the top of the PR description, or point reviewers at the change folder, so they start there.
+
+## When to archive
+
+Archiving folds a change's deltas into your main `openspec/specs/` and moves the change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`. Because `specs/` is the **shared source of truth**, the timing matters on a team. Two workable conventions:
+
+- **Archive after the PR merges (recommended).** The branch carries the active change; once it's merged to your main branch, archive there (often a tiny follow-up commit or a scheduled cleanup). This keeps the shared `specs/` moving forward only with work that actually shipped.
+- **Archive inside the PR.** Simpler for small teams: the same PR that adds the code also syncs and archives. The tradeoff is that your `specs/` diff and your code diff land together, which can make the PR noisier.
+
+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.
+
+## Two people, parallel changes
+
+Because changes are separate folders, they don't collide:
+
+- **Different changes, different people — no problem.** `add-dark-mode` and `rate-limit-login` are different folders on different branches; they never touch each other until they both archive.
+- **One change, one owner.** Two people editing the same change folder conflict exactly like two people editing the same file. Keep a change to a single author, or split it into two changes (another reason to [right-size](writing-specs.md#right-size-the-change)).
+- **The one place conflicts show up is `specs/`.** If two changes both modify the *same* requirement, archiving the second one will conflict in `openspec/specs/…/spec.md` — resolve it like any merge conflict, keeping the requirement that reflects reality. This is rare, and it's a feature: it's git telling you two changes disagreed about how the system should behave.
+
+## When planning outgrows one repo
+
+Everything above assumes the plan lives in the code repo's own `openspec/` folder, which is the right default. When your planning genuinely spans several repos or teams — one feature touching three services, or requirements one team owns and others consume — that's what the beta **stores** feature is for: planning gets its own repo that any code repo can point at. Start with the [Stores User Guide](stores-beta/user-guide.md).
+
+## Where to go next
+
+- [Reviewing a Change](reviewing-changes.md) — the review pass, now inside your PR.
+- [Writing Good Specs](writing-specs.md) — including how to right-size a change so it fits one branch.
+- [Stores User Guide](stores-beta/user-guide.md) — planning that spans repos and teams.

docs/troubleshooting.md

@@ -0,0 +1,166 @@
+# Troubleshooting
+
+Concrete fixes for concrete problems. Each entry names a symptom, explains the likely cause in a sentence, and gives you the fix. If you don't see your issue here, the [FAQ](faq.md) may help, and the [Discord](https://discord.gg/YctCnvvshC) definitely will.
+
+## Installation and setup
+
+### `openspec: command not found`
+
+The CLI isn't installed, or your shell can't find it. Install it globally and check:
+
+```bash
+npm install -g @fission-ai/openspec@latest
+openspec --version
+```
+
+If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm bin -g` to see where global binaries live, and make sure that path is in your shell profile.
+
+### "Requires Node.js 20.19.0 or higher"
+
+OpenSpec runs on Node 20.19.0+. Check your version and upgrade if needed:
+
+```bash
+node --version
+```
+
+If you use bun to install OpenSpec, note that OpenSpec still *runs* on Node, so you need Node 20.19.0+ available on your `PATH` regardless. See [Installation](installation.md).
+
+### `openspec init` didn't configure my AI tool
+
+Init asks which tools to set up. If you skipped your tool or want to add another, just run it again, or use the non-interactive form:
+
+```bash
+openspec init --tools claude,cursor
+```
+
+The full list of tool IDs is in [Supported Tools](supported-tools.md). Use `--tools all` for everything, `--tools none` to skip tool setup.
+
+## Commands don't show up
+
+If `/opsx:propose` (or your tool's equivalent) doesn't appear or doesn't do anything, work down this list. They're ordered fastest-to-check first.
+
+1. **You may be in the wrong place.** Slash commands go in your AI assistant's chat, not your terminal. If you typed `/opsx:propose` into your shell, that's the issue. See [How Commands Work](how-commands-work.md).
+
+2. **Regenerate the files.** From your project root:
+
+   ```bash
+   openspec update
+   ```
+
+   This rewrites the skill and command files for every tool you've configured.
+
+3. **Restart your assistant.** Most tools scan for skills and commands at startup. A fresh window often does it.
+
+4. **Confirm the files exist.** For Claude Code, check that `.claude/skills/` contains `openspec-*` folders. Other tools use their own directories, all listed in [Supported Tools](supported-tools.md).
+
+5. **Check you initialized this project.** Skills are written per project. If you cloned a repo or switched folders, run `openspec init` (or `openspec update`) there.
+
+6. **Confirm your tool supports command files.** A few tools (Kimi CLI, ForgeCode, Mistral Vibe) don't get generated `opsx-*` command files; they use skill-based invocations instead. The forms differ per tool: see [Supported Tools](supported-tools.md) and [How Commands Work](how-commands-work.md#slash-command-syntax-by-tool).
+
+## Working with changes
+
+### "Change not found"
+
+The command couldn't tell which change you meant. Name it explicitly, or check what exists:
+
+```bash
+openspec list                    # see active changes
+/opsx:apply add-dark-mode        # name the change in chat
+```
+
+Also confirm you're in the right project directory.
+
+### "No artifacts ready"
+
+Every artifact is either already created or blocked waiting on a dependency. See what's blocking:
+
+```bash
+openspec status --change <name>
+```
+
+Then create the missing dependency first. Remember the order: proposal enables specs and design; specs and design together enable tasks.
+
+### `openspec validate` reports warnings or errors
+
+Validation checks your specs and changes for structural problems. Read the message: it names the file and the issue.
+
+```bash
+openspec validate <name>           # validate one item
+openspec validate --all            # validate everything
+openspec validate --all --strict   # stricter checks, good for CI
+```
+
+Common causes are a missing required section (like a spec with no scenarios) or a malformed delta header. Fix the file and re-run. The [CLI reference](cli.md#openspec-validate) documents the output format.
+
+### The AI created incomplete or wrong artifacts
+
+The AI didn't have enough context. A few levers help:
+
+- Add project context in `openspec/config.yaml` so your stack and conventions are injected into every request. See [Customization](customization.md#project-configuration).
+- Add per-artifact `rules:` for guidance that only applies to, say, specs.
+- Give a more detailed description when you propose.
+- Use the expanded `/opsx:continue` to create one artifact at a time and review each, instead of `/opsx:ff` doing them all at once.
+
+### Archive won't finish, or warns about incomplete tasks
+
+Archive won't *block* on incomplete tasks, but it warns you, because archiving usually means the work is done. If tasks remain on purpose (you're filing a partial change), proceed. Otherwise finish the tasks first. Archive will also offer to sync your delta specs into the main specs if you haven't synced yet; say yes unless you have a reason not to.
+
+## Configuration
+
+### My `config.yaml` isn't being applied
+
+Three usual suspects:
+
+1. **Wrong filename.** It must be `openspec/config.yaml`, not `.yml`.
+2. **Invalid YAML.** Run it through any YAML validator; the CLI also reports syntax errors with line numbers.
+3. **You expected a restart.** You don't need one. Config changes take effect immediately.
+
+### "Unknown artifact ID in rules: X"
+
+A key under `rules:` doesn't match any artifact in your schema. For the default `spec-driven` schema the valid IDs are `proposal`, `specs`, `design`, `tasks`. To see the IDs for any schema:
+
+```bash
+openspec schemas --json
+```
+
+### "Context too large"
+
+The `context:` field is capped at 50KB, on purpose, because it's injected into every request. Summarize it, or link out to longer docs instead of pasting them. Lean context also produces better, faster results.
+
+### "Schema not found"
+
+The schema name you referenced doesn't exist. List what's available and check spelling:
+
+```bash
+openspec schemas                    # list available schemas
+openspec schema which <name>        # see where a schema resolves from
+openspec schema init <name>         # create a custom one
+```
+
+See [Customization](customization.md#custom-schemas).
+
+## Migration from the legacy workflow
+
+### "Legacy files detected in non-interactive mode"
+
+You're in CI or a non-interactive shell, and OpenSpec found old files to clean up but can't prompt you. Approve automatically:
+
+```bash
+openspec init --force
+```
+
+### Commands didn't appear after migrating
+
+Restart your IDE. Skills are detected at startup. If they still don't appear, run `openspec update` and check the file locations in [Supported Tools](supported-tools.md).
+
+### My old `project.md` wasn't migrated
+
+That's intentional. OpenSpec never deletes `project.md` automatically because it may hold context you wrote. Move the useful parts into `config.yaml`'s `context:` section, then delete it yourself. The [Migration Guide](migration-guide.md#migrating-projectmd-to-configyaml) walks through this, including a prompt you can hand to your AI to do the distilling.
+
+## Still stuck?
+
+- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
+- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
+- **From your terminal:** `openspec feedback "what went wrong"` opens an issue for you.
+
+When you report a problem, include your OpenSpec version (`openspec --version`), your Node version (`node --version`), your AI tool, and the exact command and output. It makes help much faster.

docs/workflows.md

@@ -28,7 +28,60 @@ OPSX (fluid actions):
 
 > **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
 
-## Workflow Patterns
+## Two Modes
+
+### Default Quick Path (`core` profile)
+
+New installs default to `core`, which provides:
+- `/opsx:explore`
+- `/opsx:propose`
+- `/opsx:apply`
+- `/opsx:sync`
+- `/opsx:archive`
+
+Typical flow:
+
+```text
+/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
+  (optional)
+```
+
+#### Start by exploring (the habit worth forming)
+
+`/opsx:explore` is part of the default profile, not an advanced add-on. It's the move to make whenever you have a problem but not yet a plan, which, with an AI assistant, is most of the time.
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: Our search results feel stale. I'm not sure if it's caching,
+     indexing, or the query itself.
+
+AI:  Let me look... [reads the search service and cache layer]
+     It's the index: it only rebuilds nightly, so edits don't show
+     up until the next day. Two options: rebuild on write (simple,
+     more load) or a short-TTL cache invalidation (more moving parts,
+     less load). Given your write volume is low, rebuild-on-write is
+     the cleaner fix. Want to scope it?
+
+You: Yes.
+
+You: /opsx:propose rebuild-search-index-on-write
+```
+
+Explore creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md).
+
+### Expanded/Full Workflow (custom selection)
+
+If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with:
+
+```bash
+openspec config profile
+openspec update
+```
+
+## Workflow Patterns (Expanded Mode)
 
 ### Quick Feature
 
@@ -408,18 +461,22 @@ For full command details and options, see [Commands](commands.md).
 
 | Command | Purpose | When to Use |
 |---------|---------|-------------|
-| `/opsx:explore` | Think through ideas | Unclear requirements, investigation |
-| `/opsx:new` | Start a change | Beginning any new work |
-| `/opsx:continue` | Create next artifact | Step-by-step artifact creation |
-| `/opsx:ff` | Create all planning artifacts | Clear scope, ready to build |
+| `/opsx:propose` | Create change + planning artifacts | Fast default path (`core` profile) |
+| `/opsx:explore` | Think through ideas with the AI | Start here when unsure: unclear requirements, investigation, comparing options |
+| `/opsx:new` | Start a change scaffold | Expanded mode, explicit artifact control |
+| `/opsx:continue` | Create next artifact | Expanded mode, step-by-step artifact creation |
+| `/opsx:ff` | Create all planning artifacts | Expanded mode, clear scope |
 | `/opsx:apply` | Implement tasks | Ready to write code |
-| `/opsx:verify` | Validate implementation | Before archiving, catch mismatches |
-| `/opsx:sync` | Merge delta specs | Optional—archive prompts if needed |
+| `/opsx:verify` | Validate implementation | Expanded mode, before archiving |
+| `/opsx:sync` | Merge delta specs | Expanded mode, optional |
 | `/opsx:archive` | Complete the change | All work finished |
-| `/opsx:bulk-archive` | Archive multiple changes | Parallel work, batch completion |
+| `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work |
 
 ## Next Steps
 
+- [Writing Good Specs](writing-specs.md) - What a strong requirement and scenario look like, and how to right-size a change
+- [Reviewing a Change](reviewing-changes.md) - The two-minute pass on a drafted plan before any code
+- [OpenSpec on a Team](team-workflow.md) - How changes fit branches and pull requests
 - [Commands](commands.md) - Full command reference with options
 - [Concepts](concepts.md) - Deep dive into specs, artifacts, and schemas
 - [Customization](customization.md) - Create custom workflows

docs/writing-specs.md

@@ -0,0 +1,101 @@
+# Writing Good Specs
+
+You rarely write a spec from a blank page. You describe a change in plain language, `/opsx:propose` drafts the requirements and scenarios, and then you make them good. This page is about that last part — what "good" looks like, and how to steer the AI toward it.
+
+It's the companion to [Reviewing a Change](reviewing-changes.md): reviewing is catching the weak spots in a draft, writing is knowing what a strong one is made of.
+
+## A spec is behavior, not code
+
+A spec says what your system *does*, in terms anyone could check — not how it's built. It's made of **requirements** (statements of behavior) and **scenarios** (concrete examples that prove them).
+
+```markdown
+### Requirement: Session Timeout
+The system SHALL expire a session after 30 minutes of inactivity.
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass with no activity
+- THEN the session is invalidated and the user must re-authenticate
+```
+
+Keep the *how* — the queue, the library, the table schema — in `design.md` or the code. When behavior and implementation get mixed into one requirement, the requirement stops being testable and starts going stale the moment the code changes.
+
+## What makes a good requirement
+
+A good requirement is one behavior, stated so plainly you could hand it to someone else to test.
+
+- **One statement, one `SHALL`/`MUST`.** If a requirement has three "and also" clauses, it's really three requirements. Split them.
+- **Observable.** Someone outside the code should be able to tell whether it holds. "The system SHALL show an error banner when the upload exceeds 10 MB" is observable. "The system SHALL handle large uploads gracefully" is not.
+- **The right strength.** OpenSpec uses the RFC 2119 keywords, and they mean different things:
+
+  | Keyword | Meaning |
+  |---------|---------|
+  | `MUST` / `SHALL` | A hard requirement. Non-negotiable. |
+  | `SHOULD` | A strong recommendation, with room for a justified exception. |
+  | `MAY` | Genuinely optional. |
+
+  Reach for `MUST`/`SHALL` by default. Use `SHOULD` only when you truly mean "unless there's a good reason not to."
+
+The test for a requirement: *could a tester who's never seen the code tell whether it passed?* If not, it needs sharpening.
+
+## What makes a good scenario
+
+Scenarios are where a requirement earns its keep. Each one is a concrete GIVEN / WHEN / THEN that could become an automated test.
+
+- **It exercises its requirement.** A scenario that just restates the requirement in other words tests nothing. Make it a specific situation with a specific outcome.
+- **Cover the cases that matter, not just the happy path.** The valid login is easy. The empty input, the expired token, the second click, the thing that goes wrong — those are where bugs live, and where a scenario is worth the most.
+- **Name the case in the title.** "Scenario: Rejects an expired token" tells a reviewer what's covered at a glance; "Scenario: Test 2" doesn't.
+
+A useful habit: before approving, ask *what's the one case I'd be upset to see broken?* — and make sure a scenario names it.
+
+## Pick the right kind of delta
+
+A change describes its edits to the specs with three section types. Using the right one keeps your archived specs honest:
+
+- **`## ADDED Requirements`** — brand-new behavior that didn't exist before.
+- **`## MODIFIED Requirements`** — behavior that already existed and is changing. Include the full new version; a short note on what changed helps a reviewer.
+- **`## REMOVED Requirements`** — behavior going away, with a line on why.
+
+On archive, ADDED gets appended to the main spec, MODIFIED replaces the old version, and REMOVED is deleted. If you mark a real change as ADDED, you end up with two competing requirements; if you describe new behavior as MODIFIED, there's nothing to replace. When in doubt, open the current spec and see whether the requirement is already there.
+
+## Right-size the change
+
+The single most common authoring mistake isn't a badly worded requirement — it's a change that's trying to be three changes.
+
+**A good change has one intent you can say in a sentence.** "Add a dark-mode toggle." "Rate-limit the login endpoint." "Migrate sessions off cookies." If describing the change needs a lot of "and also," that's the signal to split it.
+
+Signs a change is too big:
+
+- The proposal's scope reads like a list of unrelated features.
+- Reviewing it would take an afternoon, so nobody will.
+- Two people couldn't work on it without colliding.
+- Half the tasks could ship on their own.
+
+Smaller changes are easier to review, easier to build in one focused session, and easier to reason about six months later when the archive is all that's left. You can always run several changes in parallel — see [Editing & iterating](editing-changes.md) and [Workflows](workflows.md).
+
+The opposite also happens: a one-line typo fix doesn't need three requirements and a design doc. Match the ceremony to the stakes.
+
+## How to steer the AI toward a good draft
+
+Because `/opsx:propose` does the first draft, the quality of what you get back tracks the quality of what you give it. You don't have to write requirements by hand — you have to aim the AI well:
+
+- **State the intent and the boundary.** *"Add a dark-mode toggle that follows the OS setting on first load — don't touch the existing theme API."* The out-of-scope half matters as much as the in-scope half.
+- **Name the cases you care about.** *"Make sure there's a scenario for a user who already picked a theme manually."* The AI covers what you point at.
+- **Then edit.** It's plain Markdown. Tighten a vague `SHALL`, delete a scenario that tests nothing, add the case it missed — or ask the AI to: *"the timeout requirement is vague, pin it to 30 minutes."*
+
+Draft, sharpen, repeat. A few rounds of that produces a spec you'd trust, which is the whole point.
+
+## A quick checklist
+
+- [ ] Each requirement is one observable behavior with a `SHALL`/`MUST`.
+- [ ] No implementation details are baked into the requirements.
+- [ ] Every requirement has at least one scenario that actually exercises it.
+- [ ] The important edge and error cases have scenarios, not just the happy path.
+- [ ] Deltas use ADDED / MODIFIED / REMOVED correctly against the current spec.
+- [ ] The whole change has one intent you can state in a sentence.
+
+## Where to go next
+
+- [Reviewing a Change](reviewing-changes.md) — the two-minute pass that catches what slipped through.
+- [Concepts](concepts.md) — the deeper model behind specs, changes, and deltas.
+- [Examples & Recipes](examples.md) — real changes from start to finish.

flake.nix

@@ -51,7 +51,7 @@
               inherit (finalAttrs) pname version src;
               pnpm = pkgs.pnpm_9;
               fetcherVersion = 3;
-              hash = "sha256-9s2kdvd7svK4hofnD66HkDc86WTQeayfF5y7L2dmjNg=";
+              hash = "sha256-cFY6phUPK4IOthG/aOtMenyQlLYCCilcOIG+G+v/q04=";
             };
 
             nativeBuildInputs = with pkgs; [

openspec/changes/add-artifact-regeneration-support/proposal.md

@@ -1,136 +0,0 @@
-# Add Artifact Regeneration Support
-
-## Problem
-
-Currently, there is **no way to regenerate artifacts** in the OPSX workflow:
-
-- `/opsx:apply` just reads whatever's on disk
-- `/opsx:continue` only creates the NEXT artifact - won't touch existing ones
-
-If you edit `design.md` after `tasks.md` exists, your only options are:
-1. Delete tasks.md manually, then run `/opsx:continue`
-2. Edit tasks.md manually
-
-The documentation claims you can "update artifacts mid-flight and continue" but there's no mechanism that actually supports this.
-
-## Proposed Solution
-
-Two parts:
-
-### Part 1: Staleness Detection
-Add artifact staleness detection to `/opsx:apply`:
-
-1. **Track modification times**: When generating an artifact, record the mtime of its dependencies
-2. **Detect staleness**: When `/opsx:apply` runs, check if upstream artifacts (design.md, specs) have been modified since tasks.md was generated
-3. **Prompt user**: If stale, ask: "Design was modified after tasks were generated. Would you like to regenerate tasks with `/opsx:continue`?"
-
-## User Experience
-
-### Vision: Seamless Mid-Flight Correction
-
-This is the workflow we want to enable (currently documented but not supported):
-
-```
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ Task 1.1: Created caching layer
-     ✓ Task 1.2: Added cache invalidation
-
-     Working on 1.3: Implement TTL...
-     I noticed the design assumes Redis, but your project uses
-     in-memory caching. Should I update the design?
-
-You: Yes, update it to use the existing cache module.
-
-AI:  Updated design.md to use CacheManager from src/cache/
-     Updated tasks.md with revised implementation steps
-     Continuing implementation...
-     ✓ Task 1.3: Implemented TTL using CacheManager
-     ...
-```
-
-**No restart needed.** Just update the artifact and continue.
-
-### Staleness Warning UX
-
-When user manually edits an upstream artifact:
-
-```
-$ /opsx:apply
-
-⚠️  Detected changes to upstream artifacts:
-    - design.md modified 5 minutes ago (after tasks.md was generated)
-
-Options:
-1. Regenerate tasks (recommended)
-2. Continue anyway with current tasks
-3. Cancel
-
->
-```
-
-### Part 2: Regeneration Capability
-
-Add a way to regenerate specific artifacts:
-
-```bash
-# Option A: Flag on continue
-/opsx:continue --regenerate tasks
-
-# Option B: Separate command
-/opsx:regenerate tasks
-
-# Option C: Interactive prompt when staleness detected
-/opsx:apply
-# "Design changed. Regenerate tasks? [y/N]"
-```
-
-## Technical Approach
-
-### Option A: Metadata File
-Store `.openspec-meta.json` in change directory:
-```json
-{
-  "tasks.md": {
-    "generated_at": "2025-01-24T10:00:00Z",
-    "dependencies": {
-      "design.md": "2025-01-24T09:55:00Z",
-      "specs/feature/spec.md": "2025-01-24T09:50:00Z"
-    }
-  }
-}
-```
-
-### Option B: Frontmatter
-Add YAML frontmatter to generated artifacts:
-```markdown
----
-generated_at: 2025-01-24T10:00:00Z
-depends_on:
-  - design.md@2025-01-24T09:55:00Z
----
-# Tasks
-...
-```
-
-### Option C: Git-based
-Use git to detect if upstream files changed since downstream was last modified. No extra metadata needed but requires git.
-
-## Non-Goals
-
-- Automatic regeneration (user should always choose)
-- Blocking apply entirely (just warn)
-- Tracking code file changes (only artifact dependencies)
-
-## Dependencies
-
-- Should be implemented after `fix-midflight-update-docs` so docs are accurate first
-- Could be combined with that change if desired
-
-## Success Criteria
-
-- User is warned when applying with stale artifacts
-- Clear path to regenerate if needed
-- No false positives (only warn when genuinely stale)
-- Documentation claims become actually true

openspec/changes/add-change-stacking-awareness/.openspec.yaml

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

openspec/changes/add-change-stacking-awareness/proposal.md

@@ -0,0 +1,93 @@
+## Why
+
+Parallel changes often touch the same capabilities and `cli-init`/`cli-update` behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order.
+
+This creates three recurring problems:
+
+- teams cannot tell which change should land first
+- large changes are hard to split into safe mergeable slices
+- parallel work can accidentally reintroduce assumptions already removed by another change
+
+We need lightweight planning metadata and CLI guidance so contributors can safely stack plans on top of each other.
+
+## What Changes
+
+### 1. Add lightweight stack metadata for changes
+
+Extend change metadata to support sequencing and decomposition context, for example:
+
+- `dependsOn`: changes that must land first
+- `provides`: capability markers exposed by this change
+- `requires`: capability markers needed by this change
+- `touches`: capability/spec areas likely affected (advisory only; warning signal, not a hard dependency)
+- `parent`: optional parent change for split work
+
+Metadata is optional and backward compatible for existing changes.
+
+Ordering semantics:
+
+- `dependsOn` is the source of truth for execution/archive ordering
+- `provides`/`requires` are capability contracts for validation and planning visibility
+- `provides`/`requires` do not create implicit dependency edges; authors must still declare required ordering via `dependsOn`
+
+### 2. Add stack-aware validation
+
+Enhance change validation to detect planning issues early:
+
+- missing dependencies
+- dependency cycles
+- archive ordering violations (for example, attempting to archive a change before all `dependsOn` predecessors are archived)
+- unmatched capability markers (for example, `requires` marker with no provider in active history emits non-blocking warning)
+- overlap warnings when active changes touch the same capability
+
+Validation should fail only for deterministic blockers (for example cycles or missing required dependencies), and keep overlap checks as actionable warnings.
+
+### 3. Add sequencing visibility commands
+
+Add lightweight CLI support to inspect and execute plan order:
+
+- `openspec change graph` to show dependency DAG/order
+- `openspec change graph` validates for cycles first; when cycles are present it fails with the same deterministic cycle error as stack-aware validation
+- `openspec change next` to suggest unblocked changes ready to implement/archive
+
+### 4. Add split scaffolding for large changes
+
+Add helper workflow to decompose large proposals into stackable slices:
+
+- `openspec change split <change-id>` scaffolds child changes with `parent` + `dependsOn`
+- generates minimal proposal/tasks stubs for each child slice
+- converts the source change into a parent planning container (no duplicate child implementation tasks)
+- re-running split for an already-split source change returns a deterministic actionable error unless `--overwrite` (alias `--force`) is passed
+- `--overwrite` / `--force` fully regenerates managed child scaffold stubs and metadata links for the split, replacing prior scaffold content
+
+### 5. Document stack-first workflow
+
+Update docs to describe:
+
+- how to model dependencies and parent/child slices
+- when to split a large change
+- how to use graph/next validation signals during parallel development
+- migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md`:
+  - machine-readable change metadata becomes the normative dependency source
+  - `IMPLEMENTATION_ORDER.md` remains optional narrative context during transition
+
+## Capabilities
+
+### New Capabilities
+
+- `change-stacking-workflow`: Dependency-aware sequencing and split scaffolding for change planning
+
+### Modified Capabilities
+
+- `cli-change`: Adds graph/next/split planning commands and stack-aware validation messaging
+- `change-creation`: Supports parent/dependency metadata when creating or splitting changes
+- `openspec-conventions`: Defines optional stack metadata conventions for change proposals
+
+## Impact
+
+- `src/core/project-config.ts` and related parsing/validation utilities for change metadata loading
+- `src/core/config-schema.ts` (or dedicated change schema) for stack metadata validation
+- `src/commands/change.ts` and/or `src/core/list.ts` for graph/next/split command behavior
+- `src/core/validation/*` for dependency cycle and overlap checks
+- `docs/cli.md`, `docs/concepts.md`, and contributor guidance for stack-aware workflows
+- tests for metadata parsing, graph ordering, next-item suggestions, and split scaffolding

openspec/changes/add-change-stacking-awareness/specs/change-creation/spec.md

@@ -0,0 +1,15 @@
+## ADDED Requirements
+
+### Requirement: Stack Metadata Scaffolding
+Change creation workflows SHALL support optional dependency metadata for new or split changes.
+
+#### Scenario: Create change with stack metadata
+- **WHEN** a change is created with stack metadata inputs
+- **THEN** creation SHALL persist metadata fields in change configuration
+- **AND** persisted metadata SHALL be validated against change metadata schema rules
+
+#### Scenario: Split-generated child metadata
+- **WHEN** child changes are generated from a split workflow
+- **THEN** each child SHALL include a `parent` link to the source change
+- **AND** SHALL include dependency metadata needed for deterministic sequencing
+

openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Stack Metadata Model
+The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships.
+
+#### Scenario: Optional stack metadata is present
+- **WHEN** a change includes stack metadata fields
+- **THEN** the system SHALL parse and expose `dependsOn`, `provides`, `requires`, `touches`, and `parent`
+- **AND** validation SHALL enforce normalized field shapes and value types (`dependsOn`/`provides`/`requires`/`touches` as string arrays, `parent` as string when present)
+
+#### Scenario: Backward compatibility without stack metadata
+- **WHEN** a change does not include stack metadata
+- **THEN** existing behavior SHALL continue without migration steps
+- **AND** validation SHALL not fail solely because stack metadata is absent
+
+### Requirement: Change Dependency Graph
+The system SHALL provide dependency-aware ordering for active changes.
+
+#### Scenario: Build dependency order
+- **WHEN** users request stack planning output
+- **THEN** the system SHALL compute a dependency graph across active changes
+- **AND** SHALL return a deterministic topological order for unblocked changes
+
+#### Scenario: Tie-breaking within the same dependency depth
+- **WHEN** multiple unblocked changes share the same topological dependency depth
+- **THEN** ordering SHALL break ties lexicographically by change ID
+- **AND** repeated runs over the same input SHALL return the same order
+
+#### Scenario: Dependency cycle detection
+- **WHEN** active changes contain a dependency cycle
+- **THEN** validation SHALL fail with cycle details before archive or sequencing actions proceed
+- **AND** output SHALL include actionable guidance to break the cycle
+
+### Requirement: Capability marker and overlap semantics
+The system SHALL treat capability markers as validation contracts and `touches` as advisory overlap signals.
+
+#### Scenario: Required capability provided by an active change
+- **WHEN** change B declares `requires` marker `X`
+- **AND** active change A declares `provides` marker `X`
+- **THEN** validation SHALL require B to declare an explicit ordering edge in `dependsOn` to at least one active provider of `X`
+- **AND** validation SHALL fail if no explicit dependency is declared
+
+#### Scenario: Requires marker without active provider
+- **WHEN** a change declares a `requires` marker
+- **AND** no active change declares the corresponding `provides` marker
+- **THEN** validation SHALL NOT infer an implicit dependency edge
+- **AND** ordering SHALL continue to be determined solely by explicit `dependsOn` relationships
+
+#### Scenario: Requires marker satisfied by archived history
+- **WHEN** a change declares a `requires` marker
+- **AND** no active change provides that marker
+- **AND** at least one archived change in history provides that marker
+- **THEN** validation SHALL NOT warn solely about missing provider
+- **AND** SHALL continue to use explicit `dependsOn` for active ordering
+
+#### Scenario: Requires marker missing in full history
+- **WHEN** a change declares a `requires` marker
+- **AND** no active or archived change in history provides that marker
+- **THEN** validation SHALL emit a non-blocking warning naming the change and missing marker
+- **AND** SHALL NOT infer an implicit dependency edge
+
+#### Scenario: Overlap warning for shared touches
+- **WHEN** multiple active changes declare overlapping `touches` values
+- **THEN** validation SHALL emit a warning listing the overlapping changes and touched areas
+- **AND** validation SHALL NOT fail solely on overlap

openspec/changes/add-change-stacking-awareness/specs/cli-change/spec.md

@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Stack Planning Commands
+The change CLI SHALL provide commands for dependency-aware sequencing of active changes.
+
+#### Scenario: Show dependency graph
+- **WHEN** a user runs `openspec change graph`
+- **THEN** the CLI SHALL display dependency relationships for active changes
+- **AND** SHALL include a deterministic recommended order for execution
+
+#### Scenario: Show next unblocked changes
+- **WHEN** a user runs `openspec change next`
+- **THEN** the CLI SHALL list changes that are not blocked by unresolved dependencies
+- **AND** SHALL use deterministic tie-breaking when multiple options are available
+
+### Requirement: Split Large Change Scaffolding
+The change CLI SHALL support scaffolding child slices from an existing large change.
+
+#### Scenario: Split command scaffolds child changes
+- **WHEN** a user runs `openspec change split <change-id>`
+- **THEN** the CLI SHALL create child change directories with proposal/tasks stubs
+- **AND** generated metadata SHALL include `parent` and dependency links back to the source change
+
+#### Scenario: Re-running split on an already-split change
+- **WHEN** a user runs `openspec change split <change-id>` for a parent whose generated child directories already exist
+- **THEN** the CLI SHALL fail with a deterministic, actionable error
+- **AND** SHALL NOT mutate existing child change content unless an explicit overwrite mode is requested

openspec/changes/add-change-stacking-awareness/specs/openspec-conventions/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Stack-Aware Change Planning Conventions
+OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes.
+
+#### Scenario: Declaring change dependencies
+- **WHEN** authors need to sequence related changes
+- **THEN** conventions SHALL define how to declare dependencies and provided/required capability markers
+- **AND** validation guidance SHALL distinguish hard blockers from soft overlap warnings
+
+#### Scenario: Dependency source of truth during migration
+- **WHEN** both stack metadata and `openspec/changes/IMPLEMENTATION_ORDER.md` are present
+- **THEN** conventions SHALL treat per-change stack metadata as the normative dependency source
+- **AND** `IMPLEMENTATION_ORDER.md` SHALL be treated as optional narrative guidance
+
+#### Scenario: Explicit ordering remains required for capability markers
+- **WHEN** authors use `provides` and `requires` markers to describe capability contracts
+- **THEN** conventions SHALL require explicit `dependsOn` edges for ordering relationships
+- **AND** conventions SHALL prohibit treating `requires` as an implicit dependency edge
+
+#### Scenario: Declaring advisory overlap via touches
+- **WHEN** a change may affect capability/spec areas shared by concurrent changes without requiring ordering
+- **THEN** conventions SHALL allow authors to declare `touches` with advisory area identifiers (for example capability IDs, spec area names, or paths)
+- **AND** tooling SHALL treat `touches` as informational only (no implicit dependency edge, non-blocking validation signal)
+
+#### Scenario: Declaring parent-child split structure
+- **WHEN** a large change is decomposed into smaller slices
+- **THEN** conventions SHALL define parent-child metadata and expected ordering semantics
+- **AND** docs SHALL describe when to split versus keep a single change

openspec/changes/add-change-stacking-awareness/tasks.md

@@ -0,0 +1,39 @@
+## 1. Metadata Model
+
+- [ ] 1.1 Add optional stack metadata fields (`dependsOn`, `provides`, `requires`, `touches`, `parent`) to change metadata schema
+- [ ] 1.2 Keep metadata backward compatible for existing changes without new fields
+- [ ] 1.3 Add tests for valid/invalid metadata and schema evolution behavior
+
+## 2. Stack-Aware Validation
+
+- [ ] 2.1 Detect dependency cycles and fail validation with deterministic errors
+- [ ] 2.2 Detect missing `dependsOn` targets (referenced change ID does not exist) and detect changes transitively blocked by unresolved/cyclic dependency paths
+- [ ] 2.3 Add overlap warnings for active changes that touch the same capability/spec areas
+- [ ] 2.4 Emit advisory warnings for unmatched `requires` markers when no provider exists in active history
+- [ ] 2.5 Add tests for cycle, missing dependency, overlap warning, and unmatched `requires` cases
+
+## 3. Sequencing Commands
+
+- [ ] 3.1 Add `openspec change graph` to display dependency order for active changes
+- [ ] 3.2 Add `openspec change next` to suggest unblocked changes in recommended order
+- [ ] 3.3 Add tests for topological ordering and deterministic tie-breaking (lexicographic by change ID at equal depth)
+
+## 4. Split Scaffolding
+
+- [ ] 4.1 Add `openspec change split <change-id>` to scaffold child slices
+- [ ] 4.2 Ensure generated children include parent/dependency metadata and stub proposal/tasks files
+- [ ] 4.3 Convert the source change into a parent planning container as part of split (no duplicate child implementation tasks)
+- [ ] 4.4 Add tests for split output structure, source-change parent conversion, and deterministic re-split error behavior when overwrite mode is not requested
+- [ ] 4.5 Implement and test explicit overwrite mode for `openspec change split` (`--overwrite` / `--force`) for controlled re-splitting
+
+## 5. Documentation
+
+- [ ] 5.1 Document stack metadata and sequencing workflow in `docs/concepts.md`
+- [ ] 5.2 Document new change commands and usage examples in `docs/cli.md`
+- [ ] 5.3 Add guidance for breaking large changes into independently mergeable slices
+- [ ] 5.4 Document migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md` as optional narrative, not dependency source of truth
+
+## 6. Verification
+
+- [ ] 6.1 Run targeted tests for change parsing, validation, and CLI commands
+- [ ] 6.2 Run full test suite (`pnpm test`) and resolve regressions

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

@@ -1,60 +0,0 @@
-## 1. Project Setup and Command Registration
-
-- [x] 1.1 Create directory structure: `src/core/dashboard/` with `index.ts`, `server.ts`, `data.ts`, `markdown.ts`
-- [x] 1.2 Register `openspec dashboard` command in `src/cli/index.ts` with `--port` and `--no-open` options
-- [x] 1.3 Create `DashboardCommand` class in `src/core/dashboard/index.ts` that validates openspec directory exists
-
-## 2. Data Gathering Module
-
-- [x] 2.1 Implement `getChangesData()` in `data.ts` that returns draft/active/completed changes with artifact existence status (proposal.md, specs/, design.md, tasks.md)
-- [x] 2.2 Implement `getSpecsData()` in `data.ts` that returns specs grouped by domain prefix with requirement counts
-- [x] 2.3 Implement `getArchiveData()` in `data.ts` that returns archived changes with parsed dates, sorted reverse chronologically
-- [x] 2.4 Implement `getSummary()` in `data.ts` that aggregates counts for dashboard summary section
-- [x] 2.5 Implement `getArtifactContent()` in `data.ts` that reads a markdown file by relative path with path traversal protection
-
-## 3. Markdown Renderer
-
-- [x] 3.1 Implement markdown-to-HTML converter in `markdown.ts` handling headings, paragraphs, bold, italic, and line breaks
-- [x] 3.2 Add support for fenced code blocks and inline code
-- [x] 3.3 Add support for unordered lists, ordered lists, and checkboxes
-- [x] 3.4 Add support for blockquotes, horizontal rules, and links
-
-## 4. HTTP Server and API
-
-- [x] 4.1 Implement HTTP server in `server.ts` using Node.js built-in `http` module
-- [x] 4.2 Add route `GET /` that serves the embedded single-page HTML dashboard
-- [x] 4.3 Add route `GET /api/summary` returning aggregated project data
-- [x] 4.4 Add route `GET /api/changes` returning changes with artifact status
-- [x] 4.5 Add route `GET /api/specs` returning specs grouped by domain
-- [x] 4.6 Add route `GET /api/archive` returning archive entries with pagination (default 50)
-- [x] 4.7 Add route `GET /api/artifact?path=<relative>` returning rendered markdown HTML with path traversal guard
-- [x] 4.8 Implement port selection with auto-increment from default 3000 to 3010
-- [x] 4.9 Implement cross-platform browser opening (open/xdg-open/start)
-- [x] 4.10 Add graceful shutdown on SIGINT/SIGTERM
-
-## 5. Dashboard HTML/CSS/JS
-
-- [x] 5.1 Create embedded HTML template with navigation tabs for Changes, Specs, and Archive sections
-- [x] 5.2 Implement Changes view with status grouping (draft/active/completed), artifact indicators, and progress bars
-- [x] 5.3 Implement Specs view with domain-prefix grouping and requirement count display
-- [x] 5.4 Implement Archive view with date-based listing and "load more" pagination
-- [x] 5.5 Implement artifact detail panel that fetches and displays rendered markdown on click
-- [x] 5.6 Add basic responsive CSS styling with monospace fonts matching terminal aesthetic
-
-## 6. Testing
-
-- [x] 6.1 Add unit tests for markdown renderer in `test/core/dashboard/markdown.test.ts`
-- [x] 6.2 Add unit tests for data gathering functions in `test/core/dashboard/data.test.ts`
-- [x] 6.3 Add unit tests for path traversal prevention in artifact endpoint
-- [x] 6.4 Add unit tests for port selection logic
-- [x] 6.5 Add unit tests for domain grouping logic
-- [x] 6.6 Add unit tests for archive date parsing
-
-## 7. Polish and Integration
-
-- [x] 7.1 Add CLI help text for the dashboard command
-- [x] 7.2 Add shell completion entries for dashboard command and its options
-- [x] 7.3 Handle edge cases: empty project, missing directories, unparseable specs
-- [x] 7.4 Ensure cross-platform path handling with `path.join()` throughout
-- [x] 7.5 Run linting and fix any issues (`pnpm run lint`)
-- [x] 7.6 Run full test suite (`pnpm test`)

openspec/changes/add-global-install-scope/.openspec.yaml

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

openspec/changes/add-global-install-scope/design.md

@@ -0,0 +1,161 @@
+## Context
+
+OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable.
+
+The requested change is to support user-selectable install scope (`global` or `project`) for tool skills/commands, defaulting to `global` for new configurations while preserving legacy project-local behavior until explicit migration.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Provide a single scope preference that users can set globally and override per run
+- Default new users to `global` scope
+- Make install path resolution deterministic and explicit across tools/surfaces
+- Preserve current behavior for users with older config files that do not yet define `installScope`
+- Avoid silent partial installs; surface effective scope decisions in output
+
+**Non-Goals:**
+
+- Implementing project-local config file support for global settings
+- Defining global install paths for tools where upstream location conventions are unknown
+- Changing workflow/profile semantics (`core`, `custom`, `delivery`) in this change
+
+## Decisions
+
+### 1. Scope model in global config
+
+Add install scope preference to global config:
+
+```ts
+type InstallScope = 'global' | 'project';
+
+interface GlobalConfig {
+  // existing fields...
+  installScope?: InstallScope;
+}
+```
+
+Defaults:
+
+- New configs SHOULD write `installScope: global` explicitly.
+- Existing configs without this field continue to load safely through schema evolution and SHALL resolve effective default as `project` until users explicitly set `installScope`.
+
+### 2. Explicit tool scope support metadata
+
+Extend `AI_TOOLS` metadata with optional scope support declarations per surface:
+
+```ts
+interface ToolInstallScopeSupport {
+  skills?: InstallScope[];
+  commands?: InstallScope[];
+}
+```
+
+Resolution rules:
+
+1. If scope support metadata is absent for a tool surface, treat it as project-only support for conservative backward compatibility.
+2. Try preferred scope.
+3. If unsupported, use alternate scope when supported.
+4. If neither is supported, fail with actionable error.
+
+This enables default-global behavior while remaining safe for tools that only support project-local paths.
+
+### 3. Scope-aware install target resolver
+
+Introduce shared resolver utilities to compute effective target paths for:
+
+- skills root directory
+- command output files
+
+Resolver input:
+
+- tool id
+- requested scope
+- project root
+- environment context (`CODEX_HOME`, etc.)
+
+Resolver output:
+
+- effective scope per surface
+- concrete target paths
+- optional fallback reasons for user-facing output
+
+Platform behavior:
+
+- Resolver outputs are OS-aware and normalized for the current platform.
+- Windows global targets MUST use Windows path conventions (for example `%USERPROFILE%\.codex\prompts` fallback for Codex when `CODEX_HOME` is unset), not POSIX defaults.
+
+### 4. Context-aware command adapter paths
+
+Update command generation contract so adapters receive install context for path resolution. This avoids hardcoded absolute/relative assumptions and centralizes scope decisions.
+
+Example direction:
+
+```ts
+getFilePath(commandId: string, context: InstallContext): string
+```
+
+### 5. CLI behavior and UX
+
+`init`:
+
+- Uses configured install scope by default; if absent in a legacy config, uses migration-safe effective default (`project`).
+- Supports explicit override flag (`--scope global|project`).
+- In interactive mode, displays chosen scope and any per-tool fallback decisions before writing files.
+
+`update`:
+
+- Applies current scope preference (or override); if absent in a legacy config, uses migration-safe effective default (`project`).
+- Performs drift detection using effective scoped paths and last-applied scope state.
+- Reports effective scope decisions in summary output.
+
+`config`:
+
+- `openspec config profile` interactive flow includes install scope selection.
+- `openspec config list` shows `installScope` with source annotation (`explicit`, `new-default`, or `legacy-default`).
+
+### 6. Cleanup safety during scope changes
+
+When scope changes:
+
+- Writes occur in the new effective targets.
+- Cleanup/removal is limited to OpenSpec-managed files for the relevant tool/workflow IDs.
+- Output explicitly states which scope locations were updated and which were cleaned.
+
+### 7. Scope drift state tracking
+
+Track last successful effective scope per tool/surface in project-managed state.
+
+Rules:
+
+1. Drift is detected when current resolved scope differs from last successful scope for a configured tool/surface.
+2. Scope support MUST be validated for all configured tools/surfaces before any write starts.
+3. Update writes to newly resolved targets first, verifies completeness, then removes managed files at previous targets.
+4. If new-target writes are partial or verification fails, command SHALL abort old-target cleanup and report actionable failure with incomplete/new and preserved/old paths.
+5. Cleanup failures do not rollback new writes; command returns actionable failure with leftover paths to resolve.
+
+### 8. Coordination with command-surface capability changes
+
+If `add-tool-command-surface-capabilities` lands, planning logic must evaluate scope resolution and delivery/capability behavior together (scope × delivery × command surface).
+
+## Risks / Trade-offs
+
+**Risk: Cross-project shared global state**
+Global installs are shared across projects. Updating global artifacts from one project affects all projects using that tool scope.
+→ Mitigation: make scope explicit in output; keep profile/delivery global and deterministic.
+
+**Risk: Tool-specific unknown global conventions**
+Not all tools document a stable global install location.
+→ Mitigation: use explicit scope support metadata; fallback or fail instead of guessing.
+
+**Risk: Adapter API churn**
+Changing adapter path contracts touches many files/tests.
+→ Mitigation: migrate in one pass with adapter contract tests and existing end-to-end generation tests.
+
+## Rollout Plan
+
+1. Add config schema + defaults for install scope.
+2. Add tool scope capability metadata and resolver utilities.
+3. Upgrade command adapter contract and generator path plumbing.
+4. Integrate scope-aware behavior into init/update.
+5. Add documentation and test coverage.

openspec/changes/add-global-install-scope/proposal.md

@@ -0,0 +1,101 @@
+## Why
+
+OpenSpec installation paths are currently inconsistent:
+
+- Most skills and commands are written to project-local directories.
+- Codex commands are already global (`$CODEX_HOME/prompts` or `~/.codex/prompts`).
+- Users cannot choose a consistent install scope strategy across tools.
+
+This creates friction for users who prefer user-level setup and expect tool artifacts to be managed globally by default.
+
+## What Changes
+
+### 1. Add install scope preference with legacy-safe defaults
+
+Introduce a global install scope setting with two modes:
+
+- `global` (default for newly created configs)
+- `project`
+
+The setting is stored in global config and can be overridden per command run.
+For schema-evolved legacy configs where `installScope` is absent, effective default remains `project` until users opt in to global scope.
+
+### 2. Add scope-aware path resolution for skills and commands
+
+Refactor path resolution so both `init` and `update` compute install targets from:
+
+- selected scope preference (`global` or `project`)
+- tool capability metadata (which scopes each tool/surface supports)
+- runtime context (project root, home directories, env overrides)
+
+### 3. Add per-tool capability metadata for scope support
+
+Extend tool metadata to explicitly declare scope support per surface:
+
+- skills scope support
+- commands scope support
+
+When preferred scope is unsupported for a tool/surface, the system uses deterministic fallback rules and reports the effective scope in output.
+
+### 4. Make command generation context-aware
+
+Extend command adapter path resolution so adapters receive install context (scope + environment context), instead of only command ID. This removes special-case handling and allows consistent scope behavior across tools.
+
+### 5. Update init/update UX and behavior
+
+- `openspec init`:
+  - accepts scope override flag
+  - uses configured scope or migration-aware default (new configs default global; legacy configs preserve project until migration)
+  - applies scope-aware generation and cleanup planning
+- `openspec update`:
+  - applies current scope preference
+  - syncs artifacts in effective scope per tool/surface
+  - tracks last successful effective scope per tool/surface for deterministic scope-drift detection
+  - reports effective scope decisions clearly
+
+### 6. Extend config UX and docs
+
+- Add install scope control in `openspec config profile` interactive flow.
+- Extend `openspec config list` output with install scope source (`explicit`, `new-default`, `legacy-default`).
+- Add explicit migration guidance and prompt path so legacy users can opt into `global` scope.
+- Update supported tools and CLI docs to explain scope behavior and fallback rules.
+
+### 7. Coordinate with command-surface capability delivery rules
+
+`cli-init` and `cli-update` planning SHALL compose:
+
+- install scope (`global | project`)
+- delivery mode (`both | skills | commands`)
+- command surface capability (`adapter | skills-invocable | none`)
+
+This proposal remains focused on scope resolution, but implementation and test coverage should include mixed-tool cases to avoid regressions when combined with `add-tool-command-surface-capabilities`.
+
+## Capabilities
+
+### New Capabilities
+
+- `installation-scope`: Scope preference model and effective scope resolution for tool artifact installation.
+
+### Modified Capabilities
+
+- `global-config`: Persist install scope preference with schema evolution defaults.
+- `cli-config`: Configure and inspect install scope preferences.
+- `ai-tool-paths`: Add tool-level scope support metadata and path strategy.
+- `command-generation`: Scope-aware adapter path resolution via install context.
+- `cli-init`: Scope-aware initialization planning and output.
+- `cli-update`: Scope-aware update sync, drift detection, and output.
+- `migration`: Scope-aware migration scanning with install-scope-aware workflow lookup.
+
+## Impact
+
+- `src/core/global-config.ts` - new install scope fields and defaults
+- `src/core/config-schema.ts` - validation support for install scope config keys
+- `src/commands/config.ts` - interactive profile/config UX additions for install scope
+- `src/core/config.ts` - tool scope capability metadata
+- `src/core/available-tools.ts` and `src/core/shared/tool-detection.ts` - scope-aware configured detection
+- `src/core/command-generation/types.ts` and adapter implementations - context-aware file path resolution
+- `src/core/init.ts` - scope-aware generation/removal planning
+- `src/core/update.ts` - scope-aware sync/removal/drift planning
+- `src/core/migration.ts` - scope-aware workflow scanning support
+- `docs/supported-tools.md` and `docs/cli.md` - install scope behavior documentation
+- `test/core/init.test.ts`, `test/core/update.test.ts`, adapter tests, config tests - scope coverage

openspec/changes/add-global-install-scope/specs/ai-tool-paths/spec.md

@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: AIToolOption skillsDir field
+The `AIToolOption` interface SHALL include scope support metadata in addition to path metadata.
+
+#### Scenario: Scope support metadata present
+- **WHEN** a tool entry is defined in `AI_TOOLS`
+- **THEN** it MAY declare supported install scopes for skills and commands
+- **AND** this metadata SHALL be used for effective scope resolution
+
+#### Scenario: Scope support metadata absent
+- **WHEN** a tool entry in `AI_TOOLS` omits scope support metadata for a surface
+- **THEN** resolver behavior SHALL default that surface to project-only support
+- **AND** effective scope resolution SHALL apply normal preferred/fallback rules against that default
+
+### Requirement: Path configuration for supported tools
+Path metadata SHALL support both project and global install targets via resolver logic.
+
+#### Scenario: Project scope path
+- **WHEN** effective scope is `project` for skills
+- **THEN** `skillsDir` SHALL be treated as a tool-specific container path under project root
+- **AND** managed skill artifacts SHALL be written under `<projectRoot>/<skillsDir>/skills/`
+- **AND** tool definitions SHALL set `skillsDir` accordingly (for example `.openspec` -> `.openspec/skills/`)
+
+#### Scenario: Global scope path
+- **WHEN** effective scope is `global` for a supported tool/surface
+- **THEN** paths SHALL resolve to tool-specific global directories
+- **AND** environment overrides (for example `CODEX_HOME`) SHALL be respected where applicable
+
+#### Scenario: Windows global path resolution for Codex commands
+- **WHEN** effective scope is `global`
+- **AND** tool is Codex
+- **AND** platform is Windows
+- **THEN** command targets SHALL resolve to `%CODEX_HOME%\prompts` when `CODEX_HOME` is set
+- **AND** SHALL otherwise resolve to `%USERPROFILE%\.codex\prompts`

openspec/changes/add-global-install-scope/specs/cli-config/spec.md

@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: Install scope configuration via profile flow
+The config profile workflow SHALL allow users to configure install scope preference.
+
+#### Scenario: Interactive profile includes install scope
+- **WHEN** user runs `openspec config profile`
+- **THEN** the interactive flow SHALL include install scope selection with values `global` and `project`
+- **AND** the currently configured value SHALL be pre-selected
+
+#### Scenario: Save install scope
+- **WHEN** user confirms config profile changes
+- **THEN** selected install scope SHALL be saved to global config
+
+### Requirement: Install scope visibility in config output
+The config command SHALL display install scope preference in human-readable output.
+
+#### Scenario: Config list shows install scope
+- **WHEN** user runs `openspec config list`
+- **THEN** output SHALL include current install scope value
+- **AND** indicate whether value is default or explicit

openspec/changes/add-global-install-scope/specs/cli-init/spec.md

@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Init install scope selection
+The init command SHALL support install scope selection for generated artifacts.
+
+#### Scenario: Scope defaults to global
+- **WHEN** user runs `openspec init` without explicit scope override
+- **THEN** init SHALL use global config install scope
+- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
+
+#### Scenario: Scope override via flag
+- **WHEN** user runs `openspec init --scope project`
+- **THEN** init SHALL use `project` as preferred scope for that run
+- **AND** SHALL NOT mutate persisted global config unless user explicitly changes config
+
+### Requirement: Init uses effective scope resolution
+The init command SHALL resolve effective scope per tool surface before generating files.
+
+#### Scenario: Effective scope with fallback
+- **WHEN** selected tool/surface does not support preferred scope
+- **AND** supports alternate scope
+- **THEN** init SHALL generate files at alternate effective scope
+- **AND** SHALL display fallback note in summary
+
+#### Scenario: Unsupported scope selection
+- **WHEN** selected tool/surface supports neither preferred nor alternate scope
+- **THEN** init SHALL fail before writing files
+- **AND** SHALL provide clear error guidance

openspec/changes/add-global-install-scope/specs/cli-update/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Update install scope selection
+The update command SHALL support install scope selection for sync operations.
+
+#### Scenario: Scope defaults to global config value
+- **WHEN** user runs `openspec update` without explicit scope override
+- **THEN** update SHALL use configured install scope
+- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
+
+#### Scenario: Scope override via flag
+- **WHEN** user runs `openspec update --scope project`
+- **THEN** update SHALL use `project` as preferred scope for that run
+
+### Requirement: Scope-aware sync and drift detection
+The update command SHALL evaluate configured state and drift using effective scoped paths.
+
+#### Scenario: Scoped drift detection
+- **WHEN** update evaluates whether tools are up-to-date
+- **THEN** it SHALL inspect files at effective scoped targets for each tool/surface
+- **AND** SHALL compare current resolved scope against last successful effective scope for each tool/surface
+- **AND** SHALL treat a difference as sync-required drift
+
+#### Scenario: Scope fallback during update
+- **WHEN** preferred scope is unsupported for a configured tool/surface
+- **AND** alternate scope is supported
+- **THEN** update SHALL apply fallback scope resolution
+- **AND** SHALL report fallback in output
+
+#### Scenario: Unsupported scope during update
+- **WHEN** configured tool/surface supports neither preferred nor alternate scope
+- **THEN** scope support SHALL be validated for all configured tools/surfaces before any write
+- **AND** update SHALL fail without performing file writes when incompatibilities are detected
+- **AND** SHALL report incompatible tools with remediation steps

openspec/changes/add-global-install-scope/specs/command-generation/spec.md

@@ -0,0 +1,22 @@
+## MODIFIED Requirements
+
+### Requirement: ToolCommandAdapter interface
+The system SHALL provide install-context-aware command path resolution.
+
+#### Scenario: Adapter interface structure
+- **WHEN** implementing a tool adapter
+- **THEN** command file path resolution SHALL receive install context (including effective scope and environment context)
+- **AND** SHALL return the effective command output path for that context
+
+#### Scenario: Codex global path remains supported
+- **WHEN** resolving Codex command paths in global scope
+- **THEN** the adapter SHALL target `$CODEX_HOME/prompts` when `CODEX_HOME` is set
+- **AND** SHALL otherwise target `~/.codex/prompts`
+
+### Requirement: Command generator function
+The command generator SHALL pass install context into adapter path resolution for all generated commands.
+
+#### Scenario: Scoped command generation
+- **WHEN** generating commands for a tool with a resolved effective scope
+- **THEN** generated command paths SHALL match that effective scope
+- **AND** the formatted command body/frontmatter behavior SHALL remain tool-specific and unchanged

openspec/changes/add-global-install-scope/specs/global-config/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Install scope field in global config
+The global config schema SHALL include install scope preference.
+
+#### Scenario: Config shape supports install scope
+- **WHEN** reading or writing global config
+- **THEN** config SHALL support `installScope` with allowed values `global` and `project`
+
+#### Scenario: Schema evolution default
+- **WHEN** loading legacy config without `installScope`
+- **THEN** the system SHALL preserve schema compatibility without mutating the file
+- **AND** effective install scope SHALL resolve to `project` until user explicitly sets `installScope`
+- **AND** preserve all other existing fields
+
+#### Scenario: New config default
+- **WHEN** creating a new global config
+- **THEN** the system SHALL persist `installScope: global` by default
+- **AND** users MAY switch to `project` explicitly
+
+#### Scenario: Invalid install scope value
+- **WHEN** config validation receives an invalid install scope value
+- **THEN** the value SHALL be rejected
+- **AND** the system SHALL preserve the existing valid configuration

openspec/changes/add-global-install-scope/specs/installation-scope/spec.md

@@ -0,0 +1,71 @@
+## Purpose
+
+Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics.
+
+## ADDED Requirements
+
+### Requirement: Install scope preference model
+The system SHALL support a user-level install scope preference with values `global` and `project`.
+
+#### Scenario: Default install scope
+- **WHEN** install scope is not explicitly configured
+- **THEN** the system SHALL resolve a migration-aware default:
+- **AND** use `global` for newly created configs
+- **AND** use `project` for legacy schema-evolved configs until explicit migration
+
+#### Scenario: Explicit install scope
+- **WHEN** user configures install scope to `project`
+- **THEN** generation and update flows SHALL use `project` as the preferred scope
+
+### Requirement: Effective scope resolution by tool surface
+The system SHALL compute effective scope per tool surface (skills, commands) based on preferred scope and tool capability support.
+
+#### Scenario: Preferred scope is supported
+- **WHEN** preferred scope is supported for a tool surface
+- **THEN** the system SHALL use that scope as the effective scope
+
+#### Scenario: Preferred scope is unsupported but alternate is supported
+- **WHEN** preferred scope is not supported for a tool surface
+- **AND** the alternate scope is supported
+- **THEN** the system SHALL use the alternate scope as effective scope
+- **AND** SHALL record a fallback note for user-facing output
+
+#### Scenario: No supported scope
+- **WHEN** neither `global` nor `project` is supported for a tool surface
+- **THEN** the command SHALL fail before writing files
+- **AND** SHALL display actionable remediation
+
+### Requirement: Effective scope reporting
+The system SHALL report effective scope decisions in command output when they differ from the preferred scope.
+
+#### Scenario: Fallback reporting
+- **WHEN** fallback resolution occurs for any selected/configured tool surface
+- **THEN** init/update summaries SHALL include effective scope notes per affected tool
+
+### Requirement: Cross-platform path behavior
+Install scope resolution SHALL produce platform-correct target paths.
+
+#### Scenario: Global scope path on Windows
+- **WHEN** effective scope is `global`
+- **AND** the command runs on Windows
+- **THEN** resolved target paths SHALL use Windows path conventions and separators
+- **AND** SHALL NOT reuse POSIX-style home-relative defaults directly
+
+### Requirement: Cleanup safety for scope transitions
+Scope transitions SHALL update new targets first and clean old managed targets safely.
+
+#### Scenario: Automatic cleanup for managed files on scope change
+- **WHEN** update or init applies a scope transition for a configured tool/surface
+- **THEN** the system SHALL write new artifacts in the new effective scope before cleanup
+- **AND** SHALL automatically remove only OpenSpec-managed files in the previous effective scope
+
+#### Scenario: Cleanup scope boundaries
+- **WHEN** cleanup runs after a scope transition
+- **THEN** the system SHALL leave non-managed files untouched
+- **AND** SHALL limit removal scope to the affected tool/workflow-managed paths
+
+#### Scenario: Cleanup failure after successful writes
+- **WHEN** new artifacts were written successfully in the new scope
+- **AND** cleanup of old managed targets fails
+- **THEN** the command SHALL report failure with leftover cleanup paths
+- **AND** SHALL NOT rollback successfully written new-scope artifacts

openspec/changes/add-global-install-scope/tasks.md

@@ -0,0 +1,61 @@
+## 1. Global Config + Validation
+
+- [ ] 1.1 Add `installScope` (`global` | `project`) to `GlobalConfig` with explicit `global` default for newly created configs
+- [ ] 1.2 Update config schema validation and known-key checks to include install scope
+- [ ] 1.3 Add schema-evolution tests ensuring missing `installScope` in legacy configs resolves to effective `project` until explicit migration
+- [ ] 1.4 Extend `openspec config list` output to show install scope and source (`explicit`, `new-default`, `legacy-default`)
+
+## 2. Tool Capability Metadata + Resolvers
+
+- [ ] 2.1 Extend `AI_TOOLS` metadata to declare scope support per surface (skills/commands)
+- [ ] 2.2 Add shared install-target resolver for skills and commands using requested scope + tool support
+- [ ] 2.3 Implement deterministic fallback/error behavior when preferred scope is unsupported, including default behavior when scope support metadata is absent
+- [ ] 2.4 Add unit tests for scope resolution (preferred, fallback, and hard-fail paths)
+
+## 3. Command Generation Contract
+
+- [ ] 3.1 Update `ToolCommandAdapter` path contract to accept install context
+- [ ] 3.2 Update `generateCommand`/`generateCommands` to pass context through adapters
+- [ ] 3.3 Migrate all command adapters to the new path contract
+- [ ] 3.4 Update adapter tests for scoped path behavior (including Codex global path semantics)
+
+## 4. Init Command Scope Support
+
+- [ ] 4.1 Add scope override flag to `openspec init` (`--scope global|project`)
+- [ ] 4.2 Resolve effective scope per tool/surface before writing artifacts
+- [ ] 4.3 Apply scope-aware generation/removal planning for skills and commands
+- [ ] 4.4 Surface effective scope decisions and fallback notes in init summary output
+- [ ] 4.5 Add init tests for global default, project override, and fallback/error scenarios
+
+## 5. Update Command Scope Support
+
+- [ ] 5.1 Add scope override flag to `openspec update` (`--scope global|project`)
+- [ ] 5.2 Make configured-tool detection and drift checks scope-aware
+- [ ] 5.3 Persist and read last successful effective scope per tool/surface for deterministic scope-drift detection
+- [ ] 5.4 Apply scope-aware sync/removal with consistent fallback/error behavior
+- [ ] 5.5 Ensure scope changes update managed files in new targets and clean old managed targets safely
+- [ ] 5.6 Add update tests for global/project/fallback/error and repeat-run idempotency
+
+## 6. Config UX
+
+- [ ] 6.1 Extend `openspec config profile` interactive flow to select install scope
+- [ ] 6.2 Preserve install scope when using preset shortcuts unless explicitly changed
+- [ ] 6.3 Ensure non-interactive config behavior remains deterministic with clear errors
+- [ ] 6.4 Add/adjust config command tests for install scope flows
+- [ ] 6.5 Add migration UX for legacy users to opt into `global` scope explicitly
+
+## 7. Documentation
+
+- [ ] 7.1 Update `docs/supported-tools.md` with scope behavior and effective-scope fallback notes
+- [ ] 7.2 Update `docs/cli.md` examples for init/update scope options
+- [ ] 7.3 Document cross-project implications of global installs
+- [ ] 7.4 Add existing-user migration guide covering legacy-default behavior and explicit opt-in to `installScope: global`
+
+## 8. Verification
+
+- [ ] 8.1 Run targeted tests for config, adapters, init, and update
+- [ ] 8.2 Run full test suite (`pnpm test`) and resolve regressions
+- [ ] 8.3 Manual smoke test: init/update with `installScope=global`
+- [ ] 8.4 Manual smoke test: init/update with `--scope project`
+- [ ] 8.5 Verify path resolution behavior on Windows CI (or cross-platform unit tests with mocked Windows paths)
+- [ ] 8.6 Verify combined behavior matrix for mixed tools across scope × delivery × command-surface capability

openspec/changes/add-qa-smoke-harness/.openspec.yaml

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

openspec/changes/add-qa-smoke-harness/proposal.md

@@ -0,0 +1,45 @@
+## Why
+
+We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX.
+
+Today, manual review is mostly ad hoc: each developer sets up state differently, runs a different command order, and checks outputs informally. This makes regressions easy to miss and slows iteration on CLI UX work.
+
+An 80/20 solution is to add a lightweight smoke harness for deterministic non-interactive flows, plus a short manual checklist for interactive prompt behavior.
+
+## What Changes
+
+- Add a lightweight QA smoke harness for OpenSpec CLI behavior with isolated per-run sandbox state
+- Use `Makefile` targets as the primary entrypoint:
+  - `make qa` (default local QA entrypoint)
+  - `make qa-smoke` (deterministic non-interactive suite)
+  - `make qa-interactive` (prints/opens manual interactive checklist)
+- Implement smoke logic in a script (invoked by Make targets), not in Make itself
+- Ensure each scenario runs in an isolated sandbox with temporary `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
+- Capture scenario artifacts for inspection (command output, exit code, and before/after filesystem state)
+- Add a focused scenario set for high-risk behavior:
+  - init core output generation
+  - non-interactive detected-tool behavior
+  - migration when profile is unset
+  - delivery cleanup (`both -> skills`, `both -> commands`)
+  - commands-only update detection
+  - new tool directory detection messaging
+  - invalid profile override validation
+- Add a short interactive checklist for keypress/prompt UX verification (Space toggle, Enter confirm, detected pre-selection)
+- Wire CI to run the smoke suite on Linux as a fast regression gate
+
+## Capabilities
+
+### New Capabilities
+
+- `qa-smoke-harness`: Deterministic, sandboxed CLI smoke validation with a single developer entrypoint
+
+### Modified Capabilities
+
+- `developer-qa-workflow`: Standardized local/CI QA flow for CLI behavior and migration-sensitive scenarios
+
+## Impact
+
+- `Makefile` - Add `qa`, `qa-smoke`, and `qa-interactive` targets
+- `scripts/qa-smoke.sh` (or equivalent) - Implement sandbox setup, scenario execution, and assertions
+- `docs/` - Add/update contributor-facing QA instructions and interactive checklist usage
+- CI workflow - Add smoke target execution as a lightweight regression gate

openspec/changes/add-qa-smoke-harness/specs/developer-qa-workflow/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Makefile QA Entry Point
+
+The repository SHALL provide Makefile targets as the primary developer entrypoint for CLI QA flows.
+
+#### Scenario: Default QA target runs smoke suite
+
+- **WHEN** a developer runs `make qa`
+- **THEN** the command SHALL execute the non-interactive smoke suite
+- **AND** exit with status code 0 only when all smoke scenarios pass
+
+#### Scenario: Smoke suite target is directly invokable
+
+- **WHEN** a developer runs `make qa-smoke`
+- **THEN** the command SHALL execute the same smoke suite used by `make qa`
+- **AND** return a non-zero exit code on assertion failure
+
+#### Scenario: Interactive checklist target exists
+
+- **WHEN** a developer runs `make qa-interactive`
+- **THEN** the command SHALL provide the manual interactive verification checklist
+- **AND** SHALL NOT run interactive prompt automation by default
+
+### Requirement: Sandboxed Smoke Scenario Runner
+
+The smoke suite SHALL run CLI scenarios in isolated sandboxes so tests are repeatable and do not depend on machine-global state.
+
+#### Scenario: Scenario execution is environment-isolated
+
+- **WHEN** a smoke scenario runs
+- **THEN** it SHALL use temporary values for `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
+- **AND** global config from the host machine SHALL NOT affect scenario outcomes
+
+#### Scenario: Scenario artifacts are captured for review
+
+- **WHEN** a smoke scenario completes
+- **THEN** the runner SHALL capture command output and exit status
+- **AND** SHALL capture enough filesystem state to inspect before/after behavior
+
+#### Scenario: High-risk workflow coverage exists
+
+- **WHEN** the smoke suite executes
+- **THEN** it SHALL include scenarios covering profile/delivery behavior and migration-sensitive flows
+- **AND** include at least:
+  - non-interactive tool detection
+  - migration when profile is unset
+  - delivery cleanup (`both -> skills`, `both -> commands`)
+  - commands-only update detection

openspec/changes/add-skill-cli-auto-approval/proposal.md

@@ -0,0 +1,27 @@
+## Why
+
+Every generated OpenSpec skill drives the `openspec` CLI (`openspec list`, `status`, `instructions`, …). Today the skill frontmatter never pre-approves those calls, so agents that gate Bash on permission prompt the user on every single `openspec` invocation. The workflow stalls on approvals for a first-party, read-mostly CLI the user already opted into by installing OpenSpec.
+
+The Agent Skills standard already solves this: an `allowed-tools` frontmatter field pre-approves listed tools while a skill is active. We just aren't emitting it.
+
+## What Changes
+
+- Every generated `SKILL.md` gains `allowed-tools: Bash(openspec:*)` in its YAML frontmatter, so agents run `openspec` commands from the skill without prompting. Emitted centrally in `generateSkillContent`, so `init`, `update`, every tool's skills directory, and every current and future skill get it uniformly.
+- Claude Code slash commands (`.claude/commands/opsx/*.md`) gain the same field — commands share the skill frontmatter contract, so the same pre-approval applies when a user runs `/opsx:*`.
+- Scope is deliberately narrow: only the `openspec` CLI is pre-approved. Per the standard, `allowed-tools` pre-approves rather than restricts — so any other tool a skill or command uses (Read, Write, or arbitrary Bash for builds/tests in `apply`/`onboard`) stays available under the user's normal permission settings, still prompting as before.
+- Cross-tool: skills go to every supported tool's skills directory, and `allowed-tools` is an Agent Skills standard field — tools that implement the standard honor it; tools that don't ignore the unknown key. Only the Claude command adapter changes, because no other tool's slash-command format defines a per-command pre-approval field.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `cli-init`: the Skill Generation requirement now specifies the `allowed-tools` pre-approval in generated skill frontmatter.
+- `command-generation`: the Claude adapter frontmatter now includes the `allowed-tools` field.
+
+## Impact
+
+- `src/core/shared/allowed-tools.ts` — the shared `OPENSPEC_CLI_ALLOWED_TOOLS` constant (single source for both surfaces).
+- `src/core/shared/skill-generation.ts` — emit `allowed-tools` in the SKILL.md frontmatter.
+- `src/core/command-generation/adapters/claude.ts` — emit `allowed-tools` in the slash-command frontmatter.
+- Tests: regenerated golden skill-content hashes; new assertions that every deployed skill and the Claude command format pre-approve the CLI.
+- No behavior change for agents that ignore `allowed-tools`; pure upside for agents that honor it.

openspec/changes/add-skill-cli-auto-approval/specs/cli-init/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: Skill Generation
+
+The command SHALL generate Agent Skills for selected AI tools.
+
+#### Scenario: Generating skills for a tool
+
+- **WHEN** a tool is selected during initialization
+- **THEN** create 9 skill directories under `.<tool>/skills/`:
+  - `openspec-explore/SKILL.md`
+  - `openspec-new-change/SKILL.md`
+  - `openspec-continue-change/SKILL.md`
+  - `openspec-apply-change/SKILL.md`
+  - `openspec-ff-change/SKILL.md`
+  - `openspec-verify-change/SKILL.md`
+  - `openspec-sync-specs/SKILL.md`
+  - `openspec-archive-change/SKILL.md`
+  - `openspec-bulk-archive-change/SKILL.md`
+- **AND** each SKILL.md SHALL contain YAML frontmatter with name and description
+- **AND** each SKILL.md SHALL contain the skill instructions
+
+#### Scenario: Pre-approving the OpenSpec CLI in skill frontmatter
+
+- **WHEN** generating a skill's YAML frontmatter
+- **THEN** the frontmatter SHALL include an `allowed-tools` field with the value `Bash(openspec:*)`
+- **AND** an agent that honors `allowed-tools` SHALL run `openspec` commands from the skill without prompting for approval
+- **AND** because `allowed-tools` pre-approves rather than restricts, any other tool the skill uses SHALL remain available under the user's existing permission settings

openspec/changes/add-skill-cli-auto-approval/specs/command-generation/spec.md

@@ -0,0 +1,32 @@
+## MODIFIED Requirements
+
+### Requirement: ToolCommandAdapter interface
+
+The system SHALL define a `ToolCommandAdapter` interface for per-tool formatting.
+
+#### Scenario: Adapter interface structure
+
+- **WHEN** implementing a tool adapter
+- **THEN** `ToolCommandAdapter` SHALL require:
+  - `toolId`: string identifier matching `AIToolOption.value`
+  - `getFilePath(commandId: string)`: returns file path for command (relative from project root, or absolute for global-scoped tools like Codex)
+  - `formatFile(content: CommandContent)`: returns complete file content with frontmatter
+
+#### Scenario: Claude adapter formatting
+
+- **WHEN** formatting a command for Claude Code
+- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `allowed-tools`, `category`, `tags` fields
+- **AND** the `allowed-tools` field SHALL have the value `Bash(openspec:*)` so Claude Code runs `openspec` commands from the slash command without prompting for approval
+- **AND** file path SHALL follow pattern `.claude/commands/opsx/<id>.md`
+
+#### Scenario: Cursor adapter formatting
+
+- **WHEN** formatting a command for Cursor
+- **THEN** the adapter SHALL output YAML frontmatter with `name` as `/opsx-<id>`, `id`, `category`, `description` fields
+- **AND** file path SHALL follow pattern `.cursor/commands/opsx-<id>.md`
+
+#### Scenario: Windsurf adapter formatting
+
+- **WHEN** formatting a command for Windsurf
+- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
+- **AND** file path SHALL follow pattern `.windsurf/workflows/opsx-<id>.md`

openspec/changes/add-skill-cli-auto-approval/tasks.md

@@ -0,0 +1,15 @@
+## 1. Implementation
+
+- [x] 1.1 Add the shared `OPENSPEC_CLI_ALLOWED_TOOLS = 'Bash(openspec:*)'` constant (`src/core/shared/allowed-tools.ts`) and emit `allowed-tools` in the frontmatter built by `generateSkillContent`
+- [x] 1.2 Emit the same `allowed-tools` field in the Claude command adapter's frontmatter (`src/core/command-generation/adapters/claude.ts`); other adapters unchanged — no other tool defines a per-command pre-approval field
+
+## 2. Tests
+
+- [x] 2.1 Regenerate the golden generated-content hashes in `skill-templates-parity.test.ts`
+- [x] 2.2 Add a test asserting every deployed skill's generated content contains `allowed-tools: Bash(openspec:*)` (iterates the registry so new skills are covered)
+- [x] 2.3 Assert the Claude adapter output contains the field (`adapters.test.ts`)
+- [x] 2.4 Verify end-to-end: `openspec init --tools claude` emits the field in both SKILL.md and `.claude/commands/opsx/*.md`, and it parses as the YAML string `Bash(openspec:*)`
+
+## 3. Release
+
+- [x] 3.1 Add a changeset describing the auto-approval

openspec/changes/add-tool-command-surface-capabilities/.openspec.yaml

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

openspec/changes/add-tool-command-surface-capabilities/proposal.md

@@ -0,0 +1,115 @@
+## Why
+
+OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools.
+
+Some tools expose OpenSpec workflows via skill entries rather than adapter-generated command files. Kimi CLI is a concrete example: it invokes skills with forms such as `/skill:openspec-new-change`. In this model, skills are the command surface.
+
+Today, this creates a behavior gap:
+
+- `delivery=commands` can remove skills
+- tools without adapters skip command generation
+- result: selected tools like Kimi CLI, ForgeCode, or Mistral Vibe can end up with no invocable workflow artifacts
+
+This is more than a prompt UX issue because non-interactive and CI flows bypass interactive guidance. We need a capability-aware model in core generation logic.
+
+## What Changes
+
+### 1. Add explicit command-surface capability metadata
+
+Add an optional field in tool metadata to describe how a tool exposes commands:
+
+- `adapter`: command files are generated through a command adapter
+- `skills-invocable`: skills are directly invocable as commands
+- `none`: no OpenSpec command surface
+
+Field should be optional. Default behavior is inferred from adapter registry presence: tools with a registered adapter resolve to `adapter`; tools with no adapter registration and no explicit annotation resolve to `none`.
+Capability values use kebab-case string tokens for consistency with serialized metadata conventions.
+
+Initial explicit overrides:
+
+- ForgeCode -> `skills-invocable`
+- Kimi CLI -> `skills-invocable`
+- Mistral Vibe -> `skills-invocable`
+
+Trae no longer belongs in this override set once its `.trae/commands/opsx-<id>.md` adapter is available; it should resolve to `adapter` like other file-backed command integrations.
+
+### 2. Make delivery behavior capability-aware
+
+Update `init` and `update` to compute effective artifact actions per tool from:
+
+- global delivery (`both | skills | commands`)
+- tool command surface capability
+
+Behavior matrix:
+
+- `both`:
+  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
+  - generate command files only for `adapter` tools
+  - `none`: no artifact action; MAY emit compatibility warning
+- `skills`:
+  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
+  - remove adapter-generated command files
+  - `none`: no artifact action; MAY emit compatibility warning
+- `commands`:
+  - `adapter`: generate commands, remove skills
+  - `skills-invocable`: generate (or keep if up-to-date) skills as command surface; do not remove them
+  - `none`: fail fast with clear error
+
+### 3. Add preflight validation and clearer output
+
+Before writing/removing artifacts, validate selected/configured tools against delivery mode:
+
+- interactive flow: show clear compatibility note before confirmation
+- non-interactive flow: fail with deterministic error listing incompatible tools and supported alternatives
+
+Update summaries to show effective delivery outcomes per tool (for example, when commands mode still installs skills for skills-invocable tools).
+
+### 4. Update docs and tests
+
+- document capability model and skills-invocable behavior under delivery modes
+- ensure CLI docs and supported-tools docs reflect effective behavior
+- add test coverage for:
+  - `init --tools kimi` with `delivery=commands`
+  - `update` with Kimi CLI configured under `delivery=commands`
+  - mixed selections (`claude + kimi`) across all delivery modes
+  - explicit error path for tools with no command surface under `delivery=commands`
+
+### 5. Coordinate with install-scope behavior
+
+When combined with `add-global-install-scope`, init/update planning must compose:
+
+- install scope (`global | project`)
+- delivery mode (`both | skills | commands`)
+- command surface capability (`adapter | skills-invocable | none`)
+
+Implementation tests should cover mixed-tool matrices to ensure deterministic behavior when both changes are active.
+
+## Capabilities
+
+### New Capabilities
+
+- `tool-command-surface`: Capability model that classifies tools as `adapter`, `skills-invocable`, or `none` to drive delivery behavior
+
+### Modified Capabilities
+
+- `cli-init`: Delivery handling becomes tool-capability-aware with preflight compatibility validation
+- `cli-update`: Delivery sync becomes tool-capability-aware with consistent compatibility validation and messaging
+- `supported-tools-docs`: Documents command-surface semantics for non-adapter tools
+
+## Impact
+
+- `src/core/config.ts` - add optional command-surface metadata and skills-invocable tool overrides
+- `src/core/command-generation/registry.ts` (or shared helper) - capability inference from adapter presence
+- `src/core/init.ts` - capability-aware generation/removal planning + compatibility validation + summary messaging
+- `src/core/update.ts` - capability-aware sync/removal planning + compatibility validation + summary messaging
+- `src/core/shared/tool-detection.ts` - include capability-aware detection so `skills-invocable` tools remain detectable under `delivery=commands`, and `none` tools are excluded from command-surface artifact detection
+- `docs/supported-tools.md` and `docs/cli.md` - document delivery behavior and compatibility notes
+- `test/core/init.test.ts` and `test/core/update.test.ts` - add coverage for skills-invocable behavior and mixed-tool delivery scenarios
+
+## Sequencing Notes
+
+- This change is intended to stack safely with `simplify-skill-installation` by introducing additive, capability-specific requirements for init/update.
+- If `simplify-skill-installation` merges first, this change should be rebased and keep the capability-aware rule as the source of truth for `delivery=commands` behavior on `skills-invocable` tools.
+- If this change merges first, the `simplify-skill-installation` branch should be rebased to avoid re-introducing a global "commands-only means no skills for all tools" assumption.
+- If `add-global-install-scope` merges first, this change should be rebased to compose capability-aware behavior on top of scope-resolved path decisions from that change.
+- If this change merges first, `add-global-install-scope` should be rebased to preserve Section 5 composition rules (`install scope` + `delivery mode` + `command surface capability`) without overriding capability-aware command-surface outcomes.

openspec/changes/add-tool-command-surface-capabilities/specs/cli-init/spec.md

@@ -0,0 +1,121 @@
+## ADDED Requirements
+
+### Requirement: Command surface capability resolution
+The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference.
+
+#### Scenario: Explicit command surface override
+- **WHEN** a tool declares an explicit command-surface capability
+- **THEN** init SHALL use that explicit capability
+- **AND** SHALL NOT override it based on adapter presence
+
+#### Scenario: Inferred command surface from adapter presence
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** a command adapter is registered for the tool
+- **THEN** init SHALL infer `adapter` as the command surface
+
+#### Scenario: Inferred command surface for skills-only tool
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** no command adapter is registered for the tool
+- **AND** the tool has a configured `skillsDir`
+- **THEN** init SHALL infer `skills-invocable` as the command surface
+
+#### Scenario: Inferred command surface without adapter or skills
+- **WHEN** a tool does not declare an explicit command-surface capability
+- **AND** no command adapter is registered for the tool
+- **AND** the tool has no `skillsDir`
+- **THEN** init SHALL infer `none` as the command surface
+
+### Requirement: Delivery compatibility by tool command surface
+The init command SHALL apply delivery settings using each tool's command surface capability, not adapter presence alone.
+
+#### Scenario: Both delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL generate command files for active workflows using that adapter
+- **AND** SHALL generate or refresh managed skills when the tool has `skillsDir`
+
+#### Scenario: Both delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL NOT require adapter-generated command files for that tool
+
+#### Scenario: Both delivery for none command surface
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
+- **AND** delivery is set to `both`
+- **THEN** the system SHALL perform no command-surface artifact action for that tool
+- **AND** MAY emit a compatibility note indicating no command surface is available
+
+#### Scenario: Skills delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL remove managed adapter-generated command files for that tool
+
+#### Scenario: Skills delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
+- **AND** SHALL NOT require adapter-generated command files for that tool
+
+#### Scenario: Skills delivery for none command surface
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
+- **AND** delivery is set to `skills`
+- **THEN** the system SHALL perform no command-surface artifact action for that tool
+- **AND** MAY emit a compatibility note indicating no command surface is available
+
+#### Scenario: Commands delivery for adapter-backed tool
+- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL generate command files for active workflows using that adapter
+- **AND** the system SHALL remove managed skill directories for that tool
+
+#### Scenario: Commands delivery for skills-invocable tool
+- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
+- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
+- **AND** the system SHALL NOT require a command adapter for that tool
+
+#### Scenario: Commands delivery for mixed tool selection
+- **WHEN** user runs `openspec init` with multiple tools
+- **AND** selected tools include both adapter-backed and skills-invocable command surfaces
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL apply commands-only behavior per tool capability
+- **AND** the resulting install SHALL include command files for adapter-backed tools and skills for skills-invocable tools
+
+#### Scenario: Commands delivery for unsupported command surface
+- **WHEN** user runs `openspec init` with a selected tool that has no command surface capability
+- **AND** delivery is set to `commands`
+- **THEN** the system SHALL fail before generating or deleting artifacts
+- **AND** the error SHALL list incompatible tool IDs and explain supported alternatives (`both` or `skills`)
+
+#### Scenario: Interactive handling for unsupported command surface
+- **WHEN** user runs `openspec init` interactively
+- **AND** delivery is set to `commands`
+- **AND** selected tools include one or more tools with command surface `none`
+- **THEN** the CLI SHALL show a compatibility error and return to the interactive selection flow for correction
+- **AND** SHALL not perform artifact writes until a valid selection is confirmed
+
+### Requirement: Init compatibility signaling
+The init command SHALL clearly signal command-surface compatibility outcomes in both interactive and non-interactive flows.
+
+#### Scenario: Interactive compatibility note
+- **WHEN** init runs interactively
+- **AND** delivery is `commands`
+- **AND** selected tools include skills-invocable command surfaces
+- **THEN** the system SHALL display a compatibility note before the confirmation prompt indicating those tools will use skills as their command surface
+
+#### Scenario: Non-interactive compatibility summary for skills-invocable tools
+- **WHEN** init runs non-interactively (including `--tools` usage)
+- **AND** delivery is `commands`
+- **AND** selected tools include one or more `skills-invocable` command surfaces
+- **THEN** the command SHALL proceed with exit code 0
+- **AND** the command SHALL write deterministic compatibility summary lines to stdout indicating those tools will use managed skills as their command surface
+
+#### Scenario: Non-interactive compatibility failure
+- **WHEN** init runs non-interactively (including `--tools` usage)
+- **AND** delivery is `commands`
+- **AND** selected tools include any tool with no command surface capability
+- **THEN** the command SHALL exit with code 1
+- **AND** the command SHALL write deterministic, actionable guidance for resolving the selection to stderr

openspec/changes/add-tool-command-surface-capabilities/specs/cli-update/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: Delivery sync by command surface capability
+The update command SHALL synchronize artifacts using each configured tool's command surface capability.
+
+#### Scenario: Commands delivery for adapter-backed configured tool
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has an adapter-backed command surface
+- **THEN** the system SHALL generate or refresh command files for active workflows
+- **AND** the system SHALL remove managed skill directories for that tool
+
+#### Scenario: Commands delivery for skills-invocable configured tool
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has `skills-invocable` command surface capability
+- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
+- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
+- **AND** the system SHALL NOT attempt to require adapter-generated command files for that tool
+
+#### Scenario: Commands delivery with unsupported command surface
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a configured tool has no command surface capability
+- **THEN** the system SHALL fail with exit code 1 before applying partial updates
+- **AND** the output SHALL identify incompatible tools and recommended remediation
+
+### Requirement: Configured-tool detection for skills-invocable command surfaces
+The update command SHALL treat tools with skills-invocable command surfaces as configured when managed skill artifacts are present, including under commands delivery.
+
+#### Scenario: Skills-invocable tool under commands delivery
+- **WHEN** user runs `openspec update`
+- **AND** delivery is set to `commands`
+- **AND** a tool has no adapter-generated command files
+- **AND** that tool is marked `skills-invocable` and has managed skills installed
+- **THEN** the system SHALL include the tool in configured-tool detection
+- **AND** the system SHALL apply normal version/profile/delivery sync to that tool
+
+### Requirement: Update summary reflects effective per-tool delivery
+The update command SHALL report effective artifact behavior when delivery intent and artifact type differ due to tool capability.
+
+#### Scenario: Summary for skills-invocable tools in commands delivery
+- **WHEN** update completes successfully
+- **AND** delivery is `commands`
+- **AND** at least one updated tool is `skills-invocable`
+- **THEN** output SHALL include a clear note that those tools use skills as their command surface
+- **AND** output SHALL avoid implying that command generation was skipped due to an error
+

openspec/changes/add-tool-command-surface-capabilities/tasks.md

@@ -0,0 +1,53 @@
+## 0. Stacking Coordination
+
+- [ ] 0.1 Rebase this change on latest `main` before implementation
+- [ ] 0.2 If `simplify-skill-installation` is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement
+- [ ] 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket "commands = remove all skills" rule
+- [ ] 0.4 If `add-global-install-scope` is merged, verify combined scope × delivery × command-surface behavior remains deterministic
+
+## 1. Tool Command-Surface Capability Model
+
+- [ ] 1.1 Extend tool metadata in `src/core/config.ts` with an optional command-surface capability field
+- [ ] 1.2 Define supported capability values: `adapter`, `skills-invocable`, `none`
+- [ ] 1.3 Mark known skills-invocable tools such as ForgeCode, Kimi CLI, and Mistral Vibe as `skills-invocable`
+- [ ] 1.4 Add a shared capability resolver (explicit metadata override first, inferred fallback from adapter presence second)
+- [ ] 1.5 Add focused unit tests for capability resolution (explicit override, inferred adapter, inferred none)
+
+## 2. Init: Capability-Aware Delivery Planning
+
+- [ ] 2.1 Refactor init generation logic to compute per-tool effective actions (generate/remove skills and commands) instead of using only global booleans
+- [ ] 2.2 In `delivery=commands`, keep/generate skills for `skills-invocable` tools and do not remove those managed skill directories
+- [ ] 2.3 In `delivery=commands`, fail fast before writes when any selected tool resolves to `none`
+- [ ] 2.4 Update init output to clearly report effective behavior for `skills-invocable` tools (skills used as command surface)
+- [ ] 2.5 Ensure init no longer reports "no adapter" for tools intentionally using `skills-invocable`
+- [ ] 2.6 Add/adjust init tests for `delivery=commands` + `kimi` (skills retained/generated, no adapter error), mixed tools (`claude,kimi`) with per-tool expected outputs, and deterministic failure path for unsupported command surface (`none`)
+
+## 3. Update: Capability-Aware Sync and Drift Detection
+
+- [ ] 3.1 Refactor update sync logic to apply delivery behavior per tool capability (not globally per run)
+- [ ] 3.2 In `delivery=commands`, keep/generate managed skills for `skills-invocable` tools
+- [ ] 3.3 In `delivery=commands`, fail before partial updates when configured tools include a `none` command surface
+- [ ] 3.4 Update profile/delivery drift detection to avoid perpetual drift for `skills-invocable` tools under commands delivery
+- [ ] 3.5 Ensure configured-tool detection still includes `skills-invocable` tools under commands delivery when managed skills exist
+- [ ] 3.6 Update summary output so skills-invocable behavior is reported as expected behavior (not implicit skip/error)
+- [ ] 3.7 Add/adjust update tests for `delivery=commands` + configured Kimi CLI (skills retained/generated), idempotent second update (no false drift loop), mixed configured tools (`claude` + `kimi`), and deterministic preflight failure for unsupported command surface (`none`)
+
+## 4. UX and Error Messaging
+
+- [ ] 4.1 Add interactive init compatibility note for `delivery=commands` when selected tools include `skills-invocable`
+- [ ] 4.2 Add deterministic non-interactive error text with incompatible tool IDs and suggested alternatives (`both` or `skills`)
+- [ ] 4.3 Align init and update wording so capability-related behavior/messages are consistent
+
+## 5. Documentation Updates
+
+- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for skills-invocable tools and clarify delivery interactions
+- [ ] 5.2 Update `docs/cli.md` delivery guidance to explain capability-aware behavior for `delivery=commands`
+- [ ] 5.3 Add a short troubleshooting note for "commands-only + unsupported tool" failures
+
+## 6. Verification
+
+- [ ] 6.1 Run targeted tests: `test/core/init.test.ts` and `test/core/update.test.ts`
+- [ ] 6.2 Run any new capability/unit test files added in this change
+- [ ] 6.3 Run full test suite (`pnpm test`) and resolve regressions
+- [ ] 6.4 Manual smoke check: `openspec init --tools kimi` with `delivery=commands`
+- [ ] 6.5 Manual smoke check: mixed tools (`claude,kimi`) with `delivery=commands`

openspec/changes/add-update-workflow/.openspec.yaml

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

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

@@ -0,0 +1,115 @@
+# Design: `/opsx:update` — a thin update skill
+
+## Context
+
+OPSX models a change as a small DAG of planning artifacts. Each schema declares artifacts with `requires` edges ([schemas/spec-driven/schema.yaml](../../../schemas/spec-driven/schema.yaml)); `ArtifactGraph` ([src/core/artifact-graph/graph.ts](../../../src/core/artifact-graph/graph.ts)) topologically sorts them, and `openspec status --change <id> --json` already reports, per artifact: its `status` (`done`/`ready`/`blocked`), its `outputPath`, and — via the top-level `artifactPaths` map — its `resolvedOutputPath` and `existingOutputPaths`, plus the change's `schemaName` and `isComplete`. The two path fields differ in a way that matters for a write operation: `existingOutputPaths` is the concrete files that exist on disk (for a glob artifact such as `specs/**/*.md`, the glob already expanded to real files); `resolvedOutputPath` is the change-dir-joined declared path, which for a glob artifact is still the glob (`.../specs/**/*.md`) and is therefore **not** a write target. `/opsx:update` edits the files in `existingOutputPaths`. `openspec list --json` lists changes by recency.
+
+That is everything an update skill needs. The artifacts are a handful of markdown files on disk; the agent can read them. So `/opsx:update` is built as a thin skill over the **existing** CLI, in the same shape as `continue-change.ts` (select change → `openspec status --json` → act).
+
+This proposal began larger — a reverse-dependency graph API, content digests, a baseline ledger, a `reconcile` write op, a `status --impact` selector. Review feedback ([PR #1278](https://github.com/Fission-AI/OpenSpec/pull/1278)) was that this over-builds: coding agents tend to over-complicate skills, and the feature should work off the existing `status` command with as little new code as possible. This design follows that steer.
+
+## Goals / Non-Goals
+
+**Goals**
+- A `/opsx:update` action that revises a change's existing planning artifacts and keeps them coherent with one another.
+- Drive it from the artifact set and paths the CLI already reports — zero hardcoded artifact names — so custom schemas work.
+- Edit planning artifacts only; never touch code. Confirm every edit with the user.
+- Add as little code as possible: one skill template, no changes to the graph engine, the `status` command, or the metadata schema.
+
+**Non-Goals**
+- A new top-level `openspec update*` CLI verb (name is taken; see Naming).
+- Automatic, unattended regeneration (the user always confirms).
+- Content digests, a drift/staleness signal, a baseline ledger, a `reconcile` op, or a `status --impact` selector (see "Why not the heavier machinery").
+- Regenerating *code* from updated artifacts — that is `/opsx:apply`'s job; `/opsx:update` stops at the plan and hands off.
+- Cross-change audit ([#247](https://github.com/Fission-AI/OpenSpec/issues/247) in full) — a later proposal; this change is intra-change.
+- Updating anything other than a change's planning artifacts. v1 is specific to change proposals; generalizing "update" to other graph types is deferred until such a graph exists (see Naming).
+
+## The skill, written by hand
+
+Working backwards from "what is the minimal instruction set," here is the skill body in sketch form. It is short on purpose — few tokens, few commands:
+
+```
+Revise a change's planning artifacts and keep them coherent. Never edit code.
+
+1. Resolve the change.
+   - If named, use it. Else infer from context; if unclear, run `openspec list --json`
+     and ask the user to choose (most-recently-modified first). Never auto-select.
+
+2. Get the artifacts.
+   - Run `openspec status --change "<id>" --json`.
+   - Read `artifacts[]` (ids + status) and the `artifactPaths` map. These come from the
+     active schema — do not assume the artifact ids or paths.
+   - The files to edit are `artifactPaths.<id>.existingOutputPaths` (already glob-expanded
+     for artifacts like `specs/**/*.md`). Do not write to `resolvedOutputPath`: for a glob
+     artifact it is still the glob pattern, not a real file.
+
+3. Understand the request.
+   - If the user named a change ("the design now uses X"), that is the starting edit.
+   - If they only said "update" / "make this coherent," treat it as a coherence review.
+
+4. Read and reconcile.
+   - Read the artifact(s) the request touches and the other existing artifacts in the change.
+   - Apply the requested edit. Then check every other existing artifact against it — in any
+     direction (an edit to design may require revising the proposal, not only the tasks) —
+     and note what is now inconsistent, missing, or contradictory.
+   - Do not invent artifacts that don't exist yet; point the user to `/opsx:continue` to create them.
+
+5. Confirm and apply, one artifact at a time.
+   - Show each proposed revision and why. Write only after the user confirms.
+   - When a substantial rewrite is needed, `openspec instructions <artifact> --change "<id>" --json`
+     gives that artifact's rules/template to follow.
+
+6. Point to the next step (guidance only — never act on it).
+   - Artifacts still missing → suggest `/opsx:continue`. Change already implemented (tasks
+     checked off / applied) → the code may no longer match the revised plan; suggest
+     `/opsx:apply` to carry the delta. Fully done and implemented → suggest `/opsx:archive`.
+
+Guardrails:
+- Planning artifacts only. If the plan now implies code changes, stop and point to `/opsx:apply`.
+- Use artifact ids/paths from `openspec status`; never branch on literal proposal/specs/design/tasks names.
+- If the request changes the change's *intent* rather than refining it, recommend `/opsx:new`
+  (the "Update vs. Start Fresh" heuristic, docs/opsx.md).
+```
+
+The `spec-driven` artifact names may appear once, as a worked *example* of how to apply step 4, exactly as `continue-change.ts` does today — but the control flow reads ids from the CLI, so the skill never branches on those names. A template test asserts there is no name-based branching (the anti-[#777](https://github.com/Fission-AI/OpenSpec/issues/777) guard).
+
+## Decisions
+
+### 1. Bidirectional coherence, not downstream propagation
+The artifact graph has a build *order*, but "what needs updating after an edit" is not strictly downstream. If `design` changes, the `proposal` it elaborates may need to change too; if `tasks` reveal a missing capability, the `specs` may need a new requirement. The skill therefore reads the change's artifacts and reconciles them in whatever direction the edit demands. Build order is still useful as a default *reading* order and for presenting fixes, but it is not a constraint on which artifacts may be revised. This is why the design does not add a one-directional `getDownstream` / `--impact` primitive: it would encode the wrong model.
+
+### 2. Lean on the existing `status` command
+`openspec status --change <id> --json` already returns the artifact set, per-artifact status, and, in the `artifactPaths` map, the on-disk paths. The skill writes to `artifactPaths.<id>.existingOutputPaths` — the concrete files, glob-expanded — and deliberately not to `resolvedOutputPath`, which for a glob artifact is the pattern itself and not a file. That is everything the skill needs to know what exists and where it lives; no new CLI field is required. Picking the change reuses `openspec list --json`, exactly like `/opsx:continue`. No new CLI surface is introduced.
+
+### 3. Why not the heavier machinery (digests, ledger, reconcile, impact)
+The first draft proposed SHA-256 content digests, a per-change baseline ledger in `.openspec.yaml`, an `openspec reconcile` write op, a derived drift signal, and a `status --impact` selector — so the CLI could tell the agent *which* artifacts are stale without the agent reading them.
+
+Rejected for v1, because the cost outweighs the need:
+- The artifacts are a few markdown files. An agent that is going to *rewrite* them must read them anyway, so computing staleness for it saves little and adds a stateful subsystem (a ledger that `status` must not mutate, a separate write verb, scheme-versioning for forward-compat, cross-platform digest canonicalization, and the round-trip tests for all of it).
+- A digest/ledger only earns its keep when something must judge staleness *without* reading content — e.g. unattended drift detection across many changes ([#247](https://github.com/Fission-AI/OpenSpec/issues/247) cross-change, [#846](https://github.com/Fission-AI/OpenSpec/issues/846) tracking files). Those are out of scope here. When one of them becomes concrete, this machinery can be designed against that real need.
+
+So `/opsx:update` v1 has the agent read the change's artifacts and judge coherence directly. If, after using it, a deterministic signal proves necessary, the smallest first step is to expose the schema's `requires` edges on `status --json` (a single additive field, no new command) — and only then consider digests.
+
+### 4. Naming: `/opsx:update` skill, not `openspec update` CLI
+`openspec update [path]` already regenerates AI tool/skill files ([src/cli/index.ts](../../../src/cli/index.ts)). Overloading it would give one verb two unrelated meanings. The artifact-update action is therefore the **skill** `/opsx:update`, with no new `openspec` verb at all. Considered and rejected: `openspec regen --from <artifact>` ([#705](https://github.com/Fission-AI/OpenSpec/issues/705)) — a mutating CLI verb that rewrites artifacts duplicates the skill's job and bypasses user confirmation; the value is in the agent's semantic revision, not a CLI rewrite.
+
+Review feedback flagged that "update" alone is generic — could it apply to any graph? The resolution: the skill is scoped to **change proposals only**, and the specific name carries that scope. The skill is `openspec-update-change`, following the `openspec-<verb>-change` naming of its siblings (`openspec-continue-change`, `openspec-new-change`, …). The command is `/opsx:update` because every verb in the `/opsx:` family operates on a change (`continue`, `apply`, `archive` — none says `-change`); a change-scoped meaning is what the namespace already promises. If a future graph type needs its own update action, it gets its own specific skill name then — nothing here blocks or breaks that.
+
+### 5. Guardrails (the part that makes it the requested command)
+- **Planning artifacts only.** The skill's write targets are the artifact paths from `status`; if a revision implies code changes it stops and points to `/opsx:apply`. This directly answers [#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)'s complaint that the manual workaround edits code.
+- **Schema-driven.** Ids and paths come from `status`; no branching on literal `proposal`/`specs`/`design`/`tasks`. Works for custom schemas ([#777](https://github.com/Fission-AI/OpenSpec/issues/777), [#666](https://github.com/Fission-AI/OpenSpec/issues/666)).
+- **Confirm each edit.** One artifact at a time, shown before writing.
+- **Intent guard.** A revision that changes intent rather than refining it is redirected to `/opsx:new` (the "Update vs. Start Fresh" heuristic, [docs/opsx.md](../../../docs/opsx.md)).
+
+### 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.
+
+## 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).
+- **Coherence quality depends on the agent.** Mitigated by confirming every edit and by keeping scope to one change's artifacts (a small, readable set).
+- **Skill drifts back to hardcoding artifact names.** Mitigated by a template test asserting the control flow reads ids from `status` JSON and contains no name-based branching.
+
+## Migration Plan
+
+Additive and backward-compatible. One new skill template, installed with the default `core` profile (maintainer call on the PR: update is part of the default happy path, not expanded-only); one docs row. No existing command changes behavior; no schema or graph changes. The superseded stub (`add-artifact-regeneration-support`) is removed or folded in the same PR to avoid two competing proposals in the tree.

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

@@ -0,0 +1,66 @@
+## Why
+
+OPSX names **four** first-class actions — "create, implement, **update**, archive — do any of them anytime" ([docs/opsx.md:52](../../../docs/opsx.md)). Three ship as commands. **`update` does not exist.** The only mechanism offered is *"edit the files manually"* — and when you edit one artifact, nothing helps you keep the rest of the change coherent. Worse, the manual workaround lets the agent edit **code** when the user only wanted to revise the **plan** ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)).
+
+This is the most-requested missing capability in the tracker. It is one gap with several faces, and the fix is small: a thin `/opsx:update` skill that revises a change's planning artifacts and keeps them coherent with each other, built on the **existing** `openspec status` / `openspec list` commands. No new graph engine, no digests, no ledger — just an agent that reads the change's artifacts and updates what needs updating, with the user's confirmation.
+
+## What Changes
+
+The whole feature is a single new workflow skill, `/opsx:update`. The skill is deliberately change-scoped — `openspec-update-change`, following the `openspec-<verb>-change` naming of its siblings — and applies to change proposals only, not arbitrary artifact graphs (see design, Naming). Written by hand, its instruction set is short:
+
+1. **Understand the request** — what the user wants to revise (or, with no specific ask, "review this change for coherence").
+2. **Get the artifacts** — run `openspec status --change <id> --json`. Its `artifactPaths` map reports, per artifact, which files exist and where: `existingOutputPaths` is the concrete file list to edit — already expanded for glob artifacts like `specs/**/*.md`. (`openspec list --json` to pick the change when it isn't given.)
+3. **Read and revise** — read the relevant artifacts, make the requested edit, then check the change's **other** artifacts against it and propose any follow-on edits needed to keep the plan coherent.
+4. **Confirm and apply** — show each proposed revision, write only after the user confirms.
+5. **Point to the next step** — report where the change now stands and recommend what comes next: artifacts still missing → `/opsx:continue`; plan revised after the change was already implemented → `/opsx:apply` to carry the delta into code; everything done and implemented → `/opsx:archive`. Guidance only — the skill never acts on it.
+
+Two guardrails make it the command the cluster asked for:
+
+- **Planning artifacts only, never code.** If a revised plan implies code changes, it hands off to `/opsx:apply` ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)).
+- **Schema-driven, not name-driven.** Artifact ids and paths come from `openspec status`, so the skill works for custom schemas, not just the default `proposal → specs → design → tasks` ([#777](https://github.com/Fission-AI/OpenSpec/issues/777), [#666](https://github.com/Fission-AI/OpenSpec/issues/666)).
+
+**Coherence is bidirectional.** Earlier framing treated update as strictly "downstream" propagation. That is wrong: in `proposal → specs → design → tasks`, editing `design` can require revising `proposal` too. The skill reads the change's artifacts and reconciles them in whatever direction the edit demands, rather than assuming a fixed flow.
+
+### Deliberately not built (yet)
+
+Per the steer to introduce as little code as possible, and only when there is a defined need, this change does **not** add: a reverse-dependency graph API, content digests / staleness signals, a `.openspec.yaml` baseline ledger, an `openspec reconcile` write op, a drift report, or a `status --impact` selector. The agent reads the change's artifacts directly — a handful of markdown files — which is enough to judge coherence. If a future, concrete need emerges (e.g. unattended drift detection across many changes), exposing the schema's `requires` edges on `openspec status --json` is a one-field additive follow-up. It is out of scope here.
+
+## Capabilities
+
+### New Capabilities
+
+- `opsx-update-skill`: A new `/opsx:update` workflow skill that revises a change's existing planning artifacts and keeps them coherent with one another. It reads the artifact set and paths from `openspec status`, reviews related artifacts in any direction (not only downstream), edits planning artifacts only and never code, and confirms each edit with the user. It ends with next-step guidance — recommending `/opsx:continue`, `/opsx:apply`, or `/opsx:archive` based on the change's state — without acting on it.
+
+## Impact
+
+- `src/core/templates/workflows/update-change.ts` (**new**) — the `openspec-update-change` skill template and the `/opsx:update` command template, mirroring the structure of `continue-change.ts`. Reads artifact ids and paths from `openspec status --json`; embeds no artifact-name patterns.
+- Skill/command registration + [src/core/profiles.ts](../../../src/core/profiles.ts) — add `update` to `ALL_WORKFLOWS` **and to the default `core` profile** (`propose`, `explore`, `apply`, `sync`, `archive`), so `/opsx:update` is part of the default install rather than expanded-only (maintainer call on the PR).
+- `docs/opsx.md` — add a `/opsx:update` row to the command table and a short "Updating a change" usage note.
+- `openspec/changes/add-artifact-regeneration-support/` — the in-repo proposal-only stub for this gap is superseded; retire it or fold its notes into design.
+- No changes to `src/core/artifact-graph/*`, `src/commands/workflow/status.ts`, or `ChangeMetadataSchema`. The skill uses `openspec status` / `openspec list` as they exist today.
+
+## Issues addressed
+
+Verified against `Fission-AI/OpenSpec` on 2026-06-30.
+
+Closes (the missing-update-action family):
+
+- [#1188](https://github.com/Fission-AI/OpenSpec/issues/1188) — "Add a command to update proposal, design and task" (and stop it editing code). Delivered as `/opsx:update`, planning-artifacts-only.
+- [#705](https://github.com/Fission-AI/OpenSpec/issues/705) — "Rebuild downstream artifacts from a modified upstream." Delivered as the skill's read-and-reconcile pass over the change's artifacts.
+- [#673](https://github.com/Fission-AI/OpenSpec/issues/673) — "clarify": update existing artifacts without auto-advancing the build frontier. `/opsx:update` revises in place and never creates the next artifact.
+- [#247](https://github.com/Fission-AI/OpenSpec/issues/247) — "review and update all change proposals." Delivered as the within-a-change coherence review; cross-change audit is a separate, later proposal.
+
+Answers (questions whose honest answer today is "no command exists"):
+
+- [#694](https://github.com/Fission-AI/OpenSpec/issues/694), [#684](https://github.com/Fission-AI/OpenSpec/issues/684), [#618](https://github.com/Fission-AI/OpenSpec/issues/618) — "which command regenerates a document after the flow progressed / after apply?" → `/opsx:update`.
+- Discussion [#1206](https://github.com/Fission-AI/OpenSpec/discussions/1206) — the official answer becomes `/opsx:update`.
+
+Supersedes:
+
+- `openspec/changes/add-artifact-regeneration-support` (in-repo, proposal-only stub) — same problem, replaced by this skill. Its hardcoded-filename dependency tracking and metadata-file staleness mechanism are dropped in favor of letting the agent read the artifacts.
+
+Delineated from adjacent commands (distinct surfaces — coordinate, don't collide):
+
+- [#702](https://github.com/Fission-AI/OpenSpec/pull/702) `/opsx:clarify` — resolves ambiguity *within one artifact* via Q&A; a complementary upstream step. `/opsx:update` then reconciles the change's artifacts with each other.
+- [#1251](https://github.com/Fission-AI/OpenSpec/pull/1251) `/opsx:review`, [#880](https://github.com/Fission-AI/OpenSpec/issues/880) — review the *implementation (code)* against the plan. `/opsx:update` is the mirror image: it keeps the *plan* coherent and never touches code.
+- [#783](https://github.com/Fission-AI/OpenSpec/issues/783) — cross-artifact quality review. The skill's coherence pass is the lightweight form of this; a deterministic `validate`-side check is a separate proposal.

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

@@ -0,0 +1,138 @@
+## ADDED Requirements
+
+### Requirement: Update Workflow Command
+
+The system SHALL provide a `/opsx:update` workflow skill that revises a change's existing planning artifacts in place. It SHALL NOT advance the build frontier (it does not create a not-yet-started artifact) and SHALL edit planning artifacts only, never implementation code.
+
+#### Scenario: Select the change to update
+
+- **WHEN** the user invokes `/opsx:update` without a change name
+- **THEN** the skill infers the change from conversation context if possible
+- **AND** if it cannot, it lists available changes (most-recently-modified first) via `openspec list --json` and asks the user to choose, never auto-selecting
+
+#### Scenario: Revise without advancing the frontier
+
+- **WHEN** the user asks `/opsx:update` to revise an existing artifact
+- **THEN** the skill updates that artifact and reconciles the change's other existing artifacts with it
+- **AND** it does NOT create any artifact that does not yet exist (that remains the job of `/opsx:continue`/`/opsx:propose`)
+
+#### Scenario: Missing artifacts are deferred to continue
+
+- **WHEN** keeping the change coherent would require an artifact that has not been created yet
+- **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
+
+#### Scenario: Update stays within the plan
+
+- **WHEN** revising artifacts would imply changes to implementation code
+- **THEN** the skill updates the planning artifacts only
+- **AND** it directs the user to `/opsx:apply` to carry the revised plan into code, rather than editing code itself
+
+### Requirement: Schema-Driven Artifact Resolution
+
+The `/opsx:update` skill SHALL learn which artifacts exist and where they live by reading the change's status from the CLI, and SHALL NOT rely on hardcoded artifact names or assumed path separators. This makes the skill correct for custom schemas and on every platform, not only the default `spec-driven` schema.
+
+#### Scenario: Reads the artifact set from status
+
+- **WHEN** the skill needs to know which artifacts a change has and where they are
+- **THEN** it runs `openspec status --change <id> --json` and uses the reported artifact ids, statuses, and the `artifactPaths` map (`existingOutputPaths` for the files to edit)
+- **AND** it does not assume the artifact ids or output paths
+
+#### Scenario: Does not branch on hardcoded artifact names
+
+- **WHEN** the skill decides which artifacts to read and revise
+- **THEN** its control flow uses the ids reported by the CLI
+- **AND** it does not branch on literal `proposal`/`specs`/`design`/`tasks` names
+
+#### Scenario: Works for a custom schema
+
+- **WHEN** the active change uses a custom schema whose artifact ids are not `proposal`/`specs`/`design`/`tasks`
+- **THEN** the skill uses the artifact ids and paths reported by the CLI
+- **AND** it works without any change to the skill
+
+#### Scenario: Resolve artifact paths cross-platform
+
+- **WHEN** the skill reads or writes an artifact on macOS, Linux, or Windows
+- **THEN** it uses the `existingOutputPaths` provided by the CLI status output
+- **AND** it does not assume forward-slash separators
+
+#### Scenario: Edit the concrete files of a glob artifact
+
+- **WHEN** an artifact's declared output path is a glob (for example `specs/**/*.md`)
+- **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
+
+- **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
+
+### Requirement: Bidirectional Coherence Review
+
+The `/opsx:update` skill SHALL keep a change's existing planning artifacts coherent with one another after a revision, reviewing affected artifacts in any direction rather than assuming a fixed downstream flow.
+
+#### Scenario: Reconcile related artifacts after an edit
+
+- **WHEN** the user revises one artifact
+- **THEN** the skill reviews the change's other existing artifacts against the revision
+- **AND** it proposes follow-on edits to any artifact that is now inconsistent, whether that artifact is upstream or downstream of the edited one
+
+#### Scenario: Upstream artifact may be revised
+
+- **WHEN** an edit to a later artifact (for example design) contradicts an earlier one (for example the proposal)
+- **THEN** the skill may propose revising the earlier artifact to restore coherence
+- **AND** it does not treat propagation as downstream-only
+
+#### Scenario: Coherence review with no specific edit
+
+- **WHEN** the user invokes `/opsx:update` without a specific revision in mind ("make this change coherent")
+- **THEN** the skill reads the change's existing artifacts and reviews them against each other for contradictions, gaps, and duplication
+- **AND** it presents any findings for the user to confirm before editing
+
+#### Scenario: Coherent change yields no changes
+
+- **WHEN** the skill finds the change's artifacts already coherent
+- **THEN** it reports the change as coherent and makes no edits
+
+### Requirement: Next-Step Guidance
+
+After applying confirmed revisions (or finding none needed), the `/opsx:update` skill SHALL report where the change stands and recommend the next command, without acting on the recommendation itself.
+
+#### Scenario: Updating an already-implemented change
+
+- **WHEN** the user updates a change whose implementation already happened (for example tasks are checked off or `/opsx:apply` was already run)
+- **THEN** the skill still revises planning artifacts only
+- **AND** it notes that the implementation may no longer match the revised plan and recommends `/opsx:apply` to carry the delta into code
+- **AND** it does not implement anything itself
+
+#### Scenario: Next step when artifacts are incomplete
+
+- **WHEN** the update finishes and the change still has not-yet-created artifacts
+- **THEN** the skill recommends `/opsx:continue` to create them
+
+#### Scenario: Next step when the change is fully done
+
+- **WHEN** the update finishes and the change's artifacts are complete and already implemented
+- **THEN** the skill recommends `/opsx:archive`
+
+### Requirement: User-Confirmed Incremental Application
+
+The `/opsx:update` skill SHALL propose each artifact revision and apply it only after user confirmation.
+
+#### Scenario: Confirm before writing
+
+- **WHEN** the skill has a proposed revision for an artifact
+- **THEN** it shows the user what it intends to change and why before writing
+- **AND** it writes only after the user confirms
+
+#### Scenario: Rejected revision is not written
+
+- **WHEN** the user rejects a proposed revision for an artifact
+- **THEN** the skill does not write that revision
+- **AND** the artifact is left unchanged
+
+#### Scenario: Intent change is redirected to a new change
+
+- **WHEN** the requested revision changes the intent of the change rather than refining it (per the "Update vs. Start Fresh" heuristic)
+- **THEN** the skill recommends starting a new change (`/opsx:new`) instead of mutating the existing proposal into different work

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

@@ -0,0 +1,30 @@
+# Tasks: `/opsx:update` — a thin update skill
+
+> The whole feature is one new skill template over the existing `openspec status` / `openspec list` commands. No changes to the graph engine, the `status` command, or the metadata schema.
+
+## 1. The `/opsx:update` skill
+
+- [x] 1.1 Create `src/core/templates/workflows/update-change.ts` with `getUpdateChangeSkillTemplate()` (skill) and `getOpsxUpdateCommandTemplate()` (command), mirroring `continue-change.ts`. The skill name is `openspec-update-change` — change-scoped, per the `openspec-<verb>-change` convention (see design, Naming).
+- [x] 1.2 Instruction body (see design "The skill, written by hand"): resolve the change (infer / `openspec list --json` / ask) → `openspec status --change <id> --json` → read the relevant artifacts → apply the requested edit → reconcile the change's other existing artifacts in any direction → confirm and apply one artifact at a time → end with next-step guidance (`/opsx:continue` / `/opsx:apply` / `/opsx:archive` based on the change's state; see design Decision 6), never acting on it. Read artifact ids from the status JSON only, and write to `artifactPaths.<id>.existingOutputPaths` (never to a glob `resolvedOutputPath`).
+- [x] 1.3 Encode the guardrails: (a) planning artifacts only — never edit code, hand off to `/opsx:apply`; (b) schema-driven — no branching on literal `proposal`/`specs`/`design`/`tasks`; ids/paths come from `openspec status`; (c) revise only existing files (`existingOutputPaths`) — defer not-yet-created artifacts, and new files under a glob artifact, to `/opsx:continue`; (d) intent change → recommend `/opsx:new` (the "Update vs. Start Fresh" heuristic in `docs/opsx.md`).
+- [x] 1.4 Register the skill/command and add `update` to `ALL_WORKFLOWS` **and the default `core` profile** in `src/core/profiles.ts` (maintainer call: default install, not expanded-only).
+
+## 2. Docs & supersede the stub
+
+- [x] 2.1 Add a `/opsx:update` row to the command table in `docs/opsx.md`, plus a short "Updating a change" usage note.
+- [x] 2.2 Remove (or fold) `openspec/changes/add-artifact-regeneration-support/` so the tree has a single update proposal.
+- [x] 2.3 Update any generated-skill manifests/fixtures that enumerate workflow skills so `openspec-update-change` is included.
+
+## 3. Tests
+
+- [x] 3.1 Template generation snapshot for the skill and command templates.
+- [x] 3.2 Assert the template's control flow contains NO hardcoded artifact-name branching (the anti-#777 guard): artifact ids must be read from `openspec status` JSON.
+- [x] 3.3 Assert the template instructs planning-artifacts-only with a hand-off to `/opsx:apply` for code, and never advances the build frontier.
+- [x] 3.4 Assert the template instructs writing to `existingOutputPaths` (the glob-expanded concrete files) and not to a glob `resolvedOutputPath`.
+- [x] 3.5 Assert the template ends with next-step guidance (`/opsx:continue`/`/opsx:apply`/`/opsx:archive`) and instructs the agent never to act on it.
+- [x] 3.6 Assert `update` is included in the `core` profile's workflows (profiles test).
+
+## 4. End-to-end verification
+
+- [x] 4.1 `openspec validate add-update-workflow --strict` passes; `openspec status --change add-update-workflow` shows all artifacts complete.
+- [x] 4.2 Manual walk-through: on a `spec-driven` change, edit `design`, run `/opsx:update`, confirm it proposes coherence edits to other existing artifacts (including upstream where warranted) and never touches code.

openspec/changes/archive/2026-01-30-opencode-command-references/.openspec.yaml

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

openspec/changes/archive/2026-01-30-opencode-command-references/README.md

@@ -0,0 +1,3 @@
+# opencode-command-references
+
+Transform /opsx: to /opsx- in both commands and skills for OpenCode

openspec/changes/archive/2026-01-30-opencode-command-references/design.md

@@ -0,0 +1,70 @@
+## Context
+
+OpenCode is one of many supported AI tools. Each tool has:
+- A **command adapter** (in `src/core/command-generation/adapters/`) for generating tool-specific command files
+- **Skills** generated via `generateSkillContent()` in `src/core/shared/skill-generation.ts`
+
+Currently:
+- Commands go through the adapter system which can transform content per-tool
+- Skills use a single shared function with no tool-specific transformation
+
+The templates in `src/core/templates/skill-templates.ts` use Claude's colon-based format (`/opsx:new`) as the canonical format. Tools that use different formats need transformation at generation time.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Transform all `/opsx:` command references to `/opsx-` for OpenCode in both commands and skills
+- Create a shared, reusable transformation utility
+- Keep the transformation opt-in via a callback parameter (not hard-coded tool detection)
+
+**Non-Goals:**
+- Modifying the canonical template format (templates stay with `/opsx:`)
+- Applying transformation to other tools (only OpenCode for now)
+- Creating a full adapter system for skills (overkill for current needs)
+
+## Decisions
+
+### Decision 1: Shared Utility Function
+
+**Choice**: Create `transformToHyphenCommands()` in `src/utils/command-references.ts`
+
+**Rationale**: 
+- Single source of truth for the transformation logic
+- Can be used by both command adapter and skill generation
+- Easy to test in isolation
+- Follows existing utils pattern in the codebase
+
+**Alternatives considered**:
+- Inline the transformation in each location - Duplicates logic, harder to maintain
+
+### Decision 2: Callback Parameter for Skill Generation
+
+**Choice**: Add optional `transformInstructions?: (instructions: string) => string` parameter to `generateSkillContent()`
+
+**Rationale**:
+- Flexible - callers define the transformation, not the generation function
+- No coupling - `generateSkillContent()` doesn't need to know about tool formats
+- Extensible - could support other transformations in the future
+- Follows inversion of control principle
+
+**Alternatives considered**:
+- Add tool ID parameter and switch on it - Creates coupling, harder to extend
+- Create skill adapter system parallel to commands - Over-engineering for current needs
+- Transform in templates directly - Breaks single-source-of-truth principle
+
+### Decision 3: Apply at Generation Sites
+
+**Choice**: Pass transformer in `init.ts` and `update.ts` when `tool.value === 'opencode'`
+
+**Rationale**:
+- These are the only two places that generate skills
+- Simple conditional check, no new abstractions needed
+- Easy to extend to other tools if needed later
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| Other `/opsx:` patterns exist that shouldn't be transformed | All occurrences in templates are command invocations - verified by inspection |
+| Future tools may need same transformation | Utility is shared and easy to reuse; can add to other tools' generation |
+| Callback adds complexity to function signature | Optional parameter with sensible default (no transformation) |

openspec/changes/archive/2026-01-30-opencode-command-references/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+OpenCode uses hyphen-based command syntax (`/opsx-new`) but our templates contain colon-based references (`/opsx:new`). This creates inconsistency where generated command files and skill files contain references that don't match the actual command invocation syntax, confusing both the AI and users.
+
+## What Changes
+
+- Create a shared transformation utility (`transformToHyphenCommands`) for converting `/opsx:` to `/opsx-`
+- Update the OpenCode command adapter to transform body text using this utility
+- Add an optional `transformInstructions` callback parameter to `generateSkillContent()`
+- Update `init.ts` and `update.ts` to pass the transformer when generating skills for OpenCode
+
+## Capabilities
+
+### New Capabilities
+
+None - this is a bug fix, not a new capability.
+
+### Modified Capabilities
+
+None - no spec-level behavior changes. This is an implementation fix in the OpenCode adapter and skill generation that doesn't change any external requirements or contracts.
+
+## Impact
+
+- **Code**: 
+  - `src/utils/command-references.ts` (new file)
+  - `src/utils/index.ts` (export)
+  - `src/core/shared/skill-generation.ts` (add callback parameter)
+  - `src/core/command-generation/adapters/opencode.ts` (use transformer)
+  - `src/core/init.ts` (pass transformer for OpenCode)
+  - `src/core/update.ts` (pass transformer for OpenCode)
+- **Users**: OpenCode users will see correct `/opsx-` command references in both generated command files AND skill files
+- **Other tools**: No impact - transformation only applies to OpenCode

openspec/changes/archive/2026-01-30-opencode-command-references/specs/no-changes.md

@@ -0,0 +1,9 @@
+# No Spec Changes
+
+This is a bug fix that doesn't modify any external requirements or contracts.
+
+The proposal's Capabilities section indicates:
+- **New Capabilities**: None
+- **Modified Capabilities**: None
+
+No spec files are needed for this implementation-only fix.

openspec/changes/archive/2026-01-30-opencode-command-references/tasks.md

@@ -0,0 +1,22 @@
+## 1. Implementation
+
+- [x] 1.1 Create `src/utils/command-references.ts` with `transformToHyphenCommands()` function
+- [x] 1.2 Export `transformToHyphenCommands` from `src/utils/index.ts`
+- [x] 1.3 Update `generateSkillContent()` in `src/core/shared/skill-generation.ts` to accept optional `transformInstructions` callback
+- [x] 1.4 Update OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` to use `transformToHyphenCommands()` for body text
+- [x] 1.5 Update `init.ts` to pass transformer when generating skills for OpenCode
+- [x] 1.6 Update `update.ts` to pass transformer when generating skills for OpenCode
+
+## 2. Testing
+
+- [x] 2.1 Create `test/utils/command-references.test.ts` with unit tests for `transformToHyphenCommands()`
+- [x] 2.2 Add test to `test/core/command-generation/adapters.test.ts` for OpenCode body transformation
+- [x] 2.3 Add test to `test/core/shared/skill-generation.test.ts` for transformer callback
+
+## 3. Verification
+
+- [x] 3.1 Run `npx vitest run test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts test/core/shared/skill-generation.test.ts` to ensure tests pass
+- [x] 3.2 Run `pnpm run build` to ensure no TypeScript errors
+- [x] 3.3 Run `openspec init --tools opencode` in a temp directory and verify:
+  - Command files in `.opencode/command/` contain `/opsx-` references (not `/opsx:`)
+  - Skill files in `.opencode/skills/` contain `/opsx-` references (not `/opsx:`)

openspec/changes/archive/2026-02-17-multi-provider-skill-generation/design.md

@@ -18,7 +18,7 @@ Each AI tool has:
 - Create a generic, extensible command generation system
 
 **Non-Goals:**
-- Global path installation (deferred to future work)
+- Global path installation for tools other than Codex (Codex uses absolute adapter paths today)
 - Multi-tool generation in single command (future enhancement)
 - Unifying with existing SlashCommandConfigurator (separate systems for now)
 
@@ -41,7 +41,7 @@ interface AIToolOption {
 **Rationale**:
 - Skills follow Agent Skills spec: `<toolDir>/skills/` - suffix is standard
 - Commands need per-tool formatting, handled by adapters (not a simple path)
-- Global paths deferred - can extend interface later
+- Global paths supported — Codex adapter returns absolute paths via os.homedir()
 
 ### 2. Strategy/Adapter pattern for command generation