dirigence/reliquary
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

🏗️ Extract tome from spire into standalone plugin

Browse Source 
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:
g4borg
2026-09-14 16:14:58 +02:00
parent dd9a49a6a2
commit cfd3cfb357
18 changed files with 126 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/tome/skills/curate/SKILL.md
+279
View File
@@ -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.