OpenSpec Advanced: From Core to Expanded – Unlock All Workflows with 7 Commands

Core profile commands

The default Core profile provides four commands: /opsx:propose – create a change and generate all planning artifacts (proposal, specs, design, tasks). /opsx:explore – free‑form discussion to brainstorm before coding. /opsx:apply – execute tasks and write code. /opsx:archive – archive a completed change.

The workflow is simply /opsx:propose → /opsx:apply → /opsx:archive, suitable for small, well‑scoped changes.

Limitations of the Core profile

Cannot review artifacts step‑by‑step because /opsx:propose generates all files at once.

No built‑in verification of implementation against specifications.

Parallel changes require manual, sequential archiving.

Workflow pace is binary – either generate everything or nothing.

Enabling the Expanded workflow

According to the official documentation, enable the expanded profile in two steps:

# Step 1: select expanded profile
openspec config profile

# Step 2: refresh AI assistant commands
openspec update

Running openspec config profile opens an interactive selector where you choose expanded . After openspec update, the AI assistant recognises the new commands.

Expanded workflow commands

/opsx:new

– create a change scaffold (directory and metadata) without generating any artifacts. /opsx:continue – stepwise creation of artifacts following the dependency DAG. /opsx:ff – fast‑forward: generate all artifacts in one go (similar to core /opsx:propose). /opsx:verify – three‑dimensional check (Completeness, Correctness, Coherence) of implementation against specs. /opsx:sync – manually merge incremental specs into the main spec (optional; archive usually prompts automatically). /opsx:bulk-archive – archive multiple completed changes at once, with conflict detection. /opsx:onboard – interactive tutorial that scans the codebase and walks you through a full change.

/opsx:new – Change scaffold

Creates openspec/changes/<change-name>/ and a .openspec.yaml metadata file, then lists available artifact templates.

You: /opsx:new add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
      Schema: spec-driven
      Ready to create: proposal
      Use /opsx:continue to create it, or /opsx:ff to create all artifacts.

Supported options include --schema <name> to select a different workflow schema.

/opsx:continue – Stepwise artifact creation

Queries the artifact dependency graph, shows each artifact’s status ( ✓ done, ◆ ready, ○ blocked), creates the next ready artifact, and unlocks downstream artifacts.

You: /opsx:continue

AI:  Change: add-dark-mode
    Artifact status:
    ✓ proposal   (done)
    ◆ specs      (ready)
    ◆ design     (ready)
    ○ tasks      (blocked - needs: specs)

    Creating specs...
    ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md
    Now available: tasks
    Run /opsx:continue to create the next artifact.

Workflow steps:

Query the dependency graph to find ready artifacts.

Display the status of all artifacts.

Create the first ready artifact.

After creation, display newly unlocked artifacts.

This fine‑grained control lets you pause after generating specs to review them before proceeding.

/opsx:ff – Fast‑forward all artifacts

Equivalent to core /opsx:propose but works in expanded mode. Generates all planning artifacts in dependency order.

You: /opsx:ff add-dark-mode

AI:  Fast‑forwarding add‑dark‑mode...
    ✓ Creating proposal.md
    ✓ Creating specs/ui/spec.md
    ✓ Creating design.md
    ✓ Creating tasks.md
    All planning artifacts complete! Ready for implementation.

Use /opsx:ff when the full scope is known up front or when time is limited.

/opsx:verify – Implementation validation

Checks three dimensions:

Completeness – all tasks, requirements, and scenarios are covered.

Correctness – implementation matches spec intent and handles edge cases.

Coherence – design decisions are reflected in code structure and naming.

You: /opsx:verify

AI:  Verifying add-auth...
    COMPLETENESS
    ✓ All 12 tasks checked
    ✓ All requirements have code
    ⚠ Scenario "Session timeout" not tested
    CORRECTNESS
    ✓ Implementation matches spec intent
    ✓ Edge cases handled
    COHERENCE
    ✓ Design reflected in code
    ⚠ Design mentions "event‑driven" but implementation uses polling
    SUMMARY
    Critical issues: 0, Warnings: 2, Ready to archive: Yes (with warnings)

The command does not block archiving; it surfaces mismatches early so you can decide whether to address them before /opsx:archive.

/opsx:sync – Incremental spec merge

Manually merges delta specs into the main spec while keeping the change active for further work. Useful for long‑running changes, parallel changes that share an updated spec, or isolated spec review.

You: /opsx:sync

AI:  Syncing add-dark-mode delta specs...
    Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
    Target:  openspec/specs/ui/spec.md
    Changes to apply:
    ✓ ADDED: Theme Selection requirement (2 scenarios)
    ✓ ADDED: Accessibility requirement (1 scenario)
    Merging...
    ✓ openspec/specs/ui/spec.md updated
    Change remains active. Run /opsx:archive when ready.

Typical scenarios that require manual sync:

Long‑running change that needs the main spec updated before archiving.

Multiple parallel changes need a shared updated spec.

Separate review of the merged result.

/opsx:bulk-archive – Batch archiving

Detects spec conflicts across multiple completed changes and archives them in creation order.

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
    - add-dark-mode (all tasks done)
    - fix-login-redirect (all tasks done)
    - update-footer (all tasks done)
    Checking for spec conflicts...
    ⚠ add-dark-mode and update-footer both touch specs/ui/
    Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
    ✓ Archived fix-login-redirect
    ✓ Archived update-footer
    Specs merged in order: add-dark-mode → update-footer

The conflict‑detection logic merges changes chronologically, which is safer than a naïve text merge.

/opsx:onboard – Interactive tutorial

Scans the repository, presents a real‑code change flow, and explains each step. The tutorial takes about 15‑30 minutes and is intended for newcomers to the expanded workflow.

Workflow modes

Quick Feature –

/opsx:new → /opsx:ff → /opsx:apply → /opsx:verify → /opsx:archive

. For clear, small features.

Exploratory –

/opsx:explore → /opsx:new → /opsx:continue … → /opsx:apply

. For vague requirements; /opsx:explore is a free‑form AI discussion.

Parallel Changes – multiple changes each with their own folder; switch with /opsx:apply <change-name> and finish with /opsx:bulk‑archive.

Completing a Change – /opsx:apply → /opsx:verify → /opsx:archive. Recommended final flow.

Decision framework: ff vs. continue

If you can describe the complete range up front, choose /opsx:ff . If you need to clarify requirements on the fly, choose /opsx:continue .

When to update an existing change vs. start a new one

Update existing when the intent stays the same, the scope shrinks, or implementation reveals needed adjustments.

Start a new change when the intent fundamentally changes, the scope expands to a different work area, or the current change can be completed and archived independently.

This mirrors Git branching: continue committing to the same branch for incremental work, create a new branch for divergent work.

Artifact dependency DAG

The default spec‑driven schema defines a DAG where specs and design both depend on proposal, and tasks depend on both specs and design. The DAG enables parallel creation of specs and design while enforcing that tasks wait for both.

proposal (root)
               │
      ┌────────┴────────┐
      │                 │
   specs             design
      │                 │
      └───────┬───────┘
              │
            tasks

Artifact statuses:

BLOCKED – a predecessor is not yet completed.

READY – all dependencies are satisfied; the artifact can be generated.

DONE – the artifact file exists.

Because specs and design both only depend on proposal, they can be generated in parallel. tasks must wait until both are DONE.

Custom schemas

If the default chain does not fit, you can fork an existing schema or create one from scratch.

# Fork spec‑driven as a starting point
openspec schema fork spec-driven my-workflow

# Interactive creation of a new schema
openspec schema init research-first

Example of a minimal "rapid" schema that only includes proposal and tasks:

name: rapid
version: 1
description: Fast iteration with minimal overhead
artifacts:
- id: proposal
  generates: proposal.md
  description: Quick proposal
  template: proposal.md
  instruction: |
    Create a brief proposal for this change.
    Focus on what and why, skip detailed specs.
  requires: []
- id: tasks
  generates: tasks.md
  description: Implementation checklist
  template: tasks.md
  requires: [proposal]
apply:
  requires: [tasks]
  tracks: tasks.md

Validate a schema with:

openspec schema validate my-workflow

Core vs. Expanded side‑by‑side comparison

Command count : Core 4 vs. Expanded 11 (includes core commands).

Artifact creation : Core generates all at once; Expanded allows stepwise or fast‑forward.

Implementation verification : Only Expanded provides /opsx:verify.

Parallel change management : Only Expanded offers /opsx:bulk‑archive.

Spec sync : Core handles it automatically on archive; Expanded lets you run /opsx:sync manually.

Onboarding tutorial : Only Expanded includes /opsx:onboard.

Typical scenarios : Core – small, well‑defined features; Expanded – complex changes, parallel development, verification needs.

Official guidance: start new projects with Core; switch to Expanded when Core cannot satisfy the workflow requirements. Switching does not require migration because the artifact structures are compatible.

Best practices

Keep change granularity small – one change should do one thing.

Use meaningful change names (e.g., add-dark-mode) for clear openspec list output.

Run /opsx:verify before /opsx:archive to surface mismatches early.

Use /opsx:explore during the discovery phase; only create a change after the idea is clarified.

When working on parallel changes, watch for spec conflicts; /opsx:bulk‑archive helps resolve them.

Clear the AI assistant’s context window before starting a new change to avoid cross‑talk.

Resources

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

Workflows documentation: https://github.com/Fission-AI/OpenSpec/blob/main/docs/workflows.md

Commands reference: https://github.com/Fission-AI/OpenSpec/blob/main/docs/commands.md

Customization guide: https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md

Discord community: https://discord.gg/YctCnvvshC