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