/gograph

name: gograph
version: "0.1.0"
description: "Go repository intelligence for Claude Code. Use when reading, navigating, editing, reviewing, or refactoring a Go codebase. Exposes 65 query, analysis, and workflow capabilities through the local gograph MCP server, including bounded first-call exploration, AST-aware call graphs, blast-radius analysis, impact, and security-flow candidates."
argument-hint: "gograph stats | gograph plan UserService.Login | gograph review --uncommitted"
allowed-tools: Bash, Read
homepage: https://gograph.identuum.ai
repository: https://github.com/ozgurcd/gograph
author: ozgurcd
license: MIT
user-invocable: true

gograph: Go Repository Intelligence

`gograph` is a local, AST-aware Go code intelligence engine that exposes 65 query, analysis, and workflow capabilities over the Model Context Protocol (69 endpoints including session lifecycle). It gives terminal LLMs (Claude Code, Cursor agents, OpenClaw) a structural view backed by a persisted or in-memory graph. `gograph_explore` offers compact, standard, and deep bounded discovery over one shared native result: compact preserves identity/role and complete counts, standard includes source/direct evidence and exact impact, and deep adds depth-3 exact evidence, package context, and explanation. `gograph_context` remains the focused known-symbol bundle. Actual savings depend on the task.

`gopls` provides live compiler-backed navigation, diagnostics, implementations, refactoring, and experimental MCP support. `gograph` complements it with a persisted repository graph, composed change-analysis workflows, and policy gates for coding agents.

When to invoke this skill

Activate whenever the user is working in a Go repository:

• Reading code, asking what a function does, or tracing a behavior across files.
• Planning, editing, refactoring, or deleting any Go symbol (function, method, struct, interface, package).
• Reviewing a Go diff or unstaged changes.
• Hunting a bug, auditing for security issues, or measuring complexity / coupling.

If a `.go` file is in the CWD or the user mentions a Go symbol, type, package, or interface by name, the skill applies.

Do NOT invoke for non-Go work. The skill is Go-scoped.

Prerequisite

For unrelated broken packages, use `gograph build . --precise --strict --exclude-dirs=legacy,examples/broken`. Pass the same `--exclude-dirs` to MCP startup and verify `analysis_build_context.exclude_dirs` in capabilities. Paths are literal root-relative subtrees; imported dependencies still must compile. Excluded code is outside the census. Workspace members use `exclude_dirs` in their manifest. See `docs/build-selection.md`. For symlinked skills in v1.7.2+, exclude their real parent, for example `--exclude-dirs=.claude/skills`. Precise production/test loading masks directory links beneath it without following targets. Linked Go inputs/metadata remain errors, and an existing Go overlay conflicts with masking. `doc` retains its independent strict preflight. Codex setup: `docs/codex-integration.md`.

The gograph binary must be installed and on `$PATH`:

go install github.com/ozgurcd/gograph/cmd/gograph@latest

Verify the active installation with `gograph doctor --json`; it reports the running binary, PATH resolution, shadowed copies, and—inside a repository—the current graph's freshness, analysis capabilities, and diagnostic without executing alternate binaries. The marketplace plugin supplies this workflow guidance; it does not install the binary or register an MCP server. Register `gograph mcp <project-path>` for each project using the client's MCP setup. Packaged and generated registrations keep refresh persistence off by default.

Mandatory workflow (enforced)

1. **At the start of any Go coding session**, run CLI `gograph doctor --json` to detect installation shadowing, then invoke `gograph_capabilities` to confirm what the connected server exposes. 2. **Confirm graph health** before symbol queries. MCP creates an in-memory AST graph when the artifact is missing, unreadable, unsafe, or has an unsupported source-policy marker, and refreshes source analysis per call. Invoke `gograph_stats` with no parameters and require `build_status=complete`; a build with zero successful parses never replaces the previous graph, while partial failures are reported explicitly. When durable precise enrichment is needed, run CLI `gograph build . --precise`; use `gograph build . --precise --strict` when CI must fail on fallback. If compilation prevents precision during exploratory work, use CLI `gograph build .` and explain the fallback. 3. **For unfamiliar structural questions, invoke `gograph_explore` first; for complete structural symbol / type / function discovery, use `gograph_query` instead of `grep`, `rg`, `find`, or glob.** Start with `compact=true` when identity and evidence counts are enough; use standard mode for direct evidence or `deep=true` for bounded depth-3 exact evidence, package context, and explanation. Compact/deep are mutually exclusive and default to 5/25 rows versus standard's 10; an explicit limit overrides the mode default. `gograph_explore` discloses lexical selection, ambiguity, totals, truncation, and omissions; follow with a focused tool when a complete section is needed. Text search also matches comments and string literals; `gograph_query` returns AST-derived matches. Continue to use text search for literal strings, documentation, ordinary non-sensitive configuration, and non-Go files. 4. **Before editing any Go symbol**, invoke `gograph_plan` with `symbol=<symbol>`. The plan returns callers, tests connected to the symbol, and a blast-radius estimate. Edit decisions should reference the plan. 5. **To understand a function or method**, invoke `gograph_context` with `symbol=<symbol>`. This single call combines node + source + callers + callees + statically mapped tests; inspect source or `gopls` when the evidenc