PR #3452 - trycompai/comp

What does this PR do?

Fixes the last remaining stale npx commands in the agent instruction files, and stops root CLAUDE.md / AGENTS.md from drifting apart again.

Fixes: no linked issue — found via an external scan (details below); happy to open a tracking issue if you prefer.

The problem. Root CLAUDE.md and AGENTS.md are near-identical twins (~96% line overlap), and they have been drifting in both directions:

The npx→bunx docs sweep (2da22b6, Apr 27) fixed AGENTS.md, .claude/skills/* and .cursor/rules/* — but missed root CLAUDE.md and apps/api/CLAUDE.md. So root CLAUDE.md still says cd apps/app && npx vitest run a couple of lines below its own "Package manager: bun (never npm/yarn/pnpm)" rule, and apps/api/CLAUDE.md carries ten more npx commands.
The responsive-by-default mandate (07808ba, Jul 2) landed only in CLAUDE.md, so AGENTS.md readers never see it — while CLAUDE.md readers never see the "API Endpoint Contract" section that only exists in AGENTS.md.

This bites real users: when both files exist, Claude Code reads CLAUDE.md (not AGENTS.md), so Claude users get exactly the stale half. And .cursorrules points Cursor users at CLAUDE.md too.

The fix (4 files):

AGENTS.md — port the one rule that only existed in CLAUDE.md (the Responsive MANDATORY bullet), making it a true superset.
CLAUDE.md — replace with an @AGENTS.md import stub (Claude Code expands @ imports natively). One source of truth; the twins can't drift again.
.cursorrules — point its "read the rules" line at AGENTS.md instead of the now-stubbed CLAUDE.md.
apps/api/CLAUDE.md — mechanical npx → bunx (×10), the same substitution 2da22b6 applied everywhere else.

If you'd rather keep CLAUDE.md as a standalone full file, happy to downscope this to just fixing the four stale commands in place — though the stub is the part that prevents recurrence.

Visual Demo (For contributors especially)

Docs-only PR, so a text demo: we measured the impact with plain claude -p on a pinned checkout (b04358d), asking 12 questions about repo conventions/commands, 2 runs per side:

	pass	mean latency	agent turns
current docs	18/24	15.7 s	44
with this fix	24/24	9.9 s (−37%)	24 (−45%)

The three command questions failed deterministically before: asked "What is the exact command to run the frontend app test suite?", the agent answered cd apps/app && npx vitest run — verbatim from CLAUDE.md, in both runs, with no self-verification. With the fix it answers the bunx form and needs fewer turns (no conflicting sources left to reconcile).

Full disclosure: we found this while validating ai-harness-doctor, a doc-drift linter we maintain — that's how this repo ended up in our scan sample. The numbers above are plain claude -p runs, reproducible without our tool; raw data and methodology: benchmark/corpus/evals/comp. (The measured treatment also normalized a few section headings for our tool's benefit; content-wise it is identical to this PR.)

Mandatory Tasks (DO NOT REMOVE)

I have self-reviewed the code (A decent size PR without self-review might be rejected).
N/A — changes touch agent instruction files only, not the developer docs in /docs.
N/A — docs-only change with no code paths; manual verification steps below.

How should this be tested?

grep -rn "npx" CLAUDE.md AGENTS.md .cursorrules apps/api/CLAUDE.md → no matches.
Open CLAUDE.md — it is now a one-line @AGENTS.md import, which Claude Code expands automatically. Smoke test from the repo root: claude -p "What is the exact command to run the apps/app test suite?" → answers the bunx form.
No env vars or test data needed.

Checklist

All template bullets removed per the template's instruction — none apply (contributing guide read, style followed, no new warnings).

P.S. One more instance of the same disease, deliberately left out of scope: CONTRIBUTING.md still says PRs should be made against a dev branch, but dev no longer exists and recent PRs all target main.

Summary by cubic

Fix stale npx commands in agent docs and prevent drift between CLAUDE.md and AGENTS.md. CLAUDE.md is now an @AGENTS.md import stub, .cursorrules points to AGENTS.md, AGENTS.md adds the missing responsive rule, and apps/api/CLAUDE.md switches npx → bunx for @trycompai/api commands.