ckb/.agents/modules/software/README.md
Michał Kopeć 7863115b74 Template 1.10.0: slim skills, review fixes, docs/, tests, retrieval script
- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
  phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
  reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
  docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
  D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
  Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
  base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-24 20:45:09 +02:00

72 lines
3.6 KiB
Markdown

# `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.
Graph verbs these skills write, from the base vocabulary in
`wiki/graph/index.md`: `ckb-code-map` — `part_of`, `depends_on`, `owns`;
`ckb-spec` — `implements`. No new verbs are introduced.
## 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 [docs/OPENSPEC.md](../../../docs/OPENSPEC.md) ([Polski](../../../docs/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](../../../docs/decisions/0001-opt-in-file-based-kb-modules.md) — why modules are files in the repo.
- [D-0002](../../../docs/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).*