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>
114 lines
6.9 KiB
Markdown
114 lines
6.9 KiB
Markdown
|
|
## [2026-09-20] - Design evaluation: software/source-code KB module
|
|
|
|
- **Activity:** Evaluated options for making this KB optionally "about software
|
|
I'm building" — `src/` holding one or more independent code repos, plus
|
|
OpenSpec-driven iterative development, packaged as an opt-in module.
|
|
- **Scope:** Read-only inspection of repo layout, `.agents/skills/`, `.gitignore`,
|
|
`wiki/index.md`, `ckb-init`/`ckb-upgrade`/`ckb-lint`. No files changed.
|
|
- **User decisions made this turn:**
|
|
- Module mechanism: files-in-repo module (`.agents/modules/<name>/`), installed
|
|
on request — not a native Claude Code plugin.
|
|
- `src/` repos: plain clones, gitignored. No submodules.
|
|
- Spec location: OpenSpec at *both* levels — KB root (cross-cutting, spans
|
|
multiple `src/` repos) and inside each `src/<repo>` (travels with the code).
|
|
- Confirmed preference: `CLAUDE.md` stays a symlink to `AGENTS.md`, and
|
|
`.claude/skills` stays a symlink to `.agents/skills` (both already correct,
|
|
tracked as git mode 120000).
|
|
- **Still open:** whether the module vendors OpenSpec's own workflow skills or
|
|
depends on an external OpenSpec install (hybrid recommended); schema bump to
|
|
1.5 for `repository`/`component`/`spec` types.
|
|
- **Housekeeping:** `workload/2026-09-02_summary.md` still untracked — suggest
|
|
`ckb-sync-changes`.
|
|
|
|
## [2026-09-20] - Decisions D-0001 and D-0002 recorded
|
|
|
|
- **Activity:** Ran `ckb-decide`. Recorded the settled design as two decision
|
|
records rather than one, so the module *mechanism* can be superseded
|
|
independently of the *software module's* design (e.g. a later switch to
|
|
submodules touches only D-0002).
|
|
- **Files:** `wiki/decisions/0001-opt-in-file-based-kb-modules.md`,
|
|
`wiki/decisions/0002-software-module-design.md`, `wiki/decisions/index.md`,
|
|
`wiki/decisions/log.md`, `wiki/log.md`, `wiki/graph/edges.json` (created).
|
|
- **Open:** `kb_schema_version` bump 1.4 → 1.5 not yet applied — it belongs with
|
|
the module build, not the decision. No entity page exists for Michał Kopeć,
|
|
so `decided_by` is plain text on both records.
|
|
- **Not committed.** Say "sync changes" to push.
|
|
|
|
## [2026-09-20] - Built the module mechanism and the `software` module
|
|
|
|
- **Activity:** Implemented D-0001 and D-0002.
|
|
- **New — core (always loaded):** `.agents/skills/ckb-module/SKILL.md` — install,
|
|
list, uninstall. Owns the root `ckb.yaml` manifest, marker-wrapped patches to
|
|
`AGENTS.md` and `.gitignore`, and the additive `kb_schema_version` bump.
|
|
- **New — module payload (inert until installed):** `.agents/modules/software/`
|
|
with `module.yaml`, `README.md`, `fragments/` (AGENTS routing block, gitignore
|
|
snippet), `scaffold/` (src README, KB-root `openspec/`), and two skills —
|
|
`ckb-code-map` (repo → `type: repository`/`component` pages, commit-stamped)
|
|
and `ckb-spec` (KB-root specs, delegation to OpenSpec per repo, bridge to
|
|
decisions/entities, four-part drift check).
|
|
- **Edited core skills for module awareness:** `ckb-lint` (new check 11: stale
|
|
code maps, spec drift, remote-less repos — report-only, skipped when no
|
|
module installed), `ckb-sync-changes` (new Step 1b: never stage under `src/`,
|
|
but do report each clone's state), `ckb-upgrade` (upgrade `.agents/modules/`;
|
|
never delete a skill absent upstream without checking `ckb.yaml`), `ckb-init`
|
|
(copy the module catalogue, install nothing).
|
|
- **`AGENTS.md`:** new "Optional Modules" subsection in §1, module-schema note
|
|
in §2, `ckb-module` routing row + rule in §3. `CLAUDE.md` inherits via symlink.
|
|
- **`VERSION`:** 1.6.1 → 1.7.0 (template/tooling). `kb_schema_version` stays
|
|
`1.4` — deliberately: 1.5 arrives only when a module requiring it is installed.
|
|
- **Verified:** `.claude/skills` lists 15 skills including `ckb-module` and
|
|
*excluding* `ckb-code-map`/`ckb-spec` — the opt-in isolation works. `ckb.yaml`
|
|
absent = nothing installed. Lint clean apart from a pre-existing
|
|
`query-gaps.md` freshness finding.
|
|
- **Not done:** the `software` module is built but **not installed** here.
|
|
- **Not committed.** Say "sync changes" to push.
|
|
|
|
## [2026-09-20] - OpenSpec user guides (EN + PL)
|
|
|
|
- **New:** `OPENSPEC.md` and `OPENSPEC.pl.md` — human-facing guides to adding
|
|
OpenSpec and using it with this wiki, matching the existing
|
|
README/MANUAL `.md` + `.pl.md` convention and cross-linked both ways.
|
|
- **Verified against upstream docs, not written from memory:** Node 20.19.0+,
|
|
`npm install -g @fission-ai/openspec@latest`, `openspec init/update/list/show/
|
|
validate/archive/status/view`, and the `/opsx:propose|apply|archive` loop.
|
|
- **Key finding worth the research:** `openspec init` writes into
|
|
`.claude/skills/` and adds marker blocks to `AGENTS.md`/`CLAUDE.md`. In this
|
|
repo `.claude/skills` → `.agents/skills` and `CLAUDE.md` → `AGENTS.md` are
|
|
symlinks, so running `init` at the KB root would inject OpenSpec's per-repo
|
|
files into the KB's own skill set and system prompt. Documented as a hard
|
|
"never" in both guides *and* added as a rule inside `ckb-spec`, so the agent
|
|
refuses it rather than running and cleaning up.
|
|
- **Also:** README.md / README.pl.md now point at the guides; module README links
|
|
them too.
|
|
- **Not committed.** Say "sync changes" to push.
|
|
|
|
## [2026-09-20] - Added `ckb-reset` (destructive template reset)
|
|
|
|
- **New:** `.agents/skills/ckb-reset/SKILL.md` — empties the KB back to the
|
|
scaffold `ckb-init` Step 8 defines, so a working KB can be turned back into a
|
|
distributable template. Routed in `AGENTS.md` §3. Invocable as `/ckb-reset`.
|
|
- **Safety design (the point of the skill):** git restore-point check first and a
|
|
refusal to run on a dirty tree without override; six opt-in scope tiers with
|
|
`linked/`, `libs/` and installed modules defaulting to *no*; a counted
|
|
inventory shown *before* asking; a typed-phrase confirmation that is
|
|
re-requested whenever scope changes; post-reset lint verification before
|
|
reporting success; `src/` excluded unconditionally, even with confirmation.
|
|
- **Deliberate exception to Rule D:** `ckb-reset` does not append a workload
|
|
summary — it would be the first entry in a directory it just emptied. The skill
|
|
says so in its report so it doesn't read as a bug.
|
|
- **Fixed while here:** `wiki/graph/edges.json` was missing the `version` and
|
|
`last_updated` keys the `ckb-init` scaffold specifies. Now conformant.
|
|
- **Not committed.** Say "sync changes" to push.
|
|
|
|
## [2026-09-20] - Documented `ckb-reset` in both manuals
|
|
|
|
- **`MANUAL.md` / `MANUAL.pl.md`:** new subsection in §3 ("Starting over:
|
|
resetting to a clean template" / "Zaczynanie od zera: reset do czystego
|
|
szablonu") covering the five-stage safety flow, the six scope tiers, what is
|
|
restored, what is never touched (`src/`, template layer), and the deliberate
|
|
Rule D exception. Plus a row in each §8 quick-reference table, marked
|
|
destructive.
|
|
- **Placement rationale:** §3 "Keeping it tidy" rather than §1, because reset is
|
|
a maintenance operation on an existing KB; §1 is about creating one.
|
|
- **Not committed.** Say "sync changes" to push.
|