OpenSpec Spec-Driven Development

Specify what to build before writing code. Track changes as structured proposals. Keep specs as living documentation.

Principle: Fluid, iterative, brownfield-first. Artifacts are enablers, not gates.
Source: https://github.com/Fission-AI/OpenSpec

Prerequisites

• Node.js >= 20.19.0
• npm install -g @fission-ai/openspec@latest
• Initialize: openspec init --tools github-copilot (creates openspec/ + .github/ integration)

Directory Structure

openspec/
├── config.yaml                                      # Project context + artifact rules
├── specs/<product-ns>/<domain>/spec.md              # Current-state specs (multi-system)
│   # OR specs/<domain>/spec.md                      # (single-system repos)
├── changes/<change-name>/                           # Active change proposals
│   ├── .openspec.yaml
│   ├── proposal.md
│   ├── specs/<product-ns>/<domain>/spec.md          # Delta specs (ADDED/MODIFIED/REMOVED/RENAMED)
│   ├── design.md
│   └── tasks.md
└── changes/archive/YYYY-MM-DD-<name>/               # Completed changes

<product-ns> vs <domain>: <product-ns> (product namespace) is a stable folder that groups related domains under one system or product area — e.g. ordering/, billing/, auth/. <domain> is a single capability within that area — e.g. payments/, invoices/, sessions/. Use <product-ns>/<domain>/ in repos that host multiple distinct systems; use <domain>/ alone in single-system repos. This directory path segment is unrelated to the SDD process steps below.

SDD Process

/opsx:explore  →  Think, investigate, clarify (no code, no artifacts)
/opsx:propose  →  Create change + all planning artifacts in one step
/opsx:apply    →  Implement tasks from tasks.md checklist
/opsx:archive  →  Validate, merge delta specs, move to archive

Typical flow: propose → apply → archive.
Use explore first when the problem has hidden design gaps or ambiguities.

Child Skills

openspec-sdd is an entry-point/routing skill. Each phase of the SDD process is implemented by a dedicated child skill that carries the focused instructions for that step only.

Why separate skills, not one bundle?

• CLI-generated and CLI-owned — openspec init --tools github-copilot and openspec update write these skill files to .github/skills/. This is confirmed: running openspec update --force regenerates all four child skill files at the same timestamp as their matching .github/prompts/opsx-*.prompt.md files. Because the CLI owns these files, merging child skill content into a hand-authored parent skill would create a drift problem every time openspec update runs.
• Context efficiency — A developer running /opsx:apply doesn't need the explore or propose rules in their context window. Loading only the relevant child skill keeps token overhead low.
• Independent triggering — Each child skill has its own description frontmatter with specific trigger phrases, so it can fire directly without routing through the parent.

What openspec update generates for GitHub Copilot

For each workflow in your active config, the CLI generates two files under .github/:

File type	Path	Purpose
Skill	.github/skills/openspec-<workflow>/SKILL.md	Loaded by Copilot automatically via skills discovery
Prompt	.github/prompts/opsx-<workflow>.prompt.md	Invokable via /opsx:<workflow> slash command

Both files are stamped with generatedBy: "<version>" metadata and share an identical write timestamp after each openspec update run. The active workflow list is controlled by the workflows key in global config (see Profile vs Custom Profile below).

Currently generated child skills (this repo)

openspec config list  # profile: custom, delivery: both, workflows: propose/explore/apply/archive

Child skill	Location	Phase
openspec-explore	.github/skills/openspec-explore/	Explore
openspec-propose	.github/skills/openspec-propose/	Propose
openspec-apply-change	.github/skills/openspec-apply-change/	Apply
openspec-archive-change	.github/skills/openspec-archive-change/	Archive

Profile vs Custom Profile

OpenSpec has two profiles, configured globally via openspec config profile:

core — Opinionated preset. Generates the four base workflows (explore, propose, apply, archive) with a fixed, non-configurable setup. No openspec config set needed.

custom — Unlocks three configurable settings:

Setting	Values	Effect
delivery	both | prompts | skills	What openspec update generates — both skill + prompt files, prompts only, or skills only
workflows	Array of workflow names	Which workflows to include; controls how many skill/prompt pairs are generated
featureFlags	Object	Feature-specific toggles

Concrete example — this repo's config (C:\Users\ADMIN\AppData\Roaming\openspec\config.json):

{
  "profile": "custom",
  "delivery": "both",
  "workflows": ["explore", "propose", "apply", "archive"]
}

Result: 4 skill files + 4 prompt files generated (identical to core output, but each setting is now explicit and editable).

Concrete example — prompts-only delivery (for a team that doesn't use Copilot skills routing):

{
  "profile": "custom",
  "delivery": "prompts",
  "workflows": ["explore", "propose", "apply", "archive"]
}

Result: only .github/prompts/opsx-*.prompt.md files generated; no .github/skills/ files written.

To switch and regenerate: openspec config profile (interactive) → openspec update.

Role of openspec-sdd (this skill)

openspec-sdd covers everything the child skills don't: initialization, brownfield adoption, the mutation rule, the decision table, config, profile setup, and the overall mental model. It also serves as the landing skill when the user's intent spans multiple phases or doesn't map cleanly to a single child skill command.

AI Coding Agent Adaptation

When slash prompts aren't available, use skill files or CLI steps directly:

Alias	Skill file	CLI equivalent
/opsx:explore	openspec-explore/SKILL.md	openspec list --json, read files, no artifacts
/opsx:propose	openspec-propose/SKILL.md	openspec new change <name> + openspec instructions
/opsx:apply	openspec-apply-change/SKILL.md	openspec status --change "<name>" --json → implement tasks
/opsx:archive	openspec-archive-change/SKILL.md	openspec archive <name> -y

Read references/ai-coding-agent-workflow.md before modifying anything under openspec/.

Config

# openspec/config.yaml
schema: spec-driven
context: |
  Tech stack: Node.js 22, Express 5
  Tests: Vitest + supertest
rules:
  specs:
    - Use GIVEN/WHEN/THEN for all scenarios
  tasks:
    - Each task must be independently verifiable

context is injected into all generated artifacts (keep concise, max 50 KB).

Agent Decision Guide

Situation	Action
Problem unclear or complex	/opsx:explore — clarify first, never write code
Ready to plan + implement	/opsx:propose → /opsx:apply → /opsx:archive
Granular artifact control needed	/opsx:new → /opsx:continue (repeat) → /opsx:apply
Multiple small changes	/opsx:propose each → /opsx:bulk-archive
Implementation done, need validation	/opsx:verify
Specs changed mid-implementation	/opsx:sync then continue /opsx:apply
New contributor onboarding	/opsx:onboard
Existing codebase, no specs yet	Brownfield Adoption
Change should be abandoned	Delete folder from openspec/changes/
Multiple changes touch same domain	/opsx:bulk-archive (conflict detection built-in)

For detailed per-command behavioral rules (explore/apply/verify/archive), see references/command-rules.md.

Spec Format

Requirements use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY). Scenarios use GIVEN/WHEN/THEN. No implementation details in specs — those go in design.md.

See references/spec-format.md for the full template, delta spec marker usage (ADDED/MODIFIED/REMOVED/RENAMED), and RFC 2119 guidance.

Delta merge order during archive: RENAMED → REMOVED → MODIFIED → ADDED.

Change Artifacts

Artifact	Purpose
proposal.md	Why + what changes + impact + rollback
specs/<domain>/spec.md	Delta specs — behavioral changes only
design.md	Technical approach, architecture decisions, file changes
tasks.md	Phased checklist with - [ ] / - [x] checkboxes

For detailed templates, see references/artifact-templates.md.

Brownfield Adoption

1. openspec init --tools github-copilot — creates openspec/ + .github/ integration files
2. Edit openspec/config.yaml with tech stack and conventions
3. /opsx:explore — map current architecture, identify spec domains
4. Create openspec/specs/<domain>/spec.md for each domain, describing current behavior
   (baseline capture — the only time direct spec edits are permitted)
5. All future changes: /opsx:propose → /opsx:apply → /opsx:archive

Current-Spec Mutation Rule

openspec/specs/** is protocol-governed. Do not directly edit main specs for new, changed, renamed, or removed behavior.

• Stage all behavior changes in openspec/changes/<name>/specs/** first
• Merge into main specs only via sync or archive
• Exception: brownfield baseline capture (Step 4 above) and user-approved repair of corrupted content

Full policy: references/ai-coding-agent-workflow.md

CLI Quick Reference

Key commands: openspec init, openspec new change <name>, openspec status --change "<name>" --json, openspec validate --all, openspec archive <name> -y

Full command reference and flags: references/cli-reference.md

Spec Quality Checklist

• Requirements use RFC 2119 keywords (SHALL/MUST/SHOULD/MAY)
• Every requirement has at least one GIVEN/WHEN/THEN scenario
• No implementation details in specs (those go in design.md)
• Delta specs use correct markers (ADDED/MODIFIED/REMOVED/RENAMED)
• REMOVED requirements include deprecation reason
• RENAMED requirements include FROM:/TO: mapping

Error Handling

Failure	Action
openspec not found	npm install -g @fission-ai/openspec@latest
validate fails	Fix CRITICAL issues first, then WARNINGs → re-validate
archive fails	Check: incomplete tasks, invalid delta markers, or use --skip-specs
validate --strict fails	Resolve all WARNINGs or downgrade to non-strict

References

• ai-coding-agent-workflow.md — mutation policy, agent safety rules
• artifact-templates.md — full templates for all 4 change artifacts
• cli-reference.md — complete CLI commands and flags
• command-rules.md — per-command rules for explore/apply/verify/archive
• spec-format.md — spec template, delta markers, RFC 2119 guide
• e2e-simulation.md — annotated end-to-end workflow example (rate limiting on a SaaS API)