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

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 structure

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

• 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

1. Determine the active change id. 2. Query status and ready artifacts with the change explicitly set. 3. Present ready artifacts and their dependencies.

Expected behavior: show ready artifacts, not required steps.

2) Generate instructions for a specific artifact

1. Resolve schema and template with XDG fallback. 2. Build context: change metadata, dependency status, and target paths. 3. Return enriched instructions in plain Markdown.

3) Start a new change

1. Validate change name (kebab-case). 2. Create change directory and README. 3. Show initial status and first ready artifact.

4) Schema customization guidance

1. Explain XDG override paths. 2. Describe copying built-in schema + templates. 3. Provide verification steps or recommended CLI commands for listing and resolving.

5) Explain schema binding for a change

1. Prefer change metadata if available. 2. Fallback to project default schema if configured. 3. 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.

Links

• Documentation
• Releases
• GitHub
• npm

Artifact Graph Core (OPSX)

Key Principles

• The system is an artifact tracker with dependency awareness, not a workflow engine.
• Dependencies are enablers: they indicate what can be created next, not what must be done.
• Completion is inferred from filesystem state (file existence), not stored in a database.

Terminology

• Change: A unit of work (feature, refactor, migration) tracked under a change directory.
• Schema: A graph definition for artifacts and dependencies.
• Artifact: A node in the graph, usually a document to produce.
• Template: Instructions for creating a specific artifact.

Naming Conventions

• Specs are named after capabilities, not change IDs.
• Use the canonical path: specs/<capability>/spec.md.

Schema Resolution (XDG)

Resolution order:

1. User override: ${XDG_DATA_HOME}/openspec/schemas/<name>/schema.yaml 2. Built-in: <package>/schemas/<name>/schema.yaml

Notes:

• Use XDG data locations for schema data, not config.
• Built-ins are not auto-copied; users override by creating files in the data dir.

Template Resolution (Two Levels)

Resolution order:

1. User override: ${XDG_DATA_HOME}/openspec/schemas/<schema>/templates/<artifact>.md 2. Built-in: <package>/schemas/<schema>/templates/<artifact>.md

Rules:

• No inheritance between schemas.
• Templates are always co-located with their schema.
• If missing, return an error instead of silently falling back elsewhere.

Core Engine Behaviors

• Graph construction: artifacts are nodes with requires dependencies.
• Ready artifacts: all dependencies are complete.
• Blocked artifacts: dependencies are missing.
• Build order: topological sort of the DAG.
• Glob artifacts: patterns like specs/**/spec.md count as complete when at least one file matches.

CLI Contract (Deterministic)

• Commands must be explicit about the change context.
• CLI behavior is deterministic; agent may infer the change and pass it explicitly.
• Avoid ambiguous defaults for --change or --schema in CLI layer.

Design Constraints

• Stateless by design; each command scans the filesystem.
• Avoid hidden or cached state that can drift.
• Always surface the resolved schema and template paths in diagnostics.

Experimental Release Plan (OPSX)

Scope and Intent

• Preserve existing OpenSpec commands.
• Introduce an experimental, granular artifact workflow.
• Enable cross-editor usage via Agent Skills.

Key Work Items

1. Rename AWF commands to OPSX (new/continue). 2. Remove obsolete WF skill files. 3. Add Agent Skills for experimental workflow. 4. Update OPSX command content. 5. End-to-end testing of skills workflow. 6. User-facing docs and feedback loop.

Experimental Skills Behavior

• Skills are generated to .claude/skills/ and discovered by compatible editors.
• Expected skills include:
• openspec-new-change
• openspec-continue-change
• openspec-apply-change

Validation Checklist

• Skill files generated and detected.
• Dependency detection works in status and next.
• Templates are meaningful and actionable.
• Schemas other than spec-driven work.
• Documentation exists with setup and usage examples.

Non-Goals

• No batch mode refactor of legacy commands.
• No new schemas beyond existing defaults.
• No editor-specific configurators.

User Communication

• Emphasize experimental status.
• Provide clear setup instructions.
• Provide a feedback channel.

OPSX Workflow (Experimental)

Purpose

OPSX provides a fluid, iterative workflow for OpenSpec changes. It replaces rigid phases with flexible actions guided by artifact dependencies.

Why OPSX Exists

• Hardcoded instructions are difficult to customize.
• One-shot batch commands are hard to test or iterate on.
• Fixed workflows do not fit all teams or codebases.
• OPSX enables schema-driven, editable prompts and dependency-aware progress.

User Experience Principles

• Actions, not phases: you can update any artifact as you learn.
• Dependencies enable, they do not gate.
• Iteration is expected: adjust proposals, specs, and design during implementation.

Commands (Typical)

• status: inspect what exists and what is ready; safe even before the first change exists.
• new: start a change and scaffold structure.
• continue: create the next ready artifact.
• apply: implement tasks and update artifacts as needed.
• sync: reconcile delta specs with main specs.
• archive: finalize and move the change to archive.

Status behavior (v1.3.0)

• openspec status now exits gracefully when no changes exist instead of failing hard.
• Use it as a safe preflight check before telling the operator to create a new change or continue an existing one.

Profiles and the “Propose” Workflow (v1.2.0)

Workflow profiles

OpenSpec v1.2.0 adds workflow profiles to control which workflows/commands are installed for your AI tool(s):

• Use openspec config profile to review/change delivery + workflows.
• Fast preset: openspec config profile core (minimal essential workflows).
• To apply your selected workflows to a project’s installed command/skill files, run openspec update.

All-at-once propose (legacy)

If you want to generate the full planning set in one request (proposal + specs + design + tasks), OpenSpec provides the legacy slash command:

• /openspec:proposal

This is conceptually similar to doing /opsx:new and then /opsx:ff, but in a single step. Prefer OPSX for incremental control; use the legacy command when you intentionally want “all planning artifacts now”.

Choosing Update vs New Change

Update the existing change when:

• Intent remains the same and you are refining execution.
• Scope narrows or is clarified.
• Learning reveals corrections to design or specs.

Start a new change when:

• Intent or core problem shifts materially.
• Scope expands beyond recognition.
• The original change can be completed independently.

Dependency Model

• Artifacts form a DAG: proposal → specs → design → tasks (default schema).
• Blocked artifacts show unmet dependencies.
• Ready artifacts are those with all dependencies complete.

Communication Guidelines

• Explicitly name the change when invoking commands.
• Show progress and what is unlocked after each step.
• If schema selection is ambiguous, clarify before continuing.

Task Tracking Format

• Use checklist items in tasks artifacts.
• Required format for apply tracking: - [ ] for pending and - [x] for done.

Schema Customization (Current Process and Gaps)

Current Manual Flow

1. Determine the user data path (XDG):

• macOS/Linux: ~/.local/share/openspec/schemas/
• Windows: %LOCALAPPDATA%\openspec\schemas\
• If set: $XDG_DATA_HOME/openspec/schemas/

2. Create a schema directory with templates:

• <schema>/schema.yaml
• <schema>/templates/\*.md

3. Copy built-in schema and template files from the installed package. 4. Edit schema.yaml and templates to customize.

Friction Points

• Path discovery depends on XDG knowledge.
• Locating the package varies by install method.
• No built-in scaffolding or verification.
• No diffing against built-in defaults.

Recommended CLI Capabilities

Priority commands:

• schema list: show available schemas and sources.
• schema which <name>: display resolved location.
• schema copy <name>: scaffold a customizable copy.
• schema diff <name>: compare override to built-in.
• schema reset <name>: revert to built-in.

Guidance for User Requests

• Provide explicit paths and emphasize where overrides are read from.
• Clarify that overrides are all-or-nothing at the schema level.
• Suggest a CLI for users to avoid manual path discovery.

Schema Workflow Gaps and Proposed Fixes

Current Gaps

• Schema is not bound to a change; users must remember --schema.
• No project-local schemas for version control.
• No schema management CLI for listing, copying, or diffing.
• No project default schema.

Proposed Artifacts

Change Metadata (change.yaml)

Store per-change schema:

• schema: selected workflow schema.
• created: timestamp (ISO8601).

Project Config (openspec/config.yaml)

Store project default schema:

• defaultSchema: used when change metadata is missing.

Project-Local Schemas

Resolution order proposal:

1. ./openspec/schemas/<name>/ 2. ~/.local/share/openspec/schemas/<name>/ 3. <package>/schemas/<name>/

Selection Precedence

1. CLI --schema flag 2. Change metadata 3. Project default 4. Hardcoded fallback (spec-driven)

Implementation Phases

• Phase 1: change.yaml creation and reading.
• Phase 2: project-local schemas.
• Phase 3: schema management CLI.
• Phase 4: init-time schema selection.

Backwards Compatibility

• Missing change.yaml should default safely.
• Explicit --schema remains authoritative.
• No behavior break for existing changes.

Setup and Profiles (CLI)

Operational notes for OpenSpec v1.3.0+ about initializing a project, updating installed tool integrations, and managing workflow profiles.

Initialize a Project (openspec init)

Interactive setup (recommended):

openspec init

Non-interactive tool selection:

# Configure specific tools
openspec init --tools claude,cursor

# Configure all supported tools
openspec init --tools all

# Skip tool configuration
openspec init --tools none

OpenSpec can also auto-detect existing tool directories (e.g. .claude/, .cursor/) and pre-select them during openspec init.

In v1.3.0, GitHub Copilot detection is stricter: a bare .github/ directory is not enough. Detection should be based on Copilot-specific markers such as .github/copilot-instructions.md, .github/instructions/, .github/prompts/, .github/agents/, or .github/skills/.

New tool directories (v1.2.0)

• Pi: .pi/skills/ and .pi/prompts/
• Kiro: .kiro/skills/ and .kiro/prompts/

New tool directories / adapters (v1.3.0)

• Junie: .junie/skills/ and .junie/commands/
• Lingma: .lingma/skills/ and .lingma/commands/opsx/
• IBM Bob: .bob/skills/ and .bob/commands/
• ForgeCode: .forge/skills/ only; no command adapter is generated
• OpenCode: command files belong under .opencode/commands/ (plural)
• Pi: if command references or template arguments looked broken in older output, regenerate after upgrading to pick up the v1.3.0 fix

Shell completions (v1.3.0)

• Completion installation is opt-in. Do not assume openspec init should modify shell completion files unless the operator explicitly wants it.
• This matters most on PowerShell, where the v1.3.0 change avoids encoding corruption from automatic completion installation.

Keep Tool Files in Sync (openspec update)

After upgrading the CLI, regenerate tool-specific command/skill files:

openspec update

In v1.2.0, openspec update can also prune command files and tool skill directories for workflows you’ve deselected (so projects don’t accumulate stale integrations).

Workflow Profiles (openspec config profile)

Profiles control which workflows are selected (and thus which command/skill files are installed).

# Interactive wizard
openspec config profile

# Fast preset: minimal essential workflows
openspec config profile core

Notes:

• openspec config profile updates global configuration; apply to a project with openspec update.
• openspec config list may warn when global config and the current project’s installed files drift out of sync (run openspec update).