michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ckb/.agents/modules/software/README.md
Michał Kopeć 0c06cb64ab Restore point before wiki reset 
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>
2026-09-20 17:56:41 +02:00

3.4 KiB
Raw Permalink Blame History

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 adds under src/.

Setting up OpenSpec

See 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.