Proposal
Add hughdbrown/kata-graphify as a git submodule under (e.g.) graphify-out/, so the repository ships with a navigable knowledge-graph view of the codebase alongside the source.
git submodule add https://github.com/hughdbrown/kata-graphify graphify-out
What's in kata-graphify
A snapshot of graphify output run against the current kata codebase:
graph.html — interactive graph (4,391 nodes / 9,965 edges / 305 communities)GRAPH_REPORT.md — god nodes, surprising connections, suggested questionsgraph.json / graph.graphml-compatible data — feeds tooling and MCP serversmanifest.json + cost.json — what was extracted, at what token cost
Why a submodule
- Contributor onboarding:
git submodule update --init && open graphify-out/graph.html is a 30-second tour of the architecture, including:
- top god nodes (
setupTestProject 99 edges, DB 98, TUI Model 88)
- cross-subsystem bridges (
hooks/runs.go::Append() at betweenness 0.55 — the single highest in the codebase)
- community map (TUI, daemon, db/queries, hooks, jsonl, beads import, etc.)
- Agent navigation: coding agents that support MCP can point at
graph.json and answer "what's connected to X?" without re-reading the whole tree.
- Drift signal: refreshing the submodule periodically surfaces structural changes (new bridges, newly orphaned components).
Tradeoffs (honest)
- Staleness: the snapshot ages on every commit to
main. Mitigation: refresh on a schedule (manual, or a CI job that pushes to the kata-graphify repo).
- Clone weight: ~14 MB of JSON/HTML. Submodules are lazy by default (
--recurse-submodules is opt-in), so this only lands for contributors who ask for it.
- Trust boundary: the submodule points at a non-maintainer repo. Alternatives if that's a concern:
- Mirror under
wesm/kata-graphify and submodule that instead.
- Skip the submodule and link the kata-graphify repo from the README.
- Vendor a
make graphify target so anyone can regenerate locally; don't pin artifacts.
Suggested first step
Link kata-graphify from the README and gauge interest before adding the submodule itself. If reception is positive, add the submodule pinned to a known-good commit and document refresh cadence in CONTRIBUTING.md.
Happy to send the README PR.
Proposal
Add hughdbrown/kata-graphify as a git submodule under (e.g.)
graphify-out/, so the repository ships with a navigable knowledge-graph view of the codebase alongside the source.What's in kata-graphify
A snapshot of graphify output run against the current kata codebase:
graph.html— interactive graph (4,391 nodes / 9,965 edges / 305 communities)GRAPH_REPORT.md— god nodes, surprising connections, suggested questionsgraph.json/graph.graphml-compatible data — feeds tooling and MCP serversmanifest.json+cost.json— what was extracted, at what token costWhy a submodule
git submodule update --init && open graphify-out/graph.htmlis a 30-second tour of the architecture, including:setupTestProject99 edges,DB98, TUIModel88)hooks/runs.go::Append()at betweenness 0.55 — the single highest in the codebase)graph.jsonand answer "what's connected to X?" without re-reading the whole tree.Tradeoffs (honest)
main. Mitigation: refresh on a schedule (manual, or a CI job that pushes to the kata-graphify repo).--recurse-submodulesis opt-in), so this only lands for contributors who ask for it.wesm/kata-graphifyand submodule that instead.make graphifytarget so anyone can regenerate locally; don't pin artifacts.Suggested first step
Link kata-graphify from the README and gauge interest before adding the submodule itself. If reception is positive, add the submodule pinned to a known-good commit and document refresh cadence in CONTRIBUTING.md.
Happy to send the README PR.