Glossary

Every term used in this section, in plain language. Nothing here assumes you have read the rest.

The core nouns

Specification (spec). A document describing how part of your system behaves right now. Specifications live in openspec/specs/, are organised by domain, and are made of requirements and scenarios. The agreed answer to "what does this software do?"

Source of truth. The openspec/specs/ directory as a whole. Changes propose edits to it; archiving applies them.

Change. One unit of work, packaged as a folder under openspec/changes/<name>/. It holds everything about that work: the proposal, the design, the tasks, and the specification edits. One change, one folder, one feature.

Artifact. A document inside a change. The four standard ones are the proposal, the delta specifications, the design and the tasks.

Delta specification. A specification inside a change that describes only what is changing — using ADDED, MODIFIED, REMOVED and RENAMED sections — rather than restating the whole specification. This is what lets OpenSpec edit existing systems cleanly.

Capability. One named area of behaviour, with one specification file. Named in the proposal's ## Capabilities section, which is the contract deciding which specification files must exist.

Domain. A logical grouping for specifications — auth/, payments/, ui/. You choose domains that match how your team already thinks about the system.

Inside a specification

Requirement. A single behaviour the system must have, written with an RFC 2119 keyword: "The system SHALL expire sessions after 30 minutes." Requirements state the what, never the how.

Scenario. A concrete, testable example of a requirement in action, written as WHEN/THEN. Scenarios make a requirement verifiable — you could write an automated test from one. Written with exactly four hash marks; three fails silently.

RFC 2119 keywords. MUST, SHALL, SHOULD and MAY, which carry standardised meaning about how strict a requirement is. MUST and SHALL are absolute; SHOULD is recommended with room for exceptions; MAY is optional.

Purpose. The opening section of a main specification, and of a delta that introduces a brand-new capability. At least 50 characters, or strict validation calls it too brief.

The artifacts

Proposal (proposal.md). The why and what of a change. Requires ## Why and ## What Changes; the template adds ## Capabilities and ## Impact.

Design (design.md). The how: technical decisions, the alternatives rejected against each one, and the risks. Optional for simple changes.

Tasks (tasks.md). The implementation checklist. The AI works through it during apply, ticking items off. The - [ ] X.Y form is load-bearing — a task written any other way is not tracked.

The lifecycle

Apply. The step where code gets written. The agent works the task list in order, marking each item complete.

Archive. Finishing a change: its delta specifications merge into the main specifications, and the folder moves to openspec/changes/archive/YYYY-MM-DD-<name>/. After archiving, your specifications describe the new reality.

Sync. Merging a change's delta specifications into the main specifications without archiving the change. For long-running work where the specifications must be true before the work is complete.

Retire. Deleting a capability's main specification when its last requirement is removed. Only happens when the change's .openspec.yaml sets retire_capabilities: true.

Commands and tools

CLI. The openspec program you run in your terminal. It sets up projects, lists and validates changes, opens the dashboard, and archives.

Slash command. A command you type into your AI assistant's chat, like /opsx:propose. Slash commands drive the workflow; they are not terminal commands. Confusing the two is the most common early stumble.

OPSX. The current OpenSpec workflow, built around fluid actions rather than rigid phases. Its slash commands all begin /opsx:.

Skill. A folder of instructions (skills/openspec-*/SKILL.md) that an AI assistant auto-detects and follows. There are twelve.

Command file. A per-tool slash command file. The older delivery mechanism, still supported alongside skills.

Profile. Which slash commands are installed. Core — the default — is propose, explore, apply, update, sync, archive. Expanded adds new, continue, ff, verify, bulk-archive, onboard.

Delivery. Whether OpenSpec installs skills, command files, or both. Configured globally; applied with openspec update.

Configuration and customisation

Project config (openspec/config.yaml). Per-project settings: the default schema, the context: injected into every artifact the AI generates, and per-artifact rules:.

Change metadata (.openspec.yaml). One change's own settings: its schema, its creation date, and the skip_specs and retire_capabilities escape hatches.

Context injection. Putting project background in config.yaml's context: so it is automatically added to every artifact the AI generates, wrapped in <context> tags. More reliable than hoping the assistant reads a separate file. Capped at 50 KB.

Schema. The definition of which artifacts a workflow has and how they depend on one another. The built-in default is spec-driven. You can fork it or write your own.

Template. A Markdown file inside a schema shaping what the AI generates for one artifact. Editing a template changes the output immediately, with no rebuild.

Dependency graph. The directed acyclic graph formed by artifact requires: relationships. OpenSpec uses it to know what becomes possible next.

Enablers, not gates. The principle that artifact dependencies show what becomes possible next, not what is required next. Any artifact can be revisited and edited at any time.

Strict mode. --strict on the validator, which promotes warnings into failures. Five conditions change status under it.

skip_specs. A marker declaring that a change intentionally has no specification-level behaviour change — a pure refactor, tooling, or documentation. Validation rejects a zero-delta change without it.

Coordination across repositories (beta)

Store. A standalone repository whose whole job is planning, with the same openspec/ shape. Registered on your machine by name, so any command can work in it from anywhere.

Reference. A declaration, in a code repository's config.yaml, of a store that repository draws on. References are read-only.

Working context. What openspec context assembles: this repository's OpenSpec root plus every store it references.

Workset. A personal, machine-local set of folders you open together. Nothing about those local paths is committed to the shared planning repository.

Terms from the worked example

Article contract. contracts/article.schema.json — the structure the writing step must return: a headline under 120 characters, a body of at least 1200, one to six tags, and at least one source URL.

Canonical URL. The address a publisher declares authoritative for an item. Used to recognise something already collected, because titles get edited and feed identifiers are not universal.

Draft state. The unpublished state an article is filed in. Nothing in the pipeline can move an article out of it; only a person can.

Application password. A revocable credential scoped to one integration, issued to a dedicated WordPress account rather than to a person.

Brownfield. A codebase that already exists. Greenfield. A project with no code yet. OpenSpec's own positioning is "built for brownfield not just greenfield", and the delta grammar is why.

---