graphify-setup

name	graphify-setup
description	Graphify — autonomous setup: graphify.json, Stop hook, CLAUDE.md.

Skip Conditions

Do not run this setup if any of the following are true:

• The project contains no JavaScript, TypeScript, or Python source files (check: find . -name "*.js" -o -name "*.ts" -o -name "*.py" | grep -v node_modules | head -1)
• A valid graphify.json already exists and the project structure hasn't changed
• The user explicitly says graphify is not relevant to their stack (pure mobile, database-only, embedded, etc.)

If the project type is ambiguous, ask once: "Does your project use JavaScript, TypeScript, or Python as its primary language?" before running Step 1.

---

Purpose

Set up Graphify for the project autonomously. Claude handles everything — dependency installation, project structure inference, configuration — and only asks the user when it cannot proceed without their input (permission errors, genuinely ambiguous structure).

---

Step 1 — OS Detection

Run:

uname -s

Output	OS
Darwin	macOS — follow macOS instructions
Linux	Linux or WSL — follow Linux instructions
MINGW* / MSYS* / other	Windows — see below

Windows handling:

First, check if WSL is available and active:

wsl --status 2>/dev/null || echo "WSL_NOT_FOUND"

• WSL active → run all subsequent steps inside the WSL shell (wsl bash -c "<command>"). Follow Linux instructions for all installs.

• WSL not found or not configured → stop and inform the user:

  Windows without WSL is not supported. Please activate WSL first: 👉 https://learn.microsoft.com/en-us/windows/wsl/install

  Once WSL is set up, re-run this setup and everything will work via Linux instructions.

Do not continue on Windows until WSL is confirmed active.

---

Step 2 — Check and Install graphify + jq

command -v graphify && graphify --version || echo "NOT_FOUND"
command -v jq && jq --version || echo "NOT_FOUND"

If either is missing, run /devteam:install graphify jq and wait for it to finish — that command owns the cross-OS install/verify logic for both (skills/devops/tool-installers/SKILL.md). Do not install them directly here; this avoids duplicating install commands in two places. Do not continue past this step until both are confirmed working.

---

Step 4 — Infer Project Structure

Do not ask the user. Explore the project autonomously to determine targetPaths and manifestPaths.

4a — Detect stack via manifest files

Check which of these exist at the project root:

File	Stack
package.json	Node.js / JavaScript / TypeScript
composer.json	PHP
requirements.txt / pyproject.toml / setup.py	Python
go.mod	Go
Cargo.toml	Rust
Gemfile	Ruby
pom.xml / build.gradle	Java / Kotlin

4b — List top-level directories

find . -maxdepth 2 -type d ! -path './.git*' ! -path './node_modules*' \
  ! -path './vendor*' ! -path './dist*' ! -path './build*' \
  ! -path './.graphify*' ! -path './.claude*' ! -path './coverage*' \
  ! -path './__pycache__*' ! -path './target*' | sort

4c — Select targetPaths using these heuristics

Stack	Likely targetPaths (keep only those that exist)
Node.js	src, lib, app, routes, components, pages, services, api
PHP (Laravel)	app, routes, config, database/migrations, tests
PHP (other)	src, lib, app
Python	src, app, any directory containing __init__.py
Go	cmd, internal, pkg, api
Rust	src
Ruby	app, lib, config
Java/Kotlin	src/main, src/test
Unknown	any directory with source-like names; skip build/output dirs

Filter to only include paths that actually exist. If after applying heuristics you still cannot determine targetPaths with reasonable confidence (e.g., flat or unconventional layout), ask the user once listing your best guesses for confirmation.

4d — Select manifestPaths

Include all manifest files found in Step 4a that exist at the root. Also include lock files if present (package-lock.json, yarn.lock, pnpm-lock.yaml, composer.lock, Gemfile.lock, poetry.lock).

---

Step 5 — Generate .dev-team-agents/user-data/graphify.json

Create the config file at .dev-team-agents/user-data/graphify.json — this is where graphify-refresh.sh reads it from:

{
  "targetPaths": ["<inferred-dir1>", "<inferred-dir2>"],
  "manifestPaths": ["<inferred-manifest1>"]
}

Omit manifestPaths if no manifest files were found. Do not ask the user to confirm — proceed directly to Step 6.

---

Step 6 — Graphify Hook Sub-scripts

The 02-graphify-hint.sh (PreToolUse) sub-script is built-in to the dev-team-agents tarball. No manual creation is needed.

Graph rebuilds are on-demand, not automatic — the Stop hook that used to rebuild on every session (99-graphify-refresh.sh) is disabled (see CLAUDE-md/hooks.md § Disabled Hooks). Refresh the graph manually when needed:

bash .dev-team-agents/scripts/graphify-refresh.sh

Remove any legacy file if present:

rm -f .dev-team-agents/scripts/hooks/stop/02-graphify-refresh.sh

The Stop dispatcher and PreToolUse dispatcher pick these up automatically — no changes to settings.json are needed.

---

Step 7 — Update .gitignore

Add the following entries to the project's .gitignore. Group them under a # Dev Team Agents comment so they are easy to identify:

GITIGNORE_ENTRIES=(
  "# Dev Team Agents"
  "graphify-out/cache"
  ".worktrees"
)

for ENTRY in "${GITIGNORE_ENTRIES[@]}"; do
  grep -qxF "$ENTRY" .gitignore 2>/dev/null || echo "$ENTRY" >> .gitignore
done

• graphify-out/cache — Graphify internal cache, rebuilt automatically
• .worktrees — worktree isolation directories, local only

The build-run marker (graphify_last_run) lives in the consolidated .dev-team-agents/user-data/state.json (read/written via scripts/lib/state.sh's state_get graphify_last_run / state_set graphify_last_run <value>), which the installer already gitignores entirely — no separate entry is needed.

---

Step 8 — Run First Build

bash .dev-team-agents/scripts/graphify-refresh.sh

If the build succeeds, graphify-out/ will be created at the project root.

If it fails, diagnose the error:

Symptom	Fix
graphify not found	Complete Step 2
jq not found	Complete Step 2
graphify.json not found	Complete Step 5 — file must be at .dev-team-agents/user-data/graphify.json
Source dir not found	Verify path with user and update .dev-team-agents/user-data/graphify.json

---

Step 9 — Inject CLAUDE.md Section

Check if the project CLAUDE.md already contains a ## Context Navigation (Graphify) section. If not, append (never replace) the following:

## Context Navigation (Graphify)

**3-Layer Query Rule:**
1. Query `graphify-out/graph.json` or `GRAPH_REPORT.md` for structure and relationships
2. Check `docs/` for decisions and context
3. Read raw source files only when editing or when layers 1–2 lack the answer

**Rebuild:** always use `.dev-team-agents/scripts/graphify-refresh.sh` — never `graphify update .` directly.
Rebuild runs automatically after each Claude session via the Stop hook.
Manual rebuild needed after: new modules/services, structural reorganization, or domain flow changes.

---

Step 10 — Confirm Setup

Report to the user:

✅ Graphify is set up for this project.

  Knowledge graph : graphify-out/  (versioned)
  Last-run marker : graphify_last_run key in .dev-team-agents/user-data/state.json  (gitignored)
  Config          : .dev-team-agents/user-data/graphify.json
  Auto-rebuild    : Stop hook → .dev-team-agents/scripts/graphify-refresh.sh

Rebuilds happen automatically after each Claude session when new files are
added, deleted, or moved inside the tracked directories.