---
name: openspec
description: 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 |