g4borg
cfd3cfb357
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)
108 lines
3.9 KiB
Markdown
108 lines
3.9 KiB
Markdown
---
|
|
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.
|