Commands

This is the reference for OpenSpec's slash commands. These commands are invoked in your AI coding assistant's chat interface (e.g., Claude Code, Cursor, Windsurf).

For workflow patterns and when to use each command, see Workflows. For CLI commands, see CLI.

Quick Reference

Default Quick Path (core profile)

Expanded Workflow Commands (custom workflow selection)

The default global profile is core. To enable expanded workflow commands, run openspec config profile, select workflows, then run openspec update in your project.

Command Reference

/opsx:propose

Create a new change and generate planning artifacts in one step. This is the default start command in the core profile.

Syntax:

/opsx:propose [change-name-or-description]

Arguments:

What it does:

• Creates openspec/changes/<change-name>/
• Generates artifacts needed before implementation (for spec-driven: proposal, specs, design, tasks)
• Stops when the change is ready for /opsx:apply

Example:

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/ui/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation. Run /opsx:apply.

Tips:

• Use this for the fastest end-to-end path
• If you want step-by-step artifact control, enable expanded workflows and use /opsx:new + /opsx:continue

/opsx:explore

Think through ideas, investigate problems, and clarify requirements before committing to a change.

Syntax:

/opsx:explore [topic]

Arguments:

What it does:

• Opens an exploratory conversation with no structure required
• Investigates the codebase to answer questions
• Compares options and approaches
• Creates visual diagrams to clarify thinking
• Can transition to /opsx:propose (default) or /opsx:new (expanded workflow) when insights crystallize

Example:

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?

AI:  Let me investigate your current auth setup...
     [Analyzes codebase]

     I see you're using session-based auth for the web app.
     For mobile, we have three main options:

     1. JWT tokens (stateless, works offline)
     2. OAuth2 (if you need third-party login)
     3. Extend current sessions (simpler, but requires connectivity)

     Your API already has CORS configured. Which direction interests you?

You: Let's go with JWT. Can we start a change for that?

AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.

Tips:

• Use when requirements are unclear or you need to investigate
• No artifacts are created during exploration
• Good for comparing multiple approaches before deciding
• Can read files and search the codebase

/opsx:new

Start a new change scaffold. Creates the change folder and waits for you to generate artifacts with /opsx:continue or /opsx:ff.

This command is part of the expanded workflow set (not included in the default core profile).

Syntax:

/opsx:new [change-name] [--schema <schema-name>]

Arguments:

What it does:

• Creates openspec/changes/<change-name>/ directory
• Creates .openspec.yaml metadata file in the change folder
• Shows the first artifact template ready for creation
• Prompts for change name and schema if not provided

What it creates:

openspec/changes/<change-name>/
└── .openspec.yaml    # Change metadata (schema, created date)

Example:

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.

Tips:

• Use descriptive names: add-feature, fix-bug, refactor-module
• Avoid generic names like update, changes, wip
• Schema can also be set in project config (openspec/config.yaml)

/opsx:continue

Create the next artifact in the dependency chain. Creates one artifact at a time for incremental progress.

Syntax:

/opsx:continue [change-name]

Arguments:

What it does:

• Queries the artifact dependency graph
• Shows which artifacts are ready vs blocked
• Creates the first ready artifact
• Reads dependency files for context
• Shows what becomes available after creation

Example:

You: /opsx:continue

AI:  Change: add-dark-mode

     Artifact status:
     ✓ proposal    (done)
     ◆ specs       (ready)
     ◆ design      (ready)
     ○ tasks       (blocked - needs: specs)

     Creating specs...

     [Reads proposal.md, creates specs based on requirements]

     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md

     Now available: tasks
     Run /opsx:continue to create the next artifact.

Tips:

• Use when you want to review each artifact before proceeding
• Good for complex changes where you want control
• Multiple artifacts may become ready simultaneously
• You can edit created artifacts before continuing

/opsx:ff

Fast-forward through artifact creation. Creates all planning artifacts at once.

Syntax:

/opsx:ff [change-name]

Arguments:

What it does:

• Creates all artifacts in dependency order
• Tracks progress via todo list
• Stops when all apply-required artifacts are complete
• Reads each dependency before creating the next artifact

Example:

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. Run /opsx:apply to begin.

Tips:

• Use when you have a clear picture of what you're building
• Faster than /opsx:continue for straightforward changes
• You can still edit artifacts afterward
• Good for small to medium features

/opsx:apply

Implement tasks from the change. Works through the task list, writing code and checking off items.

Syntax:

/opsx:apply [change-name]

Arguments:

What it does:

• Reads tasks.md and identifies incomplete tasks
• Works through tasks one by one
• Writes code, creates files, runs tests as needed
• Marks tasks complete with checkboxes [x]

Example:

You: /opsx:apply

AI:  Implementing add-dark-mode...

     Reading tasks.md:
     - [ ] 1.1 Create ThemeContext
     - [ ] 1.2 Add CSS custom properties
     - [ ] 1.3 Implement localStorage persistence

     Working on 1.1: Create ThemeContext...
     [Creates src/context/ThemeContext.tsx]

     ✓ 1.1 Complete

     Working on 1.2: Add CSS custom properties...
     [Updates src/styles/globals.css]

     ✓ 1.2 Complete
     ...

Tips:

• Can resume where you left off if interrupted
• Use for parallel changes by specifying the change name
• Completion state is tracked in tasks.md checkboxes

/opsx:verify

Validate that implementation matches your change artifacts. Checks completeness, correctness, and coherence.

Syntax:

/opsx:verify [change-name]

Arguments:

What it does:

• Checks three dimensions of implementation quality
• Searches codebase for implementation evidence
• Reports issues categorized as CRITICAL, WARNING, or SUGGESTION
• Does not block archive, but surfaces issues

Verification dimensions:

Example:

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "System preference detection" has no test coverage

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for system preference detection
     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables

Tips:

• Run before archiving to catch mismatches early
• Warnings don't block archive but indicate potential issues
• Good for reviewing AI's work before committing
• Can reveal drift between artifacts and implementation

/opsx:sync

Optional command. Merge delta specs from a change into main specs. Archive will prompt to sync if needed, so you typically don't need to run this manually.

Syntax:

/opsx:sync [change-name]

Arguments:

What it does:

• Reads delta specs from change folder
• Parses ADDED/MODIFIED/REMOVED/RENAMED sections
• Merges changes into main openspec/specs/ directory
• Preserves existing content not mentioned in delta
• Does not archive the change (remains active)

Example:

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 to complete.

When to use manually:

Tips:

• Sync is intelligent, not copy-paste
• Can add scenarios to existing requirements without duplicating
• Change stays active after sync (not archived)
• Most users will never need to call this directly—archive prompts if needed

/opsx:archive

Archive a completed change. Finalizes the change and moves it to the archive folder.

Syntax:

/opsx:archive [change-name]

Arguments:

What it does:

• Checks artifact completion status
• Checks task completion (warns if incomplete)
• Offers to sync delta specs if not already synced
• Moves change folder to openspec/changes/archive/YYYY-MM-DD-<name>/
• Preserves all artifacts for audit trail

Example:

You: /opsx:archive

AI:  Archiving add-dark-mode...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (8/8 tasks complete)

     Delta specs: Not yet synced
     → Sync now? (recommended)

You: Yes

AI:  ✓ Synced specs to openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/

     Change archived successfully.

Tips:

• Archive won't block on incomplete tasks, but will warn
• Delta specs can be synced during archive or beforehand
• Archived changes are preserved for history
• Use /opsx:verify first to catch issues

/opsx:bulk-archive

Archive multiple completed changes at once. Handles spec conflicts between changes.

Syntax:

/opsx:bulk-archive [change-names...]

Arguments:

What it does:

• Lists all completed changes
• Validates each change before archiving
• Detects spec conflicts across changes
• Resolves conflicts by checking what's actually implemented
• Archives in chronological order

Example:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (8/8 tasks complete)
     - fix-login-bug (3/3 tasks complete)
     - update-footer (2/2 tasks complete)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will merge in chronological order:
     1. add-dark-mode (created Jan 20)
     2. update-footer (created Jan 22)

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-bug
     ✓ Archived update-footer
     Specs merged: add-dark-mode → update-footer

Tips:

• Good for parallel work streams
• Conflict resolution is agentic (checks codebase)
• Changes are archived in order of creation
• Prompts before overwriting spec content

/opsx:onboard

Guided onboarding through the complete OpenSpec workflow. An interactive tutorial using your actual codebase.

Syntax:

/opsx:onboard

What it does:

• Walks through a complete workflow cycle with narration
• Scans your codebase for real improvement opportunities
• Creates an actual change with real artifacts
• Implements actual work (small, safe changes)
• Archives the completed change
• Explains each step as it happens

Phases:

1. Welcome and codebase analysis
2. Finding an improvement opportunity
3. Creating a change (/opsx:new)
4. Writing the proposal
5. Creating specs
6. Writing the design
7. Creating tasks
8. Implementing tasks (/opsx:apply)
9. Verifying implementation
10. Archiving the change
11. Summary and next steps

Example:

You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)

Tips:

• Best for new users learning the workflow
• Uses real code, not toy examples
• Creates a real change you can keep or discard
• Takes 15-30 minutes to complete

Command Syntax by AI Tool

Different AI tools use slightly different command syntax. Use the format that matches your tool:

The intent is the same across tools, but how commands are surfaced can differ by integration.

Note: GitHub Copilot commands (.github/prompts/*.prompt.md) are only available in IDE extensions (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI does not currently support custom prompt files — see Supported Tools for details and workarounds.

Legacy Commands

These commands use the older "all-at-once" workflow. They still work but OPSX commands are recommended.

When to use legacy commands:

• Existing projects using the old workflow
• Simple changes where you don't need incremental artifact creation
• Preference for the all-or-nothing approach

Migrating to OPSX: Legacy changes can be continued with OPSX commands. The artifact structure is compatible.

Troubleshooting

"Change not found"

The command couldn't identify which change to work on.

Solutions:

• Specify the change name explicitly: /opsx:apply add-dark-mode
• Check that the change folder exists: openspec list
• Verify you're in the right project directory

"No artifacts ready"

All artifacts are either complete or blocked by missing dependencies.

Solutions:

• Run openspec status --change <name> to see what's blocking
• Check if required artifacts exist
• Create missing dependency artifacts first

"Schema not found"

The specified schema doesn't exist.

Solutions:

• List available schemas: openspec schemas
• Check spelling of schema name
• Create the schema if it's custom: openspec schema init <name>

Commands not recognized

The AI tool doesn't recognize OpenSpec commands.

Solutions:

• Ensure OpenSpec is initialized: openspec init
• Regenerate skills: openspec update
• Check that .claude/skills/ directory exists (for Claude Code)
• Restart your AI tool to pick up new skills

Artifacts not generating properly

The AI creates incomplete or incorrect artifacts.

Solutions:

• Add project context in openspec/config.yaml
• Add per-artifact rules for specific guidance
• Provide more detail in your change description
• Use /opsx:continue instead of /opsx:ff for more control

Next Steps

• Workflows - Common patterns and when to use each command
• CLI - Terminal commands for management and validation
• Customization - Create custom schemas and workflows