# `software` module

Opt-in. Install with "install the software module"; remove with "uninstall the
software module". Nothing in here is active until installed — the skills below
live in this folder, not in `.agents/skills/`, precisely so their descriptions
stay out of context for knowledge bases that don't document software.

## What it assumes

You are building software, and this KB holds the knowledge *about* it. The code
itself lives in `src/<repo>/` as plain clones — **gitignored**, each with its own
remote and its own history. One KB can hold several.

The code is not part of the KB's history and may be absent entirely from a fresh
clone. That is deliberate, and it is why the module writes a `type: repository`
entity page for every repo: remote URL, default branch, language, build command,
path, owner. **That page is the durable artifact; the clone is a convenience.**

## What it adds

| Skill | Does |
|---|---|
| `ckb-code-map` | Reads a `src/<repo>` clone and writes it into `wiki/entities/` as a repository page plus component pages, stamped with the commit it was generated from so staleness is detectable. |
| `ckb-spec` | Owns KB-root specs, delegates per-repo specs to OpenSpec, and bridges both into `wiki/` — archived changes become decision records, current specs become `type: spec` pages. |

Plus: `src/` and `openspec/` scaffold, a routing block in `AGENTS.md`, `.gitignore`
rules for `src/*`, and the `repository`/`component`/`spec` types.

## Two spec levels

Specs live at **both** levels, and the split is the point:

- **`openspec/` at the KB root** — what and why, across repos. Cross-cutting
  contracts that no single repo owns. Served by `ckb-spec` directly, because a
  root `openspec/` is not a normal OpenSpec install: there is no code beneath it.
- **`src/<repo>/openspec/`** — how this repo implements it. OpenSpec's native
  case: travels with the code, rides along in the repo's own PRs. Served by
  OpenSpec's own instructions; `ckb-spec` defers to them and says so plainly when
  the CLI isn't installed rather than improvising a replacement.

The levels are linked by `implements:` / `implemented_by:` frontmatter, which
becomes graph edges. This exists so that two spec levels produce a **lint signal**
when they disagree, instead of two silently divergent truths. A KB-root spec with
no implementer, or a repo-level spec whose parent was archived, is a finding.

## What it does not do

- **`src/` is not a cascade layer.** It is primary evidence, like `raw/archive/`.
  `ckb-retrieve` may open and cite it to verify a claim; it never answers "what is
  entity X", and `ckb-ingest` does not treat code as inbox material. Without this
  rule every ingest would turn your codebase into wiki pages.
- **It does not commit or push `src/` repos.** They are separate repos with
  separate remotes. `ckb-sync-changes` never `git add`s under `src/`.

## Setting up OpenSpec

See [OPENSPEC.md](../../../OPENSPEC.md) ([Polski](../../../OPENSPEC.pl.md)) for
install steps, the daily propose → apply → archive loop, and the reason
`openspec init` must never run at the KB root.

## Design record

- [D-0001](../../../wiki/decisions/0001-opt-in-file-based-kb-modules.md) — why modules are files in the repo.
- [D-0002](../../../wiki/decisions/0002-software-module-design.md) — why gitignored clones, both spec levels, hybrid vendoring.

---

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