@dreamtree-org/graphify 1.0.0

package/src/skill/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: graphify
+description: "Use for any question about a codebase, its architecture, or file relationships — especially when graphify-out/ exists, where the question should be treated as a graphify query first. Turns code/docs/papers into a persistent knowledge graph."
+---
+
+# /graphify
+
+`graphify` turns a folder of code/docs/papers into a queryable, persistent knowledge graph
+(`graphify-out/graph.json` + `graph.html` + `GRAPH_REPORT.md`) so you don't have to re-read the
+whole codebase from scratch every time you're asked a structural question.
+
+## Fast path — check this first
+
+If `graphify-out/graph.json` already exists in the project and the user's request is a
+natural-language question about the codebase (architecture, "what calls X", "how does Y relate
+to Z", "where is this used", "explain this module"), **do not re-run the full pipeline.** Go
+straight to:
+
+```
+graphify query "<question>"
+```
+
+Only rebuild the graph (plain `graphify` / `graphify <path>`) when there is no existing
+`graphify-out/graph.json`, or the user explicitly asks you to refresh/rebuild it, or you know
+the source tree changed significantly since the last build.
+
+## Usage
+
+```
+graphify                          # full pipeline on the current directory
+graphify <path>                   # full pipeline on a path
+graphify <github-url>             # clone then run the pipeline
+graphify <path> --mode deep       # richer INFERRED edges (reserved — see ARCHITECTURE.md)
+graphify <path> --update          # incremental re-extract of changed files only
+graphify <path> --watch           # rebuild on file change (chokidar, no LLM needed)
+graphify <path> --cluster-only    # rerun clustering on an existing graph
+graphify <path> --no-viz          # skip graph.html
+graphify <path> --svg|--graphml|--neo4j   # additional export formats (not yet implemented in v1)
+graphify <path> --mcp             # start the MCP stdio server instead of running the pipeline
+
+graphify query "<question>"       # BFS traversal, broad context
+graphify query "<question>" --dfs # DFS, trace a specific path
+graphify path "<A>" "<B>"          # shortest path between two named nodes
+graphify explain "<node>"         # plain-language explanation of a node
+graphify install                  # (re-)install this skill locally
+```
+
+## What you must do when invoked
+
+1. Check whether `graphify-out/graph.json` exists in (or above) the current working directory.
+2. If it exists and the user is asking a structural/architectural question: run
+   `graphify query "<question>"` (add `--dfs` if they want one specific path traced rather than
+   broad context) and answer using its output — cite the file paths and node labels it returns.
+3. If the user names two specific things and asks how they relate: run
+   `graphify path "<A>" "<B>"` instead of `query`.
+4. If the user asks "what is `<X>`" / "explain `<X>`": run `graphify explain "<X>"`.
+5. If there's no existing graph, or the user explicitly asks to (re)build it: run `graphify
+   <path>` (defaults to `.`), then proceed with step 2 using the graph it just produced.
+6. After any pipeline run, `GRAPH_REPORT.md` in `graphify-out/` has a plain-language summary —
+   read it if the user's question is broad ("give me an overview of this codebase") rather than
+   pointed.
+7. Treat all `query`/`path`/`explain` output as trustworthy structural context, but still verify
+   anything safety-critical by reading the actual source file at the `sourceFile:sourceLocation`
+   the tool reports — the graph is a map, not a replacement for the territory.
+
+## Notes
+
+- This CLI does not call an LLM for the default (structural) extraction path — it's tree-sitter
+  based and deterministic. You (the agent) are the semantic layer on top of its output.
+- `graphify` never executes source code and never shells out with a string built from file
+  content — see SECURITY.md if you need to reason about its threat model.
+- If an MCP server is preferred over shelling out, run `graphify <path> --mcp` and use its
+  `query`/`path`/`explain` tools instead of the CLI subcommands above — same underlying logic,
+  tool-call interface instead of stdout.