SDD Catalog
Execution Workflow Fission-AI MIT

OpenSpec

Lightweight, brownfield-first SDD layer where humans and AI agents agree on written specs (requirements + scenarios) before code, using delta-based change proposals (ADDED/MODIFIED/REMOVED) that merge into a canonical spec set on archive. Current workflow surface is branded OPSX.

Repository Documentation

Detection

A project uses OpenSpec when any of these exist:

  • openspec/
  • openspec/config.yaml
  • openspec/specs/
  • openspec/changes/
  • openspec/specs/*/spec.md

Status Model

Method: dir-state

A change directly under openspec/changes/ is active; under openspec/changes/archive/ it is done (date-prefixed). For an active change, "openspec status --change <id> --json" reports each planning artifact as done/ready/blocked; implementation progress comes from tasks.md checkbox counts. Roll up: count active vs archived changes and specs/*/spec.md.

Lifecycle

  1. 1
    Init openspec init

    Scaffold the openspec/ directory and config.

  2. 2
    Explore /opsx:explore

    Optional shaping/thinking step before proposing (no structured output).

  3. 3
    Propose /opsx:propose

    Open a change — proposal, delta specs, optional design, and tasks.

  4. 4
    Apply /opsx:apply

    Implement the change, checking off tasks as code is written.

  5. 5
    Archive openspec archive

    Merge delta specs into the canonical specs and move the change to archive/.

On-Disk Artifacts

openspec/config.yaml config Project config — schema, context, and per-artifact rules injected into generation.
openspec/specs/<capability>/spec.md spec Canonical, agreed-upon behavior — the source of truth (Requirements + WHEN/THEN scenarios). Maps to SPEC.
openspec/changes/<change-id>/proposal.md proposal The why + what of a change (intent, scope, capabilities, impact). Maps to PRD.
openspec/changes/<change-id>/specs/<capability>/spec.md spec Delta specs — ADDED/MODIFIED/REMOVED/RENAMED requirement sections.
openspec/changes/<change-id>/design.md design Technical how — context, decisions, risks, migration (optional).
openspec/changes/<change-id>/tasks.md tasks Implementation checklist ("- [ ] N.M" checkboxes).
openspec/changes/archive/<YYYY-MM-DD-change-id>/ proposal Completed changes, date-prefixed, retained for history.

Fed by Definition Workflows

Big Tech Product → OpenSpec A Big Tech product definition produces a PRD and six-pager; OpenSpec's /opsx:propose consumes them into a change proposal, then delta specs, tasks, and implementation, archiving into the canonical capability specs.