feat(init): force CodeGraph usage guidance into each agent's always-on instructions#26
Merged
Conversation
…n instructions
`whygraph init --agent <X>` now installs a CodeGraph usage-guidance block
into the always-on instruction surface of every supported agent, so the
agent prefers the `codegraph_*` MCP tools over grep without the user
running CodeGraph's own installer.
- Claude Code: new `.claude/CLAUDE.md` merge file (canonical block verbatim)
- Codex / Copilot: append a neutral `## CodeGraph` section to the existing
AGENTS.md / copilot-instructions.md merge files
- Cursor: new `whygraph-codegraph.mdc` rule with `alwaysApply: true`
(existing rules are `alwaysApply: false`, i.e. lazy — not forcing)
Only code change is wiring `assets_merge_files=("CLAUDE.md",)` on the
Claude target; the existing append-merge machinery handles the rest
idempotently. Tests + docs updated.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
whygraph init --agent <name>already copies a per-agent asset tree into the target repo (WhyGraph's own subagents, skills, slash commands, rules) but ships no CodeGraph usage guidance. Because WhyGraph sits on top of CodeGraph — everywhygraph scanbuilds/refreshes the.codegraph/index — a developer in a WhyGraph-initialized repo has thecodegraph_*MCP tools available, but their agent has no instructions on how to use them, so it tends to grep instead, or dump hugecodegraph_exploreoutput into context.CodeGraph's own Claude Code installer solves this by injecting a guidance block into
.claude/CLAUDE.md. This PR does the equivalent for every agent WhyGraph supports, so the guidance is forced — it lives in each agent's always-on instruction surface, not a lazily-triggered skill. (A skill / description-triggered rule may not fire before the wrong reflex — grep — wins.)Per-agent always-on surface
.claude/CLAUDE.mdassets_merge_files)AGENTS.md.github/copilot-instructions.md.cursor/rules/whygraph-codegraph.mdcalwaysApply: trueThe Cursor catch: its existing four rules are
alwaysApply: false(lazy, like skills) — not forcing. CodeGraph forcing needs a dedicatedalwaysApply: truerule.Content
.claude/CLAUDE.md, the user global, and the npm template).codegraph_*over grep", "don't pull large explore output into context", lightweight-tool table).Changes
assets_merge_files=("CLAUDE.md",)on the_CLAUDEtarget inagents.py. The existing_merge_blockmachinery handles fresh-write / replace-in-markers / append idempotently — no machinery changes.claude-code/CLAUDE.md+cursor/rules/whygraph-codegraph.mdc; extendedcodex/AGENTS.md+vscode/copilot-instructions.md.CLAUDE.md.test_init_agent_claude_merges_existing_claude_md.Verification
uv run pytest→ 451 passed.initper agent in a scratch repo: Claude gets the verbatim block, Codex/Copilot the neutral section, Cursor thealwaysApply: truerule — all under<!-- BEGIN whygraph -->markers (frontmatter for Cursor).init --agent claudekeeps exactly one WhyGraph block (idempotent, non-destructive of user content).Known tradeoff
If a user also runs CodeGraph's own installer, its block (under
<!-- CODEGRAPH_START -->) and WhyGraph's (under<!-- BEGIN whygraph -->) coexist as two near-identical blocks. Acceptable — WhyGraph's path is self-sufficient by design. No de-dup logic in v1.