OpenSpec

Spec-driven development with OpenSpec CLI. Use when building features, migrations, refactors, or any structured development work. Manages proposal → specs → design → tasks → implementation workflows. Supports custom schemas (TDD, rapid, etc.). Trigger on requests involving feature planning, spec writing, change management, or when /opsx commands are mentioned.

Security Scan

The skill's files and runtime instructions are internally consistent with a CLI-driven spec/workflow tool; it does not request unrelated credentials or hidden access, but it recommends installing a third-party npm package and will create files in your repository, so verify the package/source before installing globally.

Purpose & Capability

Name, description, and instructions consistently describe a CLI-driven spec/workflow tool (OpenSpec). The commands and artifacts (proposal, specs, design, tasks) match the stated purpose. One note: the SKILL.md instructs installing @fission-ai/openspec from npm even though the skill bundle includes no install spec or provenance information; that is coherent with a CLI-based skill but means the runtime depends on a third-party npm package not included in the registry metadata.

Instruction Scope

Instructions are scoped to project-local flows (creating changes, writing artifacts into openspec/changes/<name>/, validating, archiving). They do not instruct reading unrelated system files or environment variables. They do instruct the agent/user to write files into the repository and to auto-generate a Claude integration under .claude/skills — review any generated files for unexpected content (API keys, endpoints) before committing.

Install Mechanism

There is no formal install spec in the skill bundle (lowest disk risk), but SKILL.md tells users to run `npm install -g @fission-ai/openspec@latest`. Global npm installs execute third-party code and produce binaries; verify the package publisher, inspect the package source, or prefer a non-global/local invocation (npx or container) if you want to avoid implicit code execution. The npm package name is not a known built-in; absence of homepage/source in the registry metadata reduces provenance.

Credentials

The skill declares no required environment variables, credentials, or config paths. SKILL.md does not attempt to read environment variables or request credentials. The main proportionality concern is operational: the CLI will modify project files and may add integration files (.claude/skills); those are appropriate for its purpose but should be inspected.

Persistence & Privilege

Skill does not request always:true and allows model invocation (default). It does, however, instruct installing a CLI that will create persistent project files (openspec/, .claude/skills/). This is expected for a development tool but warrants review of any generated files before committing, and cautious handling of the global npm install step.

Assessment

This skill appears to be what it says: a CLI-based spec/workflow helper that writes artifacts into your project. Before you install or run it: 1) Verify the npm package (@fission-ai/openspec) on the npm registry or GitHub — check publisher, source code, and recent versions. 2) Prefer non-global usage (npx or local install) or inspect the package contents before running a global install. 3) When you run the CLI, review any files it creates (openspec/, openspec/config.yaml, .claude/skills/*) for secrets, endpoints, or unexpected scripts before adding them to source control. 4) If you need higher assurance, run the install in an isolated environment (container/VM) and inspect the package source and behavior there. If you want, I can list the concrete checks to run on the npm package or draft a safe install procedure (npx, sandboxed run).

OpenSpec — Spec-Driven Development

OpenSpec structures AI-assisted development into trackable changes with artifacts (proposal, specs, design, tasks) that guide implementation.

Setup

# Install globally
npm install -g @fission-ai/openspec@latest

# Initialize in a project
cd /path/to/project
openspec init --tools claude

# Update after CLI upgrade
openspec update

Core Workflow

Each change follows: new → plan → apply → verify → archive

1. Start a Change

# Create change folder with default schema
openspec new change <name>

# With specific schema
openspec new change <name> --schema tdd-driven

2. Plan (Create Artifacts)

Use the CLI instructions command to get enriched prompts for each artifact:

# Get instructions for next artifact
openspec instructions --change <name> --json

# Check progress
openspec status --change <name> --json

Artifact sequence (spec-driven schema):

1. proposal.md — Why and what (intent, scope, approach)
2. specs/ — Requirements + scenarios (Given/When/Then)
3. design.md — Technical approach and architecture decisions
4. tasks.md — Implementation checklist with checkboxes

3. Implement

Read tasks.md and work through items, marking [x] as complete.

4. Verify

openspec validate --change <name> --json

Checks completeness, correctness, and coherence.

5. Archive

openspec archive <name> --yes

Merges delta specs into main openspec/specs/ and moves change to archive.

Agent Workflow (How to Use as an AI Agent)

When the user asks to build/migrate/refactor something with OpenSpec:

1. Check project state:

   openspec list --json           # Active changes
   openspec list --specs --json   # Current specs
   openspec schemas --json        # Available schemas
   

2. Create the change:

   openspec new change <name> [--schema <schema>]
   

3. For each artifact, get instructions and create the file:

   openspec instructions <artifact> --change <name> --json
   openspec status --change <name> --json
   

   Then write the artifact file to openspec/changes/<name>/.

4. Implement tasks from tasks.md.

5. Validate and archive:

   openspec validate <name> --json
   openspec archive <name> --yes
   

CLI Quick Reference

Command	Purpose
openspec list [--specs] [--json]	List changes or specs
openspec show <name> [--json]	Show change/spec details
openspec status --change <name> [--json]	Artifact completion status
openspec instructions [artifact] --change <name> [--json]	Get enriched creation instructions
openspec validate [name] [--all] [--json]	Validate changes/specs
openspec archive <name> [--yes]	Archive completed change
openspec schemas [--json]	List available schemas
openspec templates [--json]	Show template paths
openspec config	View/modify settings

Always use --json for programmatic/agent use.

Custom Schemas

Schemas define artifact sequences. Create custom ones for different workflows:

# Fork built-in schema
openspec schema fork spec-driven my-workflow

# Create from scratch
openspec schema init my-workflow

# Validate
openspec schema validate my-workflow

Schema files live in openspec/schemas/<name>/schema.yaml with templates in templates/.

For schema structure details, see references/schemas.md.

Project Structure

project/
├── openspec/
│   ├── config.yaml          # Project config (default schema, context, rules)
│   ├── specs/               # Source of truth — current system behavior
│   ├── changes/             # Active changes (one folder each)
│   │   └── <change-name>/
│   │       ├── .openspec.yaml
│   │       ├── proposal.md
│   │       ├── specs/       # Delta specs (what's changing)
│   │       ├── design.md
│   │       └── tasks.md
│   └── schemas/             # Custom schemas
└── .claude/skills/          # Auto-generated Claude integration

Spec Format

Specs use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY) with Given/When/Then scenarios:

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

Delta Specs

Changes don't rewrite specs — they describe deltas (ADDED/MODIFIED/REMOVED) that merge into main specs on archive.

Config

openspec/config.yaml sets defaults:

schema: spec-driven      # or tdd-driven, rapid, custom
context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format