openspec-memory

An OpenSpec project workspace that extends the core workflow with a domain knowledge layer — a structured, file-based knowledge base that gives every OpenSpec skill a shared vocabulary of concepts, processes, and rules to reason from.

What it adds

By default OpenSpec skills have no structured understanding of your project's domain. Proposals use imprecise language, specs miss domain constraints, and implementations name things inconsistently. The domain knowledge layer fixes this by introducing:

Addition	Description
openspec/domain/	Convention-based directory — its presence activates domain awareness in all skills
openspec/domain/_index.yaml	Auto-generated compact YAML index loaded by every skill on entry (~600–800 tokens)
openspec/domain/static/	Curated concepts, processes, glossary terms, and rules authored before or during development
openspec/domain/discovered/	Facts surfaced during development, with provenance and lifecycle status (active | superseded | invalidated)
/opsx:domain skill	Scaffolds the domain KB (init), adds individual entries (add), and resyncs the index (sync)

Existing skills are extended to load the domain index on entry and use canonical terminology in their output:

• /opsx:explore — loads _index.yaml, offers to pull concept files as they appear in conversation
• /opsx:propose — loads _index.yaml, scans change description for concept names, flags rule conflicts before finalizing
• /opsx:apply — loads _index.yaml, reads full concept files (frontmatter + body) for concepts in task scope
• /opsx:archive — reviews completed changes for domain discoveries, captures confirmed ones, detects contradictions with active discoveries, regenerates _index.yaml

Requirements

• Claude Code — CLI or desktop app
• OpenSpec CLI v1.3.1 or later
• Node.js v18 or later (required by the OpenSpec CLI)

Installation

1. Install the OpenSpec CLI

npm install -g @fission-ai/openspec

Verify:

openspec --version

2. Clone this repository

git clone <repo-url> openspec-memory
cd openspec-memory

3. Initialize OpenSpec in your project (if starting fresh)

The openspec/ directory is already present in this repo. If you are adopting these skills into a different project, run:

openspec init

4. Activate the skills

The /opsx:* skills live in .claude/commands/opsx/ and are automatically available to Claude Code when you open this project directory. No additional installation step is required — Claude Code picks up .claude/ from the project root.

To verify the skills are loaded, open Claude Code in this directory and run:

/opsx:domain

You should see the available subcommands listed.

Usage

Initialize a domain knowledge base

Run this once per project to scaffold the domain KB from scratch:

/opsx:domain init

Claude will interview you about your domain, optionally scan your codebase, show a draft for confirmation, and write all files.

Add individual entries

/opsx:domain add concept Invoice
/opsx:domain add process InvoiceApproval
/opsx:domain add rule no-duplicate-invoice-numbers
/opsx:domain add actor AccountsPayable

Sync the index after direct edits

If you edit concept files directly, regenerate _index.yaml:

/opsx:domain sync

Normal OpenSpec workflow

The domain KB integrates transparently into the standard workflow:

/opsx:propose   → creates a change with domain-aware artifacts
/opsx:apply     → implements tasks using canonical domain terminology
/opsx:archive   → captures domain discoveries, updates the index

Project structure

openspec-memory/
├── .claude/
│   ├── commands/opsx/         # Slash commands (/opsx:domain, /opsx:apply, etc.)
│   │   ├── domain.md          # New: domain KB management skill
│   │   ├── apply.md           # Extended: domain-aware implementation
│   │   ├── archive.md         # Extended: discovery capture + index regeneration
│   │   ├── explore.md         # Extended: domain context in exploration
│   │   └── propose.md         # Extended: rule conflict detection
│   └── skills/                # Marketplace-style skill files (invokable via Skill tool)
│       ├── openspec-domain/
│       ├── openspec-apply-change/
│       ├── openspec-archive-change/
│       ├── openspec-explore/
│       └── openspec-propose/
└── openspec/
    ├── config.yaml            # Schema: spec-driven
    ├── specs/                 # Capability specs for this change
    │   ├── domain-awareness/
    │   ├── domain-discovered-knowledge/
    │   ├── domain-index/
    │   ├── domain-skill/
    │   └── domain-static-knowledge/
    └── domain/                # Domain KB for the OpenSpec domain itself
        ├── _index.yaml
        ├── static/
        │   ├── concepts/      # Change, Artifact, Spec, Skill, Schema, Discovery
        │   ├── processes/     # ChangeProposal, ChangeApplication, ChangeArchival
        │   ├── glossary.md
        │   └── rules.md
        └── discovered/

How domain awareness works

Skills follow a strict load order to keep token costs low:

1. _index.yaml always — loaded on every skill entry when openspec/domain/ exists (~600–800 tokens)
2. Concept files by name — loaded only when a concept name appears in the current change or task scope
3. Prose body only in apply — propose and explore read frontmatter only; apply reads the full file

If openspec/domain/ does not exist, all skills proceed without domain context and without error. Zero setup friction for projects that don't need it.

Token budget

A 30-concept domain fits in approximately 600–800 tokens as YAML (the index). Individual concept files add ~200–400 tokens each when loaded. The index is loaded on every skill invocation; concept files are loaded on demand.

When the index grows past ~100 entries, domain add will warn you to consider archiving inactive concepts.