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 statusnow 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
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 structureProject Configuration
Create openspec/config.yaml for per-project settings:
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
Testing: Vitest, Playwright
rules:
proposal:
- Include rollback plan
specs:
- Use Given/When/Then formatSchema 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
- Prefer update when intent stays the same and you are refining scope or approach.
- Prefer new change when intent or scope fundamentally shifts, or the original can be completed independently.
- Always preserve a clear history of why artifacts changed (proposal/specs/design/tasks).
Recipes
1) Show what is ready to create next
- Determine the active change id.
- Query status and ready artifacts with the change explicitly set.
- Present ready artifacts and their dependencies.
Expected behavior: show ready artifacts, not required steps.
2) Generate instructions for a specific artifact
- Resolve schema and template with XDG fallback.
- Build context: change metadata, dependency status, and target paths.
- Return enriched instructions in plain Markdown.
3) Start a new change
- Validate change name (kebab-case).
- Create change directory and README.
- Show initial status and first ready artifact.
4) Schema customization guidance
- Explain XDG override paths.
- Describe copying built-in schema + templates.
- Provide verification steps or recommended CLI commands for listing and resolving.
5) Explain schema binding for a change
- Prefer change metadata if available.
- Fallback to project default schema if configured.
- Otherwise default to spec-driven.
Prohibitions
- Do not treat the system as a linear workflow engine.
- Do not assume a change is active without explicit selection.
- Do not silently fall back between schemas or templates without reporting.
- Do not copy long vendor docs verbatim; summarize and provide actionable guidance.
Output Expectations
- Give clear artifact readiness and dependency explanations.
- Use explicit change identifiers in examples.
- Provide concise, actionable steps and indicate whether they are informational or required.