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)
61 lines
2.8 KiB
Markdown
61 lines
2.8 KiB
Markdown
---
|
|
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
|