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

# 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:

```markdown
# {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:

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

**If it doesn't exist**, create a minimal config:

```yaml
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