docs(readme): update documentation for new init behavior

- Replace tool list with simplified supported tools section (skills-based) - Update init instructions to document --tools flag, --force, and legacy cleanup - Replace project.md with config.yaml documentation - Update workflow examples to use /opsx:* commands instead of /openspec:* - Add command reference table for slash commands - Update Team Adoption and Updating sections for new workflow - Replace Experimental Features with Workflow Customization section
2026-10-04 06:18:24 +08:00 · 2026-01-23 20:20:32 -08:00
338 changed files with 7336 additions and 38254 deletions
@@ -1,2 +0,0 @@
---
---
@@ -1,7 +0,0 @@
---
-"@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.
@@ -1,11 +0,0 @@
---
-"@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
@@ -1,7 +0,0 @@
---
-"@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.
@@ -3,8 +3,6 @@ name: CI
 on:
  pull_request:
    branches: [main]
-  merge_group:
-    branches: [main]
  push:
    branches: [main]
  workflow_dispatch:
@@ -44,7 +42,7 @@ jobs:
    name: Test
    runs-on: ubuntu-latest
    timeout-minutes: 10
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    if: github.event_name == 'pull_request'

    steps:
      - name: Checkout code
@@ -83,7 +81,7 @@ jobs:
    name: Test (${{ matrix.label }})
    runs-on: ${{ matrix.os }}
    timeout-minutes: 15
-    if: github.event_name == 'push'
+    if: github.event_name != 'pull_request'
    strategy:
      fail-fast: false
      matrix:
@@ -192,10 +190,10 @@ jobs:
        uses: actions/checkout@v4

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

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

      - name: Build with Nix
        run: nix build
@@ -231,7 +229,7 @@ jobs:
      - name: Check flake.nix modifications
        run: |
          if git diff --quiet flake.nix; then
-            echo "ℹ️  flake.nix unchanged (hash already up-to-date)"
+            echo "⚠️  Warning: flake.nix was not modified by update script"
          else
            echo "✅ flake.nix was updated by script"
            git diff flake.nix
@@ -244,7 +242,7 @@ jobs:
  validate-changesets:
    name: Validate Changesets
    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request' || github.event_name == 'merge_group'
+    if: github.event_name == 'pull_request'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
@@ -277,7 +275,7 @@ jobs:
    name: All checks passed
    runs-on: ubuntu-latest
    needs: [test_pr, lint, nix-flake-validate]
-    if: always() && (github.event_name == 'pull_request' || github.event_name == 'merge_group')
+    if: always() && github.event_name == 'pull_request'
    steps:
      - name: Verify all checks passed
        run: |
@@ -303,7 +301,7 @@ jobs:
    name: All checks passed
    runs-on: ubuntu-latest
    needs: [test_matrix, lint, nix-flake-validate]
-    if: always() && github.event_name == 'push'
+    if: always() && github.event_name != 'pull_request'
    steps:
      - name: Verify all checks passed
        run: |
@@ -0,0 +1,149 @@
+name: Polish Release Notes
+
+# Uses Claude to transform raw changelog into polished release notes.
+# Triggered automatically by release-prepare after publishing, or manually.
+on:
+  repository_dispatch:
+    types: [polish-release-notes]
+  workflow_dispatch:
+    inputs:
+      tag_name:
+        description: 'Release tag to polish (e.g., v0.18.0)'
+        required: true
+        type: string
+
+env:
+  # repository_dispatch passes tag via client_payload, workflow_dispatch via inputs
+  TAG_NAME: ${{ github.event.client_payload.tag_name || inputs.tag_name }}
+
+permissions:
+  contents: write
+
+jobs:
+  polish:
+    # Only run on the main repo, not forks
+    if: github.repository == 'Fission-AI/OpenSpec'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get current release body
+        id: get-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release view "${{ env.TAG_NAME }}" --json body -q '.body' > current-notes.md
+          echo "Fetched release notes for ${{ env.TAG_NAME }}"
+
+      - name: Transform release notes with Claude
+        uses: anthropics/claude-code-action@v1
+        id: claude
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          claude_args: "--allowedTools Write,Read"
+          prompt: |
+            Transform the changelog in `current-notes.md` into release notes for OpenSpec ${{ env.TAG_NAME }}.
+
+            ## Voice
+
+            OpenSpec is a developer tool. Write like you're talking to a peer:
+            - Direct and practical, not marketing copy
+            - Focus on what changed and why it matters
+            - Skip the hype, keep it real
+
+            ## Output
+
+            Create two files:
+
+            ### 1. `release-title.txt`
+
+            A short title in this format:
+            ```
+            ${{ env.TAG_NAME }} - [1-4 words describing the release]
+            ```
+
+            Examples:
+            - `v0.18.0 - OPSX Experimental Workflow`
+            - `v0.16.0 - Antigravity, iFlow Support`
+            - `v0.15.0 - Gemini CLI, RooCode`
+
+            Rules for title:
+            - Lead with the most notable addition
+            - 1-4 words after the dash, no fluff
+            - If multiple features, comma-separate the top 2
+            - For bugfix-only releases, use something like `v0.17.2 - Pre-commit Hook Fix`
+
+            ### 2. `polished-notes.md`
+
+            ```markdown
+            ## What's New in ${{ env.TAG_NAME }}
+
+            [One sentence: what's the theme of this release?]
+
+            ### New
+
+            - **Feature name** - What it does and why you'd use it
+
+            ### Improved
+
+            - **Area** - What got better
+
+            ### Fixed
+
+            - What was broken, now works
+            ```
+
+            Omit empty sections.
+
+            ## Rules
+
+            1. Write for developers using OpenSpec with AI coding assistants
+            2. Remove commit hashes (like `eb152eb:`), PR numbers, and changesets wrappers (`### Minor Changes`)
+            3. Lead with what users can do, not implementation details
+            4. One to two sentences per item, max
+            5. Use **bold** for feature/area names
+            6. Skip internal changes (CI, refactors, tests) unless they affect users
+            7. If the input is already well-formatted, just clean up structure and remove noise
+
+            ## Example
+
+            Before:
+            ```
+            ### Minor Changes
+            - 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system
+              **New Commands:**
+              - `/opsx:ff` - Fast-forward through artifact creation
+            ```
+
+            After (polished-notes.md):
+            ```
+            ### New
+
+            - **Fast-forward mode** - Generate all planning artifacts at once with `/opsx:ff`. Useful when you already know what you're building.
+            ```
+
+            After (release-title.txt):
+            ```
+            v0.18.0 - OPSX Experimental Workflow
+            ```
+
+            Write both files. No other output.
+
+      - name: Update release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          TAG="${{ env.TAG_NAME }}"
+
+          if [ -f "polished-notes.md" ] && [ -f "release-title.txt" ]; then
+            TITLE=$(cat release-title.txt)
+            gh release edit "$TAG" --title "$TITLE" --notes-file polished-notes.md
+            echo "Updated: $TITLE"
+          elif [ -f "polished-notes.md" ]; then
+            gh release edit "$TAG" --notes-file polished-notes.md
+            echo "Updated notes (title unchanged)"
+          else
+            echo "No changes generated, keeping original"
+          fi
@@ -58,3 +58,19 @@ jobs:
        env:
          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
          # npm authentication handled via OIDC trusted publishing (no token needed)
+
+      # Trigger release notes polishing after a release is published
+      # Uses repository_dispatch instead of workflow_dispatch because:
+      # - workflow_dispatch requires actions:write permission (GitHub App doesn't have it)
+      # - repository_dispatch works with contents:write (which we already have)
+      - name: Polish release notes
+        if: steps.changesets.outputs.published == 'true'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          # Get version from package.json (just bumped by changesets)
+          TAG="v$(jq -r .version package.json)"
+          echo "Triggering polish workflow for $TAG"
+          gh api repos/${{ github.repository }}/dispatches \
+            --method POST \
+            --input - <<< "{\"event_type\":\"polish-release-notes\",\"client_payload\":{\"tag_name\":\"$TAG\"}}"
@@ -149,13 +149,3 @@ CLAUDE.md
 # Pnpm
 .pnpm-store/
 result
-
-# OpenCode
-.opencode/
-opencode.json
-
-# Codex
-.codex/
-
-# Bob
-.bob/
@@ -1,194 +1,5 @@
 # @fission-ai/openspec

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

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

-<details>
-<summary><strong>The most loved spec framework.</strong></summary>
-
-[![Stars](https://img.shields.io/github/stars/Fission-AI/OpenSpec?style=flat-square&label=Stars)](https://github.com/Fission-AI/OpenSpec/stargazers)
-[![Downloads](https://img.shields.io/npm/dm/@fission-ai/openspec?style=flat-square&label=Downloads/mo)](https://www.npmjs.com/package/@fission-ai/openspec)
-[![Contributors](https://img.shields.io/github/contributors/Fission-AI/OpenSpec?style=flat-square&label=Contributors)](https://github.com/Fission-AI/OpenSpec/graphs/contributors)
-
-</details>
-<p></p>
-Our philosophy:
-
-```text
-→ fluid not rigid
-→ iterative not waterfall
-→ easy not complex
-→ built for brownfield not just greenfield
-→ scalable from personal projects to enterprises
-```
-
-> [!TIP]
-> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
->
-> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
-
-<p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
-</p>
-
-<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
-
-## See it in action
-
-```text
-You: /opsx:propose add-dark-mode
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md — why we're doing this, what's changing
-     ✓ specs/       — requirements and scenarios
-     ✓ design.md    — technical approach
-     ✓ tasks.md     — implementation checklist
-     Ready for implementation!
-
-You: /opsx:apply
-AI:  Implementing tasks...
-     ✓ 1.1 Add theme context provider
-     ✓ 1.2 Create toggle component
-     ✓ 2.1 Add CSS variables
-     ✓ 2.2 Wire up localStorage
-     All tasks complete!
-
-You: /opsx:archive
-AI:  Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
-     Specs updated. Ready for the next feature.
-```
-
-<details>
-<summary><strong>OpenSpec Dashboard</strong></summary>
-
 <p align="center">
  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
 </p>

-</details>
+<p align="center">
+  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
+</p>

-## Quick Start
+<p align="center">
+  <sub>🧪 <strong>OPSX Workflow</strong> — schema-driven, hackable, fluid. See <a href="docs/experimental-workflow.md">workflow docs</a> for details.</sub>
+</p>

-**Requires Node.js 20.19.0 or higher.**
-
-Install OpenSpec globally:
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-Then navigate to your project directory and initialize:
-
-```bash
-cd your-project
-openspec init
-```
-
-Now tell your AI: `/opsx:propose <what-you-want-to-build>`
-
-If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
-
-> [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
->
-> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
-
-## Docs
-
-→ **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[Commands](docs/commands.md)**: slash commands & skills<br>
-→ **[CLI](docs/cli.md)**: terminal reference<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
-
-
-## Community schemas
-
-Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) handles tool integrations.
-
-→ **[Browse the catalog](docs/customization.md#community-schemas)** in the customization docs.
+# OpenSpec

+OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**

 ## Why OpenSpec?

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

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

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

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

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

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

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

-**Upgrade the package**
+1. Draft a change proposal that captures the spec updates you want.
+2. Review the proposal with your AI assistant until everyone agrees.
+3. Implement tasks that reference the agreed specs.
+4. Archive the change to merge the approved updates back into the source-of-truth specs.
+```
+
+## Getting Started
+
+### Supported AI Tools
+
+OpenSpec generates **Agent Skills** and **/opsx:\* slash commands** for supported tools during `openspec init`.
+
+<details>
+<summary><strong>Tools with Agent Skills + Slash Commands</strong> (click to expand)</summary>
+
+These tools support the full OpenSpec workflow with skills and commands:
+
+| Tool | Skills Location | Commands |
+|------|-----------------|----------|
+| **Claude Code** | `.claude/skills/` | `/opsx:new`, `/opsx:apply`, `/opsx:archive`, etc. |
+| **Cursor** | `.cursor/skills/` | `/opsx:*` commands via prompts |
+
+Run `openspec init` and select the tools you use. Skills and commands are generated automatically.
+
+</details>
+
+<details>
+<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
+
+Tools that support AGENTS.md can follow OpenSpec workflows by reading `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
+
+| Tools |
+|-------|
+| Amp • Jules • Others |
+
+</details>
+
+### Install & Initialize
+
+#### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
+
+#### Step 1: Install the CLI globally
+
+**Option A: Using npm**

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

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

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

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

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

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

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

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

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

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

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

- Install dependencies: `pnpm install`
- Build: `pnpm run build`
- Test: `pnpm test`
- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
- Conventional commits (one-line): `type(scope): subject`
+**What happens during initialization:**
+- You'll see an interactive tool selector to pick AI tools (Claude Code, Cursor, etc.)
+- OpenSpec generates **Agent Skills** in tool-specific directories (e.g., `.claude/skills/`)
+- **/opsx:\* slash commands** are created for each selected tool
+- A `openspec/config.yaml` file is created for project configuration
+- The `openspec/` directory structure is created (specs, changes, archive)

-## Other
+**Legacy upgrade:** If you have files from an older OpenSpec version, init will detect them and offer to clean up automatically. Use `--force` to skip the confirmation prompt.
+
+**Non-interactive mode:** For CI or scripted setups:
+```bash
+openspec init --tools claude,cursor  # Specific tools
+openspec init --tools all            # All supported tools
+openspec init --tools none           # Skip tool setup
+```
+
+**After setup:**
+- Run `/opsx:new` to start your first change
+- Run `openspec list` to verify the setup and view any active changes
+- Restart your IDE for slash commands to take effect
+
+### Optional: Configure Project Context
+
+After `openspec init`, you can customize `openspec/config.yaml` to inject project-specific context into all artifacts:
+
+```yaml
+# openspec/config.yaml
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js
+  Testing: Vitest for unit tests
+  Style: ESLint with Prettier
+
+rules:
+  proposal:
+    - Include rollback plan
+  specs:
+    - Use Given/When/Then format for scenarios
+```
+
+This context is automatically included in artifact instructions, helping the AI understand your project's conventions.
+
+### Create Your First Change
+
+Here's a real example showing the complete OpenSpec workflow using `/opsx:*` commands.
+
+#### 1. Start a New Change
+```text
+You: /opsx:new
+
+AI:  What do you want to build?
+You: Add profile search filters by role and team
+
+AI:  I'll create a new change for profile filters.
+     *Creates openspec/changes/add-profile-filters/ with proposal.md*
+```
+
+#### 2. Build Out Artifacts
+Use `/opsx:continue` to create artifacts one at a time, or `/opsx:ff` to fast-forward through all planning artifacts:
+
+```text
+You: /opsx:continue
+
+AI:  Proposal is done. Ready to create: specs, design
+     Which artifact should I create?
+You: specs
+
+AI:  *Creates specs with requirements and scenarios*
+```
+
+Or fast-forward through everything:
+```text
+You: /opsx:ff add-profile-filters
+
+AI:  *Creates proposal → specs → design → tasks in sequence*
+```
+
+#### 3. Verify & Review
+```bash
+openspec list                             # Confirm the change folder exists
+openspec validate add-profile-filters     # Validate spec formatting
+openspec show add-profile-filters         # Review proposal, tasks, and spec delta
+```
+
+#### 4. Implement the Change
+```text
+You: /opsx:apply
+
+AI:  I'll work through the tasks in the add-profile-filters change.
+     *Implements tasks, marking them complete as it goes*
+```
+
+**Key feature:** If you discover issues during implementation, you can update specs, design, or tasks — then continue. No phase gates.
+
+#### 5. Archive the Completed Change
+```text
+You: /opsx:archive
+
+AI:  I'll archive the add-profile-filters change.
+     *Runs: openspec archive add-profile-filters --yes*
+     ✓ Change archived. Specs updated. Ready for the next feature!
+```
+
+Or run directly in terminal:
+```bash
+openspec archive add-profile-filters --yes
+```
+
+## Command Reference
+
+### Slash Commands (in your AI tool)
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through ideas, investigate problems, clarify requirements |
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward — create all planning artifacts at once |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
+| `/opsx:sync` | Sync delta specs to main specs |
+| `/opsx:archive` | Archive when done |
+| `/opsx:verify` | Verify implementation matches change artifacts |
+
+### CLI Commands (in terminal)
+
+```bash
+openspec init               # Initialize OpenSpec with skills and commands
+openspec list               # View active change folders
+openspec view               # Interactive dashboard of specs and changes
+openspec show <change>      # Display change details (proposal, tasks, spec updates)
+openspec validate <change>  # Check spec formatting and structure
+openspec archive <change> [--yes|-y]   # Move a completed change into archive/
+openspec update             # Refresh skills and commands for configured tools
+```
+
+## Example: How AI Creates OpenSpec Files
+
+When you ask your AI assistant to "add two-factor authentication", it creates:
+
+```
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md           # Current auth spec (if exists)
+└── changes/
+    └── add-2fa/              # AI creates this entire structure
+        ├── proposal.md       # Why and what changes
+        ├── tasks.md          # Implementation checklist
+        ├── design.md         # Technical decisions (optional)
+        └── specs/
+            └── auth/
+                └── spec.md   # Delta showing additions
+```
+
+### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management.
+
+## Requirements
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN a JWT is returned
+```
+
+### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required
+```
+
+### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column to users table
+- [ ] 1.2 Create OTP verification logs table
+
+## 2. Backend Implementation  
+- [ ] 2.1 Add OTP generation endpoint
+- [ ] 2.2 Modify login flow to require OTP
+- [ ] 2.3 Add OTP verification endpoint
+
+## 3. Frontend Updates
+- [ ] 3.1 Create OTP input component
+- [ ] 3.2 Update login flow UI
+```
+
+**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
+
+## Understanding OpenSpec Files
+
+### Delta Format
+
+Deltas are "patches" that show how specs change:
+
+- **`## ADDED Requirements`** - New capabilities
+- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
+- **`## REMOVED Requirements`** - Deprecated features
+
+**Format requirements:**
+- Use `### Requirement: <name>` for headers
+- Every requirement needs at least one `#### Scenario:` block
+- Use SHALL/MUST in requirement text
+
+## How OpenSpec Compares
+
+### vs. spec-kit
+OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
+
+### vs. Kiro.dev
+OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
+
+### vs. No Specs
+Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
+
+## Team Adoption
+
+1. **Initialize OpenSpec** – Run `openspec init` in your repo and select your team's tools.
+2. **Start with new features** – Use `/opsx:new` to capture upcoming work as change proposals.
+3. **Grow incrementally** – Each change archives into living specs that document your system.
+4. **Stay flexible** – Different teammates can use Claude Code, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
+
+Run `openspec update` to refresh skills and commands when upgrading OpenSpec or adding new tools.
+
+## Updating OpenSpec
+
+1. **Upgrade the package**
+   ```bash
+   npm install -g @fission-ai/openspec@latest
+   ```
+2. **Refresh skills and commands**
+   ```bash
+   openspec update
+   ```
+   This regenerates skills and slash commands for all configured tools.
+
+3. **Restart your IDE** for slash commands to take effect.
+
+## Workflow Customization

 <details>
-<summary><strong>Telemetry</strong></summary>
+<summary><strong>Custom Schemas & Templates</strong></summary>

-OpenSpec collects anonymous usage stats.
+OpenSpec uses a **schema-driven workflow** that you can customize:
+
+**Why customize:**
+- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
+- **Granular** — each artifact has its own instructions, test and tweak individually
+- **Customizable** — define your own workflows, artifacts, and dependencies
+
+**Built-in schemas:**
+- `spec-driven` (default): proposal → specs → design → tasks
+- `tdd`: tests → implementation → docs
+
+**Create custom schemas:**
+```bash
+openspec schema init my-workflow     # Create new schema interactively
+openspec schema fork spec-driven my-workflow  # Fork existing schema
+openspec schemas                     # List available schemas
+```
+
+Schemas are stored in `openspec/schemas/` (project) or `~/.local/share/openspec/schemas/` (global).
+
+[Full documentation →](docs/experimental-workflow.md)
+
+</details>
+
+<details>
+<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>

 We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.

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

 </details>

+## Contributing
+
+- Install dependencies: `pnpm install`
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
+- Conventional commits (one-line): `type(scope): subject`
+
 <details>
 <summary><strong>Maintainers & Advisors</strong></summary>

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

 </details>

-
-
 ## License

 MIT
@@ -1,475 +0,0 @@
-<p align="center">
-  <a href="https://github.com/Fission-AI/OpenSpec">
-    <picture>
-      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
-      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
-      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
-    </picture>
-  </a>
-  
-</p>
-<p align="center">Spec-driven development for AI coding assistants.</p>
-<p align="center">
-  <a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
-  <a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
-  <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
-  <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
-  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
-</p>
-
-<p align="center">
-  <img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
-</p>
-
-<p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
-</p>
-
-<p align="center">
-  <sub>🧪 <strong>New:</strong> <a href="docs/opsx.md">OPSX Workflow</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
-</p>
-
-# OpenSpec
-
-OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
-
-## Why OpenSpec?
-
-AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
-
-Key outcomes:
- Human and AI stakeholders agree on specs before work begins.
- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
- Shared visibility into what's proposed, active, or archived.
- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
-
-## How OpenSpec compares (at a glance)
-
- **Lightweight**: simple workflow, no API keys, minimal setup.
- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
-
-See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
-
-## How It Works
-
-```
-┌────────────────────┐
-│ Draft Change       │
-│ Proposal           │
-└────────┬───────────┘
-         │ share intent with your AI
-         ▼
-┌────────────────────┐
-│ Review & Align     │
-│ (edit specs/tasks) │◀──── feedback loop ──────┐
-└────────┬───────────┘                          │
-         │ approved plan                        │
-         ▼                                      │
-┌────────────────────┐                          │
-│ Implement Tasks    │──────────────────────────┘
-│ (AI writes code)   │
-└────────┬───────────┘
-         │ ship the change
-         ▼
-┌────────────────────┐
-│ Archive & Update   │
-│ Specs (source)     │
-└────────────────────┘
-
-1. Draft a change proposal that captures the spec updates you want.
-2. Review the proposal with your AI assistant until everyone agrees.
-3. Implement tasks that reference the agreed specs.
-4. Archive the change to merge the approved updates back into the source-of-truth specs.
-```
-
-## Getting Started
-
-### Supported AI Tools
-
-<details>
-<summary><strong>Native Slash Commands</strong> (click to expand)</summary>
-
-These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
-
-| Tool | Commands |
-|------|----------|
-| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) |
-| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) |
-| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) |
-| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
-| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
-| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
-| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
-| **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.continue/prompts/`) |
-| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
-| **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
-| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) |
-| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) |
-| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
-| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) |
-| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
-| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
-| **Qoder** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com) |
-| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) |
-| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) |
-| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
-
-Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
-
-</details>
-
-<details>
-<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
-
-These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
-
-| Tools |
-|-------|
-| Amp • Jules • Others |
-
-</details>
-
-### Install & Initialize
-
-#### Prerequisites
- **Node.js >= 20.19.0** - Check your version with `node --version`
-
-#### Step 1: Install the CLI globally
-
-**Option A: Using npm**
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-Verify installation:
-```bash
-openspec --version
-```
-
-**Option B: Using Nix (NixOS and Nix package manager)**
-
-Run OpenSpec directly without installation:
-```bash
-nix run github:Fission-AI/OpenSpec -- init
-```
-
-Or install to your profile:
-```bash
-nix profile install github:Fission-AI/OpenSpec
-```
-
-Or add to your development environment in `flake.nix`:
-```nix
-{
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
-    openspec.url = "github:Fission-AI/OpenSpec";
-  };
-
-  outputs = { nixpkgs, openspec, ... }: {
-    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
-      buildInputs = [ openspec.packages.x86_64-linux.default ];
-    };
-  };
-}
-```
-
-Verify installation:
-```bash
-openspec --version
-```
-
-#### Step 2: Initialize OpenSpec in your project
-
-Navigate to your project directory:
-```bash
-cd my-project
-```
-
-Run the initialization:
-```bash
-openspec init
-```
-
-**What happens during initialization:**
- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
- A new `openspec/` directory structure is created in your project
-
-**After setup:**
- Primary AI tools can trigger `/openspec` workflows without additional configuration
- Run `openspec list` to verify the setup and view any active changes
- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup,
-  so a fresh launch ensures they appear
-
-### Optional: Populate Project Context
-
-After `openspec init` completes, you'll receive a suggested prompt to help populate your project context:
-
-```text
-Populate your project context:
-"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions"
-```
-
-Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes.
-
-### Create Your First Change
-
-Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
-
-#### 1. Draft the Proposal
-Start by asking your AI to create a change proposal:
-
-```text
-You: Create an OpenSpec change proposal for adding profile search filters by role and team
-     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
-
-AI:  I'll create an OpenSpec change proposal for profile filters.
-     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
-```
-
-#### 2. Verify & Review
-Check that the change was created correctly and review the proposal:
-
-```bash
-$ openspec list                             # Confirm the change folder exists
-$ openspec validate add-profile-filters     # Validate spec formatting
-$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
-```
-
-#### 3. Refine the Specs
-Iterate on the specifications until they match your needs:
-
-```text
-You: Can you add acceptance criteria for the role and team filters?
-
-AI:  I'll update the spec delta with scenarios for role and team filters.
-     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
-```
-
-#### 4. Implement the Change
-Once specs look good, start implementation:
-
-```text
-You: The specs look good. Let's implement this change.
-     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
-
-AI:  I'll work through the tasks in the add-profile-filters change.
-     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
-     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
-```
-
-#### 5. Archive the Completed Change
-After implementation is complete, archive the change:
-
-```text
-AI:  All tasks are complete. The implementation is ready.
-
-You: Please archive the change
-     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
-
-AI:  I'll archive the add-profile-filters change.
-    *Runs: openspec archive add-profile-filters --yes*
-     ✓ Change archived successfully. Specs updated. Ready for the next feature!
-```
-
-Or run the command yourself in terminal:
-```bash
-$ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
-```
-
-**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
-
-## Command Reference
-
-```bash
-openspec list               # View active change folders
-openspec view               # Interactive dashboard of specs and changes
-openspec show <change>      # Display change details (proposal, tasks, spec updates)
-openspec validate <change>  # Check spec formatting and structure
-openspec archive <change> [--yes|-y]   # Move a completed change into archive/ (non-interactive with --yes)
-```
-
-## Example: How AI Creates OpenSpec Files
-
-When you ask your AI assistant to "add two-factor authentication", it creates:
-
-```
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md           # Current auth spec (if exists)
-└── changes/
-    └── add-2fa/              # AI creates this entire structure
-        ├── proposal.md       # Why and what changes
-        ├── tasks.md          # Implementation checklist
-        ├── design.md         # Technical decisions (optional)
-        └── specs/
-            └── auth/
-                └── spec.md   # Delta showing additions
-```
-
-### AI-Generated Spec (created in `openspec/specs/auth/spec.md`):
-
-```markdown
-# Auth Specification
-
-## Purpose
-Authentication and session management.
-
-## Requirements
-### Requirement: User Authentication
-The system SHALL issue a JWT on successful login.
-
-#### Scenario: Valid credentials
- WHEN a user submits valid credentials
- THEN a JWT is returned
-```
-
-### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`):
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
-
-#### Scenario: OTP required
- WHEN a user submits valid credentials
- THEN an OTP challenge is required
-```
-
-### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`):
-
-```markdown
-## 1. Database Setup
- [ ] 1.1 Add OTP secret column to users table
- [ ] 1.2 Create OTP verification logs table
-
-## 2. Backend Implementation  
- [ ] 2.1 Add OTP generation endpoint
- [ ] 2.2 Modify login flow to require OTP
- [ ] 2.3 Add OTP verification endpoint
-
-## 3. Frontend Updates
- [ ] 3.1 Create OTP input component
- [ ] 3.2 Update login flow UI
-```
-
-**Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase.
-
-## Understanding OpenSpec Files
-
-### Delta Format
-
-Deltas are "patches" that show how specs change:
-
- **`## ADDED Requirements`** - New capabilities
- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
- **`## REMOVED Requirements`** - Deprecated features
-
-**Format requirements:**
- Use `### Requirement: <name>` for headers
- Every requirement needs at least one `#### Scenario:` block
- Use SHALL/MUST in requirement text
-
-## How OpenSpec Compares
-
-### vs. spec-kit
-OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
-
-### vs. Kiro.dev
-OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
-
-### vs. No Specs
-Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
-
-## Team Adoption
-
-1. **Initialize OpenSpec** – Run `openspec init` in your repo.
-2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
-3. **Grow incrementally** – Each change archives into living specs that document your system.
-4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
-
-Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
-
-## Updating OpenSpec
-
-1. **Upgrade the package**
-   ```bash
-   npm install -g @fission-ai/openspec@latest
-   ```
-2. **Refresh agent instructions**
-   - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
-
-## Experimental Features
-
-<details>
-<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
-
-**Why this exists:**
- Standard workflow is locked down — you can't tweak instructions or customize
- When AI output is bad, you can't improve the prompts yourself
- Same workflow for everyone, no way to match how your team works
-
-**What's different:**
- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
- **Granular** — each artifact has its own instructions, test and tweak individually
- **Customizable** — define your own workflows, artifacts, and dependencies
- **Fluid** — no phase gates, update any artifact anytime
-
-```
-You can always go back:
-
-  proposal ──→ specs ──→ design ──→ tasks ──→ implement
-     ▲           ▲          ▲                    │
-     └───────────┴──────────┴────────────────────┘
-```
-
-| Command | What it does |
-|---------|--------------|
-| `/opsx:new` | Start a new change |
-| `/opsx:continue` | Create the next artifact (based on what's ready) |
-| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
-| `/opsx:apply` | Implement tasks, updating artifacts as needed |
-| `/opsx:archive` | Archive when done |
-
-**Setup:** `openspec experimental`
-
-[Full documentation →](docs/opsx.md)
-
-</details>
-
-<details>
-<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>
-
-We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
-
-**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
-
-</details>
-
-## Contributing
-
- Install dependencies: `pnpm install`
- Build: `pnpm run build`
- Test: `pnpm test`
- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
- Conventional commits (one-line): `type(scope): subject`
-
-<details>
-<summary><strong>Maintainers & Advisors</strong></summary>
-
-See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and advisors who help guide the project.
-
-</details>
-
-## License
-
-MIT
@@ -1,470 +0,0 @@
-# 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.
-```
@@ -1,67 +0,0 @@
-# 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.
@@ -0,0 +1,597 @@
+# POC-OpenSpec-Core Analysis
+
+---
+
+## Design Decisions & Terminology
+
+### Philosophy: Not a Workflow System
+
+This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
+
+| What it's NOT | What it IS |
+|---------------|------------|
+| Linear step-by-step progression | Exploratory, iterative planning |
+| Bureaucratic checkpoints | Enablers that unlock possibilities |
+| "You must complete step 1 first" | "Here's what you could create now" |
+| Form-filling | Fluid document creation |
+
+**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
+
+### Terminology
+
+| Term | Definition | Example |
+|------|------------|---------|
+| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
+| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
+| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
+| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
+
+### Hierarchy
+
+```
+Schema (defines) ──→ Artifacts (guided by) ──→ Templates
+```
+
+- **Schema** = the artifact graph (what exists, dependencies)
+- **Artifact** = a document to produce
+- **Template** = instructions for creating that artifact
+
+### Schema Variations
+
+Schemas can vary across multiple dimensions:
+
+| Dimension | Examples |
+|-----------|----------|
+| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
+| Version | `v1`, `v2`, `v3` |
+| Language | `en`, `zh`, `es` |
+| Custom | `team-alpha`, `experimental` |
+
+### Schema Resolution (XDG Standard)
+
+Schemas follow the XDG Base Directory Specification with a 2-level resolution:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # Global user override
+2. <package>/schemas/<name>/schema.yaml                    # Built-in defaults
+```
+
+**Platform-specific paths:**
+- Unix/macOS: `~/.local/share/openspec/schemas/`
+- Windows: `%LOCALAPPDATA%/openspec/schemas/`
+- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set)
+
+**Why XDG?**
+- Schemas are workflow definitions (data), not user preferences (config)
+- Built-ins baked into package, never auto-copied
+- Users customize by creating files in global data dir
+- Consistent with modern CLI tooling standards
+
+### Template Inheritance (2 Levels Max)
+
+Templates are co-located with schemas in a `templates/` subdirectory:
+
+```
+1. ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+2. <package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+```
+
+**Rules:**
+- User overrides take precedence over package built-ins
+- A CLI command shows resolved paths (no guessing)
+- No inheritance between schemas (copy if you need to diverge)
+- Templates are always co-located with their schema
+
+**Why this matters:**
+- Avoids "where does this come from?" debugging
+- No implicit magic that works until it doesn't
+- Schema + templates form a cohesive unit
+
+---
+
+## Executive Summary
+
+This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+
+The system answers:
+- "What artifacts exist for this change?"
+- "What could I create next?" (not "what must I create")
+- "What's blocking X?" (informational, not prescriptive)
+
+---
+
+## Core Components
+
+### 1. ArtifactGraph (Slice 1 - COMPLETE)
+
+The dependency graph engine with XDG-compliant schema resolution.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Model artifacts as a DAG | Artifact with `requires: string[]` |
+| Track completion state | `Set<string>` for completed artifacts |
+| Calculate build order | Kahn's algorithm (topological sort) |
+| Find ready artifacts | Check if all dependencies are in `completed` set |
+| Resolve schemas | XDG global → package built-ins |
+
+**Key Data Structures (Zod-validated):**
+
+```typescript
+// Zod schemas define types + validation
+const ArtifactSchema = z.object({
+  id: z.string().min(1),
+  generates: z.string().min(1),      // e.g., "proposal.md" or "specs/*.md"
+  description: z.string(),
+  template: z.string(),              // path to template file
+  requires: z.array(z.string()).default([]),
+});
+
+const SchemaYamlSchema = z.object({
+  name: z.string().min(1),
+  version: z.number().int().positive(),
+  description: z.string().optional(),
+  artifacts: z.array(ArtifactSchema).min(1),
+});
+
+// Derived types
+type Artifact = z.infer<typeof ArtifactSchema>;
+type SchemaYaml = z.infer<typeof SchemaYamlSchema>;
+```
+
+**Key Methods:**
+- `resolveSchema(name)` - Load schema with XDG fallback
+- `ArtifactGraph.fromSchema(schema)` - Build graph from schema
+- `detectState(graph, changeDir)` - Scan filesystem for completion
+- `getNextArtifacts(graph, completed)` - Find artifacts ready to create
+- `getBuildOrder(graph)` - Topological sort of all artifacts
+- `getBlocked(graph, completed)` - Artifacts with unmet dependencies
+
+---
+
+### 2. Change Utilities (Slice 2)
+
+Simple utility functions for programmatic change creation. No class, no abstraction layer.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Create changes | Create dirs under `openspec/changes/<name>/` with README |
+| Name validation | Enforce kebab-case naming |
+
+**Key Paths:**
+
+```
+openspec/changes/<name>/   → Change instances with artifacts (project-level)
+```
+
+**Key Functions** (`src/utils/change-utils.ts`):
+- `createChange(projectRoot, name, description?)` - Create new change directory + README
+- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }`
+
+**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is.
+
+---
+
+### 3. InstructionLoader (Slice 3)
+
+Template resolution and instruction enrichment.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) |
+| Build dynamic context | Gather dependency status, change info |
+| Enrich templates | Inject context into base templates |
+| Generate status reports | Formatted markdown with progress |
+
+**Key Class - ChangeState:**
+
+```
+ChangeState {
+  changeName: string
+  changeDir: string
+  graph: ArtifactGraph
+  completed: Set<string>
+
+  // Methods
+  getNextSteps(): string[]
+  getStatus(artifactId): ArtifactStatus
+  isComplete(): boolean
+}
+```
+
+**Key Functions:**
+- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
+- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
+
+---
+
+### 4. CLI (Slice 4)
+
+User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
+
+| Command | Function | Status |
+|---------|----------|--------|
+| `status --change <id>` | Show change progress (artifact graph) | **NEW** |
+| `next --change <id>` | Show artifacts ready to create | **NEW** |
+| `instructions <artifact> --change <id>` | Get enriched instructions for artifact | **NEW** |
+| `list` | List all changes | EXISTS (`openspec change list`) |
+| `new <name>` | Create change | **NEW** (uses `createChange()`) |
+| `init` | Initialize structure | EXISTS (`openspec init`) |
+| `templates --change <id>` | Show resolved template paths | **NEW** |
+
+**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
+
+**Existing CLI commands** (not part of this slice):
+- `openspec change list` / `openspec change show <id>` / `openspec change validate <id>`
+- `openspec list --changes` / `openspec list --specs`
+- `openspec view` (dashboard)
+- `openspec init` / `openspec archive <change>`
+
+---
+
+### 5. Claude Commands
+
+Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
+
+| Command | Purpose |
+|---------|---------|
+| `/status` | Show change progress |
+| `/next` | Show what's ready to create |
+| `/run [artifact]` | Execute a specific step (power users) |
+| `/list` | List all changes |
+| `/new <name>` | Create a new change |
+| `/init` | Initialize structure |
+
+**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
+1. Infers change from conversation (confirms if uncertain)
+2. Infers artifact from request
+3. Calls CLI with explicit `--change` parameter
+4. Creates artifact following instructions
+
+This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
+
+**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
+
+---
+
+## Component Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PRESENTATION LAYER                       │
+│  ┌──────────────┐                    ┌────────────────────┐ │
+│  │     CLI      │ ←─shell exec───────│ Claude Commands    │ │
+│  └──────┬───────┘                    └────────────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+          │ imports
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    ORCHESTRATION LAYER                       │
+│  ┌────────────────────┐        ┌──────────────────────────┐ │
+│  │ InstructionLoader  │        │  change-utils (Slice 2)  │ │
+│  │    (Slice 3)       │        │  createChange()          │ │
+│  └─────────┬──────────┘        │  validateChangeName()    │ │
+│            │                   └──────────────────────────┘ │
+└────────────┼────────────────────────────────────────────────┘
+             │ uses
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CORE LAYER                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │               ArtifactGraph (Slice 1)                │   │
+│  │                                                      │   │
+│  │  Schema Resolution (XDG) ──→ Graph ──→ State Detection│   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+             ▲
+             │ reads from
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   PERSISTENCE LAYER                          │
+│  ┌──────────────────┐   ┌────────────────────────────────┐  │
+│  │  XDG Schemas     │   │  Project Artifacts             │  │
+│  │  ~/.local/share/ │   │  openspec/changes/<name>/      │  │
+│  │  openspec/       │   │  - proposal.md, design.md      │  │
+│  │  schemas/        │   │  - specs/*.md, tasks.md        │  │
+│  └──────────────────┘   └────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Design Patterns
+
+### 1. Filesystem as Database
+
+No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
+
+```
+// State detection is just file existence checking
+if (exists(artifactPath)) {
+  completed.add(artifactId)
+}
+```
+
+### 2. Deterministic CLI, Inferring Agent
+
+**CLI layer:** Always deterministic - requires explicit `--change` parameter.
+
+```
+openspec status --change add-auth     # explicit, works
+openspec status                        # error: "No change specified"
+```
+
+**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
+
+This separation means:
+- CLI is pure, testable, no state to corrupt
+- Agent handles all "smartness"
+- No config.yaml tracking of "active change"
+
+### 3. XDG-Compliant Schema Resolution
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml   # User override
+    ↓ (not found)
+<package>/schemas/<name>/schema.yaml                    # Built-in
+    ↓ (not found)
+Error (schema not found)
+```
+
+### 4. Two-Level Template Fallback
+
+```
+${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md  # User override
+    ↓ (not found)
+<package>/schemas/<schema>/templates/<artifact>.md                   # Built-in
+    ↓ (not found)
+Error (no silent fallback to avoid confusion)
+```
+
+### 5. Glob Pattern Support
+
+`specs/*.md` allows multiple files to satisfy a single artifact:
+
+```
+if (artifact.generates.includes("*")) {
+  const parentDir = changeDir / patternParts[0]
+  if (exists(parentDir) && hasFiles(parentDir)) {
+    completed.add(artifactId)
+  }
+}
+```
+
+### 6. Stateless State Detection
+
+Every command re-scans the filesystem. No cached state to corrupt.
+
+---
+
+## Artifact Pipeline (Default Schema)
+
+The default `spec-driven` schema:
+
+```
+┌──────────┐
+│ proposal │  (no dependencies)
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  specs   │  (requires: proposal)
+└────┬─────┘
+     │
+     ├──────────────┐
+     ▼              ▼
+┌──────────┐   ┌──────────┐
+│  design  │   │          │
+│          │◄──┤ proposal │
+└────┬─────┘   └──────────┘
+     │         (requires: proposal, specs)
+     ▼
+┌──────────┐
+│  tasks   │  (requires: design)
+└──────────┘
+```
+
+Other schemas (TDD, prototype-first) would have different graphs.
+
+---
+
+## Implementation Order
+
+Structured as **vertical slices** - each slice is independently testable.
+
+---
+
+### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE
+
+**Delivers:** Types + Graph + State Detection + Schema Resolution
+
+**Implementation:** `src/core/artifact-graph/`
+- `types.ts` - Zod schemas and derived TypeScript types
+- `schema.ts` - YAML parsing with Zod validation
+- `graph.ts` - ArtifactGraph class with topological sort
+- `state.ts` - Filesystem-based state detection
+- `resolver.ts` - XDG-compliant schema resolution
+- `builtin-schemas.ts` - Package-bundled default schemas
+
+**Key decisions made:**
+- Zod for schema validation (consistent with project)
+- XDG for global schema overrides
+- `Set<string>` for completion state (immutable, functional)
+- `inProgress` and `failed` states deferred (require external tracking)
+
+---
+
+### Slice 2: "Change Creation Utilities"
+
+**Delivers:** Utility functions for programmatic change creation
+
+**Scope:**
+- `createChange(projectRoot, name, description?)` → creates directory + README
+- `validateChangeName(name)` → kebab-case pattern enforcement
+
+**Not in scope (already exists in CLI commands):**
+- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()`
+- `getChangePath()` → simple `path.join()` inline
+- `changeExists()` → simple `fs.access()` inline
+- `isInitialized()` → simple directory check inline
+
+**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation.
+
+---
+
+### Slice 3: "Get Instructions" (Enrichment)
+
+**Delivers:** Template resolution + context injection
+
+**Testable behaviors:**
+- Template fallback: schema-specific → shared → built-in → error
+- Context injection: completed deps show ✓, missing show ✗
+- Output path shown correctly based on change directory
+
+---
+
+### Slice 4: "CLI + Integration"
+
+**Delivers:** New artifact graph commands (builds on existing CLI)
+
+**New commands:**
+- `status --change <id>` - Show artifact completion state
+- `next --change <id>` - Show ready-to-create artifacts
+- `instructions <artifact> --change <id>` - Get enriched template
+- `templates --change <id>` - Show resolved paths
+- `new <name>` - Create change (wrapper for `createChange()`)
+
+**Already exists (not in scope):**
+- `openspec change list/show/validate` - change management
+- `openspec list --changes/--specs` - listing
+- `openspec view` - dashboard
+- `openspec init` - initialization
+
+**Testable behaviors:**
+- Each new command produces expected output
+- Commands compose correctly (status → next → instructions flow)
+- Error handling for missing changes, invalid artifacts, etc.
+
+---
+
+## Directory Structure
+
+```
+# Global (XDG paths - user overrides)
+~/.local/share/openspec/           # Unix/macOS ($XDG_DATA_HOME/openspec/)
+%LOCALAPPDATA%/openspec/           # Windows
+└── schemas/                       # Schema overrides
+    └── custom-workflow/           # User-defined schema directory
+        ├── schema.yaml            # Schema definition
+        └── templates/             # Co-located templates
+            └── proposal.md
+
+# Package (built-in defaults)
+<package>/
+└── schemas/                       # Built-in schema definitions
+    ├── spec-driven/               # Default: proposal → specs → design → tasks
+    │   ├── schema.yaml
+    │   └── templates/
+    │       ├── proposal.md
+    │       ├── design.md
+    │       ├── spec.md
+    │       └── tasks.md
+    └── tdd/                       # TDD: tests → implementation → docs
+        ├── schema.yaml
+        └── templates/
+            ├── test.md
+            ├── implementation.md
+            ├── spec.md
+            └── docs.md
+
+# Project (change instances)
+openspec/
+└── changes/                       # Change instances
+    ├── add-auth/
+    │   ├── README.md              # Auto-generated on creation
+    │   ├── proposal.md            # Created artifacts
+    │   ├── design.md
+    │   └── specs/
+    │       └── *.md
+    ├── refactor-db/
+    │   └── ...
+    └── archive/                   # Completed changes
+        └── 2025-01-01-add-auth/
+
+.claude/
+├── settings.local.json            # Permissions
+└── commands/                      # Slash commands
+    └── *.md
+```
+
+---
+
+## Schema YAML Format
+
+```yaml
+# Built-in: <package>/schemas/spec-driven/schema.yaml
+# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml
+name: spec-driven
+version: 1
+description: Specification-driven development
+
+artifacts:
+  - id: proposal
+    generates: "proposal.md"
+    description: "Create project proposal document"
+    template: "proposal.md"          # resolves from co-located templates/ directory
+    requires: []
+
+  - id: specs
+    generates: "specs/*.md"          # glob pattern
+    description: "Create technical specification documents"
+    template: "specs.md"
+    requires:
+      - proposal
+
+  - id: design
+    generates: "design.md"
+    description: "Create design document"
+    template: "design.md"
+    requires:
+      - proposal
+      - specs
+
+  - id: tasks
+    generates: "tasks.md"
+    description: "Create tasks breakdown document"
+    template: "tasks.md"
+    requires:
+      - design
+```
+
+---
+
+## Summary
+
+| Layer | Component | Responsibility | Status |
+|-------|-----------|----------------|--------|
+| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE |
+| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) |
+| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) |
+| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) |
+| Integration | Claude Commands | AI assistant glue | Slice 4 |
+
+**What already exists (not in this proposal):**
+- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes
+- `ChangeCommand.list/show/validate()` in `src/commands/change.ts`
+- `ListCommand.execute()` in `src/core/list.ts`
+- `ViewCommand.execute()` in `src/core/view.ts` - dashboard
+- `src/core/init.ts` - initialization
+- `src/core/archive.ts` - archiving
+
+**Key Principles:**
+- **Filesystem IS the database** - stateless, version-control friendly
+- **Dependencies are enablers** - show what's possible, don't force order
+- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
+- **XDG-compliant paths** - schemas and templates use standard user data directories
+- **2-level inheritance** - user override → package built-in (no deeper)
+- **Schemas are versioned** - support variations by philosophy, version, language
@@ -1,705 +0,0 @@
-# Commands
-
-This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Windsurf).
-
-For workflow patterns and when to use each command, see [Workflows](workflows.md). For CLI commands, see [CLI](cli.md).
-
-## Quick Reference
-
-### Default Quick Path (`core` profile)
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step |
-| `/opsx:explore` | Think through ideas before committing to a change |
-| `/opsx:apply` | Implement tasks from the change |
-| `/opsx:sync` | Merge delta specs into main specs |
-| `/opsx:archive` | Archive a completed change |
-
-### Expanded Workflow Commands (custom workflow selection)
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:new` | Start a new change scaffold |
-| `/opsx:continue` | Create the next artifact based on dependencies |
-| `/opsx:ff` | Fast-forward: create all planning artifacts at once |
-| `/opsx:verify` | Validate implementation matches artifacts |
-| `/opsx:bulk-archive` | Archive multiple changes at once |
-| `/opsx:onboard` | Guided tutorial through the complete workflow |
-
-The default global profile is `core`. To enable expanded workflow commands, run `openspec config profile`, select workflows, then run `openspec update` in your project.
-
---
-
-## Command Reference
-
-### `/opsx:propose`
-
-Create a new change and generate planning artifacts in one step. This is the default start command in the `core` profile.
-
-**Syntax:**
-```text
-/opsx:propose [change-name-or-description]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name-or-description` | No | Kebab-case name or plain-language change description |
-
-**What it does:**
- Creates `openspec/changes/<change-name>/`
- Generates artifacts needed before implementation (for `spec-driven`: proposal, specs, design, tasks)
- Stops when the change is ready for `/opsx:apply`
-
-**Example:**
-```text
-You: /opsx:propose add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md
-     ✓ specs/ui/spec.md
-     ✓ design.md
-     ✓ tasks.md
-     Ready for implementation. Run /opsx:apply.
-```
-
-**Tips:**
- Use this for the fastest end-to-end path
- If you want step-by-step artifact control, enable expanded workflows and use `/opsx:new` + `/opsx:continue`
-
---
-
-### `/opsx:explore`
-
-Think through ideas, investigate problems, and clarify requirements before committing to a change.
-
-**Syntax:**
-```
-/opsx:explore [topic]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `topic` | No | What you want to explore or investigate |
-
-**What it does:**
- Opens an exploratory conversation with no structure required
- Investigates the codebase to answer questions
- Compares options and approaches
- Creates visual diagrams to clarify thinking
- Can transition to `/opsx:propose` (default) or `/opsx:new` (expanded workflow) when insights crystallize
-
-**Example:**
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: How should we handle authentication for the mobile app?
-
-AI:  Let me investigate your current auth setup...
-     [Analyzes codebase]
-
-     I see you're using session-based auth for the web app.
-     For mobile, we have three main options:
-
-     1. JWT tokens (stateless, works offline)
-     2. OAuth2 (if you need third-party login)
-     3. Extend current sessions (simpler, but requires connectivity)
-
-     Your API already has CORS configured. Which direction interests you?
-
-You: Let's go with JWT. Can we start a change for that?
-
-AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.
-```
-
-**Tips:**
- Use when requirements are unclear or you need to investigate
- No artifacts are created during exploration
- Good for comparing multiple approaches before deciding
- Can read files and search the codebase
-
---
-
-### `/opsx:new`
-
-Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with `/opsx:continue` or `/opsx:ff`.
-
-This command is part of the expanded workflow set (not included in the default `core` profile).
-
-**Syntax:**
-```
-/opsx:new [change-name] [--schema <schema-name>]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Name for the change folder (prompted if not provided) |
-| `--schema` | No | Workflow schema to use (default: from config or `spec-driven`) |
-
-**What it does:**
- Creates `openspec/changes/<change-name>/` directory
- Creates `.openspec.yaml` metadata file in the change folder
- Shows the first artifact template ready for creation
- Prompts for change name and schema if not provided
-
-**What it creates:**
-```
-openspec/changes/<change-name>/
-└── .openspec.yaml    # Change metadata (schema, created date)
-```
-
-**Example:**
-```
-You: /opsx:new add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     Schema: spec-driven
-
-     Ready to create: proposal
-     Use /opsx:continue to create it, or /opsx:ff to create all artifacts.
-```
-
-**Tips:**
- Use descriptive names: `add-feature`, `fix-bug`, `refactor-module`
- Avoid generic names like `update`, `changes`, `wip`
- Schema can also be set in project config (`openspec/config.yaml`)
-
---
-
-### `/opsx:continue`
-
-Create the next artifact in the dependency chain. Creates one artifact at a time for incremental progress.
-
-**Syntax:**
-```
-/opsx:continue [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to continue (inferred from context if not provided) |
-
-**What it does:**
- Queries the artifact dependency graph
- Shows which artifacts are ready vs blocked
- Creates the first ready artifact
- Reads dependency files for context
- Shows what becomes available after creation
-
-**Example:**
-```
-You: /opsx:continue
-
-AI:  Change: add-dark-mode
-
-     Artifact status:
-     ✓ proposal    (done)
-     ◆ specs       (ready)
-     ◆ design      (ready)
-     ○ tasks       (blocked - needs: specs)
-
-     Creating specs...
-
-     [Reads proposal.md, creates specs based on requirements]
-
-     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
-
-     Now available: tasks
-     Run /opsx:continue to create the next artifact.
-```
-
-**Tips:**
- Use when you want to review each artifact before proceeding
- Good for complex changes where you want control
- Multiple artifacts may become ready simultaneously
- You can edit created artifacts before continuing
-
---
-
-### `/opsx:ff`
-
-Fast-forward through artifact creation. Creates all planning artifacts at once.
-
-**Syntax:**
-```
-/opsx:ff [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to fast-forward (inferred from context if not provided) |
-
-**What it does:**
- Creates all artifacts in dependency order
- Tracks progress via todo list
- Stops when all `apply-required` artifacts are complete
- Reads each dependency before creating the next artifact
-
-**Example:**
-```
-You: /opsx:ff add-dark-mode
-
-AI:  Fast-forwarding add-dark-mode...
-
-     ✓ Creating proposal.md
-     ✓ Creating specs/ui/spec.md
-     ✓ Creating design.md
-     ✓ Creating tasks.md
-
-     All planning artifacts complete!
-     Ready for implementation. Run /opsx:apply to begin.
-```
-
-**Tips:**
- Use when you have a clear picture of what you're building
- Faster than `/opsx:continue` for straightforward changes
- You can still edit artifacts afterward
- Good for small to medium features
-
---
-
-### `/opsx:apply`
-
-Implement tasks from the change. Works through the task list, writing code and checking off items.
-
-**Syntax:**
-```
-/opsx:apply [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to implement (inferred from context if not provided) |
-
-**What it does:**
- Reads `tasks.md` and identifies incomplete tasks
- Works through tasks one by one
- Writes code, creates files, runs tests as needed
- Marks tasks complete with checkboxes `[x]`
-
-**Example:**
-```
-You: /opsx:apply
-
-AI:  Implementing add-dark-mode...
-
-     Reading tasks.md:
-     - [ ] 1.1 Create ThemeContext
-     - [ ] 1.2 Add CSS custom properties
-     - [ ] 1.3 Implement localStorage persistence
-
-     Working on 1.1: Create ThemeContext...
-     [Creates src/context/ThemeContext.tsx]
-
-     ✓ 1.1 Complete
-
-     Working on 1.2: Add CSS custom properties...
-     [Updates src/styles/globals.css]
-
-     ✓ 1.2 Complete
-     ...
-```
-
-**Tips:**
- Can resume where you left off if interrupted
- Use for parallel changes by specifying the change name
- Completion state is tracked in `tasks.md` checkboxes
-
---
-
-### `/opsx:verify`
-
-Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.
-
-**Syntax:**
-```
-/opsx:verify [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to verify (inferred from context if not provided) |
-
-**What it does:**
- Checks three dimensions of implementation quality
- Searches codebase for implementation evidence
- Reports issues categorized as CRITICAL, WARNING, or SUGGESTION
- Does not block archive, but surfaces issues
-
-**Verification dimensions:**
-
-| Dimension | What it validates |
-|-----------|-------------------|
-| **Completeness** | All tasks done, all requirements implemented, scenarios covered |
-| **Correctness** | Implementation matches spec intent, edge cases handled |
-| **Coherence** | Design decisions reflected in code, patterns consistent |
-
-**Example:**
-```
-You: /opsx:verify
-
-AI:  Verifying add-dark-mode...
-
-     COMPLETENESS
-     ✓ All 8 tasks in tasks.md are checked
-     ✓ All requirements in specs have corresponding code
-     ⚠ Scenario "System preference detection" has no test coverage
-
-     CORRECTNESS
-     ✓ Implementation matches spec intent
-     ✓ Edge cases from scenarios are handled
-     ✓ Error states match spec definitions
-
-     COHERENCE
-     ✓ Design decisions reflected in code structure
-     ✓ Naming conventions consistent with design.md
-     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes
-
-     SUMMARY
-     ─────────────────────────────
-     Critical issues: 0
-     Warnings: 2
-     Ready to archive: Yes (with warnings)
-
-     Recommendations:
-     1. Add test for system preference detection
-     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables
-```
-
-**Tips:**
- Run before archiving to catch mismatches early
- Warnings don't block archive but indicate potential issues
- Good for reviewing AI's work before committing
- Can reveal drift between artifacts and implementation
-
---
-
-### `/opsx:sync`
-
-**Optional command.** Merge delta specs from a change into main specs. Archive will prompt to sync if needed, so you typically don't need to run this manually.
-
-**Syntax:**
-```
-/opsx:sync [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to sync (inferred from context if not provided) |
-
-**What it does:**
- Reads delta specs from change folder
- Parses ADDED/MODIFIED/REMOVED/RENAMED sections
- Merges changes into main `openspec/specs/` directory
- Preserves existing content not mentioned in delta
- Does not archive the change (remains active)
-
-**Example:**
-```text
-You: /opsx:sync
-
-AI:  Syncing add-dark-mode delta specs...
-
-     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
-     Target:  openspec/specs/ui/spec.md
-
-     Changes to apply:
-     ✓ ADDED: Theme Selection requirement (2 scenarios)
-     ✓ ADDED: Accessibility requirement (1 scenario)
-
-     Merging...
-     ✓ openspec/specs/ui/spec.md updated
-
-     Change remains active. Run /opsx:archive when ready to complete.
-```
-
-**When to use manually:**
-
-| Scenario | Use sync? |
-|----------|-----------|
-| Long-running change, want specs in main before archiving | Yes |
-| Multiple parallel changes need the updated base specs | Yes |
-| Want to preview/review the merge separately | Yes |
-| Quick change, going straight to archive | No (archive handles it) |
-
-**Tips:**
- Sync is intelligent, not copy-paste
- Can add scenarios to existing requirements without duplicating
- Change stays active after sync (not archived)
- Most users will never need to call this directly—archive prompts if needed
-
---
-
-### `/opsx:archive`
-
-Archive a completed change. Finalizes the change and moves it to the archive folder.
-
-**Syntax:**
-```
-/opsx:archive [change-name]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-name` | No | Which change to archive (inferred from context if not provided) |
-
-**What it does:**
- Checks artifact completion status
- Checks task completion (warns if incomplete)
- Offers to sync delta specs if not already synced
- Moves change folder to `openspec/changes/archive/YYYY-MM-DD-<name>/`
- Preserves all artifacts for audit trail
-
-**Example:**
-```text
-You: /opsx:archive
-
-AI:  Archiving add-dark-mode...
-
-     Artifact status:
-     ✓ proposal.md exists
-     ✓ specs/ exists
-     ✓ design.md exists
-     ✓ tasks.md exists (8/8 tasks complete)
-
-     Delta specs: Not yet synced
-     → Sync now? (recommended)
-
-You: Yes
-
-AI:  ✓ Synced specs to openspec/specs/ui/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
-
-     Change archived successfully.
-```
-
-**Tips:**
- Archive won't block on incomplete tasks, but will warn
- Delta specs can be synced during archive or beforehand
- Archived changes are preserved for history
- Use `/opsx:verify` first to catch issues
-
---
-
-### `/opsx:bulk-archive`
-
-Archive multiple completed changes at once. Handles spec conflicts between changes.
-
-**Syntax:**
-```
-/opsx:bulk-archive [change-names...]
-```
-
-**Arguments:**
-| Argument | Required | Description |
-|----------|----------|-------------|
-| `change-names` | No | Specific changes to archive (prompts to select if not provided) |
-
-**What it does:**
- Lists all completed changes
- Validates each change before archiving
- Detects spec conflicts across changes
- Resolves conflicts by checking what's actually implemented
- Archives in chronological order
-
-**Example:**
-```
-You: /opsx:bulk-archive
-
-AI:  Found 3 completed changes:
-     - add-dark-mode (8/8 tasks complete)
-     - fix-login-bug (3/3 tasks complete)
-     - update-footer (2/2 tasks complete)
-
-     Checking for spec conflicts...
-     ⚠ add-dark-mode and update-footer both touch specs/ui/
-
-     Inspecting codebase to resolve...
-     Both changes are implemented. Will merge in chronological order:
-     1. add-dark-mode (created Jan 20)
-     2. update-footer (created Jan 22)
-
-     Archive all 3 changes?
-
-You: Yes
-
-AI:  ✓ Archived add-dark-mode
-     ✓ Archived fix-login-bug
-     ✓ Archived update-footer
-     Specs merged: add-dark-mode → update-footer
-```
-
-**Tips:**
- Good for parallel work streams
- Conflict resolution is agentic (checks codebase)
- Changes are archived in order of creation
- Prompts before overwriting spec content
-
---
-
-### `/opsx:onboard`
-
-Guided onboarding through the complete OpenSpec workflow. An interactive tutorial using your actual codebase.
-
-**Syntax:**
-```
-/opsx:onboard
-```
-
-**What it does:**
- Walks through a complete workflow cycle with narration
- Scans your codebase for real improvement opportunities
- Creates an actual change with real artifacts
- Implements actual work (small, safe changes)
- Archives the completed change
- Explains each step as it happens
-
-**Phases:**
-1. Welcome and codebase analysis
-2. Finding an improvement opportunity
-3. Creating a change (`/opsx:new`)
-4. Writing the proposal
-5. Creating specs
-6. Writing the design
-7. Creating tasks
-8. Implementing tasks (`/opsx:apply`)
-9. Verifying implementation
-10. Archiving the change
-11. Summary and next steps
-
-**Example:**
-```
-You: /opsx:onboard
-
-AI:  Welcome to OpenSpec!
-
-     I'll walk you through the complete workflow using your actual codebase.
-     We'll find something small to improve, create a proper change for it,
-     implement it, and archive it.
-
-     Let me scan your codebase for opportunities...
-
-     [Analyzes codebase]
-
-     I found a few things we could work on:
-     1. Add input validation to the contact form
-     2. Improve error messages in the auth flow
-     3. Add loading states to async buttons
-
-     Which interests you? (or suggest something else)
-```
-
-**Tips:**
- Best for new users learning the workflow
- Uses real code, not toy examples
- Creates a real change you can keep or discard
- Takes 15-30 minutes to complete
-
---
-
-## Command Syntax by AI Tool
-
-Different AI tools use slightly different command syntax. Use the format that matches your tool:
-
-| Tool | Syntax Example |
-|------|----------------|
-| Claude Code | `/opsx:propose`, `/opsx:apply` |
-| Cursor | `/opsx-propose`, `/opsx-apply` |
-| Windsurf | `/opsx-propose`, `/opsx-apply` |
-| Copilot (IDE) | `/opsx-propose`, `/opsx-apply` |
-| Kimi CLI | Skill-based invocations such as `/skill:openspec-propose`, `/skill:openspec-apply-change` (no generated `opsx-*` command files) |
-| Trae | Skill-based invocations such as `/openspec-propose`, `/openspec-apply-change` (no generated `opsx-*` command files) |
-
-The intent is the same across tools, but how commands are surfaced can differ by integration.
-
-> **Note:** GitHub Copilot commands (`.github/prompts/*.prompt.md`) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see [Supported Tools](supported-tools.md) for details and workarounds.
-
---
-
-## Legacy Commands
-
-These commands use the older "all-at-once" workflow. They still work but OPSX commands are recommended.
-
-| Command | What it does |
-|---------|--------------|
-| `/openspec:proposal` | Create all artifacts at once (proposal, specs, design, tasks) |
-| `/openspec:apply` | Implement the change |
-| `/openspec:archive` | Archive the change |
-
-**When to use legacy commands:**
- Existing projects using the old workflow
- Simple changes where you don't need incremental artifact creation
- Preference for the all-or-nothing approach
-
-**Migrating to OPSX:**
-Legacy changes can be continued with OPSX commands. The artifact structure is compatible.
-
---
-
-## Troubleshooting
-
-### "Change not found"
-
-The command couldn't identify which change to work on.
-
-**Solutions:**
- Specify the change name explicitly: `/opsx:apply add-dark-mode`
- Check that the change folder exists: `openspec list`
- Verify you're in the right project directory
-
-### "No artifacts ready"
-
-All artifacts are either complete or blocked by missing dependencies.
-
-**Solutions:**
- Run `openspec status --change <name>` to see what's blocking
- Check if required artifacts exist
- Create missing dependency artifacts first
-
-### "Schema not found"
-
-The specified schema doesn't exist.
-
-**Solutions:**
- List available schemas: `openspec schemas`
- Check spelling of schema name
- Create the schema if it's custom: `openspec schema init <name>`
-
-### Commands not recognized
-
-The AI tool doesn't recognize OpenSpec commands.
-
-**Solutions:**
- Ensure OpenSpec is initialized: `openspec init`
- Regenerate skills: `openspec update`
- Check that `.claude/skills/` directory exists (for Claude Code)
- Restart your AI tool to pick up new skills
-
-### Artifacts not generating properly
-
-The AI creates incomplete or incorrect artifacts.
-
-**Solutions:**
- Add project context in `openspec/config.yaml`
- Add per-artifact rules for specific guidance
- Provide more detail in your change description
- Use `/opsx:continue` instead of `/opsx:ff` for more control
-
---
-
-## Next Steps
-
- [Workflows](workflows.md) - Common patterns and when to use each command
- [CLI](cli.md) - Terminal commands for management and validation
- [Customization](customization.md) - Create custom schemas and workflows
@@ -1,745 +0,0 @@
-# Concepts
-
-This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see [Getting Started](getting-started.md) and [Workflows](workflows.md).
-
-## Philosophy
-
-OpenSpec is built around four principles:
-
-```
-fluid not rigid         — no phase gates, work on what makes sense
-iterative not waterfall — learn as you build, refine as you go
-easy not complex        — lightweight setup, minimal ceremony
-brownfield-first        — works with existing codebases, not just greenfield
-```
-
-### Why These Principles Matter
-
-**Fluid not rigid.** Traditional spec systems lock you into phases: first you plan, then you implement, then you're done. OpenSpec is more flexible — you can create artifacts in any order that makes sense for your work.
-
-**Iterative not waterfall.** Requirements change. Understanding deepens. What seemed like a good approach at the start might not hold up after you see the codebase. OpenSpec embraces this reality.
-
-**Easy not complex.** Some spec frameworks require extensive setup, rigid formats, or heavyweight processes. OpenSpec stays out of your way. Initialize in seconds, start working immediately, customize only if you need to.
-
-**Brownfield-first.** Most software work isn't building from scratch — it's modifying existing systems. OpenSpec's delta-based approach makes it easy to specify changes to existing behavior, not just describe new systems.
-
-## The Big Picture
-
-OpenSpec organizes your work into two main areas:
-
-```
-┌────────────────────────────────────────────────────────────────────┐
-│                        openspec/                                   │
-│                                                                    │
-│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
-│   │       specs/        │      │         changes/              │   │
-│   │                     │      │                               │   │
-│   │  Source of truth    │◄─────│  Proposed modifications       │   │
-│   │  How your system    │ merge│  Each change = one folder     │   │
-│   │  currently works    │      │  Contains artifacts + deltas  │   │
-│   │                     │      │                               │   │
-│   └─────────────────────┘      └───────────────────────────────┘   │
-│                                                                    │
-└────────────────────────────────────────────────────────────────────┘
-```
-
-**Specs** are the source of truth — they describe how your system currently behaves.
-
-**Changes** are proposed modifications — they live in separate folders until you're ready to merge them.
-
-This separation is key. You can work on multiple changes in parallel without conflicts. You can review a change before it affects the main specs. And when you archive a change, its deltas merge cleanly into the source of truth.
-
-## 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.
-
-### Structure
-
-```
-openspec/specs/
-├── auth/
-│   └── spec.md           # Authentication behavior
-├── payments/
-│   └── spec.md           # Payment processing
-├── notifications/
-│   └── spec.md           # Notification system
-└── ui/
-    └── spec.md           # UI behavior and themes
-```
-
-Organize specs by domain — logical groupings that make sense for your system. Common patterns:
-
- **By feature area**: `auth/`, `payments/`, `search/`
- **By component**: `api/`, `frontend/`, `workers/`
- **By bounded context**: `ordering/`, `fulfillment/`, `inventory/`
-
-### Spec Format
-
-A spec contains requirements, and each requirement has scenarios:
-
-```markdown
-# Auth Specification
-
-## Purpose
-Authentication and session management for the application.
-
-## Requirements
-
-### Requirement: User Authentication
-The system SHALL issue a JWT token upon successful login.
-
-#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits login form
- THEN a JWT token is returned
- AND the user is redirected to dashboard
-
-#### Scenario: Invalid credentials
- GIVEN invalid credentials
- WHEN the user submits login form
- THEN an error message is displayed
- AND no token is issued
-
-### Requirement: Session Expiration
-The system MUST expire sessions after 30 minutes of inactivity.
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
- AND the user must re-authenticate
-```
-
-**Key elements:**
-
-| Element | Purpose |
-|---------|---------|
-| `## Purpose` | High-level description of this spec's domain |
-| `### Requirement:` | A specific behavior the system must have |
-| `#### Scenario:` | A concrete example of the requirement in action |
-| SHALL/MUST/SHOULD | RFC 2119 keywords indicating requirement strength |
-
-### Why Structure Specs This Way
-
-**Requirements are the "what"** — they state what the system should do without specifying implementation.
-
-**Scenarios are the "when"** — they provide concrete examples that can be verified. Good scenarios:
- Are testable (you could write an automated test for them)
- Cover both happy path and edge cases
- Use Given/When/Then or similar structured format
-
-**RFC 2119 keywords** (SHALL, MUST, SHOULD, MAY) communicate intent:
- **MUST/SHALL** — absolute requirement
- **SHOULD** — recommended, but exceptions exist
- **MAY** — optional
-
-### What a Spec Is (and Is Not)
-
-A spec is a **behavior contract**, not an implementation plan.
-
-Good spec content:
- Observable behavior users or downstream systems rely on
- Inputs, outputs, and error conditions
- External constraints (security, privacy, reliability, compatibility)
- Scenarios that can be tested or explicitly validated
-
-Avoid in specs:
- Internal class/function names
- Library or framework choices
- Step-by-step implementation details
- Detailed execution plans (those belong in `design.md` or `tasks.md`)
-
-Quick test:
- If implementation can change without changing externally visible behavior, it likely does not belong in the spec.
-
-### Keep It Lightweight: Progressive Rigor
-
-OpenSpec aims to avoid bureaucracy. Use the lightest level that still makes the change verifiable.
-
-**Lite spec (default):**
- Short behavior-first requirements
- Clear scope and non-goals
- A few concrete acceptance checks
-
-**Full spec (for higher risk):**
- Cross-team or cross-repo changes
- API/contract changes, migrations, security/privacy concerns
- Changes where ambiguity is likely to cause expensive rework
-
-Most changes should stay in Lite mode.
-
-### Human + Agent Collaboration
-
-In many teams, humans explore and agents draft artifacts. The intended loop is:
-
-1. Human provides intent, context, and constraints.
-2. Agent converts this into behavior-first requirements and scenarios.
-3. Agent keeps implementation detail in `design.md` and `tasks.md`, not `spec.md`.
-4. Validation confirms structure and clarity before implementation.
-
-This keeps specs readable for humans and consistent for agents.
-
-## Changes
-
-A change is a proposed modification to your system, packaged as a folder with everything needed to understand and implement it.
-
-### Change Structure
-
-```
-openspec/changes/add-dark-mode/
-├── proposal.md           # Why and what
-├── design.md             # How (technical approach)
-├── tasks.md              # Implementation checklist
-├── .openspec.yaml        # Change metadata (optional)
-└── specs/                # Delta specs
-    └── ui/
-        └── spec.md       # What's changing in ui/spec.md
-```
-
-Each change is self-contained. It has:
- **Artifacts** — documents that capture intent, design, and tasks
- **Delta specs** — specifications for what's being added, modified, or removed
- **Metadata** — optional configuration for this specific change
-
-### Why Changes Are Folders
-
-Packaging a change as a folder has several benefits:
-
-1. **Everything together.** Proposal, design, tasks, and specs live in one place. No hunting through different locations.
-
-2. **Parallel work.** Multiple changes can exist simultaneously without conflicting. Work on `add-dark-mode` while `fix-auth-bug` is also in progress.
-
-3. **Clean history.** When archived, changes move to `changes/archive/` with their full context preserved. You can look back and understand not just what changed, but why.
-
-4. **Review-friendly.** A change folder is easy to review — open it, read the proposal, check the design, see the spec deltas.
-
-## Artifacts
-
-Artifacts are the documents within a change that guide the work.
-
-### The Artifact Flow
-
-```
-proposal ──────► specs ──────► design ──────► tasks ──────► implement
-    │               │             │              │
-   why            what           how          steps
- + scope        changes       approach      to take
-```
-
-Artifacts build on each other. Each artifact provides context for the next.
-
-### Artifact Types
-
-#### Proposal (`proposal.md`)
-
-The proposal captures **intent**, **scope**, and **approach** at a high level.
-
-```markdown
-# Proposal: Add Dark Mode
-
-## Intent
-Users have requested a dark mode option to reduce eye strain
-during nighttime usage and match system preferences.
-
-## Scope
-In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage
-
-Out of scope:
- Custom color themes (future work)
- Per-page theme overrides
-
-## Approach
-Use CSS custom properties for theming with a React context
-for state management. Detect system preference on first load,
-allow manual override.
-```
-
-**When to update the proposal:**
- Scope changes (narrowing or expanding)
- Intent clarifies (better understanding of the problem)
- Approach fundamentally shifts
-
-#### Specs (delta specs in `specs/`)
-
-Delta specs describe **what's changing** relative to the current specs. See [Delta Specs](#delta-specs) below.
-
-#### Design (`design.md`)
-
-The design captures **technical approach** and **architecture decisions**.
-
-````markdown
-# Design: Add Dark Mode
-
-## Technical Approach
-Theme state managed via React Context to avoid prop drilling.
-CSS custom properties enable runtime switching without class toggling.
-
-## Architecture Decisions
-
-### Decision: Context over Redux
-Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency
-
-### Decision: CSS Custom Properties
-Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution
-
-## Data Flow
-```
-ThemeProvider (context)
-       │
-       ▼
-ThemeToggle ◄──► localStorage
-       │
-       ▼
-CSS Variables (applied to :root)
-```
-
-## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)
-````
-
-**When to update the design:**
- Implementation reveals the approach won't work
- Better solution discovered
- Dependencies or constraints change
-
-#### Tasks (`tasks.md`)
-
-Tasks are the **implementation checklist** — concrete steps with checkboxes.
-
-```markdown
-# Tasks
-
-## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
- [ ] 1.4 Add system preference detection
-
-## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
-
-## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
- [ ] 3.3 Test contrast ratios for accessibility
-```
-
-**Task best practices:**
- Group related tasks under headings
- Use hierarchical numbering (1.1, 1.2, etc.)
- Keep tasks small enough to complete in one session
- Check tasks off as you complete them
-
-## Delta Specs
-
-Delta specs are the key concept that makes OpenSpec work for brownfield development. They describe **what's changing** rather than restating the entire spec.
-
-### The Format
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-
-### Requirement: Two-Factor Authentication
-The system MUST support TOTP-based two-factor authentication.
-
-#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation
-
-#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP
-
-## MODIFIED Requirements
-
-### Requirement: Session Expiration
-The system MUST expire sessions after 15 minutes of inactivity.
-(Previously: 30 minutes)
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated
-
-## REMOVED Requirements
-
-### Requirement: Remember Me
-(Deprecated in favor of 2FA. Users should re-authenticate each session.)
-```
-
-### Delta Sections
-
-| Section | Meaning | What Happens on Archive |
-|---------|---------|------------------------|
-| `## ADDED Requirements` | New behavior | Appended to main spec |
-| `## MODIFIED Requirements` | Changed behavior | Replaces existing requirement |
-| `## REMOVED Requirements` | Deprecated behavior | Deleted from main spec |
-
-### Why Deltas Instead of Full Specs
-
-**Clarity.** A delta shows exactly what's changing. Reading a full spec, you'd have to diff it mentally against the current version.
-
-**Conflict avoidance.** Two changes can touch the same spec file without conflicting, as long as they modify different requirements.
-
-**Review efficiency.** Reviewers see the change, not the unchanged context. Focus on what matters.
-
-**Brownfield fit.** Most work modifies existing behavior. Deltas make modifications first-class, not an afterthought.
-
-## Schemas
-
-Schemas define the artifact types and their dependencies for a workflow.
-
-### How Schemas Work
-
-```yaml
-# openspec/schemas/spec-driven/schema.yaml
-name: spec-driven
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    requires: []              # No dependencies, can create first
-
-  - id: specs
-    generates: specs/**/*.md
-    requires: [proposal]      # Needs proposal before creating
-
-  - id: design
-    generates: design.md
-    requires: [proposal]      # Can create in parallel with specs
-
-  - id: tasks
-    generates: tasks.md
-    requires: [specs, design] # Needs both specs and design first
-```
-
-**Artifacts form a dependency graph:**
-
-```
-                    proposal
-                   (root node)
-                       │
-         ┌─────────────┴─────────────┐
-         │                           │
-         ▼                           ▼
-      specs                       design
-   (requires:                  (requires:
-    proposal)                   proposal)
-         │                           │
-         └─────────────┬─────────────┘
-                       │
-                       ▼
-                    tasks
-                (requires:
-                specs, design)
-```
-
-**Dependencies are enablers, not gates.** They show what's possible to create, not what you must create next. You can skip design if you don't need it. You can create specs before or after design — both depend only on proposal.
-
-### Built-in Schemas
-
-**spec-driven** (default)
-
-The standard workflow for spec-driven development:
-
-```
-proposal → specs → design → tasks → implement
-```
-
-Best for: Most feature work where you want to agree on specs before implementation.
-
-### Custom Schemas
-
-Create custom schemas for your team's workflow:
-
-```bash
-# Create from scratch
-openspec schema init research-first
-
-# Or fork an existing one
-openspec schema fork spec-driven research-first
-```
-
-**Example custom schema:**
-
-```yaml
-# openspec/schemas/research-first/schema.yaml
-name: research-first
-artifacts:
-  - id: research
-    generates: research.md
-    requires: []           # Do research first
-
-  - id: proposal
-    generates: proposal.md
-    requires: [research]   # Proposal informed by research
-
-  - id: tasks
-    generates: tasks.md
-    requires: [proposal]   # Skip specs/design, go straight to tasks
-```
-
-See [Customization](customization.md) for full details on creating and using custom schemas.
-
-## Archive
-
-Archiving completes a change by merging its delta specs into the main specs and preserving the change for history.
-
-### What Happens When You Archive
-
-```
-Before archive:
-
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md ◄────────────────┐
-└── changes/                         │
-    └── add-2fa/                     │
-        ├── proposal.md              │
-        ├── design.md                │ merge
-        ├── tasks.md                 │
-        └── specs/                   │
-            └── auth/                │
-                └── spec.md ─────────┘
-
-
-After archive:
-
-openspec/
-├── specs/
-│   └── auth/
-│       └── spec.md        # Now includes 2FA requirements
-└── changes/
-    └── archive/
-        └── 2025-01-24-add-2fa/    # Preserved for history
-            ├── proposal.md
-            ├── design.md
-            ├── tasks.md
-            └── specs/
-                └── auth/
-                    └── spec.md
-```
-
-### The Archive Process
-
-1. **Merge deltas.** Each delta spec section (ADDED/MODIFIED/REMOVED) is applied to the corresponding main spec.
-
-2. **Move to archive.** The change folder moves to `changes/archive/` with a date prefix for chronological ordering.
-
-3. **Preserve context.** All artifacts remain intact in the archive. You can always look back to understand why a change was made.
-
-### Why Archive Matters
-
-**Clean state.** Active changes (`changes/`) shows only work in progress. Completed work moves out of the way.
-
-**Audit trail.** The archive preserves the full context of every change — not just what changed, but the proposal explaining why, the design explaining how, and the tasks showing the work done.
-
-**Spec evolution.** Specs grow organically as changes are archived. Each archive merges its deltas, building up a comprehensive specification over time.
-
-## How It All Fits Together
-
-```
-┌──────────────────────────────────────────────────────────────────────────────┐
-│                              OPENSPEC FLOW                                   │
-│                                                                              │
-│   ┌────────────────┐                                                         │
-│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
-│   │     CHANGE     │                                                         │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
-│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
-│   │                │  (based on schema dependencies)                         │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  3. IMPLEMENT  │  /opsx:apply                                            │
-│   │     TASKS      │  Work through tasks, checking them off                  │
-│   │                │◄──── Update artifacts as you learn                      │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐                                                         │
-│   │  4. VERIFY     │  /opsx:verify (optional)                                │
-│   │     WORK       │  Check implementation matches specs                     │
-│   └───────┬────────┘                                                         │
-│           │                                                                  │
-│           ▼                                                                  │
-│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
-│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
-│   │     CHANGE     │     │  Change folder moves to archive/             │    │
-│   └────────────────┘     │  Specs are now the updated source of truth   │    │
-│                          └──────────────────────────────────────────────┘    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
-
-**The virtuous cycle:**
-
-1. Specs describe current behavior
-2. Changes propose modifications (as deltas)
-3. Implementation makes the changes real
-4. Archive merges deltas into specs
-5. Specs now describe the new behavior
-6. Next change builds on updated specs
-
-## Glossary
-
-| Term | Definition |
-|------|------------|
-| **Artifact** | A document within a change (proposal, design, tasks, or delta specs) |
-| **Archive** | The process of completing a change and merging its deltas into main specs |
-| **Change** | A proposed modification to the system, packaged as a folder with artifacts |
-| **Delta spec** | A spec that describes changes (ADDED/MODIFIED/REMOVED) relative to current specs |
-| **Domain** | A logical grouping for specs (e.g., `auth/`, `payments/`) |
-| **Requirement** | A specific behavior the system must have |
-| **Scenario** | A concrete example of a requirement, typically in Given/When/Then format |
-| **Schema** | A definition of artifact types and their dependencies |
-| **Spec** | A specification describing system behavior, containing requirements and scenarios |
-| **Source of truth** | The `openspec/specs/` directory, containing the current agreed-upon behavior |
-
-## Next Steps
-
- [Getting Started](getting-started.md) - Practical first steps
- [Workflows](workflows.md) - Common patterns and when to use each
- [Commands](commands.md) - Full command reference
- [Customization](customization.md) - Create custom schemas and configure your project
@@ -1,356 +0,0 @@
-# Customization
-
-OpenSpec provides three levels of customization:
-
-| Level | What it does | Best for |
-|-------|--------------|----------|
-| **Project Config** | Set defaults, inject context/rules | Most teams |
-| **Custom Schemas** | Define your own workflow artifacts | Teams with unique processes |
-| **Global Overrides** | Share schemas across all projects | Power users |
-
---
-
-## Project Configuration
-
-The `openspec/config.yaml` file is the easiest way to customize OpenSpec for your team. It lets you:
-
- **Set a default schema** - Skip `--schema` on every command
- **Inject project context** - AI sees your tech stack, conventions, etc.
- **Add per-artifact rules** - Custom rules for specific artifacts
-
-### Quick Setup
-
-```bash
-openspec init
-```
-
-This walks you through creating a config interactively. Or create one manually:
-
-```yaml
-# openspec/config.yaml
-schema: spec-driven
-
-context: |
-  Tech stack: TypeScript, React, Node.js, PostgreSQL
-  API style: RESTful, documented in docs/api.md
-  Testing: Jest + React Testing Library
-  We value backwards compatibility for all public APIs
-
-rules:
-  proposal:
-    - Include rollback plan
-    - Identify affected teams
-  specs:
-    - Use Given/When/Then format
-    - Reference existing patterns before inventing new ones
-```
-
-### How It Works
-
-**Default schema:**
-
-```bash
-# Without config
-openspec new change my-feature --schema spec-driven
-
-# With config - schema is automatic
-openspec new change my-feature
-```
-
-**Context and rules injection:**
-
-When generating any artifact, your context and rules are injected into the AI prompt:
-
-```xml
-<context>
-Tech stack: TypeScript, React, Node.js, PostgreSQL
-...
-</context>
-
-<rules>
- Include rollback plan
- Identify affected teams
-</rules>
-
-<template>
-[Schema's built-in template]
-</template>
-```
-
- **Context** appears in ALL artifacts
- **Rules** ONLY appear for the matching artifact
-
-### Schema Resolution Order
-
-When OpenSpec needs a schema, it checks in this order:
-
-1. CLI flag: `--schema <name>`
-2. Change metadata (`.openspec.yaml` in the change folder)
-3. Project config (`openspec/config.yaml`)
-4. Default (`spec-driven`)
-
---
-
-## Custom Schemas
-
-When project config isn't enough, create your own schema with a completely custom workflow. Custom schemas live in your project's `openspec/schemas/` directory and are version-controlled with your code.
-
-```text
-your-project/
-├── openspec/
-│   ├── config.yaml        # Project config
-│   ├── schemas/           # Custom schemas live here
-│   │   └── my-workflow/
-│   │       ├── schema.yaml
-│   │       └── templates/
-│   └── changes/           # Your changes
-└── src/
-```
-
-### Fork an Existing Schema
-
-The fastest way to customize is to fork a built-in schema:
-
-```bash
-openspec schema fork spec-driven my-workflow
-```
-
-This copies the entire `spec-driven` schema to `openspec/schemas/my-workflow/` where you can edit it freely.
-
-**What you get:**
-
-```text
-openspec/schemas/my-workflow/
-├── schema.yaml           # Workflow definition
-└── templates/
-    ├── proposal.md       # Template for proposal artifact
-    ├── spec.md           # Template for specs
-    ├── design.md         # Template for design
-    └── tasks.md          # Template for tasks
-```
-
-Now edit `schema.yaml` to change the workflow, or edit templates to change what AI generates.
-
-### Create a Schema from Scratch
-
-For a completely fresh workflow:
-
-```bash
-# Interactive
-openspec schema init research-first
-
-# Non-interactive
-openspec schema init rapid \
-  --description "Rapid iteration workflow" \
-  --artifacts "proposal,tasks" \
-  --default
-```
-
-### Schema Structure
-
-A schema defines the artifacts in your workflow and how they depend on each other:
-
-```yaml
-# openspec/schemas/my-workflow/schema.yaml
-name: my-workflow
-version: 1
-description: My team's custom workflow
-
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Initial proposal document
-    template: proposal.md
-    instruction: |
-      Create a proposal that explains WHY this change is needed.
-      Focus on the problem, not the solution.
-    requires: []
-
-  - id: design
-    generates: design.md
-    description: Technical design
-    template: design.md
-    instruction: |
-      Create a design document explaining HOW to implement.
-    requires:
-      - proposal    # Can't create design until proposal exists
-
-  - id: tasks
-    generates: tasks.md
-    description: Implementation checklist
-    template: tasks.md
-    requires:
-      - design
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-```
-
-**Key fields:**
-
-| Field | Purpose |
-|-------|---------|
-| `id` | Unique identifier, used in commands and rules |
-| `generates` | Output filename (supports globs like `specs/**/*.md`) |
-| `template` | Template file in `templates/` directory |
-| `instruction` | AI instructions for creating this artifact |
-| `requires` | Dependencies - which artifacts must exist first |
-
-### Templates
-
-Templates are markdown files that guide the AI. They're injected into the prompt when creating that artifact.
-
-```markdown
-<!-- templates/proposal.md -->
-## Why
-
-<!-- Explain the motivation for this change. What problem does this solve? -->
-
-## What Changes
-
-<!-- Describe what will change. Be specific about new capabilities or modifications. -->
-
-## Impact
-
-<!-- Affected code, APIs, dependencies, systems -->
-```
-
-Templates can include:
- Section headers the AI should fill in
- HTML comments with guidance for the AI
- Example formats showing expected structure
-
-### Validate Your Schema
-
-Before using a custom schema, validate it:
-
-```bash
-openspec schema validate my-workflow
-```
-
-This checks:
- `schema.yaml` syntax is correct
- All referenced templates exist
- No circular dependencies
- Artifact IDs are valid
-
-### Use Your Custom Schema
-
-Once created, use your schema with:
-
-```bash
-# Specify on command
-openspec new change feature --schema my-workflow
-
-# Or set as default in config.yaml
-schema: my-workflow
-```
-
-### Debug Schema Resolution
-
-Not sure which schema is being used? Check with:
-
-```bash
-# See where a specific schema resolves from
-openspec schema which my-workflow
-
-# List all available schemas
-openspec schema which --all
-```
-
-Output shows whether it's from your project, user directory, or the package:
-
-```text
-Schema: my-workflow
-Source: project
-Path: /path/to/project/openspec/schemas/my-workflow
-```
-
---
-
-> **Note:** OpenSpec also supports user-level schemas at `~/.local/share/openspec/schemas/` for sharing across projects, but project-level schemas in `openspec/schemas/` are recommended since they're version-controlled with your code.
-
---
-
-## Examples
-
-### Rapid Iteration Workflow
-
-A minimal workflow for quick iterations:
-
-```yaml
-# openspec/schemas/rapid/schema.yaml
-name: rapid
-version: 1
-description: Fast iteration with minimal overhead
-
-artifacts:
-  - id: proposal
-    generates: proposal.md
-    description: Quick proposal
-    template: proposal.md
-    instruction: |
-      Create a brief proposal for this change.
-      Focus on what and why, skip detailed specs.
-    requires: []
-
-  - id: tasks
-    generates: tasks.md
-    description: Implementation checklist
-    template: tasks.md
-    requires: [proposal]
-
-apply:
-  requires: [tasks]
-  tracks: tasks.md
-```
-
-### Adding a Review Artifact
-
-Fork the default and add a review step:
-
-```bash
-openspec schema fork spec-driven with-review
-```
-
-Then edit `schema.yaml` to add:
-
-```yaml
-  - id: review
-    generates: review.md
-    description: Pre-implementation review checklist
-    template: review.md
-    instruction: |
-      Create a review checklist based on the design.
-      Include security, performance, and testing considerations.
-    requires:
-      - design
-
-  - id: tasks
-    # ... existing tasks config ...
-    requires:
-      - specs
-      - design
-      - review    # Now tasks require review too
-```
-
---
-
-## Community Schemas
-
-OpenSpec also supports community-maintained schemas distributed via standalone repositories. These provide opinionated workflows that integrate OpenSpec with other tools or systems, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) works for spec-kit.
-
-Community schemas are not vendored into OpenSpec core — they live in their own repositories with their own release cadence. To use one, copy the schema bundle into your project's `openspec/schemas/<schema-name>/` directory (each repo's README has install instructions).
-
-| Schema | Maintainer | Repository | Description |
-|--------|-----------|-----------|-------------|
-| `superpowers-bridge` | @JiangWay | [JiangWay/openspec-schemas](https://github.com/JiangWay/openspec-schemas/tree/main/superpowers-bridge) | Integrates OpenSpec's artifact governance with [obra/superpowers](https://github.com/obra/superpowers) execution skills (brainstorming, writing-plans, TDD via subagents, code review, finishing). Adds an evidence-first `retrospective` artifact filling a gap Superpowers does not natively cover. |
-
-> Want to contribute a community schema? Open an issue with a link to your repository, or submit a PR adding a row to this table.
-
---
-
-## See Also
-
- [CLI Reference: Schema Commands](cli.md#schema-commands) - Full command documentation
@@ -0,0 +1,926 @@
+# OpenSpec Experimental Release Plan
+
+This document outlines the plan to release the experimental artifact workflow system for user testing.
+
+## Overview
+
+The goal is to allow users to test the new artifact-driven workflow system alongside the existing OpenSpec commands. This experimental system (`opsx`) provides a more granular, step-by-step approach to creating change artifacts.
+
+## Three Workflow Modes
+
+### 1. Old Workflow (Current Production)
+- **Commands**: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
+- **Behavior**: Hardcoded slash commands that generate all artifacts in one command
+- **Status**: Production, unchanged
+
+### 2. New Artifact System - Batch Mode (Future)
+- **Commands**: Refactored `/openspec:proposal` using schemas
+- **Behavior**: Schema-driven but generates all artifacts at once (like legacy)
+- **Status**: Not in scope for this experimental release
+- **Note**: This is a future refactor to unify the old system with schemas
+
+### 3. New Artifact System - Granular Mode (Experimental)
+- **Commands**: `/opsx:new`, `/opsx:continue`
+- **Behavior**: One artifact at a time, dependency-driven, iterative
+- **Status**: Target for this experimental release
+
+---
+
+## Work Items
+
+### 1. Rename AWF to OPSX
+
+**Current State:**
+- Commands: `/awf:start`, `/awf:continue`
+- Files: `.claude/commands/awf/start.md`, `.claude/commands/awf/continue.md`
+
+**Target State:**
+- Commands: `/opsx:new`, `/opsx:continue`
+- Files: `.claude/commands/opsx/new.md`, `.claude/commands/opsx/continue.md`
+
+**Tasks:**
+- [x] Create `.claude/commands/opsx/` directory
+- [x] Rename `start.md` → `new.md` and update content
+- [x] Copy `continue.md` with updated references
+- [x] Update all references from "awf" to "opsx" in command content
+- [x] Update frontmatter (name, description) to use "opsx" naming
+- [x] Remove `.claude/commands/awf/` directory
+
+**CLI Commands:**
+The underlying CLI commands (`openspec status`, `openspec instructions`, etc.) remain unchanged. Only the slash command names change.
+
+---
+
+### 2. Remove WF Skill Files
+
+**Current State:**
+- `.claude/commands/wf/start.md` - References non-existent `openspec wf` commands
+- `.claude/commands/wf/continue.md` - References non-existent `openspec wf` commands
+
+**Target State:**
+- Directory and files removed
+
+**Tasks:**
+- [x] Delete `.claude/commands/wf/start.md`
+- [x] Delete `.claude/commands/wf/continue.md`
+- [x] Delete `.claude/commands/wf/` directory
+
+---
+
+### 3. Add Agent Skills for Experimental Workflow
+
+**Purpose:**
+Generate experimental workflow skills using the [Agent Skills](https://agentskills.io/specification) open standard.
+
+**Why Skills Instead of Slash Commands:**
+- **Cross-editor compatibility**: Skills work in Claude Code, Cursor, Windsurf, and other compatible editors automatically
+- **Simpler implementation**: Single directory (`.claude/skills/`) instead of 18+ editor-specific configurators
+- **Standard format**: Open standard with simple YAML frontmatter + markdown
+- **User invocation**: Users explicitly invoke skills when they want to use them
+
+**Behavior:**
+1. Create `.claude/skills/` directory if it doesn't exist
+2. Generate two skills using the Agent Skills specification:
+   - `openspec-new-change/SKILL.md` - Start a new change with artifact workflow
+   - `openspec-continue-change/SKILL.md` - Continue working on a change (create next artifact)
+3. Skills are added **alongside** existing `/openspec:*` commands (not replacing)
+
+**Supported Editors:**
+- Claude Code (native support)
+- Cursor (native support via Settings → Rules → Import Settings)
+- Windsurf (imports `.claude` configs)
+- Cline, Codex, and other Agent Skills-compatible editors
+
+**Tasks:**
+- [x] Create skill template content for `openspec-new-change` (based on current opsx:new)
+- [x] Create skill template content for `openspec-continue-change` (based on current opsx:continue)
+- [x] Add temporary `artifact-experimental-setup` command to CLI
+- [x] Implement skill file generation (YAML frontmatter + markdown body)
+- [x] Add success message with usage instructions
+
+**Note:** The `artifact-experimental-setup` command is temporary and will be merged into `openspec init` once the experimental workflow is promoted to stable.
+
+**Skill Format:**
+Each skill is a directory with a `SKILL.md` file:
+```
+.claude/skills/
+├── openspec-new-change/
+│   └── SKILL.md          # name, description, instructions
+├── openspec-continue-change/
+│   └── SKILL.md          # name, description, instructions
+└── openspec-apply-change/
+    └── SKILL.md          # name, description, instructions
+```
+
+**CLI Interface:**
+```bash
+openspec artifact-experimental-setup
+
+# Output:
+# 🧪 Experimental Artifact Workflow Skills Created
+#
+#   ✓ .claude/skills/openspec-new-change/SKILL.md
+#   ✓ .claude/skills/openspec-continue-change/SKILL.md
+#   ✓ .claude/skills/openspec-apply-change/SKILL.md
+#
+# 📖 Usage:
+#
+#   Skills work automatically in compatible editors:
+#   • Claude Code - Auto-detected, ready to use
+#   • Cursor - Enable in Settings → Rules → Import Settings
+#   • Windsurf - Auto-imports from .claude directory
+#
+#   Ask Claude naturally:
+#   • "I want to start a new OpenSpec change to add <feature>"
+#   • "Continue working on this change"
+#
+#   Claude will automatically use the appropriate skill.
+#
+# 💡 This is an experimental feature.
+#    Feedback welcome at: https://github.com/Fission-AI/OpenSpec/issues
+```
+
+**Implementation Notes:**
+- Simple file writing: Create directories and write templated `SKILL.md` files (no complex logic)
+- Use existing `FileSystemUtils.writeFile()` pattern like slash command configurators
+- Template structure: YAML frontmatter + markdown body
+- Keep existing `/opsx:*` slash commands for now (manual cleanup later)
+- Skills use invocation model (user explicitly asks Claude to use them)
+- Skill `description` field guides when Claude suggests using the skill
+- Each `SKILL.md` has required fields: `name` (matches directory) and `description`
+
+---
+
+### 4. Update `/opsx:new` Command Content
+
+**Current Behavior (awf:start):**
+1. Ask user what they want to build (if no input)
+2. Create change directory
+3. Show artifact status
+4. Show what's ready
+5. Get instructions for proposal
+6. STOP and wait
+
+**New Behavior (opsx:new):**
+Same flow but with updated naming:
+- References to "awf" → "opsx"
+- References to `/awf:continue` → `/opsx:continue`
+- Update frontmatter name/description
+
+**Tasks:**
+- [x] Update all "awf" references to "opsx"
+- [x] Update command references in prompt text
+- [x] Verify CLI commands still work (they use `openspec`, not `awf`)
+
+---
+
+### 5. Update `/opsx:continue` Command Content
+
+**Current Behavior (awf:continue):**
+1. Prompt for change selection (if not provided)
+2. Check current status
+3. Create ONE artifact based on what's ready
+4. Show progress and what's unlocked
+5. STOP
+
+**New Behavior (opsx:continue):**
+Same flow with updated naming.
+
+**Tasks:**
+- [x] Update all "awf" references to "opsx"
+- [x] Update command references in prompt text
+
+---
+
+### 6. End-to-End Testing
+
+**Objective:**
+Run through a complete workflow with Claude using the new skills to create a real feature, validating the entire flow works.
+
+**Test Scenario:**
+Use a real OpenSpec feature as the test case (dog-fooding).
+
+**Test Flow:**
+1. Run `openspec artifact-experimental-setup` to create skills
+2. Verify `.claude/skills/openspec-new-change/SKILL.md` created
+3. Verify `.claude/skills/openspec-continue-change/SKILL.md` created
+4. Verify `.claude/skills/openspec-apply-change/SKILL.md` created
+5. Ask Claude: "I want to start a new OpenSpec change to add feature X"
+6. Verify Claude invokes the `openspec-new-change` skill
+7. Verify change directory created at `openspec/changes/add-feature-x/`
+8. Verify proposal template shown
+9. Ask Claude: "Continue working on this change"
+10. Verify Claude invokes the `openspec-continue-change` skill
+11. Verify `proposal.md` created with content
+12. Ask Claude: "Continue" (create specs)
+13. Verify `specs/*.md` created
+14. Ask Claude: "Continue" (create design)
+15. Verify `design.md` created
+16. Ask Claude: "Continue" (create tasks)
+17. Verify `tasks.md` created
+18. Verify status shows 4/4 complete
+19. Implement the feature based on tasks
+20. Run `/openspec:archive` to archive the change
+
+**Validation Checklist:**
+- [ ] `openspec artifact-experimental-setup` creates correct directory structure
+- [ ] Skills are auto-detected in Claude Code
+- [ ] Skill descriptions trigger appropriate invocations
+- [ ] Skills create change directory and show proposal template
+- [ ] Skills correctly identify ready artifacts
+- [ ] Skills create artifacts with meaningful content
+- [ ] Dependency detection works (specs requires proposal, etc.)
+- [ ] Progress tracking is accurate
+- [ ] Template content is useful and well-structured
+- [ ] Error handling works (invalid names, missing changes, etc.)
+- [ ] Works with different schemas (spec-driven, tdd)
+- [ ] Test in Cursor (Settings → Rules → Import Settings)
+
+**Document Results:**
+- Create test log documenting what worked and what didn't
+- Note any friction points or confusing UX
+- Identify bugs or improvements needed before user release
+
+---
+
+### 7. Documentation for Users
+
+**Create user-facing documentation explaining:**
+
+1. **What is the experimental workflow?**
+   - A new way to create OpenSpec changes step-by-step using Agent Skills
+   - One artifact at a time with dependency tracking
+   - More interactive and iterative than the batch approach
+   - Works across Claude Code, Cursor, Windsurf, and other compatible editors
+
+2. **How to set up experimental workflow**
+   ```bash
+   openspec artifact-experimental-setup
+   ```
+
+   Note: This is a temporary command that will be integrated into `openspec init` once promoted to stable.
+
+3. **Available skills**
+   - `openspec-new-change` - Start a new change with artifact workflow
+   - `openspec-continue-change` - Continue working (create next artifact)
+
+4. **How to use**
+   - **Claude Code**: Skills are auto-detected, just ask Claude naturally
+     - "I want to start a new OpenSpec change to add X"
+     - "Continue working on this change"
+   - **Cursor**: Enable in Settings → Rules → Import Settings
+   - **Windsurf**: Auto-imports `.claude` directory
+
+5. **Example workflow**
+   - Step-by-step walkthrough with natural language interactions
+   - Show how Claude invokes skills based on user requests
+
+6. **Feedback mechanism**
+   - GitHub issue template for feedback
+   - What to report (bugs, UX issues, suggestions)
+
+**Tasks:**
+- [ ] Create `docs/experimental-workflow.md` user guide
+- [ ] Add GitHub issue template for experimental feedback
+- [ ] Update README with mention of experimental features
+
+---
+
+## Dependency Graph
+
+```
+1. Remove WF skill files
+   └── (no dependencies)
+
+2. Rename AWF to OPSX
+   └── (no dependencies)
+
+3. Add Agent Skills
+   └── Depends on: Rename AWF to OPSX (uses opsx content as templates)
+
+4. Update opsx:new content
+   └── Depends on: Rename AWF to OPSX
+
+5. Update opsx:continue content
+   └── Depends on: Rename AWF to OPSX
+
+6. E2E Testing
+   └── Depends on: Add Agent Skills (tests the skills workflow)
+
+7. User Documentation
+   └── Depends on: E2E Testing (need to know final behavior)
+```
+
+---
+
+## Out of Scope
+
+The following are explicitly NOT part of this experimental release:
+
+1. **Batch mode refactor** - Making legacy `/openspec:proposal` use schemas
+2. **New schemas** - Only shipping with existing `spec-driven` and `tdd`
+3. **Schema customization UI** - No `openspec schema list` or similar
+4. **Multiple editor support in CLI** - Skills work cross-editor automatically via `.claude/skills/`
+5. **Replacing existing commands** - Skills are additive, not replacing `/openspec:*` or `/opsx:*`
+
+---
+
+## Success Criteria
+
+The experimental release is ready when:
+
+1. `openspec-new-change`, `openspec-continue-change`, and `openspec-apply-change` skills work end-to-end
+2. `openspec artifact-experimental-setup` creates skills in `.claude/skills/`
+3. Skills work in Claude Code and are compatible with Cursor/Windsurf
+4. At least one complete workflow has been tested manually
+5. User documentation exists explaining how to generate and use skills
+6. Feedback mechanism is in place
+7. WF skill files are removed
+8. No references to "awf" remain in user-facing content
+
+---
+
+## Open Questions
+
+1. **Schema selection** - Should `opsx:new` allow selecting a schema, or always use `spec-driven`?
+   - Current: Always uses `spec-driven` as default
+   - Consider: Add `--schema tdd` option or prompt
+
+2. **Namespace in CLI** - Should experimental CLI commands be namespaced?
+   - Current: `openspec status`, `openspec instructions` (no namespace)
+   - Alternative: `openspec opsx status` (explicit experimental namespace)
+   - Recommendation: Keep current, less typing for users
+
+3. **Deprecation path** - If opsx becomes the default, how do we migrate?
+   - Not needed for experimental release
+   - Document that command names may change
+
+---
+
+## Estimated Work Breakdown
+
+| Item | Complexity | Notes |
+|------|------------|-------|
+| Remove WF files | Trivial | Just delete 2 files + directory |
+| Rename AWF → OPSX | Low | File renames + content updates |
+| Add Agent Skills | **Low** | **Simple: 3-4 files, single output directory, standard format** |
+| Update opsx:new content | Low | Text replacements |
+| Update opsx:continue content | Low | Text replacements |
+| E2E Testing | Medium | Manual testing, documenting results |
+| User Documentation | Medium | New docs, issue template |
+
+**Key Improvement:** Switching to Agent Skills reduces complexity significantly:
+- **Before:** 20+ files (type definitions, 18+ editor configurators, editor selection UI)
+- **After:** 3-4 files (skill templates, simple CLI command)
+- **Cross-editor:** Works automatically in Claude Code, Cursor, Windsurf without extra code
+
+---
+
+## User Feedback from E2E Testing
+
+### What Worked Well
+
+1. **Clear dependency graph** ⭐ HIGH PRIORITY - KEEP
+   - The status command showing blocked/unblocked artifacts was intuitive:
+     ```
+     [x] proposal
+     [ ] design
+     [-] tasks (blocked by: design, specs)
+     ```
+   - Users always knew what they could work on next
+   - **Relevance**: Core UX strength to preserve
+
+2. **Structured instructions output** ⭐ HIGH PRIORITY - KEEP
+   - `openspec instructions <artifact>` gave templates, output paths, and context in one call
+   - Very helpful for understanding what to create
+   - **Relevance**: Essential for agent-driven workflow
+
+3. **Simple scaffolding** ✅ WORKS WELL
+   - `openspec new change "name"` just worked - created directory structure without fuss
+   - **Relevance**: Good baseline, room for improvement (see pain points)
+
+---
+
+### Pain Points & Confusion
+
+1. **Redundant CLI calls** ⚠️ MEDIUM PRIORITY
+   - Users called both `status` AND `next` every time, but they overlap significantly
+   - `status` already shows what's blocked
+   - **Recommendation**: Consider merging or making `next` give actionable guidance beyond just listing names
+   - **Relevance**: Reduces friction in iterative workflow
+
+2. **Specs directory structure was ambiguous** 🔥 HIGH PRIORITY - FIX
+   - Instructions said: `Write to: .../specs/**/*.md`
+   - Users had to guess: `specs/spec.md`? `specs/game/spec.md`? `specs/tic-tac-toe/spec.md`?
+   - Users ended up doing manual `mkdir -p .../specs/tic-tac-toe` then writing `spec.md` inside
+   - **Recommendation**: CLI should scaffold this directory structure automatically
+   - **Relevance**: Critical agent UX - ambiguous paths cause workflow friction
+
+3. **Repetitive --change flag** ⚠️ MEDIUM PRIORITY
+   - Every command needed `--change "tic-tac-toe-game"`
+   - After 10+ calls, this felt verbose
+   - **Recommendation**: `openspec use "tic-tac-toe-game"` to set context, then subsequent commands assume that change
+   - **Relevance**: Quality of life improvement for iterative sessions
+
+4. **No validation feedback** 🔥 HIGH PRIORITY - ADD
+   - After writing each artifact, users just ran `status` hoping it would show `[x]`
+   - Questions raised:
+     - How did it know the artifact was "done"? File existence?
+     - What if spec format was wrong (e.g., wrong heading levels)?
+   - **Recommendation**: Add `openspec validate --change "name"` to check content quality
+   - **Relevance**: Critical for user confidence and catching errors early
+
+5. **Query-heavy, action-light CLI** 🔥 HIGH PRIORITY - ENHANCE
+   - Most commands retrieve info. The only "action" is `new change`
+   - Artifact creation is manual Write to guessed paths
+   - **Recommendation**: `openspec create proposal --change "name"` could scaffold the file with template pre-filled, then user just edits
+   - **Relevance**: Directly impacts agent productivity - reduce manual file writing
+
+6. **Instructions output was verbose** ⚠️ LOW PRIORITY
+   - XML-style output (`<artifact>`, `<template>`, `<instruction>`) was parseable but long
+   - Key info (output path, template) was buried in ~50 lines
+   - **Recommendation**: Add compact mode or structured JSON output for agents
+   - **Relevance**: Nice-to-have for agent parsing efficiency
+
+---
+
+### Workflow Friction
+
+1. **Mandatory "STOP and wait" after showing proposal template** ⚠️ MEDIUM PRIORITY
+   - The skill said "STOP and wait" after showing the proposal template
+   - This felt overly cautious when user had already provided enough context (e.g., "tic tac toe, single player vs AI, minimal aesthetics")
+   - **Recommendation**: Make the pause optional or conditional based on context clarity
+   - **Relevance**: Reduces unnecessary round-trips in agent conversations
+
+2. **No connection to implementation** 🔥 HIGH PRIORITY - ROADMAP ITEM
+   - After 4/4 artifacts complete, then what? The workflow ends at planning
+   - No `openspec apply` or guidance on how to execute the tasks
+   - User asked "would you like me to implement?" but that's outside OpenSpec's scope currently
+   - **Recommendation**: Add implementation bridge - either:
+     - `openspec apply` command to start execution phase
+     - Clear handoff to existing `/openspec:apply` workflow
+     - Documentation on next steps after planning completes
+   - **Relevance**: Critical missing piece - users expect end-to-end workflow
+
+---
+
+### Priority Summary
+
+**MUST FIX (High Priority):**
+1. Specs directory structure ambiguity (#2)
+2. Add validation feedback (#4)
+3. Make CLI more action-oriented (#5)
+4. Bridge to implementation phase (#2 in Workflow Friction)
+5. Keep clear dependency graph (#1 in What Worked)
+6. Keep structured instructions (#2 in What Worked)
+
+**SHOULD FIX (Medium Priority):**
+1. Reduce redundant CLI calls (#1)
+2. Repetitive `--change` flag (#3)
+3. Mandatory STOP behavior (#1 in Workflow Friction)
+
+**NICE TO HAVE (Low Priority):**
+1. Compact instructions output mode (#6)
+
+---
+
+## Design Decisions (from E2E Testing Feedback)
+
+Based on dev testing and analysis of agent workflow friction, we identified three blockers for experimental release and made the following decisions.
+
+### Blockers Identified
+
+From the pain points in E2E testing, three issues are blocking the experimental release:
+
+1. **Specs directory ambiguity** - Agents don't know where to write spec files or how to name capabilities
+2. **CLI is query-heavy** - Most commands retrieve info, artifact creation is manual
+3. **Apply integration missing** - After 4/4 artifacts complete, no guidance on implementation phase
+
+### Decision 1: Capability Discovery in Proposal (RESOLVED)
+
+**Problem:** The specs artifact instruction says "Create one spec file per capability in `specs/<name>/spec.md`" but:
+- Agent doesn't know what `<name>` should be
+- Capability identification requires research (existing specs, codebase)
+- Proposal template asks for "Affected specs" but doesn't structure it
+- Research happens implicitly, output isn't captured
+
+**Decision:** Enrich the proposal template to explicitly capture capability discovery.
+
+**Current proposal template:**
+```markdown
+## Why
+## What Changes
+## Impact
+- Affected specs: List capabilities...  ← vague, easy to skip
+- Affected code: ...
+```
+
+**New proposal template:**
+```markdown
+## Why
+## What Changes
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced (will create new specs/<name>/spec.md) -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities being changed (will update existing specs) -->
+- `<existing-name>`: <what's changing>
+
+## Impact
+<!-- Affected code, APIs, dependencies, systems -->
+```
+
+**Rationale:**
+- Proposal already asks for capabilities (just poorly) - this makes it explicit
+- Captured output is reviewable (vs implicit research that can't be verified)
+- Creates clear contract between proposal and specs phases
+- Distinguishes NEW vs MODIFIED upfront (critical for specs phase)
+- Agent can't skip research - it's part of the deliverable
+
+**Implementation:**
+- Update `schemas/spec-driven/templates/proposal.md`
+- Update proposal instruction in `schemas/spec-driven/schema.yaml`
+- Update skill instructions to guide capability discovery
+
+### Decision 2: CLI Action Commands (IN PROGRESS)
+
+**Problem:** CLI is mostly query-oriented. Agents run `openspec status`, `openspec next`, `openspec instructions` but then must manually write files.
+
+#### Decision 2a: Remove `openspec next` command (RESOLVED)
+
+**Problem:** The `next` command is redundant. It only shows which artifacts are ready, but `status` already shows this information (artifacts with status "ready" vs "blocked" vs "done").
+
+**Current behavior:**
+```bash
+openspec status --change "X"  # Shows: proposal (done), specs (ready), design (blocked), tasks (blocked)
+openspec next --change "X"    # Shows: ["specs"]  ← redundant
+```
+
+**Decision:** Remove the `next` command. Agents should use `status` which provides the same info plus more context.
+
+**Implementation:**
+- Remove `next` command from CLI
+- Update skill instructions to use `status` instead of `next`
+- Update AGENTS.md references
+
+#### Decision 2b: CLI Scaffolding (RESOLVED - NO)
+
+**Problem:** After getting instructions, agents manually write files. Should CLI scaffold artifacts instead?
+
+**Options considered:**
+- Add `openspec create <artifact>` commands that scaffold files with templates
+- Keep current approach where agent writes files directly from instructions
+- Hybrid: CLI can scaffold, agent can also write directly
+
+**Decision:** Keep current flow. No scaffolding commands.
+
+**Rationale (from agent ergonomics perspective):**
+- One Write is better than multiple Edits - agent composes full content atomically
+- `instructions` already provides template in context - scaffolding just moves it to a file
+- Fewer tool calls: `instructions` + Write (2) vs `create` + `instructions` + Read + Edit×N (4+)
+- Scaffolding doesn't solve the real problem (not knowing WHAT to write)
+- Real problem solved by proposal template change (capability discovery)
+
+**For multi-file artifacts (specs):** Scaffolding can't help because CLI doesn't know capability names until proposal is complete. The capability discovery in proposal solves this.
+
+### Decision 3: Apply Integration (RESOLVED)
+
+**Original problem:** After planning completes (4/4 artifacts), the experimental workflow ends. No guidance on implementation.
+
+**Key insight: No phases, just actions.**
+
+Through discussion, we realized phases (planning → implementation → archive) are an artificial constraint. Work is fluid:
+- You might start implementing, realize the design is wrong → update design.md
+- You're halfway through tasks, discover a new requirement → update specs
+- You bounce between "planning" and "implementing" constantly
+
+**The better model: Actions on a Change**
+
+A change is a thing (with artifacts). Actions are verbs you perform on a change. Actions aren't phases - they're fluid operations you can perform anytime.
+
+| Action | What it does | Skill | CLI Command |
+|--------|--------------|-------|-------------|
+| `new` | Create a change (scaffold directory) | `opsx:new` | `openspec new change` |
+| `continue` | Create next artifact (dependency-aware) | `opsx:continue` | `openspec instructions` |
+| `apply` | Implement tasks (execute, check off) | `opsx:apply` (NEW) | TBD |
+| `update` | Refresh/update artifacts based on learnings | `opsx:update` (NEW) | TBD |
+| `explore` | Research, ask questions, understand | `opsx:explore` (NEW) | TBD |
+| `validate` | Check artifacts are correct/complete | TBD | `openspec validate` |
+| `archive` | Finalize and move to archive | existing | `openspec archive` |
+
+**Key principles:**
+- Actions are modeled as skills (primary interface for agents)
+- Some skills have matching CLI commands for convenience
+- Skills and CLI commands are decoupled - not everything needs both
+- Actions can be performed in any order (with soft prerequisites)
+- No linear phase gates
+
+**What the schema defines:**
+- Artifacts (what they are, where they go)
+- Dependencies (what must exist first)
+- Required vs optional
+- Templates + instructions
+
+**What the schema does NOT define:**
+- Phases
+- When you can modify things
+- Linear workflow
+
+**Progress tracking:**
+- tasks.md checkboxes = implementation progress
+- Artifact existence = planning progress
+- Archive readiness = user decides (or all tasks done)
+
+**For experimental release:**
+- Create `opsx:apply` skill (guidance for implementing tasks)
+- Document the "actions on a change" model
+- Other actions (update, explore) can come later
+
+---
+
+### Design: `openspec-apply-change` Skill
+
+#### Overview
+
+The apply skill guides agents through implementing tasks from a completed (or in-progress) change. Unlike the old `/openspec:apply` command, this skill:
+- Is **fluid** - can be invoked anytime, not just after all artifacts are done
+- Allows **artifact updates** - if implementation reveals issues, update design/specs
+- Works **until done** - keeps going through tasks until complete or blocked
+- Tracks **progress via checkboxes** - tasks.md is the source of truth
+
+#### Skill Metadata
+
+```yaml
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+```
+
+#### When to Invoke
+
+The skill should be invoked when:
+- User says "implement this change" or "start implementing"
+- User says "work on the tasks" or "do the next task"
+- User says "apply this change"
+- All artifacts are complete and user wants to proceed
+- User wants to continue implementation after a break
+
+#### Input
+
+- Optionally: change name
+- Optionally: specific task number to work on
+- If omitted: prompt for change selection (same pattern as continue-change)
+
+#### Steps
+
+```markdown
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use **AskUserQuestion** to let user select.
+
+   Show changes that have tasks.md (implementation-ready).
+   Mark changes with incomplete tasks as "(In Progress)".
+
+2. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (proposal, specs, design, tasks)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If blocked (missing artifacts): show message, suggest `openspec-continue-change`
+   - If all done: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+3. **Read context files**
+
+   Read the files listed in the instructions:
+   - `proposal.md` - why and what
+   - `specs/*.md` - requirements and scenarios
+   - `design.md` - technical approach (if exists)
+   - `tasks.md` - the implementation checklist
+
+4. **Show current progress**
+
+   Display:
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+5. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in tasks.md: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+6. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+```
+
+#### Output Format
+
+**During implementation:**
+```
+## Implementing: add-user-auth
+
+Working on task 3/7: Create UserAuth service class
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: Add login endpoint to AuthController
+[...implementation happening...]
+✓ Task complete
+
+Working on task 5/7: Add JWT token generation
+[...implementation happening...]
+```
+
+**On completion:**
+```
+## Implementation Complete
+
+**Change:** add-user-auth
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Create UserAuth service class
+- [x] Add login endpoint to AuthController
+- [x] Add JWT token generation
+- [x] Add logout endpoint
+- [x] Add auth middleware
+- [x] Write unit tests
+- [x] Update API documentation
+
+All tasks complete! Ready to archive this change.
+```
+
+**On pause (issue encountered):**
+```
+## Implementation Paused
+
+**Change:** add-user-auth
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+Task 5 "Add JWT token generation" - the design specifies using RS256 but
+the existing auth library only supports HS256.
+
+**Options:**
+1. Update design.md to use HS256 instead
+2. Add a new JWT library that supports RS256
+3. Other approach
+
+What would you like to do?
+```
+
+#### Guardrails
+
+- Keep going through tasks until done or blocked
+- Always read context before starting (specs, design)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+
+#### Fluid Workflow Integration
+
+The apply skill supports the "actions on a change" model:
+
+**Can be invoked anytime:**
+- Before all artifacts are done (if tasks.md exists)
+- After partial implementation
+- Interleaved with other actions (update, continue)
+
+**Allows artifact updates:**
+- If implementation reveals design issues → suggest `opsx:update` or manual edit
+- If requirements need clarification → suggest updating specs
+- Not phase-locked - work fluidly
+
+**Example fluid workflow:**
+```
+User: "Implement add-user-auth"
+→ openspec-apply-change: implements tasks 1, 2, 3, 4...
+→ Pauses at task 5: "Design says RS256 but library only supports HS256"
+
+User: "Let's use HS256 instead, update the design"
+→ User edits design.md (or uses opsx:update in future)
+
+User: "Continue implementing"
+→ openspec-apply-change: implements tasks 5, 6, 7
+→ "All tasks complete! Ready to archive."
+```
+
+#### CLI Commands Used
+
+```bash
+openspec list --json                        # List changes for selection
+openspec status --change "<name>"           # Check artifact completion
+openspec instructions apply --change "<name>" # Get apply instructions (NEW)
+# File reads via Read tool for proposal, specs, design, tasks
+# File edits via Edit tool for checking off tasks
+```
+
+#### New CLI Command: `openspec instructions apply`
+
+For consistency with artifact instructions.
+
+**Usage:**
+```bash
+openspec instructions apply --change "<name>" [--json]
+```
+
+**Output (Markdown format):**
+```markdown
+## Apply: add-user-auth
+
+### Context Files
+- proposal: openspec/changes/add-user-auth/proposal.md
+- specs: openspec/changes/add-user-auth/specs/**/*.md
+- design: openspec/changes/add-user-auth/design.md
+- tasks: openspec/changes/add-user-auth/tasks.md
+
+### Progress
+2/7 complete
+
+### Tasks
+- [x] Create UserAuth service class
+- [x] Add login endpoint
+- [ ] Add JWT token generation
+- [ ] Add logout endpoint
+- [ ] Add auth middleware
+- [ ] Write unit tests
+- [ ] Update API documentation
+
+### Instruction
+Read context files, work through pending tasks, mark complete as you go.
+Pause if you hit blockers or need clarification.
+```
+
+**Benefits of CLI command:**
+- **Consistency** - same pattern as `openspec instructions <artifact>`
+- **Structured output** - progress, tasks, context paths in one call
+- **Clean format** - markdown is readable and compact (vs verbose XML)
+- **Extensibility** - can add more sections later if needed
+- **JSON option** - `--json` flag available for programmatic use
+
+#### Differences from Old `/openspec:apply`
+
+| Aspect | Old `/openspec:apply` | New `openspec-apply-change` |
+|--------|----------------------|----------------------------|
+| Invocation | After all artifacts done | Anytime (if tasks.md exists) |
+| Granularity | All tasks at once | All tasks, but pauses on issues |
+| Artifact updates | Not mentioned | Encouraged when needed |
+| Progress tracking | Update all at end | Update after each task |
+| Flow control | Push through everything | Pause on blockers, resume after |
+| Context loading | Read once at start | Read context, reference as needed |
+| Issue handling | Not specified | Pause, present options, wait for guidance |
+
+#### Implementation Notes
+
+1. **Add CLI command**: Add `openspec instructions apply` to artifact-workflow.ts
+   - Parse tasks.md for progress (count done/pending)
+   - Return context paths, progress, task list, simple instruction
+2. **Add to skill-templates.ts**: Create `getApplyChangeSkillTemplate()` function
+3. **Update artifact-experimental-setup**: Generate this skill alongside new/continue
+4. **Update skills list**: Add to `.claude/skills/` directory
+5. **Test the flow**: Verify it works with existing changes that have tasks.md
+
+---
+
+## Next Steps
+
+1. ~~Review this plan and confirm scope~~ (Done - blockers identified)
+2. ~~Design decisions~~ (Done - all 3 blockers resolved)
+3. ~~Design apply skill~~ (Done - documented above)
+4. ~~Implement proposal template change (Decision 1 - capability discovery)~~ (Done)
+5. ~~Remove `openspec next` command (Decision 2a)~~ (Done)
+6. ~~Add `openspec instructions apply` CLI command~~ (Done)
+7. ~~Create `openspec-apply-change` skill~~ (Done)
+8. Conduct E2E testing with updated workflow
+9. Write user docs (document "actions on a change" model)
+10. Release to test users
@@ -1,16 +1,16 @@
-# OPSX Workflow
+# Experimental Workflow (OPSX)

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

 ## What Is It?

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

 ## Why This Exists

-The legacy OpenSpec workflow works, but it's **locked down**:
+The standard OpenSpec workflow works, but it's **locked down**:

 - **Instructions are hardcoded** — buried in TypeScript, you can't change them
 - **All-or-nothing** — one big command creates everything, can't test individual pieces
@@ -25,7 +25,7 @@ The legacy OpenSpec workflow works, but it's **locked down**:
 4. **Iterate quickly** — change a template, test immediately, no rebuild

 ```
-Legacy workflow:                      OPSX:
+Standard workflow:                    OPSX:
 ┌────────────────────────┐           ┌────────────────────────┐
 │  Hardcoded in package  │           │  schema.yaml           │◄── You edit this
 │  (can't change)        │           │  templates/*.md        │◄── Or this
@@ -51,21 +51,32 @@ You're "in planning phase", then "in implementation phase", then "done". But rea
 **OPSX approach:**
 - **Actions, not phases** — create, implement, update, archive — do any of them anytime
 - **Dependencies are enablers** — they show what's possible, not what's required next
+- **Update as you learn** — halfway through implementation? Go back and fix the design. That's normal.

 ```
+You can always go back:
+
+     ┌────────────────────────────────────┐
+     │                                    │
+     ▼                                    │
  proposal ──→ specs ──→ design ──→ tasks ──→ implement
+     ▲           ▲          ▲               │
+     │           │          │               │
+     └───────────┴──────────┴───────────────┘
+              update as you learn
 ```

 ## Setup

 ```bash
-# Make sure you have openspec installed — skills are automatically generated
+# 1. Make sure you have openspec installed and initialized
 openspec init
+
+# 2. Generate the experimental skills
+openspec experimental
 ```

-This creates skills in `.claude/skills/` (or equivalent) that AI coding assistants auto-detect.
-
-By default, OpenSpec uses the `core` workflow profile (`propose`, `explore`, `apply`, `sync`, `archive`). If you want the expanded workflow commands (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`), configure them with `openspec config profile` and apply with `openspec update`.
+This creates skills in `.claude/skills/` that Claude Code auto-detects.

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

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

 ### Creating Config

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

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

 | Field | Type | Description |
 |-------|------|-------------|
-| `schema` | string | Default schema for new changes (e.g., `spec-driven`) |
+| `schema` | string | Default schema for new changes (e.g., `spec-driven`, `tdd`) |
 | `context` | string | Project context injected into all artifact instructions |
 | `rules` | object | Per-artifact rules, keyed by artifact ID |

 ### How It Works

 **Schema precedence** (highest to lowest):
-1. CLI flag (`--schema <name>`)
+1. CLI flag (`--schema tdd`)
 2. Change metadata (`.openspec.yaml` in change directory)
 3. Project config (`openspec/config.yaml`)
 4. Default (`spec-driven`)
@@ -131,6 +142,12 @@ rules:
 - `design` — Technical design
 - `tasks` — Implementation tasks

+**tdd**:
+- `spec` — Feature specification
+- `tests` — Test file
+- `implementation` — Implementation code
+- `docs` — Documentation
+
 ### Config Validation

 - Unknown artifact IDs in `rules` generate warnings
@@ -157,17 +174,13 @@ rules:

 | Command | What it does |
 |---------|--------------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step (default quick path) |
 | `/opsx:explore` | Think through ideas, investigate problems, clarify requirements |
-| `/opsx:new` | Start a new change scaffold (expanded workflow) |
-| `/opsx:continue` | Create the next artifact (expanded workflow) |
-| `/opsx:ff` | Fast-forward planning artifacts (expanded workflow) |
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward — create all planning artifacts at once |
 | `/opsx:apply` | Implement tasks, updating artifacts as needed |
-| `/opsx:verify` | Validate implementation against artifacts (expanded workflow) |
-| `/opsx:sync` | Sync delta specs to main (default workflow, optional) |
+| `/opsx:sync` | Sync delta specs to main specs |
 | `/opsx:archive` | Archive when done |
-| `/opsx:bulk-archive` | Archive multiple completed changes (expanded workflow) |
-| `/opsx:onboard` | Guided walkthrough of an end-to-end change (expanded workflow) |

 ## Usage

@@ -175,21 +188,13 @@ rules:
 ```
 /opsx:explore
 ```
-Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:propose` (default) or `/opsx:new`/`/opsx:ff` (expanded).
+Think through ideas, investigate problems, compare options. No structure required - just a thinking partner. When insights crystallize, transition to `/opsx:new` or `/opsx:ff`.

 ### Start a new change
 ```
-/opsx:propose
-```
-Creates the change and generates planning artifacts needed before implementation.
-
-If you've enabled expanded workflows, you can instead use:
-
-```text
-/opsx:new        # scaffold only
-/opsx:continue   # create one artifact at a time
-/opsx:ff         # create all planning artifacts at once
+/opsx:new
 ```
+You'll be asked what you want to build and which workflow schema to use.

 ### Create artifacts
 ```
@@ -206,16 +211,17 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
 ```
 /opsx:apply
 ```
-Works through tasks, checking them off as you go. If you're juggling multiple changes, you can run `/opsx:apply <name>`; otherwise it should infer from the conversation and prompt you to choose if it can't tell.
+Works through tasks, checking them off as you go. **Key difference:** if you discover issues during implementation, you can update your specs, design, or tasks — then continue. No phase gates. If you're juggling multiple changes, you can run `/opsx:apply <name>`; otherwise it should infer from the conversation and prompt you to choose if it can’t tell.

 ### Finish up
 ```
-/opsx:archive   # Move to archive when done (prompts to sync specs if needed)
+/opsx:sync      # Update main specs with your delta specs
+/opsx:archive   # Move to archive when done
 ```

 ## When to Update vs. Start Fresh

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

 ### What a Proposal Captures

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

 ## What's Different?

-| | Legacy (`/openspec:proposal`) | OPSX (`/opsx:*`) |
+| | Standard (`/openspec:proposal`) | Experimental (`/opsx:*`) |
 |---|---|---|
 | **Structure** | One big proposal document | Discrete artifacts with dependencies |
 | **Workflow** | Linear phases: plan → implement → archive | Fluid actions — do anything anytime |
@@ -312,14 +318,13 @@ Think of it like git branches:

 ## Architecture Deep Dive

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

 ### Philosophy: Phases vs Actions

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

 ### Component Architecture

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

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

 ### Information Flow

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

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

 ### Iteration Model

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

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

 ### Summary

-| Aspect | Legacy | OPSX |
+| Aspect | Standard | OPSX |
 |--------|----------|------|
 | **Templates** | Hardcoded TypeScript | External YAML + Markdown |
 | **Dependencies** | None (all at once) | DAG with topological sort |
 | **State** | Phase-based mental model | Filesystem existence |
 | **Customization** | Edit source, rebuild | Create schema.yaml |
 | **Iteration** | Phase-locked | Fluid, edit anything |
-| **Editor Support** | Tool-specific configurator/adapters | Single skills directory |
+| **Editor Support** | 18+ configurator classes | Single skills directory |

 ## Schemas

 Schemas define what artifacts exist and their dependencies. Currently available:

 - **spec-driven** (default): proposal → specs → design → tasks
+- **tdd**: tests → implementation → docs

 ```bash
 # List available schemas
@@ -1,253 +0,0 @@
-# Getting Started
-
-This guide explains how OpenSpec works after you've installed and initialized it. For installation instructions, see the [main README](../README.md#quick-start).
-
-## How It Works
-
-OpenSpec helps you and your AI coding assistant agree on what to build before any code is written.
-
-**Default quick path (core profile):**
-
-```text
-/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-```
-
-**Expanded path (custom workflow selection):**
-
-```text
-/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
-```
-
-The default global profile is `core`, which includes `propose`, `explore`, `apply`, `sync`, and `archive`. You can enable the expanded workflow commands with `openspec config profile` and then `openspec update`.
-
-## What OpenSpec Creates
-
-After running `openspec init`, your project has this structure:
-
-```
-openspec/
-├── specs/              # Source of truth (your system's behavior)
-│   └── <domain>/
-│       └── spec.md
-├── changes/            # Proposed updates (one folder per change)
-│   └── <change-name>/
-│       ├── proposal.md
-│       ├── design.md
-│       ├── tasks.md
-│       └── specs/      # Delta specs (what's changing)
-│           └── <domain>/
-│               └── spec.md
-└── config.yaml         # Project configuration (optional)
-```
-
-**Two key directories:**
-
- **`specs/`** - The source of truth. These specs describe how your system currently behaves. Organized by domain (e.g., `specs/auth/`, `specs/payments/`).
-
- **`changes/`** - Proposed modifications. Each change gets its own folder with all related artifacts. When a change is complete, its specs merge into the main `specs/` directory.
-
-## Understanding Artifacts
-
-Each change folder contains artifacts that guide the work:
-
-| Artifact | Purpose |
-|----------|---------|
-| `proposal.md` | The "why" and "what" - captures intent, scope, and approach |
-| `specs/` | Delta specs showing ADDED/MODIFIED/REMOVED requirements |
-| `design.md` | The "how" - technical approach and architecture decisions |
-| `tasks.md` | Implementation checklist with checkboxes |
-
-**Artifacts build on each other:**
-
-```
-proposal ──► specs ──► design ──► tasks ──► implement
-   ▲           ▲          ▲                    │
-   └───────────┴──────────┴────────────────────┘
-            update as you learn
-```
-
-You can always go back and refine earlier artifacts as you learn more during implementation.
-
-## How Delta Specs Work
-
-Delta specs are the key concept in OpenSpec. They show what's changing relative to your current specs.
-
-### The Format
-
-Delta specs use sections to indicate the type of change:
-
-```markdown
-# Delta for Auth
-
-## ADDED Requirements
-
-### Requirement: Two-Factor Authentication
-The system MUST require a second factor during login.
-
-#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
-
-## MODIFIED Requirements
-
-### Requirement: Session Timeout
-The system SHALL expire sessions after 30 minutes of inactivity.
-(Previously: 60 minutes)
-
-#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated
-
-## REMOVED Requirements
-
-### Requirement: Remember Me
-(Deprecated in favor of 2FA)
-```
-
-### What Happens on Archive
-
-When you archive a change:
-
-1. **ADDED** requirements are appended to the main spec
-2. **MODIFIED** requirements replace the existing version
-3. **REMOVED** requirements are deleted from the main spec
-
-The change folder moves to `openspec/changes/archive/` for audit history.
-
-## Example: Your First Change
-
-Let's walk through adding dark mode to an application.
-
-### 1. Start the Change (Default)
-
-```text
-You: /opsx:propose add-dark-mode
-
-AI:  Created openspec/changes/add-dark-mode/
-     ✓ proposal.md — why we're doing this, what's changing
-     ✓ specs/       — requirements and scenarios
-     ✓ design.md    — technical approach
-     ✓ tasks.md     — implementation checklist
-     Ready for implementation!
-```
-
-If you've enabled the expanded workflow profile, you can also do this as two steps: `/opsx:new` then `/opsx:ff` (or `/opsx:continue` incrementally).
-
-### 2. What Gets Created
-
-**proposal.md** - Captures the intent:
-
-```markdown
-# Proposal: Add Dark Mode
-
-## Intent
-Users have requested a dark mode option to reduce eye strain
-during nighttime usage.
-
-## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage
-
-## Approach
-Use CSS custom properties for theming with a React context
-for state management.
-```
-
-**specs/ui/spec.md** - Delta showing new requirements:
-
-```markdown
-# Delta for UI
-
-## ADDED Requirements
-
-### Requirement: Theme Selection
-The system SHALL allow users to choose between light and dark themes.
-
-#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions
-
-#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used
-```
-
-**tasks.md** - Implementation checklist:
-
-```markdown
-# Tasks
-
-## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence
-
-## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
-
-## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
-```
-
-### 3. Implement
-
-```
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ 1.1 Created ThemeContext with light/dark state
-     ✓ 1.2 Added CSS custom properties to globals.css
-     ✓ 1.3 Implemented localStorage persistence
-     ✓ 2.1 Created ThemeToggle component
-     ...
-     All tasks complete!
-```
-
-During implementation, if you discover the design needs adjustment, just update the artifact and continue.
-
-### 4. Archive
-
-```
-You: /opsx:archive
-
-AI:  Archiving add-dark-mode...
-     ✓ Merged specs into openspec/specs/ui/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
-     Done! Ready for the next feature.
-```
-
-Your delta specs are now part of the main specs, documenting how your system works.
-
-## Verifying and Reviewing
-
-Use the CLI to check on your changes:
-
-```bash
-# List active changes
-openspec list
-
-# View change details
-openspec show add-dark-mode
-
-# Validate spec formatting
-openspec validate add-dark-mode
-
-# Interactive dashboard
-openspec view
-```
-
-## Next Steps
-
- [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
@@ -1,120 +0,0 @@
-# Installation
-
-## Prerequisites
-
- **Node.js 20.19.0 or higher** — Check your version: `node --version`
-
-## Package Managers
-
-### npm
-
-```bash
-npm install -g @fission-ai/openspec@latest
-```
-
-### pnpm
-
-```bash
-pnpm add -g @fission-ai/openspec@latest
-```
-
-### yarn
-
-```bash
-yarn global add @fission-ai/openspec@latest
-```
-
-### bun
-
-Bun can install OpenSpec globally, but OpenSpec currently runs on Node.js.
-You still need Node.js 20.19.0 or higher available on `PATH`.
-
-```bash
-bun add -g @fission-ai/openspec@latest
-```
-
-## Nix
-
-Run OpenSpec directly without installation:
-
-```bash
-nix run github:Fission-AI/OpenSpec -- init
-```
-
-Or install to your profile:
-
-```bash
-nix profile install github:Fission-AI/OpenSpec
-```
-
-Or add to your development environment in `flake.nix`:
-
-```nix
-{
-  inputs = {
-    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
-    openspec.url = "github:Fission-AI/OpenSpec";
-  };
-
-  outputs = { nixpkgs, openspec, ... }: {
-    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
-      buildInputs = [ openspec.packages.x86_64-linux.default ];
-    };
-  };
-}
-```
-
-## Verify Installation
-
-```bash
-openspec --version
-```
-
-## Troubleshooting PATH Visibility
-
-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
-printf '%s/bin\n' "$(npm prefix -g)"
-
-# pnpm
-pnpm bin -g
-
-# bun
-bun pm bin -g
-
-# current shell
-command -v openspec
-```
-
-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.
-
-To bypass global bin discovery while debugging, run OpenSpec through a package
-manager:
-
-```bash
-npx -y @fission-ai/openspec@latest --version
-pnpm dlx @fission-ai/openspec@latest --version
-```
-
-## Next Steps
-
-After installing, initialize OpenSpec in your project:
-
-```bash
-cd your-project
-openspec init
-```
-
-See [Getting Started](getting-started.md) for a full walkthrough.
@@ -1,596 +0,0 @@
-# Migrating to OPSX
-
-This guide helps you transition from the legacy OpenSpec workflow to OPSX. The migration is designed to be smooth—your existing work is preserved, and the new system offers more flexibility.
-
-## What's Changing?
-
-OPSX replaces the old phase-locked workflow with a fluid, action-based approach. Here's the key shift:
-
-| Aspect | Legacy | OPSX |
-|--------|--------|------|
-| **Commands** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | Default: `/opsx:propose`, `/opsx:apply`, `/opsx:sync`, `/opsx:archive` (expanded workflow commands optional) |
-| **Workflow** | Create all artifacts at once | Create incrementally or all at once—your choice |
-| **Going back** | Awkward phase gates | Natural—update any artifact anytime |
-| **Customization** | Fixed structure | Schema-driven, fully hackable |
-| **Configuration** | `CLAUDE.md` with markers + `project.md` | Clean config in `openspec/config.yaml` |
-
-**The philosophy change:** Work isn't linear. OPSX stops pretending it is.
-
---
-
-## Before You Begin
-
-### Your Existing Work Is Safe
-
-The migration process is designed with preservation in mind:
-
- **Active changes in `openspec/changes/`** — Completely preserved. You can continue them with OPSX commands.
- **Archived changes** — Untouched. Your history remains intact.
- **Main specs in `openspec/specs/`** — Untouched. These are your source of truth.
- **Your content in CLAUDE.md, AGENTS.md, etc.** — Preserved. Only the OpenSpec marker blocks are removed; everything you wrote stays.
-
-### What Gets Removed
-
-Only OpenSpec-managed files that are being replaced:
-
-| What | Why |
-|------|-----|
-| Legacy slash command directories/files | Replaced by the new skills system |
-| `openspec/AGENTS.md` | Obsolete workflow trigger |
-| OpenSpec markers in `CLAUDE.md`, `AGENTS.md`, etc. | No longer needed |
-
-**Legacy command locations by tool** (examples—your tool may vary):
-
- Claude Code: `.claude/commands/openspec/`
- Cursor: `.cursor/commands/openspec-*.md`
- Windsurf: `.windsurf/workflows/openspec-*.md`
- Cline: `.clinerules/workflows/openspec-*.md`
- Roo: `.roo/commands/openspec-*.md`
- GitHub Copilot: `.github/prompts/openspec-*.prompt.md` (IDE extensions only; not supported in Copilot CLI)
- And others (Augment, Continue, Amazon Q, etc.)
-
-The migration detects whichever tools you have configured and cleans up their legacy files.
-
-The removal list may seem long, but these are all files that OpenSpec originally created. Your own content is never deleted.
-
-### What Needs Your Attention
-
-One file requires manual migration:
-
-**`openspec/project.md`** — This file isn't deleted automatically because it may contain project context you've written. You'll need to:
-
-1. Review its contents
-2. Move useful context to `openspec/config.yaml` (see guidance below)
-3. Delete the file when ready
-
-**Why we made this change:**
-
-The old `project.md` was passive—agents might read it, might not, might forget what they read. We found reliability was inconsistent.
-
-The new `config.yaml` context is **actively injected into every OpenSpec planning request**. This means your project conventions, tech stack, and rules are always present when the AI is creating artifacts. Higher reliability.
-
-**The tradeoff:**
-
-Because context is injected into every request, you'll want to be concise. Focus on what really matters:
- Tech stack and key conventions
- Non-obvious constraints the AI needs to know
- Rules that frequently got ignored before
-
-Don't worry about getting it perfect. We're still learning what works best here, and we'll be improving how context injection works as we experiment.
-
---
-
-## Running the Migration
-
-Both `openspec init` and `openspec update` detect legacy files and guide you through the same cleanup process. Use whichever fits your situation:
-
- New installs default to profile `core` (`propose`, `explore`, `apply`, `sync`, `archive`).
- Migrated installs preserve your previously installed workflows by writing a `custom` profile when needed.
-
-### Using `openspec init`
-
-Run this if you want to add new tools or reconfigure which tools are set up:
-
-```bash
-openspec init
-```
-
-The init command detects legacy files and guides you through cleanup:
-
-```
-Upgrading to the new OpenSpec
-
-OpenSpec now uses agent skills, the emerging standard across coding
-agents. This simplifies your setup while keeping everything working
-as before.
-
-Files to remove
-No user content to preserve:
-  • .claude/commands/openspec/
-  • openspec/AGENTS.md
-
-Files to update
-OpenSpec markers will be removed, your content preserved:
-  • CLAUDE.md
-  • AGENTS.md
-
-Needs your attention
-  • openspec/project.md
-    We won't delete this file. It may contain useful project context.
-
-    The new openspec/config.yaml has a "context:" section for planning
-    context. This is included in every OpenSpec request and works more
-    reliably than the old project.md approach.
-
-    Review project.md, move any useful content to config.yaml's context
-    section, then delete the file when ready.
-
-? Upgrade and clean up legacy files? (Y/n)
-```
-
-**What happens when you say yes:**
-
-1. Legacy slash command directories are removed
-2. OpenSpec markers are stripped from `CLAUDE.md`, `AGENTS.md`, etc. (your content stays)
-3. `openspec/AGENTS.md` is deleted
-4. New skills are installed in `.claude/skills/`
-5. `openspec/config.yaml` is created with a default schema
-
-### Using `openspec update`
-
-Run this if you just want to migrate and refresh your existing tools to the latest version:
-
-```bash
-openspec update
-```
-
-The update command also detects and cleans up legacy artifacts, then refreshes generated skills/commands to match your current profile and delivery settings.
-
-### Non-Interactive / CI Environments
-
-For scripted migrations:
-
-```bash
-openspec init --force --tools claude
-```
-
-The `--force` flag skips prompts and auto-accepts cleanup.
-
---
-
-## Migrating project.md to config.yaml
-
-The old `openspec/project.md` was a freeform markdown file for project context. The new `openspec/config.yaml` is structured and—critically—**injected into every planning request** so your conventions are always present when the AI works.
-
-### Before (project.md)
-
-```markdown
-# Project Context
-
-This is a TypeScript monorepo using React and Node.js.
-We use Jest for testing and follow strict ESLint rules.
-Our API is RESTful and documented in docs/api.md.
-
-## Conventions
-
- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications
-```
-
-### After (config.yaml)
-
-```yaml
-schema: spec-driven
-
-context: |
-  Tech stack: TypeScript, React, Node.js
-  Testing: Jest with React Testing Library
-  API: RESTful, documented in docs/api.md
-  We maintain backwards compatibility for all public APIs
-
-rules:
-  proposal:
-    - Include rollback plan for risky changes
-  specs:
-    - Use Given/When/Then format for scenarios
-    - Reference existing patterns before inventing new ones
-  design:
-    - Include sequence diagrams for complex flows
-```
-
-### Key Differences
-
-| project.md | config.yaml |
-|------------|-------------|
-| Freeform markdown | Structured YAML |
-| One blob of text | Separate context and per-artifact rules |
-| Unclear when it's used | Context appears in ALL artifacts; rules appear in matching artifacts only |
-| No schema selection | Explicit `schema:` field sets default workflow |
-
-### What to Keep, What to Drop
-
-When migrating, be selective. Ask yourself: "Does the AI need this for *every* planning request?"
-
-**Good candidates for `context:`**
- Tech stack (languages, frameworks, databases)
- Key architectural patterns (monorepo, microservices, etc.)
- Non-obvious constraints ("we can't use library X because...")
- Critical conventions that often get ignored
-
-**Move to `rules:` instead**
- Artifact-specific formatting ("use Given/When/Then in specs")
- Review criteria ("proposals must include rollback plans")
- These only appear for the matching artifact, keeping other requests lighter
-
-**Leave out entirely**
- General best practices the AI already knows
- Verbose explanations that could be summarized
- Historical context that doesn't affect current work
-
-### Migration Steps
-
-1. **Create config.yaml** (if not already created by init):
-   ```yaml
-   schema: spec-driven
-   ```
-
-2. **Add your context** (be concise—this goes into every request):
-   ```yaml
-   context: |
-     Your project background goes here.
-     Focus on what the AI genuinely needs to know.
-   ```
-
-3. **Add per-artifact rules** (optional):
-   ```yaml
-   rules:
-     proposal:
-       - Your proposal-specific guidance
-     specs:
-       - Your spec-writing rules
-   ```
-
-4. **Delete project.md** once you've moved everything useful.
-
-**Don't overthink it.** Start with the essentials and iterate. If you notice the AI missing something important, add it. If context feels bloated, trim it. This is a living document.
-
-### Need Help? Use This Prompt
-
-If you're unsure how to distill your project.md, ask your AI assistant:
-
-```
-I'm migrating from OpenSpec's old project.md to the new config.yaml format.
-
-Here's my current project.md:
-[paste your project.md content]
-
-Please help me create a config.yaml with:
-1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
-2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)
-
-Leave out anything generic that AI models already know. Be ruthless about brevity.
-```
-
-The AI will help you identify what's essential vs. what can be trimmed.
-
---
-
-## The New Commands
-
-Command availability is profile-dependent:
-
-**Default (`core` profile):**
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:propose` | Create a change and generate planning artifacts in one step |
-| `/opsx:explore` | Think through ideas with no structure |
-| `/opsx:apply` | Implement tasks from tasks.md |
-| `/opsx:archive` | Finalize and archive the change |
-
-**Expanded workflow (custom selection):**
-
-| Command | Purpose |
-|---------|---------|
-| `/opsx:new` | Start a new change scaffold |
-| `/opsx:continue` | Create the next artifact (one at a time) |
-| `/opsx:ff` | Fast-forward—create planning artifacts at once |
-| `/opsx:verify` | Validate implementation matches specs |
-| `/opsx:sync` | Preview/spec-merge without archiving |
-| `/opsx:bulk-archive` | Archive multiple changes at once |
-| `/opsx:onboard` | Guided end-to-end onboarding workflow |
-
-Enable expanded commands with `openspec config profile`, then run `openspec update`.
-
-### Command Mapping from Legacy
-
-| Legacy | OPSX Equivalent |
-|--------|-----------------|
-| `/openspec:proposal` | `/opsx:propose` (default) or `/opsx:new` then `/opsx:ff` (expanded) |
-| `/openspec:apply` | `/opsx:apply` |
-| `/openspec:archive` | `/opsx:archive` |
-
-### New Capabilities
-
-These capabilities are part of the expanded workflow command set.
-
-**Granular artifact creation:**
-```
-/opsx:continue
-```
-Creates one artifact at a time based on dependencies. Use this when you want to review each step.
-
-**Exploration mode:**
-```
-/opsx:explore
-```
-Think through ideas with a partner before committing to a change.
-
---
-
-## Understanding the New Architecture
-
-### From Phase-Locked to Fluid
-
-The legacy workflow forced linear progression:
-
-```
-┌──────────────┐      ┌──────────────┐      ┌──────────────┐
-│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
-│    PHASE     │      │    PHASE     │      │    PHASE     │
-└──────────────┘      └──────────────┘      └──────────────┘
-
-If you're in implementation and realize the design is wrong?
-Too bad. Phase gates don't let you go back easily.
-```
-
-OPSX uses actions, not phases:
-
-```
-         ┌───────────────────────────────────────────────┐
-         │           ACTIONS (not phases)                │
-         │                                               │
-         │     new ◄──► continue ◄──► apply ◄──► archive │
-         │      │          │           │             │   │
-         │      └──────────┴───────────┴─────────────┘   │
-         │                    any order                  │
-         └───────────────────────────────────────────────┘
-```
-
-### Dependency Graph
-
-Artifacts form a directed graph. Dependencies are enablers, not gates:
-
-```
-                        proposal
-                       (root node)
-                            │
-              ┌─────────────┴─────────────┐
-              │                           │
-              ▼                           ▼
-           specs                       design
-        (requires:                  (requires:
-         proposal)                   proposal)
-              │                           │
-              └─────────────┬─────────────┘
-                            │
-                            ▼
-                         tasks
-                     (requires:
-                     specs, design)
-```
-
-When you run `/opsx:continue`, it checks what's ready and offers the next artifact. You can also create multiple ready artifacts in any order.
-
-### Skills vs Commands
-
-The legacy system used tool-specific command files:
-
-```
-.claude/commands/openspec/
-├── proposal.md
-├── apply.md
-└── archive.md
-```
-
-OPSX uses the emerging **skills** standard:
-
-```
-.claude/skills/
-├── openspec-explore/SKILL.md
-├── openspec-new-change/SKILL.md
-├── openspec-continue-change/SKILL.md
-├── openspec-apply-change/SKILL.md
-└── ...
-```
-
-Skills are recognized across multiple AI coding tools and provide richer metadata.
-
---
-
-## Continuing Existing Changes
-
-Your in-progress changes work seamlessly with OPSX commands.
-
-**Have an active change from the legacy workflow?**
-
-```
-/opsx:apply add-my-feature
-```
-
-OPSX reads the existing artifacts and continues from where you left off.
-
-**Want to add more artifacts to an existing change?**
-
-```
-/opsx:continue add-my-feature
-```
-
-Shows what's ready to create based on what already exists.
-
-**Need to see status?**
-
-```bash
-openspec status --change add-my-feature
-```
-
---
-
-## The New Config System
-
-### config.yaml Structure
-
-```yaml
-# Required: Default schema for new changes
-schema: spec-driven
-
-# Optional: Project context (max 50KB)
-# Injected into ALL artifact instructions
-context: |
-  Your project background, tech stack,
-  conventions, and constraints.
-
-# Optional: Per-artifact rules
-# Only injected into matching artifacts
-rules:
-  proposal:
-    - Include rollback plan
-  specs:
-    - Use Given/When/Then format
-  design:
-    - Document fallback strategies
-  tasks:
-    - Break into 2-hour maximum chunks
-```
-
-### Schema Resolution
-
-When determining which schema to use, OPSX checks in order:
-
-1. **CLI flag**: `--schema <name>` (highest priority)
-2. **Change metadata**: `.openspec.yaml` in the change directory
-3. **Project config**: `openspec/config.yaml`
-4. **Default**: `spec-driven`
-
-### Available Schemas
-
-| Schema | Artifacts | Best For |
-|--------|-----------|----------|
-| `spec-driven` | proposal → specs → design → tasks | Most projects |
-
-List all available schemas:
-
-```bash
-openspec schemas
-```
-
-### Custom Schemas
-
-Create your own workflow:
-
-```bash
-openspec schema init my-workflow
-```
-
-Or fork an existing one:
-
-```bash
-openspec schema fork spec-driven my-workflow
-```
-
-See [Customization](customization.md) for details.
-
---
-
-## Troubleshooting
-
-### "Legacy files detected in non-interactive mode"
-
-You're running in a CI or non-interactive environment. Use:
-
-```bash
-openspec init --force
-```
-
-### Commands not appearing after migration
-
-Restart your IDE. Skills are detected at startup.
-
-### "Unknown artifact ID in rules"
-
-Check that your `rules:` keys match your schema's artifact IDs:
-
- **spec-driven**: `proposal`, `specs`, `design`, `tasks`
-
-Run this to see valid artifact IDs:
-
-```bash
-openspec schemas --json
-```
-
-### Config not being applied
-
-1. Ensure the file is at `openspec/config.yaml` (not `.yml`)
-2. Validate YAML syntax
-3. Config changes take effect immediately—no restart needed
-
-### project.md not migrated
-
-The system intentionally preserves `project.md` because it may contain your custom content. Review it manually, move useful parts to `config.yaml`, then delete it.
-
-### Want to see what would be cleaned up?
-
-Run init and decline the cleanup prompt—you'll see the full detection summary without any changes being made.
-
---
-
-## Quick Reference
-
-### Files After Migration
-
-```
-project/
-├── openspec/
-│   ├── specs/                    # Unchanged
-│   ├── changes/                  # Unchanged
-│   │   └── archive/              # Unchanged
-│   └── config.yaml               # NEW: Project configuration
-├── .claude/
-│   └── skills/                   # NEW: OPSX skills
-│       ├── openspec-propose/     # default core profile
-│       ├── openspec-explore/
-│       ├── openspec-apply-change/
-│       ├── openspec-sync-specs/
-│       └── ...                   # expanded profile adds new/continue/ff/etc.
-├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
-└── AGENTS.md                     # OpenSpec markers removed, your content preserved
-```
-
-### What's Gone
-
- `.claude/commands/openspec/` — replaced by `.claude/skills/`
- `openspec/AGENTS.md` — obsolete
- `openspec/project.md` — migrate to `config.yaml`, then delete
- OpenSpec marker blocks in `CLAUDE.md`, `AGENTS.md`, etc.
-
-### Command Cheatsheet
-
-```text
-/opsx:propose      Start quickly (default core profile)
-/opsx:apply        Implement tasks
-/opsx:archive      Finish and archive
-
-# Expanded workflow (if enabled):
-/opsx:new          Scaffold a change
-/opsx:continue     Create next artifact
-/opsx:ff           Create planning artifacts
-```
-
---
-
-## Getting Help
-
- **Discord**: [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC)
- **GitHub Issues**: [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues)
- **Documentation**: [docs/opsx.md](opsx.md) for the full OPSX reference
@@ -1,115 +0,0 @@
-# Multi-Language Guide
-
-Configure OpenSpec to generate artifacts in languages other than English.
-
-## Quick Setup
-
-Add a language instruction to your `openspec/config.yaml`:
-
-```yaml
-schema: spec-driven
-
-context: |
-  Language: Portuguese (pt-BR)
-  All artifacts must be written in Brazilian Portuguese.
-
-  # Your other project context below...
-  Tech stack: TypeScript, React, Node.js
-```
-
-That's it. All generated artifacts will now be in Portuguese.
-
-## Language Examples
-
-### Portuguese (Brazil)
-
-```yaml
-context: |
-  Language: Portuguese (pt-BR)
-  All artifacts must be written in Brazilian Portuguese.
-```
-
-### Spanish
-
-```yaml
-context: |
-  Idioma: Español
-  Todos los artefactos deben escribirse en español.
-```
-
-### Chinese (Simplified)
-
-```yaml
-context: |
-  语言：中文（简体）
-  所有产出物必须用简体中文撰写。
-```
-
-### Japanese
-
-```yaml
-context: |
-  言語：日本語
-  すべての成果物は日本語で作成してください。
-```
-
-### French
-
-```yaml
-context: |
-  Langue : Français
-  Tous les artefacts doivent être rédigés en français.
-```
-
-### German
-
-```yaml
-context: |
-  Sprache: Deutsch
-  Alle Artefakte müssen auf Deutsch verfasst werden.
-```
-
-## Tips
-
-### Handle Technical Terms
-
-Decide how to handle technical terminology:
-
-```yaml
-context: |
-  Language: Japanese
-  Write in Japanese, but:
-  - Keep technical terms like "API", "REST", "GraphQL" in English
-  - Code examples and file paths remain in English
-```
-
-### Combine with Other Context
-
-Language settings work alongside your other project context:
-
-```yaml
-schema: spec-driven
-
-context: |
-  Language: Portuguese (pt-BR)
-  All artifacts must be written in Brazilian Portuguese.
-
-  Tech stack: TypeScript, React 18, Node.js 20
-  Database: PostgreSQL with Prisma ORM
-```
-
-## Verification
-
-To verify your language config is working:
-
-```bash
-# Check the instructions - should show your language context
-openspec instructions proposal --change my-change
-
-# Output will include your language context
-```
-
-## Related Documentation
-
- [Customization Guide](./customization.md) - Project configuration options
- [Workflows Guide](./workflows.md) - Full workflow documentation
@@ -0,0 +1,205 @@
+# Project Config Demo Guide
+
+A quick-reference guide for demonstrating the `openspec/config.yaml` feature.
+
+## Summary: What Project Config Does
+
+The feature adds `openspec/config.yaml` as a lightweight customization layer that lets teams:
+
+- **Set a default schema** - New changes automatically use this schema instead of having to specify `--schema` every time
+- **Inject project context** - Shared context (tech stack, conventions) shown to AI when creating any artifact
+- **Add per-artifact rules** - Custom rules that only apply to specific artifacts (e.g., proposal, specs)
+
+## Demo Walkthrough
+
+### Demo 1: Interactive Setup (Recommended Entry Point)
+
+The easiest way to demo is through the experimental setup command:
+
+```bash
+openspec artifact-experimental-setup
+```
+
+After creating skills/commands, it will prompt:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Project Configuration (Optional)
+
+Configure project defaults for OpenSpec workflows.
+
+? Create openspec/config.yaml? (Y/n)
+```
+
+Walk through:
+
+1. **Select schema** - Shows available schemas with their artifact flows
+2. **Add context** - Opens editor for multi-line project context (tech stack, conventions)
+3. **Add rules** - Checkbox to select artifacts, then line-by-line rule entry
+
+This creates `openspec/config.yaml` with the user's choices.
+
+### Demo 2: Manual Config Creation
+
+Show that users can create the config directly:
+
+```bash
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+
+context: |
+  Tech stack: TypeScript, React, Node.js, PostgreSQL
+  API style: RESTful, documented in docs/api.md
+  Testing: Jest + React Testing Library
+  We value backwards compatibility for all public APIs
+
+rules:
+  proposal:
+    - Include rollback plan
+    - Identify affected teams and notify in #platform-changes
+  specs:
+    - Use Given/When/Then format
+    - Reference existing patterns before inventing new ones
+EOF
+```
+
+### Demo 3: Effect on New Changes
+
+Show that creating a new change now uses the default schema:
+
+```bash
+# Before config: had to specify schema
+openspec new change my-feature --schema spec-driven
+
+# After config: schema is automatic
+openspec new change my-feature
+# Automatically uses spec-driven from config
+```
+
+### Demo 4: Context and Rules Injection
+
+The key demo moment - show how instructions are enriched:
+
+```bash
+# Get instructions for an artifact
+openspec instructions proposal --change my-feature
+```
+
+Output shows the XML structure:
+
+```xml
+<context>
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+API style: RESTful, documented in docs/api.md
+...
+</context>
+
+<rules>
+- Include rollback plan
+- Identify affected teams and notify in #platform-changes
+</rules>
+
+<template>
+[Schema's built-in proposal template]
+</template>
+```
+
+Key points to highlight:
+
+- **Context** appears in ALL artifacts (proposal, specs, design, tasks)
+- **Rules** ONLY appear for the matching artifact (proposal rules only in proposal instructions)
+
+### Demo 5: Precedence Override
+
+Show the schema resolution order:
+
+```bash
+# Config sets schema: spec-driven
+
+# 1. CLI flag wins
+openspec new change feature-a --schema tdd  # Uses tdd
+
+# 2. Change metadata wins over config
+# (if .openspec.yaml in change directory specifies schema)
+
+# 3. Config is used as default
+openspec new change feature-b  # Uses spec-driven from config
+
+# 4. Hardcoded default (no config)
+# Would fall back to spec-driven anyway
+```
+
+### Demo 6: Validation and Error Handling
+
+Show graceful error handling:
+
+```bash
+# Create config with typo
+echo "schema: spec-drivne" > openspec/config.yaml
+
+# Try to use it - shows fuzzy matching suggestions
+openspec new change test
+# Schema 'spec-drivne' not found
+# Did you mean: spec-driven (built-in)
+```
+
+```bash
+# Unknown artifact ID in rules - warns but doesn't halt
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+rules:
+  testplan:  # Schema doesn't have this
+    - Some rule
+EOF
+
+openspec instructions proposal --change test
+# ⚠️ Unknown artifact ID in rules: "testplan". Valid IDs for schema "spec-driven": ...
+# (continues working)
+```
+
+## Quick Demo Script
+
+Here's a quick all-in-one demo:
+
+```bash
+# 1. Show there's no config initially
+cat openspec/config.yaml 2>/dev/null || echo "No config exists"
+
+# 2. Create a simple config
+cat > openspec/config.yaml << 'EOF'
+schema: spec-driven
+context: |
+  This is a demo project using React and TypeScript.
+  We follow semantic versioning.
+rules:
+  proposal:
+    - Include migration steps if breaking change
+EOF
+
+# 3. Show the config
+cat openspec/config.yaml
+
+# 4. Create a change (uses default schema from config)
+openspec new change demo-feature
+
+# 5. Show instructions with injected context/rules
+openspec instructions proposal --change demo-feature | head -30
+
+# 6. Show that specs don't have proposal rules
+openspec instructions specs --change demo-feature | head -30
+```
+
+## What to Emphasize in Demo
+
+- **Low friction** - Teams can customize without forking schemas
+- **Shared context** - Everyone on the team gets the same project knowledge
+- **Per-artifact rules** - Targeted guidance where it matters
+- **Graceful failures** - Typos warn, don't break workflow
+- **Team sharing** - Just commit `openspec/config.yaml` and everyone benefits
+
+## Related Documentation
+
+- [Experimental Workflow Guide](./experimental-workflow.md) - Full user guide with config section
+- [Project Config Proposal](../openspec/changes/project-config/proposal.md) - Original design proposal
+- [Project Config Design](../openspec/changes/project-config/design.md) - Technical implementation details
@@ -0,0 +1,211 @@
+# Schema Customization
+
+This document describes how users can customize OpenSpec schemas and templates, the current manual process, and the gap that needs to be addressed.
+
+---
+
+## Overview
+
+OpenSpec uses a 2-level schema resolution system following the XDG Base Directory Specification:
+
+1. **User override**: `${XDG_DATA_HOME}/openspec/schemas/<name>/`
+2. **Package built-in**: `<npm-package>/schemas/<name>/`
+
+When a schema is requested (e.g., `spec-driven`), the resolver checks the user directory first. If found, that entire schema directory is used. Otherwise, it falls back to the package's built-in schema.
+
+---
+
+## Current Manual Process
+
+To override the default `spec-driven` schema, a user must:
+
+### 1. Determine the correct directory path
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.local/share/openspec/schemas/` |
+| Windows | `%LOCALAPPDATA%\openspec\schemas\` |
+| All (if set) | `$XDG_DATA_HOME/openspec/schemas/` |
+
+### 2. Create the directory structure
+
+```bash
+# macOS/Linux example
+mkdir -p ~/.local/share/openspec/schemas/spec-driven/templates
+```
+
+### 3. Find and copy the default schema files
+
+The user must locate the installed npm package to copy the defaults:
+
+```bash
+# Find the package location (varies by install method)
+npm list -g openspec --parseable
+# or
+which openspec && readlink -f $(which openspec)
+
+# Copy files from the package's schemas/ directory
+cp <package-path>/schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
+cp <package-path>/schemas/spec-driven/templates/*.md ~/.local/share/openspec/schemas/spec-driven/templates/
+```
+
+### 4. Modify the copied files
+
+Edit `schema.yaml` to change the workflow structure:
+
+```yaml
+name: spec-driven
+version: 1
+description: My custom workflow
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal
+    template: proposal.md
+    requires: []
+  # Add, remove, or modify artifacts...
+```
+
+Edit templates in `templates/` to customize the content guidance.
+
+### 5. Verify the override is active
+
+Currently there's no command to verify which schema is being used. Users must trust that the file exists in the right location.
+
+---
+
+## Gap Analysis
+
+The current process has several friction points:
+
+| Issue | Impact |
+|-------|--------|
+| **Path discovery** | Users must know XDG conventions and platform-specific paths |
+| **Package location** | Finding the npm package path varies by install method (global, local, pnpm, yarn, volta, etc.) |
+| **No scaffolding** | Users must manually create directories and copy files |
+| **No verification** | No way to confirm which schema is actually being resolved |
+| **No diffing** | When upgrading openspec, users can't see what changed in built-in templates |
+| **Full copy required** | Must copy entire schema even to change one template |
+
+### User Stories Not Currently Supported
+
+1. *"I want to add a `research` artifact before `proposal`"* — requires manual copy and edit
+2. *"I want to customize just the proposal template"* — must copy entire schema
+3. *"I want to see what the default schema looks like"* — must find package path
+4. *"I want to revert to defaults"* — must delete files and hope paths are correct
+5. *"I upgraded openspec, did the templates change?"* — no way to diff
+
+---
+
+## Proposed Solution: Schema Configurator
+
+A CLI command (or set of commands) that handles path resolution and file operations for users.
+
+### Option A: Single `openspec schema` command
+
+```bash
+# List available schemas (built-in and user overrides)
+openspec schema list
+
+# Show where a schema resolves from
+openspec schema which spec-driven
+# Output: /Users/me/.local/share/openspec/schemas/spec-driven/ (user override)
+# Output: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+
+# Copy a built-in schema to user directory for customization
+openspec schema copy spec-driven
+# Creates ~/.local/share/openspec/schemas/spec-driven/ with all files
+
+# Show diff between user override and built-in
+openspec schema diff spec-driven
+
+# Remove user override (revert to built-in)
+openspec schema reset spec-driven
+
+# Validate a schema
+openspec schema validate spec-driven
+```
+
+### Option B: Dedicated `openspec customize` command
+
+```bash
+# Interactive schema customization
+openspec customize
+# Prompts: Which schema? What do you want to change? etc.
+
+# Copy and open for editing
+openspec customize spec-driven
+# Copies to user dir, prints path, optionally opens in $EDITOR
+```
+
+### Option C: Init-time schema selection
+
+```bash
+# During project init, offer schema customization
+openspec init
+# ? Select a workflow schema:
+#   > spec-driven (default)
+#     tdd
+#     minimal
+#     custom (copy and edit)
+```
+
+### Recommended Approach
+
+**Option A** provides the most flexibility and follows Unix conventions (subcommands for discrete operations). Key commands in priority order:
+
+1. `openspec schema list` — see what's available
+2. `openspec schema which <name>` — debug resolution
+3. `openspec schema copy <name>` — scaffold customization
+4. `openspec schema diff <name>` — compare with built-in
+5. `openspec schema reset <name>` — revert to defaults
+
+---
+
+## Implementation Considerations
+
+### Path Resolution
+
+The resolver already exists in `src/core/artifact-graph/resolver.ts`:
+
+```typescript
+export function getPackageSchemasDir(): string { ... }
+export function getUserSchemasDir(): string { ... }
+export function getSchemaDir(name: string): string | null { ... }
+export function listSchemas(): string[] { ... }
+```
+
+New commands would leverage these existing functions.
+
+### File Operations
+
+- Copy should preserve file permissions
+- Copy should not overwrite existing user files without `--force`
+- Reset should prompt for confirmation
+
+### Template-Only Overrides
+
+A future enhancement could support overriding individual templates without copying the entire schema. This would require changes to the resolution logic:
+
+```
+Current: schema dir (user) OR schema dir (built-in)
+Future:  schema.yaml from user OR built-in
+         + each template from user OR built-in (independent fallback)
+```
+
+This adds complexity but enables the "I just want to change one template" use case.
+
+---
+
+## Related Documents
+
+- [Schema Workflow Gaps](./schema-workflow-gaps.md) — End-to-end workflow analysis and phased implementation plan
+
+## Related Files
+
+| File | Purpose |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
+| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
+| `src/core/global-config.ts` | XDG path helpers |
+| `schemas/spec-driven/` | Default schema and templates |
@@ -0,0 +1,379 @@
+# Schema Workflow: End-to-End Analysis
+
+This document analyzes the complete user journey for working with schemas in OpenSpec, identifies gaps, and proposes a phased solution.
+
+---
+
+## Current State
+
+### What Exists
+
+| Component | Status |
+|-----------|--------|
+| Schema resolution | 3-level: project → user → package (PR #522) |
+| Built-in schemas | `spec-driven`, `tdd` |
+| Artifact workflow commands | `status`, `next`, `instructions`, `templates` with `--schema` flag |
+| Change creation | `openspec new change <name>` — no schema binding |
+| Project-local schemas | ✅ Supported via `openspec/schemas/` (PR #522) |
+| Schema management CLI | ✅ `schema which`, `validate`, `fork`, `init` (PR #525) |
+
+### What's Missing
+
+| Component | Status |
+|-----------|--------|
+| Schema bound to change | Not stored — must pass `--schema` every time |
+| Project default schema | None — hardcoded to `spec-driven` |
+
+---
+
+## User Journey Analysis
+
+### Scenario 1: Using a Non-Default Schema
+
+**Goal:** User wants to use TDD workflow for a new feature.
+
+**Today's experience:**
+```bash
+openspec new change add-auth
+# Creates directory, no schema info stored
+
+openspec status --change add-auth
+# Shows spec-driven artifacts (WRONG - user wanted TDD)
+
+# User realizes mistake...
+openspec status --change add-auth --schema tdd
+# Correct, but must remember --schema every time
+
+# 6 months later...
+openspec status --change add-auth
+# Wrong again - nobody remembers this was TDD
+```
+
+**Problems:**
+- Schema is a runtime argument, not persisted
+- Easy to forget `--schema` and get wrong results
+- No record of intended schema for future reference
+
+---
+
+### Scenario 2: Customizing a Schema
+
+**Goal:** User wants to add a "research" artifact before "proposal".
+
+**Today's experience:**
+```bash
+# Step 1: Figure out where to put overrides
+# Must know XDG conventions:
+#   macOS/Linux: ~/.local/share/openspec/schemas/
+#   Windows: %LOCALAPPDATA%\openspec\schemas/
+
+# Step 2: Create directory structure
+mkdir -p ~/.local/share/openspec/schemas/my-workflow/templates
+
+# Step 3: Find the npm package to copy defaults
+npm list -g openspec --parseable
+# Output varies by package manager:
+#   npm: /usr/local/lib/node_modules/openspec
+#   pnpm: ~/.local/share/pnpm/global/5/node_modules/openspec
+#   volta: ~/.volta/tools/image/packages/openspec/...
+#   yarn: ~/.config/yarn/global/node_modules/openspec
+
+# Step 4: Copy files
+cp -r <package-path>/schemas/spec-driven/* \
+      ~/.local/share/openspec/schemas/my-workflow/
+
+# Step 5: Edit schema.yaml and templates
+# No way to verify override is active
+# No way to diff against original
+```
+
+**Problems:**
+- Must know XDG path conventions
+- Finding npm package path varies by install method
+- No tooling to scaffold or verify
+- No diff capability when upgrading openspec
+
+---
+
+### Scenario 3: Team Sharing Custom Workflow
+
+**Goal:** Team wants everyone to use the same custom schema.
+
+**Today's options:**
+1. Everyone manually sets up XDG override — error-prone, drift risk
+2. Document setup in README — still manual, easy to miss
+3. Publish separate npm package — overkill for most teams
+4. Check schema into repo — **not supported** (no project-local resolution)
+
+**Problems:**
+- No project-local schema resolution
+- Can't version control custom schemas with the codebase
+- No single source of truth for team workflow
+
+---
+
+## Gap Summary
+
+| Gap | Impact | Status |
+|-----|--------|--------|
+| Schema not bound to change | Wrong results, forgotten context | ⏳ Pending (Phase 1) |
+| No project-local schemas | Can't share via repo | ✅ Fixed (PR #522) |
+| No schema management CLI | Manual path hunting | ✅ Fixed (PR #525) |
+| No project default schema | Must specify every time | ⏳ Pending (Phase 4) |
+| No init-time schema selection | Missed setup opportunity | ⏳ Pending (Phase 4) |
+
+---
+
+## Proposed Architecture
+
+### New File Structure
+
+```
+openspec/
+├── config.yaml                 # Project config (NEW)
+├── schemas/                    # Project-local schemas (NEW)
+│   └── my-workflow/
+│       ├── schema.yaml
+│       └── templates/
+│           ├── research.md
+│           ├── proposal.md
+│           └── ...
+└── changes/
+    └── add-auth/
+        ├── change.yaml         # Change metadata (NEW)
+        ├── proposal.md
+        └── ...
+```
+
+### config.yaml (Project Config)
+
+```yaml
+# openspec/config.yaml
+defaultSchema: spec-driven
+```
+
+Sets the project-wide default schema. Used when:
+- Creating new changes without `--schema`
+- Running commands on changes without `change.yaml`
+
+### change.yaml (Change Metadata)
+
+```yaml
+# openspec/changes/add-auth/change.yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+description: Add user authentication system
+```
+
+Binds a specific schema to a change. Created automatically by `openspec new change`.
+
+### Schema Resolution Order
+
+```
+1. ./openspec/schemas/<name>/                    # Project-local
+2. ~/.local/share/openspec/schemas/<name>/       # User global (XDG)
+3. <npm-package>/schemas/<name>/                 # Built-in
+```
+
+Project-local takes priority, enabling version-controlled custom schemas.
+
+### Schema Selection Order (Per Command)
+
+```
+1. --schema CLI flag                    # Explicit override
+2. change.yaml in change directory      # Change-specific binding
+3. openspec/config.yaml defaultSchema   # Project default
+4. "spec-driven"                        # Hardcoded fallback
+```
+
+---
+
+## Ideal User Experience
+
+### Creating a Change
+
+```bash
+# Uses project default (from config.yaml, or spec-driven)
+openspec new change add-auth
+# Creates openspec/changes/add-auth/change.yaml:
+#   schema: spec-driven
+#   created: 2025-01-15T10:30:00Z
+
+# Explicit schema for this change
+openspec new change add-auth --schema tdd
+# Creates change.yaml with schema: tdd
+```
+
+### Working with Changes
+
+```bash
+# Auto-reads schema from change.yaml — no --schema needed
+openspec status --change add-auth
+# Output: "Change: add-auth (schema: tdd)"
+# Shows which artifacts are ready/blocked/done
+
+# Explicit override still works (with informational message)
+openspec status --change add-auth --schema spec-driven
+# "Note: change.yaml specifies 'tdd', using 'spec-driven' per --schema flag"
+```
+
+### Customizing Schemas
+
+```bash
+# See what's available
+openspec schema list
+# Built-in:
+#   spec-driven    proposal → specs → design → tasks
+#   tdd            spec → tests → implementation → docs
+# Project: (none)
+# User: (none)
+
+# Copy to project for customization
+openspec schema copy spec-driven my-workflow
+# Created ./openspec/schemas/my-workflow/
+# Edit schema.yaml and templates/ to customize
+
+# Copy to global (user-level override)
+openspec schema copy spec-driven --global
+# Created ~/.local/share/openspec/schemas/spec-driven/
+
+# See where a schema resolves from
+openspec schema which spec-driven
+# ./openspec/schemas/spec-driven/ (project)
+# or: ~/.local/share/openspec/schemas/spec-driven/ (user)
+# or: /usr/local/lib/node_modules/openspec/schemas/spec-driven/ (built-in)
+
+# Compare override with built-in
+openspec schema diff spec-driven
+# Shows diff between user/project version and package built-in
+
+# Remove override, revert to built-in
+openspec schema reset spec-driven
+# Removes ./openspec/schemas/spec-driven/ (or --global for user dir)
+```
+
+### Project Setup
+
+```bash
+openspec init
+# ? Select default workflow schema:
+#   > spec-driven (proposal → specs → design → tasks)
+#     tdd (spec → tests → implementation → docs)
+#     (custom schemas if detected)
+#
+# Writes to openspec/config.yaml:
+#   defaultSchema: spec-driven
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Change Metadata (change.yaml)
+
+**Priority:** High
+**Solves:** "Forgot --schema", lost context, wrong results
+
+**Scope:**
+- Create `change.yaml` when running `openspec new change`
+- Store `schema`, `created` timestamp
+- Modify workflow commands to read schema from `change.yaml`
+- `--schema` flag overrides (with informational message)
+- Backwards compatible: missing `change.yaml` → use default
+
+**change.yaml format:**
+```yaml
+schema: tdd
+created: 2025-01-15T10:30:00Z
+```
+
+**Migration:**
+- Existing changes without `change.yaml` continue to work
+- Default to `spec-driven` (current behavior)
+- Optional: `openspec migrate` to add `change.yaml` to existing changes
+
+---
+
+### Phase 2: Project-Local Schemas
+
+**Status:** ✅ Complete (PR #522)
+**Solves:** Team sharing, version control, no XDG knowledge needed
+
+**Implemented:**
+- `./openspec/schemas/` added to resolution order (first priority)
+- `openspec schema fork <name> [new-name]` creates in project by default
+- Teams can commit `openspec/schemas/` to repo
+
+**Resolution order:**
+```
+1. ./openspec/schemas/<name>/           # Project-local
+2. ~/.local/share/openspec/schemas/<name>/  # User global
+3. <npm-package>/schemas/<name>/        # Built-in
+```
+
+---
+
+### Phase 3: Schema Management CLI
+
+**Status:** ✅ Complete (PR #525)
+**Solves:** Path discovery, scaffolding, debugging
+
+**Implemented Commands:**
+```bash
+openspec schema which [name]          # Show resolution path, --all for all schemas
+openspec schema validate [name]       # Validate schema structure and templates
+openspec schema fork <source> [name]  # Copy existing schema for customization
+openspec schema init <name>           # Create new project-local schema (interactive)
+```
+
+**Not implemented (may add later):**
+- `schema diff` — Compare override with built-in
+- `schema reset` — Remove override, revert to built-in
+
+---
+
+### Phase 4: Project Config + Init Enhancement
+
+**Priority:** Low
+**Solves:** Project-wide defaults, streamlined setup
+
+**Scope:**
+- Add `openspec/config.yaml` with `defaultSchema` field
+- `openspec init` prompts for schema selection
+- Store selection in `config.yaml`
+- Commands use as fallback when no `change.yaml` exists
+
+**config.yaml format:**
+```yaml
+defaultSchema: spec-driven
+```
+
+---
+
+## Backwards Compatibility
+
+| Scenario | Behavior |
+|----------|----------|
+| Existing change without `change.yaml` | Uses `--schema` flag or project default or `spec-driven` |
+| Existing project without `config.yaml` | Falls back to `spec-driven` |
+| `--schema` flag provided | Overrides `change.yaml` (with info message) |
+| No project-local schemas dir | Skipped in resolution, checks user/built-in |
+
+All existing functionality continues to work. New features are additive.
+
+---
+
+## Related Documents
+
+- [Schema Customization](./schema-customization.md) — Details on manual override process and CLI gaps
+- [Artifact POC](./artifact_poc.md) — Core artifact graph architecture
+
+## Related Code
+
+| File | Purpose |
+|------|---------|
+| `src/core/artifact-graph/resolver.ts` | Schema resolution logic |
+| `src/core/artifact-graph/instruction-loader.ts` | Template loading |
+| `src/core/global-config.ts` | XDG path helpers |
+| `src/commands/artifact-workflow.ts` | CLI commands |
+| `src/utils/change-utils.ts` | Change creation utilities |
@@ -1,111 +0,0 @@
-# Supported Tools
-
-OpenSpec works with many AI coding assistants. When you run `openspec init`, OpenSpec configures selected tools using your active profile/workflow selection and delivery mode.
-
-## How It Works
-
-For each selected tool, OpenSpec can install:
-
-1. **Skills** (if delivery includes skills): `.../skills/openspec-*/SKILL.md`
-2. **Commands** (if delivery includes commands): tool-specific `opsx-*` command files
-
-By default, OpenSpec uses the `core` profile, which includes:
- `propose`
- `explore`
- `apply`
- `sync`
- `archive`
-
-You can enable expanded workflows (`new`, `continue`, `ff`, `verify`, `bulk-archive`, `onboard`) via `openspec config profile`, then run `openspec update`.
-
-## Tool Directory Reference
-
-| Tool (ID) | Skills path pattern | Command path pattern |
-|-----------|---------------------|----------------------|
-| Amazon Q Developer (`amazon-q`) | `.amazonq/skills/openspec-*/SKILL.md` | `.amazonq/prompts/opsx-<id>.md` |
-| Antigravity (`antigravity`) | `.agent/skills/openspec-*/SKILL.md` | `.agent/workflows/opsx-<id>.md` |
-| Auggie (`auggie`) | `.augment/skills/openspec-*/SKILL.md` | `.augment/commands/opsx-<id>.md` |
-| IBM Bob Shell (`bob`) | `.bob/skills/openspec-*/SKILL.md` | `.bob/commands/opsx-<id>.md` |
-| Claude Code (`claude`) | `.claude/skills/openspec-*/SKILL.md` | `.claude/commands/opsx/<id>.md` |
-| Cline (`cline`) | `.cline/skills/openspec-*/SKILL.md` | `.clinerules/workflows/opsx-<id>.md` |
-| CodeBuddy (`codebuddy`) | `.codebuddy/skills/openspec-*/SKILL.md` | `.codebuddy/commands/opsx/<id>.md` |
-| Codex (`codex`) | `.codex/skills/openspec-*/SKILL.md` | `$CODEX_HOME/prompts/opsx-<id>.md`\* |
-| ForgeCode (`forgecode`) | `.forge/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
-| Continue (`continue`) | `.continue/skills/openspec-*/SKILL.md` | `.continue/prompts/opsx-<id>.prompt` |
-| CoStrict (`costrict`) | `.cospec/skills/openspec-*/SKILL.md` | `.cospec/openspec/commands/opsx-<id>.md` |
-| Crush (`crush`) | `.crush/skills/openspec-*/SKILL.md` | `.crush/commands/opsx/<id>.md` |
-| Cursor (`cursor`) | `.cursor/skills/openspec-*/SKILL.md` | `.cursor/commands/opsx-<id>.md` |
-| Factory Droid (`factory`) | `.factory/skills/openspec-*/SKILL.md` | `.factory/commands/opsx-<id>.md` |
-| Gemini CLI (`gemini`) | `.gemini/skills/openspec-*/SKILL.md` | `.gemini/commands/opsx/<id>.toml` |
-| GitHub Copilot (`github-copilot`) | `.github/skills/openspec-*/SKILL.md` | `.github/prompts/opsx-<id>.prompt.md`\*\* |
-| iFlow (`iflow`) | `.iflow/skills/openspec-*/SKILL.md` | `.iflow/commands/opsx-<id>.md` |
-| Junie (`junie`) | `.junie/skills/openspec-*/SKILL.md` | `.junie/commands/opsx-<id>.md` |
-| Kilo Code (`kilocode`) | `.kilocode/skills/openspec-*/SKILL.md` | `.kilocode/workflows/opsx-<id>.md` |
-| Kimi CLI (`kimi`) | `.kimi/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/skill:openspec-*` invocations) |
-| Kiro (`kiro`) | `.kiro/skills/openspec-*/SKILL.md` | `.kiro/prompts/opsx-<id>.prompt.md` |
-| Lingma (`lingma`) | `.lingma/skills/openspec-*/SKILL.md` | `.lingma/commands/opsx/<id>.md` |
-| OpenCode (`opencode`) | `.opencode/skills/openspec-*/SKILL.md` | `.opencode/commands/opsx-<id>.md` |
-| Pi (`pi`) | `.pi/skills/openspec-*/SKILL.md` | `.pi/prompts/opsx-<id>.md` |
-| Qoder (`qoder`) | `.qoder/skills/openspec-*/SKILL.md` | `.qoder/commands/opsx/<id>.md` |
-| Qwen Code (`qwen`) | `.qwen/skills/openspec-*/SKILL.md` | `.qwen/commands/opsx-<id>.toml` |
-| RooCode (`roocode`) | `.roo/skills/openspec-*/SKILL.md` | `.roo/commands/opsx-<id>.md` |
-| Trae (`trae`) | `.trae/skills/openspec-*/SKILL.md` | Not generated (no command adapter; use skill-based `/openspec-*` invocations) |
-| Windsurf (`windsurf`) | `.windsurf/skills/openspec-*/SKILL.md` | `.windsurf/workflows/opsx-<id>.md` |
-
-\* Codex commands are installed in the global Codex home (`$CODEX_HOME/prompts/` if set, otherwise `~/.codex/prompts/`), not your project directory.
-
-\*\* GitHub Copilot prompt files are recognized as custom slash commands in IDE extensions (VS Code, JetBrains, Visual Studio). Copilot CLI does not currently consume `.github/prompts/*.prompt.md` directly.
-
-## Non-Interactive Setup
-
-For CI/CD or scripted setup, use `--tools` (and optionally `--profile`):
-
-```bash
-# Configure specific tools
-openspec init --tools claude,cursor
-
-# Configure all supported tools
-openspec init --tools all
-
-# Skip tool configuration
-openspec init --tools none
-
-# Override profile for this init run
-openspec init --profile core
-```
-
-**Available tool IDs (`--tools`):** `amazon-q`, `antigravity`, `auggie`, `bob`, `claude`, `cline`, `codex`, `forgecode`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `junie`, `kilocode`, `kimi`, `kiro`, `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`, `sync`, `archive`
- **Custom selection:** any subset of all workflow IDs:
-  `propose`, `explore`, `new`, `continue`, `apply`, `ff`, `sync`, `archive`, `bulk-archive`, `verify`, `onboard`
-
-In other words, skill/command counts are profile-dependent and delivery-dependent, not fixed.
-
-## Generated Skill Names
-
-When selected by profile/workflow config, OpenSpec generates these skills:
-
- `openspec-propose`
- `openspec-explore`
- `openspec-new-change`
- `openspec-continue-change`
- `openspec-apply-change`
- `openspec-ff-change`
- `openspec-sync-specs`
- `openspec-archive-change`
- `openspec-bulk-archive-change`
- `openspec-verify-change`
- `openspec-onboard`
-
-See [Commands](commands.md) for command behavior and [CLI](cli.md) for `init`/`update` options.
-
-## Related
-
- [CLI Reference](cli.md) — Terminal commands
- [Commands](commands.md) — Slash commands and skills
- [Getting Started](getting-started.md) — First-time setup
@@ -1,452 +0,0 @@
-# Workflows
-
-This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see [Getting Started](getting-started.md). For command reference, see [Commands](commands.md).
-
-## Philosophy: Actions, Not Phases
-
-Traditional workflows force you through phases: planning, then implementation, then done. But real work doesn't fit neatly into boxes.
-
-OPSX takes a different approach:
-
-```text
-Traditional (phase-locked):
-
-  PLANNING ────────► IMPLEMENTING ────────► DONE
-      │                    │
-      │   "Can't go back"  │
-      └────────────────────┘
-
-OPSX (fluid actions):
-
-  proposal ──► specs ──► design ──► tasks ──► implement
-```
-
-**Key principles:**
-
- **Actions, not phases** - Commands are things you can do, not stages you're stuck in
- **Dependencies are enablers** - They show what's possible, not what's required next
-
-> **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
-
-## Two Modes
-
-### Default Quick Path (`core` profile)
-
-New installs default to `core`, which provides:
- `/opsx:propose`
- `/opsx:explore`
- `/opsx:apply`
- `/opsx:sync`
- `/opsx:archive`
-
-Typical flow:
-
-```text
-/opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
-```
-
-### Expanded/Full Workflow (custom selection)
-
-If you want explicit scaffold-and-build commands (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), enable them with:
-
-```bash
-openspec config profile
-openspec update
-```
-
-## Workflow Patterns (Expanded Mode)
-
-### Quick Feature
-
-When you know what you want to build and just need to execute:
-
-```text
-/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive
-```
-
-**Example conversation:**
-
-```text
-You: /opsx:new add-logout-button
-
-AI:  Created openspec/changes/add-logout-button/
-     Ready to create: proposal
-
-You: /opsx:ff
-
-AI:  Creating all planning artifacts...
-     ✓ proposal.md
-     ✓ specs/
-     ✓ design.md
-     ✓ tasks.md
-     Ready for implementation!
-
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ Added logout button to header
-     ✓ Implemented session clearing
-     ✓ Added confirmation dialog
-     All tasks complete!
-
-You: /opsx:archive
-
-AI:  ✓ Merged specs
-     ✓ Archived change
-```
-
-**Best for:** Small to medium features, bug fixes, straightforward changes.
-
-### Exploratory
-
-When requirements are unclear or you need to investigate first:
-
-```text
-/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply
-```
-
-**Example conversation:**
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: I want to improve page load performance but I'm not sure
-     where the bottlenecks are.
-
-AI:  Let me help investigate...
-     [Analyzes bundle sizes, identifies slow queries, reviews
-     component render patterns]
-
-     I found three main bottlenecks:
-     1. Large unoptimized images
-     2. Synchronous data fetching in ProductList
-     3. Re-renders from context changes
-
-     Which would you like to address first?
-
-You: Let's tackle the data fetching issue.
-
-You: /opsx:new optimize-product-list-fetching
-
-AI:  Created change. Ready to create: proposal
-
-You: /opsx:continue
-
-AI:  Creating proposal based on our exploration...
-     [Writes proposal incorporating investigation insights]
-
-     Ready to create: specs, design
-     Which would you like next?
-
-You: /opsx:continue
-
-AI:  Creating specs...
-```
-
-**Best for:** Performance optimization, debugging, architectural decisions, unclear requirements.
-
-### Parallel Changes
-
-Work on multiple changes at once:
-
-```text
-Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
-                                         │
-                                    context switch
-                                         │
-Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply
-```
-
-**Example conversation:**
-
-```text
-You: I'm working on add-dark-mode but got pulled into a bug fix
-
-You: /opsx:new fix-login-redirect
-
-AI:  Created openspec/changes/fix-login-redirect/
-
-You: /opsx:ff
-
-AI:  ✓ Created planning artifacts
-
-You: /opsx:apply
-
-AI:  Working on fix-login-redirect...
-     [Implements the fix]
-     All tasks complete!
-
-You: /opsx:archive
-
-AI:  ✓ Archived fix-login-redirect
-
-You: Let's get back to dark mode
-
-You: /opsx:apply add-dark-mode
-
-AI:  Resuming add-dark-mode...
-     Picking up at task 2.3: Update Header...
-```
-
-**Best for:** Parallel work streams, urgent interrupts, team collaboration.
-
-When you have multiple completed changes, use `/opsx:bulk-archive`:
-
-```text
-You: /opsx:bulk-archive
-
-AI:  Found 3 completed changes:
-     - add-dark-mode (all tasks done)
-     - fix-login-redirect (all tasks done)
-     - update-footer (all tasks done)
-
-     Checking for spec conflicts...
-     ⚠ add-dark-mode and update-footer both touch specs/ui/
-
-     Inspecting codebase to resolve...
-     Both changes are implemented. Will apply in chronological order.
-
-     Archive all 3 changes?
-
-You: Yes
-
-AI:  ✓ Archived add-dark-mode
-     ✓ Archived fix-login-redirect
-     ✓ Archived update-footer
-     Specs merged in order: add-dark-mode → update-footer
-```
-
-Bulk archive detects when multiple changes touch the same specs and resolves conflicts by checking what's actually implemented.
-
-### Completing a Change
-
-The recommended completion flow:
-
-```text
-/opsx:apply ──► /opsx:verify ──► /opsx:archive
-                    │                 │
-              validates          prompts to sync
-              implementation     if needed
-```
-
-#### Verify: Check Your Work
-
-`/opsx:verify` validates implementation against your artifacts across three dimensions:
-
-```text
-You: /opsx:verify
-
-AI:  Verifying add-auth...
-
-     COMPLETENESS
-     ✓ All 12 tasks in tasks.md are checked
-     ✓ All requirements in specs have corresponding code
-     ⚠ Scenario "Session timeout after inactivity" not tested
-
-     CORRECTNESS
-     ✓ Implementation matches spec intent
-     ✓ Edge cases from scenarios are handled
-     ✓ Error states match spec definitions
-
-     COHERENCE
-     ✓ Design decisions reflected in code structure
-     ✓ Naming conventions consistent with design.md
-     ⚠ Design mentions "event-driven" but implementation uses polling
-
-     SUMMARY
-     ─────────────────────────────
-     Critical issues: 0
-     Warnings: 2
-     Ready to archive: Yes (with warnings)
-
-     Recommendations:
-     1. Add test for session timeout scenario
-     2. Consider refactoring to event-driven as designed, or update design.md
-```
-
-**What verify checks:**
-
-| Dimension | What it validates |
-|-----------|------------------|
-| Completeness | All tasks done, all requirements implemented, scenarios covered |
-| Correctness | Implementation matches spec intent, edge cases handled |
-| Coherence | Design decisions reflected in code, patterns consistent |
-
-Verify won't block archive, but it surfaces issues you might want to address first.
-
-#### Archive: Finalize the Change
-
-`/opsx:archive` completes the change and moves it to the archive:
-
-```text
-You: /opsx:archive
-
-AI:  Archiving add-auth...
-
-     Artifact status:
-     ✓ proposal.md exists
-     ✓ specs/ exists
-     ✓ design.md exists
-     ✓ tasks.md exists (12/12 tasks complete)
-
-     Delta specs: Not yet synced to main
-     → Would you like to sync now?
-
-You: Yes
-
-AI:  ✓ Synced specs to openspec/specs/auth/spec.md
-     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/
-
-     Change archived successfully.
-```
-
-Archive will prompt if specs aren't synced. It won't block on incomplete tasks, but it will warn you.
-
-## When to Use What
-
-### `/opsx:ff` vs `/opsx:continue`
-
-| Situation | Use |
-|-----------|-----|
-| Clear requirements, ready to build | `/opsx:ff` |
-| Exploring, want to review each step | `/opsx:continue` |
-| Want to iterate on proposal before specs | `/opsx:continue` |
-| Time pressure, need to move fast | `/opsx:ff` |
-| Complex change, want control | `/opsx:continue` |
-
-**Rule of thumb:** If you can describe the full scope upfront, use `/opsx:ff`. If you're figuring it out as you go, use `/opsx:continue`.
-
-### When to Update vs Start Fresh
-
-A common question: when is updating an existing change okay, and when should you start a new one?
-
-**Update the existing change when:**
-
- Same intent, refined execution
- Scope narrows (MVP first, rest later)
- Learning-driven corrections (codebase isn't what you expected)
- Design tweaks based on implementation discoveries
-
-**Start a new change when:**
-
- Intent fundamentally changed
- Scope exploded to different work entirely
- Original change can be marked "done" standalone
- Patches would confuse more than clarify
-
-```text
-                     ┌─────────────────────────────────────┐
-                     │     Is this the same work?          │
-                     └──────────────┬──────────────────────┘
-                                    │
-                 ┌──────────────────┼──────────────────┐
-                 │                  │                  │
-                 ▼                  ▼                  ▼
-          Same intent?      >50% overlap?      Can original
-          Same problem?     Same scope?        be "done" without
-                 │                  │          these changes?
-                 │                  │                  │
-       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
-       │                 │  │             │   │               │
-      YES               NO YES           NO  NO              YES
-       │                 │  │             │   │               │
-       ▼                 ▼  ▼             ▼   ▼               ▼
-    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW
-```
-
-**Example: "Add dark mode"**
-
- "Need to also support custom themes" → New change (scope exploded)
- "System preference detection is harder than expected" → Update (same intent)
- "Let's ship toggle first, add preferences later" → Update then archive, then new change
-
-## Best Practices
-
-### Keep Changes Focused
-
-One logical unit of work per change. If you're doing "add feature X and also refactor Y", consider two separate changes.
-
-**Why it matters:**
- Easier to review and understand
- Cleaner archive history
- Can ship independently
- Simpler rollback if needed
-
-### Use `/opsx:explore` for Unclear Requirements
-
-Before committing to a change, explore the problem space:
-
-```text
-You: /opsx:explore
-
-AI:  What would you like to explore?
-
-You: How should we handle rate limiting for our API?
-
-AI:  Let me investigate your current setup and options...
-     [Researches codebase, considers patterns]
-
-     I see three approaches we could take:
-     1. Middleware-based (simple, per-endpoint)
-     2. Redis-backed (scalable, shared state)
-     3. Token bucket per user (fair, complex)
-
-     Your current stack suggests #1 or #2. What's your scale?
-```
-
-Exploration clarifies thinking before you create artifacts.
-
-### Verify Before Archiving
-
-Use `/opsx:verify` to check implementation matches artifacts:
-
-```text
-You: /opsx:verify
-
-AI:  Verifying add-dark-mode...
-
-     ✓ All tasks in tasks.md are checked
-     ✓ Requirements in specs have corresponding code
-     ✓ Design decisions are reflected in implementation
-
-     Ready to archive!
-```
-
-Catches mismatches before you close out the change.
-
-### Name Changes Clearly
-
-Good names make `openspec list` useful:
-
-```text
-Good:                          Avoid:
-add-dark-mode                  feature-1
-fix-login-redirect             update
-optimize-product-query         changes
-implement-2fa                  wip
-```
-
-## Command Quick Reference
-
-For full command details and options, see [Commands](commands.md).
-
-| Command | Purpose | When to Use |
-|---------|---------|-------------|
-| `/opsx:propose` | Create change + planning artifacts | Fast default path (`core` profile) |
-| `/opsx:explore` | Think through ideas | 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 |
-| `/opsx:apply` | Implement tasks | Ready to write code |
-| `/opsx:verify` | Validate implementation | Expanded mode, before archiving |
-| `/opsx:sync` | Merge delta specs | Expanded mode, optional |
-| `/opsx:archive` | Complete the change | All work finished |
-| `/opsx:bulk-archive` | Archive multiple changes | Expanded mode, parallel work |
-
-## Next Steps
-
- [Commands](commands.md) - Full command reference with options
- [Concepts](concepts.md) - Deep dive into specs, artifacts, and schemas
- [Customization](customization.md) - Create custom workflows
@@ -5,47 +5,23 @@
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  };

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

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

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

            pnpmDeps = pkgs.fetchPnpmDeps {
              inherit (finalAttrs) pname version src;
@@ -79,8 +55,7 @@
              mainProgram = "openspec";
            };
          });
-        }
-      );
+        });

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

-      devShells = forAllSystems (
-        system:
+      devShells = forAllSystems (system:
        let
          pkgs = nixpkgs.legacyPackages.${system};
        in
@@ -108,7 +82,6 @@
              echo "Run 'pnpm install' to install dependencies"
            '';
          };
-        }
-      );
+        });
    };
 }
@@ -1,136 +0,0 @@
-# Add Artifact Regeneration Support
-
-## Problem
-
-Currently, there is **no way to regenerate artifacts** in the OPSX workflow:
-
- `/opsx:apply` just reads whatever's on disk
- `/opsx:continue` only creates the NEXT artifact - won't touch existing ones
-
-If you edit `design.md` after `tasks.md` exists, your only options are:
-1. Delete tasks.md manually, then run `/opsx:continue`
-2. Edit tasks.md manually
-
-The documentation claims you can "update artifacts mid-flight and continue" but there's no mechanism that actually supports this.
-
-## Proposed Solution
-
-Two parts:
-
-### Part 1: Staleness Detection
-Add artifact staleness detection to `/opsx:apply`:
-
-1. **Track modification times**: When generating an artifact, record the mtime of its dependencies
-2. **Detect staleness**: When `/opsx:apply` runs, check if upstream artifacts (design.md, specs) have been modified since tasks.md was generated
-3. **Prompt user**: If stale, ask: "Design was modified after tasks were generated. Would you like to regenerate tasks with `/opsx:continue`?"
-
-## User Experience
-
-### Vision: Seamless Mid-Flight Correction
-
-This is the workflow we want to enable (currently documented but not supported):
-
-```
-You: /opsx:apply
-
-AI:  Working through tasks...
-     ✓ Task 1.1: Created caching layer
-     ✓ Task 1.2: Added cache invalidation
-
-     Working on 1.3: Implement TTL...
-     I noticed the design assumes Redis, but your project uses
-     in-memory caching. Should I update the design?
-
-You: Yes, update it to use the existing cache module.
-
-AI:  Updated design.md to use CacheManager from src/cache/
-     Updated tasks.md with revised implementation steps
-     Continuing implementation...
-     ✓ Task 1.3: Implemented TTL using CacheManager
-     ...
-```
-
-**No restart needed.** Just update the artifact and continue.
-
-### Staleness Warning UX
-
-When user manually edits an upstream artifact:
-
-```
-$ /opsx:apply
-
-⚠️  Detected changes to upstream artifacts:
-    - design.md modified 5 minutes ago (after tasks.md was generated)
-
-Options:
-1. Regenerate tasks (recommended)
-2. Continue anyway with current tasks
-3. Cancel
-
->
-```
-
-### Part 2: Regeneration Capability
-
-Add a way to regenerate specific artifacts:
-
-```bash
-# Option A: Flag on continue
-/opsx:continue --regenerate tasks
-
-# Option B: Separate command
-/opsx:regenerate tasks
-
-# Option C: Interactive prompt when staleness detected
-/opsx:apply
-# "Design changed. Regenerate tasks? [y/N]"
-```
-
-## Technical Approach
-
-### Option A: Metadata File
-Store `.openspec-meta.json` in change directory:
-```json
-{
-  "tasks.md": {
-    "generated_at": "2025-01-24T10:00:00Z",
-    "dependencies": {
-      "design.md": "2025-01-24T09:55:00Z",
-      "specs/feature/spec.md": "2025-01-24T09:50:00Z"
-    }
-  }
-}
-```
-
-### Option B: Frontmatter
-Add YAML frontmatter to generated artifacts:
-```markdown
---
-generated_at: 2025-01-24T10:00:00Z
-depends_on:
-  - design.md@2025-01-24T09:55:00Z
---
-# Tasks
-...
-```
-
-### Option C: Git-based
-Use git to detect if upstream files changed since downstream was last modified. No extra metadata needed but requires git.
-
-## Non-Goals
-
- Automatic regeneration (user should always choose)
- Blocking apply entirely (just warn)
- Tracking code file changes (only artifact dependencies)
-
-## Dependencies
-
- Should be implemented after `fix-midflight-update-docs` so docs are accurate first
- Could be combined with that change if desired
-
-## Success Criteria
-
- User is warned when applying with stale artifacts
- Clear path to regenerate if needed
- No false positives (only warn when genuinely stale)
- Documentation claims become actually true
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-21
@@ -1,93 +0,0 @@
-## Why
-
-Parallel changes often touch the same capabilities and `cli-init`/`cli-update` behavior, but today there is no machine-readable way to express sequencing, dependencies, or expected merge order.
-
-This creates three recurring problems:
-
- teams cannot tell which change should land first
- large changes are hard to split into safe mergeable slices
- parallel work can accidentally reintroduce assumptions already removed by another change
-
-We need lightweight planning metadata and CLI guidance so contributors can safely stack plans on top of each other.
-
-## What Changes
-
-### 1. Add lightweight stack metadata for changes
-
-Extend change metadata to support sequencing and decomposition context, for example:
-
- `dependsOn`: changes that must land first
- `provides`: capability markers exposed by this change
- `requires`: capability markers needed by this change
- `touches`: capability/spec areas likely affected (advisory only; warning signal, not a hard dependency)
- `parent`: optional parent change for split work
-
-Metadata is optional and backward compatible for existing changes.
-
-Ordering semantics:
-
- `dependsOn` is the source of truth for execution/archive ordering
- `provides`/`requires` are capability contracts for validation and planning visibility
- `provides`/`requires` do not create implicit dependency edges; authors must still declare required ordering via `dependsOn`
-
-### 2. Add stack-aware validation
-
-Enhance change validation to detect planning issues early:
-
- missing dependencies
- dependency cycles
- archive ordering violations (for example, attempting to archive a change before all `dependsOn` predecessors are archived)
- unmatched capability markers (for example, `requires` marker with no provider in active history emits non-blocking warning)
- overlap warnings when active changes touch the same capability
-
-Validation should fail only for deterministic blockers (for example cycles or missing required dependencies), and keep overlap checks as actionable warnings.
-
-### 3. Add sequencing visibility commands
-
-Add lightweight CLI support to inspect and execute plan order:
-
- `openspec change graph` to show dependency DAG/order
- `openspec change graph` validates for cycles first; when cycles are present it fails with the same deterministic cycle error as stack-aware validation
- `openspec change next` to suggest unblocked changes ready to implement/archive
-
-### 4. Add split scaffolding for large changes
-
-Add helper workflow to decompose large proposals into stackable slices:
-
- `openspec change split <change-id>` scaffolds child changes with `parent` + `dependsOn`
- generates minimal proposal/tasks stubs for each child slice
- converts the source change into a parent planning container (no duplicate child implementation tasks)
- re-running split for an already-split source change returns a deterministic actionable error unless `--overwrite` (alias `--force`) is passed
- `--overwrite` / `--force` fully regenerates managed child scaffold stubs and metadata links for the split, replacing prior scaffold content
-
-### 5. Document stack-first workflow
-
-Update docs to describe:
-
- how to model dependencies and parent/child slices
- when to split a large change
- how to use graph/next validation signals during parallel development
- migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md`:
-  - machine-readable change metadata becomes the normative dependency source
-  - `IMPLEMENTATION_ORDER.md` remains optional narrative context during transition
-
-## Capabilities
-
-### New Capabilities
-
- `change-stacking-workflow`: Dependency-aware sequencing and split scaffolding for change planning
-
-### Modified Capabilities
-
- `cli-change`: Adds graph/next/split planning commands and stack-aware validation messaging
- `change-creation`: Supports parent/dependency metadata when creating or splitting changes
- `openspec-conventions`: Defines optional stack metadata conventions for change proposals
-
-## Impact
-
- `src/core/project-config.ts` and related parsing/validation utilities for change metadata loading
- `src/core/config-schema.ts` (or dedicated change schema) for stack metadata validation
- `src/commands/change.ts` and/or `src/core/list.ts` for graph/next/split command behavior
- `src/core/validation/*` for dependency cycle and overlap checks
- `docs/cli.md`, `docs/concepts.md`, and contributor guidance for stack-aware workflows
- tests for metadata parsing, graph ordering, next-item suggestions, and split scaffolding
@@ -1,15 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Metadata Scaffolding
-Change creation workflows SHALL support optional dependency metadata for new or split changes.
-
-#### Scenario: Create change with stack metadata
- **WHEN** a change is created with stack metadata inputs
- **THEN** creation SHALL persist metadata fields in change configuration
- **AND** persisted metadata SHALL be validated against change metadata schema rules
-
-#### Scenario: Split-generated child metadata
- **WHEN** child changes are generated from a split workflow
- **THEN** each child SHALL include a `parent` link to the source change
- **AND** SHALL include dependency metadata needed for deterministic sequencing
-
@@ -1,65 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Metadata Model
-The system SHALL support optional metadata on active changes to express sequencing and decomposition relationships.
-
-#### Scenario: Optional stack metadata is present
- **WHEN** a change includes stack metadata fields
- **THEN** the system SHALL parse and expose `dependsOn`, `provides`, `requires`, `touches`, and `parent`
- **AND** validation SHALL enforce normalized field shapes and value types (`dependsOn`/`provides`/`requires`/`touches` as string arrays, `parent` as string when present)
-
-#### Scenario: Backward compatibility without stack metadata
- **WHEN** a change does not include stack metadata
- **THEN** existing behavior SHALL continue without migration steps
- **AND** validation SHALL not fail solely because stack metadata is absent
-
-### Requirement: Change Dependency Graph
-The system SHALL provide dependency-aware ordering for active changes.
-
-#### Scenario: Build dependency order
- **WHEN** users request stack planning output
- **THEN** the system SHALL compute a dependency graph across active changes
- **AND** SHALL return a deterministic topological order for unblocked changes
-
-#### Scenario: Tie-breaking within the same dependency depth
- **WHEN** multiple unblocked changes share the same topological dependency depth
- **THEN** ordering SHALL break ties lexicographically by change ID
- **AND** repeated runs over the same input SHALL return the same order
-
-#### Scenario: Dependency cycle detection
- **WHEN** active changes contain a dependency cycle
- **THEN** validation SHALL fail with cycle details before archive or sequencing actions proceed
- **AND** output SHALL include actionable guidance to break the cycle
-
-### Requirement: Capability marker and overlap semantics
-The system SHALL treat capability markers as validation contracts and `touches` as advisory overlap signals.
-
-#### Scenario: Required capability provided by an active change
- **WHEN** change B declares `requires` marker `X`
- **AND** active change A declares `provides` marker `X`
- **THEN** validation SHALL require B to declare an explicit ordering edge in `dependsOn` to at least one active provider of `X`
- **AND** validation SHALL fail if no explicit dependency is declared
-
-#### Scenario: Requires marker without active provider
- **WHEN** a change declares a `requires` marker
- **AND** no active change declares the corresponding `provides` marker
- **THEN** validation SHALL NOT infer an implicit dependency edge
- **AND** ordering SHALL continue to be determined solely by explicit `dependsOn` relationships
-
-#### Scenario: Requires marker satisfied by archived history
- **WHEN** a change declares a `requires` marker
- **AND** no active change provides that marker
- **AND** at least one archived change in history provides that marker
- **THEN** validation SHALL NOT warn solely about missing provider
- **AND** SHALL continue to use explicit `dependsOn` for active ordering
-
-#### Scenario: Requires marker missing in full history
- **WHEN** a change declares a `requires` marker
- **AND** no active or archived change in history provides that marker
- **THEN** validation SHALL emit a non-blocking warning naming the change and missing marker
- **AND** SHALL NOT infer an implicit dependency edge
-
-#### Scenario: Overlap warning for shared touches
- **WHEN** multiple active changes declare overlapping `touches` values
- **THEN** validation SHALL emit a warning listing the overlapping changes and touched areas
- **AND** validation SHALL NOT fail solely on overlap
@@ -1,27 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack Planning Commands
-The change CLI SHALL provide commands for dependency-aware sequencing of active changes.
-
-#### Scenario: Show dependency graph
- **WHEN** a user runs `openspec change graph`
- **THEN** the CLI SHALL display dependency relationships for active changes
- **AND** SHALL include a deterministic recommended order for execution
-
-#### Scenario: Show next unblocked changes
- **WHEN** a user runs `openspec change next`
- **THEN** the CLI SHALL list changes that are not blocked by unresolved dependencies
- **AND** SHALL use deterministic tie-breaking when multiple options are available
-
-### Requirement: Split Large Change Scaffolding
-The change CLI SHALL support scaffolding child slices from an existing large change.
-
-#### Scenario: Split command scaffolds child changes
- **WHEN** a user runs `openspec change split <change-id>`
- **THEN** the CLI SHALL create child change directories with proposal/tasks stubs
- **AND** generated metadata SHALL include `parent` and dependency links back to the source change
-
-#### Scenario: Re-running split on an already-split change
- **WHEN** a user runs `openspec change split <change-id>` for a parent whose generated child directories already exist
- **THEN** the CLI SHALL fail with a deterministic, actionable error
- **AND** SHALL NOT mutate existing child change content unless an explicit overwrite mode is requested
@@ -1,29 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Stack-Aware Change Planning Conventions
-OpenSpec conventions SHALL define optional metadata fields for sequencing and decomposition across concurrent changes.
-
-#### Scenario: Declaring change dependencies
- **WHEN** authors need to sequence related changes
- **THEN** conventions SHALL define how to declare dependencies and provided/required capability markers
- **AND** validation guidance SHALL distinguish hard blockers from soft overlap warnings
-
-#### Scenario: Dependency source of truth during migration
- **WHEN** both stack metadata and `openspec/changes/IMPLEMENTATION_ORDER.md` are present
- **THEN** conventions SHALL treat per-change stack metadata as the normative dependency source
- **AND** `IMPLEMENTATION_ORDER.md` SHALL be treated as optional narrative guidance
-
-#### Scenario: Explicit ordering remains required for capability markers
- **WHEN** authors use `provides` and `requires` markers to describe capability contracts
- **THEN** conventions SHALL require explicit `dependsOn` edges for ordering relationships
- **AND** conventions SHALL prohibit treating `requires` as an implicit dependency edge
-
-#### Scenario: Declaring advisory overlap via touches
- **WHEN** a change may affect capability/spec areas shared by concurrent changes without requiring ordering
- **THEN** conventions SHALL allow authors to declare `touches` with advisory area identifiers (for example capability IDs, spec area names, or paths)
- **AND** tooling SHALL treat `touches` as informational only (no implicit dependency edge, non-blocking validation signal)
-
-#### Scenario: Declaring parent-child split structure
- **WHEN** a large change is decomposed into smaller slices
- **THEN** conventions SHALL define parent-child metadata and expected ordering semantics
- **AND** docs SHALL describe when to split versus keep a single change
@@ -1,39 +0,0 @@
-## 1. Metadata Model
-
- [ ] 1.1 Add optional stack metadata fields (`dependsOn`, `provides`, `requires`, `touches`, `parent`) to change metadata schema
- [ ] 1.2 Keep metadata backward compatible for existing changes without new fields
- [ ] 1.3 Add tests for valid/invalid metadata and schema evolution behavior
-
-## 2. Stack-Aware Validation
-
- [ ] 2.1 Detect dependency cycles and fail validation with deterministic errors
- [ ] 2.2 Detect missing `dependsOn` targets (referenced change ID does not exist) and detect changes transitively blocked by unresolved/cyclic dependency paths
- [ ] 2.3 Add overlap warnings for active changes that touch the same capability/spec areas
- [ ] 2.4 Emit advisory warnings for unmatched `requires` markers when no provider exists in active history
- [ ] 2.5 Add tests for cycle, missing dependency, overlap warning, and unmatched `requires` cases
-
-## 3. Sequencing Commands
-
- [ ] 3.1 Add `openspec change graph` to display dependency order for active changes
- [ ] 3.2 Add `openspec change next` to suggest unblocked changes in recommended order
- [ ] 3.3 Add tests for topological ordering and deterministic tie-breaking (lexicographic by change ID at equal depth)
-
-## 4. Split Scaffolding
-
- [ ] 4.1 Add `openspec change split <change-id>` to scaffold child slices
- [ ] 4.2 Ensure generated children include parent/dependency metadata and stub proposal/tasks files
- [ ] 4.3 Convert the source change into a parent planning container as part of split (no duplicate child implementation tasks)
- [ ] 4.4 Add tests for split output structure, source-change parent conversion, and deterministic re-split error behavior when overwrite mode is not requested
- [ ] 4.5 Implement and test explicit overwrite mode for `openspec change split` (`--overwrite` / `--force`) for controlled re-splitting
-
-## 5. Documentation
-
- [ ] 5.1 Document stack metadata and sequencing workflow in `docs/concepts.md`
- [ ] 5.2 Document new change commands and usage examples in `docs/cli.md`
- [ ] 5.3 Add guidance for breaking large changes into independently mergeable slices
- [ ] 5.4 Document migration guidance for `openspec/changes/IMPLEMENTATION_ORDER.md` as optional narrative, not dependency source of truth
-
-## 6. Verification
-
- [ ] 6.1 Run targeted tests for change parsing, validation, and CLI commands
- [ ] 6.2 Run full test suite (`pnpm test`) and resolve regressions
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-21
@@ -1,161 +0,0 @@
-## Context
-
-OpenSpec today assumes project-local installation for most generated artifacts, with Codex command prompts as the main global exception. This mixed model works, but it is implicit and not user-configurable.
-
-The requested change is to support user-selectable install scope (`global` or `project`) for tool skills/commands, defaulting to `global` for new configurations while preserving legacy project-local behavior until explicit migration.
-
-## Goals / Non-Goals
-
-**Goals:**
-
- Provide a single scope preference that users can set globally and override per run
- Default new users to `global` scope
- Make install path resolution deterministic and explicit across tools/surfaces
- Preserve current behavior for users with older config files that do not yet define `installScope`
- Avoid silent partial installs; surface effective scope decisions in output
-
-**Non-Goals:**
-
- Implementing project-local config file support for global settings
- Defining global install paths for tools where upstream location conventions are unknown
- Changing workflow/profile semantics (`core`, `custom`, `delivery`) in this change
-
-## Decisions
-
-### 1. Scope model in global config
-
-Add install scope preference to global config:
-
-```ts
-type InstallScope = 'global' | 'project';
-
-interface GlobalConfig {
-  // existing fields...
-  installScope?: InstallScope;
-}
-```
-
-Defaults:
-
- New configs SHOULD write `installScope: global` explicitly.
- Existing configs without this field continue to load safely through schema evolution and SHALL resolve effective default as `project` until users explicitly set `installScope`.
-
-### 2. Explicit tool scope support metadata
-
-Extend `AI_TOOLS` metadata with optional scope support declarations per surface:
-
-```ts
-interface ToolInstallScopeSupport {
-  skills?: InstallScope[];
-  commands?: InstallScope[];
-}
-```
-
-Resolution rules:
-
-1. If scope support metadata is absent for a tool surface, treat it as project-only support for conservative backward compatibility.
-2. Try preferred scope.
-3. If unsupported, use alternate scope when supported.
-4. If neither is supported, fail with actionable error.
-
-This enables default-global behavior while remaining safe for tools that only support project-local paths.
-
-### 3. Scope-aware install target resolver
-
-Introduce shared resolver utilities to compute effective target paths for:
-
- skills root directory
- command output files
-
-Resolver input:
-
- tool id
- requested scope
- project root
- environment context (`CODEX_HOME`, etc.)
-
-Resolver output:
-
- effective scope per surface
- concrete target paths
- optional fallback reasons for user-facing output
-
-Platform behavior:
-
- Resolver outputs are OS-aware and normalized for the current platform.
- Windows global targets MUST use Windows path conventions (for example `%USERPROFILE%\.codex\prompts` fallback for Codex when `CODEX_HOME` is unset), not POSIX defaults.
-
-### 4. Context-aware command adapter paths
-
-Update command generation contract so adapters receive install context for path resolution. This avoids hardcoded absolute/relative assumptions and centralizes scope decisions.
-
-Example direction:
-
-```ts
-getFilePath(commandId: string, context: InstallContext): string
-```
-
-### 5. CLI behavior and UX
-
-`init`:
-
- Uses configured install scope by default; if absent in a legacy config, uses migration-safe effective default (`project`).
- Supports explicit override flag (`--scope global|project`).
- In interactive mode, displays chosen scope and any per-tool fallback decisions before writing files.
-
-`update`:
-
- Applies current scope preference (or override); if absent in a legacy config, uses migration-safe effective default (`project`).
- Performs drift detection using effective scoped paths and last-applied scope state.
- Reports effective scope decisions in summary output.
-
-`config`:
-
- `openspec config profile` interactive flow includes install scope selection.
- `openspec config list` shows `installScope` with source annotation (`explicit`, `new-default`, or `legacy-default`).
-
-### 6. Cleanup safety during scope changes
-
-When scope changes:
-
- Writes occur in the new effective targets.
- Cleanup/removal is limited to OpenSpec-managed files for the relevant tool/workflow IDs.
- Output explicitly states which scope locations were updated and which were cleaned.
-
-### 7. Scope drift state tracking
-
-Track last successful effective scope per tool/surface in project-managed state.
-
-Rules:
-
-1. Drift is detected when current resolved scope differs from last successful scope for a configured tool/surface.
-2. Scope support MUST be validated for all configured tools/surfaces before any write starts.
-3. Update writes to newly resolved targets first, verifies completeness, then removes managed files at previous targets.
-4. If new-target writes are partial or verification fails, command SHALL abort old-target cleanup and report actionable failure with incomplete/new and preserved/old paths.
-5. Cleanup failures do not rollback new writes; command returns actionable failure with leftover paths to resolve.
-
-### 8. Coordination with command-surface capability changes
-
-If `add-tool-command-surface-capabilities` lands, planning logic must evaluate scope resolution and delivery/capability behavior together (scope × delivery × command surface).
-
-## Risks / Trade-offs
-
-**Risk: Cross-project shared global state**
-Global installs are shared across projects. Updating global artifacts from one project affects all projects using that tool scope.
-→ Mitigation: make scope explicit in output; keep profile/delivery global and deterministic.
-
-**Risk: Tool-specific unknown global conventions**
-Not all tools document a stable global install location.
-→ Mitigation: use explicit scope support metadata; fallback or fail instead of guessing.
-
-**Risk: Adapter API churn**
-Changing adapter path contracts touches many files/tests.
-→ Mitigation: migrate in one pass with adapter contract tests and existing end-to-end generation tests.
-
-## Rollout Plan
-
-1. Add config schema + defaults for install scope.
-2. Add tool scope capability metadata and resolver utilities.
-3. Upgrade command adapter contract and generator path plumbing.
-4. Integrate scope-aware behavior into init/update.
-5. Add documentation and test coverage.
@@ -1,101 +0,0 @@
-## Why
-
-OpenSpec installation paths are currently inconsistent:
-
- Most skills and commands are written to project-local directories.
- Codex commands are already global (`$CODEX_HOME/prompts` or `~/.codex/prompts`).
- Users cannot choose a consistent install scope strategy across tools.
-
-This creates friction for users who prefer user-level setup and expect tool artifacts to be managed globally by default.
-
-## What Changes
-
-### 1. Add install scope preference with legacy-safe defaults
-
-Introduce a global install scope setting with two modes:
-
- `global` (default for newly created configs)
- `project`
-
-The setting is stored in global config and can be overridden per command run.
-For schema-evolved legacy configs where `installScope` is absent, effective default remains `project` until users opt in to global scope.
-
-### 2. Add scope-aware path resolution for skills and commands
-
-Refactor path resolution so both `init` and `update` compute install targets from:
-
- selected scope preference (`global` or `project`)
- tool capability metadata (which scopes each tool/surface supports)
- runtime context (project root, home directories, env overrides)
-
-### 3. Add per-tool capability metadata for scope support
-
-Extend tool metadata to explicitly declare scope support per surface:
-
- skills scope support
- commands scope support
-
-When preferred scope is unsupported for a tool/surface, the system uses deterministic fallback rules and reports the effective scope in output.
-
-### 4. Make command generation context-aware
-
-Extend command adapter path resolution so adapters receive install context (scope + environment context), instead of only command ID. This removes special-case handling and allows consistent scope behavior across tools.
-
-### 5. Update init/update UX and behavior
-
- `openspec init`:
-  - accepts scope override flag
-  - uses configured scope or migration-aware default (new configs default global; legacy configs preserve project until migration)
-  - applies scope-aware generation and cleanup planning
- `openspec update`:
-  - applies current scope preference
-  - syncs artifacts in effective scope per tool/surface
-  - tracks last successful effective scope per tool/surface for deterministic scope-drift detection
-  - reports effective scope decisions clearly
-
-### 6. Extend config UX and docs
-
- Add install scope control in `openspec config profile` interactive flow.
- Extend `openspec config list` output with install scope source (`explicit`, `new-default`, `legacy-default`).
- Add explicit migration guidance and prompt path so legacy users can opt into `global` scope.
- Update supported tools and CLI docs to explain scope behavior and fallback rules.
-
-### 7. Coordinate with command-surface capability delivery rules
-
-`cli-init` and `cli-update` planning SHALL compose:
-
- install scope (`global | project`)
- delivery mode (`both | skills | commands`)
- command surface capability (`adapter | skills-invocable | none`)
-
-This proposal remains focused on scope resolution, but implementation and test coverage should include mixed-tool cases to avoid regressions when combined with `add-tool-command-surface-capabilities`.
-
-## Capabilities
-
-### New Capabilities
-
- `installation-scope`: Scope preference model and effective scope resolution for tool artifact installation.
-
-### Modified Capabilities
-
- `global-config`: Persist install scope preference with schema evolution defaults.
- `cli-config`: Configure and inspect install scope preferences.
- `ai-tool-paths`: Add tool-level scope support metadata and path strategy.
- `command-generation`: Scope-aware adapter path resolution via install context.
- `cli-init`: Scope-aware initialization planning and output.
- `cli-update`: Scope-aware update sync, drift detection, and output.
- `migration`: Scope-aware migration scanning with install-scope-aware workflow lookup.
-
-## Impact
-
- `src/core/global-config.ts` - new install scope fields and defaults
- `src/core/config-schema.ts` - validation support for install scope config keys
- `src/commands/config.ts` - interactive profile/config UX additions for install scope
- `src/core/config.ts` - tool scope capability metadata
- `src/core/available-tools.ts` and `src/core/shared/tool-detection.ts` - scope-aware configured detection
- `src/core/command-generation/types.ts` and adapter implementations - context-aware file path resolution
- `src/core/init.ts` - scope-aware generation/removal planning
- `src/core/update.ts` - scope-aware sync/removal/drift planning
- `src/core/migration.ts` - scope-aware workflow scanning support
- `docs/supported-tools.md` and `docs/cli.md` - install scope behavior documentation
- `test/core/init.test.ts`, `test/core/update.test.ts`, adapter tests, config tests - scope coverage
@@ -1,35 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: AIToolOption skillsDir field
-The `AIToolOption` interface SHALL include scope support metadata in addition to path metadata.
-
-#### Scenario: Scope support metadata present
- **WHEN** a tool entry is defined in `AI_TOOLS`
- **THEN** it MAY declare supported install scopes for skills and commands
- **AND** this metadata SHALL be used for effective scope resolution
-
-#### Scenario: Scope support metadata absent
- **WHEN** a tool entry in `AI_TOOLS` omits scope support metadata for a surface
- **THEN** resolver behavior SHALL default that surface to project-only support
- **AND** effective scope resolution SHALL apply normal preferred/fallback rules against that default
-
-### Requirement: Path configuration for supported tools
-Path metadata SHALL support both project and global install targets via resolver logic.
-
-#### Scenario: Project scope path
- **WHEN** effective scope is `project` for skills
- **THEN** `skillsDir` SHALL be treated as a tool-specific container path under project root
- **AND** managed skill artifacts SHALL be written under `<projectRoot>/<skillsDir>/skills/`
- **AND** tool definitions SHALL set `skillsDir` accordingly (for example `.openspec` -> `.openspec/skills/`)
-
-#### Scenario: Global scope path
- **WHEN** effective scope is `global` for a supported tool/surface
- **THEN** paths SHALL resolve to tool-specific global directories
- **AND** environment overrides (for example `CODEX_HOME`) SHALL be respected where applicable
-
-#### Scenario: Windows global path resolution for Codex commands
- **WHEN** effective scope is `global`
- **AND** tool is Codex
- **AND** platform is Windows
- **THEN** command targets SHALL resolve to `%CODEX_HOME%\prompts` when `CODEX_HOME` is set
- **AND** SHALL otherwise resolve to `%USERPROFILE%\.codex\prompts`
@@ -1,21 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Install scope configuration via profile flow
-The config profile workflow SHALL allow users to configure install scope preference.
-
-#### Scenario: Interactive profile includes install scope
- **WHEN** user runs `openspec config profile`
- **THEN** the interactive flow SHALL include install scope selection with values `global` and `project`
- **AND** the currently configured value SHALL be pre-selected
-
-#### Scenario: Save install scope
- **WHEN** user confirms config profile changes
- **THEN** selected install scope SHALL be saved to global config
-
-### Requirement: Install scope visibility in config output
-The config command SHALL display install scope preference in human-readable output.
-
-#### Scenario: Config list shows install scope
- **WHEN** user runs `openspec config list`
- **THEN** output SHALL include current install scope value
- **AND** indicate whether value is default or explicit
@@ -1,28 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Init install scope selection
-The init command SHALL support install scope selection for generated artifacts.
-
-#### Scenario: Scope defaults to global
- **WHEN** user runs `openspec init` without explicit scope override
- **THEN** init SHALL use global config install scope
- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
-
-#### Scenario: Scope override via flag
- **WHEN** user runs `openspec init --scope project`
- **THEN** init SHALL use `project` as preferred scope for that run
- **AND** SHALL NOT mutate persisted global config unless user explicitly changes config
-
-### Requirement: Init uses effective scope resolution
-The init command SHALL resolve effective scope per tool surface before generating files.
-
-#### Scenario: Effective scope with fallback
- **WHEN** selected tool/surface does not support preferred scope
- **AND** supports alternate scope
- **THEN** init SHALL generate files at alternate effective scope
- **AND** SHALL display fallback note in summary
-
-#### Scenario: Unsupported scope selection
- **WHEN** selected tool/surface supports neither preferred nor alternate scope
- **THEN** init SHALL fail before writing files
- **AND** SHALL provide clear error guidance
@@ -1,34 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Update install scope selection
-The update command SHALL support install scope selection for sync operations.
-
-#### Scenario: Scope defaults to global config value
- **WHEN** user runs `openspec update` without explicit scope override
- **THEN** update SHALL use configured install scope
- **AND** if unset, SHALL resolve migration-aware default (`global` for newly created configs, `project` for legacy schema-evolved configs)
-
-#### Scenario: Scope override via flag
- **WHEN** user runs `openspec update --scope project`
- **THEN** update SHALL use `project` as preferred scope for that run
-
-### Requirement: Scope-aware sync and drift detection
-The update command SHALL evaluate configured state and drift using effective scoped paths.
-
-#### Scenario: Scoped drift detection
- **WHEN** update evaluates whether tools are up-to-date
- **THEN** it SHALL inspect files at effective scoped targets for each tool/surface
- **AND** SHALL compare current resolved scope against last successful effective scope for each tool/surface
- **AND** SHALL treat a difference as sync-required drift
-
-#### Scenario: Scope fallback during update
- **WHEN** preferred scope is unsupported for a configured tool/surface
- **AND** alternate scope is supported
- **THEN** update SHALL apply fallback scope resolution
- **AND** SHALL report fallback in output
-
-#### Scenario: Unsupported scope during update
- **WHEN** configured tool/surface supports neither preferred nor alternate scope
- **THEN** scope support SHALL be validated for all configured tools/surfaces before any write
- **AND** update SHALL fail without performing file writes when incompatibilities are detected
- **AND** SHALL report incompatible tools with remediation steps
@@ -1,22 +0,0 @@
-## MODIFIED Requirements
-
-### Requirement: ToolCommandAdapter interface
-The system SHALL provide install-context-aware command path resolution.
-
-#### Scenario: Adapter interface structure
- **WHEN** implementing a tool adapter
- **THEN** command file path resolution SHALL receive install context (including effective scope and environment context)
- **AND** SHALL return the effective command output path for that context
-
-#### Scenario: Codex global path remains supported
- **WHEN** resolving Codex command paths in global scope
- **THEN** the adapter SHALL target `$CODEX_HOME/prompts` when `CODEX_HOME` is set
- **AND** SHALL otherwise target `~/.codex/prompts`
-
-### Requirement: Command generator function
-The command generator SHALL pass install context into adapter path resolution for all generated commands.
-
-#### Scenario: Scoped command generation
- **WHEN** generating commands for a tool with a resolved effective scope
- **THEN** generated command paths SHALL match that effective scope
- **AND** the formatted command body/frontmatter behavior SHALL remain tool-specific and unchanged
@@ -1,24 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Install scope field in global config
-The global config schema SHALL include install scope preference.
-
-#### Scenario: Config shape supports install scope
- **WHEN** reading or writing global config
- **THEN** config SHALL support `installScope` with allowed values `global` and `project`
-
-#### Scenario: Schema evolution default
- **WHEN** loading legacy config without `installScope`
- **THEN** the system SHALL preserve schema compatibility without mutating the file
- **AND** effective install scope SHALL resolve to `project` until user explicitly sets `installScope`
- **AND** preserve all other existing fields
-
-#### Scenario: New config default
- **WHEN** creating a new global config
- **THEN** the system SHALL persist `installScope: global` by default
- **AND** users MAY switch to `project` explicitly
-
-#### Scenario: Invalid install scope value
- **WHEN** config validation receives an invalid install scope value
- **THEN** the value SHALL be rejected
- **AND** the system SHALL preserve the existing valid configuration
@@ -1,71 +0,0 @@
-## Purpose
-
-Define the install scope model for OpenSpec-generated skills and commands, including scope preference, effective scope resolution, and fallback/error semantics.
-
-## ADDED Requirements
-
-### Requirement: Install scope preference model
-The system SHALL support a user-level install scope preference with values `global` and `project`.
-
-#### Scenario: Default install scope
- **WHEN** install scope is not explicitly configured
- **THEN** the system SHALL resolve a migration-aware default:
- **AND** use `global` for newly created configs
- **AND** use `project` for legacy schema-evolved configs until explicit migration
-
-#### Scenario: Explicit install scope
- **WHEN** user configures install scope to `project`
- **THEN** generation and update flows SHALL use `project` as the preferred scope
-
-### Requirement: Effective scope resolution by tool surface
-The system SHALL compute effective scope per tool surface (skills, commands) based on preferred scope and tool capability support.
-
-#### Scenario: Preferred scope is supported
- **WHEN** preferred scope is supported for a tool surface
- **THEN** the system SHALL use that scope as the effective scope
-
-#### Scenario: Preferred scope is unsupported but alternate is supported
- **WHEN** preferred scope is not supported for a tool surface
- **AND** the alternate scope is supported
- **THEN** the system SHALL use the alternate scope as effective scope
- **AND** SHALL record a fallback note for user-facing output
-
-#### Scenario: No supported scope
- **WHEN** neither `global` nor `project` is supported for a tool surface
- **THEN** the command SHALL fail before writing files
- **AND** SHALL display actionable remediation
-
-### Requirement: Effective scope reporting
-The system SHALL report effective scope decisions in command output when they differ from the preferred scope.
-
-#### Scenario: Fallback reporting
- **WHEN** fallback resolution occurs for any selected/configured tool surface
- **THEN** init/update summaries SHALL include effective scope notes per affected tool
-
-### Requirement: Cross-platform path behavior
-Install scope resolution SHALL produce platform-correct target paths.
-
-#### Scenario: Global scope path on Windows
- **WHEN** effective scope is `global`
- **AND** the command runs on Windows
- **THEN** resolved target paths SHALL use Windows path conventions and separators
- **AND** SHALL NOT reuse POSIX-style home-relative defaults directly
-
-### Requirement: Cleanup safety for scope transitions
-Scope transitions SHALL update new targets first and clean old managed targets safely.
-
-#### Scenario: Automatic cleanup for managed files on scope change
- **WHEN** update or init applies a scope transition for a configured tool/surface
- **THEN** the system SHALL write new artifacts in the new effective scope before cleanup
- **AND** SHALL automatically remove only OpenSpec-managed files in the previous effective scope
-
-#### Scenario: Cleanup scope boundaries
- **WHEN** cleanup runs after a scope transition
- **THEN** the system SHALL leave non-managed files untouched
- **AND** SHALL limit removal scope to the affected tool/workflow-managed paths
-
-#### Scenario: Cleanup failure after successful writes
- **WHEN** new artifacts were written successfully in the new scope
- **AND** cleanup of old managed targets fails
- **THEN** the command SHALL report failure with leftover cleanup paths
- **AND** SHALL NOT rollback successfully written new-scope artifacts
@@ -1,61 +0,0 @@
-## 1. Global Config + Validation
-
- [ ] 1.1 Add `installScope` (`global` | `project`) to `GlobalConfig` with explicit `global` default for newly created configs
- [ ] 1.2 Update config schema validation and known-key checks to include install scope
- [ ] 1.3 Add schema-evolution tests ensuring missing `installScope` in legacy configs resolves to effective `project` until explicit migration
- [ ] 1.4 Extend `openspec config list` output to show install scope and source (`explicit`, `new-default`, `legacy-default`)
-
-## 2. Tool Capability Metadata + Resolvers
-
- [ ] 2.1 Extend `AI_TOOLS` metadata to declare scope support per surface (skills/commands)
- [ ] 2.2 Add shared install-target resolver for skills and commands using requested scope + tool support
- [ ] 2.3 Implement deterministic fallback/error behavior when preferred scope is unsupported, including default behavior when scope support metadata is absent
- [ ] 2.4 Add unit tests for scope resolution (preferred, fallback, and hard-fail paths)
-
-## 3. Command Generation Contract
-
- [ ] 3.1 Update `ToolCommandAdapter` path contract to accept install context
- [ ] 3.2 Update `generateCommand`/`generateCommands` to pass context through adapters
- [ ] 3.3 Migrate all command adapters to the new path contract
- [ ] 3.4 Update adapter tests for scoped path behavior (including Codex global path semantics)
-
-## 4. Init Command Scope Support
-
- [ ] 4.1 Add scope override flag to `openspec init` (`--scope global|project`)
- [ ] 4.2 Resolve effective scope per tool/surface before writing artifacts
- [ ] 4.3 Apply scope-aware generation/removal planning for skills and commands
- [ ] 4.4 Surface effective scope decisions and fallback notes in init summary output
- [ ] 4.5 Add init tests for global default, project override, and fallback/error scenarios
-
-## 5. Update Command Scope Support
-
- [ ] 5.1 Add scope override flag to `openspec update` (`--scope global|project`)
- [ ] 5.2 Make configured-tool detection and drift checks scope-aware
- [ ] 5.3 Persist and read last successful effective scope per tool/surface for deterministic scope-drift detection
- [ ] 5.4 Apply scope-aware sync/removal with consistent fallback/error behavior
- [ ] 5.5 Ensure scope changes update managed files in new targets and clean old managed targets safely
- [ ] 5.6 Add update tests for global/project/fallback/error and repeat-run idempotency
-
-## 6. Config UX
-
- [ ] 6.1 Extend `openspec config profile` interactive flow to select install scope
- [ ] 6.2 Preserve install scope when using preset shortcuts unless explicitly changed
- [ ] 6.3 Ensure non-interactive config behavior remains deterministic with clear errors
- [ ] 6.4 Add/adjust config command tests for install scope flows
- [ ] 6.5 Add migration UX for legacy users to opt into `global` scope explicitly
-
-## 7. Documentation
-
- [ ] 7.1 Update `docs/supported-tools.md` with scope behavior and effective-scope fallback notes
- [ ] 7.2 Update `docs/cli.md` examples for init/update scope options
- [ ] 7.3 Document cross-project implications of global installs
- [ ] 7.4 Add existing-user migration guide covering legacy-default behavior and explicit opt-in to `installScope: global`
-
-## 8. Verification
-
- [ ] 8.1 Run targeted tests for config, adapters, init, and update
- [ ] 8.2 Run full test suite (`pnpm test`) and resolve regressions
- [ ] 8.3 Manual smoke test: init/update with `installScope=global`
- [ ] 8.4 Manual smoke test: init/update with `--scope project`
- [ ] 8.5 Verify path resolution behavior on Windows CI (or cross-platform unit tests with mocked Windows paths)
- [ ] 8.6 Verify combined behavior matrix for mixed tools across scope × delivery × command-surface capability
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-20
@@ -1,45 +0,0 @@
-## Why
-
-We need a faster, more reliable way to manually validate CLI behavior changes like profile/delivery sync, migration behavior, and tool-detection UX.
-
-Today, manual review is mostly ad hoc: each developer sets up state differently, runs a different command order, and checks outputs informally. This makes regressions easy to miss and slows iteration on CLI UX work.
-
-An 80/20 solution is to add a lightweight smoke harness for deterministic non-interactive flows, plus a short manual checklist for interactive prompt behavior.
-
-## What Changes
-
- Add a lightweight QA smoke harness for OpenSpec CLI behavior with isolated per-run sandbox state
- Use `Makefile` targets as the primary entrypoint:
-  - `make qa` (default local QA entrypoint)
-  - `make qa-smoke` (deterministic non-interactive suite)
-  - `make qa-interactive` (prints/opens manual interactive checklist)
- Implement smoke logic in a script (invoked by Make targets), not in Make itself
- Ensure each scenario runs in an isolated sandbox with temporary `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
- Capture scenario artifacts for inspection (command output, exit code, and before/after filesystem state)
- Add a focused scenario set for high-risk behavior:
-  - init core output generation
-  - non-interactive detected-tool behavior
-  - migration when profile is unset
-  - delivery cleanup (`both -> skills`, `both -> commands`)
-  - commands-only update detection
-  - new tool directory detection messaging
-  - invalid profile override validation
- Add a short interactive checklist for keypress/prompt UX verification (Space toggle, Enter confirm, detected pre-selection)
- Wire CI to run the smoke suite on Linux as a fast regression gate
-
-## Capabilities
-
-### New Capabilities
-
- `qa-smoke-harness`: Deterministic, sandboxed CLI smoke validation with a single developer entrypoint
-
-### Modified Capabilities
-
- `developer-qa-workflow`: Standardized local/CI QA flow for CLI behavior and migration-sensitive scenarios
-
-## Impact
-
- `Makefile` - Add `qa`, `qa-smoke`, and `qa-interactive` targets
- `scripts/qa-smoke.sh` (or equivalent) - Implement sandbox setup, scenario execution, and assertions
- `docs/` - Add/update contributor-facing QA instructions and interactive checklist usage
- CI workflow - Add smoke target execution as a lightweight regression gate
@@ -1,49 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Makefile QA Entry Point
-
-The repository SHALL provide Makefile targets as the primary developer entrypoint for CLI QA flows.
-
-#### Scenario: Default QA target runs smoke suite
-
- **WHEN** a developer runs `make qa`
- **THEN** the command SHALL execute the non-interactive smoke suite
- **AND** exit with status code 0 only when all smoke scenarios pass
-
-#### Scenario: Smoke suite target is directly invokable
-
- **WHEN** a developer runs `make qa-smoke`
- **THEN** the command SHALL execute the same smoke suite used by `make qa`
- **AND** return a non-zero exit code on assertion failure
-
-#### Scenario: Interactive checklist target exists
-
- **WHEN** a developer runs `make qa-interactive`
- **THEN** the command SHALL provide the manual interactive verification checklist
- **AND** SHALL NOT run interactive prompt automation by default
-
-### Requirement: Sandboxed Smoke Scenario Runner
-
-The smoke suite SHALL run CLI scenarios in isolated sandboxes so tests are repeatable and do not depend on machine-global state.
-
-#### Scenario: Scenario execution is environment-isolated
-
- **WHEN** a smoke scenario runs
- **THEN** it SHALL use temporary values for `HOME`, `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and `CODEX_HOME`
- **AND** global config from the host machine SHALL NOT affect scenario outcomes
-
-#### Scenario: Scenario artifacts are captured for review
-
- **WHEN** a smoke scenario completes
- **THEN** the runner SHALL capture command output and exit status
- **AND** SHALL capture enough filesystem state to inspect before/after behavior
-
-#### Scenario: High-risk workflow coverage exists
-
- **WHEN** the smoke suite executes
- **THEN** it SHALL include scenarios covering profile/delivery behavior and migration-sensitive flows
- **AND** include at least:
-  - non-interactive tool detection
-  - migration when profile is unset
-  - delivery cleanup (`both -> skills`, `both -> commands`)
-  - commands-only update detection
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-19
@@ -1,111 +0,0 @@
-## Why
-
-OpenSpec currently assumes command delivery maps directly to command adapters. That assumption does not hold for all tools.
-
-Trae is a concrete example: it invokes OpenSpec workflows via skill entries (for example `/openspec-new-change`) rather than adapter-generated command files. In this model, skills are the command surface.
-
-Today, this creates a behavior gap:
-
- `delivery=commands` can remove skills
- tools without adapters skip command generation
- result: selected tools like Trae can end up with no invocable workflow artifacts
-
-This is more than a prompt UX issue because non-interactive and CI flows bypass interactive guidance. We need a capability-aware model in core generation logic.
-
-## What Changes
-
-### 1. Add explicit command-surface capability metadata
-
-Add an optional field in tool metadata to describe how a tool exposes commands:
-
- `adapter`: command files are generated through a command adapter
- `skills-invocable`: skills are directly invocable as commands
- `none`: no OpenSpec command surface
-
-Field should be optional. Default behavior is inferred from adapter registry presence: tools with a registered adapter resolve to `adapter`; tools with no adapter registration and no explicit annotation resolve to `none`.
-Capability values use kebab-case string tokens for consistency with serialized metadata conventions.
-
-Initial explicit override:
-
- Trae -> `skills-invocable`
-
-### 2. Make delivery behavior capability-aware
-
-Update `init` and `update` to compute effective artifact actions per tool from:
-
- global delivery (`both | skills | commands`)
- tool command surface capability
-
-Behavior matrix:
-
- `both`:
-  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
-  - generate command files only for `adapter` tools
-  - `none`: no artifact action; MAY emit compatibility warning
- `skills`:
-  - generate skills for all tools with `skillsDir` (including `skills-invocable`)
-  - remove adapter-generated command files
-  - `none`: no artifact action; MAY emit compatibility warning
- `commands`:
-  - `adapter`: generate commands, remove skills
-  - `skills-invocable`: generate (or keep if up-to-date) skills as command surface; do not remove them
-  - `none`: fail fast with clear error
-
-### 3. Add preflight validation and clearer output
-
-Before writing/removing artifacts, validate selected/configured tools against delivery mode:
-
- interactive flow: show clear compatibility note before confirmation
- non-interactive flow: fail with deterministic error listing incompatible tools and supported alternatives
-
-Update summaries to show effective delivery outcomes per tool (for example, when commands mode still installs skills for skills-invocable tools).
-
-### 4. Update docs and tests
-
- document capability model and Trae behavior under delivery modes
- ensure CLI docs and supported-tools docs reflect effective behavior
- add test coverage for:
-  - `init --tools trae` with `delivery=commands`
-  - `update` with Trae configured under `delivery=commands`
-  - mixed selections (`claude + trae`) across all delivery modes
-  - explicit error path for tools with no command surface under `delivery=commands`
-
-### 5. Coordinate with install-scope behavior
-
-When combined with `add-global-install-scope`, init/update planning must compose:
-
- install scope (`global | project`)
- delivery mode (`both | skills | commands`)
- command surface capability (`adapter | skills-invocable | none`)
-
-Implementation tests should cover mixed-tool matrices to ensure deterministic behavior when both changes are active.
-
-## Capabilities
-
-### New Capabilities
-
- `tool-command-surface`: Capability model that classifies tools as `adapter`, `skills-invocable`, or `none` to drive delivery behavior
-
-### Modified Capabilities
-
- `cli-init`: Delivery handling becomes tool-capability-aware with preflight compatibility validation
- `cli-update`: Delivery sync becomes tool-capability-aware with consistent compatibility validation and messaging
- `supported-tools-docs`: Documents command-surface semantics for non-adapter tools
-
-## Impact
-
- `src/core/config.ts` - add optional command-surface metadata and Trae override
- `src/core/command-generation/registry.ts` (or shared helper) - capability inference from adapter presence
- `src/core/init.ts` - capability-aware generation/removal planning + compatibility validation + summary messaging
- `src/core/update.ts` - capability-aware sync/removal planning + compatibility validation + summary messaging
- `src/core/shared/tool-detection.ts` - include capability-aware detection so `skills-invocable` tools remain detectable under `delivery=commands`, and `none` tools are excluded from command-surface artifact detection
- `docs/supported-tools.md` and `docs/cli.md` - document delivery behavior and compatibility notes
- `test/core/init.test.ts` and `test/core/update.test.ts` - add coverage for skills-invocable behavior and mixed-tool delivery scenarios
-
-## Sequencing Notes
-
- This change is intended to stack safely with `simplify-skill-installation` by introducing additive, capability-specific requirements for init/update.
- If `simplify-skill-installation` merges first, this change should be rebased and keep the capability-aware rule as the source of truth for `delivery=commands` behavior on `skills-invocable` tools.
- If this change merges first, the `simplify-skill-installation` branch should be rebased to avoid re-introducing a global "commands-only means no skills for all tools" assumption.
- If `add-global-install-scope` merges first, this change should be rebased to compose capability-aware behavior on top of scope-resolved path decisions from that change.
- If this change merges first, `add-global-install-scope` should be rebased to preserve Section 5 composition rules (`install scope` + `delivery mode` + `command surface capability`) without overriding capability-aware command-surface outcomes.
@@ -1,121 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Command surface capability resolution
-The init command SHALL resolve each selected tool's command surface using explicit metadata first, then deterministic inference.
-
-#### Scenario: Explicit command surface override
- **WHEN** a tool declares an explicit command-surface capability
- **THEN** init SHALL use that explicit capability
- **AND** SHALL NOT override it based on adapter presence
-
-#### Scenario: Inferred command surface from adapter presence
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** a command adapter is registered for the tool
- **THEN** init SHALL infer `adapter` as the command surface
-
-#### Scenario: Inferred command surface for skills-only tool
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** no command adapter is registered for the tool
- **AND** the tool has a configured `skillsDir`
- **THEN** init SHALL infer `skills-invocable` as the command surface
-
-#### Scenario: Inferred command surface without adapter or skills
- **WHEN** a tool does not declare an explicit command-surface capability
- **AND** no command adapter is registered for the tool
- **AND** the tool has no `skillsDir`
- **THEN** init SHALL infer `none` as the command surface
-
-### Requirement: Delivery compatibility by tool command surface
-The init command SHALL apply delivery settings using each tool's command surface capability, not adapter presence alone.
-
-#### Scenario: Both delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `both`
- **THEN** the system SHALL generate command files for active workflows using that adapter
- **AND** SHALL generate or refresh managed skills when the tool has `skillsDir`
-
-#### Scenario: Both delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `both`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL NOT require adapter-generated command files for that tool
-
-#### Scenario: Both delivery for none command surface
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
- **AND** delivery is set to `both`
- **THEN** the system SHALL perform no command-surface artifact action for that tool
- **AND** MAY emit a compatibility note indicating no command surface is available
-
-#### Scenario: Skills delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `skills`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL remove managed adapter-generated command files for that tool
-
-#### Scenario: Skills delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `skills`
- **THEN** the system SHALL generate or refresh managed skill directories when the tool has `skillsDir`
- **AND** SHALL NOT require adapter-generated command files for that tool
-
-#### Scenario: Skills delivery for none command surface
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `none`
- **AND** delivery is set to `skills`
- **THEN** the system SHALL perform no command-surface artifact action for that tool
- **AND** MAY emit a compatibility note indicating no command surface is available
-
-#### Scenario: Commands delivery for adapter-backed tool
- **WHEN** user runs `openspec init` with a selected tool that has a command adapter
- **AND** delivery is set to `commands`
- **THEN** the system SHALL generate command files for active workflows using that adapter
- **AND** the system SHALL remove managed skill directories for that tool
-
-#### Scenario: Commands delivery for skills-invocable tool
- **WHEN** user runs `openspec init` with a selected tool whose command surface is `skills-invocable`
- **AND** delivery is set to `commands`
- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
- **AND** the system SHALL NOT require a command adapter for that tool
-
-#### Scenario: Commands delivery for mixed tool selection
- **WHEN** user runs `openspec init` with multiple tools
- **AND** selected tools include both adapter-backed and skills-invocable command surfaces
- **AND** delivery is set to `commands`
- **THEN** the system SHALL apply commands-only behavior per tool capability
- **AND** the resulting install SHALL include command files for adapter-backed tools and skills for skills-invocable tools
-
-#### Scenario: Commands delivery for unsupported command surface
- **WHEN** user runs `openspec init` with a selected tool that has no command surface capability
- **AND** delivery is set to `commands`
- **THEN** the system SHALL fail before generating or deleting artifacts
- **AND** the error SHALL list incompatible tool IDs and explain supported alternatives (`both` or `skills`)
-
-#### Scenario: Interactive handling for unsupported command surface
- **WHEN** user runs `openspec init` interactively
- **AND** delivery is set to `commands`
- **AND** selected tools include one or more tools with command surface `none`
- **THEN** the CLI SHALL show a compatibility error and return to the interactive selection flow for correction
- **AND** SHALL not perform artifact writes until a valid selection is confirmed
-
-### Requirement: Init compatibility signaling
-The init command SHALL clearly signal command-surface compatibility outcomes in both interactive and non-interactive flows.
-
-#### Scenario: Interactive compatibility note
- **WHEN** init runs interactively
- **AND** delivery is `commands`
- **AND** selected tools include skills-invocable command surfaces
- **THEN** the system SHALL display a compatibility note before the confirmation prompt indicating those tools will use skills as their command surface
-
-#### Scenario: Non-interactive compatibility summary for skills-invocable tools
- **WHEN** init runs non-interactively (including `--tools` usage)
- **AND** delivery is `commands`
- **AND** selected tools include one or more `skills-invocable` command surfaces
- **THEN** the command SHALL proceed with exit code 0
- **AND** the command SHALL write deterministic compatibility summary lines to stdout indicating those tools will use managed skills as their command surface
-
-#### Scenario: Non-interactive compatibility failure
- **WHEN** init runs non-interactively (including `--tools` usage)
- **AND** delivery is `commands`
- **AND** selected tools include any tool with no command surface capability
- **THEN** the command SHALL exit with code 1
- **AND** the command SHALL write deterministic, actionable guidance for resolving the selection to stderr
@@ -1,48 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Delivery sync by command surface capability
-The update command SHALL synchronize artifacts using each configured tool's command surface capability.
-
-#### Scenario: Commands delivery for adapter-backed configured tool
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has an adapter-backed command surface
- **THEN** the system SHALL generate or refresh command files for active workflows
- **AND** the system SHALL remove managed skill directories for that tool
-
-#### Scenario: Commands delivery for skills-invocable configured tool
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has `skills-invocable` command surface capability
- **THEN** the system SHALL generate or refresh managed skill directories for active workflows
- **AND** the system SHALL NOT remove those managed skill directories as part of commands-only cleanup
- **AND** the system SHALL NOT attempt to require adapter-generated command files for that tool
-
-#### Scenario: Commands delivery with unsupported command surface
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a configured tool has no command surface capability
- **THEN** the system SHALL fail with exit code 1 before applying partial updates
- **AND** the output SHALL identify incompatible tools and recommended remediation
-
-### Requirement: Configured-tool detection for skills-invocable command surfaces
-The update command SHALL treat tools with skills-invocable command surfaces as configured when managed skill artifacts are present, including under commands delivery.
-
-#### Scenario: Skills-invocable tool under commands delivery
- **WHEN** user runs `openspec update`
- **AND** delivery is set to `commands`
- **AND** a tool has no adapter-generated command files
- **AND** that tool is marked `skills-invocable` and has managed skills installed
- **THEN** the system SHALL include the tool in configured-tool detection
- **AND** the system SHALL apply normal version/profile/delivery sync to that tool
-
-### Requirement: Update summary reflects effective per-tool delivery
-The update command SHALL report effective artifact behavior when delivery intent and artifact type differ due to tool capability.
-
-#### Scenario: Summary for skills-invocable tools in commands delivery
- **WHEN** update completes successfully
- **AND** delivery is `commands`
- **AND** at least one updated tool is `skills-invocable`
- **THEN** output SHALL include a clear note that those tools use skills as their command surface
- **AND** output SHALL avoid implying that command generation was skipped due to an error
-
@@ -1,53 +0,0 @@
-## 0. Stacking Coordination
-
- [ ] 0.1 Rebase this change on latest `main` before implementation
- [ ] 0.2 If `simplify-skill-installation` is merged first, preserve its profile/delivery model and apply this change as a capability-aware refinement
- [ ] 0.3 If this change merges first, ensure follow-up rebases do not reintroduce a blanket "commands = remove all skills" rule
- [ ] 0.4 If `add-global-install-scope` is merged, verify combined scope × delivery × command-surface behavior remains deterministic
-
-## 1. Tool Command-Surface Capability Model
-
- [ ] 1.1 Extend tool metadata in `src/core/config.ts` with an optional command-surface capability field
- [ ] 1.2 Define supported capability values: `adapter`, `skills-invocable`, `none`
- [ ] 1.3 Mark Trae as `skills-invocable`
- [ ] 1.4 Add a shared capability resolver (explicit metadata override first, inferred fallback from adapter presence second)
- [ ] 1.5 Add focused unit tests for capability resolution (explicit override, inferred adapter, inferred none)
-
-## 2. Init: Capability-Aware Delivery Planning
-
- [ ] 2.1 Refactor init generation logic to compute per-tool effective actions (generate/remove skills and commands) instead of using only global booleans
- [ ] 2.2 In `delivery=commands`, keep/generate skills for `skills-invocable` tools and do not remove those managed skill directories
- [ ] 2.3 In `delivery=commands`, fail fast before writes when any selected tool resolves to `none`
- [ ] 2.4 Update init output to clearly report effective behavior for `skills-invocable` tools (skills used as command surface)
- [ ] 2.5 Ensure init no longer reports "no adapter" for tools intentionally using `skills-invocable`
- [ ] 2.6 Add/adjust init tests for `delivery=commands` + `trae` (skills retained/generated, no adapter error), mixed tools (`claude,trae`) with per-tool expected outputs, and deterministic failure path for unsupported command surface (`none`)
-
-## 3. Update: Capability-Aware Sync and Drift Detection
-
- [ ] 3.1 Refactor update sync logic to apply delivery behavior per tool capability (not globally per run)
- [ ] 3.2 In `delivery=commands`, keep/generate managed skills for `skills-invocable` tools
- [ ] 3.3 In `delivery=commands`, fail before partial updates when configured tools include a `none` command surface
- [ ] 3.4 Update profile/delivery drift detection to avoid perpetual drift for `skills-invocable` tools under commands delivery
- [ ] 3.5 Ensure configured-tool detection still includes `skills-invocable` tools under commands delivery when managed skills exist
- [ ] 3.6 Update summary output so skills-invocable behavior is reported as expected behavior (not implicit skip/error)
- [ ] 3.7 Add/adjust update tests for `delivery=commands` + configured Trae (skills retained/generated), idempotent second update (no false drift loop), mixed configured tools (`claude` + `trae`), and deterministic preflight failure for unsupported command surface (`none`)
-
-## 4. UX and Error Messaging
-
- [ ] 4.1 Add interactive init compatibility note for `delivery=commands` when selected tools include `skills-invocable`
- [ ] 4.2 Add deterministic non-interactive error text with incompatible tool IDs and suggested alternatives (`both` or `skills`)
- [ ] 4.3 Align init and update wording so capability-related behavior/messages are consistent
-
-## 5. Documentation Updates
-
- [ ] 5.1 Update `docs/supported-tools.md` to document command-surface semantics for Trae and clarify delivery interactions
- [ ] 5.2 Update `docs/cli.md` delivery guidance to explain capability-aware behavior for `delivery=commands`
- [ ] 5.3 Add a short troubleshooting note for "commands-only + unsupported tool" failures
-
-## 6. Verification
-
- [ ] 6.1 Run targeted tests: `test/core/init.test.ts` and `test/core/update.test.ts`
- [ ] 6.2 Run any new capability/unit test files added in this change
- [ ] 6.3 Run full test suite (`pnpm test`) and resolve regressions
- [ ] 6.4 Manual smoke check: `openspec init --tools trae` with `delivery=commands`
- [ ] 6.5 Manual smoke check: mixed tools (`claude,trae`) with `delivery=commands`
@@ -1,18 +1,17 @@
 ## ADDED Requirements

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

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

-#### Scenario: Version display
- **WHEN** script runs
- **THEN** script displays current package version
- **AND** indicates version is read dynamically by flake.nix
+#### Scenario: Version already up-to-date
+- **WHEN** script runs and flake.nix version already matches package.json
+- **THEN** script reports version is up-to-date
+- **AND** continues to hash update

 ### Requirement: Automatic Hash Determination
 The script SHALL automatically determine and update the correct pnpm dependency hash.
@@ -30,8 +29,7 @@ The script SHALL automatically determine and update the correct pnpm dependency

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

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

 #### Scenario: Success summary
 - **WHEN** script completes successfully
- **THEN** summary shows version and hash changes
- **AND** next steps are displayed (test, verify, commit)
-
-#### Scenario: No changes needed
- **WHEN** hash is already up-to-date
- **THEN** script reports no changes needed
- **AND** exits with success code 0
+- **THEN** summary shows updated version and hash
+- **AND** next steps are displayed (test, commit, etc.)

 ### Requirement: Script Safety
 The script SHALL fail fast on errors and use safe defaults.
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-30
@@ -1,3 +0,0 @@
-# opencode-command-references
-
-Transform /opsx: to /opsx- in both commands and skills for OpenCode
@@ -1,70 +0,0 @@
-## Context
-
-OpenCode is one of many supported AI tools. Each tool has:
- A **command adapter** (in `src/core/command-generation/adapters/`) for generating tool-specific command files
- **Skills** generated via `generateSkillContent()` in `src/core/shared/skill-generation.ts`
-
-Currently:
- Commands go through the adapter system which can transform content per-tool
- Skills use a single shared function with no tool-specific transformation
-
-The templates in `src/core/templates/skill-templates.ts` use Claude's colon-based format (`/opsx:new`) as the canonical format. Tools that use different formats need transformation at generation time.
-
-## Goals / Non-Goals
-
-**Goals:**
- Transform all `/opsx:` command references to `/opsx-` for OpenCode in both commands and skills
- Create a shared, reusable transformation utility
- Keep the transformation opt-in via a callback parameter (not hard-coded tool detection)
-
-**Non-Goals:**
- Modifying the canonical template format (templates stay with `/opsx:`)
- Applying transformation to other tools (only OpenCode for now)
- Creating a full adapter system for skills (overkill for current needs)
-
-## Decisions
-
-### Decision 1: Shared Utility Function
-
-**Choice**: Create `transformToHyphenCommands()` in `src/utils/command-references.ts`
-
-**Rationale**: 
- Single source of truth for the transformation logic
- Can be used by both command adapter and skill generation
- Easy to test in isolation
- Follows existing utils pattern in the codebase
-
-**Alternatives considered**:
- Inline the transformation in each location - Duplicates logic, harder to maintain
-
-### Decision 2: Callback Parameter for Skill Generation
-
-**Choice**: Add optional `transformInstructions?: (instructions: string) => string` parameter to `generateSkillContent()`
-
-**Rationale**:
- Flexible - callers define the transformation, not the generation function
- No coupling - `generateSkillContent()` doesn't need to know about tool formats
- Extensible - could support other transformations in the future
- Follows inversion of control principle
-
-**Alternatives considered**:
- Add tool ID parameter and switch on it - Creates coupling, harder to extend
- Create skill adapter system parallel to commands - Over-engineering for current needs
- Transform in templates directly - Breaks single-source-of-truth principle
-
-### Decision 3: Apply at Generation Sites
-
-**Choice**: Pass transformer in `init.ts` and `update.ts` when `tool.value === 'opencode'`
-
-**Rationale**:
- These are the only two places that generate skills
- Simple conditional check, no new abstractions needed
- Easy to extend to other tools if needed later
-
-## Risks / Trade-offs
-
-| Risk | Mitigation |
-|------|------------|
-| Other `/opsx:` patterns exist that shouldn't be transformed | All occurrences in templates are command invocations - verified by inspection |
-| Future tools may need same transformation | Utility is shared and easy to reuse; can add to other tools' generation |
-| Callback adds complexity to function signature | Optional parameter with sensible default (no transformation) |
@@ -1,32 +0,0 @@
-## Why
-
-OpenCode uses hyphen-based command syntax (`/opsx-new`) but our templates contain colon-based references (`/opsx:new`). This creates inconsistency where generated command files and skill files contain references that don't match the actual command invocation syntax, confusing both the AI and users.
-
-## What Changes
-
- Create a shared transformation utility (`transformToHyphenCommands`) for converting `/opsx:` to `/opsx-`
- Update the OpenCode command adapter to transform body text using this utility
- Add an optional `transformInstructions` callback parameter to `generateSkillContent()`
- Update `init.ts` and `update.ts` to pass the transformer when generating skills for OpenCode
-
-## Capabilities
-
-### New Capabilities
-
-None - this is a bug fix, not a new capability.
-
-### Modified Capabilities
-
-None - no spec-level behavior changes. This is an implementation fix in the OpenCode adapter and skill generation that doesn't change any external requirements or contracts.
-
-## Impact
-
- **Code**: 
-  - `src/utils/command-references.ts` (new file)
-  - `src/utils/index.ts` (export)
-  - `src/core/shared/skill-generation.ts` (add callback parameter)
-  - `src/core/command-generation/adapters/opencode.ts` (use transformer)
-  - `src/core/init.ts` (pass transformer for OpenCode)
-  - `src/core/update.ts` (pass transformer for OpenCode)
- **Users**: OpenCode users will see correct `/opsx-` command references in both generated command files AND skill files
- **Other tools**: No impact - transformation only applies to OpenCode
@@ -1,9 +0,0 @@
-# No Spec Changes
-
-This is a bug fix that doesn't modify any external requirements or contracts.
-
-The proposal's Capabilities section indicates:
- **New Capabilities**: None
- **Modified Capabilities**: None
-
-No spec files are needed for this implementation-only fix.
@@ -1,22 +0,0 @@
-## 1. Implementation
-
- [x] 1.1 Create `src/utils/command-references.ts` with `transformToHyphenCommands()` function
- [x] 1.2 Export `transformToHyphenCommands` from `src/utils/index.ts`
- [x] 1.3 Update `generateSkillContent()` in `src/core/shared/skill-generation.ts` to accept optional `transformInstructions` callback
- [x] 1.4 Update OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` to use `transformToHyphenCommands()` for body text
- [x] 1.5 Update `init.ts` to pass transformer when generating skills for OpenCode
- [x] 1.6 Update `update.ts` to pass transformer when generating skills for OpenCode
-
-## 2. Testing
-
- [x] 2.1 Create `test/utils/command-references.test.ts` with unit tests for `transformToHyphenCommands()`
- [x] 2.2 Add test to `test/core/command-generation/adapters.test.ts` for OpenCode body transformation
- [x] 2.3 Add test to `test/core/shared/skill-generation.test.ts` for transformer callback
-
-## 3. Verification
-
- [x] 3.1 Run `npx vitest run test/utils/command-references.test.ts test/core/command-generation/adapters.test.ts test/core/shared/skill-generation.test.ts` to ensure tests pass
- [x] 3.2 Run `pnpm run build` to ensure no TypeScript errors
- [x] 3.3 Run `openspec init --tools opencode` in a temp directory and verify:
-  - Command files in `.opencode/command/` contain `/opsx-` references (not `/opsx:`)
-  - Skill files in `.opencode/skills/` contain `/opsx-` references (not `/opsx:`)
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-24
@@ -1,115 +0,0 @@
-## Context
-
-OpenSpec has a complete skill and slash command generation system. Skills are defined in `src/core/templates/skill-templates.ts` as functions that return `SkillTemplate` objects (for Agent Skills) and `CommandTemplate` objects (for slash commands). These are registered in `src/core/shared/skill-generation.ts` and generated during `openspec init` and `openspec update`.
-
-Existing skills follow a consistent pattern:
- `getXxxSkillTemplate()` returns the skill with name, description, instructions
- `getOpsxXxxCommandTemplate()` returns the slash command with name, description, category, tags, content
- Both are registered in their respective arrays in `skill-generation.ts`
-
-## Goals / Non-Goals
-
-**Goals:**
- Add `/opsx:onboard` skill that teaches the OpenSpec workflow through guided practice
- Follow existing patterns for skill/command template generation
- Provide comprehensive narration that explains each step
- Include codebase analysis to suggest real, appropriately-scoped tasks
-
-**Non-Goals:**
- Creating a separate "demo mode" or simulated workflow (we do real work)
- Adding new CLI commands (this is purely agent instructions)
- Modifying the init/update flow (just adding to the template arrays)
-
-## Decisions
-
-### Decision 1: Single Monolithic Skill
-
-The onboard skill will be a single comprehensive instruction set rather than composing existing skills with flags.
-
-**Rationale:**
- Slash commands don't support flags (they're just prompts)
- A monolithic skill gives complete control over narration and pacing
- Easier to maintain a single cohesive experience
- Users learn the real commands by seeing them mentioned in narration
-
-### Decision 2: Codebase Analysis Patterns
-
-The skill instructions will direct the agent to look for specific patterns when suggesting starter tasks:
-
-1. TODO/FIXME comments in code
-2. Missing error handling (`catch` blocks that swallow errors, no try-catch around risky operations)
-3. Functions without tests (cross-reference src/ with test files)
-4. Type: `any` in TypeScript files
-5. Console.log statements in non-debug code
-6. Missing input validation on user-facing inputs
-7. Recent git commits (for context on what user is working on)
-
-**Rationale:** These are universally applicable, easy to detect, and produce well-scoped tasks.
-
-### Decision 3: Narration Integration Style
-
-Each phase will follow a pattern:
-1. **EXPLAIN** what we're about to do and why (1-2 sentences)
-2. **DO** the action (run command, create artifact)
-3. **SHOW** what happened
-4. **PAUSE** at key transitions (not every step)
-
-Pauses occur at:
- After task selection (before creating change)
- After drafting proposal (before saving)
- After tasks are generated (before implementation)
- After archive (final recap)
-
-**Rationale:** Too many pauses becomes tedious. Too few loses the teaching opportunity. These are the natural "chapter breaks."
-
-### Decision 4: Scope Guardrail Approach
-
-When user selects a task that's too large, the skill will:
-1. Acknowledge the task is valuable
-2. Explain why smaller is better for first time
-3. Suggest a smaller slice or alternative
-4. Let user override if they insist
-
-**Rationale:** Soft guardrails teach without frustrating. Users learn scope calibration as part of the experience.
-
-### Decision 5: Template Structure
-
-The skill template will be ~400-600 lines of instruction text, structured as:
-
-```
- Preflight checks (init status)
- Phase 1: Welcome & Setup
- Phase 2: Task Selection (with codebase analysis instructions)
- Phase 3: Explore Demo (brief)
- Phase 4: Change Creation
- Phase 5: Proposal
- Phase 6: Specs
- Phase 7: Design
- Phase 8: Tasks
- Phase 9: Apply (Implementation)
- Phase 10: Archive
- Phase 11: Recap & Next Steps
- Edge cases & graceful exits
-```
-
-The command template will be identical to the skill template (same content, different wrapper).
-
-**Rationale:** Following the established pattern where skill and command share the same core instructions.
-
-## Risks / Trade-offs
-
-**Risk: Instruction length**
-The skill will be significantly longer than existing skills (~500 lines vs ~100-200).
-→ Mitigation: This is acceptable since onboarding is inherently comprehensive. Token cost is one-time per session.
-
-**Risk: Codebase analysis may find nothing**
-Some codebases (new projects, very clean code) may not have obvious improvement opportunities.
-→ Mitigation: Fall back to asking user what they want to build. Include "add a new feature" as an option.
-
-**Risk: Task suggestions may be inappropriate**
-Agent might suggest tasks that touch sensitive code or have hidden complexity.
-→ Mitigation: User always chooses; agent just suggests. Scope estimates help set expectations.
-
-**Risk: User abandons mid-way**
-Onboarding takes ~15 minutes; users may not complete it.
-→ Mitigation: Graceful exit handling - note the change is saved, explain how to continue later.
@@ -1,27 +0,0 @@
-## Why
-
-Users who run `openspec init` are left with files but no clear path to actually using the system. There's a gap between "I have OpenSpec set up" and "I understand the workflow." An onboarding skill would guide users through their first complete change cycle on a real task in their codebase, teaching the workflow by doing it.
-
-## What Changes
-
- Add new `/opsx:onboard` skill that guides users through their first OpenSpec change
- Add corresponding slash command template for editor integrations
- The skill will:
-  - Analyze the user's codebase to suggest appropriately-scoped starter tasks
-  - Walk through the full workflow (explore → new → proposal → specs → design → tasks → apply → archive)
-  - Provide narration explaining each step as it happens
-  - Result in a real, implemented change in the user's codebase
-
-## Capabilities
-
-### New Capabilities
- `opsx-onboard-skill`: The onboarding skill that guides users through their first complete OpenSpec workflow cycle with narration and codebase-aware task suggestions
-
-### Modified Capabilities
-<!-- No existing specs are being modified - this is purely additive -->
-
-## Impact
-
- `src/core/templates/skill-templates.ts`: Add `getOnboardSkillTemplate()` and `getOpsxOnboardCommandTemplate()` functions
- `src/core/shared/skill-generation.ts`: Register the new skill and command templates in `getSkillTemplates()` and `getCommandTemplates()`
- Users running `openspec init` or `openspec update` will get the new skill/command files generated
@@ -1,162 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OPSX Onboard Skill
-
-The system SHALL provide an `/opsx:onboard` skill that guides users through their first complete OpenSpec workflow cycle with narration and real codebase work.
-
-#### Scenario: Skill invocation
-
- **WHEN** user invokes `/opsx:onboard`
- **THEN** agent checks if OpenSpec is initialized
- **AND** if not initialized, prompts user to run `openspec init` first
- **AND** if initialized, proceeds with onboarding flow
-
-#### Scenario: Welcome and expectations
-
- **WHEN** onboarding begins
- **THEN** agent displays welcome message explaining what will happen
- **AND** sets expectation of ~15 minute duration
- **AND** explains the workflow phases: explore → new → artifacts → apply → archive
-
-### Requirement: Codebase Analysis for Task Suggestions
-
-The skill SHALL analyze the user's codebase to suggest appropriately-scoped starter tasks.
-
-#### Scenario: Codebase scanning
-
- **WHEN** onboarding reaches task selection phase
- **THEN** agent scans codebase for small improvement opportunities
- **AND** looks for: TODO/FIXME comments, missing error handling, functions without tests, outdated dependencies, type: any in TypeScript, console.log in production code, missing input validation
- **AND** checks recent git commits for context on current work
-
-#### Scenario: Task suggestion presentation
-
- **WHEN** agent has analyzed codebase
- **THEN** agent presents 3-4 specific task suggestions with scope estimates
- **AND** each suggestion includes: task description, estimated scope (files/lines), why it's a good starter
- **AND** offers option for user to specify their own task
-
-#### Scenario: Scope guardrail
-
- **WHEN** user selects or describes a task that is too large
- **THEN** agent gently redirects toward smaller scope
- **AND** suggests breaking down or deferring the large task
- **AND** offers appropriately-sized alternatives
-
-### Requirement: Explore Phase Demo
-
-The skill SHALL briefly demonstrate explore mode before creating a change.
-
-#### Scenario: Brief explore demonstration
-
- **WHEN** task is selected
- **THEN** agent briefly demonstrates `/opsx:explore` by investigating relevant code
- **AND** explains explore mode is for thinking before doing
- **AND** keeps this phase short (not a full exploration session)
- **AND** transitions to change creation
-
-### Requirement: Guided Artifact Creation
-
-The skill SHALL guide users through each artifact with narration explaining the purpose.
-
-#### Scenario: Change creation with narration
-
- **WHEN** creating the change directory
- **THEN** agent runs `openspec new change "<name>"` with derived kebab-case name
- **AND** explains what a "change" is (container for thinking and planning)
- **AND** shows the folder structure that was created
- **AND** pauses for user acknowledgment before proceeding
-
-#### Scenario: Proposal creation with narration
-
- **WHEN** creating proposal.md
- **THEN** agent explains proposals capture WHY we're making this change
- **AND** drafts proposal based on selected task
- **AND** shows draft to user for approval before saving
- **AND** explains the sections (Why, What Changes, Capabilities, Impact)
-
-#### Scenario: Specs creation with narration
-
- **WHEN** creating spec files
- **THEN** agent explains specs define WHAT we're building in detail
- **AND** explains the requirement/scenario format
- **AND** creates spec file(s) based on proposal capabilities
- **AND** notes that specs become documentation that stays in sync
-
-#### Scenario: Design creation with narration
-
- **WHEN** creating design.md
- **THEN** agent explains design captures HOW we'll build it
- **AND** notes this is where technical decisions and tradeoffs live
- **AND** for small changes, acknowledges design may be brief
- **AND** creates design based on proposal and specs
-
-#### Scenario: Tasks creation with narration
-
- **WHEN** creating tasks.md
- **THEN** agent explains tasks break work into checkboxes
- **AND** explains these drive the apply phase
- **AND** generates task list from design and specs
- **AND** shows tasks and asks if ready to implement
-
-### Requirement: Guided Implementation
-
-The skill SHALL implement tasks with narration connecting back to artifacts.
-
-#### Scenario: Implementation with narration
-
- **WHEN** implementing tasks
- **THEN** agent announces each task before working on it
- **AND** implements the change in the codebase
- **AND** occasionally references how specs/design informed decisions
- **AND** marks each task complete as it finishes
- **AND** keeps narration light (not over-explaining)
-
-#### Scenario: Implementation completion
-
- **WHEN** all tasks are complete
- **THEN** agent announces completion
- **AND** summarizes what was done
- **AND** transitions to archive phase
-
-### Requirement: Archive with Explanation
-
-The skill SHALL archive the completed change and explain what happened.
-
-#### Scenario: Archive with narration
-
- **WHEN** archiving the change
- **THEN** agent explains archive moves change to dated folder
- **AND** runs archive process
- **AND** shows where archived change lives
- **AND** explains the long-term value (finding decisions later)
-
-### Requirement: Recap and Next Steps
-
-The skill SHALL conclude with a recap and command reference.
-
-#### Scenario: Final recap
-
- **WHEN** onboarding is complete
- **THEN** agent summarizes the workflow phases completed
- **AND** emphasizes this rhythm works for any size change
- **AND** provides command reference table (/opsx:explore, /opsx:new, /opsx:ff, /opsx:continue, /opsx:apply, /opsx:verify, /opsx:archive)
- **AND** suggests next actions (try /opsx:new or /opsx:ff on something)
-
-### Requirement: Graceful Exit Handling
-
-The skill SHALL handle users who want to stop mid-way.
-
-#### Scenario: User wants to stop
-
- **WHEN** user indicates they want to stop during onboarding
- **THEN** agent acknowledges gracefully
- **AND** notes that the in-progress change is saved
- **AND** explains how to continue later with `/opsx:continue <name>`
- **AND** exits without pressure
-
-#### Scenario: User wants quick reference only
-
- **WHEN** user says they just want to see the commands
- **THEN** agent provides command cheat sheet
- **AND** exits gracefully with encouragement to try `/opsx:new`
@@ -1,21 +0,0 @@
-## 1. Add Skill Template
-
- [x] 1.1 Add `getOnboardSkillTemplate()` function to `src/core/templates/skill-templates.ts` with full onboarding instruction text covering all phases (preflight, welcome, task selection, explore demo, change creation, proposal, specs, design, tasks, apply, archive, recap)
- [x] 1.2 Include codebase analysis instructions for suggesting starter tasks (TODO/FIXME, missing error handling, missing tests, type:any, console.log, missing validation)
- [x] 1.3 Include narration pattern instructions (EXPLAIN → DO → SHOW → PAUSE at key transitions)
- [x] 1.4 Include scope guardrail instructions for redirecting users away from overly large tasks
- [x] 1.5 Include graceful exit handling instructions (user stops mid-way, user just wants command reference)
-
-## 2. Add Command Template
-
- [x] 2.1 Add `getOpsxOnboardCommandTemplate()` function to `src/core/templates/skill-templates.ts` returning CommandTemplate with same instruction content as skill
-
-## 3. Register Templates
-
- [x] 3.1 Add onboard skill to `getSkillTemplates()` array in `src/core/shared/skill-generation.ts` with dirName `openspec-onboard`
- [x] 3.2 Add onboard command to `getCommandTemplates()` array in `src/core/shared/skill-generation.ts` with id `onboard`
-
-## 4. Verify
-
- [x] 4.1 Run `pnpm run build` to ensure TypeScript compiles
- [x] 4.2 Test skill generation by running `openspec init` in a test directory and verifying onboard skill/command files are created
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-04-23
@@ -1,3 +0,0 @@
-# add-kimi-cli-skills-only-support
-
-Add Kimi CLI as a supported skills-only tool without a command adapter
@@ -1,85 +0,0 @@
-## Context
-
-Kimi CLI is not another Claude/Codex-style adapter target. Its extension model is built around discovered skills, not external command files:
-
- skills are discovered from `.kimi/skills/`
- skills are exposed as `/skill:<name>`
- no stable `.kimi/commands/` or prompt-file loading mechanism was found in the Kimi CLI codebase
-
-OpenSpec's existing architecture can already represent that shape:
-
- `AI_TOOLS` can advertise a `skillsDir`
- `init` can install skills for any selected tool with `skillsDir`
- when command generation is attempted for a tool without an adapter, OpenSpec already records `commandsSkipped`
-
-## Goals
-
- Add Kimi CLI using the same narrow `skills-only` pattern already used by Trae
- Keep the implementation small: metadata, docs, and a focused regression test
- Make the spec text match the current code path for adapterless tools
-
-## Non-Goals
-
- designing a Kimi-specific command adapter without upstream support
- changing tool capability modeling across the whole generation pipeline
- reworking `delivery=commands` behavior for all adapterless tools
-
-## Decisions
-
-### 1. Represent Kimi CLI as an adapterless tool with `.kimi`
-
-Add a new `AI_TOOLS` entry:
-
-```ts
-{ name: 'Kimi CLI', value: 'kimi', available: true, successLabel: 'Kimi CLI', skillsDir: '.kimi' }
-```
-
-This matches Kimi CLI's project-local skills root and lets existing init/update detection paths treat it as a supported tool.
-
-### 2. Do not add a Kimi command adapter
-
-No `src/core/command-generation/adapters/kimi.ts` file will be added, and the command adapter registry will remain unchanged.
-
-Rationale:
-
- Kimi CLI exposes skills dynamically as `/skill:<name>`
- the previous upstream PR stalled specifically because no legitimate adapter target was available
- adding a fake `.kimi/commands/...` path would create behavior OpenSpec cannot justify against upstream Kimi CLI behavior
-
-### 3. Document Kimi by its real invocation surface
-
-Kimi documentation in OpenSpec must use Kimi's actual skill invocation form:
-
- supported-tools: no generated command files, use `/skill:openspec-*`
- commands doc: examples such as `/skill:openspec-propose`
-
-The docs must not claim generated `opsx-*` files or `/openspec-*` direct invocations for Kimi.
-
-### 4. Keep the change compatible with existing Trae-style behavior
-
-This change intentionally follows the current adapterless-tool behavior already present in the codebase:
-
- skills are created whenever delivery includes skills
- command generation is skipped when no adapter exists
- init output reports `Commands skipped for: kimi (no adapter)`
-
-This keeps the Kimi change small and avoids overlapping implementation work already captured in `add-tool-command-surface-capabilities`.
-
-## Test Strategy
-
-Add one focused regression test in `test/core/init.test.ts`:
-
- configure `delivery=both`
- run init with `--tools kimi`
- verify Kimi skills are created under `.kimi/skills/...`
- verify init reports the skipped command generation path for `kimi`
-
-That test is enough for this narrow change because:
-
- adapterless update behavior already has generic coverage
- CLI tool-id rendering is derived from `AI_TOOLS`
- no command adapter or path formatting logic is being introduced
-
-## Risks / Trade-offs
-
-The main trade-off is scope: Kimi will inherit the current adapterless-tool behavior, including the broader limitation that `delivery=commands` is not yet capability-aware for skills-invocable tools. That is acceptable for this change because it matches the existing Trae/ForgeCode model and keeps the implementation aligned with verified Kimi CLI behavior.
@@ -1,38 +0,0 @@
-## Why
-
-OpenSpec already has user demand for Kimi CLI support, but the previous upstream attempt stalled because it assumed Kimi needed a command adapter. Local review of the Kimi CLI codebase shows a different integration surface: Kimi discovers `SKILL.md` files from `.kimi/skills/` and exposes them through `/skill:<name>`, but it does not provide a stable, file-based custom command directory like Claude Code or Codex.
-
-OpenSpec already supports tools that install skills without a command adapter. Trae and ForgeCode are the existing examples. Kimi should follow the same pattern instead of introducing undocumented `.kimi/commands/...` behavior.
-
-## What Changes
-
- Add Kimi CLI as a supported tool in `AI_TOOLS` with `skillsDir: '.kimi'`
- Document Kimi CLI as a skills-only integration in supported tools and command usage docs
- Align change specs so `cli-init` explicitly allows selected tools with `skillsDir` but no registered command adapter
-
-## Capabilities
-
-### New Capabilities
-
-_None._
-
-### Modified Capabilities
-
- `ai-tool-paths`: define the `.kimi` skills root for Kimi CLI
- `cli-init`: clarify that adapterless tools remain valid selections and skip command-file generation with an informational message
-
-## Impact
-
- `src/core/config.ts` - add Kimi CLI tool metadata
- `docs/supported-tools.md` - add Kimi CLI row and tool id
- `docs/commands.md` - document `/skill:openspec-*` usage for Kimi CLI
- `docs/cli.md` - include `kimi` in the supported `--tools` list
- `test/core/init.test.ts` - cover Kimi CLI as an adapterless tool during init
-
-## Non-Goals
-
- Adding `src/core/command-generation/adapters/kimi.ts`
- Defining a `.kimi/commands/...` output path
- Changing the broader delivery model for adapterless tools under `delivery=commands`
-
-That broader capability-aware delivery work is already being explored separately in `add-tool-command-surface-capabilities`. This change stays narrow and follows the existing Trae/ForgeCode pattern.
@@ -1,12 +0,0 @@
-# ai-tool-paths Delta Specification
-
-## MODIFIED Requirements
-
-### Requirement: Path configuration for supported tools
-
-The `AI_TOOLS` array SHALL include `skillsDir` for tools that support the Agent Skills specification.
-
-#### Scenario: Kimi CLI paths defined
-
- **WHEN** looking up the `kimi` tool
- **THEN** `skillsDir` SHALL be `.kimi`
@@ -1,37 +0,0 @@
-# cli-init Delta Specification
-
-## MODIFIED Requirements
-
-### Requirement: Slash Command Generation
-
-The command SHALL generate opsx slash commands only for selected tools that have a registered command adapter, while keeping adapterless tools valid for skill generation.
-
-#### Scenario: Generating slash commands for a tool with a registered adapter
-
- **WHEN** a tool with a registered command adapter is selected during initialization
- **THEN** create 9 slash command files using the tool's command adapter:
-  - `/opsx:explore`
-  - `/opsx:new`
-  - `/opsx:continue`
-  - `/opsx:apply`
-  - `/opsx:ff`
-  - `/opsx:verify`
-  - `/opsx:sync`
-  - `/opsx:archive`
-  - `/opsx:bulk-archive`
- **AND** use tool-specific path conventions (e.g., `.claude/commands/opsx/` for Claude)
- **AND** include tool-specific frontmatter format
-
-#### Scenario: Selected tool has no command adapter
-
- **GIVEN** a selected tool has `skillsDir` configured but no registered command adapter
- **WHEN** initialization includes command generation
- **THEN** skill generation for that tool SHALL still remain valid
- **AND** command-file generation SHALL be skipped for that tool
- **AND** the command output SHALL include `Commands skipped for: <tool-id> (no adapter)`
-
-#### Scenario: Kimi CLI skips command-file generation
-
- **WHEN** the user selects Kimi CLI during initialization
- **THEN** OpenSpec SHALL treat it as a supported tool with `skillsDir: '.kimi'`
- **AND** command-file generation SHALL be skipped because no Kimi adapter is registered
@@ -1,22 +0,0 @@
-## 1. Change Artifacts
-
- [x] 1.1 Write proposal, design, and spec deltas for Kimi CLI skills-only support
-
-## 2. Tool Metadata
-
- [x] 2.1 Add `Kimi CLI` to `src/core/config.ts` with `value: 'kimi'` and `skillsDir: '.kimi'`
-
-## 3. Documentation
-
- [x] 3.1 Update `docs/supported-tools.md` with a Kimi CLI row that clearly states there is no command adapter
- [x] 3.2 Update `docs/commands.md` to document Kimi CLI usage via `/skill:openspec-*`
- [x] 3.3 Update `docs/cli.md` so the supported `--tools` list includes `kimi`
-
-## 4. Tests
-
- [x] 4.1 Add a targeted init regression test for `--tools kimi` under adapterless command generation
-
-## 5. Validation
-
- [x] 5.1 Validate the change artifacts with `openspec validate`
- [x] 5.2 Run targeted tests and fix any regressions
@@ -1,208 +0,0 @@
-## Product Model
-
-An OpenSpec workspace is the durable planning home for work that spans multiple repos or folders.
-
-It should feel like this:
-
-```text
-workspace = where related changes live
-link      = a named repo or folder the workspace can plan against
-change    = one feature, fix, project, or other planned piece of work
-```
-
-The foundation intentionally avoids the rest of the workflow. It only defines how OpenSpec recognizes a workspace, where managed workspaces live, how linked paths are represented, and how shared state differs from local state.
-
-A workspace is not a feature. It can hold many changes over time. The linked repos or folders provide planning context, while the code stays where it is.
-
-## Workspace Shape
-
-OpenSpec workspaces use this shape:
-
-```text
-workspace-root/
-  changes/                       # workspace-level proposals, tasks, specs
-  .openspec-workspace/
-    workspace.yaml               # shared workspace information
-    local.yaml                   # this machine's paths and preferences
-```
-
-The user-facing planning surface is `changes/`. The identity file that makes the directory a workspace is `.openspec-workspace/workspace.yaml`.
-
-Repo-local projects keep the existing shape:
-
-```text
-repo-root/
-  openspec/
-    specs/
-    changes/
-```
-
-That distinction lets a user or agent tell which surface they are working in:
-
-```text
-coordination workspace -> shared cross-repo planning
-repo-local project     -> repo-owned specs and implementation planning
-```
-
-Users should not run repo-local `openspec init` inside the workspace root. A workspace is already an OpenSpec coordination surface; it is not a product repo adopting repo-local OpenSpec.
-
-## Workspace Names
-
-A workspace name is a simple folder-style identifier, not a display name.
-
-The name must be usable as a folder name in the current runtime. It must not be empty, must not be `.` or `..`, and must not contain path separators.
-
-OpenSpec should not maintain a cross-platform reserved-name list in this slice. Setup/create flows should let filesystem creation surface OS-specific invalid folder names, then report that failure clearly.
-
-The same workspace name is stored in `.openspec-workspace/workspace.yaml`, used as the default managed workspace folder name, and used as the local registry name.
-
-## Shared And Local State
-
-Workspace state follows a simple sharing rule:
-
-```text
-share stable link names and planning
-keep local checkout paths local
-```
-
-Expected shared state:
-
-```yaml
-version: 1
-name: platform
-links:
-  api: {}
-  web: {}
-```
-
-Expected local state:
-
-```yaml
-version: 1
-paths:
-  api: /repos/api
-  web: /repos/web
-```
-
-Later slices can expand these shapes, but the product rule should stay stable: a shared workspace should not commit one user's absolute checkout paths.
-
-OpenSpec-created workspaces should include an ignore rule for `.openspec-workspace/local.yaml` so local checkout paths are not accidentally shared. `.openspec-workspace/workspace.yaml` remains the portable workspace identity and link-name state.
-
-## Workspace Location
-
-OpenSpec should create managed workspaces in one standard place:
-
-```text
-getGlobalDataDir()/workspaces
-```
-
-That reuses existing OpenSpec data-directory behavior:
-
- `$XDG_DATA_HOME/openspec/workspaces` when `XDG_DATA_HOME` is set
- `~/.local/share/openspec/workspaces` on Unix/macOS fallback
- `%LOCALAPPDATA%\openspec\workspaces` on native Windows fallback
-
-This slice intentionally does not define a workspace-specific environment-variable, command, or configuration override for managed workspace storage. Tests should rely on existing global data-directory controls and test helpers instead of a separate workspace-home override.
-
-This is deliberately quiet. The product should not ask most users where workspaces should live.
-
-OpenSpec should show the resolved workspace path after setup. Quiet defaults should avoid a prompt, not hide where planning files were created.
-
-## Local Workspace Registry
-
-OpenSpec should keep a lightweight local registry of known workspaces:
-
-```text
-getGlobalDataDir()/workspaces/registry.yaml
-```
-
-Expected registry state:
-
-```yaml
-version: 1
-workspaces:
-  platform: /Users/tabish/.local/share/openspec/workspaces/platform
-  checkout: /Users/tabish/.local/share/openspec/workspaces/checkout
-```
-
-The registry is a local index, not the source of truth. It exists so workspace commands can work from anywhere, show a picker when multiple workspaces exist, and list known workspaces without scanning arbitrary folders.
-
-Each workspace folder remains authoritative for its own `.openspec-workspace/workspace.yaml` and `.openspec-workspace/local.yaml`. If a registry entry points at a missing or invalid workspace, later check/list flows can report that and suggest a repair.
-
-## Windows And WSL2
-
-Path behavior is runtime-local:
-
- PowerShell/native Windows uses Windows paths and Windows data-directory fallback.
- WSL2 uses Linux paths and Linux/XDG fallback inside WSL.
- Local repo paths are stored as the user supplied them for the current runtime.
-
-Examples:
-
-```text
-PowerShell:
-  default base -> %LOCALAPPDATA%\openspec\workspaces
-
-WSL2:
-  default base -> ~/.local/share/openspec/workspaces
-```
-
-This slice should not translate between `D:\repo`, `/mnt/d/repo`, and `\\wsl$` paths. Cross-runtime translation can be reconsidered later if an agent-launch workflow requires it.
-
-## Link Names
-
-A link name is the stable way to refer to a repo or folder inside workspace planning.
-
-The local path can vary by machine:
-
-```text
-shared link name: landing
-Tabish path:      /Users/tabish/repos/landing
-Windows path:     D:\repos\landing
-WSL2 path:        /mnt/d/repos/landing
-```
-
-Later workflows should refer to `landing` in workspace planning, status, and apply context. The local path is only how the current machine finds that repo or folder.
-
-Link names are intentionally minimal: they must be non-empty, must not be `.` or `..`, must not contain path separators, and must be unique within the workspace.
-
-The owning repo or folder remains the home of canonical specs and implementation work. The workspace makes the cross-boundary plan legible; it does not take ownership away from the linked repos or folders.
-
-Link names are normally inferred from the folder basename in guided flows. Direct flows can allow an explicit name when the default would conflict or be unclear.
-
-## Linked Repos And Folders
-
-Workspace planning visibility should not require repo-local OpenSpec state.
-
-That matters for two common cases:
-
- a repo has not adopted OpenSpec yet, but still needs to be considered in planning
- a large monorepo has folders such as packages, services, or apps that should be planned like separate areas, without each folder having its own `openspec/`
-
-Foundation should allow the link model to describe both:
-
-```text
-multi-repo:
-  api      -> /repos/api
-  web      -> /repos/web
-
-large monorepo:
-  billing  -> /repos/platform/services/billing
-  checkout -> /repos/platform/apps/checkout
-```
-
-Later apply/verify/archive workflows can decide what extra readiness is needed for implementation. Planning should be able to start before that.
-
-Linking only records the relationship between a workspace link name and a local path. It must not create, copy, move, initialize, or edit files inside the linked repo or folder.
-
-Repo-local spec availability is computed when needed. For example, `repo_specs_path` can be reported by a later doctor command when a linked path contains `openspec/specs`, but that path should not be treated as required workspace state.
-
-## Later Slices
-
-This foundation stops before user-facing workspace workflows:
-
- `workspace-create-and-register-repos` owns setup, link, relink, list, and doctor behavior.
- `workspace-open-agent-context` owns agent launch context.
- `workspace-change-planning` owns workspace proposals and repo scope.
- `workspace-apply-repo-slice` owns implementation of one repo slice.
- `workspace-verify-and-archive` owns completion and archive behavior.
@@ -1,142 +0,0 @@
-## Why
-
-Users need a workspace to feel like the obvious home for planning across multiple repos or folders.
-
-They should be able to think:
-
-```text
-I have repos or folders that are often planned together.
-I create an OpenSpec workspace.
-That workspace is where changes live.
-My code stays where it is.
-OpenSpec links the workspace to those local paths.
-```
-
-A workspace is not a feature. It is the durable planning home. Individual features, fixes, and projects are changes inside the workspace.
-
-Users should not have to choose a storage location, create a change early, or understand internal workspace state before OpenSpec can orient itself.
-
-The POC proved that workspace state is useful. This reimplementation should turn that into a simple product model that users and agents can explain without special-case vocabulary.
-
-## What Changes
-
-This change defines the user-facing foundation for OpenSpec workspaces.
-
-An OpenSpec workspace has a recognizable planning home:
-
-```text
-workspace-root/
-  changes/
-  .openspec-workspace/
-```
-
-`changes/` is where workspace-level planning lives. `.openspec-workspace/` identifies the directory as an OpenSpec workspace and stores workspace state.
-
-OpenSpec-managed workspaces live in one standard location:
-
-```text
-<global-data-dir>/workspaces/
-```
-
-Users should not need to choose that location. OpenSpec still shows the workspace path after setup so users know where planning files live. This foundation slice does not provide a workspace-specific environment-variable or configuration override for managed workspace storage.
-
-OpenSpec also keeps a lightweight local registry of known workspaces on the current machine. The registry powers global commands, pickers, and listing, but each workspace folder remains the source of truth.
-
-Workspace state is split by user expectation:
-
- shared workspace information can move between machines
- local checkout paths stay local to each machine
- linked repos and folders are referred to by stable link names, not by absolute paths
-
-A linked path can be a full repo, a folder inside a monorepo, or another existing folder the workspace should plan against. A linked path does not need repo-local `openspec/` state before it can be included in workspace planning. Repo-local OpenSpec state may still matter later for implementation, verification, or archive workflows, but it is not a prerequisite for planning visibility.
-
-Native Windows/PowerShell and WSL2 are both supported. Each runtime uses its own path conventions. OpenSpec does not translate paths between Windows and WSL in this foundation slice.
-
-## Outcome
-
-After this change, later workspace features can rely on one clear product contract:
-
- OpenSpec can tell when the user is inside a workspace.
- OpenSpec knows where to create managed workspaces by default.
- OpenSpec can keep a local registry of known workspaces.
- A workspace has one visible planning area: `changes/`.
- Workspace state is distinguishable from repo-local `openspec/` state.
- Shared workspace state does not force one user's local paths onto another user.
- Workspace planning can reference existing repos or folders by stable link names.
- Linked repos or folders do not need repo-local OpenSpec state for workspace planning.
- Multi-repo and large-monorepo work can use the same workspace planning model.
- Repo-owned specs and implementation remain owned by their repos or source areas.
- Windows, PowerShell, and WSL2 path behavior is predictable.
-
-This change does not deliver the full workspace workflow. It gives `workspace-create-and-register-repos` the foundation it needs to add the first user-facing commands.
-
-## POC Findings
-
-Behavior to preserve:
-
- A workspace is a durable coordination home for cross-repo planning.
- The workspace has a visible `changes/` directory at its root.
- Linked repos and folders provide the context the workspace can plan against.
- Stable link names matter more than local checkout paths.
- Local machine paths should not become shared workspace state.
- Canonical specs and implementation still belong to the owning repos.
-
-Lessons to carry forward:
-
- The POC's hidden `.openspec/` workspace metadata shape made workspace state too easy to confuse with repo-local OpenSpec state.
- Users should not need to run repo-local `openspec init` inside the workspace root.
- The POC's requirement that registered repos already have `openspec/` is too strict for planning. Repos and folders should be linkable before they adopt repo-local OpenSpec state.
- Repo or folder visibility should not depend on creating a change.
- Workspace setup should not imply repo-local implementation, branch, worktree, apply, verify, or archive behavior.
- `add-repo` is too narrow for the user-facing model. Linking an existing repo or folder is clearer.
-
-## Decisions
-
- Workspace identity directory: `.openspec-workspace/`.
- Workspace identity file: `.openspec-workspace/workspace.yaml`.
- Workspace name: a valid folder name for the current OS, excluding empty names, `.`/`..`, and path separators.
- Workspace name usage: stored in `workspace.yaml`, used as the default managed workspace folder name, and used as the local registry name.
- Planning surface: top-level `changes/`.
- Local machine state: `.openspec-workspace/local.yaml`.
- Local machine state exclusion: OpenSpec-created workspaces exclude `.openspec-workspace/local.yaml` from portable collaboration state by default.
- Local workspace registry: `<global-data-dir>/workspaces/registry.yaml`.
- Default workspace base: `<global-data-dir>/workspaces/`.
- Platform behavior: native Windows and WSL2 each use the path conventions of the runtime running OpenSpec.
- Linked paths may be full repos, monorepo folders, or other existing folders.
- Link names: non-empty stable names, unique within a workspace, excluding `.`/`..` and path separators.
- Repo-local `openspec/` state is not required for workspace planning visibility.
- Linking records the relationship only; it does not create, copy, move, initialize, or edit files in the linked repo or folder.
-
-Planning dependency:
-
- None. This is the first implementation slice.
-
-## Non-Goals
-
- No complete `openspec workspace setup`, `openspec workspace link`, or `openspec workspace relink` flow yet.
- No public `openspec workspace create` command in the first user-facing workspace flow.
- No user-facing command, environment variable, or configuration setting for changing the standard workspace location.
- No question that asks users where OpenSpec should store workspaces by default.
- No automatic Windows-to-WSL or WSL-to-Windows path translation.
- No workspace-open agent launch behavior.
- No workspace-level proposal creation.
- No repo-slice apply, verify, archive, branch, or worktree behavior.
- No copying workspace planning files into linked repos or folders as a side effect of creating, detecting, or linking a workspace.
-
-## Capabilities
-
-### New Capabilities
-
- `workspace-foundation`: Defines the product foundation for OpenSpec workspaces.
-
-### Modified Capabilities
-
- `openspec-conventions`: Describes how coordination workspaces differ from repo-local OpenSpec projects.
-
-## Impact
-
- Workspace recognition and path behavior.
- Workspace state parsing.
- Local workspace registry parsing.
- Documentation and agent guidance for the workspace mental model.
- Later workspace slices should build on this contract instead of redefining workspace storage, identity, registry, or path behavior.
@@ -1,29 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Workspace Product Language
-OpenSpec conventions SHALL describe coordination workspaces in user-facing product terms.
-
-#### Scenario: Describing workspace structure
- **WHEN** OpenSpec documentation describes workspace support
- **THEN** it SHALL present a workspace as the planning home for work across linked repos or folders
- **AND** it SHALL describe `changes/` as the workspace planning area
-
-#### Scenario: Avoiding internal workspace vocabulary
- **WHEN** OpenSpec documentation explains what a workspace includes
- **THEN** it SHALL prefer plain product language such as "repos or folders"
- **AND** it SHALL avoid user-facing reliance on terms such as "working set", "code area", "entry", "alias", or "local overlay"
-
-#### Scenario: Distinguishing workspaces from changes
- **WHEN** OpenSpec documentation explains workspace planning
- **THEN** it SHALL describe a workspace as a durable planning home
- **AND** it SHALL describe individual features, fixes, and projects as changes inside the workspace
-
-#### Scenario: Distinguishing workspace and repo-local surfaces
- **WHEN** OpenSpec documentation compares workspace and repo-local flows
- **THEN** it SHALL explain that workspace planning lives in the workspace root
- **AND** it SHALL explain that repo-local specs and changes continue to live under each repo's `openspec/` directory
-
-#### Scenario: Sequencing the workspace roadmap
- **WHEN** workspace reimplementation work is split across multiple active changes
- **THEN** conventions SHALL allow those changes to remain flat siblings under `openspec/changes/`
- **AND** dependency order MAY be documented in proposal prose until formal change stacking metadata is available
@@ -1,199 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Recognizable Workspace Home
-OpenSpec SHALL give users and agents a recognizable workspace home for cross-repo planning.
-
-#### Scenario: Planning across linked repos or folders
- **WHEN** a user creates an OpenSpec workspace for repos or folders they plan across
- **THEN** the workspace SHALL provide a durable planning home
- **AND** the workspace SHALL be able to hold multiple changes over time
-
-#### Scenario: Working from inside a workspace
- **GIVEN** a user runs OpenSpec from a workspace root or one of its subdirectories
- **WHEN** OpenSpec resolves the current workspace
- **THEN** it SHALL identify the workspace root
- **AND** it SHALL use the workspace root's `changes/` directory as the workspace planning area
-
-#### Scenario: Avoiding accidental workspace mode
- **GIVEN** a directory has `changes/` but is not an OpenSpec workspace
- **WHEN** OpenSpec resolves the current workspace
- **THEN** it SHALL avoid treating that directory as a workspace
- **AND** it SHALL enter workspace mode only when the workspace identity file is present
-
-### Requirement: Stable Workspace Name
-OpenSpec SHALL use one folder-style workspace name across workspace identity, managed storage, and the local registry.
-
-#### Scenario: Using one workspace name
- **WHEN** OpenSpec creates or registers a managed workspace
- **THEN** the workspace name SHALL be stored in `.openspec-workspace/workspace.yaml`
- **AND** the same name SHALL be used as the default managed workspace folder name
- **AND** the same name SHALL be used as the local registry name
-
-#### Scenario: Rejecting invalid folder-style names
- **WHEN** OpenSpec accepts a workspace name
- **THEN** it SHALL reject empty names, `.` or `..`, and names containing path separators
- **AND** setup or create flows SHALL report OS-level folder creation failures clearly
-
-### Requirement: Dedicated Workspace Identity
-OpenSpec SHALL distinguish a coordination workspace from a repo-local OpenSpec project.
-
-#### Scenario: Reading workspace identity
- **WHEN** OpenSpec reads or writes workspace identity and workspace state
- **THEN** it SHALL use `.openspec-workspace/`
-
-#### Scenario: Preserving repo-local OpenSpec projects
- **GIVEN** a repo-local OpenSpec project uses `openspec/`
- **WHEN** that repo is linked to a workspace
- **THEN** OpenSpec SHALL continue treating `openspec/` as that repo's local OpenSpec directory
- **AND** workspace planning SHALL remain anchored in the workspace root
-
-#### Scenario: Avoiding repo-local initialization in the workspace root
- **WHEN** a user is working from an OpenSpec workspace root
- **THEN** OpenSpec SHALL treat that root as a workspace coordination surface
- **AND** users SHALL not need to initialize a repo-local `openspec/` project inside the workspace root
-
-### Requirement: Safe Workspace Sharing
-OpenSpec SHALL keep shared workspace information separate from local machine paths.
-
-#### Scenario: Sharing workspace planning
- **WHEN** a workspace is shared with another user or machine
- **THEN** shared workspace information SHALL include portable workspace identity and stable link names
- **AND** it SHALL not require another user to reuse the original user's absolute checkout paths
-
-#### Scenario: Keeping checkout paths local
- **WHEN** OpenSpec stores local paths for a workspace
- **THEN** those paths SHALL be treated as local to the current machine and runtime
- **AND** another machine MAY map the same link names to different local paths
-
-#### Scenario: Preserving runtime-local paths
- **WHEN** OpenSpec reads or writes local workspace paths
- **THEN** it SHALL preserve path strings valid for the current runtime
- **AND** it SHALL support native Windows paths and WSL2/Linux paths as local state values
-
-#### Scenario: Excluding local state from portable collaboration
- **WHEN** OpenSpec creates a workspace
- **THEN** it SHALL exclude `.openspec-workspace/local.yaml` from portable collaboration state by default
- **AND** `.openspec-workspace/workspace.yaml` SHALL remain the portable workspace identity and link-name state
-
-### Requirement: Standard Workspace Location
-OpenSpec SHALL use a standard location for OpenSpec-managed workspaces without asking most users to choose one.
-
-#### Scenario: Using the standard workspace location
- **WHEN** OpenSpec needs the location for OpenSpec-managed workspaces
- **THEN** it SHALL use `<global-data-dir>/workspaces`
- **AND** `<global-data-dir>` SHALL follow existing OpenSpec XDG and platform data directory behavior
-
-#### Scenario: Avoiding workspace-specific storage overrides
- **WHEN** OpenSpec resolves the location for OpenSpec-managed workspaces
- **THEN** it SHALL not use a workspace-specific environment variable, command, or configuration setting in this slice
- **AND** managed workspace storage SHALL remain under `<global-data-dir>/workspaces`
-
-#### Scenario: Running from native Windows
- **WHEN** OpenSpec runs from native Windows shells such as PowerShell
- **AND** `XDG_DATA_HOME` is not set
- **THEN** OpenSpec SHALL store managed workspaces under the Windows global data location
- **AND** paths SHALL follow native Windows path behavior
-
-#### Scenario: Running from WSL2
- **WHEN** OpenSpec runs from WSL2
- **THEN** OpenSpec SHALL store managed workspaces under the Linux/XDG data location inside WSL
- **AND** paths SHALL follow Linux path behavior inside WSL
-
-#### Scenario: Using the workspace location automatically
- **WHEN** OpenSpec creates or resolves OpenSpec-managed workspaces in later workflows
- **THEN** it SHALL use the resolved workspace location by default
- **AND** users SHALL be able to follow the normal workspace flow without choosing a storage location
-
-#### Scenario: Showing the workspace path
- **WHEN** OpenSpec creates a workspace in the standard workspace location
- **THEN** it SHALL report the workspace path to the user
- **AND** it SHALL not hide where planning files were created
-
-#### Scenario: Staying in the current runtime
- **WHEN** OpenSpec resolves workspace paths or local repo paths
- **THEN** it SHALL interpret paths for the runtime running OpenSpec
- **AND** Windows, UNC WSL, and WSL mount paths SHALL remain explicit user-provided paths
-
-### Requirement: Local Workspace Registry
-OpenSpec SHALL keep a lightweight local registry of known workspaces on the current machine.
-
-#### Scenario: Recording known workspaces
- **WHEN** OpenSpec creates or learns about a managed workspace
- **THEN** it SHALL be able to record the workspace name and path in a local registry
- **AND** the registry SHALL be machine-local state
-
-#### Scenario: Keeping workspace folders authoritative
- **WHEN** OpenSpec reads workspace details
- **THEN** each workspace folder's `.openspec-workspace/workspace.yaml` SHALL remain the source of truth for that workspace
- **AND** the local registry SHALL act only as an index of known workspace paths
-
-#### Scenario: Finding workspaces from anywhere
- **WHEN** a later workspace command runs outside a workspace directory
- **THEN** OpenSpec MAY use the local registry to find known workspaces
- **AND** commands that need one workspace MAY use the registry to support an interactive picker
-
-### Requirement: Stable Link Names
-OpenSpec SHALL use stable link names to refer to repos and folders in workspace planning.
-
-#### Scenario: Referring to a repo or folder in workspace planning
- **WHEN** workspace state or later workspace planning artifacts refer to a linked repo or folder
- **THEN** they SHALL use the stable link name
- **AND** the same link name SHALL remain valid even when local checkout paths differ
-
-#### Scenario: Reusing link names across machines
- **WHEN** a workspace is used on another machine
- **THEN** link names SHALL remain stable
- **AND** local checkout paths MAY differ on that machine
-
-#### Scenario: Rejecting invalid link names
- **WHEN** OpenSpec accepts a workspace link name
- **THEN** it SHALL reject empty names, `.` or `..`, and names containing path separators
- **AND** link names SHALL be unique within the workspace
-
-### Requirement: Linked Repos And Folders
-OpenSpec SHALL allow workspace planning to include linked repos and folders before they have repo-local OpenSpec state.
-
-#### Scenario: Planning with a repo that has not adopted OpenSpec
- **WHEN** a workspace links a repo path that does not yet contain repo-local `openspec/`
- **THEN** the repo SHALL still be available for workspace-level planning
- **AND** implementation readiness MAY be handled by a later workflow
-
-#### Scenario: Planning across monorepo folders
- **WHEN** planning spans multiple packages, services, apps, or directories inside one monorepo
- **THEN** the workspace SHALL be able to link those folders separately
- **AND** each folder SHALL not need its own repo-local `openspec/` directory to participate in workspace planning
-
-#### Scenario: Treating repos and folders consistently
- **WHEN** a workspace plan includes both separate repos and folders inside a monorepo
- **THEN** OpenSpec SHALL use the same planning model for both
- **AND** users SHALL not need to create different kinds of workspace plans for multi-repo and monorepo changes
-
-#### Scenario: Recording links without changing targets
- **WHEN** OpenSpec records a link between a workspace and a local repo or folder
- **THEN** it SHALL store the link in workspace state
- **AND** it SHALL not create, copy, move, initialize, or edit files inside the linked repo or folder
-
-### Requirement: Planning Before Implementation
-OpenSpec SHALL treat workspace creation and detection as planning setup, not implementation.
-
-#### Scenario: Creating or detecting a workspace
- **WHEN** a workspace exists
- **THEN** OpenSpec SHALL treat it as a place for workspace-level planning
- **AND** repo implementation files SHALL remain unchanged until an explicit implementation workflow runs
-
-#### Scenario: Deferring repo implementation
- **WHEN** repo-local implementation, apply, verify, or archive behavior is needed
- **THEN** that behavior SHALL require an explicit later workspace workflow
-
-### Requirement: Repo Ownership Boundaries
-OpenSpec SHALL keep repo ownership legible when planning happens in a workspace.
-
-#### Scenario: Planning across owned repos
- **WHEN** a workspace plan refers to behavior owned by a repo or source area
- **THEN** that owner SHALL remain the home for canonical specs and implementation work
- **AND** the workspace SHALL make the cross-boundary plan visible without taking ownership away from that owner
-
-#### Scenario: Drafting before ownership is clear
- **WHEN** cross-repo behavior is still being explored and ownership is not clear
- **THEN** the workspace MAY hold planning notes or draft behavior
- **AND** those drafts SHALL remain distinguishable from canonical repo-owned specs
@@ -1,56 +0,0 @@
-## 1. POC Findings And Model Decisions
-
- [x] 1.1 Capture the foundation POC findings in the proposal/design artifacts
- [x] 1.2 Settle `.openspec-workspace/` as the workspace metadata directory
- [x] 1.3 Define the minimal workspace root shape and root marker
- [x] 1.4 Define committed workspace state versus machine-local workspace state
- [x] 1.5 Capture that workspace setup is useful only after at least one repo or folder is linked
- [x] 1.6 Capture that repo-owned specs and implementation remain owned by repos
- [x] 1.7 Capture that planning can include repos or monorepo folders without repo-local OpenSpec state
- [x] 1.8 Capture that workspaces hold many changes and are not feature containers
- [x] 1.9 Capture `link`/`relink` as the user-facing model instead of `add-repo`/`update-repo`
-
-## 2. Foundation Helpers
-
- [x] 2.1 Add workspace path constants and helpers for `.openspec-workspace/`, `workspace.yaml`, `local.yaml`, and root `changes/`
- [x] 2.2 Add workspace root detection from an arbitrary starting directory
- [x] 2.3 Add typed parsing and validation for minimal shared workspace state
- [x] 2.4 Add typed parsing and validation for minimal machine-local workspace state
- [x] 2.5 Ensure repo-local `openspec/` projects are not mistaken for coordination workspaces
- [x] 2.6 Add a standard workspace location resolver using `getGlobalDataDir()/workspaces`
- [x] 2.7 Ensure workspace path helpers use platform path APIs and avoid hardcoded POSIX separators
- [x] 2.8 Add local workspace registry path constants and helpers
-
-## 3. Metadata And Local State
-
- [x] 3.1 Define the versioned shared-state shape with workspace name and stable link map
- [x] 3.2 Define the versioned local-state shape with stable link names mapped to local paths
- [x] 3.3 Ensure local-state files are treated as machine-local and OpenSpec-created workspaces exclude `.openspec-workspace/local.yaml` from portable collaboration state
- [x] 3.4 Add validation for invalid versions, invalid link names, malformed link maps, and malformed local path maps
- [x] 3.5 Preserve native Windows and WSL2 path strings when reading and writing local path state
- [x] 3.6 Define the versioned local registry shape with workspace names mapped to workspace roots
- [x] 3.7 Ensure the local registry is treated as a convenience index, not the workspace source of truth
-
-## 4. Documentation And Guidance
-
- [x] 4.1 Document the coordination workspace mental model
- [x] 4.2 Document how `.openspec-workspace/` differs from repo-local `openspec/`
- [x] 4.3 Document stable link names as the way to refer to linked repos and folders
- [x] 4.4 Document which behavior is intentionally deferred to later workspace slices
- [x] 4.5 Document native Windows/PowerShell and WSL2 path behavior for managed workspace storage
- [x] 4.6 Document linked repos/folders without repo-local OpenSpec and large-monorepo planning behavior
- [x] 4.7 Document the local workspace registry and global command model
-
-## 5. Verification
-
- [x] 5.1 Add unit tests for root detection and non-detection cases
- [x] 5.2 Add unit tests for shared-state and local-state parsing
- [x] 5.3 Add unit tests for standard workspace location resolution with XDG/Linux fallback and native Windows fallback
- [x] 5.4 Add unit tests that local-state parsing preserves native Windows and WSL2-style paths
- [x] 5.5 Add unit tests for repo-local compatibility boundaries
- [x] 5.6 Add tests or docs coverage that linked repos/folders do not require repo-local `openspec/`
- [x] 5.7 Add tests or docs coverage for monorepo folder links under the same workspace model
- [x] 5.8 Add tests for local registry parsing and stale registry entries
- [x] 5.9 Add tests or docs coverage for `.openspec-workspace/local.yaml` exclusion in OpenSpec-created workspaces
- [x] 5.10 Run `openspec validate workspace-foundation --strict`
- [x] 5.11 Run targeted test coverage for the new workspace foundation helpers
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-25
@@ -1,48 +0,0 @@
-## Context
-
-The OpenCode adapter in `src/core/command-generation/adapters/opencode.ts` currently generates command files at `.opencode/command/opsx-<id>.md` (singular `command`). OpenCode's official documentation uses `.opencode/commands/` (plural), and every other adapter in the codebase follows the plural convention for commands directories. The legacy cleanup module in `src/core/legacy-cleanup.ts` also references the singular form for detecting old artifacts.
-
-## Goals / Non-Goals
-
-**Goals:**
- Align the OpenCode adapter path with OpenCode's official `.opencode/commands/` convention
- Add the old singular path `.opencode/command/` to legacy cleanup so existing installations are properly cleaned
- Update documentation to reflect the corrected path
- Update test assertions to match the new path
-
-**Non-Goals:**
- Changing the OpenCode skill path (`.opencode/skills/`) — already correct
- Modifying any other adapter's directory structure
- Adding migration prompts or interactive upgrade flows
-
-## Decisions
-
-### 1. Direct path rename in adapter
-
-**Decision:** Change `path.join('.opencode', 'command', ...)` to `path.join('.opencode', 'commands', ...)` in the adapter's `getFilePath` method.
-
-**Rationale:** This is a single-line change that aligns with the established pattern across all other adapters. No abstraction or indirection needed.
-
-**Alternatives considered:**
- Add a configuration option for the directory name — rejected as over-engineering for a bug fix
- Keep singular and add plural as alias — rejected as it creates ambiguity about which is canonical
-
-### 2. Legacy cleanup via existing constant map
-
-**Decision:** Update the `LEGACY_SLASH_COMMAND_PATHS` entry for `'opencode'` from `'.opencode/command/openspec-*.md'` to `'.opencode/command/opsx-*.md'` (the old singular path becomes the legacy pattern) and ensure the new path is handled by the current command generation pipeline.
-
-**Rationale:** The existing legacy cleanup infrastructure uses `LEGACY_SLASH_COMMAND_PATHS` as an explicit lookup. The old singular-path pattern already matches the legacy format (`openspec-*` prefix from the old SlashCommandRegistry era). The current command generation uses the `opsx-*` prefix, so we also need to add a legacy pattern for `opsx-*` files in the old singular directory.
-
-**Alternatives considered:**
- Add a separate migration script — rejected; the existing legacy cleanup mechanism handles this scenario
-
-### 3. Documentation update
-
-**Decision:** Update the `docs/supported-tools.md` table entry for OpenCode from `.opencode/command/opsx-<id>.md` to `.opencode/commands/opsx-<id>.md`.
-
-**Rationale:** Documentation must match the actual generated paths.
-
-## Risks / Trade-offs
-
- **[Existing installations have files at old path]** → Mitigated by legacy cleanup detecting `.opencode/command/` artifacts. On next `openspec init`, old files are cleaned up and new files written to `.opencode/commands/`.
- **[Users referencing old path in custom scripts]** → Low risk. The old path was incorrect per OpenCode's specification, so custom references were already misaligned.
@@ -1,26 +0,0 @@
-## Why
-
-The OpenCode adapter uses `.opencode/command/` (singular) for its commands directory, but OpenCode's official documentation specifies `.opencode/commands/` (plural). Every other adapter in the codebase also uses plural directory names (`.claude/commands/`, `.cursor/commands/`, `.factory/commands/`, etc.). This inconsistency was introduced in Oct 2025 without documented rationale. Fixes [#748](https://github.com/Fission-AI/OpenSpec/issues/748).
-
-## What Changes
-
- OpenCode adapter path changes from `.opencode/command/` to `.opencode/commands/`
- Legacy cleanup adds `.opencode/command/` (old singular path) for backward compatibility
- Documentation updated to reflect the new plural path
-
-## Capabilities
-
-### New Capabilities
-
-_None._
-
-### Modified Capabilities
-
- `command-generation`: OpenCode adapter path changes from singular `command/` to plural `commands/` to match OpenCode's official directory convention
-
-## Impact
-
- `src/core/command-generation/adapters/opencode.ts` — adapter path
- `src/core/legacy-cleanup.ts` — legacy cleanup pattern + add old singular path
- `docs/supported-tools.md` — documentation table
- `test/core/command-generation/adapters.test.ts` — test assertion
@@ -1,63 +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`, `category`, `tags` fields
- **AND** file path SHALL follow pattern `.claude/commands/opsx/<id>.md`
-
-#### Scenario: Cursor adapter formatting
-
- **WHEN** formatting a command for Cursor
- **THEN** the adapter SHALL output YAML frontmatter with `name` as `/opsx-<id>`, `id`, `category`, `description` fields
- **AND** file path SHALL follow pattern `.cursor/commands/opsx-<id>.md`
-
-#### Scenario: Windsurf adapter formatting
-
- **WHEN** formatting a command for Windsurf
- **THEN** the adapter SHALL output YAML frontmatter with `name`, `description`, `category`, `tags` fields
- **AND** file path SHALL follow pattern `.windsurf/workflows/opsx-<id>.md`
-
-#### Scenario: OpenCode adapter formatting
-
- **WHEN** formatting a command for OpenCode
- **THEN** the adapter SHALL output YAML frontmatter with `description` field
- **AND** file path SHALL follow pattern `.opencode/commands/opsx-<id>.md` using `path.join('.opencode', 'commands', ...)` for cross-platform compatibility
- **AND** the adapter SHALL transform colon-based command references (`/opsx:name`) to hyphen-based (`/opsx-name`) in the body
-
-## ADDED Requirements
-
-### Requirement: Legacy cleanup for renamed OpenCode command directory
-
-The legacy cleanup module SHALL detect and remove old OpenCode command files from the previous singular `.opencode/command/` directory path.
-
-#### Scenario: Detect old singular-path OpenCode command files
-
- **WHEN** running legacy artifact detection on a project with files matching `.opencode/command/opsx-*.md` or `.opencode/command/openspec-*.md`
- **THEN** the system SHALL include those files in the legacy slash command files list via `LEGACY_SLASH_COMMAND_PATHS`
- **AND** `LegacySlashCommandPattern.pattern` SHALL accept `string | string[]` to support multiple glob patterns per tool
-
-#### Scenario: Clean up old OpenCode command files on init
-
- **WHEN** a user runs `openspec init` in a project with old `.opencode/command/` artifacts
- **THEN** the system SHALL remove the old files
- **AND** generate new command files at `.opencode/commands/`
-
-#### Scenario: Auto-cleanup legacy artifacts in non-interactive mode
-
- **WHEN** a user runs `openspec init` in non-interactive mode (e.g., CI) and legacy artifacts are detected
- **THEN** the system SHALL auto-cleanup legacy artifacts without requiring `--force`
- **AND** legacy slash command files (100% OpenSpec-managed) SHALL be removed
- **AND** config file cleanup SHALL only remove OpenSpec markers (never delete user files)
@@ -1,19 +0,0 @@
-## 1. Adapter Fix
-
- [x] 1.1 Update `src/core/command-generation/adapters/opencode.ts`: change `path.join('.opencode', 'command', ...)` to `path.join('.opencode', 'commands', ...)` and update the JSDoc comment
-
-## 2. Legacy Cleanup
-
- [x] 2.1 Update `src/core/legacy-cleanup.ts`: update the `'opencode'` entry in `LEGACY_SLASH_COMMAND_PATHS` to detect both `opsx-*.md` and `openspec-*.md` patterns at `.opencode/command/` for backward compatibility
-
-## 3. Documentation
-
- [x] 3.1 Update `docs/supported-tools.md`: change OpenCode command path from `.opencode/command/opsx-<id>.md` to `.opencode/commands/opsx-<id>.md`
-
-## 4. Tests
-
- [x] 4.1 Update `test/core/command-generation/adapters.test.ts`: change the OpenCode file path assertion from `path.join('.opencode', 'command', 'opsx-explore.md')` to `path.join('.opencode', 'commands', 'opsx-explore.md')`
-
-## 5. Changeset
-
- [x] 5.1 Create a changeset file (`.changeset/fix-opencode-commands-directory.md`) with a patch bump describing the path fix
@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-02-25
@@ -1,38 +0,0 @@
-## Context
-
-`statusCommand` in `src/commands/workflow/status.ts` calls `validateChangeExists()` from `shared.ts` as its first operation. When no `--change` option is provided and no change directories exist, `validateChangeExists` throws: `No changes found. Create one with: openspec new change <name>`. This error propagates up as a fatal CLI error (non-zero exit code).
-
-This is correct behavior for commands like `apply` and `show` that require a change to operate on. However, `status` is an informational command — it should report the current state, even when that state is "no changes exist."
-
-The error surfaces during onboarding (issue #714) when AI agents call `openspec status` before any change has been created.
-
-## Goals / Non-Goals
-
-**Goals:**
- Make `openspec status` exit with code 0 and a friendly message when no changes exist
- Support both text and JSON output modes for the no-changes case
- Keep all other commands' validation behavior unchanged
-
-**Non-Goals:**
- Changing the behavior of `validateChangeExists` (keep it strict for all consumers; only extract its internal helper)
- Changing the onboard template or skill instructions
- Handling the case where `--change` is provided but the specific change doesn't exist (this should remain an error)
-
-## Decisions
-
-### Extract `getAvailableChanges` and check before validation
-
-**Rationale**: Extract the private `getAvailableChanges` closure from `validateChangeExists` into a public exported function in `shared.ts`. Then, in `statusCommand`, call `getAvailableChanges` *before* `validateChangeExists` to detect the no-changes case early and handle it gracefully. This avoids using try/catch for control flow and eliminates any coupling to error message strings.
-
-**Alternative considered**: Catching the error from `validateChangeExists` by matching `error.message.startsWith('No changes found')`. Rejected because string coupling is fragile — if the error message changes, the catch silently stops working.
-
-**Alternative considered**: Adding a `throwOnEmpty` parameter to `validateChangeExists`. Rejected because it adds complexity to a shared function for a single consumer's needs and mixes UX concerns into a validation utility.
-
-### Keep `validateChangeExists` strict
-
-**Rationale**: `validateChangeExists` remains unchanged in behavior — it still throws for all error cases. The graceful handling lives entirely in `statusCommand`, which is the appropriate layer for UX decisions. Other commands (`apply`, `show`, `instructions`) are unaffected.
-
-## Risks / Trade-offs
-
- [Risk] Extra filesystem read when no `--change` is provided and changes *do* exist (`getAvailableChanges` is called first, then `validateChangeExists` performs its own read) → Mitigation: `statusCommand` returns early before reaching `validateChangeExists` when no changes exist, so the double-read only occurs when changes are present — minimal overhead.
- [Risk] Other commands may also benefit from graceful no-changes handling in the future → Mitigation: `getAvailableChanges` is now public and reusable, making it easy to apply the same pattern elsewhere.
@@ -1,25 +0,0 @@
-## Why
-
-When `openspec status` is called without `--change` and no changes exist (e.g., during onboarding on a freshly initialized project), the CLI throws a fatal error: `No changes found. Create one with: openspec new change <name>`. This breaks the onboarding flow because AI agents may call `openspec status` before any change has been created, causing the agent to halt or report failure. Fixes [#714](https://github.com/Fission-AI/OpenSpec/issues/714).
-
-## What Changes
-
- `openspec status` will exit gracefully (code 0) with a friendly message when no changes exist, instead of throwing a fatal error
- `openspec status --json` will return a valid JSON object with an empty changes array when no changes exist
- Other commands (`apply`, `show`, etc.) retain their current strict validation behavior
-
-## Capabilities
-
-### New Capabilities
-
- `graceful-status-empty`: Graceful handling of `openspec status` when no changes exist, covering both text and JSON output modes
-
-### Modified Capabilities
-
-_None — `validateChangeExists` was internally refactored to delegate to the newly exported `getAvailableChanges`, but its behavior and public contract are unchanged. Other consumers are unaffected._
-
-## Impact
-
- `src/commands/workflow/shared.ts` — extract `getAvailableChanges` as a public function (validation behavior unchanged)
- `src/commands/workflow/status.ts` — check for available changes before validation, handle empty case gracefully
- Tests for the status command need to cover the new graceful behavior
@@ -1,27 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Status command exits gracefully when no changes exist
-The `statusCommand` function SHALL check for available changes via `getAvailableChanges` before calling `validateChangeExists`. When no `--change` option is provided and no change directories exist, it SHALL print a friendly informational message and exit with code 0, instead of reaching `validateChangeExists` and propagating a fatal error.
-
-#### Scenario: No changes exist, text mode
- **WHEN** user runs `openspec status` without `--change` and no change directories exist under `openspec/changes/`
- **THEN** the CLI prints `No active changes. Create one with: openspec new change <name>` to stdout and exits with code 0
-
-#### Scenario: No changes exist, JSON mode
- **WHEN** user runs `openspec status --json` without `--change` and no change directories exist
- **THEN** the CLI outputs `{"changes":[],"message":"No active changes."}` as valid JSON to stdout and exits with code 0
-
-### Requirement: Existing status validation behavior is preserved
-Other error paths in `validateChangeExists` that apply to the status command SHALL continue to throw errors as before. Commands other than `status` that use `validateChangeExists` SHALL NOT be affected.
-
-#### Scenario: Changes exist but --change not specified
- **WHEN** user runs `openspec status` without `--change` and one or more change directories exist
- **THEN** the CLI throws an error listing available changes with the message `Missing required option --change. Available changes: ...`
-
-#### Scenario: Specified change does not exist
- **WHEN** user runs `openspec status --change non-existent`
- **THEN** the CLI throws an error with message `Change 'non-existent' not found`
-
-#### Scenario: Other commands unaffected
- **WHEN** user runs `openspec show` or `openspec instructions` without `--change` and no changes exist
- **THEN** the CLI throws the original `No changes found` error (no behavior change)
@@ -1,16 +0,0 @@
-## 1. Implementation
-
- [x] 1.1 Extract `getAvailableChanges` in `shared.ts` and use it in `statusCommand` to check for changes before calling `validateChangeExists`
- [x] 1.2 In text mode: print `No active changes. Create one with: openspec new change <name>` and return (exit 0)
- [x] 1.3 In JSON mode: output `{"changes":[],"message":"No active changes."}` and return (exit 0)
-
-## 2. Tests
-
- [x] 2.1 Add test: `openspec status` with no changes exits gracefully with friendly message (text mode)
- [x] 2.2 Add test: `openspec status --json` with no changes returns valid JSON with empty changes array
- [x] 2.3 Verify existing behavior: `openspec status` without `--change` when changes exist still throws missing option error
- [x] 2.4 Verify cross-platform: tests use `path.join()` for any path assertions
-
-## 3. Release
-
- [x] 3.1 Add changeset describing the fix
--- a/Show More
+++ b/Show More