OpenSpec — Spec-Driven Contract Layer + Internal Framework Router

Overview

This skill does two things, and they are orthogonal:

1. Contract layer (Part A) — Persist requirements and design decisions into specs that live in the repo, so every session works against the single source of truth instead of someone's latest recollection. Distilled from Fission-AI/OpenSpec (MIT).
2. Framework router (Part B) — When the work touches an internal framework, route to the right framework skill instead of re-deriving how to use it. One entry point, many destinations — like a switchboard.

The red line with Superpowers (memorize this): OpenSpec owns what to build and the contract (proposals, specs, design, tasks). The methodology layer — [[superpowers]] (its §brainstorming / §writing-plans / §test-driven-development / §systematic-debugging / §verification-before-completion disciplines) — owns how to build and the quality. This skill reads specs; it does not redefine the requirement baseline. Light projects can skip OpenSpec entirely and run on methodology alone.

Part A — Spec-Driven Workflow (the contract layer)

The philosophy

• Fluid, not rigid. Specs evolve; they are not carved in stone. Propose a delta, review it, merge it.
• Iterative, not waterfall. You can go explore → propose → apply → archive more than once for the same feature as understanding grows.
• Brownfield, not just greenfield. An existing project already has specs (even implicit ones). The first job is to make them explicit, not to start over.

The 4-phase loop

You do not need the upstream CLI for the methodology. The phases are a discipline. If you install upstream (npm install -g @fission-ai/openspec), the /opsx:* commands automate the bookkeeping; without it, you follow the same four phases by hand.

The four artifacts (what lives in the repo)

The gate before "Apply"

Do not start apply until:

• The proposal has testable acceptance criteria (not "make it better").
• Repository-answerable questions were answered by reading, not by asking the user.
• The user has reviewed the artifacts or explicitly approved proceeding.

(Same instinct as [[grill-me]] — drive the soft spots into the open before building.)

Directory layout in the repo (reference)

openspec/
├── specs/                 # the living source of truth (current, accumulated)
│   ├── ...
├── changes/               # in-flight and historical proposals
│   ├── <change-id>/       #   proposal.md + specs/ + design.md? + tasks.md
│   └── archive/           #   landed changes, post-merge

Part B — Internal Framework Router (the "use what" layer)

Any time the task touches an internal framework: scaffolding a new service, middleware integration, data access, caching, messaging, permissions, scheduled tasks.

You do not re-derive framework usage here. You route to the right framework skill and follow its conventions. This skill is the switchboard; your framework skills are the destinations. (Single source of truth — their content lives in your skill library, not duplicated here.)

Replace this table with your own framework skills. Placeholder example:

When NOT to route

• Pure business logic with no framework surface → stay in Part A flow.
• The user explicitly says "don't use the framework" → plain implementation.

When to use

• The user invokes it: /openspec, "启用 openspec", "走 spec-driven", "写规格", "提个 proposal".
• Requirements need to survive across sessions, or multiple people/agents must agree on the contract.
• The work touches an internal framework and you need the right module's conventions.

When NOT to use

• Light, single-dev, short-lived work with no cross-session memory needs — methodology layer + [[ponytail]] is enough. Don't pay the spec tax.
• Debugging a concrete bug — use [[superpowers]] §systematic-debugging. (You may read specs to understand intended behavior, but don't run the propose loop mid-bug.)
• The task touches no internal framework module — Part B has nothing to route to; Part A may still apply if you want a contract trail.

Anti-patterns (Never)

• Never redefine the requirement baseline inside this skill — that is OpenSpec's whole job; this skill runs it, and the methodology skills read it.
• Never copy framework-skill content into this skill — single source of truth. Route, don't duplicate. When a framework convention changes upstream, only that framework skill should need updating.
• Never confuse OpenSpec with [[trellis]] — OpenSpec owns the requirement contract (propose → archive a delta); Trellis owns persistence + multi-agent orchestration (spec/task/memory + worker coordination). They can coexist; they are not the same layer.
• Never start apply before the user reviews the proposal artifacts — the whole point is a reviewed contract.
• Never treat specs as immutable once a change lands — archive deliberately rewrites openspec/specs/. Fluid, not rigid.

Collaborates with

• Superpowers methodology layer — orthogonal. OpenSpec = what/contract; [[superpowers]] (its §brainstorming / §writing-plans / §test-driven-development / §verification-before-completion) = how/quality. Per the red line, one owns the baseline, the other owns execution — neither crosses over.
• [[trellis]] — sibling at the engineering-framework tier. Trellis is the persistence + orchestration frame; OpenSpec is the contract layer. For a heavy project you might use both: OpenSpec to negotiate the contract, Trellis to keep it + the tasks + memory coherent across agents.
• [[grill-me]] — the propose phase's interview instinct is the same: drive soft spots into the open before building.
• Framework skills (your-framework-*) — Part B is a router to them; they are the destinations, this skill is the switchboard.