From dcda9e446ecdf9b8e0fbb309d8f5857ff4fcbd09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabor=20K=C3=B6rber?= Date: Thu, 17 Sep 2026 13:49:17 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20Spire=20vs=20Tome=20compar?= =?UTF-8?q?ison=20report=20(setup=20+=20self-learning)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fable-authored report comparing how each plugin handles project adoption/init and cross-session knowledge accumulation. Surfaces six gaps including missing spire:init, unshipped adept scaffolding, and a stale tome.just path from the extraction commit. --- ...-09-17-spire-vs-tome-setup-and-learning.md | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/workpad/reports/2026-09-17-spire-vs-tome-setup-and-learning.md diff --git a/docs/workpad/reports/2026-09-17-spire-vs-tome-setup-and-learning.md b/docs/workpad/reports/2026-09-17-spire-vs-tome-setup-and-learning.md new file mode 100644 index 0000000..1767caa --- /dev/null +++ b/docs/workpad/reports/2026-09-17-spire-vs-tome-setup-and-learning.md @@ -0,0 +1,77 @@ +# Spire vs. Tome — Setup Mechanics and Self-Learning + +**Date**: 2026-09-17 +**Scope**: `plugins/spire/`, `plugins/tome/`, `docs/workpad/goals/igor-project-adoption.md` + +## 1. Setup / Init Mechanics + +### Tome + +Tome is opt-in with a real bootstrap. `plugins/tome/README.md`: "Install the plugin, then run `/tome:init` in your project to scaffold the knowledge structure. Without init, the skills are available but have nothing to navigate." + +`plugins/tome/skills/init/SKILL.md` is human-triggered (`disable-model-invocation: true`) and runs four phases: + +1. **Deterministic scaffold** — `just tome init` runs `bin/knowledge.py bootstrap`: creates `wiki/boot.md`, `wiki/README.md`, stub `NAV.md` files, gitignored `.inventory.md`. `boot.md` is auto-filled from README, detected toolchains (Cargo, uv, npm, Just), Justfile recipes, and root-control-file `## Warnings` (`knowledge.py:773-916`). +2. **Agent-authored overlay** — a project skill directory (e.g. `.claude/skills/-tome/`) with a three-layer navigate skill ("Universal truths / Bounded possibilities / Runtime probes"), `folder-guide.md`, `platform-notes.md`. Step 2.1 reads `Cargo.toml`, `package.json`, `Justfile`, `**/CLAUDE.md` first. +3. **Curation method selection** — recorded in `references/curation-rules.md`. +4. **`@AGENTS.md` routing convention** for long CLAUDE.md tables. + +Re-running is safe: `write_generated_file()` never clobbers `authored` or `stub` files (`knowledge.py:467-489`). `tome.just` ships with the plugin; the host adds one `mod tome` line. + +### Spire + +Spire has no init skill. Configuration is meant to live in `skills/igor/references/project.md`, headed "per-project — swap this file when adopting Igor". It is a comment-only template with seven placeholder fields. + +Igor loads it via `@references/project.md` (`skills/igor/SKILL.md:32`); athanor via `@skills/igor/references/project.md` (`agents/athanor.md:25`). Both resolve into the plugin cache. The goal doc: "There is no mechanism to actually swap it — every project gets the blank template." + +Spire compensates with per-session runtime discovery: +- Workpad via the `spire:workpad` resolution chain (`skills/workpad/SKILL.md:12-24`): env var, Justfile recipe, `docs/workpad`, `.workpad`, or ask. +- Pinned agents from `.claude/agents/` (`SKILL.md:63`). +- Architecture entry point from "the root CLAUDE.md/AGENTS.md" (`SKILL.md:121`). +- `skills/knowledge/SKILL.md` gives a manual fallback when tome is absent and points to `/tome:init` for the full path. + +## 2. Self-Learning Abilities + +### Spire + +Learning is **narrative and session-shaped**. `references/mindset.md`: "The enemy is forgetting... The journal, the adepts' folders, the accreted corrections to existing documents are what survive." + +- **Session journals** — `/journals/-.md`, append-only, from `journal-template.md`: "record the tangents and dead ends, not only the results." Igor writes on lulls (`SKILL.md:111`) and adds a self-review at wrap-up (`SKILL.md:124`). +- **Adept folders** — `/adepts//` with `CLAUDE.md` plus dated journals (`agents/adept.md:60-66`). Two tiers: "Solid knowledge" (verified on main, goes to CLAUDE.md) vs. "Experiences" (branch work, journal only). Successors read predecessor files on genesis; the genesis journal records "what steps you took to orient". +- **Accretion** — `SKILL.md:57-59`: "add a dated refinement section — not inline edits... Link back to the source conversation or session journal." Compression is deferred: "The curator does not exist yet... accrete and move on." + +### Tome + +Learning is **structural and code-anchored**. Knowledge lives in `wiki/` with front-matter `status: generated | authored | stub` and `source-paths` tying docs to code. + +- **Six curation methods** (`skills/curate/SKILL.md`): code-digest, reference-digest, explorer, concept-author, workpad-graduate, seal. All human-triggered. +- **Correct on contact** (`skills/navigate/SKILL.md:46-51`): "Distributed micro-corrections during normal work are the cheapest curation the wiki gets." +- **Impact analysis** (`skills/handoff/SKILL.md`): `just tome impact` maps changed files to wiki docs via `source-paths`, bucketed direct/directory/control/potential. +- **Mechanical validation** (`skills/check/SKILL.md`): broken links, missing source paths, bad front-matter, stale NAV. +- **"Earned place" test**: "Would removing this force an agent to do thinking work to reconstruct it, or just a tool call?" + +The workpad flow is one-way: "The wiki never cites or links to workpad content" (`curate/SKILL.md:171`). + +### Portability + +| Pattern | Origin | Portable? | +|---------|--------|-----------| +| Correct on contact | Both (`adept.md:41`, `navigate:46`) | Already shared, same wording | +| Solid vs. experience tiers | Spire | Yes; maps onto `authored`/`stub` | +| Dated accretion sections | Spire | Yes, any authored doc | +| `source-paths` + impact | Tome | Needs `knowledge.py` | +| Genesis orientation trace | Spire | Yes; could seed tome's explorer | + +## 3. Gaps and Opportunities + +1. **No `spire:init`.** The goal's acceptance criteria are unmet: no project-local override, no auto-fill, no `/assistant` alias. Tome's init Phase 2.1 already does the stack detection Spire needs; `detect_toolchains` and `parse_justfile` (`knowledge.py:605-678`) could be reused. + +2. **`project.md` cannot be overridden.** `skills/igor/SKILL.md:32` and `agents/athanor.md:25` hard-bind the bundled template. The goal suggests "project-local → plugin-bundled" resolution or "a conditional read pattern" in skill text. + +3. **Adept scaffolding referenced but not shipped.** `agents/adept.md:23,26` tell the adept to read `/adepts/CLAUDE.md` and copy `adepts/_template/CLAUDE.md`. Neither exists in the plugin or this repo (`docs/workpad/adepts/` is absent). `spire:init` should create both. + +4. **No curator.** Spire defers compression to a curator that "does not exist yet." Tome's `seal` and `workpad-graduate` are the nearest implementation; a Spire curator could route through them when tome is present. + +5. **Stale path in `tome.just:6`.** Header still reads `/skills/tome/tome.just`, left over from before the extraction in `cfd3cfb`. + +6. **Journal-to-wiki bridge is manual.** `workpad-graduate` fires only when "User (or curator) identifies a workpad note with lasting value." Igor's wrap-up produces no graduation-candidate signal.