Michał Kopeć
0c06cb64ab
Commit all in-flight work — ckb-module and ckb-reset skills, the .agents/modules/ scaffold, OPENSPEC docs, decision records D-0001 and D-0002, graph edges and workload summaries — so the reset that follows is fully recoverable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
68 lines
3.4 KiB
Markdown
68 lines
3.4 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.
|
|
|
|
## 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).*
|