Improve graph tool routing guidance

[mohanagy]

Summary

• route installed graphify guidance by question type across Claude, Gemini, Cursor, and hook surfaces
• add regression tests for the install guidance so focused MCP tools stay documented
• cap Vitest workers at 4 to keep the full suite stable on shared machines

Testing

• npm run typecheck
• npm run test:run
• npm run build
• npm pack --dry-run

Summary by CodeRabbit

• New Features

  • Updated installation guidance and on-screen reminders to route tool recommendations by question type, clarifying which focused tools to try first and when raw-file fallback is appropriate.

• Tests

  • Improved test coverage for installation templates and generated docs.
  • Added validation to stabilize test runs by capping test worker parallelism.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c1cde11d-fbfa-44ae-899f-6288573130cc

📥 Commits

Reviewing files that changed from the base of the PR and between 2b8ee76 and 845375c.

📒 Files selected for processing (1)

• tests/unit/install.test.ts

✅ Files skipped from review due to trivial changes (1)

• tests/unit/install.test.ts

---

📝 Walkthrough

Walkthrough

Installation guidance now routes tool usage by question type (choose among retrieve, relevant_files, feature_map, risk_map, implementation_checklist, impact) instead of enforcing a single retrieve-first rule; templates, pre-tool messages, and tests updated accordingly.

Changes

Cohort / File(s)	Summary
MCP Routing Guidance src/infrastructure/install.ts	Introduce MCP_ROUTING_GUIDANCE and inject into pre-tool system message; replace rigid "retrieve first" wording; constrain raw-file fallback to graph-tool failures or MCP unavailability; update bash pre-command echo and related rule text.
Markdown Templates templates/.../CLAUDE.md, templates/.../GEMINI.md, templates/.../AGENTS.md	Rewrite/format "IMPORTANT" rules blocks to reflect new routing order and strengthened prohibition on using Glob/Grep/Bash/Read/Agent/Explore subagents first.
Installation Template Tests tests/unit/install-templates.test.ts	Add Vitest case decoding .claude/settings.json PreToolUse payload and assert presence of question-type routing tokens (relevant_files, feature_map, risk_map, implementation_checklist, impact) plus existing checks.
Install Function Tests tests/unit/install.test.ts	Extend geminiInstall and claudeInstall tests to assert generated GEMINI.md / CLAUDE.md include the new routing tool labels.
Test Config & Helpers vitest.config.ts, tests/unit/package-metadata.test.ts	Set maxWorkers: 4 to cap Vitest parallelism; add helper and test to verify config presence.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Dev as Developer/Agent
  participant Installer as install.ts
  participant MCP as MCP Server (graph tools)
  participant FS as Raw File Store

  Dev->>Installer: run claudeInstall / geminiInstall
  Installer->>Dev: inject MCP_ROUTING_GUIDANCE into pre-tool message
  Dev->>MCP: ask question -> choose tool by question type (e.g., relevant_files)
  MCP-->>Dev: graph-tool answer (feature_map / risk_map / etc.)
  alt MCP cannot answer or unavailable
    Dev->>FS: use raw-file search (retrieve / read)
    FS-->>Dev: file contents
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• v0.10.1 — honest numbers + lean MCP profile #28: Modifies src/infrastructure/install.ts and installation templates; likely directly related to routing/pre-tool message changes.

Poem

🐰 I hopped through code, rearranged the trail,
Questions choose the tool — no single frail tale.
Graph first, then files when graphs can't cope,
A nimble route, a developer's hope. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Improve graph tool routing guidance' directly summarizes the main change: updating how graphify MCP tool usage is routed across different AI agent platforms and surfaces.
Description check	✅ Passed	The description covers all required template sections with substance: Summary explains the three main changes, Testing lists verification commands, and Checklist items address updates/tests/secrets. The description is complete and well-structured.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch native-agent-routing

---

_{Review rate limit: 9/10 reviews remaining, refill in 6 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@tests/unit/install.test.ts`:
- Around line 236-239: The test assertions checking the generated GEMINI.md are
missing an assertion for the routing-token "impact"; update the assertions that
call readFileSync(join(projectDir, 'GEMINI.md'), 'utf8') to also include
expect(...).toContain('impact') so the test covers the impact section for both
occurrences (the block around the current expect(...).toContain('relevant_files'
/ 'feature_map' / 'risk_map' / 'implementation_checklist') and the other similar
block later in the file).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: b146c2c5-4f66-47e8-9464-5e08a5c2fe01

📥 Commits

Reviewing files that changed from the base of the PR and between bba3bd5 and 2b8ee76.

📒 Files selected for processing (5)

• src/infrastructure/install.ts
• tests/unit/install-templates.test.ts
• tests/unit/install.test.ts
• tests/unit/package-metadata.test.ts
• vitest.config.ts