[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.

[clay-good]

Hey @TabishB ,

Instead of a standard PR, I’d like to propose a Modular Subcommand Architecture that could fundamentally scale how OpenSpec grows.

The Vision: OpenSpec as a Multi-Engine CLI

• Imagine if openspec acted as a lightweight orchestrator. Commands like bootstrap, drift, or map could call out to specialized engines (like spec-gen) only when needed.
• I will continue to harden the heavy-duty static analysis and LLM logic in spec-gen, while the OpenSpec core remains lean and fast. I am also adding new logic for generating ADRs, detecting drift between ADRs and specs, etc. It needs a lot more testing!
• This opens the door for other developers to contribute "Engines" for specialized tasks (e.g., security auditing, performance specs, or even paid proprietary tools) that plug into the OpenSpec workflow via subcommands.
• Users only pull down the heavy dependencies (Tree-sitter, LLM SDKs) when they actually run a discovery/bootstrap command.

We could introduce an openspec bootstrap command that interfaces with spec-gen to solve the 'Brownfield Problem' for legacy codebases. This allows us to offer users a choice of tools or run them in sequence/parallel, effectively turning OpenSpec into the industry standard 'Spec-Ops' platform.

I'm happy to do the heavy lifting on the spec-gen side to fit whatever interface you envision. Does this modular direction align with where you want to take the Fission ecosystem or would you like to go a different direction?

Thanks!

[dhajoshi]

Does it work with IaaC as well ? E.g terraform ?

[clay-good]

Not yet but I will add that soon now, thank you for your message.

[dhajoshi]

Thanks, if you have any guide may be I can contribute. Also if there is way to integrate any MCP servers it can refer to.

[clay-good]

@dhajoshi I've added IaC support in the latest version. If you'd like to contribute, please open a PR and assign me as reviewer or you can open an issue. Thank you. 🙏 ❤️

[dhajoshi]

Thanks, one question, does it work or integrated with openscap after it rename ? If yes, how do I tag openscap to use latest version of openlore

[clay-good]

Yes, "spec-gen" is now OpenLore (same project, just renamed). Upgrade with: npm i -g openlore@latest

You don't "tag OpenSpec to use latest version of OpenLore." OpenLore is the tool you run against your codebase, and it generates/updates the openspec/specs/ files for you (e.g. openlore analyze, openlore generate). OpenSpec is the spec format OpenLore writes into.