expert-factory: Instructions file for Claude Code

this project

ef is an installable CLI in src/ef/. It imports graphify as a library — no shelling out to a graphify binary and no interpreter selection, because graphifyy[all] is a hard dependency so one install satisfies both import graphify and import mcp.

uv sync                       # dev install; `ef` lands in .venv/bin
.venv/bin/python -m pytest -q
ruff check src tests && ruff format src tests

Two invariants that are easy to break:

• src/ef/__init__.py sets GRAPHIFY_OUT=graph before any graphify import. graphify reads it once at import time and derives its skip-directory set from it, so setting it later would make graph/ graph itself.
• ef run owns stdout for JSON-RPC framing. Every graphify call in server.py is wrapped in contextlib.redirect_stdout(sys.stderr); a stray print corrupts the stream.

Tests drive real entry points and assert on emitted artifacts, never on private helper names or call ordering, and none of them spends an LLM token.

graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:

• For codebase questions, first run graphify query "<question>" when graphify-out/graph.json exists. Use graphify path "<A>" "<B>" for relationships and graphify explain "<concept>" for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
• If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
• Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
• After modifying code, run graphify update . to keep the graph current (AST-only, no API cost).

External repo graphs (direct, no global graph)

Graphs of other repos are read by pointing --graph at their graph.json directly. Nothing needs to be registered or merged first — a graph is just a file.