openlore-generate

name	openlore-generate
description	Reverse-engineer OpenSpec specifications from an existing codebase. Performs "code archaeology" — extracting what code actually does and documenting it as structured OpenSpec specs across all detected domains.
license	MIT
version	1.0.0
author	Clay Good
repository	https://github.com/clay-good/openlore
compatibility	openlore MCP server
user-invocable	true
allowed-tools	["read_file","write_file","list_directory","run_command","use_mcp_tool","openlore-analyze-codebase","openlore-plan-refactor"]

openlore: Generate OpenSpec Specifications

When to use this skill

Trigger this skill when the user asks to generate specs from an existing codebase, with phrasings like:

• "run openlore on this codebase"
• "reverse-engineer the specs"
• "generate OpenSpec from my code"
• "document what this code does"
• explicit command /openlore-generate

---

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

---

Phase 1 — Codebase Survey

Understand the project structure before touching any files.

1. Identify project type by checking for:

File	Stack
package.json	Node.js / TypeScript
pyproject.toml / setup.py	Python
go.mod	Go
Cargo.toml	Rust
pom.xml / build.gradle	Java

2. Find high-value files — prioritize:

• Schema / model files (entities, types, interfaces)
• 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)

4. Detect frameworks from dependencies and patterns:

• Web: Express, NestJS, FastAPI, Django, etc.
• Database: PostgreSQL, MongoDB, etc.
• Auth: JWT, OAuth, etc.

---

Phase 2 — Deep Analysis

For each identified domain, analyze the relevant files.

Extract entities:

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

Extract behaviors:

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

Extract API surface (if applicable):

• What endpoints exist?
• What are the request / response shapes?
• What authentication 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 MUST follow this exact format:

# {Domain} Specification

> Generated by openlore 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 all existing content and append:

# Auto-detected by openlore
openlore:
  generatedAt: "{timestamp}"
  domains:
    - {domain-1}
    - {domain-2}

If it doesn't exist, create a 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 explicitly asked to validate specs.

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, 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 (e.g. src/auth/ → auth domain)

3. Detect four categories of drift:

Category	Meaning
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 each issue with: affected file, domain, and a suggested resolution.

CLI shorthand: openlore drift runs this check. Use openlore drift --install-hook to add it as a git pre-commit hook.

---

Output Checklist

Before finishing, verify every item:

• 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 — run openlore drift to verify specs match code

---

Absolute constraints

• Never invent requirements — every item must be traceable to actual code
• Always preserve existing openspec/config.yaml content before appending
• Never use delta markers (ADDED, MODIFIED, REMOVED) in baseline specs
• Scenarios must use exactly 4 hashtags — never 3 or 5
• RFC 2119 keywords (SHALL, MUST, SHOULD, MAY) must be uppercase

---

Suggested next steps after generation

Report what was created, then suggest:

• openspec validate --all — check spec structure
• openlore drift --install-hook — catch future drift automatically
• openspec list --specs — see all generated specs
• Manual review and refinement of generated specs
• Run /openlore-plan-refactor to identify refactoring targets now that specs exist