# OpenSpec Integration Guide

This document details how openlore integrates with the OpenSpec ecosystem.

## Overview

openlore is designed as the "brownfield on-ramp" for OpenSpec. While `openspec init` creates empty scaffolding for new projects, openlore reverse-engineers specifications from existing codebases.

```
┌─────────────────────────────────────────────────────────────────┐
│                    OpenSpec Ecosystem                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  GREENFIELD (new projects)     BROWNFIELD (existing code)       │
│  ─────────────────────────     ────────────────────────────     │
│  openspec init                 openlore analyze                  │
│       │                             │                            │
│       ▼                             ▼                            │
│  Empty scaffolding             Codebase analysis                 │
│       │                             │                            │
│       ▼                             ▼                            │
│  Manual spec writing           openlore generate                 │
│       │                             │                            │
│       └──────────┬──────────────────┘                            │
│                  ▼                                               │
│         openspec/specs/ (populated)                              │
│                  │                                               │
│                  ▼                                               │
│         openspec change my-feature                               │
│         openspec validate                                        │
│         openspec archive                                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Directory Structure

openlore outputs to the standard OpenSpec directory structure:

```
project-root/
├── openspec/                           # OpenSpec root
│   ├── config.yaml                     # Project configuration
│   ├── specs/                          # Source of truth
│   │   ├── overview/
│   │   │   └── spec.md                 # System overview
│   │   ├── architecture/
│   │   │   └── spec.md                 # System architecture
│   │   ├── {domain-1}/
│   │   │   └── spec.md                 # Domain specification
│   │   ├── {domain-2}/
│   │   │   └── spec.md
│   │   └── api/
│   │       └── spec.md                 # API specification
│   ├── changes/                        # Proposed modifications
│   │   └── archive/                    # Completed changes
│   └── schemas/                        # Custom workflow schemas
├── .openlore/                          # openlore working directory
│   ├── config.json                     # openlore configuration (commit this)
│   ├── analysis/                       # Analysis artifacts (regeneratable)
│   ├── outputs/                        # Generation reports
│   ├── verification/                   # Verification results
│   ├── backups/                        # Backed up specs
│   ├── runs/                           # Run metadata
│   └── logs/                           # LLM request/response logs
└── .gitignore                          # Updated to include .openlore/
```

## Spec File Format

Generated specs follow OpenSpec's standard format:

```markdown
# {Domain} Specification

> Generated by openlore v{version} on {date}
> Source files: {list of analyzed files}
> Confidence: {percentage}%

## Purpose

{High-level description of what this domain covers}

## Requirements

### Requirement: {RequirementName}

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

#### Scenario: {ScenarioName}
- **GIVEN** {precondition or initial state}
- **WHEN** {action or trigger occurs}
- **THEN** {expected outcome or result}
- **AND** {additional assertion if needed}

### Requirement: {RequirementName2}

{Another requirement...}

#### Scenario: {AnotherScenario}
- **GIVEN** ...
- **WHEN** ...
- **THEN** ...

## Technical Notes

- **Implementation**: `{file paths}`
- **Dependencies**: {list of related domains/services}
- **Patterns**: {observed architectural patterns}
```

### RFC 2119 Keywords

All requirements use RFC 2119 keywords:

| Keyword | Meaning |
|---------|---------|
| SHALL / MUST | Absolute requirement |
| SHALL NOT / MUST NOT | Absolute prohibition |
| SHOULD | Recommended |
| SHOULD NOT | Not recommended |
| MAY | Optional |

### Scenario Format

Scenarios MUST use exactly 4 hashtags (####) per OpenSpec convention:

```markdown
#### Scenario: ValidUserLogin
- **GIVEN** a registered user with valid credentials
- **WHEN** the user submits the login form
- **THEN** the user is authenticated
- **AND** a session token is created
```

## config.yaml Integration

openlore updates `openspec/config.yaml` while preserving user content:

```yaml
# User-defined content (preserved)
schema: spec-driven
context: |
  This is an e-commerce platform built for enterprise clients.
  Key requirements include PCI compliance and high availability.

rules:
  proposal:
    - Must include cost analysis
  specs:
    - All requirements must be testable

# Auto-generated by openlore (merged)
openlore:
  version: "1.0.0"
  generatedAt: "2024-01-15T10:30:00Z"
  domains:
    - user
    - order
    - auth
    - api
  confidence: 0.85
  sourceAnalysis: ".openlore/analysis/repo-structure.json"
```

### Context Injection

If existing context is present, openlore appends detected information:

```yaml
context: |
  # User-provided context (preserved)
  This is an e-commerce platform for enterprise clients.

  # Auto-detected by openlore (appended)
  Tech stack: Node.js 20, TypeScript 5.3, Express 4.18, TypeORM 0.3
  Architecture: Layered (routes → controllers → services → repositories)
  Detected domains: user, order, product, payment, notification
  Key patterns: Repository pattern, Dependency injection
```

## OpenSpec CLI Compatibility

Generated specs work with all OpenSpec commands:

### Validation

```bash
openspec validate --all
```

openlore ensures:
- Valid markdown structure
- Correct heading hierarchy
- RFC 2119 keywords in requirements
- Proper scenario format (#### heading, GIVEN/WHEN/THEN)
- No delta markers (ADDED, MODIFIED, REMOVED)

### Listing

```bash
openspec list --specs
```

Shows all generated domain specs.

### Viewing

```bash
openspec show specs/user
```

Displays the user domain specification.

### Changes

```bash
openspec change add-payment-feature
```

Works normally - generated specs serve as the baseline for proposed changes.

## Merge Strategies

When specs already exist, openlore offers three strategies:

### 1. Replace (Default)

```bash
openlore generate
```

- Creates backup in `.openlore/backups/{timestamp}/`
- Replaces existing specs with new generation
- Logs what was replaced

### 2. Merge

```bash
openlore generate --merge
```

- Preserves all existing content
- Appends "## Generated Analysis" section
- Never removes user-written requirements

### 3. Skip

```bash
openlore generate --no-overwrite
```

- Only writes specs for new domains
- Skips any existing spec files
- Useful for incremental generation

## Workflow Examples

### Initial Brownfield Adoption

```bash
# 1. Initialize OpenSpec (if not already done)
openspec init

# 2. Run openlore to reverse-engineer
openlore

# 3. Review generated specs
openspec list --specs
openspec show specs/user

# 4. Validate structure
openspec validate --all

# 5. Verify accuracy
openlore verify

# 6. Start spec-driven development
openspec change my-first-feature
```

### Adding a New Domain

```bash
# 1. Code is added to codebase (e.g., new payment module)

# 2. Re-run analysis
openlore analyze --force

# 3. Generate only the new domain
openlore generate --domains payment --no-overwrite

# 4. Review and refine
openspec show specs/payment
```

### Refreshing After Major Refactor

```bash
# 1. Re-analyze codebase
openlore analyze --force

# 2. Generate with merge to preserve manual edits
openlore generate --merge

# 3. Review differences
# (check the "## Generated Analysis" sections)

# 4. Manually reconcile if needed
```

### Continuous Drift Detection

```bash
# 1. Install pre-commit hook (runs static mode — fast, no API key)
openlore drift --install-hook

# 2. Check drift on a feature branch
openlore drift --base main

# 3. Use LLM to filter false positives
openlore drift --use-llm

# 4. CI/CD integration
openlore drift --json --fail-on error
```

### Using Custom LLM Endpoints

For enterprise teams or local model servers:

```bash
# Generate specs with a local vLLM server
openlore generate --api-base http://localhost:8000/v1

# Verify with an internal endpoint and self-signed cert
openlore verify --api-base https://llm.internal.corp/v1 --insecure

# Or configure once in .openlore/config.json:
# { "llm": { "apiBase": "http://localhost:8000/v1", "sslVerify": false } }
```

## Domain Naming Conventions

openlore follows OpenSpec conventions for domain names:

| Convention | Example |
|------------|---------|
| Lowercase | `user`, `order`, `payment` |
| Kebab-case for multi-word | `order-management`, `user-auth` |
| Descriptive but concise | `auth` not `authentication-service` |
| Match existing names | If `openspec/specs/user/` exists, use `user` |

Avoided names:
- `misc`, `other`, `utils` (too generic)
- `service`, `module` (describes structure, not domain)
- Implementation-specific names

## Technical Notes Format

Each spec includes technical notes linking to implementation:

```markdown
## Technical Notes

- **Implementation**: `src/services/user-service.ts`, `src/repositories/user-repo.ts`
- **Dependencies**: auth, notification, database
- **Patterns**: Repository pattern, Service layer
- **External Integrations**: Stripe (payment processing), SendGrid (email)
```

This helps developers:
- Find source code for requirements
- Understand dependencies between domains
- Identify integration points

## Confidence Scores

openlore provides confidence scores at multiple levels:

### Overall Confidence

In `openspec/config.yaml`:
```yaml
openlore:
  confidence: 0.85
```

### Per-Domain Confidence

In each spec file header:
```markdown
> Confidence: 82%
```

### Interpretation

| Score | Meaning |
|-------|---------|
| 90-100% | High confidence, minimal review needed |
| 75-89% | Good coverage, review recommended |
| 50-74% | Partial coverage, significant review needed |
| <50% | Low confidence, consider manual writing |

## Troubleshooting

### Validation Failures

```bash
openspec validate --all
# Error: Invalid scenario format in specs/user/spec.md
```

**Check:**
- Scenario headings have exactly 4 hashtags (####)
- GIVEN/WHEN/THEN keywords are present
- No delta markers (ADDED, MODIFIED, REMOVED)

### Missing Domains

If expected domains aren't generated:

1. Check analysis output: `.openlore/analysis/repo-structure.json`
2. Verify file scoring in `.openlore/analysis/SUMMARY.md`
3. Adjust scoring or explicitly add domains

### Incorrect Clustering

If files are grouped wrong:

1. Review dependency graph: `.openlore/analysis/dependency-graph.json`
2. Check for missing imports in source code
3. Manually specify domains: `openlore generate --domains user,order,auth`

## Best Practices

1. **Review Before Committing**
   - Always review generated specs before committing
   - Check for inaccuracies or missing context

2. **Preserve Manual Edits**
   - Use `--merge` or `--no-overwrite` to protect edits
   - Consider adding manual sections after "## Technical Notes"

3. **Regular Verification**
   - Run `openlore verify` periodically
   - Address gaps identified in verification

4. **Incremental Updates**
   - Generate specific domains when adding features
   - Don't regenerate everything on every change

5. **Version Control**
   - Commit `.openlore/config.json` (project configuration)
   - Don't commit `.openlore/analysis/` (regeneratable)
   - Do commit `openspec/specs/` (the actual specs)
