[Proposal] spec-gen: Reverse-engineer OpenSpec specifications from existing codebases

[clay-good]

Summary

I've built spec-gen, an open-source CLI tool that reverse-engineers OpenSpec-compatible specifications from existing codebases. It addresses the "cold start" problem for teams wanting to adopt OpenSpec on established projects.

Repository: https://github.com/clay-good/spec-gen

The Problem

OpenSpec excels at spec-driven development, but adoption faces a significant barrier for existing projects:

1. openspec init creates empty scaffolding — Projects with thousands of lines of code still need to manually write every specification
2. Manual specification is time-consuming — Documenting existing behavior is tedious and error-prone
3. The documented flow assumes greenfield development — "Populate your project context" works for new projects, but not for legacy codebases

Teams end up choosing between:

• Starting fresh with spec-driven development (abandoning existing work)
• Manually reverse-engineering specs (time-consuming, often abandoned)
• Not using OpenSpec at all

The Solution: spec-gen

spec-gen automates the reverse-engineering process through a combination of static analysis and LLM-based extraction:

cd /path/to/existing-project
spec-gen init      # Detect project type, create config
spec-gen analyze   # Static analysis (no API key needed)
spec-gen generate  # Generate OpenSpec specs (requires API key)
spec-gen verify    # Test spec accuracy against code

Key Features

Feature	Description
Static Analysis	File discovery, significance scoring, dependency graphs, domain clustering — no LLM required
Multi-stage LLM Pipeline	Survey → Entities → Services → APIs → Architecture
OpenSpec-native Output	Writes directly to openspec/specs/*/spec.md with RFC 2119 keywords
Verification	Tests generated specs by predicting file contents from specs alone
Language Support	TypeScript (full), Python (basic), Go (basic)

4 Usage Options

spec-gen provides multiple ways to reverse-engineer specifications:

Option	Description	Best For
CLI Tool	Full-featured command-line with static analysis + LLM	Automated pipelines, CI/CD
Claude Code Skill	.claude/skills/spec-gen.md for natural language use	Claude Code users
OpenSpec Skill	skills/openspec-skill.md for OpenSpec's skill system	OpenSpec native integration
AGENTS.md	System prompt for any LLM (ChatGPT, Claude web, etc.)	Quick adoption, any LLM

How It Works

Phase 1: Static Analysis (No API Key)

• Walks directory tree respecting .gitignore
• Scores files by significance (schemas > services > routes > utils)
• Parses imports/exports to build dependency graph
• Clusters related files into domains automatically

Phase 2: LLM Generation

• Stage 1: Project Survey — Quick categorization
• Stage 2: Entity Extraction — Core data models
• Stage 3: Service Analysis — Business logic
• Stage 4: API Extraction — HTTP endpoints
• Stage 5: Architecture Synthesis — Overall structure

Phase 3: Verification

• Selects files NOT used in generation
• LLM predicts what each file should contain based on specs alone
• Compares predictions to actual code
• Reports accuracy score and identifies gaps

Output Format

Generated specs follow OpenSpec conventions exactly:

# User Management

## Requirements

### REQ-USER-001: User Creation
The system SHALL allow users to be created with email and password.

#### Scenario: Successful user creation
**Given** a valid email and password
**When** the user submits the registration form
**Then** a new user account SHALL be created

> **Technical Note:** Implemented in `src/services/user.ts:42`

Example: OpenSpec CLI Analysis

I ran spec-gen against the OpenSpec CLI itself:

Analysis Complete

  Repository Structure:
    ├─ Files analyzed: 221 of 231
    ├─ High-significance files: 15
    ├─ Languages: TypeScript (78%), Markdown (12%)

  Detected Domains:
    ├─ completions (16 files)
    ├─ command-generation (26 files)
    ├─ artifact-graph (7 files)
    ├─ schemas (9 files)
    ├─ validation (3 files)
    └─ commands (14 files)

Full example output: https://github.com/clay-good/spec-gen/tree/main/examples

How This Complements OpenSpec

spec-gen is designed to feed into the OpenSpec ecosystem, not replace it:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Existing Code  │ ──▶ │    spec-gen     │ ──▶ │    OpenSpec     │
│                 │     │   (bootstrap)   │     │  (ongoing dev)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘

• spec-gen generates initial specifications from existing code
• OpenSpec validates and evolves those specifications going forward
• Teams can then use openspec run with accurate context

Integration Points

1. Output Format: spec-gen writes to openspec/specs/*/spec.md — the exact structure OpenSpec expects
2. config.yaml: Updates the OpenSpec config with detected project context
3. RFC 2119: Uses the same requirement keywords (SHALL, MUST, SHOULD, MAY)
4. Scenario Format: Given/When/Then structure matches OpenSpec conventions

Technical Details

• Node.js 20+ required
• 698 tests with Vitest
• Zero runtime dependencies on OpenSpec (works standalone)
• MIT License

Install and Try

git clone https://github.com/clay-good/spec-gen
cd spec-gen
npm install && npm run build && npm link

cd /path/to/your-project
spec-gen init
spec-gen analyze  # Try this first - no API key needed!

Questions for the Community

1. Would this be useful as an official companion tool? I'm happy to contribute this to Fission-AI if there's interest.
2. Naming: Is "spec-gen" clear enough, or would something like "openspec-bootstrap" or "openspec-reverse" be better?
3. Integration depth: Should spec-gen become a subcommand of OpenSpec itself (openspec reverse-engineer)?
4. Output validation: Would it be valuable to add a --validate flag that runs openspec validate on generated specs?

Links

• Repository: https://github.com/clay-good/spec-gen
• Examples: https://github.com/clay-good/spec-gen/tree/main/examples
• Documentation: https://github.com/clay-good/spec-gen/tree/main/docs
• AGENTS.md: https://github.com/clay-good/spec-gen/blob/main/AGENTS.md (copy as system prompt for any LLM)
• Claude Code Skill: https://github.com/clay-good/spec-gen/tree/main/.claude/skills
• OpenSpec Skill: https://github.com/clay-good/spec-gen/tree/main/skills

[mahes1287]

it would be nice , if this is official

[aegenes]

I'm still new to OpenSpec, but this feels like a valuable capability for anyone kicking off true spec-driven development from brownfield. The project seems to be thinking about this as well because they have an FAQ on the OpenSpec website that says:

We're exploring generating specs for existing codebases, but our view is that trying to generate all your specs upfront is a waste of time. Create specs as you need them and build your way through.

I can see where they're coming from, but I still think there's a valid use case for generating reverse-engineered specs and documentation for existing codebases in addition to go-forward specs.

@clay-good, how many codebases have you run spec-gen on and how happy are you with the results?

[clay-good]

@aegenes So far, about 8 (my own repos and the OpenSpec repo as examples) but I am still testing/developing it. It's been useful to map relationships and business logic without requiring manual documentation.

I agree the vision OpenSpec has is great and that's why I wanted to present this as a possible way forward by providing different forms (agents.md, openspec skill, claude code skill, and a cli tool). I'm also new to OpenSpec and excited to see it's so popular! This is the way.