Skip to content

DETAILS.md

Latest commit

 

History

History
192 lines (132 loc) · 5.3 KB

DETAILS.md

File metadata and controls

192 lines (132 loc) · 5.3 KB
Raw

OpenSpec Details

This file contains more details and OpenSpec reference material.

What This Setup Does

This guide covers the practical OpenSpec loop for planning, implementing, verifying, and archiving agent-driven changes.

  • Separates current behavior from proposed changes: current specs live in openspec/specs/, active changes live in openspec/changes/
  • Uses specs for behavior: product requirements belong in spec files, not hidden inside task checklists
  • Uses tasks for execution: tasks.md tells the agent what to implement and in what order
  • Keeps changes reviewable: one OpenSpec change should be small enough to validate, test, and archive as one unit

Mental Model

OpenSpec separates the current system from proposed changes.

openspec/
  specs/      # current source of truth
  changes/    # proposed changes in progress

A change usually looks like this:

openspec/changes/add-feature/
  proposal.md
  design.md
  tasks.md
  specs/
    feature/spec.md

Use this meaning:

File Purpose
proposal.md Why this change exists and what it should include
specs/ Product behavior and requirements being added or changed
design.md Technical approach and important decisions
tasks.md Implementation checklist for the agent

The important rule:

specs define behavior
tasks define execution

If something in tasks.md changes how the product behaves, it should also be represented in specs/.

Creating a Change

When the scope is clear, run this inside the AI coding assistant chat:

/opsx:propose add-feature-name

This should create:

openspec/changes/add-feature-name/
  proposal.md
  design.md
  tasks.md
  specs/

Review the generated files before implementation.

Exploring First

Use this when the work is not clear yet:

/opsx:explore

Good for:

  • understanding the codebase
  • comparing options
  • shaping a fuzzy idea into a concrete change
  • deciding the right implementation order

No code should be written during exploration.

Working With Large Projects

For a full project, do not create one giant change.

Prefer several ordered changes:

foundation-001
data-model-002
domain-logic-003
ui-shell-004
feature-workflow-005
polish-006
verification-007

Then execute them in that order:

/opsx:apply foundation-001
/opsx:archive foundation-001

/opsx:apply data-model-002
/opsx:archive data-model-002

Use numeric suffixes when order matters. OpenSpec change names must start with a letter.

The order is not automatically taken from every tasks.md file. The order should be made explicit through change names, dependencies, or your own project plan.

Good Change Size

A good OpenSpec change should be small enough to review and archive as one unit.

Good examples:

add-password-reset
create-billing-schema
implement-approval-flow
add-dashboard-filters

If a change has many unrelated sections in tasks.md, split it into smaller changes before implementation.

Common Checks Before Apply

Before running /opsx:apply, ask:

Review this OpenSpec change before implementation.

Check tasks.md against proposal.md, design.md, and specs/.
If tasks.md contains behavior or acceptance criteria missing from specs, update the spec delta first.
If it is only implementation detail, leave it in tasks.md.

Do not implement code yet.

Then apply only when the artifacts look correct.

Common Mistakes

Archiving Too Early

Do not archive until the whole change is implemented.

If only half of tasks.md is complete, keep the change active.

Letting Tasks Become Hidden Specs

Implementation details can live only in tasks.md.

Product behavior should live in specs/.

Keeping Huge Changes

If one change contains a full project, split it into smaller ordered changes.

Useful Commands

Command Where Use
openspec init Terminal Initialize OpenSpec in a project
openspec update Terminal Regenerate assistant instruction files after config or CLI changes
openspec list Terminal List active changes
openspec show <change> Terminal Inspect a change
openspec validate <change> Terminal Validate formatting and structure
openspec archive <change> Terminal Archive a completed change from the CLI
/opsx:explore AI chat Think before creating artifacts
/opsx:propose <change> AI chat Create a new change
/opsx:apply <change> AI chat Implement a change
/opsx:archive <change> AI chat Finalize and archive a completed change

The default OpenSpec profile includes /opsx:explore, /opsx:propose, /opsx:apply, /opsx:sync, and /opsx:archive. Expanded workflow commands such as /opsx:verify, /opsx:new, /opsx:continue, and /opsx:ff can be enabled with openspec config profile and openspec update.

References