crew-graph

Files (4)

• SKILL.md
• reconcile.md
• crew_upgrade.py · scripts/
• graph_reconcile.py · scripts/

SKILL.md (first lines)

# Crew Graph

Wraps `graphify`, an external CLI that builds a static code graph and answers
questions against it. This skill detects it, builds keyless, and queries it
instead of loading the raw graph into context.

**The filesystem is the home of the graph, and its only home.**
`graphify-out/graph.json` is one file, greppable, refreshed by a post-commit
hook, and queried without loading it. Everything this skill does stays inside
the repo. It writes nothing to a vault, a notes app, or anywhere else — see
**Why there is no Obsidian export** below, which is a closed question, not a
default someone can turn back on.

## Detect — never auto-install

```
command -v graphify
```

Absent means report it and stop; do not install anything without asking.
Offer:

```
uv tool install graphifyy
```

The package on PyPI is `graphifyy` — double-y — while the CLI it installs is
`graphify`. Every other `graphify*` name on PyPI is unaffiliated. Installing
the wrong one fails silently: `pip`/`uv` succeeds, and the command you get is
not this tool. Say the package name out loud when offering the install; don't
just say "install graphify."

The same install adds a second executable, `graphify-mcp` — see MCP server
below. Confirm with `graphify --version`.

## Build

Check the secrets denylist first, every time:

```
python3 ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/crew_graph_ignore.py --root . --check
```

Exit 0 means graphify will read no secrets-denylisted file. On exit 1, stop:
name the paths it printed and offer `--write`, which adds the missing
patterns to `.graphifyignore`. On exit 2, stop and report its reason. Never
build around either, and never build first and check after — a graph built
over a secret already holds it (**Tainted graph** below). Then:

```
graphify . --no-viz --code-only
```

On native Windows, run it as
`python3 "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/crew_shell.py" run -- "graphify . --no-viz --code-only"`
and quote the `crew-shell:` route line (see `crew-setup/platform.md`). On Git
Bash without `python3`, use `python` or `py -3` with the same arguments.

This is the default, always. Both flags matter and neither is optional:

- **`--code-only`** skips docs, papers, and images. Without it, graphify
  errors on any repo that has documentation at all — which is nearly every
  real repo, this one included — with `no LLM API key found (N doc/paper/
  image file(s) need semantic extraction)`. Code-only needs no API key.
  `--code-only` dropped from a command in this skill is a bug, not a
  simplification.
- **`--no-viz`** skips the HTML visualization. It's unopenable past roughly
  5000 nodes, and an agent reads `graph.json` through the CLI, not the HTML,
  so building it is wasted work.

Output lands in `graphify-out/`: `graph.json`, `manifest.json`, `cache/`.
Measured on this repo (106 code files): 1478 nodes, 3170 edges, 1.8 MB.

**Docs, PDFs, and images are opt-in.** Extracting them needs an LLM call, so
before offering to run graphify without `--code-only`, tell the user which
API key env var graphify needs and confirm it's set — don't let them discover
the key requirement from an error after the fact.

## Refresh

Prefer `/crew:graph --refresh` over a raw graphify line. It runs the
denylist check above, then the repo's sanctioned command (`graphify update .`
where `GRAPH_REPORT.md` is tracked beside the graph, which keeps the pair
consistent; the **Build** line where it is not), then proves the report's
`## Summary` counts equal `graph.json`'s `nodes` and `links`. It never
commits: whoever ran it commits the pair. `/crew:graph --status` says in one
line whether the graph is current. **Build** above stays the first build.

## Secrets denylist

graphify reads every file its ignore rules do not exclude, and puts the
symbols it finds into `graph.json`. `crew_graph_ignore.py` builds the repo's
denylist from three sources, in this order:

- **built-in**: `.env`, `.env.*` (but not `.env.example`), `*.pem`, `*.key`,
  `*.p12`, `*.pfx`, `id_rsa*`, `id_ed25519*`;
- **`.claude/secrets-denylist`**: optional, tracked, gitignore syntax. This
  is where repo-specific paths go (`config/`, `/init.php`). A repo's own
  secrets guard can read the same file;
- **`Read(...)` deny rules** in `.claude/settings.json` and
  `.claude/settings.local.json`, translated to root-anchored patterns. A rule
  outside the repo (`~/…`, `//…`) is skipped by name, and a deny-all `Read`
  is `unknown`.

**`.gitignore` never protects a tracked file from graphify.** graphify 0.9.65
(`detect.py`, `_is_scan_ignored`) skips `.gitignore` rules for any path in
`git ls-files --cached`. Only `.graphifyignore` and `--exclude` can exclude
a tracked file. So the check is on the root `.graphifyignore` only. A nested
`.graphifyignore` could re-include a path with `!`, so its presence makes
the answer `unknown`, never covered. The matching is git's own
(`check-ignore --no-index`). Where git and graphify parse an edge pattern
differently, that disagreement is an accepted risk, and the real-graphify
fixture test (`test_graph_ignore_graphify.py`) covers the directory,
anchored, extension and nested forms.

The same check runs in `crew_refresh_check.py`, which will not name a graph
refresh while it fails, and on `/crew:status`'s `graph-ignore` line.

## Tainted graph

From mbadali25/useful-claude-add-ons, GPL-2.0.

More from mbadali25/useful-claude-add-ons