Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

release: 0.7.1 — tools-in-directive orientation + leaner skill

Shrish Dwivedi85a17d00548c
diff --git a/.claude/skills/graft/SKILL.md b/.claude/skills/graft/SKILL.md
index 314bce99..5be5c060 100644
--- a/.claude/skills/graft/SKILL.md
+++ b/.claude/skills/graft/SKILL.md
@@ -1,93 +1,121 @@
---
name: graft
-description: This repo is indexed by graft/. For ANY task here — understanding
- how something works, finding where code lives, or scoping a change — get your
- context from graft before grepping or reading source files.
+description: This repo is indexed by graft/. For ANY task here, whether
+ understanding how something works, finding where code lives, tracing what
+ calls a symbol or what a change breaks, or scoping an edit, get your context
+ from graft before grepping or reading source files.
---
# graft
-This repo's code is summarised in `graft/` — small markdown nodes, each
-explaining one part in plain prose and naming the exact files and line-spans it
-covers. Reading a node costs a few hundred tokens; reading source to rebuild the
-same understanding costs thousands.
-
-**Choose the graft tool by task shape — pick the one that answers in a single call:**
-
-- **Locate / understand / "how does X work"** → `graft ask "<task>" --source` —
- ranked nodes with the code inlined (`--source` gives each hit's ≤8-line crux;
- add `--full` only if the crux isn't enough). For a genuinely multi-part
- question, ask once per distinct sub-aspect. **But if an ask returns few or
- weak hits, do NOT re-ask with reworded phrasings — switch tool** (below). The
- ask output tells you when to switch.
-- **Every occurrence / "all the X" / a symbol or literal everywhere** →
- `graft grep "<literal>"` — exhaustive, grouped by enclosing symbol. Ranked
- ask is top-N and WILL miss instances; grep is the tool for "find them all".
-- **A file's whole API surface** → `graft skeleton <file>` — every signature in
- ~200 tokens. One call beats several asks when you just need "what's in here".
-- **Who uses / what breaks if I change X** → `graft callers <symbol>` (add
- `--depth N` to walk transitively for the full blast radius); what X itself
- depends on → `graft callers <symbol> --direction out`. Run one before
- editing a symbol.
-- **First contact with an unfamiliar repo** → `graft map` — token-budgeted
- orientation (dir clusters, hubs, hotspots). Read the hub cards it names rather
- than asking per subsystem.
-- **Monorepos / a folder of multiple repos** → graft ranks fairly across
- sub-projects instead of letting the biggest one drown the rest; hits carry
- `[scope/]` labels naming which sub-project they're from. Know where you're
- working? Narrow with `graft ask "<task>" --in <scope>/`.
-
-You can also grep / ls / cat inside `graft/` directly (the nodes are plain
-markdown; `graft/INDEX.md` lists them) — but the commands above are faster and
-exhaustive where it matters, so reach for them first.
-
-**Match the tool to the task shape:**
-
-- **Understanding, explaining, locating where a change goes** — the node IS the
- answer. Cite files and functions straight from its `covers:` list — it gives
- the exact `file:line` for every symbol, so you can cite precisely without
- opening the source. The spans are generated from that source and are
- authoritative; don't re-open files just to "double-check" them.
-- **Editing:** run `graft ask "<symbol>" --source` to pull the exact span's
- code inline, and edit straight from that. Touch the file only to apply the
- change at the named `file:line` — never read the whole file to get oriented;
- the pack already oriented you.
-- **Exhaustive tasks — "every occurrence / every provider / every caller of
- this pattern":** ranked results are top-N, not a complete list. Run
- `graft grep "<literal>"` instead — it's exhaustive over every indexed file,
- grouped by enclosing symbol, and tells you what it couldn't see (unreadable
- or unindexed files). Fall back to raw `grep -rn` only for files graft
- doesn't index (docs, configs, new files). Ask alone will miss instances;
- that is expected, not a graft failure.
-
-**Precise graph modes** — for structural questions, skip ranking and go
-straight to precomputed edges. It's all one command, `graft callers`:
-
-- `graft callers <symbol>` — who calls/references this (exact edges, not text);
- structural phrasing inside ask ("who calls X") routes here too.
-- `graft callers <symbol> --direction out` — the reverse: what this symbol
- itself calls/depends on (the old `callees`).
-- `graft callers <symbol> --depth N` — walk transitively out to depth N for the
- full blast radius of a change (the old `impact`).
-
-When the graft MCP server is connected, the same operations are exposed as
-tools — `graft_ask`, `graft_callers` (with `direction`/`depth`),
-`graft_grep`, `graft_skeleton`, `graft_map` — prefer whichever surface is
-available.
-
-If a returned span is truncated ("+N more lines"), open the file at that exact
-range before finalizing.
-
-**Report what graft saved — every turn.** Each retrieval tool ends its output
-with a `[graft] tokens saved ≈ N` line: the estimated tokens that one call
-saved versus reading the files it covers whole. Whenever you used any graft tool
-in a turn, close your reply with a one-line tally that sums those numbers across
-every graft call you made — e.g. `🌱 graft saved ~12,400 tokens this turn (3
-calls)`. A call with no footer (tiny files, where the pointers cost as much as
-the source) saved nothing — skip it. This is the per-turn figure; the statusline
-carries the running session total.
-
-If a node genuinely lacks a detail you need, ask for a more specific node, and
-if it still lacks it, read the source — at the exact file:line the node points
-to, not the whole file. Reading whole source files to build understanding is
-the thing graft exists to replace.
+`graft/` holds a graph of this repo: small markdown nodes that each explain one
+part in prose and name the exact `file:line` spans they cover, plus a wiring
+graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
+that understanding by reading source costs thousands, and misses the edges.
+
+Every command below is `$0`, needs no API key, and returns in under a second.
+There are six of them. **Pick the one that fits the task, run it, act on the
+answer; don't chain tools hoping for more. Most tasks need one call.**
+
+## The tools
+
+### 1 · `graft ask "<question>" --source`: locate + understand (the default)
+Ranked retrieval over the graph, routed automatically between prose nodes and
+the wiring graph, returning the top hits with exact `file:line`.
+- `--source` inlines the code at each hit, the ≤8-line **crux** of each
+ definition, so the result IS the code you need, no follow-up file read. Add
+ `--full` only when the crux is too small to act on.
+- `--in <path>` narrows to a subtree before ranking; `-n N` caps results (default 8).
+- **Use it when** the question is conceptual or locational: "how does auth
+ work", "where is rate-limiting handled", "what assembles the request pipeline".
+- One ask usually answers. A genuinely multi-part question needs one ask per
+ distinct sub-aspect, never the same question reworded. Few or weak hits mean
+ switch tool (grep / skeleton / callers), don't re-ask.
+
+### 2 · `graft grep "<pattern>"`: exhaustive find
+Regex (or `--fixed` for a literal) over every indexed file, hits **grouped by
+enclosing symbol** and ranked by coupling; it also reports files it couldn't read.
+- **Use it when** you need every occurrence: all call sites, all uses of a
+ constant, all providers. `ask` is ranked top-N and *will* miss instances;
+ grep won't. One grep replaces a spray of asks.
+- `-i` case-insensitive; `--in <path>` scopes to a subtree. Fall back to raw
+ `grep -rn` only for files graft doesn't index (docs, configs, new files).
+
+### 3 · `graft skeleton <file>`: a file's API at a glance
+Signatures-only view of one file (every function / method / type with its span)
+in ~200 tokens, ~10x cheaper than reading the file.
+- **Use it when** you need "what's in this file / what can I call here" before
+ editing or wiring into it. One skeleton is the whole answer for a file; don't
+ re-skeleton the same file, and don't skeleton every file `map` already named.
+
+### 4 · `graft callers <symbol>`: the exact edges
+Precomputed call/reference edges, not a text search. Symbol can be bare
+(`Foo`), qualified (`Class.method`), or package-qualified (`pkg.Fn`).
+- default `--direction in`: **who calls/references** this; run before you
+ rename, delete, or change its signature.
+- `--direction out`: **what this symbol itself calls/depends on** (the old `callees`).
+- `--depth N`: walk transitively N hops for the **full blast radius** (the old
+ `impact`); `--depth 2` is the usual "what breaks if I touch this".
+
+### 5 · `graft map`: orientation for an unfamiliar repo or area
+A token-budgeted tour: directory clusters, per-directory hubs, and global
+hotspots, straight from the wiring graph.
+- **Use it when** you land in a repo cold or are asked for "the architecture".
+ `map` alone is the answer: read the hub cards it names; do NOT then skeleton
+ or ask your way through every subsystem it lists. `--max-dirs N` widens it.
+
+### 6 · Lifecycle: `graft build` / `graft check`
+`build` regenerates the graph after code changes (`$0`; `--deep` adds an LLM
+concept map, skip unless asked). `check` fails when `graft/` is stale (for CI).
+You rarely touch these mid-task; the graph is already built and committed.
+
+## Scenarios: the shortest path through a coding task
+
+| When you're… | Reach for | Calls |
+|---|---|---|
+| Onboarding / "explain this codebase" | `graft map`, then read the named hub cards | 1 |
+| Understanding a flow ("how does X work") | `graft ask "<flow>" --source` | 1 |
+| Finding where a change belongs | `graft ask "where is <behavior>" --source` | 1 |
+| Editing a known symbol | `graft ask "<symbol>" --source`, edit at the `file:line` | 1 |
+| Renaming / deleting / changing a signature | `graft callers <sym> --depth 2` first | 1 |
+| "What does this depend on?" | `graft callers <sym> --direction out` | 1 |
+| Finding every occurrence of a pattern | `graft grep "<literal>"` | 1 |
+| "What's the API of this file?" | `graft skeleton <file>` | 1 |
+| Debugging a failure in area X | `graft ask "<symptom>" --source`, then `callers` on the suspect | 1–2 |
+| Judging a diff's risk before merge | `graft callers <changed sym> --depth 2` | 1 / symbol |
+| Working inside one repo of a monorepo | add `--in <scope>/` to ask / grep / callers | n/a |
+
+In a multi-repo workspace, graft ranks fairly so the biggest repo can't drown
+the rest, and every hit carries a `[scope/]` label naming its sub-project; when
+you already know where you're working, narrow with `graft ask "<task>" --in <scope>/`.
+
+## Spend the fewest calls
+- A node's `covers:` list already gives exact `file:line` for every symbol, so
+ cite straight from it. The spans are generated from source and authoritative;
+ don't re-open or re-grep files to "double-check".
+- When editing, pull the span with `graft ask "<symbol>" --source` and edit at
+ that `file:line`; never read the whole file to orient, the pack did that.
+- Trust the answer and act. Reach for a second tool only when the first genuinely
+ fell short: weak hits, a truncated span, or a need to be exhaustive.
+
+## Report what graft saved, every turn
+Each retrieval tool ends its output with a `[graft] tokens saved ≈ N` line: the
+estimated tokens that call saved versus reading the files it covers whole.
+Whenever you used any graft tool in a turn, close your reply with a one-line
+tally summing those numbers across every graft call you made, e.g.
+`🌱 graft saved ~12,400 tokens this turn (3 calls)`. A call with no footer (tiny
+files, where the pointers cost as much as the source) saved nothing, so skip it.
+This is the per-turn figure; the statusline carries the running session total.
+
+## When graft isn't enough
+- Span truncated ("+N more lines"): open the file at that exact range.
+- A node lacks a detail: ask a more specific question; only then read source at
+ the exact `file:line`, never a whole file to rebuild understanding graft gives.
+- You may also grep / ls / cat inside `graft/` directly (plain markdown;
+ `graft/INDEX.md` indexes the nodes), but the tools above are faster and
+ exhaustive where it matters, so reach for them first.
+
+When the graft MCP server is connected, these are exposed as tools too:
+`graft_ask`, `graft_grep`, `graft_skeleton`, `graft_callers` (with
+`direction` / `depth`), `graft_map`, `graft_check`. Use whichever surface is
+available; the guidance is identical.
diff --git a/package.json b/package.json
index 53cf6bfd..c6a6e2e3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@nanonets/graft",
- "version": "0.7.0",
+ "version": "0.7.1",
"description": "Build a repo's context graph as a folder of linked markdown files that live in the repo and stay in sync with the code through git.",
"keywords": [
"ai",
diff --git a/src/claude/format.ts b/src/claude/format.ts
index a07bce53..d6a3a010 100644
--- a/src/claude/format.ts
+++ b/src/claude/format.ts
@@ -63,7 +63,7 @@ export function formatBlastRadius(w: GraphV1, filePath: string, cap = 8): string
return ` • ${e.relation} ← ${label}`;
});
const more = edges.length > cap ? `\n • +${edges.length - cap} more` : '';
- return `[graft] blast radius for ${basename(filePath)} — who depends on it:\n${items.join('\n')}${more}`;
+ return `[graft] blast radius for ${basename(filePath)}, who depends on it:\n${items.join('\n')}${more}`;
}
export interface AskJson {
@@ -84,7 +84,7 @@ function retrievalBody(hits: AskJson['hits']): string {
const blocks = hits.map((h, i) => {
const ptr = (h.pointer ?? '').split(',')[0].trim();
const snip = (h.snippet ?? '').replace(/\s+/g, ' ').trim().slice(0, 140);
- let b = ` ${i + 1}. ${h.title} — ${ptr}`;
+ let b = ` ${i + 1}. ${h.title}: ${ptr}`;
if (snip) b += `\n ${snip}`;
if (h.code) b += `\n\`\`\`\n${h.code}\n\`\`\``;
return b;
@@ -94,8 +94,8 @@ function retrievalBody(hits: AskJson['hits']): string {
// pulling spans itself via `graft ask --source` (push→pull: per-prompt injected
// tokens are always fresh full-price input, so the pack stays tiny).
const header = hits.some((h) => h.code)
- ? '[graft] retrieved context — read these spans, do not re-open the files:'
- : '[graft] starting points for this task — pull the code inline with `graft ask "<what you need>" --source`, trace impact with `graft callers <symbol>`, or search with `graft grep "<literal>"`:';
+ ? '[graft] retrieved context, read these spans; do not re-open the files:'
+ : '[graft] starting points for this task: pull the code inline with `graft ask "<what you need>" --source`, trace impact with `graft callers <symbol>`, or search with `graft grep "<literal>"`:';
return `${header}\n${blocks.join('\n')}`;
}
@@ -117,7 +117,7 @@ export function formatRetrieval(ask: AskJson, cap = 5): string | null {
const base = tokensOf(ask.saved!.baselineChars);
const pct = Math.round((saved / base) * 100);
return (
- `${body}\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%) — this pack ≈ ` +
+ `${body}\n[graft] tokens saved ≈ ${saved.toLocaleString()} (${pct}%); this pack ≈ ` +
`${tokensOf(body.length).toLocaleString()} tok vs reading the ${ask.saved!.files} file(s) whole ≈ ` +
`${base.toLocaleString()} tok (estimate).`
);
@@ -156,14 +156,20 @@ export function relevantRetrieval(ask: AskJson, s: SessionState, cap = 3): strin
export function formatOrientation(indexMd: string, budgetBytes = 1500): string {
// Always-on directive (cached, seen turn 0) so the agent reaches for graft's
- // commands without waiting for the discretionary skill to load. Positive only
- // — names the tools, forbids nothing.
+ // commands without waiting for the discretionary skill to load. This is the
+ // reliable steering channel (fires every session, unlike the discretionary
+ // skill): it carries a one-line description of each tool AND the call-discipline
+ // that keeps the agent from over-tooling. Positive only, names the tools,
+ // forbids nothing.
const directive =
- `[graft] This repo is indexed by graft. To find or understand code, reach for graft first — it cites exact file:line and is faster than grep/read:\n` +
- ` • graft ask "<task>" --source — the relevant code, inline (skip the file read)\n` +
- ` • graft callers <sym> --depth 2 — who/what breaks if it changes\n` +
- ` • graft grep "<literal>" — exhaustive search, grouped by enclosing symbol\n` +
- ` • graft skeleton <file> · graft map — a file's API · whole-repo orientation\n`;
+ `[graft] This repo is indexed by graft. To find, understand, or change code, reach for graft first; it answers from a prebuilt graph with exact file:line, faster than grep/read. Pick the ONE tool that fits and act on its answer. Most tasks need a single call. If one isn't enough, switch to the tool that fits the next need; don't call the same tool again and again or re-ask a question reworded:\n` +
+ ` • graft ask "<task>" --source: locate + understand. Ranked nodes with the code inlined at each file:line (the ≤8-line crux; add --full for the whole span). The default for "how does X work" / "where is Y".\n` +
+ ` • graft grep "<literal>": exhaustive find. Every occurrence, grouped by enclosing symbol; use when you need them ALL (ask is ranked top-N and misses instances).\n` +
+ ` • graft skeleton <file>: a file's whole API in ~200 tokens, every signature + span, ~10x cheaper than reading the file.\n` +
+ ` • graft callers <sym> [--direction out] [--depth N]: exact edges. Who calls it (default), what it calls (--direction out), or the full blast radius (--depth 2). Run before you change a symbol.\n` +
+ ` • graft map: orientation for an unfamiliar repo, directory clusters, hubs, hotspots. map alone is the answer; don't then skeleton every subsystem it names.\n` +
+ ` In a monorepo, add --in <path>/ to ask/grep/callers to scope to one sub-project; hits are labeled [scope/].\n` +
+ `Each tool prints a "[graft] tokens saved ≈ N" footer; when you used graft this turn, close your reply with a one-line tally of the total saved (e.g. 🌱 graft saved ~12k tokens this turn, 3 calls).\n`;
return `${directive}\nrepo map (graft/INDEX.md):\n${indexMd.slice(0, budgetBytes)}`;
}
diff --git a/src/claude/skill-template.ts b/src/claude/skill-template.ts
index 0f49c036..8da65e40 100644
--- a/src/claude/skill-template.ts
+++ b/src/claude/skill-template.ts
@@ -1,101 +1,129 @@
// The graft Claude Code skill, bundled as a string so `graft init` can write it into a
-// consumer repo's .claude/skills/graft/SKILL.md — no network fetch, version-locked to the
-// installed graft. This is the single source of truth for the skill text; graft's own
+// consumer repo's .claude/skills/graft/SKILL.md (no network fetch, version-locked to the
+// installed graft). This is the single source of truth for the skill text; graft's own
// repo copy is regenerated from here when `init` runs in this repo. Mirrors the `.cjs`
// shim pattern in shim-template.ts.
export function skillTemplate(): string {
return `---
name: graft
-description: This repo is indexed by graft/. For ANY task here — understanding
- how something works, finding where code lives, or scoping a change — get your
- context from graft before grepping or reading source files.
+description: This repo is indexed by graft/. For ANY task here, whether
+ understanding how something works, finding where code lives, tracing what
+ calls a symbol or what a change breaks, or scoping an edit, get your context
+ from graft before grepping or reading source files.
---
# graft
-This repo's code is summarised in \`graft/\` — small markdown nodes, each
-explaining one part in plain prose and naming the exact files and line-spans it
-covers. Reading a node costs a few hundred tokens; reading source to rebuild the
-same understanding costs thousands.
-
-**Choose the graft tool by task shape — pick the one that answers in a single call:**
-
-- **Locate / understand / "how does X work"** → \`graft ask "<task>" --source\` —
- ranked nodes with the code inlined (\`--source\` gives each hit's ≤8-line crux;
- add \`--full\` only if the crux isn't enough). For a genuinely multi-part
- question, ask once per distinct sub-aspect. **But if an ask returns few or
- weak hits, do NOT re-ask with reworded phrasings — switch tool** (below). The
- ask output tells you when to switch.
-- **Every occurrence / "all the X" / a symbol or literal everywhere** →
- \`graft grep "<literal>"\` — exhaustive, grouped by enclosing symbol. Ranked
- ask is top-N and WILL miss instances; grep is the tool for "find them all".
-- **A file's whole API surface** → \`graft skeleton <file>\` — every signature in
- ~200 tokens. One call beats several asks when you just need "what's in here".
-- **Who uses / what breaks if I change X** → \`graft callers <symbol>\` (add
- \`--depth N\` to walk transitively for the full blast radius); what X itself
- depends on → \`graft callers <symbol> --direction out\`. Run one before
- editing a symbol.
-- **First contact with an unfamiliar repo** → \`graft map\` — token-budgeted
- orientation (dir clusters, hubs, hotspots). Read the hub cards it names rather
- than asking per subsystem.
-- **Monorepos / a folder of multiple repos** → graft ranks fairly across
- sub-projects instead of letting the biggest one drown the rest; hits carry
- \`[scope/]\` labels naming which sub-project they're from. Know where you're
- working? Narrow with \`graft ask "<task>" --in <scope>/\`.
-
-You can also grep / ls / cat inside \`graft/\` directly (the nodes are plain
-markdown; \`graft/INDEX.md\` lists them) — but the commands above are faster and
-exhaustive where it matters, so reach for them first.
-
-**Match the tool to the task shape:**
-
-- **Understanding, explaining, locating where a change goes** — the node IS the
- answer. Cite files and functions straight from its \`covers:\` list — it gives
- the exact \`file:line\` for every symbol, so you can cite precisely without
- opening the source. The spans are generated from that source and are
- authoritative; don't re-open files just to "double-check" them.
-- **Editing:** run \`graft ask "<symbol>" --source\` to pull the exact span's
- code inline, and edit straight from that. Touch the file only to apply the
- change at the named \`file:line\` — never read the whole file to get oriented;
- the pack already oriented you.
-- **Exhaustive tasks — "every occurrence / every provider / every caller of
- this pattern":** ranked results are top-N, not a complete list. Run
- \`graft grep "<literal>"\` instead — it's exhaustive over every indexed file,
- grouped by enclosing symbol, and tells you what it couldn't see (unreadable
- or unindexed files). Fall back to raw \`grep -rn\` only for files graft
- doesn't index (docs, configs, new files). Ask alone will miss instances;
- that is expected, not a graft failure.
-
-**Precise graph modes** — for structural questions, skip ranking and go
-straight to precomputed edges. It's all one command, \`graft callers\`:
-
-- \`graft callers <symbol>\` — who calls/references this (exact edges, not text);
- structural phrasing inside ask ("who calls X") routes here too.
-- \`graft callers <symbol> --direction out\` — the reverse: what this symbol
- itself calls/depends on (the old \`callees\`).
-- \`graft callers <symbol> --depth N\` — walk transitively out to depth N for the
- full blast radius of a change (the old \`impact\`).
-
-When the graft MCP server is connected, the same operations are exposed as
-tools — \`graft_ask\`, \`graft_callers\` (with \`direction\`/\`depth\`),
-\`graft_grep\`, \`graft_skeleton\`, \`graft_map\` — prefer whichever surface is
-available.
-
-If a returned span is truncated ("+N more lines"), open the file at that exact
-range before finalizing.
-
-**Report what graft saved — every turn.** Each retrieval tool ends its output
-with a \`[graft] tokens saved ≈ N\` line: the estimated tokens that one call
-saved versus reading the files it covers whole. Whenever you used any graft tool
-in a turn, close your reply with a one-line tally that sums those numbers across
-every graft call you made — e.g. \`🌱 graft saved ~12,400 tokens this turn (3
-calls)\`. A call with no footer (tiny files, where the pointers cost as much as
-the source) saved nothing — skip it. This is the per-turn figure; the statusline
-carries the running session total.
-
-If a node genuinely lacks a detail you need, ask for a more specific node, and
-if it still lacks it, read the source — at the exact file:line the node points
-to, not the whole file. Reading whole source files to build understanding is
-the thing graft exists to replace.
+\`graft/\` holds a graph of this repo: small markdown nodes that each explain one
+part in prose and name the exact \`file:line\` spans they cover, plus a wiring
+graph of who-calls-what. Querying a node costs a few hundred tokens; rebuilding
+that understanding by reading source costs thousands, and misses the edges.
+
+Every command below is \`$0\`, needs no API key, and returns in under a second.
+There are six of them. **Pick the one that fits the task, run it, act on the
+answer; don't chain tools hoping for more. Most tasks need one call.**
+
+## The tools
+
+### 1 · \`graft ask "<question>" --source\`: locate + understand (the default)
+Ranked retrieval over the graph, routed automatically between prose nodes and
+the wiring graph, returning the top hits with exact \`file:line\`.
+- \`--source\` inlines the code at each hit, the ≤8-line **crux** of each
+ definition, so the result IS the code you need, no follow-up file read. Add
+ \`--full\` only when the crux is too small to act on.
+- \`--in <path>\` narrows to a subtree before ranking; \`-n N\` caps results (default 8).
+- **Use it when** the question is conceptual or locational: "how does auth
+ work", "where is rate-limiting handled", "what assembles the request pipeline".
+- One ask usually answers. A genuinely multi-part question needs one ask per
+ distinct sub-aspect, never the same question reworded. Few or weak hits mean
+ switch tool (grep / skeleton / callers), don't re-ask.
+
+### 2 · \`graft grep "<pattern>"\`: exhaustive find
+Regex (or \`--fixed\` for a literal) over every indexed file, hits **grouped by
+enclosing symbol** and ranked by coupling; it also reports files it couldn't read.
+- **Use it when** you need every occurrence: all call sites, all uses of a
+ constant, all providers. \`ask\` is ranked top-N and *will* miss instances;
+ grep won't. One grep replaces a spray of asks.
+- \`-i\` case-insensitive; \`--in <path>\` scopes to a subtree. Fall back to raw
+ \`grep -rn\` only for files graft doesn't index (docs, configs, new files).
+
+### 3 · \`graft skeleton <file>\`: a file's API at a glance
+Signatures-only view of one file (every function / method / type with its span)
+in ~200 tokens, ~10x cheaper than reading the file.
+- **Use it when** you need "what's in this file / what can I call here" before
+ editing or wiring into it. One skeleton is the whole answer for a file; don't
+ re-skeleton the same file, and don't skeleton every file \`map\` already named.
+
+### 4 · \`graft callers <symbol>\`: the exact edges
+Precomputed call/reference edges, not a text search. Symbol can be bare
+(\`Foo\`), qualified (\`Class.method\`), or package-qualified (\`pkg.Fn\`).
+- default \`--direction in\`: **who calls/references** this; run before you
+ rename, delete, or change its signature.
+- \`--direction out\`: **what this symbol itself calls/depends on** (the old \`callees\`).
+- \`--depth N\`: walk transitively N hops for the **full blast radius** (the old
+ \`impact\`); \`--depth 2\` is the usual "what breaks if I touch this".
+
+### 5 · \`graft map\`: orientation for an unfamiliar repo or area
+A token-budgeted tour: directory clusters, per-directory hubs, and global
+hotspots, straight from the wiring graph.
+- **Use it when** you land in a repo cold or are asked for "the architecture".
+ \`map\` alone is the answer: read the hub cards it names; do NOT then skeleton
+ or ask your way through every subsystem it lists. \`--max-dirs N\` widens it.
+
+### 6 · Lifecycle: \`graft build\` / \`graft check\`
+\`build\` regenerates the graph after code changes (\`$0\`; \`--deep\` adds an LLM
+concept map, skip unless asked). \`check\` fails when \`graft/\` is stale (for CI).
+You rarely touch these mid-task; the graph is already built and committed.
+
+## Scenarios: the shortest path through a coding task
+
+| When you're… | Reach for | Calls |
+|---|---|---|
+| Onboarding / "explain this codebase" | \`graft map\`, then read the named hub cards | 1 |
+| Understanding a flow ("how does X work") | \`graft ask "<flow>" --source\` | 1 |
+| Finding where a change belongs | \`graft ask "where is <behavior>" --source\` | 1 |
+| Editing a known symbol | \`graft ask "<symbol>" --source\`, edit at the \`file:line\` | 1 |
+| Renaming / deleting / changing a signature | \`graft callers <sym> --depth 2\` first | 1 |
+| "What does this depend on?" | \`graft callers <sym> --direction out\` | 1 |
+| Finding every occurrence of a pattern | \`graft grep "<literal>"\` | 1 |
+| "What's the API of this file?" | \`graft skeleton <file>\` | 1 |
+| Debugging a failure in area X | \`graft ask "<symptom>" --source\`, then \`callers\` on the suspect | 1–2 |
+| Judging a diff's risk before merge | \`graft callers <changed sym> --depth 2\` | 1 / symbol |
+| Working inside one repo of a monorepo | add \`--in <scope>/\` to ask / grep / callers | n/a |
+
+In a multi-repo workspace, graft ranks fairly so the biggest repo can't drown
+the rest, and every hit carries a \`[scope/]\` label naming its sub-project; when
+you already know where you're working, narrow with \`graft ask "<task>" --in <scope>/\`.
+
+## Spend the fewest calls
+- A node's \`covers:\` list already gives exact \`file:line\` for every symbol, so
+ cite straight from it. The spans are generated from source and authoritative;
+ don't re-open or re-grep files to "double-check".
+- When editing, pull the span with \`graft ask "<symbol>" --source\` and edit at
+ that \`file:line\`; never read the whole file to orient, the pack did that.
+- Trust the answer and act. Reach for a second tool only when the first genuinely
+ fell short: weak hits, a truncated span, or a need to be exhaustive.
+
+## Report what graft saved, every turn
+Each retrieval tool ends its output with a \`[graft] tokens saved ≈ N\` line: the
+estimated tokens that call saved versus reading the files it covers whole.
+Whenever you used any graft tool in a turn, close your reply with a one-line
+tally summing those numbers across every graft call you made, e.g.
+\`🌱 graft saved ~12,400 tokens this turn (3 calls)\`. A call with no footer (tiny
+files, where the pointers cost as much as the source) saved nothing, so skip it.
+This is the per-turn figure; the statusline carries the running session total.
+
+## When graft isn't enough
+- Span truncated ("+N more lines"): open the file at that exact range.
+- A node lacks a detail: ask a more specific question; only then read source at
+ the exact \`file:line\`, never a whole file to rebuild understanding graft gives.
+- You may also grep / ls / cat inside \`graft/\` directly (plain markdown;
+ \`graft/INDEX.md\` indexes the nodes), but the tools above are faster and
+ exhaustive where it matters, so reach for them first.
+
+When the graft MCP server is connected, these are exposed as tools too:
+\`graft_ask\`, \`graft_grep\`, \`graft_skeleton\`, \`graft_callers\` (with
+\`direction\` / \`depth\`), \`graft_map\`, \`graft_check\`. Use whichever surface is
+available; the guidance is identical.
`;
}
diff --git a/test/claude-format.test.ts b/test/claude-format.test.ts
index 6f8f1d73..55abbae9 100644
--- a/test/claude-format.test.ts
+++ b/test/claude-format.test.ts
@@ -60,7 +60,7 @@ test('formatRetrieval renders top hits, trims snippet, first pointer only', () =
] } as any;
const txt = strip(formatRetrieval(ask)!);
assert.match(txt, /starting points for this task/); // pointers-only header (no inlined code)
- assert.match(txt, /PKCE — src\/pkce\.ts/);
+ assert.match(txt, /PKCE: src\/pkce\.ts/);
assert.match(txt, /Validates the challenge\./); // snippet trimmed, own line
assert.doesNotMatch(txt, /client\.ts/); // only the first pointer segment
});
@@ -69,7 +69,7 @@ test('formatRetrieval keeps the substitutive header when code is inlined', () =>
const ask = { query: 'pkce', mode: 'lexical', hits: [
{ kind: 'symbol', title: 'verify', pointer: 'src/pkce.ts:L1-L4', snippet: 's', score: 1, code: 'a\nb' },
] } as any;
- assert.match(strip(formatRetrieval(ask)!), /retrieved context — read these spans/);
+ assert.match(strip(formatRetrieval(ask)!), /retrieved context, read these spans/);
});
test('formatRetrieval appends a tokens-saved line when ask reports a baseline', () => {
@@ -131,8 +131,8 @@ test('formatOrientation labels and truncates to budget', () => {
const out = strip(formatOrientation(md, 1500));
assert.match(out, /repo map/);
assert.match(out, /reach for graft first/, 'always-on usage directive present');
- // index truncated to budget (1500) + the fixed usage directive header (~500).
- assert.ok(out.length < 2200, 'index trimmed to budget; only the fixed directive adds to it');
+ // index truncated to budget (1500) + the fixed usage directive (per-tool descriptions + discipline).
+ assert.ok(out.length < 3200, 'index trimmed to budget; only the fixed directive adds to it');
// Regression: `graft impact` was folded into `graft callers --depth` in 0.6.0 —
// the always-on directive must teach the current command, not a dead one.
assert.doesNotMatch(out, /graft impact\b/, 'does not teach the removed `graft impact` command');