OpenSpec Commands

​

OpenSpec vs. Spec-Kit

• Making iterative changes to existing features
• You need explicit change proposals before implementation
• Working on brownfield projects with existing specifications
• You want a clear archive of completed changes

• Defining new features from scratch
• Establishing project constitutions and principles
• Creating detailed feature specifications
• Breaking down work into implementation tasks

​

Core Workflow

​

Stage 1: Proposal (/openspec.proposal)

1. Reviews openspec/project.md for project conventions
2. Runs openspec list to see active changes and openspec list --specs for existing capabilities
3. Scaffolds proposal.md, tasks.md, and optional design.md
4. Creates spec deltas showing what will be ADDED, MODIFIED, or REMOVED
5. Validates with openspec validate <change-id> --strict

• proposal.md - Why and what
• tasks.md - Implementation checklist
• specs/<capability>/spec.md - Spec deltas

​

Stage 2: Apply (/openspec.apply)

1. Reads proposal and tasks
2. Implements tasks sequentially
3. Updates task checkboxes as work completes
4. Ensures approval gate is passed before starting

​

Stage 3: Archive (/openspec.archive)

1. Moves changes/<name>/ to changes/archive/YYYY-MM-DD-<name>/
2. Updates source-of-truth specs if capabilities changed
3. Validates the archived change with openspec validate --strict

​

Maestro-Specific Commands

​

/openspec.implement - Generate Auto Run Documents

1. Reads the proposal and tasks from a change
2. Converts tasks into Auto Run document format with phases
3. Saves to .maestro/playbooks/ with task checkboxes (filename: OpenSpec-<change-id>-Phase-XX-[Description].md)
4. Preserves task IDs (T001, T002, etc.) for traceability
5. Groups related tasks into logical phases (5-15 tasks each)

​

/openspec.help - Workflow Overview

​

Directory Structure

openspec/
├── project.md              # Project conventions
├── specs/                  # Current truth - what IS built
│   └── <capability>/
│       ├── spec.md         # Requirements and scenarios
│       └── design.md       # Technical patterns
└── changes/                # Proposals - what SHOULD change
    ├── <change-name>/
    │   ├── proposal.md     # Why, what, impact
    │   ├── tasks.md        # Implementation checklist
    │   └── specs/          # Spec deltas (ADDED/MODIFIED/REMOVED)
    └── archive/            # Completed changes

​

Spec Delta Format

## ADDED Requirements

### Requirement: New Feature

The system SHALL provide...

#### Scenario: Success case

- **WHEN** user performs action
- **THEN** expected result

## MODIFIED Requirements

### Requirement: Existing Feature

[Complete updated requirement text]

## REMOVED Requirements

### Requirement: Old Feature

**Reason**: [Why removing]
**Migration**: [How to handle]

​

OpenSpec CLI Commands

​

Viewing & Managing Commands

• View all commands - Click the chevron to expand and see the full prompt
• Check for Updates - Pull the latest workflow from GitHub
• Edit prompts - Customize prompts for your workflow
• Reset to default - Restore modified prompts to bundled version

​

Auto-Updates

1. Open Settings → AI Commands
2. Click Check for Updates in the OpenSpec section
3. New workflow improvements are downloaded
4. Your custom modifications are preserved

​

Tips for Best Results

• Proposal first - Never start implementation without an approved proposal
• Keep changes focused - One logical change per proposal
• Use verb-led IDs - add-user-auth, update-api-schema, remove-legacy-handler
• Include scenarios - Every requirement needs at least one #### Scenario: block
• Check existing work - Run openspec list before creating proposals to avoid conflicts
• Validate early - Run openspec validate <change-id> --strict before sharing
• Archive promptly - Archive changes after deployment to keep changes/ clean