- 🧪 New:Experimental Workflow (OPSX) — schema-driven, hackable, fluid. Iterate on workflows without code changes.
-
+
+The most loved spec framework.
-# OpenSpec
+[](https://github.com/Fission-AI/OpenSpec/stargazers)
+[](https://www.npmjs.com/package/@fission-ai/openspec)
+[](https://github.com/Fission-AI/OpenSpec/graphs/contributors)
-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.**
+
+
+Our philosophy:
-## Why OpenSpec?
+```text
+→ fluid not rigid
+→ iterative not waterfall
+→ easy not complex
+→ built for brownfield not just greenfield
+→ scalable from personal projects to enterprises
+```
-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.
+> [!TIP]
+> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
+>
+> Run `/opsx:onboard` to get started. → [Learn more here](docs/opsx.md)
-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)
+### Teams
-- **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.
+Using OpenSpec in a team? [Email here](mailto:teams@openspec.dev) for access to our Slack channel.
-See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
+
-## How It Works
+## See it in action
+```text
+You: /opsx:new add-dark-mode
+AI: Created openspec/changes/add-dark-mode/
+ Ready to create: proposal
+
+You: /opsx:ff # "fast-forward" - generate all planning docs
+AI: ✓ 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.
```
-┌────────────────────┐
-│ 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
-
-
-Native Slash Commands (click to expand)
-
-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`.
-
-
-AGENTS.md Compatible (click to expand)
+OpenSpec Dashboard
-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 |
+
+
+
-### Install & Initialize
+## Quick Start
-#### Prerequisites
-- **Node.js >= 20.19.0** - Check your version with `node --version`
+**Requires Node.js 20.19.0 or higher.**
-#### Step 1: Install the CLI globally
-
-**Option A: Using npm**
+Install OpenSpec globally:
```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
-```
+Then navigate to your project directory and initialize:
-Run the initialization:
```bash
+cd your-project
openspec init
```
-**What happens during initialization:**
-- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
-- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
-- A new `openspec/` directory structure is created in your project
-
-**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.
+Now tell your AI: `/opsx:new `
-### Create Your First Change
+> [!NOTE]
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing.
+>
+> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
-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.
+## Docs
-#### 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
-```
+→ **[Getting Started](docs/getting-started.md)**: first steps
+→ **[Workflows](docs/workflows.md)**: combos and patterns
+→ **[Commands](docs/commands.md)**: slash commands & skills
+→ **[CLI](docs/cli.md)**: terminal reference
+→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths
+→ **[Concepts](docs/concepts.md)**: how it all fits
+→ **[Multi-Language](docs/multi-language.md)**: multi-language support
+→ **[Customization](docs/customization.md)**: make it yours
-#### 3. Refine the Specs
-Iterate on the specifications until they match your needs:
-```text
-You: Can you add acceptance criteria for the role and team filters?
+## Why OpenSpec?
-AI: I'll update the spec delta with scenarios for role and team filters.
- *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
-```
+AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.
-#### 4. Implement the Change
-Once specs look good, start implementation:
+- **Agree before you build** — human and AI align on specs before code gets written
+- **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
+- **Work fluidly** — update any artifact anytime, no rigid phase gates
+- **Use your tools** — works with 20+ AI assistants via slash commands
-```text
-You: The specs look good. Let's implement this change.
- (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+### How we compare
-AI: I'll work through the tasks in the add-profile-filters change.
- *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
- *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
-```
+**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
-#### 5. Archive the Completed Change
-After implementation is complete, archive the change:
+**vs. [Kiro](https://kiro.dev)** (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.
-```text
-AI: All tasks are complete. The implementation is ready.
+**vs. nothing** — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.
-You: Please archive the change
- (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
+## Updating OpenSpec
-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!
-```
+**Upgrade the package**
-Or run the command yourself in terminal:
```bash
-$ openspec archive add-profile-filters --yes # Archive the completed change without prompts
+npm install -g @fission-ai/openspec@latest
```
-**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".
+**Refresh agent instructions**
-## Command Reference
+Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
```bash
-openspec list # View active change folders
-openspec view # Interactive dashboard of specs and changes
-openspec show # Display change details (proposal, tasks, spec updates)
-openspec validate # Check spec formatting and structure
-openspec archive [--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
+openspec update
```
-**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
+## Usage Notes
-Deltas are "patches" that show how specs change:
+**Model selection**: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.
-- **`## ADDED Requirements`** - New capabilities
-- **`## MODIFIED Requirements`** - Changed behavior (include complete updated text)
-- **`## REMOVED Requirements`** - Deprecated features
+**Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
-**Format requirements:**
-- Use `### Requirement: ` 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.
+## Contributing
-### 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.
+**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
-## Team Adoption
+**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.
-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.
+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.
-Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
+**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").
-## Updating OpenSpec
+### Development
-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.
+- 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`
-## Experimental Features
+## Other
-🧪 OPSX: Fluid, Iterative Workflow (Claude Code only)
-
-**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
- ▲ ▲ ▲ │
- └───────────┴──────────┴────────────────────┘
-```
+Telemetry
-| 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/experimental-workflow.md)
-
-
-
-
-Telemetry – OpenSpec collects anonymous usage stats (opt-out: OPENSPEC_TELEMETRY=0)
+OpenSpec collects anonymous usage stats.
We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
@@ -455,14 +190,6 @@ We collect only command names and version to understand usage patterns. No argum
-## 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`
-
Maintainers & Advisors
@@ -470,6 +197,8 @@ See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and adviso
+
+
## License
MIT
diff --git a/README_OLD.md b/README_OLD.md
new file mode 100644
index 000000000..e0f7f39a8
--- /dev/null
+++ b/README_OLD.md
@@ -0,0 +1,475 @@
+
+ 🧪 New:OPSX Workflow — schema-driven, hackable, fluid. Iterate on workflows without code changes.
+
+
+# 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
+
+
+Native Slash Commands (click to expand)
+
+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`.
+
+
+
+
+AGENTS.md Compatible (click to expand)
+
+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 |
+
+
+
+### 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 # Display change details (proposal, tasks, spec updates)
+openspec validate # Check spec formatting and structure
+openspec archive [--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: ` 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
+
+
+🧪 OPSX: Fluid, Iterative Workflow (Claude Code only)
+
+**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)
+
+
+
+
+Telemetry – OpenSpec collects anonymous usage stats (opt-out: OPENSPEC_TELEMETRY=0)
+
+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`
+
+
+
+## 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`
+
+
+Maintainers & Advisors
+
+See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and advisors who help guide the project.
+
+
+
+## License
+
+MIT
diff --git a/assets/openspec_bg.png b/assets/openspec_bg.png
new file mode 100644
index 000000000..423c2d35a
Binary files /dev/null and b/assets/openspec_bg.png differ
diff --git a/docs/artifact_poc.md b/docs/artifact_poc.md
deleted file mode 100644
index 01dd00985..000000000
--- a/docs/artifact_poc.md
+++ /dev/null
@@ -1,597 +0,0 @@
-# POC-OpenSpec-Core Analysis
-
----
-
-## Design Decisions & Terminology
-
-### Philosophy: Not a Workflow System
-
-This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
-
-| What it's NOT | What it IS |
-|---------------|------------|
-| Linear step-by-step progression | Exploratory, iterative planning |
-| Bureaucratic checkpoints | Enablers that unlock possibilities |
-| "You must complete step 1 first" | "Here's what you could create now" |
-| Form-filling | Fluid document creation |
-
-**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
-
-### Terminology
-
-| Term | Definition | Example |
-|------|------------|---------|
-| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
-| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` |
-| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
-| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
-
-### Hierarchy
-
-```
-Schema (defines) ──→ Artifacts (guided by) ──→ Templates
-```
-
-- **Schema** = the artifact graph (what exists, dependencies)
-- **Artifact** = a document to produce
-- **Template** = instructions for creating that artifact
-
-### Schema Variations
-
-Schemas can vary across multiple dimensions:
-
-| Dimension | Examples |
-|-----------|----------|
-| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
-| Version | `v1`, `v2`, `v3` |
-| Language | `en`, `zh`, `es` |
-| Custom | `team-alpha`, `experimental` |
-
-### Schema Resolution (XDG Standard)
-
-Schemas follow the XDG Base Directory Specification with a 2-level resolution:
-
-```
-1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml # Global user override
-2. /schemas//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//templates/.md # User override
-2. /schemas//templates/.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` 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;
-type SchemaYaml = z.infer;
-```
-
-**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//` with README |
-| Name validation | Enforce kebab-case naming |
-
-**Key Paths:**
-
-```
-openspec/changes// → 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
-
- // 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 ` | Show change progress (artifact graph) | **NEW** |
-| `next --change ` | Show artifacts ready to create | **NEW** |
-| `instructions --change ` | Get enriched instructions for artifact | **NEW** |
-| `list` | List all changes | EXISTS (`openspec change list`) |
-| `new ` | Create change | **NEW** (uses `createChange()`) |
-| `init` | Initialize structure | EXISTS (`openspec init`) |
-| `templates --change ` | 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 ` / `openspec change validate `
-- `openspec list --changes` / `openspec list --specs`
-- `openspec view` (dashboard)
-- `openspec init` / `openspec archive `
-
----
-
-### 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 ` | 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// │ │
-│ │ 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//schema.yaml # User override
- ↓ (not found)
-/schemas//schema.yaml # Built-in
- ↓ (not found)
-Error (schema not found)
-```
-
-### 4. Two-Level Template Fallback
-
-```
-${XDG_DATA_HOME}/openspec/schemas//templates/.md # User override
- ↓ (not found)
-/schemas//templates/.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` 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 ` - Show artifact completion state
-- `next --change ` - Show ready-to-create artifacts
-- `instructions --change ` - Get enriched template
-- `templates --change ` - Show resolved paths
-- `new ` - 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)
-/
-└── 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: /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
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 000000000..7c260c0ea
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,898 @@
+# CLI Reference
+
+The OpenSpec CLI (`openspec`) provides terminal commands for project setup, validation, status inspection, and management. These commands complement the AI slash commands (like `/opsx:new`) documented in [Commands](commands.md).
+
+## Summary
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **Setup** | `init`, `update` | Initialize and update OpenSpec in your project |
+| **Browsing** | `list`, `view`, `show` | Explore changes and specs |
+| **Validation** | `validate` | Check changes and specs for issues |
+| **Lifecycle** | `archive` | Finalize completed changes |
+| **Workflow** | `status`, `instructions`, `templates`, `schemas` | Artifact-driven workflow support |
+| **Schemas** | `schema init`, `schema fork`, `schema validate`, `schema which` | Create and manage custom workflows |
+| **Config** | `config` | View and modify settings |
+| **Utility** | `feedback`, `completion` | Feedback and shell integration |
+
+---
+
+## Human vs Agent Commands
+
+Most CLI commands are designed for **human use** in a terminal. Some commands also support **agent/script use** via JSON output.
+
+### Human-Only Commands
+
+These commands are interactive and designed for terminal use:
+
+| Command | Purpose |
+|---------|---------|
+| `openspec init` | Initialize project (interactive prompts) |
+| `openspec view` | Interactive dashboard |
+| `openspec config edit` | Open config in editor |
+| `openspec feedback` | Submit feedback via GitHub |
+| `openspec completion install` | Install shell completions |
+
+### Agent-Compatible Commands
+
+These commands support `--json` output for programmatic use by AI agents and scripts:
+
+| Command | Human Use | Agent Use |
+|---------|-----------|-----------|
+| `openspec list` | Browse changes/specs | `--json` for structured data |
+| `openspec show ` | Read content | `--json` for parsing |
+| `openspec validate` | Check for issues | `--all --json` for bulk validation |
+| `openspec status` | See artifact progress | `--json` for structured status |
+| `openspec instructions` | Get next steps | `--json` for agent instructions |
+| `openspec templates` | Find template paths | `--json` for path resolution |
+| `openspec schemas` | List available schemas | `--json` for schema discovery |
+
+---
+
+## Global Options
+
+These options work with all commands:
+
+| Option | Description |
+|--------|-------------|
+| `--version`, `-V` | Show version number |
+| `--no-color` | Disable color output |
+| `--help`, `-h` | Display help for command |
+
+---
+
+## Setup Commands
+
+### `openspec init`
+
+Initialize OpenSpec in your project. Creates the folder structure and configures AI tool integrations.
+
+```
+openspec init [path] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `path` | No | Target directory (default: current directory) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--tools ` | Configure AI tools non-interactively. Use `all`, `none`, or comma-separated list |
+| `--force` | Auto-cleanup legacy files without prompting |
+
+**Supported tools:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codex`, `codebuddy`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`, `qwen`, `roocode`, `windsurf`
+
+**Examples:**
+
+```bash
+# Interactive initialization
+openspec init
+
+# Initialize in a specific directory
+openspec init ./my-project
+
+# Non-interactive: configure for Claude and Cursor
+openspec init --tools claude,cursor
+
+# Configure for all supported tools
+openspec init --tools all
+
+# Skip prompts and auto-cleanup legacy files
+openspec init --force
+```
+
+**What it creates:**
+
+```
+openspec/
+├── specs/ # Your specifications (source of truth)
+├── changes/ # Proposed changes
+└── config.yaml # Project configuration
+
+.claude/skills/ # Claude Code skill files (if claude selected)
+.cursor/rules/ # Cursor rules (if cursor selected)
+... (other tool configs)
+```
+
+---
+
+### `openspec update`
+
+Update OpenSpec instruction files after upgrading the CLI. Re-generates AI tool configuration files.
+
+```
+openspec update [path] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `path` | No | Target directory (default: current directory) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Force update even when files are up to date |
+
+**Example:**
+
+```bash
+# Update instruction files after npm upgrade
+npm update @fission-ai/openspec
+openspec update
+```
+
+---
+
+## Browsing Commands
+
+### `openspec list`
+
+List changes or specs in your project.
+
+```
+openspec list [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--specs` | List specs instead of changes |
+| `--changes` | List changes (default) |
+| `--sort ` | Sort by `recent` (default) or `name` |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# List all active changes
+openspec list
+
+# List all specs
+openspec list --specs
+
+# JSON output for scripts
+openspec list --json
+```
+
+**Output (text):**
+
+```
+Active changes:
+ add-dark-mode UI theme switching support
+ fix-login-bug Session timeout handling
+```
+
+---
+
+### `openspec view`
+
+Display an interactive dashboard for exploring specs and changes.
+
+```
+openspec view
+```
+
+Opens a terminal-based interface for navigating your project's specifications and changes.
+
+---
+
+### `openspec show`
+
+Display details of a change or spec.
+
+```
+openspec show [item-name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `item-name` | No | Name of change or spec (prompts if omitted) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--type ` | Specify type: `change` or `spec` (auto-detected if unambiguous) |
+| `--json` | Output as JSON |
+| `--no-interactive` | Disable prompts |
+
+**Change-specific options:**
+
+| Option | Description |
+|--------|-------------|
+| `--deltas-only` | Show only delta specs (JSON mode) |
+
+**Spec-specific options:**
+
+| Option | Description |
+|--------|-------------|
+| `--requirements` | Show only requirements, exclude scenarios (JSON mode) |
+| `--no-scenarios` | Exclude scenario content (JSON mode) |
+| `-r, --requirement ` | Show specific requirement by 1-based index (JSON mode) |
+
+**Examples:**
+
+```bash
+# Interactive selection
+openspec show
+
+# Show a specific change
+openspec show add-dark-mode
+
+# Show a specific spec
+openspec show auth --type spec
+
+# JSON output for parsing
+openspec show add-dark-mode --json
+```
+
+---
+
+## Validation Commands
+
+### `openspec validate`
+
+Validate changes and specs for structural issues.
+
+```
+openspec validate [item-name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `item-name` | No | Specific item to validate (prompts if omitted) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--all` | Validate all changes and specs |
+| `--changes` | Validate all changes |
+| `--specs` | Validate all specs |
+| `--type ` | Specify type when name is ambiguous: `change` or `spec` |
+| `--strict` | Enable strict validation mode |
+| `--json` | Output as JSON |
+| `--concurrency ` | Max parallel validations (default: 6, or `OPENSPEC_CONCURRENCY` env) |
+| `--no-interactive` | Disable prompts |
+
+**Examples:**
+
+```bash
+# Interactive validation
+openspec validate
+
+# Validate a specific change
+openspec validate add-dark-mode
+
+# Validate all changes
+openspec validate --changes
+
+# Validate everything with JSON output (for CI/scripts)
+openspec validate --all --json
+
+# Strict validation with increased parallelism
+openspec validate --all --strict --concurrency 12
+```
+
+**Output (text):**
+
+```
+Validating add-dark-mode...
+ ✓ proposal.md valid
+ ✓ specs/ui/spec.md valid
+ ⚠ design.md: missing "Technical Approach" section
+
+1 warning found
+```
+
+**Output (JSON):**
+
+```json
+{
+ "version": "1.0.0",
+ "results": {
+ "changes": [
+ {
+ "name": "add-dark-mode",
+ "valid": true,
+ "warnings": ["design.md: missing 'Technical Approach' section"]
+ }
+ ]
+ },
+ "summary": {
+ "total": 1,
+ "valid": 1,
+ "invalid": 0
+ }
+}
+```
+
+---
+
+## Lifecycle Commands
+
+### `openspec archive`
+
+Archive a completed change and merge delta specs into main specs.
+
+```
+openspec archive [change-name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `change-name` | No | Change to archive (prompts if omitted) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `-y, --yes` | Skip confirmation prompts |
+| `--skip-specs` | Skip spec updates (for infrastructure/tooling/doc-only changes) |
+| `--no-validate` | Skip validation (requires confirmation) |
+
+**Examples:**
+
+```bash
+# Interactive archive
+openspec archive
+
+# Archive specific change
+openspec archive add-dark-mode
+
+# Archive without prompts (CI/scripts)
+openspec archive add-dark-mode --yes
+
+# Archive a tooling change that doesn't affect specs
+openspec archive update-ci-config --skip-specs
+```
+
+**What it does:**
+
+1. Validates the change (unless `--no-validate`)
+2. Prompts for confirmation (unless `--yes`)
+3. Merges delta specs into `openspec/specs/`
+4. Moves change folder to `openspec/changes/archive/YYYY-MM-DD-/`
+
+---
+
+## Workflow Commands
+
+These commands support the artifact-driven OPSX workflow. They're useful for both humans checking progress and agents determining next steps.
+
+### `openspec status`
+
+Display artifact completion status for a change.
+
+```
+openspec status [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--change ` | Change name (prompts if omitted) |
+| `--schema ` | Schema override (auto-detected from change's config) |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# Interactive status check
+openspec status
+
+# Status for specific change
+openspec status --change add-dark-mode
+
+# JSON for agent use
+openspec status --change add-dark-mode --json
+```
+
+**Output (text):**
+
+```
+Change: add-dark-mode
+Schema: spec-driven
+
+Artifacts:
+ ✓ proposal proposal.md exists
+ ✓ specs specs/ exists
+ ◆ design ready (requires: specs)
+ ○ tasks blocked (requires: design)
+
+Next: Create design using /opsx:continue
+```
+
+**Output (JSON):**
+
+```json
+{
+ "change": "add-dark-mode",
+ "schema": "spec-driven",
+ "artifacts": [
+ {"id": "proposal", "status": "complete", "path": "proposal.md"},
+ {"id": "specs", "status": "complete", "path": "specs/"},
+ {"id": "design", "status": "ready", "requires": ["specs"]},
+ {"id": "tasks", "status": "blocked", "requires": ["design"]}
+ ],
+ "next": "design"
+}
+```
+
+---
+
+### `openspec instructions`
+
+Get enriched instructions for creating an artifact or applying tasks. Used by AI agents to understand what to create next.
+
+```
+openspec instructions [artifact] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `artifact` | No | Artifact ID: `proposal`, `specs`, `design`, `tasks`, or `apply` |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--change ` | Change name (required in non-interactive mode) |
+| `--schema ` | Schema override |
+| `--json` | Output as JSON |
+
+**Special case:** Use `apply` as the artifact to get task implementation instructions.
+
+**Examples:**
+
+```bash
+# Get instructions for next artifact
+openspec instructions --change add-dark-mode
+
+# Get specific artifact instructions
+openspec instructions design --change add-dark-mode
+
+# Get apply/implementation instructions
+openspec instructions apply --change add-dark-mode
+
+# JSON for agent consumption
+openspec instructions design --change add-dark-mode --json
+```
+
+**Output includes:**
+
+- Template content for the artifact
+- Project context from config
+- Content from dependency artifacts
+- Per-artifact rules from config
+
+---
+
+### `openspec templates`
+
+Show resolved template paths for all artifacts in a schema.
+
+```
+openspec templates [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--schema ` | Schema to inspect (default: `spec-driven`) |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# Show template paths for default schema
+openspec templates
+
+# Show templates for custom schema
+openspec templates --schema tdd
+
+# JSON for programmatic use
+openspec templates --json
+```
+
+**Output (text):**
+
+```
+Schema: spec-driven
+
+Templates:
+ proposal → ~/.openspec/schemas/spec-driven/templates/proposal.md
+ specs → ~/.openspec/schemas/spec-driven/templates/specs.md
+ design → ~/.openspec/schemas/spec-driven/templates/design.md
+ tasks → ~/.openspec/schemas/spec-driven/templates/tasks.md
+```
+
+---
+
+### `openspec schemas`
+
+List available workflow schemas with their descriptions and artifact flows.
+
+```
+openspec schemas [options]
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output as JSON |
+
+**Example:**
+
+```bash
+openspec schemas
+```
+
+**Output:**
+
+```
+Available schemas:
+
+ spec-driven (package)
+ The default spec-driven development workflow
+ Flow: proposal → specs → design → tasks
+
+ tdd (package)
+ Test-driven development workflow
+ Flow: spec → tests → implementation → docs
+
+ my-custom (project)
+ Custom workflow for this project
+ Flow: research → proposal → tasks
+```
+
+---
+
+## Schema Commands
+
+Commands for creating and managing custom workflow schemas.
+
+### `openspec schema init`
+
+Create a new project-local schema.
+
+```
+openspec schema init [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | Yes | Schema name (kebab-case) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--description ` | Schema description |
+| `--artifacts ` | Comma-separated artifact IDs (default: `proposal,specs,design,tasks`) |
+| `--default` | Set as project default schema |
+| `--no-default` | Don't prompt to set as default |
+| `--force` | Overwrite existing schema |
+| `--json` | Output as JSON |
+
+**Examples:**
+
+```bash
+# Interactive schema creation
+openspec schema init research-first
+
+# Non-interactive with specific artifacts
+openspec schema init tdd-lite \
+ --description "Lightweight TDD workflow" \
+ --artifacts "spec,tests,implementation" \
+ --default
+```
+
+**What it creates:**
+
+```
+openspec/schemas//
+├── schema.yaml # Schema definition
+└── templates/
+ ├── proposal.md # Template for each artifact
+ ├── specs.md
+ ├── design.md
+ └── tasks.md
+```
+
+---
+
+### `openspec schema fork`
+
+Copy an existing schema to your project for customization.
+
+```
+openspec schema fork [name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `source` | Yes | Schema to copy |
+| `name` | No | New schema name (default: `-custom`) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--force` | Overwrite existing destination |
+| `--json` | Output as JSON |
+
+**Example:**
+
+```bash
+# Fork the built-in spec-driven schema
+openspec schema fork spec-driven my-workflow
+```
+
+---
+
+### `openspec schema validate`
+
+Validate a schema's structure and templates.
+
+```
+openspec schema validate [name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | No | Schema to validate (validates all if omitted) |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--verbose` | Show detailed validation steps |
+| `--json` | Output as JSON |
+
+**Example:**
+
+```bash
+# Validate a specific schema
+openspec schema validate my-workflow
+
+# Validate all schemas
+openspec schema validate
+```
+
+---
+
+### `openspec schema which`
+
+Show where a schema resolves from (useful for debugging precedence).
+
+```
+openspec schema which [name] [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `name` | No | Schema name |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--all` | List all schemas with their sources |
+| `--json` | Output as JSON |
+
+**Example:**
+
+```bash
+# Check where a schema comes from
+openspec schema which spec-driven
+```
+
+**Output:**
+
+```
+spec-driven resolves from: package
+ Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven
+```
+
+**Schema precedence:**
+
+1. Project: `openspec/schemas//`
+2. User: `~/.openspec/schemas//`
+3. Package: Built-in schemas
+
+---
+
+## Configuration Commands
+
+### `openspec config`
+
+View and modify global OpenSpec configuration.
+
+```
+openspec config [options]
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `path` | Show config file location |
+| `list` | Show all current settings |
+| `get ` | Get a specific value |
+| `set ` | Set a value |
+| `unset ` | Remove a key |
+| `reset` | Reset to defaults |
+| `edit` | Open in `$EDITOR` |
+
+**Examples:**
+
+```bash
+# Show config file path
+openspec config path
+
+# List all settings
+openspec config list
+
+# Get a specific value
+openspec config get telemetry.enabled
+
+# Set a value
+openspec config set telemetry.enabled false
+
+# Set a string value explicitly
+openspec config set user.name "My Name" --string
+
+# Remove a custom setting
+openspec config unset user.name
+
+# Reset all configuration
+openspec config reset --all --yes
+
+# Edit config in your editor
+openspec config edit
+```
+
+---
+
+## Utility Commands
+
+### `openspec feedback`
+
+Submit feedback about OpenSpec. Creates a GitHub issue.
+
+```
+openspec feedback [options]
+```
+
+**Arguments:**
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `message` | Yes | Feedback message |
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--body ` | Detailed description |
+
+**Requirements:** GitHub CLI (`gh`) must be installed and authenticated.
+
+**Example:**
+
+```bash
+openspec feedback "Add support for custom artifact types" \
+ --body "I'd like to define my own artifact types beyond the built-in ones."
+```
+
+---
+
+### `openspec completion`
+
+Manage shell completions for the OpenSpec CLI.
+
+```
+openspec completion [shell]
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `generate [shell]` | Output completion script to stdout |
+| `install [shell]` | Install completion for your shell |
+| `uninstall [shell]` | Remove installed completions |
+
+**Supported shells:** `bash`, `zsh`, `fish`, `powershell`
+
+**Examples:**
+
+```bash
+# Install completions (auto-detects shell)
+openspec completion install
+
+# Install for specific shell
+openspec completion install zsh
+
+# Generate script for manual installation
+openspec completion generate bash > ~/.bash_completion.d/openspec
+
+# Uninstall
+openspec completion uninstall
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Error (validation failure, missing files, etc.) |
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENSPEC_CONCURRENCY` | Default concurrency for bulk validation (default: 6) |
+| `EDITOR` or `VISUAL` | Editor for `openspec config edit` |
+| `NO_COLOR` | Disable color output when set |
+
+---
+
+## Related Documentation
+
+- [Commands](commands.md) - AI slash commands (`/opsx:new`, `/opsx:apply`, etc.)
+- [Workflows](workflows.md) - Common patterns and when to use each command
+- [Customization](customization.md) - Create custom schemas and templates
+- [Getting Started](getting-started.md) - First-time setup guide
diff --git a/docs/commands.md b/docs/commands.md
new file mode 100644
index 000000000..1311bdb79
--- /dev/null
+++ b/docs/commands.md
@@ -0,0 +1,662 @@
+# 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
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:explore` | Think through ideas before committing to a change |
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact based on dependencies |
+| `/opsx:ff` | Fast-forward: create all planning artifacts at once |
+| `/opsx:apply` | Implement tasks from the change |
+| `/opsx:verify` | Validate implementation matches artifacts |
+| `/opsx:sync` | Merge delta specs into main specs |
+| `/opsx:archive` | Archive a completed change |
+| `/opsx:bulk-archive` | Archive multiple changes at once |
+| `/opsx:onboard` | Guided tutorial through the complete workflow |
+
+---
+
+## Command Reference
+
+### `/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:new` 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:new 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. Creates the change folder structure and scaffolds it with the selected schema.
+
+**Syntax:**
+```
+/opsx:new [change-name] [--schema ]
+```
+
+**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//` 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//
+└── .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.
+```
+
+**Example with schema:**
+```
+You: /opsx:new write-tests --schema tdd
+
+AI: Created openspec/changes/write-tests/
+ Schema: tdd
+
+ Ready to create: spec
+```
+
+**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-/`
+- 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:new`, `/opsx:apply` |
+| Cursor | `/opsx-new`, `/opsx-apply` |
+| Windsurf | `/opsx-new`, `/opsx-apply` |
+| Copilot | `/opsx-new`, `/opsx-apply` |
+
+The functionality is identical regardless of syntax.
+
+---
+
+## 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 ` 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 `
+
+### 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
diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 000000000..4972ff2b4
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,592 @@
+# Concepts
+
+This guide explains the core ideas behind OpenSpec and how they fit together. For practical usage, see [Getting Started](getting-started.md) and [Workflows](workflows.md).
+
+## Philosophy
+
+OpenSpec is built around four principles:
+
+```
+fluid not rigid — no phase gates, work on what makes sense
+iterative not waterfall — learn as you build, refine as you go
+easy not complex — lightweight setup, minimal ceremony
+brownfield-first — works with existing codebases, not just greenfield
+```
+
+### Why These Principles Matter
+
+**Fluid not rigid.** Traditional spec systems lock you into phases: first you plan, then you implement, then you're done. OpenSpec is more flexible — you can create artifacts in any order that makes sense for your work.
+
+**Iterative not waterfall.** Requirements change. Understanding deepens. What seemed like a good approach at the start might not hold up after you see the codebase. OpenSpec embraces this reality.
+
+**Easy not complex.** Some spec frameworks require extensive setup, rigid formats, or heavyweight processes. OpenSpec stays out of your way. Initialize in seconds, start working immediately, customize only if you need to.
+
+**Brownfield-first.** Most software work isn't building from scratch — it's modifying existing systems. OpenSpec's delta-based approach makes it easy to specify changes to existing behavior, not just describe new systems.
+
+## The Big Picture
+
+OpenSpec organizes your work into two main areas:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ openspec/ │
+│ │
+│ ┌─────────────────────┐ ┌──────────────────────────────┐ │
+│ │ specs/ │ │ changes/ │ │
+│ │ │ │ │ │
+│ │ Source of truth │◄─────│ Proposed modifications │ │
+│ │ How your system │ merge│ Each change = one folder │ │
+│ │ currently works │ │ Contains artifacts + deltas │ │
+│ │ │ │ │ │
+│ └─────────────────────┘ └──────────────────────────────┘ │
+│ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Specs** are the source of truth — they describe how your system currently behaves.
+
+**Changes** are proposed modifications — they live in separate folders until you're ready to merge them.
+
+This separation is key. You can work on multiple changes in parallel without conflicts. You can review a change before it affects the main specs. And when you archive a change, its deltas merge cleanly into the source of truth.
+
+## Specs
+
+Specs describe your system's behavior using structured requirements and scenarios.
+
+### Structure
+
+```
+openspec/specs/
+├── auth/
+│ └── spec.md # Authentication behavior
+├── payments/
+│ └── spec.md # Payment processing
+├── notifications/
+│ └── spec.md # Notification system
+└── ui/
+ └── spec.md # UI behavior and themes
+```
+
+Organize specs by domain — logical groupings that make sense for your system. Common patterns:
+
+- **By feature area**: `auth/`, `payments/`, `search/`
+- **By component**: `api/`, `frontend/`, `workers/`
+- **By bounded context**: `ordering/`, `fulfillment/`, `inventory/`
+
+### Spec Format
+
+A spec contains requirements, and each requirement has scenarios:
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management for the application.
+
+## Requirements
+
+### Requirement: User Authentication
+The system SHALL issue a JWT token upon successful login.
+
+#### Scenario: Valid credentials
+- GIVEN a user with valid credentials
+- WHEN the user submits login form
+- THEN a JWT token is returned
+- AND the user is redirected to dashboard
+
+#### Scenario: Invalid credentials
+- GIVEN invalid credentials
+- WHEN the user submits login form
+- THEN an error message is displayed
+- AND no token is issued
+
+### Requirement: Session Expiration
+The system MUST expire sessions after 30 minutes of inactivity.
+
+#### Scenario: Idle timeout
+- GIVEN an authenticated session
+- WHEN 30 minutes pass without activity
+- THEN the session is invalidated
+- AND the user must re-authenticate
+```
+
+**Key elements:**
+
+| Element | Purpose |
+|---------|---------|
+| `## Purpose` | High-level description of this spec's domain |
+| `### Requirement:` | A specific behavior the system must have |
+| `#### Scenario:` | A concrete example of the requirement in action |
+| SHALL/MUST/SHOULD | RFC 2119 keywords indicating requirement strength |
+
+### Why Structure Specs This Way
+
+**Requirements are the "what"** — they state what the system should do without specifying implementation.
+
+**Scenarios are the "when"** — they provide concrete examples that can be verified. Good scenarios:
+- Are testable (you could write an automated test for them)
+- Cover both happy path and edge cases
+- Use Given/When/Then or similar structured format
+
+**RFC 2119 keywords** (SHALL, MUST, SHOULD, MAY) communicate intent:
+- **MUST/SHALL** — absolute requirement
+- **SHOULD** — recommended, but exceptions exist
+- **MAY** — optional
+
+## 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.
+
+**tdd**
+
+Test-driven development workflow:
+
+```
+spec → tests → implementation → docs
+```
+
+Best for: Teams practicing TDD who write tests 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:new creates a change folder │
+│ │ CHANGE │ │
+│ └───────┬────────┘ │
+│ │ │
+│ ▼ │
+│ ┌────────────────┐ │
+│ │ 2. CREATE │ /opsx:ff or /opsx:continue │
+│ │ 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
diff --git a/docs/customization.md b/docs/customization.md
new file mode 100644
index 000000000..cd64bb7fb
--- /dev/null
+++ b/docs/customization.md
@@ -0,0 +1,184 @@
+# Customization
+
+OpenSpec provides two levels of customization:
+
+1. **Project Config** (`openspec/config.yaml`) - Lightweight per-project customization for default schemas, shared context, and per-artifact rules
+2. **Schema Overrides** - Full schema and template customization via XDG directories
+
+---
+
+## Project Configuration
+
+The `openspec/config.yaml` file provides a lightweight customization layer that lets teams:
+
+- **Set a default schema** - New changes automatically use this schema instead of specifying `--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)
+
+### Creating a Config
+
+You can create the config through the interactive setup:
+
+```bash
+openspec init
+```
+
+Or create it 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 Config Affects Workflows
+
+**Default schema selection:**
+
+```bash
+# Without config: must specify schema
+openspec new change my-feature --schema spec-driven
+
+# With config: schema is automatic
+openspec new change my-feature
+```
+
+**Context and rules injection:**
+
+When generating instructions for an artifact, context and rules are injected:
+
+```xml
+
+Tech stack: TypeScript, React, Node.js, PostgreSQL
+API style: RESTful, documented in docs/api.md
+...
+
+
+
+- Include rollback plan
+- Identify affected teams
+
+
+
+[Schema's built-in template]
+
+```
+
+- **Context** appears in ALL artifacts
+- **Rules** ONLY appear for the matching artifact
+
+### Schema Resolution Precedence
+
+1. CLI flag wins: `openspec new change feature --schema tdd`
+2. Change metadata (if `.openspec.yaml` specifies schema)
+3. Project config (`openspec/config.yaml`)
+4. Default schema (`spec-driven`)
+
+### Error Handling
+
+The config provides graceful error handling:
+
+```bash
+# Typo in schema name - shows suggestions
+# Schema 'spec-drivne' not found
+# Did you mean: spec-driven (built-in)
+
+# Unknown artifact ID in rules - warns but continues
+# ⚠️ Unknown artifact ID in rules: "testplan". Valid IDs for schema "spec-driven": ...
+```
+
+---
+
+## Schema Overrides
+
+For deeper customization, you can override entire schemas or templates.
+
+### How Schema Resolution Works
+
+OpenSpec uses a 2-level schema resolution system following the XDG Base Directory Specification:
+
+1. **User override**: `${XDG_DATA_HOME}/openspec/schemas//`
+2. **Package built-in**: `/schemas//`
+
+When a schema is requested, 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.
+
+### Override Directories
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.local/share/openspec/schemas/` |
+| Windows | `%LOCALAPPDATA%\openspec\schemas\` |
+| All (if set) | `$XDG_DATA_HOME/openspec/schemas/` |
+
+### Manual Schema Override
+
+To override the default `spec-driven` schema:
+
+**1. Create the directory structure:**
+
+```bash
+# macOS/Linux
+mkdir -p ~/.local/share/openspec/schemas/spec-driven/templates
+```
+
+**2. Find and copy the default schema files:**
+
+```bash
+# Find the package location
+npm list -g openspec --parseable
+
+# Copy files from the package's schemas/ directory
+cp /schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
+cp /schemas/spec-driven/templates/*.md ~/.local/share/openspec/schemas/spec-driven/templates/
+```
+
+**3. 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.
+
+### Current Limitations
+
+| Issue | Impact |
+|-------|--------|
+| **Path discovery** | Users must know XDG conventions and platform-specific paths |
+| **Package location** | Finding the npm package path varies by install method |
+| **No scaffolding** | Users must manually create directories and copy files |
+| **No verification** | No way to confirm which schema is actually being resolved |
+| **Full copy required** | Must copy entire schema even to change one template |
+
+### 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 |
diff --git a/docs/experimental-release-plan.md b/docs/experimental-release-plan.md
deleted file mode 100644
index 387b48cff..000000000
--- a/docs/experimental-release-plan.md
+++ /dev/null
@@ -1,926 +0,0 @@
-# OpenSpec Experimental Release Plan
-
-This document outlines the plan to release the experimental artifact workflow system for user testing.
-
-## Overview
-
-The goal is to allow users to test the new artifact-driven workflow system alongside the existing OpenSpec commands. This experimental system (`opsx`) provides a more granular, step-by-step approach to creating change artifacts.
-
-## Three Workflow Modes
-
-### 1. Old Workflow (Current Production)
-- **Commands**: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive`
-- **Behavior**: Hardcoded slash commands that generate all artifacts in one command
-- **Status**: Production, unchanged
-
-### 2. New Artifact System - Batch Mode (Future)
-- **Commands**: Refactored `/openspec:proposal` using schemas
-- **Behavior**: Schema-driven but generates all artifacts at once (like legacy)
-- **Status**: Not in scope for this experimental release
-- **Note**: This is a future refactor to unify the old system with schemas
-
-### 3. New Artifact System - Granular Mode (Experimental)
-- **Commands**: `/opsx:new`, `/opsx:continue`
-- **Behavior**: One artifact at a time, dependency-driven, iterative
-- **Status**: Target for this experimental release
-
----
-
-## Work Items
-
-### 1. Rename AWF to OPSX
-
-**Current State:**
-- Commands: `/awf:start`, `/awf:continue`
-- Files: `.claude/commands/awf/start.md`, `.claude/commands/awf/continue.md`
-
-**Target State:**
-- Commands: `/opsx:new`, `/opsx:continue`
-- Files: `.claude/commands/opsx/new.md`, `.claude/commands/opsx/continue.md`
-
-**Tasks:**
-- [x] Create `.claude/commands/opsx/` directory
-- [x] Rename `start.md` → `new.md` and update content
-- [x] Copy `continue.md` with updated references
-- [x] Update all references from "awf" to "opsx" in command content
-- [x] Update frontmatter (name, description) to use "opsx" naming
-- [x] Remove `.claude/commands/awf/` directory
-
-**CLI Commands:**
-The underlying CLI commands (`openspec status`, `openspec instructions`, etc.) remain unchanged. Only the slash command names change.
-
----
-
-### 2. Remove WF Skill Files
-
-**Current State:**
-- `.claude/commands/wf/start.md` - References non-existent `openspec wf` commands
-- `.claude/commands/wf/continue.md` - References non-existent `openspec wf` commands
-
-**Target State:**
-- Directory and files removed
-
-**Tasks:**
-- [x] Delete `.claude/commands/wf/start.md`
-- [x] Delete `.claude/commands/wf/continue.md`
-- [x] Delete `.claude/commands/wf/` directory
-
----
-
-### 3. Add Agent Skills for Experimental Workflow
-
-**Purpose:**
-Generate experimental workflow skills using the [Agent Skills](https://agentskills.io/specification) open standard.
-
-**Why Skills Instead of Slash Commands:**
-- **Cross-editor compatibility**: Skills work in Claude Code, Cursor, Windsurf, and other compatible editors automatically
-- **Simpler implementation**: Single directory (`.claude/skills/`) instead of 18+ editor-specific configurators
-- **Standard format**: Open standard with simple YAML frontmatter + markdown
-- **User invocation**: Users explicitly invoke skills when they want to use them
-
-**Behavior:**
-1. Create `.claude/skills/` directory if it doesn't exist
-2. Generate two skills using the Agent Skills specification:
- - `openspec-new-change/SKILL.md` - Start a new change with artifact workflow
- - `openspec-continue-change/SKILL.md` - Continue working on a change (create next artifact)
-3. Skills are added **alongside** existing `/openspec:*` commands (not replacing)
-
-**Supported Editors:**
-- Claude Code (native support)
-- Cursor (native support via Settings → Rules → Import Settings)
-- Windsurf (imports `.claude` configs)
-- Cline, Codex, and other Agent Skills-compatible editors
-
-**Tasks:**
-- [x] Create skill template content for `openspec-new-change` (based on current opsx:new)
-- [x] Create skill template content for `openspec-continue-change` (based on current opsx:continue)
-- [x] Add temporary `artifact-experimental-setup` command to CLI
-- [x] Implement skill file generation (YAML frontmatter + markdown body)
-- [x] Add success message with usage instructions
-
-**Note:** The `artifact-experimental-setup` command is temporary and will be merged into `openspec init` once the experimental workflow is promoted to stable.
-
-**Skill Format:**
-Each skill is a directory with a `SKILL.md` file:
-```
-.claude/skills/
-├── openspec-new-change/
-│ └── SKILL.md # name, description, instructions
-├── openspec-continue-change/
-│ └── SKILL.md # name, description, instructions
-└── openspec-apply-change/
- └── SKILL.md # name, description, instructions
-```
-
-**CLI Interface:**
-```bash
-openspec artifact-experimental-setup
-
-# Output:
-# 🧪 Experimental Artifact Workflow Skills Created
-#
-# ✓ .claude/skills/openspec-new-change/SKILL.md
-# ✓ .claude/skills/openspec-continue-change/SKILL.md
-# ✓ .claude/skills/openspec-apply-change/SKILL.md
-#
-# 📖 Usage:
-#
-# Skills work automatically in compatible editors:
-# • Claude Code - Auto-detected, ready to use
-# • Cursor - Enable in Settings → Rules → Import Settings
-# • Windsurf - Auto-imports from .claude directory
-#
-# Ask Claude naturally:
-# • "I want to start a new OpenSpec change to add "
-# • "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 ` 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 (``, ``, ``) 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//spec.md`" but:
-- Agent doesn't know what `` 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
-
-- ``:
-
-### Modified Capabilities
-
-- ``:
-
-## Impact
-
-```
-
-**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 ` 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 "" --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 "" # Check artifact completion
-openspec instructions apply --change "" # 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 "" [--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 `
-- **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
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 000000000..e3912722c
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,273 @@
+# 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. The workflow follows a simple pattern:
+
+```
+┌────────────────────┐
+│ Start a Change │ /opsx:new
+└────────┬───────────┘
+ │
+ ▼
+┌────────────────────┐
+│ Create Artifacts │ /opsx:ff or /opsx:continue
+│ (proposal, specs, │
+│ design, tasks) │
+└────────┬───────────┘
+ │
+ ▼
+┌────────────────────┐
+│ Implement Tasks │ /opsx:apply
+│ (AI writes code) │
+└────────┬───────────┘
+ │
+ ▼
+┌────────────────────┐
+│ Archive & Merge │ /opsx:archive
+│ Specs │
+└────────────────────┘
+```
+
+## What OpenSpec Creates
+
+After running `openspec init`, your project has this structure:
+
+```
+openspec/
+├── specs/ # Source of truth (your system's behavior)
+│ └── /
+│ └── spec.md
+├── changes/ # Proposed updates (one folder per change)
+│ └── /
+│ ├── proposal.md
+│ ├── design.md
+│ ├── tasks.md
+│ └── specs/ # Delta specs (what's changing)
+│ └── /
+│ └── 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
+
+```
+You: /opsx:new add-dark-mode
+
+AI: Created openspec/changes/add-dark-mode/
+ Ready to create: proposal
+```
+
+### 2. Create Artifacts
+
+Use `/opsx:ff` (fast-forward) to create all planning artifacts at once:
+
+```
+You: /opsx:ff
+
+AI: Creating artifacts for add-dark-mode...
+ ✓ proposal.md — why we're doing this, what's changing
+ ✓ specs/ — requirements and scenarios
+ ✓ design.md — technical approach
+ ✓ tasks.md — implementation checklist
+ Ready for implementation!
+```
+
+### 3. 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
+```
+
+### 4. 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.
+
+### 5. 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
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 000000000..78910513c
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,79 @@
+# 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
+
+```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
+```
+
+## 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.
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
new file mode 100644
index 000000000..075261385
--- /dev/null
+++ b/docs/migration-guide.md
@@ -0,0 +1,577 @@
+# 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` | `/opsx:new`, `/opsx:continue`, `/opsx:apply`, and more |
+| **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`
+- 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:
+
+### 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 your skills to the latest version.
+
+### 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
+
+After migration, you have 9 OPSX commands instead of 3:
+
+| Command | Purpose |
+|---------|---------|
+| `/opsx:explore` | Think through ideas with no structure |
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (one at a time) |
+| `/opsx:ff` | Fast-forward—create all planning artifacts at once |
+| `/opsx:apply` | Implement tasks from tasks.md |
+| `/opsx:verify` | Validate implementation matches specs |
+| `/opsx:sync` | Preview spec merge (optional—archive prompts if needed) |
+| `/opsx:archive` | Finalize and archive the change |
+| `/opsx:bulk-archive` | Archive multiple changes at once |
+
+### Command Mapping from Legacy
+
+| Legacy | OPSX Equivalent |
+|--------|-----------------|
+| `/openspec:proposal` | `/opsx:new` then `/opsx:ff` |
+| `/openspec:apply` | `/opsx:apply` |
+| `/openspec:archive` | `/opsx:archive` |
+
+### New Capabilities
+
+**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 tdd` (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 |
+| `tdd` | spec → tests → implementation → docs | Test-first development |
+
+List all available schemas:
+
+```bash
+openspec workflow 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`
+- **tdd**: `spec`, `tests`, `implementation`, `docs`
+
+Run this to see valid artifact IDs:
+
+```bash
+openspec workflow 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-explore/
+│ ├── openspec-new-change/
+│ └── ...
+├── 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
+
+```
+/opsx:new Start a change
+/opsx:continue Create next artifact
+/opsx:ff Create all planning artifacts
+/opsx:apply Implement tasks
+/opsx:archive Finish and archive
+```
+
+---
+
+## 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
diff --git a/docs/multi-language.md b/docs/multi-language.md
new file mode 100644
index 000000000..0dfb91a9a
--- /dev/null
+++ b/docs/multi-language.md
@@ -0,0 +1,115 @@
+# Multi-Language Guide
+
+Configure OpenSpec to generate artifacts in languages other than English.
+
+## Quick Setup
+
+Add a language instruction to your `openspec/config.yaml`:
+
+```yaml
+schema: spec-driven
+
+context: |
+ Language: Portuguese (pt-BR)
+ All artifacts must be written in Brazilian Portuguese.
+
+ # Your other project context below...
+ Tech stack: TypeScript, React, Node.js
+```
+
+That's it. All generated artifacts will now be in Portuguese.
+
+## Language Examples
+
+### Portuguese (Brazil)
+
+```yaml
+context: |
+ Language: Portuguese (pt-BR)
+ All artifacts must be written in Brazilian Portuguese.
+```
+
+### Spanish
+
+```yaml
+context: |
+ Idioma: Español
+ Todos los artefactos deben escribirse en español.
+```
+
+### Chinese (Simplified)
+
+```yaml
+context: |
+ 语言：中文（简体）
+ 所有产出物必须用简体中文撰写。
+```
+
+### Japanese
+
+```yaml
+context: |
+ 言語：日本語
+ すべての成果物は日本語で作成してください。
+```
+
+### French
+
+```yaml
+context: |
+ Langue : Français
+ Tous les artefacts doivent être rédigés en français.
+```
+
+### German
+
+```yaml
+context: |
+ Sprache: Deutsch
+ Alle Artefakte müssen auf Deutsch verfasst werden.
+```
+
+## Tips
+
+### Handle Technical Terms
+
+Decide how to handle technical terminology:
+
+```yaml
+context: |
+ Language: Japanese
+ Write in Japanese, but:
+ - Keep technical terms like "API", "REST", "GraphQL" in English
+ - Code examples and file paths remain in English
+```
+
+### Combine with Other Context
+
+Language settings work alongside your other project context:
+
+```yaml
+schema: spec-driven
+
+context: |
+ Language: Portuguese (pt-BR)
+ All artifacts must be written in Brazilian Portuguese.
+
+ Tech stack: TypeScript, React 18, Node.js 20
+ Database: PostgreSQL with Prisma ORM
+```
+
+## Verification
+
+To verify your language config is working:
+
+```bash
+# Check the instructions - should show your language context
+openspec instructions proposal --change my-change
+
+# Output will include your language context
+```
+
+## Related Documentation
+
+- [Customization Guide](./customization.md) - Project configuration options
+- [Workflows Guide](./workflows.md) - Full workflow documentation
diff --git a/docs/experimental-workflow.md b/docs/opsx.md
similarity index 95%
rename from docs/experimental-workflow.md
rename to docs/opsx.md
index 96d9993c3..10aaaca9e 100644
--- a/docs/experimental-workflow.md
+++ b/docs/opsx.md
@@ -1,8 +1,6 @@
-# Experimental Workflow (OPSX)
+# OPSX Workflow
-> **Status:** Experimental. Things might break. Feedback welcome on [Discord](https://discord.gg/YctCnvvshC).
->
-> **Compatibility:** Claude Code only (for now)
+> **Compatibility:** Claude Code only (for now). Feedback welcome on [Discord](https://discord.gg/YctCnvvshC).
## What Is It?
@@ -51,19 +49,9 @@ 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
@@ -179,7 +167,7 @@ rules:
| `/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:sync` | Sync delta specs to main (optional—archive prompts if needed) |
| `/opsx:archive` | Archive when done |
## Usage
@@ -211,17 +199,16 @@ Creates all planning artifacts at once. Use when you have a clear picture of wha
```
/opsx:apply
```
-Works through tasks, checking them off as you go. **Key difference:** if you discover issues during implementation, you can update your specs, design, or tasks — then continue. No phase gates. If you're juggling multiple changes, you can run `/opsx:apply `; 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. If you're juggling multiple changes, you can run `/opsx:apply `; otherwise it should infer from the conversation and prompt you to choose if it can't tell.
### Finish up
```
-/opsx:sync # Update main specs with your delta specs
-/opsx:archive # Move to archive when done
+/opsx:archive # Move to archive when done (prompts to sync specs if needed)
```
## When to Update vs. Start Fresh
-OPSX lets you update artifacts anytime. But when does "update as you learn" become "this is different work"?
+You can always edit your proposal or specs before implementation. But when does refining become "this is different work"?
### What a Proposal Captures
@@ -351,9 +338,9 @@ This section explains how OPSX works under the hood and how it compares to the s
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
-│ │ new ◄──► continue ◄──► apply ◄──► sync │ │
-│ │ │ │ │ │ │ │
-│ │ └──────────┴───────────┴──────────┘ │ │
+│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
+│ │ │ │ │ │ │ │
+│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
diff --git a/docs/project-config-demo.md b/docs/project-config-demo.md
deleted file mode 100644
index 7a37cd4e8..000000000
--- a/docs/project-config-demo.md
+++ /dev/null
@@ -1,205 +0,0 @@
-# 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
-
-Tech stack: TypeScript, React, Node.js, PostgreSQL
-API style: RESTful, documented in docs/api.md
-...
-
-
-
-- Include rollback plan
-- Identify affected teams and notify in #platform-changes
-
-
-
-[Schema's built-in proposal 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
diff --git a/docs/schema-customization.md b/docs/schema-customization.md
deleted file mode 100644
index d4cc3f253..000000000
--- a/docs/schema-customization.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# Schema Customization
-
-This document describes how users can customize OpenSpec schemas and templates, the current manual process, and the gap that needs to be addressed.
-
----
-
-## Overview
-
-OpenSpec uses a 2-level schema resolution system following the XDG Base Directory Specification:
-
-1. **User override**: `${XDG_DATA_HOME}/openspec/schemas//`
-2. **Package built-in**: `/schemas//`
-
-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 /schemas/spec-driven/schema.yaml ~/.local/share/openspec/schemas/spec-driven/
-cp /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 ` — debug resolution
-3. `openspec schema copy ` — scaffold customization
-4. `openspec schema diff ` — compare with built-in
-5. `openspec schema reset ` — 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 |
diff --git a/docs/schema-workflow-gaps.md b/docs/schema-workflow-gaps.md
deleted file mode 100644
index 27d76b1f4..000000000
--- a/docs/schema-workflow-gaps.md
+++ /dev/null
@@ -1,379 +0,0 @@
-# Schema Workflow: End-to-End Analysis
-
-This document analyzes the complete user journey for working with schemas in OpenSpec, identifies gaps, and proposes a phased solution.
-
----
-
-## Current State
-
-### What Exists
-
-| Component | Status |
-|-----------|--------|
-| Schema resolution | 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 ` — 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 /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// # Project-local
-2. ~/.local/share/openspec/schemas// # User global (XDG)
-3. /schemas// # 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 [new-name]` creates in project by default
-- Teams can commit `openspec/schemas/` to repo
-
-**Resolution order:**
-```
-1. ./openspec/schemas// # Project-local
-2. ~/.local/share/openspec/schemas// # User global
-3. /schemas// # 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 [name] # Copy existing schema for customization
-openspec schema init # 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 |
diff --git a/docs/supported-tools.md b/docs/supported-tools.md
new file mode 100644
index 000000000..df178c5ff
--- /dev/null
+++ b/docs/supported-tools.md
@@ -0,0 +1,84 @@
+# Supported Tools
+
+OpenSpec works with 20+ AI coding assistants. When you run `openspec init`, you'll be prompted to select which tools you use, and OpenSpec will configure the appropriate integrations.
+
+## How It Works
+
+For each tool you select, OpenSpec installs:
+
+1. **Skills** — Reusable instruction files that power the `/opsx:*` workflow commands
+2. **Commands** — Tool-specific slash command bindings
+
+## Tool Directory Reference
+
+| Tool | Skills Location | Commands Location |
+|------|-----------------|-------------------|
+| Amazon Q Developer | `.amazonq/skills/` | `.amazonq/prompts/` |
+| Antigravity | `.agent/skills/` | `.agent/workflows/` |
+| Auggie (Augment CLI) | `.augment/skills/` | `.augment/commands/` |
+| Claude Code | `.claude/skills/` | `.claude/commands/opsx/` |
+| Cline | `.cline/skills/` | `.clinerules/workflows/` |
+| CodeBuddy | `.codebuddy/skills/` | `.codebuddy/commands/opsx/` |
+| Codex | `.codex/skills/` | `.codex/prompts/` |
+| Continue | `.continue/skills/` | `.continue/prompts/` |
+| CoStrict | `.cospec/skills/` | `.cospec/openspec/commands/` |
+| Crush | `.crush/skills/` | `.crush/commands/opsx/` |
+| Cursor | `.cursor/skills/` | `.cursor/commands/` |
+| Factory Droid | `.factory/skills/` | `.factory/commands/` |
+| Gemini CLI | `.gemini/skills/` | `.gemini/commands/opsx/` |
+| GitHub Copilot | `.github/skills/` | `.github/prompts/` |
+| iFlow | `.iflow/skills/` | `.iflow/commands/` |
+| Kilo Code | `.kilocode/skills/` | `.kilocode/workflows/` |
+| OpenCode | `.opencode/skills/` | `.opencode/command/` |
+| Qoder | `.qoder/skills/` | `.qoder/commands/opsx/` |
+| Qwen Code | `.qwen/skills/` | `.qwen/commands/` |
+| RooCode | `.roo/skills/` | `.roo/commands/` |
+| Windsurf | `.windsurf/skills/` | `.windsurf/commands/opsx/` |
+
+## Non-Interactive Setup
+
+For CI/CD or scripted setup, use the `--tools` flag:
+
+```bash
+# Configure specific tools
+openspec init --tools claude,cursor
+
+# Configure all supported tools
+openspec init --tools all
+
+# Skip tool configuration
+openspec init --tools none
+```
+
+**Available tool IDs:** `amazon-q`, `antigravity`, `auggie`, `claude`, `cline`, `codebuddy`, `codex`, `continue`, `costrict`, `crush`, `cursor`, `factory`, `gemini`, `github-copilot`, `iflow`, `kilocode`, `opencode`, `qoder`, `qwen`, `roocode`, `windsurf`
+
+## What Gets Installed
+
+For each tool, OpenSpec generates 10 skill files that power the OPSX workflow:
+
+| Skill | Purpose |
+|-------|---------|
+| `openspec-explore` | Thinking partner for exploring ideas |
+| `openspec-new-change` | Start a new change |
+| `openspec-continue-change` | Create the next artifact |
+| `openspec-ff-change` | Fast-forward through all planning artifacts |
+| `openspec-apply-change` | Implement tasks |
+| `openspec-verify-change` | Verify implementation completeness |
+| `openspec-sync-specs` | Sync delta specs to main (optional—archive prompts if needed) |
+| `openspec-archive-change` | Archive a completed change |
+| `openspec-bulk-archive-change` | Archive multiple changes at once |
+| `openspec-onboard` | Guided onboarding through a complete workflow cycle |
+
+These skills are invoked via slash commands like `/opsx:new`, `/opsx:apply`, etc. See [Commands](commands.md) for the full list.
+
+## Adding a New Tool
+
+Want to add support for another AI coding assistant? Check out the [command adapter pattern](../CONTRIBUTING.md) or open an issue on GitHub.
+
+---
+
+## Related
+
+- [CLI Reference](cli.md) — Terminal commands
+- [Commands](commands.md) — Slash commands and skills
+- [Getting Started](getting-started.md) — First-time setup
diff --git a/docs/workflows.md b/docs/workflows.md
new file mode 100644
index 000000000..8aac9df12
--- /dev/null
+++ b/docs/workflows.md
@@ -0,0 +1,425 @@
+# Workflows
+
+This guide covers common workflow patterns for OpenSpec and when to use each one. For basic setup, see [Getting Started](getting-started.md). For command reference, see [Commands](commands.md).
+
+## Philosophy: Actions, Not Phases
+
+Traditional workflows force you through phases: planning, then implementation, then done. But real work doesn't fit neatly into boxes.
+
+OPSX takes a different approach:
+
+```text
+Traditional (phase-locked):
+
+ PLANNING ────────► IMPLEMENTING ────────► DONE
+ │ │
+ │ "Can't go back" │
+ └────────────────────┘
+
+OPSX (fluid actions):
+
+ proposal ──► specs ──► design ──► tasks ──► implement
+```
+
+**Key principles:**
+
+- **Actions, not phases** - Commands are things you can do, not stages you're stuck in
+- **Dependencies are enablers** - They show what's possible, not what's required next
+
+> **Customization:** OPSX workflows are driven by schemas that define artifact sequences. See [Customization](customization.md) for details on creating custom schemas.
+
+## Workflow Patterns
+
+### 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:explore` | Think through ideas | Unclear requirements, investigation |
+| `/opsx:new` | Start a change | Beginning any new work |
+| `/opsx:continue` | Create next artifact | Step-by-step artifact creation |
+| `/opsx:ff` | Create all planning artifacts | Clear scope, ready to build |
+| `/opsx:apply` | Implement tasks | Ready to write code |
+| `/opsx:verify` | Validate implementation | Before archiving, catch mismatches |
+| `/opsx:sync` | Merge delta specs | Optional—archive prompts if needed |
+| `/opsx:archive` | Complete the change | All work finished |
+| `/opsx:bulk-archive` | Archive multiple changes | Parallel work, batch completion |
+
+## 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
diff --git a/openspec/changes/add-artifact-regeneration-support/proposal.md b/openspec/changes/add-artifact-regeneration-support/proposal.md
new file mode 100644
index 000000000..d855cdc97
--- /dev/null
+++ b/openspec/changes/add-artifact-regeneration-support/proposal.md
@@ -0,0 +1,136 @@
+# Add Artifact Regeneration Support
+
+## Problem
+
+Currently, there is **no way to regenerate artifacts** in the OPSX workflow:
+
+- `/opsx:apply` just reads whatever's on disk
+- `/opsx:continue` only creates the NEXT artifact - won't touch existing ones
+
+If you edit `design.md` after `tasks.md` exists, your only options are:
+1. Delete tasks.md manually, then run `/opsx:continue`
+2. Edit tasks.md manually
+
+The documentation claims you can "update artifacts mid-flight and continue" but there's no mechanism that actually supports this.
+
+## Proposed Solution
+
+Two parts:
+
+### Part 1: Staleness Detection
+Add artifact staleness detection to `/opsx:apply`:
+
+1. **Track modification times**: When generating an artifact, record the mtime of its dependencies
+2. **Detect staleness**: When `/opsx:apply` runs, check if upstream artifacts (design.md, specs) have been modified since tasks.md was generated
+3. **Prompt user**: If stale, ask: "Design was modified after tasks were generated. Would you like to regenerate tasks with `/opsx:continue`?"
+
+## User Experience
+
+### Vision: Seamless Mid-Flight Correction
+
+This is the workflow we want to enable (currently documented but not supported):
+
+```
+You: /opsx:apply
+
+AI: Working through tasks...
+ ✓ Task 1.1: Created caching layer
+ ✓ Task 1.2: Added cache invalidation
+
+ Working on 1.3: Implement TTL...
+ I noticed the design assumes Redis, but your project uses
+ in-memory caching. Should I update the design?
+
+You: Yes, update it to use the existing cache module.
+
+AI: Updated design.md to use CacheManager from src/cache/
+ Updated tasks.md with revised implementation steps
+ Continuing implementation...
+ ✓ Task 1.3: Implemented TTL using CacheManager
+ ...
+```
+
+**No restart needed.** Just update the artifact and continue.
+
+### Staleness Warning UX
+
+When user manually edits an upstream artifact:
+
+```
+$ /opsx:apply
+
+⚠️ Detected changes to upstream artifacts:
+ - design.md modified 5 minutes ago (after tasks.md was generated)
+
+Options:
+1. Regenerate tasks (recommended)
+2. Continue anyway with current tasks
+3. Cancel
+
+>
+```
+
+### Part 2: Regeneration Capability
+
+Add a way to regenerate specific artifacts:
+
+```bash
+# Option A: Flag on continue
+/opsx:continue --regenerate tasks
+
+# Option B: Separate command
+/opsx:regenerate tasks
+
+# Option C: Interactive prompt when staleness detected
+/opsx:apply
+# "Design changed. Regenerate tasks? [y/N]"
+```
+
+## Technical Approach
+
+### Option A: Metadata File
+Store `.openspec-meta.json` in change directory:
+```json
+{
+ "tasks.md": {
+ "generated_at": "2025-01-24T10:00:00Z",
+ "dependencies": {
+ "design.md": "2025-01-24T09:55:00Z",
+ "specs/feature/spec.md": "2025-01-24T09:50:00Z"
+ }
+ }
+}
+```
+
+### Option B: Frontmatter
+Add YAML frontmatter to generated artifacts:
+```markdown
+---
+generated_at: 2025-01-24T10:00:00Z
+depends_on:
+ - design.md@2025-01-24T09:55:00Z
+---
+# Tasks
+...
+```
+
+### Option C: Git-based
+Use git to detect if upstream files changed since downstream was last modified. No extra metadata needed but requires git.
+
+## Non-Goals
+
+- Automatic regeneration (user should always choose)
+- Blocking apply entirely (just warn)
+- Tracking code file changes (only artifact dependencies)
+
+## Dependencies
+
+- Should be implemented after `fix-midflight-update-docs` so docs are accurate first
+- Could be combined with that change if desired
+
+## Success Criteria
+
+- User is warned when applying with stale artifacts
+- Clear path to regenerate if needed
+- No false positives (only warn when genuinely stale)
+- Documentation claims become actually true
diff --git a/openspec/changes/add-opsx-onboard-skill/.openspec.yaml b/openspec/changes/add-opsx-onboard-skill/.openspec.yaml
new file mode 100644
index 000000000..a5a6fec48
--- /dev/null
+++ b/openspec/changes/add-opsx-onboard-skill/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-01-24
diff --git a/openspec/changes/add-opsx-onboard-skill/design.md b/openspec/changes/add-opsx-onboard-skill/design.md
new file mode 100644
index 000000000..505f94e9c
--- /dev/null
+++ b/openspec/changes/add-opsx-onboard-skill/design.md
@@ -0,0 +1,115 @@
+## 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.
diff --git a/openspec/changes/add-opsx-onboard-skill/proposal.md b/openspec/changes/add-opsx-onboard-skill/proposal.md
new file mode 100644
index 000000000..b280cc2de
--- /dev/null
+++ b/openspec/changes/add-opsx-onboard-skill/proposal.md
@@ -0,0 +1,27 @@
+## 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
+
+
+## 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
diff --git a/openspec/changes/add-opsx-onboard-skill/specs/opsx-onboard-skill/spec.md b/openspec/changes/add-opsx-onboard-skill/specs/opsx-onboard-skill/spec.md
new file mode 100644
index 000000000..ffb44743c
--- /dev/null
+++ b/openspec/changes/add-opsx-onboard-skill/specs/opsx-onboard-skill/spec.md
@@ -0,0 +1,162 @@
+## 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 ""` 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 `
+- **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`
diff --git a/openspec/changes/add-opsx-onboard-skill/tasks.md b/openspec/changes/add-opsx-onboard-skill/tasks.md
new file mode 100644
index 000000000..7671b3291
--- /dev/null
+++ b/openspec/changes/add-opsx-onboard-skill/tasks.md
@@ -0,0 +1,21 @@
+## 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
diff --git a/src/core/shared/skill-generation.ts b/src/core/shared/skill-generation.ts
index c0119dc97..db7c6fe3c 100644
--- a/src/core/shared/skill-generation.ts
+++ b/src/core/shared/skill-generation.ts
@@ -14,6 +14,7 @@ import {
getArchiveChangeSkillTemplate,
getBulkArchiveChangeSkillTemplate,
getVerifyChangeSkillTemplate,
+ getOnboardSkillTemplate,
getOpsxExploreCommandTemplate,
getOpsxNewCommandTemplate,
getOpsxContinueCommandTemplate,
@@ -23,6 +24,7 @@ import {
getOpsxArchiveCommandTemplate,
getOpsxBulkArchiveCommandTemplate,
getOpsxVerifyCommandTemplate,
+ getOpsxOnboardCommandTemplate,
type SkillTemplate,
} from '../templates/skill-templates.js';
import type { CommandContent } from '../command-generation/index.js';
@@ -57,6 +59,7 @@ export function getSkillTemplates(): SkillTemplateEntry[] {
{ template: getArchiveChangeSkillTemplate(), dirName: 'openspec-archive-change' },
{ template: getBulkArchiveChangeSkillTemplate(), dirName: 'openspec-bulk-archive-change' },
{ template: getVerifyChangeSkillTemplate(), dirName: 'openspec-verify-change' },
+ { template: getOnboardSkillTemplate(), dirName: 'openspec-onboard' },
];
}
@@ -74,6 +77,7 @@ export function getCommandTemplates(): CommandTemplateEntry[] {
{ template: getOpsxArchiveCommandTemplate(), id: 'archive' },
{ template: getOpsxBulkArchiveCommandTemplate(), id: 'bulk-archive' },
{ template: getOpsxVerifyCommandTemplate(), id: 'verify' },
+ { template: getOpsxOnboardCommandTemplate(), id: 'onboard' },
];
}
diff --git a/src/core/templates/skill-templates.ts b/src/core/templates/skill-templates.ts
index 811cdd3ab..8bae07359 100644
--- a/src/core/templates/skill-templates.ts
+++ b/src/core/templates/skill-templates.ts
@@ -920,6 +920,545 @@ Main specs are now updated. The change remains active - archive when implementat
};
}
+/**
+ * Template for openspec-onboard skill
+ * Guided onboarding through the complete OpenSpec workflow
+ */
+export function getOnboardSkillTemplate(): SkillTemplate {
+ return {
+ name: 'openspec-onboard',
+ description: 'Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.',
+ instructions: getOnboardInstructions(),
+ license: 'MIT',
+ compatibility: 'Requires openspec CLI.',
+ metadata: { author: 'openspec', version: '1.0' },
+ };
+}
+
+/**
+ * Shared onboarding instructions used by both skill and command templates.
+ */
+function getOnboardInstructions(): string {
+ return `Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if OpenSpec is initialized:
+
+\`\`\`bash
+openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+\`\`\`
+
+**If not initialized:**
+> OpenSpec isn't set up in this project yet. Run \`openspec init\` first, then come back to \`/opsx:onboard\`.
+
+Stop here if not initialized.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+\`\`\`
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+\`\`\`
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for \`TODO\`, \`FIXME\`, \`HACK\`, \`XXX\` in code files
+2. **Missing error handling** - \`catch\` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference \`src/\` with test directories
+4. **Type issues** - \`any\` types in TypeScript files (\`: any\`, \`as any\`)
+5. **Debug artifacts** - \`console.log\`, \`console.debug\`, \`debugger\` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+\`\`\`bash
+git log --oneline -10 2>/dev/null || echo "No git history"
+\`\`\`
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+\`\`\`
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+ Location: \`src/path/to/file.ts:42\`
+ Scope: ~1-2 files, ~20-30 lines
+ Why it's good: [brief reason]
+
+**2. [Second task]**
+ Location: \`src/another/file.ts\`
+ Scope: ~1 file, ~15 lines
+ Why it's good: [brief reason]
+
+**3. [Third task]**
+ Location: [location]
+ Scope: [estimate]
+ Why it's good: [brief reason]
+
+**4. Something else?**
+ Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+\`\`\`
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+\`\`\`
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+\`\`\`
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+\`\`\`
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+\`\`\`
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+\`\`\`
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│ [Optional: ASCII diagram if helpful] │
+└─────────────────────────────────────────┘
+
+Explore mode (\`/opsx:explore\`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+\`\`\`
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+\`\`\`
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in \`openspec/changes//\` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+\`\`\`
+
+**DO:** Create the change with a derived kebab-case name:
+\`\`\`bash
+openspec new change ""
+\`\`\`
+
+**SHOW:**
+\`\`\`
+Created: \`openspec/changes//\`
+
+The folder structure:
+\`\`\`
+openspec/changes//
+├── proposal.md ← Why we're doing this (empty, we'll fill it)
+├── design.md ← How we'll build it (empty)
+├── specs/ ← Detailed requirements (empty)
+└── tasks.md ← Implementation checklist (empty)
+\`\`\`
+
+Now let's fill in the first artifact—the proposal.
+\`\`\`
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+\`\`\`
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+\`\`\`
+
+**DO:** Draft the proposal content (don't save yet):
+
+\`\`\`
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- \`\`: [brief description]
+
+### Modified Capabilities
+
+
+## Impact
+
+- \`src/path/to/file.ts\`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+\`\`\`
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+\`\`\`bash
+openspec instructions proposal --change "" --json
+\`\`\`
+Then write the content to \`openspec/changes//proposal.md\`.
+
+\`\`\`
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+\`\`\`
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+\`\`\`
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+\`\`\`
+
+**DO:** Create the spec file:
+\`\`\`bash
+mkdir -p openspec/changes//specs/
+\`\`\`
+
+Draft the spec content:
+
+\`\`\`
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement:
+
+
+
+#### Scenario:
+
+- **WHEN**
+- **THEN**
+- **AND**
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+\`\`\`
+
+Save to \`openspec/changes//specs//spec.md\`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+\`\`\`
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+\`\`\`
+
+**DO:** Draft design.md:
+
+\`\`\`
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+\`\`\`
+
+Save to \`openspec/changes//design.md\`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+\`\`\`
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+\`\`\`
+
+**DO:** Generate tasks based on specs and design:
+
+\`\`\`
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+\`\`\`
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to \`openspec/changes//tasks.md\`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+\`\`\`
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+\`\`\`
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: \`- [ ]\` → \`- [x]\`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+\`\`\`
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+\`\`\`
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+\`\`\`
+## Archiving
+
+When a change is complete, we archive it. This moves it from \`openspec/changes/\` to \`openspec/archive/YYYY-MM-DD--/\`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+\`\`\`
+
+**DO:**
+\`\`\`bash
+openspec archive ""
+\`\`\`
+
+**SHOW:**
+\`\`\`
+Archived to: \`openspec/archive/YYYY-MM-DD--/\`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+\`\`\`
+
+---
+
+## Phase 11: Recap & Next Steps
+
+\`\`\`
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+| Command | What it does |
+|---------|--------------|
+| \`/opsx:explore\` | Think through problems before/during work |
+| \`/opsx:new\` | Start a new change, step through artifacts |
+| \`/opsx:ff\` | Fast-forward: create all artifacts at once |
+| \`/opsx:continue\` | Continue working on an existing change |
+| \`/opsx:apply\` | Implement tasks from a change |
+| \`/opsx:verify\` | Verify implementation matches artifacts |
+| \`/opsx:archive\` | Archive a completed change |
+
+---
+
+## What's Next?
+
+Try \`/opsx:new\` or \`/opsx:ff\` on something you actually want to build. You've got the rhythm now!
+\`\`\`
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+\`\`\`
+No problem! Your change is saved at \`openspec/changes//\`.
+
+To pick up where we left off later:
+- \`/opsx:continue \` - Resume artifact creation
+- \`/opsx:apply \` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+\`\`\`
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+\`\`\`
+## OpenSpec Quick Reference
+
+| Command | What it does |
+|---------|--------------|
+| \`/opsx:explore\` | Think through problems (no code changes) |
+| \`/opsx:new \` | Start a new change, step by step |
+| \`/opsx:ff \` | Fast-forward: all artifacts at once |
+| \`/opsx:continue \` | Continue an existing change |
+| \`/opsx:apply \` | Implement tasks |
+| \`/opsx:verify \` | Verify implementation |
+| \`/opsx:archive \` | Archive when done |
+
+Try \`/opsx:new\` to start your first change, or \`/opsx:ff\` if you want to move fast.
+\`\`\`
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice`;
+}
+
// -----------------------------------------------------------------------------
// Slash Command Templates
// -----------------------------------------------------------------------------
@@ -2408,6 +2947,20 @@ Target archive directory already exists.
};
}
+/**
+ * Template for /opsx:onboard slash command
+ * Guided onboarding through the complete OpenSpec workflow
+ */
+export function getOpsxOnboardCommandTemplate(): CommandTemplate {
+ return {
+ name: 'OPSX: Onboard',
+ description: 'Guided onboarding - walk through a complete OpenSpec workflow cycle with narration',
+ category: 'Workflow',
+ tags: ['workflow', 'onboarding', 'tutorial', 'learning'],
+ content: getOnboardInstructions(),
+ };
+}
+
/**
* Template for /opsx:bulk-archive slash command
*/
diff --git a/test/core/shared/skill-generation.test.ts b/test/core/shared/skill-generation.test.ts
index f69cfaa43..df6d2e3b8 100644
--- a/test/core/shared/skill-generation.test.ts
+++ b/test/core/shared/skill-generation.test.ts
@@ -8,9 +8,9 @@ import {
describe('skill-generation', () => {
describe('getSkillTemplates', () => {
- it('should return all 9 skill templates', () => {
+ it('should return all 10 skill templates', () => {
const templates = getSkillTemplates();
- expect(templates).toHaveLength(9);
+ expect(templates).toHaveLength(10);
});
it('should have unique directory names', () => {
@@ -33,6 +33,7 @@ describe('skill-generation', () => {
expect(dirNames).toContain('openspec-archive-change');
expect(dirNames).toContain('openspec-bulk-archive-change');
expect(dirNames).toContain('openspec-verify-change');
+ expect(dirNames).toContain('openspec-onboard');
});
it('should have valid template structure', () => {
@@ -48,9 +49,9 @@ describe('skill-generation', () => {
});
describe('getCommandTemplates', () => {
- it('should return all 9 command templates', () => {
+ it('should return all 10 command templates', () => {
const templates = getCommandTemplates();
- expect(templates).toHaveLength(9);
+ expect(templates).toHaveLength(10);
});
it('should have unique IDs', () => {
@@ -73,13 +74,14 @@ describe('skill-generation', () => {
expect(ids).toContain('archive');
expect(ids).toContain('bulk-archive');
expect(ids).toContain('verify');
+ expect(ids).toContain('onboard');
});
});
describe('getCommandContents', () => {
- it('should return all 9 command contents', () => {
+ it('should return all 10 command contents', () => {
const contents = getCommandContents();
- expect(contents).toHaveLength(9);
+ expect(contents).toHaveLength(10);
});
it('should have valid content structure', () => {
+ 
- 
- 
-