pi-openspec/skills/openspec/SKILL.md

name	description
openspec	Spec-driven development workflow using OpenSpec. Use when initializing OpenSpec in a project, creating change proposals, writing specs, generating designs and task lists, implementing changes, or archiving completed work. Provides step-by-step workflow guidance for all 13 openspec tools.

OpenSpec Workflow Skill

OpenSpec organizes software work into specs (source of truth) and changes (proposed modifications). The workflow guides you from intent to implementation to archive.

When to load this skill

Load when you are:

• Setting up OpenSpec in a new or existing project
• Creating a change proposal for a new feature or fix
• Writing specs, designs, or task lists for an active change
• Implementing tasks from a change
• Validating or archiving completed work

Core Concepts

Specs (openspec/specs/) — the source of truth. Describe how the system currently behaves. Organized by domain (e.g., specs/auth/, specs/payments/).

Changes (openspec/changes/) — proposed modifications. Each change is a folder with proposal, delta specs, design, and task list. Changes merge into specs on archive.

Artifacts — the documents inside a change. The default spec-driven schema builds them in dependency order:

proposal → specs (delta) → design → tasks → implement → archive

Key insight: openspec_instructions is your north star. Call it before writing each artifact — it returns enriched context, rules, template structure, and output path. Do NOT skip this step.

The Standard Workflow

0. Initialize (once per project)

openspec_init(path=".", tools="pi")

Creates openspec/ directory, config.yaml, and pi-compatible skill files. Run once. Safe to skip if openspec/ already exists.

1. Orient

openspec_list()                    # see active changes in progress
openspec_spec_list()               # see stable spec domains
openspec_show(name="change-name")  # read an existing change in full

Run at session start to understand what's in flight before creating anything new.

2. Create a Change

openspec_new_change(name="add-user-auth", description="Add JWT auth to API")

Creates openspec/changes/add-user-auth/ with scaffolded artifact files. Name in kebab-case. Be specific — avoid generic names like update or wip.

Then immediately:

openspec_status(changeName="add-user-auth")

This shows the dependency graph: which artifacts exist, which are ready to write, which are blocked.

3. Write Each Artifact (in dependency order)

For each artifact the status shows as "ready":

openspec_instructions(changeName="add-user-auth", artifact="proposal")

Read the returned context, rules, and template carefully. The outputPath tells you exactly where to write. The dependencies list tells you what to read first.

IMPORTANT: context and rules guide what YOU write — do NOT copy them into the artifact file. Use template as the structure.

Write the artifact using the Write tool. Then call openspec_status again to see what unlocks next.

Repeat for: specs, design, tasks.

4. Implement Tasks

openspec_instructions(changeName="add-user-auth", artifact="apply")

Returns the task list and implementation approach. Work through tasks, checking them off in tasks.md as you go. Commit per completed task (not per file edit).

5. Validate

openspec_validate(name="add-user-auth")

Checks structural correctness of all artifacts. Fix any CRITICAL issues before archiving. WARNINGS are advisory.

6. Archive

openspec_archive(changeName="add-user-auth")

Merges delta specs into openspec/specs/. Moves the change folder to openspec/changes/archive/YYYY-MM-DD-add-user-auth/. The change is done.

Schema Operations

openspec_schema_list()                          # see available workflow schemas
openspec_schema_fork(source="spec-driven", name="rapid")  # fork for customization

Use rapid or other custom schemas when the full spec-driven workflow is more than the task needs (e.g., a small bugfix that doesn't warrant a full spec + design).

Reading Existing Specs

openspec_spec_list()              # list spec domains
openspec_spec_show(specId="auth") # read a spec in full

Always read relevant specs before creating a change — understand what's already specified and which domain your change touches.

Common Patterns

Starting fresh on an existing codebase:

1. openspec_init → openspec_spec_list (probably empty) → openspec_new_change for your first feature → write artifacts → implement

Resuming work in progress:

1. openspec_list → openspec_show (read the change) → openspec_status (see what's ready) → openspec_instructions for next artifact → continue

Quick change (small fix):

1. openspec_new_change(schema="rapid") if you have a rapid schema, else use spec-driven and skip non-critical artifacts → openspec_instructions(artifact="apply") → implement → openspec_archive

Gotchas

• Don't skip openspec_instructions before writing an artifact. The context and rules it returns are essential — they encode project-specific constraints that the template alone doesn't carry.
• Commit per task, not per file. The session commit protocol applies — each logical unit of work is one commit.
• openspec_update after config changes. If you modify openspec/config.yaml or switch schemas, run openspec_update to regenerate skill files.
• Delta specs are not full specs. A delta spec shows what's ADDED/MODIFIED/REMOVED relative to existing specs. Don't rewrite the entire domain — only the changes.

Tool Reference

Tool	Purpose
openspec_init	Initialize OpenSpec in a project
openspec_update	Regenerate skill/instruction files after config changes
openspec_list	List active changes (WIP) or stable specs
openspec_show	Show a change or spec in full
openspec_new_change	Create a new change directory with scaffolded artifacts
openspec_status	Artifact dependency graph and completion state
openspec_instructions	Enriched instructions for creating a specific artifact
openspec_validate	Validate change/spec structural correctness
openspec_archive	Archive completed change (merges delta specs into main)
openspec_spec_list	List spec domains (stable source of truth)
openspec_spec_show	View a specific spec by ID
openspec_schema_list	List available workflow schemas
openspec_schema_fork	Fork a schema for customization