feat: graphify agent discovery for token savings on clone

.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(dart run *)"
+    ]
+  },
+  "defaultMode": "auto",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); case \"$CMD\" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *)   [ -f graphify-out/graph.json ] &&   echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"graphify: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files.\"}}'   || true ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}

.gitignore

@@ -8,4 +8,4 @@ dist-test/
 #graphify
 graphify-out/manifest.json    # mtime-based, breaks after git clone
 graphify-out/cost.json        # local only
-# graphify-out/cache/         # optional: commit for speed, skip to keep repo small
+graphify-out/cache/

.hooks/post-checkout

@@ -0,0 +1,69 @@
+#!/bin/sh
+# graphify-checkout-hook-start
+# Auto-rebuilds the knowledge graph (code only) when switching branches.
+# Installed by: graphify hook install
+
+PREV_HEAD=$1
+NEW_HEAD=$2
+BRANCH_SWITCH=$3
+
+# Only run on branch switches, not file checkouts
+if [ "$BRANCH_SWITCH" != "1" ]; then
+    exit 0
+fi
+
+# Only run if graphify-out/ exists (graph has been built before)
+if [ ! -d "graphify-out" ]; then
+    exit 0
+fi
+
+# Skip during rebase/merge/cherry-pick
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+[ -d "$GIT_DIR/rebase-merge" ] && exit 0
+[ -d "$GIT_DIR/rebase-apply" ] && exit 0
+[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
+[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0
+
+# Detect the correct Python interpreter (handles pipx, venv, system installs)
+GRAPHIFY_BIN=$(command -v graphify 2>/dev/null)
+if [ -n "$GRAPHIFY_BIN" ]; then
+    case "$GRAPHIFY_BIN" in
+        *.exe) _SHEBANG="" ;;
+        *)     _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | sed 's/^#![[:space:]]*//') ;;
+    esac
+    case "$_SHEBANG" in
+        */env\ *) GRAPHIFY_PYTHON="${_SHEBANG#*/env }" ;;
+        *)         GRAPHIFY_PYTHON="$_SHEBANG" ;;
+    esac
+    # Allowlist: only keep characters valid in a filesystem path to prevent
+    # injection if the shebang contains shell metacharacters
+    case "$GRAPHIFY_PYTHON" in
+        *[!a-zA-Z0-9/_.@-]*) GRAPHIFY_PYTHON="" ;;
+    esac
+    if [ -n "$GRAPHIFY_PYTHON" ] && ! "$GRAPHIFY_PYTHON" -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON=""
+    fi
+fi
+# Fall back: try python3, then python (Windows has no python3 shim)
+if [ -z "$GRAPHIFY_PYTHON" ]; then
+    if command -v python3 >/dev/null 2>&1 && python3 -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python3"
+    elif command -v python >/dev/null 2>&1 && python -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python"
+    else
+        exit 0
+    fi
+fi
+
+echo "[graphify] Branch switched - rebuilding knowledge graph (code files)..."
+$GRAPHIFY_PYTHON -c "
+from graphify.watch import _rebuild_code
+from pathlib import Path
+import sys
+try:
+    _rebuild_code(Path('.'))
+except Exception as exc:
+    print(f'[graphify] Rebuild failed: {exc}')
+    sys.exit(1)
+"
+# graphify-checkout-hook-end

.hooks/post-commit

@@ -0,0 +1,69 @@
+#!/bin/sh
+# graphify-hook-start
+# Auto-rebuilds the knowledge graph after each commit (code files only, no LLM needed).
+# Installed by: graphify hook install
+
+# Skip during rebase/merge/cherry-pick to avoid blocking --continue with unstaged changes
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+[ -d "$GIT_DIR/rebase-merge" ] && exit 0
+[ -d "$GIT_DIR/rebase-apply" ] && exit 0
+[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
+[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0
+
+CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null)
+if [ -z "$CHANGED" ]; then
+    exit 0
+fi
+
+# Detect the correct Python interpreter (handles pipx, venv, system installs)
+GRAPHIFY_BIN=$(command -v graphify 2>/dev/null)
+if [ -n "$GRAPHIFY_BIN" ]; then
+    case "$GRAPHIFY_BIN" in
+        *.exe) _SHEBANG="" ;;
+        *)     _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | sed 's/^#![[:space:]]*//') ;;
+    esac
+    case "$_SHEBANG" in
+        */env\ *) GRAPHIFY_PYTHON="${_SHEBANG#*/env }" ;;
+        *)         GRAPHIFY_PYTHON="$_SHEBANG" ;;
+    esac
+    # Allowlist: only keep characters valid in a filesystem path to prevent
+    # injection if the shebang contains shell metacharacters
+    case "$GRAPHIFY_PYTHON" in
+        *[!a-zA-Z0-9/_.@-]*) GRAPHIFY_PYTHON="" ;;
+    esac
+    if [ -n "$GRAPHIFY_PYTHON" ] && ! "$GRAPHIFY_PYTHON" -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON=""
+    fi
+fi
+# Fall back: try python3, then python (Windows has no python3 shim)
+if [ -z "$GRAPHIFY_PYTHON" ]; then
+    if command -v python3 >/dev/null 2>&1 && python3 -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python3"
+    elif command -v python >/dev/null 2>&1 && python -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python"
+    else
+        exit 0
+    fi
+fi
+
+export GRAPHIFY_CHANGED="$CHANGED"
+$GRAPHIFY_PYTHON -c "
+import os, sys
+from pathlib import Path
+
+changed_raw = os.environ.get('GRAPHIFY_CHANGED', '')
+changed = [Path(f.strip()) for f in changed_raw.strip().splitlines() if f.strip()]
+
+if not changed:
+    sys.exit(0)
+
+print(f'[graphify hook] {len(changed)} file(s) changed - rebuilding graph...')
+
+try:
+    from graphify.watch import _rebuild_code
+    _rebuild_code(Path('.'))
+except Exception as exc:
+    print(f'[graphify hook] Rebuild failed: {exc}')
+    sys.exit(1)
+"
+# graphify-hook-end

AGENTS.md

@@ -0,0 +1,23 @@
+## graphify — Knowledge Graph
+
+This project has a pre-built knowledge graph at `graphify-out/`. Use it to understand architecture before reading source files.
+
+### Before exploring the codebase
+
+Read `graphify-out/GRAPH_REPORT.md` for god nodes, community structure, and surprising connections. If `graphify-out/wiki/index.md` exists, navigate the wiki instead of reading raw source files — each article covers one architectural community with its nodes, edges, and relationships.
+
+### Instead of grep for architecture questions
+
+Use graph queries instead of scanning files:
+
+```bash
+graphify query "how does config connect to providers?"
+graphify path "ConfigModule" "ProviderRegistry"
+graphify explain "main()"
+```
+
+These traverse EXTRACTED + INFERRED edges in the knowledge graph rather than doing text search.
+
+### After modifying code
+
+Run `graphify --update` to keep the graph current. This is AST-only for code changes — no API cost.

CLAUDE.md

@@ -0,0 +1,3 @@
+## graphify
+
+See AGENTS.md for knowledge graph instructions.

docs/superpowers/specs/2026-05-03-graphify-agent-discovery-design.md

@@ -0,0 +1,54 @@
+# Graphify Agent Discovery Integration
+
+**Date:** 2026-05-03
+**Status:** Approved
+
+## Goal
+
+Make the graphify knowledge graph discoverable by any coding agent (Claude Code, Copilot CLI, Cursor) immediately on clone, so agents read the pre-built graph instead of scanning raw source files — saving tokens and improving architecture awareness.
+
+## Decisions
+
+- **Agent scope:** Claude Code + cross-agent via AGENTS.md (Copilot CLI, Cursor). No per-agent files (GEMINI.md, .cursorrules) for now.
+- **Hook scope:** Keep current search-only PreToolUse hook (grep/rg/find/fd/ack/ag). No interception of file reads.
+- **Commit strategy:** Commit all graphify outputs (graph.json, GRAPH_REPORT.md, graph.html, wiki/) so the graph is available on clone.
+- **Instruction consolidation:** AGENTS.md is the single source of truth for graphify instructions. CLAUDE.md references it instead of duplicating.
+
+## Changes
+
+### 1. Create `AGENTS.md`
+
+New root file read by all agents. Contains:
+- Instruction to read `graphify-out/GRAPH_REPORT.md` before exploring the codebase
+- Instruction to navigate `graphify-out/wiki/index.md` instead of reading raw source files
+- Available query commands: `graphify query`, `graphify path`, `graphify explain`
+- Instruction to run `graphify --update` after code changes
+
+### 2. Update `CLAUDE.md`
+
+Replace the `## graphify` section (written by `graphify claude install`) with a one-liner referencing AGENTS.md. The PreToolUse hook remains in `.claude/settings.json` — it's Claude Code infrastructure, not agent instructions.
+
+### 3. Generate wiki
+
+Run the graphify wiki pipeline to produce `graphify-out/wiki/` with `index.md` + one article per community. The CLAUDE.md rule "if wiki/index.md exists, navigate it instead of reading raw files" becomes active once this exists.
+
+### 4. Update `.gitignore`
+
+Uncomment `graphify-out/cache/` to actively ignore it. Keep ignoring `manifest.json` (mtime-based, breaks after clone) and `cost.json` (local tracking). Everything else in `graphify-out/` is committed.
+
+### 5. Commit all outputs
+
+Single commit containing:
+- `AGENTS.md` (new)
+- `CLAUDE.md` (updated)
+- `.claude/settings.json` (already exists, unchanged)
+- `.hooks/post-commit`, `.hooks/post-checkout` (already exist)
+- `graphify-out/graph.json`, `graphify-out/GRAPH_REPORT.md`, `graphify-out/graph.html`
+- `graphify-out/wiki/` (new)
+
+## What's NOT changing
+
+- PreToolUse hook in `.claude/settings.json` — already correct, search-only
+- Git hooks in `.hooks/` — already installed and working
+- No new source code in claudely itself
+- No GEMINI.md or .cursorrules files