Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
feat(guidance): task-shape skill + instructions — validated by A/B; teaches graph commands
Shrish Dwivedif4bf84a7673d
diff --git a/README.md b/README.mdindex fc20c91a..78fb1e1e 100644--- a/README.md+++ b/README.md@@ -195,6 +195,10 @@ graft build --extensions .ts .py # only include these code extensionsgraft ask "<task>" [dir] # query the graph — ranked nodes + exact file:line (no LLM, no key)graft ask "<task>" --json # machine-readable result+graft callers <symbol> [dir] # who calls/references/imports/implements/extends a symbol (no LLM, no key)+graft callees <symbol> [dir] # what a symbol calls/references/imports/implements/extends (no LLM, no key)+graft impact <symbol> [dir] -d N # BFS over incoming edges — who breaks if this symbol changes (no LLM, no key)+graft check [dir] # fail (exit 1) if graft/ has drifted from the codegraft check --json # print the drift report as JSONdiff --git a/src/claude/skill-template.ts b/src/claude/skill-template.tsindex de223390..0bf2a2d3 100644--- a/src/claude/skill-template.ts+++ b/src/claude/skill-template.ts@@ -23,26 +23,44 @@ same understanding costs thousands.- Ask: \`graft ask "<your task, in plain words>"\` — returns the relevant nodes,ranked, with file:line pointers. Add \`--source\` to inline the actual code ateach span, so the result IS the code you need — no separate file read.+ Ask is cheap (<1s) — re-ask with different phrasings for each sub-question,+ and use structural forms too: \`graft ask "who calls <symbol>"\`.- Or explore as usual: grep / ls / cat inside \`graft/\`. A grep for any concept,symbol, or filename hits the node that covers it; \`graft/INDEX.md\` lists themall.-**Then STOP at the node. It is the answer, not a lookup toward the answer.**+**Match the tool to the task shape:**-- **Explaining / tracing / understanding** (no code change): the node's prose- IS your deliverable. Cite files and functions straight from its \`covers:\`- list — \`covers:\` gives you the exact \`file:line\` for every symbol, so you can- cite precisely **without opening the source at all.** Do NOT open source to- "verify," "confirm," or "see the real code" — the node was generated from that- source and the spans are authoritative. Opening it costs thousands of tokens- and changes nothing in your answer.+- **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. Only touch the file to apply the- change at the named \`file:line\` — never read the whole file, never open- neighbouring files to "get oriented"; the pack already oriented you.+ 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. Use graft to+ orient (what is the pattern, where does it live), then ENUMERATE with grep+ over the source and verify each hit. Ask alone will miss instances; that is+ expected, not a graft failure.-If a node genuinely lacks a detail you need, \`graft ask\` for a more specific-node before falling back to source. Reading whole source files to build-understanding is the thing graft exists to replace — it already did that work.+**Precise graph modes** — for structural questions, skip ranking and go+straight to precomputed edges:++- \`graft callers <symbol>\` / \`graft callees <symbol>\` — who breaks if this+ changes / what does this call — precomputed edges, exact answers; structural+ phrasing inside ask ("who calls X") routes here too.+- \`graft impact <symbol> [-d N]\` — BFS over incoming edges out to depth N: the+ full blast radius of a change.++If a returned span is truncated ("+N more lines"), open the file at that exact+range before finalizing.++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.`;}diff --git a/src/hosts/instructions.ts b/src/hosts/instructions.tsindex dcfc03ac..f49da7c3 100644--- a/src/hosts/instructions.ts+++ b/src/hosts/instructions.ts@@ -11,14 +11,24 @@ system and carry exact file:line spans, kept in sync with the code through git.For ANY task here — understanding how something works, finding where code lives,or scoping a change — get context from the graph before grepping or opening-source files:+source files. Re-ask freely (it's cheap) and reuse literal identifiers you+already have (symbol, error string, file name) as the query.- Run \`graft ask "<your question>" --source\` → ranked nodes with the relevant- code spans inlined. The node usually IS the answer; stop there.+ code spans inlined. Match the tool to the task shape: for understanding or+ editing, the top node IS the answer — cite its \`covers:\` file:line spans and+ edit straight from \`--source\`. For exhaustive tasks ("every occurrence /+ every caller of this pattern"), ranked results are top-N, not complete — use+ graft to orient, then enumerate with grep over the source and verify each hit.+- \`graft callers/callees <symbol>\` and \`graft impact <symbol> [-d N]\` give+ precomputed, exact edges — who calls/is called by a symbol, and the full+ blast radius — for structural questions, skip ranking and use these directly.- Or browse: \`graft/INDEX.md\` lists every node; follow the links.-Only open source files when a node genuinely lacks a needed detail, and then at-the exact file:line the node points to — never re-read whole files.+If a returned span is truncated ("+N more lines"), open the file at that exact+range before finalizing. Only open source files when a node genuinely lacks a+needed detail, and then at the exact file:line the node points to — never+re-read whole files.After big code changes, refresh the graph with \`graft build\` (deterministic,no API key, $0).`;diff --git a/test/claude-skill-template.test.ts b/test/claude-skill-template.test.tsindex 1655ca5f..ca63d087 100644--- a/test/claude-skill-template.test.ts+++ b/test/claude-skill-template.test.ts@@ -10,4 +10,9 @@ test('skill template is a well-formed SKILL.md', () => {const body = src.split(/\n---\n/)[1] ?? '';assert.ok(body.trim().length > 0, 'has a non-empty body');assert.match(body, /graft ask/, 'body tells the agent to use `graft ask`');+ assert.match(body, /every occurrence/i, 'body teaches the exhaustive-task grep rule');+ assert.match(body, /graft callers/, 'body teaches the callers command');+ assert.match(body, /graft callees/, 'body teaches the callees command');+ assert.match(body, /graft impact/, 'body teaches the impact command');+ assert.match(body, /truncated/i, 'body tells the agent to follow up on truncated spans');});diff --git a/test/hosts-instructions.test.ts b/test/hosts-instructions.test.tsindex 3ae4659b..fac9aee2 100644--- a/test/hosts-instructions.test.ts+++ b/test/hosts-instructions.test.ts@@ -8,6 +8,9 @@ test('canonical body names the three essentials', () => {assert.match(b, /graft ask "/);assert.match(b, /graft\/INDEX\.md/);assert.match(b, /graft build/);+ assert.match(b, /every occurrence|enumerate with grep/i, 'teaches the exhaustive-task grep rule');+ assert.match(b, /callers/, 'teaches the callers/callees/impact commands');+ assert.match(b, /truncated/i, 'tells the agent to follow up on truncated spans');assert.ok(!/\bhook|statusline\b/i.test(b), 'no host-specific machinery in the shared body');});