OpenSpec Spec-Driven Development Assistant

Core Principles

• Flow over Rigidity - Handle any artifact at any time, no phase gates
• Iteration over Waterfall - Refine understanding while building
• Simplicity over Complexity - Minimize setup and ceremony
• Brownfield First - Modify existing systems in a Delta approach

Trigger Scenarios

Explicit Triggers

• User mentions "openspec", "opsx"
• User uses

  /opsx:*

  slash commands
• User mentions "spec-driven development" or "spec-driven"
• User asks how to manage requirements or specification documents

Contextual Triggers

• Before a user starts new feature development (recommend using OpenSpec)
• User complains about AI misunderstanding or frequent rework
• User asks how to make AI understand requirements more accurately
• User needs to generate technical documents or design documents

Project Phase Triggers

• Project initialization phase (recommend configuring OpenSpec)
• Preparing for major refactoring (recommend writing specs first)
• Team collaboration scenarios (need unified requirement descriptions)
• Before developing complex features (need to clarify requirement boundaries)

Applicable Scenarios

• Improve existing projects (brownfield development)
• Critical features requiring high-quality implementation
• Team collaborative development
• Projects requiring long-term maintenance

• Rapid prototype verification (0→1 exploration)
• One-off small scripts
• Innovative exploration with extremely unclear requirements

Directory Structure

openspec/
├── config.yaml           # Project configuration (optional)
├── specs/                # Current system behavior (source of truth)
│   ├── auth.md
│   └── api.md
├── changes/              # Active changes
│   └── add-feature/
│       ├── .openspec.yaml
│       ├── proposal.md
│       ├── specs/
│       ├── design.md
│       └── tasks.md
├── archive/              # Archived changes
│   └── 2025-01-23-add-feature/
└── schemas/              # Custom workflows (optional)
    └── my-workflow/
        ├── schema.yaml
        └── templates/

Slash Commands

/opsx:explore

/opsx:new

/opsx:continue

/opsx:ff

/opsx:apply

/opsx:verify

/opsx:sync

/opsx:archive

/opsx:bulk-archive

/opsx:onboard

CLI Commands

openspec init                              # Initialize project
openspec update                            # Update instruction files
openspec list                              # List active changes
openspec show <name>                       # View change details
openspec validate <name> --strict          # Strict format validation
openspec status --change <name>            # View artifact status
openspec archive <name> --yes              # Archive change
openspec schemas                           # List available schemas
openspec schema init <name>                # Create custom schema
openspec schema fork <source> <name>       # Copy existing schema

Workflow Modes

Quick Feature Flow

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

Exploratory Flow

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

Incremental Flow

/opsx:new → /opsx:continue (repeat) → /opsx:apply → /opsx:archive

Artifact System

Default Schema: spec-driven

proposal → specs → design → tasks → implement
          ↓
       design

BLOCKED → READY → DONE
   ↓         ↓       ↓
Missing dependencies  Dependencies completed  File exists

Artifact Types

1. proposal.md - Change Proposal (Why/What/Impact)
2. specs/ - Delta Specs (ADDED/MODIFIED/REMOVED)
3. design.md - Technical Design
4. tasks.md - Task List (with checkboxes)

Delta Specs Format

## ADDED Requirements

### Requirement: New Feature Name

The system MUST provide [feature description].

#### Scenario: Scenario Name

- **WHEN** Precondition
- **THEN** Expected result
- **AND** Additional conditions

## MODIFIED Requirements

### Requirement: Modified Feature

- **Change Description**: Specific changes
- **Reason**: Reason for modification
- **Impact Scope**: Affected areas

## REMOVED Requirements

### Requirement: Deprecated Feature

- **Reason**: Deprecation reason
- **Migration**: Migration path

Format Requirements

1. Delta sections use English headings (ADDED/MODIFIED/REMOVED)
2. Requirements must include MUST/SHALL/SHOULD keywords
3. Scenarios use English Gherkin keywords (GIVEN/WHEN/THEN/AND)
4. Each Requirement has at least one Scenario
5. REMOVED sections must provide Reason and Migration

Project Configuration

config.yaml

schema: spec-driven # Default schema

context: | # Context injected into all artifacts
  Tech stack: TypeScript, React, Node.js
  Testing: Vitest
  Style: ESLint + Prettier

rules: # Specific rules per artifact
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Include sequence diagrams

Schema Priority

1. CLI flag:

   --schema <name>

2. Change metadata:

   .openspec.yaml

3. Project configuration:

   openspec/config.yaml

4. Default value:

   spec-driven

Custom Schema

Create New Schema

openspec schema init my-workflow
# Or based on existing schema
openspec schema fork spec-driven my-workflow

Schema Structure

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: Custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    template: proposal.md
    requires: []

  - id: tasks
    generates: tasks.md
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Template Example

<!-- templates/proposal.md -->

## Why

<!-- Why this change is needed -->

## What Changes

<!-- Specific change content -->

## Impact

<!-- Impact scope -->

Verification Command

/opsx:verify

• Completeness - All tasks completed, requirements implemented
• Correctness - Matches specification intent, handles edge cases
• Coherence - Design decisions reflected in code

Updates and Iterations

When to Update Existing Changes

• Same intent, optimized execution
• Scope reduction (MVP first)
• Learning-driven corrections

When to Initiate New Changes

• Fundamental change in intent
• Explosive scope growth
• Original change can be completed independently

Judgment Heuristics

Same intent? → YES: UPDATE / NO: NEW
>50% overlap?→ YES: UPDATE / NO: NEW
Original can be completed?→ NO: UPDATE / YES: NEW

Notes for Executing Long Tasks

1. Update task files promptly - Update

   tasks.md

   immediately after completing a task
2. Parallel sub-agents - Launch multiple sub-agents to complete tasks by module
3. Reply in Chinese - Always respond to users in Chinese
4. Re-read task requirements - Re-read specifications after context merging
5. Continuous execution - Complete all tasks in

   tasks.md

   at once
6. No batch scripts - Use specific file edits instead of batch script modifications
7. Master-slave agent scheduling:
   • Master agent: Read all tasks, assign to sub-agents, monitor feedback
   • Sub agents: Strictly complete tasks as required by the master agent

Troubleshooting

Command Unavailable

# Check installation
openspec --version

# Reinstall
npm install -g @fission-ai/openspec@latest

# Refresh instructions
openspec update

Artifact State Issues

# View status
openspec status --change <name> --json

# Validate format
openspec validate <name> --strict

Archive Failure

1. First run

   openspec validate <name> --strict

2. Check if the

   specs/

   directory has content
3. Resolve Git conflicts and retry

Environment Variables

• OPENSPEC_CONCURRENCY

  - Number of parallel verifications (default: 6)

• OPENSPEC_TELEMETRY=0

  - Disable telemetry

• NO_COLOR

  - Disable color output

Reference Resources

• OpenSpec Repository: https://github.com/Fission-AI/OpenSpec
• OPSX Workflow: https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md
• CLI Reference: https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md
• Custom Configuration: https://github.com/Fission-AI/OpenSpec/blob/main/docs/customization.md