Graph Code

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence. [BLOCKING] Mode routing — detect FIRST. The mode is --mode=build|query|trace|blast-radius|connect-api|export, or the first argument when it is exactly one of those six words ($graph-code export --format=mermaid <file>). Everything after the mode is that mode's own arguments (--scope=, --direction, --node-mode, --format=, --json, a target). Read the mode file in full before anything else (see Mode Dispatch). Each of the six modes works called directly with no workflow.

Quick Summary

Goal: [Code Intelligence] Operate the structural code knowledge graph (Tree-sitter nodes and edges in .code-graph/graph.db, SQLite) through the python .claude/scripts/code_graph CLI: build or sync it, query relationships, trace system flow, analyze the blast radius of a change, match frontend calls to backend routes, and export JSON snapshots or single-file Mermaid diagrams.

Workflow: Detect the mode → read its references/mode-<x>.md in full → run the CLI live → report the JSON result with file:line evidence.

Key Rules:

• One mode per invocation. No mode and no mode word: show the Mode Dispatch table and ask which mode via ask user question tool; a natural-language request that matches exactly one row of the Intent column selects that row's mode (the Intent column holds action phrases only: a prompt that merely names "code graph", "knowledge graph" or "uncommitted changes" carries no action and gets the table); anything else gets the table, never a guess.
• Always pass --json to the CLI so the output is structured and parseable.
• Graph not built (.code-graph/graph.db absent): report plainly — "graph not built — run $graph-code --mode=build, or continue with grep" — and stop that mode. It is never an error for a caller.
• MUST ATTENTION keep claims evidence-based (file:line) with confidence >80% to act; MUST ATTENTION keep task tracking updated as each step starts/completes.

Optional: graph as a hint

Optional: when grep and reading files alone may not reveal a high-risk blast radius (shared contract, many callers, cross-module or cross-service flow, public API), the code graph (.code-graph/graph.db) can add callers, dependents and impacted tests. Treat it as a hint, NOT proof: the graph can be stale or incomplete (it lags uncommitted edits and unindexed paths) — verify anything that matters by reading the files/grep. Skip it for low-risk or local changes.

Nothing in this skill is mandatory for other skills or workflows. Pattern when used: grep/read finds a key entry-point file (entity, command, query, event or command handler, controller, bus message or consumer, component, store, api-service) → an optional trace <file> --direction both --json suggests callers, consumers, bus messages, event chains and tests → grep/read verifies the details.

Mode Dispatch

Detect the mode from the invocation arguments before any other work; do not load a mode file the invocation did not select.

• [BLOCKING] When --mode=build, read references/mode-build.md in full FIRST; it owns the tooling-install Step 0, the --scope=full|update|sync branches (default: auto-detect) and the Python/CLI preconditions.
• [BLOCKING] When --mode=query, read references/mode-query.md in full FIRST; it owns intent mapping, the status handling (ok/ambiguous/not_found/error) and the result formats.
• [BLOCKING] When --mode=trace, read references/mode-trace.md in full FIRST; it owns direction choice, the bug/failure upstream-first rule and the CLI flags.
• [BLOCKING] When --mode=blast-radius, read references/mode-blast-radius.md in full FIRST; it owns the live CLI run, the risk bands and the recommendations.
• [BLOCKING] When --mode=connect-api, read references/mode-connect-api.md in full FIRST; it owns the matching strategies, zero-config detection and the optional graphConnectors.apiEndpoints config.
• [BLOCKING] When --mode=export, read references/mode-export.md in full FIRST; it owns --format=json|mermaid (default JSON), file selection, required Mermaid target, output paths and result reporting.
• The six modes share one CLI and one database, never one body: a mode never loads another mode's file. Cross-mode hints are plain pointers ($graph-code --mode=build builds the graph).
• The CLI verbs blast-radius, connect-api, connect-implicit, export, export-mermaid, review-context and describe are not skills; $graph-code --mode=export owns JSON and Mermaid exports. The hooks graph-session-init, graph-prompt-sync and graph-auto-update keep the graph current without this skill.

<!-- PROTOCOL-GUIDES:START -->

Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.

• end-to-start-debugger-trace — Walk backward from the observed end state through every feeder path before fixing; investigating non-trivial bugs or failed verification, changing code behavior, or tracing unclear code flow → .claude/skills/shared/protocols/end-to-start-debugger-trace.md

<!-- PROTOCOL-GUIDES:END -->

<!-- SYNC:end-to-start-debugger-trace:reminder -->

IMPORTANT MUST ATTENTION for non-trivial bugs, failed verification, regression fixes, behavior-changing code or unclear code flow, trace backward from the observed output through every feeder path before fixing. Establish hypotheses, the authoritative invariant owner and forward proof; retain validation at untrusted boundaries. Ordinary artifact review or graph lookup alone does not trigger a debugging workflow.

<!-- /SYNC:end-to-start-debugger-trace:reminder -->

Closing Reminders

IMPORTANT MUST ATTENTION Goal: Operate the code knowledge graph through exactly one mode per invocation, read that mode's reference in full first, and treat every graph answer as a stale-able hint to verify by reading.

Protocols in force (concise digest of the SYNC/shared blocks this skill carries):

• End-To-Start Debugger Trace: for bug/failure or unclear-code investigation, trace backward from the observed output and establish hypotheses before fixing. Build, query and export alone do not trigger debugging.

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using todo tracking BEFORE starting

• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)

• MANDATORY IMPORTANT MUST ATTENTION --mode=<x> reads references/mode-<x>.md in full FIRST; no mode and no matching intent shows the mode table, never a guess

• MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using todo tracking.