From Stages to Actions: A Complete Guide to the New AI‑Driven OpenSpec OPSX Workflow

OPSX Overview

OPSX replaces the fixed stage‑locked workflow of OpenSpec with an action‑first model. Development is expressed as a chain of actions that can be executed at any time, keeping the specification (Spec) an active part of the loop.

Core ideas

Action‑first, not stage‑first.

Dependencies connect information rather than constrain flow.

Progressive generation – generate one artifact, review, then decide the next step.

Easy iteration – modify design.md or tasks.md mid‑process and continue without restarting.

Highly customizable via schema.yaml and Markdown templates.

Transparent – adjust prompts or templates when AI output is unsatisfactory.

Why the classic stage‑based flow fails

The linear pipeline PLANNING → IMPLEMENTING → DONE locks the process. Once in the implementation stage, returning to design or adjusting requirements is difficult, leading to manual file edits, abandoned flows, or blind continuation.

OPSX solution

proposal ──► specs ──► design ──► tasks ──► implement
   ▲          ▲          ▲          │
   └──────────┴──────────┴───────────
   Continuous updates and iteration

Operation modes

Default Quick Path (core profile)

Designed for clear, small‑to‑medium features. Provides four core commands: /opsx:explore – exploratory research when requirements are vague. /opsx:propose – creates proposal, spec, design, and task list in one step. /opsx:apply – executes tasks sequentially. /opsx:archive – archives the change and merges the spec.

Expanded Path (custom workflow)

For complex or fine‑grained control. Additional commands: /opsx:new – scaffold a new change. /opsx:ff – fast‑forward: generate all planning documents at once. /opsx:continue – create the next artifact step‑by‑step. /opsx:verify – check implementation against the spec. /opsx:bulk-archive – archive multiple changes together. /opsx:onboard – guide new team members.

Choosing a mode

Need fine‑grained control?
│
├─ Yes → Enable Expanded Path
│   │
│   Is the requirement clear?
│   │
│   ├─ Yes → /opsx:new + /opsx:ff
│   └─ No  → /opsx:new + /opsx:continue
│
└─ No → Use Default Quick Path
    │
    Need to explore first?
    │
    ├─ Yes → /opsx:explore → /opsx:propose
    └─ No  → /opsx:propose

Workflow modes in detail

Exploratory development

When the problem space is unclear, start with /opsx:explore. The AI researches, produces a brief analysis, and feeds the result into the next steps.

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Fast feature development

For well‑defined requirements, use /opsx:ff to generate all planning artifacts at once, then run /opsx:apply to implement.

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Parallel change management

Multiple changes can run side‑by‑side. OPSX tracks context for each change, allowing seamless switches.

Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                               │
                               └─ Context switch
Change B: /opsx:new ──► /opsx:ff ──► /opsx:apply

Quick‑start guide

1. Install and initialize

# Global install OpenSpec
npm install -g @fission-ai/openspec@latest

# Verify installation
openspec --version

# Enter project directory
cd your-project

# Initialize OpenSpec
openspec init

During initialization you will be asked which AI tool you use; the answer is stored in openspec/config.yaml and drives prompt generation.

2. Project configuration (optional)

openspec/config.yaml

contains three main sections:

schema – default schema name (e.g., spec-driven).

context – project‑level information injected into every prompt (keep concise, under 50 KB).

rules – defines each artifact’s generation rule (id, generates, template, instruction, requires).

3. Full example – adding Dark Mode

Create a proposal /opsx:propose add-dark-mode This creates proposal.md, a spec delta under specs/ui/spec.md, and tasks.md.

Implement /opsx:apply The tool follows the ordered tasks in tasks.md. If a design issue is discovered, edit design.md or tasks.md and rerun /opsx:apply; OPSX resumes from the interruption point.

Verify /opsx:verify Verification checks three dimensions:

Completeness – all tasks finished, requirements covered.

Correctness – implementation matches spec intent, edge cases handled.

Consistency – design decisions reflected in code structure.

Archive /opsx:archive Archiving stores the proposal, design, tasks, and spec delta, then merges the final spec into specs/ as part of the project’s current state.

Custom schema – when the default profile isn’t enough

Fork an existing schema

# Fork spec-driven schema
openspec schema fork spec-driven my-workflow

This creates openspec/schemas/my-workflow/ with schema.yaml and template files. Edit schema.yaml to add or remove artifacts, change dependencies, or adjust prompts.

Create a schema from scratch

# Interactive creation
openspec schema init research-first

# Or with flags
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Schema field reference

id – unique artifact identifier.

generates – output file pattern (e.g., specs/**/*.md).

template – Markdown template used for generation.

instruction – prompt sent to the AI.

requires – list of dependent artifacts that must exist first.

Validate a schema

openspec schema validate my-workflow

Validation checks YAML syntax, template existence, circular dependencies, and artifact IDs.

Use a custom schema

# Specify schema when creating a change
openspec new change feature --schema my-workflow

# Or set as default in config.yaml
schema: my-workflow

Debug schema resolution

# Show which schema is active
openspec schema which my-workflow

# List all available schemas
openspec schema which --all

Best practices – updating vs. creating a new change

A decision matrix helps decide whether to continue updating the current change or start a new one. Four dimensions are considered:

Intent – same problem vs. different goal.

Overlap – code/spec overlap.

Scope – size of work change.

Independence – can the original change be completed alone?

Case 1 – Dark mode → custom theme : scope expands → create new change.

Case 2 – API performance tweak : same intent, implementation tweak → update existing change.

Case 3 – User auth → OAuth later : independent feature → archive first change, then start new one.

Team adoption checklist

Introduce OPSX with a small pilot.

Collect project‑level context and add it to config.yaml.

Start with the built‑in spec-driven schema.

Iteratively customize the schema to match team needs.

Make proposal and spec reviews part of the development gate.

Common pitfalls

Over‑customizing the schema re‑introduces heavyweight processes.

Bloated context (over 50 KB) hurts AI output; keep it concise.

Skipping artifact review reduces traceability.

Unmanaged changes/ directory leads to clutter; regularly archive or clean up stale changes.

Migration from the old OpenSpec workflow

Run openspec init or openspec update. The tool detects legacy files, removes obsolete directories, strips OpenSpec markers from old markdown files, and creates a fresh .claude/skills/ structure. Use --force for non‑interactive CI environments. openspec init --force --tools claude After migration, verify the new schema, run a quick /opsx:propose test, and continue with the new workflow.

Repository

GitHub: https://github.com/Fission-AI/OpenSpec