OpenSpec

OpenSpec is an AI-native spec-driven workflow system for Claude, Codex, and Gemini.

This package now ships as a Node CLI with:

• optional project-local openspec/config.yaml overrides
• full workflow command set by default (no profile split)
• schema-driven workflow metadata
• generated platform adapters
• pure Node install/uninstall/check/doc/language commands
• built-in security-review gating and workflow checkpoints
• runtime guidance primitives for status/instructions integrations

Quick start

npm install -g @xenonbyte/openspec
openspec install --platform claude,codex,gemini
$openspec help me start an OpenSpec workflow

Current release: 2.0.1

Release focus:

• advisory security-review is now consistently non-actionable in runtime, workflow, and summary APIs
• runtime guidance preserves caller-provided preview sources unless on-disk artifacts contain meaningful content
• whitespace-only planning files no longer erase in-memory preview text
• apply previews now normalize array-backed tasks sources correctly
• apply readiness stays file-based, so unsaved planning previews cannot bypass required artifacts

Codex usage

Preferred:

$openspec create an OpenSpec change for add-dark-mode

Explicit routing:

/prompts:openspec
/prompts:opsx-propose

If a /prompts:* route still needs a change name or description, provide it in the next message.

Project config

openspec/config.yaml controls:

• schema
• language
• context
• rules
• securityReview

Precedence:

• change metadata
• project config
• global config
• package defaults

Workflow checkpoints

• security-review sits after design and before tasks
• spec checkpoint runs before tasks
• task checkpoint runs before apply
• execution checkpoint runs after each top-level task group during apply
• Security-review states: required, recommended, waived, completed
• Checkpoint states: PASS, WARN, BLOCK

Commands

openspec install --platform claude,codex,gemini
openspec uninstall --platform codex
openspec --check
openspec --doc
openspec --language zh
openspec --help
openspec --version

Behavior notes:

• install and uninstall accept comma-separated platforms via --platform.
• --check lists installed platform manifests from ~/.openspec/manifests/*.manifest; config platform is reported as the last selected platform.
• --doc prefers the package-local guide (skills/openspec/GUIDE-*.md) and falls back to the shared installed copy.

Documentation

• Command reference
• Codex usage guide
• Customization guide
• Runtime guidance kernel
• Supported tools

Repository shape

• lib/: runtime modules for config, generation, install, and CLI behavior
• schemas/: workflow schema definitions
• templates/: command and project templates
• commands/: generated platform adapters
• skills/openspec/: distributed skill bundle
• openspec/: dogfooded project workspace for this repository