| name | openspec-sdd |
| description | Spec-driven development (SDD) using OpenSpec with GitHub Copilot. Use when initializing OpenSpec in a project, writing specifications (requirements + scenarios), proposing changes with delta specs, designing and breaking down tasks, implementing from tasks.md, verifying against specs, syncing/archiving completed changes, managing the openspec/ directory, or adopting specs in existing brownfield codebases. Triggers: "openspec", "spec-driven", "SDD", "write specs", "propose a change", "delta spec", "archive change", "opsx", "/opsx:", "GIVEN/WHEN/THEN scenarios", "requirements specification", "change proposal", "brownfield specs", "verify implementation". |
| metadata | {"version":"0.2.0","author":"arisng"} |
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
| 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
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
openspec init --tools github-copilot — creates openspec/ + .github/ integration files- Edit
openspec/config.yaml with tech stack and conventions
/opsx:explore — map current architecture, identify spec domains- Create
openspec/specs/<domain>/spec.md for each domain, describing current behavior
(baseline capture — the only time direct spec edits are permitted)
- 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
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
