Add CLI path visibility guidance

2026-10-04 06:18:24 +08:00 · 2026-05-06 04:01:08 +10:00
668 changed files with 15737 additions and 101246 deletions
@@ -1,180 +0,0 @@
---
-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.
@@ -1,4 +0,0 @@
-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."
@@ -1,89 +0,0 @@
-# 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.
@@ -12,12 +12,11 @@ Follow the prompts to select version bump type and describe your changes.

 ## Workflow

-1. **Choose the release path**: Maintainers decide whether a PR follows the normal release cadence or gets dedicated release tracking.
-2. **Add dedicated release tracking**: When a maintainer asks for a changeset, run `pnpm changeset` locally before or after your PR.
-3. **Version PR**: CI opens/updates a "Version Packages" PR when changesets merge to main.
-4. **Release**: Merging the Version PR triggers npm publish and GitHub Release.
+1. **Add a changeset** — Run `pnpm changeset` locally before or after your PR
+2. **Version PR** — CI opens/updates a "Version Packages" PR when changesets merge to main
+3. **Release** — Merging the Version PR triggers npm publish and GitHub Release

-> **Note:** The default path is the normal release cadence. Add a changeset when a maintainer or release owner wants dedicated release notes and version tracking for the PR. Versioning (`changeset version`) and publishing happen automatically in CI.
+> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI.

 ## Template

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

 | Type | When to use | Example |
 |------|-------------|---------|
-| `patch` | Release-tracked bug fixes, small improvements | Fixed crash when config missing |
+| `patch` | Bug fixes, small improvements | Fixed crash when config missing |
 | `minor` | New features, non-breaking additions | Added `--verbose` flag |
 | `major` | Breaking changes, removed features | Renamed `init` to `setup` |

 ## When to Create a Changeset

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

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

 ## Writing Good Descriptions
@@ -0,0 +1,2 @@
+---
+---
@@ -0,0 +1,7 @@
+---
+"@fission-ai/openspec": patch
+---
+
+### Bug Fixes
+
+- **CLI path visibility**: OpenSpec now documents editor and agent PATH mismatches, warns during global installs when the detected CLI bin directory is not on PATH, and generates workflow skills with guidance for resolving `openspec` through `OPENSPEC_BIN` or an absolute path.
@@ -0,0 +1,11 @@
+---
+"@fission-ai/openspec": minor
+---
+
+### 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
@@ -0,0 +1,7 @@
+---
+"@fission-ai/openspec": minor
+---
+
+### New Features
+
+- Include the sync workflow in the default core profile so new installs generate `/opsx:sync` skills and commands by default.
@@ -1,6 +1,6 @@
 {
  "name": "OpenSpec Development",
-  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
+  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",

  // Additional tools and features
  "features": {
@@ -1,4 +0,0 @@
-# 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
@@ -1,2 +1,2 @@
 # Default code ownership
-* @Fission-AI/openspec-maintainers
+* @TabishB
@@ -1,98 +0,0 @@
-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:
-          - "*"
@@ -25,12 +25,10 @@ jobs:
      nix: ${{ steps.filter.outputs.nix }}
    steps:
      - name: Checkout code
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
+        uses: actions/checkout@v4

      - name: Check for Nix-related changes
-        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4
+        uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
@@ -39,15 +37,53 @@ jobs:
              - 'flake.lock'
              - 'package.json'
              - 'pnpm-lock.yaml'
-              - 'pnpm-workspace.yaml'
              - 'scripts/update-flake.sh'
              - '.github/workflows/ci.yml'

+  test_pr:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build project
+        run: pnpm run build
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Upload test coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report-pr
+          path: coverage/
+          retention-days: 7
+
  test_matrix:
    name: Test (${{ matrix.label }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group' || github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'push'
    strategy:
      fail-fast: false
      matrix:
@@ -55,15 +91,12 @@ 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:
@@ -71,18 +104,19 @@ jobs:

    steps:
      - name: Checkout code
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@v4
        with:
          fetch-depth: 0
-          persist-credentials: false

      - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9

      - name: Setup Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Print environment diagnostics
@@ -96,48 +130,32 @@ jobs:
        run: pnpm run build

      - name: Run tests
-        env:
-          VITEST_MAX_WORKERS: ${{ matrix.vitest_workers }}
        run: pnpm test

      - name: Upload test coverage
        if: matrix.os == 'ubuntu-latest'
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@v4
        with:
-          name: coverage-report-${{ github.event_name }}
+          name: coverage-report-main
          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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
+        uses: actions/checkout@v4

      - name: Setup pnpm
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9

      - name: Setup Node.js
-        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        uses: actions/setup-node@v4
        with:
-          node-version: '20.19.0'
+          node-version: '20'
          cache: 'pnpm'

      - name: Install dependencies
@@ -171,15 +189,13 @@ jobs:
    if: needs.changes.outputs.nix == 'true'
    steps:
      - name: Checkout code
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          persist-credentials: false
+        uses: actions/checkout@v4

      - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+        uses: DeterminateSystems/nix-installer-action@v21

      - name: Setup Nix cache
-        uses: DeterminateSystems/magic-nix-cache-action@908b263ff629f4cc17666315b7fd3ec127c6244d # v14
+        uses: DeterminateSystems/magic-nix-cache-action@v13

      - name: Build with Nix
        run: nix build
@@ -226,66 +242,47 @@ jobs:
        run: git checkout -- flake.nix || true

  validate-changesets:
-    name: Validate Release Tracking
+    name: Validate Changesets
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
    steps:
      - name: Checkout code
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        uses: actions/checkout@v4
        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
-        if: steps.changed-changesets.outputs.has_changesets == 'true'
-        uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9

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

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

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

  required-checks-pr:
    name: All checks passed
    runs-on: ubuntu-latest
-    needs: [test_matrix, lint, nix-flake-validate]
+    needs: [test_pr, lint, nix-flake-validate]
    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
    steps:
      - name: Verify all checks passed
        run: |
-          if [[ "${{ needs.test_matrix.result }}" != "success" ]]; then
-            echo "Matrix test job failed"
+          if [[ "${{ needs.test_pr.result }}" != "success" ]]; then
+            echo "Test job failed"
            exit 1
          fi
          if [[ "${{ needs.lint.result }}" != "success" ]]; then
@@ -1,15 +1,12 @@
-name: Release
+name: Release (prepare)

 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:
@@ -18,31 +15,29 @@ concurrency:

 jobs:
  prepare:
-    if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'push'
+    if: github.repository == 'Fission-AI/OpenSpec'
    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:
      # 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
+        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}

-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          token: ${{ steps.app-token.outputs.token }}

-      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9

-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+      - uses: actions/setup-node@v4
        with:
          node-version: '24' # Node 24 includes npm 11.5.1+ required for OIDC
          cache: 'pnpm'
@@ -53,7 +48,7 @@ jobs:
      # Opens/updates the Version Packages PR; publishes when the Version PR merges
      - name: Create/Update Version PR
        id: changesets
-        uses: changesets/action@a45c4d594aa4e2c509dc14a9f2b3b67ba3780d0d # v1
+        uses: changesets/action@v1
        with:
          title: 'chore(release): version packages'
          createGithubReleases: true
@@ -63,126 +58,3 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
          # npm authentication handled via OIDC trusted publishing (no token needed)
-
-  # Manually-dispatched beta prerelease from main: version is the next stable
-  # release per pending changesets with a -beta.N suffix (e.g. v1.6.0-beta.1),
-  # published to npm under the `beta` dist-tag and posted as a prerelease-flagged
-  # GitHub Release. Changesets are left unconsumed, so the stable flow above is
-  # unaffected. This job lives in this file because npm trusted publishing
-  # authorizes a single workflow file per package.
-  #
-  # Users opt in with: npm install -g @fission-ai/openspec@beta
-  beta:
-    if: github.repository == 'Fission-AI/OpenSpec' && github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@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
@@ -1,120 +0,0 @@
-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
@@ -148,7 +148,6 @@ CLAUDE.md

 # Pnpm
 .pnpm-store/
-/package-lock.json
 result

 # OpenCode
@@ -160,9 +159,3 @@ opencode.json

 # Bob
 .bob/
-
-# Trae
-.trae/
-
-# Cursor
-.cursor/
@@ -1,487 +1,5 @@
 # @fission-ai/openspec

-## 1.10.0
-
-### Minor Changes
-
- [#1685](https://github.com/Fission-AI/OpenSpec/pull/1685) [`c747ed1`](https://github.com/Fission-AI/OpenSpec/commit/c747ed1f34459ca6bc15d43ad9f68dfdf7750875) Thanks [@clay-good](https://github.com/clay-good)! - Add `openspec init --language <language>` to configure the language used for artifacts in new projects.
-
-### Patch Changes
-
- [#1704](https://github.com/Fission-AI/OpenSpec/pull/1704) [`7276c6c`](https://github.com/Fission-AI/OpenSpec/commit/7276c6c26832f699a63544302d38b1af8ddb9844) Thanks [@clay-good](https://github.com/clay-good)! - Drop the npm `postinstall` script. Its only job was printing a one-line tip about opt-in shell completions, but shipping any install script made `npm install -g @fission-ai/openspec` emit an `allow-scripts` warning that reads as a packaging fault (and `npm approve-scripts` then fails with `ENOMATCH` on a global install, since it looks in the local project). The tip now prints from the CLI on its first run — to stderr, in an interactive terminal, once, and not at all if you already have completions installed — and the published package declares no `preinstall`/`install`/`postinstall` script, so a registry install runs no OpenSpec code. Suppress the tip with `OPENSPEC_NO_COMPLETIONS=1`.
-
- [#1656](https://github.com/Fission-AI/OpenSpec/pull/1656) [`a72a74d`](https://github.com/Fission-AI/OpenSpec/commit/a72a74de6571c26fd79a193bb33fa3b8e1a767fb) Thanks [@clay-good](https://github.com/clay-good)! - ### Bug Fixes
-
-  - `openspec update` now suggests restarting an IDE only when it updates an IDE-resident tool. CLI tools such as Claude Code, Codex, and Gemini CLI no longer show an unnecessary restart hint.
-
- [#1703](https://github.com/Fission-AI/OpenSpec/pull/1703) [`9643888`](https://github.com/Fission-AI/OpenSpec/commit/9643888a7525467c7a076bfec9bb075910e78bb8) Thanks [@clay-good](https://github.com/clay-good)! - Point the spec-driven `specs` instruction's main-spec read and edit at the store-aware root. It named `openspec/specs/<capability-path>/spec.md`, a path relative to the current directory, for both step 1 of the MODIFIED workflow ("locate the existing requirement") and the edit that fixes a leftover `TBD` Purpose. When the change lives in a store — whether selected with `--store`, a project `store:` pointer, or a global default store — the main spec is under the store root, so that read missed it, or silently returned a different capability when a local one happened to share the name, and the MODIFIED block was then copied from the wrong requirement. Both operations now use `<planningHome.root>/openspec/specs/...`, the root already returned by `openspec instructions ... --json` and the same convention the sync and archive workflows use. Fixes [#1702](https://github.com/Fission-AI/OpenSpec/issues/1702).
-
- [#1699](https://github.com/Fission-AI/OpenSpec/pull/1699) [`18688c8`](https://github.com/Fission-AI/OpenSpec/commit/18688c8b27820da3435a47a7f11e90073724b728) Thanks [@clay-good](https://github.com/clay-good)! - archive: tell the author how to retire a capability when the emptied spec also holds content the merge cannot account for. That combination printed only "Spec must have at least one requirement" and no guidance at all; the abort now names the blocking lines and reports a `retire_capabilities` marker that is present but cannot be honored. Authored content quoted in those messages - the blocking lines, and the marker's own reason, which `openspec validate` prints too - is stripped of control characters and bounded in length before it reaches the terminal.
-
- [#1660](https://github.com/Fission-AI/OpenSpec/pull/1660) [`7da3f34`](https://github.com/Fission-AI/OpenSpec/commit/7da3f34fb66d602bd987caa7dddcf3d6621e7d44) Thanks [@clay-good](https://github.com/clay-good)! - Require generated tasks to state how their completion can be verified.
-
-## 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
@@ -7,13 +7,6 @@ People who maintain and guide OpenSpec.
 | 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

@@ -47,14 +47,6 @@ Our philosophy:
 ## 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
@@ -76,29 +68,6 @@ 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>

@@ -108,18 +77,6 @@ OpenSpec is built with OpenSpec — browse this repo's live [specs](openspec/spe

 </details>

-## Why teams adopt OpenSpec
-
-Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
-
-**[Stores](docs/stores-beta/user-guide.md)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
-
- **Cross-repo features** — one change, one plan, even when the code lands in three repos.
- **Shared requirements** — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
- **Plan before code** — capture the plan in the store now; the code repos catch up later.
-
-> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
-
 ## Quick Start

 **Requires Node.js 20.19.0 or higher.**
@@ -137,42 +94,25 @@ cd your-project
 openspec init
 ```

-> **Want your AI to do it?** Paste the [setup prompt](docs/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+Now tell your AI: `/opsx:propose <what-you-want-to-build>`

-Now talk to your AI:
-
- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
-
-Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
-
-`/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).
+If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.

 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
 >
 > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).

 ## Docs

-**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
-
 → **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
-→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
-→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
-→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
 → **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
-→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
 → **[Commands](docs/commands.md)**: slash commands & skills<br>
 → **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
 → **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
 → **[Concepts](docs/concepts.md)**: how it all fits<br>
 → **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours<br>
-→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
+→ **[Customization](docs/customization.md)**: make it yours


 ## Community schemas
@@ -189,7 +129,7 @@ AI coding assistants are powerful but unpredictable when requirements live only
 - **Agree before you build** — human and AI align on specs before code gets written
 - **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
 - **Work fluidly** — update any artifact anytime, no rigid phase gates
- **Use your tools** — works with 30+ AI assistants via slash commands
+- **Use your tools** — works with 20+ AI assistants via slash commands

 ### How we compare

@@ -217,7 +157,7 @@ openspec update

 ## Usage Notes

-**Model selection**: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 for both planning and implementation.
+**Model selection**: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.

 **Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.

@@ -248,9 +188,7 @@ 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)
+**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`

 </details>

@@ -1,62 +0,0 @@
-# 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/`, and `schemas/`. 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 scripts | The package ships no `preinstall`, `install`, or `postinstall` script, so installing it from the npm registry runs no code from OpenSpec. (`prepare` is still declared; npm runs it only for git and local-directory installs, where it builds from source.) Shell completions are opt-in via `openspec completion install`; the CLI prints a one-line tip about them on its first run. |
-| 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.
@@ -0,0 +1,470 @@
+# Workspace Reimplementation Direction
+
+Date: 2026-04-30
+
+Fresh-agent entry point: read `WORKSPACE_REIMPLEMENTATION_START_HERE.md` first, then return to this document for the full product direction.
+
+This document captures the intended direction for reimplementing OpenSpec workspace support from scratch, based on what we learned from the workspace POC.
+
+The reimplementation should be ordered around the path a real user takes through OpenSpec:
+
+```text
+set up workspace
+  -> link repos or folders
+  -> open workspace
+  -> explore across repos or folders
+  -> create proposal
+  -> apply one repo slice
+  -> verify
+  -> archive
+```
+
+The goal is not to rebuild every POC mechanism. The goal is to get one user-facing capability working at a time, in the same order a user would naturally create, implement, verify, and archive a change.
+
+## North Star
+
+A user should think:
+
+```text
+I have a multi-repo product goal.
+I set up an OpenSpec workspace.
+I open it with my agent.
+The agent can see the linked repos or folders.
+We explore until the scope is clear.
+Then we create a proposal.
+Then we implement one repo slice at a time.
+```
+
+They should not think:
+
+```text
+I need to create a change so repos become visible.
+I need to materialize repo-local artifacts.
+I need to understand implementation-specific workspace machinery.
+I need to manage target metadata separately from proposal files.
+```
+
+The core product rule is:
+
+```text
+Workspace visibility is not change commitment.
+```
+
+Linked repos or folders are planning context. Creating a change is a planning commitment. Applying a change is an implementation workflow.
+
+## Build Order
+
+### 1. Workspace Setup And Links
+
+First make workspace setup boring and solid.
+
+User goal:
+
+```text
+Create a planning home and link the repos or folders OpenSpec should know about.
+```
+
+Expected surface:
+
+```bash
+openspec workspace setup
+openspec workspace setup --no-interactive --name platform --link /path/to/api --link web=/path/to/web
+openspec workspace list
+openspec workspace ls
+openspec workspace link /path/to/api
+openspec workspace link api-service /path/to/api
+openspec workspace relink api /new/path/to/api
+openspec workspace doctor
+```
+
+Expected outcome:
+
+```text
+workspace-folder/
+  changes/
+  .openspec-workspace/
+    workspace.yaml
+    local.yaml
+```
+
+Product decisions:
+
+- Use `.openspec-workspace/`, not `.openspec/`, for workspace metadata.
+- Keep `changes/` visible in the workspace folder.
+- Keep setup as the only public creation path for the first release; do not expose `workspace create`.
+- Use `workspace link` and `workspace relink`, not POC-era `add-repo` or `update-repo`.
+- Allow linked repos or folders without repo-local `openspec/` state.
+- Keep stable link names in shared workspace state and local paths in machine-local state.
+- Make `doctor` show link names, resolved paths, repo-local specs paths when present, and suggested fixes.
+
+Defer:
+
+- Agent launch and workspace open behavior.
+- Preferred-agent prompts.
+- Owner or handoff metadata.
+- Workspace change creation or target selection.
+- Branches.
+- Worktrees.
+- Apply.
+- Archive.
+- Complex target lifecycle.
+
+Done when a user can set up a workspace, link repos or folders, list known workspaces, relink local paths, and run `doctor` to see exactly what OpenSpec can resolve.
+
+### 2. Workspace Open
+
+Next make the workspace openable in the way users expect.
+
+User goal:
+
+```text
+Open this multi-repo planning context with my coding agent.
+```
+
+Expected surface:
+
+```bash
+openspec workspace open
+openspec workspace open --agent codex
+openspec workspace open --agent github-copilot
+```
+
+Product behavior:
+
+- `workspace open` opens the coordination workspace plus linked repos or folders.
+- Repo visibility is default.
+- Change selection is optional focus, not the mechanism for repo access.
+- `--agent` should be a one-session override by default. Persisting the preferred agent should require an explicit preference-setting action.
+
+For GitHub Copilot, generate or open a `.code-workspace` file with:
+
+```text
+workspace folder
+linked repo or folder A
+linked repo or folder B
+```
+
+For Claude and Codex, attach the linked repo or folder directories through the agent's supported mechanism.
+
+Defer:
+
+- `workspace open --change`.
+- In-session upgrade flows.
+- Per-change attachment restrictions.
+
+Done when opening a workspace gives the agent visibility into the coordination root and all linked repos or folders.
+
+### 3. Agent Guidance And Explore
+
+Then make exploration work.
+
+User goal:
+
+```text
+Tell the agent a rough product goal and have it inspect the repos before creating a proposal.
+```
+
+Expected user prompt:
+
+```text
+Explore how we should make the OpenSpec docs available on the landing page.
+Look across the linked repos or folders, but do not implement yet.
+```
+
+Agent behavior:
+
+- Understand it is in workspace mode.
+- Inspect linked repos or folders.
+- Explain likely affected repos.
+- Ask for clarification only when needed.
+- Avoid implementation edits during explore.
+
+Build:
+
+- Workspace-level `AGENTS.md` guidance.
+- Normal OpenSpec skills and commands in workspace sessions.
+- Workspace-specific guidance layered on top of normal `/explore`, not replacing it.
+
+Defer:
+
+- Proposal artifact generation.
+- Target confirmation commands.
+- Apply context providers.
+
+Done when a user can open a workspace and run a useful cross-repo exploration without creating a dummy change.
+
+### 4. Proposal Creation
+
+Only after explore works, build proposal creation.
+
+User goal:
+
+```text
+Now that we understand the scope, capture the plan.
+```
+
+Expected user prompt:
+
+```text
+Create a proposal for this change.
+Target the repos that are actually affected.
+```
+
+Preferred artifact shape:
+
+```text
+changes/integrate-docs/
+  proposal.md
+  design.md
+  tasks.md
+  specs/
+    openspec/
+      docs-conventions/spec.md
+    landing/
+      docs-routing/spec.md
+```
+
+Key workflow rule:
+
+```text
+/explore may leave targets unknown.
+/propose may discover targets.
+/propose must confirm targets before saying ready for apply.
+```
+
+Targets should be represented by the proposal artifacts themselves where possible. If there is `specs/landing/...`, then `landing` is in scope. Avoid a separate required `targets: [...]` metadata list as the active source of truth.
+
+Defer:
+
+- Repo-local materialization.
+- Worktree selection.
+- Multi-repo implementation.
+- Archive.
+
+Done when a user can explore, then create a workspace proposal with repo-scoped specs and tasks.
+
+### 5. Status
+
+Before implementation, make status excellent.
+
+User goal:
+
+```text
+Where are we, what repos are involved, and is this ready to implement?
+```
+
+Expected surface:
+
+```bash
+openspec status
+openspec status --change integrate-docs
+```
+
+Human output should answer:
+
+```text
+Change: integrate-docs
+Scope: openspec, landing
+Proposal: present
+Design: present
+Tasks: present
+Ready for apply: yes/no
+```
+
+Status should also catch structural mistakes:
+
+- Unknown repo folder under `specs/`.
+- Missing tasks.
+- No confirmed affected repo.
+- Linked repo or folder path missing.
+
+Done when the agent and user can trust status before applying.
+
+### 6. Apply One Repo Slice
+
+Only now build `/apply`.
+
+User goal:
+
+```text
+Implement the planned slice for one repo.
+```
+
+Expected user prompt:
+
+```text
+/apply integrate-docs for landing
+```
+
+Product contract:
+
+```text
+/apply means implement.
+```
+
+It does not mean:
+
+```text
+copy planning files
+materialize repo-local OpenSpec state
+create the proposal files for the first time
+```
+
+Agent behavior:
+
+1. Ask OpenSpec for apply context.
+2. Read proposal, design, tasks, and relevant specs.
+3. Confirm the target repo checkout.
+4. Edit only that repo.
+5. Update workspace tasks.
+6. Run relevant checks.
+
+This likely wants a normalized context command internally, but that is supporting machinery:
+
+```json
+{
+  "mode": "workspace",
+  "change": "integrate-docs",
+  "target": "landing",
+  "implementationRoot": "/repos/openspec-landing",
+  "contextFiles": [
+    "changes/integrate-docs/proposal.md",
+    "changes/integrate-docs/design.md",
+    "changes/integrate-docs/tasks.md",
+    "changes/integrate-docs/specs/landing/docs-routing/spec.md"
+  ],
+  "allowedEditRoots": [
+    "/repos/openspec-landing"
+  ],
+  "tasksFile": "changes/integrate-docs/tasks.md"
+}
+```
+
+Defer:
+
+- Applying multiple repos at once.
+- Automatic branch creation.
+- Worktree management.
+- Repo-local OpenSpec mirroring.
+
+Done when one repo slice can be implemented from the central workspace plan.
+
+### 7. Verify
+
+Then build verification.
+
+User goal:
+
+```text
+Check whether the implemented repo slice satisfies the plan.
+```
+
+Expected prompt:
+
+```text
+/verify integrate-docs for landing
+```
+
+Behavior:
+
+- Read the same normalized context as `/apply`.
+- Inspect the implementation checkout.
+- Check tasks and specs for that repo.
+- Run repo validation.
+- Report gaps clearly.
+
+Default behavior should verify one repo slice. Whole-workspace verification can come later.
+
+Done when a user can verify one implemented repo slice against the central workspace plan.
+
+### 8. Archive
+
+Archive comes last in the first complete loop.
+
+User goal:
+
+```text
+The change is done. Move it out of active planning.
+```
+
+Expected prompt:
+
+```text
+/archive integrate-docs
+```
+
+Behavior:
+
+- Require all targeted repo slices to be complete or explicitly accepted.
+- Archive the workspace change.
+- Do not require repo-local planning copies unless OpenSpec later decides that repo-local archival matters.
+
+Done when a user can complete the full lifecycle:
+
+```text
+workspace setup
+  -> link repos or folders
+  -> open
+  -> explore
+  -> propose
+  -> apply repo A
+  -> apply repo B
+  -> verify
+  -> archive
+```
+
+## Implementation Discipline
+
+Build only the next user-visible step.
+
+The sequence should stay grounded in these questions:
+
+```text
+1. Can I set up the workspace?
+2. Can I see my linked repos or folders?
+3. Can my agent explore them?
+4. Can we capture a proposal?
+5. Can status tell us if it is ready?
+6. Can the agent implement one repo slice?
+7. Can we verify it?
+8. Can we archive it?
+```
+
+Avoid starting with internal abstractions unless they are required for the next user-visible capability.
+
+Do not start with:
+
+- Target metadata machinery.
+- Materialization.
+- Adapter abstractions.
+- Branch orchestration.
+- Worktree orchestration.
+- Multi-repo apply.
+
+Those may matter later, but they should not define the first reimplementation path.
+
+## Product Shape
+
+The workspace should feel like OpenSpec's normal workflow stretched across multiple repos, not a second product with its own lifecycle.
+
+The durable product model is:
+
+```text
+workspace = durable planning home
+links = repos or folders visible for planning
+proposal = scoped planning commitment
+repo slice = one affected repo or folder in the plan
+branch/worktree = implementation checkout
+/apply = implement one selected repo slice
+```
+
+Keep the user journey simple:
+
+```text
+Open the workspace.
+Ask the agent to explore.
+Create the proposal when scope is clear.
+Implement one repo slice at a time.
+Verify.
+Archive.
+```
@@ -0,0 +1,67 @@
+# Workspace Reimplementation Start Here
+
+This is the grep-friendly entry point for agents working on the workspace reimplementation.
+
+Useful search terms:
+
+```text
+workspace reimplementation
+workspace poc
+workspace-poc
+workspace reference guide
+workspace roadmap
+fresh agent
+start here
+```
+
+## Start Here
+
+Read these files in order:
+
+1. `WORKSPACE_REIMPLEMENTATION_DIRECTION.md`
+2. `openspec/changes/workspace-reimplementation-roadmap/README.md`
+3. `openspec/changes/workspace-reimplementation-roadmap/POC_REFERENCE_GUIDE.md`
+4. The proposal for the next implementation slice
+
+The POC reference commit is:
+
+```text
+workspace-poc @ 79a45ac043f414e63d13e08b9da83b135cb20a39
+```
+
+Use the POC as research material. Do not merge it into an implementation branch. Do not preserve its architecture unless a slice proposal or design explicitly decides to do so.
+
+## Implementation Order
+
+Implement these flat OpenSpec changes in order:
+
+1. `workspace-foundation`
+2. `workspace-create-and-register-repos`
+3. `workspace-open-agent-context`
+4. `workspace-change-planning`
+5. `workspace-apply-repo-slice`
+6. `workspace-verify-and-archive`
+
+`workspace-reimplementation-roadmap` is the continuity and reference container for the plan.
+
+## Before Editing
+
+For the slice you are about to implement, inspect the pinned POC commit using `POC_REFERENCE_GUIDE.md`, then write down:
+
+```text
+POC findings for <slice>:
+
+User behavior to preserve:
+- ...
+
+Tests or examples worth translating:
+- ...
+
+Implementation shortcuts to avoid:
+- ...
+
+Open design questions:
+- ...
+```
+
+Capture durable findings in the relevant OpenSpec artifact so future sessions do not depend on chat history.
@@ -1,5 +1,3 @@
 #!/usr/bin/env node

-import { runCli } from '../dist/cli/index.js';
-
-runCli();
+import '../dist/cli/index.js';
@@ -1,114 +0,0 @@
-# OpenSpec Documentation
-
-Welcome. This is the home for everything OpenSpec.
-
-OpenSpec helps you and your AI coding assistant **agree on what to build before any code is written.** You describe the change, the AI drafts a short spec and a task list, you both look at the same plan, and then the work happens. No more discovering halfway through that the AI built the wrong thing.
-
-If you read nothing else, read these two pages:
-
-1. [Getting Started](getting-started.md): install, initialize, and ship your first change.
-2. [How Commands Work](how-commands-work.md): where you actually type `/opsx:propose` (hint: in your AI chat, not the terminal). This trips up almost everyone once.
-
-That second one matters more than it looks. OpenSpec has two halves: a command line tool you run in your terminal, and slash commands you give to your AI assistant. Knowing which is which saves you the most common moment of confusion.
-
-> **The best habit to build first: when you're not sure what to build, start with `/opsx:explore`.** It's a no-stakes thinking partner that reads your code, weighs options, and sharpens a fuzzy idea into a concrete plan before any artifact or code exists. The [Explore First](explore.md) guide makes the case.
-
-## Pick your path
-
-**I'm brand new.** Start with [Getting Started](getting-started.md), then skim the [Core Concepts at a Glance](overview.md). When something feels mysterious, the [FAQ](faq.md) and [Glossary](glossary.md) are nearby.
-
-**I have a problem but not a plan.** This is the common case, and it has a dedicated answer: [Explore First](explore.md). Use `/opsx:explore` to think it through with the AI before committing to anything.
-
-**I have a big existing codebase.** You don't document all of it. [Using OpenSpec in an Existing Project](existing-projects.md) shows how to start on real, brownfield code without boiling the ocean.
-
-**I just want to get it working.** [Install](installation.md), run `openspec init`, then read [How Commands Work](how-commands-work.md) so your first slash command lands in the right place. 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.
@@ -1,142 +0,0 @@
-# OpenSpec Agent Contract
-
-Machine-readable surfaces of the `openspec` CLI, verified against `src/` (capstone audit, 2026-06-11). Every shape below is documented from the emitting code.
-
-## 1. General conventions
-
- **One JSON document per invocation.** In `--json` mode, stdout carries exactly one JSON document (2-space pretty-printed). Human prose, spinners, and the store banner go to stderr.
- **Store banner.** In human mode, a store-selected root prints `Using OpenSpec root: <id> (<path>)` to stderr. Never printed in JSON mode.
- **Key casing is surface-dependent** (see Known inconsistencies): store/doctor/context payloads use `snake_case`; workflow payloads (`status`, `instructions`, `new change`, `validate`, `list`) use `camelCase`, except the embedded `root` object, which always uses `store_id`.
- **Optional keys are omitted, not null**, in most payloads (e.g. `root.store_id`, `member.path`). Exceptions that use explicit `null` are called out per shape (store doctor `git.*`, failure payloads).
-
-## 2. The diagnostic envelope
-
-One envelope shape is shared by every machine-readable diagnostic (`StoreDiagnostic`):
-
-```json
-{
-  "severity": "error" | "warning" | "info",
-  "code": "snake_case_string",
-  "message": "human sentence",
-  "target": "dotted.surface (optional)",
-  "fix": "one actionable sentence/command (optional)"
-}
-```
-
-Diagnostics appear in two positions: **status arrays** (`status: StoreDiagnostic[]` at top level or per entry) for health findings, and **thrown errors** converted to a single-element `status` array on command failure.
-
-## 3. Root selection and `RootOutput`
-
-All root-resolving commands (`list`, `show`, `validate`, `status`, `instructions`, `instructions apply`, `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`.
@@ -7,14 +7,11 @@ The OpenSpec CLI (`openspec`) provides terminal commands for project setup, vali
 | Category | Commands | Purpose |
 |----------|----------|---------|
 | **Setup** | `init`, `update` | Initialize and update OpenSpec in your project |
-| **Stores (standalone OpenSpec repos)** | `store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor` | Manage stores — standalone OpenSpec repos you've registered |
-| **Health** | `doctor` | Report relationship health for the resolved root |
-| **Working context** | `context` | Assemble the working set (root + referenced stores) |
-| **Personal worksets** | `workset create`, `workset list`, `workset open`, `workset remove` | Keep and open personal, local working views in your tool |
+| **Workspaces (beta)** | `workspace setup`, `workspace list`, `workspace ls`, `workspace link`, `workspace relink`, `workspace doctor` | Set up planning across linked repos or folders |
 | **Browsing** | `list`, `view`, `show` | Explore changes and specs |
 | **Validation** | `validate` | Check changes and specs for issues |
 | **Lifecycle** | `archive` | Finalize completed changes |
-| **Workflow** | `new change`, `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
+| **Workflow** | `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
 | **Schemas** | `schema init`, `schema fork`, `schema validate`, `schema which` | Create and manage custom workflows |
 | **Config** | `config` | View and modify settings |
 | **Utility** | `feedback`, `completion` | Feedback and shell integration |
@@ -33,7 +30,6 @@ These commands are interactive and designed for terminal use:
 |---------|---------|
 | `openspec init` | Initialize project (interactive prompts) |
 | `openspec view` | Interactive dashboard |
-| `openspec workset open <name>` | Open a saved workset (editor window or terminal agent session) |
 | `openspec config edit` | Open config in editor |
 | `openspec feedback` | Submit feedback via GitHub |
 | `openspec completion install` | Install shell completions |
@@ -50,17 +46,12 @@ These commands support `--json` output for programmatic use by AI agents and scr
 | `openspec status` | See artifact progress | `--json` for structured status |
 | `openspec instructions` | Get next steps | `--json` for agent instructions |
 | `openspec templates` | Find template paths | `--json` for path resolution |
-| `openspec schemas` | List available schemas | `--json` for schema discovery; `--store <id>` to select a registered root |
-| `openspec store setup <id>` | Create and register a local store | `--json` with explicit inputs for structured setup output |
-| `openspec store register <path>` | Register an existing store | `--json` for structured registration output |
-| `openspec store unregister <id>` | Forget a local store registration | `--json` for structured cleanup output |
-| `openspec store remove <id>` | Delete a registered local store folder | `--yes --json` for non-interactive deletion |
-| `openspec store list` | Browse registered stores | `--json` for structured registrations |
-| `openspec store doctor` | Check local store setup | `--json` for structured diagnostics |
-| `openspec new change <id>` | Create repo-local change scaffolding | `--json`, plus `--store <id>` to use a registered store as the OpenSpec root |
-| `openspec workset create [name]` | Compose a personal working view | `--member <path> --json` for non-interactive composition |
-| `openspec workset list` | Browse saved worksets | `--json` for structured views |
-| `openspec workset remove <name>` | Delete a saved view | `--yes --json` for non-interactive removal |
+| `openspec schemas` | List available schemas | `--json` for schema discovery |
+| `openspec workspace setup --no-interactive` | Create a workspace with explicit inputs | `--json` for structured setup output |
+| `openspec workspace list` | Browse known workspaces | `--json` for typed workspace objects |
+| `openspec workspace link` | Link a repo or folder | `--json` for structured link output |
+| `openspec workspace relink` | Repair a linked path | `--json` for structured link output |
+| `openspec workspace doctor` | Check one workspace | `--json` for structured status output |

 ---

@@ -82,16 +73,12 @@ These options work with all commands:

 Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations.

-Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, update, sync, archive`.
+Default behavior uses global config defaults: profile `core`, delivery `both`, workflows `propose, explore, apply, sync, archive`.

 ```
 openspec init [path] [options]
 ```

-Use `--language <language>` to add a language instruction to a new project's
-`openspec/config.yaml`. For an existing project, edit the config's `context`
-field so OpenSpec never overwrites project-specific guidance.
-
 **Arguments:**

 | Argument | Required | Description |
@@ -103,20 +90,12 @@ field so OpenSpec never overwrites project-specific guidance.
 | Option | Description |
 |--------|-------------|
 | `--tools <list>` | Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list |
-| `--language <language>` | Write artifacts in this language when creating a new config |
 | `--force` | Auto-cleanup legacy files without prompting |
 | `--profile <profile>` | Override global profile for this init run (`core` or `custom`) |
-| `--no-animation` | Show a static welcome screen instead of the animated one |
-| `--copilot-cloud` | Set up GitHub Copilot [cloud coding-agent files](supported-tools.md#github-copilot-cloud-coding-agent) without prompting |
-| `--no-copilot-cloud` | Skip GitHub Copilot cloud coding-agent files without prompting |

 `--profile custom` uses whatever workflows are currently selected in global config (`openspec config profile`).

-The welcome animation is also skipped when the `OPENSPEC_NO_ANIMATION` environment variable is set (any value, including empty), when `NO_COLOR` is set to a non-empty value, or when the OS reduced-motion preference is enabled (macOS Reduce Motion, GNOME animations disabled).
-
-**Supported 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`, `zed`, `zcode`, `agents`
-
-> This list mirrors `AI_TOOLS` in `src/core/config.ts`. See [Supported Tools](supported-tools.md) for each tool's skill and command paths.
+**Supported tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `opencode`, `pi`, `qoder`, `lingma`, `qwen`, `roocode`, `trae`, `windsurf`

 **Examples:**

@@ -130,9 +109,6 @@ openspec init ./my-project
 # Non-interactive: configure for Claude and Cursor
 openspec init --tools claude,cursor

-# Non-interactive: configure global MiniMax Code skills
-openspec init --tools minimax-code
-
 # Configure for all supported tools
 openspec init --tools all

@@ -154,7 +130,6 @@ openspec/
 .claude/skills/         # Claude Code skills (if claude selected)
 .cursor/skills/         # Cursor skills (if cursor selected)
 .cursor/commands/       # Cursor OPSX commands (if delivery includes commands)
-.agents/skills/         # Shared skills for AGENTS.md-compatible tools (if agents selected)
 ... (other tool configs)
 ```

@@ -184,245 +159,106 @@ openspec update [path] [options]

 ```bash
 # Update instruction files after npm upgrade
-npm install -g @fission-ai/openspec@latest
+npm update @fission-ai/openspec
 openspec update
 ```

-Upgrade the package first. Instruction files are generated by the installed CLI, so running `openspec update` against a stale install reports everything up to date without adding the workflows newer releases ship.
-
-To make that visible, `openspec update` asks the npm registry whether a newer CLI has been published. When yours is behind, it offers to upgrade:
-
-```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)
-```
-
-Answer yes and it runs `npm install -g @fission-ai/openspec@latest`, then re-runs the update with the new CLI so the new workflows land in the same command. It confirms the upgrade by asking the installed binary its version rather than trusting npm's exit code, so if another install earlier on your `PATH` is still answering, it tells you instead of claiming success. Answer no and it prints the command and updates with the CLI you have. Ctrl-C stops the command.
-
-The offer appears only in an interactive terminal, and only when npm owns the install — the one case `npm install -g` actually fixes. Everything else gets the command that matches how it was installed instead:
-
-| How OpenSpec is installed | What you get |
-|---------------------------|--------------|
-| Global npm install | The prompt, and the upgrade run for you — in an interactive terminal; piped output gets the printed command instead |
-| Global pnpm, bun, yarn, or volta install | That manager's own command: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest`, or `volta install …@latest` |
-| A dependency of the project | A note to update the dependency, since its package manager owns the lockfile |
-| An `npx` / `dlx` cache | `npx @fission-ai/openspec@latest update` — that command is the update, so there is no second step |
-| A git clone | Nothing — your version is whatever the branch says |
-
-Whenever anything is printed, it names the directory the running CLI was loaded from — the thing to check when you did upgrade but a stale shim still owns your `PATH`.
-
-It asks the registry in `npm_config_registry` when npm exports it, and `https://registry.npmjs.org` otherwise. No `.npmrc` is read: letting file contents choose where an outbound request goes is a flow worth avoiding, and a project's `.npmrc` travels with the repository. On a private mirror, export `npm_config_registry` — or set `OPENSPEC_NO_UPDATE_CHECK` to skip the check entirely. The check is skipped when `CI` is set to anything but an explicit off-value (`false`, `0`, `no`, `off`, or empty), under `NODE_ENV=test`, and whenever `OPENSPEC_NO_UPDATE_CHECK` (any value), `DO_NOT_TRACK=1`, or `OPENSPEC_TELEMETRY=0` is set. It runs before the update and can delay it by at most 1.5 seconds — it gives up after that even when the network drops packets silently, and stays quiet when the registry is unreachable.
-
-**How "up to date" is decided:** skill files record the version that generated
-them, so OpenSpec compares that against the installed CLI. Command files carry no
-version stamp, so for a tool that has commands but no skills (delivery
-`commands`), OpenSpec compares the file contents against what it would generate
-now — edits to those files count as drift and are overwritten. With delivery
-`skills` or `both`, only the recorded version is checked, so a hand-edited file
-whose version still matches is left alone; use `--force` to rewrite it. Either
-way, generated files are OpenSpec's to own — keep your own instructions
-elsewhere.
-
 ---

-## Stores (standalone OpenSpec repos)
+## Workspace Commands

-> **Beta.** Stores and the features built on them (references, working context, worksets) are new; command names, flags, file formats, and JSON output may change shape between releases. For the problem-first walkthrough, see the [stores guide](stores-beta/user-guide.md).
+Workspace commands are under active development and are not ready for use yet. Do not build external automation, integrations, or long-lived workflows on top of this command surface; command behavior, state files, and JSON output can change at any point.

-A store is a standalone OpenSpec repo you've registered on this machine — for example a planning repo or a contracts repo. Registering a store lets normal commands (`list`, `show`, `status`, `validate`, `new change`, `archive`, ...) act in it from anywhere by passing `--store <id>`.
+Coordination workspaces are planning homes for work that spans multiple repos or folders. Workspace visibility is not change commitment: link the repos or folders OpenSpec should know about, then create changes when you are ready to plan specific work.

-### `openspec store setup`
+### `openspec workspace setup`

-Create and register a local store. With no arguments in a terminal,
-OpenSpec guides the user through setup. Agents and scripts should pass explicit
-inputs and use `--json`.
+Create a workspace in the standard OpenSpec workspace location and link at least one existing repo or folder.

 ```bash
-openspec store setup [id] [options]
+openspec workspace setup [options]
 ```

 **Options:**

 | Option | Description |
 |--------|-------------|
-| `--path <path>` | Folder where the store should live (for example `~/openspec/<id>`) |
-| `--remote <url>` | Record the canonical remote in the new store's `store.yaml` |
-| `--init-git` | Initialize a Git repository with an initial commit (default) |
-| `--no-init-git` | Skip every Git action: no init, no initial commit |
-| `--json` | Output JSON |
+| `--name <name>` | Workspace name. Names must be kebab-case |
+| `--link <path>` | Link an existing repo or folder and infer the link name from the folder name |
+| `--link <name>=<path>` | Link an existing repo or folder with an explicit link name |
+| `--no-interactive` | Disable prompts; requires `--name` and at least one `--link` |
+| `--json` | Output JSON; requires `--no-interactive` |

-Non-interactive runs (`--json`, scripts, agents) must pass both the store id and `--path`. In an interactive terminal, setup prompts for the location with an editable suggestion in a visible, user-owned place (for example `~/openspec/<id>`); it never defaults to OpenSpec's managed data directory.
-
-Examples:
+**Examples:**

 ```bash
-openspec store setup
-openspec store setup team-context
-openspec store setup team-context --path ~/openspec/team-context --no-init-git
-openspec store setup team-context --path ~/openspec/team-context --no-init-git --json
+openspec workspace setup
+openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
+openspec workspace setup --no-interactive --json --name checkout --link /repos/platform/apps/checkout
 ```

-### `openspec store register`
+Setup prints the workspace location, planning path, linked repos or folders, and a workspace check. It does not ask for a preferred agent or open the workspace.

-Register an existing local store folder. During the stores beta, a root may be
-registered before any changes exist, specs have been applied, or changes have
-been archived; in that case `openspec/changes/`, `openspec/specs/`, and
-`openspec/changes/archive/` may be absent until normal commands create them.
-A config-only repo that declares `store: <id>` remains a pointer to another
-store and is not registered as a store root unless that pointer is removed.
+### `openspec workspace list`
+
+List known OpenSpec workspaces from the local registry.

 ```bash
-openspec store register [path] [options]
+openspec workspace list [--json]
+openspec workspace ls [--json]
+```
+
+The list shows each workspace location and linked repos or folders. Stale registry records are reported but not changed.
+
+### `openspec workspace link`
+
+Record an existing repo or folder for one workspace.
+
+```bash
+openspec workspace link [name] <path> [options]
 ```

 **Options:**

 | Option | Description |
 |--------|-------------|
-| `--id <id>` | Store id; defaults to store metadata or folder name |
-| `--yes` | Confirm creating store identity metadata for a healthy OpenSpec root |
+| `--workspace <name>` | Select a known workspace from the local registry |
 | `--json` | Output JSON |
+| `--no-interactive` | Disable workspace picker prompts |

-### `openspec store unregister`
-
-Forget a local store registration without deleting files.
+**Examples:**

 ```bash
-openspec store unregister <id> [--json]
+openspec workspace link /repos/api
+openspec workspace link api-service /repos/api
+openspec workspace link --workspace platform /repos/platform/apps/checkout
 ```

-Use this when a store was moved, cloned somewhere else, or should no longer be
-shown by OpenSpec on this machine.
+The path must already exist. Relative paths are resolved against the command's current directory before OpenSpec stores the verified absolute path in machine-local workspace state. Linked paths can be full repos, packages, services, apps, or folders without repo-local `openspec/` state.

-### `openspec store remove`
+### `openspec workspace relink`

-Forget a local store registration and delete its local folder.
+Repair or change the local path for an existing link.

 ```bash
-openspec store remove <id> [--yes] [--json]
+openspec workspace relink <name> <path> [options]
 ```

-`remove` shows the exact folder before deleting in an interactive terminal.
-Agents, scripts, and JSON callers must pass `--yes` to confirm deletion.
-OpenSpec refuses to delete a folder that does not contain matching
-store metadata.
+The path must already exist. Relink updates only the machine-local path for the stable link name.

-### `openspec store list`
+### `openspec workspace doctor`

-List locally registered stores.
+Check what one workspace can resolve on the current machine.

 ```bash
-openspec store list [--json]
-openspec store ls [--json]
+openspec workspace doctor [options]
 ```

-### `openspec store doctor`
+Doctor shows the workspace location, planning path, linked repos or folders, missing paths, repo-local specs paths when present, and suggested fixes. It reports issues only; it does not repair them automatically.

-Check local store registration, metadata, and Git presence.
+Commands that need one workspace use the current workspace when run from inside a workspace folder or subdirectory. From elsewhere, pass `--workspace <name>`, select from the picker in an interactive terminal, or rely on the only known workspace when exactly one exists. In `--json` or `--no-interactive` mode, ambiguous selection fails with a structured status error and suggests `--workspace <name>`.

-```bash
-openspec store doctor [id] [--json]
-```
-
-Doctor is diagnostic-only; it reports missing roots, metadata mismatches, and invalid local registry state without modifying the store.
-
-### Referencing stores from a project
-
-A project repo can declare which stores its work draws on in `openspec/config.yaml`:
-
-```yaml
-schema: spec-driven
-references:
-  - team-context
-```
-
-From then on, `openspec instructions` output in that repo (both the per-artifact and `apply` surfaces, JSON and human modes) carries an index of each referenced store's specs — spec ids, a one-line summary from each spec's Purpose section, and the fetch command (`openspec show <spec-id> --type spec --store <id>`). The index is built live from the registered checkout on every run; spec content is never copied into the output.
-
-References are read-only context. They never change where commands act: work stays in the repo's own root, and writing to a referenced store remains an explicit `--store` action. A reference that cannot be resolved (for example, a store not registered on this machine) degrades to a warning in the index with the exact fix, and instructions still generate. `openspec doctor` reports reference health in one place.
-
-### Recording where a store is cloned from
-
-A store can record its canonical clone source in its committed identity file, so onboarding never dead-ends at "register the store":
-
-```bash
-openspec store setup team-context --path ~/openspec/team-context \
-  --remote git@github.com:acme/team-context.git
-```
-
-The remote lands in `.openspec-store/store.yaml` inside the initial commit, so every clone is born knowing it. For an existing store, edit `store.yaml` by hand and commit. `store doctor` shows the recorded remote (and the checkout's observed Git origin); setup/register sharing guidance names it; and register records the checkout's origin in the machine-local registry.
-
-A reference declaration can carry the clone source too, so a teammate who doesn't have the store yet gets a complete, pasteable fix (`git clone <remote> <path> && openspec store register <path> --id <id>`):
-
-```yaml
-references:
-  - { id: team-context, remote: "git@github.com:acme/team-context.git" }
-```
-
-Recording a remote is not sync: OpenSpec never clones, pulls, or pushes on its own.
-
-### Declaring a default store
-
-A repo whose planning is fully externalized — no local `openspec/specs/` or `openspec/changes/` — can declare its store once instead of passing `--store` on every command:
-
-```yaml
-# openspec/config.yaml (the only file under openspec/)
-store: team-context
-```
-
-Normal commands then resolve to the declared store automatically; the root banner and JSON `root` block report `source: "declared"` with the store id, and printed hints still carry `--store <id>`. The declaration is a fallback, never an override: explicit `--store` always wins, and a directory with real planning folders ignores the pointer (with a warning). To convert a pointer repo into a local OpenSpec root, remove the `store:` line and run `openspec init` — init refuses to scaffold while the declaration is present.
-
-A machine-level variant covers every repo at once: `openspec config set defaultStore <id>` (see Configuration). It is consulted only after `--store`, a local root, and a project pointer have all failed to resolve; the root banner and JSON `root` block then report `source: "global_default"`.
-
-## Doctor (relationship health)
-
-One read-only question, one place: is the OpenSpec root healthy, and are the stores it references available on this machine?
-
-```bash
-openspec doctor [--store <id>] [--json]
-```
-
-The report separates root health, store metadata health (including a note when the recorded remote and the checkout's origin diverge, and a note when the store checkout has drifted behind its last-fetched upstream tracking ref), and reference health (the same diagnostics instructions show, with clone fixes for unresolved references). Health findings of any severity exit 0 — agents read the `status` arrays; only command failures (no root, unknown store) exit 1. Doctor never clones, syncs, or repairs. To get the assembled set itself rather than its health, use `openspec context`.
-
-## Working context (the assembled set)
-
-Everything this work relates to through OpenSpec declarations, in one working set: the OpenSpec root and the stores it references.
-
-```bash
-openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]
-```
-
-The JSON brief is agent-consumable (each available referenced store carries its fetch recipe; unresolved members carry the same fixes instructions and doctor show). `--code-workspace` additionally writes a VS Code workspace file containing the root plus the available referenced stores (`ref:<id>` folders) — the one write this command performs, refused without `--force` if the file exists. Unavailable members are reported, never guessed at.
-
-"Working context" is the assembled set; the `context:` field in `openspec/config.yaml` is project background injected into instructions — two different things. `openspec doctor` answers whether the set is healthy; `openspec context` answers what the set is.
-
-## Personal worksets
-
-> **Beta.** Worksets are part of the new beta surface; commands, flags, and file formats may change shape between releases. For the walkthrough, see the [stores guide](stores-beta/user-guide.md#worksets-reopen-the-folders-you-work-on-together).
-
-A workset is a personal, named view of the folders you work on together — a planning root plus whatever else you choose — kept on your machine and reopened by name in your tool. It is purely local: never committed, never shared, never derived from declarations, and removing one never touches a member folder.
-
-```bash
-openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
-openspec workset list [--json]
-openspec workset open <name> [--tool <id>]
-openspec workset remove <name> [--yes] [--json]
-```
-
-`create` runs a short guided flow (or takes `--member` flags non-interactively; the first member is the primary — sessions start there). `open` launches the chosen tool: editors (VS Code, Cursor) open a window with every member and return; CLI agents (Claude Code, codex) take over this terminal as a session with every member attached and no prompt pre-filled, ending when you exit. A member folder missing at open time is skipped with a note; the rest opens. The saved tool preference is overridable per open with `--tool`.
-
-Supporting a new tool is configuration, not code. Every tool is one of two launch styles — `workspace-file` (launched with the generated `.code-workspace`) or `attach-dirs` (one attach flag per member) — and the `openers` key in the global `config.json` (open it with `openspec config edit`) adds tools or adjusts built-ins per field:
-
-```json
-{
-  "openers": {
-    "zed": { "style": "workspace-file" },
-    "claude": { "attach_flag": "--dir" }
-  }
-}
-```
-
-All workset state lives under the global data dir's `worksets/` folder (the saved views plus the generated `<name>.code-workspace` files, regenerated on every open); deleting that folder removes every trace.
+JSON responses use typed objects plus `status` arrays. Primary data lives in `workspace`, `workspaces`, or `link`; warnings and errors live in `status`.

 ---

@@ -461,8 +297,9 @@ openspec list --json
 **Output (text):**

 ```
-Changes:
-  add-dark-mode     No tasks      just now
+Active changes:
+  add-dark-mode     UI theme switching support
+  fix-login-bug     Session timeout handling
 ```

 ---
@@ -537,14 +374,12 @@ openspec show add-dark-mode --json

 ### `openspec validate`

-Validate changes and specs for structural issues, and check a change's MODIFIED requirements against the main specs they would replace.
+Validate changes and specs for structural issues.

 ```
 openspec validate [item-name] [options]
 ```

-A change with zero spec deltas fails validation unless its `.openspec.yaml` declares `skip_specs: true` (for pure refactors, tooling, or docs work — see [Recipe 5](examples.md#recipe-5-a-refactor-with-no-behavior-change)).
-
 **Arguments:**

 | Argument | Required | Description |
@@ -558,15 +393,12 @@ A change with zero spec deltas fails validation unless its `.openspec.yaml` decl
 | `--all` | Validate all changes and specs |
 | `--changes` | Validate all changes |
 | `--specs` | Validate all specs |
-| `--archived` | Validate that archived changes have all tasks completed (for pre-commit linting) |
 | `--type <type>` | Specify type when name is ambiguous: `change` or `spec` |
 | `--strict` | Enable strict validation mode |
 | `--json` | Output as JSON |
 | `--concurrency <n>` | Max parallel validations (default: 6, or `OPENSPEC_CONCURRENCY` env) |
 | `--no-interactive` | Disable prompts |

-`--archived` is its own scope: it does not validate spec deltas (already applied at archive time), it verifies that every change under `changes/archive/` has all of its `tasks.md` checkboxes ticked, exiting non-zero if any are unchecked. This catches changes that were archived with unfinished work — handy in a pre-commit hook.
-
 **Examples:**

 ```bash
@@ -584,9 +416,6 @@ openspec validate --all --json

 # Strict validation with increased parallelism
 openspec validate --all --strict --concurrency 12
-
-# Fail if any archived change still has unchecked tasks
-openspec validate --archived
 ```

 **Output (text):**
@@ -638,26 +467,26 @@ openspec archive [change-name] [options]

 | Argument | Required | Description |
 |----------|----------|-------------|
-| `change-name` | No | Change to archive (prompts if omitted; required when nothing can answer the prompt) |
+| `change-name` | No | Change to archive (prompts if omitted) |

 **Options:**

 | Option | Description |
 |--------|-------------|
-| `-y, --yes` | Skip confirmation prompts. Required when nothing can answer them — an AI agent, a CI job, or any run with stdin closed |
-| `--skip-specs` | Skip spec updates for one archive run. A change that permanently has no spec deltas should declare `skip_specs: true` in its `.openspec.yaml` instead — it archives with no flag |
-| `--no-validate` | Skip validation (requires confirmation). Also disables capability retirement — with no validator verdict, nothing is retired |
+| `-y, --yes` | Skip confirmation prompts |
+| `--skip-specs` | Skip spec updates (for infrastructure/tooling/doc-only changes) |
+| `--no-validate` | Skip validation (requires confirmation) |

 **Examples:**

 ```bash
-# Interactive archive (asks which change, then confirms)
+# Interactive archive
 openspec archive

 # Archive specific change
 openspec archive add-dark-mode

-# Archive without prompts (agents, CI, scripts)
+# Archive without prompts (CI/scripts)
 openspec archive add-dark-mode --yes

 # Archive a tooling change that doesn't affect specs
@@ -668,16 +497,8 @@ openspec archive update-ci-config --skip-specs

 1. Validates the change (unless `--no-validate`)
 2. Prompts for confirmation (unless `--yes`)
-3. Claims the archive destination before changing any main spec
-4. Validates and merges the active delta specs into `openspec/specs/` — a capability whose last requirement the change removes is retired, and its spec file deleted, but only when the change's `.openspec.yaml` declares `retire_capabilities: true` next to its `schema:`
-5. Moves the change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
-6. If a spec mutation or final move fails before a complete archive is secured, restores the specs and leaves or returns the change at its active path
-7. If a verified fallback copy completes but staged-source cleanup fails, retains the complete archive and committed spec state for recovery
-
-**Without a terminal:** an AI agent, a CI job, or any run with stdin closed cannot
-answer step 2, so archive stops before touching anything, exits 1, and names the
-command to rerun — `openspec archive <name> --yes`, carrying whatever other flags
-you passed. Pass `--yes` (and the change name) up front to skip the round trip.
+3. Merges delta specs into `openspec/specs/`
+4. Moves change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`

 ---

@@ -685,37 +506,6 @@ you passed. Pass `--yes` (and the change name) up front to skip the round trip.

 These commands support the artifact-driven OPSX workflow. They're useful for both humans checking progress and agents determining next steps.

-### `openspec new change`
-
-Create a change directory and optional checked-in metadata in the resolved OpenSpec root.
-
-```bash
-openspec new change <name> [options]
-```
-
-Change names must use lowercase kebab-case: lowercase letters, numbers, and
-single hyphens. They cannot contain spaces, underscores, uppercase letters,
-consecutive hyphens, or leading/trailing hyphens. A leading number is allowed,
-so you can prefix names to order or tier changes, for example `100-add-feature`
-or `00001-add-auth`.
-
-**Options:**
-
-| Option | Description |
-|--------|-------------|
-| `--description <text>` | Description to add to `README.md` |
-| `--goal <text>` | Optional goal metadata to store with the change |
-| `--schema <name>` | Workflow schema to use |
-| `--store <id>` | Store id to use as the OpenSpec root (a store is a standalone OpenSpec repo you've registered) |
-| `--json` | Output JSON |
-
-Examples:
-
-```bash
-openspec new change add-billing-api
-openspec new change add-billing-api --store team-context --json
-```
-
 ### `openspec status`

 Display artifact completion status for a change.
@@ -753,42 +543,28 @@ Schema: spec-driven
 Progress: 2/4 artifacts complete

 [x] proposal
-[x] specs
 [ ] design
+[x] specs
 [-] tasks (blocked by: design)
 ```

-A change that declares `skip_specs: true` shows its specs stage as `[~] specs (skipped: change declares skip_specs)` and excludes it from the progress count.
-
 **Output (JSON):**

 ```json
 {
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
-  "isPlanningComplete": false,
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
-    {"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
-    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
-    {"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
-    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
+    {"id": "proposal", "outputPath": "proposal.md", "status": "done"},
+    {"id": "design", "outputPath": "design.md", "status": "ready"},
+    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done"},
+    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "missingDeps": ["design"]}
  ]
 }
 ```

-`isPlanningComplete` reports whether every non-skipped planning artifact exists;
-skipped artifacts count as satisfied without being created. It does not report
-whether implementation tasks are complete. `isComplete` is retained as a
-compatibility alias with the same value.
-
-Artifacts are listed in dependency order - a dependency never appears after
-something that requires it - and artifacts that become ready at the same time
-(spec-driven's `specs` and `design` both need only `proposal`) keep the order the
-schema declares them rather than an alphabetical one. So the first `ready` entry
-is the artifact to write next.
-
 ---

 ### `openspec instructions`
@@ -803,7 +579,7 @@ openspec instructions [artifact] [options]

 | Argument | Required | Description |
 |----------|----------|-------------|
-| `artifact` | No | Artifact ID, or workflow input surface: `apply` or `archive` |
+| `artifact` | No | Artifact ID: `proposal`, `specs`, `design`, `tasks`, or `apply` |

 **Options:**

@@ -813,9 +589,7 @@ openspec instructions [artifact] [options]
 | `--schema <name>` | Schema override |
 | `--json` | Output as JSON |

-**Special cases:** Use `apply` to get task implementation instructions. Use
-`archive` to fetch current, read-only archive inputs (`context` and
-`operationGuidance`) for a valid change; it does not archive or mutate anything.
+**Special case:** Use `apply` as the artifact to get task implementation instructions.

 **Examples:**

@@ -829,9 +603,6 @@ openspec instructions design --change add-dark-mode
 # Get apply/implementation instructions
 openspec instructions apply --change add-dark-mode

-# Get current archive operation inputs without archiving
-openspec instructions archive --change add-dark-mode --json
-
 # JSON for agent consumption
 openspec instructions design --change add-dark-mode --json
 ```
@@ -842,21 +613,6 @@ openspec instructions design --change add-dark-mode --json
 - Project context from config
 - Content from dependency artifacts
 - Per-artifact rules from config
- Current project context and matching operation guidance for `apply`/`archive`
-
-Operation inputs are read from the resolved repo or selected store on every
-invocation. Project context is a required prompt-level input: agents read it and
-apply relevant project facts, conventions, and constraints. Operation guidance is
-optional additive advice: agents consider every entry and follow only entries that
-are applicable and compatible with the built-in workflow. Both fields remain
-separate from explicit user choices, CLI-controlled state, built-in instructions,
-and artifact rules. Conflicting context is reported; conflicting or inapplicable
-guidance is not followed and the reason is explained. These are behavioral
-contracts for generated agents, not enforceable CLI checks. `instructions archive`
-returns only the selected change, optional inputs, and root metadata; it does not
-include the static archive workflow.
-
-For an artifact skipped via `skip_specs: true`, the output is a warning only (JSON adds `skipped`/`warning` fields) — the artifact must not be created.

 ---

@@ -915,7 +671,6 @@ openspec schemas [options]
 | Option | Description |
 |--------|-------------|
 | `--json` | Output as JSON |
-| `--store <id>` | Use a registered store as the OpenSpec root |

 **Example:**

@@ -1137,7 +892,7 @@ openspec config list
 # Get a specific value
 openspec config get telemetry.enabled

-# Set a value (disable anonymous usage telemetry)
+# Set a value
 openspec config set telemetry.enabled false

 # Set a string value explicitly
@@ -1146,10 +901,6 @@ openspec config set user.name "My Name" --string
 # Remove a custom setting
 openspec config unset user.name

-# Set a machine-level default store (fallback root when no --store,
-# local root, or project store: pointer resolves)
-openspec config set defaultStore team-plans
-
 # Reset all configuration
 openspec config reset --all --yes

@@ -1163,11 +914,6 @@ openspec config profile
 openspec config profile core
 ```

-**Telemetry opt-out:** `telemetry.enabled` defaults to on when unset (opt-out model).
-Set it to `false` to disable anonymous usage stats and the `openspec update` version check.
-Environment variables take precedence over config: `OPENSPEC_TELEMETRY=0`, `DO_NOT_TRACK=1`,
-and a truthy `CI` value (e.g. `true`/`1`/`yes`) always disable telemetry regardless of the config value.
-
 `openspec config profile` starts with a current-state summary, then lets you choose:
 - Change delivery + workflows
 - Change delivery only
@@ -1175,7 +921,7 @@ and a truthy `CI` value (e.g. `true`/`1`/`yes`) always disable telemetry regardl
 - Keep current settings (exit)

 If you keep current settings, no changes are written and no update prompt is shown.
-If there are no config changes but the current project files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest `openspec update`.
+If there are no config changes but the current project files are out of sync with your global profile/delivery, OpenSpec will show a warning and suggest running `openspec update`.
 Pressing `Ctrl+C` also cancels the flow cleanly (no stack trace) and exits with code `130`.
 In the workflow checklist, `[x]` means the workflow is selected in global config. To apply those selections to project files, run `openspec update` (or choose `Apply changes to this project now?` when prompted inside a project).

@@ -1209,13 +955,13 @@ openspec feedback <message> [options]

 | Argument | Required | Description |
 |----------|----------|-------------|
-| `message` | Yes | Feedback summary; long text is shortened in the issue title and preserved in the body |
+| `message` | Yes | Feedback message |

 **Options:**

 | Option | Description |
 |--------|-------------|
-| `--body <text>` | Additional details included after the summary |
+| `--body <text>` | Detailed description |

 **Requirements:** GitHub CLI (`gh`) must be installed and authenticated.

@@ -1262,11 +1008,6 @@ openspec completion generate bash > ~/.bash_completion.d/openspec
 openspec completion uninstall
 ```

-Completions are opt-in. The CLI mentions them once, on stderr, the first time you
-run a command in an interactive terminal, and never again — it also stays quiet
-if you already have completions installed. Set `OPENSPEC_NO_COMPLETIONS=1` to
-suppress that tip entirely.
-
 ---

 ## Exit Codes
@@ -1282,15 +1023,11 @@ suppress that tip entirely.

 | Variable | Description |
 |----------|-------------|
-| `OPENSPEC_TELEMETRY` | Set to `0` to disable telemetry and the `openspec update` version check (overrides `telemetry.enabled` in global config) |
-| `DO_NOT_TRACK` | Set to `1` to disable telemetry and the `openspec update` version check (standard DNT signal; overrides config) |
+| `OPENSPEC_TELEMETRY` | Set to `0` to disable telemetry |
+| `DO_NOT_TRACK` | Set to `1` to disable telemetry (standard DNT signal) |
 | `OPENSPEC_CONCURRENCY` | Default concurrency for bulk validation (default: 6) |
 | `EDITOR` or `VISUAL` | Editor for `openspec config edit` |
 | `NO_COLOR` | Disable color output when set |
-| `OPENSPEC_NO_ANIMATION` | Disable the `openspec init` welcome animation when set |
-| `OPENSPEC_NO_COMPLETIONS` | Set to `1` to suppress the one-time tip about shell completions |
-| `OPENSPEC_NO_UPDATE_CHECK` | Disable the `openspec update` check for a newer published CLI when set (any value, including empty). Also skipped when `CI` is set (unless `false`/`0`/`no`/`off`) or `NODE_ENV=test` |
-| `npm_config_registry` | Registry the `openspec update` version check asks. Must be an `http(s)` URL or it falls back to `https://registry.npmjs.org`. No `.npmrc` file is read |

 ---

@@ -1,14 +1,9 @@
 # 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).
+This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Windsurf).

 For workflow patterns and when to use each command, see [Workflows](workflows.md). For CLI commands, see [CLI](cli.md).

-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)
@@ -18,7 +13,6 @@ for your tool. The files OpenSpec generates already use the right form.
 | `/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 |

@@ -78,8 +72,6 @@ AI:  Created openspec/changes/add-dark-mode/

 ### `/opsx:explore`

-> **Start here when you're unsure.** Explore is a no-stakes thinking partner: it reads your codebase, compares options, and sharpens a fuzzy idea into a concrete plan before any change exists. It ships in the default profile. For the full case and more examples, see the [Explore First](explore.md) guide.
-
 Think through ideas, investigate problems, and clarify requirements before committing to a change.

 **Syntax:**
@@ -210,7 +202,7 @@ AI:  Change: add-dark-mode
     ✓ proposal    (done)
     ◆ specs       (ready)
     ◆ design      (ready)
-     ○ tasks       (blocked - needs: specs, design)
+     ○ tasks       (blocked - needs: specs)

     Creating specs...

@@ -218,7 +210,7 @@ AI:  Change: add-dark-mode

     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md

-     Now available: design
+     Now available: tasks
     Run /opsx:continue to create the next artifact.
 ```

@@ -323,55 +315,6 @@ AI:  Implementing add-dark-mode...

 ---

-### `/opsx:update`
-
-Revise a change's existing planning artifacts and keep them coherent with one another. Planning artifacts only - it never edits code.
-
-**Syntax:**
-
-```text
-/opsx:update [change-name]
-```
-
-**Arguments:**
-
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to update (inferred from context if not provided) |
-
-**What it does:**
-
- Reads the change's artifacts via `openspec status --change <name> --json`
- Applies your requested revision, or reviews the artifacts for contradictions if you didn't name one
- Reconciles the other existing artifacts in any direction (a design edit may ripple back to the proposal)
- Confirms every edit with you before writing, one artifact at a time
- Ends by recommending the next step: `/opsx:continue` (artifacts missing), `/opsx:apply` (carry a revised plan into code), or `/opsx:archive` (all done)
-
-**Example:**
-
-```text
-You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage
-
-AI:  Reading add-dark-mode artifacts...
-
-     The design references localStorage in two places; tasks 1.3 covers
-     localStorage persistence; the proposal doesn't mention storage.
-
-     Proposed revisions:
-     1. design.md - swap localStorage decision for cookie storage
-     2. tasks.md - reword task 1.3 to cookie persistence
-
-     Apply revision 1? (design.md)
-```
-
-**Tips:**
-
- It won't create missing artifacts - that's `/opsx:continue`
- If the change was already implemented, follow up with `/opsx:apply` so the code matches the revised plan
- If your revision changes the *intent* of the change, start fresh with a new change instead (see [When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh))
-
---
-
 ### `/opsx:verify`

 Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.
@@ -669,20 +612,16 @@ AI:  Welcome to OpenSpec!

 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, Zed Agent, shared `.agents` |
-| none — Kimi Code | `/skill:openspec-propose` | Kimi Code |
-| none — Codex CLI | `$openspec-propose` | Codex |
+| Tool | Syntax Example |
+|------|----------------|
+| Claude Code | `/opsx:propose`, `/opsx:apply` |
+| Cursor | `/opsx-propose`, `/opsx-apply` |
+| Windsurf | `/opsx-propose`, `/opsx-apply` |
+| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
+| Kimi CLI | Skill-based invocations such as `/skill:openspec-propose`, `/skill:openspec-apply-change` (no generated `opsx-*` command files) |
+| Trae | Skill-based invocations such as `/openspec-propose`, `/openspec-apply-change` (no generated `opsx-*` command files) |

-> **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.
+The intent is the same across tools, but how commands are surfaced can differ by integration.

 > **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds.

@@ -49,6 +49,123 @@ OpenSpec organizes your work into two main areas:

 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.

+## Coordination Workspaces
+
+Workspace support is under active development and is not ready for use yet. Do not build external automation, integrations, or long-lived workflows on top of workspace behavior; the commands, state files, and JSON output can change at any point.
+
+The commands below provide the first setup flow for planning across linked repos or folders.
+
+Repo-local OpenSpec projects are the right default when one repo owns the planning, implementation, and archive flow. Some work spans several repos or folders. For that case, an OpenSpec coordination workspace is the durable planning home.
+
+The workspace mental model is:
+
+```text
+workspace = where related cross-repo changes live
+link      = a stable name for a repo or folder the workspace can plan against
+change    = one feature, fix, project, or other planned piece of work
+```
+
+A workspace has a different shape from a repo-local project:
+
+```text
+workspace-folder/
+├── changes/                       # Workspace-level planning
+└── .openspec-workspace/
+    ├── workspace.yaml             # Shared workspace identity and link names
+    └── local.yaml                 # This machine's local paths
+```
+
+Repo-local OpenSpec state keeps the existing shape:
+
+```text
+repo-root/
+└── openspec/
+    ├── specs/
+    └── changes/
+```
+
+That distinction matters. The workspace folder is a coordination surface for planning across linked repos or folders. Each repo's `openspec/` directory remains the home for repo-owned specs, repo-local changes, and implementation planning. Users do not need to run repo-local `openspec init` inside a workspace folder.
+
+Stable link names are how workspace planning refers to repos and folders. The shared workspace state keeps names such as `api`, `web`, or `checkout`; each machine maps those names to its own local paths in `.openspec-workspace/local.yaml`.
+
+```yaml
+# .openspec-workspace/workspace.yaml
+version: 1
+name: platform
+links:
+  api: {}
+  web: {}
+```
+
+```yaml
+# .openspec-workspace/local.yaml
+version: 1
+paths:
+  api: /repos/api
+  web: /repos/web
+```
+
+OpenSpec-created workspaces exclude `.openspec-workspace/local.yaml` from portable collaboration state by default. `.openspec-workspace/workspace.yaml` remains portable because it stores the workspace name and stable link names, not one user's absolute checkout paths.
+
+Linked paths can be full repos, folders inside a large monorepo, or other existing folders. They do not need repo-local `openspec/` state before they can participate in workspace planning. Later implementation, verify, or archive workflows may require more repo readiness, but planning visibility starts with the link.
+
+```text
+multi-repo:
+  api      -> /repos/api
+  web      -> /repos/web
+
+large monorepo:
+  billing  -> /repos/platform/services/billing
+  checkout -> /repos/platform/apps/checkout
+```
+
+Managed workspaces live under the standard OpenSpec data directory:
+
+```text
+getGlobalDataDir()/workspaces
+```
+
+That means `$XDG_DATA_HOME/openspec/workspaces` when `XDG_DATA_HOME` is set, `~/.local/share/openspec/workspaces` on Unix-style fallback, and `%LOCALAPPDATA%\openspec\workspaces` on native Windows fallback. Native Windows shells, PowerShell, and WSL2 each keep the path strings for the runtime running OpenSpec. This foundation does not translate between `D:\repo`, `/mnt/d/repo`, and UNC WSL paths.
+
+OpenSpec also keeps a machine-local registry at:
+
+```text
+getGlobalDataDir()/workspaces/registry.yaml
+```
+
+The registry maps workspace names to workspace locations so later global commands can list or select known workspaces from anywhere. It is only an index. Each workspace folder remains authoritative for its own `.openspec-workspace/workspace.yaml` and `.openspec-workspace/local.yaml`, so stale registry records can be reported and repaired without redefining the workspace itself.
+
+Workspace visibility is not change commitment. Set up a workspace when OpenSpec should know which repos or folders are relevant; create a change later when you are ready to plan a feature, fix, project, or other piece of work.
+
+Useful commands:
+
+```bash
+# Guided setup
+openspec workspace setup
+
+# Automation-friendly setup
+openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
+
+# See known workspaces from the local registry
+openspec workspace list
+openspec workspace ls
+
+# Add or repair links for the selected workspace
+openspec workspace link /repos/api
+openspec workspace link api-service /repos/api
+openspec workspace relink api-service /new/path/to/api
+
+# Check what this machine can resolve
+openspec workspace doctor
+openspec workspace doctor --workspace platform
+```
+
+`workspace setup` always creates the workspace in the standard workspace location, records it in the local registry, shows the workspace location, and requires at least one linked repo or folder. `workspace link` and `workspace relink` record existing folders only; they do not create, copy, move, initialize, or edit the linked repo or folder.
+
+Workspace commands that need one workspace can run from anywhere with `--workspace <name>`. If you run them inside a workspace folder or subdirectory, OpenSpec uses that current workspace. If several known workspaces are available and you do not pass `--workspace <name>`, human commands show a picker; `--json` and `--no-interactive` fail with a structured status error instead of prompting.
+
+Direct workspace commands support JSON output for scripts. JSON responses keep primary data in `workspace`, `workspaces`, or `link` objects and report warnings or errors in `status` arrays. Healthy objects use `status: []`.
+
 ## Specs

 Specs describe your system's behavior using structured requirements and scenarios.
@@ -190,7 +307,7 @@ 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
+├── .openspec.yaml        # Change metadata (optional)
 └── specs/                # Delta specs
    └── ui/
        └── spec.md       # What's changing in ui/spec.md
@@ -392,8 +509,7 @@ The system MUST expire sessions after 15 minutes of inactivity.
 |---------|---------|------------------------|
 | `## 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 |
+| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec |

 ### Why Deltas Instead of Full Specs

@@ -17,8 +17,6 @@ The `openspec/config.yaml` file is the easiest way to customize OpenSpec for 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

@@ -45,19 +43,6 @@ rules:
  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
@@ -95,60 +80,6 @@ Tech stack: TypeScript, React, Node.js, PostgreSQL
 - **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:
@@ -266,10 +197,6 @@ apply:
 | `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.
@@ -418,11 +345,7 @@ Community schemas are not vendored into OpenSpec core — they live in their own

 | 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.

@@ -1,91 +0,0 @@
-# Editing & Iterating on a Change
-
-**Every artifact in a change is just a Markdown file you can edit at any time.** There is no locked "planning phase," no approval gate, no special edit mode to enter. Want to change the proposal after you've started building? Open `proposal.md` and change it. Realized the design is wrong mid-implementation? Fix `design.md` and keep going. That's the whole answer, and it's by design.
-
-This page is for the moment you think "wait, can I go back and change that?" Yes. Here's how, for each common case.
-
-## Two ways to edit anything
-
-You always have both:
-
-1. **Edit the file directly.** Artifacts are plain Markdown in `openspec/changes/<name>/`. Open `proposal.md`, `design.md`, `tasks.md`, or a delta spec under `specs/` in your editor and change it. Nothing else is required.
-
-2. **Ask your AI to revise it.** In chat, just say what you want: "Update the proposal to drop the caching idea and add a rate-limit section," or "the design should use a queue, not polling." The AI edits the artifact for you, using the rest of the change as context.
-
-Use whichever fits the moment. Small wording tweak? Edit the file. Substantive rethink? Let the AI revise with full context.
-
-## "How do I update the proposal (or specs) after I've started?"
-
-Just update it. Same change, refined.
-
-If you're using the expanded commands, the natural flow is: edit the artifact, then run `/opsx:continue` to pick up from the new state, or `/opsx:apply` to keep implementing against the updated plan. If you're on the default `core` commands, edit the artifact and run `/opsx:apply`; it reads the current files, so it builds against whatever the artifacts now say.
-
-The mental model: artifacts are the live plan, not a signed contract. The AI always works from their current contents, so editing them steers the work.
-
-```text
-You: I want to change the approach in this change.
-
-You: [edit design.md, or tell the AI:]
-     Update design.md to use a background job instead of a synchronous call.
-
-AI:  Updated design.md. The task list still fits; want me to continue applying?
-
-You: /opsx:apply
-```
-
-This answers a very common question: there's no separate "update proposal" command because you don't need one. The file is the source of truth, and editing it (by hand or via the AI) is the update.
-
-## "How do I go back to review after implementing?"
-
-You don't have to "go back," because you never left. The workflow is fluid: review, edit, and implementation aren't sequential phases you're trapped in.
-
-Concretely, after some `/opsx:apply` work:
-
- Want to re-examine the plan? Open the artifacts and read them, or run `openspec show <change>` in your terminal for a consolidated view.
- Found something to change? Edit the artifact (or ask the AI to), then continue.
- Want a structured check that the code matches the plan? Run `/opsx:verify` (expanded command). It reports completeness, correctness, and coherence without blocking anything. See [Workflows: Verify](workflows.md#verify-check-your-work).
-
-There's no "review phase" to return to, because review is something you can do at any point, including after implementation.
-
-## "I edited the code by hand. How do I reconcile that with OpenSpec?"
-
-This happens constantly and it's fine. You tweaked something in your editor, and now the code and the artifacts disagree. Bring them back in sync in whichever direction is true:
-
- **The code is now correct, the spec is stale.** Update the delta spec (and tasks, if relevant) to describe the behavior you actually shipped. The spec should match reality before you archive, because archiving merges the spec into your source of truth.
- **The spec is correct, the code drifted.** Keep building or fixing until the code matches the spec.
-
-A fast way to surface mismatches is `/opsx:verify`: it reads your artifacts and your code and tells you where they diverge. Treat its output as a to-do list for reconciliation, then archive once they agree.
-
-The principle: at archive time, your specs become the truth of record. So before you archive, make the specs honest about what the code does. Manual edits are welcome; just don't let them quietly desync the spec.
-
-## Refining a proposal you're not happy with
-
-If a generated proposal misses the mark, you have three good moves:
-
- **Iterate in place.** Tell the AI what's off ("the scope is too broad, drop the admin features") and let it revise. Cheapest and usually right.
- **Explore first, then re-propose.** If the problem is that the idea itself is unclear, step back to `/opsx:explore`, think it through, and let a sharper proposal come out of that. See [Explore First](explore.md).
- **Start fresh.** If the intent has fundamentally changed, a new change can be clearer than patching the old one.
-
-That last move has its own decision guide, next.
-
-## When to update vs. start a new change
-
-Short version: **update when it's the same work refined; start new when the intent fundamentally changed or the scope exploded into different work.**
-
- Same goal, better approach? Update.
- Scope narrowing (ship the MVP now, more later)? Update, then archive, then a new change for phase two.
- The problem itself changed ("add dark mode" became "build a full theming system")? New change.
-
-There's a full flowchart and worked examples in [Workflows: When to Update vs Start Fresh](workflows.md#when-to-update-vs-start-fresh) and a deeper treatment in [OPSX: When to Update vs. Start Fresh](opsx.md#when-to-update-vs-start-fresh).
-
-## A note on tasks
-
-`tasks.md` is a living checklist, not a frozen plan. As you implement, you can add tasks you discover, remove ones that turned out unnecessary, or reorder them. The AI checks items off as it completes them during `/opsx:apply`, and it resumes from the first unchecked task if you come back later. Editing the list mid-flight is expected.
-
-## Where to go next
-
- [Workflows](workflows.md) - patterns, plus the update-vs-new decision guide
- [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
@@ -1,224 +0,0 @@
-# Examples & Recipes
-
-Real changes, start to finish. Each recipe shows the commands you'd type and what you'd see back, so you can match your situation to a pattern and copy it. These use the default **core** commands (`propose`, `explore`, `apply`, `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
@@ -1,134 +0,0 @@
-# Using OpenSpec in an Existing Project
-
-**You do not document your whole codebase to start. You write specs only for what you're about to change.** That's the single most important thing to know about adopting OpenSpec on an existing project, and it's why OpenSpec is built brownfield-first.
-
-A common worry sounds like this: "My app is 80,000 lines old. Do I have to write specs for all of it before OpenSpec is useful?" No. You'd hate that, and so would we. OpenSpec grows your specs one change at a time. Your first change documents the slice it touches, the next change documents its slice, and over months your specs fill in naturally around the work you actually do.
-
-This guide shows how to start on day one without boiling the ocean.
-
-## The thirty-second version
-
-```bash
-$ cd your-existing-project
-$ openspec init          # adds openspec/ and your AI tool's commands
-```
-
-Then, in your AI chat:
-
-```text
-/opsx:explore            # optional: have the AI read the area you'll touch
-/opsx:propose <a real, small change you actually need>
-/opsx:apply
-/opsx:archive
-```
-
-Your specs now describe exactly the part of the system that change touched, and nothing more. That's correct. You're done worrying about the other 80,000 lines.
-
-## Why delta-first is the whole trick
-
-OpenSpec changes are written as **deltas**: `ADDED`, `MODIFIED`, `REMOVED`. A delta describes what's changing relative to current behavior, not the entire system.
-
-This is exactly what brownfield work needs. You're rarely building from nothing. You're adding a field, fixing a redirect, tightening a timeout. A delta lets you specify that one change precisely without first writing a 40-page spec of everything around it.
-
-So your `openspec/specs/` directory doesn't start full and complete. It starts nearly empty and accumulates. Each archived change merges its delta in. The spec for `auth/` becomes thorough only after you've made several auth changes, which is exactly when you want it thorough.
-
-If you want the deeper mechanics, see [Concepts: Delta Specs](concepts.md#delta-specs).
-
-## Your first change on a real codebase
-
-Pick something small and real. Not a toy, not a rewrite. A change you were going to make this week anyway. Small first changes teach you the workflow with low stakes.
-
-**Step 1: Let the AI read the relevant area.** This is where `/opsx:explore` earns its keep on an unfamiliar or large codebase. Point it at the part you're about to touch and let it map how things work before proposing anything.
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: I need to add rate limiting to our public API, but I'm not sure
-     how requests currently flow through the middleware.
-
-AI:  Let me trace it... [reads the router, middleware stack, and config]
-     Requests hit Express, pass through auth middleware, then your
-     controllers. There's no rate-limiting layer today. The cleanest
-     insertion point is a middleware right after auth. Want me to scope it?
-```
-
-Notice the AI now understands your actual structure, so the proposal it writes will fit your code, not a generic template. On a big codebase, this single habit saves the most pain. See [Explore First](explore.md).
-
-**Step 2: Propose the change.** The proposal and its delta spec capture just this change.
-
-```text
-You: /opsx:propose add-api-rate-limiting
-```
-
-**Step 3: Build and archive** with `/opsx:apply` and `/opsx:archive`, same as any change. After archiving, you have a real spec for your rate-limiting behavior, born from a change you needed anyway.
-
-## Prefer a guided tour? Use onboard
-
-If you'd rather watch the whole loop happen on your own code with narration, the expanded command `/opsx:onboard` does exactly that: it scans your codebase for a small, safe improvement, then walks you through proposing, building, and archiving it, explaining each step.
-
-Turn on the expanded commands first:
-
-```bash
-$ openspec config profile      # select the expanded workflows
-$ openspec update              # apply them to this project
-```
-
-Then in chat:
-
-```text
-/opsx:onboard
-```
-
-It's the gentlest possible introduction on a real project, and it leaves you with a genuine (small) change you can keep or discard. See [Commands: `/opsx:onboard`](commands.md#opsxonboard).
-
-## "But I already have requirements docs"
-
-Maybe you have a PRD, an SRS, a formal spec, even TLA+ models. Good. You don't import them wholesale, and you don't throw them away either.
-
-Treat existing docs as **source material for exploration**, not as specs to convert. When you start a change, paste or point the AI at the relevant section, and let it shape a focused OpenSpec delta from it. The delta captures the behavior you're changing now, in OpenSpec's testable requirement-and-scenario form. Your original documents stay where they are as background.
-
-The honest reason: OpenSpec specs are deliberately behavior-first and scoped to changes. A 40-page PRD is a different artifact with a different job. Forcing a one-time bulk conversion tends to produce a large, stale spec nobody trusts. Letting specs grow from real changes keeps them accurate.
-
-```text
-You: /opsx:explore
-You: Here's the section of our PRD about checkout. I'm implementing the
-     "guest checkout" requirement next.
-     [paste the relevant requirement]
-AI:  [reads it, asks clarifying questions, then helps scope a change]
-You: /opsx:propose add-guest-checkout
-```
-
-## Organizing specs in a big codebase
-
-Specs live under `openspec/specs/`, grouped by **domain**: a logical area that matches how your team thinks about the system. You don't have to design the whole taxonomy up front. Create a domain folder when your first change in that area needs one.
-
-Common ways to slice domains:
-
- **By feature area:** `auth/`, `payments/`, `search/`
- **By component:** `api/`, `frontend/`, `workers/`
- **By bounded context:** `ordering/`, `fulfillment/`, `inventory/`
-
-Pick whatever makes a newcomer nod. You can refine later. See [Concepts: Specs](concepts.md#specs).
-
-## Monorepos and work that spans repos
-
-For a monorepo, the simplest model is one `openspec/` directory at the repo root, with domains that map to your packages or services. That covers most teams.
-
-If your work genuinely spans **multiple repositories** (or several packages you treat as separate), OpenSpec has a beta **stores** feature: planning lives in its own standalone repo that any of your code repos can reference, so the plan does not have to live inside one repo's `openspec/` folder. It's beta, so treat its commands and state as evolving. Start with the [Stores User Guide](stores-beta/user-guide.md) for the mental model and the smallest useful path.
-
-## A few honest cautions
-
- **Resist the urge to back-fill everything.** Writing specs for code you aren't changing feels productive and usually isn't. Those specs go stale, because nothing forces them to track reality. Let real changes drive your specs.
- **Keep early changes small.** Your first few changes are as much about learning the rhythm as shipping. A tight scope makes the loop fast and the lessons cheap.
- **Commit `openspec/` to git.** Your specs and archive belong in version control alongside the code they describe.
- **Give the AI context.** On a large codebase with strong conventions, fill in `openspec/config.yaml`'s `context:` so every proposal respects your stack and patterns. See [Customization](customization.md#project-configuration).
-
-## Where to go next
-
- [Explore First](explore.md) - the key habit for understanding code before you change it
- [Getting Started](getting-started.md) - the full first-change walkthrough
- [Editing & Iterating on a Change](editing-changes.md) - adjusting a change as you learn
- [Concepts: Delta Specs](concepts.md#delta-specs) - why deltas make brownfield work clean
- [Customization](customization.md) - teach OpenSpec your project's conventions
@@ -1,121 +0,0 @@
-# Explore First
-
-**`/opsx:explore` is your thinking partner. Reach for it whenever you have a problem but not yet a plan.** It investigates your codebase, weighs options with you, and clarifies what you actually want, all before a single artifact or line of code is created. When the picture is clear, it hands off to `/opsx:propose`.
-
-If you take one habit from these docs, take this one: **when you're not sure, explore before you propose.**
-
-Here's why that matters. AI coding assistants are eager. Ask vaguely and they'll confidently build *something*, just maybe not the thing you needed. Explore is the cure. It's a no-stakes conversation where you and the AI figure out the right move together, so that by the time you propose, you're proposing the right thing.
-
-## When to explore
-
-Explore is the right first step more often than people expect. Use it when any of these is true:
-
- You know the *problem* but not the *solution*. ("Pages feel slow." "Auth is a mess." "We keep getting duplicate orders.")
- You're choosing between approaches and want the tradeoffs laid out against your actual code.
- You're new to a codebase and need to understand how something works before you change it.
- The requirements are fuzzy and you want to sharpen them before committing.
- You suspect the work is bigger or smaller than it looks and want to scope it honestly.
-
-Skip explore only when you already know exactly what you want and how. In that case go straight to [`/opsx:propose`](commands.md#opsxpropose).
-
-## What it does (and doesn't)
-
-Explore is a **conversation**, not a generator.
-
-**It does:**
- Read and search your codebase to answer real questions.
- Compare options and name the tradeoffs of each.
- Draw diagrams to make a design legible.
- Help you narrow a vague idea into a concrete, buildable scope.
- Transition to `/opsx:propose` when you're ready.
-
-**It does not:**
- Create a change folder.
- Write any artifacts (no proposal, specs, design, or tasks).
- Write or modify code.
-
-That's the point. Exploring costs you nothing and commits you to nothing. You can explore three dead ends, learn something from each, and only then propose the path that survived.
-
-## It's already installed
-
-Good news: `/opsx:explore` ships in the default **core** profile, right alongside `propose`, `apply`, `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
@@ -1,155 +0,0 @@
-# FAQ
-
-Quick answers to the questions people ask most. If your question is really a "something is broken" question, [Troubleshooting](troubleshooting.md) is the better page. If you want a term defined, see the [Glossary](glossary.md).
-
-## The basics
-
-### What is OpenSpec, in one sentence?
-
-A lightweight layer that gets you and your AI coding assistant to agree on what to build, in writing, before any code is written.
-
-### Why would I want that?
-
-Because AI assistants are confident even when they're wrong. When the requirements live only in a chat thread, the AI fills gaps with guesses, and you find out after the code exists. OpenSpec moves the agreement earlier, where mistakes are cheap to fix. See [Core Concepts at a Glance](overview.md) for the full case.
-
-### Do I have to use it for everything?
-
-No. Use it where agreement matters, which is most non-trivial work. For a one-character typo fix, the ceremony probably isn't worth it, and that's fine.
-
-### Can I use it on a big existing codebase, or only new projects?
-
-Existing codebases are the main event. OpenSpec is brownfield-first: you do not document your whole app up front. You write specs only for what each change touches, and your specs fill in over time around the work you actually do. There's a dedicated guide: [Using OpenSpec in an Existing Project](existing-projects.md).
-
-### Is it tied to one AI tool?
-
-No. OpenSpec works with 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.
@@ -1,32 +1,6 @@
 # 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).
+This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start).

 ## How It Works

@@ -35,19 +9,16 @@ OpenSpec helps you and your AI coding assistant agree on what to build before an
 **Default quick path (core profile):**

 ```text
-/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-   (optional)
+/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
 ```

-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`.
+The default global profile is `core`, which includes `propose`, `explore`, `apply`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`.

 ## What OpenSpec Creates

@@ -276,16 +247,7 @@ 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
@@ -1,91 +0,0 @@
-# Glossary
-
-Every OpenSpec term in one place, defined in plain language. Skim it once and the rest of the docs read faster.
-
-Terms are grouped by topic, then alphabetized within each group.
-
-## The core nouns
-
-**Spec.** A document describing how part of your system behaves. Specs live in `openspec/specs/`, are organized by domain, and are made of requirements and scenarios. The spec is the agreed-upon answer to "what does this software do?" See [Concepts](concepts.md#specs).
-
-**Source of truth.** The `openspec/specs/` directory as a whole. It holds the current, agreed-upon behavior of your system. Changes propose edits to it; archiving applies them.
-
-**Change.** One unit of work, packaged as a folder under `openspec/changes/<name>/`. A change holds everything about that work: its proposal, design, tasks, and the spec edits it introduces. One change, one feature or fix.
-
-**Artifact.** A document inside a change. The standard artifacts are the proposal, the delta specs, the design, and the tasks. They're created in dependency order and feed into each other.
-
-**Delta spec.** A spec inside a change that describes only what's changing, using `ADDED`, `MODIFIED`, and `REMOVED` sections, rather than restating the entire spec. This is what lets OpenSpec edit existing systems cleanly. See [Concepts](concepts.md#delta-specs).
-
-**Domain.** A logical grouping for specs, like `auth/`, `payments/`, or `ui/`. You choose domains that match how you think about your system.
-
-## Inside a spec
-
-**Requirement.** A single behavior the system must have, usually written with an RFC 2119 keyword: "The system SHALL expire sessions after 30 minutes." Requirements state the *what*, not the *how*.
-
-**Scenario.** A concrete, testable example of a requirement in action, typically in Given/When/Then form. Scenarios make a requirement verifiable: you could write an automated test from one.
-
-**RFC 2119 keywords.** The words MUST, SHALL, SHOULD, and MAY, which carry standardized meaning about how strict a requirement is. MUST and SHALL are absolute. SHOULD is recommended with room for exceptions. MAY is optional. The name comes from the internet standards document that defined them.
-
-## The artifacts
-
-**Proposal (`proposal.md`).** The *why* and *what* of a change: its intent, scope, and high-level approach. The first artifact you create.
-
-**Design (`design.md`).** The *how*: technical approach, architecture decisions, and the files you expect to touch. Optional for simple changes.
-
-**Tasks (`tasks.md`).** The implementation checklist, with checkboxes. The AI works through it during `/opsx:apply` and checks items off as it goes.
-
-## The lifecycle
-
-**Archive.** The act of finishing a change. Its delta specs merge into the main specs, and the change folder moves to `openspec/changes/archive/YYYY-MM-DD-<name>/`. After archiving, your specs describe the new reality. See [Concepts](concepts.md#archive).
-
-**Sync.** Merging a change's delta specs into the main specs *without* archiving the change. Usually automatic (archive offers to do it), but available on its own as `/opsx:sync` for long-running changes. See [Commands](commands.md#opsxsync).
-
-## Workflow and commands
-
-**OPSX.** The current standard OpenSpec workflow, built around fluid actions instead of rigid phases. Its slash commands all start with `/opsx:`. See [OPSX Workflow](opsx.md).
-
-**Slash command.** A command you type into your AI assistant's chat, like `/opsx:propose`. Slash commands drive the workflow. They are not terminal commands. See [How Commands Work](how-commands-work.md).
-
-**Explore (`/opsx:explore`).** The thinking-partner command. It reads your codebase, compares options, and clarifies a fuzzy idea into a concrete plan, creating no artifacts and writing no code. The recommended starting point whenever you have a problem but not yet a plan. See [Explore First](explore.md).
-
-**CLI.** The `openspec` program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives. The terminal half of OpenSpec. See [CLI](cli.md).
-
-**Skill.** A folder of instructions (`.../skills/openspec-*/SKILL.md`) that your AI assistant auto-detects and follows. Skills are the emerging cross-tool standard for delivering the OpenSpec workflow to your assistant.
-
-**Command file.** A per-tool slash command file (`.../commands/opsx-*`). The older delivery mechanism, still supported alongside skills. You rarely touch these directly.
-
-**Profile.** The set of slash commands installed in your project. **Core** (the default) is `propose`, `explore`, `apply`, `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
@@ -1,173 +0,0 @@
-# How Commands Work
-
-**The one thing to know: OpenSpec has two kinds of commands, and they run in two different places.**
-
- `openspec ...` commands run in your **terminal**. (Example: `openspec init`.)
- `/opsx:...` commands run in your **AI assistant's chat**. (Example: `/opsx:propose`.)
-
-If you ever type `/opsx:propose` into your terminal and nothing happens, this page is why. You are talking to the wrong half of OpenSpec. Slash commands are not terminal commands. They are instructions you give to your AI coding assistant, in the same chat box where you'd normally type "add a login form."
-
-That single distinction is the most common stumbling block for new users, so let's make it crystal clear.
-
-## The two halves
-
-OpenSpec is one project wearing two hats.
-
-**The CLI (terminal half).** A program named `openspec` that you install and run from your shell. It sets up your project, lists and validates changes, shows a dashboard, and archives finished work. You type these into iTerm, the VS Code terminal, PowerShell, anywhere you'd run `git` or `npm`.
-
-```bash
-openspec init        # set up OpenSpec in this project
-openspec list        # see active changes
-openspec view        # open the interactive dashboard
-```
-
-**The slash commands (chat half).** Short commands like `/opsx:propose` and `/opsx:apply` that you type into your AI assistant. These tell the AI to follow the OpenSpec workflow: draft a proposal, write specs, build from the task list, archive when done. You type these into Claude Code, Cursor, 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, Zed Agent, 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, Zed Agent, 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
@@ -4,78 +4,6 @@

 - **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
@@ -96,25 +24,6 @@ pnpm add -g @fission-ai/openspec@latest
 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.
@@ -161,39 +70,44 @@ Or add to your development environment in `flake.nix`:
 openspec --version
 ```

-## Updating
+## Troubleshooting PATH Visibility

-Upgrade the package, then refresh each project's generated files:
+If `openspec --version` works in one terminal but fails in an editor, AI agent,
+GUI app, or automation, OpenSpec is usually installed correctly but that process
+started with a different `PATH`.
+
+Global package managers create an executable shim in a bin directory, then your
+shell or launcher must put that directory on `PATH`. Common ways to inspect the
+directory are:

 ```bash
-npm install -g @fission-ai/openspec@latest   # or pnpm/yarn/bun equivalent
-openspec update                              # run inside each project
+# npm
+printf '%s/bin\n' "$(npm prefix -g)"
+
+# pnpm
+pnpm bin -g
+
+# bun
+bun pm bin -g
+
+# current shell
+command -v openspec
 ```

-`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).
+Make sure the environment that launches your editor, agent, GUI app, or
+automation includes the package-manager bin directory. For shell startup files,
+keep this to a minimal `PATH` export in a file that the target environment
+actually reads. Do not move interactive setup such as prompts, themes,
+completions, or commands that can block into always-loaded startup files.

-## 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:**
+To bypass global bin discovery while debugging, run OpenSpec through a package
+manager:

 ```bash
-npm uninstall -g @fission-ai/openspec   # or: pnpm rm -g / yarn global remove / bun rm -g
+npx -y @fission-ai/openspec@latest --version
+pnpm dlx @fission-ai/openspec@latest --version
 ```

-**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:
@@ -8,7 +8,7 @@ OPSX replaces the old phase-locked workflow with a fluid, action-based approach.

 | Aspect | Legacy | OPSX |
 |--------|--------|------|
-| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:update`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
+| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
 | **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice |
 | **Going back** | Awkward phase gates | Natural—update any artifact anytime |
 | **Customization** | Fixed structure | Schema-driven, fully hackable |
@@ -43,11 +43,10 @@ Only OpenSpec-managed files that are being replaced:

 - Claude Code: `.claude/commands/openspec/`
 - Cursor: `.cursor/commands/openspec-*.md`
- Devin Desktop, formerly Windsurf: `.windsurf/workflows/openspec-*.md`
+- Windsurf: `.windsurf/workflows/openspec-*.md`
 - Cline: `.clinerules/workflows/openspec-*.md`
 - Roo: `.roo/commands/openspec-*.md`
 - GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
- 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.
@@ -85,7 +84,7 @@ Don't worry about getting it perfect. We're still learning what works best here,

 Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation:

- New installs default to profile `core` (`propose`, `explore`, `apply`, `update`, `sync`, `archive`).
+- New installs default to profile `core` (`propose`, `explore`, `apply`, `sync`, `archive`).
 - Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed.

 ### Using `openspec init`
@@ -157,8 +156,6 @@ 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
@@ -290,8 +287,6 @@ Command availability is profile-dependent:
 | `/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):**
@@ -302,6 +297,7 @@ Command availability is profile-dependent:
 | `/opsx:continue` | Create the next artifact (one at a time) |
 | `/opsx:ff` | Fast-forward—create planning artifacts at once |
 | `/opsx:verify` | Validate implementation matches specs |
+| `/opsx:sync` | Preview/spec-merge without archiving |
 | `/opsx:bulk-archive` | Archive multiple changes at once |
 | `/opsx:onboard` | Guided end-to-end onboarding workflow |

@@ -411,8 +407,6 @@ OPSX uses the emerging **skills** standard:

 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
@@ -567,9 +561,7 @@ project/
 │       ├── 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
@@ -4,18 +4,6 @@ Configure OpenSpec to generate artifacts in languages other than English.

 ## Quick Setup

-For a new project, set the language during initialization:
-
-```bash
-openspec init --language "Portuguese (pt-BR)"
-```
-
-This writes the language instruction to `openspec/config.yaml`. If the project
-already has a config, edit its `context` field directly so existing project
-guidance is preserved.
-
-You can also configure the same behavior manually:
-
 Add a language instruction to your `openspec/config.yaml`:

 ```yaml
@@ -24,7 +12,6 @@ schema: spec-driven
 context: |
  Language: Portuguese (pt-BR)
  All artifacts must be written in Brazilian Portuguese.
-  Keep OpenSpec structural headings and SHALL/MUST keywords in English.

  # Your other project context below...
  Tech stack: TypeScript, React, Node.js
@@ -32,10 +19,6 @@ context: |

 That's it. All generated artifacts will now be in Portuguese.

-OpenSpec's document structure and normative `SHALL`/`MUST` keywords remain in
-English because validation relies on them. The surrounding requirement and
-scenario prose can use your selected language.
-
 ## Language Examples

 ### Portuguese (Brazil)
@@ -65,7 +65,7 @@ openspec init

 This creates skills in `.claude/skills/` (or equivalent) that AI coding assistants auto-detect.

-By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `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`.
+By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`.

 During setup, you'll be prompted to create a **project config** (`openspec/config.yaml`). This is optional but recommended.

@@ -163,9 +163,8 @@ rules:
 | `/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: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:sync` | Sync delta specs to main (default workflow, optional) |
 | `/opsx:archive` | Archive when done |
 | `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) |
 | `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) |
@@ -209,18 +208,6 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 Works through tasks, checking them off as you go. If you're juggling multiple changes, you can run `/opsx:apply <name>`; otherwise it should infer from the conversation and prompt you to choose if it can't tell.

-### Updating a change
-```
-/opsx:update add-dark-mode - we're storing the theme in a cookie now
-```
-Revises the change's existing planning artifacts and keeps them coherent - in any direction (a design edit may ripple back to the proposal). Planning artifacts only: it never edits code, and it never creates missing artifacts (that's `/opsx:continue`). Every edit is confirmed with you first. If the change was already implemented, it recommends `/opsx:apply` so the code catches up with the revised plan. If your revision changes the change's *intent*, start fresh instead - see [When to Update vs. Start Fresh](#when-to-update-vs-start-fresh).
-
-### 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:archive   # Move to archive when done (prompts to sync specs if needed)
@@ -425,7 +412,7 @@ Examples in this section use the expanded command set (`new`, `continue`, etc.);
 │                    ▼                                                        │
 │   Skill Files (.claude/skills/openspec-*/SKILL.md)                          │
 │                                                                             │
-│   • Cross-editor compatible (Claude Code, Cursor, Devin)                    │
+│   • Cross-editor compatible (Claude Code, Cursor, Windsurf)                 │
 │   • Skills query CLI for structured data                                    │
 │   • Fully customizable via schema files                                     │
 │                                                                             │
@@ -484,7 +471,7 @@ Artifacts form a directed acyclic graph (DAG). Dependencies are **enablers**, no
  │  • Create proposal.md                   │
  │  • Create tasks.md                      │
  │  • Create design.md                     │
-  │  • Create delta spec files              │
+  │  • Create specs/<capability>/spec.md    │
  │                                         │
  │  No awareness of what exists or         │
  │  dependencies between artifacts         │
@@ -510,8 +497,7 @@ 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", "design"]}                          │  │
+  │  │      {"id": "tasks", "status": "blocked", "missingDeps": ["specs"]}│  │
  │  │    ]                                                               │  │
  │  │  }                                                                 │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
@@ -1,91 +0,0 @@
-# Core Concepts at a Glance
-
-**OpenSpec is a lightweight agreement layer between you and your AI.** You write down what a change should do, the AI drafts the details, you both look at the same plan, and only then does code get written. This page is the whole mental model on one screen. When you want the long version, [Concepts](concepts.md) has it.
-
-Here's the entire idea in five words: **agree first, then build confidently.**
-
-## The five ideas
-
-Everything in OpenSpec is built from five concepts. Learn these and the rest is detail.
-
-**1. Specs are the truth.** A spec describes how your system behaves *right now*. It lives in `openspec/specs/`, organized by domain (`auth/`, `payments/`, `ui/`). Specs are made of requirements ("the system SHALL expire sessions after 30 minutes") and scenarios (concrete given/when/then examples). Think of specs as the single agreed-upon answer to "what does this software do?"
-
-**2. A change is one unit of work.** When you want to add, modify, or remove behavior, you create a change: a folder in `openspec/changes/` holding everything about that work in one place. A proposal, a design, a task list, and the spec edits. One change, one folder, one feature.
-
-**3. Delta specs describe what's changing, not the whole world.** Inside a change, you don't rewrite the entire spec. You write a small delta: `ADDED` this requirement, `MODIFIED` that one, `REMOVED` this other one. This is the trick that makes OpenSpec good at editing existing systems, not just green-field ones. You describe the diff, not the destination.
-
-**4. Artifacts build on each other.** A change contains a few documents, created in a natural order, each feeding the next:
-
-```text
-proposal ──► specs ──► design ──► tasks ──► implement
-   why        what       how       steps      do it
-```
-
-You can revisit any of them at any time. They're enablers, not gates. (More on that below.)
-
-**5. Archiving folds the change back into the truth.** When the work is done, you archive the change. Its delta specs merge into your main specs, and the change folder moves to `changes/archive/` with a date stamp. Now your specs describe the new reality, and you're ready for the next change. The cycle closes.
-
-## The picture
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                          openspec/                              │
-│                                                                 │
-│   ┌──────────────────┐         ┌──────────────────────────┐    │
-│   │     specs/       │         │        changes/          │    │
-│   │                  │ ◄─────  │                          │    │
-│   │ source of truth  │  merge  │ one folder per change    │    │
-│   │ how things work  │  on     │ proposal · design ·      │    │
-│   │ today            │ archive │ tasks · delta specs      │    │
-│   └──────────────────┘         └──────────────────────────┘    │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-Two folders. `specs/` is what's true. `changes/` is what you're proposing. Archiving moves a proposal into truth.
-
-## The loop you'll actually run
-
-In the default setup, your day looks like this. Optionally think it through first; then one command drafts the plan, you read it, the next builds it, and the last files it away.
-
-```text
-/opsx:explore                   →  (optional) think it through with the AI first
-/opsx:propose add-dark-mode     →  AI drafts proposal, specs, design, tasks
-        (you read and adjust the plan)
-/opsx:apply                     →  AI builds it, checking off tasks
-/opsx:archive                   →  specs updated, change archived
-```
-
-**When in doubt, start by exploring.** `/opsx:explore` is a no-stakes thinking partner: it reads your code, lays out options, and turns a fuzzy idea into a concrete plan before any artifact exists. It's the best antidote to an AI that will otherwise build *something* from a vague prompt. Already know exactly what you want? Skip straight to `/opsx:propose`. Either way, explore ships in the default profile, so it's always there. See the [Explore guide](explore.md).
-
-Those are slash commands, typed in your AI assistant's chat. Setup (`openspec init`) happens in your terminal. If that split is new to you, read [How Commands Work](how-commands-work.md) first; it's the most common point of confusion.
-
-## "Enablers, not gates"
-
-This phrase shows up everywhere in OpenSpec, so here's what it means in plain terms.
-
-Old-school spec processes are waterfalls: finish planning, *then* you're allowed to implement, and going back is painful. OpenSpec refuses that. The order `proposal → specs → design → tasks` shows what becomes *possible* next, not what you're *forced* to do next.
-
-Discover during implementation that the design was wrong? Edit `design.md` and keep going. Realize the scope should shrink? Update the proposal. Nothing locks. The dependencies exist only so the AI has the context it needs (you can't write good tasks without specs to base them on), not to box you in.
-
-The strength here is honesty: real work is messy and iterative, and OpenSpec lets it be. The tradeoff is discipline: because nothing forces you forward, it's on you to keep a change focused rather than letting it sprawl. The [Workflows](workflows.md) guide has good habits for that.
-
-## Why this is worth the small overhead
-
-Plain truth: OpenSpec adds a step. You write a short plan before building. So what do you get for it?
-
- **You catch wrong turns before they cost you.** Fixing a misunderstanding in a one-paragraph proposal is free. Fixing it after the AI wrote 400 lines is not.
- **The plan and the code stay in the same repo.** Six months later, the spec tells you (and the next AI session) why the system works the way it does.
- **Changes are reviewable.** A change folder is a tidy package: read the proposal, skim the deltas, check the tasks. No archaeology through chat history.
- **It fits existing codebases.** Deltas mean you can specify a change to a 50,000-line app without first documenting the whole thing.
-
-And the honest tradeoff: for a truly trivial one-line fix, the ceremony may not pay off, and that's fine. OpenSpec is designed to be lightweight, but it isn't free. Use it where agreement matters, which turns out to be most of the time once you're working with an AI that will confidently build whatever you vaguely asked for.
-
-## Where to go next
-
- New here? [Getting Started](getting-started.md) walks the first change in full.
- Not sure what to build yet? [Explore First](explore.md) is the place to start.
- Confused about where commands run? [How Commands Work](how-commands-work.md).
- Want the deep version of everything above? [Concepts](concepts.md).
- Learn by example? [Examples & Recipes](examples.md).
- Need a term defined? [Glossary](glossary.md).
@@ -1,143 +0,0 @@
-# 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.
@@ -1,462 +0,0 @@
-# Stores: Plan in Its Own Repo
-
-> **Beta.** Stores, references, working context, and worksets are
-> new. Command names, flags, file formats, and JSON output may still change
-> shape between releases. Every walkthrough below was run against the
-> current build, but re-read this guide after upgrading.
-
-## The problem this solves
-
-OpenSpec normally lives inside one code repo: an `openspec/` folder next to
-your code, holding specs and changes for that repo.
-
-That stops fitting the moment your planning is bigger than one repo:
-
- Your work spans several repos — one feature touches the API server, the
-  web app, and a shared library. Whose `openspec/` folder does the plan
-  live in?
- Your team plans before code exists, or plans things that never become
-  code in *this* repo.
- Requirements are owned by one team and consumed by others. The wiki
-  version drifts, and your coding agent can't read it anyway.
-
-A **store** is the answer: a standalone repo whose whole job is planning.
-It has the same `openspec/` shape you already know — specs and changes —
-plus a small identity file. You register it on your machine once, by name,
-and then every normal OpenSpec command can work in it from anywhere.
-
-## The shape
-
-```
-            team-plans  (a store: planning in its own repo)
-            ├── .openspec-store/store.yaml     identity: "I am team-plans"
-            └── openspec/
-                ├── specs/      what is true
-                └── changes/    what is in motion
-                      ▲
-                      │ registered on each machine by name;
-                      │ shared by pushing/cloning like any repo
-        ┌─────────────┼─────────────┐
-        │             │             │
-    web-app       api-server     mobile-app
-   (code repo)   (code repo)    (code repo)
-```
-
-Two rules keep this simple:
-
-1. **A store is just a git repo.** You commit, push, pull, and review it
-   yourself. OpenSpec never clones, syncs, or pushes anything on its own.
-2. **Declarations, not machinery.** Repos can *declare* how they relate to
-   stores (shown below). Declarations change what OpenSpec can tell you —
-   never where your commands act.
-
-## Five minutes to your first store
-
-Two commands take you from nothing to a working, store-scoped change:
-
-```bash
-openspec store setup team-plans --path ~/openspec/team-plans
-```
-
-```
-Store ready: team-plans
-Location: /Users/you/openspec/team-plans
-OpenSpec root: ready
-Registry: registered
-
-Next: run normal OpenSpec commands against this store, for example:
-  openspec new change <change-id> --store team-plans
-Share this store by committing and pushing it like any Git repo.
-```
-
-```bash
-openspec new change add-login --store team-plans
-```
-
-```
-Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
-Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
-Schema: spec-driven
-Next: openspec status --change add-login --store team-plans
-```
-
-That's the whole model. From here the lifecycle is exactly what you know —
-`status`, `instructions`, `validate`, `archive` — with `--store team-plans`
-on each command, and every printed hint carries the flag for you. The
-`Using OpenSpec root:` line always tells you where a command is acting.
-
-## Story: one team, one planning repo
-
-A team keeps its specs and changes in `team-plans` instead of scattering
-them across code repos.
-
-**Day one (whoever sets it up):**
-
-```bash
-openspec store setup team-plans --path ~/openspec/team-plans \
-  --remote git@github.com:acme/team-plans.git
-git -C ~/openspec/team-plans push -u origin main
-```
-
-Passing `--remote` records the clone URL inside the store's own identity
-file (`.openspec-store/store.yaml`), in the initial commit. Every future
-clone is born knowing where it came from, so health checks and error
-messages can print a complete, pasteable fix for teammates who don't have
-it yet.
-
-**Every teammate (once per machine):**
-
-```bash
-git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
-openspec store register ~/openspec/team-plans
-```
-
-From then on, everyone works in the same planning repo by name:
-
-```bash
-openspec status --store team-plans --change add-login
-openspec show add-login --store team-plans
-```
-
-**Sharing work is git, on purpose.** A change you create exists only in
-your checkout until you commit and push it — same as code. Plans get
-branches, pull requests, and review for free, because a store is an
-ordinary repo.
-
-**Connecting the team's code repos.** A code repo whose planning is fully
-externalized needs exactly one line, in `openspec/config.yaml`:
-
-```yaml
-# web-app/openspec/config.yaml
-store: team-plans
-```
-
-Now every OpenSpec command run inside `web-app` acts on `team-plans` with
-no flags at all:
-
-```bash
-cd ~/src/web-app
-openspec status --change add-login
-```
-
-```
-Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
-...
-```
-
-The pointer is a fallback, never an override: an explicit `--store` always
-wins, and if the repo grows real planning folders of its own, those win
-(with a warning to remove the stale pointer).
-
-**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).
@@ -9,57 +9,15 @@ 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, Zed Agent, 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 |
@@ -70,11 +28,8 @@ to read the hint.
 | 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`\*\*\*\* |
+| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
 | ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
 | Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
 | CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-<id>.md` |
@@ -83,118 +38,23 @@ to read the hint.
 | 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) |
+| Kimi CLI (`kimi`) | `.kimi/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
 | Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
 | Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
-| 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` |
-| [Zed Agent](https://zed.dev/docs/ai/skills) (`zed`) | `.agents/skills/openspec-*/SKILL.md` | Not generated (skills-only; use `/openspec-*` or `@openspec-*`) |
-| 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) |
+| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-<id>.toml` |
+| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
+| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
+| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-<id>.md` |

-\*\* 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.
+\* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory.

-\*\*\* 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 and Zed Agent are the exceptions because they use the same canonical
-`.agents` root. If Codex is selected with Zed or `agents`, 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).
-
-Zed support here is for the built-in Zed Agent. Zed External Agents and Terminal
-Threads use their own integrations. Agent Skills require
-[Zed v1.4.2](https://github.com/zed-industries/zed/releases/tag/v1.4.2) or newer.
-Project-local skills are unavailable in an untrusted worktree until you
-[grant trust](https://zed.dev/docs/worktree-trust).
-
-Because `.agents/skills/` is shared by Codex, Zed Agent, and the vendor-neutral target,
-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,
-Zed Agent, 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.
+\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.

 ## Non-Interactive Setup

@@ -214,15 +74,15 @@ openspec init --tools none
 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`, `zed`, `zcode`, `agents`
+**Available tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `opencode`, `pi`, `qoder`, `lingma`, `qwen`, `roocode`, `trae`, `windsurf`

 ## Workflow-Dependent Installation

 OpenSpec installs workflow artifacts based on selected workflows:

- **Core profile (default):** `propose`, `explore`, `apply`, `update`, `sync`, `archive`
+- **Core profile (default):** `propose`, `explore`, `apply`, `sync`, `archive`
 - **Custom selection:** any subset of all workflow IDs:
-  `propose`, `explore`, `new`, `continue`, `apply`, `update`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`
+  `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`

 In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed.

@@ -235,7 +95,6 @@ When selected by profile/workflow config, OpenSpec generates these skills:
 - `openspec-new-change`
 - `openspec-continue-change`
 - `openspec-apply-change`
- `openspec-update-change`
 - `openspec-ff-change`
 - `openspec-sync-specs`
 - `openspec-archive-change`
@@ -1,74 +0,0 @@
-# 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.
@@ -1,195 +0,0 @@
-# Troubleshooting
-
-Concrete fixes for concrete problems. Each entry names a symptom, explains the likely cause in a sentence, and gives you the fix. If you don't see your issue here, the [FAQ](faq.md) may help, and the [Discord](https://discord.gg/YctCnvvshC) definitely will.
-
-## Installation and setup
-
-### `openspec: command not found`
-
-The CLI isn't installed, or your shell can't find it. Install it globally and check:
-
-```bash
-npm install -g @fission-ai/openspec@latest
-openspec --version
-```
-
-If it installed but still isn't found, your global npm bin directory probably isn't on your `PATH`. Run `npm 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, Zed Agent, 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.
@@ -28,120 +28,23 @@ OPSX (fluid actions):

 > **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.

-## Workflow 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:explore`
 - `/opsx:apply`
- `/opsx:update`
 - `/opsx:sync`
 - `/opsx:archive`

 Typical flow:

 ```text
-/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-  (optional)
+/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
 ```

-#### 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:
@@ -532,7 +435,7 @@ 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:explore` | Think through ideas | Unclear requirements, investigation |
 | `/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 |
@@ -544,9 +447,6 @@ For full command details and options, see [Commands](commands.md).

 ## 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
@@ -1,103 +0,0 @@
-# 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. Retirement deletes the whole file, so it is also refused while the spec holds anything outside its title, `## Purpose`, and its requirement blocks — a `## Notes` section, a comment under a requirement. The abort names those lines; move them into `## Purpose` or a requirement, or delete the spec by hand. 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.
@@ -39,7 +39,6 @@
                ./test
                ./package.json
                ./pnpm-lock.yaml
-                ./pnpm-workspace.yaml
                ./tsconfig.json
                ./build.js
                ./vitest.config.ts
@@ -52,11 +51,11 @@
              inherit (finalAttrs) pname version src;
              pnpm = pkgs.pnpm_9;
              fetcherVersion = 3;
-              hash = "sha256-fzQ9rIQi5RdbKZdcGUynbmo6eX8JEjx78CurnolOGgw=";
+              hash = "sha256-9s2kdvd7svK4hofnD66HkDc86WTQeayfF5y7L2dmjNg=";
            };

            nativeBuildInputs = with pkgs; [
-              nodejs_22
+              nodejs_20
              npmHooks.npmInstallHook
              pnpmConfigHook
              pnpm_9
@@ -98,7 +97,7 @@
        {
          default = pkgs.mkShell {
            buildInputs = with pkgs; [
-              nodejs_22
+              nodejs_20
              pnpm_9
            ];

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

 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.
+Trae is a concrete example: it invokes OpenSpec workflows via skill entries (for example `/openspec-new-change`) rather than adapter-generated command files. In this model, skills are the command surface.

 Today, this creates a behavior gap:

 - `delivery=commands` can remove skills
 - tools without adapters skip command generation
- result: selected tools like Kimi CLI, ForgeCode, or Mistral Vibe can end up with no invocable workflow artifacts
+- result: selected tools like Trae can end up with no invocable workflow artifacts

 This is more than a prompt UX issue because non-interactive and CI flows bypass interactive guidance. We need a capability-aware model in core generation logic.

@@ -25,13 +25,9 @@ Add an optional field in tool metadata to describe how a tool exposes commands:
 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:
+Initial explicit override:

- 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.
+- Trae -> `skills-invocable`

 ### 2. Make delivery behavior capability-aware

@@ -66,12 +62,12 @@ Update summaries to show effective delivery outcomes per tool (for example, when

 ### 4. Update docs and tests

- document capability model and skills-invocable behavior under delivery modes
+- document capability model and Trae behavior under delivery modes
 - ensure CLI docs and supported-tools docs reflect effective behavior
 - add test coverage for:
-  - `init --tools kimi` with `delivery=commands`
-  - `update` with Kimi CLI configured under `delivery=commands`
-  - mixed selections (`claude + kimi`) across all delivery modes
+  - `init --tools trae` with `delivery=commands`
+  - `update` with Trae configured under `delivery=commands`
+  - mixed selections (`claude + trae`) across all delivery modes
  - explicit error path for tools with no command surface under `delivery=commands`

 ### 5. Coordinate with install-scope behavior
@@ -98,7 +94,7 @@ Implementation tests should cover mixed-tool matrices to ensure deterministic be

 ## Impact

- `src/core/config.ts` - add optional command-surface metadata and skills-invocable tool overrides
+- `src/core/config.ts` - add optional command-surface metadata and Trae override
 - `src/core/command-generation/registry.ts` (or shared helper) - capability inference from adapter presence
 - `src/core/init.ts` - capability-aware generation/removal planning + compatibility validation + summary messaging
 - `src/core/update.ts` - capability-aware sync/removal planning + compatibility validation + summary messaging
@@ -9,7 +9,7 @@

 - [ ] 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.3 Mark Trae as `skills-invocable`
 - [ ] 1.4 Add a shared capability resolver (explicit metadata override first, inferred fallback from adapter presence second)
 - [ ] 1.5 Add focused unit tests for capability resolution (explicit override, inferred adapter, inferred none)

@@ -20,7 +20,7 @@
 - [ ] 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`)
+- [ ] 2.6 Add/adjust init tests for `delivery=commands` + `trae` (skills retained/generated, no adapter error), mixed tools (`claude,trae`) with per-tool expected outputs, and deterministic failure path for unsupported command surface (`none`)

 ## 3. Update: Capability-Aware Sync and Drift Detection

@@ -30,7 +30,7 @@
 - [ ] 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`)
+- [ ] 3.7 Add/adjust update tests for `delivery=commands` + configured Trae (skills retained/generated), idempotent second update (no false drift loop), mixed configured tools (`claude` + `trae`), and deterministic preflight failure for unsupported command surface (`none`)

 ## 4. UX and Error Messaging

@@ -40,7 +40,7 @@

 ## 5. Documentation Updates

- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for skills-invocable tools and clarify delivery interactions
+- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for Trae and clarify delivery interactions
 - [ ] 5.2 Update `docs/cli.md` delivery guidance to explain capability-aware behavior for `delivery=commands`
 - [ ] 5.3 Add a short troubleshooting note for "commands-only + unsupported tool" failures

@@ -49,5 +49,5 @@
 - [ ] 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`
+- [ ] 6.4 Manual smoke check: `openspec init --tools trae` with `delivery=commands`
+- [ ] 6.5 Manual smoke check: mixed tools (`claude,trae`) with `delivery=commands`
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-06-29
@@ -1,116 +0,0 @@
-# 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.
@@ -1,66 +0,0 @@
-## Why
-
-OPSX names **four** first-class actions — "create, implement, **update**, archive — do any of them anytime" ([docs/opsx.md:52](../../../docs/opsx.md)). Three ship as commands. **`update` does not exist.** The only mechanism offered is *"edit the files manually"* — and when you edit one artifact, nothing helps you keep the rest of the change coherent. Worse, the manual workaround lets the agent edit **code** when the user only wanted to revise the **plan** ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)).
-
-This is the most-requested missing capability in the tracker. It is one gap with several faces, and the fix is small: a thin `/opsx:update` skill that revises a change's planning artifacts and keeps them coherent with each other, built on the **existing** `openspec status` / `openspec list` commands. No new graph engine, no digests, no ledger — just an agent that reads the change's artifacts and updates what needs updating, with the user's confirmation.
-
-## What Changes
-
-The whole feature is a single new workflow skill, `/opsx:update`. The skill is deliberately change-scoped — `openspec-update-change`, following the `openspec-<verb>-change` naming of its siblings — and applies to change proposals only, not arbitrary artifact graphs (see design, Naming). Written by hand, its instruction set is short:
-
-1. **Understand the request** — what the user wants to revise (or, with no specific ask, "review this change for coherence").
-2. **Get the artifacts** — run `openspec status --change <id> --json`. Its `artifactPaths` map reports, per artifact, which files exist and where: `existingOutputPaths` is the concrete file list to edit — already expanded for glob artifacts like `specs/**/*.md`. (`openspec list --json` to pick the change when it isn't given.)
-3. **Read and revise** — read the relevant artifacts, make the requested edit, then check the change's **other** artifacts against it and propose any follow-on edits needed to keep the plan coherent.
-4. **Confirm and apply** — show each proposed revision, write only after the user confirms.
-5. **Point to the next step** — report where the change now stands and recommend what comes next: artifacts still missing → `/opsx:continue`; plan revised after the change was already implemented → `/opsx:apply` to carry the delta into code; everything done and implemented → `/opsx:archive`. Guidance only — the skill never acts on it.
-
-Two guardrails make it the command the cluster asked for:
-
- **Planning artifacts only, never code.** If a revised plan implies code changes, it hands off to `/opsx:apply` ([#1188](https://github.com/Fission-AI/OpenSpec/issues/1188)).
- **Schema-driven, not name-driven.** Artifact ids and paths come from `openspec status`, so the skill works for custom schemas, not just the default `proposal → specs → design → tasks` ([#777](https://github.com/Fission-AI/OpenSpec/issues/777), [#666](https://github.com/Fission-AI/OpenSpec/issues/666)).
-
-**Coherence is bidirectional.** Earlier framing treated update as strictly "downstream" propagation. That is wrong: in `proposal → specs → design → tasks`, editing `design` can require revising `proposal` too. The skill reads the change's artifacts and reconciles them in whatever direction the edit demands, rather than assuming a fixed flow.
-
-### Deliberately not built (yet)
-
-Per the steer to introduce as little code as possible, and only when there is a defined need, this change does **not** add: a reverse-dependency graph API, content digests / staleness signals, a `.openspec.yaml` baseline ledger, an `openspec reconcile` write op, a drift report, or a `status --impact` selector. The agent reads the change's artifacts directly — a handful of markdown files — which is enough to judge coherence. If a future, concrete need emerges (e.g. unattended drift detection across many changes), exposing the schema's `requires` edges on `openspec status --json` is a one-field additive follow-up. It is out of scope here.
-
-## Capabilities
-
-### New Capabilities
-
- `opsx-update-skill`: A new `/opsx:update` workflow skill that revises a change's existing planning artifacts and keeps them coherent with one another. It reads the artifact set and paths from `openspec status`, reviews related artifacts in any direction (not only downstream), edits planning artifacts only and never code, and confirms each edit with the user. It ends with next-step guidance — recommending `/opsx:continue`, `/opsx:apply`, or `/opsx:archive` based on the change's state — without acting on it.
-
-## Impact
-
- `src/core/templates/workflows/update-change.ts` (**new**) — the `openspec-update-change` skill template and the `/opsx:update` command template, mirroring the structure of `continue-change.ts`. Reads artifact ids and paths from `openspec status --json`; embeds no artifact-name patterns.
- Skill/command registration + [src/core/profiles.ts](../../../src/core/profiles.ts) — add `update` to `ALL_WORKFLOWS` **and to the default `core` profile** (`propose`, `explore`, `apply`, `sync`, `archive`), so `/opsx:update` is part of the default install rather than expanded-only (maintainer call on the PR).
- `docs/opsx.md` — add a `/opsx:update` row to the command table and a short "Updating a change" usage note.
- `openspec/changes/add-artifact-regeneration-support/` — the in-repo proposal-only stub for this gap is superseded; retire it or fold its notes into design.
- No changes to `src/core/artifact-graph/*`, `src/commands/workflow/status.ts`, or `ChangeMetadataSchema`. The skill uses `openspec status` / `openspec list` as they exist today.
-
-## Issues addressed
-
-Verified against `Fission-AI/OpenSpec` on 2026-06-30.
-
-Closes (the missing-update-action family):
-
- [#1188](https://github.com/Fission-AI/OpenSpec/issues/1188) — "Add a command to update proposal, design and task" (and stop it editing code). Delivered as `/opsx:update`, planning-artifacts-only.
- [#705](https://github.com/Fission-AI/OpenSpec/issues/705) — "Rebuild downstream artifacts from a modified upstream." Delivered as the skill's read-and-reconcile pass over the change's artifacts.
- [#673](https://github.com/Fission-AI/OpenSpec/issues/673) — "clarify": update existing artifacts without auto-advancing the build frontier. `/opsx:update` revises in place and never creates the next artifact.
- [#247](https://github.com/Fission-AI/OpenSpec/issues/247) — "review and update all change proposals." Delivered as the within-a-change coherence review; cross-change audit is a separate, later proposal.
-
-Answers (questions whose honest answer today is "no command exists"):
-
- [#694](https://github.com/Fission-AI/OpenSpec/issues/694), [#684](https://github.com/Fission-AI/OpenSpec/issues/684), [#618](https://github.com/Fission-AI/OpenSpec/issues/618) — "which command regenerates a document after the flow progressed / after apply?" → `/opsx:update`.
- Discussion [#1206](https://github.com/Fission-AI/OpenSpec/discussions/1206) — the official answer becomes `/opsx:update`.
-
-Supersedes:
-
- `openspec/changes/add-artifact-regeneration-support` (in-repo, proposal-only stub) — same problem, replaced by this skill. Its hardcoded-filename dependency tracking and metadata-file staleness mechanism are dropped in favor of letting the agent read the artifacts.
-
-Delineated from adjacent commands (distinct surfaces — coordinate, don't collide):
-
- [#702](https://github.com/Fission-AI/OpenSpec/pull/702) `/opsx:clarify` — resolves ambiguity *within one artifact* via Q&A; a complementary upstream step. `/opsx:update` then reconciles the change's artifacts with each other.
- [#1251](https://github.com/Fission-AI/OpenSpec/pull/1251) `/opsx:review`, [#880](https://github.com/Fission-AI/OpenSpec/issues/880) — review the *implementation (code)* against the plan. `/opsx:update` is the mirror image: it keeps the *plan* coherent and never touches code.
- [#783](https://github.com/Fission-AI/OpenSpec/issues/783) — cross-artifact quality review. The skill's coherence pass is the lightweight form of this; a deterministic `validate`-side check is a separate proposal.
@@ -1,139 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Update Workflow Command
-
-The system SHALL provide a `/opsx:update` workflow skill that revises a change's existing planning artifacts in place. It SHALL NOT advance the build frontier (it does not create a not-yet-started artifact) and SHALL edit planning artifacts only, never implementation code.
-
-#### Scenario: Select the change to update
-
- **WHEN** the user invokes `/opsx:update` without a change name
- **THEN** the skill infers the change from conversation context if possible, or auto-selects the change when only one active change exists
- **AND** if it is still ambiguous, it lists available changes (most-recently-modified first) via `openspec list --json` and asks the user to choose
- **AND** it announces which change was selected and how to override
-
-#### Scenario: Revise without advancing the frontier
-
- **WHEN** the user asks `/opsx:update` to revise an existing artifact
- **THEN** the skill updates that artifact and reconciles the change's other existing artifacts with it
- **AND** it does NOT create any artifact that does not yet exist (that remains the job of `/opsx:continue`/`/opsx:propose`)
-
-#### Scenario: Missing artifacts are deferred to continue
-
- **WHEN** keeping the change coherent would require an artifact that has not been created yet
- **THEN** the skill revises only the artifacts that currently exist
- **AND** it notes the not-yet-created artifacts and points the user to `/opsx:continue` to create them
-
-#### Scenario: Update stays within the plan
-
- **WHEN** revising artifacts would imply changes to implementation code
- **THEN** the skill updates the planning artifacts only
- **AND** it directs the user to `/opsx:apply` to carry the revised plan into code, rather than editing code itself
-
-### Requirement: Schema-Driven Artifact Resolution
-
-The `/opsx:update` skill SHALL learn which artifacts exist and where they live by reading the change's status from the CLI, and SHALL NOT rely on hardcoded artifact names or assumed path separators. This makes the skill correct for custom schemas and on every platform, not only the default `spec-driven` schema.
-
-#### Scenario: Reads the artifact set from status
-
- **WHEN** the skill needs to know which artifacts a change has and where they are
- **THEN** it runs `openspec status --change <id> --json` and uses the reported artifact ids, statuses, and the `artifactPaths` map (`existingOutputPaths` for the files to edit)
- **AND** it does not assume the artifact ids or output paths
-
-#### Scenario: Does not branch on hardcoded artifact names
-
- **WHEN** the skill decides which artifacts to read and revise
- **THEN** its control flow uses the ids reported by the CLI
- **AND** it does not branch on literal `proposal`/`specs`/`design`/`tasks` names
-
-#### Scenario: Works for a custom schema
-
- **WHEN** the active change uses a custom schema whose artifact ids are not `proposal`/`specs`/`design`/`tasks`
- **THEN** the skill uses the artifact ids and paths reported by the CLI
- **AND** it works without any change to the skill
-
-#### Scenario: Resolve artifact paths cross-platform
-
- **WHEN** the skill reads or writes an artifact on macOS, Linux, or Windows
- **THEN** it uses the `existingOutputPaths` provided by the CLI status output
- **AND** it does not assume forward-slash separators
-
-#### Scenario: Edit the concrete files of a glob artifact
-
- **WHEN** an artifact's declared output path is a glob (for example `specs/**/*.md`)
- **THEN** the skill edits the concrete files reported in that artifact's `existingOutputPaths`
- **AND** it does not write to `resolvedOutputPath`, which for a glob artifact remains the glob pattern rather than a real file
-
-#### Scenario: A new file under a glob artifact is deferred to continue
-
- **WHEN** keeping the change coherent would require a new file under a glob artifact that does not exist yet (for example a spec for a not-yet-captured capability)
- **THEN** the skill revises only the files already present in `existingOutputPaths`
- **AND** it points the user to `/opsx:continue`/`/opsx:propose` to create the new file rather than inventing a path from the glob
-
-### Requirement: Bidirectional Coherence Review
-
-The `/opsx:update` skill SHALL keep a change's existing planning artifacts coherent with one another after a revision, reviewing affected artifacts in any direction rather than assuming a fixed downstream flow.
-
-#### Scenario: Reconcile related artifacts after an edit
-
- **WHEN** the user revises one artifact
- **THEN** the skill reviews the change's other existing artifacts against the revision
- **AND** it proposes follow-on edits to any artifact that is now inconsistent, whether that artifact is upstream or downstream of the edited one
-
-#### Scenario: Upstream artifact may be revised
-
- **WHEN** an edit to a later artifact (for example design) contradicts an earlier one (for example the proposal)
- **THEN** the skill may propose revising the earlier artifact to restore coherence
- **AND** it does not treat propagation as downstream-only
-
-#### Scenario: Coherence review with no specific edit
-
- **WHEN** the user invokes `/opsx:update` without a specific revision in mind ("make this change coherent")
- **THEN** the skill reads the change's existing artifacts and reviews them against each other for contradictions, gaps, and duplication
- **AND** it presents any findings for the user to confirm before editing
-
-#### Scenario: Coherent change yields no changes
-
- **WHEN** the skill finds the change's artifacts already coherent
- **THEN** it reports the change as coherent and makes no edits
-
-### Requirement: Next-Step Guidance
-
-After applying confirmed revisions (or finding none needed), the `/opsx:update` skill SHALL report where the change stands and recommend the next command, without acting on the recommendation itself.
-
-#### Scenario: Updating an already-implemented change
-
- **WHEN** the user updates a change whose implementation already happened (for example tasks are checked off or `/opsx:apply` was already run)
- **THEN** the skill still revises planning artifacts only
- **AND** it notes that the implementation may no longer match the revised plan and recommends `/opsx:apply` to carry the delta into code
- **AND** it does not implement anything itself
-
-#### Scenario: Next step when artifacts are incomplete
-
- **WHEN** the update finishes and the change still has not-yet-created artifacts
- **THEN** the skill recommends `/opsx:continue` to create them
-
-#### Scenario: Next step when the change is fully done
-
- **WHEN** the update finishes and the change's artifacts are complete and already implemented
- **THEN** the skill recommends `/opsx:archive`
-
-### Requirement: User-Confirmed Incremental Application
-
-The `/opsx:update` skill SHALL propose each artifact revision and apply it only after user confirmation.
-
-#### Scenario: Confirm before writing
-
- **WHEN** the skill has a proposed revision for an artifact
- **THEN** it shows the user what it intends to change and why before writing
- **AND** it writes only after the user confirms
-
-#### Scenario: Rejected revision is not written
-
- **WHEN** the user rejects a proposed revision for an artifact
- **THEN** the skill does not write that revision
- **AND** the artifact is left unchanged
-
-#### Scenario: Intent change is redirected to a new change
-
- **WHEN** the requested revision changes the intent of the change rather than refining it (per the "Update vs. Start Fresh" heuristic)
- **THEN** the skill recommends starting a new change (`/opsx:new`) instead of mutating the existing proposal into different work
@@ -1,30 +0,0 @@
-# Tasks: `/opsx:update` — a thin update skill
-
-> The whole feature is one new skill template over the existing `openspec status` / `openspec list` commands. No changes to the graph engine, the `status` command, or the metadata schema.
-
-## 1. The `/opsx:update` skill
-
- [x] 1.1 Create `src/core/templates/workflows/update-change.ts` with `getUpdateChangeSkillTemplate()` (skill) and `getOpsxUpdateCommandTemplate()` (command), mirroring `continue-change.ts`. The skill name is `openspec-update-change` — change-scoped, per the `openspec-<verb>-change` convention (see design, Naming).
- [x] 1.2 Instruction body (see design "The skill, written by hand"): resolve the change (infer / `openspec list --json` / ask) → `openspec status --change <id> --json` → read the relevant artifacts → apply the requested edit → reconcile the change's other existing artifacts in any direction → confirm and apply one artifact at a time → end with next-step guidance (`/opsx:continue` / `/opsx:apply` / `/opsx:archive` based on the change's state; see design Decision 6), never acting on it. Read artifact ids from the status JSON only, and write to `artifactPaths.<id>.existingOutputPaths` (never to a glob `resolvedOutputPath`).
- [x] 1.3 Encode the guardrails: (a) planning artifacts only — never edit code, hand off to `/opsx:apply`; (b) schema-driven — no branching on literal `proposal`/`specs`/`design`/`tasks`; ids/paths come from `openspec status`; (c) revise only existing files (`existingOutputPaths`) — defer not-yet-created artifacts, and new files under a glob artifact, to `/opsx:continue`; (d) intent change → recommend `/opsx:new` (the "Update vs. Start Fresh" heuristic in `docs/opsx.md`).
- [x] 1.4 Register the skill/command and add `update` to `ALL_WORKFLOWS` **and the default `core` profile** in `src/core/profiles.ts` (maintainer call: default install, not expanded-only).
-
-## 2. Docs & supersede the stub
-
- [x] 2.1 Add a `/opsx:update` row to the command table in `docs/opsx.md`, plus a short "Updating a change" usage note.
- [x] 2.2 Remove (or fold) `openspec/changes/add-artifact-regeneration-support/` so the tree has a single update proposal.
- [x] 2.3 Update any generated-skill manifests/fixtures that enumerate workflow skills so `openspec-update-change` is included.
-
-## 3. Tests
-
- [x] 3.1 Template generation snapshot for the skill and command templates.
- [x] 3.2 Assert the template's control flow contains NO hardcoded artifact-name branching (the anti-#777 guard): artifact ids must be read from `openspec status` JSON.
- [x] 3.3 Assert the template instructs planning-artifacts-only with a hand-off to `/opsx:apply` for code, and never advances the build frontier.
- [x] 3.4 Assert the template instructs writing to `existingOutputPaths` (the glob-expanded concrete files) and not to a glob `resolvedOutputPath`.
- [x] 3.5 Assert the template ends with next-step guidance (`/opsx:continue`/`/opsx:apply`/`/opsx:archive`) and instructs the agent never to act on it.
- [x] 3.6 Assert `update` is included in the `core` profile's workflows (profiles test).
-
-## 4. End-to-end verification
-
- [x] 4.1 `openspec validate add-update-workflow --strict` passes; `openspec status --change add-update-workflow` shows all artifacts complete.
- [x] 4.2 Manual walk-through: on a `spec-driven` change, edit `design`, run `/opsx:update`, confirm it proposes coherence edits to other existing artifacts (including upstream where warranted) and never touches code.
@@ -1,266 +0,0 @@
-## Product Shape
-
-`workspace open` should feel like opening a multi-root working set.
-
-The user model is:
-
-```text
-workspace setup = create the planning home and choose the default opener
-workspace links = the repos or folders OpenSpec can plan across
-workspace open = open that linked working set
--agent = use a different agent for this one session
--editor = open the working set as an editor workspace
-```
-
-Repo or folder visibility supports exploration and planning. Opening a workspace gives the agent or editor access to linked paths, and implementation starts through an explicit later workflow.
-
-## Command Surface
-
-Supported v1 forms:
-
-```bash
-openspec workspace open
-openspec workspace open platform
-openspec workspace open --agent codex
-openspec workspace open platform --agent github-copilot
-openspec workspace open --editor
-```
-
-The positional workspace name is the primary explicit selection surface for `open`. User-facing docs should prefer the positional form because a flag such as `--workspace <name>` repeats the noun.
-
-For consistency with other workspace commands and scripts, `workspace open` may also support `--workspace <name>` as an alias for the positional name:
-
-```bash
-openspec workspace open platform
-openspec workspace open --workspace platform
-```
-
-User-facing docs should prefer the positional form. If both are provided and they differ, OpenSpec should fail with a clear conflict error.
-
-`--prepare-only` should not be included. The POC used it to build and print launch surfaces without starting the external tool, but that does not map cleanly to a user-facing intent.
-
-`--json` should not be included in this slice. If a future integration needs a machine-readable resolved-open context, design that as a separate context/query surface instead of overloading the launching command.
-
-`--change` should be deferred. Change-scoped open depends on workspace change planning and target semantics that this slice should not invent.
-
-## Workspace Selection
-
-Selection should follow this order:
-
-1. If a positional workspace name is provided, open that known workspace.
-2. Otherwise, if the command runs from inside a workspace, open the current workspace.
-3. Otherwise, if exactly one workspace is known locally, open it.
-4. Otherwise, if multiple workspaces are known and the terminal is interactive, present a picker.
-5. Otherwise, fail with a clear message that names the known workspaces and asks the user to pass the workspace name.
-
-This keeps the common cases direct while still supporting global use.
-
-## Preferred Opener
-
-Workspace setup should ask which opener the user wants by default. The answer is machine-local state because different machines may have different installed agents or editors.
-
-`workspace open` uses the saved opener when no override is passed.
-
-`--agent <tool>` is a one-session override that leaves the saved preference unchanged. Persisting a changed default should require an explicit preference/config action in a later slice if users need it.
-
-This slice should not add global workspace opener config. OpenSpec already has a global config system, and workspace-level defaults can be added there later if repeated setup makes the local prompt feel noisy.
-
-The local preference should be shaped so a future global default can fit underneath it with smooth migration. The intended precedence is:
-
-```text
-command override
-  -> workspace-local preferred opener
-  -> future global workspace default opener
-  -> interactive prompt or built-in fallback
-```
-
-In future config terms, that global default might look like `workspace.defaultOpener`; this slice documents the precedence for later implementation.
-
-Store the preferred opener as a structured object in `.openspec-workspace/local.yaml`:
-
-```yaml
-preferred_opener:
-  kind: agent
-  id: codex
-```
-
-```yaml
-preferred_opener:
-  kind: editor
-  id: vscode
-```
-
-Allowed initial values:
-
-```text
-kind: agent, id: codex
-kind: agent, id: claude
-kind: agent, id: github-copilot
-kind: editor, id: vscode
-```
-
-The structure keeps the agent/editor distinction clear and leaves room for future opener variants without changing the local-state shape.
-
-Interactive setup should show all supported opener choices, but it should order detected/available openers first. Unavailable choices should still be visible with a note such as `not found on PATH`.
-
-Setup should prefer the plain editor option over an agent when a fallback default is needed for an interactive picker.
-
-Non-interactive setup stores a preferred opener when the caller explicitly passes an opener option. Otherwise, it leaves opener selection for a later interactive `workspace open` prompt or a non-interactive error that explains how to choose an opener.
-
-The setup-time flag should be:
-
-```bash
-openspec workspace setup --no-interactive --name platform --link /repo --opener codex
-openspec workspace setup --no-interactive --name platform --link /repo --opener editor
-```
-
-`--opener <id>` sets the stored preference. It is different from `workspace open --agent <id>` and `workspace open --editor`, which are one-session runtime overrides.
-
-Initial opener detection should stay simple and executable-based:
-
-```text
-VS Code editor: code
-Codex: codex
-Claude: claude
-GitHub Copilot in VS Code: code
-```
-
-Keep initial detection scoped to executable availability in this slice.
-
-Supported agent values for the initial open surface should be limited to tools with a real launch or attachment mechanism:
-
-```text
-claude
-codex
-github-copilot
-```
-
-Plain editor open should be represented by `--editor` with an explicit editor kind.
-
-For this slice, `--editor` means VS Code editor. The `.code-workspace` format is VS Code-specific, so prompts and errors should call this `VS Code editor` rather than implying generic editor support.
-
-`github-copilot` means the VS Code Copilot experience. It should open the maintained `.code-workspace` in VS Code because that is the product surface where this Copilot mode is available.
-
-If OpenSpec later supports a Copilot CLI agent, it should use a distinct value such as `github-copilot-cli` and launch the CLI agent directly. VS Code Copilot and a CLI agent have different opener mechanics, so they should remain distinct opener values.
-
-## Opener Availability
-
-`workspace open` should fail with a clear error when the selected opener is unavailable on the current machine.
-
-The selected opener remains required because it represents user intent, whether it came from local preference or a command-line override.
-
-Errors should name the missing executable or unavailable opener and suggest a concrete next step. For editor-based open, the error should include the `.code-workspace` path so the user can open it manually if needed.
-
-When no preferred opener is stored and no command-line override is provided, `workspace open` should prompt in interactive mode. In non-interactive mode, it should fail and tell the user to pass either an agent override or the editor option.
-
-## Editor Open
-
-`--editor` opens the workspace root plus every linked repo or folder with a valid local path.
-
-For VS Code-style editor support, OpenSpec should create and maintain a `.code-workspace` file as part of the workspace setup/link/relink lifecycle. `workspace open` should launch against existing workspace state.
-
-Expected local workspace shape:
-
-```text
-workspace-root/
-  changes/
-  <workspace-name>.code-workspace
-  .openspec-workspace/
-    workspace.yaml
-    local.yaml
-```
-
-The `.code-workspace` file should include the workspace root and each linked repo or folder with a valid local path. Because linked paths come from machine-local workspace state, OpenSpec-created workspaces should ignore the maintained `.code-workspace` file by default.
-
-The ignore rule should target the specific maintained file and leave other `*.code-workspace` files available for user-authored tracking:
-
-```text
-<workspace-name>.code-workspace
-```
-
-This lets teams add a separate user-authored portable `.code-workspace` later if they have a shared relative-path layout.
-
-`workspace setup`, `workspace link`, and `workspace relink` should all run the same open-surface sync after mutating workspace state. That sync owns:
-
- `AGENTS.md`
- `<workspace-name>.code-workspace`
- workspace ignore rules for machine-local files
-
-Even when a command only changes local state, such as `workspace relink`, it should refresh the full openable workspace surface so user-facing files do not drift.
-
-`--agent github-copilot` may use the same editor workspace mechanics, but it also needs Copilot prompt context. Plain `--editor` keeps a normal editor-workspace intent.
-
-`--agent github-copilot` should still open VS Code. The distinction from `--editor` is intent: `--editor` opens the workspace as a normal editor workspace, while `--agent github-copilot` opens the same editor workspace for the user to work with the VS Code Copilot agent experience.
-
-## Workspace Guidance
-
-Workspace setup should install stable guidance in the workspace root, preferably `AGENTS.md`.
-
-The guidance should explain durable workspace rules:
-
- the workspace root is the planning home
- `changes/` contains workspace-level planning
- linked repos and folders are available for exploration and planning
- visibility supports exploration and planning
- implementation edits start after the user explicitly asks for implementation work
-
-The managed `AGENTS.md` text should stay short and durable, covering stable workspace guidance while runtime details remain discoverable from workspace state. A starting shape:
-
-```markdown
-# OpenSpec Workspace Guidance
-
-This directory is an OpenSpec workspace for planning across linked repos or folders.
-
- Use `changes/` for workspace-level planning.
- Linked repos and folders are available for exploration and planning.
- Repo or folder visibility supports exploration and planning.
- Make implementation edits after the user explicitly asks for implementation work.
- Treat linked repos and folders as the implementation homes for their owned code.
- Use OpenSpec workspace commands instead of hand-editing `.openspec-workspace/*.yaml`.
-```
-
-`workspace open` is a launching feature. It should launch the selected opener against existing workspace files.
-
-For Claude and Codex, `workspace open` may still need to pass workspace and linked directory arguments to the agent process at launch because those tools do not consume `.code-workspace` directly. If an opener requires an initial prompt argument, it should be minimal, such as `Open this OpenSpec workspace.`
-
-Dynamic workspace facts should normally be discoverable from existing files:
-
- linked paths: `.openspec-workspace/local.yaml`
- stable link names: `.openspec-workspace/workspace.yaml`
- active workspace changes: `changes/`
- editor working set: `<workspace-name>.code-workspace`
-
-Report a command file or prompt file path only when the file is actually written and used.
-
-OpenSpec should own a marked workspace-guidance block inside `AGENTS.md`:
-
-```markdown
-<!-- OPENSPEC:WORKSPACE-GUIDANCE:START -->
-# OpenSpec Workspace Guidance
-
-...
-<!-- OPENSPEC:WORKSPACE-GUIDANCE:END -->
-```
-
-`workspace setup`, `workspace link`, and `workspace relink` may rewrite that marked block during open-surface sync. Content outside the marked block should be preserved so users can keep their own workspace notes in the same file.
-
-If `AGENTS.md` is missing, OpenSpec should recreate it. If `AGENTS.md` exists and the markers are absent, OpenSpec should append the managed block while preserving existing content.
-
-## Linked Paths
-
-Root workspace open should attach every linked repo or folder with a valid local path.
-
-Broken links are skipped during workspace open. OpenSpec should surface clear status in human output, with `openspec workspace doctor` as the repair path.
-
-Links with repo-local `openspec/` state absent remain valid for workspace open. Missing repo-local OpenSpec state can matter later for implementation readiness while still allowing visibility for exploration and planning.
-
-## Safety Boundary
-
-The opening prompt or editor guidance should say:
-
-```text
-Linked repos and folders are visible for exploration and planning.
-Make implementation edits after the user explicitly asks for implementation work.
-```
-
-Prompt guidance is acceptable for this slice because apply/verify/archive sit outside the open surface. Later implementation workflows should enforce mode and scope through explicit context providers as well as prompt wording.
@@ -1,65 +0,0 @@
-## Why
-
-After a user creates a workspace and links repos or folders, they need to open that workspace with their preferred agent or editor and have the working set available immediately.
-
-The workspace should provide repo and folder locations, link names, and the context that distinguishes planning from implementation.
-
-## What Changes
-
-Add the workspace-open experience:
-
-```text
-Open this workspace.
-Use my preferred opener by default and honor explicit opener overrides.
-The opener sees the workspace location, linked repos or folders, current changes, and relevant instructions.
-```
-
-Links are the planning context. The local registry serves as a workspace-discovery index for finding known workspaces on the current machine.
-
-Expected user surface:
-
-```bash
-openspec workspace open
-openspec workspace open platform
-openspec workspace open --agent codex
-openspec workspace open platform --agent github-copilot
-openspec workspace open --editor
-```
-
-`workspace open` should open the current workspace when run from inside one, auto-select the only known workspace when run outside a workspace, and present an interactive picker when multiple known workspaces are available. Users can pass a workspace name as the positional argument when they want to choose explicitly.
-
-Workspace setup should ask for and store a preferred opener in machine-local workspace state. `workspace open` uses that preference by default. `--agent <tool>` is a one-session override that leaves the saved preference unchanged.
-
-`--editor` opens the workspace as an editor workspace. This is related to, but distinct from, `--agent github-copilot`: GitHub Copilot needs editor workspace support plus agent prompt context, while plain editor open should focus on opening the linked working set.
-
-Workspace guidance should live in durable workspace files where possible:
-
- stable behavior belongs in workspace-level `AGENTS.md`
- opener-specific launch prompts stay minimal when required
- linked repos or folders are visible for exploration and planning before a change exists
-
-This slice supports root workspace launching through the documented opener forms. Public preview (`--prepare-only`) and machine-readable context (`--json`) surfaces belong in a future context/query design if a clear user need appears.
-
-This slice focuses on root workspace open behavior. Change-scoped sessions need the target model from workspace change planning before they can be specified cleanly.
-
-Planning dependency:
-
- Depends on `workspace-create-and-register-repos`.
-
-## Capabilities
-
-### New Capabilities
-
- `workspace-open`: Opens a workspace through a preferred agent or VS Code editor with linked repos or folders available for exploration and planning.
-
-### Modified Capabilities
-
- `workspace-foundation`: Extends machine-local workspace state and setup/link/relink behavior with a preferred opener and maintained openable workspace surface.
-
-## Impact
-
- `openspec workspace open`
- Workspace setup preferred opener prompt and local preference storage.
- Workspace prompt, editor workspace, and agent-launch context.
- Generated or committed agent guidance for workspace mode.
- Tests for opening inside a workspace, auto-selecting one known workspace, picking among multiple known workspaces, opening by workspace name, one-session agent overrides, and editor open.
@@ -1,76 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace Preferred Opener State
-OpenSpec SHALL store a workspace's preferred opener in machine-local workspace state when the user explicitly chooses one.
-
-#### Scenario: Recording an interactive setup opener choice
- **WHEN** an interactive user chooses a preferred opener during `openspec workspace setup`
- **THEN** OpenSpec SHALL record the opener in `.openspec-workspace/local.yaml`
- **AND** the stored value SHALL use a structured `preferred_opener` object with `kind` and `id`
-
-#### Scenario: Recording a non-interactive setup opener choice
- **WHEN** a non-interactive user runs `openspec workspace setup --no-interactive --opener codex`
- **THEN** OpenSpec SHALL record `preferred_opener.kind` as `agent`
- **AND** it SHALL record `preferred_opener.id` as `codex`
-
-#### Scenario: Leaving opener unset during non-interactive setup
- **WHEN** a non-interactive user runs `openspec workspace setup --no-interactive` with opener selection omitted
- **THEN** OpenSpec SHALL leave the workspace preferred opener unset
- **AND** the unset state SHALL allow `workspace open` to prompt later
-
-#### Scenario: Supported preferred opener values
- **WHEN** OpenSpec accepts a preferred opener value
- **THEN** it SHALL accept `codex`, `claude`, `github-copilot`, and `editor`
- **AND** it SHALL map `editor` to `kind: editor` and `id: vscode`
- **AND** it SHALL map agent values to `kind: agent` and the matching agent `id`
-
-#### Scenario: Ordering setup opener choices
- **WHEN** interactive setup displays opener choices
- **THEN** OpenSpec SHALL show all supported openers
- **AND** it SHALL order openers with detected executables before unavailable openers
- **AND** unavailable openers SHALL remain visible with an availability note
-
-### Requirement: Maintained Workspace Open Surface
-OpenSpec SHALL maintain files that make a workspace directly openable after setup and link changes.
-
-#### Scenario: Creating the open surface during setup
- **WHEN** `openspec workspace setup` creates a workspace
- **THEN** OpenSpec SHALL create or refresh `AGENTS.md`
- **AND** it SHALL create or refresh `<workspace-name>.code-workspace`
- **AND** it SHALL create or refresh workspace ignore rules for machine-local open files
-
-#### Scenario: Refreshing the open surface after linking
- **WHEN** `openspec workspace link` succeeds
- **THEN** OpenSpec SHALL refresh `AGENTS.md`
- **AND** it SHALL refresh `<workspace-name>.code-workspace`
- **AND** it SHALL refresh workspace ignore rules for machine-local open files
-
-#### Scenario: Refreshing the open surface after relinking
- **WHEN** `openspec workspace relink` succeeds
- **THEN** OpenSpec SHALL refresh `AGENTS.md`
- **AND** it SHALL refresh `<workspace-name>.code-workspace`
- **AND** it SHALL refresh workspace ignore rules for machine-local open files
-
-#### Scenario: Building the VS Code workspace file
- **WHEN** OpenSpec refreshes `<workspace-name>.code-workspace`
- **THEN** the file SHALL include the workspace root
- **AND** the workspace root folder entry SHALL use the root path without a synthetic display name
- **AND** it SHALL include every linked repo or folder with a valid local path
- **AND** it SHALL omit linked repos or folders whose local paths are missing or invalid
-
-#### Scenario: Ignoring the maintained VS Code workspace file
- **WHEN** OpenSpec refreshes workspace ignore rules
- **THEN** it SHALL ignore the specific maintained `<workspace-name>.code-workspace` file
- **AND** user-authored `*.code-workspace` files SHALL remain eligible for tracking
-
-#### Scenario: Preserving user-authored AGENTS content
- **GIVEN** `AGENTS.md` contains content outside the OpenSpec workspace guidance markers
- **WHEN** OpenSpec refreshes workspace guidance
- **THEN** it SHALL replace only the marked OpenSpec workspace guidance block
- **AND** it SHALL preserve content outside the markers
-
-#### Scenario: Appending AGENTS guidance when markers are missing
- **GIVEN** `AGENTS.md` exists and OpenSpec workspace guidance markers are absent
- **WHEN** OpenSpec refreshes workspace guidance
- **THEN** it SHALL append the marked OpenSpec workspace guidance block
- **AND** it SHALL preserve the existing file content
@@ -1,199 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace Open Command
-OpenSpec SHALL provide a `workspace open` command that opens an OpenSpec workspace working set through an agent or VS Code editor.
-
-#### Scenario: Opening the current workspace
- **GIVEN** the command runs from inside an OpenSpec workspace
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL open that current workspace
- **AND** it SHALL use the selected opener for that workspace
-
-#### Scenario: Opening a named workspace
- **GIVEN** a workspace named `platform` is known locally
- **WHEN** the user runs `openspec workspace open platform`
- **THEN** OpenSpec SHALL open the `platform` workspace
-
-#### Scenario: Opening a named workspace with the selection flag
- **GIVEN** a workspace named `platform` is known locally
- **WHEN** the user runs `openspec workspace open --workspace platform`
- **THEN** OpenSpec SHALL open the `platform` workspace
-
-#### Scenario: Conflicting workspace selectors
- **GIVEN** workspaces named `platform` and `checkout` are known locally
- **WHEN** the user runs `openspec workspace open platform --workspace checkout`
- **THEN** OpenSpec SHALL fail with a clear conflict error
- **AND** the error SHALL name both conflicting selectors
-
-#### Scenario: Handling unsupported preview and JSON flags
- **WHEN** the user runs `openspec workspace open` with `--prepare-only` or `--json`
- **THEN** OpenSpec SHALL fail with a clear error that the root workspace open surface supports launching through a selected opener
- **AND** the error SHALL direct preview or machine-readable context needs to a future context/query surface
-
-#### Scenario: Handling change-scoped open before workspace planning
- **WHEN** the user runs `openspec workspace open --change <id>`
- **THEN** OpenSpec SHALL fail with a clear error that this slice supports root workspace open
- **AND** the error SHALL direct change-scoped open behavior to future workspace change planning
-
-### Requirement: Workspace Selection For Open
-OpenSpec SHALL resolve the workspace to open using current workspace context, local registry state, and interactive selection.
-
-#### Scenario: Current workspace wins
- **GIVEN** the command runs from a workspace folder or one of its subdirectories
- **AND** no workspace name is provided
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL open the current workspace
-
-#### Scenario: Auto-selecting the only known workspace
- **GIVEN** the command runs outside a workspace
- **AND** exactly one workspace is known locally
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL open that known workspace directly
-
-#### Scenario: Picking from multiple workspaces
- **GIVEN** the command runs outside a workspace
- **AND** multiple workspaces are known locally
- **AND** the terminal is interactive
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL present a picker with workspace names and locations
- **AND** it SHALL open the workspace the user selects
-
-#### Scenario: Non-interactive ambiguous selection
- **GIVEN** the command runs outside a workspace
- **AND** multiple workspaces are known locally
- **AND** the terminal is non-interactive
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL fail with a clear message listing the known workspace names
- **AND** it SHALL ask the user to pass a workspace name
-
-#### Scenario: No known workspace
- **GIVEN** the command runs outside a workspace
- **AND** no workspaces are known locally
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL fail with a clear message
- **AND** it SHALL suggest running `openspec workspace setup`
-
-### Requirement: Opener Resolution
-OpenSpec SHALL resolve the opener from command overrides, workspace-local preference, or an interactive prompt.
-
-#### Scenario: Conflicting opener overrides
- **WHEN** the user runs `openspec workspace open --agent codex --editor`
- **THEN** OpenSpec SHALL fail with a clear conflict error naming `--agent` and `--editor`
- **AND** it SHALL avoid launching any opener
- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Using the stored preferred opener
- **GIVEN** the workspace has a machine-local preferred opener
- **WHEN** the user runs `openspec workspace open` using default opener resolution
- **THEN** OpenSpec SHALL use the stored preferred opener
-
-#### Scenario: Overriding with an agent for one session
- **GIVEN** the workspace has a stored preferred opener
- **WHEN** the user runs `openspec workspace open --agent codex`
- **THEN** OpenSpec SHALL use Codex for that open command
- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Overriding with VS Code editor for one session
- **GIVEN** the workspace has a stored preferred opener
- **WHEN** the user runs `openspec workspace open --editor`
- **THEN** OpenSpec SHALL open the workspace in VS Code editor mode
- **AND** it SHALL leave the stored preferred opener unchanged
-
-#### Scenario: Prompting when no opener is stored
- **GIVEN** the workspace has no stored preferred opener
- **AND** the terminal is interactive
- **WHEN** the user runs `openspec workspace open` using default opener resolution
- **THEN** OpenSpec SHALL prompt the user to choose an opener
- **AND** it SHALL only offer openers with detected executables
-
-#### Scenario: Failing when no opener can be prompted
- **GIVEN** the workspace has no stored preferred opener
- **AND** the terminal is interactive
- **AND** no supported opener executable is available on `PATH`
- **WHEN** the user runs `openspec workspace open` using default opener resolution
- **THEN** OpenSpec SHALL fail with a clear message that no supported opener is available
- **AND** it SHALL avoid prompting with unlaunchable choices
-
-#### Scenario: Failing when no opener is stored in non-interactive mode
- **GIVEN** the workspace has no stored preferred opener
- **AND** the terminal is non-interactive
- **WHEN** the user runs `openspec workspace open` using default opener resolution
- **THEN** OpenSpec SHALL fail with a clear message
- **AND** it SHALL ask the user to pass `--agent <tool>` or `--editor`
-
-### Requirement: Opener Launch Behavior
-OpenSpec SHALL launch the selected opener using existing workspace files and linked path state.
-
-#### Scenario: Opening VS Code editor
- **GIVEN** the user selected the VS Code editor opener
- **WHEN** `code` is available on `PATH`
- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
-
-#### Scenario: Opening GitHub Copilot in VS Code
- **GIVEN** the user selected `--agent github-copilot`
- **WHEN** `code` is available on `PATH`
- **THEN** OpenSpec SHALL open the workspace's maintained `.code-workspace` file with VS Code
- **AND** it SHALL treat this as the VS Code Copilot experience
-
-#### Scenario: Opening Codex
- **GIVEN** the user selected `--agent codex`
- **WHEN** `codex` is available on `PATH`
- **THEN** OpenSpec SHALL launch Codex from the workspace root
- **AND** it SHALL attach every linked repo or folder with a valid local path using Codex's supported directory attachment mechanism
-
-#### Scenario: Opening Claude
- **GIVEN** the user selected `--agent claude`
- **WHEN** `claude` is available on `PATH`
- **THEN** OpenSpec SHALL launch Claude from the workspace root
- **AND** it SHALL attach every linked repo or folder with a valid local path using Claude's supported directory attachment mechanism
-
-#### Scenario: Missing opener executable
- **GIVEN** the selected opener requires an executable that is not available on `PATH`
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL fail with a clear error naming the missing executable
- **AND** it SHALL keep the selected opener as the required opener
-
-#### Scenario: Missing VS Code executable
- **GIVEN** the selected opener is VS Code editor or GitHub Copilot in VS Code
- **AND** `code` is not available on `PATH`
- **WHEN** the user runs `openspec workspace open`
- **THEN** OpenSpec SHALL fail with a clear error naming `code`
- **AND** it SHALL include the maintained `.code-workspace` path so the user can open it manually
-
-### Requirement: Linked Working Set Visibility
-OpenSpec SHALL make linked repos and folders visible for workspace exploration and planning before change creation.
-
-#### Scenario: Attaching valid linked paths
- **GIVEN** a workspace has linked repos or folders with valid local paths
- **WHEN** the user opens the workspace through an opener that supports linked directory attachment
- **THEN** OpenSpec SHALL include every valid linked path in the opened working set
- **AND** it SHALL support opening before a workspace change exists
-
-#### Scenario: Skipping broken linked paths
- **GIVEN** a workspace has at least one linked path that is missing or not recorded locally
- **WHEN** the user opens the workspace
- **THEN** OpenSpec SHALL skip the broken linked path
- **AND** it SHALL report that the path was skipped with `openspec workspace doctor` as the repair path
- **AND** it SHALL continue opening the workspace when the selected opener itself is available
-
-#### Scenario: Opening links with repo-local OpenSpec state absent
- **GIVEN** a linked repo or folder has a valid local path and repo-local `openspec/` state is absent
- **WHEN** the user opens the workspace
- **THEN** OpenSpec SHALL include that link when its local path is valid
- **AND** it SHALL treat missing repo-local OpenSpec state as an implementation-readiness concern for later workflows while continuing open
-
-### Requirement: Workspace Open Guidance
-OpenSpec SHALL use durable workspace guidance as the primary context source for root workspace open.
-
-#### Scenario: Launching with existing workspace guidance
- **GIVEN** the workspace has OpenSpec-managed guidance in `AGENTS.md`
- **WHEN** the user opens the workspace
- **THEN** OpenSpec SHALL refresh the maintained `.code-workspace` from current linked path state
- **AND** it SHALL launch the selected opener against refreshed workspace files
- **AND** it SHALL use durable workspace files as the primary workspace-open artifact
-
-#### Scenario: Minimal required launch prompt
- **GIVEN** an opener requires an initial prompt argument
- **WHEN** OpenSpec launches that opener
- **THEN** OpenSpec SHALL use a minimal prompt such as `Open this OpenSpec workspace.`
- **AND** durable workspace rules SHALL remain in workspace files
@@ -1,89 +0,0 @@
-## 1. Preferred Opener State
-
- [x] 1.1 Add structured `preferred_opener` support to workspace local state parsing and serialization
- [x] 1.2 Support backward-compatible parsing for existing local workspace files while adding `preferred_opener`
- [x] 1.3 Validate supported opener values: `codex`, `claude`, `github-copilot`, and `editor`
- [x] 1.4 Map `editor` to `kind: editor, id: vscode`
- [x] 1.5 Map agent opener values to `kind: agent` with the matching `id`
- [x] 1.6 Add simple executable detection for `code`, `codex`, and `claude`
- [x] 1.7 Add unit tests for preferred opener parsing, serialization, and invalid opener values
-
-## 2. Setup Opener Selection
-
- [x] 2.1 Add interactive setup prompt for the preferred opener
- [x] 2.2 Show all supported opener choices with detected openers ordered first
- [x] 2.3 Mark unavailable opener choices with a clear availability note
- [x] 2.4 Prefer the plain editor option for setup fallback selection when a fallback is needed
- [x] 2.5 Add `workspace setup --opener <id>` for non-interactive setup
- [x] 2.6 Store a preferred opener during non-interactive setup when `--opener` is provided
- [x] 2.7 Add tests for interactive opener selection and non-interactive `--opener`
- [x] 2.8 Add tests that non-interactive setup with omitted `--opener` leaves opener unset
-
-## 3. Open Surface Sync
-
- [x] 3.1 Add a shared open-surface sync helper used by setup, link, and relink
- [x] 3.2 Create or refresh root `AGENTS.md` with an OpenSpec-managed workspace guidance block
- [x] 3.3 Preserve user-authored `AGENTS.md` content outside the managed block
- [x] 3.4 Append the managed block to unmarked existing `AGENTS.md` files
- [x] 3.5 Create or refresh `<workspace-name>.code-workspace` at the workspace root
- [x] 3.6 Include the workspace root and every linked repo or folder with a valid local path in the `.code-workspace`
- [x] 3.7 Omit linked repos or folders with missing or invalid local paths from the `.code-workspace`
- [x] 3.8 Refresh `.gitignore` with the specific maintained `<workspace-name>.code-workspace` entry
- [x] 3.9 Scope ignore updates to the maintained `<workspace-name>.code-workspace` file
- [x] 3.10 Add cross-platform tests for `.code-workspace` path construction and Windows-style paths where practical
-
-## 4. Workspace Open Selection
-
- [x] 4.1 Add `openspec workspace open [name]`
- [x] 4.2 Support `openspec workspace open --workspace <name>` as an alias for the positional name
- [x] 4.3 Fail clearly when positional name and `--workspace` are both provided with different values
- [x] 4.4 Open the current workspace when run from a workspace folder or subdirectory
- [x] 4.5 Auto-select the only known workspace when run outside a workspace
- [x] 4.6 Present an interactive picker when multiple workspaces are known
- [x] 4.7 Report ambiguous workspace selection in non-interactive mode and list known workspace names
- [x] 4.8 Report unresolved workspace selection clearly and suggest `openspec workspace setup`
- [x] 4.9 Handle unsupported `--prepare-only`, `--json`, and `--change` flags with clear errors
- [x] 4.10 Add command integration tests for selection, conflict, unsupported flags, and no-workspace cases
-
-## 5. Opener Resolution
-
- [x] 5.1 Resolve command-line opener overrides before workspace-local preferences
- [x] 5.2 Implement `workspace open --agent codex`
- [x] 5.3 Implement `workspace open --agent claude`
- [x] 5.4 Implement `workspace open --agent github-copilot`
- [x] 5.5 Implement `workspace open --editor`
- [x] 5.6 Keep the stored preferred opener unchanged for `--agent` and `--editor` overrides
- [x] 5.7 Prompt interactively to choose an opener when the opener preference is unset
- [x] 5.8 Report unset opener preference in non-interactive mode with override guidance
- [x] 5.9 Add tests for opener precedence, prompting, non-interactive failure, and unchanged preference behavior
-
-## 6. Opener Launchers
-
- [x] 6.1 Launch VS Code editor by opening the maintained `.code-workspace` file with `code`
- [x] 6.2 Launch GitHub Copilot by opening the maintained `.code-workspace` file with VS Code
- [x] 6.3 Launch Codex from the workspace root with valid linked paths attached
- [x] 6.4 Launch Claude from the workspace root with valid linked paths attached
- [x] 6.5 Use a minimal launch prompt when an agent CLI requires an initial prompt argument
- [x] 6.6 Report skipped broken links with `openspec workspace doctor` as the repair path
- [x] 6.7 Fail clearly when the selected opener executable is unavailable
- [x] 6.8 Include the `.code-workspace` path in VS Code opener availability errors
- [x] 6.9 Keep the selected opener as required when launching
- [x] 6.10 Add unit tests for launcher command construction using test doubles for external tools
-
-## 7. Documentation And Command Metadata
-
- [x] 7.1 Update workspace command help for setup `--opener`, open positional name, `--workspace`, `--agent`, and `--editor`
- [x] 7.2 Update command registry and shell completion metadata for the new workspace open surface
- [x] 7.3 Update workspace documentation to describe preferred openers, editor open, agent open, and `.code-workspace` behavior
- [x] 7.4 Document that `.code-workspace` is machine-local and ignored by default
- [x] 7.5 Document that root workspace open supports exploration and planning, with implementation started by explicit user request
-
-## 8. Verification
-
- [x] 8.1 Run `node bin/openspec.js validate workspace-open-agent-context --strict`
- [x] 8.2 Run targeted workspace command tests
- [x] 8.3 Run targeted workspace foundation tests
- [x] 8.4 Run command-generation or launcher tests that cover Codex, Claude, GitHub Copilot, and VS Code editor paths
- [x] 8.5 Run cross-platform path-focused tests for workspace open surfaces
- [x] 8.6 Run the relevant TypeScript test suite
- [x] 8.7 Run `pnpm run build`
@@ -1,242 +0,0 @@
-## Context
-
-Workspace setup already creates a planning home, records linked repos or folders, stores a preferred opener, and maintains the root open surface. For workspace change planning to work in practice, the opened agent also needs OpenSpec workflow skills available from that workspace root.
-
-Repo-local `openspec init` and `openspec update` already provide the user model for choosing agent surfaces and generating skills. Workspace setup should feel similar, but the installation target is the workspace root rather than any linked repo or folder.
-
-The existing artifact workflow assumes a change lives under a repo-local `openspec/changes/<id>` path. Workspace planning needs the same workflow vocabulary, but the planning home may be a workspace root and the implementation homes may be linked repos or folders.
-
-## Goals / Non-Goals
-
-**Goals:**
- Install OpenSpec agent skills into the workspace root during workspace setup.
- Use the active global profile to select which workflow skills are installed in the workspace.
- Let users choose which agents receive skills with familiar `--tools` semantics.
- Persist workspace-local agent skill selection so update can refresh the same agents later.
- Let users refresh, add, or remove workspace-local skills later through `workspace update`.
- Detect and report workspace-local skill drift from the active global profile.
- Let `openspec config profile` offer to apply changed profile settings to the current workspace when run from inside a workspace.
- Redirect workspace users from repo-local `openspec update` to `openspec workspace update`.
- Add a built-in workspace planning schema for workspace-scoped changes.
- Create workspace changes under the workspace planning path.
- Represent affected areas without forcing implementation artifacts into linked repos.
- Give agents machine-readable planning context through status/instructions output.
- Preserve the workspace boundary: linked repos and folders remain untouched during setup/update.
-
-**Non-Goals:**
- Generating slash commands as part of workspace setup.
- Honoring global `delivery: commands` by generating workspace command files.
- Installing skills into linked repos or folders.
- Adding workspace-local workflow profiles separate from global config.
- Solving workspace-scoped artifact path discovery in the first setup-skill step.
- Adding a separate artifact-context CLI command in the first version.
- Implementing workspace apply, verify, or archive semantics end to end.
- Changing repo-local `openspec init` or `openspec update` behavior.
-
-## Decisions
-
-### Use agent-skill language in workspace UX
-
-Workspace setup should ask, "Which agents should get OpenSpec skills in this workspace?" rather than using the broader "AI tools" wording. The user-visible action is installing skills for coding agents, and the target is the workspace planning home.
-
-Alternative considered: reuse the exact `init` wording. That would be familiar, but it hides the important distinction between opening a workspace and installing skills into it.
-
-### Reuse the existing tool id model
-
-The CLI should use the existing `--tools all|none|<ids>` grammar for non-interactive setup and update. Reusing the existing tool IDs avoids inventing a second naming system for the same configured agents.
-
-Alternative considered: add `--agents`. That reads better in isolation, but it creates unnecessary parallel vocabulary next to `openspec init --tools`.
-
-### Let profile choose workflows and tools choose agents
-
-Workspace setup/update should use the active global profile to decide which OpenSpec workflow skills are installed. The profile answers "which actions are available?" while `--tools` answers "which agents get those actions?" Keeping those concerns separate preserves the existing profile model and avoids adding workspace-local workflow selection in this slice.
-
-If global profile is `core`, workspace skills should include the core workflow set. If global profile is `custom`, workspace skills should include only the configured custom workflows. `--tools none` should still mean no agent skills are installed, regardless of profile.
-
-Alternative considered: add a workspace-local profile file. That might be useful later for team-shared workspace defaults, but this slice already stores machine-local agent paths and should avoid introducing another config authority before the global profile behavior works.
-
-### Preselect the preferred opener when possible
-
-Interactive setup should preselect the preferred opener when that opener maps to a skill-capable agent. The user can accept the default, add more agents, or deselect it.
-
-Alternative considered: install skills only for the preferred opener. That is simpler, but opener choice means "how should I open this workspace" while skill selection means "which agents should understand OpenSpec here."
-
-### Persist selected workspace skill agents locally
-
-Workspace setup should store the selected skill-capable agents in `.openspec-workspace/local.yaml` because agent paths and installed tool surfaces are machine-local. Workspace update should use that stored selection when the user does not pass `--tools` or make a new interactive selection.
-
-Explicit `--tools` on workspace setup/update should replace the stored selection. `--tools none` should store an empty selection and remove only known OpenSpec-managed workspace skill directories.
-
-The local state should also record enough last-applied information to support drift detection, such as the workflow IDs installed for each selected agent and the effective global profile/delivery at the time of the last successful sync. This is diagnostic state, not a second source of truth.
-
-Alternative considered: infer selected agents by scanning `.codex/skills/`, `.claude/skills/`, and similar directories. Scanning is useful as a fallback, but persisted selection gives predictable update behavior and avoids treating unrelated user-authored files as OpenSpec-managed state.
-
-### Keep non-interactive setup backward-compatible
-
-`openspec workspace setup --no-interactive` should not require `--tools`. If `--tools` is omitted, setup should create the workspace and skip skill installation, preserving existing scripted workspace setup behavior. Human and JSON output should say that no workspace skills were installed and that `openspec workspace update --tools <ids>` can add them later.
-
-`openspec workspace update --no-interactive` without `--tools` should refresh the stored workspace skill agent selection. If no selection is stored, it should complete without installing skills and report a clear no-op with guidance to pass `--tools`.
-
-Alternative considered: require `--tools` whenever workspace setup/update is non-interactive. That mirrors repo-local init, but it would break existing workspace setup scripts that predate workspace-local skill installation.
-
-### Generate workspace-local skills only
-
-Workspace setup/update should generate skills under the workspace root, such as `.codex/skills/` or `.claude/skills/`. It should not generate slash commands in this slice because some command adapters resolve to global locations, and workspace setup should remain local and predictable.
-
-When global delivery is `commands` or `both`, workspace setup/update should still generate only skills and report that workspace command generation is not part of this slice. This keeps profile workflow selection useful without making workspace setup perform global or repo-local command writes.
-
-Alternative considered: mirror `init` exactly and generate both skills and commands. That risks surprising global writes and makes the setup boundary harder to explain.
-
-### Add `workspace update` for skill refresh
-
-`openspec workspace update` should refresh, add, or remove workspace-local OpenSpec skills after setup. It should resolve the current workspace when run from inside a workspace, and also support named and non-interactive forms.
-
-Workspace update should compare the active global profile's workflow selection with the last applied workspace skill state. If they differ, update should add/remove only OpenSpec-managed workflow skill directories for the selected agents. Workspace doctor/list/status surfaces may report the drift as a warning, and `openspec config profile` no-op inside a workspace should use the same drift check for guidance.
-
-Alternative considered: reuse `openspec update` from inside the workspace. That command currently means repo/project update, while workspace update needs workspace selection, workspace JSON/status behavior, and linked-repo safety rules.
-
-### Make `config profile` workspace-aware
-
-`openspec config profile` should remain a global configuration command. When it runs inside a repo-local OpenSpec project and the user chooses to apply changes, it should continue to run `openspec update`.
-
-When it runs inside an OpenSpec workspace and the profile or delivery settings actually change, it should prompt to apply changes to the current workspace. If confirmed, it should run `openspec workspace update` for that workspace. If declined, it should explain that the global config changed and the user can run `openspec workspace update` later.
-
-The preset shortcut `openspec config profile core` should keep its non-interactive character and not launch an apply prompt. When run from inside a workspace, it should save global config and print workspace-specific follow-up guidance to run `openspec workspace update`. When run inside a repo-local project, it should keep the existing repo-local guidance.
-
-For this slice, automatic workspace context should come from the workspace planning home and its own subdirectories. Running a command from inside a linked repo or folder should keep that location's repo-local behavior unless the user explicitly selects the workspace with a workspace command option. This avoids surprising repo-local commands merely because the repo is registered as a workspace link.
-
-If a directory is both inside a workspace planning home and inside a repo-local OpenSpec project, the nearest planning home should determine the apply prompt. This avoids applying a workspace profile change to a linked repo when the user is intentionally operating from the workspace planning home.
-
-Alternative considered: make `openspec config profile` update all known workspaces. That would be convenient in small setups, but global config changes should not fan out into multiple planning homes without an explicit per-workspace action.
-
-### Resolve a planning home before acting
-
-Workflow commands should resolve whether the current change belongs to a repo-local planning home or a workspace planning home before computing paths. The resolver should identify the planning root, change root, linked areas when present, and whether implementation edits are allowed. Linked repos are not implicitly treated as workspace planning homes just because they are registered in a workspace; workspace-scoped behavior is selected from the workspace planning home or through explicit workspace selection.
-
-Alternative considered: add workspace-specific command branches wherever paths are used. That would make the workspace model leak into every workflow and make generated skills more fragile.
-
-### Store workspace changes in the workspace planning path
-
-Workspace changes should live under the workspace planning path, initially `changes/<id>` at the workspace root. Creating the workspace change should capture shared intent once and may record affected areas, but it should not create repo-local `openspec/changes/<id>` directories in linked repos.
-
-Alternative considered: materialize a repo-local change in every affected repo during workspace change creation. That was easy to reason about in the POC, but it commits too early and makes exploration look like implementation.
-
-### Add a workspace planning schema
-
-Workspace-scoped changes should use a built-in `workspace-planning` schema by default. This keeps the workflow verbs familiar while letting workspace changes have a structure that fits cross-area planning.
-
-Initial artifact shape:
-
-```text
-changes/<id>/
-  .openspec.yaml          # schema: workspace-planning
-  proposal.md             # shared goal and scope
-  design.md               # cross-area decisions
-  tasks.md                # coordination tasks, optionally grouped by affected area
-  specs/
-    <area-or-repo>/
-      <capability>/spec.md
-```
-
-The first schema should stay intentionally close to the normal OpenSpec artifact shape: proposal, specs, design, and tasks. Area-specific requirements live under `specs/` and area-specific work can be represented as sections in `tasks.md`. This slice does not introduce another area manifest beside those normal planning artifacts.
-
-Alternative considered: reuse `spec-driven` unchanged and make all workspace differences implicit in status output. That hides the fact that workspace planning needs different instructions for organizing requirements and tasks by affected area.
-
-Alternative considered: create separate workspace workflow skills instead of a schema. That would duplicate workflow guidance and make workspace mode feel like a different product.
-
-### Support nested workspace spec paths in the schema
-
-The `workspace-planning` schema should define its specs artifact so nested workspace paths are first-class, not accidental. The intended output pattern is `specs/**/*.md`, and the schema instructions should explicitly describe `specs/<area-or-repo>/<capability>/spec.md` as the default convention for area-specific requirements.
-
-Status and instructions output should preserve the concrete nested paths it discovers. Repo-local spec sync, archive, and validation paths that assume `specs/<capability>/spec.md` should not treat workspace-scoped specs as repo-local capability specs until a later explicit implementation, sync, or archive workflow selects an affected area and defines the destination.
-
-### Use affected areas, not targets or repo slices
-
-The planning model should call ownership or implementation boundaries "affected areas." Affected areas can start with registered workspace link names, but the language should leave room for folders, packages, services, apps, or docs sites. Delivery breakdown remains a separate concept and should not be called an area.
-
-Alternative considered: keep "targets" because it maps to the old POC flag. That term is implementation-first and encourages users to choose repos before the plan is clear.
-
-### Make status JSON the agent context contract
-
-`openspec status --change <id> --json` should become the primary source of machine-readable action context. It should include the planning home, change root, concrete artifact paths, affected areas, next steps, and constraints such as allowed edit roots when implementation is later in scope.
-
-Alternative considered: create a separate context command immediately. Status is already used by generated workflow skills, so enriching it first gives agents a single place to look.
-
-### Keep generated skills path-agnostic
-
-Generated workflow skills should ask OpenSpec where artifacts live instead of embedding repo-local paths such as `openspec/changes/<name>`. The standard skill pattern should be:
-
-```text
-1. Run `openspec status --change "<name>" --json`.
-2. Use the returned planning home, artifacts, next steps, and action context.
-3. Run `openspec instructions <artifact> --change "<name>" --json` before writing an artifact.
-4. Write to the resolved path returned by the CLI.
-```
-
-This keeps the same skill usable in repo-local and workspace-scoped changes. If status/instructions output later becomes too crowded, a separate context command can be introduced in a future change without changing the high-level skill rule.
-
-Alternative considered: add a new `openspec context` command now. That may become useful, but it adds a new surface before we have proven that enriched status/instructions are insufficient.
-
-### Guard unsupported workspace workflow actions
-
-The global profile may select workflows whose workspace-scoped behavior is not implemented in this slice, such as full workspace apply, verify, or archive. Generated workspace-local skills for those workflows should be safe: they should inspect status/instructions, explain the unsupported workspace action, and avoid editing linked repos unless a later explicit implementation workflow supplies an allowed edit root.
-
-This keeps the workspace skill set aligned with the user's profile while preventing repo-local fallbacks from pretending to implement workspace semantics.
-
-Alternative considered: filter unsupported workflows out of workspace skill generation. That would avoid unsupported commands, but it would make the workspace skill set silently diverge from the user's profile and make drift harder to explain.
-
-### Redirect repo update from workspace roots
-
-`openspec update` should remain the repo/project update command. When it is run from an OpenSpec workspace planning home, it should not try to treat the workspace as a repo-local project. It should fail or redirect with clear guidance to run `openspec workspace update`.
-
-Alternative considered: make `openspec update` polymorphic and perform workspace update inside workspaces. That would be convenient, but it blurs the repo/project versus workspace boundary this change is trying to make explicit.
-
-### Update docs, help, and completions
-
-The CLI help, command registry/completions, and user docs should include `openspec workspace update`, its `--tools` behavior, the global-profile relationship, and the skills-only workspace delivery rule.
-
-Alternative considered: document this only after implementation. Because profile/update behavior is easy to confuse with repo-local update, the docs and help updates are part of the user-facing feature.
-
-### Treat manual acceptance and UX review as phase gates
-
-Each phase should produce a user-testable increment, even when most of the work is internal. The phase is not done until a user can exercise the named behavior through the CLI, inspect the resulting output or files, and understand what changed.
-
-Each implementation phase should include a manual acceptance pass in addition to automated tests. The manual pass should exercise the real CLI flow, inspect the generated files or output, and confirm linked repos or folders stay untouched where that is part of the contract.
-
-Each phase should also include a lightweight UX review of prompts, command forms, human output, JSON output, artifact paths, and next-step guidance. Any confusing UX found during review should be fixed in the same phase or recorded as an intentional follow-up before the phase is considered done.
-
-Alternative considered: keep manual review only in the final verification phase. That would catch end-to-end issues late, but workspace planning is mostly workflow and agent-facing UX, so each phase needs its own human check while the behavior is still fresh.
-
-### Reduce self-validation bias with evidence-based review
-
-Implementation should define acceptance evidence before marking tasks done. For each phase, the implementer should capture the exact manual commands or interaction path, expected observations, and actual observations. A task is not complete merely because the implementer believes the code matches the design.
-
-When practical, a separate reviewer or fresh agent context should run the manual acceptance checklist and UX review using only the change artifacts, CLI output, and observed filesystem state. If a separate reviewer is not available, the implementer should rerun the checklist from a clean temporary workspace and record the evidence in the change notes or final implementation summary.
-
-Alternative considered: rely on automated tests plus the implementer's final review. Automated tests are necessary, but this change is workflow-heavy and agent-facing, so independent evidence is more useful than confidence alone.
-
-## Deferred Direction
-
-The earlier product notes pointed at a richer workspace model than this slice ships. Keep that direction as follow-up material, not competing current scope.
-
- Full workspace apply should select or confirm one work focus before implementation. The first work focus should be an affected area with an allowed edit root; later work may add an optional delivery phase when a large change needs sequencing. Until that model exists, workspace apply/verify/archive skills remain guarded.
- Workspace verify and archive should wait for a clear model of partial area completion, final whole-change completion, and how workspace-scoped specs become repo-local canonical specs.
- Scoped plan files may eventually attach at the change, phase, affected-area, or work-focus level. This slice intentionally keeps the first workspace schema close to normal OpenSpec artifacts: proposal, specs, design, and tasks.
- Affected areas can start as registered workspace link names, but future flows may refine or derive them from planning artifacts. That derivation should avoid reintroducing target-first or repo-slice language.
- Workflow skills may later separate generic OpenSpec workflow semantics from agent-specific affordances such as asking questions, tracking todos, or delegating work. This slice only makes generated workflow skills path-agnostic.
- OpenSpec may need a named exploratory-notes convention for preserving unsettled thinking before it is promoted into proposal, design, specs, or tasks. This cleanup keeps the current change folder focused on standard artifacts.
-
-## Risks / Trade-offs
-
- Skill generation logic may drift from `init/update` → share the same template generation and tool validation helpers where practical.
- Removing unselected skills could remove user-modified files → remove only known OpenSpec-managed workflow skill directories by explicit workflow list.
- `--tools` is less precise than `--agents` in workspace UX → keep `--tools` for CLI consistency, but use "agents" in prompts and human output.
- Global delivery can say `commands` while workspace update remains skills-only → report this explicitly so users know command generation is deferred, not silently broken.
- `config profile` may run from a linked repo inside an opened workspace → resolve the current planning home carefully and apply only to that home.
- Stored workspace skill state can become stale or hand-edited → treat it as diagnostic machine-local state and always reconcile managed files from the active global profile during update.
- Profile-selected workflows may not yet have full workspace semantics → generated skills must guard unsupported actions and avoid repo-local fallbacks.
- Existing generated skills still contain repo-local path assumptions → handle that as a later artifact-context step after workspace-local skills can be installed.
- Status JSON may become too broad → keep fields plain and action-oriented, such as `planningHome`, `artifacts`, `affectedAreas`, `nextSteps`, and `actionContext`.
- Affected area discovery may be ambiguous → start with explicit registered workspace links and allow later refinement instead of parsing free-form Markdown headings as the only source of truth.
- A new schema can drift from repo-local workflow expectations → keep artifact IDs plain and make status/instructions carry the schema-specific paths.
- Skill instructions may lag behind CLI behavior → audit source workflow templates for hardcoded repo-local paths and replace them with the path-agnostic status/instructions pattern.
@@ -1,78 +0,0 @@
-## Why
-
-Once repos are visible and the agent has workspace context, the user should be able to plan a cross-repo change without creating repo-local artifacts before implementation starts.
-
-The user goal is:
-
-```text
-Explore the product goal across repos.
-Decide the scope.
-Create one workspace-level proposal that identifies the affected areas.
-```
-
-Planning should be the commitment point. Repo visibility alone should remain lightweight.
-
-## What Changes
-
-Add workspace-level change planning:
-
- install and refresh OpenSpec agent skills from the workspace root so agents can operate from the planning home
- use the active global workflow profile to decide which workflow skills are installed in the workspace
- keep `--tools` focused on which agents receive those workspace-local skills
- add a workspace-specific planning schema for workspace changes
- create a workspace change from the coordination root
- capture the product goal once
- identify affected areas by registered workspace link name where applicable
- let the agent explore before committing to affected areas or delivery slices
- keep the workspace as the planning source of truth
- update workflow skill instructions to use CLI-reported artifact paths instead of hardcoded repo-local paths
-
-This slice should avoid creating repo-local artifacts as a side effect of planning. Repo-local artifacts should not be created merely because a workspace change exists.
-
-Workspace setup and update may write agent skill files into the workspace root, such as `.codex/skills/` or `.claude/skills/`, because those files make the workspace planning home usable by agents. That setup work must not write OpenSpec artifacts or agent skill files into linked repos or folders.
-
-Interactive setup should ask which agents should get OpenSpec skills in the workspace, preselecting the preferred opener when that opener supports skills. Workspace update should let users refresh or change those installed agent skills later, including when run from inside the workspace.
-
-Workspace setup and update should treat the global profile as the workflow selection source. For this slice, workspace setup and update are skills-only even when global delivery is `commands` or `both`; command generation for workspaces is deferred.
-
-`openspec config profile` should remain global, but when it runs from inside an OpenSpec workspace and changes the global profile or delivery settings, it should offer to apply the new workflow selection to the current workspace by running `openspec workspace update`.
-
-Workspace-local skill selection should be machine-local state: setup records which agents received skills, update refreshes that stored selection by default, and explicit `--tools` changes the stored selection. OpenSpec should detect when workspace-local skills drift from the current global profile and give clear update guidance.
-
-Selected profile workflows that are not yet fully implemented for workspace-scoped changes should still be safe. Generated skills and CLI guidance must guard unsupported workspace actions instead of falling back to repo-local behavior or editing linked repos implicitly.
-
-Workspace help, docs, and completions should make the distinction legible: `openspec update` remains repo/project sync, while `openspec workspace update` syncs workspace-local agent skills.
-
-Planning dependency:
-
- Depends on `workspace-open-agent-context`.
-
-## Capabilities
-
-### New Capabilities
-
- `workspace-change-planning`: Creates and manages workspace-level proposals for cross-repo goals.
-
-### Modified Capabilities
-
- `workspace-links`: Adds workspace setup/update behavior for workspace-local agent skill installation.
- `cli-config`: Makes `openspec config profile` aware of workspace roots and able to apply global profile changes to the current workspace.
- `change-creation`: Adds workspace-aware change creation semantics and affected area identification.
- `cli-artifact-workflow`: Enriches workflow status and instructions so agents can discover planning context and artifact paths without hardcoded repo-local assumptions.
- `artifact-graph`: Adds a built-in workspace planning schema for workspace-scoped changes.
- `schema-resolution`: Ensures workspace-scoped change creation and workflow commands can resolve the workspace planning schema.
- `openspec-conventions`: Defines the relationship between workspace-level planning and repo-local implementation work.
-
-## Impact
-
- Workspace change creation.
- Workspace-specific planning schema and templates.
- Affected area metadata and validation.
- Workspace setup and update behavior for installing or refreshing agent skills in the workspace root.
- Global profile integration for workspace-local skill workflow selection.
- Workspace-aware `openspec config profile` apply prompt behavior.
- Workspace-local agent skill selection state and drift detection.
- Guarded workflow guidance for profile workflows whose workspace behavior is not implemented in this slice.
- Docs, help, and completions for workspace skill update behavior.
- Agent instructions for proposing cross-repo changes without hardcoded change paths.
- Tests that registered repos are visible before change creation and that creating a change does not imply repo-local artifact creation.
@@ -1,36 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace planning schema
-The artifact graph SHALL provide a built-in workspace planning schema for workspace-scoped changes.
-
-#### Scenario: Built-in workspace planning schema is available
- **WHEN** schemas are resolved from package built-ins
- **THEN** a schema named `workspace-planning` SHALL be available
- **AND** it SHALL describe the artifact structure for workspace-scoped planning
-
-#### Scenario: Workspace planning schema artifacts
- **WHEN** the `workspace-planning` schema is loaded
- **THEN** it SHALL include the normal planning artifacts for a shared proposal, workspace-scoped specs, cross-area design, and coordination tasks
- **AND** it SHALL not require an additional area manifest outside those normal planning artifacts
-
-#### Scenario: Workspace planning schema supports nested specs
- **WHEN** the `workspace-planning` schema defines its specs artifact
- **THEN** the specs artifact SHALL resolve workspace-scoped spec files under `specs/**/*.md`
- **AND** schema guidance SHALL describe `specs/<area-or-repo>/<capability>/spec.md` as the default convention for area-specific requirements
-
-#### Scenario: Workspace planning schema templates
- **WHEN** artifact instructions are requested for the `workspace-planning` schema
- **THEN** the schema SHALL provide templates that guide agents to write workspace-level planning content
- **AND** those templates SHALL avoid instructing agents to create repo-local implementation artifacts
- **AND** specs instructions SHALL support organizing area-specific requirements under workspace-scoped `specs/` paths
-
-#### Scenario: Workspace nested spec paths stay workspace-scoped
- **GIVEN** a workspace change has spec files under `specs/<area-or-repo>/<capability>/spec.md`
- **WHEN** OpenSpec reports status or artifact instructions for the workspace change
- **THEN** it SHALL preserve the concrete nested workspace spec paths
- **AND** it SHALL not treat those files as repo-local specs to sync or archive without an explicit affected-area implementation context
-
-#### Scenario: Workspace planning apply readiness
- **WHEN** the `workspace-planning` schema defines apply readiness
- **THEN** it SHALL require coordination tasks before implementation begins
- **AND** the apply guidance SHALL direct agents to select an affected area before making implementation edits
@@ -1,42 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace-aware change creation
-Change creation SHALL support both repo-local and workspace planning homes.
-
-#### Scenario: Creating a change from a workspace root
- **GIVEN** the command runs from an OpenSpec workspace root
- **WHEN** the user creates a new change
- **THEN** OpenSpec SHALL create the change under the workspace planning path
- **AND** it SHALL not create the change under a linked repo's `openspec/changes/` directory
- **AND** it SHALL use the `workspace-planning` schema when no explicit schema is provided
-
-#### Scenario: Creating a change from inside a workspace
- **GIVEN** the command runs from a subdirectory of an OpenSpec workspace planning home
- **WHEN** the user creates a new change
- **THEN** OpenSpec SHALL resolve the current workspace as the planning home
- **AND** it SHALL create the change under that workspace's planning path
- **AND** it SHALL use the `workspace-planning` schema when no explicit schema is provided
-
-#### Scenario: Creating a change from inside a linked repo
- **GIVEN** a repo or folder is registered as a workspace link
- **AND** the command runs from inside that linked repo or folder rather than from the workspace planning home
- **WHEN** the user creates a new change without explicitly selecting a workspace
- **THEN** OpenSpec SHALL preserve repo-local change creation behavior for that location
- **AND** it SHALL not create a workspace-scoped change merely because the location is registered as a workspace link
-
-#### Scenario: Preserving repo-local change creation
- **GIVEN** the command runs outside an OpenSpec workspace
- **WHEN** the user creates a new change in a repo-local OpenSpec project
- **THEN** OpenSpec SHALL continue to create the change under `openspec/changes/`
-
-#### Scenario: Rejecting invalid workspace affected areas
- **GIVEN** a workspace change creation request includes affected area names
- **WHEN** one or more names are not registered workspace links
- **THEN** OpenSpec SHALL reject those invalid affected areas
- **AND** it SHALL list the valid workspace link names
-
-#### Scenario: Creating without affected areas
- **GIVEN** the user is still exploring scope
- **WHEN** the user creates a workspace change without affected areas
- **THEN** OpenSpec SHALL create the workspace change
- **AND** it SHALL allow affected areas to be identified later
@@ -1,100 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Status JSON provides planning context
-The status command SHALL provide machine-readable planning context for repo-local and workspace changes.
-
-#### Scenario: Reporting planning home
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** the output SHALL identify whether the change is repo-local or workspace-scoped
- **AND** it SHALL include the planning home root and change root
-
-#### Scenario: Reporting concrete artifact paths
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** the output SHALL include concrete paths for existing artifacts
- **AND** agents SHALL be able to read those paths without assuming `openspec/changes/<id>/`
- **AND** workspace-scoped nested spec paths SHALL be reported without flattening the area or capability path
-
-#### Scenario: Reporting workspace affected areas
- **GIVEN** the change is workspace-scoped
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** the output SHALL include known affected areas
- **AND** it SHALL indicate when affected areas remain unresolved without requiring an additional area manifest artifact
-
-#### Scenario: Reporting next steps
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** the output SHALL include next step guidance for agents
- **AND** the guidance SHALL use plain action language
-
-### Requirement: Status JSON action context
-The status command SHALL expose action context that lets agents act without hardcoded filesystem assumptions.
-
-#### Scenario: Planning action context
- **WHEN** a workspace change is still in planning
- **THEN** status JSON SHALL identify the planning artifacts agents may read or update
- **AND** it SHALL indicate that linked repos and folders are context for exploration
-
-#### Scenario: Implementation action context
- **WHEN** a workspace change has a selected affected area for implementation
- **THEN** status JSON SHALL include the allowed edit root for that area
- **AND** it SHALL avoid authorizing edits outside that selected area
-
-#### Scenario: Repo-local action context
- **GIVEN** the change is repo-local
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** status JSON SHALL preserve existing artifact status behavior
- **AND** it SHALL report a repo-local planning home for agents that use action context
-
-### Requirement: Instructions use resolved planning paths
-Artifact and apply instructions SHALL use resolved planning paths rather than hardcoded repo-local change paths.
-
-#### Scenario: Workspace artifact instructions
- **GIVEN** the change is workspace-scoped
- **WHEN** a user runs `openspec instructions <artifact> --change <id> --json`
- **THEN** instruction output SHALL point to the artifact path under the workspace change root
- **AND** it SHALL not instruct the agent to write under a linked repo unless an explicit implementation context allows it
-
-#### Scenario: Repo-local artifact instructions
- **GIVEN** the change is repo-local
- **WHEN** a user runs `openspec instructions <artifact> --change <id> --json`
- **THEN** instruction output SHALL preserve existing repo-local paths
-
-### Requirement: Workflow skills use CLI artifact context
-Generated workflow skills SHALL use OpenSpec CLI output as the source of truth for artifact locations.
-
-#### Scenario: Skills inspect status before artifact work
- **WHEN** a generated workflow skill needs to inspect or create artifacts for a change
- **THEN** it SHALL instruct the agent to run `openspec status --change <id> --json`
- **AND** it SHALL use returned planning context and artifact paths rather than assuming a repo-local change path
-
-#### Scenario: Skills use instructions before writing artifacts
- **WHEN** a generated workflow skill is about to create or update an artifact
- **THEN** it SHALL instruct the agent to run `openspec instructions <artifact> --change <id> --json`
- **AND** it SHALL write to the resolved artifact path returned by the command
-
-#### Scenario: Skills avoid hardcoded repo-local paths
- **WHEN** generated workflow skills describe artifact locations
- **THEN** they SHALL avoid hardcoded examples that require changes to live under `openspec/changes/<id>/`
- **AND** any examples SHALL defer to CLI-reported paths for repo-local and workspace-scoped changes
-
-#### Scenario: Skills guard unsupported workspace workflows
- **GIVEN** a generated workflow skill is selected by the global profile
- **AND** the workflow does not yet have full workspace-scoped behavior in this slice
- **WHEN** the skill is used for a workspace-scoped change
- **THEN** it SHALL tell the agent that the workspace action is not supported yet
- **AND** it SHALL not instruct the agent to fall back to repo-local paths or edit linked repos without an explicit allowed edit root
-
-### Requirement: Workspace schema instructions
-Workflow commands SHALL use the workspace planning schema instructions for workspace-scoped changes that use that schema.
-
-#### Scenario: Workspace planning artifact order
- **GIVEN** a workspace-scoped change uses schema `workspace-planning`
- **WHEN** a user runs `openspec status --change <id> --json`
- **THEN** the artifact list SHALL reflect the workspace planning schema
- **AND** it SHALL include the normal proposal, specs, design, and tasks artifacts
-
-#### Scenario: Workspace specs instructions
- **GIVEN** a workspace-scoped change uses schema `workspace-planning`
- **WHEN** a user requests instructions for the specs artifact
- **THEN** instruction output SHALL guide the agent to organize area-specific requirements under workspace-scoped `specs/` paths
- **AND** it SHALL not require all affected areas to be finalized before planning can continue
- **AND** it SHALL not instruct the agent to create repo-local spec files while the change is still in workspace planning
@@ -1,55 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Config profile applies to current workspace
-The `openspec config profile` command SHALL remain global while offering an explicit workspace apply path when run from inside an OpenSpec workspace.
-
-#### Scenario: Config profile run inside a workspace
- **GIVEN** the command runs from inside an OpenSpec workspace
- **WHEN** the user changes profile or delivery settings with interactive `openspec config profile`
- **THEN** OpenSpec SHALL save the global config changes
- **AND** it SHALL prompt: `Apply changes to this workspace now?`
-
-#### Scenario: User confirms workspace apply
- **GIVEN** `openspec config profile` changed global profile or delivery settings inside a workspace
- **WHEN** the user confirms the workspace apply prompt
- **THEN** OpenSpec SHALL run `openspec workspace update` for the current workspace
- **AND** it SHALL not run repo-local `openspec update` unless the current planning home is repo-local
-
-#### Scenario: User declines workspace apply
- **GIVEN** `openspec config profile` changed global profile or delivery settings inside a workspace
- **WHEN** the user declines the workspace apply prompt
- **THEN** OpenSpec SHALL explain that global config was updated
- **AND** it SHALL tell the user to run `openspec workspace update` later to apply the profile to workspace-local skills
- **AND** it SHALL not modify workspace skill files
-
-#### Scenario: No-op inside workspace
- **GIVEN** the command runs from inside an OpenSpec workspace
- **WHEN** `openspec config profile` exits with no effective config changes
- **THEN** OpenSpec SHALL not prompt to apply changes
- **AND** it SHALL warn if workspace-local skills are out of sync with the current global profile
- **AND** the warning SHALL suggest `openspec workspace update`
-
-#### Scenario: Core preset shortcut inside a workspace
- **GIVEN** the command runs from inside an OpenSpec workspace
- **WHEN** the user runs `openspec config profile core`
- **THEN** OpenSpec SHALL save the global config change without prompting to apply immediately
- **AND** it SHALL tell the user to run `openspec workspace update` to apply the profile to workspace-local skills
-
-#### Scenario: Core preset shortcut inside a repo project
- **GIVEN** the command runs from inside a repo-local OpenSpec project
- **WHEN** the user runs `openspec config profile core`
- **THEN** OpenSpec SHALL preserve existing repo-local shortcut behavior
- **AND** it SHALL tell the user to run `openspec update` to apply the profile to project files
-
-#### Scenario: Workspace planning home wins over linked repo project
- **GIVEN** the command runs in a path under a workspace planning home where a repo-local OpenSpec project could also be detected
- **WHEN** OpenSpec decides which apply prompt to show
- **THEN** the nearest current planning home SHALL determine whether to offer `openspec workspace update` or repo-local `openspec update`
- **AND** OpenSpec SHALL not apply profile changes to a linked repo when the current planning home is the workspace
-
-#### Scenario: Linked repo keeps repo-local profile behavior
- **GIVEN** a repo-local OpenSpec project is registered as a workspace link
- **AND** the command runs from inside that linked repo rather than from the workspace planning home
- **WHEN** OpenSpec decides which apply prompt or guidance to show
- **THEN** OpenSpec SHALL preserve repo-local `openspec update` behavior for that repo
- **AND** it SHALL not offer `openspec workspace update` unless the workspace is explicitly selected
@@ -1,21 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Repo update redirects from workspace planning homes
-The repo-local `openspec update` command SHALL not silently treat a workspace planning home as a repo-local OpenSpec project.
-
-#### Scenario: Running update from a workspace root
- **GIVEN** the command runs from an OpenSpec workspace root
- **WHEN** the user runs `openspec update`
- **THEN** OpenSpec SHALL not generate repo-local project files in the workspace root
- **AND** it SHALL tell the user to run `openspec workspace update`
-
-#### Scenario: Running update from inside a workspace planning directory
- **GIVEN** the command runs from a subdirectory of an OpenSpec workspace planning home
- **WHEN** the user runs `openspec update`
- **THEN** OpenSpec SHALL not run repo-local update behavior
- **AND** it SHALL tell the user to run `openspec workspace update`
-
-#### Scenario: Running update from a repo-local project
- **GIVEN** the command runs from inside a repo-local OpenSpec project
- **WHEN** the user runs `openspec update`
- **THEN** OpenSpec SHALL preserve existing repo-local update behavior
@@ -1,32 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace planning vocabulary
-OpenSpec conventions SHALL distinguish workspace planning concepts using user-facing product language.
-
-#### Scenario: Naming affected areas
- **WHEN** documentation or generated guidance refers to repos, folders, packages, services, apps, or docs sites touched by a workspace change
- **THEN** it SHALL call them affected areas
- **AND** it SHALL avoid using "target repo" or "repo slice" as the primary user-facing term
-
-#### Scenario: Naming delivery slices
- **WHEN** documentation or generated guidance refers to delivery increments inside a larger change
- **THEN** it SHALL call them slices or phases only when delivery sequencing is the subject
- **AND** it SHALL not use slice as a synonym for repo, folder, or affected area
-
-### Requirement: Workspace planning and implementation boundary
-OpenSpec conventions SHALL distinguish workspace-level planning from repo-local implementation ownership.
-
-#### Scenario: Workspace as shared planning home
- **WHEN** a change spans linked repos or folders
- **THEN** conventions SHALL describe the workspace as the shared planning home
- **AND** repo-local implementation homes SHALL retain ownership of their code and canonical behavior
-
-#### Scenario: Avoiding materialization-first language
- **WHEN** documentation explains workspace change creation
- **THEN** it SHALL describe the user outcome in terms of shared planning and affected areas
- **AND** it SHALL avoid making users understand implementation terms such as materialization before they can plan
-
-#### Scenario: Preserving familiar workflow verbs
- **WHEN** workspace guidance describes OpenSpec workflows
- **THEN** it SHALL keep the familiar verbs explore, propose, apply, verify, and archive
- **AND** it SHALL explain that workspace context changes paths, scope, and allowed edit roots rather than creating a separate workflow family
@@ -1,25 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace planning schema resolution
-Schema resolution SHALL support the built-in workspace planning schema.
-
-#### Scenario: Listing workspace planning schema
- **WHEN** a user runs `openspec schemas`
- **THEN** the output SHALL include `workspace-planning`
- **AND** it SHALL identify it as a package-provided schema unless overridden by a higher-precedence schema
-
-#### Scenario: Resolving workspace planning schema by name
- **WHEN** a workflow command requests schema `workspace-planning`
- **THEN** schema resolution SHALL resolve it using the normal project, user, then package precedence order
-
-#### Scenario: Workspace default schema for new changes
- **GIVEN** the command creates a change in a workspace planning home
- **AND** the user did not pass an explicit `--schema`
- **WHEN** OpenSpec resolves the schema for the new change
- **THEN** it SHALL use `workspace-planning` as the default schema
-
-#### Scenario: Explicit schema override for workspace change
- **GIVEN** the command creates a change in a workspace planning home
- **WHEN** the user passes an explicit `--schema <name>`
- **THEN** OpenSpec SHALL use the explicitly requested schema
- **AND** it SHALL validate that schema using normal schema resolution
@@ -1,67 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace change planning home
-OpenSpec SHALL support workspace-level changes whose shared plan lives in the workspace planning home.
-
-#### Scenario: Creating a workspace change
- **GIVEN** the command runs from an OpenSpec workspace
- **WHEN** the user creates a change for workspace planning
- **THEN** OpenSpec SHALL create the change under the workspace planning path
- **AND** it SHALL treat the workspace as the planning home for that change
- **AND** it SHALL use the workspace planning schema when no explicit schema is provided
-
-#### Scenario: Workspace planning artifact structure
- **GIVEN** a workspace change uses the workspace planning schema
- **WHEN** OpenSpec reports or creates planning artifacts for that change
- **THEN** it SHALL use workspace-level artifacts for proposal, specs, cross-area design, and coordination tasks
- **AND** those artifacts SHALL live under the workspace change root
- **AND** it SHALL not require an additional area manifest outside those normal planning artifacts
-
-#### Scenario: Capturing the shared goal once
- **WHEN** a workspace change is proposed
- **THEN** OpenSpec SHALL capture the product goal at the workspace change level
- **AND** it SHALL avoid requiring separate repo-local proposals before the affected areas are understood
-
-#### Scenario: Preserving linked repos during change creation
- **WHEN** OpenSpec creates a workspace-level change
- **THEN** it SHALL not create repo-local OpenSpec change directories inside linked repos or folders
- **AND** it SHALL not edit implementation files in linked repos or folders
-
-### Requirement: Workspace affected areas
-OpenSpec SHALL represent ownership or implementation boundaries in a workspace change as affected areas.
-
-#### Scenario: Using registered workspace links as areas
- **GIVEN** a workspace has linked repos or folders
- **WHEN** a workspace change identifies affected areas by registered link name
- **THEN** OpenSpec SHALL validate those area names against the workspace links
- **AND** it SHALL report invalid area names clearly
-
-#### Scenario: Planning before all areas are known
- **WHEN** a user is still exploring a workspace change
- **THEN** OpenSpec SHALL allow the shared plan to exist before all affected areas are finalized
- **AND** it SHALL keep unresolved affected area questions visible in the normal planning artifacts and status output
-
-#### Scenario: Organizing requirements by area
- **GIVEN** a workspace change has requirements owned by one or more affected areas
- **WHEN** OpenSpec reports or creates workspace-scoped specs
- **THEN** it SHALL allow area-specific requirements to be organized under `specs/<area-or-repo>/<capability>/spec.md`
- **AND** it SHALL not require separate area folders outside the normal `specs/` artifact tree
- **AND** it SHALL preserve the area-or-repo path segment as workspace planning context rather than flattening it into a repo-local capability name
-
-#### Scenario: Separating areas from delivery slices
- **WHEN** a workspace change reports affected areas
- **THEN** OpenSpec SHALL distinguish affected areas from delivery slices or phases
- **AND** it SHALL not require users to define delivery slices for a small cross-area change
-
-### Requirement: Workspace planning source of truth
-OpenSpec SHALL keep the workspace change plan as the source of truth until implementation begins for a selected affected area.
-
-#### Scenario: Exploring before implementation
- **WHEN** an agent explores a workspace change
- **THEN** it SHALL use workspace-level planning artifacts as the shared planning source
- **AND** it SHALL treat linked repos and folders as available context rather than committed implementation targets
-
-#### Scenario: Deferring repo-local implementation
- **WHEN** repo-local implementation work is needed for a workspace change
- **THEN** OpenSpec SHALL require an explicit implementation workflow with a selected affected area
- **AND** it SHALL expose the allowed edit root for that selected area before implementation edits begin
@@ -1,163 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace setup installs agent skills
-OpenSpec SHALL let users install OpenSpec agent skills into a workspace during workspace setup.
-
-#### Scenario: Prompting for workspace agent skills
- **WHEN** interactive workspace setup reaches agent skill installation
- **THEN** OpenSpec SHALL ask which agents should get OpenSpec skills in this workspace
- **AND** the prompt SHALL use agent-skill language rather than "AI tools" language
-
-#### Scenario: Preselecting the preferred opener
- **GIVEN** the user selected a preferred opener that supports OpenSpec skill generation
- **WHEN** interactive workspace setup asks which agents should get skills
- **THEN** OpenSpec SHALL preselect the matching agent
- **AND** the user SHALL be able to select additional agents or deselect the preselected agent
-
-#### Scenario: Installing selected workspace skills
- **WHEN** workspace setup completes with one or more selected agents
- **THEN** OpenSpec SHALL generate or refresh OpenSpec skill files under the workspace root for each selected agent
- **AND** it SHALL report which agents received skills
- **AND** it SHALL store the selected agents in workspace-local machine state
-
-#### Scenario: Installing profile-selected workflows
- **GIVEN** global config resolves to a workflow profile
- **WHEN** workspace setup installs agent skills
- **THEN** OpenSpec SHALL install workspace-local skills for the workflows selected by that profile
- **AND** it SHALL treat `--tools` as agent selection, not workflow selection
- **AND** it SHALL record the last applied workflow IDs for drift detection
-
-#### Scenario: Installing skills only during setup
- **WHEN** workspace setup installs agent skills
- **THEN** OpenSpec SHALL generate skill files only
- **AND** it SHALL not generate slash command files or global command files as part of workspace setup
-
-#### Scenario: Ignoring command delivery for workspace setup
- **GIVEN** global config delivery is `commands` or `both`
- **WHEN** workspace setup installs agent skills
- **THEN** OpenSpec SHALL still generate workspace-local skills only
- **AND** it SHALL report that workspace command generation is not part of this slice
-
-#### Scenario: Preserving linked repos during skill installation
- **WHEN** workspace setup installs agent skills
- **THEN** OpenSpec SHALL leave linked repos and folders unchanged
- **AND** generated skills SHALL be scoped to the workspace planning home
-
-#### Scenario: Non-interactive setup tool selection
- **WHEN** non-interactive workspace setup receives `--tools all`, `--tools none`, or `--tools <ids>`
- **THEN** OpenSpec SHALL use the selected tool set for workspace agent skill installation
- **AND** it SHALL validate tool IDs using the same supported tool IDs as skill generation for repo initialization
-
-#### Scenario: Non-interactive setup without tool selection
- **WHEN** non-interactive workspace setup omits `--tools`
- **THEN** OpenSpec SHALL create the workspace without installing agent skills
- **AND** it SHALL report that no workspace skills were installed
- **AND** it SHALL tell the user to run `openspec workspace update --tools <ids>` to install skills later
-
-#### Scenario: Reporting setup skills in JSON output
- **WHEN** non-interactive workspace setup installs agent skills with JSON output enabled
- **THEN** OpenSpec SHALL include generated, refreshed, skipped, or failed skill installation results in machine-readable output
-
-### Requirement: Workspace update manages agent skills
-OpenSpec SHALL provide a workspace update flow for refreshing agent skills after setup.
-
-#### Scenario: Updating the current workspace
- **GIVEN** the command runs from inside an OpenSpec workspace
- **WHEN** the user runs `openspec workspace update`
- **THEN** OpenSpec SHALL update that current workspace
-
-#### Scenario: Updating a named workspace
- **GIVEN** a workspace named `platform` is known locally
- **WHEN** the user runs `openspec workspace update platform`
- **THEN** OpenSpec SHALL update the `platform` workspace
-
-#### Scenario: Updating a workspace selected by flag
- **GIVEN** a workspace named `platform` is known locally
- **WHEN** the user runs `openspec workspace update --workspace platform`
- **THEN** OpenSpec SHALL update the `platform` workspace
-
-#### Scenario: Updating selected workspace skills
- **WHEN** workspace update completes with selected agents
- **THEN** OpenSpec SHALL refresh OpenSpec skills for selected agents
- **AND** it SHALL add skills for newly selected agents
- **AND** it SHALL remove OpenSpec-managed workflow skill directories for agents that are no longer selected
- **AND** it SHALL update the stored workspace-local selected agent list
-
-#### Scenario: Updating profile-selected workflows
- **GIVEN** global config resolves to a workflow profile
- **WHEN** workspace update refreshes workspace-local skills
- **THEN** OpenSpec SHALL sync the workspace-local skill workflow set to the workflows selected by that profile
- **AND** deselected workflow skill directories SHALL be removed only when they are known OpenSpec-managed workflow skill directories
- **AND** it SHALL update the last applied workflow IDs used for drift detection
-
-#### Scenario: Ignoring command delivery for workspace update
- **GIVEN** global config delivery is `commands` or `both`
- **WHEN** workspace update refreshes workspace-local skills
- **THEN** OpenSpec SHALL still update workspace-local skills only
- **AND** it SHALL not generate slash command files or global command files
-
-#### Scenario: Removing only managed skill directories
- **WHEN** workspace update removes skills for an unselected agent
- **THEN** OpenSpec SHALL remove only known OpenSpec-managed workflow skill directories
- **AND** it SHALL preserve unrelated files in the agent directory
-
-#### Scenario: Updating stored agent selection by flag
- **WHEN** workspace update receives `--tools <ids>` or `--tools none`
- **THEN** OpenSpec SHALL replace the stored workspace-local selected agent list with that selection
- **AND** future workspace updates without `--tools` SHALL use the stored selection
-
-#### Scenario: Non-interactive update tool selection
- **WHEN** workspace update receives `--tools all`, `--tools none`, or `--tools <ids>`
- **THEN** OpenSpec SHALL update workspace agent skills using that selected tool set
- **AND** it SHALL avoid prompting for agent selection
-
-#### Scenario: Non-interactive update without tool selection
- **GIVEN** workspace-local selected agents are stored
- **WHEN** non-interactive workspace update omits `--tools`
- **THEN** OpenSpec SHALL refresh the stored selected agents using the active global profile
- **AND** it SHALL avoid prompting for agent selection
-
-#### Scenario: Non-interactive update without stored selection
- **GIVEN** no workspace-local selected agents are stored
- **WHEN** non-interactive workspace update omits `--tools`
- **THEN** OpenSpec SHALL complete without installing agent skills
- **AND** it SHALL report a no-op with guidance to pass `--tools`
-
-#### Scenario: Reporting workspace skill drift
- **GIVEN** workspace-local skill state records last applied workflow IDs
- **AND** the active global profile resolves to a different workflow set
- **WHEN** OpenSpec reports workspace skill state
- **THEN** it SHALL report that workspace-local skills are out of sync with the global profile
- **AND** it SHALL suggest `openspec workspace update`
-
-#### Scenario: Reporting clean workspace skill sync
- **GIVEN** workspace-local skill state matches the active global profile and selected agents
- **WHEN** OpenSpec reports workspace skill state
- **THEN** it SHALL not report profile drift
-
-#### Scenario: Reporting workspace skill update results
- **WHEN** workspace update changes agent skill state
- **THEN** OpenSpec SHALL report which agents were refreshed, added, removed, skipped, or failed
-
-#### Scenario: Reporting workspace update results in JSON output
- **WHEN** workspace update runs with JSON output enabled
- **THEN** OpenSpec SHALL include refreshed, added, removed, skipped, or failed skill results in machine-readable output
-
-### Requirement: Workspace skill update surface is documented
-OpenSpec SHALL expose workspace skill setup/update behavior in user-facing command surfaces.
-
-#### Scenario: Workspace update appears in help
- **WHEN** a user runs `openspec workspace --help`
- **THEN** OpenSpec SHALL list `workspace update`
- **AND** it SHALL describe it as refreshing workspace-local agent skills
-
-#### Scenario: Workspace update options appear in help
- **WHEN** a user runs `openspec workspace update --help`
- **THEN** OpenSpec SHALL document workspace selection options
- **AND** it SHALL document `--tools all|none|<ids>`
- **AND** it SHALL state that global profile selects workflows and `--tools` selects agents
-
-#### Scenario: Workspace update appears in completions
- **WHEN** shell completions are generated
- **THEN** the workspace command registry SHALL include `workspace update`
- **AND** it SHALL include relevant options such as `--workspace`, `--tools`, `--json`, and `--no-interactive`
@@ -1,133 +0,0 @@
-## Phase 1: Workspace Setup Skills
-
-User-testable outcome: A user can run workspace setup, choose which agents get the active profile's OpenSpec skills, and verify the selected skills are generated in the workspace root only.
-
- [x] 1.1 Add an interactive workspace setup step named "Install agent skills" that asks which agents should get OpenSpec skills in this workspace.
- [x] 1.2 Preselect the preferred opener when that opener supports skills, while allowing users to choose different or additional agents.
- [x] 1.3 Support non-interactive agent selection with the existing `--tools all|none|<ids>` style.
- [x] 1.4 Validate workspace setup tool IDs using the same supported skill-generation tool set as repo initialization.
- [x] 1.5 Resolve the active global profile and use it to choose which workflow skills workspace setup installs.
- [x] 1.6 Ensure `openspec workspace setup` generates or refreshes OpenSpec agent skills in the workspace root for the selected agents.
- [x] 1.7 Keep setup-time skill generation scoped to the workspace planning home; do not write skills or OpenSpec artifacts into linked repos or folders during workspace setup.
- [x] 1.8 Keep workspace setup skill generation skills-only for this slice; do not generate slash commands or global command files even when global delivery includes commands.
- [x] 1.9 Define how setup reports generated, refreshed, skipped, failed, and skills-only delivery work in human and JSON output.
- [x] 1.10 Store the selected workspace skill agents and last-applied workflow IDs in workspace-local machine state.
- [x] 1.11 Preserve non-interactive setup compatibility when `--tools` is omitted by skipping skill installation with clear guidance.
- [x] 1.12 Manually run workspace setup in interactive and non-interactive modes and verify the selected profile workflows land only in the workspace root.
- [x] 1.13 Review the setup UX: prompt wording, defaults, skip path, profile/delivery messaging, success output, and JSON output are clear before moving on.
-
-## Phase 2: Workspace Skill Updates
-
-User-testable outcome: A user can change the global profile, run workspace update in an existing workspace, and see workspace-local skills refresh to the selected workflows with clear human and JSON output.
-
- [x] 2.1 Add a workspace update flow that refreshes, adds, or removes OpenSpec agent skills in an existing workspace.
- [x] 2.2 Let `openspec workspace update` resolve the current workspace when run from inside a workspace.
- [x] 2.3 Support named and selected-workspace update forms such as `openspec workspace update platform` and `openspec workspace update --workspace platform`.
- [x] 2.4 Support non-interactive update forms such as `openspec workspace update platform --tools codex,claude`.
- [x] 2.5 Remove only known OpenSpec-managed workflow skill directories for agents that are no longer selected.
- [x] 2.6 Sync workspace-local workflow skill directories to the current global profile selection.
- [x] 2.7 Keep workspace update skills-only for this slice; do not generate slash commands or global command files even when global delivery includes commands.
- [x] 2.8 Define how update reports refreshed, added, removed, skipped, failed, and skills-only delivery work in human and JSON output.
- [x] 2.9 Use stored selected agents when workspace update runs without `--tools`, and update that stored selection when `--tools` is passed.
- [x] 2.10 Detect workspace-local skill drift from the active global profile and report `openspec workspace update` guidance.
- [x] 2.11 Manually run workspace update for refresh, add, remove, no-op, omitted-`--tools`, and profile-change cases and verify linked repos remain unchanged.
- [x] 2.12 Review the update UX: command forms, current-workspace detection, profile/delivery messaging, drift messaging, removal messaging, and JSON output are understandable.
-
-## Phase 3: Config Profile Workspace Apply
-
-User-testable outcome: A user can run `openspec config profile` inside a workspace and choose whether to apply the changed global profile to that workspace now.
-
- [x] 3.1 Detect when `openspec config profile` runs from inside an OpenSpec workspace.
- [x] 3.2 After an actual profile or delivery change inside a workspace, prompt to apply changes to the current workspace now.
- [x] 3.3 When confirmed, run `openspec workspace update` for the current workspace instead of repo-local `openspec update`.
- [x] 3.4 When declined, report that global config changed and that `openspec workspace update` applies it later.
- [x] 3.5 Preserve existing repo-local `openspec config profile` apply behavior outside workspaces.
- [x] 3.6 Keep `openspec config profile core` non-interactive, but print workspace-specific `openspec workspace update` guidance when run inside a workspace.
- [x] 3.7 Warn on no-op config profile inside a workspace when workspace-local skills drift from the active global profile.
- [x] 3.8 Manually run `openspec config profile` inside a workspace for confirm, decline, no-op, drift-warning, and `core` preset paths.
- [x] 3.9 Review the config-profile UX: prompt wording, project/workspace distinction, no-op behavior, preset guidance, and follow-up guidance are clear.
-
-## Phase 4: Workspace Change Creation
-
-User-testable outcome: A user can create a workspace-level change from the coordination root, inspect its workspace planning artifacts, and confirm linked repos were not edited.
-
- [x] 4.1 Add a built-in `workspace-planning` schema and templates that keep the normal proposal/specs/design/tasks artifact shape.
- [x] 4.2 Define the workspace-planning specs artifact with nested `specs/**/*.md` output support and instructions for `specs/<area-or-repo>/<capability>/spec.md`.
- [x] 4.3 Add workspace-aware change creation from the workspace coordination root.
- [x] 4.4 Default workspace-scoped change creation to the `workspace-planning` schema.
- [x] 4.5 Store workspace-level changes under the workspace planning path rather than under linked repos or folders.
- [x] 4.6 Capture the product goal once at the workspace change level.
- [x] 4.7 Record or validate affected area names through workspace-scoped specs or task sections using registered workspace link names where applicable.
- [x] 4.8 Ensure creating a workspace change does not create repo-local OpenSpec artifacts or edit linked repos.
- [x] 4.9 Preserve repo-local change creation behavior outside workspaces.
- [x] 4.10 Manually create a workspace change from a coordination root and verify the generated artifacts, workspace-scoped specs/tasks, affected areas, and untouched linked repos.
- [x] 4.11 Review the change creation UX: goal capture, affected-area identification, artifact paths, and next-step guidance feel clear.
-
-## Phase 5: Planning Home And Agent Context
-
-User-testable outcome: A user can run status and instructions for repo-local and workspace changes and see the resolved planning home, artifact paths, affected areas, constraints, and next steps.
-
- [x] 5.1 Introduce a shared planning-home resolver that identifies repo-local versus workspace planning homes.
- [x] 5.2 Enrich `openspec status --change <id> --json` with planning home, change root, relevant artifact paths, affected areas, next steps, and action context.
- [x] 5.3 Enrich `openspec instructions <artifact> --change <id> --json` with resolved artifact paths for repo-local and workspace-scoped changes.
- [x] 5.4 Keep workspace-level planning as the source of truth until an explicit implementation workflow selects an affected area.
- [x] 5.5 Preserve nested workspace spec paths in status and instructions output without flattening them into repo-local capability paths.
- [x] 5.6 Manually run status and instructions for both repo-local and workspace-scoped changes and verify paths and action context are correct.
- [x] 5.7 Review the planning-context UX: human output, JSON field names, and next-step guidance are easy for users and agents to follow.
-
-## Phase 6: Workflow Skill Instructions
-
-User-testable outcome: A user can inspect regenerated workflow skills and verify they are path-agnostic and tell agents to use CLI-reported artifact paths.
-
- [x] 6.1 Update generated workflow skill templates to run `openspec status --change <id> --json` before artifact work and trust returned planning context.
- [x] 6.2 Update generated workflow skill templates to run `openspec instructions <artifact> --change <id> --json` before writing artifacts and use the resolved output path.
- [x] 6.3 Audit source workflow templates for hardcoded `openspec/changes/<name>` assumptions and replace them with CLI-reported path guidance.
- [x] 6.4 Keep a separate artifact-context command out of this slice unless enriched status/instructions prove insufficient during implementation.
- [x] 6.5 Manually regenerate or inspect installed workflow skills and verify they follow CLI-reported artifact paths in a workspace change.
- [x] 6.6 Guard profile-selected workflow skills whose workspace behavior is not implemented yet so they do not fall back to repo-local paths or edit linked repos.
- [x] 6.7 Review the agent-instruction UX: instructions are concise, path-agnostic, safe for unsupported workspace workflows, and practical for both repo-local and workspace planning.
-
-## Phase 7: Verification
-
-User-testable outcome: A user or reviewer can run the full manual checklist from a clean workspace and compare expected versus actual evidence for every earlier phase.
-
- [x] 7.1 Add tests that workspace setup installs skills in the workspace root and leaves linked repos unchanged.
- [x] 7.2 Add tests that workspace update refreshes, adds, and removes only managed workspace skill directories.
- [x] 7.3 Add tests that workspace setup/update use the current global profile for workflow skill selection while keeping workspace delivery skills-only.
- [x] 7.4 Add tests that `openspec config profile` inside a workspace can apply changes through `openspec workspace update`.
- [x] 7.5 Add tests for stored workspace skill agent selection, omitted-`--tools` behavior, and profile drift reporting.
- [x] 7.6 Add tests that `openspec update` from a workspace planning home redirects to `openspec workspace update`.
- [x] 7.7 Add tests that unsupported workspace workflow skills are guarded and do not instruct repo-local fallback edits.
- [x] 7.8 Add tests that registered repos are visible before change creation.
- [x] 7.9 Add tests that workspace change creation does not imply repo-local artifact creation.
- [x] 7.10 Add tests that the workspace-planning schema resolves nested `specs/<area-or-repo>/<capability>/spec.md` files as workspace-scoped specs.
- [x] 7.11 Add cross-platform path tests for workspace-root skill paths and workspace change paths.
- [x] 7.12 Update CLI docs, command help, and shell completion coverage for `workspace update`, `--tools`, profile behavior, and workspace skills-only delivery.
- [x] 7.13 Run `openspec validate workspace-change-planning --strict`.
- [x] 7.14 Run the full manual acceptance checklist across setup, update, config profile, change creation, planning context, and workflow skills before marking the change complete.
- [x] 7.15 Complete a final UX review across the whole workflow and record any follow-up fixes or intentional deferrals.
- [x] 7.16 Before implementation sign-off, record the manual commands or interaction paths, expected observations, and actual observations for each phase.
- [x] 7.17 Have a separate reviewer or fresh agent context rerun the manual acceptance and UX checklist when available; otherwise rerun it from a clean temporary workspace and report the evidence.
-
-## Verification Evidence
-
-Completion evidence was recorded on 2026-05-14.
-
-Automated checks:
-
-```bash
-pnpm run build
-pnpm vitest run test/commands/workspace.test.ts test/commands/artifact-workflow.test.ts test/core/workspace/skills.test.ts test/core/planning-home.test.ts test/core/templates/skill-templates-parity.test.ts
-node dist/cli/index.js validate workspace-change-planning --strict
-git diff --check
-```
-
-Clean workspace rerun covered non-interactive workspace setup, workspace doctor, config profile update guidance, workspace update redirection, workspace change creation with `--areas api,web`, status/instructions JSON for nested workspace specs, linked repo cleanliness, and guarded unsupported workflow skills.
-
-Observed results:
-
- Build, targeted tests, strict validation, and whitespace checks passed.
- Workspace setup/update generated skills only in the workspace root and left linked repos untouched.
- Workspace change creation used schema `workspace-planning`, reported affected areas `api` and `web`, preserved nested `specs/api/login/spec.md`, and kept `actionContext.allowedEditRoots` empty during planning.
- Generated workflow skills used CLI-reported paths and workspace guards rather than hardcoded `openspec/changes/<name>` paths.
- Fresh-agent rerun was not available; the clean temporary workspace rerun served as the fallback independent acceptance pass.
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-07-26
@@ -1,53 +0,0 @@
-## Context
-
-The `schema init` action currently checks whether the destination exists and, when `--force` is present, immediately removes that directory. Only afterward does it collect the remaining inputs and validate `--artifacts`. An unknown artifact therefore produces the expected error only after the existing schema has already been deleted.
-
-The command is implemented as one Commander action in `src/commands/schema.ts`. Its current tests largely exercise supporting schema functions or manually create expected files instead of invoking the registered command, so they do not observe mutation ordering.
-
-## Goals / Non-Goals
-
-**Goals:**
-
- Finish collecting and validating schema-init inputs before any forced replacement mutates the destination.
- Preserve the complete existing schema when an artifact ID is invalid.
- Keep error output, exit status, and successful `--force` replacement behavior compatible.
- Cover the behavior through the real registered `schema init` command on cross-platform temporary paths.
-
-**Non-Goals:**
-
- Change the set of artifact IDs accepted by `schema init` or how the comma-separated list is parsed.
- Make replacement transactional for filesystem failures that occur after validation succeeds.
- Change overwrite behavior in other schema subcommands.
-
-## Decisions
-
-### Separate preparation from destination mutation
-
-The action will retain the early destination-exists check so an invocation without `--force` still fails without prompting or doing extra work. When overwrite is allowed, it will defer `fs.rmSync()` until after the command has:
-
-1. Determined interactive or non-interactive mode.
-2. Collected the description and artifact selection.
-3. Rejected an empty selection or unknown artifact ID.
-4. Constructed the artifact definitions and in-memory schema object.
-
-Only then will the command remove the existing directory and write the replacement.
-
-This directly fixes the deterministic validation failure without introducing temporary-directory swaps or rollback machinery. Staging and atomically swapping the entire schema was considered, but it would broaden this targeted fix to cover unrelated filesystem failures and platform-specific rename behavior.
-
-### Preserve the existing failure contract
-
-Invalid artifacts will continue to produce the same text or JSON error, set a non-zero exit code, and report the valid artifact IDs. The only observable difference is that an existing destination remains unchanged.
-
-Keeping the output contract stable limits the change for scripts and agents that already consume the JSON response.
-
-### Add command-level regression tests
-
-Tests will register `schema` on a fresh Commander program and call `parseAsync()` with real command arguments inside a temporary project directory. The primary regression test will place a sentinel file in an existing schema, invoke `schema init --force` with an unknown artifact, and verify that both the directory and sentinel content survive.
-
-A successful overwrite test will use valid artifact IDs and verify that the old sentinel is removed while the expected generated files exist. Paths will be constructed with Node.js `path` helpers so the same tests run on Windows, macOS, and Linux.
-
-## Risks / Trade-offs
-
- **Risk: Moving mutation later could accidentally weaken successful overwrite behavior.** Mitigation: Keep a positive command-level test that proves a valid forced initialization still replaces the destination.
- **Risk: Commander tests can leak `process.exitCode` or the working directory into neighboring tests.** Mitigation: Save and restore process state in test setup and teardown.
- **Trade-off: A write failure after validation can still leave a partial replacement.** Mitigation: Treat full transactional replacement as a separate hardening effort; this change guarantees safety for input and selection failures only.
@@ -1,28 +0,0 @@
-## Why
-
-`openspec schema init --force` removes an existing project-local schema before validating the requested artifact list. A command that ultimately fails for an unknown artifact can therefore destroy the schema it was supposed to replace, turning a recoverable input error into data loss.
-
-## What Changes
-
- Complete schema-init input collection and artifact validation before replacing an existing schema.
- Preserve the existing schema and its contents when validation fails, including when `--force` is present.
- Keep successful `--force` replacement behavior unchanged once all inputs are valid.
- Add command-level regression coverage for both failed preservation and successful replacement.
- Keep the change narrowly scoped to `schema init` artifact validation and forced replacement; no other CLI behavior changes.
-
-## Capabilities
-
-### New Capabilities
-
- None.
-
-### Modified Capabilities
-
- `schema-init-command`: Require failed schema-init validation to leave an existing schema unchanged before any forced replacement begins.
-
-## Impact
-
- **CLI behavior**: Failed `schema init --force` validation no longer deletes an existing project-local schema.
- **Code**: The `schema init` action in `src/commands/schema.ts` will separate non-destructive preparation from the destructive replacement step.
- **Tests**: `test/commands/schema.test.ts` will exercise the registered command instead of simulating schema creation for the affected cases.
- **Dependencies and APIs**: No new dependencies or public API changes.
@@ -1,21 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Schema init validates artifacts before forced replacement
-The CLI SHALL validate all requested artifact IDs before replacing an existing project-local schema. If artifact validation fails, the CLI SHALL leave the existing schema directory and all of its contents unchanged on every supported platform.
-
-#### Scenario: Unknown artifact preserves existing schema
- **GIVEN** `openspec/schemas/tdd-driven/` already exists with user-authored files
- **WHEN** the user runs `schema init tdd-driven` with `--force` and an artifact list containing the unknown ID `task`
- **THEN** the command exits with a non-zero status and reports the unknown artifact
- **AND** the existing `tdd-driven` schema directory and its contents remain unchanged
-
-#### Scenario: Unknown artifact preserves a schema at a Windows project path
- **GIVEN** an existing project-local schema is resolved from a Windows filesystem path
- **WHEN** forced schema initialization fails artifact validation
- **THEN** the resolved schema directory and its contents remain unchanged
-
-#### Scenario: Valid artifacts allow forced replacement
- **GIVEN** a project-local schema already exists
- **WHEN** the user runs `schema init` with `--force` and only valid artifact IDs
- **THEN** the command replaces the existing schema with the newly generated schema
- **AND** reports successful creation
@@ -1,17 +0,0 @@
-## 1. Command-Level Regression Coverage
-
- [x] 1.1 Add a test helper that registers the schema command on a fresh Commander program and restores `cwd`, `process.exitCode`, environment variables, and console spies after each test.
- [x] 1.2 Add a regression test that creates an existing schema with a sentinel file, runs forced initialization with an unknown artifact ID, and verifies the non-zero JSON error plus byte-for-byte preservation of the existing schema.
- [x] 1.3 Add a positive regression test that runs forced initialization with valid artifact IDs and verifies the old sentinel is removed and the expected schema and templates are generated.
-
-## 2. Validation-First Forced Replacement
-
- [x] 2.1 Reorganize the `schema init` action so it collects inputs, validates artifact IDs, and constructs the in-memory schema before deleting an existing destination.
- [x] 2.2 Keep the existing unknown-artifact output and exit status unchanged while ensuring every pre-mutation return path leaves the destination untouched.
- [x] 2.3 Confirm a valid `--force` invocation still replaces the existing schema and reports the same successful result.
-
-## 3. Cross-Platform Verification and Release Metadata
-
- [x] 3.1 Use Node.js path helpers and temporary directories in the regression tests, and confirm the affected test runs in the existing Windows CI environment.
- [x] 3.2 Run `pnpm exec vitest run test/commands/schema.test.ts`, `pnpm run lint`, and `pnpm run build`.
- [x] 3.3 Add a patch changeset describing that failed forced schema initialization now preserves the existing schema.
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-07-22
@@ -1,183 +0,0 @@
-## Context
-
-OpenSpec project config currently provides a top-level `context` value and an artifact-keyed `rules` map. Artifact instruction generation reads both values at runtime, but the apply and archive workflow surfaces do not expose equivalent current inputs.
-
-Apply already has a dynamic instruction command: `openspec instructions apply --change <name>`. Archive skills are generated from static templates and currently have no dedicated runtime-input command. Adding operation-specific advice directly to generated templates would make it stale whenever project config changes.
-
-This change adds a small runtime contract for apply and archive without changing archive execution ownership. The existing single-change archive skill, bulk archive skill, spec sync behavior, and direct `openspec archive` command keep their current flows.
-
-## Goals / Non-Goals
-
-**Goals:**
-
- Model optional apply and archive working advice as `operations.<operation>.guidance`.
- Fetch current project context and matching operation guidance whenever apply or archive instructions are requested.
- Return context and operation guidance as separate structured fields.
- Make the single-change and bulk archive skills consume current inputs at execution time.
- Carry current `specs` artifact rules into archive-driven and standalone spec sync whenever concrete delta specs are merged into main specs.
- Preserve existing artifact rules, skill steps, user prompts, and CLI behavior.
- Keep config parsing resilient so malformed operation config does not invalidate unrelated fields.
-
-**Non-Goals:**
-
- Change archive execution ownership, phases, safety guarantees, or filesystem behavior.
- Change `openspec archive`, its flags, filesystem behavior, or compatibility contract.
- Change semantic spec sync ownership, merge phases, or main-spec format.
- Add new enforceable archive checks or configurable operation checks.
- Make any natural-language instruction input a security or validation boundary.
- Change the structure or meaning of artifact `rules`.
- Generalize semantic spec sync to arbitrary artifact IDs or infer delta specs from non-`specs` artifacts.
-
-## Decisions
-
-### D1: Give operation guidance its own typed namespace
-
-Project config gains this optional shape:
-
-```yaml
-context: |
-  TypeScript project using pnpm.
-
-rules:
-  specs:
-    - Preserve requirement IDs when meaning is unchanged.
-
-operations:
-  apply:
-    guidance:
-      - Keep test summaries concise.
-  archive:
-    guidance:
-      - Summarize the archive outcome before finishing.
-```
-
-The in-memory model uses explicit operation IDs:
-
-```ts
-const OPERATION_IDS = ['apply', 'archive'] as const;
-type OperationId = (typeof OPERATION_IDS)[number];
-
-interface OperationConfig {
-  guidance?: string[];
-}
-```
-
-Parsing remains resilient and field-by-field. An invalid operation entry is omitted with a warning without discarding valid context, rules, references, store settings, or other operation entries. Unknown operation IDs and unknown fields receive actionable warnings. Empty guidance strings are removed while non-empty strings retain their original order, line breaks, and Markdown.
-
-Artifact `rules` remain unchanged and are not read as operation guidance.
-
-### D2: Load operation inputs through one shared helper
-
-Apply and archive instruction generation use a shared helper conceptually shaped as:
-
-```ts
-loadOperationInputs(projectConfig, operationId): {
-  context?: string;
-  operationGuidance?: string[];
-}
-```
-
-The existing root-config loader calls `readProjectConfig()` once for each instruction command and passes that parsed `ProjectConfig` to the helper. The same config snapshot supplies references, context, and operation guidance, so malformed-field warnings are not duplicated and one command cannot mix values from two reads. There is no generated-skill or module-state cache, so the next command observes later config changes.
-
-Absent context and empty guidance are omitted rather than returned as empty values.
-
-### D3: Extend apply output without changing apply state behavior
-
-`generateApplyInstructions()` adds the shared operation inputs to its existing result:
-
-```ts
-{
-  context?: string;
-  operationGuidance?: string[];
-}
-```
-
-The existing apply state, task progress, missing-artifact checks, context files, references, and schema instruction remain unchanged. JSON serialization includes the new fields automatically. Text output renders project context as a required instruction-input section and operation guidance as a distinct advisory section after the built-in apply instruction content.
-
-The apply skill template keeps both fields structurally separate from CLI-returned state, progress, tasks, missing artifacts, context files, and built-in instruction. When context is present, the agent must read it and apply relevant project facts, conventions, and constraints as a required prompt-level input. When operation guidance is present, the agent must read and consider it as optional additive advice and follow entries that are applicable and compatible with the built-in workflow.
-
-This change does not modify CLI-controlled fields or their state transitions. The template tells the agent not to treat context or guidance as task completion, a replacement for the state-driven workflow, or permission to bypass a blocked state. It must report context conflicts with the built-in instruction, explicit user choices, or CLI-controlled values. If guidance is inapplicable or conflicts with those controlling inputs, the agent preserves the built-in flow and explains why the advice was not followed. It must not copy either field's contents into implementation files or planning artifacts.
-
-### D4: Add a dedicated archive runtime-input branch
-
-`openspec instructions archive --change <name> --json` is handled as a workflow instruction branch alongside apply. It:
-
- resolves the selected repo or store using the existing instruction-command options;
- requires and validates the change name so the invocation stays scoped to the intended planning root;
- reads the current config through the shared operation-input helper;
- returns `changeName`, optional `context`, optional `operationGuidance`, and the normal resolved-root envelope;
- does not return a static archive workflow template;
- does not inspect delta specs, update specs, move the change, or invoke `openspec archive`.
-
-Human-readable output shows project context as a required instruction-input section and operation guidance as a separate advisory section. If neither value is configured, the command still succeeds with the change and root metadata so skill behavior is uniform.
-
-Keeping this as an instruction surface makes the runtime contract available immediately while leaving archive execution redesign independent.
-
-### D5: Archive and sync skills consume inputs without changing their flow
-
-After resolving the target change and selected root, the single-change archive skill calls:
-
-```bash
-openspec instructions archive --change "<name>" --json
-```
-
-It must read returned context and apply relevant project facts, conventions, and constraints as a required prompt-level input. It reads and considers returned archive guidance as optional additive advice and follows applicable entries that are compatible with the built-in archive workflow. Explicit user choices, target paths, CLI checks, and command flags are not replaced or inferred from either field. Context conflicts are reported; conflicting or inapplicable guidance is not followed and the reason is explained.
-
-A successful response may omit both optional fields, which means no archive operation inputs are configured. If the command exits non-zero or does not return valid archive-instruction JSON, the single-change skill reports the error and stops before inspecting or writing specs or moving the change. A failed lookup is never treated as an empty successful response.
-
-The bulk archive skill makes the same call once for the selected root, using one selected change to establish context, and applies the returned inputs across that batch. If this lookup exits non-zero or returns invalid archive-instruction JSON, the skill reports the error and stops the batch before inspecting or writing specs or moving any change. It does not change the existing bulk conflict analysis or archive orchestration.
-
-Semantic spec sync keeps its existing artifact contract. The concrete delta spec paths are exactly `artifactPaths.specs.existingOutputPaths` from the selected change's status output. If `artifactPaths.specs` is absent or its concrete output list is empty, that change has no delta specs for this workflow: archive continues without a spec-sync prompt, standalone sync reports that there is nothing to sync, and neither workflow infers delta specs from other artifacts.
-
-When concrete `specs` outputs exist and a write-producing sync will run:
-
-1. Use the same selected change and planning root that supplied the status result.
-2. Call `openspec instructions specs --change "<name>" --json` once immediately before the semantic merge.
-3. Apply only its returned artifact rules to the main specs produced by that merge.
-4. Keep those rules separate from archive operation guidance and unrelated workflow steps.
-
-A valid artifact-instruction response that omits `rules` means that no `specs` rules are configured and the existing semantic merge continues. A non-zero exit or a response that is not valid artifact-instruction JSON is a lookup failure, not an empty rule set. Single-change archive and standalone sync report that error and stop before modifying any main spec; archive also stops before moving the change.
-
-The single-change archive skill fetches this specs-instruction snapshot after sync has been selected and immediately before invoking inline semantic sync. The bulk archive skill resolves every required specs-instruction snapshot after its sync decisions but before the first main-spec write; if any lookup fails, it reports the affected change and stops the whole batch before writing any main spec or moving any change. Archive passes each successful specs-rule snapshot into the inline sync workflow, which reuses it without fetching the same instructions again. When the sync skill is invoked directly, with no archive-supplied snapshot, it fetches current `specs` instructions itself.
-
-For a mixed-schema batch, this decision is made independently for each change. A change whose resolved schema exposes concrete `artifactPaths.specs.existingOutputPaths` participates in spec sync and receives that change's current `specs` rules. A change whose schema has no `specs` artifact, such as a research/design/plan workflow, has no spec sync and continues through the existing archive path.
-
-Artifact rules are not returned from the archive operation-input surface, relabeled as archive guidance, or applied to unrelated archive steps.
-
-The archive, bulk archive, and sync templates retain the existing rule that runtime context, operation guidance, and rule text must not be copied verbatim into specs, change artifacts, summaries, or other files unless the user separately asks for that content. Artifact rules constrain the produced artifact without becoming artifact content.
-
-### D6: Require context consumption while keeping guidance advisory
-
-Current context is a required prompt-level input, not optional-to-ignore metadata. When present, the generated skill must tell the agent to read it and apply relevant project facts, conventions, and constraints.
-
-Operation guidance is optional additive advice. When present, the generated skill must tell the agent to read and consider it and to follow entries that are applicable and compatible with the built-in workflow. If guidance is inapplicable or conflicts with an explicit user choice, resolved path, CLI-controlled state, or command contract, the skill preserves the controlling value and explains why the advice was not followed.
-
-Both semantics remain behavioral contracts for the agent, not enforcement mechanisms. OpenSpec guarantees that it validates the config shape, keeps fields separate from CLI-controlled values, delivers current inputs through the documented instruction surfaces, and leaves existing CLI checks unchanged. Existing checks continue to run wherever the current CLI already owns them. Any invariant that must be non-bypassable belongs in a real CLI check and remains outside this change; stronger archive guarantees require a separate archive execution design.
-
-## Risks / Trade-offs
-
- **Context conflicts with the built-in workflow** -> Require the skill to report the conflict, preserve explicit user choices and CLI-controlled state, validation, paths, and command contracts, and do not claim prompt-level enforcement.
- **Guidance is inapplicable or conflicts with the built-in workflow** -> Keep it advisory and separate, preserve controlling workflow inputs, and explain why the advice was not followed.
- **Generated skills become stale** -> Skills fetch current inputs on every invocation instead of embedding config content.
- **Repo/store roots diverge** -> Instruction commands reuse existing root selection and read one config snapshot from the resolved root.
- **Archive runtime input is mistaken for archive execution** -> Command naming, JSON fields, docs, and tests state that the instruction surface is read-only and performs no archive mutation.
- **Bulk archive spans an unexpected root** -> The skill resolves the batch root first and fetches inputs once for that root; cross-root batching remains outside the current behavior.
- **Artifact rules are mistaken for archive guidance** -> Fetch them only when writing their artifact, keep them out of `operationGuidance`, and test that they do not affect unrelated archive steps.
- **A custom schema has no `specs` artifact** -> Treat it as having no semantic spec-sync input; do not infer delta specs from unrelated artifacts.
- **Archive and inline sync fetch different rule snapshots** -> Archive fetches once and inline sync reuses the supplied specs-rule snapshot; only standalone sync performs its own lookup.
- **A failed instruction lookup is mistaken for absent optional input** -> Require a successful, valid JSON response before continuing; archive-input failures stop before spec inspection or change moves, and specs-instruction failures stop before main-spec writes or change moves.
-
-## Implementation Plan
-
-1. Add typed operation config parsing and tests.
-2. Add the shared runtime-input loader using the root command's single parsed config snapshot.
-3. Extend apply instruction JSON and text output.
-4. Add archive instruction JSON and text output without changing archive execution.
-5. Update single-change archive, bulk archive, and standalone sync templates to fetch current `specs` rules when concrete delta specs exist and reuse the same snapshot during inline sync.
-6. Update generated config help, documentation, template parity fixtures, and end-to-end coverage.
-
-Rollback is a code revert. The config field is additive, and no archive filesystem format or durable project state changes in this change.
-
-## Open Questions
-
-None.
@@ -1,56 +0,0 @@
-## Why
-
-Project configuration reaches agents while they create OpenSpec artifacts, but apply and archive workflows cannot fetch the same current project context or operation-specific working preferences when they run. Generated skills therefore lack a stable runtime input contract and can become disconnected from later configuration changes.
-
-OpenSpec needs a clear separation between project context, artifact requirements, and operation advice. Project `context` supplies facts, conventions, and constraints the agent must apply when relevant. Artifact `rules` continue to describe the artifacts an agent produces, while optional operation guidance provides additive advice about how an agent should conduct apply or archive work. Both apply and archive should fetch their current inputs from OpenSpec at execution time.
-
-## What Changes
-
- Add optional `operations.apply.guidance` and `operations.archive.guidance` configuration for additive operation advice. A skill considers returned guidance and follows it when applicable and compatible with the built-in workflow.
- Keep `rules` artifact-specific and preserve all existing artifact-instruction behavior.
- Extend apply instruction output with separate optional fields for current project context and apply operation guidance.
- Update the apply skill template to consume those current runtime inputs while preserving its existing state-driven workflow.
- Add an archive runtime-input surface through `openspec instructions archive --change <name>` so archive skills can fetch current project context and archive operation guidance when they run.
- Treat a non-zero or invalid archive-input response as blocking: report the error and stop before inspecting or writing specs or moving the change. A successful response with omitted optional fields remains the valid no-input case.
- Update the single-change and bulk archive skill templates to consume current archive inputs without embedding configuration snapshots in generated skill text.
- Keep the existing spec-sync contract: delta specs come from `artifactPaths.specs.existingOutputPaths`; schemas without that artifact do not participate in spec sync.
- When archive-driven or standalone spec sync updates main specs, fetch current `specs` artifact instructions and apply their rules to the semantic merge. Archive passes its fetched specs-rule snapshot into the inline sync workflow; standalone sync fetches the same input itself.
- Treat a non-zero or invalid `specs` instruction response as blocking before any main-spec write or archive move. A successful response that omits `rules` continues with the existing semantic merge.
- Treat current context as a required prompt-level input: the agent must read it and apply relevant project facts, conventions, and constraints.
- Treat operation guidance as optional additive advice: the agent considers it and follows applicable entries, but guidance does not define or replace the built-in workflow.
- Keep current context and operation guidance structurally separate from explicit user choices and CLI-controlled behavior. Context conflicts must be reported; guidance that is inapplicable or conflicts with controlling workflow input is not followed and the reason is explained. Neither field is presented as an enforceable security or validation boundary.
- Validate the `operations` config field independently so one malformed operation entry does not discard otherwise valid project configuration.
-
-This change does not redesign archive execution or the semantic spec-merge algorithm. The existing archive skill orchestration and `openspec archive` command remain intact.
-
-## Capabilities
-
-### New Capabilities
-
- `operation-guidance`: define the `operations.<operation>.guidance` config model, resilient validation, advisory semantics, and runtime delivery for apply and archive
- `cli-archive-instructions`: provide current archive operation inputs in structured JSON and readable text form
- `opsx-apply-skill`: consume current apply context and guidance without changing the built-in apply workflow
- `opsx-bulk-archive-skill`: fetch current archive inputs for a selected batch and apply relevant artifact rules during each spec sync
-
-### Modified Capabilities
-
- `config-loading`: parse operation guidance independently from existing project-config fields
- `context-injection`: expose the latest project context to apply and archive runtime surfaces in addition to artifact instructions
- `cli-artifact-workflow`: include current context and apply operation guidance in schema-aware apply instruction output
- `opsx-archive-skill`: fetch and apply current archive context and guidance, and carry artifact rules into archive-driven spec sync, while preserving the existing archive flow
- `specs-sync-skill`: apply current `specs` artifact rules during standalone sync, while reusing an archive-supplied specs-rule snapshot when invoked inline
-
-## Impact
-
- Project config types, parsing, generated help text, and documentation gain an optional `operations` section.
- Apply JSON and text instruction output gain separate optional `context` and `operationGuidance` fields.
- The apply skill must consume current context as a required prompt-level input and consider current operation guidance as optional additive advice, while CLI-returned state, tasks, progress, and instructions remain structurally unchanged.
- `openspec instructions archive --change <name>` becomes a reserved workflow instruction surface and returns current archive inputs without performing archive work.
- Archive skill templates call the runtime surface at execution time, must apply relevant returned context, consider and follow applicable operation guidance, and do not copy their text into output files.
- Archive and bulk archive stop before spec inspection, spec writes, or change moves when the required archive-input lookup fails or returns invalid JSON.
- Archive-driven and standalone spec sync continue to use `artifactPaths.specs.existingOutputPaths`, fetch current `specs` instructions when delta specs exist, and follow those rules without exposing them as operation guidance.
- Archive, bulk archive, and standalone sync stop before writing main specs when a required `specs` instruction lookup fails or returns invalid JSON; only a valid response with no `rules` means that no artifact rules are configured.
- Schemas without a `specs` artifact, or changes with no concrete `specs` outputs, continue without spec sync and do not infer delta specs from other artifacts.
- Inline sync reuses the specs-rule snapshot supplied by archive, avoiding a second fetch with potentially different config or duplicate warnings.
- Existing artifact-rule configuration and instruction output, archive filesystem behavior, direct archive CLI options, semantic merge ownership, and bulk archive orchestration remain unchanged.
- Tests cover resilient config parsing, runtime freshness, single-read config handling, field separation, required context consumption, advisory operation guidance, conflict reporting, selected-root behavior, output rendering, archive and standalone-sync `specs` rule consumption, failed and invalid instruction responses, no-write/no-move failure behavior, schemas with and without `specs`, mixed-schema batches, and generated-template parity.
@@ -1,60 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Provide current archive operation inputs
-
-The CLI SHALL provide `openspec instructions archive --change <name>` as a read-only workflow instruction surface for current archive operation inputs.
-
-#### Scenario: Archive JSON contains context and guidance
-
- **WHEN** a user runs `openspec instructions archive --change <name> --json`
- **AND** config contains project context and `operations.archive.guidance`
- **THEN** the JSON contains `changeName`, `context`, and `operationGuidance` as separate fields
- **AND** includes the normal resolved-root envelope
-
-#### Scenario: Archive text contains context and guidance
-
- **WHEN** a user runs `openspec instructions archive --change <name>` with configured inputs
- **THEN** text output labels project context as a required instruction input
- **AND** labels operation guidance as separate advisory input
-
-#### Scenario: Archive inputs are absent
-
- **WHEN** config has no non-empty context or archive guidance
- **THEN** the command succeeds with change and root metadata
- **AND** omits both optional fields
-
-#### Scenario: Archive reads current config
-
- **WHEN** config changes between two archive instruction calls
- **THEN** the second output reflects the current context and archive guidance
-
-### Requirement: Scope archive inputs to a valid selected root
-
-The archive instruction surface SHALL require a valid change and use existing repo/store root selection before reading config.
-
-#### Scenario: Change is missing
-
- **WHEN** the archive instruction command is called without `--change`
- **THEN** it returns the existing actionable missing-change error
-
-#### Scenario: Change does not exist in the selected root
-
- **WHEN** the supplied change is absent from the resolved repo or store
- **THEN** the command fails before returning operation inputs
-
-#### Scenario: Store is selected
-
- **WHEN** the command is run with a selected store
- **THEN** change validation and config loading both use that store's planning root
-
-### Requirement: Keep archive instructions read-only
-
-The archive instruction surface SHALL return runtime instruction inputs without performing archive execution work.
-
-#### Scenario: Archive instructions are requested
-
- **WHEN** the command succeeds
- **THEN** it does not inspect or rewrite delta specs
- **AND** does not update main specs
- **AND** does not move or otherwise modify the change
- **AND** does not include the static archive workflow template in JSON output
--- a/Show More
+++ b/Show More