ckb/OPENSPEC.md

OpenSpec in this knowledge base

Read this in: English | Polski

How to add OpenSpec 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/ — which must be installed before any of this applies. Say "install the software module".

---

Contents

1. What OpenSpec is for here
2. Read this before you run openspec init
3. Installing
4. The two spec levels
5. Daily workflow
6. How specs reach the wiki
7. Keeping the levels honest
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+.

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

Then, per repository:

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 · Fission-AI/OpenSpec · @fission-ai/openspec on npm
• Design records: D-0001, D-0002

---

Licensed under the Apache License, Version 2.0 — see LICENSE.