🏗️ Extract tome from spire into standalone plugin

Tome is opt-in per project — each project declares its own knowledge management approach. Spire retains a small knowledge-awareness skill that explains what tome does and provides a fallback strategy for projects without it. - New plugins/tome/ with own manifests, README, all 5 sub-skills - Spire keeps skills/knowledge/SKILL.md as awareness stub - Updated all READMEs and marketplace JSONs - tome: namespace refs now correct (tome is its own plugin)
2026-09-14 16:14:58 +02:00
parent dd9a49a6a2
commit cfd3cfb357
18 changed files with 126 additions and 8 deletions
@@ -0,0 +1,228 @@
+---
+name: init
+description: >
+  Initialize the tome knowledge layer for this repository — scaffold the wiki,
+  build the project-specific overlay (navigate skill, folder guide, platform
+  notes), and select which curation methods apply. Run once on a new project,
+  or after major structural changes. Human-triggered.
+disable-model-invocation: true
+allowed-tools: Bash(just:*), Bash(uv run:*), Bash(git:*), Bash(ls:*), Bash(cat:*), Read, Write, Glob, Grep, Agent
+---
+
+# Tome — Init
+
+Tome is **opt-in** — it requires project-level setup to be useful. Install the
+`tome` plugin, then run this skill to scaffold the knowledge structure.
+
+Three phases: deterministic scaffold, agent-authored project overlay, and
+curation method selection.
+
+## Phase 1 — Bootstrap the wiki scaffold
+
+```bash
+just tome init
+```
+
+(Without Justfile: `uv run -q --script <tome-plugin-dir>/bin/knowledge.py bootstrap`)
+
+This creates the `wiki/` tree, `boot.md`, and folder navigation. Review its output.
+
+## Phase 2 — Build the project-specific overlay
+
+The real value is a **project-specific skills directory** that layers project
+knowledge on top of generic tome navigation. This can be a sibling skill directory
+or an overlay in the project's `.claude/` configuration.
+
+Pick a short project slug (e.g. `myapp`, `acme`). Create the overlay at a
+location appropriate for the project (e.g. `.claude/skills/<slug>-tome/`).
+
+### Step 2.1 — Detect the project stack
+
+Investigate before writing anything:
+
+- **Language / framework**: Read `Cargo.toml`, `package.json`, `pyproject.toml`,
+  `go.mod`, or equivalent. Note major frameworks.
+- **Build tool / task runner**: Check for `Justfile`, `Makefile`, `Taskfile.yml`,
+  `package.json` scripts, etc.
+- **Shell / platform**: Check the environment — `$SHELL`, `$OS`, platform in
+  `CLAUDE.local.md`. Note any platform-specific quirks.
+- **Existing CLAUDE.md files**: Glob for `**/CLAUDE.md` to understand what
+  documentation already exists and how the project structures its knowledge.
+- **Top-level directories**: `ls` the repo root. Note which directories hold
+  source, assets, docs, config, build output, tests, scripts.
+
+### Step 2.2 — Create the overlay scaffold
+
+Create these files in the overlay directory:
+
+**`plugin.json`** (if creating a standalone plugin overlay):
+```json
+{
+  "name": "<slug>-tome",
+  "version": "0.1.0",
+  "description": "<Project>-specific navigation and project knowledge layer. Extends the generic tome with project-aware folder orientation, platform quirks, build conventions, and runtime probes."
+}
+```
+
+### Step 2.3 — Write the navigate skill
+
+Create a **navigate skill** (e.g. `skills/navigate/SKILL.md`) with this structure:
+
+```
+---
+name: navigate
+description: >
+  <Project>-specific navigation layer. Provides project-aware orientation ...
+  on top of the generic tome:navigate skill.
+allowed-tools: Bash(just:*), Bash(uv run:*)
+---
+```
+
+The body must have three layers of **decreasing certainty**:
+
+1. **Layer 1 — Universal truths**: Facts that never change. Path conventions,
+   where source code lives, what each top-level directory means, which files
+   are stubs vs real code. Things an agent must always know.
+
+2. **Layer 2 — Bounded possibilities**: Things that vary but within known
+   bounds. Platform targets, optional features/flags, environment variants,
+   toolchain choices. Things that narrow the search space.
+
+3. **Layer 3 — Runtime probes**: Commands the agent should run to resolve
+   remaining uncertainty. `just tome context "<path>"`, `just --list`, checking
+   configs, reading specific CLAUDE.md files. Teach the agent how to self-serve.
+
+End with a **Reference documents** section pointing to the folder guide,
+platform notes, wiki NAV files, glossary, and root CLAUDE.md.
+
+### Step 2.4 — Write the folder guide
+
+Create **`references/folder-guide.md`**. This is NOT a file listing — it
+explains what each directory IS and WHY it matters.
+
+Structure it as tables:
+- **Top-level** directories (every directory at repo root worth mentioning)
+- **Key nested directories** in the main source tree
+- **Key nested directories** in secondary source locations (if any)
+- **Wiki structure** (if wiki/ exists after Phase 1)
+
+For each entry: folder path, what it is (one phrase), and notes (CLAUDE.md
+presence, gotchas, relationships to other directories).
+
+### Step 2.5 — Write platform notes
+
+Create **`references/platform-notes.md`**. Cover what agents need to avoid
+common mistakes:
+
+- **Paths**: Slash conventions, absolute vs relative expectations
+- **Task runner**: Canonical way to build/run/test, key recipes
+- **Language toolchain**: Version pinning, workspace structure, known quirks
+- **Optional integrations**: Feature flags, external services, SDKs
+- **Scripting**: Where helper scripts live, how to run them
+- **Key binaries / entry points**: How to run the app in different modes
+
+Only include sections that apply. Be specific — generic advice wastes tokens.
+
+### Step 2.6 — (Optional) Curation rules
+
+If the project has enough CLAUDE.md files or wiki content to warrant curation
+conventions, create **`references/curation-rules.md`** describing when to
+create vs update CLAUDE.md files, what status markers mean, and how the wiki
+relates to inline docs.
+
+Skip this for small projects — but proceed to Phase 3 regardless, as method
+selection applies to projects of all sizes.
+
+## Phase 3 — Curation method selection
+
+Detect what the project has and record which curation methods apply. This
+determines what `/tome:curate` can do for this project.
+
+### Step 3.1 — Detect signals
+
+| Detection signal | Method | Check |
+|------------------|--------|-------|
+| Source code exists | `code-digest` | Always true if there's a repo |
+| Authored reference docs exist | `reference-digest` | `docs/topics/`, `docs/design/`, `doc/`, or similar |
+| Any project | `explorer` | Always available |
+| Domain knowledge without code | `concept-author` | Business rules, taxonomy, domain jargon |
+| Workpad/research notes exist | `workpad-graduate` | `docs/workpad/`, `notes/`, `research/` |
+| Wiki has content | `seal` | Available once other methods have produced content |
+
+### Step 3.2 — Propose methods
+
+Present the user with a table of detected methods and entry points:
+
+```
+Detected curation methods for <project>:
+
+| Method | Entry points | Signal |
+|--------|-------------|--------|
+| code-digest | codebase/ | Source tree with N modules |
+| reference-digest | design/ | M docs in docs/topics/ |
+| explorer | wiki root | Always available |
+| concept-author | concepts/ | Project has domain knowledge |
+| workpad-graduate | (varies) | docs/workpad/ has research notes |
+| seal | (all folders) | Available after content exists |
+
+Proceed with these? [confirm/adjust]
+```
+
+### Step 3.3 — Record in curation rules
+
+Add an **Active Curation Methods** section to the project's curation rules
+(`references/curation-rules.md`). If no curation rules file exists yet, create
+one. The section declares:
+
+- Which methods are active
+- What entry points each method feeds (wiki folder names)
+- What source locations each method reads from
+- Any project-specific notes per method
+
+Example:
+
+```markdown
+## Active Curation Methods
+
+| Method | Entry Points | Source | Notes |
+|--------|-------------|--------|-------|
+| code-digest | `codebase/` | `src/`, `lib/` | Baseline. |
+| reference-digest | `design/` | `docs/topics/` | Reference docs to digest. |
+| explorer | wiki root | Entire project | Replace generated README.md with authored narrative. |
+| concept-author | `concepts/` | User knowledge | Domain rules, taxonomy. |
+| workpad-graduate | (varies) | `docs/workpad/` | Available path. Graduation is user-triggered. |
+| seal | (all folders) | Wiki structure | Run after other methods produce content. |
+```
+
+### Step 3.4 — Scaffold entry points
+
+For each active method that feeds a wiki entry point that doesn't exist yet:
+
+1. Create the directory (e.g. `wiki/design/`, `wiki/concepts/`)
+2. Create a `NAV.md` with `status: stub` front matter
+3. Do NOT create content — that's what the curation methods themselves do
+
+## Phase 4 — CLAUDE.md routing convention
+
+If the project's root CLAUDE.md (or any module CLAUDE.md) has routing tables
+exceeding ~15 lines, propose splitting them into `@AGENTS.md` includes:
+
+```markdown
+# Module Name
+@AGENTS.md
+```
+
+This keeps CLAUDE.md small and readable while AGENTS.md carries the machine-
+readable routing. Works in Claude Code (`@`-includes) and other agent frameworks.
+
+Do not force this — propose it when it would reduce CLAUDE.md size meaningfully.
+
+## Verification
+
+After creating all files:
+
+1. Confirm the overlay is loadable: check that any `plugin.json` is valid JSON
+2. Run `just tome check` to verify knowledge-layer health
+3. Read back the navigate skill and verify the three layers make sense for
+   the project you just analyzed
+4. Verify that the curation rules list the right methods for what you detected