ckb/.agents/modules/software/README.md
Michał Kopeć bbfda5a65d Sync: local changes as of 2026-10-29T13:50:12Z
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-10-29 14:50:12 +01:00

3.6 KiB

software module

Read this in: English | Polski

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/, 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.

These skills write graph verbs from the base vocabulary in wiki/graph/index.md: ckb-code-map writes part_of, depends_on and owns; ckb-spec writes implements. The module adds no new verbs.

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. That way two spec levels that disagree produce a lint signal 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 adds under src/.

Setting up OpenSpec

See docs/OPENSPEC.md (Polski) 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: why modules are files in the repo.
  • D-0002: why gitignored clones, both spec levels, hybrid vendoring.

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