michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ckb/workload/2026-09-20_summary.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

6.9 KiB
Raw Blame History

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