🏗️ 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)
This commit is contained in:
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"name": "tome",
|
||||
"version": "0.1.0",
|
||||
"description": "Tome — knowledge layer for agent-managed projects. Navigate, curate, check, handoff, init. Opt-in per project: install the plugin, then run /tome:init to set up the knowledge structure.",
|
||||
"author": {
|
||||
"name": "Gabor Körber",
|
||||
"email": "gab@g4b.org"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"name": "tome",
|
||||
"version": "0.1.0",
|
||||
"description": "Tome — knowledge layer for agent-managed projects. Navigate, curate, check, handoff, init. Opt-in per project: install the plugin, then run /tome:init to set up the knowledge structure.",
|
||||
"author": {
|
||||
"name": "Gabor Körber",
|
||||
"email": "gab@g4b.org"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
# 📖 Tome
|
||||
|
||||
Knowledge layer for agent-managed projects. Tome gives agents a structured way to navigate, curate, and maintain a project's knowledge base — CLAUDE.md files, topic docs, domain maps.
|
||||
|
||||
**Opt-in.** 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.
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `navigate` | Find the right CLAUDE.md or topic doc for a given question. Entry point for knowledge lookups. |
|
||||
| `curate` | Maintain and improve knowledge files — fill gaps, fix stale content, restructure. |
|
||||
| `check` | Verify knowledge-layer health: stale refs, missing docs, broken links. |
|
||||
| `handoff` | Prepare knowledge for a session transition or successor agent. |
|
||||
| `init` | Scaffold a project's knowledge structure from scratch. |
|
||||
|
||||
## Installation
|
||||
|
||||
Add `tome` to `enabledPlugins` in `.claude/settings.json` (official) or `.claude/settings.local.json` (shadow):
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledPlugins": ["tome@reliquary"]
|
||||
}
|
||||
```
|
||||
|
||||
Pairs well with `spire` — Igor and adepts can use tome skills when available, but don't require them.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: check
|
||||
description: >
|
||||
Validate tome knowledge-layer health — broken Markdown links, referenced source paths
|
||||
that no longer exist, missing generated navigation resources, invalid control-file
|
||||
headings or wiki front-matter, and generated folder navigation that has drifted from
|
||||
the current repository structure. Human-triggered; CI-friendly (non-zero exit on
|
||||
error-severity findings).
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(just:*), Bash(uv run:*)
|
||||
---
|
||||
|
||||
# Tome — Check
|
||||
|
||||
```bash
|
||||
just tome check
|
||||
```
|
||||
|
||||
(Equivalent without the Justfile: `uv run -q --script <tome-plugin-dir>/bin/knowledge.py check`)
|
||||
|
||||
Review the findings. `check` validates only **objective, mechanically verifiable**
|
||||
issues:
|
||||
|
||||
- Broken Markdown links (local targets that do not exist).
|
||||
- Referenced source paths (`source-paths`) that no longer exist.
|
||||
- Missing generated navigation resources (`boot.md`, wiki nav).
|
||||
- Invalid recognized control-file headings / structure.
|
||||
- Invalid wiki front-matter `status` values.
|
||||
- Generated folder navigation that differs from the current repository structure.
|
||||
|
||||
It exits non-zero when there are **error**-severity findings (suitable for CI);
|
||||
warnings alone do not fail. Subjective semantic quality and architectural correctness
|
||||
are out of scope — that judgment belongs to `/tome:curate` and to humans.
|
||||
@@ -0,0 +1,279 @@
|
||||
---
|
||||
name: curate
|
||||
description: >
|
||||
Run a bounded curation pass over the tome knowledge layer — using one of six
|
||||
curation methods (code-digest, reference-digest, explorer, concept-author,
|
||||
workpad-graduate, seal). Each method is independent and feeds specific wiki
|
||||
entry points. Human-triggered. Use periodically, or after a wave of changes
|
||||
has accumulated. Specify a method, or omit to get guidance on what's needed.
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(just:*), Bash(uv run:*), Read, Write, Glob, Grep, Agent
|
||||
---
|
||||
|
||||
# Tome — Curate
|
||||
|
||||
## Orientation
|
||||
|
||||
The wiki grows through **curation methods** — independent strategies for producing
|
||||
wiki content. Each method feeds specific entry points and can run alone.
|
||||
|
||||
Check the project's curation rules (in the project-specific tome overlay, e.g.
|
||||
a `references/curation-rules.md` in the project's tome configuration) to see which
|
||||
methods are active and what entry points they feed. If no curation rules exist, only
|
||||
`code-digest` is available by default.
|
||||
|
||||
When invoked without a specific method, assess what's needed:
|
||||
- Are inventories stale? -> run `code-digest`
|
||||
- Are there reference docs without wiki digests? -> run `reference-digest`
|
||||
- Is the wiki root a stub or generated placeholder? -> run `explorer`
|
||||
- Are there wiki folders with no README? -> run `seal`
|
||||
|
||||
## Step 1: Refresh inventories (all methods)
|
||||
|
||||
```bash
|
||||
just tome refresh
|
||||
```
|
||||
|
||||
This regenerates `.inventory.md` files (gitignored) with the current state.
|
||||
|
||||
## Method: code-digest
|
||||
|
||||
*Baseline method. Reads source code, produces wiki docs.*
|
||||
|
||||
**Entry points**: `codebase/`, or project-equivalent source directories
|
||||
|
||||
1. Review `.inventory.md` for changes since last curation.
|
||||
2. Curate NAV files: diff inventory against NAV, promote what earns its place.
|
||||
3. Correct wiki claims that are now false. Flag conceptual drift.
|
||||
4. Create new wiki docs only for genuinely new patterns, domains, or layers.
|
||||
5. Apply the "earned place" test for all content.
|
||||
|
||||
### NAV files (inventory -> judgment)
|
||||
|
||||
NAV files are **selective, curated navigation** — not directory listings. The tool
|
||||
produces `.inventory.md` with the exhaustive listing; your job is to decide what
|
||||
earns a place in `NAV.md`.
|
||||
|
||||
1. Read `.inventory.md` (the full machine-generated inventory)
|
||||
2. Read the existing `NAV.md`
|
||||
3. **Diff**: What's new in the inventory that should be promoted to NAV? What's in
|
||||
NAV that no longer exists or isn't important enough?
|
||||
4. Write to NAV only what earns its place — 5-15 key entry points with a sentence
|
||||
about *why each matters*, not just what it is.
|
||||
|
||||
When a NAV file has `status: stub`, it means it was seeded but never curated.
|
||||
Curate it and change status to `authored`.
|
||||
|
||||
### Wiki documents
|
||||
|
||||
- Correct wiki claims you can confirm are now false.
|
||||
- Flag possible conceptual drift; create new wiki documents for genuinely new
|
||||
patterns, domains, or layers (mark them `status: authored`).
|
||||
- Do **not** broadly rewrite authored knowledge. Curation tracks *current
|
||||
understanding* — treat diffs as input signals, not find-and-replace targets.
|
||||
|
||||
## Method: reference-digest
|
||||
|
||||
*Reads authored reference docs, distills decisions into wiki.*
|
||||
|
||||
**Entry point**: `design/` (or project-equivalent)
|
||||
|
||||
1. Identify reference docs (e.g. `docs/topics/`, design specs, architecture guides).
|
||||
2. For each doc without a wiki digest, or with a stale one:
|
||||
a. Read the reference doc.
|
||||
b. Extract decisions, invariants, lifecycle models, key constraints.
|
||||
c. Write a digest (50-100 lines) carrying the *thinking work* — not a summary
|
||||
of prose, but crystallized knowledge an agent needs.
|
||||
d. Use front matter with `source-paths` pointing to the reference doc.
|
||||
3. Check existing digests for staleness: has the source doc changed since the
|
||||
digest was written?
|
||||
|
||||
**Front matter example:**
|
||||
```yaml
|
||||
---
|
||||
status: authored
|
||||
source-paths:
|
||||
- docs/topics/some-topic.md
|
||||
---
|
||||
```
|
||||
|
||||
**What a good digest contains:**
|
||||
- The 3-7 key decisions the doc makes, each with 2-3 sentences of rationale
|
||||
- Links to the full doc sections for details
|
||||
- Cross-links to related wiki docs
|
||||
- NOT a prose summary — the crystallized decisions and models
|
||||
|
||||
## Method: explorer
|
||||
|
||||
*An agent explores the project and writes what it learns.*
|
||||
|
||||
**Entry point**: Wiki root (`README.md` or `index.md`)
|
||||
|
||||
This is the most open-ended method. The agent acts like a person spending a day
|
||||
with the codebase and writing down what they learn.
|
||||
|
||||
1. Explore broadly: scan directories, read READMEs, check build config, run the
|
||||
build if possible.
|
||||
2. Write a wiki frontpage explaining:
|
||||
- What the project is and why it exists
|
||||
- How it works at a high level
|
||||
- Where the interesting, complex, or surprising parts are
|
||||
- What's well-documented vs. what's still unclear
|
||||
3. Create stub pages for areas that need deeper investigation.
|
||||
Use `status: stub` front matter.
|
||||
4. Mark confidence levels in prose: "I'm confident about X" vs "I think Y works
|
||||
like Z but haven't verified."
|
||||
|
||||
**What makes this different from code-digest:**
|
||||
- Top-down (understand project -> describe) vs bottom-up (read file -> write doc)
|
||||
- Stubs and uncertainty markers are features, not gaps
|
||||
- Reads like something a person wrote, not a generated inventory
|
||||
- The explorer's judgment about what's interesting IS the value
|
||||
|
||||
**Output tone:** Conversational but precise. "The network model is surprisingly
|
||||
complex — the server doesn't replicate transforms at all, instead..." Not:
|
||||
"This section covers the network model implementation details."
|
||||
|
||||
## Method: concept-author
|
||||
|
||||
*Direct authoring of non-code knowledge.*
|
||||
|
||||
**Entry point**: `concepts/`, or project-appropriate branch
|
||||
|
||||
For knowledge that has no source code counterpart: domain rules, taxonomy,
|
||||
design principles, or other conceptual knowledge unique to the project.
|
||||
|
||||
1. Identify concepts that exist in the team's heads or in scattered brainstorms
|
||||
but have no structured home.
|
||||
2. Author wiki docs directly. The wiki *is* the source of truth.
|
||||
3. Use `source-paths: []` in front matter (no backing file).
|
||||
|
||||
**Brainstorm boundary:** Brainstorms are exploration, not source material. If a
|
||||
brainstorm produced a lasting decision, that decision is authored here as
|
||||
standalone knowledge — not as a digest of the brainstorm. A one-line origin note
|
||||
is acceptable:
|
||||
`> Design rationale explored in /docs/brainstorm/topic.md`
|
||||
|
||||
## Method: workpad-graduate
|
||||
|
||||
*Promotes lasting research into the wiki.*
|
||||
|
||||
**Entry point**: Wherever the knowledge fits
|
||||
|
||||
Workpad content is ephemeral by design. But sometimes research produces lasting
|
||||
knowledge that should live in the wiki.
|
||||
|
||||
1. User (or curator) identifies a workpad note with lasting value.
|
||||
2. Distill the knowledge — not the research process — into a wiki doc.
|
||||
3. The wiki doc stands alone. It does NOT reference the workpad.
|
||||
4. The workpad note stays where it is (historical record).
|
||||
|
||||
**Key rule:** The wiki never cites or links to workpad content. The graduation
|
||||
step distills and relocates. If someone deletes the workpad note, the wiki doc
|
||||
must still make complete sense.
|
||||
|
||||
**Reverse flow:** When starting new research, read the wiki first to understand
|
||||
what's already known. The wiki is both a sink for lasting knowledge and a source
|
||||
for new exploration.
|
||||
|
||||
## Method: seal
|
||||
|
||||
*Ensures every wiki folder has a README that orients a reader.*
|
||||
|
||||
**Entry point**: All wiki folders
|
||||
|
||||
The finishing pass that makes the wiki feel complete rather than scaffolded.
|
||||
|
||||
1. Walk every wiki folder.
|
||||
2. For each folder, check:
|
||||
- Does it have a README.md (or equivalent orientation doc)?
|
||||
- Does the README explain what this section covers?
|
||||
- Does it mention what's well-documented vs. still thin?
|
||||
3. For folders missing a README: write one. It should orient a reader who landed
|
||||
here without context — what's in this section, why it matters, what to read
|
||||
first.
|
||||
4. For folders with only a NAV.md: the NAV is navigation, not orientation. Add a
|
||||
README that introduces the section. NAV remains for structured links.
|
||||
5. Review glossary completeness: scan wiki docs for terms that should be in the
|
||||
glossary but aren't.
|
||||
|
||||
**What sealing fixes:**
|
||||
- Folders with only a NAV.md and no orientation
|
||||
- Entry points that read like directory listings instead of introductions
|
||||
- Missing context about what a section covers and what's still thin
|
||||
- A root README that only talks about codebase as an entry point
|
||||
|
||||
## Cross-Method Rules
|
||||
|
||||
These apply regardless of which method is active.
|
||||
|
||||
### File structure (non-codebase wiki)
|
||||
|
||||
Outside `wiki/codebase/`, wiki documents follow the **flat-file-first** rule:
|
||||
|
||||
- **Default**: Create `topic.md` as a flat file in its parent directory.
|
||||
- **Promote**: Only create `topic/README.md` when you're also creating child pages
|
||||
under that topic. Move the content from `topic.md` into `topic/README.md`.
|
||||
- **Split threshold**: If a wiki page grows past ~150 lines or covers 3+ distinct
|
||||
sub-concepts that could stand alone, consider splitting into a folder with children.
|
||||
|
||||
Inside `wiki/codebase/`, the mirror structure uses `directory/README.md` to match
|
||||
the source tree layout.
|
||||
|
||||
### Triage
|
||||
|
||||
If content doesn't belong where you found it:
|
||||
|
||||
- Add it to `wiki/_triage.md` with a `found-in` note
|
||||
- Don't place it in the wrong wiki doc just to avoid the triage inbox
|
||||
- Categories determine exit path:
|
||||
- `cross-cutting-pattern` / `design-decision` -> wiki docs
|
||||
- `convention` -> project skill or CLAUDE.md
|
||||
- `todo` / `future-idea` -> workpad or issue tracker (exits wiki entirely)
|
||||
|
||||
### Warnings must be machine-visible
|
||||
|
||||
`tome context` surfaces hazards only from `## Warnings` H2 sections in control files
|
||||
(CLAUDE.md / AGENTS.md). A hazard written as free prose in a router is invisible to
|
||||
the navigation plane. When curating a control file that carries active hazards, put
|
||||
them as bullets under a `## Warnings` section — one line each, stating what breaks
|
||||
and what to do instead.
|
||||
|
||||
### The "earned place" test
|
||||
|
||||
Before adding content to the wiki, ask: *Would removing this force an agent to do
|
||||
thinking work to reconstruct it, or just a tool call?*
|
||||
|
||||
- If a tool call (`ls`, `grep`, `git log`) can recover it -> it doesn't belong
|
||||
- If understanding the codebase, patterns, or design rationale is required -> it earns its place
|
||||
|
||||
### Glossary consistency
|
||||
|
||||
During any curation method, check `/wiki/glossary.md`:
|
||||
|
||||
- If a wiki doc introduces a term that's in the glossary, use the glossary's name
|
||||
- If you encounter a term that should be in the glossary but isn't, add it
|
||||
- If a glossary definition has drifted from reality, update it
|
||||
- Mark uncertain additions as `[unverified]`
|
||||
- Every curation method that introduces new terminology must feed the glossary
|
||||
|
||||
### `@AGENTS.md` include pattern
|
||||
|
||||
When writing or updating CLAUDE.md routers, use `@AGENTS.md` includes for routing
|
||||
tables that exceed ~15 lines. This keeps CLAUDE.md small and readable while
|
||||
carrying the machine-readable routing in a framework-agnostic include:
|
||||
|
||||
```markdown
|
||||
# Module Name
|
||||
@AGENTS.md
|
||||
```
|
||||
|
||||
Works in Claude Code (which resolves `@`-includes) and other agent frameworks.
|
||||
|
||||
## Step 3: Validate
|
||||
|
||||
```bash
|
||||
just tome check
|
||||
```
|
||||
|
||||
Verify no broken links or structural issues were introduced.
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
name: handoff
|
||||
description: >
|
||||
After substantial implementation work, check whether the tome knowledge layer needs
|
||||
updating before you hand off — use impact analysis to find wiki docs and CLAUDE.md
|
||||
routers affected by the files you changed, triage what actually needs updating, and
|
||||
validate the result. Human-triggered. Use at the end of a feature, refactor, or
|
||||
structural change. Skip for bug fixes, minor refactors, and implementation details.
|
||||
disable-model-invocation: true
|
||||
allowed-tools: Bash(just:*), Bash(uv run:*), Bash(git:*)
|
||||
---
|
||||
|
||||
# Tome — Handoff
|
||||
|
||||
A targeted knowledge-layer check keyed to the files you just changed. Target: 5-10
|
||||
minutes of agent time. This is NOT a full curation pass.
|
||||
|
||||
## Step 1: Detect what changed
|
||||
|
||||
```bash
|
||||
# Files changed on this branch vs main
|
||||
git diff --name-only main...HEAD
|
||||
|
||||
# Or against a specific number of commits
|
||||
git diff --name-only HEAD~3
|
||||
```
|
||||
|
||||
If the change was a single targeted fix (one file, no structural impact), you can
|
||||
skip to Step 5 (validate). Impact analysis pays off for multi-file, structural, or
|
||||
architectural changes.
|
||||
|
||||
## Step 2: Run impact analysis
|
||||
|
||||
Pipe the changed paths into the `impact` subcommand:
|
||||
|
||||
```bash
|
||||
# Via just (preferred)
|
||||
just tome impact src/path/file.rs src/path/other.rs
|
||||
|
||||
# Or pipe from git diff
|
||||
git diff --name-only main...HEAD | uv run -q --script <tome-plugin-dir>/bin/knowledge.py impact
|
||||
```
|
||||
|
||||
The output groups hits into four buckets:
|
||||
|
||||
| Bucket | Meaning |
|
||||
|--------|---------|
|
||||
| **Direct hits** | Wiki docs whose `source-paths` list the exact changed file |
|
||||
| **Directory hits** | Wiki docs whose `source-paths` list a parent directory |
|
||||
| **Control file hits** | `CLAUDE.md` routers in ancestor directories |
|
||||
| **Potential stale** | Same-module wiki docs (weak signal only) |
|
||||
|
||||
## Step 3: Triage — decide what actually needs updating
|
||||
|
||||
Work top-down by bucket priority: direct -> directory -> control -> potential.
|
||||
|
||||
**Direct and directory hits** — these wiki docs explicitly cover the changed code:
|
||||
- Read the doc and check whether any stated facts are now wrong
|
||||
- Look for: named components/systems that were renamed, removed, or replaced;
|
||||
described lifecycles that changed; documented hazards that were resolved or
|
||||
introduced; architectural claims that no longer hold
|
||||
|
||||
**Control file hits** — CLAUDE.md routers:
|
||||
- Check if the module's stated purpose, key types, or entry points still match
|
||||
- These usually only need updates for module renames, splits, or new cross-cutting
|
||||
dependencies
|
||||
|
||||
**Potential stale** — skim only if the change was structural:
|
||||
- New module added, file moved, concept renamed -> worth a look
|
||||
- Bug fix, refactor within same module -> skip
|
||||
|
||||
**Most changes need no wiki updates.** The triage step often concludes: nothing to do.
|
||||
|
||||
## Step 4: Fix what is actually wrong
|
||||
|
||||
Update only what you can confirm is incorrect. Do not speculatively rewrite.
|
||||
|
||||
**Update wiki docs when:**
|
||||
- A named component, system, plugin, or resource was renamed or removed
|
||||
- A lifecycle or state machine changed (new states, different transitions)
|
||||
- A new hazard or known failure mode was introduced
|
||||
- A documented integration pattern no longer applies
|
||||
|
||||
**Update CLAUDE.md routers when:**
|
||||
- The module's primary responsibility changed
|
||||
- A new domain, plugin, or cross-cutting dependency was added
|
||||
- Key entry-point files moved or were renamed
|
||||
|
||||
**Do NOT update for:**
|
||||
- Bug fixes and implementation detail changes
|
||||
- Internal refactors that don't change public contracts or architecture
|
||||
- Performance tweaks, test additions, or formatting changes
|
||||
- Content that is already accurate but could be "improved"
|
||||
|
||||
**Adding new wiki content** — only if the change introduced something the wiki
|
||||
*should* cover: a new domain, a new hazard class, a new architectural pattern. Apply
|
||||
the "earned place" test: would removing this force an agent to do thinking work, or
|
||||
just a tool call?
|
||||
|
||||
## Step 5: Validate
|
||||
|
||||
```bash
|
||||
just tome check
|
||||
```
|
||||
|
||||
Confirms no broken links or structural issues were introduced. Fix any errors before
|
||||
handing off.
|
||||
@@ -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
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
name: navigate
|
||||
description: >
|
||||
Repository orientation and navigation for this codebase. Resolves the warnings,
|
||||
required reading, relevant commands, and folder navigation that apply to a target
|
||||
path. Use this BEFORE doing substantial work in an unfamiliar area of the codebase —
|
||||
starting in a new module, switching context to a different subsystem, exploring
|
||||
project structure, or whenever you are unsure which constraints and docs govern the
|
||||
code you are about to touch. Prefer this over guessing where the rules live.
|
||||
allowed-tools: Bash(just:*), Bash(uv run:*)
|
||||
---
|
||||
|
||||
# Tome — Navigate
|
||||
|
||||
The knowledge layer keeps a *navigation plane* (where to go, what to read, what to
|
||||
avoid) separate from the *source* (the executable truth). This skill resolves that
|
||||
navigation for the path you are about to work in, so you do not have to rediscover the
|
||||
project's conventions from scratch.
|
||||
|
||||
## Before substantial work
|
||||
|
||||
1. Read `wiki/boot.md` (from repo root) for project identity and orientation — what the
|
||||
project is, key folders, essential commands, and where executable truth lives.
|
||||
If it does not exist, run `just tome bootstrap` (or the knowledge.py bootstrap command) to generate it.
|
||||
|
||||
2. Resolve context for your target path:
|
||||
|
||||
```bash
|
||||
just tome context "<target-path>"
|
||||
```
|
||||
|
||||
(Equivalent without the Justfile: `uv run -q --script <tome-plugin-dir>/bin/knowledge.py context "<target-path>"`)
|
||||
|
||||
3. Read the **Warnings** and **Read first** references it returns before editing.
|
||||
Warnings are constraints that an agent should know *before* deciding what to inspect.
|
||||
|
||||
4. **NAV files are selective pointers, not complete inventories.** They list the 5-15
|
||||
most important entry points with context about why each matters. Always supplement
|
||||
with `ls` or `glob` when you need a complete directory listing. If a NAV file has
|
||||
`status: stub`, it hasn't been curated yet — treat it as a starting point, not
|
||||
authoritative navigation.
|
||||
|
||||
5. Still inspect the source before making executable claims about behavior. Wiki prose
|
||||
explains *how to understand* an area; it is not authoritative for current behavior,
|
||||
signatures, or registrations — the code is.
|
||||
|
||||
6. **Correct on contact.** If the source contradicts a wiki claim you relied on, fix
|
||||
that claim (or, if unsure of the correct version, mark it `[unverified]` or add a
|
||||
`wiki/_triage.md` note) before moving on. Distributed micro-corrections during
|
||||
normal work are the cheapest curation the wiki gets — do not leave known-wrong
|
||||
statements for a future curation pass to find.
|
||||
|
||||
## After substantial work
|
||||
|
||||
If you changed structure, routes, or documented behavior, consider running
|
||||
`/tome:handoff` (or at minimum `/tome:check`) to verify knowledge-layer health.
|
||||
|
||||
## Reference
|
||||
|
||||
- `wiki/boot.md` — project identity: what the project is, toolchains, key folders, essential commands, critical warnings
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
status: generated
|
||||
source-paths: []
|
||||
---
|
||||
|
||||
# Detected Tooling
|
||||
|
||||
This file is generated by `knowledge.py bootstrap` or `knowledge.py refresh` and
|
||||
reflects the toolchains, commands, and scripts detected in the host project.
|
||||
|
||||
Run `just tome init` (or `knowledge.py bootstrap`) to populate this file with
|
||||
project-specific tooling information.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Tome — knowledge-layer recipes (self-contained).
|
||||
#
|
||||
# This file ships WITH the plugin so the tome command surface travels with it.
|
||||
# A host project opts in with one line in its own Justfile:
|
||||
#
|
||||
# mod tome "<path-to-spire-plugin>/skills/tome/tome.just"
|
||||
#
|
||||
# ...then drives it as `just tome init`, `just tome context <path>`, etc.
|
||||
#
|
||||
# just runs a module's recipes with the working directory set to THIS file's
|
||||
# directory, so the tool is referenced by a plain relative path. `uv run
|
||||
# --no-project` provides a Python interpreter without depending on any host
|
||||
# project or `python` being on PATH. Nothing here reaches into the host repo;
|
||||
# the tool itself discovers the repository root via `git`.
|
||||
|
||||
# A host project may export RUST_LOG (e.g. via dotenv) for its own Rust builds.
|
||||
# uv honours RUST_LOG and would then print resolver traces, so silence it for
|
||||
# our invocations. Scoped to this module; does not affect the host's recipes.
|
||||
export RUST_LOG := "off"
|
||||
|
||||
knowledge := "uv run -q --script bin/knowledge.py"
|
||||
|
||||
# Show the available tome recipes
|
||||
default:
|
||||
@echo "tome — knowledge layer. Recipes: init | refresh | context <path> | check | impact <paths...>"
|
||||
|
||||
# Initialize the knowledge layer (scaffold wiki + navigation resources)
|
||||
init:
|
||||
{{ knowledge }} bootstrap
|
||||
|
||||
# Refresh deterministic resources; report authored knowledge needing review
|
||||
refresh:
|
||||
{{ knowledge }} refresh
|
||||
|
||||
# Resolve navigation context for a path. Usage: just tome context src/game/weapons
|
||||
context path:
|
||||
{{ knowledge }} context "{{ path }}"
|
||||
|
||||
# Validate knowledge-layer health (CI-friendly; non-zero exit on errors)
|
||||
check:
|
||||
{{ knowledge }} check
|
||||
|
||||
# Show which wiki docs are affected by changed files. Usage: just tome impact src/foo.rs src/bar.rs
|
||||
impact +paths:
|
||||
{{ knowledge }} impact {{ paths }}
|
||||
Reference in New Issue
Block a user