Openspec Integration

OpenSpec Integration Skill

When to Use

This skill auto-activates when:

• openspec/ directory detected in project
• User is working on API specifications
• SDD workflow needs spec format
• Part of the unified workflow

Overview

OpenSpec is a fluid, iterative approach to API specification that emphasizes:

• Fluid not rigid: Specs evolve with understanding
• Iterative not waterfall: Continuous refinement
• Easy not complex: Simple, readable format

OpenSpec Philosophy

From Fission-AI/OpenSpec:

"Traditional spec-first development often fails because:

• Specs become outdated immediately
• They're too rigid for changing requirements
• They're hard to maintain

OpenSpec solves this by making specs:

• Living documents that evolve
• Easy to update iteratively
• Tightly integrated with code"

Directory Structure

Detect and use OpenSpec structure:

openspec/
├── spec/                  # API specifications
│   ├── api.yaml          # Main OpenAPI spec
│   ├── endpoints/        # Endpoint details
│   └── schemas/          # Schema definitions
├── plan/                  # Planning documents (optional)
│   ├── architecture.md
│   └── decisions.md
└── examples/              # Example requests/responses
    ├── requests/
    └── responses/

Integration with Workflow

1. Auto-Detection

# Check if OpenSpec exists
if [ -d "openspec/" ]; then
  USE_OPENSPEC=true
  SPEC_DIR="openspec/spec/"
else
  SPEC_DIR="docs/api/" or "api/"
fi

2. Spec Creation (SDD Phase)

When creating specs:

# openspec/spec/api.yaml
openapi: 3.1.0
info:
  title: User Authentication API
  version: 0.1.0
  description: |
    Initial spec - will evolve as we learn more.

    Status: DRAFT
    Last updated: 2026-02-09

paths:
  /auth/login:
    post:
      summary: User login
      description: |
        Authenticate user with email/password.

        TODO: Decide on token format (JWT vs session)
        TODO: Rate limiting strategy
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials

# Version: 0.1.0 - Initial draft
# Version: 0.2.0 - Added rate limiting (pending)
# Version: 1.0.0 - Production ready (target)

Iterative evolution:

## Spec Evolution Log

### v0.1.0 (2026-02-09)
- Initial draft based on requirements
- Open questions: token format, rate limiting

### v0.2.0 (2026-02-10)
- Decided: JWT tokens (30min access + 7day refresh)
- Added: Rate limiting (5 attempts per 15min)
- Refined: Error response format

### v0.3.0 (2026-02-11)
- Added: OAuth2 support
- Changed: Session management approach

3. Workflow Integration

Spec-first workflow:

# 1. Start with OpenSpec
/workflow:start-development-workflow "Add payment processing API"

# Auto-detects openspec/ directory

# 2. Create initial spec (fluid)
→ Creates openspec/spec/payment.yaml
→ Version 0.1.0 - DRAFT
→ Includes TODOs and open questions

# 3. BDD scenarios from spec
→ Generates features/payment.feature
→ Based on spec endpoints and schemas

# 4. Implement iteratively
→ For each endpoint:
  - TDD implementation
  - Update spec as we learn
  - Mark sections STABLE when complete

# 5. Spec evolves
→ v0.1.0 DRAFT → v0.5.0 WORKING → v1.0.0 STABLE

4. Fluid Spec Updates

As implementation reveals new insights:

# BEFORE (v0.1.0 - assumptions)
/payments:
  post:
    summary: Process payment
    # TODO: What payment methods?
    # TODO: How to handle failures?

# AFTER (v0.3.0 - learned from implementation)
/payments:
  post:
    summary: Process payment
    description: |
      Supports: credit card, PayPal, Apple Pay

      LEARNED: Need idempotency keys for retry safety
      LEARNED: Webhook callbacks for async processing

    parameters:
      - name: Idempotency-Key
        in: header
        required: true
        description: Unique key for safe retries

OpenSpec vs Traditional Spec

Traditional (rigid):

1. Write complete spec upfront
2. Spec is "frozen"
3. Implementation must match spec exactly
4. Changes require formal approval
5. Spec becomes outdated quickly

OpenSpec (fluid):

1. Start with minimal spec (DRAFT)
2. Implement and learn
3. Update spec as understanding grows
4. Mark stable sections
5. Spec stays current with code

Status Markers

Use status markers in specs:

paths:
  /users:
    get:
      # STATUS: STABLE - Don't change without discussion
      summary: List users

  /users/{id}:
    put:
      # STATUS: WORKING - Still refining
      summary: Update user

  /admin/reports:
    get:
      # STATUS: DRAFT - Open questions
      # TODO: What metrics?
      # TODO: Date range format?
      summary: Generate reports

Integration Points

With SDD Workflow:

• Auto-detect openspec/ directory
• Use OpenSpec format for all API specs
• Follow iterative refinement process

With BDD Workflow:

• Generate BDD scenarios from OpenSpec endpoints
• Keep scenarios in sync with spec versions

With TDD Workflow:

• Implement against current spec version
• Update spec when tests reveal new requirements

With Task Management:

• Create tasks for DRAFT sections
• Track spec evolution through task updates

Commands

Create OpenSpec spec:

/workflow:create-workflow-spec "User API"
→ Detects openspec/ directory
→ Creates openspec/spec/user-api.yaml
→ Version 0.1.0 DRAFT
→ Includes standard sections + TODOs

Update spec iteratively:

/workflow:create-workflow-spec-update
→ Opens current spec
→ Marks changes with version bump
→ Logs evolution in spec comments

Validate spec:

/workflow:create-workflow-spec-validate
→ OpenAPI validation
→ Check status markers
→ Identify DRAFT sections needing attention

Example: Iterative Spec Evolution

Day 1: Initial spec

# v0.1.0 - DRAFT
paths:
  /auth/login:
    post:
      summary: Login endpoint
      # TODO: Decide on auth mechanism

Day 2: After BDD scenarios

# v0.2.0 - WORKING
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: Returns JWT access token
      # Decided: JWT tokens
      # TODO: Refresh token strategy?

Day 3: After TDD implementation

# v0.3.0 - WORKING
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: |
        Returns JWT access token (30min) + refresh token (7 days)

        LEARNED: Need to handle concurrent logins
        LEARNED: Should return user profile in response
      # TODO: Add rate limiting details

Day 5: After testing

# v1.0.0 - STABLE
paths:
  /auth/login:
    post:
      summary: User login with email/password
      description: |
        Authenticates user and returns JWT tokens.
        Rate limited to 5 attempts per 15 minutes.
      # STABLE: Don't change without team discussion

Best Practices

DO:

• Start with minimal DRAFT specs
• Update specs as you learn
• Use status markers (DRAFT/WORKING/STABLE)
• Log evolution in spec comments
• Keep spec close to code

DON'T:

• Try to design everything upfront
• Freeze specs too early
• Let specs drift from implementation
• Skip status markers
• Forget to version bump

Output

OpenSpec files:

openspec/spec/<feature>.yaml     - Main spec file
openspec/plan/<feature>.md       - Planning notes (optional)
openspec/examples/               - Request/response examples

Spec includes:

• Version number and status
• Evolution log
• Open questions (TODO)
• Learned insights
• Status markers per endpoint