OpenSpec

What is OpenSpec?

OpenSpec is a file-based specification format that lives inside your repository. It gives your team a structured, version-controlled way to describe what your system does — module boundaries, business rules, domain vocabulary — all in plain Markdown.

When ArcLume indexes a repository that contains OpenSpec files, it automatically detects them and uses them to ground story generation in your team's own language and intent. Instead of guessing from code alone, ArcLume respects the boundaries and terminology you've already documented.

Why OpenSpec matters

Code tells you how something works. OpenSpec tells you what it should do and why. When both are available, ArcLume can:

• Generate better-scoped stories — specs define module boundaries, so generated stories stay within them instead of drifting across concerns
• Write more accurate acceptance criteria — specs describe existing behavior and constraints, so ArcLume knows what to preserve
• Use your team's vocabulary — specs use your domain language and concepts, which flows directly into the generated output
• Reduce hallucination — structured specs give the AI concrete constraints instead of guessing from code patterns alone

Directory structure

OpenSpec files live in an openspec/ directory at the root of your repository:

your-repo/
├── openspec/
│   ├── specs/           # What your system does today
│   │   ├── auth.md
│   │   ├── billing.md
│   │   └── notifications.md
│   └── changes/         # Structured change proposals (generated by ArcLume export)
│       ├── add-sso/
│       │   ├── proposal.md
│       │   ├── design.md
│       │   └── tasks.md
│       └── usage-based-billing/
│           ├── proposal.md
│           └── design.md
├── src/
└── ...

Specs (openspec/specs/*.md)

Spec files describe the current state of a feature or domain area. They answer: "What does this part of the system do?"

These are the most important files to write. They provide the context that makes ArcLume's story generation dramatically more accurate.

A good spec file includes:

• A summary of the feature's purpose
• Key behaviors and business rules
• Important constraints or invariants
• References to the relevant code areas (optional but helpful)

Example:

# Authentication

## Summary
Users authenticate via email/password or GitHub OAuth.
Sessions are stored server-side with a 30-day expiry.

## Business Rules
- Email addresses must be unique across all auth methods
- OAuth callback links to existing accounts by email match
- Failed login attempts are rate-limited to 5 per minute

## Key Files
- `app/controllers/auth_controller.ts`
- `app/services/oauth_account_service.ts`

Change proposals (openspec/changes/<name>/)

Change proposals describe a planned modification to the system. Each change gets its own subdirectory with one or more Markdown files. They answer: "What are we building or changing?"

You don't need to write these by hand. ArcLume's Export to OpenSpec feature generates change proposals automatically from your maps — turning your generated stories into version-controlled specs.

A change proposal typically contains:

• proposal.md — the what and why: summary, business value, assumptions, out-of-scope items
• design.md — the how: technical approach, architecture decisions, acceptance criteria
• tasks.md — breakdown of implementation tasks with complexity estimates

How ArcLume uses OpenSpec

Reading specs (context for generation)

When you index a repository, ArcLume automatically detects OpenSpec files and treats them specially:

1. Detection — files matching openspec/specs/*.md are tagged as spec nodes; files under openspec/changes/*/ are tagged as change proposals
2. Boosted relevance — OpenSpec chunks receive a significant similarity boost during retrieval, ensuring they surface ahead of less relevant code when generating epics and stories
3. Grounding context — specs shape how ArcLume scopes stories (respecting documented module boundaries), names things (using your team's vocabulary), and writes acceptance criteria (referencing documented constraints)

You drive the map from your brief. Specs provide the grounding context that makes the output feel like it was written by someone who actually understands your project.

Exporting maps (write path)

After generating stories in ArcLume, you can export the result back into OpenSpec format:

1. Open a map in ArcLume
2. Click Export to OpenSpec in the sidebar
3. ArcLume generates proposal.md, design.md, and tasks.md from your epic and stories
4. Download the files and commit them to your repo under openspec/changes/

This closes the loop: you start with a brief, ArcLume generates stories grounded in your code and specs, then you export structured change proposals back into version control. On the next re-index, those proposals are detected and available as context for future maps.

The full workflow

The most effective way to use OpenSpec with ArcLume:

1. Document your system — add spec files under openspec/specs/ describing key feature areas
2. Index — connect your repo and let ArcLume index it (specs are auto-detected)
3. Generate — create a map from a brief; ArcLume uses your specs as grounding context
4. Export — export the map to OpenSpec change proposals and commit to your repo
5. Build — push stories to Linear, generate context bundles, hand to engineering
6. Update — after code ships, update specs to reflect the new reality; the next cycle benefits automatically

Getting started

Adding OpenSpec to your repository takes minutes:

1. Create the openspec/ directory at your repo root
2. Add at least one spec file under openspec/specs/ describing a key feature area
3. Commit and push
4. Re-index the repository in ArcLume (Settings → Repos → Re-index)
5. The OpenSpec notice on the repo card will disappear once specs are detected

Start small — even a single spec file improves generation quality for that domain area. Add more specs as your team adopts the workflow.

Tips for effective specs

• Keep specs focused — one spec per feature area or domain concept, not one giant file
• Write for humans first — specs should be useful to your team even without ArcLume
• Update specs when behavior changes — outdated specs are worse than no specs
• Be explicit about boundaries — clearly state what each module owns and what it doesn't
• Reference code paths — mentioning key files helps ArcLume connect specs to the right code