spec-gen

name

spec-gen

description

Reverse-engineer OpenSpec specifications from an existing codebase. Use this skill when the user wants to generate specs from code, document what code actually does as specifications, perform code archaeology, detect spec drift, or bootstrap an openspec directory from an existing project. Also use when the user says "run spec-gen", "generate specs", "reverse engineer specs", or "check for spec drift".

Spec-Gen: Reverse-Engineer OpenSpec Specifications

You are performing "code archaeology" — extracting the truth of what code does and documenting it as OpenSpec specifications.

Philosophy

• Archaeology over Creativity: Document what the code ACTUALLY does, not what you imagine it should do
• Evidence-based: Every requirement and scenario must trace back to actual code
• OpenSpec-native: Output follows OpenSpec conventions exactly

Process

Phase 1: Codebase Survey

First, understand the project structure:

1. Identify project type by checking for:

   • Package.swift → Swift Package Manager
   • package.json → Node.js/TypeScript
   • pyproject.toml / setup.py → Python
   • go.mod → Go
   • Cargo.toml → Rust
   • pom.xml / build.gradle → Java
   • *.xcodeproj / *.xcworkspace → Xcode/Apple platforms

2. Find high-value files (prioritize these for analysis):

   • Schema/model files (entities, types, interfaces, protocols)
   • Service files (business logic)
   • Route/controller files (API surface)
   • Config files (settings, environment)
   • Entry points (main, index, app)

3. Identify domains by looking for:

   • Directory structure (src/users/, src/orders/, etc.)
   • File naming patterns (user-service, order-controller)
   • Import clusters (files that import each other heavily)
   • Module/target structure in build manifests

4. Detect frameworks from dependencies and patterns:

   • Express, NestJS, FastAPI, Django, etc.
   • Database: PostgreSQL, MongoDB, etc.
   • Auth: JWT, OAuth, etc.
   • Apple: SwiftUI, UIKit, AppKit, etc.

Phase 2: Deep Analysis

For each identified domain, analyze the relevant files:

1. Extract entities:

   • What data structures exist?
   • What are their properties and types?
   • How do they relate to each other?

2. Extract behaviors:

   • What operations can be performed?
   • What are the business rules/validations?
   • What side effects occur (emails, payments, etc.)?

3. Extract API surface (if applicable):

   • What endpoints or public interfaces exist?
   • What are the request/response shapes or method signatures?
   • What authentication or access control is required?

Phase 3: Generate OpenSpec Specifications

Create the OpenSpec directory structure if it doesn't exist:

openspec/
├── config.yaml
└── specs/
    ├── overview/
    │   └── spec.md
    ├── {domain-1}/
    │   └── spec.md
    ├── {domain-2}/
    │   └── spec.md
    └── architecture/
        └── spec.md

Spec File Format

Each spec.md follows this format:

# {Domain} Specification

> Generated by spec-gen on {date}
> Source files: {list of files analyzed}

## Purpose

{2-3 sentences describing what this domain handles}

## Requirements

### Requirement: {RequirementName}

{The system SHALL/MUST/SHOULD do X...}

Use RFC 2119 keywords:
- **SHALL/MUST**: Required behavior
- **SHOULD**: Recommended behavior
- **MAY**: Optional behavior

#### Scenario: {ScenarioName}
- **GIVEN** {precondition}
- **WHEN** {action}
- **THEN** {expected outcome}

## Technical Notes

- **Implementation**: `{file paths}`
- **Dependencies**: {related domains/services}

Critical Formatting Rules

1. Requirements use RFC 2119 keywords (SHALL, MUST, SHOULD, MAY)
2. Scenarios use exactly 4 hashtags (####)
3. Scenarios follow Given/When/Then format with bold labels
4. No delta markers (ADDED, MODIFIED, REMOVED) — these are baseline specs

Phase 4: Update OpenSpec Config

If openspec/config.yaml exists, preserve existing content and add:

# Existing content preserved...

spec-gen:
  generatedAt: "{timestamp}"
  domains:
    - {domain-1}
    - {domain-2}

If it doesn't exist, create minimal config:

schema: spec-driven
context: |
  {Brief project description based on analysis}

  Tech stack: {detected technologies}
  Architecture: {detected pattern}

Phase 5: Drift Detection

When specs already exist and code has changed, check for spec drift — divergence between the codebase and its specifications.

When to check: Before committing code, when reviewing PRs, or when asked to validate specs are current.

Process:

1. Identify what changed — Use git to find added, modified, deleted, or renamed source files compared to the base branch. Filter out test files, generated files, lock files, static assets, and CI configs.

2. Map changes to specs — For each changed file, determine which spec domain covers it by checking:

   • > Source files: header in each spec.md
   • **Implementation**: references in Technical Notes
   • Directory structure inference

3. Detect four categories of drift:

   • Gap: Code changed but its spec was not updated
   • Stale: Spec references a deleted or renamed file
   • Uncovered: New source file has no matching spec domain
   • Orphaned Spec: Spec declares source files that no longer exist

4. Report issues with the affected file, domain, and a suggestion for resolution.

Output Checklist

Before finishing, verify:

• openspec/specs/overview/spec.md exists with system summary
• Each domain has openspec/specs/{domain}/spec.md
• openspec/specs/architecture/spec.md describes system structure
• All requirements use RFC 2119 keywords
• All scenarios use Given/When/Then format
• openspec/config.yaml is created or updated
• No spec drift — specs match code

Example Invocation

User: "Run spec-gen on this codebase"

You should:

1. Survey the codebase structure
2. Identify 3-6 core domains
3. Analyze high-value files in each domain
4. Generate spec.md files for each domain
5. Create overview and architecture specs
6. Update config.yaml
7. Run drift check to confirm specs are in sync

Report what you created and suggest next steps:

• Manual review and refinement of generated specs
• Use /opsx:apply to implement changes against specs
• Run spec-gen again after code changes to detect drift