Openspec

# OpenSpec (OPSX) Skill

Use this skill to guide or reason about the OpenSpec artifact-driven workflow system (OPSX), including artifact graphs, schema/template resolution, change lifecycle, and experimental commands/skills.

## Quick Navigation

- Artifact graph core concepts: references/artifact-core.md
- OPSX workflow behavior and usage: references/opsx-workflow.md
- Setup + profiles (init, update, config profile): references/setup-profiles.md
- Schema customization workflow and gaps: references/schema-customization.md
- End-to-end schema workflow gaps and proposed solution: references/schema-workflow-gaps.md
- Experimental release plan and rollout checklist: references/experimental-release-plan.md

## Release Highlights (1.2.0 → 1.3.0)

- **More tool integrations:** adds support for Junie, Lingma, ForgeCode, and IBM Bob.
- **Safer setup:** shell completion installation is now opt-in, and Copilot auto-detection no longer triggers from a bare `.github/` directory alone.
- **Adapter fixes:** Pi command generation was corrected, and OpenCode now uses the canonical `.opencode/commands/` path.
- **Safer status checks:** `openspec status` now exits cleanly when a project has no changes yet.

## OPSX Commands

| Command              | Purpose                                                  |
| -------------------- | -------------------------------------------------------- |
| `/opsx:explore`      | Think through ideas, investigate problems (no structure) |
| `/opsx:new`          | Start a new change                                       |
| `/opsx:continue`     | Create next artifact based on dependencies               |
| `/opsx:ff`           | Fast-forward — create all planning artifacts at once     |
| `/opsx:apply`        | Implement tasks, updating artifacts as needed            |
| `/opsx:verify`       | Validate implementation matches spec                     |
| `/opsx:sync`         | Sync delta specs to main specs                           |
| `/opsx:archive`      | Archive single completed change                          |
| `/opsx:bulk-archive` | Archive multiple completed changes at once               |

**Legacy (non-OPSX) command:** `/openspec:proposal` creates all planning artifacts at once. Prefer OPSX, but this can be useful for small/straightforward changes or older setups.

## Schema Management

```bash
openspec schemas                    # List available schemas
openspec schema which --all         # Show resolution sources
openspec schema init my-workflow    # Create new schema interactively
openspec schema fork spec-driven my-workflow  # Fork existing schema
openspec schema validate my-workflow  # Validate schema structure
```

## Project Configuration

Create `openspec/config.yaml` for per-project settings:

```yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest, Playwright

rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
```

**Schema precedence:** CLI flag → Change metadata → Project config → Default (`spec-driven`)

## Core Concepts

- **Artifact graph, not a workflow engine**: Dependencies enable actions; they do not force linear phases.
- **Filesystem-as-database**: Completion is derived from file existence, not stored state.
- **Deterministic CLI**: Commands require explicit change context (agent infers, CLI remains strict).
- **XDG schema resolution**: User overrides take precedence over built-ins.
- **Templates are schema-scoped**: Templates live next to schema and resolve with a strict 2-level fallback.

## Decision Rules

-