@neat.is/claude-skill 0.5.2 → 0.5.3

package/GRAPH_FIRST.md

@@ -0,0 +1,35 @@
+<!-- NEAT graph-first guidance. Paste this block into your agent's project
+     instructions — CLAUDE.md, AGENTS.md, .cursorrules, or the equivalent —
+     so the agent reaches for NEAT's graph before scanning files by hand.
+     Agent-agnostic: it is plain guidance, no Claude Code features required. -->
+
+## Reach for NEAT's graph before grepping
+
+This project has NEAT wired in. NEAT keeps a live semantic graph of the system —
+code, infrastructure, and runtime behaviour fused into one model — reachable over
+MCP (and a REST API). Every edge carries provenance: `EXTRACTED` from source,
+`OBSERVED` from OpenTelemetry, `INFERRED` where the trace stitcher bridges a gap,
+`STALE` when runtime goes quiet — so you know how much to trust each answer.
+
+When you need to understand this codebase, query the graph first. It is usually
+faster and more accurate than `grep`/`glob`/`find`, and it can tell you what the
+system *actually does at runtime*, not only what the source declares.
+
+Reach for these MCP tools before raw text search:
+
+- `semantic_search` — find code/nodes by a natural-language description.
+- `get_dependencies` — a node's transitive outgoing dependencies (declared, `EXTRACTED`).
+- `get_observed_dependencies` — only what a node calls *in production* (`OBSERVED` via OTel).
+- `get_divergences` — where the code (`EXTRACTED`) and production (`OBSERVED`) disagree.
+  The most NEAT-shaped query; reach for it on "is anything weird here?"
+- `get_root_cause` — trace a failing node up its dependency graph to the culprit.
+- `get_blast_radius` — everything downstream of a node: what breaks if it changes or fails.
+- `get_incident_history` — recent OTel error events recorded against a node.
+- `check_policies` — the project's `policy.json` violations, actual or hypothetical.
+
+Text search is still a fine fallback. If the graph does not have what you need —
+comments, string literals, config minutiae, a file NEAT does not model — go ahead
+and `grep`. The point is order: ask the graph first, then fall back to scanning.
+
+If the tools are not available, the NEAT daemon may not be running (`neatd status`)
+or the MCP server may not be wired in (`neat skill --apply`).

package/README.md

@@ -6,9 +6,13 @@ See [SKILL.md](./SKILL.md) for the tool list, install steps, and prerequisites.
 
 The shipped artifact is `claude_code_config.json` — a single object you merge into your `~/.claude.json` under `mcpServers.neat`. The `neat skill` CLI verb (in `@neat.is/core`) handles the merge for you.
 
+Alongside the MCP config, this package ships the affordances that make an agent reach for the graph before it grep-scans a repo: a Claude Code search-nudge `PreToolUse` hook (`hooks/neat-search-nudge.mjs`) and agent-agnostic graph-first guidance (`GRAPH_FIRST.md`). `neat hooks --apply` installs both. See [SKILL.md](./SKILL.md#reach-for-the-graph-first).
+
 ## Files
 
 - `claude_code_config.json` — the MCP server snippet
+- `hooks/neat-search-nudge.mjs` — the Claude Code search-nudge PreToolUse hook
+- `GRAPH_FIRST.md` — agent-agnostic graph-first guidance to paste into project instructions
 - `SKILL.md` — what the skill exposes and how to install
 - `package.json` — workspace metadata; this package ships no compiled code
 

package/SKILL.md

@@ -69,6 +69,42 @@ neat skill --apply
 
 This merges the `neat` server into `~/.claude.json` without touching other entries.
 
+## Reach for the graph first
+
+Wiring the tools in is half the job; the other half is getting your agent to
+*use* them instead of falling straight to text search. NEAT ships two nudges:
+
+```bash
+neat hooks --apply
+```
+
+That installs both:
+
+1. **A Claude Code search-nudge hook.** A `PreToolUse` hook (materialised to
+   `~/.neat/hooks/neat-search-nudge.mjs`, wired into `~/.claude/settings.json`)
+   that fires when the agent reaches for `Grep`, `Glob`, or a Bash
+   `grep`/`rg`/`find`. It injects a short note steering the agent to
+   `semantic_search` / `get_dependencies` / `get_divergences` first. It is a
+   **gentle, non-blocking nudge** — the search still runs; the agent just sees
+   the graph as the better first move. Your existing hooks are left in place,
+   and re-running is idempotent.
+
+2. **Agent-agnostic graph-first guidance** (`GRAPH_FIRST.md`, also written to
+   `~/.neat/neat-graph-first.md`). A markdown block you paste into your project
+   instructions — `CLAUDE.md`, `AGENTS.md`, `.cursorrules`, whatever your agent
+   reads — so the same "ask the graph before grepping" steer reaches agents on
+   any harness.
+
+The hook is Claude-Code-specific; agents on other harnesses (Codex, Gemini,
+Cursor, …) don't get the `PreToolUse` interception, but the guidance block
+gives them the same instruction. Preview either without installing:
+
+```bash
+neat hooks --print-hook       # the hook script
+neat hooks --print-guide      # the graph-first guidance
+neat hooks --print-settings   # the settings.json block --apply merges
+```
+
 ## Prerequisites
 
 - `neat init <repo>` has registered at least one project.

package/hooks/neat-search-nudge.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// NEAT search-nudge — a Claude Code PreToolUse hook.
+//
+// When the agent reaches for raw text search — the Grep or Glob tools, or a
+// Bash command that shells out to grep / rg / ag / ack / find / fd — this hook
+// injects a short note suggesting NEAT's graph tools first. NEAT already holds
+// this project's structure, dependencies, and runtime behaviour, so a graph
+// query is usually faster and more accurate than scanning files by hand.
+//
+// It is a NUDGE, not a gate. The hook only ever adds context; it never denies
+// the call and always exits 0, so the search runs regardless. Anything that is
+// not a text search is a silent no-op.
+//
+// Wired by `neat hooks --apply`, which copies this script under ~/.neat/hooks/
+// and adds a PreToolUse entry to ~/.claude/settings.json. The hook itself is
+// Claude-Code-specific; agents on other harnesses get the same steer from the
+// graph-first guidance NEAT ships instead (see `neat hooks --print-guide`).
+//
+// This file is a documentation copy. The source of truth is NEAT_SEARCH_HOOK
+// in @neat.is/core (packages/core/src/hooks-cli.ts); a contract test keeps the
+// two byte-aligned.
+
+import process from 'node:process'
+
+// grep-family and file-finder binaries. Matched at a word boundary so a path
+// like agent.ts does not trip it, and after a shell separator so the binary in
+// a pipe (... | grep foo) still counts.
+const SEARCH_BINARY = /(?:^|[\s|;&(){}])(?:grep|egrep|fgrep|rg|ripgrep|ag|ack|find|fd)(?=\s|$)/
+
+function bashLooksLikeSearch(command) {
+  return typeof command === 'string' && SEARCH_BINARY.test(command)
+}
+
+function nudge(toolName) {
+  return [
+    'NEAT is wired into this project — its live graph already knows this codebase',
+    'structure, dependencies, and runtime behaviour. Before leaning on ' + toolName + ', consider',
+    'asking the graph over MCP; it answers with structured, provenance-tagged results',
+    'rather than line matches:',
+    '',
+    '  - semantic_search — find code/nodes by a natural-language description',
+    '  - get_dependencies / get_observed_dependencies — what a thing calls, as declared',
+    '    in code (EXTRACTED) vs. what it actually calls in production (OBSERVED)',
+    '  - get_divergences — where the code and production disagree',
+    '  - get_root_cause / get_blast_radius — trace a failure, or a change reach',
+    '',
+    'Text search is still a fine fallback — go ahead and run it if the graph does not',
+    'have what you need.',
+  ].join('\n')
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', (chunk) => {
+      data += chunk
+    })
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', () => resolve(data))
+  })
+}
+
+const raw = await readStdin()
+
+let payload
+try {
+  payload = JSON.parse(raw)
+} catch {
+  // No parseable payload — nothing to nudge about. Let the call proceed.
+  process.exit(0)
+}
+
+const toolName = typeof payload?.tool_name === 'string' ? payload.tool_name : ''
+const toolInput = payload?.tool_input ?? {}
+
+let isSearch = false
+if (toolName === 'Grep' || toolName === 'Glob') isSearch = true
+else if (toolName === 'Bash') isSearch = bashLooksLikeSearch(toolInput.command)
+
+if (!isSearch) process.exit(0)
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      additionalContext: nudge(toolName),
+    },
+  }),
+)
+process.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neat.is/claude-skill",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Claude Code skill drop-in for NEAT — wires the @neat.is/mcp server into Claude's MCP config",
   "license": "BUSL-1.1",
   "homepage": "https://neat.is",
@@ -18,7 +18,9 @@
   "files": [
     "README.md",
     "SKILL.md",
-    "claude_code_config.json"
+    "GRAPH_FIRST.md",
+    "claude_code_config.json",
+    "hooks/neat-search-nudge.mjs"
   ],
   "scripts": {
     "test": "vitest run --passWithNoTests",