fix(installer): stop duplicating agent instructions; MCP server is the single source of truth (#529) (#538)

The installer wrote a `## CodeGraph` usage block into each agent's
instructions file (CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules /
Kiro steering) that duplicated, almost verbatim, the guidance the MCP
server already emits in its `initialize` response — so agents that
surface MCP instructions (Claude Code) read the same playbook twice
every turn.

All 6 instruction-writing targets (claude, cursor, codex, opencode,
gemini, kiro) now stop writing the block. install self-heals by
stripping a block a previous version wrote (uninstall already did), so
the next `codegraph install`/`uninstall` cleans up existing installs;
upgrading the package alone does not (the leftover block is harmless).
server-instructions.ts is now the single source of truth — the two
steers unique to the old template ("trust codegraph, don't re-verify
with grep" and the not-initialized -> `init -i` hint) are ported there.

Removes the now-dead INSTRUCTIONS_TEMPLATE / CLAUDE_MD_TEMPLATE,
claude-md-template.ts, writeClaudeMd / hasClaudeMdSection, and the
Cursor-only wireProjectSurfaces bootstrap. The install log learned a
"Removed" verb. Tests rewritten to the new contract + self-heal
coverage (140/140 installer tests pass).

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
2026-05-28 15:13:23 -05:00
committed by GitHub
co-authored by Claude Opus 4.8
parent cea78ceb1b
commit a9c9e76d8c
18 changed files with 282 additions and 593 deletions
+18
View File
@@ -154,6 +154,24 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
bodies). An agent investigating `Splitter.SplittingIterator.separatorStart`
now sees the four anonymous overrides in its trail without a Read.
### Changed
- **The installer no longer writes a `## CodeGraph` instructions block into
your agent's instructions file** (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`,
Cursor's `.cursor/rules/codegraph.mdc`, or Kiro's steering doc). That block
duplicated, almost verbatim, the usage guidance the MCP server already
emits in its `initialize` response — so every agent that surfaces MCP
instructions (Claude Code does) read the same playbook twice each turn
(#529). The MCP server instructions are now the single source of truth.
`codegraph install` stops writing the block, and **the next time you run
`codegraph install` (or `codegraph uninstall`) it strips a block a previous
version wrote**, preserving everything else in the file (and deleting Cursor
`.mdc` / Kiro steering files that were ours outright). Note: simply upgrading
the npm package does not remove an existing block — re-run the installer to
clean it up. The leftover block is harmless meanwhile (just redundant with
the MCP instructions). If you'd added your own notes inside the
`<!-- CODEGRAPH_START -->`/`<!-- CODEGRAPH_END -->` markers, move them outside
the markers first — only the marked block is removed.
### Fixed
- **MCP tools no longer return rows for files deleted while no server was
running.** The post-open catch-up sync that reconciles the index against