Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runmaestro.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenSpec is a spec-driven development tool from Fission-AI/OpenSpec that ensures alignment between humans and AI coding assistants before any code is written. Maestro bundles these workflow commands and keeps them updated automatically.

​
OpenSpec vs. Spec-Kit

Maestro offers two complementary spec-driven development tools:
FeatureOpenSpecSpec-Kit
FocusChange management & proposalsFeature specifications
WorkflowProposal → Apply → ArchiveConstitution → Specify → Plan → Tasks
Best ForIterative changes, brownfield projectsNew features, greenfield development
OutputChange proposals with spec deltasFeature specifications and task lists
Directoryopenspec/specs/ or project root
Use OpenSpec when:
  • 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
Use Spec-Kit when:
  • Defining new features from scratch
  • Establishing project constitutions and principles
  • Creating detailed feature specifications
  • Breaking down work into implementation tasks
Both tools integrate with Maestro’s Auto Run for autonomous execution.

​
Core Workflow

OpenSpec follows a three-stage cycle:

​
Stage 1: Proposal (/openspec.proposal)

Create a change proposal before writing any code:
  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
Creates: A openspec/changes/<change-id>/ directory with:
  • proposal.md — Why and what
  • tasks.md — Implementation checklist
  • specs/<capability>/spec.md — Spec deltas

​
Stage 2: Apply (/openspec.apply)

Implement the approved proposal:
  1. Reads proposal and tasks
  2. Implements tasks sequentially
  3. Updates task checkboxes as work completes
  4. Ensures approval gate is passed before starting
Tip: Only start implementation after the proposal is reviewed and approved.

​
Stage 3: Archive (/openspec.archive)

After deployment, archive the completed change:
  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
CLI command: openspec archive <change-id> --yes (use --skip-specs for tooling-only changes that don’t affect capabilities)

​
Maestro-Specific Commands

​
/openspec.implement — Generate Auto Run Documents

Bridges OpenSpec with Maestro’s Auto Run:
  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

Get help with OpenSpec concepts and Maestro integration.

​
Directory Structure

OpenSpec uses a clear separation between current truth and proposed changes: 
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

Changes use explicit operation headers: 
## 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

The OpenSpec CLI provides these essential commands:
CommandPurpose
openspec listDisplay active changes in changes/
openspec list --specsList existing capability specs
openspec show <change-id>View change or spec details
openspec validate <change-id> --strictComprehensive validation
openspec archive <change-id> --yesArchive after deployment
openspec spec list --longEnumerate all specifications

​
Viewing & Managing Commands

Access OpenSpec commands via Settings → AI Commands tab. Here you can:
  • 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
Commands marked with a Maestro badge are Maestro-specific additions to the upstream workflow.
OpenSpec commands in the AI Commands panel

​
Auto-Updates

OpenSpec prompts are synced from the Fission-AI/OpenSpec repository:
  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