reliquary/docs/workpad/reports/2026-09-17-spire-vs-tome-setup-and-learning.md

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/<slug>-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 — <workpad>/journals/<YYYY-MM-DD-hh>-<slug>.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 — <workpad>/adepts/<domain-slug>/ 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 <workpad>/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 <path-to-spire-plugin>/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.