> ## Documentation Index > Fetch the complete documentation index at: https://runmaestro-feat-autonomous-manager-agent.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # OpenSpec Commands > Spec-driven development workflow for managing code changes with AI-assisted proposal, implementation, and archival. OpenSpec is a spec-driven development tool from [Fission-AI/OpenSpec](https://github.com/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: | Feature | OpenSpec | Spec-Kit | | ------------- | -------------------------------------- | ------------------------------------- | | **Focus** | Change management & proposals | Feature specifications | | **Workflow** | Proposal → Apply → Archive | Constitution → Specify → Plan → Tasks | | **Best For** | Iterative changes, brownfield projects | New features, greenfield development | | **Output** | Change proposals with spec deltas | Feature specifications and task lists | | **Directory** | `openspec/` | `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 --strict` **Creates:** A `openspec/changes//` directory with: * `proposal.md` - Why and what * `tasks.md` - Implementation checklist * `specs//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//` to `changes/archive/YYYY-MM-DD-/` 2. Updates source-of-truth specs if capabilities changed 3. Validates the archived change with `openspec validate --strict` **CLI command:** `openspec archive --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--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 │ └── / │ ├── spec.md # Requirements and scenarios │ └── design.md # Technical patterns └── changes/ # Proposals - what SHOULD change ├── / │ ├── 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: ```markdown theme={null} ## 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: | Command | Purpose | | ---------------------------------------- | ------------------------------------ | | `openspec list` | Display active changes in `changes/` | | `openspec list --specs` | List existing capability specs | | `openspec show ` | View change or spec details | | `openspec validate --strict` | Comprehensive validation | | `openspec archive --yes` | Archive after deployment | | `openspec spec list --long` | Enumerate 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](https://github.com/Fission-AI/OpenSpec): 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 --strict` before sharing * **Archive promptly** - Archive changes after deployment to keep `changes/` clean