ckb/OPENSPEC.md

# OpenSpec in this knowledge base

*Read this in: **English** | [Polski](OPENSPEC.pl.md)*

How to add [OpenSpec](https://openspec.dev) to a Cascade KB that documents
software you're building, and how it fits alongside the wiki.

This is a human guide. The agent's own rules live in the `software` module —
[.agents/modules/software/](.agents/modules/software/README.md) — which must be
installed before any of this applies. Say **"install the software module"**.

---

## Contents

1. [What OpenSpec is for here](#1-what-openspec-is-for-here)
2. [Read this before you run `openspec init`](#2-read-this-before-you-run-openspec-init)
3. [Installing](#3-installing)
4. [The two spec levels](#4-the-two-spec-levels)
5. [Daily workflow](#5-daily-workflow)
6. [How specs reach the wiki](#6-how-specs-reach-the-wiki)
7. [Keeping the levels honest](#7-keeping-the-levels-honest)
8. [Quick reference](#8-quick-reference)

---

## 1. What OpenSpec is for here

The wiki records three different things about software, and it's worth keeping
them apart:

| Question | Where it lives | Who writes it |
|---|---|---|
| What *is* the code? | `wiki/entities/` — `repository` and `component` pages | `ckb-code-map` |
| What *should* it do? | `openspec/specs/` | `ckb-spec` + OpenSpec |
| What did we *choose*, and why? | `wiki/decisions/` | `ckb-decide` |

OpenSpec owns the middle row: a spec states a standing contract, and a change
proposal states what should become true next. You write the spec before the
code, the agent implements against it, and the archived change becomes part of
the permanent record.

If something doesn't constrain future behaviour, it isn't a spec — it's a
decision. Say "record a decision" instead.

## 2. Read this before you run `openspec init`

**Never run `openspec init` in the knowledge base root.** Run it inside
`src/<repo>/`.

This isn't stylistic caution. `openspec init` writes tool integration files into
`.claude/skills/`, and it adds marker blocks to `AGENTS.md` / `CLAUDE.md`. In
this repository both of those are load-bearing:

- `.claude/skills` is a **symlink** to `.agents/skills`. Anything OpenSpec writes
  there lands in your KB's own skill set.
- `CLAUDE.md` is a **symlink** to `AGENTS.md` — the KB's system prompt. They are
  one file, so a marker block written to "both" is written twice to the same
  place.

Run it at the root and you get OpenSpec's per-repo workflow instructions mixed
into the rules governing your whole knowledge base. Run it in `src/<repo>/` and
everything stays where it belongs: the repo gets its own `.claude/`, its own
`AGENTS.md`, and its specs travel with its code.

The KB root's `openspec/` directory is **not** an OpenSpec install (§4), so it
never needs `init`.

## 3. Installing

Needs **Node.js 20.19.0+**.

```bash
npm install -g @fission-ai/openspec@latest   # or pnpm / yarn / bun
openspec --version
```

Then, per repository:

```bash
cd src/<repo>
openspec init
```

After upgrading the CLI later, run `openspec update` in each repo to refresh its
generated instruction files.

**Uninstalling from a repo** means removing its `openspec/` directory, its
generated tool files, and the OpenSpec marker blocks from that repo's
`AGENTS.md` / `CLAUDE.md` by hand — the CLI doesn't unwind those for you.

## 4. The two spec levels

Specs live in two places on purpose.

**KB root — `openspec/`** — cross-cutting capabilities that span several `src/`
repos. The *what* and *why* that no single repo owns.

This layer is managed by the `ckb-spec` skill, **not** by the OpenSpec CLI.
There's no code beneath it and no repo for it to govern, so OpenSpec's
repo-shaped workflow doesn't apply. It's tracked in the KB's git history, like
every other piece of knowledge here.

**Per repo — `src/<repo>/openspec/`** — how that repo implements those
capabilities. The *how*. This is OpenSpec's native case: managed by the CLI and
its own instructions, travelling with the code and riding along in that repo's
pull requests.

The agent defers to OpenSpec here and won't substitute a workflow of its own. If
the CLI isn't installed it says so rather than improvising.

## 5. Daily workflow

From inside a repo that's been initialized, the loop is
**propose → apply → archive**:

| Step | Say / run | What happens |
|---|---|---|
| Propose | `/opsx:propose <what you want>` | Proposal, spec delta, design and tasks written as Markdown under `openspec/changes/<id>/` |
| Review | `openspec show <id>`, `openspec validate <id>` | Read the delta; validation checks structure and checks modified requirements against the specs they'd replace |
| Apply | `/opsx:apply` | The agent implements against the spec |
| Archive | `/opsx:archive` or `openspec archive <id>` | The change merges into the main specs and moves to `changes/archive/` |

Useful alongside: `openspec list`, `openspec status`, `openspec view` (an
interactive dashboard).

For the KB-root layer there's no CLI — just say **"write a cross-cutting spec
for X"** and `ckb-spec` handles it.

## 6. How specs reach the wiki

Three bridges, all handled by `ckb-spec`. This is what stops OpenSpec from being
a parallel universe next to your knowledge base.

**Archived change → decision record.** An applied-and-archived change is a
decision that was made and acted on. The agent *offers* to record it under
`wiki/decisions/` — the proposal's reasoning becomes Context and Rationale, the
delta becomes the Decision, rejected options become Alternatives considered.

It offers rather than doing it automatically, deliberately. Not every routine
change deserves a permanent numbered record, and a decisions log padded with
them stops being worth reading.

**Spec → entity page.** Current KB-root specs surface in `wiki/entities/` as thin
`type: spec` pages, so questions like "what is this supposed to do?" get answered
from the index without opening the spec tree. The spec file stays the source of
truth — the wiki page is a pointer, not a copy.

**Level → level.** Root specs and repo specs link to each other (§7).

## 7. Keeping the levels honest

Two spec levels means two places a statement can live, and therefore two places
it can quietly diverge. One rule prevents that:

> A root spec lists every repo spec implementing it in `implemented_by:`.
> A repo spec names its parent in `implements:`.
> **Always set both sides.**

Those links become graph edges, which turns divergence into a visible finding
rather than a silent second source of truth.

Say **"sync the specs"** (or run `lint`) and you get four checks:

1. Root specs with no implementer — *specified, but nobody's building it.*
2. Repo specs whose parent is missing or archived — *building against something
   that's no longer true.*
3. One-sided links, either direction.
4. Root specs older than the mapped commit of every repo implementing them —
   *possible drift, worth a look.*

None of these are auto-fixed. Each is a statement about intent, and only you know
which side is right.

## 8. Quick reference

| You want to | Say / run |
|---|---|
| Enable all of this | "install the software module" |
| Add OpenSpec to a repo | `cd src/<repo> && openspec init` |
| Map a repo into the wiki | "map `src/<repo>`" |
| Write a cross-cutting spec | "write a cross-cutting spec for X" |
| Propose a change in a repo | `/opsx:propose <what>` |
| Check spec health | "sync the specs" |
| Turn an archived change into a decision | "record this change as a decision" |

**Never:** run `openspec init` at the KB root · `git add` anything under `src/` ·
edit a repo's OpenSpec files to match this KB's conventions.

---

## Sources

- [OpenSpec documentation](https://openspec.dev/docs/installation) ·
  [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) ·
  [@fission-ai/openspec on npm](https://www.npmjs.com/package/@fission-ai/openspec)
- Design records: [D-0001](wiki/decisions/0001-opt-in-file-based-kb-modules.md),
  [D-0002](wiki/decisions/0002-software-module-design.md)

---

*Licensed under the Apache License, Version 2.0 — see [LICENSE](LICENSE).*