feat!: rewrite plugin around the /mcp/v1/projects code-graph surface

[Edwinbhart]

Rewrite plugin around project code-graph surface

🆕 New Feature · ♻️ Refactor · 📝 Docs

This PR transitions the plugin from a global system-wide knowledge graph to a per-project code-graph model. It introduces a new set of MCP tools and a project-selection workflow designed for deep code exploration across indexed repositories.

Complexity

🟠 High · 9 files changed, 124 insertions(+), 153 deletions(-)

This PR is a foundational overhaul of the plugin's interaction model. It replaces the entire global knowledge-graph toolset with a project-centric code-graph surface, requiring coordinated changes across the manifest, hook logic, agent behavior, and documentation. While the individual bash scripts are straightforward, the architectural shift significantly changes how Claude interacts with OpenTrace.

Review focus

Pay particular attention to the following areas:

• MCP Endpoint — verify the updated URL in mcp-servers/opentrace.json correctly points to the new projects-based surface.
• Hook Parameter Mapping — ensure the PreToolUse bash script correctly extracts the new max_depth and rel_type parameters from the traverse_project tool input.
• Instruction Clarity — check that the SessionStart and explore agent instructions provide sufficient guidance for the "list -> select -> investigate" workflow.

[opentrace]

✅ Approved

This is a solid pivot to the project-level code graph surface. The consolidation of tools and the addition of the dedicated explore agent make the plugin's purpose much clearer and more actionable for the model. The instructions in agents/explore.md are particularly well-crafted, especially the guidance on project ID persistence and handling lazy bundle loads.

See the inline comments for a few minor suggestions regarding the resilience of the hook scripts.

Minor observations

1. Lazy Loading Context: hooks/session-start/script.sh
   You might consider adding the "first query may be slow/timeout" warning to the additionalContext in the SessionStart hook as well. While it's in the agent file and README, having it in the session context ensures even the default agent is aware of it immediately.

2. Project Selection Logic: agents/explore.md
   The instruction to "match the current directory's git repo name" is clever. If you have the ability to expose the current working directory or git root to the MCP server in the future, that could automate this further.

3. Cspell updates: cspell.json
   Clean removal of the old camelCase terms. Since you've introduced project_id and traverse_project, it's worth a quick check to see if those trigger any local linting, though they are standard enough that they likely won't.