Skip to content

feat(init): force CodeGraph usage guidance into each agent's always-on instructions#26

Merged
cvetty merged 2 commits into
mainfrom
feature/make-image-targets
May 31, 2026
Merged

feat(init): force CodeGraph usage guidance into each agent's always-on instructions#26
cvetty merged 2 commits into
mainfrom
feature/make-image-targets

Conversation

@cvetty
Copy link
Copy Markdown
Contributor

@cvetty cvetty commented May 31, 2026

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 — every whygraph scan builds/refreshes the .codegraph/ index — a developer in a WhyGraph-initialized repo has the codegraph_* MCP tools available, but their agent has no instructions on how to use them, so it tends to grep instead, or dump huge codegraph_explore output 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

Agent Surface Mechanism
Claude Code .claude/CLAUDE.md new append-merge file (assets_merge_files)
Codex AGENTS.md extend existing merge file
Copilot / VS Code .github/copilot-instructions.md extend existing merge file
Cursor .cursor/rules/whygraph-codegraph.mdc new rule with alwaysApply: true

The Cursor catch: its existing four rules are alwaysApply: false (lazy, like skills) — not forcing. CodeGraph forcing needs a dedicated alwaysApply: true rule.

Content

  • Source of truth: CodeGraph's own block (verified byte-identical across the repo's .claude/CLAUDE.md, the user global, and the npm template).
  • Claude Code: vendored verbatim ("Explore agent" / "main session" are native Claude Code concepts).
  • Cursor / Codex / Copilot: same forcing rules in neutral wording (drop Claude-isms; keep "prefer codegraph_* over grep", "don't pull large explore output into context", lightweight-tool table).

Changes

  • Only code change: assets_merge_files=("CLAUDE.md",) on the _CLAUDE target in agents.py. The existing _merge_block machinery handles fresh-write / replace-in-markers / append idempotently — no machinery changes.
  • New bundled claude-code/CLAUDE.md + cursor/rules/whygraph-codegraph.mdc; extended codex/AGENTS.md + vscode/copilot-instructions.md.
  • One-sentence note in the project CLAUDE.md.
  • Tests: count/manifest assertions updated (8→9 files, +cursor rule), marker assertions on the Claude/Cursor init tests, and a new test_init_agent_claude_merges_existing_claude_md.

Verification

  • uv run pytest451 passed.
  • Manual init per agent in a scratch repo: Claude gets the verbatim block, Codex/Copilot the neutral section, Cursor the alwaysApply: true rule — all under <!-- BEGIN whygraph --> markers (frontmatter for Cursor).
  • Re-running init --agent claude keeps 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.

cvetty added 2 commits May 31, 2026 19:42
…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.
@cvetty cvetty merged commit 0062d4a into main May 31, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant