🏗️ 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,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.
|
||||
Reference in New Issue
Block a user