Version Packages (#1629)

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

.actrc

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

.agents/skills/release-openspec/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: release-openspec
+description: >-
+  Use this skill when releasing OpenSpec: audit merged work and changeset
+  coverage, decide whether a catch-up changeset PR is needed, prepare or resume
+  the Changesets Version Packages PR, cut a beta or stable release, verify
+  publishing, and polish GitHub release notes. Also use when asked whether an
+  open release PR is complete, what the next release step is, or to continue a
+  release paused for human approval.
+---
+
+# Release OpenSpec
+
+Run the OpenSpec release workflow as a resumable state machine. Inspect live GitHub state on every invocation and take only the next safe action. Do not assume an earlier invocation completed.
+
+## Principles
+
+- Treat `Fission-AI/OpenSpec` and `origin/main` as the release source of truth.
+- Default to a read-only audit when the user asks for status, readiness, or advice.
+- Treat a request to release, prepare a release, continue, or resume as authorization to perform the applicable release actions.
+- Preserve the user's checkout. Never discard unrelated changes or switch their current branch just to prepare a changeset.
+- Use a temporary worktree from current `origin/main` for release-authored commits when the checkout is dirty or not on `main`.
+- Never approve your own PR. Human review is a deliberate gate.
+- Treat merge-queue entry as an intermediate state, not a merge. Advance only after GitHub reports `mergedAt` and the commit is present on `main`.
+- Never create the automated Version Packages PR manually. The Changesets action owns it.
+- Never push an empty commit merely to retrigger CI. Diagnose the failed or missing run first.
+- Report URLs, the state reached, and the exact human action needed whenever pausing.
+
+## Know the two PR types
+
+Keep these distinct in output and decisions:
+
+- **Changeset PR**: A normal human-authored PR that adds one or more `.changeset/*.md` files. Prefer adding a changeset to the feature/fix PR; create a catch-up changeset PR only for already-merged work that should be included.
+- **Version Packages PR**: The automated `changeset-release/main` PR titled `chore(release): version packages`. Merging or adding changesets to `main` updates this same PR. Merging it publishes the stable release.
+
+An open Version Packages PR does not prohibit a catch-up changeset PR. It means a catch-up PR is useful only when the audit finds missing release-worthy work. Once that PR merges, wait for the existing Version Packages PR to update.
+
+## Start with a release audit
+
+1. Verify the repository and tools:
+   - Resolve the GitHub repository with `gh repo view --json nameWithOwner,url`.
+   - Require authenticated `gh`, `git`, and `pnpm` before write actions.
+   - Stop before release mutations if the canonical repository is not `Fission-AI/OpenSpec`.
+2. Refresh without modifying the worktree:
+
+   ```bash
+   git fetch origin main
+   ```
+
+   Do not fetch every tag indiscriminately. This repository may contain a conflicting historical local tag, which can make `git fetch --tags` fail even though `origin/main` fetched successfully.
+
+3. Find the latest stable GitHub release. Exclude drafts and prereleases; do not use `git describe`, because a beta tag may be newer than the stable baseline.
+
+   ```bash
+   gh release list --repo Fission-AI/OpenSpec \
+     --exclude-drafts --exclude-pre-releases --limit 100 \
+     --json tagName,publishedAt \
+     --jq 'max_by(.publishedAt) | {tagName, publishedAt}'
+   ```
+
+   Ensure that exact stable tag resolves locally before using it as a `git log` boundary. Fetch only that tag if it is missing. If a same-named local tag disagrees with the canonical remote, report the mismatch and use a separately resolved canonical commit; never force-rewrite the user's tag as part of an audit.
+
+4. Find open release-related PRs:
+
+   ```bash
+   gh pr list --repo Fission-AI/OpenSpec --state open \
+     --head changeset-release/main \
+     --json number,title,headRefName,baseRefName,url,reviewDecision,statusCheckRollup
+   ```
+
+   Identify the Version Packages PR by `headRefName == "changeset-release/main"`, not title alone. Separately list likely changeset PRs and inspect their files; require positive additions to `.changeset/*.md`. Do not mistake the Version Packages PR's changeset deletions for authored changesets, and do not rely on titles because a feature/fix PR may add release tracking.
+5. Read the live release policy in `.changeset/README.md`, pending `.changeset/*.md` files on `origin/main`, and the Version Packages PR body/files when it exists.
+6. List first-parent commits since the latest stable tag:
+
+   ```bash
+   git log --first-parent --date=short \
+     --pretty=format:'%h%x09%ad%x09%s' <stable-tag>..origin/main
+   ```
+
+7. Map release-worthy merged PRs to existing changesets. Use PR files and changeset history; do not infer coverage from similar wording alone.
+8. Classify the audit as:
+   - `missing-tracking`: user-facing work intended for this release lacks a changeset;
+   - `awaiting-changeset-review`: a suitable changeset PR already exists;
+   - `awaiting-merge-queue`: an approved changeset or Version Packages PR is queued but has not landed on `main`;
+   - `awaiting-version-update`: required changesets are on `main`, but the Version Packages PR has not incorporated them;
+   - `awaiting-version-review`: the Version Packages PR is current but lacks approval;
+   - `ready-to-publish`: the Version Packages PR is current, approved, and green;
+   - `publishing`: the Version Packages PR merged but artifacts are incomplete;
+   - `needs-finalization`: npm, tag, and GitHub Release exist but notes are still raw;
+   - `complete`: package, tag, GitHub Release, and polished notes agree.
+
+Present a compact audit with the stable baseline, proposed version, covered changes, possible omissions, intentionally skipped internal/docs work, open PRs, and next action.
+
+## Decide changeset coverage
+
+Follow `.changeset/README.md` rather than assuming every merged PR needs a changeset.
+
+Include work selected for release tracking, especially:
+
+- new user-facing features or commands;
+- notable fixes or hotfixes;
+- breaking changes or deprecations;
+- user-visible performance improvements.
+
+Normally skip documentation-only work, tests, CI/tooling, and internal refactors. Flag ambiguous user-visible changes instead of silently excluding them. Ask the user only when the ambiguity materially changes release scope or the semantic version; otherwise use best judgment and let PR review be the approval gate.
+
+## Create or continue a changeset PR
+
+Do this only for `missing-tracking`.
+
+1. If an open changeset PR already covers the missing work, reuse it. Inspect its `headRefName`, head repository, and `maintainerCanModify`; fetch that exact head branch from its owning repository into a temporary worktree, make the update there, and push back to the same PR head. Stop if the branch is not writable. Do not create a duplicate PR or replacement branch.
+2. Read `.changeset/README.md` immediately before authoring.
+3. Only when no suitable PR exists, create a short `changeset-<scope>` branch from current `origin/main`. Use a temporary worktree so the operator's checkout remains untouched.
+4. Prefer one changeset per coherent release unit. A single catch-up changeset may summarize several small items selected for the same release.
+5. Use the exact package name `"@fission-ai/openspec"`, the highest required semantic bump, only relevant headings, and user-focused descriptions.
+6. Validate before pushing:
+
+   ```bash
+   pnpm exec changeset status
+   ```
+
+7. Commit, push, and open a PR whose body lists the covered merged PRs and explains why the catch-up is needed.
+8. Stop after returning the PR URL and request human approval. Do not approve it yourself.
+
+On a later invocation, if the PR is approved and checks are green, merge or enqueue it only when the user asked to continue or complete the release. If GitHub uses a merge queue, inspect `mergeQueueEntry`, queue checks, and `mergedAt`; remain in `awaiting-merge-queue` until the PR actually lands on `main`. Then wait for the Changesets action on `main` to update the existing Version Packages PR. Poll with concise progress updates; do not push an empty commit or another branch update, because that can dismiss approval and restart the queue.
+
+## Validate the Version Packages PR
+
+Before calling it ready:
+
+1. Confirm it targets `main` from `changeset-release/main` and is generated by the expected automation.
+2. Enumerate every pending `.changeset/*.md` file on current `main`, excluding `.changeset/README.md`. Verify the PR consumes every one and contains the corresponding changelog content. If any pending changeset should be deferred, stop: remove or revise it through a separately reviewed change and wait for automation to regenerate the Version Packages PR before continuing.
+3. Fetch `baseRefOid` and `headRefOid` with `gh pr view`, require `baseRefOid` to equal current `origin/main`, and create clean detached temporary worktrees for both revisions. If the head object is missing locally, fetch the immutable `pull/<number>/head` ref first. Never validate from the operator's current worktree.
+4. In the base worktree, run `pnpm exec changeset status --output changeset-status.json` and read the expected package/version from that file. Install locked dependencies in the temporary worktree first if the Changesets CLI is unavailable.
+5. Compare the base status and complete pending-changeset set against the head worktree: `package.json`, `CHANGELOG.md`, removed changeset files, PR body, and proposed version must all agree. This is a base-to-head comparison because the head has already consumed the changesets and cannot calculate the pending release itself.
+6. Remove the temporary worktrees after validation, then inspect all required checks and review state with `gh pr view` / `gh pr checks`.
+
+If current but unapproved, return the URL and pause for human approval. If approved and green, merge or enqueue only when the user asked to release or continue. With merge queue enabled, do not treat approval, auto-merge enablement, or queue entry as the stable publish trigger; wait for `mergedAt` and confirmation that the merge reached `main`.
+
+## Verify stable publishing
+
+After the Version Packages PR merges:
+
+1. Find the release workflow run for the merge commit and wait for completion.
+2. Verify all three artifacts independently:
+   - `npm view @fission-ai/openspec@<version> version`
+   - remote tag `v<version>` points at the expected commit;
+   - `gh release view v<version>` exists and is not a prerelease.
+3. If only some artifacts exist, report partial state and resume verification before retrying any publish action. Never republish a version already on npm.
+4. Once all artifacts exist, read [references/release-notes.md](references/release-notes.md), polish the GitHub Release, and verify the saved title/body.
+
+## Cut a beta
+
+Only enter this path when the user explicitly asks for a beta or prerelease.
+
+1. Run the same audit and confirm pending changesets produce a next stable version.
+2. Explain that beta publishing does not consume changesets or replace the stable Version Packages PR.
+3. Trigger the existing `release-prepare.yml` workflow on `main`; do not calculate or set the beta version locally.
+4. Verify the workflow-selected version, npm `beta` dist-tag, remote tag, and prerelease GitHub Release.
+5. Do not merge the stable Version Packages PR as part of a beta request.
+
+## Handle failures
+
+- For failed CI, inspect the failing check and logs before proposing a rerun or code change.
+- For a stale Version Packages PR, first confirm a successful `push` run of `release-prepare.yml` occurred after the latest changeset reached `main`.
+- For branch divergence, let the Changesets action update its branch. Do not force-push `changeset-release/main`.
+- For a queued PR, inspect merge-group checks and queue state. Do not re-enqueue, update the branch, or rerun unrelated checks while it is progressing normally.
+- For a version that already exists on npm, stop and reconcile the tag/GitHub Release rather than incrementing or republishing implicitly.
+- For missing GitHub permissions or required review, report the exact gate and URL; preserve the detected state so the next invocation can resume by inspection.
+
+## Completion report
+
+Report:
+
+- released version and stable/beta channel;
+- changeset PR and Version Packages PR URLs, when applicable;
+- release workflow result;
+- npm package, tag, and GitHub Release verification;
+- release-notes finalization status;
+- any intentionally deferred changes.

.agents/skills/release-openspec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release OpenSpec"
+  short_description: "Audit, prepare, publish, and finalize releases"
+  default_prompt: "Use $release-openspec to audit the current release state and take the next safe release step."

.agents/skills/release-openspec/references/release-notes.md

@@ -0,0 +1,89 @@
+# GitHub release notes
+
+Read this file only after the npm package, tag, and GitHub Release exist, or when the user explicitly asks to preview or polish release notes.
+
+## Gather source material
+
+1. Bind the release values once and fetch the current release. Replace the example values, but keep every expansion quoted:
+
+   ```bash
+   tag="vX.Y.Z"
+   previous_tag="vA.B.C"
+   gh release view "$tag" --repo Fission-AI/OpenSpec \
+     --json body,name,isPrerelease,url
+   ```
+
+2. For a stable release, find the preceding stable release by excluding drafts and prereleases. For a beta, compare against the preceding tag in the same beta series when one exists; otherwise compare against the latest stable release.
+3. Fetch GitHub-generated notes to recover first-time contributor attribution and the full changelog link:
+
+   ```bash
+   gh api repos/Fission-AI/OpenSpec/releases/generate-notes \
+     -f "tag_name=$tag" -f "previous_tag_name=$previous_tag" -q '.body'
+   ```
+
+4. Cross-check the final content against the released `CHANGELOG.md` section and the merged Version Packages PR. Never invent an item from commit titles alone.
+
+## Title
+
+Use:
+
+```text
+<tag> - <one-to-four-word theme>
+```
+
+Lead with the most notable user-facing addition. For two similarly important additions, comma-separate them. For a fix-only release, name the primary fixed area.
+
+## Body
+
+Use only the sections that contain content:
+
+```markdown
+## What's New in <tag>
+
+<One direct sentence describing the release theme.>
+
+### New
+
+- **Feature** - What users can now do and when it helps.
+
+### Improved
+
+- **Area** - What became easier, safer, faster, or more consistent.
+
+### Fixed
+
+- **Area** - What now behaves correctly.
+
+## New Contributors
+
+* @username made their first contribution in #PR
+
+**Full Changelog**: <compare-link>
+```
+
+## Voice and cleanup
+
+- Write for developers using OpenSpec with AI coding assistants.
+- Be direct and practical; avoid marketing language.
+- Lead with user capability or impact, not implementation.
+- Keep each item to one or two sentences.
+- Remove commit hashes, changeset wrappers, raw semantic-bump headings, and inline `Thanks @user` boilerplate.
+- Omit internal CI, test, and refactor details unless users experience the result.
+- Keep contribution credit in `New Contributors`, not inside feature bullets.
+- Preserve GitHub's first-contribution wording and PR link.
+- Exclude core maintainer `@TabishB` from `New Contributors`. If no external first-time contributors remain, omit that section.
+- Always retain the full changelog compare link.
+
+## Apply and verify
+
+Create a temporary file, write the body to it with the available file-editing tool, bind the final title, then update:
+
+```bash
+notes_file="$(mktemp)"
+title="$tag - Release Theme"
+# Write the polished Markdown body to "$notes_file" before continuing.
+gh release edit "$tag" --repo Fission-AI/OpenSpec \
+  --title "$title" --notes-file "$notes_file"
+```
+
+When the user asked only for a preview or audit, show the proposed title/body without editing. When the user asked to run, continue, or complete the release, apply the polished notes without an extra confirmation pause, then fetch the release again and verify the saved title/body.

.changeset/README.md

@@ -1,6 +1,97 @@
-This directory is managed by Changesets.
+# Changesets
 
-- Add a changeset locally with `pnpm changeset`.
-- The CI "Release (prepare)" workflow opens/updates a Version Packages PR.
-- Publishing happens from a GitHub Release via the "Publish to npm" workflow.
+This directory is managed by [Changesets](https://github.com/changesets/changesets).
 
+## Quick Start
+
+```bash
+pnpm changeset
+```
+
+Follow the prompts to select version bump type and describe your changes.
+
+## Workflow
+
+1. **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:** 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
+
+Use this structure for your changeset content:
+
+```markdown
+---
+"@fission-ai/openspec": patch
+---
+
+### New Features
+
+- **Feature name** — What users can now do
+
+### Bug Fixes
+
+- Fixed issue where X happened when Y
+
+### Breaking Changes
+
+- `oldMethod()` has been removed, use `newMethod()` instead
+
+### Deprecations
+
+- `legacyOption` is deprecated and will be removed in v2.0
+
+### Other
+
+- Internal refactoring of X for better performance
+```
+
+Include only the sections relevant to your change.
+
+## Version Bump Guide
+
+| Type | When to use | Example |
+|------|-------------|---------|
+| `patch` | 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
+
+**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 and that are planned for release
+
+**Use the normal release cadence for:**
+- Routine bug fixes that fit the normal release cadence
+- Documentation-only changes
+- Test additions/fixes
+- Internal refactoring that preserves user behavior
+- CI/tooling changes
+
+## Writing Good Descriptions
+
+**Do:** Write for users, not developers
+```markdown
+- **Shell completions** — Tab completion now available for Bash, Fish, and PowerShell
+```
+
+**Don't:** Write implementation details
+```markdown
+- Added ShellCompletionGenerator class with Bash/Fish/PowerShell subclasses
+```
+
+**Do:** Explain the impact
+```markdown
+- Fixed config loading to respect `XDG_CONFIG_HOME` on Linux
+```
+
+**Don't:** Just reference the fix
+```markdown
+- Fixed #123
+```

.changeset/config.json

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

.devcontainer/devcontainer.json

@@ -1,6 +1,6 @@
 {
   "name": "OpenSpec Development",
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
 
   // Additional tools and features
   "features": {

.gitattributes

@@ -0,0 +1,4 @@
+# The skills.sh distribution files are generated LF-only and compared
+# byte-for-byte by test/core/templates/skillssh-parity.test.ts. Force LF on
+# checkout so Windows autocrlf doesn't turn them into CRLF and fail parity.
+skills/** text eol=lf

.github/CODEOWNERS

@@ -1,2 +1,2 @@
 # Default code ownership
-* @TabishB
+* @Fission-AI/openspec-maintainers

.github/dependabot.yml

@@ -0,0 +1,98 @@
+version: 2
+
+# Dependabot does not manage two dependency surfaces in this repo:
+#   1. pnpm `overrides` (pnpm-workspace.yaml + package.json, root and website) —
+#      transitive version pins that remediate advisories Dependabot can't otherwise
+#      reach. It never bumps or removes these; each carries an inline advisory
+#      comment noting the removal condition (see pnpm-workspace.yaml).
+#   2. The Nix flake (flake.nix / flake.lock). Update nixpkgs manually with
+#      `nix flake update`; there is no Dependabot ecosystem for Nix. Note that the
+#      pnpmDeps FOD hash in flake.nix must be regenerated on any root lockfile change.
+
+updates:
+  # Published CLI package
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    # Let a freshly published version sit before adopting it. Security updates
+    # ignore the cooldown, so this only delays routine bumps — long enough for a
+    # compromised release to be yanked before it reaches this repo.
+    cooldown:
+      default-days: 7
+      semver-major-days: 30
+      semver-minor-days: 7
+      semver-patch-days: 3
+    open-pull-requests-limit: 5
+    ignore:
+      - dependency-name: "@types/node"
+        update-types:
+          - version-update:semver-major
+      - dependency-name: "typescript"
+        update-types:
+          - version-update:semver-major
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      production-dependencies:
+        dependency-type: production
+        update-types:
+          - minor
+          - patch
+      development-dependencies:
+        dependency-type: development
+        update-types:
+          - minor
+          - patch
+
+  # Documentation site (not published to npm)
+  - package-ecosystem: npm
+    directory: /website
+    schedule:
+      interval: weekly
+      day: monday
+    # Let a freshly published version sit before adopting it. Security updates
+    # ignore the cooldown, so this only delays routine bumps — long enough for a
+    # compromised release to be yanked before it reaches this repo.
+    cooldown:
+      default-days: 7
+      semver-major-days: 30
+      semver-minor-days: 7
+      semver-patch-days: 3
+    open-pull-requests-limit: 3
+    ignore:
+      - dependency-name: "@types/node"
+        update-types:
+          - version-update:semver-major
+      - dependency-name: "typescript"
+        update-types:
+          - version-update:semver-major
+    commit-message:
+      prefix: chore
+      include: scope
+    groups:
+      website-dependencies:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+
+  # CI workflow actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    # Actions are not semver-versioned the way packages are, so this ecosystem
+    # accepts default-days only.
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ci
+    groups:
+      github-actions:
+        patterns:
+          - "*"

.github/workflows/README.md

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

.github/workflows/ci.yml

@@ -3,6 +3,8 @@ name: CI
 on:
   pull_request:
     branches: [main]
+  merge_group:
+    branches: [main]
   push:
     branches: [main]
   workflow_dispatch:
@@ -15,50 +17,37 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  test_pr:
-    name: Test
+  # Detect which files changed to enable path-based filtering
+  changes:
+    name: Detect changes
     runs-on: ubuntu-latest
-    timeout-minutes: 10
-    if: github.event_name == 'pull_request'
-
+    outputs:
+      nix: ${{ steps.filter.outputs.nix }}
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
-          fetch-depth: 0
+          persist-credentials: false
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
+      - name: Check for Nix-related changes
+        uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4
+        id: filter
         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
+          filters: |
+            nix:
+              - 'flake.nix'
+              - 'flake.lock'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'pnpm-workspace.yaml'
+              - 'scripts/update-flake.sh'
+              - '.github/workflows/ci.yml'
 
   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:
@@ -66,12 +55,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:
@@ -79,19 +71,18 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
+          node-version: '20.19.0'
           cache: 'pnpm'
 
       - name: Print environment diagnostics
@@ -105,32 +96,48 @@ 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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         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
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          node-version: '20'
+          node-version: '20.19.0'
           cache: 'pnpm'
 
       - name: Install dependencies
@@ -156,61 +163,124 @@ jobs:
             exit 1
           fi
 
-  validate-changesets:
-    name: Validate Changesets
+  nix-flake-validate:
+    name: Nix Flake Validation
     runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
+    timeout-minutes: 10
+    needs: changes
+    if: needs.changes.outputs.nix == 'true'
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+
+      - name: Setup Nix cache
+        uses: DeterminateSystems/magic-nix-cache-action@908b263ff629f4cc17666315b7fd3ec127c6244d # v14
+
+      - name: Build with Nix
+        run: nix build
+
+      - name: Verify build output
+        run: |
+          if [ ! -e "result" ]; then
+            echo "Error: Nix build output 'result' symlink not found"
+            exit 1
+          fi
+          if [ ! -f "result/bin/openspec" ]; then
+            echo "Error: openspec binary not found in build output"
+            exit 1
+          fi
+          echo "✅ Build output verified"
+
+      - name: Test binary execution
+        run: |
+          VERSION=$(nix run . -- --version)
+          echo "OpenSpec version: $VERSION"
+          if [ -z "$VERSION" ]; then
+            echo "Error: Version command returned empty output"
+            exit 1
+          fi
+          echo "✅ Binary execution successful"
+
+      - name: Validate update script
+        run: |
+          echo "Testing update-flake.sh script..."
+          bash scripts/update-flake.sh
+          echo "✅ Update script executed successfully"
+
+      - name: Check flake.nix modifications
+        run: |
+          if git diff --quiet flake.nix; then
+            echo "ℹ️  flake.nix unchanged (hash already up-to-date)"
+          else
+            echo "✅ flake.nix was updated by script"
+            git diff flake.nix
+          fi
+
+      - name: Restore flake.nix
+        if: always()
+        run: git checkout -- flake.nix || true
+
+  validate-changesets:
+    name: Validate Release Tracking
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          persist-credentials: false
+
+      - 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
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        if: steps.changed-changesets.outputs.has_changesets == 'true'
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         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]
-    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
-          echo "All required checks passed!"
-
-  required-checks-main:
-    name: All checks passed
-    runs-on: ubuntu-latest
-    needs: [test_matrix, lint]
-    if: always() && github.event_name != 'pull_request'
+    needs: [test_matrix, lint, nix-flake-validate]
+    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
     steps:
       - name: Verify all checks passed
         run: |
@@ -222,4 +292,38 @@ jobs:
             echo "Lint job failed"
             exit 1
           fi
+          # Nix validation may be skipped if no Nix-related files changed
+          if [[ "${{ needs.nix-flake-validate.result }}" != "success" && "${{ needs.nix-flake-validate.result }}" != "skipped" ]]; then
+            echo "Nix flake validation job failed"
+            exit 1
+          fi
+          if [[ "${{ needs.nix-flake-validate.result }}" == "skipped" ]]; then
+            echo "Nix flake validation skipped (no Nix-related changes)"
+          fi
+          echo "All required checks passed!"
+
+  required-checks-main:
+    name: All checks passed
+    runs-on: ubuntu-latest
+    needs: [test_matrix, lint, nix-flake-validate]
+    if: always() && github.event_name == 'push'
+    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!"

.github/workflows/release-prepare.yml

@@ -1,12 +1,15 @@
-name: Release (prepare)
+name: Release
 
 on:
   push:
     branches: [main]
+  workflow_dispatch: # manually cut a beta prerelease from main
 
+# Floor for both jobs. The prepare job widens this to pull-requests: write for
+# the Version Packages PR; the beta job only tags/releases + publishes via OIDC
+# and needs no PR access, so it inherits this narrower default.
 permissions:
   contents: write
-  pull-requests: write
   id-token: write # Required for npm OIDC trusted publishing
 
 concurrency:
@@ -15,18 +18,31 @@ concurrency:
 
 jobs:
   prepare:
-    if: github.repository == 'Fission-AI/OpenSpec'
+    if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'push'
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write # changesets opens/updates the Version Packages PR
+      id-token: write # Required for npm OIDC trusted publishing
     steps:
-      - uses: actions/checkout@v4
+      # Generate GitHub App token first - used for checkout and changesets
+      # This allows git operations to trigger CI workflows on the version PR
+      # (GITHUB_TOKEN cannot trigger workflows by design)
+      - name: Generate GitHub App Token
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
 
-      - uses: pnpm/action-setup@v4
-        with:
-          version: 9
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '24' # Node 24 includes npm 11.5.1+ required for OIDC
           cache: 'pnpm'
@@ -36,7 +52,8 @@ jobs:
 
       # Opens/updates the Version Packages PR; publishes when the Version PR merges
       - name: Create/Update Version PR
-        uses: changesets/action@v1
+        id: changesets
+        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1
         with:
           title: 'chore(release): version packages'
           createGithubReleases: true
@@ -44,5 +61,128 @@ jobs:
           # so package.json already contains the bumped version.
           publish: pnpm run release:ci
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
           # npm authentication handled via OIDC trusted publishing (no token needed)
+
+  # 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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        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

.github/workflows/security.yml

@@ -0,0 +1,120 @@
+name: Security
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/package.json'
+      - '**/pnpm-lock.yaml'
+      - '**/pnpm-workspace.yaml'
+      - '.github/workflows/security.yml'
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly, so a newly published advisory surfaces even with no commits.
+    - cron: '17 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Blocks a pull request that introduces a vulnerable or badly licensed dependency.
+  dependency-review:
+    name: Dependency Review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # No PR comment: that needs `pull-requests: write`, which a fork's token
+      # never gets. The failed check plus its log is the signal.
+      - name: Review dependency changes
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: high
+
+  audit:
+    name: Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+
+      # No dependency cache: `pnpm audit` reads the lockfile, nothing is installed,
+      # so a cache-save step would fail on the missing store path.
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.19.0'
+
+      # Advisory on pull requests: a newly published advisory should not stop an
+      # unrelated change, and the step depends on registry availability.
+      # Blocking everywhere else — on the weekly schedule and on pushes to main
+      # — so a high-severity advisory in a shipped dependency still fails a run
+      # even when no dependency changed.
+      - name: Audit published dependencies
+        continue-on-error: ${{ github.event_name == 'pull_request' }}
+        run: pnpm audit --prod --audit-level high
+
+      # Build and test tooling never reaches an installed copy of OpenSpec, so an
+      # advisory here is a scheduled-update item.
+      - name: Audit build and test tooling
+        continue-on-error: true
+        run: pnpm audit --audit-level high
+
+      # The docs site keeps its own lockfile and is not a workspace member, so
+      # neither audit above can see it. Without this step a website advisory is
+      # invisible — which is how two of them sat open long enough to need a
+      # manual override.
+      #
+      # Same blocking rule as the published-dependency audit: advisory on pull
+      # requests, blocking on the weekly schedule and on pushes to main. Green
+      # here has to mean the site is clean, or the step just relocates the blind
+      # spot into a passing log. `!cancelled()` because the two audits above can
+      # fail hard, and a root advisory must not silently skip this one.
+      - name: Audit documentation site
+        if: ${{ !cancelled() }}
+        continue-on-error: ${{ github.event_name == 'pull_request' }}
+        run: pnpm audit --audit-level high --dir website
+
+  # The website keeps its own lockfile and is never installed or built elsewhere
+  # in CI, so a website/package.json change — e.g. a security override — that is
+  # not reflected in website/pnpm-lock.yaml goes unnoticed: the override you think
+  # patches an advisory may not be in the committed graph at all, and `pnpm audit`
+  # would happily audit the stale (possibly still-vulnerable) tree. A frozen-lockfile
+  # install fails fast on that drift. Root drift is already caught by the
+  # `--frozen-lockfile` installs in ci.yml; this closes the same gap for the website.
+  # `--ignore-scripts` skips sharp's native build (irrelevant to lockfile validation
+  # and the usual source of install flake).
+  website-lockfile:
+    name: Website Lockfile Drift
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: '20.19.0'
+
+      - name: Verify website lockfile matches package.json
+        run: pnpm install --frozen-lockfile --ignore-scripts --dir website

.gitignore

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

AGENTS.md

@@ -1,18 +0,0 @@
-<!-- OPENSPEC:START -->
-# OpenSpec Instructions
-
-These instructions are for AI assistants working in this project.
-
-Always open `@/openspec/AGENTS.md` when the request:
-- Mentions planning or proposals (words like proposal, spec, change, plan)
-- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work
-- Sounds ambiguous and you need the authoritative spec before coding
-
-Use `@/openspec/AGENTS.md` to learn:
-- How to create and apply change proposals
-- Spec format and conventions
-- Project structure and guidelines
-
-Keep this managed block so 'openspec update' can refresh the instructions.
-
-<!-- OPENSPEC:END -->

CHANGELOG.md

@@ -1,5 +1,742 @@
 # @fission-ai/openspec
 
+## 1.9.0
+
+### Minor Changes
+
+- [#1622](https://github.com/Fission-AI/OpenSpec/pull/1622) [`59c16a4`](https://github.com/Fission-AI/OpenSpec/commit/59c16a4461254ed984d1d5e29d00af1a5610035a) Thanks [@clay-good](https://github.com/clay-good)! - ### New Features
+
+  - **Command Code command adapter** — Command Code is now a first-class, adapter-backed tool. `openspec init` generates OpenSpec commands under `.commandcode/commands/opsx-<id>.md` (invoked as `/opsx-<id>`) alongside the skills under `.commandcode/skills/`, matching Command Code's documented custom-slash-command surface.
+
+- [#1613](https://github.com/Fission-AI/OpenSpec/pull/1613) [`42d7f67`](https://github.com/Fission-AI/OpenSpec/commit/42d7f673bc5f13378451267c8a9d0c23f63a2d1a) Thanks [@Angelthebestone](https://github.com/Angelthebestone)! - ### New Features
+
+  - **Command Code support** — `openspec init` now supports Command Code as an adapterless skills-only tool. It installs the OpenSpec skills under `.commandcode/skills/` and invokes them as `/openspec-*` commands, matching Command Code's native skill surface.
+
+- [#1604](https://github.com/Fission-AI/OpenSpec/pull/1604) [`83be9d1`](https://github.com/Fission-AI/OpenSpec/commit/83be9d113e8310789c281f7c8a00ed4fad191dd5) Thanks [@clay-good](https://github.com/clay-good)! - Add `openspec validate --archived`: an opt-in check that every change under `changes/archive/` has all of its `tasks.md` checkboxes ticked, exiting non-zero if any are unchecked. This surfaces changes that were archived with unfinished work — which the normal validate flow never catches, because it only looks at active changes — and is meant for a pre-commit or CI hook ([#205](https://github.com/Fission-AI/OpenSpec/issues/205)). It is a standalone scope: it does not alter any existing `validate` invocation and does not re-validate already-applied spec deltas.
+
+### Patch Changes
+
+- [#1530](https://github.com/Fission-AI/OpenSpec/pull/1530) [`bf5099e`](https://github.com/Fission-AI/OpenSpec/commit/bf5099e39fdb5d7bde2adc84f49ea93afd7463e9) Thanks [@clay-good](https://github.com/clay-good)! - Apply workflow now tells agents to surface unexpected scope instead of hiding it. When a task needs work beyond what the spec describes, the `/opsx:apply` skill and command guidance direct the agent to pause and report the added scope rather than silently narrowing, deferring, or simplifying away specified behavior, and to mark a task complete only when its specified behavior is fully implemented. Fixes [#1529](https://github.com/Fission-AI/OpenSpec/issues/1529).
+
+- [#1603](https://github.com/Fission-AI/OpenSpec/pull/1603) [`9ae75c8`](https://github.com/Fission-AI/OpenSpec/commit/9ae75c86efe5d326ffa7ca5a3fd64b1f1e7728c2) Thanks [@clay-good](https://github.com/clay-good)! - `openspec archive` no longer writes terminal escape codes to a redirected or captured stdout. Its confirmation prompts and the no-argument change picker drew their live UI with ANSI cursor-move sequences even when stdout was not a terminal — noise in a redirected log, and in some non-interactive hosts an unbounded render loop that could grow the captured output until the disk filled. When stdout (or stdin) is not a terminal, archive now reads the confirmations as plain text, and a no-argument run asks you to pass a change name up front instead of drawing a menu. Piped answers (`printf 'y\n' | openspec archive …`) and `--yes` behave as before, and interactive terminals are unchanged. Fixes [#1526](https://github.com/Fission-AI/OpenSpec/issues/1526).
+
+- [#1528](https://github.com/Fission-AI/OpenSpec/pull/1528) [`9425897`](https://github.com/Fission-AI/OpenSpec/commit/942589741de35f1b8896b410d7ea70295bb137c0) Thanks [@Marzx13](https://github.com/Marzx13)! - Canonicalize rebuilt specs to end with exactly one final LF. Previously a spec whose `## Requirements` section was last was rebuilt with a trailing blank line (`\n\n`), which failed Markdown whitespace checks after sync or archive. Internal spacing and content after the Requirements section are unchanged.
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - Preserve the blank lines around a spec's `## Requirements` heading when syncing a delta. `openspec archive` rebuilt `openspec/specs/<capability>/spec.md` by joining its slices with a bare newline, so the blank lines that surround the heading were dropped and the resulting file failed Markdown whitespace checks. The rebuild now keeps that spacing intact. Fixes [#1625](https://github.com/Fission-AI/OpenSpec/issues/1625). Thanks [@jwang513](https://github.com/jwang513)! ([#1637](https://github.com/Fission-AI/OpenSpec/pull/1637))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate --all` and `openspec list --json` no longer silently pass when run outside an OpenSpec project. From a directory with no root they used to resolve the current directory as an implicit root, exit 0, and report empty results — a false pass for CI and agents. Bulk validation (`--all`, `--changes`, `--specs`) and `list` now require an existing root (the `openspec/project.md` fallback for legacy projects is kept), while direct validation and other intentional implicit-root workflows are unchanged. Thanks [@clay-good](https://github.com/clay-good)! ([#1612](https://github.com/Fission-AI/OpenSpec/pull/1612))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - Label the `update` workflow in the `openspec config` workflow picker. The checklist had friendly labels for 11 of the 12 workflows but was missing `update`, so that row — one of the six core workflows every user sees — fell back to its raw id with a placeholder description. The update-change template's stale "expanded-profile" wording is also reworded to "optional". Fixes [#1627](https://github.com/Fission-AI/OpenSpec/issues/1627). Thanks [@clay-good](https://github.com/clay-good)! ([#1632](https://github.com/Fission-AI/OpenSpec/pull/1632))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec schema fork` now preserves the source schema's YAML formatting. Renaming a forked `schema.yaml` round-tripped through a parse/re-serialize step that dropped comments, could rewrite block-scalar style (a literal `|` folded to `>`), and reordered keys, so the fork no longer matched its source. The rename now edits the document in place via the YAML Document API, leaving comments, scalar style, and key order untouched. Thanks [@clay-good](https://github.com/clay-good)! ([#1607](https://github.com/Fission-AI/OpenSpec/pull/1607))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec schemas` now resolves through the canonical OpenSpec root-selection precedence instead of always reading from the current directory. It accepts `--store <id>`, rejects `--store-path` like the other store-aware commands, and returns the shared machine-readable diagnostics on JSON failures, while preserving the existing human output and bare JSON array on success. Thanks [@Patodo](https://github.com/Patodo)! ([#1616](https://github.com/Fission-AI/OpenSpec/pull/1616))
+
+- [#1640](https://github.com/Fission-AI/OpenSpec/pull/1640) [`610b78f`](https://github.com/Fission-AI/OpenSpec/commit/610b78f6554e8aabfa294df53962428ff85c8b76) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate` now warns on ambiguous task numbering in `spec-driven` changes: a task ID duplicated at full depth (including across resolved task files), or a task whose leading number disagrees with its enclosing `## N.` group. Numeric-looking text outside numbered groups is ignored, and custom schemas are unchanged until they opt in. The checks run across direct, bulk, and deprecated change validation. Closes [#1520](https://github.com/Fission-AI/OpenSpec/issues/1520). Thanks [@alectimison-maker](https://github.com/alectimison-maker)! ([#1523](https://github.com/Fission-AI/OpenSpec/pull/1523))
+
+- [#1522](https://github.com/Fission-AI/OpenSpec/pull/1522) [`07dea6e`](https://github.com/Fission-AI/OpenSpec/commit/07dea6ed2faf71c8b9f4944d64246f2ff39eeffc) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Don't let a legacy Codex upgrade hijack the vendor-neutral `agents` target** — `openspec update` no longer overwrites an existing `.agents` skills tree (and its ownership marker) when Codex is detected only from leftover global `~/.codex/prompts`. Because Codex and the vendor-neutral `agents` target share `.agents/skills`, a project that used the `agents` target could have its generic skills silently rewritten with Codex-specific syntax and its target flipped to Codex on the next `update --force`. The legacy-upgrade path now respects the established owner of a shared skills directory, matching the one-writer rule `openspec init` already applies. When an upgrade is skipped this way, that tool's repo-local legacy files (e.g. `.codex/prompts/openspec-*.md`) are also preserved rather than cleaned up, since no replacement was written to take their place. A genuine first-time Codex upgrade (no `.agents` tree yet) is unaffected.
+
+- [#1521](https://github.com/Fission-AI/OpenSpec/pull/1521) [`c751b3d`](https://github.com/Fission-AI/OpenSpec/commit/c751b3da52a7f06d6662a8673feff4685566cdd4) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Stop silently dropping unlabeled scenarios on archive** — `openspec validate` and `openspec archive` now recognize every level-4 (`####` followed by whitespace) child of a requirement as a scenario, matching how the spec is counted elsewhere. Before, the scenario-loss guard only recognized headers written exactly as `#### Scenario:`, so a `MODIFIED` requirement that dropped a differently-labeled child (for example `#### Edge case`) passed validation and was then permanently deleted by archive with no warning. Both paths now agree, so the loss is caught at authoring time. Scenario names are normalized when comparing (an optional `Scenario:` prefix and a CommonMark closing `#` run are ignored), so simply relabeling a scenario is not mistaken for dropping one.
+
+- [#1610](https://github.com/Fission-AI/OpenSpec/pull/1610) [`17581c1`](https://github.com/Fission-AI/OpenSpec/commit/17581c11edf6b27ef18be7be1e4dcc06c81a3fff) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - `openspec init` now suggests an IDE restart only when an IDE-resident tool such as Cursor, GitHub Copilot, Continue, or Cline was configured. CLI tools like Claude Code, Codex, and Gemini CLI no longer show the hint, since their commands work as soon as the files exist.
+
+- [#1609](https://github.com/Fission-AI/OpenSpec/pull/1609) [`804427b`](https://github.com/Fission-AI/OpenSpec/commit/804427b6ff3f3b35b542365ba8b32e183fce3287) Thanks [@clay-good](https://github.com/clay-good)! - Suppress the first-run telemetry disclosure notice when `--json` is used. On a
+  first-ever run the notice was written to stdout and could break `--json`
+  consumers; it is now deferred to the first later non-JSON run, keeping `--json`
+  output valid while still guaranteeing the disclosure.
+
+## 1.8.0
+
+### Minor Changes
+
+- [#1303](https://github.com/Fission-AI/OpenSpec/pull/1303) [`1aa0f2a`](https://github.com/Fission-AI/OpenSpec/commit/1aa0f2abfc19f2487f5b8566e6eb3bf15f41c20a) Thanks [@solanab](https://github.com/solanab)! - Add the vendor-neutral `agents` target: `openspec init --tools agents` installs the workflow skills to `.agents/skills/openspec-*/SKILL.md`, the shared location AGENTS.md-compatible assistants read. It is skills-only, so no slash commands are generated. Because `agents` is now a real target, `--tools all` includes it and creates `.agents/skills/` where it previously did not.
+
+- [#1274](https://github.com/Fission-AI/OpenSpec/pull/1274) [`7a4a745`](https://github.com/Fission-AI/OpenSpec/commit/7a4a745d803b698c34947eda6d73b5a24aebb58c) Thanks [@NicoAvanzDev](https://github.com/NicoAvanzDev)! - Generate GitHub Copilot coding agent setup and custom agent files during `openspec init` and keep them synchronized during `openspec update`.
+
+- [#1214](https://github.com/Fission-AI/OpenSpec/pull/1214) [`161f945`](https://github.com/Fission-AI/OpenSpec/commit/161f9454a372aab67c495d780928bba89c829f3e) Thanks [@showms](https://github.com/showms)! - Add MiniMax Code as a global skills-only tool target.
+
+- [#1518](https://github.com/Fission-AI/OpenSpec/pull/1518) [`568e56c`](https://github.com/Fission-AI/OpenSpec/commit/568e56c67231dbe2447aca4f0e7995c05ada95a3) Thanks [@clay-good](https://github.com/clay-good)! - ### New Features
+
+  - **Atlassian Rovo Dev CLI** — `openspec init --tools rovodev` installs the OpenSpec workflow skills for Atlassian's Rovo Dev CLI. It is skills-only (no slash commands), written to `.rovodev`.
+
+  ### Bug Fixes
+
+  - **Codex skills now live in the shared `.agents` directory** — `openspec init` and `openspec update` install Codex skills under `.agents/skills/` (the canonical location assistants read) and migrate an existing `.codex` skills directory in place. Files you customized are preserved, not overwritten.
+  - **`openspec status` separates planning from implementation** — status now reports `isPlanningComplete` (every non-skipped planning artifact exists; skipped artifacts count as satisfied without being written) distinctly from overall progress, and its messages no longer imply a change is finished before it has been implemented. `isComplete` is kept as a compatibility alias, so existing scripts keep working.
+
+- [#1517](https://github.com/Fission-AI/OpenSpec/pull/1517) [`73207a6`](https://github.com/Fission-AI/OpenSpec/commit/73207a6f2cd235729ac3fe3cb1e44152b8f63f12) Thanks [@clay-good](https://github.com/clay-good)! - Make GitHub Copilot cloud coding-agent files opt-in. Selecting the `github-copilot` tool no longer silently writes a GitHub Actions workflow into `.github/`; `openspec init` now asks first (default No) and remembers the choice in `openspec/config.yaml` (`githubCopilot.cloudAgent`). Use `--copilot-cloud` / `--no-copilot-cloud` to decide non-interactively.
+
+  - `openspec update` never prompts — it only refreshes cloud files for projects that opted in (or that already have generated cloud files, so existing setups keep working).
+  - Opting out (`--no-copilot-cloud` or `cloudAgent: false`) removes OpenSpec-managed cloud files; a user-customized file is always preserved, never overwritten or deleted.
+  - `init` and `update` now report whether cloud files were written, skipped, or left untouched — and if you already have your own `copilot-setup-steps.yml`, they say it was preserved and that you need to add the OpenSpec install step by hand.
+
+- [#1484](https://github.com/Fission-AI/OpenSpec/pull/1484) [`521ee33`](https://github.com/Fission-AI/OpenSpec/commit/521ee33e6ece269241b45e08017ee60f13fdef08) Thanks [@clay-good](https://github.com/clay-good)! - Retire a capability when a change removes its last requirement. A change that declares `retire_capabilities: true` in its `.openspec.yaml` (alongside the `schema:` that file requires) may now be archived even when its REMOVED entries take a capability's last requirement: `openspec archive` deletes that capability's main spec instead of aborting with "Spec must have at least one requirement". Without the marker nothing changes — the archive aborts exactly as before, except the message now names the marker as the way out. Retirement happens only when the emptied spec could not have been written at all, every one is named in the archive output, a pasteable `git checkout` is included when the spec lived in the caller's checkout, and `--no-validate` never retires. Archive now also rejects a main spec with duplicate canonical requirement names instead of letting delta reconciliation collapse one of the duplicate blocks. One thing to know before retiring: a capability's spec is the base another change's MODIFIED block is checked against, so an in-flight change that modifies the capability you just retired will keep validating clean and then refuse to archive ("target spec does not exist; only ADDED requirements are allowed for new specs") — close or rework that change alongside the retirement.
+
+### Patch Changes
+
+- [#1502](https://github.com/Fission-AI/OpenSpec/pull/1502) [`ece8660`](https://github.com/Fission-AI/OpenSpec/commit/ece8660d44bd19b86440376327752cda3d7b0717) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate` now treats the English `SHALL`/`MUST` convention as guidance in normal mode, so requirements written in other languages can validate. Strict mode continues to enforce the convention.
+
+- [#1483](https://github.com/Fission-AI/OpenSpec/pull/1483) [`2b3d368`](https://github.com/Fission-AI/OpenSpec/commit/2b3d368539132be6311e55db58899abbf5306b81) Thanks [@clay-good](https://github.com/clay-good)! - Tell the caller which flag to pass when `openspec archive` cannot ask its confirmation questions. An AI agent (or any script) runs the CLI with stdin closed, so every prompt rejects with `@inquirer`'s `User force closed the prompt with 0 null` — the archive aborted with an error that named neither the question nor the flag, and agents burned a turn guessing ([#1479](https://github.com/Fission-AI/OpenSpec/issues/1479)). Each confirmation now reports what it needed and a pasteable rerun that carries the flags you already passed: `openspec archive <name> --skip-specs --yes` stays a `--skip-specs` run, so following the suggestion cannot merge specs you opted out of merging, and a change name that needs quoting gets double quotes, the one form bash, zsh, PowerShell and cmd.exe all read the same way (a name no shell reads literally even quoted — one containing `$`, a backtick, or the `%`/`!` that cmd.exe still expands inside quotes — is left as a `<change-name>` placeholder rather than a command that would target something else). `openspec archive` with no change name used to swallow the same failure, print `No change selected. Aborting.` and exit 0 — success for a run that archived nothing; it now exits 1 asking for a change name, matching how `openspec show` and `openspec validate` already behave without a terminal. The check is reactive — it inspects a prompt that already failed — so answers piped into the command, `--yes`, `--json`, and Ctrl-C all behave exactly as before, and a run that OpenSpec already considers non-interactive (`CI`, `OPEN_SPEC_INTERACTIVE=0`, `--no-interactive`) gets the guidance even when the runner allocated a pty. The onboarding walkthrough, the only generated guidance that tells an agent to run `openspec archive`, now shows `--yes`.
+
+- [#1486](https://github.com/Fission-AI/OpenSpec/pull/1486) [`427abf4`](https://github.com/Fission-AI/OpenSpec/commit/427abf40ac45a9a44f78eb74c81f53f9f4197ccf) Thanks [@clay-good](https://github.com/clay-good)! - Task progress now counts indented sub-tasks. A `tasks.md` whose sub-tasks were unfinished reported `✓ Complete` in `openspec list` and `openspec view`, was missing those tasks from the `openspec instructions apply` list, and archived with no incomplete-task warning, because both checkbox parsers only matched checkboxes at column 0.
+
+  Progress counting and the apply task list now share one parser, so `list`, `view`, `archive` and `apply` agree about which lines of a tasks file are tasks. A checkbox with no text after it is left out of the apply list, which has nothing to act on, but still counts toward every progress number; a file of nothing but such checkboxes now asks to be rewritten rather than reporting itself done. The shared pattern matches every line the two it replaced matched, and more, so task counts can rise but never fall: no change starts reporting less work than before, and archive's incomplete-task warning can only become stricter. Checkboxes are still counted wherever they appear, including inside a code fence, an HTML comment or an indented block, so a `tasks.md` that shows a checklist as a format example can now count that example as work — remove it from the file, or pass `--yes` to archive.
+
+- [#1500](https://github.com/Fission-AI/OpenSpec/pull/1500) [`26bd1d4`](https://github.com/Fission-AI/OpenSpec/commit/26bd1d4e5c6c6ba75bd7d6136424019b2bf89ced) Thanks [@clay-good](https://github.com/clay-good)! - Keep generated workflows on the selected store, handle optional workflow fallbacks safely, and validate synced specs before reporting success.
+
+- [#1490](https://github.com/Fission-AI/OpenSpec/pull/1490) [`45cca5d`](https://github.com/Fission-AI/OpenSpec/commit/45cca5db6137ed209117cc70510eb3e057fb981b) Thanks [@clay-good](https://github.com/clay-good)! - Say before confirmation when archiving a change will delete a note written next to a requirement. A requirement absorbs anything below it that OpenSpec doesn't recognize as a new heading — a note indented by the one to three spaces Markdown allows, for example — so removing or modifying that requirement took the note with it, silently. `openspec archive` now names content the rebuilt spec would actually drop and where to move it to keep it. The merge itself is unchanged: nothing is relocated, because a `#` line inside a scenario looks identical to a note and moving one of those would rewrite the spec wrongly.
+
+- [#1492](https://github.com/Fission-AI/OpenSpec/pull/1492) [`690a27e`](https://github.com/Fission-AI/OpenSpec/commit/690a27e649c4a3325daeb0f6667ebe0f82792179) Thanks [@mc856](https://github.com/mc856)! - `openspec init` and `openspec update` no longer delete the CoStrict and Junie command files they just generated. Legacy cleanup removes artifacts older OpenSpec versions left behind, and two of its patterns named paths the current adapters still write to. CoStrict's was a whole-directory removal of `.cospec/openspec/commands/`, the folder the adapter writes `opsx-<id>.md` into, so every run wiped the directory — including any file the user kept there — while the banner above it read `No user content to preserve`. Junie's `.junie/commands/opsx-*.md` listed its own current output. Cleanup runs before the config migration, so on a config that has no `profile` key yet the missing command files make delivery detection read the project as skills-only and persist that to the global config: the files are not regenerated, and the preference changes for every other project too.
+
+  CoStrict is now a file pattern, `.cospec/openspec/commands/openspec-*.md`, matching the three commands the pre-`opsx` CoStrict integration wrote there (`openspec-proposal.md`, `openspec-apply.md`, `openspec-archive.md`) and the same shape every other file-based tool already uses. Junie's entry is removed outright: Junie support arrived after the slash configurators that wrote `openspec-*` files were deleted, so no OpenSpec version ever created those files there. Genuinely legacy files are still detected and removed, and no other tool's patterns change — they never overlapped their adapter's current output.
+
+- [#1501](https://github.com/Fission-AI/OpenSpec/pull/1501) [`0b20ae3`](https://github.com/Fission-AI/OpenSpec/commit/0b20ae3964283bdcb4e34ea7380770857f6a339c) Thanks [@clay-good](https://github.com/clay-good)! - Keep the propose workflow focused on planning, clarify material ambiguities before creating a change, and hand implementation off to the apply workflow.
+
+- [#1503](https://github.com/Fission-AI/OpenSpec/pull/1503) [`8a3850d`](https://github.com/Fission-AI/OpenSpec/commit/8a3850da735e241c14ad94935463f879b33f21a9) Thanks [@clay-good](https://github.com/clay-good)! - When exploration turns into a new change, generated explore guidance now instructs agents to run `openspec new change` before writing requested artifacts. This preserves the required `.openspec.yaml` metadata instead of letting an agent create an incomplete change directory by hand. After the user accepts a capture, explore also creates the requested artifacts without requiring another workflow command.
+
+- [#1513](https://github.com/Fission-AI/OpenSpec/pull/1513) [`622c509`](https://github.com/Fission-AI/OpenSpec/commit/622c509a1349c3ad9c52cd1a4ee007bd47549204) Thanks [@FasterPHP](https://github.com/FasterPHP)! - Honor `telemetry.enabled` in global config. `false` disables anonymous telemetry and `openspec update` version checks; unset keeps telemetry enabled, and env/CI opt-outs still take precedence.
+
+- [#1499](https://github.com/Fission-AI/OpenSpec/pull/1499) [`9cd845f`](https://github.com/Fission-AI/OpenSpec/commit/9cd845fc459b71486d9f2424c2e1f38e2ca8766e) Thanks [@clay-good](https://github.com/clay-good)! - Keep generated files, specs, archive moves, and local state inside their intended security boundaries without breaking linked monorepo workflows.
+
+- [#1482](https://github.com/Fission-AI/OpenSpec/pull/1482) [`84ebc57`](https://github.com/Fission-AI/OpenSpec/commit/84ebc57cb3f0e91b93484484092fdc2f9fcf39e6) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate <change>` now reports a MODIFIED requirement that omits a scenario the main spec still has — the same loss archive already refuses to apply — so the change fails at authoring time instead of at archive time. A change carrying a stale MODIFIED block will start failing validation; it was already unarchivable, and the message names the scenarios to copy back in.
+
+## 1.7.0
+
+### Minor Changes
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Add CodeArts Agent skills support: `openspec init --tools codeartsagent` installs the workflow skills.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Add Hermes Agent as a supported AI tool: `openspec init --tools hermes` installs the workflow skills (Hermes is skills-only and invokes them directly).
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Add ZCode as a supported AI tool: `openspec init --tools zcode` generates its skills and `/opsx:*` commands.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Codex is now skills-only: workflows install as `$openspec-*` skills and previously managed custom prompts are retired (existing ones are cleaned up on update).
+
+- [#1062](https://github.com/Fission-AI/OpenSpec/pull/1062) [`eac2973`](https://github.com/Fission-AI/OpenSpec/commit/eac2973819037727b10214f70db2f54d82f2d891) Thanks [@showms](https://github.com/showms)! - Add current project context and per-operation guidance to apply and archive workflows. Projects can configure `operations.apply.guidance` and `operations.archive.guidance`; `openspec instructions apply` returns apply inputs, and the new read-only `openspec instructions archive` surface returns archive inputs for the selected root.
+
+  Archive, bulk archive, and sync skills now load current archive inputs and `specs` artifact rules at execution time, fail before writes or moves when required instruction lookups fail, and reuse specs-rule snapshots during inline sync.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Publish the workflow skills as static `skills/<name>/SKILL.md` files so `npx skills add Fission-AI/OpenSpec` works.
+
+- [#1399](https://github.com/Fission-AI/OpenSpec/pull/1399) [`27b22ab`](https://github.com/Fission-AI/OpenSpec/commit/27b22ab4cbf530fa00e17f0f6b75a44d56777542) Thanks [@clay-good](https://github.com/clay-good)! - Add `skip_specs: true` change metadata for work with no spec-level behavior change (pure refactors, tooling, docs). `openspec validate` accepts a zero-delta change that declares the marker (honored only when the metadata parses under the shared change-metadata schema and names a schema that loads) and errors when the marker and delta specs are both present, the artifact graph no longer blocks `tasks` on spec files for such changes, `openspec status` renders the specs stage as explicitly skipped, and the propose/specs guidance points to the marker instead of contradicting the validator.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Resolve symlinked schema directories so schemas shared via symlink (e.g. from a dotfiles repo) are discovered.
+
+- [#1470](https://github.com/Fission-AI/OpenSpec/pull/1470) [`6295515`](https://github.com/Fission-AI/OpenSpec/commit/6295515d4da4f7c76eaed00b7f1926771eae92de) Thanks [@clay-good](https://github.com/clay-good)! - `openspec update` now offers to upgrade the CLI when yours is behind the published one. Instruction files are generated by the installed CLI, so a stale install reported `✓ All 1 tool(s) up to date (v1.6.0)` while the workflows added in newer releases were never written:
+
+  ```text
+  A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
+    Running from: /usr/local/lib/node_modules/@fission-ai/openspec
+  ? Upgrade to v1.7.0 now? (Y/n)
+  ```
+
+  Say yes and it upgrades, confirms the new version is the one that answers, then re-runs the update so the new workflows arrive in the same command. Say no and it prints the command matching how you installed OpenSpec, and updates with what you have. Nothing happens to your machine that you did not agree to: the offer appears only in an interactive terminal and only where `npm install -g` would help, and the check is skipped in CI or when `OPENSPEC_NO_UPDATE_CHECK`, `DO_NOT_TRACK=1`, or `OPENSPEC_TELEMETRY=0` is set.
+
+  See [CLI reference → `openspec update`](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md#openspec-update) for the per-install-method behavior and every opt-out.
+
+### Patch Changes
+
+- [#1404](https://github.com/Fission-AI/OpenSpec/pull/1404) [`a84ae70`](https://github.com/Fission-AI/OpenSpec/commit/a84ae70e8c6ef6ffaab56599d6f91fa39873e63d) Thanks [@clay-good](https://github.com/clay-good)! - Generated skills for tools without a command adapter (Kimi Code, Mistral Vibe, Hermes, ForgeCode, CodeArts) no longer reference `/opsx:*` commands that were never generated: skill cross-references, the init getting-started hint, and the profile-migration message now use each tool's documented skill invocation (Kimi Code: `/skill:openspec-*`; others: `/openspec-*`), and Codex — skills-invocable with no slash surface — gets a syntax-neutral hint that names the skill. Selections that mix invocation syntaxes print one labeled hint per distinct form, so every advertised instruction is usable by the tool it names. When `delivery: commands` would generate nothing for a selected tool, init prints a configuration correction naming that tool, even when other tools did get commands or skills. The committed skills.sh distribution is regenerated with skill references (default `/openspec-*` form, as that channel installs skills only).
+
+- [#1363](https://github.com/Fission-AI/OpenSpec/pull/1363) [`5199f41`](https://github.com/Fission-AI/OpenSpec/commit/5199f41a5d523b9212dd2854ec5e505d2f80e2e7) Thanks [@clay-good](https://github.com/clay-good)! - ### Features
+
+  - **One default store for every repo on your machine** — `openspec config set defaultStore <id>` sets a machine-level fallback root: any command run outside a planning root, with no `--store` flag and no project `store:` pointer, resolves to that store. It sits at the bottom of the precedence list, so `--store`, a local root, and a project pointer all still win. The root banner and JSON `root` block report the distinct provenance `source: "global_default"`, so users and tooling can tell a machine-wide default from a repo's own pointer. A stale id degrades to the underlying store error with a fix that names `openspec config unset defaultStore`.
+
+- [#1435](https://github.com/Fission-AI/OpenSpec/pull/1435) [`6a5171e`](https://github.com/Fission-AI/OpenSpec/commit/6a5171e18630db4ed8e78c9edfaae4be532e2af6) Thanks [@clay-good](https://github.com/clay-good)! - `openspec new change` now accepts numeric-prefixed names like `100-add-feature` or `00001-add-auth`, useful for ordering or tiering changes. Change names now use the same kebab-case grammar as store ids and change metadata (a leading digit is allowed); `archive` already treated date-prefixed names as a supported convention. Uppercase, spaces, underscores, and leading/trailing or consecutive hyphens are still rejected, and every previously valid name stays valid.
+
+- [#1425](https://github.com/Fission-AI/OpenSpec/pull/1425) [`040a869`](https://github.com/Fission-AI/OpenSpec/commit/040a86931f5398167137a483b2e8081aec13016e) Thanks [@clay-good](https://github.com/clay-good)! - Compare config key guards literally instead of through a helper.
+
+  `setNestedValue` and `deleteNestedValue` rejected prototype-reaching key segments through a helper that did a `Set` lookup. That is correct, but static analysis could not follow it, so CodeQL kept reporting prototype-pollution on the very assignments the guard protects. The segments are now compared literally in the same function, still checked across the whole path before anything is written. Behavior is unchanged for every input, verified against the previous implementation across 400,000 generated cases.
+
+- [#1431](https://github.com/Fission-AI/OpenSpec/pull/1431) [`6a4f0d7`](https://github.com/Fission-AI/OpenSpec/commit/6a4f0d7f3384486132cb9c516b635c23cadc1fa2) Thanks [@clay-good](https://github.com/clay-good)! - A delta spec that introduces a brand-new capability can now open with a `## Purpose`, and `openspec archive` uses it as the Purpose of the main spec it creates instead of writing the `TBD - created by archiving change <name>. Update Purpose after archive.` placeholder over it. The `specs` artifact instruction, its example, the delta template and the `openspec-sync-specs` skill all tell authors and agents to write one, so the CLI and agent-driven sync paths produce the same main spec.
+
+  Archive keeps the placeholder when the delta has no usable `## Purpose`:
+
+  - no `## Purpose` header outside a code fence or HTML comment, or a body that is only a code fence or only a comment
+  - a body that would leave a spec its own parser cannot read — a heading or requirement header that truncates a section, an unterminated fence, or any HTML comment
+  - in the second case archive also says why, and still completes rather than aborting
+
+  A carried Purpose under 50 characters is kept but warned about, since `openspec validate --strict` reports it as too brief. The Purpose of an existing main spec is never touched; archive warns when it ignores a delta's Purpose there.
+
+- [#1437](https://github.com/Fission-AI/OpenSpec/pull/1437) [`19d4171`](https://github.com/Fission-AI/OpenSpec/commit/19d41714c8b790488732687443713e406ef5aeef) Thanks [@clay-good](https://github.com/clay-good)! - `openspec archive` no longer aborts when a REMOVED delta's requirement is already gone from the main spec (the early-sync pattern the sync skill teaches): it warns, treats the removal as already applied, and reports applied-only totals. In `--json` mode those warnings are carried in a new optional `warnings` array on the archive result. When every operation for a spec was already synced, archive skips rewriting that file instead of churning normalization differences into it. A delta that both RENAMEs and REMOVEs the same requirement is now rejected explicitly, by both `validate` and `archive` — the two spellings are compared case- and whitespace-insensitively — and a REMOVED header that differs only in case or whitespace from an existing requirement still aborts (that is a typo, not an early sync). Also fixed: the archive delta gate matches section headers case-insensitively like the parser; symlinked `specs/<capability>/spec.md` files are discovered instead of silently dropped; `openspec show <change>` no longer prints a spurious "scenarios" flag warning; files generated for qwen and bob reference commands by their real hyphenated names (`/opsx-<id>`), and init's getting-started hint follows suit; apply/update/onboard guidance names the CLI fallback for profiles that don't install `/opsx:continue` or `/opsx:new`.
+
+- [#1411](https://github.com/Fission-AI/OpenSpec/pull/1411) [`c439a4e`](https://github.com/Fission-AI/OpenSpec/commit/c439a4ee48ef02dcdae6ac8101b7d12924695e7e) Thanks [@clay-good](https://github.com/clay-good)! - Fix phantom requirements parsed from delta specs, which made `openspec archive` warn about problems `openspec validate` never reported.
+
+  A header inside a delta section that is not a `### Requirement:` header — a divider such as `### Documentation Requirements` — was read as a requirement with no scenario. `openspec archive` warned that it was missing a scenario, and `openspec show <change> --json` and `openspec change list` counted it as an extra delta. The change parser now ignores those headers, matching the delta reader, so the phantom is gone from the warnings and from the JSON. Main spec parsing is unchanged.
+
+  `openspec archive` also no longer repeats requirement-level issues from the delta specs in its non-blocking "Proposal warnings in proposal.md" block. Each defect was printed twice there, and a `## REMOVED Requirements` entry — names-only by design — was reported as missing a scenario on every correct removal. Delta spec validation still reports and blocks on genuine defects, and proposal-level warnings are unchanged.
+
+- [#1394](https://github.com/Fission-AI/OpenSpec/pull/1394) [`b474f81`](https://github.com/Fission-AI/OpenSpec/commit/b474f81cb4bebbeff0e447fd78c34a613ebd02fa) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Archive no longer races the spec sync, or reports a sync that never landed** — the generated `openspec-archive-change` skill (and the matching `opsx:archive` command) handed the spec sync to a background task and then moved the change folder immediately. The archive could move the delta specs out from under the running sync: the change ended up archived, `openspec/specs/` was never updated, and the summary still reported `Specs: ✓ Synced`. The sync now runs inline, and the archive only proceeds once every capability with a delta spec has been checked against it — ADDED present, MODIFIED changes applied, REMOVED gone, RENAMED under the new name and not the old. If the sync fails or a capability doesn't match, the archive stops and reports what differs instead of claiming success; nothing has moved, so you can fix it and retry.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Apply profile changes with the installed CLI instead of shelling out to `npx`, which could run a different version.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Delta and main-spec parsers strip a UTF-8 BOM, so files saved by Windows editors or PowerShell redirects no longer fail with "No delta sections found".
+
+- [#1398](https://github.com/Fission-AI/OpenSpec/pull/1398) [`97d441a`](https://github.com/Fission-AI/OpenSpec/commit/97d441a8ee2738d3008709e61acfc91925c7ae3a) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Bulk archive now stops when you pick "Cancel"** — the generated `openspec-bulk-archive-change` skill (and the matching `opsx:bulk-archive` command) offered a "Cancel" option at the confirmation prompt but never told the agent what to do with it, so the next step archived every selected change anyway. The prompt now routes each answer by intent: "Cancel" stops without archiving anything, the archive options proceed (the ready-only option archives just the changes the status table marks `Ready` or `Ready*`), and any other answer re-asks instead of archiving. The single-change archive skill already routes Cancel this way; this brings the bulk variant in line.
+
+- [#1375](https://github.com/Fission-AI/OpenSpec/pull/1375) [`52a8bce`](https://github.com/Fission-AI/OpenSpec/commit/52a8bce1fd2bc98c51fa35cf0cfa05e799eb4404) Thanks [@clay-good](https://github.com/clay-good)! - `--change` now accepts any change name that exists on disk (e.g. date-prefixed names like `2026-07-04-voice-copilot-v1`), matching what `list`, `validate`, and `archive` already resolve. Lookup still rejects unsafe names (path separators, `..`, hidden entries); the kebab-case naming rule still applies when creating a change.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec new change` rejects names over 200 characters with a validation message instead of surfacing a raw ENAMETOOLONG filesystem error.
+
+- [#1447](https://github.com/Fission-AI/OpenSpec/pull/1447) [`fb19699`](https://github.com/Fission-AI/OpenSpec/commit/fb196995dad017074415a638824eb546f3321cbc) Thanks [@hsusul](https://github.com/hsusul)! - Generated tool command files now carry valid YAML frontmatter for every supported tool. Command names ship as `OPSX: Explore`, and the unquoted `name: OPSX: Explore` that adapters emitted is not parseable YAML — strict parsers rejected the whole file, so the command failed to load. Several adapters also re-implemented their own escaping, and a few interpolated descriptions in raw.
+
+  Escaping now lives in one place (`escapeYamlValue` / `formatTagsArray`) and every adapter uses it. String frontmatter values are always double-quoted, which also keeps values like `true`, `null` and `123` from round-tripping as booleans, nulls and numbers. Non-string fields such as `allowed-tools` and `invokable` are unchanged. Expect the first `openspec update` after upgrading to rewrite the frontmatter lines of your generated command files.
+
+  Archive workflow guidance also gets two corrections: bulk archive now carries its per-delta include/exclude decisions into execution, so a delta whose implementation was not found is reported as `sync skipped` instead of being synced anyway, and both archive workflows verify the main specs before moving the change directory.
+
+- [#1471](https://github.com/Fission-AI/OpenSpec/pull/1471) [`9a937cb`](https://github.com/Fission-AI/OpenSpec/commit/9a937cb9b36fb1040bdbde3bab3fa3903944ef10) Thanks [@clay-good](https://github.com/clay-good)! - Reference slash commands by the name each tool actually registers. Command bodies, generated `SKILL.md` cross-references, and the `init`/`update`/migration hints all advertised `/opsx:<id>`, but only 7 of the 28 tools with a command adapter register that name — the ones whose files sit in an `opsx/` directory. The other 21 write `.../opsx-<id>.md`, where the filename is the command, so tools such as Cursor, GitHub Copilot, Windsurf and Kilo Code were told to type a command their palette never had; a single generated Cursor file named itself `/opsx-apply` in frontmatter and then told the reader to run `/opsx:apply`. The command _name_ is now derived from the command file each adapter writes rather than a hand-maintained tool list, so a newly added adapter cannot drift, and the _wrapper_ around it is adapter metadata: Amazon Q loads its files into a prompt library invoked with `@`, so it now gets `@opsx-<id>` in command bodies, skills, and the onboarding hint instead of a slash command it never registers. Codex, which generates no command files at all, now gets `$openspec-<skill>` — the syntax its CLI actually accepts — everywhere it previously advertised `/opsx:*`, superseding the syntax-neutral hint described in the pending `adapterless-skill-references` note. Command filenames and paths are unchanged, and Claude Code output is byte-identical.
+
+- [#1364](https://github.com/Fission-AI/OpenSpec/pull/1364) [`f58b445`](https://github.com/Fission-AI/OpenSpec/commit/f58b4456925b6331f3e5902a1c57905afe7edbf5) Thanks [@clay-good](https://github.com/clay-good)! - Fix `openspec completion install` detecting the wrong shell for fish (and other)
+  users whose interactive shell differs from their login shell. Detection now
+  consults the parent process before falling back to `$SHELL`, so running the
+  command from fish installs fish completions instead of defaulting to bash.
+
+- [#1377](https://github.com/Fission-AI/OpenSpec/pull/1377) [`285dfd7`](https://github.com/Fission-AI/OpenSpec/commit/285dfd7d764752b2a1e7e8cc843d613421e62652) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - Config `rules:` keys are no longer reported as `Unknown artifact ID` when they belong to a different schema. The global rules map is now validated against the union of artifact IDs across every available schema, so multi-schema projects stop seeing spurious warnings on every command ([#1322](https://github.com/Fission-AI/OpenSpec/issues/1322)).
+
+- [#1401](https://github.com/Fission-AI/OpenSpec/pull/1401) [`b33b15d`](https://github.com/Fission-AI/OpenSpec/commit/b33b15d98ae929624c991632c7382ebc234d4ca7) Thanks [@clay-good](https://github.com/clay-good)! - Stop `design.md` from restating the proposal. In the default `spec-driven` schema, the design instruction asked for "Background, current state, constraints, stakeholders" and "What this design achieves and excludes" without saying that motivation and scope already live in `proposal.md`, so agents restated the proposal's Why and What Changes instead of adding the design's own value - approach, alternatives, and trade-offs. The instruction and the design template now state the boundary explicitly (the proposal covers why and what, design covers how) and tell the agent to reference those documents rather than repeat them ([#1382](https://github.com/Fission-AI/OpenSpec/issues/1382)).
+
+- [#1167](https://github.com/Fission-AI/OpenSpec/pull/1167) [`1637856`](https://github.com/Fission-AI/OpenSpec/commit/1637856c423f2e84457652d1ab58885fe9744fb2) Thanks [@mehdishahdoost](https://github.com/mehdishahdoost)! - **Windsurf is now Devin Desktop.** Windsurf was rebranded on June 2, 2026 and its config directory moved: `.devin/` is the preferred read + write location, `.windsurf/` a legacy read-only fallback that the Devin Local agent does not read at all. OpenSpec follows the rename rather than carrying two ids for one product — the tool id is `devin`, writing `.devin/workflows/opsx-<id>.md` and `.devin/skills/openspec-*/SKILL.md`, and it is detected from either directory.
+
+  - `--tools windsurf` still resolves, so existing setup scripts keep working; it now configures `.devin/`.
+  - If your OpenSpec files are still in `.windsurf/`, `openspec update` explains the rebrand and offers to move them. `--force` and non-interactive runs take the move; declining leaves every file exactly where it is. Only the files OpenSpec generates move — each skill's `SKILL.md` and commands named `opsx-*`. A hand-written Cascade workflow, a reference file you keep beside a `SKILL.md`, a command file you edited, and `.devin/rules/` all stay exactly where they are.
+  - Devin skills and the getting-started hint reference `/openspec-*` skills rather than `/opsx-*` workflows, because only Devin Desktop reads workflows; the `/openspec-*` form works on both agents. Workflow bodies still use `/opsx-<id>`, the name Devin registers for a workflow file.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec doctor` now notes when a store checkout is behind its upstream ref.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Make the archive scenario-drift check multiplicity-aware: a MODIFIED block that keeps only one of two same-named scenarios no longer silently drops the other.
+
+- [#1408](https://github.com/Fission-AI/OpenSpec/pull/1408) [`378d468`](https://github.com/Fission-AI/OpenSpec/commit/378d468ad348dc1e973ed30c5cfa458fb77c9de3) Thanks [@clay-good](https://github.com/clay-good)! - Explore now reads the project's context and rules from `openspec/config.yaml` (or `config.yml`) at the start of a session, so it reasons with the same tech stack and conventions the artifact-creating workflows already receive.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec feedback` shows the formatted text and a pre-filled submission URL on any gh failure (issues disabled, network, rate limit), not only when gh is missing or unauthenticated.
+
+- [#1396](https://github.com/Fission-AI/OpenSpec/pull/1396) [`60f720c`](https://github.com/Fission-AI/OpenSpec/commit/60f720c43acd94de7645ac8629c614ede4682b6a) Thanks [@clay-good](https://github.com/clay-good)! - Fix `openspec feedback` failing when the repository does not define the `feedback` label. The command now retries without the label and notes that it was not applied, instead of exiting with an error and discarding the feedback.
+
+- [#1151](https://github.com/Fission-AI/OpenSpec/pull/1151) [`18cbf5d`](https://github.com/Fission-AI/OpenSpec/commit/18cbf5d32ffe1bff4fff692e24568c605cf1e0fa) Thanks [@javigomez](https://github.com/javigomez)! - ### Fixed
+
+  - Ignore Markdown structure (requirement headers, delta sections, scenarios, REMOVED/RENAMED entries) that appears inside fenced code blocks when parsing delta specs. Previously a fenced `### Requirement:` example was parsed as a real (phantom) requirement, producing spurious `validate` errors and risking incorrect `archive` output. Fenced-code detection is now shared across the Markdown parsers so `validate` and `archive` behave consistently.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - The archive scenario-drift check now ignores `#### Scenario:` lines inside fenced code blocks, matching validate: a fenced example no longer false-aborts an archive, and a fenced name no longer masks a genuinely dropped scenario.
+
+- [#1316](https://github.com/Fission-AI/OpenSpec/pull/1316) [`9b70481`](https://github.com/Fission-AI/OpenSpec/commit/9b70481df727ab9f7a00dd0118e4e09373a36fb9) Thanks [@mc856](https://github.com/mc856)! - ### Bug Fixes
+
+  - **`archive` no longer stacks a second date prefix** — archiving a change whose name already starts with a `YYYY-MM-DD-` prefix (a common authoring convention) keeps the name as-is instead of prepending today's date. Previously `openspec archive 2026-07-04-voice-copilot-v1 --yes` produced `2026-07-06-2026-07-04-voice-copilot-v1`, and when run on a later day the folder sorted under a day on which the change did not happen. Names without a full date prefix (including partial dates like `2026-07-feature`) are dated as before, and the naming is now idempotent.
+
+- [#1374](https://github.com/Fission-AI/OpenSpec/pull/1374) [`da3907b`](https://github.com/Fission-AI/OpenSpec/commit/da3907b8a9170711c8b7f63e18352e8577cf7df5) Thanks [@clay-good](https://github.com/clay-good)! - fix(completion): make the PowerShell completion script parse and load again
+
+  The generated `OpenSpecCompletion.ps1` contained 18 empty `switch ($positionalIndex) { }` blocks — emitted for commands whose positionals are all `path`-typed (PowerShell completes paths natively, so those cases produce no clauses). A switch with no clauses is a PowerShell parse error ("Missing condition in switch statement clause"), and PowerShell parses the whole file before running it, so the script never loaded and completions never registered. The generator now skips the positional-index block entirely when no positional produces completions, so the script parses clean (18 → 0 errors) and tab completion works.
+
+- [#1388](https://github.com/Fission-AI/OpenSpec/pull/1388) [`9b5d2cd`](https://github.com/Fission-AI/OpenSpec/commit/9b5d2cdd0c1aa4b1b49da4f95c6cec8d7d38b155) Thanks [@mc856](https://github.com/mc856)! - ### Bug Fixes
+
+  - **Archive workflow templates no longer teach agents to stack a second date prefix** — the `openspec-archive-change` and `openspec-bulk-archive-change` skill/command templates (and the onboarding walkthrough's archived-path example) now mirror the `openspec archive` rule: a change whose name already starts with a `YYYY-MM-DD-` prefix is archived under its own name, while other names get the current date prepended as before. Previously an agent following the workflow instructions on a change named `2026-07-04-voice-copilot-v1` produced `archive/2026-07-07-2026-07-04-voice-copilot-v1`, whatever the CLI did.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Gemini command files escape TOML-active characters (quotes, backslashes, control characters) in the description and prompt, so a template value containing them can no longer produce an invalid `.toml` file.
+
+- [#1464](https://github.com/Fission-AI/OpenSpec/pull/1464) [`5bcf057`](https://github.com/Fission-AI/OpenSpec/commit/5bcf05766a70ec0163c3e700a3029b1c1da895d8) Thanks [@clay-good](https://github.com/clay-good)! - Workflow skills and commands no longer tell agents to use the Claude Code-only AskUserQuestion tool. The same templates are generated for every supported tool, and agents without that tool (OpenCode, Factory Droid, Codex, and others) errored or stalled on the instruction. The guidance is now runtime-neutral: agents are simply told to ask the user.
+
+- [#1403](https://github.com/Fission-AI/OpenSpec/pull/1403) [`2d6c447`](https://github.com/Fission-AI/OpenSpec/commit/2d6c447100c51fb1e5f65c6f6a35ce02a3196a10) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Propose and fast-forward skills no longer name the Claude-only TodoWrite tool** — the generated `openspec-propose` and `openspec-ff-change` skills (and their `/opsx:propose` / `/opsx:ff` commands) told every agent to "Use the **TodoWrite tool**", which only exists in Claude Code. Codex, Cursor, Gemini, Copilot, and the other supported tools have no such tool, so agents either errored or stalled looking for it. The instruction is now runtime-neutral ("Use a todo list to track progress"), which works everywhere — including Claude Code.
+
+- [#1415](https://github.com/Fission-AI/OpenSpec/pull/1415) [`e2f748c`](https://github.com/Fission-AI/OpenSpec/commit/e2f748c64f05efaeac720f83c71fb6f1b6f6e18d) Thanks [@clay-good](https://github.com/clay-good)! - Reject config key paths that reach the prototype chain, and update the bundled `yaml` dependency.
+
+  `openspec config set --allow-unknown __proto__.polluted <value>` reported success and assigned onto `Object.prototype` for the rest of the process. `--allow-unknown` was meant to relax the known-key check only, but it skipped every key check, so `__proto__`, `constructor`, and `prototype` segments reached the nested-write helper. Those segments are now rejected in `config set` whether or not `--allow-unknown` is passed, and `setNestedValue` / `deleteNestedValue` refuse them regardless of caller. Ordinary keys such as `featureFlags.myFlag` behave exactly as before.
+
+  The `yaml` runtime dependency moves from 2.8.2 to 2.9.0, picking up the fix for a stack overflow on deeply nested input (GHSA / advisory patched in 2.8.3).
+
+- [#1376](https://github.com/Fission-AI/OpenSpec/pull/1376) [`7958924`](https://github.com/Fission-AI/OpenSpec/commit/7958924e95654af981437951e967983385da8001) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Archive after early sync** — `openspec archive` no longer fails with `ADDED failed … already exists` when a change's specs were already synced to the main specs before archiving (the early-sync pattern from the `sync` workflow). If an ADDED requirement already exists in the target spec with identical content, applying it is treated as a no-op; a same-named requirement with different content still aborts the archive as a genuine conflict ([#1332](https://github.com/Fission-AI/OpenSpec/issues/1332)).
+
+- [#1386](https://github.com/Fission-AI/OpenSpec/pull/1386) [`b419e96`](https://github.com/Fission-AI/OpenSpec/commit/b419e965bbf413cc658bbac37325ebc147b1c869) Thanks [@mc856](https://github.com/mc856)! - ### Bug Fixes
+
+  - **Archive after early sync (RENAMED)** — `openspec archive` no longer fails with `RENAMED failed … source not found` when a change's renames were already synced to the main specs before archiving (the early-sync pattern from the `sync` workflow). If a RENAMED requirement's source header is gone but the target header exists in the spec, applying the rename is treated as a no-op; a rename whose source and target are both missing still aborts the archive as a genuine error, and reported counts reflect only renames actually applied.
+
+- [#1462](https://github.com/Fission-AI/OpenSpec/pull/1462) [`ebf66c7`](https://github.com/Fission-AI/OpenSpec/commit/ebf66c7ee1df3f7465d7f480753f952483133a73) Thanks [@clay-good](https://github.com/clay-good)! - Respect reduced-motion preferences in `openspec init`: the welcome animation is skipped when the OS reduced-motion setting is on (macOS Reduce Motion, GNOME animations disabled), when `OPENSPEC_NO_ANIMATION` is set, or when the new `--no-animation` flag is passed. The static welcome screen is shown instead.
+
+- [#1405](https://github.com/Fission-AI/OpenSpec/pull/1405) [`5dfef4b`](https://github.com/Fission-AI/OpenSpec/commit/5dfef4b00c233fbe78f40488bd4ff98f4204684c) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
+
+  - **Custom schema instructions are no longer overridden by hard-coded spec-driven patterns** — the `openspec-continue-change` skill/command embedded one-line "common artifact patterns" for proposal.md, specs, design.md, and tasks.md, so agents followed those shortcuts instead of the schema's `instruction` field whenever a custom schema reused familiar artifact names. The templates now state that the `instruction` field is the authoritative guidance, and the `propose`, `continue`, and `ff` workflows direct the agent — both in the artifact-creation step and in the guidelines — to invoke a skill when the instruction delegates artifact creation to one, verifying the artifact exists afterward (fixes [#777](https://github.com/Fission-AI/OpenSpec/issues/777)).
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Follow the Kimi CLI rename to Kimi Code: new install paths with automatic migration of existing `.kimi` setups.
+
+- [#1415](https://github.com/Fission-AI/OpenSpec/pull/1415) [`e2f748c`](https://github.com/Fission-AI/OpenSpec/commit/e2f748c64f05efaeac720f83c71fb6f1b6f6e18d) Thanks [@clay-good](https://github.com/clay-good)! - Parse spec headings in linear time when the title is padded with whitespace.
+
+  Building the reference index read the first Purpose line with a regex that backtracked quadratically on a heading full of spaces: 10,000 characters of padding took 60ms, and 100,000 would have taken roughly six seconds. The heading scan is now hand-rolled and linear. Behavior is unchanged — the replacement was checked against the old implementation across 303,000 generated inputs, including CommonMark closing sequences (`## Purpose ##`), seven-hash lines, and headings with no space after the hashes.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Use local dates for CLI date-only values (archive names, timestamps) instead of UTC, so late-evening archives no longer get tomorrow's date.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec update` warns when a custom profile is missing core workflows instead of silently generating a partial install.
+
+- [#1428](https://github.com/Fission-AI/OpenSpec/pull/1428) [`81d5109`](https://github.com/Fission-AI/OpenSpec/commit/81d5109b86f16537deb99f84a772a83235dc9e09) Thanks [@taltas](https://github.com/taltas)! - Update current Roo Code product references to its community successor, Zoo Code.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Archive treats a MODIFIED delta whose content already matches the main spec as a no-op: a fully early-synced change now reports "Specs already in sync" instead of rewriting the file and claiming modifications.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Render multi-select prompts with `[x]`/`[ ]` checkbox markers instead of radio-button icons.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Discover nested spec paths like `specs/<area>/<capability>/spec.md` recursively and consistently across parse, apply, and archive.
+
+- [#1410](https://github.com/Fission-AI/OpenSpec/pull/1410) [`b3b05e1`](https://github.com/Fission-AI/OpenSpec/commit/b3b05e1abeb312caefd57e60be799aeb466c1d0e) Thanks [@clay-good](https://github.com/clay-good)! - Only advertise onboarding commands that will actually exist. The `openspec init` welcome screen and the `openspec update` "Getting started" summary listed `/opsx:new` and `/opsx:continue`, which the default `core` profile never generates, so users were told to run commands that did not exist. Both surfaces now list the commands for the installed workflows. The `init` and `update` completion hints also name the skill (`/openspec-propose`) instead of a command for tools that receive no command files — Codex, and any tool under skills-only delivery.
+
+- [#1412](https://github.com/Fission-AI/OpenSpec/pull/1412) [`1dc670d`](https://github.com/Fission-AI/OpenSpec/commit/1dc670deea741b8313b8a22fb975741f84677b3f) Thanks [@clay-good](https://github.com/clay-good)! - ### Fixed
+
+  - **`/opsx:propose` and `/opsx:ff` no longer finish a change with no spec written.** The workflows listed only `proposal`/`design`/`tasks` and treated the apply phase's `tasks` artifact as the stop condition — but `status` marks an artifact `done` as soon as a matching file exists, so writing `tasks.md` early satisfied the loop while `specs/<capability>/spec.md` was never created (a spec-less change in a spec-driven tool). The loop now derives the full required set — every apply dependency plus everything it transitively `requires` — from a single `status` call, creates each missing artifact, and only skips one when its own `instruction` field marks it conditional. ([#1260](https://github.com/Fission-AI/OpenSpec/issues/1260), [#788](https://github.com/Fission-AI/OpenSpec/issues/788))
+
+  ### Changed
+
+  - **`openspec status --json` now reports each artifact's `requires` edges.** Every entry in the `artifacts` array carries a `requires` array of the ids it directly depends on, present for every status (including `done`) so agents can compute the transitive required set from `status` alone. Additive and backward-compatible — existing fields are unchanged.
+
+- [#1191](https://github.com/Fission-AI/OpenSpec/pull/1191) [`7704702`](https://github.com/Fission-AI/OpenSpec/commit/7704702d61fa71e4f553c21a06bdf8e4ee803b4a) Thanks [@mc856](https://github.com/mc856)! - Generate Markdown commands for Qwen Code instead of deprecated TOML format. Qwen Code now recommends Markdown custom commands with YAML frontmatter; the old `.qwen/commands/opsx-*.toml` files are cleaned up as legacy artifacts on update.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - An already-synced RENAMED delta aborts when a case/whitespace variant of the source requirement still exists — the same typo guard REMOVED deltas have.
+
+- [#1368](https://github.com/Fission-AI/OpenSpec/pull/1368) [`de78c31`](https://github.com/Fission-AI/OpenSpec/commit/de78c31ffd885a0558ae55d332f74d5485dc01c0) Thanks [@clay-good](https://github.com/clay-good)! - ### Fixes
+
+  - **Regenerated artifacts now pick up your manual edits** — the continue, propose, and fast-forward workflows (and the `openspec instructions` dependency block) now tell the agent to re-read dependency artifacts from disk before creating the next one, instead of trusting whatever version it saw earlier in the conversation. Previously, editing `spec.md` and deleting `design.md`/`tasks.md` to regenerate them could silently produce artifacts based on the stale, pre-edit content.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Proposal guidance now resolves blocking open questions with the user instead of deferring them to design.md.
+
+- [#1392](https://github.com/Fission-AI/OpenSpec/pull/1392) [`a13abea`](https://github.com/Fission-AI/OpenSpec/commit/a13abeac47d419462b0193dbf9423dd466ffe6c7) Thanks [@clay-good](https://github.com/clay-good)! - ### Fixed
+
+  - Stop a delta spec written directly at a change's `specs/` root from being silently dropped. `validate` accepted `specs/spec.md` and counted its deltas, but the apply/archive merge only reads capability folders (`specs/<capability>/spec.md`), so the change could pass validation and be archived while its requirements never reached `openspec/specs/`. `validate` now uses the same discovery rules as the merge path and reports the misplaced file with a fix hint, and `archive` blocks instead of completing.
+
+- [#1465](https://github.com/Fission-AI/OpenSpec/pull/1465) [`f917b8b`](https://github.com/Fission-AI/OpenSpec/commit/f917b8be5e1100189ef62320ba9322763053640e) Thanks [@clay-good](https://github.com/clay-good)! - Order artifacts by the schema's declaration order instead of alphabetically.
+
+  `specs` and `design` both require only `proposal`, so both become ready at once - and the tie used to be broken alphabetically, which put `design` first. `openspec status` listed design above specs and `nextSteps` recommended writing `design.md` before any spec existed, contradicting the spec-driven schema's own documented `proposal → specs → design → tasks` sequence.
+
+  Ties now follow the order the schema declares its artifacts, so `openspec status`, `status --json`, `nextSteps`, `blocked by:` lists, and an artifact's `unlocks` all agree. No dependency edges changed, so nothing newly blocks and `design.md` stays optional - only the order of equally-ready artifacts moved. Custom schemas get the same guarantee: dependency order still comes first, but wherever your schema leaves two artifacts equally ready, the order of its `artifacts:` list now decides which one the CLI recommends - so reorder that list if it was never deliberate.
+
+- [#1446](https://github.com/Fission-AI/OpenSpec/pull/1446) [`5348da9`](https://github.com/Fission-AI/OpenSpec/commit/5348da930c4038ffd5b5a521702b71315dcd0019) Thanks [@showms](https://github.com/showms)! - ### Bug Fixes
+
+  - Preserve an existing project-local schema when `openspec schema init --force` rejects an unknown artifact ID. Forced replacement now begins only after artifact validation succeeds.
+
+- [#1433](https://github.com/Fission-AI/OpenSpec/pull/1433) [`26f009d`](https://github.com/Fission-AI/OpenSpec/commit/26f009d940f311b99db7f310816bb166a99fb3ef) Thanks [@clay-good](https://github.com/clay-good)! - Change lookup no longer requires `proposal.md`. `openspec show`, `openspec change list/show/validate`, and shell completion now resolve a change by its directory, matching `openspec list`, `status`, `instructions`, and `validate`.
+
+  Previously a change created by `openspec new change` — which scaffolds only `.openspec.yaml` — was reported as `Unknown item` by `openspec show` and was missing from completions and `openspec change list` until a proposal was written, and a change from a schema with no proposal artifact was never resolvable. `openspec change list` now reports the same set as `openspec list`, keeps task counts for a change that has no proposal yet, and labels it `(no proposal.md yet)` rather than `(unable to read)`. Showing such a change explains that the proposal is not written yet and points at `openspec status --change <name>`.
+
+- [#1468](https://github.com/Fission-AI/OpenSpec/pull/1468) [`fc886af`](https://github.com/Fission-AI/OpenSpec/commit/fc886af7f93068482bbf2c66fd1eb76b40c6a22f) Thanks [@clay-good](https://github.com/clay-good)! - The continue, update, verify, sync, and archive workflow skills now select a change the same way apply does: use the provided name, infer it from conversation context, auto-select when exactly one active change exists, and only prompt when the choice is genuinely ambiguous. Previously these workflows were told to always prompt ("Do NOT guess or auto-select"), so invoking them with a single active change stalled on a question with only one possible answer. The selection is always announced ("Using change: <name>") with how to override, and bulk archive still always prompts.
+
+- [#1194](https://github.com/Fission-AI/OpenSpec/pull/1194) [`b7c85c7`](https://github.com/Fission-AI/OpenSpec/commit/b7c85c741ca56748a4ae095b573fe4550c5c977f) Thanks [@mc856](https://github.com/mc856)! - Fix skills-only delivery emitting `/opsx:*` command references. SKILL.md files generated by init, update, and workspace skill setup now reference the corresponding skills (e.g. `/openspec-apply-change`) when `delivery: 'skills'` is configured, instead of commands that were never generated.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Specs instructions include the spec content guidance from the concepts docs, so generated specs follow the requirement/scenario format.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - The static welcome screen (reduced motion, `--no-animation`, narrow terminals) now waits for the Enter it asks for instead of letting the keystroke submit the tool picker unseen.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Sync and archive workflows resolve main specs through the store-aware root instead of assuming `openspec/specs` in the repo.
+
+- [#1402](https://github.com/Fission-AI/OpenSpec/pull/1402) [`0da5f98`](https://github.com/Fission-AI/OpenSpec/commit/0da5f98e147543a44379e32295e2e9798d775d83) Thanks [@clay-good](https://github.com/clay-good)! - Show the main spec format in the sync-specs skill so agents stop leaving delta operation headers (`## ADDED/MODIFIED Requirements`) in `openspec/specs/` — merged main specs with those headers parse as 0 requirements in `openspec view` ([#1120](https://github.com/Fission-AI/OpenSpec/issues/1120)).
+
+- [#1476](https://github.com/Fission-AI/OpenSpec/pull/1476) [`8731290`](https://github.com/Fission-AI/OpenSpec/commit/87312900f532c6c13ea556d4badaff2efdfa9602) Thanks [@clay-good](https://github.com/clay-good)! - Telemetry no longer depends on `posthog-node`: the single usage event is sent with a plain fetch to the same endpoint. Installing OpenSpec no longer pulls the fast-publishing `posthog-node`/`@posthog/core`/`@posthog/types` tree, which broke downstream installs under supply-chain age policies like pnpm's `minimumReleaseAge` ([#1390](https://github.com/Fission-AI/OpenSpec/issues/1390)).
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - The stale-CLI check hardens its install detection: a directory merely named `volta` no longer changes the upgrade hint, the Windows npm-ownership check corroborates against the `openspec.cmd` shim npm actually writes, and a registry redirect from https to plain http is no longer followed.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - The stale-CLI check tears down a redirected registry connection when its time budget expires instead of leaving the socket open.
+
+- [#1442](https://github.com/Fission-AI/OpenSpec/pull/1442) [`10fa39b`](https://github.com/Fission-AI/OpenSpec/commit/10fa39b1c3a3e88c02ae7d3053864c03a793ff47) Thanks [@hsusul](https://github.com/hsusul)! - `openspec update` now refreshes tools that are configured with command files but no skills (delivery `commands`). Previously it read the generating version only from skill files, so such a tool was reported as "up to date" forever and its command files were never regenerated after a CLI upgrade. Command files carry no version stamp, so OpenSpec compares their contents against what it would generate now — including removing a command file left behind by a workflow you have since deselected. CRLF line endings and a UTF-8 BOM are treated as checkout artifacts rather than drift, so a Windows clone does not report a spurious update.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec update` with `delivery: commands` prints the same configuration correction as init when it removes the skills of a tool that supports only skills, instead of deleting them silently.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - `openspec validate` reports an unreadable specs/ directory as the error it is instead of misdiagnosing it as "no deltas found".
+
+- [#1455](https://github.com/Fission-AI/OpenSpec/pull/1455) [`6b3623a`](https://github.com/Fission-AI/OpenSpec/commit/6b3623a39e96f49995d38d642738b31f68e92039) Thanks [@c4patino](https://github.com/c4patino)! - `openspec view` now resolves the configured OpenSpec root instead of always reading the current directory, and accepts `--store <id>` like its sibling commands. Projects whose `openspec/config.yaml` points at an external store saw an empty dashboard — 0 specs, 0 requirements — while `openspec list` read the same store correctly.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - Preserve keyboard input on Windows after the welcome screen instead of dropping the first keystrokes.
+
+- [#1475](https://github.com/Fission-AI/OpenSpec/pull/1475) [`17af60c`](https://github.com/Fission-AI/OpenSpec/commit/17af60c66e4c049e3986fdbafcdc16b202cda59f) Thanks [@clay-good](https://github.com/clay-good)! - zsh completion install honors `$ZSH` and `$ZSH_CUSTOM`, so Oh My Zsh setups at custom locations get the completion where their shell actually loads it.
+
+## 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
+
+- [#596](https://github.com/Fission-AI/OpenSpec/pull/596) [`e91568d`](https://github.com/Fission-AI/OpenSpec/commit/e91568deb948073f3e9d9bb2d2ab5bf8080d6cf4) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
+
+  - Clarified spec naming convention — Specs should be named after capabilities (`specs/<capability>/spec.md`), not changes
+  - Fixed task checkbox format guidance — Tasks now clearly require `- [ ]` checkbox format for apply phase tracking
+
+## 1.0.1
+
+### Patch Changes
+
+- [#587](https://github.com/Fission-AI/OpenSpec/pull/587) [`943e0d4`](https://github.com/Fission-AI/OpenSpec/commit/943e0d41026d034de66b9442d1276c01b293eb2b) Thanks [@TabishB](https://github.com/TabishB)! - ### Bug Fixes
+
+  - Fixed incorrect archive path in onboarding documentation — the template now shows the correct path `openspec/changes/archive/YYYY-MM-DD-<name>/` instead of the incorrect `openspec/archive/YYYY-MM-DD--<name>/`
+
+## 1.0.0
+
+### Major Changes
+
+- [#578](https://github.com/Fission-AI/OpenSpec/pull/578) [`0cc9d90`](https://github.com/Fission-AI/OpenSpec/commit/0cc9d9025af367faa1688a7b2606a2549053cd3f) Thanks [@TabishB](https://github.com/TabishB)! - ## OpenSpec 1.0 — The OPSX Release
+
+  The workflow has been rebuilt from the ground up. OPSX replaces the old phase-locked `/openspec:*` commands with an action-based system where AI understands what artifacts exist, what's ready to create, and what each action unlocks.
+
+  ### Breaking Changes
+
+  - **Old commands removed** — `/openspec:proposal`, `/openspec:apply`, and `/openspec:archive` no longer exist
+  - **Config files removed** — Tool-specific instruction files (`CLAUDE.md`, `.cursorrules`, `AGENTS.md`, `project.md`) are no longer generated
+  - **Migration** — Run `openspec init` to upgrade. Legacy artifacts are detected and cleaned up with confirmation.
+
+  ### From Static Prompts to Dynamic Instructions
+
+  **Before:** AI received the same static instructions every time, regardless of project state.
+
+  **Now:** Instructions are dynamically assembled from three layers:
+
+  1. **Context** — Project background from `config.yaml` (tech stack, conventions)
+  2. **Rules** — Artifact-specific constraints (e.g., "propose spike tasks for unknowns")
+  3. **Template** — The actual structure for the output file
+
+  AI queries the CLI for real-time state: which artifacts exist, what's ready to create, what dependencies are satisfied, and what each action unlocks.
+
+  ### From Phase-Locked to Action-Based
+
+  **Before:** Linear workflow — proposal → apply → archive. Couldn't easily go back or iterate.
+
+  **Now:** Flexible actions on a change. Edit any artifact anytime. The artifact graph tracks state automatically.
+
+  | Command              | What it does                                         |
+  | -------------------- | ---------------------------------------------------- |
+  | `/opsx:explore`      | Think through ideas before committing to a change    |
+  | `/opsx:new`          | Start a new change                                   |
+  | `/opsx:continue`     | Create one artifact at a time (step-through)         |
+  | `/opsx:ff`           | Create all planning artifacts at once (fast-forward) |
+  | `/opsx:apply`        | Implement tasks                                      |
+  | `/opsx:verify`       | Validate implementation matches artifacts            |
+  | `/opsx:sync`         | Sync delta specs to main specs                       |
+  | `/opsx:archive`      | Archive completed change                             |
+  | `/opsx:bulk-archive` | Archive multiple changes with conflict detection     |
+  | `/opsx:onboard`      | Guided 15-minute walkthrough of complete workflow    |
+
+  ### From Text Merging to Semantic Spec Syncing
+
+  **Before:** Spec updates required manual merging or wholesale file replacement.
+
+  **Now:** Delta specs use semantic markers that AI understands:
+
+  - `## ADDED Requirements` — New requirements to add
+  - `## MODIFIED Requirements` — Partial updates (add scenario without copying existing ones)
+  - `## REMOVED Requirements` — Delete with reason and migration notes
+  - `## RENAMED Requirements` — Rename preserving content
+
+  Archive parses these at the requirement level, not brittle header matching.
+
+  ### From Scattered Files to Agent Skills
+
+  **Before:** 8+ config files at project root + slash commands scattered across 21 tool-specific locations with different formats.
+
+  **Now:** Single `.claude/skills/` directory with YAML-fronted markdown files. Auto-detected by Claude Code, Cursor, Windsurf. Cross-editor compatible.
+
+  ### New Features
+
+  - **Onboarding skill** — `/opsx:onboard` walks new users through their first complete change with codebase-aware task suggestions and step-by-step narration (11 phases, ~15 minutes)
+
+  - **21 AI tools supported** — Claude Code, Cursor, Windsurf, Continue, Gemini CLI, GitHub Copilot, Amazon Q, Cline, RooCode, Kilo Code, Auggie, CodeBuddy, Qoder, Qwen, CoStrict, Crush, Factory, OpenCode, Antigravity, iFlow, and Codex
+
+  - **Interactive setup** — `openspec init` shows animated welcome screen and searchable multi-select for choosing tools. Pre-selects already-configured tools for easy refresh.
+
+  - **Customizable schemas** — Define custom artifact workflows in `openspec/schemas/` without touching package code. Teams can share workflows via version control.
+
+  ### Bug Fixes
+
+  - Fixed Claude Code YAML parsing failure when command names contained colons
+  - Fixed task file parsing to handle trailing whitespace on checkbox lines
+  - Fixed JSON instruction output to separate context/rules from template — AI was copying constraint blocks into artifact files
+
+  ### Documentation
+
+  - New getting-started guide, CLI reference, concepts documentation
+  - Removed misleading "edit mid-flight and continue" claims that weren't implemented
+  - Added migration guide for upgrading from pre-OPSX versions
+
+## 0.23.0
+
+### Minor Changes
+
+- [#540](https://github.com/Fission-AI/OpenSpec/pull/540) [`c4cfdc7`](https://github.com/Fission-AI/OpenSpec/commit/c4cfdc7c499daef30d8a218f5f59b8d9e5adb754) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features
+
+  - **Bulk archive skill** — Archive multiple completed changes in a single operation with `/opsx:bulk-archive`. Includes batch validation, spec conflict detection, and consolidated confirmation
+
+  ### Other
+
+  - **Simplified setup** — Config creation now uses sensible defaults with helpful comments instead of interactive prompts
+
+## 0.22.0
+
+### Minor Changes
+
+- [#530](https://github.com/Fission-AI/OpenSpec/pull/530) [`33466b1`](https://github.com/Fission-AI/OpenSpec/commit/33466b1e2a6798bdd6d0e19149173585b0612e6f) Thanks [@TabishB](https://github.com/TabishB)! - Add project-level configuration, project-local schemas, and schema management commands
+
+  **New Features**
+
+  - **Project-level configuration** — Configure OpenSpec behavior per-project via `openspec/config.yaml`, including custom rules injection, context files, and schema resolution settings
+  - **Project-local schemas** — Define custom artifact schemas within your project's `openspec/schemas/` directory for project-specific workflows
+  - **Schema management commands** — New `openspec schema` commands (`list`, `show`, `export`, `validate`) for inspecting and managing artifact schemas (experimental)
+
+  **Bug Fixes**
+
+  - Fixed config loading to handle null `rules` field in project configuration
+
+## 0.21.0
+
+### Minor Changes
+
+- [#516](https://github.com/Fission-AI/OpenSpec/pull/516) [`b5a8847`](https://github.com/Fission-AI/OpenSpec/commit/b5a884748be6156a7bb140b4941cfec4f20a9fc8) Thanks [@TabishB](https://github.com/TabishB)! - Add feedback command and Nix flake support
+
+  **New Features**
+
+  - **Feedback command** — Submit feedback directly from the CLI with `openspec feedback`, which creates GitHub Issues with automatic metadata inclusion and graceful fallback for manual submission
+  - **Nix flake support** — Install and develop openspec using Nix with the new `flake.nix`, including automated flake maintenance and CI validation
+
+  **Bug Fixes**
+
+  - **Explore mode guardrails** — Explore mode now explicitly prevents implementation, keeping the focus on thinking and discovery while still allowing artifact creation
+
+  **Other**
+
+  - Improved change inference in `opsx apply` — automatically detects the target change from conversation context or prompts when ambiguous
+  - Streamlined archive sync assessment with clearer delta spec location guidance
+
+## 0.20.0
+
+### Minor Changes
+
+- [#502](https://github.com/Fission-AI/OpenSpec/pull/502) [`9db74aa`](https://github.com/Fission-AI/OpenSpec/commit/9db74aa5ac6547efadaed795217cfa17444f2004) Thanks [@TabishB](https://github.com/TabishB)! - Add `/opsx:verify` command and fix vitest process storms
+
+  **New Features**
+
+  - **`/opsx:verify` command** — Validate that change implementations match their specifications
+
+  **Bug Fixes**
+
+  - Fixed vitest process storms by capping worker parallelism
+  - Fixed agent workflows to use non-interactive mode for validation commands
+  - Fixed PowerShell completions generator to remove trailing commas
+
+## 0.19.0
+
+### Minor Changes
+
+- eb152eb: Add Continue IDE support, shell completions, and `/opsx:explore` command
+
+  **New Features**
+
+  - **Continue IDE support** – OpenSpec now generates slash commands for [Continue](https://continue.dev/), expanding editor integration options alongside Cursor, Windsurf, Claude Code, and others
+  - **Shell completions for Bash, Fish, and PowerShell** – Run `openspec completion install` to set up tab completion in your preferred shell
+  - **`/opsx:explore` command** – A new thinking partner mode for exploring ideas and investigating problems before committing to changes
+  - **Codebuddy slash command improvements** – Updated frontmatter format for better compatibility
+
+  **Bug Fixes**
+
+  - Shell completions now correctly offer parent-level flags (like `--help`) when a command has subcommands
+  - Fixed Windows compatibility issues in tests
+
+  **Other**
+
+  - Added optional anonymous usage statistics to help understand how OpenSpec is used. This is **opt-out** by default – set `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable. Only command names and version are collected; no arguments, file paths, or content. Automatically disabled in CI environments.
+
 ## 0.18.0
 
 ### Minor Changes
@@ -51,13 +788,15 @@
 
 ### Minor Changes
 
-- 2e71835: ### New Features
+- 2e71835: Add `openspec config` command and Oh-my-zsh completions
+
+  **New Features**
 
   - Add `openspec config` command for managing global configuration settings
   - Implement global config directory with XDG Base Directory specification support
   - Add Oh-my-zsh shell completions support for enhanced CLI experience
 
-  ### Bug Fixes
+  **Bug Fixes**
 
   - Fix hang in pre-commit hooks by using dynamic imports
   - Respect XDG_CONFIG_HOME environment variable on all platforms
@@ -65,7 +804,7 @@
   - Align cli-completion spec with implementation
   - Remove hardcoded agent field from slash commands
 
-  ### Documentation
+  **Documentation**
 
   - Alphabetize AI tools list in README and make it collapsible
 
@@ -86,6 +825,8 @@
 
 ### Minor Changes
 
+- Add Continue slash command support so `openspec init` can generate `.continue/prompts/openspec-*.prompt` files with MARKDOWN frontmatter and `$ARGUMENTS` placeholder, and refresh them on `openspec update`.
+
 - Add Antigravity slash command support so `openspec init` can generate `.agent/workflows/openspec-*.md` files with description-only frontmatter and `openspec update` refreshes existing workflows alongside Windsurf.
 
 ## 0.15.0

MAINTAINERS.md

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

README.md

@@ -1,432 +1,268 @@
 <p align="center">
   <a href="https://github.com/Fission-AI/OpenSpec">
     <picture>
-      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
-      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
-      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
+      <source srcset="assets/openspec_bg.png">
+      <img src="assets/openspec_bg.png" alt="OpenSpec logo">
     </picture>
   </a>
-  
-</p>
-<p align="center">Spec-driven development for AI coding assistants.</p>
-<p align="center">
-  <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
-  <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
-  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
-  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>
 
 <p align="center">
-  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
+  <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
+  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
+  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/discord/1411657095639601154?style=flat-square&logo=discord&logoColor=white&label=Discord&suffix=%20online" /></a>
 </p>
 
+<details>
+<summary><strong>The most loved spec framework.</strong></summary>
+
+[![Stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars)](https://github.com/Fission-AI/OpenSpec/stargazers)
+[![Downloads](https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo)](https://www.npmjs.com/package/@fission-ai/openspec)
+[![Contributors](https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors)](https://github.com/Fission-AI/OpenSpec/graphs/contributors)
+
+</details>
+<p></p>
+Our philosophy:
+
+```text
+→ fluid not rigid
+→ iterative not waterfall
+→ easy not complex
+→ built for brownfield not just greenfield
+→ scalable from personal projects to enterprises
+```
+
+> [!TIP]
+> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
+>
+> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
+
 <p align="center">
   Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
+<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
+
+## See it in action
+
+```text
+You: /opsx:explore
+AI:  What would you like to explore?
+You: I want dark mode but I'm not sure how to do it cleanly.
+AI:  Let me look at your styling setup...
+     Cleanest path here: CSS variables + a small theme context,
+     with system-preference detection. No new dependencies. Scope it?
+You: Yes, let's do it.
+
+You: /opsx:propose add-dark-mode
+AI:  Created openspec/changes/add-dark-mode/
+     ✓ proposal.md — why we're doing this, what's changing
+     ✓ specs/       — requirements and scenarios
+     ✓ design.md    — technical approach
+     ✓ tasks.md     — implementation checklist
+     Ready for implementation!
+
+You: /opsx:apply
+AI:  Implementing tasks...
+     ✓ 1.1 Add theme context provider
+     ✓ 1.2 Create toggle component
+     ✓ 2.1 Add CSS variables
+     ✓ 2.2 Wire up localStorage
+     All tasks complete!
+
+You: /opsx:archive
+AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
+     Specs updated. Ready for the next feature.
+```
+
+<details>
+<summary><strong>What do the specs actually look like?</strong></summary>
+
+Plain Markdown — requirements with concrete scenarios, no special syntax to learn. Here's what goes in the `specs/` folder created above:
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Theme selection
+The app SHALL let users switch between light and dark themes,
+defaulting to the system preference.
+
+#### Scenario: User toggles dark mode
+- **WHEN** the user clicks the theme toggle
+- **THEN** the app switches to dark mode and persists the choice
+```
+
+Your AI writes these; you review the plan before any code is written.
+
+OpenSpec is built with OpenSpec — browse this repo's live [specs](openspec/specs) and in-flight [changes](openspec/changes) for real examples at scale.
+
+</details>
+
+<details>
+<summary><strong>OpenSpec Dashboard</strong></summary>
+
 <p align="center">
-  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
+  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
 </p>
 
-# OpenSpec
-
-OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
-
-## Why OpenSpec?
-
-AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
-
-Key outcomes:
-- Human and AI stakeholders agree on specs before work begins.
-- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
-- Shared visibility into what's proposed, active, or archived.
-- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
-
-## How OpenSpec compares (at a glance)
-
-- **Lightweight**: simple workflow, no API keys, minimal setup.
-- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
-- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
-- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
-
-See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
-
-## How It Works
-
-```
-┌────────────────────┐
-│ Draft Change       │
-│ Proposal           │
-└────────┬───────────┘
-         │ share intent with your AI
-         ▼
-┌────────────────────┐
-│ Review & Align     │
-│ (edit specs/tasks) │◀──── feedback loop ──────┐
-└────────┬───────────┘                          │
-         │ approved plan                        │
-         ▼                                      │
-┌────────────────────┐                          │
-│ Implement Tasks    │──────────────────────────┘
-│ (AI writes code)   │
-└────────┬───────────┘
-         │ ship the change
-         ▼
-┌────────────────────┐
-│ Archive & Update   │
-│ Specs (source)     │
-└────────────────────┘
-
-1. Draft a change proposal that captures the spec updates you want.
-2. Review the proposal with your AI assistant until everyone agrees.
-3. Implement tasks that reference the agreed specs.
-4. Archive the change to merge the approved updates back into the source-of-truth specs.
-```
-
-## Getting Started
-
-### Supported AI Tools
-
-<details>
-<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
-
-These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
-
-| Tool | Commands |
-|------|----------|
-| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
-| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
-| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
-| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
-| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
-| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
-| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
-| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
-| **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
-| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
-| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
-| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
-| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
-| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) |
-| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
-| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-
-Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
-
 </details>
 
-<details>
-<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+## Why teams adopt OpenSpec
 
-These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
+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.
 
-| Tools |
-|-------|
-| Amp • Jules • Others |
+**[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.
 
-</details>
+- **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.
 
-### Install & Initialize
+> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
 
-#### Prerequisites
-- **Node.js >= 20.19.0** - Check your version with `node --version`
+## Quick Start
 
-#### Step 1: Install the CLI globally
+**Requires Node.js 20.19.0 or higher.**
+
+Install OpenSpec globally:
 
 ```bash
 npm install -g @fission-ai/openspec@latest
 ```
 
-Verify installation:
-```bash
-openspec --version
-```
+Then navigate to your project directory and initialize:
 
-#### Step 2: Initialize OpenSpec in your project
-
-Navigate to your project directory:
-```bash
-cd my-project
-```
-
-Run the initialization:
 ```bash
+cd your-project
 openspec init
 ```
 
-**What happens during initialization:**
-- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
-- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
-- A new `openspec/` directory structure is created in your project
+> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
-**After setup:**
-- Primary AI tools can trigger `/openspec` workflows without additional configuration
-- Run `openspec list` to verify the setup and view any active changes
-- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
-  so a fresh launch ensures they appear
+Now talk to your AI:
 
-### Optional: Populate Project Context
+- **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>`.
 
-After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
+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`.
 
-```text
-Populate your project context:
-"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
-```
+`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [How To Invoke](docs/supported-tools.md#how-to-invoke).
 
-Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
+> [!NOTE]
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
+>
+> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
 
-### Create Your First Change
+## Docs
 
-Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
+**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`).
 
-#### 1. Draft the Proposal
-Start by asking your AI to create a change proposal:
+→ **[Getting Started](docs/getting-started.md)**: first steps<br>
+→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
+→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
+→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
+→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
+→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
+→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
+→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
+→ **[Commands](docs/commands.md)**: slash commands & skills<br>
+→ **[CLI](docs/cli.md)**: terminal reference<br>
+→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
+→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
+→ **[Concepts](docs/concepts.md)**: how it all fits<br>
+→ **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
+→ **[Customization](docs/customization.md)**: make it yours<br>
+→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
 
-```text
-You: Create an OpenSpec change proposal for adding profile search filters by role and team
-     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
 
-AI:  I'll create an OpenSpec change proposal for profile filters.
-     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
-```
+## Community schemas
 
-#### 2. Verify & Review
-Check that the change was created correctly and review the proposal:
+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.
 
-```bash
-$ openspec list                             # Confirm the change folder exists
-$ openspec validate add-profile-filters     # Validate spec formatting
-$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
-```
+→ **[Browse the catalog](docs/customization.md#community-schemas)** in the customization docs.
 
-#### 3. Refine the Specs
-Iterate on the specifications until they match your needs:
 
-```text
-You: Can you add acceptance criteria for the role and team filters?
+## Why OpenSpec?
 
-AI:  I'll update the spec delta with scenarios for role and team filters.
-     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
-```
+AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.
 
-#### 4. Implement the Change
-Once specs look good, start implementation:
+- **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 30+ AI assistants via slash commands
 
-```text
-You: The specs look good. Let's implement this change.
-     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+### How we compare
 
-AI:  I'll work through the tasks in the add-profile-filters change.
-     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
-     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
-```
+**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
 
-#### 5. Archive the Completed Change
-After implementation is complete, archive the change:
+**vs. [Kiro](https://kiro.dev)** (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.
 
-```text
-AI:  All tasks are complete. The implementation is ready.
-
-You: Please archive the change
-     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
-
-AI:  I'll archive the add-profile-filters change.
-    *Runs: openspec archive add-profile-filters --yes*
-     ✓ Change archived successfully. Specs updated. Ready for the next feature!
-```
-
-Or run the command yourself in terminal:
-```bash
-$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
-```
-
-**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
-
-## Command Reference
-
-```bash
-openspec list               # View active change folders
-openspec view               # Interactive dashboard of specs and changes
-openspec show <change>      # Display change details (proposal, tasks, spec updates)
-openspec validate <change>  # Check spec formatting and structure
-openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
-```
-
-## Example: How AI Creates OpenSpec Files
-
-When you ask your AI assistant to "add two-factor authentication", it creates:
-
-```
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md           # Current auth spec (if exists)
-└── changes/
-    └── add-2fa/              # AI creates this entire structure
-        ├── proposal.md       # Why and what changes
-        ├── tasks.md          # Implementation checklist
-        ├── design.md         # Technical decisions (optional)
-        └── specs/
-            └── auth/
-                └── spec.md   # Delta showing additions
-```
-
-### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
-
-```markdown
-# Auth Specification
-
-## Purpose
-Authentication and session management.
-
-## Requirements
-### Requirement: User Authentication
-The system SHALL issue a JWT on successful login.
-
-#### Scenario: Valid credentials
-- WHEN a user submits valid credentials
-- THEN a JWT is returned
-```
-
-### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
-
-#### Scenario: OTP required
-- WHEN a user submits valid credentials
-- THEN an OTP challenge is required
-```
-
-### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
-
-```markdown
-## 1. Database Setup
-- [ ] 1.1 Add OTP secret column to users table
-- [ ] 1.2 Create OTP verification logs table
-
-## 2. Backend Implementation  
-- [ ] 2.1 Add OTP generation endpoint
-- [ ] 2.2 Modify login flow to require OTP
-- [ ] 2.3 Add OTP verification endpoint
-
-## 3. Frontend Updates
-- [ ] 3.1 Create OTP input component
-- [ ] 3.2 Update login flow UI
-```
-
-**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
-
-## Understanding OpenSpec Files
-
-### Delta Format
-
-Deltas are "patches" that show how specs change:
-
-- **`## ADDED Requirements`** - New capabilities
-- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
-- **`## REMOVED Requirements`** - Deprecated features
-
-**Format requirements:**
-- Use `### Requirement: <name>` for headers
-- Every requirement needs at least one `#### Scenario:` block
-- Use SHALL/MUST in requirement text
-
-## How OpenSpec Compares
-
-### vs. spec-kit
-OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
-
-### vs. Kiro.dev
-OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
-
-### vs. No Specs
-Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
-
-## Team Adoption
-
-1. **Initialize OpenSpec** – Run `openspec init` in your repo.
-2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
-3. **Grow incrementally** – Each change archives into living specs that document your system.
-4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
-
-Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
+**vs. nothing** — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.
 
 ## Updating OpenSpec
 
-1. **Upgrade the package**
-   ```bash
-   npm install -g @fission-ai/openspec@latest
-   ```
-2. **Refresh agent instructions**
-   - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
+**Upgrade the package**
 
-## Experimental Features
-
-<details>
-<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
-
-**Why this exists:**
-- Standard workflow is locked down — you can't tweak instructions or customize
-- When AI output is bad, you can't improve the prompts yourself
-- Same workflow for everyone, no way to match how your team works
-
-**What's different:**
-- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
-- **Granular** — each artifact has its own instructions, test and tweak individually
-- **Customizable** — define your own workflows, artifacts, and dependencies
-- **Fluid** — no phase gates, update any artifact anytime
-
-```
-You can always go back:
-
-  proposal ──→ specs ──→ design ──→ tasks ──→ implement
-     ▲           ▲          ▲                    │
-     └───────────┴──────────┴────────────────────┘
+```bash
+npm install -g @fission-ai/openspec@latest
 ```
 
-| Command | What it does |
-|---------|--------------|
-| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact (based on what's ready) |
-| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
-| `/opsx:apply` | Implement tasks, updating artifacts as needed |
-| `/opsx:archive` | Archive when done |
+**Refresh agent instructions**
 
-**Setup:** `openspec artifact-experimental-setup`
+Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
 
-[Full documentation →](docs/experimental-workflow.md)
+```bash
+openspec update
+```
 
-</details>
+## Usage Notes
 
-<details>
-<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>
+**Model selection**: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.
 
-We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
-
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
-
-</details>
+**Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
 
 ## Contributing
 
+**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+
+**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
+
+When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
+
+**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
+
+### Development
+
 - Install dependencies: `pnpm install`
 - Build: `pnpm run build`
 - Test: `pnpm test`
 - Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
 - Conventional commits (one-line): `type(scope): subject`
 
+## Other
+
+<details>
+<summary><strong>Telemetry</strong></summary>
+
+OpenSpec collects anonymous usage stats.
+
+We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
+
+**Opt-out (any one is enough):**
+- `openspec config set telemetry.enabled false` (global config; unset means on)
+- `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1` (env overrides config)
+
+</details>
+
+<details>
+<summary><strong>Maintainers & Advisors</strong></summary>
+
+See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and advisors who help guide the project.
+
+</details>
+
+
+
 ## License
 
 MIT

README_OLD.md

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

SECURITY.md

@@ -0,0 +1,62 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report privately through [GitHub Security Advisories](https://github.com/Fission-AI/OpenSpec/security/advisories/new). Please don't open a public issue for a suspected vulnerability.
+
+Include what you can: affected version, reproduction steps, and the impact you believe it has. We aim to acknowledge within 3 business days and to ship a fix or a decision within 30 days. Valid reports are credited in the advisory unless you'd rather stay anonymous.
+
+## Supported versions
+
+Fixes ship in the latest published version on npm. Older versions are not patched — upgrade to pick up a fix.
+
+## Threat model
+
+OpenSpec is a local command-line tool. It has no server, no network listener, and no privileged daemon. It reads and writes markdown under the directory you run it in, using paths you supply, with your own user permissions. It can offer to upgrade itself during `openspec update`, and only with your say-so. It sends anonymous usage telemetry, which you can disable with `OPENSPEC_TELEMETRY=0`.
+
+That shapes what is and isn't a vulnerability here:
+
+| In scope | Out of scope |
+| --- | --- |
+| Code execution triggered by parsing a spec, config, or template file | Reading or writing a file path you passed to the CLI yourself |
+| Escaping the directory OpenSpec was pointed at, via untrusted input | Static-analysis findings on file-path joins with no untrusted input |
+| Leaking credentials or file contents through telemetry or logs | Vulnerabilities in devDependencies that don't ship in the published package |
+| Prototype pollution or injection reachable from a config or spec file | Denial of service against your own machine using your own input |
+
+If you think something sits on the boundary, report it and we'll work it out together.
+
+## Published package contents
+
+The `openspec` npm package publishes `dist/`, `bin/`, `schemas/`, and `scripts/postinstall.js`. Build and test tooling (vite, rollup, vitest, eslint, and their transitive dependencies) is not published. Scanners that read `pnpm-lock.yaml` without separating dependency scope will report advisories for packages that never reach an installed copy of OpenSpec.
+
+You do not have to take that on trust — install the package and look:
+
+```sh
+npm install @fission-ai/openspec
+ls node_modules | grep -E '^(vite|rollup|vitest|eslint|js-yaml|minimatch)$'   # no matches
+```
+
+`pnpm audit --prod` in this repository reports the same scope, and CI runs it on every pull request.
+
+## What the CLI does on your machine
+
+| Surface | Behavior |
+| --- | --- |
+| Install script | `scripts/postinstall.js` prints one line suggesting shell completions. It makes no network request, writes no files, and runs no shell. Completions are opt-in via `openspec completion install`. |
+| Running other programs | Every call that goes through a shell uses a fixed literal (`which gh`, `gh auth status`). Anything carrying your input — issue text, editor paths, workset commands, the path passed to `openspec update` — uses an argument array, never string interpolation into a shell. On Windows, `.cmd` shims are launched through `cross-spawn`, which escapes arguments rather than concatenating them. |
+| Installing software | `openspec update` can run `npm install -g @fission-ai/openspec@latest` and then re-run `openspec update` with the upgraded CLI. It does this only after you answer yes to a prompt, only for the OpenSpec package itself, only when npm owns the install, and never in CI or a non-interactive shell. A global install lives outside your project, so it runs with your permissions there and executes whatever lifecycle scripts the published package ships. It then reads the installed binary's version back rather than assuming the upgrade took. Decline and it prints the command for you to run yourself. |
+| Telemetry | Command name, OpenSpec version, and a locally generated random UUID. No file paths, no file contents, no environment, no hostname, and IP capture is explicitly disabled. Opt out with `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1`; it is off in CI automatically. |
+| Network | Telemetry when enabled, and one npm registry request during `openspec update` to check whether a newer CLI has been published. That request sends no data about you beyond what any HTTP request reveals, runs once per `openspec update` with nothing cached, and is skipped when `CI` is set to anything but an explicit off-value, under `NODE_ENV=test`, or when `OPENSPEC_NO_UPDATE_CHECK`, `DO_NOT_TRACK=1`, or `OPENSPEC_TELEMETRY=0` is set. Reading, writing, and validating specs is entirely local. |
+
+## Automated checks
+
+| Tool | Covers |
+| --- | --- |
+| [CodeQL](https://github.com/Fission-AI/OpenSpec/security/code-scanning) | Static analysis on every push and pull request to `main` |
+| [Dependabot](https://github.com/Fission-AI/OpenSpec/security/dependabot) | Dependency advisories plus weekly update pull requests for the CLI, the docs site, and CI actions |
+| Dependency review | Blocks a pull request that introduces a high-severity dependency |
+| Secret scanning | Enabled on the repository, including push protection |
+| `pnpm audit` | Published dependencies are audited on every pull request, on pushes to `main`, and weekly. Advisory on pull requests so an unrelated change is not blocked; failing elsewhere, so a new advisory surfaces even when no dependency changed. Build tooling is always advisory. |
+| Pinned actions | Every GitHub Action runs from a commit SHA, so a moved tag cannot change what CI executes |
+
+Alerts are triaged against the threat model above, so a finding in build-only tooling is fixed on the normal update cadence rather than treated as an incident.

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. Or hand the setup to your assistant with the [AI-assisted install prompt](installation.md#install-with-your-ai-assistant).
+
+**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, a prompt that hands setup to your AI assistant, 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 30+ 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,142 @@
+# 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`, `instructions archive`, `new change`, `archive`, `doctor`, `context`, `schemas`) 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 + global `defaultStore` set (`openspec config set defaultStore <id>`) → that store, `source: "global_default"`; a stale id fails with the underlying store error and a `fix` naming `openspec config unset defaultStore`.
+4. No nearest root, no default + registered stores exist → error `no_root_with_registered_stores`.
+5. No root, no default, no stores: commands may treat the cwd as `source: "implicit"`; `doctor`, `context`, `list`, and bulk `validate` instead fail with `no_openspec_root`. `list` preserves the implicit fallback for legacy projects with `openspec/project.md`.
+
+Successful JSON payloads normally embed the root; successful `schemas --json`
+deliberately remains the compatibility bare array documented in §4.13:
+
+```json
+"root": { "path": "/abs/path", "source": "store" | "declared" | "global_default" | "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" }, "isPlanningComplete", "isComplete", "applyRequires", "artifacts": [ {id, outputPath, status: "done"|"skipped"|"ready"|"blocked", requires, missingDeps?} ], "root" }`. `isPlanningComplete` means every non-skipped planning artifact exists; skipped artifacts count as satisfied without being created. It does not mean implementation tasks are complete. `isComplete` is retained as a compatibility alias with the same value. Each artifact's `requires` is its direct dependency ids (present for every status, so the transitive required set is computable even when the artifact is `done`); `missingDeps` appears only when `blocked`. The `artifacts` array is in dependency order, with the schema's `artifacts:` declaration order breaking ties between artifacts that become ready at the same time (never alphabetical), so the first `ready` entry is the artifact to write next; `missingDeps` uses that same order. `"skipped"` marks an artifact whose `generates` path is under `specs/` in a change whose `.openspec.yaml` declares `skip_specs: true`; it satisfies dependencies but must not be created. No active changes: `{ "changes": [], "message", "root" }`, exit 0.
+
+### 4.5 `instructions <artifact> --json`
+`{ "changeName", "artifactId", "schemaName", "changeDir", "planningHome"?, "outputPath", "resolvedOutputPath", "existingOutputPaths", "description", "instruction"?, "context"?, "rules"?, "references"?: ReferenceIndexEntry[], "skipped"?, "warning"?, "template", "dependencies": [{id,done,path,description,skipped?}], "unlocks", "root" }`. `unlocks` lists the artifacts this one makes ready, in the schema's declaration order (the same order `status` recommends them). `"skipped": true` (with `"warning"`) appears when the change declares `skip_specs: true` and this artifact is skipped — do not create its files. A dependency entry with `skipped: true` is satisfied without files — do not try to read its paths.
+
+`ReferenceIndexEntry`: `{ "store_id", "root"?, "specs"?: [{id,summary}], "fetch"?, "status": [] }` — resolved entries carry root/specs/fetch; unresolved carry store_id + warning status. Index capped at 50KB (`reference_index_truncated`).
+
+### 4.6 `instructions apply --json`
+`{ "changeName", "changeDir", "schemaName", "contextFiles": { "<artifactId>": ["/abs", ...] }, "progress": {total,complete,remaining}, "tasks": [{id,description,done}], "state": "blocked"|"all_done"|"ready", "missingArtifacts"?, "instruction", "references"?, "context"?, "operationGuidance"?, "root" }`. Both optional fields are read from the selected root on every invocation. `context` is a required prompt-level input whose relevant project facts, conventions, and constraints must be applied; `operationGuidance` is advisory input whose entries are followed only when applicable and compatible with the built-in workflow. Both remain separate from state, tasks, progress, context files, and the built-in instruction.
+
+### 4.7 `instructions archive --json`
+`{ "changeName", "context"?, "operationGuidance"?, "root" }`. Requires a valid `--change` in the resolved repo/store root and uses the same required-context/advisory-guidance semantics as apply. This is a read-only runtime-input surface: it does not return the static archive workflow, inspect or merge delta specs, write main specs, or move the change.
+
+### 4.8 `new change <name> --json`
+Success: `{ "change": { "id", "path", "metadataPath", "schema" }, "root" }`. Failure: `{ "change": null, "status": [d] }`, exit 1.
+
+### 4.9 `archive <name> --json`
+Success: `{ "archive": { "change", "archivedAs": "YYYY-MM-DD-name", "path", "specsUpdated", "totals"?, "warnings"? }, "root" }`. Failure: `{ "archive": null, "root"?, "status": [d] }`, exit 1. `specsUpdated` is true only when at least one spec file was written or retired (a capability whose last requirement the change removed has its spec deleted, which requires `retire_capabilities: true` in the change's `.openspec.yaml`; every retirement is named in `warnings`, with a pasteable Git recovery command only when the spec lived in the caller's checkout); an already-synced change archives with all-zero totals and the skips listed in `warnings`. JSON mode is strictly non-interactive: every prompt point becomes an `archive_*` code.
+
+### 4.10 `doctor --json`
+`{ "root": { "path", "source", "store_id"?, "healthy", "status": [] }, "store": { "id", "metadata": {present,valid,remote?}, "origin_url"?, "drift"?: {ahead,behind}, "status": [] } | null, "references": [...], "status": [] }`. `drift` (present only for a git-backed store checkout that has an upstream tracking ref) is ahead/behind counts against the last-fetched upstream, not the live remote. Health findings of any severity exit 0. Failure payload: `{ "root": null, "store": null, "references": [], "status": [d] }`, exit 1.
+
+### 4.11 `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.12 `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.13 `schemas --json` / `templates --json`
+`schemas`: success remains a bare array `[ {name, description, artifacts, source} ]`; it resolves the canonical root-selection precedence and accepts `--store <id>`. Root-selection failure: `{ "schemas": [], "root": null, "status": [d] }`, exit 1. `templates`: keyed object `{ "<artifactId>": {path, source} }`, still cwd-based with 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), `store_checkout_drift` (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_change_symlink`, `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. `templates` ignores root selection (cwd-based, no `--store`).
+8. Deprecated noun forms (`change`/`spec` subcommands) emit unenveloped payloads without `root`/`status`.

docs/artifact_poc.md

@@ -1,597 +0,0 @@
-# POC-OpenSpec-Core Analysis
-
----
-
-## Design Decisions & Terminology
-
-### Philosophy: Not a Workflow System
-
-This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
-
-| What it's NOT | What it IS |
-|---------------|------------|
-| Linear step-by-step progression | Exploratory, iterative planning |
-| Bureaucratic checkpoints | Enablers that unlock possibilities |
-| "You must complete step 1 first" | "Here's what you could create now" |
-| Form-filling | Fluid document creation |
-
-**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
-
-### Terminology
-
-| Term | Definition | Example |
-|------|------------|---------|
-| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
-| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
-| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
-| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
-
-### Hierarchy
-
-```
-Schema (defines) ──→ Artifacts (guided by) ──→ Templates
-```
-
-- **Schema** = the artifact graph (what exists, dependencies)
-- **Artifact** = a document to produce
-- **Template** = instructions for creating that artifact
-
-### Schema Variations
-
-Schemas can vary across multiple dimensions:
-
-| Dimension | Examples |
-|-----------|----------|
-| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
-| Version | `v1`, `v2`, `v3` |
-| Language | `en`, `zh`, `es` |
-| Custom | `team-alpha`, `experimental` |
-
-### Schema Resolution (XDG Standard)
-
-Schemas follow the XDG Base Directory Specification with a 2-level resolution:
-
-```
-1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # Global user override
-2. <package>/schemas/<name>/schema.yaml                    # Built-in defaults
-```
-
-**Platform-specific paths:**
-- Unix/macOS: `~/.local/share/openspec/schemas/`
-- Windows: `%LOCALAPPDATA%/openspec/schemas/`
-- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set)
-
-**Why XDG?**
-- Schemas are workflow definitions (data), not user preferences (config)
-- Built-ins baked into package, never auto-copied
-- Users customize by creating files in global data dir
-- Consistent with modern CLI tooling standards
-
-### Template Inheritance (2 Levels Max)
-
-Templates are co-located with schemas in a `templates/` subdirectory:
-
-```
-1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
-2. <package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
-```
-
-**Rules:**
-- User overrides take precedence over package built-ins
-- A CLI command shows resolved paths (no guessing)
-- No inheritance between schemas (copy if you need to diverge)
-- Templates are always co-located with their schema
-
-**Why this matters:**
-- Avoids "where does this come from?" debugging
-- No implicit magic that works until it doesn't
-- Schema + templates form a cohesive unit
-
----
-
-## Executive Summary
-
-This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
-
-The system answers:
-- "What artifacts exist for this change?"
-- "What could I create next?" (not "what must I create")
-- "What's blocking X?" (informational, not prescriptive)
-
----
-
-## Core Components
-
-### 1. ArtifactGraph (Slice 1 - COMPLETE)
-
-The dependency graph engine with XDG-compliant schema resolution.
-
-| Responsibility | Approach |
-|----------------|----------|
-| Model artifacts as a DAG | Artifact with `requires: string[]` |
-| Track completion state | `Set<string>` for completed artifacts |
-| Calculate build order | Kahn's algorithm (topological sort) |
-| Find ready artifacts | Check if all dependencies are in `completed` set |
-| Resolve schemas | XDG global → package built-ins |
-
-**Key Data Structures (Zod-validated):**
-
-```typescript
-// Zod schemas define types + validation
-const ArtifactSchema = z.object({
-  id: z.string().min(1),
-  generates: z.string().min(1),      // e.g., "proposal.md" or "specs/*.md"
-  description: z.string(),
-  template: z.string(),              // path to template file
-  requires: z.array(z.string()).default([]),
-});
-
-const SchemaYamlSchema = z.object({
-  name: z.string().min(1),
-  version: z.number().int().positive(),
-  description: z.string().optional(),
-  artifacts: z.array(ArtifactSchema).min(1),
-});
-
-// Derived types
-type Artifact = z.infer<typeof ArtifactSchema>;
-type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
-```
-
-**Key Methods:**
-- `resolveSchema(name)` - Load schema with XDG fallback
-- `ArtifactGraph.fromSchema(schema)` - Build graph from schema
-- `detectState(graph, changeDir)` - Scan filesystem for completion
-- `getNextArtifacts(graph, completed)` - Find artifacts ready to create
-- `getBuildOrder(graph)` - Topological sort of all artifacts
-- `getBlocked(graph, completed)` - Artifacts with unmet dependencies
-
----
-
-### 2. Change Utilities (Slice 2)
-
-Simple utility functions for programmatic change creation. No class, no abstraction layer.
-
-| Responsibility | Approach |
-|----------------|----------|
-| Create changes | Create dirs under `openspec/changes/<name>/` with README |
-| Name validation | Enforce kebab-case naming |
-
-**Key Paths:**
-
-```
-openspec/changes/<name>/   → Change instances with artifacts (project-level)
-```
-
-**Key Functions** (`src/utils/change-utils.ts`):
-- `createChange(projectRoot, name, description?)` - Create new change directory + README
-- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }`
-
-**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is.
-
----
-
-### 3. InstructionLoader (Slice 3)
-
-Template resolution and instruction enrichment.
-
-| Responsibility | Approach |
-|----------------|----------|
-| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) |
-| Build dynamic context | Gather dependency status, change info |
-| Enrich templates | Inject context into base templates |
-| Generate status reports | Formatted markdown with progress |
-
-**Key Class - ChangeState:**
-
-```
-ChangeState {
-  changeName: string
-  changeDir: string
-  graph: ArtifactGraph
-  completed: Set<string>
-
-  // Methods
-  getNextSteps(): string[]
-  getStatus(artifactId): ArtifactStatus
-  isComplete(): boolean
-}
-```
-
-**Key Functions:**
-- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback
-- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
-- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
-
----
-
-### 4. CLI (Slice 4)
-
-User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
-
-| Command | Function | Status |
-|---------|----------|--------|
-| `status --change <id>` | Show change progress (artifact graph) | **NEW** |
-| `next --change <id>` | Show artifacts ready to create | **NEW** |
-| `instructions <artifact> --change <id>` | Get enriched instructions for artifact | **NEW** |
-| `list` | List all changes | EXISTS (`openspec change list`) |
-| `new <name>` | Create change | **NEW** (uses `createChange()`) |
-| `init` | Initialize structure | EXISTS (`openspec init`) |
-| `templates --change <id>` | Show resolved template paths | **NEW** |
-
-**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
-
-**Existing CLI commands** (not part of this slice):
-- `openspec change list` / `openspec change show <id>` / `openspec change validate <id>`
-- `openspec list --changes` / `openspec list --specs`
-- `openspec view` (dashboard)
-- `openspec init` / `openspec archive <change>`
-
----
-
-### 5. Claude Commands
-
-Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
-
-| Command | Purpose |
-|---------|---------|
-| `/status` | Show change progress |
-| `/next` | Show what's ready to create |
-| `/run [artifact]` | Execute a specific step (power users) |
-| `/list` | List all changes |
-| `/new <name>` | Create a new change |
-| `/init` | Initialize structure |
-
-**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
-1. Infers change from conversation (confirms if uncertain)
-2. Infers artifact from request
-3. Calls CLI with explicit `--change` parameter
-4. Creates artifact following instructions
-
-This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
-
-**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
-
----
-
-## Component Dependency Graph
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     PRESENTATION LAYER                       │
-│  ┌──────────────┐                    ┌────────────────────┐ │
-│  │     CLI      │ ←─shell exec───────│ Claude Commands    │ │
-│  └──────┬───────┘                    └────────────────────┘ │
-└─────────┼───────────────────────────────────────────────────┘
-          │ imports
-          ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    ORCHESTRATION LAYER                       │
-│  ┌────────────────────┐        ┌──────────────────────────┐ │
-│  │ InstructionLoader  │        │  change-utils (Slice 2)  │ │
-│  │    (Slice 3)       │        │  createChange()          │ │
-│  └─────────┬──────────┘        │  validateChangeName()    │ │
-│            │                   └──────────────────────────┘ │
-└────────────┼────────────────────────────────────────────────┘
-             │ uses
-             ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      CORE LAYER                              │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │               ArtifactGraph (Slice 1)                │   │
-│  │                                                      │   │
-│  │  Schema Resolution (XDG) ──→ Graph ──→ State Detection│   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-             ▲
-             │ reads from
-             ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   PERSISTENCE LAYER                          │
-│  ┌──────────────────┐   ┌────────────────────────────────┐  │
-│  │  XDG Schemas     │   │  Project Artifacts             │  │
-│  │  ~/.local/share/ │   │  openspec/changes/<name>/      │  │
-│  │  openspec/       │   │  - proposal.md, design.md      │  │
-│  │  schemas/        │   │  - specs/*.md, tasks.md        │  │
-│  └──────────────────┘   └────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Key Design Patterns
-
-### 1. Filesystem as Database
-
-No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
-
-```
-// State detection is just file existence checking
-if (exists(artifactPath)) {
-  completed.add(artifactId)
-}
-```
-
-### 2. Deterministic CLI, Inferring Agent
-
-**CLI layer:** Always deterministic - requires explicit `--change` parameter.
-
-```
-openspec status --change add-auth     # explicit, works
-openspec status                        # error: "No change specified"
-```
-
-**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
-
-This separation means:
-- CLI is pure, testable, no state to corrupt
-- Agent handles all "smartness"
-- No config.yaml tracking of "active change"
-
-### 3. XDG-Compliant Schema Resolution
-
-```
-${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
-    ↓ (not found)
-<package>/schemas/<name>/schema.yaml                    # Built-in
-    ↓ (not found)
-Error (schema not found)
-```
-
-### 4. Two-Level Template Fallback
-
-```
-${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
-    ↓ (not found)
-<package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
-    ↓ (not found)
-Error (no silent fallback to avoid confusion)
-```
-
-### 5. Glob Pattern Support
-
-`specs/*.md` allows multiple files to satisfy a single artifact:
-
-```
-if (artifact.generates.includes("*")) {
-  const parentDir = changeDir / patternParts[0]
-  if (exists(parentDir) && hasFiles(parentDir)) {
-    completed.add(artifactId)
-  }
-}
-```
-
-### 6. Stateless State Detection
-
-Every command re-scans the filesystem. No cached state to corrupt.
-
----
-
-## Artifact Pipeline (Default Schema)
-
-The default `spec-driven` schema:
-
-```
-┌──────────┐
-│ proposal │  (no dependencies)
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│  specs   │  (requires: proposal)
-└────┬─────┘
-     │
-     ├──────────────┐
-     ▼              ▼
-┌──────────┐   ┌──────────┐
-│  design  │   │          │
-│          │◄──┤ proposal │
-└────┬─────┘   └──────────┘
-     │         (requires: proposal, specs)
-     ▼
-┌──────────┐
-│  tasks   │  (requires: design)
-└──────────┘
-```
-
-Other schemas (TDD, prototype-first) would have different graphs.
-
----
-
-## Implementation Order
-
-Structured as **vertical slices** - each slice is independently testable.
-
----
-
-### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE
-
-**Delivers:** Types + Graph + State Detection + Schema Resolution
-
-**Implementation:** `src/core/artifact-graph/`
-- `types.ts` - Zod schemas and derived TypeScript types
-- `schema.ts` - YAML parsing with Zod validation
-- `graph.ts` - ArtifactGraph class with topological sort
-- `state.ts` - Filesystem-based state detection
-- `resolver.ts` - XDG-compliant schema resolution
-- `builtin-schemas.ts` - Package-bundled default schemas
-
-**Key decisions made:**
-- Zod for schema validation (consistent with project)
-- XDG for global schema overrides
-- `Set<string>` for completion state (immutable, functional)
-- `inProgress` and `failed` states deferred (require external tracking)
-
----
-
-### Slice 2: "Change Creation Utilities"
-
-**Delivers:** Utility functions for programmatic change creation
-
-**Scope:**
-- `createChange(projectRoot, name, description?)` → creates directory + README
-- `validateChangeName(name)` → kebab-case pattern enforcement
-
-**Not in scope (already exists in CLI commands):**
-- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()`
-- `getChangePath()` → simple `path.join()` inline
-- `changeExists()` → simple `fs.access()` inline
-- `isInitialized()` → simple directory check inline
-
-**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation.
-
----
-
-### Slice 3: "Get Instructions" (Enrichment)
-
-**Delivers:** Template resolution + context injection
-
-**Testable behaviors:**
-- Template fallback: schema-specific → shared → built-in → error
-- Context injection: completed deps show ✓, missing show ✗
-- Output path shown correctly based on change directory
-
----
-
-### Slice 4: "CLI + Integration"
-
-**Delivers:** New artifact graph commands (builds on existing CLI)
-
-**New commands:**
-- `status --change <id>` - Show artifact completion state
-- `next --change <id>` - Show ready-to-create artifacts
-- `instructions <artifact> --change <id>` - Get enriched template
-- `templates --change <id>` - Show resolved paths
-- `new <name>` - Create change (wrapper for `createChange()`)
-
-**Already exists (not in scope):**
-- `openspec change list/show/validate` - change management
-- `openspec list --changes/--specs` - listing
-- `openspec view` - dashboard
-- `openspec init` - initialization
-
-**Testable behaviors:**
-- Each new command produces expected output
-- Commands compose correctly (status → next → instructions flow)
-- Error handling for missing changes, invalid artifacts, etc.
-
----
-
-## Directory Structure
-
-```
-# Global (XDG paths - user overrides)
-~/.local/share/openspec/           # Unix/macOS ($XDG_DATA_HOME/openspec/)
-%LOCALAPPDATA%/openspec/           # Windows
-└── schemas/                       # Schema overrides
-    └── custom-workflow/           # User-defined schema directory
-        ├── schema.yaml            # Schema definition
-        └── templates/             # Co-located templates
-            └── proposal.md
-
-# Package (built-in defaults)
-<package>/
-└── schemas/                       # Built-in schema definitions
-    ├── spec-driven/               # Default: proposal → specs → design → tasks
-    │   ├── schema.yaml
-    │   └── templates/
-    │       ├── proposal.md
-    │       ├── design.md
-    │       ├── spec.md
-    │       └── tasks.md
-    └── tdd/                       # TDD: tests → implementation → docs
-        ├── schema.yaml
-        └── templates/
-            ├── test.md
-            ├── implementation.md
-            ├── spec.md
-            └── docs.md
-
-# Project (change instances)
-openspec/
-└── changes/                       # Change instances
-    ├── add-auth/
-    │   ├── README.md              # Auto-generated on creation
-    │   ├── proposal.md            # Created artifacts
-    │   ├── design.md
-    │   └── specs/
-    │       └── *.md
-    ├── refactor-db/
-    │   └── ...
-    └── archive/                   # Completed changes
-        └── 2025-01-01-add-auth/
-
-.claude/
-├── settings.local.json            # Permissions
-└── commands/                      # Slash commands
-    └── *.md
-```
-
----
-
-## Schema YAML Format
-
-```yaml
-# Built-in: <package>/schemas/spec-driven/schema.yaml
-# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
-name: spec-driven
-version: 1
-description: Specification-driven development
-
-artifacts:
-  - id: proposal
-    generates: "proposal.md"
-    description: "Create project proposal document"
-    template: "proposal.md"          # resolves from co-located templates/ directory
-    requires: []
-
-  - id: specs
-    generates: "specs/*.md"          # glob pattern
-    description: "Create technical specification documents"
-    template: "specs.md"
-    requires:
-      - proposal
-
-  - id: design
-    generates: "design.md"
-    description: "Create design document"
-    template: "design.md"
-    requires:
-      - proposal
-      - specs
-
-  - id: tasks
-    generates: "tasks.md"
-    description: "Create tasks breakdown document"
-    template: "tasks.md"
-    requires:
-      - design
-```
-
----
-
-## Summary
-
-| Layer | Component | Responsibility | Status |
-|-------|-----------|----------------|--------|
-| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
-| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
-| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
-| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
-| Integration | Claude Commands | AI assistant glue | Slice 4 |
-
-**What already exists (not in this proposal):**
-- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
-- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
-- `ListCommand.execute()` in `src/core/list.ts`
-- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
-- `src/core/init.ts` - initialization
-- `src/core/archive.ts` - archiving
-
-**Key Principles:**
-- **Filesystem IS the database** - stateless, version-control friendly
-- **Dependencies are enablers** - show what's possible, don't force order
-- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
-- **XDG-compliant paths** - schemas and templates use standard user data directories
-- **2-level inheritance** - user override → package built-in (no deeper)
-- **Schemas are versioned** - support variations by philosophy, version, language

docs/commands.md

@@ -0,0 +1,766 @@
+# Commands
+
+This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Devin Desktop).
+
+For workflow patterns and when to use each command, see [Workflows](workflows.md). For CLI commands, see [CLI](cli.md).
+
+These pages use `/opsx:<command>` as the canonical name. Some tools spell it
+differently — Cursor and GitHub Copilot register `/opsx-propose`, Codex uses
+`$openspec-propose` — so check [How To Invoke](supported-tools.md#how-to-invoke)
+for your tool. The files OpenSpec generates already use the right form.
+
+## Quick Reference
+
+### Default Quick Path (`core` profile)
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:propose` | Create a change and generate planning artifacts in one step |
+| `/opsx:explore` | Think through ideas before committing to a change |
+| `/opsx:apply` | Implement tasks from the change |
+| `/opsx: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:**
+```
+/opsx:explore [topic]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `topic` | No | What you want to explore or investigate |
+
+**What it does:**
+- Opens an exploratory conversation with no structure required
+- Investigates the codebase to answer questions
+- Compares options and approaches
+- Creates visual diagrams to clarify thinking
+- Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
+
+**Example:**
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: How should we handle authentication for the mobile app?
+
+AI:  Let me investigate your current auth setup...
+     [Analyzes codebase]
+
+     I see you're using session-based auth for the web app.
+     For mobile, we have three main options:
+
+     1. JWT tokens (stateless, works offline)
+     2. OAuth2 (if you need third-party login)
+     3. Extend current sessions (simpler, but requires connectivity)
+
+     Your API already has CORS configured. Which direction interests you?
+
+You: Let's go with JWT. Can we start a change for that?
+
+AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
+```
+
+**Tips:**
+- Use when requirements are unclear or you need to investigate
+- No artifacts are created during exploration
+- Good for comparing multiple approaches before deciding
+- Can read files and search the codebase
+
+---
+
+### `/opsx:new`
+
+Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with `/opsx:continue` or `/opsx:ff`.
+
+This command is part of the expanded workflow set (not included in the default `core` profile).
+
+**Syntax:**
+```
+/opsx:new [change-name] [--schema <schema-name>]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Name for the change folder (prompted if not provided) |
+| `--schema` | No | Workflow schema to use (default: from config or `spec-driven`) |
+
+**What it does:**
+- Creates `openspec/changes/<change-name>/` directory
+- Creates `.openspec.yaml` metadata file in the change folder
+- Shows the first artifact template ready for creation
+- Prompts for change name and schema if not provided
+
+**What it creates:**
+```
+openspec/changes/<change-name>/
+└── .openspec.yaml    # Change metadata (schema, created date)
+```
+
+**Example:**
+```
+You: /opsx:new add-dark-mode
+
+AI:  Created openspec/changes/add-dark-mode/
+     Schema: spec-driven
+
+     Ready to create: proposal
+     Use /opsx:continue to create it, or /opsx:ff to create all artifacts.
+```
+
+**Tips:**
+- Use descriptive names: `add-feature`, `fix-bug`, `refactor-module`
+- Avoid generic names like `update`, `changes`, `wip`
+- Schema can also be set in project config (`openspec/config.yaml`)
+
+---
+
+### `/opsx:continue`
+
+Create the next artifact in the dependency chain. Creates one artifact at a time for incremental progress.
+
+**Syntax:**
+```
+/opsx:continue [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to continue (inferred from context if not provided) |
+
+**What it does:**
+- Queries the artifact dependency graph
+- Shows which artifacts are ready vs blocked
+- Creates the first ready artifact
+- Reads dependency files for context
+- Shows what becomes available after creation
+
+**Example:**
+```
+You: /opsx:continue
+
+AI:  Change: add-dark-mode
+
+     Artifact status:
+     ✓ proposal    (done)
+     ◆ specs       (ready)
+     ◆ design      (ready)
+     ○ tasks       (blocked - needs: specs, design)
+
+     Creating specs...
+
+     [Reads proposal.md, creates specs based on requirements]
+
+     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
+
+     Now available: design
+     Run /opsx:continue to create the next artifact.
+```
+
+**Tips:**
+- Use when you want to review each artifact before proceeding
+- Good for complex changes where you want control
+- Multiple artifacts may become ready simultaneously
+- You can edit created artifacts before continuing
+
+---
+
+### `/opsx:ff`
+
+Fast-forward through artifact creation. Creates all planning artifacts at once.
+
+**Syntax:**
+```
+/opsx:ff [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to fast-forward (inferred from context if not provided) |
+
+**What it does:**
+- Creates all artifacts in dependency order
+- Tracks progress via todo list
+- Stops when all `apply-required` artifacts are complete
+- Reads each dependency before creating the next artifact
+
+**Example:**
+```
+You: /opsx:ff add-dark-mode
+
+AI:  Fast-forwarding add-dark-mode...
+
+     ✓ Creating proposal.md
+     ✓ Creating specs/ui/spec.md
+     ✓ Creating design.md
+     ✓ Creating tasks.md
+
+     All planning artifacts complete!
+     Ready for implementation. Run /opsx:apply to begin.
+```
+
+**Tips:**
+- Use when you have a clear picture of what you're building
+- Faster than `/opsx:continue` for straightforward changes
+- You can still edit artifacts afterward
+- Good for small to medium features
+
+---
+
+### `/opsx:apply`
+
+Implement tasks from the change. Works through the task list, writing code and checking off items.
+
+**Syntax:**
+```
+/opsx:apply [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to implement (inferred from context if not provided) |
+
+**What it does:**
+- Reads `tasks.md` and identifies incomplete tasks
+- Works through tasks one by one
+- Writes code, creates files, runs tests as needed
+- Marks tasks complete with checkboxes `[x]`
+
+**Example:**
+```
+You: /opsx:apply
+
+AI:  Implementing add-dark-mode...
+
+     Reading tasks.md:
+     - [ ] 1.1 Create ThemeContext
+     - [ ] 1.2 Add CSS custom properties
+     - [ ] 1.3 Implement localStorage persistence
+
+     Working on 1.1: Create ThemeContext...
+     [Creates src/context/ThemeContext.tsx]
+
+     ✓ 1.1 Complete
+
+     Working on 1.2: Add CSS custom properties...
+     [Updates src/styles/globals.css]
+
+     ✓ 1.2 Complete
+     ...
+```
+
+**Tips:**
+- Can resume where you left off if interrupted
+- Use for parallel changes by specifying the change name
+- Completion state is tracked in `tasks.md` checkboxes
+
+---
+
+### `/opsx: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.
+
+**Syntax:**
+```
+/opsx:verify [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to verify (inferred from context if not provided) |
+
+**What it does:**
+- Checks three dimensions of implementation quality
+- Searches codebase for implementation evidence
+- Reports issues categorized as CRITICAL, WARNING, or SUGGESTION
+- Does not block archive, but surfaces issues
+
+**Verification dimensions:**
+
+| Dimension | What it validates |
+|-----------|-------------------|
+| **Completeness** | All tasks done, all requirements implemented, scenarios covered |
+| **Correctness** | Implementation matches spec intent, edge cases handled |
+| **Coherence** | Design decisions reflected in code, patterns consistent |
+
+**Example:**
+```
+You: /opsx:verify
+
+AI:  Verifying add-dark-mode...
+
+     COMPLETENESS
+     ✓ All 8 tasks in tasks.md are checked
+     ✓ All requirements in specs have corresponding code
+     ⚠ Scenario "System preference detection" has no test coverage
+
+     CORRECTNESS
+     ✓ Implementation matches spec intent
+     ✓ Edge cases from scenarios are handled
+     ✓ Error states match spec definitions
+
+     COHERENCE
+     ✓ Design decisions reflected in code structure
+     ✓ Naming conventions consistent with design.md
+     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes
+
+     SUMMARY
+     ─────────────────────────────
+     Critical issues: 0
+     Warnings: 2
+     Ready to archive: Yes (with warnings)
+
+     Recommendations:
+     1. Add test for system preference detection
+     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables
+```
+
+**Tips:**
+- Run before archiving to catch mismatches early
+- Warnings don't block archive but indicate potential issues
+- Good for reviewing AI's work before committing
+- Can reveal drift between artifacts and implementation
+
+---
+
+### `/opsx:sync`
+
+**Optional command.** Merge delta specs from a change into main specs. Archive will prompt to sync if needed, so you typically don't need to run this manually.
+
+**Syntax:**
+```
+/opsx:sync [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to sync (inferred from context if not provided) |
+
+**What it does:**
+- Reads delta specs from change folder
+- Parses ADDED/MODIFIED/REMOVED/RENAMED sections
+- Merges changes into main `openspec/specs/` directory
+- Preserves existing content not mentioned in delta
+- Does not archive the change (remains active)
+
+**Example:**
+```text
+You: /opsx:sync
+
+AI:  Syncing add-dark-mode delta specs...
+
+     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
+     Target:  openspec/specs/ui/spec.md
+
+     Changes to apply:
+     ✓ ADDED: Theme Selection requirement (2 scenarios)
+     ✓ ADDED: Accessibility requirement (1 scenario)
+
+     Merging...
+     ✓ openspec/specs/ui/spec.md updated
+
+     Change remains active. Run /opsx:archive when ready to complete.
+```
+
+**When to use manually:**
+
+| Scenario | Use sync? |
+|----------|-----------|
+| Long-running change, want specs in main before archiving | Yes |
+| Multiple parallel changes need the updated base specs | Yes |
+| Want to preview/review the merge separately | Yes |
+| Quick change, going straight to archive | No (archive handles it) |
+
+**Tips:**
+- Sync is intelligent, not copy-paste
+- Can add scenarios to existing requirements without duplicating
+- Change stays active after sync (not archived)
+- Most users will never need to call this directly—archive prompts if needed
+
+---
+
+### `/opsx:archive`
+
+Archive a completed change. Finalizes the change and moves it to the archive folder.
+
+**Syntax:**
+```
+/opsx:archive [change-name]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Which change to archive (inferred from context if not provided) |
+
+**What it does:**
+- Checks artifact completion status
+- Checks task completion (warns if incomplete)
+- Offers to sync delta specs if not already synced
+- Moves change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
+- Preserves all artifacts for audit trail
+
+**Example:**
+```text
+You: /opsx:archive
+
+AI:  Archiving add-dark-mode...
+
+     Artifact status:
+     ✓ proposal.md exists
+     ✓ specs/ exists
+     ✓ design.md exists
+     ✓ tasks.md exists (8/8 tasks complete)
+
+     Delta specs: Not yet synced
+     → Sync now? (recommended)
+
+You: Yes
+
+AI:  ✓ Synced specs to openspec/specs/ui/spec.md
+     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
+
+     Change archived successfully.
+```
+
+**Tips:**
+- Archive won't block on incomplete tasks, but will warn
+- Delta specs can be synced during archive or beforehand
+- Archived changes are preserved for history
+- Use `/opsx:verify` first to catch issues
+
+---
+
+### `/opsx:bulk-archive`
+
+Archive multiple completed changes at once. Handles spec conflicts between changes.
+
+**Syntax:**
+```
+/opsx:bulk-archive [change-names...]
+```
+
+**Arguments:**
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-names` | No | Specific changes to archive (prompts to select if not provided) |
+
+**What it does:**
+- Lists all completed changes
+- Validates each change before archiving
+- Detects spec conflicts across changes
+- Resolves conflicts by checking what's actually implemented
+- Archives in chronological order
+
+**Example:**
+```
+You: /opsx:bulk-archive
+
+AI:  Found 3 completed changes:
+     - add-dark-mode (8/8 tasks complete)
+     - fix-login-bug (3/3 tasks complete)
+     - update-footer (2/2 tasks complete)
+
+     Checking for spec conflicts...
+     ⚠ add-dark-mode and update-footer both touch specs/ui/
+
+     Inspecting codebase to resolve...
+     Both changes are implemented. Will merge in chronological order:
+     1. add-dark-mode (created Jan 20)
+     2. update-footer (created Jan 22)
+
+     Archive all 3 changes?
+
+You: Yes
+
+AI:  ✓ Archived add-dark-mode
+     ✓ Archived fix-login-bug
+     ✓ Archived update-footer
+     Specs merged: add-dark-mode → update-footer
+```
+
+**Tips:**
+- Good for parallel work streams
+- Conflict resolution is agentic (checks codebase)
+- Changes are archived in order of creation
+- Prompts before overwriting spec content
+
+---
+
+### `/opsx:onboard`
+
+Guided onboarding through the complete OpenSpec workflow. An interactive tutorial using your actual codebase.
+
+**Syntax:**
+```
+/opsx:onboard
+```
+
+**What it does:**
+- Walks through a complete workflow cycle with narration
+- Scans your codebase for real improvement opportunities
+- Creates an actual change with real artifacts
+- Implements actual work (small, safe changes)
+- Archives the completed change
+- Explains each step as it happens
+
+**Phases:**
+1. Welcome and codebase analysis
+2. Finding an improvement opportunity
+3. Creating a change (`/opsx:new`)
+4. Writing the proposal
+5. Creating specs
+6. Writing the design
+7. Creating tasks
+8. Implementing tasks (`/opsx:apply`)
+9. Verifying implementation
+10. Archiving the change
+11. Summary and next steps
+
+**Example:**
+```
+You: /opsx:onboard
+
+AI:  Welcome to OpenSpec!
+
+     I'll walk you through the complete workflow using your actual codebase.
+     We'll find something small to improve, create a proper change for it,
+     implement it, and archive it.
+
+     Let me scan your codebase for opportunities...
+
+     [Analyzes codebase]
+
+     I found a few things we could work on:
+     1. Add input validation to the contact form
+     2. Improve error messages in the auth flow
+     3. Add loading states to async buttons
+
+     Which interests you? (or suggest something else)
+```
+
+**Tips:**
+- Best for new users learning the workflow
+- Uses real code, not toy examples
+- Creates a real change you can keep or discard
+- Takes 15-30 minutes to complete
+
+---
+
+## Command Syntax by AI Tool
+
+Different AI tools use slightly different command syntax. Use the format that matches your tool:
+
+| Your tool's command file | Syntax example | Example tools |
+|--------------------------|----------------|---------------|
+| `.../commands/opsx/<id>.*` | `/opsx:propose`, `/opsx:apply` | Claude Code, Gemini CLI, Crush |
+| `.../opsx-<id>.*` | `/opsx-propose`, `/opsx-apply` | Cursor, Devin Desktop, Copilot (IDE), Trae, Oh My Pi |
+| none — skills only | `/openspec-propose`, `/openspec-apply-change` | CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, shared `.agents` |
+| none — Kimi Code | `/skill:openspec-propose` | Kimi Code |
+| none — Codex CLI | `$openspec-propose` | Codex |
+
+> **Devin Desktop vs Devin Local:** the `.devin/workflows/opsx-*.md` files give
+> Devin Desktop `/opsx-propose`. Devin Local has no workflows — use the skills
+> OpenSpec writes to `.devin/skills/`, e.g. `/openspec-propose`, which work on
+> both agents.
+
+The intent is the same across tools, but how commands are surfaced can differ by integration. [How To Invoke](supported-tools.md#how-to-invoke) lists every supported tool; this table shows only examples of each shape.
+
+> **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds.
+
+---
+
+## Legacy Commands
+
+These commands use the older "all-at-once" workflow. They still work but OPSX commands are recommended.
+
+| Command | What it does |
+|---------|--------------|
+| `/openspec:proposal` | Create all artifacts at once (proposal, specs, design, tasks) |
+| `/openspec:apply` | Implement the change |
+| `/openspec:archive` | Archive the change |
+
+**When to use legacy commands:**
+- Existing projects using the old workflow
+- Simple changes where you don't need incremental artifact creation
+- Preference for the all-or-nothing approach
+
+**Migrating to OPSX:**
+Legacy changes can be continued with OPSX commands. The artifact structure is compatible.
+
+---
+
+## Troubleshooting
+
+### "Change not found"
+
+The command couldn't identify which change to work on.
+
+**Solutions:**
+- Specify the change name explicitly: `/opsx:apply add-dark-mode`
+- Check that the change folder exists: `openspec list`
+- Verify you're in the right project directory
+
+### "No artifacts ready"
+
+All artifacts are either complete or blocked by missing dependencies.
+
+**Solutions:**
+- Run `openspec status --change <name>` to see what's blocking
+- Check if required artifacts exist
+- Create missing dependency artifacts first
+
+### "Schema not found"
+
+The specified schema doesn't exist.
+
+**Solutions:**
+- List available schemas: `openspec schemas`
+- Check spelling of schema name
+- Create the schema if it's custom: `openspec schema init <name>`
+
+### Commands not recognized
+
+The AI tool doesn't recognize OpenSpec commands.
+
+**Solutions:**
+- Ensure OpenSpec is initialized: `openspec init`
+- Regenerate skills: `openspec update`
+- Check that `.claude/skills/` directory exists (for Claude Code)
+- Restart your AI tool to pick up new skills
+
+### Artifacts not generating properly
+
+The AI creates incomplete or incorrect artifacts.
+
+**Solutions:**
+- Add project context in `openspec/config.yaml`
+- Add per-artifact rules for specific guidance
+- Provide more detail in your change description
+- Use `/opsx:continue` instead of `/opsx:ff` for more control
+
+---
+
+## Next Steps
+
+- [Workflows](workflows.md) - Common patterns and when to use each command
+- [CLI](cli.md) - Terminal commands for management and validation
+- [Customization](customization.md) - Create custom schemas and workflows

docs/concepts.md

@@ -0,0 +1,629 @@
+# Concepts
+
+This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see [Getting Started](getting-started.md) and [Workflows](workflows.md).
+
+## Philosophy
+
+OpenSpec is built around four principles:
+
+```
+fluid not rigid         — no phase gates, work on what makes sense
+iterative not waterfall — learn as you build, refine as you go
+easy not complex        — lightweight setup, minimal ceremony
+brownfield-first        — works with existing codebases, not just greenfield
+```
+
+### Why These Principles Matter
+
+**Fluid not rigid.** Traditional spec systems lock you into phases: first you plan, then you implement, then you're done. OpenSpec is more flexible — you can create artifacts in any order that makes sense for your work.
+
+**Iterative not waterfall.** Requirements change. Understanding deepens. What seemed like a good approach at the start might not hold up after you see the codebase. OpenSpec embraces this reality.
+
+**Easy not complex.** Some spec frameworks require extensive setup, rigid formats, or heavyweight processes. OpenSpec stays out of your way. Initialize in seconds, start working immediately, customize only if you need to.
+
+**Brownfield-first.** Most software work isn't building from scratch — it's modifying existing systems. OpenSpec's delta-based approach makes it easy to specify changes to existing behavior, not just describe new systems.
+
+## The Big Picture
+
+OpenSpec organizes your work into two main areas:
+
+```
+┌────────────────────────────────────────────────────────────────────┐
+│                        openspec/                                   │
+│                                                                    │
+│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
+│   │       specs/        │      │         changes/              │   │
+│   │                     │      │                               │   │
+│   │  Source of truth    │◄─────│  Proposed modifications       │   │
+│   │  How your system    │ merge│  Each change = one folder     │   │
+│   │  currently works    │      │  Contains artifacts + deltas  │   │
+│   │                     │      │                               │   │
+│   └─────────────────────┘      └───────────────────────────────┘   │
+│                                                                    │
+└────────────────────────────────────────────────────────────────────┘
+```
+
+**Specs** are the source of truth — they describe how your system currently behaves.
+
+**Changes** are proposed modifications — they live in separate folders until you're ready to merge them.
+
+This separation is key. You can work on multiple changes in parallel without conflicts. You can review a change before it affects the main specs. And when you archive a change, its deltas merge cleanly into the source of truth.
+
+## Specs
+
+Specs describe your system's behavior using structured requirements and scenarios.
+
+### Structure
+
+```
+openspec/specs/
+├── auth/
+│   └── spec.md           # Authentication behavior
+├── payments/
+│   └── spec.md           # Payment processing
+├── notifications/
+│   └── spec.md           # Notification system
+└── ui/
+    └── spec.md           # UI behavior and themes
+```
+
+Organize specs by domain — logical groupings that make sense for your system. Common patterns:
+
+- **By feature area**: `auth/`, `payments/`, `search/`
+- **By component**: `api/`, `frontend/`, `workers/`
+- **By bounded context**: `ordering/`, `fulfillment/`, `inventory/`
+
+### Spec Format
+
+A spec contains requirements, and each requirement has scenarios:
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management for the application.
+
+## Requirements
+
+### Requirement: User Authentication
+The system SHALL issue a JWT token upon successful login.
+
+#### Scenario: Valid credentials
+- GIVEN a user with valid credentials
+- WHEN the user submits login form
+- THEN a JWT token is returned
+- AND the user is redirected to dashboard
+
+#### Scenario: Invalid credentials
+- GIVEN invalid credentials
+- WHEN the user submits login form
+- THEN an error message is displayed
+- AND no token is issued
+
+### Requirement: Session Expiration
+The system MUST expire sessions after 30 minutes of inactivity.
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass without activity
+- THEN the session is invalidated
+- AND the user must re-authenticate
+```
+
+**Key elements:**
+
+| Element | Purpose |
+|---------|---------|
+| `## Purpose` | High-level description of this spec's domain |
+| `### Requirement:` | A specific behavior the system must have |
+| `#### Scenario:` | A concrete example of the requirement in action |
+| SHALL/MUST/SHOULD | RFC 2119 keywords indicating requirement strength |
+
+### Why Structure Specs This Way
+
+**Requirements are the "what"** — they state what the system should do without specifying implementation.
+
+**Scenarios are the "when"** — they provide concrete examples that can be verified. Good scenarios:
+- Are testable (you could write an automated test for them)
+- Cover both happy path and edge cases
+- Use Given/When/Then or similar structured format
+
+**RFC 2119 keywords** (SHALL, MUST, SHOULD, MAY) communicate intent:
+- **MUST/SHALL** — absolute requirement
+- **SHOULD** — recommended, but exceptions exist
+- **MAY** — optional
+
+### What a Spec Is (and Is Not)
+
+A spec is a **behavior contract**, not an implementation plan.
+
+Good spec content:
+- Observable behavior users or downstream systems rely on
+- Inputs, outputs, and error conditions
+- External constraints (security, privacy, reliability, compatibility)
+- Scenarios that can be tested or explicitly validated
+
+Avoid in specs:
+- Internal class/function names
+- Library or framework choices
+- Step-by-step implementation details
+- Detailed execution plans (those belong in `design.md` or `tasks.md`)
+
+Quick test:
+- If implementation can change without changing externally visible behavior, it likely does not belong in the spec.
+
+### Keep It Lightweight: Progressive Rigor
+
+OpenSpec aims to avoid bureaucracy. Use the lightest level that still makes the change verifiable.
+
+**Lite spec (default):**
+- Short behavior-first requirements
+- Clear scope and non-goals
+- A few concrete acceptance checks
+
+**Full spec (for higher risk):**
+- Cross-team or cross-repo changes
+- API/contract changes, migrations, security/privacy concerns
+- Changes where ambiguity is likely to cause expensive rework
+
+Most changes should stay in Lite mode.
+
+### Human + Agent Collaboration
+
+In many teams, humans explore and agents draft artifacts. The intended loop is:
+
+1. Human provides intent, context, and constraints.
+2. Agent converts this into behavior-first requirements and scenarios.
+3. Agent keeps implementation detail in `design.md` and `tasks.md`, not `spec.md`.
+4. Validation confirms structure and clarity before implementation.
+
+This keeps specs readable for humans and consistent for agents.
+
+## Changes
+
+A change is a proposed modification to your system, packaged as a folder with everything needed to understand and implement it.
+
+### Change Structure
+
+```
+openspec/changes/add-dark-mode/
+├── proposal.md           # Why and what
+├── design.md             # How (technical approach)
+├── tasks.md              # Implementation checklist
+├── .openspec.yaml        # Change metadata (optional): schema, created, skip_specs, retire_capabilities
+└── specs/                # Delta specs
+    └── ui/
+        └── spec.md       # What's changing in ui/spec.md
+```
+
+Each change is self-contained. It has:
+- **Artifacts** — documents that capture intent, design, and tasks
+- **Delta specs** — specifications for what's being added, modified, or removed
+- **Metadata** — optional configuration for this specific change
+
+### Why Changes Are Folders
+
+Packaging a change as a folder has several benefits:
+
+1. **Everything together.** Proposal, design, tasks, and specs live in one place. No hunting through different locations.
+
+2. **Parallel work.** Multiple changes can exist simultaneously without conflicting. Work on `add-dark-mode` while `fix-auth-bug` is also in progress.
+
+3. **Clean history.** When archived, changes move to `changes/archive/` with their full context preserved. You can look back and understand not just what changed, but why.
+
+4. **Review-friendly.** A change folder is easy to review — open it, read the proposal, check the design, see the spec deltas.
+
+## Artifacts
+
+Artifacts are the documents within a change that guide the work.
+
+### The Artifact Flow
+
+```
+proposal ──────► specs ──────► design ──────► tasks ──────► implement
+    │               │             │              │
+   why            what           how          steps
+ + scope        changes       approach      to take
+```
+
+Artifacts build on each other. Each artifact provides context for the next.
+
+### Artifact Types
+
+#### Proposal (`proposal.md`)
+
+The proposal captures **intent**, **scope**, and **approach** at a high level.
+
+```markdown
+# Proposal: Add Dark Mode
+
+## Intent
+Users have requested a dark mode option to reduce eye strain
+during nighttime usage and match system preferences.
+
+## Scope
+In scope:
+- Theme toggle in settings
+- System preference detection
+- Persist preference in localStorage
+
+Out of scope:
+- Custom color themes (future work)
+- Per-page theme overrides
+
+## Approach
+Use CSS custom properties for theming with a React context
+for state management. Detect system preference on first load,
+allow manual override.
+```
+
+**When to update the proposal:**
+- Scope changes (narrowing or expanding)
+- Intent clarifies (better understanding of the problem)
+- Approach fundamentally shifts
+
+#### Specs (delta specs in `specs/`)
+
+Delta specs describe **what's changing** relative to the current specs. See [Delta Specs](#delta-specs) below.
+
+#### Design (`design.md`)
+
+The design captures **technical approach** and **architecture decisions**.
+
+````markdown
+# Design: Add Dark Mode
+
+## Technical Approach
+Theme state managed via React Context to avoid prop drilling.
+CSS custom properties enable runtime switching without class toggling.
+
+## Architecture Decisions
+
+### Decision: Context over Redux
+Using React Context for theme state because:
+- Simple binary state (light/dark)
+- No complex state transitions
+- Avoids adding Redux dependency
+
+### Decision: CSS Custom Properties
+Using CSS variables instead of CSS-in-JS because:
+- Works with existing stylesheet
+- No runtime overhead
+- Browser-native solution
+
+## Data Flow
+```
+ThemeProvider (context)
+       │
+       ▼
+ThemeToggle ◄──► localStorage
+       │
+       ▼
+CSS Variables (applied to :root)
+```
+
+## File Changes
+- `src/contexts/ThemeContext.tsx` (new)
+- `src/components/ThemeToggle.tsx` (new)
+- `src/styles/globals.css` (modified)
+````
+
+**When to update the design:**
+- Implementation reveals the approach won't work
+- Better solution discovered
+- Dependencies or constraints change
+
+#### Tasks (`tasks.md`)
+
+Tasks are the **implementation checklist** — concrete steps with checkboxes.
+
+```markdown
+# Tasks
+
+## 1. Theme Infrastructure
+- [ ] 1.1 Create ThemeContext with light/dark state
+- [ ] 1.2 Add CSS custom properties for colors
+- [ ] 1.3 Implement localStorage persistence
+- [ ] 1.4 Add system preference detection
+
+## 2. UI Components
+- [ ] 2.1 Create ThemeToggle component
+- [ ] 2.2 Add toggle to settings page
+- [ ] 2.3 Update Header to include quick toggle
+
+## 3. Styling
+- [ ] 3.1 Define dark theme color palette
+- [ ] 3.2 Update components to use CSS variables
+- [ ] 3.3 Test contrast ratios for accessibility
+```
+
+**Task best practices:**
+- Group related tasks under headings
+- Use hierarchical numbering (1.1, 1.2, etc.)
+- Keep tasks small enough to complete in one session
+- Check tasks off as you complete them
+
+## Delta Specs
+
+Delta specs are the key concept that makes OpenSpec work for brownfield development. They describe **what's changing** rather than restating the entire spec.
+
+### The Format
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST support TOTP-based two-factor authentication.
+
+#### Scenario: 2FA enrollment
+- GIVEN a user without 2FA enabled
+- WHEN the user enables 2FA in settings
+- THEN a QR code is displayed for authenticator app setup
+- AND the user must verify with a code before activation
+
+#### Scenario: 2FA login
+- GIVEN a user with 2FA enabled
+- WHEN the user submits valid credentials
+- THEN an OTP challenge is presented
+- AND login completes only after valid OTP
+
+## MODIFIED Requirements
+
+### Requirement: Session Expiration
+The system MUST expire sessions after 15 minutes of inactivity.
+(Previously: 30 minutes)
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 15 minutes pass without activity
+- THEN the session is invalidated
+
+## REMOVED Requirements
+
+### Requirement: Remember Me
+(Deprecated in favor of 2FA. Users should re-authenticate each session.)
+```
+
+### Delta Sections
+
+| Section | Meaning | What Happens on Archive |
+|---------|---------|------------------------|
+| `## ADDED Requirements` | New behavior | Appended to main spec |
+| `## MODIFIED Requirements` | Changed behavior | Replaces existing requirement |
+| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec; removing the last requirement retires the capability and deletes its spec file, when the change declares `retire_capabilities: true` |
+| `## Purpose` | What a brand-new capability is for | Seeds the Purpose of the main spec being created; ignored when the spec already exists |
+
+### Why Deltas Instead of Full Specs
+
+**Clarity.** A delta shows exactly what's changing. Reading a full spec, you'd have to diff it mentally against the current version.
+
+**Conflict avoidance.** Two changes can touch the same spec file without conflicting, as long as they modify different requirements.
+
+**Review efficiency.** Reviewers see the change, not the unchanged context. Focus on what matters.
+
+**Brownfield fit.** Most work modifies existing behavior. Deltas make modifications first-class, not an afterthought.
+
+## Schemas
+
+Schemas define the artifact types and their dependencies for a workflow.
+
+### How Schemas Work
+
+```yaml
+# openspec/schemas/spec-driven/schema.yaml
+name: spec-driven
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    requires: []              # No dependencies, can create first
+
+  - id: specs
+    generates: specs/**/*.md
+    requires: [proposal]      # Needs proposal before creating
+
+  - id: design
+    generates: design.md
+    requires: [proposal]      # Can create in parallel with specs
+
+  - id: tasks
+    generates: tasks.md
+    requires: [specs, design] # Needs both specs and design first
+```
+
+**Artifacts form a dependency graph:**
+
+```
+                    proposal
+                   (root node)
+                       │
+         ┌─────────────┴─────────────┐
+         │                           │
+         ▼                           ▼
+      specs                       design
+   (requires:                  (requires:
+    proposal)                   proposal)
+         │                           │
+         └─────────────┬─────────────┘
+                       │
+                       ▼
+                    tasks
+                (requires:
+                specs, design)
+```
+
+**Dependencies are enablers, not gates.** They show what's possible to create, not what you must create next. You can skip design if you don't need it. You can create specs before or after design — both depend only on proposal.
+
+### Built-in Schemas
+
+**spec-driven** (default)
+
+The standard workflow for spec-driven development:
+
+```
+proposal → specs → design → tasks → implement
+```
+
+Best for: Most feature work where you want to agree on specs before implementation.
+
+### Custom Schemas
+
+Create custom schemas for your team's workflow:
+
+```bash
+# Create from scratch
+openspec schema init research-first
+
+# Or fork an existing one
+openspec schema fork spec-driven research-first
+```
+
+**Example custom schema:**
+
+```yaml
+# openspec/schemas/research-first/schema.yaml
+name: research-first
+artifacts:
+  - id: research
+    generates: research.md
+    requires: []           # Do research first
+
+  - id: proposal
+    generates: proposal.md
+    requires: [research]   # Proposal informed by research
+
+  - id: tasks
+    generates: tasks.md
+    requires: [proposal]   # Skip specs/design, go straight to tasks
+```
+
+See [Customization](customization.md) for full details on creating and using custom schemas.
+
+## Archive
+
+Archiving completes a change by merging its delta specs into the main specs and preserving the change for history.
+
+### What Happens When You Archive
+
+```
+Before archive:
+
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md ◄────────────────┐
+└── changes/                         │
+    └── add-2fa/                     │
+        ├── proposal.md              │
+        ├── design.md                │ merge
+        ├── tasks.md                 │
+        └── specs/                   │
+            └── auth/                │
+                └── spec.md ─────────┘
+
+
+After archive:
+
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md        # Now includes 2FA requirements
+└── changes/
+    └── archive/
+        └── 2025-01-24-add-2fa/    # Preserved for history
+            ├── proposal.md
+            ├── design.md
+            ├── tasks.md
+            └── specs/
+                └── auth/
+                    └── spec.md
+```
+
+### The Archive Process
+
+1. **Merge deltas.** Each delta spec section (ADDED/MODIFIED/REMOVED) is applied to the corresponding main spec.
+
+2. **Move to archive.** The change folder moves to `changes/archive/` with a date prefix for chronological ordering.
+
+3. **Preserve context.** All artifacts remain intact in the archive. You can always look back to understand why a change was made.
+
+### Why Archive Matters
+
+**Clean state.** Active changes (`changes/`) shows only work in progress. Completed work moves out of the way.
+
+**Audit trail.** The archive preserves the full context of every change — not just what changed, but the proposal explaining why, the design explaining how, and the tasks showing the work done.
+
+**Spec evolution.** Specs grow organically as changes are archived. Each archive merges its deltas, building up a comprehensive specification over time.
+
+## How It All Fits Together
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                              OPENSPEC FLOW                                   │
+│                                                                              │
+│   ┌────────────────┐                                                         │
+│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
+│   │     CHANGE     │                                                         │
+│   └───────┬────────┘                                                         │
+│           │                                                                  │
+│           ▼                                                                  │
+│   ┌────────────────┐                                                         │
+│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
+│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
+│   │                │  (based on schema dependencies)                         │
+│   └───────┬────────┘                                                         │
+│           │                                                                  │
+│           ▼                                                                  │
+│   ┌────────────────┐                                                         │
+│   │  3. IMPLEMENT  │  /opsx:apply                                            │
+│   │     TASKS      │  Work through tasks, checking them off                  │
+│   │                │◄──── Update artifacts as you learn                      │
+│   └───────┬────────┘                                                         │
+│           │                                                                  │
+│           ▼                                                                  │
+│   ┌────────────────┐                                                         │
+│   │  4. VERIFY     │  /opsx:verify (optional)                                │
+│   │     WORK       │  Check implementation matches specs                     │
+│   └───────┬────────┘                                                         │
+│           │                                                                  │
+│           ▼                                                                  │
+│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
+│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
+│   │     CHANGE     │     │  Change folder moves to archive/             │    │
+│   └────────────────┘     │  Specs are now the updated source of truth   │    │
+│                          └──────────────────────────────────────────────┘    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+**The virtuous cycle:**
+
+1. Specs describe current behavior
+2. Changes propose modifications (as deltas)
+3. Implementation makes the changes real
+4. Archive merges deltas into specs
+5. Specs now describe the new behavior
+6. Next change builds on updated specs
+
+## Glossary
+
+| Term | Definition |
+|------|------------|
+| **Artifact** | A document within a change (proposal, design, tasks, or delta specs) |
+| **Archive** | The process of completing a change and merging its deltas into main specs |
+| **Change** | A proposed modification to the system, packaged as a folder with artifacts |
+| **Delta spec** | A spec that describes changes (ADDED/MODIFIED/REMOVED) relative to current specs |
+| **Domain** | A logical grouping for specs (e.g., `auth/`, `payments/`) |
+| **Requirement** | A specific behavior the system must have |
+| **Scenario** | A concrete example of a requirement, typically in Given/When/Then format |
+| **Schema** | A definition of artifact types and their dependencies |
+| **Spec** | A specification describing system behavior, containing requirements and scenarios |
+| **Source of truth** | The `openspec/specs/` directory, containing the current agreed-upon behavior |
+
+## Next Steps
+
+- [Getting Started](getting-started.md) - Practical first steps
+- [Workflows](workflows.md) - Common patterns and when to use each
+- [Commands](commands.md) - Full command reference
+- [Customization](customization.md) - Create custom schemas and configure your project

docs/customization.md

@@ -0,0 +1,433 @@
+# Customization
+
+OpenSpec provides three levels of customization:
+
+| Level | What it does | Best for |
+|-------|--------------|----------|
+| **Project Config** | Set defaults, inject context/rules | Most teams |
+| **Custom Schemas** | Define your own workflow artifacts | Teams with unique processes |
+| **Global Overrides** | Share schemas across all projects | Power users |
+
+---
+
+## Project Configuration
+
+The `openspec/config.yaml` file is the easiest way to customize OpenSpec for your team. It lets you:
+
+- **Set a default schema** - Skip `--schema` on every command
+- **Inject project context** - AI sees your tech stack, conventions, etc.
+- **Add per-artifact rules** - Custom rules for specific artifacts
+- **Add per-operation guidance** - Advisory preferences for apply and archive work
+- **Remember integration choices** - e.g. the [GitHub Copilot cloud coding agent](supported-tools.md#github-copilot-cloud-coding-agent) opt-in
+
+### Quick Setup
+
+```bash
+openspec init
+```
+
+This walks you through creating a config interactively. Or create one manually:
+
+```yaml
+# openspec/config.yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js, PostgreSQL
+  API style: RESTful, documented in docs/api.md
+  Testing: Jest + React Testing Library
+  We value backwards compatibility for all public APIs
+
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams
+  specs:
+    - Use Given/When/Then format
+    - Reference existing patterns before inventing new ones
+
+operations:
+  apply:
+    guidance:
+      - Run focused tests before the full suite
+  archive:
+    guidance:
+      - Keep the completion summary concise
+
+# Set by `openspec init` when you choose (or decline) the GitHub Copilot
+# cloud coding agent; controls whether `init`/`update` generate its files.
+githubCopilot:
+  cloudAgent: false
+```
+
+### How It Works
+
+**Default schema:**
+
+```bash
+# Without config
+openspec new change my-feature --schema spec-driven
+
+# With config - schema is automatic
+openspec new change my-feature
+```
+
+**Context and rules injection:**
+
+When generating any artifact, your context and rules are injected into the AI prompt:
+
+```xml
+<context>
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+...
+</context>
+
+<rules>
+- Include rollback plan
+- Identify affected teams
+</rules>
+
+<template>
+[Schema's built-in template]
+</template>
+```
+
+- **Context** appears in ALL artifacts
+- **Rules** ONLY appear for the matching artifact
+
+**Operation guidance:**
+
+`operations.apply.guidance` and `operations.archive.guidance` are optional arrays
+of advisory instructions for how an agent should conduct those operations. They
+are separate from `rules`: operation guidance does not constrain artifact content,
+and artifact rules are never relabeled as operation guidance.
+
+Apply and archive fetch these inputs at execution time:
+
+```bash
+openspec instructions apply --change my-feature --json
+openspec instructions archive --change my-feature --json
+```
+
+Both surfaces return current project `context` and matching
+`operationGuidance` as separate optional fields. Each invocation reads a fresh
+snapshot from the resolved root. When `--store <id>` is selected, the change,
+context, and guidance all come from that store rather than the current repository.
+The archive instruction command is read-only: it does not inspect or merge delta
+specs, write main specs, move the change, or run the static archive workflow.
+
+Project context is a required prompt-level input. Generated workflows read it and
+apply relevant project facts, conventions, and constraints. Operation guidance is
+optional additive advice: workflows consider every entry and follow entries that
+are applicable and compatible with the built-in workflow.
+
+Both fields remain separate from CLI-controlled state, resolved paths, built-in
+steps, explicit user choices, and artifact rules. A workflow reports context
+conflicts while preserving the controlling value. It does not follow inapplicable
+or conflicting guidance and explains why. Neither field is an enforceable check,
+and workflows do not copy their text into implementation files, specs, change
+artifacts, or summaries unless the user separately requests that content.
+
+**Archive and spec-sync input safety:**
+
+Archive, bulk archive, and standalone sync use
+`artifactPaths.specs.existingOutputPaths` from `openspec status --json` as the
+only delta-spec source. A schema without a `specs` artifact, or a change whose
+concrete output list is empty, has nothing to sync; other artifacts are not used
+to infer delta specs.
+
+Before a semantic merge writes a main spec, the workflow consumes current
+`openspec instructions specs --change <name> --json` output. The returned
+`specs` rules constrain only the main specs produced by that merge. Single archive
+passes that snapshot into inline sync, standalone sync fetches it directly, and
+bulk archive obtains every required snapshot before its first spec write. A
+non-zero or invalid JSON archive/specs instruction response is a lookup failure,
+not an empty input: the workflow stops before the affected spec write or change
+move (for bulk archive, before any batch write or move).
+
+This configuration does not change archive execution phases, user prompts,
+filesystem operations, semantic merge ownership, the direct `openspec archive`
+command, or the structure and output of artifact `rules`.
+
+### Schema Resolution Order
+
+When OpenSpec needs a schema, it checks in this order:
+
+1. CLI flag: `--schema <name>`
+2. Change metadata (`.openspec.yaml` in the change folder)
+3. Project config (`openspec/config.yaml`)
+4. Default (`spec-driven`)
+
+---
+
+## Custom Schemas
+
+When project config isn't enough, create your own schema with a completely custom workflow. Custom schemas live in your project's `openspec/schemas/` directory and are version-controlled with your code.
+
+```text
+your-project/
+├── openspec/
+│   ├── config.yaml        # Project config
+│   ├── schemas/           # Custom schemas live here
+│   │   └── my-workflow/
+│   │       ├── schema.yaml
+│   │       └── templates/
+│   └── changes/           # Your changes
+└── src/
+```
+
+### Fork an Existing Schema
+
+The fastest way to customize is to fork a built-in schema:
+
+```bash
+openspec schema fork spec-driven my-workflow
+```
+
+This copies the entire `spec-driven` schema to `openspec/schemas/my-workflow/` where you can edit it freely.
+
+**What you get:**
+
+```text
+openspec/schemas/my-workflow/
+├── schema.yaml           # Workflow definition
+└── templates/
+    ├── proposal.md       # Template for proposal artifact
+    ├── spec.md           # Template for specs
+    ├── design.md         # Template for design
+    └── tasks.md          # Template for tasks
+```
+
+Now edit `schema.yaml` to change the workflow, or edit templates to change what AI generates.
+
+### Create a Schema from Scratch
+
+For a completely fresh workflow:
+
+```bash
+# Interactive
+openspec schema init research-first
+
+# Non-interactive
+openspec schema init rapid \
+  --description "Rapid iteration workflow" \
+  --artifacts "proposal,tasks" \
+  --default
+```
+
+### Schema Structure
+
+A schema defines the artifacts in your workflow and how they depend on each other:
+
+```yaml
+# openspec/schemas/my-workflow/schema.yaml
+name: my-workflow
+version: 1
+description: My team's custom workflow
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document
+    template: proposal.md
+    instruction: |
+      Create a proposal that explains WHY this change is needed.
+      Focus on the problem, not the solution.
+    requires: []
+
+  - id: design
+    generates: design.md
+    description: Technical design
+    template: design.md
+    instruction: |
+      Create a design document explaining HOW to implement.
+    requires:
+      - proposal    # Can't create design until proposal exists
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist
+    template: tasks.md
+    requires:
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+```
+
+**Key fields:**
+
+| Field | Purpose |
+|-------|---------|
+| `id` | Unique identifier, used in commands and rules |
+| `generates` | Output filename (supports globs like `specs/**/*.md`) |
+| `template` | Template file in `templates/` directory |
+| `instruction` | AI instructions for creating this artifact |
+| `requires` | Dependencies - which artifacts must exist first |
+
+List artifacts in the order you want them written. `requires` decides what is
+possible; the order of the `artifacts:` list decides what comes first when
+several artifacts are ready at once.
+
+### Templates
+
+Templates are markdown files that guide the AI. They're injected into the prompt when creating that artifact.
+
+```markdown
+<!-- templates/proposal.md -->
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities or modifications. -->
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->
+```
+
+Templates can include:
+- Section headers the AI should fill in
+- HTML comments with guidance for the AI
+- Example formats showing expected structure
+
+### Validate Your Schema
+
+Before using a custom schema, validate it:
+
+```bash
+openspec schema validate my-workflow
+```
+
+This checks:
+- `schema.yaml` syntax is correct
+- All referenced templates exist
+- No circular dependencies
+- Artifact IDs are valid
+
+### Use Your Custom Schema
+
+Once created, use your schema with:
+
+```bash
+# Specify on command
+openspec new change feature --schema my-workflow
+
+# Or set as default in config.yaml
+schema: my-workflow
+```
+
+### Debug Schema Resolution
+
+Not sure which schema is being used? Check with:
+
+```bash
+# See where a specific schema resolves from
+openspec schema which my-workflow
+
+# List all available schemas
+openspec schema which --all
+```
+
+Output shows whether it's from your project, user directory, or the package:
+
+```text
+Schema: my-workflow
+Source: project
+Path: /path/to/project/openspec/schemas/my-workflow
+```
+
+---
+
+> **Note:** OpenSpec also supports user-level schemas at `~/.local/share/openspec/schemas/` for sharing across projects, but project-level schemas in `openspec/schemas/` are recommended since they're version-controlled with your code.
+
+---
+
+## Examples
+
+### Rapid Iteration Workflow
+
+A minimal workflow for quick iterations:
+
+```yaml
+# openspec/schemas/rapid/schema.yaml
+name: rapid
+version: 1
+description: Fast iteration with minimal overhead
+
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Quick proposal
+    template: proposal.md
+    instruction: |
+      Create a brief proposal for this change.
+      Focus on what and why, skip detailed specs.
+    requires: []
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist
+    template: tasks.md
+    requires: [proposal]
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+```
+
+### Adding a Review Artifact
+
+Fork the default and add a review step:
+
+```bash
+openspec schema fork spec-driven with-review
+```
+
+Then edit `schema.yaml` to add:
+
+```yaml
+  - id: review
+    generates: review.md
+    description: Pre-implementation review checklist
+    template: review.md
+    instruction: |
+      Create a review checklist based on the design.
+      Include security, performance, and testing considerations.
+    requires:
+      - design
+
+  - id: tasks
+    # ... existing tasks config ...
+    requires:
+      - specs
+      - design
+      - review    # Now tasks require review too
+```
+
+---
+
+## Community Schemas
+
+OpenSpec also supports community-maintained schemas distributed via standalone repositories. These provide opinionated workflows that integrate OpenSpec with other tools or systems, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) works for spec-kit.
+
+Community schemas are not vendored into OpenSpec core — they live in their own repositories with their own release cadence. To use one, copy the schema bundle into your project's `openspec/schemas/<schema-name>/` directory (each repo's README has install instructions).
+
+| Schema | Maintainer | Repository | Description |
+|--------|-----------|-----------|-------------|
+| `intent-driven` | @harikrishnan83 | [intent-driven-dev/openspec-schemas](https://github.com/intent-driven-dev/openspec-schemas/tree/main/openspec/schemas/intent-driven) | Captures change intent, observable behaviour, technical design, and durable architectural decisions before implementation. Adds a change-local ADR review manifest and writes qualifying long-lived decisions as immutable, supersedable ADRs. |
+| `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. |
+| `nanopm` | @nmrtn | [nmrtn/nanopm](https://github.com/nmrtn/nanopm/tree/main/openspec-schema) | PM-first workflow. Runs [nanopm](https://github.com/nmrtn/nanopm)'s planning pipeline (audit → strategy → roadmap → PRD) upstream of implementation. Bridges product planning to OpenSpec's spec-driven engineering workflow. Artifacts read from `.nanopm/` if present — proposal sources the audit, design sources the strategy, and tasks source the PRD breakdown. |
+| `e2e-runbooks` | @Lukk17 | [Lukk17/openspec-schemas](https://github.com/Lukk17/openspec-schemas/tree/master/openspec/schemas/e2e-runbooks) | Capability-level end-to-end test runbooks. Each capability gets an immutable spec, an immutable tasks-template, and one timestamped run record per execution. Assertions are observable behaviour only (HTTP status, response body, persisted state — never log substrings); each run records start/end UTC, duration, and best-estimate LLM token consumption. |
+| `anvil` | @jikkujoyce | [jikkujoyce/openspec-schemas](https://github.com/jikkujoyce/openspec-schemas/tree/main/schemas/anvil) | Spec-driven workflow with TDD discipline and an adversarial review step. Flow: `proposal` → `specs` → `design` → `review` → `test-plan` → `tasks` → `apply` → `verify`. `review` is written by a fresh-context, read-only reviewer (a second model when one is available) and emits a `VERDICT:` line telling the agent to gate `test-plan`, `tasks`, and `apply`; OpenSpec only checks that artifacts exist, so enforce the gate with your own CI or hook. `test-plan` maps every spec scenario to a named test and doubles as a red/green ledger that `verify` audits. |
+
+> 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,224 @@
+# 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`, `update`, `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.
+```
+
+Declare the empty delta explicitly by setting `skip_specs: true` in the change's `.openspec.yaml`:
+
+```yaml
+schema: spec-driven
+skip_specs: true
+```
+
+Without the marker, `openspec validate` rejects a change with zero deltas (so a forgotten specs phase still gets caught); with it, validation passes and `openspec status` shows the specs stage as explicitly skipped rather than pending. If the refactor turns out to change behavior after all, remove `skip_specs` from `.openspec.yaml` and write the delta specs — validate treats the marker plus spec files as a conflict, so the stale marker can't linger silently.
+
+Archiving a marked change needs no extra flags (there are no deltas to merge). Independently, the `--skip-specs` flag tells the terminal command to skip the spec step explicitly:
+
+```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/experimental-release-plan.md

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

docs/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`, `update`, `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 30+ assistants, including Claude Code, Cursor, Devin Desktop, 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, you used a spelling your tool doesn't register, or the commands aren't installed yet. If the files are missing — or you never set the tool up — run `openspec init`; `openspec update` only refreshes files that already exist. Then restart your assistant and use the form printed under "Getting started" — see [How To Invoke](supported-tools.md#how-to-invoke). [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, and OpenSpec spells them the way your tool loads the file it wrote. A command file named `opsx-propose.md` is typed `/opsx-propose`; one filed under `commands/opsx/` is typed `/opsx:propose`. Tools that take skills instead of commands use the skill name — Codex needs `$openspec-propose`, Kimi Code `/skill:openspec-propose`. The `openspec init` "Getting started" line already prints the right form for the tools you picked; the full table is in [How To Invoke](supported-tools.md#how-to-invoke).
+
+### 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`, `update`, `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 change artifacts preserved. The change moves out of your active list. A change that explicitly declares `retire_capabilities: true` can also delete a main capability spec when it removes that capability's final requirement.
+
+## 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

@@ -0,0 +1,291 @@
+# Getting Started
+
+This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start) or the [Installation guide](installation.md). New to the whole docs set? The [documentation home](README.md) maps everything.
+
+> **Where do I type these commands?** Two places, and mixing them up is the most common early stumble.
+>
+> - `openspec ...` commands (like `openspec init`) run in your **terminal**.
+> - `/opsx:...` commands (like `/opsx:propose`) run in your **AI assistant's chat**, the same box where you'd ask it to write code.
+>
+> There's no separate "interactive mode" to start. You just type the slash command in chat and your assistant takes it from there. Full explanation: [How Commands Work](how-commands-work.md).
+
+## Your First Five Minutes
+
+The whole loop, with each step labeled by where it happens:
+
+```text
+TERMINAL   $ npm install -g @fission-ai/openspec@latest
+TERMINAL   $ cd your-project && openspec init
+AI CHAT      /opsx:explore                    (optional: think it through first)
+AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
+AI CHAT      /opsx:apply                      (AI builds it)
+AI CHAT      /opsx:archive                    (specs updated, change filed away)
+```
+
+Two terminal steps to set up, then you live in chat. The rest of this guide unpacks what each step does and what you'll see.
+
+**Don't want to do the terminal part yourself?** Paste the [setup prompt](installation.md#install-with-your-ai-assistant) into your assistant and it handles both lines, then reports what it created.
+
+> **Not sure what to build yet? Start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your codebase, weighs options, and sharpens a fuzzy idea into a concrete plan, all before any artifact or code exists. When the picture is clear, it hands off to `/opsx:propose`. This is the single best habit for working with an AI that will otherwise confidently build the wrong thing. See the [Explore guide](explore.md).
+
+## How It Works
+
+OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
+
+**Default quick path (core profile):**
+
+```text
+/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
+   (optional)
+```
+
+Start with `/opsx:explore` when you're figuring out what to do, or jump straight to `/opsx:propose` when you already know. Explore is in the default profile, so it's always there when you want it.
+
+**Expanded path (custom workflow selection):**
+
+```text
+/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
+```
+
+The default global profile is `core`, which includes `propose`, `explore`, `apply`, `update`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`.
+
+## What OpenSpec Creates
+
+After running `openspec init`, your project has this structure:
+
+```
+openspec/
+├── specs/              # Source of truth (your system's behavior)
+│   └── <domain>/
+│       └── spec.md
+├── changes/            # Proposed updates (one folder per change)
+│   └── <change-name>/
+│       ├── proposal.md
+│       ├── design.md
+│       ├── tasks.md
+│       └── specs/      # Delta specs (what's changing)
+│           └── <domain>/
+│               └── spec.md
+└── config.yaml         # Project configuration (optional)
+```
+
+**Two key directories:**
+
+- **`specs/`** - The source of truth. These specs describe how your system currently behaves. Organized by domain (e.g., `specs/auth/`, `specs/payments/`).
+
+- **`changes/`** - Proposed modifications. Each change gets its own folder with all related artifacts. When a change is complete, its specs merge into the main `specs/` directory.
+
+## Understanding Artifacts
+
+Each change folder contains artifacts that guide the work:
+
+| Artifact | Purpose |
+|----------|---------|
+| `proposal.md` | The "why" and "what" - captures intent, scope, and approach |
+| `specs/` | Delta specs showing ADDED/MODIFIED/REMOVED requirements |
+| `design.md` | The "how" - technical approach and architecture decisions |
+| `tasks.md` | Implementation checklist with checkboxes |
+
+**Artifacts build on each other:**
+
+```
+proposal ──► specs ──► design ──► tasks ──► implement
+   ▲           ▲          ▲                    │
+   └───────────┴──────────┴────────────────────┘
+            update as you learn
+```
+
+You can always go back and refine earlier artifacts as you learn more during implementation.
+
+## How Delta Specs Work
+
+Delta specs are the key concept in OpenSpec. They show what's changing relative to your current specs.
+
+### The Format
+
+Delta specs use sections to indicate the type of change:
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- GIVEN a user with 2FA enabled
+- WHEN the user submits valid credentials
+- THEN an OTP challenge is presented
+
+## MODIFIED Requirements
+
+### Requirement: Session Timeout
+The system SHALL expire sessions after 30 minutes of inactivity.
+(Previously: 60 minutes)
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass without activity
+- THEN the session is invalidated
+
+## REMOVED Requirements
+
+### Requirement: Remember Me
+(Deprecated in favor of 2FA)
+```
+
+### What Happens on Archive
+
+When you archive a change:
+
+1. **ADDED** requirements are appended to the main spec
+2. **MODIFIED** requirements replace the existing version
+3. **REMOVED** requirements are deleted from the main spec
+
+The change folder moves to `openspec/changes/archive/` for audit history.
+
+## Example: Your First Change
+
+Let's walk through adding dark mode to an application.
+
+### 1. Start the Change (Default)
+
+```text
+You: /opsx:propose add-dark-mode
+
+AI:  Created openspec/changes/add-dark-mode/
+     ✓ proposal.md — why we're doing this, what's changing
+     ✓ specs/       — requirements and scenarios
+     ✓ design.md    — technical approach
+     ✓ tasks.md     — implementation checklist
+     Ready for implementation!
+```
+
+If you've enabled the expanded workflow profile, you can also do this as two steps: `/opsx:new` then `/opsx:ff` (or `/opsx:continue` incrementally).
+
+### 2. What Gets Created
+
+**proposal.md** - Captures the intent:
+
+```markdown
+# Proposal: Add Dark Mode
+
+## Intent
+Users have requested a dark mode option to reduce eye strain
+during nighttime usage.
+
+## Scope
+- Add theme toggle in settings
+- Support system preference detection
+- Persist preference in localStorage
+
+## Approach
+Use CSS custom properties for theming with a React context
+for state management.
+```
+
+**specs/ui/spec.md** - Delta showing new requirements:
+
+```markdown
+# Delta for UI
+
+## ADDED Requirements
+
+### Requirement: Theme Selection
+The system SHALL allow users to choose between light and dark themes.
+
+#### Scenario: Manual toggle
+- GIVEN a user on any page
+- WHEN the user clicks the theme toggle
+- THEN the theme switches immediately
+- AND the preference persists across sessions
+
+#### Scenario: System preference
+- GIVEN a user with no saved preference
+- WHEN the application loads
+- THEN the system's preferred color scheme is used
+```
+
+**tasks.md** - Implementation checklist:
+
+```markdown
+# Tasks
+
+## 1. Theme Infrastructure
+- [ ] 1.1 Create ThemeContext with light/dark state
+- [ ] 1.2 Add CSS custom properties for colors
+- [ ] 1.3 Implement localStorage persistence
+
+## 2. UI Components
+- [ ] 2.1 Create ThemeToggle component
+- [ ] 2.2 Add toggle to settings page
+- [ ] 2.3 Update Header to include quick toggle
+
+## 3. Styling
+- [ ] 3.1 Define dark theme color palette
+- [ ] 3.2 Update components to use CSS variables
+```
+
+### 3. Implement
+
+```
+You: /opsx:apply
+
+AI:  Working through tasks...
+     ✓ 1.1 Created ThemeContext with light/dark state
+     ✓ 1.2 Added CSS custom properties to globals.css
+     ✓ 1.3 Implemented localStorage persistence
+     ✓ 2.1 Created ThemeToggle component
+     ...
+     All tasks complete!
+```
+
+During implementation, if you discover the design needs adjustment, just update the artifact and continue.
+
+### 4. Archive
+
+```
+You: /opsx:archive
+
+AI:  Archiving add-dark-mode...
+     ✓ Merged specs into openspec/specs/ui/spec.md
+     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
+     Done! Ready for the next feature.
+```
+
+Your delta specs are now part of the main specs, documenting how your system works.
+
+## Verifying and Reviewing
+
+Use the CLI to check on your changes:
+
+```bash
+# List active changes
+openspec list
+
+# View change details
+openspec show add-dark-mode
+
+# Validate spec formatting
+openspec validate add-dark-mode
+
+# Interactive dashboard
+openspec view
+```
+
+## Next Steps
+
+- [Explore First](explore.md) - Use `/opsx:explore` to think through an idea before you commit
+- [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`, `update`, `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,173 @@
+# 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, Devin Desktop, 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, Devin Desktop, 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 30+ 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 Devin Desktop 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 spelling follows the file your tool loads.
+
+| Your tool's command file | How you type it | Example tools |
+|--------------------------|-----------------|---------------|
+| `.../commands/opsx/<id>.*` | `/opsx:propose` | Claude Code, Gemini CLI, Crush |
+| `.../opsx-<id>.*` | `/opsx-propose` | Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi |
+| `.amazonq/prompts/opsx-<id>.md` | `@opsx-propose` | Amazon Q Developer |
+| none — skills only | `/openspec-propose` | CodeArts, ForgeCode, Hermes, Mistral Vibe, shared `.agents` |
+| none — Kimi Code | `/skill:openspec-propose` | Kimi Code |
+| none — Codex CLI | `$openspec-propose` | Codex |
+
+Devin is the one tool that spans two rows. Devin Desktop reads
+`.devin/workflows/`, so `/opsx-propose` works there; [Devin Local does
+not](https://docs.devin.ai/desktop/devin-local), so on that agent use the
+`/openspec-propose` skill instead. The skills OpenSpec writes to
+`.devin/skills/` work on both, which is why they reference each other by skill
+name.
+
+Every tool is listed in [How To Invoke](supported-tools.md#how-to-invoke) — that
+table is the authoritative one. Two rows are not slash commands at all: Amazon Q
+loads its files into a prompt library invoked with `@`, and the last three rows
+use the *skill* name, which is not the command id (`/opsx:apply` is the
+`openspec-apply-change` skill).
+
+When in doubt, read the "Getting started" line `openspec init` printed: it already
+uses the form your tools registered. Typing a slash and watching the autocomplete
+works too, for the tools that surface slash commands at all.
+
+## 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 `.cursor/commands/opsx-<id>.md` or `.claude/commands/opsx/<id>.md` — the layout is the tool's, and it decides how you type the command. They're the older per-tool slash command files. Codex does not get generated command files; use `.agents/skills/openspec-*`.
+
+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. On a skills-only tool (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, or the shared `.agents` target) `/opsx` never completes even on a healthy install — try the skill name from the table above instead.
+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:update`: revise a change's planning artifacts and keep them coherent
+- `/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

@@ -0,0 +1,206 @@
+# Installation
+
+## Prerequisites
+
+- **Node.js 20.19.0 or higher** — Check your version: `node --version`
+
+## Install with your AI assistant
+
+Rather not do this by hand? Paste the prompt below into any coding assistant that can run shell commands — Claude Code, Codex, Cursor, Gemini CLI, Copilot, and the rest of the [supported tools](supported-tools.md). It installs the CLI, initializes this project, and reports back what actually happened.
+
+The manual steps below are the source of truth — the prompt just runs them for you. If your assistant stops and hands something back, that's by design: it asks before anything privileged and never edits your shell startup files. Finish those bits yourself with [Package Managers](#package-managers) and [Troubleshooting](troubleshooting.md).
+
+```text
+Install OpenSpec in this project and set it up for me. Follow these steps in
+order, and stop where a step tells you to stop.
+
+1. RUNTIME. Run `node --version`. OpenSpec needs Node.js 20.19.0 or higher. If
+   Node is missing or older, say so and stop — don't install Node, switch
+   versions, or reconfigure my version manager for me.
+
+2. INSTALL. Use whichever package manager is already on my PATH, preferring npm:
+     npm install -g @fission-ai/openspec@latest
+     pnpm add -g @fission-ai/openspec@latest
+     bun add -g @fission-ai/openspec@latest
+     yarn global add @fission-ai/openspec@latest   (Yarn 1.x only)
+   Don't pick based on this project's lockfile — a global install has nothing to
+   do with how this repo's own dependencies are installed. If none of those four
+   is available, stop and tell me — don't improvise an install. (If I'm on Nix,
+   point me at the Nix section of the OpenSpec installation docs instead.)
+   Show me the exact command and let me confirm before you run it; this installs
+   software outside the project, and I may want a different package manager to
+   own it.
+   Stop and ask me again if the install needs sudo or admin rights, fails with a
+   permissions error, or reports that its global bin directory is missing or
+   unconfigured. Never edit my shell startup files (.bashrc, .zshrc, .profile,
+   fish, PowerShell profile), and never run a setup command that edits them for
+   me — show me the change and let me make it.
+
+3. PATH. Run `openspec --version`. If the command isn't found, it may just be
+   missing from this shell: tell me where the package manager installed it and
+   how to add that directory to PATH for my shell and OS, then stop until I
+   confirm. If it prints an older version than the one the install just
+   reported, an earlier copy is shadowing it on PATH — tell me both versions
+   instead of continuing. If I use a version manager, say so rather than editing
+   PATH around it: with nvm or fnm the CLI is tied to the Node version that was
+   active when you installed it, and with asdf or volta a shim may need
+   regenerating.
+
+4. INITIALIZE. Ask me which AI coding tool or tools I use and map each to an id
+   from `openspec init --help` (Copilot is `github-copilot`, Zoo Code is
+   `roocode`). `--tools` takes a comma-separated list, so name all of them.
+   `openspec init --tools <ids>` deletes leftovers from older OpenSpec versions
+   automatically, without asking — including `opsx-*.md` prompt files in my home
+   directory (Codex keeps them in ~/.codex/prompts). Before you run it, look for
+   those: `.../commands/openspec/` folders, OpenSpec marker blocks in files like
+   CLAUDE.md or AGENTS.md, and home-directory `opsx-*.md` prompts. List whatever
+   you find and wait for my go-ahead; if you find nothing, say so and carry on
+   without asking. An existing `openspec/` folder is not a problem — init
+   refreshes it and leaves my specs and changes alone.
+   Confirm I'm in the right folder too: init creates `openspec/` wherever it
+   runs, including inside a monorepo package.
+   Then run: openspec init --tools <ids>
+
+5. REPORT. Don't assume what should exist — tell me what init actually printed:
+   how many skills and/or commands it created and where, the config file line,
+   any "Setup required" note, and what to restart or reload. Some tools are
+   skills-only and correctly create zero command files, so missing commands is
+   not a failure on its own. If init said nothing was generated, relay the fix
+   it suggested instead of retrying. Finish by telling me how to invoke OpenSpec
+   in my tool, and take the exact spelling from the files init created rather
+   than from its summary line: the punctuation differs per tool (/opsx:propose
+   in some, /opsx-propose in others, @opsx-propose in Amazon Q), and tools that
+   get skills instead of commands are invoked by skill name (/openspec-propose,
+   or $openspec-propose in Codex, or /skill:openspec-propose in Kimi Code).
+```
+
+Nothing in the prompt is vendor-specific: it's plain instructions plus the same commands documented on this page. It works on macOS, Linux, and Windows, and it deliberately stops rather than improvising when a step needs your permission. Your assistant does need to be able to run shell commands — a few IDE integrations can't.
+
+## Package Managers
+
+### npm
+
+```bash
+npm install -g @fission-ai/openspec@latest
+```
+
+### pnpm
+
+```bash
+pnpm add -g @fission-ai/openspec@latest
+```
+
+### yarn
+
+```bash
+yarn global add @fission-ai/openspec@latest
+```
+
+Yarn 2 and later (Berry) removed the `global` command. On those versions, install OpenSpec with npm, pnpm, or bun instead — a global CLI doesn't need to share your project's package manager.
+
+### deno
+
+Deno sometimes has issues parsing the @latest tag, but we can specify a version while installing initially.
+If that happens, you could try to change the @latest tag with the version, something like `@^1.3.1`
+
+```bash
+deno install --global \
+  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
+  npm:@fission-ai/openspec@latest
+# or
+deno install --global \
+  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
+  npm:@fission-ai/openspec@^1.3.1
+```
+
+Note: If your subcommands launch external tools, like config edit, feedback, or workspace open, you may need a scoped --allow-run=<program>.
+
+### bun
+
+Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
+You still need Node.js 20.19.0 or higher available on `PATH`.
+
+```bash
+bun add -g @fission-ai/openspec@latest
+```
+
+## Nix
+
+Run OpenSpec directly without installation:
+
+```bash
+nix run github:Fission-AI/OpenSpec -- init
+```
+
+Or install to your profile:
+
+```bash
+nix profile install github:Fission-AI/OpenSpec
+```
+
+Or add to your development environment in `flake.nix`:
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    openspec.url = "github:Fission-AI/OpenSpec";
+  };
+
+  outputs = { nixpkgs, openspec, ... }: {
+    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
+      buildInputs = [ openspec.packages.x86_64-linux.default ];
+    };
+  };
+}
+```
+
+## Verify Installation
+
+```bash
+openspec --version
+```
+
+## Updating
+
+Upgrade the package, then refresh each project's generated files:
+
+```bash
+npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
+openspec update                              # run inside each project
+```
+
+`openspec update` regenerates the skill and command files for the tools you've configured, so your slash commands stay current with the installed version. It also checks whether a newer CLI has been published and offers to upgrade, since upgrading is what makes new workflows available in the first place — see [CLI Reference](cli.md#openspec-update).
+
+## Uninstalling
+
+There's no `openspec uninstall` command, because OpenSpec is just a global package plus some files in your project. Removing it is a few manual steps, and nothing here touches your source code.
+
+**1. Remove the global package:**
+
+```bash
+npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
+```
+
+**2. Remove OpenSpec from a project (optional).** Delete the `openspec/` directory if you no longer want its specs and changes:
+
+```bash
+rm -rf openspec/
+```
+
+Think before you do this: `openspec/specs/` and `openspec/changes/archive/` are your record of how the system behaves and why it changed. If you might want that history, keep the folder (or keep it in git) even after uninstalling.
+
+**3. Remove generated AI tool files (optional).** OpenSpec writes skill and command files into per-tool directories like `.claude/skills/openspec-*/`, `.cursor/commands/opsx-*`, and so on. Delete the `openspec-*` skills and `opsx-*` commands for whichever tools you configured. The exact paths per tool are listed in [Supported Tools](supported-tools.md).
+
+If you also have OpenSpec marker blocks in files like `CLAUDE.md` or `AGENTS.md`, remove those blocks by hand; your own content in those files is yours to keep.
+
+## Next Steps
+
+After installing, initialize OpenSpec in your project:
+
+```bash
+cd your-project
+openspec init
+```
+
+See [Getting Started](getting-started.md) for a full walkthrough.

docs/migration-guide.md

@@ -0,0 +1,604 @@
+# Migrating to OPSX
+
+This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility.
+
+## What's Changing?
+
+OPSX replaces the old phase-locked workflow with a fluid, action-based approach. Here's the key shift:
+
+| Aspect | Legacy | OPSX |
+|--------|--------|------|
+| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:update`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
+| **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice |
+| **Going back** | Awkward phase gates | Natural—update any artifact anytime |
+| **Customization** | Fixed structure | Schema-driven, fully hackable |
+| **Configuration** | `CLAUDE.md` with markers + `project.md` | Clean config in `openspec/config.yaml` |
+
+**The philosophy change:** Work isn't linear. OPSX stops pretending it is.
+
+---
+
+## Before You Begin
+
+### Your Existing Work Is Safe
+
+The migration process is designed with preservation in mind:
+
+- **Active changes in `openspec/changes/`** — Completely preserved. You can continue them with OPSX commands.
+- **Archived changes** — Untouched. Your history remains intact.
+- **Main specs in `openspec/specs/`** — Untouched. These are your source of truth.
+- **Your content in CLAUDE.md, AGENTS.md, etc.** — Preserved. Only the OpenSpec marker blocks are removed; everything you wrote stays.
+
+### What Gets Removed
+
+Only OpenSpec-managed files that are being replaced:
+
+| What | Why |
+|------|-----|
+| Legacy slash command directories/files | Replaced by the new skills system |
+| `openspec/AGENTS.md` | Obsolete workflow trigger |
+| OpenSpec markers in `CLAUDE.md`, `AGENTS.md`, etc. | No longer needed |
+
+**Legacy command locations by tool** (examples—your tool may vary):
+
+- Claude Code: `.claude/commands/openspec/`
+- Cursor: `.cursor/commands/openspec-*.md`
+- Devin Desktop, formerly Windsurf: `.windsurf/workflows/openspec-*.md`
+- Cline: `.clinerules/workflows/openspec-*.md`
+- Roo: `.roo/commands/openspec-*.md`
+- GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
+- Codex: OpenSpec now uses the canonical `.agents/skills/openspec-*` path. OpenSpec-managed `SKILL.md` files under the former `.codex/skills` path are reconciled only after replacements exist; custom files and divergent copies stay in place. If an unmarked `.agents` tree already contains OpenSpec skills, OpenSpec preserves its existing Codex (`$openspec-*`) or generic (`/openspec-*`) rendering instead of guessing from the legacy directory. Select `codex` explicitly with `openspec init` to switch ownership. Legacy prompt cleanup still targets only OpenSpec's allowlisted filenames in `$CODEX_HOME/prompts` or `~/.codex/prompts`.
+- And others (Augment, Continue, Amazon Q, etc.)
+
+The migration detects whichever tools you have configured and cleans up their legacy files.
+
+The removal list may seem long, but these are all files that OpenSpec originally created. Your own content is never deleted.
+
+### What Needs Your Attention
+
+One file requires manual migration:
+
+**`openspec/project.md`** — This file isn't deleted automatically because it may contain project context you've written. You'll need to:
+
+1. Review its contents
+2. Move useful context to `openspec/config.yaml` (see guidance below)
+3. Delete the file when ready
+
+**Why we made this change:**
+
+The old `project.md` was passive—agents might read it, might not, might forget what they read. We found reliability was inconsistent.
+
+The new `config.yaml` context is **actively injected into every OpenSpec planning request**. This means your project conventions, tech stack, and rules are always present when the AI is creating artifacts. Higher reliability.
+
+**The tradeoff:**
+
+Because context is injected into every request, you'll want to be concise. Focus on what really matters:
+- Tech stack and key conventions
+- Non-obvious constraints the AI needs to know
+- Rules that frequently got ignored before
+
+Don't worry about getting it perfect. We're still learning what works best here, and we'll be improving how context injection works as we experiment.
+
+---
+
+## Running the Migration
+
+Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation:
+
+- New installs default to profile `core` (`propose`, `explore`, `apply`, `update`, `sync`, `archive`).
+- Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed.
+
+### Using `openspec init`
+
+Run this if you want to add new tools or reconfigure which tools are set up:
+
+```bash
+openspec init
+```
+
+The init command detects legacy files and guides you through cleanup:
+
+```
+Upgrading to the new OpenSpec
+
+OpenSpec now uses agent skills, the emerging standard across coding
+agents. This simplifies your setup while keeping everything working
+as before.
+
+Files to remove
+No user content to preserve:
+  • .claude/commands/openspec/
+  • openspec/AGENTS.md
+
+Files to update
+OpenSpec markers will be removed, your content preserved:
+  • CLAUDE.md
+  • AGENTS.md
+
+Needs your attention
+  • openspec/project.md
+    We won't delete this file. It may contain useful project context.
+
+    The new openspec/config.yaml has a "context:" section for planning
+    context. This is included in every OpenSpec request and works more
+    reliably than the old project.md approach.
+
+    Review project.md, move any useful content to config.yaml's context
+    section, then delete the file when ready.
+
+? Upgrade and clean up legacy files? (Y/n)
+```
+
+**What happens when you say yes:**
+
+1. Legacy slash command directories are removed
+2. OpenSpec markers are stripped from `CLAUDE.md`, `AGENTS.md`, etc. (your content stays)
+3. `openspec/AGENTS.md` is deleted
+4. New skills are installed in `.claude/skills/`
+5. `openspec/config.yaml` is created with a default schema
+
+### Using `openspec update`
+
+Run this if you just want to migrate and refresh your existing tools to the latest version:
+
+```bash
+openspec update
+```
+
+The update command also detects and cleans up legacy artifacts, then refreshes generated skills/commands to match your current profile and delivery settings.
+
+### Non-Interactive / CI Environments
+
+For scripted migrations:
+
+```bash
+openspec init --force --tools claude
+```
+
+The `--force` flag skips prompts and auto-accepts cleanup.
+
+This includes cleanup of OpenSpec-managed Codex prompt files in the global Codex prompt directory. Cleanup only targets OpenSpec's allowlisted legacy Codex prompt filenames, removes them only after replacement `.agents/skills/openspec-*` skills exist, and preserves all other files.
+
+---
+
+## Migrating project.md to config.yaml
+
+The old `openspec/project.md` was a freeform markdown file for project context. The new `openspec/config.yaml` is structured and—critically—**injected into every planning request** so your conventions are always present when the AI works.
+
+### Before (project.md)
+
+```markdown
+# Project Context
+
+This is a TypeScript monorepo using React and Node.js.
+We use Jest for testing and follow strict ESLint rules.
+Our API is RESTful and documented in docs/api.md.
+
+## Conventions
+
+- All public APIs must maintain backwards compatibility
+- New features should include tests
+- Use Given/When/Then format for specifications
+```
+
+### After (config.yaml)
+
+```yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  Testing: Jest with React Testing Library
+  API: RESTful, documented in docs/api.md
+  We maintain backwards compatibility for all public APIs
+
+rules:
+  proposal:
+    - Include rollback plan for risky changes
+  specs:
+    - Use Given/When/Then format for scenarios
+    - Reference existing patterns before inventing new ones
+  design:
+    - Include sequence diagrams for complex flows
+```
+
+### Key Differences
+
+| project.md | config.yaml |
+|------------|-------------|
+| Freeform markdown | Structured YAML |
+| One blob of text | Separate context and per-artifact rules |
+| Unclear when it's used | Context appears in ALL artifacts; rules appear in matching artifacts only |
+| No schema selection | Explicit `schema:` field sets default workflow |
+
+### What to Keep, What to Drop
+
+When migrating, be selective. Ask yourself: "Does the AI need this for *every* planning request?"
+
+**Good candidates for `context:`**
+- Tech stack (languages, frameworks, databases)
+- Key architectural patterns (monorepo, microservices, etc.)
+- Non-obvious constraints ("we can't use library X because...")
+- Critical conventions that often get ignored
+
+**Move to `rules:` instead**
+- Artifact-specific formatting ("use Given/When/Then in specs")
+- Review criteria ("proposals must include rollback plans")
+- These only appear for the matching artifact, keeping other requests lighter
+
+**Leave out entirely**
+- General best practices the AI already knows
+- Verbose explanations that could be summarized
+- Historical context that doesn't affect current work
+
+### Migration Steps
+
+1. **Create config.yaml** (if not already created by init):
+   ```yaml
+   schema: spec-driven
+   ```
+
+2. **Add your context** (be concise—this goes into every request):
+   ```yaml
+   context: |
+     Your project background goes here.
+     Focus on what the AI genuinely needs to know.
+   ```
+
+3. **Add per-artifact rules** (optional):
+   ```yaml
+   rules:
+     proposal:
+       - Your proposal-specific guidance
+     specs:
+       - Your spec-writing rules
+   ```
+
+4. **Delete project.md** once you've moved everything useful.
+
+**Don't overthink it.** Start with the essentials and iterate. If you notice the AI missing something important, add it. If context feels bloated, trim it. This is a living document.
+
+### Need Help? Use This Prompt
+
+If you're unsure how to distill your project.md, ask your AI assistant:
+
+```
+I'm migrating from OpenSpec's old project.md to the new config.yaml format.
+
+Here's my current project.md:
+[paste your project.md content]
+
+Please help me create a config.yaml with:
+1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
+2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)
+
+Leave out anything generic that AI models already know. Be ruthless about brevity.
+```
+
+The AI will help you identify what's essential vs. what can be trimmed.
+
+---
+
+## The New Commands
+
+Command availability is profile-dependent:
+
+**Default (`core` profile):**
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:propose` | Create a change and generate planning artifacts in one step |
+| `/opsx:explore` | Think through ideas with no structure |
+| `/opsx:apply` | Implement tasks from tasks.md |
+| `/opsx:update` | Revise a change's planning artifacts and keep them coherent |
+| `/opsx:sync` | Merge delta specs into main specs |
+| `/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:bulk-archive` | Archive multiple changes at once |
+| `/opsx:onboard` | Guided end-to-end onboarding workflow |
+
+Enable expanded commands with `openspec config profile`, then run `openspec update`.
+
+### Command Mapping from Legacy
+
+| Legacy | OPSX Equivalent |
+|--------|-----------------|
+| `/openspec:proposal` | `/opsx:propose` (default) or `/opsx:new` then `/opsx:ff` (expanded) |
+| `/openspec:apply` | `/opsx:apply` |
+| `/openspec:archive` | `/opsx:archive` |
+
+### New Capabilities
+
+These capabilities are part of the expanded workflow command set.
+
+**Granular artifact creation:**
+```
+/opsx:continue
+```
+Creates one artifact at a time based on dependencies. Use this when you want to review each step.
+
+**Exploration mode:**
+```
+/opsx:explore
+```
+Think through ideas with a partner before committing to a change.
+
+---
+
+## Understanding the New Architecture
+
+### From Phase-Locked to Fluid
+
+The legacy workflow forced linear progression:
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
+│    PHASE     │      │    PHASE     │      │    PHASE     │
+└──────────────┘      └──────────────┘      └──────────────┘
+
+If you're in implementation and realize the design is wrong?
+Too bad. Phase gates don't let you go back easily.
+```
+
+OPSX uses actions, not phases:
+
+```
+         ┌───────────────────────────────────────────────┐
+         │           ACTIONS (not phases)                │
+         │                                               │
+         │     new ◄──► continue ◄──► apply ◄──► archive │
+         │      │          │           │             │   │
+         │      └──────────┴───────────┴─────────────┘   │
+         │                    any order                  │
+         └───────────────────────────────────────────────┘
+```
+
+### Dependency Graph
+
+Artifacts form a directed graph. Dependencies are enablers, not gates:
+
+```
+                        proposal
+                       (root node)
+                            │
+              ┌─────────────┴─────────────┐
+              │                           │
+              ▼                           ▼
+           specs                       design
+        (requires:                  (requires:
+         proposal)                   proposal)
+              │                           │
+              └─────────────┬─────────────┘
+                            │
+                            ▼
+                         tasks
+                     (requires:
+                     specs, design)
+```
+
+When you run `/opsx:continue`, it checks what's ready and offers the next artifact. You can also create multiple ready artifacts in any order.
+
+### Skills vs Commands
+
+The legacy system used tool-specific command files:
+
+```
+.claude/commands/openspec/
+├── proposal.md
+├── apply.md
+└── archive.md
+```
+
+OPSX uses the emerging **skills** standard:
+
+```
+.claude/skills/
+├── openspec-explore/SKILL.md
+├── openspec-new-change/SKILL.md
+├── openspec-continue-change/SKILL.md
+├── openspec-apply-change/SKILL.md
+└── ...
+```
+
+Skills are recognized across multiple AI coding tools and provide richer metadata.
+
+Codex is skills-only in OPSX. OpenSpec no longer generates Codex custom prompt files; use the generated `.agents/skills/openspec-*` directories instead.
+
+---
+
+## Continuing Existing Changes
+
+Your in-progress changes work seamlessly with OPSX commands.
+
+**Have an active change from the legacy workflow?**
+
+```
+/opsx:apply add-my-feature
+```
+
+OPSX reads the existing artifacts and continues from where you left off.
+
+**Want to add more artifacts to an existing change?**
+
+```
+/opsx:continue add-my-feature
+```
+
+Shows what's ready to create based on what already exists.
+
+**Need to see status?**
+
+```bash
+openspec status --change add-my-feature
+```
+
+---
+
+## The New Config System
+
+### config.yaml Structure
+
+```yaml
+# Required: Default schema for new changes
+schema: spec-driven
+
+# Optional: Project context (max 50KB)
+# Injected into ALL artifact instructions
+context: |
+  Your project background, tech stack,
+  conventions, and constraints.
+
+# Optional: Per-artifact rules
+# Only injected into matching artifacts
+rules:
+  proposal:
+    - Include rollback plan
+  specs:
+    - Use Given/When/Then format
+  design:
+    - Document fallback strategies
+  tasks:
+    - Break into 2-hour maximum chunks
+```
+
+### Schema Resolution
+
+When determining which schema to use, OPSX checks in order:
+
+1. **CLI flag**: `--schema <name>` (highest priority)
+2. **Change metadata**: `.openspec.yaml` in the change directory
+3. **Project config**: `openspec/config.yaml`
+4. **Default**: `spec-driven`
+
+### Available Schemas
+
+| Schema | Artifacts | Best For |
+|--------|-----------|----------|
+| `spec-driven` | proposal → specs → design → tasks | Most projects |
+
+List all available schemas:
+
+```bash
+openspec schemas
+```
+
+### Custom Schemas
+
+Create your own workflow:
+
+```bash
+openspec schema init my-workflow
+```
+
+Or fork an existing one:
+
+```bash
+openspec schema fork spec-driven my-workflow
+```
+
+See [Customization](customization.md) for details.
+
+---
+
+## Troubleshooting
+
+### "Legacy files detected in non-interactive mode"
+
+You're running in a CI or non-interactive environment. Use:
+
+```bash
+openspec init --force
+```
+
+### Commands not appearing after migration
+
+Restart your IDE. Skills are detected at startup.
+
+### "Unknown artifact ID in rules"
+
+Check that your `rules:` keys match your schema's artifact IDs:
+
+- **spec-driven**: `proposal`, `specs`, `design`, `tasks`
+
+Run this to see valid artifact IDs:
+
+```bash
+openspec schemas --json
+```
+
+### Config not being applied
+
+1. Ensure the file is at `openspec/config.yaml` (not `.yml`)
+2. Validate YAML syntax
+3. Config changes take effect immediately—no restart needed
+
+### project.md not migrated
+
+The system intentionally preserves `project.md` because it may contain your custom content. Review it manually, move useful parts to `config.yaml`, then delete it.
+
+### Want to see what would be cleaned up?
+
+Run init and decline the cleanup prompt—you'll see the full detection summary without any changes being made.
+
+---
+
+## Quick Reference
+
+### Files After Migration
+
+```
+project/
+├── openspec/
+│   ├── specs/                    # Unchanged
+│   ├── changes/                  # Unchanged
+│   │   └── archive/              # Unchanged
+│   └── config.yaml               # NEW: Project configuration
+├── .claude/
+│   └── skills/                   # NEW: OPSX skills
+│       ├── openspec-propose/     # default core profile
+│       ├── openspec-explore/
+│       ├── openspec-apply-change/
+│       ├── openspec-update-change/
+│       ├── openspec-sync-specs/
+│       ├── openspec-archive-change/
+│       └── ...                   # expanded profile adds new/continue/ff/etc.
+├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
+└── AGENTS.md                     # OpenSpec markers removed, your content preserved
+```
+
+### What's Gone
+
+- `.claude/commands/openspec/` — replaced by `.claude/skills/`
+- `openspec/AGENTS.md` — obsolete
+- `openspec/project.md` — migrate to `config.yaml`, then delete
+- OpenSpec marker blocks in `CLAUDE.md`, `AGENTS.md`, etc.
+
+### Command Cheatsheet
+
+```text
+/opsx:propose      Start quickly (default core profile)
+/opsx:apply        Implement tasks
+/opsx:archive      Finish and archive
+
+# Expanded workflow (if enabled):
+/opsx:new          Scaffold a change
+/opsx:continue     Create next artifact
+/opsx:ff           Create planning artifacts
+```
+
+---
+
+## Getting Help
+
+- **Discord**: [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
+- **GitHub Issues**: [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
+- **Documentation**: [docs/opsx.md](opsx.md) for the full OPSX reference

docs/multi-language.md

@@ -0,0 +1,115 @@
+# Multi-Language Guide
+
+Configure OpenSpec to generate artifacts in languages other than English.
+
+## Quick Setup
+
+Add a language instruction to your `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+
+  # Your other project context below...
+  Tech stack: TypeScript, React, Node.js
+```
+
+That's it. All generated artifacts will now be in Portuguese.
+
+## Language Examples
+
+### Portuguese (Brazil)
+
+```yaml
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+```
+
+### Spanish
+
+```yaml
+context: |
+  Idioma: Español
+  Todos los artefactos deben escribirse en español.
+```
+
+### Chinese (Simplified)
+
+```yaml
+context: |
+  语言：中文（简体）
+  所有产出物必须用简体中文撰写。
+```
+
+### Japanese
+
+```yaml
+context: |
+  言語：日本語
+  すべての成果物は日本語で作成してください。
+```
+
+### French
+
+```yaml
+context: |
+  Langue : Français
+  Tous les artefacts doivent être rédigés en français.
+```
+
+### German
+
+```yaml
+context: |
+  Sprache: Deutsch
+  Alle Artefakte müssen auf Deutsch verfasst werden.
+```
+
+## Tips
+
+### Handle Technical Terms
+
+Decide how to handle technical terminology:
+
+```yaml
+context: |
+  Language: Japanese
+  Write in Japanese, but:
+  - Keep technical terms like "API", "REST", "GraphQL" in English
+  - Code examples and file paths remain in English
+```
+
+### Combine with Other Context
+
+Language settings work alongside your other project context:
+
+```yaml
+schema: spec-driven
+
+context: |
+  Language: Portuguese (pt-BR)
+  All artifacts must be written in Brazilian Portuguese.
+
+  Tech stack: TypeScript, React 18, Node.js 20
+  Database: PostgreSQL with Prisma ORM
+```
+
+## Verification
+
+To verify your language config is working:
+
+```bash
+# Check the instructions - should show your language context
+openspec instructions proposal --change my-change
+
+# Output will include your language context
+```
+
+## Related Documentation
+
+- [Customization Guide](./customization.md) - Project configuration options
+- [Workflows Guide](./workflows.md) - Full workflow documentation

docs/opsx.md

@@ -1,16 +1,16 @@
-# Experimental Workflow (OPSX)
+# OPSX Workflow
 
-> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/BYjPaKbqMt).
->
-> **Compatibility:** Claude Code only (for now)
+> Feedback welcome on [Discord](https://discord.gg/YctCnvvshC).
 
 ## What Is It?
 
-OPSX is a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
+OPSX is now the standard workflow for OpenSpec.
+
+It's a **fluid, iterative workflow** for OpenSpec changes. No more rigid phases — just actions you can take anytime.
 
 ## Why This Exists
 
-The standard OpenSpec workflow works, but it's **locked down**:
+The legacy OpenSpec workflow works, but it's **locked down**:
 
 - **Instructions are hardcoded** — buried in TypeScript, you can't change them
 - **All-or-nothing** — one big command creates everything, can't test individual pieces
@@ -25,7 +25,7 @@ The standard OpenSpec workflow works, but it's **locked down**:
 4. **Iterate quickly** — change a template, test immediately, no rebuild
 
 ```
-Standard workflow:                    OPSX:
+Legacy workflow:                      OPSX:
 ┌────────────────────────┐           ┌────────────────────────┐
 │  Hardcoded in package  │           │  schema.yaml           │◄── You edit this
 │  (can't change)        │           │  templates/*.md        │◄── Or this
@@ -51,44 +51,124 @@ You're "in planning phase", then "in implementation phase", then "done". But rea
 **OPSX approach:**
 - **Actions, not phases** — create, implement, update, archive — do any of them anytime
 - **Dependencies are enablers** — they show what's possible, not what's required next
-- **Update as you learn** — halfway through implementation? Go back and fix the design. That's normal.
 
 ```
-You can always go back:
-
-     ┌────────────────────────────────────┐
-     │                                    │
-     ▼                                    │
   proposal ──→ specs ──→ design ──→ tasks ──→ implement
-     ▲           ▲          ▲               │
-     │           │          │               │
-     └───────────┴──────────┴───────────────┘
-              update as you learn
 ```
 
 ## Setup
 
 ```bash
-# 1. Make sure you have openspec installed and initialized
+# Make sure you have openspec installed — skills are automatically generated
 openspec init
-
-# 2. Generate the experimental skills
-openspec artifact-experimental-setup
 ```
 
-This creates skills in `.claude/skills/` that Claude Code auto-detects.
+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`, `update`, `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
+
+Project config lets you set defaults and inject project-specific context into all artifacts.
+
+### Creating Config
+
+Config is created during `openspec init`, or manually:
+
+```yaml
+# openspec/config.yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  API conventions: RESTful, JSON responses
+  Testing: Vitest for unit tests, Playwright for e2e
+  Style: ESLint with Prettier, strict TypeScript
+
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams
+  specs:
+    - Use Given/When/Then format for scenarios
+  design:
+    - Include sequence diagrams for complex flows
+```
+
+### Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `schema` | string | Default schema for new changes (e.g., `spec-driven`) |
+| `context` | string | Project context injected into all artifact instructions |
+| `rules` | object | Per-artifact rules, keyed by artifact ID |
+
+### How It Works
+
+**Schema precedence** (highest to lowest):
+1. CLI flag (`--schema <name>`)
+2. Change metadata (`.openspec.yaml` in change directory)
+3. Project config (`openspec/config.yaml`)
+4. Default (`spec-driven`)
+
+**Context injection:**
+- Context is prepended to every artifact's instructions
+- Wrapped in `<context>...</context>` tags
+- Helps AI understand your project's conventions
+
+**Rules injection:**
+- Rules are only injected for matching artifacts
+- Wrapped in `<rules>...</rules>` tags
+- Appear after context, before the template
+
+### Artifact IDs by Schema
+
+**spec-driven** (default):
+- `proposal` — Change proposal
+- `specs` — Specifications
+- `design` — Technical design
+- `tasks` — Implementation tasks
+
+### Config Validation
+
+- Unknown artifact IDs in `rules` generate warnings
+- Schema names are validated against available schemas
+- Context has a 50KB size limit
+- Invalid YAML is reported with line numbers
+
+### Troubleshooting
+
+**"Unknown artifact ID in rules: X"**
+- Check artifact IDs match your schema (see list above)
+- Run `openspec schemas --json` to see artifact IDs for each schema
+
+**Config not being applied:**
+- Ensure file is at `openspec/config.yaml` (not `.yml`)
+- Check YAML syntax with a validator
+- Config changes take effect immediately (no restart needed)
+
+**Context too large:**
+- Context is limited to 50KB
+- Summarize or link to external docs instead
 
 ## Commands
 
 | Command | What it does |
 |---------|--------------|
+| `/opsx: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 specs |
+| `/opsx:update` | Revise a change's planning artifacts and keep them coherent |
+| `/opsx:verify` | Validate implementation against artifacts (expanded workflow) |
+| `/opsx:sync` | Merge delta specs into main specs (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
 
@@ -96,13 +176,21 @@ This creates skills in `.claude/skills/` that Claude Code auto-detects.
 ```
 /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
 ```
@@ -119,17 +207,28 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 /opsx:apply
 ```
-Works through tasks, checking them off as you go. **Key difference:** if you discover issues during implementation, you can update your specs, design, or tasks — then continue. No phase gates.
+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).
+
+### Sync delta specs
+```text
+/opsx:sync
+```
+Merges the current change's delta specs into your main `openspec/specs/` without archiving — the change stays active. It applies the whole delta: a requirement under `## REMOVED` is deleted from the main spec and a renamed one is retitled in place, while content the delta doesn't mention is left untouched. Syncing is optional — archive prompts you to sync first if you haven't. Reach for it when you want main specs updated before archiving, when a parallel change needs to build on specs this one just added, or when you want to review the merged main spec before archiving.
 
 ### Finish up
 ```
-/opsx:sync      # Update main specs with your delta specs
-/opsx:archive   # Move to archive when done
+/opsx:archive   # Move to archive when done (prompts to sync specs if needed)
 ```
 
 ## When to Update vs. Start Fresh
 
-OPSX lets you update artifacts anytime. But when does "update as you learn" become "this is different work"?
+You can always edit your proposal or specs before implementation. But when does refining become "this is different work"?
 
 ### What a Proposal Captures
 
@@ -215,7 +314,7 @@ Think of it like git branches:
 
 ## What's Different?
 
-| | Standard (`/openspec:proposal`) | Experimental (`/opsx:*`) |
+| | Legacy (`/openspec:proposal`) | OPSX (`/opsx:*`) |
 |---|---|---|
 | **Structure** | One big proposal document | Discrete artifacts with dependencies |
 | **Workflow** | Linear phases: plan → implement → archive | Fluid actions — do anything anytime |
@@ -226,13 +325,14 @@ Think of it like git branches:
 
 ## Architecture Deep Dive
 
-This section explains how OPSX works under the hood and how it compares to the standard workflow.
+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
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                         STANDARD WORKFLOW                                    │
+│                         LEGACY WORKFLOW                                      │
 │                    (Phase-Locked, All-or-Nothing)                           │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                             │
@@ -259,9 +359,9 @@ This section explains how OPSX works under the hood and how it compares to the s
 │              ┌────────────────────────────────────────────┐                 │
 │              │           ACTIONS (not phases)             │                 │
 │              │                                            │                 │
-│              │   new ◄──► continue ◄──► apply ◄──► sync   │                 │
-│              │    │          │           │          │     │                 │
-│              │    └──────────┴───────────┴──────────┘     │                 │
+│              │   new ◄──► continue ◄──► apply ◄──► archive │                 │
+│              │    │          │           │           │    │                 │
+│              │    └──────────┴───────────┴───────────┘    │                 │
 │              │              any order                     │                 │
 │              └────────────────────────────────────────────┘                 │
 │                                                                             │
@@ -274,17 +374,17 @@ This section explains how OPSX works under the hood and how it compares to the s
 
 ### Component Architecture
 
-**Standard workflow** uses hardcoded templates in TypeScript:
+**Legacy workflow** uses hardcoded templates in TypeScript:
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                      STANDARD WORKFLOW COMPONENTS                            │
+│                      LEGACY WORKFLOW COMPONENTS                              │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │                                                                             │
 │   Hardcoded Templates (TypeScript strings)                                  │
 │                    │                                                        │
 │                    ▼                                                        │
-│   Configurators (18+ classes, one per editor)                               │
+│   Tool-specific configurators/adapters                                      │
 │                    │                                                        │
 │                    ▼                                                        │
 │   Generated Command Files (.claude/commands/openspec/*.md)                  │
@@ -325,7 +425,7 @@ This section explains how OPSX works under the hood and how it compares to the s
 │                    ▼                                                        │
 │   Skill Files (.claude/skills/openspec-*/SKILL.md)                          │
 │                                                                             │
-│   • Cross-editor compatible (Claude Code, Cursor, Windsurf)                 │
+│   • Cross-editor compatible (Claude Code, Cursor, Devin)                    │
 │   • Skills query CLI for structured data                                    │
 │   • Fully customizable via schema files                                     │
 │                                                                             │
@@ -373,7 +473,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
 
 ### Information Flow
 
-**Standard workflow** — agent receives static instructions:
+**Legacy workflow** — agent receives static instructions:
 
 ```
   User: "/openspec:proposal"
@@ -384,7 +484,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
   │  • Create proposal.md                   │
   │  • Create tasks.md                      │
   │  • Create design.md                     │
-  │  • Create specs/*.md                    │
+  │  • Create delta spec files              │
   │                                         │
   │  No awareness of what exists or         │
   │  dependencies between artifacts         │
@@ -410,7 +510,8 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
   │  │      {"id": "proposal", "status": "done"},                         │  │
   │  │      {"id": "specs", "status": "ready"},      ◄── First ready      │  │
   │  │      {"id": "design", "status": "ready"},                          │  │
-  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
+  │  │      {"id": "tasks", "status": "blocked",                          │  │
+  │  │       "missingDeps": ["specs", "design"]}                          │  │
   │  │    ]                                                               │  │
   │  │  }                                                                 │  │
   │  └────────────────────────────────────────────────────────────────────┘  │
@@ -432,7 +533,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
 
 ### Iteration Model
 
-**Standard workflow** — awkward to iterate:
+**Legacy workflow** — awkward to iterate:
 
 ```
   ┌─────────┐     ┌─────────┐     ┌─────────┐
@@ -473,57 +574,89 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
 
 ### Custom Schemas
 
-Create your own workflow by adding a schema to `~/.local/share/openspec/schemas/`:
+Create custom workflows using the schema management commands:
 
+```bash
+# Create a new schema from scratch (interactive)
+openspec schema init my-workflow
+
+# Or fork an existing schema as a starting point
+openspec schema fork spec-driven my-workflow
+
+# Validate your schema structure
+openspec schema validate my-workflow
+
+# See where a schema resolves from (useful for debugging)
+openspec schema which my-workflow
 ```
-~/.local/share/openspec/schemas/research-first/
+
+Schemas are stored in `openspec/schemas/` (project-local, version controlled) or `~/.local/share/openspec/schemas/` (user global).
+
+**Schema structure:**
+```
+openspec/schemas/research-first/
 ├── schema.yaml
 └── templates/
     ├── research.md
     ├── proposal.md
     └── tasks.md
+```
 
-schema.yaml:
-┌─────────────────────────────────────────────────────────────────┐
-│  name: research-first                                           │
-│  artifacts:                                                     │
-│    - id: research        # Added before proposal                │
-│      generates: research.md                                     │
-│      requires: []                                               │
-│                                                                 │
-│    - id: proposal                                               │
-│      generates: proposal.md                                     │
-│      requires: [research]  # Now depends on research            │
-│                                                                 │
-│    - id: tasks                                                  │
-│      generates: tasks.md                                        │
-│      requires: [proposal]                                       │
-└─────────────────────────────────────────────────────────────────┘
+**Example schema.yaml:**
+```yaml
+name: research-first
+artifacts:
+  - id: research        # Added before proposal
+    generates: research.md
+    requires: []
 
-Dependency Graph:
+  - id: proposal
+    generates: proposal.md
+    requires: [research]  # Now depends on research
 
+  - id: tasks
+    generates: tasks.md
+    requires: [proposal]
+```
+
+**Dependency Graph:**
+```
    research ──► proposal ──► tasks
 ```
 
 ### Summary
 
-| Aspect | Standard | OPSX |
+| Aspect | Legacy | OPSX |
 |--------|----------|------|
 | **Templates** | Hardcoded TypeScript | External YAML + Markdown |
 | **Dependencies** | None (all at once) | DAG with topological sort |
 | **State** | Phase-based mental model | Filesystem existence |
 | **Customization** | Edit source, rebuild | Create schema.yaml |
 | **Iteration** | Phase-locked | Fluid, edit anything |
-| **Editor Support** | 18+ configurator classes | Single skills directory |
+| **Editor Support** | Tool-specific configurator/adapters | Single skills directory |
 
 ## Schemas
 
 Schemas define what artifacts exist and their dependencies. Currently available:
 
 - **spec-driven** (default): proposal → specs → design → tasks
-- **tdd**: tests → implementation → docs
 
-Run `openspec schemas` to see available schemas.
+```bash
+# List available schemas
+openspec schemas
+
+# See all schemas with their resolution sources
+openspec schema which --all
+
+# Create a new schema interactively
+openspec schema init my-workflow
+
+# Fork an existing schema for customization
+openspec schema fork spec-driven my-workflow
+
+# Validate schema structure before use
+openspec schema validate my-workflow
+```
 
 ## Tips
 
@@ -537,4 +670,4 @@ Run `openspec schemas` to see available schemas.
 
 This is rough. That's intentional — we're learning what works.
 
-Found a bug? Have ideas? Join us on [Discord](https://discord.gg/BYjPaKbqMt) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).
+Found a bug? Have ideas? Join us on [Discord](https://discord.gg/YctCnvvshC) or open an issue on [GitHub](https://github.com/Fission-AI/openspec/issues).

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/schema-customization.md

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

docs/schema-workflow-gaps.md

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

docs/stores-beta/user-guide.md

@@ -0,0 +1,462 @@
+# 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).
+
+**One default for every repo on your machine.** If you work across many
+code repos that all plan into the same store, set it once, globally,
+instead of adding the `store:` line to each repo:
+
+```bash
+openspec config set defaultStore team-plans
+```
+
+Now any command run outside a planning root — and with no `--store` and no
+project pointer — resolves to `team-plans`. It sits at the bottom of the
+precedence list, so `--store`, a local root, and a project `store:` pointer
+all still win. The root banner and JSON `root` block report
+`source: "global_default"` with the store id, so you can always tell a
+machine-wide default from a repo's own pointer. Clear it with
+`openspec config unset defaultStore`. If the id is not registered, commands
+error and tell you to register it or clear the stale default.
+
+## Example: one feature, two component repos
+
+Suppose `add-checkout-promo` changes both `checkout-api` and
+`checkout-web`. The team wants one shared product contract, while each code
+repo still needs its own implementation tasks, branch, and review.
+
+Use two layers:
+
+1. Keep the shared behavior in `team-plans`.
+2. Keep implementation plans in each component repo and reference the store
+   as read-only upstream context.
+
+First, plan the shared contract in the store:
+
+```bash
+openspec new change add-checkout-promo --store team-plans
+openspec status --change add-checkout-promo --store team-plans
+```
+
+The proposal and specs should describe the behavior at the boundary between
+the components — for example, the promotion fields returned by the service
+and how the frontend handles an ineligible checkout. Review this change in
+the store repo like any other branch and pull request.
+
+### What context does planning see?
+
+Selecting a store changes the OpenSpec root; it does not discover or read
+every code repo that uses that store. Store instructions see the artifacts
+and configured context in the store. They see component code only when those
+folders are also available to the agent or editor and the agent reads them.
+
+A workset is a convenient way to open the planning store and both code repos
+together:
+
+```bash
+openspec workset create checkout-promo \
+  --member ~/openspec/team-plans \
+  --member ~/src/checkout-api \
+  --member ~/src/checkout-web \
+  --tool code
+openspec workset open checkout-promo
+```
+
+This makes the folders visible in one IDE workspace. It does not copy source
+context into the store, select affected repos, or grant an agent permission
+to edit them. Put durable cross-component facts in the shared specs; do not
+rely on a planner remembering source it happened to inspect.
+
+### How does implementation start in each repo?
+
+When no explicit `--store` or nearer `openspec/` root applies, a
+`store: team-plans` pointer routes commands to that store. It does not split
+one store task list by the directory from which `apply` was invoked. OpenSpec
+currently does not route tasks to repos.
+
+When each component needs an independently scoped apply/review cycle, give it
+a local OpenSpec root and reference the central store instead of pointing at
+it:
+
+```yaml
+# checkout-api/openspec/config.yaml (and likewise in checkout-web)
+schema: spec-driven
+references:
+  - team-plans
+```
+
+After the shared contract is approved and available in the store's main
+specs, create a small local change for the component's part:
+
+```bash
+cd ~/src/checkout-api
+openspec new change implement-checkout-promo-api
+
+cd ~/src/checkout-web
+openspec new change implement-checkout-promo-ui
+```
+
+The reference index in each repo's instructions supplies the store spec's
+summary and exact `openspec show ... --store team-plans` fetch command. Each
+local proposal cites that shared contract, and its tasks describe only work
+in that component. Then run `/opsx:apply` in each repo separately; root
+resolution keeps the artifacts and implementation edits scoped to that repo.
+The service and frontend changes can now be tested, reviewed, merged, and
+archived independently.
+
+If implementation must begin while the shared store change is still active,
+fetch it explicitly with
+`openspec show add-checkout-promo --store team-plans`; reference indexes list
+canonical store specs, not active store changes. Keep the store branch and
+component branches linked in their pull-request descriptions so reviewers
+can see which version of the contract each implementation follows.
+
+## 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. defaultStore          global config sets a machine  → that store
+                         default
+5. 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.** `templates` and the
+  deprecated noun forms (`openspec change show`, ...) act on the current
+  directory only — no `--store`. `schemas` follows the canonical root-selection
+  precedence and accepts `--store <id>` while keeping its successful JSON array
+  shape unchanged.
+- **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

@@ -0,0 +1,244 @@
+# Supported Tools
+
+OpenSpec works with many AI coding assistants. When you run `openspec init`, OpenSpec configures selected tools using your active profile/workflow selection and delivery mode.
+
+## How It Works
+
+For each selected tool, OpenSpec can install:
+
+1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md`
+2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files
+
+Codex is skills-only: OpenSpec installs `.agents/skills/openspec-*/SKILL.md` for Codex even when delivery is set to `commands`, and it does not generate Codex custom prompt files. Existing OpenSpec-managed skills under the legacy `.codex/skills` path are reconciled after their replacements are written; custom and divergent files are preserved.
+
+By default, OpenSpec uses the `core` profile, which includes:
+- `propose`
+- `explore`
+- `apply`
+- `update`
+- `sync`
+- `archive`
+
+You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`) via `openspec config profile`, then run `openspec update`.
+
+## How To Invoke
+
+These docs use `/opsx:propose` as the canonical name, but each tool spells it the
+way it loads the file OpenSpec wrote. Find your tool's command path in the
+[Tool Directory Reference](#tool-directory-reference) below, then match its shape here.
+
+| Command file OpenSpec writes | You type | Tools |
+|------------------------------|----------|-------|
+| `.../commands/opsx/<id>.*` — an `opsx/` folder namespaces it | `/opsx:<id>` | Claude Code, CodeBuddy, Crush, Gemini CLI, Lingma, Qoder, ZCode |
+| `.../opsx-<id>.*` — the filename is the command | `/opsx-<id>` | Every other tool with generated command files, except Amazon Q and Devin |
+| `.devin/workflows/opsx-<id>.md` — read by only one of Devin's two agents | `/opsx-<id>` on Devin Desktop, `/openspec-<skill>` on Devin Local | Devin Desktop\*\*\*\* |
+| `.amazonq/prompts/opsx-<id>.md` — a prompt, not a command | `@opsx-<id>` | Amazon Q Developer |
+| none — skills only | `/openspec-<skill>` | CodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, shared `.agents` |
+| none — Kimi Code | `/skill:openspec-<skill>` | Kimi Code |
+| none — Codex CLI | `$openspec-<skill>` | Codex ([`/openspec-<skill>` is not recognized](https://github.com/openai/codex/issues/11817)) |
+
+So `/opsx:propose` is `/opsx-propose` in Cursor, `@opsx-propose` in Amazon Q, and
+`$openspec-propose` in Codex.
+
+Two things vary independently, which is why the rows do not collapse:
+
+- **The name.** Rows 1–2 differ only in how the file names the command, and the
+  `opsx-<id>` / `opsx:<id>` stem is the same for every tool with generated
+  command files.
+- **The wrapper.** Amazon Q loads its files into a prompt library invoked with
+  `@`. Skills-only tools generate no command files at all, so their last three
+  rows use *skill* names — listed under
+  [Generated Skill Names](#generated-skill-names) — which do not map one-to-one
+  onto command ids (`/opsx:apply` is the `openspec-apply-change` skill).
+
+The command path patterns above are extension-neutral (`.*`) on purpose: the
+extension is the tool's (`.toml` for Gemini CLI, `.prompt` for Continue,
+`.prompt.md` for Kiro and GitHub Copilot), and a few tools show the name with
+its extension in the picker. Match the directory shape, not the extension.
+
+The files OpenSpec generates, and the "Getting started" hint printed after setup,
+already use the right form for the tools you selected — so the fastest answer is
+to read the hint.
+
+## Tool Directory Reference
+
+| Tool (ID) | Skills path pattern | Command path pattern |
+|-----------|---------------------|----------------------|
+| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-<id>.md` |
+| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-<id>.md` |
+| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-<id>.md` |
+| IBM Bob Shell (`bob`) | `.bob/skills/openspec-*/SKILL.md` | `.bob/commands/opsx-<id>.md` |
+| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
+| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
+| Command Code (`command-code`) | `.commandcode/skills/openspec-*/SKILL.md` | `.commandcode/commands/opsx-<id>.md` |
+| CodeArts (`codeartsagent`) | `.codeartsdoer/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
+| Codex (`codex`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (skills-only; use `$openspec-*`) |
+| Devin Desktop, formerly Windsurf (`devin`) | `.devin/skills/openspec-*/SKILL.md` | `.devin/workflows/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`\*\* |
+| Hermes Agent (`hermes`) | `.hermes/skills/openspec-*/SKILL.md`\*\*\* | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-<id>.md` |
+| Junie (`junie`) | `.junie/skills/openspec-*/SKILL.md` | `.junie/commands/opsx-<id>.md` |
+| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-<id>.md` |
+| Kimi Code (`kimi`) | `.kimi-code/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
+| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
+| Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
+| MiniMax Code (`minimax-code`) | `~/.minimax/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use MiniMax Code skills) |
+| 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>.md` |
+| [Rovo Dev CLI](https://support.atlassian.com/rovo/docs/use-rovo-dev-cli/) (`rovodev`) | `.rovodev/skills/openspec-*/SKILL.md` | Not generated. Rovo has no slash-command surface — it matches skills automatically or by prompt (e.g. "use the openspec-propose skill"); `/skills` only manages them. Generated content references skills by name, never as `/openspec-*` commands. |
+| [Zoo Code](https://github.com/Zoo-Code-Org/Zoo-Code) (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
+| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | `.trae/commands/opsx-<id>.md` |
+| ZCode (`zcode`) | `.zcode/skills/openspec-*/SKILL.md` | `.zcode/commands/opsx/<id>.md` |
+| Shared `.agents` skills (`agents`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+
+\*\* 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. Selecting `github-copilot` can also set up the GitHub-hosted **cloud coding agent** — see [GitHub Copilot cloud coding agent](#github-copilot-cloud-coding-agent) below.
+
+\*\*\* Hermes loads skills from `~/.hermes/skills/` by default. To use project-local OpenSpec skills, add the project `.hermes/skills/` directory to `skills.external_dirs` in `~/.hermes/config.yaml`; Hermes then exposes skills with user-facing slash invocations such as `/openspec-propose`.
+
+\*\*\*\* Windsurf was [rebranded to Devin Desktop](https://docs.devin.ai/desktop/devin-desktop-faq) on June 2, 2026, and its config directory moved: `.devin/` is the preferred read + write location, `.windsurf/` a legacy read-only fallback. OpenSpec follows the rename — the tool id is `devin`, and `--tools windsurf` still resolves to it so existing setup scripts keep working. A project still holding OpenSpec files in `.windsurf/` is offered the move on the next `openspec update`; declining leaves them in place, and files you wrote yourself are never touched. Workflows are invoked by filename, so `.devin/workflows/opsx-apply.md` is `/opsx-apply`. The [Devin Local agent does not support workflows](https://docs.devin.ai/desktop/devin-local) — only skills, and it does not read `.windsurf/` at all — so whenever OpenSpec writes Devin skills it keeps their bodies, and the getting-started hint, on `/openspec-*` skill invocations, which work on both agents. Under commands-only delivery no skills are written and both fall back to `/opsx-*`.
+
+MiniMax Code is a global skills-only integration. OpenSpec writes only its
+`openspec-*` directories under `~/.minimax/skills/`; it does not create
+repo-local `.minimax` or `.mavis` directories. Commands-only delivery leaves
+existing global MiniMax Code skills untouched so one project's delivery setting
+cannot remove skills used by another project.
+
+### GitHub Copilot cloud coding agent
+
+GitHub's [Copilot coding agent](https://docs.github.com/en/copilot/using-github-copilot/coding-agent) runs on GitHub in a GitHub Actions environment — separate from Copilot in your editor. OpenSpec can set it up to use the OpenSpec CLI by generating two files:
+
+- `.github/workflows/copilot-setup-steps.yml` — installs `@fission-ai/openspec` in the agent's environment
+- `.github/agents/openspec.agent.md` — tells the agent how to drive OpenSpec
+
+Because this writes a GitHub Actions workflow into your repository, it is **opt-in**:
+
+| How | Behavior |
+|-----|----------|
+| `openspec init` (interactive) | Asks whether to set up cloud files. Default is **No**. |
+| `openspec init --copilot-cloud` | Sets them up without prompting (for scripts/CI). |
+| `openspec init --no-copilot-cloud` | Skips them without prompting, and removes any previously generated ones. |
+| `openspec update` | Never prompts. Refreshes the files only if you opted in (or the project already has them). If you opted out, it removes OpenSpec-managed cloud files. |
+
+Your choice is saved in `openspec/config.yaml` as `githubCopilot.cloudAgent: true|false`, so non-interactive updates honor it. OpenSpec only ever writes or removes files whose content it generated — if you customize `copilot-setup-steps.yml` or `openspec.agent.md`, or already have your own, it is left untouched (and `init`/`update` tell you so).
+
+### When to pick the shared `.agents` target
+
+`agents` is the vendor-neutral option: it writes skills to `.agents/skills/`, the
+shared root many agent tools read, instead of a tool-specific directory.
+
+| Situation | Pick |
+|-----------|------|
+| Your tool has its own row above | Its own ID — you get that tool's integration, including slash commands where it supports them |
+| Several agents on one repo, all reading `.agents/skills` | `agents` — one skill tree instead of one per tool |
+| Your tool isn't listed yet but reads `.agents/skills` | `agents` |
+
+Selecting it alongside a tool-specific ID is fine; each normally writes to its
+own root. Codex is the exception because it uses the same canonical `.agents`
+root. If both `codex` and `agents` are selected, OpenSpec keeps one
+Codex-led tree. Its handoffs name both `$openspec-*` for Codex and
+`/openspec-*` for other agents, so `--tools all` and existing multi-agent
+setups keep working without two writers overwriting the same files.
+OpenSpec also offers it automatically once a project has a `.agents/skills/`
+directory — a bare `.agents/` is not enough, since tools use that root for rules
+and subagent definitions too. Note `.agents` is not `.agent`: the singular
+directory belongs to Antigravity.
+
+Two things to know:
+
+- **Skills only.** No command adapter exists, so no `opsx-*` command files are
+  written; with a commands-inclusive delivery mode `openspec init` lists `agents`
+  among the tools it reports under `Commands skipped for: … (no adapter)`.
+  Invoke the workflows by skill name —
+  most assistants that read `.agents/skills` spell that `/openspec-propose`, the form
+  OpenSpec's setup hint prints. The target is vendor-neutral, so check your
+  assistant's own docs if it uses another form.
+- **No `AGENTS.md` is created or edited.** The target is the `.agents/` directory.
+  If your root `AGENTS.md` still carries OpenSpec marker blocks from an older
+  version, `openspec update` strips them — see the [Migration Guide](migration-guide.md).
+
+Because `.agents/skills/` is shared, it is worth knowing what OpenSpec claims there:
+it writes, refreshes, and removes only the `openspec-*` skill directories for your
+selected workflows, plus an `.openspec-target` marker that records whether Codex
+or the vendor-neutral target rendered that shared tree. Anything else in that
+directory is left alone. Treat the `openspec-*` names and marker as OpenSpec's —
+edits inside them are replaced on the next `openspec update`, the same as for
+every other tool.
+
+For pre-marker projects, OpenSpec infers ownership from managed skill references:
+`$openspec-*` means Codex and `/openspec-*` means the vendor-neutral target. A
+generic canonical tree alongside legacy `.codex/skills` is treated as an older
+dual-target install and consolidated into the compatible shared tree.
+
+`openspec update` honors this ownership too. If a project owns `.agents` as the
+vendor-neutral target and a leftover Codex install is detected only from stray
+prompt files, the update leaves the established `agents` tree in place instead of
+rewriting it with Codex syntax, and preserves those legacy prompt files rather
+than deleting them. To hand the shared tree to Codex, run `openspec init --tools
+codex` explicitly.
+
+## Non-Interactive Setup
+
+For CI/CD or scripted setup, use `--tools` (and optionally `--profile`):
+
+```bash
+# Configure specific tools
+openspec init --tools claude,cursor
+
+# Configure all supported tools
+openspec init --tools all
+
+# Skip tool configuration
+openspec init --tools none
+
+# Override profile for this init run
+openspec init --profile core
+```
+
+**Available tool IDs (`--tools`)** — `windsurf` is also accepted, as an alias for `devin`: `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `command-code`, `codeartsagent`, `codex`, `devin`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `hermes`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `lingma`, `minimax-code`, `vibe`, `oh-my-pi`, `opencode`, `pi`, `qoder`, `qwen`, `roocode`, `trae`, `zcode`, `agents`
+
+## Workflow-Dependent Installation
+
+OpenSpec installs workflow artifacts based on selected workflows:
+
+- **Core profile (default):** `propose`, `explore`, `apply`, `update`, `sync`, `archive`
+- **Custom selection:** any subset of all workflow IDs:
+  `propose`, `explore`, `new`, `continue`, `apply`, `update`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`
+
+In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed.
+
+## Generated Skill Names
+
+When selected by profile/workflow config, OpenSpec generates these skills:
+
+- `openspec-propose`
+- `openspec-explore`
+- `openspec-new-change`
+- `openspec-continue-change`
+- `openspec-apply-change`
+- `openspec-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
+
+- [CLI Reference](cli.md) — Terminal commands
+- [Commands](commands.md) — Slash commands and skills
+- [Getting Started](getting-started.md) — First-time setup

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,195 @@
+# 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 prefix -g` to see where global packages live: on macOS and Linux the binaries are in that directory's `bin/`, and on Windows they sit directly in it. Make sure that path is on your `PATH`. (`npm bin -g` was removed in npm 9.)
+
+If you used the [AI-assisted install](installation.md#install-with-your-ai-assistant), this is the expected hand-off point: that prompt tells your assistant to show you the `PATH` change rather than edit your shell startup files itself.
+
+### "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.
+
+   Instruction files come from the *installed* CLI, so an outdated CLI reports everything up to date without ever writing the newer workflows. `openspec update` now checks for that and offers to upgrade — take the offer if you see it.
+
+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.** Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe and the shared `.agents` target don't get generated `opsx-*` command files; they use skill-based invocations instead, so `/opsx` will never autocomplete for them. Type `$openspec-propose` in Codex, `/skill:openspec-propose` in Kimi Code, and `/openspec-propose` in the rest. The shared `.agents` target is vendor-neutral, so `/openspec-propose` is the common form rather than a guaranteed one — if your assistant does not answer to it, check its own docs for how it invokes a skill. Amazon Q does get command files, but loads them into its prompt library rather than its slash menu — type `@opsx-propose` there, not `/opsx`. Every tool's form is listed in [How To Invoke](supported-tools.md#how-to-invoke).
+
+## 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
+openspec validate --archived       # fail if archived changes have unchecked tasks
+```
+
+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.
+
+One message deserves its own note:
+
+```text
+MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"
+```
+
+A `MODIFIED` requirement replaces the whole requirement block, so it has to carry every scenario that survives the change, not only the ones you edited. Copy the named scenarios from `openspec/specs/<capability-path>/spec.md` back into the delta, preserving any domain directories in the path. This often appears on an older change after someone else's change added a scenario to the same requirement — archive refuses that change either way, and validation now says so before you implement it.
+
+### 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.
+
+### "User force closed the prompt with 0 null"
+
+Something ran `openspec archive` where nothing can answer a question — an AI agent calling it from a tool, a CI job, or any shell with stdin closed. Archive asks up to three confirmations, and an unanswerable one used to fail with that raw message.
+
+Pass `--yes` to answer them up front:
+
+```bash
+openspec archive <change-name> --yes
+```
+
+Keep any flags you were already passing — `--skip-specs` and `--no-validate` change what archive does, so a bare `--yes` rerun is not the same command. Current versions name the flag for you and print a `Fix:` line you can paste. If you meant to pick from a list, pass the change name explicitly: the picker needs an answer too.
+
+If you instead ran archive with its output redirected to a file or captured by a tool and *did* pipe an answer (`printf 'y\n' | openspec archive …`), older versions wrote terminal escape codes into that capture while drawing the prompt — in some environments enough to bloat the file badly. Current versions read the confirmation prompts as plain text whenever stdout is not a terminal, and a no-argument `openspec archive` (which would otherwise draw an interactive change picker) asks you to pass a change name up front instead of rendering a menu into the capture. Either way, redirected and agent runs stay clean; passing `--yes` (with a change name) skips the prompts entirely.
+
+## 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
+```
+
+For Codex, OpenSpec may detect old managed prompt files in `$CODEX_HOME/prompts` or `~/.codex/prompts`. That cleanup is limited to OpenSpec's allowlisted legacy Codex prompt filenames, and non-interactive `openspec init` removes only the files whose replacement `.agents/skills/openspec-*` skills exist. Non-interactive `openspec update` leaves all legacy cleanup untouched unless you pass `--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

@@ -0,0 +1,552 @@
+# Workflows
+
+This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see [Getting Started](getting-started.md). For command reference, see [Commands](commands.md).
+
+## Philosophy: Actions, Not Phases
+
+Traditional workflows force you through phases: planning, then implementation, then done. But real work doesn't fit neatly into boxes.
+
+OPSX takes a different approach:
+
+```text
+Traditional (phase-locked):
+
+  PLANNING ────────► IMPLEMENTING ────────► DONE
+      │                    │
+      │   "Can't go back"  │
+      └────────────────────┘
+
+OPSX (fluid actions):
+
+  proposal ──► specs ──► design ──► tasks ──► implement
+```
+
+**Key principles:**
+
+- **Actions, not phases** - Commands are things you can do, not stages you're stuck in
+- **Dependencies are enablers** - They show what's possible, not what's required next
+
+> **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
+
+## Workflow at a Glance
+
+The default workflow stays fluid: exploration and verification are optional, and
+you can update planning artifacts whenever implementation reveals something new.
+
+```mermaid
+flowchart TD
+    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
+    Idea --> Propose["/opsx:propose"]
+    Explore --> Propose
+    Propose --> Review{"Planning artifacts<br/>ready?"}
+    Review -->|"Refine"| Update["/opsx:update"]
+    Update --> Review
+    Review -->|"Implement"| Apply["/opsx:apply"]
+    Apply -->|"Plan changed"| Update
+    Apply --> Archive["/opsx:archive"]
+    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
+    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
+    Verify --> Verified{"Ready to archive?"}
+    Verified -->|"Fix implementation"| Apply
+    Verified -->|"Revise plan"| Update
+    Verified -->|"Ready"| Sync
+    Verified -->|"Ready"| Archive
+    Sync --> Archive
+```
+
+The AI assistant drives the workflow, while the CLI provides deterministic
+scaffolding, status, and artifact instructions:
+
+```mermaid
+sequenceDiagram
+    actor Human
+    participant Assistant as AI assistant
+    participant CLI as OpenSpec CLI
+    participant Files as Planning and implementation files
+
+    Human->>Assistant: /opsx:propose "change"
+    Assistant->>CLI: openspec new change
+    CLI->>Files: Scaffold change metadata
+    Assistant->>CLI: Request status and artifact instructions
+    CLI-->>Assistant: Build order, paths, and templates
+    Assistant->>Files: Write schema-defined planning artifacts
+    Assistant-->>Human: Present artifacts for review
+
+    Human->>Assistant: /opsx:apply
+    Assistant->>CLI: Request apply instructions
+    CLI-->>Assistant: Context files and task state
+    Assistant->>Files: Implement tasks and update checkboxes
+    Assistant-->>Human: Report implementation status
+
+    Human->>Assistant: /opsx:archive
+    Assistant->>CLI: Request archive inputs and artifact status
+    CLI-->>Assistant: Planning paths and artifact completion
+    Assistant->>Files: Read task state and compare delta specs
+    opt Delta specs exist
+        Assistant-->>Human: Offer to sync before archiving
+        alt Sync accepted
+            Human->>Assistant: Confirm sync
+            Assistant->>Files: Merge delta specs into main specs
+        else Sync skipped
+            Human->>Assistant: Archive without syncing
+        end
+    end
+    Assistant->>Files: Move the change into the archive
+    Assistant-->>Human: Report archive location and sync result
+
+    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts; it still validates, then applies any delta specs and archives
+```
+
+## Two Modes
+
+### Default Quick Path (`core` profile)
+
+New installs default to `core`, which provides:
+- `/opsx:explore`
+- `/opsx:propose`
+- `/opsx:apply`
+- `/opsx:update`
+- `/opsx:sync`
+- `/opsx:archive`
+
+Typical flow:
+
+```text
+/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
+  (optional)
+```
+
+#### Start by exploring (the habit worth forming)
+
+`/opsx:explore` is part of the default profile, not an advanced add-on. It's the move to make whenever you have a problem but not yet a plan, which, with an AI assistant, is most of the time.
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: Our search results feel stale. I'm not sure if it's caching,
+     indexing, or the query itself.
+
+AI:  Let me look... [reads the search service and cache layer]
+     It's the index: it only rebuilds nightly, so edits don't show
+     up until the next day. Two options: rebuild on write (simple,
+     more load) or a short-TTL cache invalidation (more moving parts,
+     less load). Given your write volume is low, rebuild-on-write is
+     the cleaner fix. Want to scope it?
+
+You: Yes.
+
+You: /opsx:propose rebuild-search-index-on-write
+```
+
+Explore creates no artifacts and writes no code. It's a free, no-stakes conversation that turns a vague worry into a precise change, so the proposal that follows is sharp. Already know exactly what you want? Skip it and go straight to `/opsx:propose`. Full guide: [Explore First](explore.md).
+
+### Expanded/Full Workflow (custom selection)
+
+If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with:
+
+```bash
+openspec config profile
+openspec update
+```
+
+## Workflow Patterns (Expanded Mode)
+
+### Quick Feature
+
+When you know what you want to build and just need to execute:
+
+```text
+/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
+```
+
+**Example conversation:**
+
+```text
+You: /opsx:new add-logout-button
+
+AI:  Created openspec/changes/add-logout-button/
+     Ready to create: proposal
+
+You: /opsx:ff
+
+AI:  Creating all planning artifacts...
+     ✓ proposal.md
+     ✓ specs/
+     ✓ design.md
+     ✓ tasks.md
+     Ready for implementation!
+
+You: /opsx:apply
+
+AI:  Working through tasks...
+     ✓ Added logout button to header
+     ✓ Implemented session clearing
+     ✓ Added confirmation dialog
+     All tasks complete!
+
+You: /opsx:archive
+
+AI:  ✓ Merged specs
+     ✓ Archived change
+```
+
+**Best for:** Small to medium features, bug fixes, straightforward changes.
+
+### Exploratory
+
+When requirements are unclear or you need to investigate first:
+
+```text
+/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
+```
+
+**Example conversation:**
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: I want to improve page load performance but I'm not sure
+     where the bottlenecks are.
+
+AI:  Let me help investigate...
+     [Analyzes bundle sizes, identifies slow queries, reviews
+     component render patterns]
+
+     I found three main bottlenecks:
+     1. Large unoptimized images
+     2. Synchronous data fetching in ProductList
+     3. Re-renders from context changes
+
+     Which would you like to address first?
+
+You: Let's tackle the data fetching issue.
+
+You: /opsx:new optimize-product-list-fetching
+
+AI:  Created change. Ready to create: proposal
+
+You: /opsx:continue
+
+AI:  Creating proposal based on our exploration...
+     [Writes proposal incorporating investigation insights]
+
+     Ready to create: specs, design
+     Which would you like next?
+
+You: /opsx:continue
+
+AI:  Creating specs...
+```
+
+**Best for:** Performance optimization, debugging, architectural decisions, unclear requirements.
+
+### Parallel Changes
+
+Work on multiple changes at once:
+
+```text
+Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
+                                         │
+                                    context switch
+                                         │
+Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply
+```
+
+**Example conversation:**
+
+```text
+You: I'm working on add-dark-mode but got pulled into a bug fix
+
+You: /opsx:new fix-login-redirect
+
+AI:  Created openspec/changes/fix-login-redirect/
+
+You: /opsx:ff
+
+AI:  ✓ Created planning artifacts
+
+You: /opsx:apply
+
+AI:  Working on fix-login-redirect...
+     [Implements the fix]
+     All tasks complete!
+
+You: /opsx:archive
+
+AI:  ✓ Archived fix-login-redirect
+
+You: Let's get back to dark mode
+
+You: /opsx:apply add-dark-mode
+
+AI:  Resuming add-dark-mode...
+     Picking up at task 2.3: Update Header...
+```
+
+**Best for:** Parallel work streams, urgent interrupts, team collaboration.
+
+When you have multiple completed changes, use `/opsx:bulk-archive`:
+
+```text
+You: /opsx:bulk-archive
+
+AI:  Found 3 completed changes:
+     - add-dark-mode (all tasks done)
+     - fix-login-redirect (all tasks done)
+     - update-footer (all tasks done)
+
+     Checking for spec conflicts...
+     ⚠ add-dark-mode and update-footer both touch specs/ui/
+
+     Inspecting codebase to resolve...
+     Both changes are implemented. Will apply in chronological order.
+
+     Archive all 3 changes?
+
+You: Yes
+
+AI:  ✓ Archived add-dark-mode
+     ✓ Archived fix-login-redirect
+     ✓ Archived update-footer
+     Specs merged in order: add-dark-mode → update-footer
+```
+
+Bulk archive detects when multiple changes touch the same specs and resolves conflicts by checking what's actually implemented.
+
+### Completing a Change
+
+The recommended completion flow:
+
+```text
+/opsx:apply ──► /opsx:verify ──► /opsx:archive
+                    │                 │
+              validates          prompts to sync
+              implementation     if needed
+```
+
+#### Verify: Check Your Work
+
+`/opsx:verify` validates implementation against your artifacts across three dimensions:
+
+```text
+You: /opsx:verify
+
+AI:  Verifying add-auth...
+
+     COMPLETENESS
+     ✓ All 12 tasks in tasks.md are checked
+     ✓ All requirements in specs have corresponding code
+     ⚠ Scenario "Session timeout after inactivity" not tested
+
+     CORRECTNESS
+     ✓ Implementation matches spec intent
+     ✓ Edge cases from scenarios are handled
+     ✓ Error states match spec definitions
+
+     COHERENCE
+     ✓ Design decisions reflected in code structure
+     ✓ Naming conventions consistent with design.md
+     ⚠ Design mentions "event-driven" but implementation uses polling
+
+     SUMMARY
+     ─────────────────────────────
+     Critical issues: 0
+     Warnings: 2
+     Ready to archive: Yes (with warnings)
+
+     Recommendations:
+     1. Add test for session timeout scenario
+     2. Consider refactoring to event-driven as designed, or update design.md
+```
+
+**What verify checks:**
+
+| Dimension | What it validates |
+|-----------|------------------|
+| Completeness | All tasks done, all requirements implemented, scenarios covered |
+| Correctness | Implementation matches spec intent, edge cases handled |
+| Coherence | Design decisions reflected in code, patterns consistent |
+
+Verify won't block archive, but it surfaces issues you might want to address first.
+
+#### Archive: Finalize the Change
+
+`/opsx:archive` completes the change and moves it to the archive:
+
+```text
+You: /opsx:archive
+
+AI:  Archiving add-auth...
+
+     Artifact status:
+     ✓ proposal.md exists
+     ✓ specs/ exists
+     ✓ design.md exists
+     ✓ tasks.md exists (12/12 tasks complete)
+
+     Delta specs: Not yet synced to main
+     → Would you like to sync now?
+
+You: Yes
+
+AI:  ✓ Synced specs to openspec/specs/auth/spec.md
+     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/
+
+     Change archived successfully.
+```
+
+Archive will prompt if specs aren't synced. It won't block on incomplete tasks, but it will warn you.
+
+## When to Use What
+
+### `/opsx:ff` vs `/opsx:continue`
+
+| Situation | Use |
+|-----------|-----|
+| Clear requirements, ready to build | `/opsx:ff` |
+| Exploring, want to review each step | `/opsx:continue` |
+| Want to iterate on proposal before specs | `/opsx:continue` |
+| Time pressure, need to move fast | `/opsx:ff` |
+| Complex change, want control | `/opsx:continue` |
+
+**Rule of thumb:** If you can describe the full scope upfront, use `/opsx:ff`. If you're figuring it out as you go, use `/opsx:continue`.
+
+### When to Update vs Start Fresh
+
+A common question: when is updating an existing change okay, and when should you start a new one?
+
+**Update the existing change when:**
+
+- Same intent, refined execution
+- Scope narrows (MVP first, rest later)
+- Learning-driven corrections (codebase isn't what you expected)
+- Design tweaks based on implementation discoveries
+
+**Start a new change when:**
+
+- Intent fundamentally changed
+- Scope exploded to different work entirely
+- Original change can be marked "done" standalone
+- Patches would confuse more than clarify
+
+```text
+                     ┌─────────────────────────────────────┐
+                     │     Is this the same work?          │
+                     └──────────────┬──────────────────────┘
+                                    │
+                 ┌──────────────────┼──────────────────┐
+                 │                  │                  │
+                 ▼                  ▼                  ▼
+          Same intent?      >50% overlap?      Can original
+          Same problem?     Same scope?        be "done" without
+                 │                  │          these changes?
+                 │                  │                  │
+       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
+       │                 │  │             │   │               │
+      YES               NO YES           NO  NO              YES
+       │                 │  │             │   │               │
+       ▼                 ▼  ▼             ▼   ▼               ▼
+    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW
+```
+
+**Example: "Add dark mode"**
+
+- "Need to also support custom themes" → New change (scope exploded)
+- "System preference detection is harder than expected" → Update (same intent)
+- "Let's ship toggle first, add preferences later" → Update then archive, then new change
+
+## Best Practices
+
+### Keep Changes Focused
+
+One logical unit of work per change. If you're doing "add feature X and also refactor Y", consider two separate changes.
+
+**Why it matters:**
+- Easier to review and understand
+- Cleaner archive history
+- Can ship independently
+- Simpler rollback if needed
+
+### Use `/opsx:explore` for Unclear Requirements
+
+Before committing to a change, explore the problem space:
+
+```text
+You: /opsx:explore
+
+AI:  What would you like to explore?
+
+You: How should we handle rate limiting for our API?
+
+AI:  Let me investigate your current setup and options...
+     [Researches codebase, considers patterns]
+
+     I see three approaches we could take:
+     1. Middleware-based (simple, per-endpoint)
+     2. Redis-backed (scalable, shared state)
+     3. Token bucket per user (fair, complex)
+
+     Your current stack suggests #1 or #2. What's your scale?
+```
+
+Exploration clarifies thinking before you create artifacts.
+
+### Verify Before Archiving
+
+Use `/opsx:verify` to check implementation matches artifacts:
+
+```text
+You: /opsx:verify
+
+AI:  Verifying add-dark-mode...
+
+     ✓ All tasks in tasks.md are checked
+     ✓ Requirements in specs have corresponding code
+     ✓ Design decisions are reflected in implementation
+
+     Ready to archive!
+```
+
+Catches mismatches before you close out the change.
+
+### Name Changes Clearly
+
+Good names make `openspec list` useful:
+
+```text
+Good:                          Avoid:
+add-dark-mode                  feature-1
+fix-login-redirect             update
+optimize-product-query         changes
+implement-2fa                  wip
+```
+
+## Command Quick Reference
+
+For full command details and options, see [Commands](commands.md).
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/opsx:propose` | Create change + planning artifacts | Fast default path (`core` profile) |
+| `/opsx:explore` | Think through ideas with the AI | Start here when unsure: unclear requirements, investigation, comparing options |
+| `/opsx:new` | Start a change scaffold | Expanded mode, explicit artifact control |
+| `/opsx:continue` | Create next artifact | Expanded mode, step-by-step artifact creation |
+| `/opsx:ff` | Create all planning artifacts | Expanded mode, clear scope |
+| `/opsx:apply` | Implement tasks | Ready to write code |
+| `/opsx:verify` | Validate implementation | Expanded mode, before archiving |
+| `/opsx:sync` | Merge delta specs | Expanded mode, optional |
+| `/opsx:archive` | Complete the change | All work finished |
+| `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work |
+
+## Next Steps
+
+- [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,103 @@
+# 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 dropped from it. Remove the last requirement a capability has and you retire it: rather than leave a spec with nothing in it, archive deletes `openspec/specs/<capability>/spec.md`. Because that is the one archive step that removes a file, it has to be asked for — add `retire_capabilities: true` to the change's `.openspec.yaml`, alongside the `schema:` that file already needs. Without it the archive aborts and tells you so. For a spec in the caller's checkout, the archive output also names the `git checkout` that restores a committed file; selected stores receive checkout-scoped recovery guidance instead. 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.
+
+One more section is worth knowing about. When your delta creates a capability that doesn't exist yet, open it with `## Purpose` — a sentence or two on what the capability is for. Archive uses it as the Purpose of the main spec it creates; skip it and you get a `TBD` placeholder to fill in by hand. An existing spec already has a Purpose, so a delta's is ignored there — edit `openspec/specs/<capability-path>/spec.md` directly to change one. Here, `<capability-path>` is the directory relative to `specs/`, such as `user-auth` in a flat project or `identity/user-auth` in a project organized by domain.
+
+## 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.lock

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

flake.nix

@@ -0,0 +1,115 @@
+{
+  description = "OpenSpec - AI-native system for spec-driven development";
+
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+  };
+
+  outputs =
+    { self, nixpkgs }:
+    let
+      supportedSystems = [
+        "x86_64-linux"
+        "aarch64-linux"
+        "x86_64-darwin"
+        "aarch64-darwin"
+      ];
+
+      forAllSystems = f: nixpkgs.lib.genAttrs supportedSystems (system: f system);
+    in
+    {
+      packages = forAllSystems (
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+          inherit (pkgs) lib;
+        in
+        {
+          default = pkgs.stdenv.mkDerivation (finalAttrs: {
+            pname = "openspec";
+            version = (builtins.fromJSON (builtins.readFile ./package.json)).version;
+
+            src = lib.fileset.toSource {
+              root = ./.;
+              fileset = lib.fileset.unions [
+                ./src
+                ./bin
+                ./schemas
+                ./scripts
+                ./test
+                ./package.json
+                ./pnpm-lock.yaml
+                ./pnpm-workspace.yaml
+                ./tsconfig.json
+                ./build.js
+                ./vitest.config.ts
+                ./vitest.setup.ts
+                ./eslint.config.js
+              ];
+            };
+
+            pnpmDeps = pkgs.fetchPnpmDeps {
+              inherit (finalAttrs) pname version src;
+              pnpm = pkgs.pnpm_9;
+              fetcherVersion = 3;
+              hash = "sha256-LerQoKH3MX5mWZ2Sk9p9Q3kUNwckfA1RnP7Z3FueAXU=";
+            };
+
+            nativeBuildInputs = with pkgs; [
+              nodejs_22
+              npmHooks.npmInstallHook
+              pnpmConfigHook
+              pnpm_9
+            ];
+
+            buildPhase = ''
+              runHook preBuild
+
+              pnpm run build
+
+              runHook postBuild
+            '';
+
+            dontNpmPrune = true;
+
+            meta = with pkgs.lib; {
+              description = "AI-native system for spec-driven development";
+              homepage = "https://github.com/Fission-AI/OpenSpec";
+              license = licenses.mit;
+              maintainers = [ ];
+              mainProgram = "openspec";
+            };
+          });
+        }
+      );
+
+      apps = forAllSystems (system: {
+        default = {
+          type = "app";
+          program = "${self.packages.${system}.default}/bin/openspec";
+        };
+      });
+
+      devShells = forAllSystems (
+        system:
+        let
+          pkgs = nixpkgs.legacyPackages.${system};
+        in
+        {
+          default = pkgs.mkShell {
+            buildInputs = with pkgs; [
+              nodejs_22
+              pnpm_9
+            ];
+
+            shellHook = ''
+              echo "OpenSpec development environment"
+              echo "Node version: $(node --version)"
+              echo "pnpm version: $(pnpm --version)"
+              echo "Run 'pnpm install' to install dependencies"
+            '';
+          };
+        }
+      );
+    };
+}

openspec/AGENTS.md

@@ -1,454 +0,0 @@
-# OpenSpec Instructions
-
-Instructions for AI coding assistants using OpenSpec for spec-driven development.
-
-## TL;DR Quick Checklist
-
-- Search existing work: `openspec spec list --long`, `openspec list` (use `rg` only for full-text search)
-- Decide scope: new capability vs modify existing capability
-- Pick a unique `change-id`: kebab-case, verb-led (`add-`, `update-`, `remove-`, `refactor-`)
-- Scaffold: `proposal.md`, `tasks.md`, `design.md` (only if needed), and delta specs per affected capability
-- Write deltas: use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements`; include at least one `#### Scenario:` per requirement
-- Validate: `openspec validate [change-id] --strict` and fix issues
-- Request approval: Do not start implementation until proposal is approved
-
-## Three-Stage Workflow
-
-### Stage 1: Creating Changes
-Create proposal when you need to:
-- Add features or functionality
-- Make breaking changes (API, schema)
-- Change architecture or patterns  
-- Optimize performance (changes behavior)
-- Update security patterns
-
-Triggers (examples):
-- "Help me create a change proposal"
-- "Help me plan a change"
-- "Help me create a proposal"
-- "I want to create a spec proposal"
-- "I want to create a spec"
-
-Loose matching guidance:
-- Contains one of: `proposal`, `change`, `spec`
-- With one of: `create`, `plan`, `make`, `start`, `help`
-
-Skip proposal for:
-- Bug fixes (restore intended behavior)
-- Typos, formatting, comments
-- Dependency updates (non-breaking)
-- Configuration changes
-- Tests for existing behavior
-
-**Workflow**
-1. Review `openspec/project.md`, `openspec list`, and `openspec list --specs` to understand current context.
-2. Choose a unique verb-led `change-id` and scaffold `proposal.md`, `tasks.md`, optional `design.md`, and spec deltas under `openspec/changes/<id>/`.
-3. Draft spec deltas using `## ADDED|MODIFIED|REMOVED Requirements` with at least one `#### Scenario:` per requirement.
-4. Run `openspec validate <id> --strict` and resolve any issues before sharing the proposal.
-
-### Stage 2: Implementing Changes
-Track these steps as TODOs and complete them one by one.
-1. **Read proposal.md** - Understand what's being built
-2. **Read design.md** (if exists) - Review technical decisions
-3. **Read tasks.md** - Get implementation checklist
-4. **Implement tasks sequentially** - Complete in order
-5. **Confirm completion** - Ensure every item in `tasks.md` is finished before updating statuses
-6. **Update checklist** - After all work is done, set every task to `- [x]` so the list reflects reality
-7. **Approval gate** - Do not start implementation until the proposal is reviewed and approved
-
-### Stage 3: Archiving Changes
-After deployment, create separate PR to:
-- Move `changes/[name]/` → `changes/archive/YYYY-MM-DD-[name]/`
-- Update `specs/` if capabilities changed
-- Use `openspec archive <change-id> --skip-specs --yes` for tooling-only changes (always pass the change ID explicitly)
-- Run `openspec validate --strict` to confirm the archived change passes checks
-
-## Before Any Task
-
-**Context Checklist:**
-- [ ] Read relevant specs in `specs/[capability]/spec.md`
-- [ ] Check pending changes in `changes/` for conflicts
-- [ ] Read `openspec/project.md` for conventions
-- [ ] Run `openspec list` to see active changes
-- [ ] Run `openspec list --specs` to see existing capabilities
-
-**Before Creating Specs:**
-- Always check if capability already exists
-- Prefer modifying existing specs over creating duplicates
-- Use `openspec show [spec]` to review current state
-- If request is ambiguous, ask 1–2 clarifying questions before scaffolding
-
-### Search Guidance
-- Enumerate specs: `openspec spec list --long` (or `--json` for scripts)
-- Enumerate changes: `openspec list` (or `openspec change list --json` - deprecated but available)
-- Show details:
-  - Spec: `openspec show <spec-id> --type spec` (use `--json` for filters)
-  - Change: `openspec show <change-id> --json --deltas-only`
-- Full-text search (use ripgrep): `rg -n "Requirement:|Scenario:" openspec/specs`
-
-## Quick Start
-
-### CLI Commands
-
-```bash
-# Essential commands
-openspec list                  # List active changes
-openspec list --specs          # List specifications
-openspec show [item]           # Display change or spec
-openspec validate [item]       # Validate changes or specs
-openspec archive <change-id> [--yes|-y]   # Archive after deployment (add --yes for non-interactive runs)
-
-# Project management
-openspec init [path]           # Initialize OpenSpec
-openspec update [path]         # Update instruction files
-
-# Interactive mode
-openspec show                  # Prompts for selection
-openspec validate              # Bulk validation mode
-
-# Debugging
-openspec show [change] --json --deltas-only
-openspec validate [change] --strict
-```
-
-### Command Flags
-
-- `--json` - Machine-readable output
-- `--type change|spec` - Disambiguate items
-- `--strict` - Comprehensive validation
-- `--no-interactive` - Disable prompts
-- `--skip-specs` - Archive without spec updates
-- `--yes`/`-y` - Skip confirmation prompts (non-interactive archive)
-
-## Directory Structure
-
-```
-openspec/
-├── project.md              # Project conventions
-├── specs/                  # Current truth - what IS built
-│   └── [capability]/       # Single focused capability
-│       ├── spec.md         # Requirements and scenarios
-│       └── design.md       # Technical patterns
-├── changes/                # Proposals - what SHOULD change
-│   ├── [change-name]/
-│   │   ├── proposal.md     # Why, what, impact
-│   │   ├── tasks.md        # Implementation checklist
-│   │   ├── design.md       # Technical decisions (optional; see criteria)
-│   │   └── specs/          # Delta changes
-│   │       └── [capability]/
-│   │           └── spec.md # ADDED/MODIFIED/REMOVED
-│   └── archive/            # Completed changes
-```
-
-## Creating Change Proposals
-
-### Decision Tree
-
-```
-New request?
-├─ Bug fix restoring spec behavior? → Fix directly
-├─ Typo/format/comment? → Fix directly  
-├─ New feature/capability? → Create proposal
-├─ Breaking change? → Create proposal
-├─ Architecture change? → Create proposal
-└─ Unclear? → Create proposal (safer)
-```
-
-### Proposal Structure
-
-1. **Create directory:** `changes/[change-id]/` (kebab-case, verb-led, unique)
-
-2. **Write proposal.md:**
-```markdown
-## Why
-[1-2 sentences on problem/opportunity]
-
-## What Changes
-- [Bullet list of changes]
-- [Mark breaking changes with **BREAKING**]
-
-## Impact
-- Affected specs: [list capabilities]
-- Affected code: [key files/systems]
-```
-
-3. **Create spec deltas:** `specs/[capability]/spec.md`
-```markdown
-## ADDED Requirements
-### Requirement: New Feature
-The system SHALL provide...
-
-#### Scenario: Success case
-- **WHEN** user performs action
-- **THEN** expected result
-
-## MODIFIED Requirements
-### Requirement: Existing Feature
-[Complete modified requirement]
-
-## REMOVED Requirements
-### Requirement: Old Feature
-**Reason**: [Why removing]
-**Migration**: [How to handle]
-```
-If multiple capabilities are affected, create multiple delta files under `changes/[change-id]/specs/<capability>/spec.md`—one per capability.
-
-4. **Create tasks.md:**
-```markdown
-## 1. Implementation
-- [ ] 1.1 Create database schema
-- [ ] 1.2 Implement API endpoint
-- [ ] 1.3 Add frontend component
-- [ ] 1.4 Write tests
-```
-
-5. **Create design.md when needed:**
-Create `design.md` if any of the following apply; otherwise omit it:
-- Cross-cutting change (multiple services/modules) or a new architectural pattern
-- New external dependency or significant data model changes
-- Security, performance, or migration complexity
-- Ambiguity that benefits from technical decisions before coding
-
-Minimal `design.md` skeleton:
-```markdown
-## Context
-[Background, constraints, stakeholders]
-
-## Goals / Non-Goals
-- Goals: [...]
-- Non-Goals: [...]
-
-## Decisions
-- Decision: [What and why]
-- Alternatives considered: [Options + rationale]
-
-## Risks / Trade-offs
-- [Risk] → Mitigation
-
-## Migration Plan
-[Steps, rollback]
-
-## Open Questions
-- [...]
-```
-
-## Spec File Format
-
-### Critical: Scenario Formatting
-
-**CORRECT** (use #### headers):
-```markdown
-#### Scenario: User login success
-- **WHEN** valid credentials provided
-- **THEN** return JWT token
-```
-
-**WRONG** (don't use bullets or bold):
-```markdown
-- **Scenario: User login**  ❌
-**Scenario**: User login     ❌
-### Scenario: User login      ❌
-```
-
-Every requirement MUST have at least one scenario.
-
-### Requirement Wording
-- Use SHALL/MUST for normative requirements (avoid should/may unless intentionally non-normative)
-
-### Delta Operations
-
-- `## ADDED Requirements` - New capabilities
-- `## MODIFIED Requirements` - Changed behavior
-- `## REMOVED Requirements` - Deprecated features
-- `## RENAMED Requirements` - Name changes
-
-Headers matched with `trim(header)` - whitespace ignored.
-
-#### When to use ADDED vs MODIFIED
-- ADDED: Introduces a new capability or sub-capability that can stand alone as a requirement. Prefer ADDED when the change is orthogonal (e.g., adding "Slash Command Configuration") rather than altering the semantics of an existing requirement.
-- MODIFIED: Changes the behavior, scope, or acceptance criteria of an existing requirement. Always paste the full, updated requirement content (header + all scenarios). The archiver will replace the entire requirement with what you provide here; partial deltas will drop previous details.
-- RENAMED: Use when only the name changes. If you also change behavior, use RENAMED (name) plus MODIFIED (content) referencing the new name.
-
-Common pitfall: Using MODIFIED to add a new concern without including the previous text. This causes loss of detail at archive time. If you aren’t explicitly changing the existing requirement, add a new requirement under ADDED instead.
-
-Authoring a MODIFIED requirement correctly:
-1) Locate the existing requirement in `openspec/specs/<capability>/spec.md`.
-2) Copy the entire requirement block (from `### Requirement: ...` through its scenarios).
-3) Paste it under `## MODIFIED Requirements` and edit to reflect the new behavior.
-4) Ensure the header text matches exactly (whitespace-insensitive) and keep at least one `#### Scenario:`.
-
-Example for RENAMED:
-```markdown
-## RENAMED Requirements
-- FROM: `### Requirement: Login`
-- TO: `### Requirement: User Authentication`
-```
-
-## Troubleshooting
-
-### Common Errors
-
-**"Change must have at least one delta"**
-- Check `changes/[name]/specs/` exists with .md files
-- Verify files have operation prefixes (## ADDED Requirements)
-
-**"Requirement must have at least one scenario"**
-- Check scenarios use `#### Scenario:` format (4 hashtags)
-- Don't use bullet points or bold for scenario headers
-
-**Silent scenario parsing failures**
-- Exact format required: `#### Scenario: Name`
-- Debug with: `openspec show [change] --json --deltas-only`
-
-### Validation Tips
-
-```bash
-# Always use strict mode for comprehensive checks
-openspec validate [change] --strict
-
-# Debug delta parsing
-openspec show [change] --json | jq '.deltas'
-
-# Check specific requirement
-openspec show [spec] --json -r 1
-```
-
-## Happy Path Script
-
-```bash
-# 1) Explore current state
-openspec spec list --long
-openspec list
-# Optional full-text search:
-# rg -n "Requirement:|Scenario:" openspec/specs
-# rg -n "^#|Requirement:" openspec/changes
-
-# 2) Choose change id and scaffold
-CHANGE=add-two-factor-auth
-mkdir -p openspec/changes/$CHANGE/{specs/auth}
-printf "## Why\n...\n\n## What Changes\n- ...\n\n## Impact\n- ...\n" > openspec/changes/$CHANGE/proposal.md
-printf "## 1. Implementation\n- [ ] 1.1 ...\n" > openspec/changes/$CHANGE/tasks.md
-
-# 3) Add deltas (example)
-cat > openspec/changes/$CHANGE/specs/auth/spec.md << 'EOF'
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-Users MUST provide a second factor during login.
-
-#### Scenario: OTP required
-- **WHEN** valid credentials are provided
-- **THEN** an OTP challenge is required
-EOF
-
-# 4) Validate
-openspec validate $CHANGE --strict
-```
-
-## Multi-Capability Example
-
-```
-openspec/changes/add-2fa-notify/
-├── proposal.md
-├── tasks.md
-└── specs/
-    ├── auth/
-    │   └── spec.md   # ADDED: Two-Factor Authentication
-    └── notifications/
-        └── spec.md   # ADDED: OTP email notification
-```
-
-auth/spec.md
-```markdown
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-...
-```
-
-notifications/spec.md
-```markdown
-## ADDED Requirements
-### Requirement: OTP Email Notification
-...
-```
-
-## Best Practices
-
-### Simplicity First
-- Default to <100 lines of new code
-- Single-file implementations until proven insufficient
-- Avoid frameworks without clear justification
-- Choose boring, proven patterns
-
-### Complexity Triggers
-Only add complexity with:
-- Performance data showing current solution too slow
-- Concrete scale requirements (>1000 users, >100MB data)
-- Multiple proven use cases requiring abstraction
-
-### Clear References
-- Use `file.ts:42` format for code locations
-- Reference specs as `specs/auth/spec.md`
-- Link related changes and PRs
-
-### Capability Naming
-- Use verb-noun: `user-auth`, `payment-capture`
-- Single purpose per capability
-- 10-minute understandability rule
-- Split if description needs "AND"
-
-### Change ID Naming
-- Use kebab-case, short and descriptive: `add-two-factor-auth`
-- Prefer verb-led prefixes: `add-`, `update-`, `remove-`, `refactor-`
-- Ensure uniqueness; if taken, append `-2`, `-3`, etc.
-
-## Tool Selection Guide
-
-| Task | Tool | Why |
-|------|------|-----|
-| Find files by pattern | Glob | Fast pattern matching |
-| Search code content | Grep | Optimized regex search |
-| Read specific files | Read | Direct file access |
-| Explore unknown scope | Task | Multi-step investigation |
-
-## Error Recovery
-
-### Change Conflicts
-1. Run `openspec list` to see active changes
-2. Check for overlapping specs
-3. Coordinate with change owners
-4. Consider combining proposals
-
-### Validation Failures
-1. Run with `--strict` flag
-2. Check JSON output for details
-3. Verify spec file format
-4. Ensure scenarios properly formatted
-
-### Missing Context
-1. Read project.md first
-2. Check related specs
-3. Review recent archives
-4. Ask for clarification
-
-## Quick Reference
-
-### Stage Indicators
-- `changes/` - Proposed, not yet built
-- `specs/` - Built and deployed
-- `archive/` - Completed changes
-
-### File Purposes
-- `proposal.md` - Why and what
-- `tasks.md` - Implementation steps
-- `design.md` - Technical decisions
-- `spec.md` - Requirements and behavior
-
-### CLI Essentials
-```bash
-openspec list              # What's in progress?
-openspec show [item]       # View details
-openspec validate --strict # Is it correct?
-openspec archive <change-id> [--yes|-y]  # Mark complete (add --yes for automation)
-```
-
-Remember: Specs are truth. Changes are proposals. Keep them in sync.

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-devin-desktop-support/.openspec.yaml

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

openspec/changes/add-devin-desktop-support/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+- Windsurf has been [rebranded to **Devin Desktop**](https://docs.devin.ai/desktop/devin-desktop-faq) as of June 2, 2026. Same IDE, same editor, new brand.
+- The rebrand moved the config directory: `.devin/` is now the preferred read + write location and `.windsurf/` the legacy read-only fallback, for `rules/`, `workflows/`, `skills/`, and `plans/`. OpenSpec writes only `.windsurf/`, so every Devin install lands in the deprecated path.
+- Devin ships two agents. Devin Desktop (Cascade) reads workflows; the [Devin Local agent does not](https://docs.devin.ai/desktop/devin-local) — its docs say to migrate workflows to skills, and it does not read `.windsurf/` at all. An existing Windsurf user's OpenSpec files are therefore invisible to Devin Local entirely.
+- Adding `devin` as a *second* tool id alongside `windsurf` would list one product twice in the picker and leave existing users with two parallel installs. This follows the rename instead, matching what OpenSpec already did for Kimi CLI → Kimi Code.
+
+## What Changes
+
+- **Rename the tool, don't duplicate it.** `windsurf` is retired as a tool id; `devin` (Devin Desktop) takes its place with `skillsDir: '.devin'` and `detectionPaths: ['.devin', '.windsurf']`. The Windsurf adapter is replaced by a Devin adapter writing `.devin/workflows/opsx-<id>.md`.
+- **Keep `--tools windsurf` working.** A `TOOL_ID_ALIASES` map resolves retired ids, so existing setup scripts and CI keep running; they now configure `.devin/`.
+- **Migrate existing installs, with consent.** OpenSpec-managed skills (`openspec-*`) and command files (`opsx-*`) under `.windsurf/` move to `.devin/`. `openspec update` explains the rebrand and asks first; `--force` and non-interactive runs take the move. Selecting the tool during `openspec init` is itself consent. Files the user wrote are never touched.
+- Route Devin's **skill** bodies and the getting-started hint through the skill-reference transformer so they say `/openspec-*`, the one invocation both Devin agents accept.
+- Update the tool reference, invocation, and command-syntax tables in `docs/`, plus the website tool list.
+
+## Impact
+
+- **Specs:** `ai-tool-paths`, `cli-init`, `cli-update`, `command-generation`
+- **Code:**
+  - `src/core/command-generation/adapters/devin.ts` (new; `windsurf.ts` deleted)
+  - `src/core/command-generation/registry.ts`, `adapters/index.ts`, `index.ts`
+  - `src/core/config.ts` (`AI_TOOLS` row, `TOOL_ID_ALIASES`, `resolveToolIdAlias`)
+  - `src/core/migration.ts` (`LEGACY_TOOL_ROOTS`, consent-aware migration of skills *and* command files)
+  - `src/core/init.ts`, `src/core/update.ts` (alias resolution, migration prompt)
+  - `src/core/legacy-cleanup.ts` (pre-opsx `.windsurf/` files now key to `devin`)
+  - `src/utils/command-references.ts` (Devin's skill-reference transformer)
+- **Docs:** `supported-tools.md`, `cli.md`, `commands.md`, `how-commands-work.md`, `faq.md`, `migration-guide.md`, `opsx.md`, website home page
+
+## Notes
+
+- **Who could be affected:** a user still on a pre-rebrand Windsurf build reads only `.windsurf/`. That is why the move is offered rather than taken — declining leaves every file where it is. Declining does mean `.windsurf/` stops being refreshed, which the prompt says plainly.
+- The `.devin/` directory also covers `rules/` and `plans/`. OpenSpec writes neither, so they are out of scope and untouched.

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

@@ -0,0 +1,137 @@
+# ai-tool-paths Delta Specification
+
+## ADDED Requirements
+
+### Requirement: Migrating OpenSpec content out of a renamed tool's former directory
+
+When a tool's directory is renamed, OpenSpec-managed content left in the former
+location SHALL be moved to the current one. Content the user wrote SHALL never
+be moved or deleted.
+
+Some renames are safe to apply silently and some are not, so each former root
+declares whether leaving it needs the user's consent. Kimi CLI is gone, so
+`.kimi` can be vacated without asking. Windsurf's `.windsurf` cannot: a
+pre-rebrand Windsurf build reads only that directory, and nothing on disk
+distinguishes that user from one who took the rebrand.
+
+#### Scenario: Moving a former directory that needs no consent
+
+- **WHEN** `openspec init` or `openspec update` runs and OpenSpec-managed content is found under a former root marked as needing no consent, such as `.kimi`
+- **THEN** move it to the tool's current directory without prompting
+- **AND** report what moved
+
+#### Scenario: Offering a move that needs consent
+
+- **GIVEN** OpenSpec skills or command files under `.windsurf/`
+- **WHEN** `openspec update` runs interactively without `--force`
+- **THEN** explain that Windsurf is now Devin Desktop, that `.devin/` is the current directory, and that Devin Local does not read `.windsurf/` at all
+- **AND** ask before moving anything
+- **AND** on decline, leave every file untouched and state that `.windsurf/` will no longer be refreshed until it is moved
+
+#### Scenario: Unattended runs take the move
+
+- **WHEN** `openspec update` runs with `--force`, or non-interactively
+- **THEN** perform the move without prompting, reporting what moved
+
+#### Scenario: Selecting a renamed tool is consent
+
+- **WHEN** `openspec init` configures a tool that has OpenSpec content under a former root
+- **THEN** move that content as part of setup, rather than leaving the user with two installs of one tool
+
+#### Scenario: Both directories already hold OpenSpec content
+
+- **GIVEN** the same OpenSpec-managed skill or command exists under both the former and the current root
+- **WHEN** the move runs
+- **THEN** the copy under the current root SHALL win, rather than being merged or overwritten
+- **AND** only the file OpenSpec generated SHALL be removed from the former root — for a skill directory that is `SKILL.md` alone, never the directory and whatever else it holds
+- **AND** one rule SHALL govern skills and command files alike: the former copy SHALL be removed only when it is byte-identical to the surviving one
+- **AND** a former copy that differs SHALL be left where it is, since the difference may be a customization
+- **AND** files left behind for that reason SHALL be reported, so the user knows two copies now exist
+
+#### Scenario: Every former file differs, so nothing is movable
+
+- **GIVEN** every OpenSpec-managed file under the former root differs from its counterpart under the current one
+- **WHEN** the move runs
+- **THEN** report the files left in place, rather than staying silent because nothing moved
+- **AND** NOT offer to move anything, since there is nothing movable to consent to
+- **AND** NOT report a migration that did not happen
+
+#### Scenario: One root is a symbolic link to the other
+
+- **GIVEN** the former and current roots resolve to the same directory, as when a user symlinks one at the other to straddle the rename
+- **WHEN** the move runs
+- **THEN** recognize that source and destination are the same file and change nothing, rather than deleting the only copy
+
+#### Scenario: User files survive the move
+
+- **GIVEN** a former root also holds files the user wrote, such as a hand-written workflow beside the generated ones
+- **WHEN** the move runs
+- **THEN** move only the files OpenSpec generates — each skill's `SKILL.md` and command files named `opsx-*`
+- **AND** delete the former directory only when the move leaves it empty
+
+#### Scenario: A user file beside a generated skill is not carried into a directory OpenSpec prunes
+
+- **GIVEN** a former skill directory holds `SKILL.md` alongside a file the user wrote
+- **AND** OpenSpec removes whole skill directories it owns, as under commands-only delivery or for a workflow outside the active profile
+- **WHEN** the move runs
+- **THEN** move `SKILL.md` alone and leave the user's file under the former root
+- **AND** never move the enclosing directory, which would hand that file to a later removal
+
+#### Scenario: The move is idempotent
+
+- **WHEN** `openspec update` runs again after a completed move
+- **THEN** find nothing to migrate and report nothing
+
+## MODIFIED Requirements
+
+### Requirement: Path configuration for supported tools
+
+The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
+
+#### Scenario: Claude Code paths defined
+
+- **WHEN** looking up the `claude` tool
+- **THEN** `skillsDir` SHALL be `.claude`
+
+#### Scenario: Cursor paths defined
+
+- **WHEN** looking up the `cursor` tool
+- **THEN** `skillsDir` SHALL be `.cursor`
+
+#### Scenario: Windsurf paths defined
+
+- **GIVEN** RETIRED — Windsurf was rebranded to Devin Desktop and `windsurf` is no longer a tool id
+- **WHEN** looking up the `windsurf` tool
+- **THEN** no `AI_TOOLS` entry SHALL exist for it
+- **AND** the id SHALL resolve to `devin`, whose `skillsDir` is `.devin` and whose `detectionPaths` still include the legacy `.windsurf`
+
+#### Scenario: Kimi Code paths defined
+
+- **WHEN** looking up the `kimi` tool
+- **THEN** `skillsDir` SHALL be `.kimi-code`
+- **AND** OpenSpec-managed skills remaining under the legacy `.kimi/skills` directory SHALL be migrated to `.kimi-code/skills` during init and update, preserving user files
+
+#### Scenario: Hermes Agent paths defined
+
+- **WHEN** looking up the `hermes` tool
+- **THEN** `skillsDir` SHALL be `.hermes`
+- **AND** `setupNote` SHALL explain that project `.hermes/skills` must be added to `skills.external_dirs` in `~/.hermes/config.yaml`
+- **AND** `openspec init` and `openspec update` SHALL display the note whenever `hermes` is configured
+
+#### Scenario: Devin Desktop paths defined
+
+- **WHEN** looking up the `devin` tool
+- **THEN** `skillsDir` SHALL be `.devin`
+- **AND** workflow files SHALL be written to `.devin/workflows/opsx-<id>.md`
+- **AND** `detectionPaths` SHALL include both `.devin` and the legacy `.windsurf`, so a project set up before the rebrand is still recognized
+
+#### Scenario: Retired tool ids resolve on the command line
+
+- **WHEN** a retired brand is named on the command line, such as `--tools windsurf`
+- **THEN** it SHALL resolve to the current tool id `devin` rather than erroring as unknown
+- **AND** generation SHALL write the current directory `.devin/`, not the retired one
+
+#### Scenario: Tools without skillsDir
+
+- **WHEN** a tool has no `skillsDir` defined
+- **THEN** skill generation SHALL error with message indicating the tool is not supported

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

@@ -0,0 +1,72 @@
+# cli-init Delta Specification
+
+## 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: Devin skills reference skills rather than workflows
+
+- **GIVEN** the Devin Local agent does not support workflows and its documentation directs users to skills instead
+- **WHEN** generating skills for the `devin` tool
+- **THEN** rewrite `/opsx:<id>` references in the skill body to the matching `/openspec-<skill>` invocation, which both Devin agents accept
+- **AND** the getting-started hint SHALL name `/openspec-propose` rather than a workflow
+- **AND** under commands-only delivery, where no Devin skills are written, both the workflow bodies and the hint SHALL fall back to `/opsx-<id>`
+
+### Requirement: Slash Command Generation
+
+The command SHALL generate opsx slash commands only for selected tools that have a registered command adapter, while keeping adapterless tools valid for skill generation.
+
+#### Scenario: Generating slash commands for a tool with a registered adapter
+
+- **WHEN** a tool with a registered command adapter is selected during initialization
+- **THEN** create 9 slash command files using the tool's command adapter:
+  - `/opsx:explore`
+  - `/opsx:new`
+  - `/opsx:continue`
+  - `/opsx:apply`
+  - `/opsx:ff`
+  - `/opsx:verify`
+  - `/opsx:sync`
+  - `/opsx:archive`
+  - `/opsx:bulk-archive`
+- **AND** use tool-specific path conventions (e.g., `.claude/commands/opsx/` for Claude)
+- **AND** include tool-specific frontmatter format
+
+#### Scenario: Selected tool has no command adapter
+
+- **GIVEN** a selected tool has `skillsDir` configured but no registered command adapter
+- **WHEN** initialization includes command generation
+- **THEN** skill generation for that tool SHALL still remain valid
+- **AND** command-file generation SHALL be skipped for that tool
+- **AND** the command output SHALL include `Commands skipped for: <tool-id> (no adapter)`
+
+#### Scenario: Kimi Code skips command-file generation
+
+- **WHEN** the user selects Kimi Code during initialization
+- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi-code'`
+- **AND** command-file generation SHALL be skipped because no Kimi adapter is registered
+
+#### Scenario: Generating workflows for Devin Desktop
+
+- **WHEN** the user selects Devin Desktop during initialization
+- **THEN** create one workflow file per profile workflow at `.devin/workflows/opsx-<id>.md`
+- **AND** include frontmatter with `name`, `description`, `category`, and `tags`
+- **AND** rewrite `/opsx:<id>` references in the body to `/opsx-<id>`, the name Devin registers for a workflow file

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

@@ -0,0 +1,113 @@
+# cli-update Delta Specification
+
+## MODIFIED Requirements
+
+### Requirement: Slash Command Updates
+
+The update command SHALL refresh existing slash command files for configured tools without creating new ones, and ensure the OpenCode archive command accepts change ID arguments.
+
+#### Scenario: Updating slash commands for Antigravity
+- **WHEN** `.agent/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh the OpenSpec-managed portion of each file so the workflow copy matches other tools while preserving the existing single-field `description` frontmatter
+- **AND** skip creating any missing workflow files during update, mirroring the behavior for Devin Desktop and other IDEs
+
+#### Scenario: Updating slash commands for Claude Code
+- **WHEN** `.claude/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for CodeBuddy Code
+- **WHEN** `.codebuddy/commands/openspec/` contains `proposal.md`, `apply.md`, and `archive.md`
+- **THEN** refresh each file using the shared CodeBuddy templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** use square bracket format for `argument-hint` parameters (e.g., `[change-id]`)
+- **AND** preserve any user customizations outside the OpenSpec managed markers
+
+#### Scenario: Updating slash commands for Cline
+- **WHEN** `.clinerules/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Cline-specific Markdown heading frontmatter
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Continue
+- **WHEN** `.continue/prompts/` contains `openspec-proposal.prompt`, `openspec-apply.prompt`, and `openspec-archive.prompt`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Crush
+- **WHEN** `.crush/commands/` contains `openspec/proposal.md`, `openspec/apply.md`, and `openspec/archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** include Crush-specific frontmatter with OpenSpec category and tags
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Cursor
+- **WHEN** `.cursor/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Factory Droid
+- **WHEN** `.factory/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using the shared Factory templates that include YAML frontmatter for the `description` and `argument-hint` fields
+- **AND** ensure the template body retains the `$ARGUMENTS` placeholder so user input keeps flowing into droid
+- **AND** update only the content inside the OpenSpec managed markers, leaving any unmanaged notes untouched
+- **AND** skip creating missing files during update
+
+#### Scenario: Updating slash commands for OpenCode
+- **WHEN** `.opencode/commands/` contains OpenSpec-managed `opsx-*.md` command files for the configured profile (for example `opsx-propose.md`, `opsx-apply.md`, and `opsx-archive.md`)
+- **THEN** refresh each file using shared templates
+- **AND** transform command references to hyphen form (for example `/opsx-propose`), as for every tool whose command files are named `opsx-<id>`
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** ensure the archive command includes `$ARGUMENTS` placeholder in frontmatter for accepting change ID arguments
+
+#### Scenario: Legacy OpenCode command path cleanup
+- **WHEN** a project still has command files under the legacy singular path `.opencode/command/` (for example `opsx-*.md` or `openspec-*.md`)
+- **THEN** `openspec init` or legacy cleanup SHALL remove those files and generate replacements under `.opencode/commands/`
+- **AND** `openspec update` SHALL NOT refresh files that remain only under `.opencode/command/`
+
+#### Scenario: Updating slash commands for Windsurf
+- **WHEN** the legacy Windsurf location `.windsurf/workflows/`, now Devin's, contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating workflows for Devin Desktop
+- **WHEN** Devin Desktop is a configured tool (its `.devin/` directory exists)
+- **THEN** write `.devin/workflows/opsx-<id>.md` for each workflow in the active profile, from shared templates
+- **AND** emit frontmatter with `name`, `description`, `category`, and `tags`
+- **AND** transform command references to hyphen form (for example `/opsx-propose`), the name Devin registers for a workflow file
+- **AND** refresh `.devin/skills/openspec-*/SKILL.md` with `/openspec-*` skill references, the one invocation both Devin agents accept
+
+#### Scenario: Updating slash commands for Kilo Code
+- **WHEN** `.kilocode/workflows/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates wrapped in OpenSpec markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+- **AND** skip creating missing files (the update command only refreshes what already exists)
+
+#### Scenario: Updating slash commands for Codex
+- **GIVEN** the global Codex prompt directory contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **WHEN** a user runs `openspec update`
+- **THEN** refresh each file using the shared slash-command templates (including placeholder guidance)
+- **AND** preserve any unmanaged content outside the OpenSpec marker block
+- **AND** skip creation when a Codex prompt file is missing
+
+#### Scenario: Updating slash commands for GitHub Copilot
+- **WHEN** `.github/prompts/` contains `openspec-proposal.prompt.md`, `openspec-apply.prompt.md`, and `openspec-archive.prompt.md`
+- **THEN** refresh each file using shared templates while preserving the YAML frontmatter
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Updating slash commands for Gemini CLI
+- **WHEN** `.gemini/commands/openspec/` contains `proposal.toml`, `apply.toml`, and `archive.toml`
+- **THEN** refresh the body of each file using the shared proposal/apply/archive templates
+- **AND** replace only the content between `<!-- OPENSPEC:START -->` and `<!-- OPENSPEC:END -->` markers inside the `prompt = """` block so the TOML framing (`description`, `prompt`) stays intact
+- **AND** skip creating any missing `.toml` files during update; only pre-existing Gemini commands are refreshed
+
+#### Scenario: Updating slash commands for iFlow CLI
+- **WHEN** `.iflow/commands/` contains `openspec-proposal.md`, `openspec-apply.md`, and `openspec-archive.md`
+- **THEN** refresh each file using shared templates
+- **AND** preserve the YAML frontmatter with `name`, `id`, `category`, and `description` fields
+- **AND** update only the OpenSpec-managed block between markers
+- **AND** ensure templates include instructions for the relevant workflow stage
+
+#### Scenario: Missing slash command file
+- **WHEN** a tool lacks a slash command file
+- **THEN** do not create a new file during update

openspec/changes/add-devin-desktop-support/specs/command-generation/spec.md

@@ -0,0 +1,45 @@
+# command-generation Delta Specification
+
+## 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`, `category`, `tags` fields
+- **AND** file path SHALL follow pattern `.claude/commands/opsx/<id>.md`
+
+#### Scenario: Cursor adapter formatting
+
+- **WHEN** formatting a command for Cursor
+- **THEN** the adapter SHALL output YAML frontmatter with `name` as `/opsx-<id>`, `id`, `category`, `description` fields
+- **AND** file path SHALL follow pattern `.cursor/commands/opsx-<id>.md`
+
+#### Scenario: Windsurf adapter formatting
+
+- **GIVEN** RETIRED — Windsurf was rebranded to Devin Desktop and its config directory moved
+- **WHEN** looking for a Windsurf adapter
+- **THEN** none SHALL be registered — it is replaced by the Devin adapter below, not kept alongside a second adapter for the same product
+
+#### Scenario: Devin Desktop adapter formatting
+
+- **WHEN** formatting a command for Devin Desktop
+- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
+- **AND** file path SHALL follow pattern `.devin/workflows/opsx-<id>.md`
+
+#### Scenario: Trae adapter formatting
+
+- **WHEN** formatting a command for Trae
+- **THEN** the adapter SHALL output YAML frontmatter with `name` and `description` fields
+- **AND** file path SHALL follow pattern `.trae/commands/opsx-<id>.md`

openspec/changes/add-devin-desktop-support/tasks.md

@@ -0,0 +1,44 @@
+# Implementation Tasks
+
+## 1. Adapter
+
+- [x] 1.1 Add `src/core/command-generation/adapters/devin.ts`: `.devin/workflows/opsx-<id>.md`, frontmatter `name`/`description`/`category`/`tags` via the shared helpers in `command-generation/yaml.ts`.
+- [x] 1.2 Keep the adapter a pure formatter: the `opsx-` filename prefix makes Devin a flat invocation, so the generator rewrites `/opsx:<id>` body references to `/opsx-<id>` — the name Devin registers for a workflow file.
+- [x] 1.3 Delete `adapters/windsurf.ts` and its registry/barrel entries; register `devinAdapter` in their place.
+
+## 2. Tool wiring
+
+- [x] 2.1 Replace the `windsurf` row in `AI_TOOLS` with `devin` (`skillsDir: '.devin'`, `detectionPaths: ['.devin', '.windsurf']`). Detection, the init picker, `--tools` validation, update, and profile sync all derive from this row.
+- [x] 2.2 Add `TOOL_ID_ALIASES` / `resolveToolIdAlias` in `src/core/config.ts` and apply it when parsing `--tools`, so `--tools windsurf` still resolves.
+- [x] 2.3 Re-key the pre-opsx `.windsurf/workflows/openspec-*.md` entry in `LEGACY_SLASH_COMMAND_PATHS` to `devin` — that map's keys are tool ids.
+- [x] 2.4 In `getTransformerForTool`, give `devin` the skill-reference transformer whenever skills are generated, so skill bodies and the getting-started hint say `/openspec-*` — the Devin Local agent has no workflows. Under commands-only delivery, fall through to the invocation rewrite.
+
+## 3. Migration
+
+- [x] 3.1 Replace `LEGACY_SKILLS_DIRS` with `LEGACY_TOOL_ROOTS`, each root carrying whether leaving it needs consent (`.kimi` no, `.windsurf` yes).
+- [x] 3.2 Extend the move to command files, deriving the legacy path from the adapter's own `getFilePath` so no layout is hard-coded. Skip absolute paths.
+- [x] 3.3 Split find from apply (`findLegacyToolMigrations` / `migrateLegacyToolDirs`) so a consent-gated move can be described before it happens.
+- [x] 3.4 `openspec update`: explain the rebrand, prompt interactively, migrate under `--force` or non-interactively, and say plainly what declining costs.
+- [x] 3.5 `openspec init`: treat selecting the tool as consent and migrate for the selected tools only.
+
+## 4. Documentation
+
+- [x] 4.1 `docs/supported-tools.md`: give Devin its own row in the authoritative "How To Invoke" table — the catch-all row would otherwise claim `/opsx-<id>` for both agents. Replace the Windsurf directory row and rewrite the footnote to cover the rename, the alias, and the migration.
+- [x] 4.2 Drop `windsurf` from the `--tools` ID lists in `docs/cli.md` and `docs/supported-tools.md`, noting it is still accepted as an alias.
+- [x] 4.3 Update the command-syntax tables in `docs/commands.md` and `docs/how-commands-work.md`, plus prose mentions in `faq.md`, `migration-guide.md`, `opsx.md`, and the website tool list.
+
+## 5. Tests
+
+- [x] 5.1 Adapter: tool id, `getFilePath`, and frontmatter. Hyphen rewriting is asserted end to end in the `generateCommand` flat-tool loop, and YAML escaping by the registry-derived parity matrix — both enroll Devin automatically.
+- [x] 5.2 Detection: `.devin` and legacy `.windsurf` both resolve to `devin`; neither present means not detected.
+- [x] 5.3 Alias: `--tools windsurf` writes `.devin/` and leaves no `.windsurf/`.
+- [x] 5.4 Migration: skills and workflows move, user-authored files in `.windsurf/` survive, and a second run migrates nothing.
+- [x] 5.5 `init`/`update`: both surfaces — `.devin/workflows/opsx-*.md` carry `/opsx-*`, `.devin/skills/openspec-*/SKILL.md` carry `/openspec-*`, and neither carries `/opsx:`.
+- [x] 5.6 `getTransformerForTool` returns the skill transformer for Devin under `both`/`skills` delivery and the hyphen form under `commands`.
+
+## 6. Verification
+
+- [x] 6.1 `openspec validate add-devin-desktop-support --strict`.
+- [x] 6.2 `openspec archive add-devin-desktop-support --yes` merges cleanly and additively (run on a scratch copy, then reverted).
+- [x] 6.3 Full suite green.
+- [x] 6.4 Manual journeys in scratch repos: legacy `.windsurf` install upgraded; both directories populated; IDE-written `.devin/rules/` preserved; `--tools windsurf` alias.

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-init-agents-target/.openspec.yaml

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

openspec/changes/add-init-agents-target/proposal.md

@@ -0,0 +1,33 @@
+## Why
+
+`.agents/skills` has become the shared, vendor-neutral location modern agent tools read. OpenSpec already carried an `agents` entry in `AI_TOOLS`, but with `available: false` and no `skillsDir` it was unreachable — every real gate keys off `skillsDir`. Teams running several agents on one repo, or a tool with no first-class integration yet, had to generate for some other tool and move the files by hand (#1480), or pick a vendor target they do not use (#1104, #653).
+
+## What Changes
+
+- Enable `agents` in `AI_TOOLS` with `skillsDir: '.agents'`, making it selectable interactively and via `--tools agents`.
+- Scope detection to `detectionPaths: ['.agents/skills']` so a bare `.agents/` written by another framework does not select — or silently install into — the target.
+- Rename the entry to `Shared .agents skills`. The old label said "AGENTS.md", but OpenSpec writes no `AGENTS.md` — it strips its markers out of one.
+- Document the target, including when to prefer it over a tool-specific integration.
+
+## Capabilities
+
+### New Capabilities
+
+_None._
+
+### Modified Capabilities
+
+- `ai-tool-paths`: define the `.agents` skills root and its scoped detection path
+- `cli-init`: record that the shared target installs skills and skips command generation
+
+## Impact
+
+- `src/core/config.ts` - enable the `agents` entry, scope detection, correct the label
+- `.changeset/add-agents-tool.md` - minor release note, including the `--tools all` behavior change
+- `docs/supported-tools.md`, `docs/cli.md`, `docs/commands.md`, `docs/how-commands-work.md`, `docs/troubleshooting.md` - list `agents` among skills-only tools and explain when to choose it
+- `test/core/*`, `test/commands/*`, `test/cli-e2e/*` - cover init, update, detection, and the deprecated alias
+
+## Non-Goals
+
+- No command adapter for `agents`. There is no cross-vendor slash-command format, so commands stay skills-only (the Kimi/Hermes pattern).
+- No `.pi`, `.codex`, or `.agent` migration into `.agents`. Moving vendor tools to the shared root is separate work (#830, #1157).

openspec/changes/add-init-agents-target/specs/ai-tool-paths/spec.md

@@ -0,0 +1,23 @@
+# ai-tool-paths Delta Specification
+
+## ADDED Requirements
+
+### Requirement: Shared .agents skills target
+
+OpenSpec SHALL provide a vendor-neutral `agents` tool target rooted at the shared `.agents` directory, for assistants that read skills from the shared location rather than a vendor-specific one.
+
+#### Scenario: Shared agents target paths defined
+
+- **WHEN** looking up the `agents` tool
+- **THEN** `skillsDir` SHALL be `.agents`
+
+#### Scenario: Detection keys off the shared skills subtree
+
+- **WHEN** a project contains a `.agents/skills` path
+- **THEN** OpenSpec SHALL detect `agents` as an available target
+
+#### Scenario: A bare shared root does not select the target
+
+- **GIVEN** a project contains `.agents` but no `.agents/skills` path
+- **WHEN** OpenSpec detects available tools
+- **THEN** `agents` SHALL NOT be reported as available

openspec/changes/add-init-agents-target/specs/cli-init/spec.md

@@ -0,0 +1,20 @@
+# cli-init Delta Specification
+
+## ADDED Requirements
+
+### Requirement: Shared .agents target initialization
+
+`openspec init` SHALL accept the shared `agents` target wherever tool IDs are selected, and SHALL treat it as a skills-only tool.
+
+#### Scenario: Non-interactive selection of the shared target
+
+- **WHEN** the user runs `openspec init --tools agents`
+- **THEN** OpenSpec SHALL generate skills for the `agents` target
+- **AND** initialization SHALL NOT fail because `agents` has no registered command adapter
+
+#### Scenario: Shared agents target skips command-file generation
+
+- **GIVEN** the configured delivery includes command generation
+- **WHEN** the user selects the shared `agents` target during initialization
+- **THEN** command-file generation SHALL be skipped because no `agents` adapter is registered
+- **AND** `agents` SHALL be listed among the tools reported as having commands skipped

openspec/changes/add-init-agents-target/tasks.md

@@ -0,0 +1,21 @@
+## 1. Tests
+
+- [x] 1.1 Cover `agents` init, update, detection, and the deprecated `experimental --tool` alias
+- [x] 1.2 Assert a bare `.agents/` directory does not select the target
+
+## 2. Registry
+
+- [x] 2.1 Enable `agents` in `src/core/config.ts` with `skillsDir: '.agents'`
+- [x] 2.2 Scope detection with `detectionPaths: ['.agents/skills']`
+- [x] 2.3 Rename the entry to `Shared .agents skills` so it names the directory instead of a file OpenSpec never writes
+
+## 3. Docs
+
+- [x] 3.1 Add `agents` to the tool ID lists in `docs/cli.md` and `docs/supported-tools.md`
+- [x] 3.2 Add the Tool Directory row and the skills-only invocation rows across `docs/supported-tools.md`, `docs/commands.md`, `docs/how-commands-work.md`, and `docs/troubleshooting.md`
+- [x] 3.3 Document when to choose the shared target over a tool-specific integration
+
+## 4. Verification
+
+- [x] 4.1 Run `pnpm run build` and the full Vitest suite
+- [x] 4.2 Validate with `openspec validate --strict`, and confirm `openspec archive` applies cleanly against a scratch copy of `openspec/`

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,116 @@
+# 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, or auto-select the only active change;
+     if still unclear, run `openspec list --json` and ask the user to choose
+     (most-recently-modified first). Announce the selection and how to override.
+
+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.