---
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