octopus-workflow/core/rules/code-graph.md

Code Graph First (mandatory)

Before any cross-file understanding or change, query the code graph first. Do NOT grep + read whole files to reconstruct relationships.

• Session start: run codegraph_status to confirm the graph is built; if empty, run codegraph init -i from the project root once. The graph persists and is reused for the whole session.
• Trust but verify stats: codegraph_status can return a stale or partial snapshot. If counts look low, run codegraph_status again — codegraph auto-syncs on file changes (2s debounce via native OS file watcher). Do not run structural queries against a graph you suspect is incomplete.
• Structural questions ("who calls / what depends on / where defined / what breaks if I change this") MUST use codegraph_explore (primary, for flows and surveys), codegraph_search (locate symbols), codegraph_callers (every call site). Do not piece relationships together from grep + read output.
• Reading an implementation: use read(filePath, symbol: "<name>") to fetch only the target symbol's line range. Do not read an entire large file to see one function.
• grep is the fallback, not the default: use grep only for fuzzy text the graph cannot answer (comments, string literals, config text). Use codegraph_node with symbolsOnly: true for a cheap structural overview instead of Glob.
• Delegate exploration: prefer running graph + read inside an Explorer subagent and returning only file:line results and conclusions, to keep the main context lean.

Per-worktree indexes (mandatory for worktree sessions)

The main checkout's .codegraph/ indexes ONLY that tree. A git worktree lives outside the repo path, so nearest-.codegraph/ resolution finds nothing under it — graph queries in a workflow worktree silently degrade to grep+read (the [org-internal #2561] / TD-006 gap).

• script/session-worktree.sh create and script/scratch-worktree.sh create build a per-worktree index automatically: codegraph init -i <path> runs in the background (best-effort — missing CLI, existing index, or init failure never blocks worktree creation). Set CODEGRAPH_SKIP=1 to disable (selftests / CI).
• Worktrees created BEFORE this hook landed have no index: run codegraph init -i once from inside them.
• First query after creating a worktree may hit a still-building index; if results look empty, check codegraph status inside the worktree, then retry.
• Kickoff readiness (checkCodegraph) checks <root>/.codegraph/codegraph.db per root, and codegraph serve --mcp resolves from the session's cwd — both pick the worktree's own index once it exists.