docs(agents): one compact guide for Claude, Codex and Cursor

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — the agent instructions for Claude Code, Codex and Cursor, plus a test. No engine change. Not micro: more than 200 lines.

• Problem: coding agents are a headline feature of this repo, and their instructions had four problems:
  • Codex couldn't read most of them. AGENTS.md was 55 KB, and Codex reads AGENTS.md only up to project_doc_max_bytes (32 KiB by default). Everything after line 460 was silently dropped: structured-output, squad and simulation formats, reference rules, commands, naming and renames.
  • They taught agents things that break.
    • UUIDs in assistant_ids, scenario judges and credentialId (they only work in one org, and break promotion);
    • the deprecated endCallFunctionEnabled;
    • a cleanup --force command that is refused without --confirm;
    • "every command is interactive";
    • "files get a UUID suffix after first push" (only pulled files do).
  • The most important safety rule only reached Claude: a direct API PATCH replaces nested objects. A partial model PATCH once wiped live system prompts.
  • The customer-deployment changelog rule only reached Cursor. Claude and Codex never saw it.
• Who it affects: everyone who points a coding agent at this repo or a fork, and the live phone lines those agents can change.
• What changes:

  • AGENTS.md is rewritten as a 19 KB core:

    • which repository you're in (template or customer deployment);
    • safety rules:
      • ask before anything that changes a live org or deletes, with a table of commands and why;
      • never handle API keys;
      • reference resources by name, never by UUID;
      • the PATCH rule;
      • .ts files execute code;
      • don't bypass a safety check to make a command pass;
    • setup without a terminal, and the change loop (validate, dry-run PR checks, deploy only with a yes, verify, commit);
    • a corrected quick reference and reference table, and naming and renames;
    • simulations and PR checks, and promotion;
    • learnings routing, and engine conventions.

  • Reference material moves to docs/guides/:

    • resource-reference.md: every setting, with the UUID and deprecation fixes;
    • writing-prompts.md;
    • sync internals (conflicts, drift gate, output icons, list completeness) into how-it-works.md;
    • test-call output into commands.md.

    push --strict is documented, and "run a plain pull first in an existing repo" is now in both AGENTS.md and the workflows guide.

  • CLAUDE.md is now @AGENTS.md plus one paragraph, instead of a hand-copied 19-row routing list.

  • Cursor: the changelog rule folds into AGENTS.md, and the learnings rule matches the two indexes and asks for no customer or person names.

  • New tests/agent-docs.test.ts checks that:

    • AGENTS.md stays under 30 KB;
    • CLAUDE.md imports it;
    • every docs/learnings/ file is routed from both indexes;
    • there are no UUIDs in agent-facing examples.

  • The README and CONTRIBUTING.md link the new guides and describe the single-file setup.

Evidence of value

Check	Before	After
AGENTS.md size	55,358 bytes (Codex reads up to line 460)	18,852 bytes (Codex reads all of it)
PATCH safety rule visible to	Claude only	Claude, Codex, Cursor
Changelog rule visible to	Cursor only	Claude, Codex, Cursor
UUIDs in agent-facing examples	3, plus a credentialId placeholder telling agents to use a UUID	0 (tested)

• Each correction was checked against the code:
  • the engine resolves assistant_ids and credential names;
  • endCallFunctionEnabled is marked deprecated in the API types;
  • cleanup requires --confirm;
  • pull names new files <slug>-<uuid8>, and push never renames;
  • six commands are interactive;
  • --strict refuses to push on validation errors.
• Nothing lost: I compared every line of the old AGENTS.md and CLAUDE.md; each one is restated in the new core or moved into a guide. Two facts that had been dropped were restored (--strict, and seeding baselines with a first pull).
• Tests and links: npm test passes, 500 tests (4 new), and every link across 47 markdown files resolves.

Found while checking (not changed here): npm run cleanup doesn't read .vapi-ignore, and deletes every platform resource missing from the state file. Ignored resources are never in state, so a destructive cleanup deletes exactly the resources a team excluded. This PR documents the hazard (AGENTS.md, workflows guide) and logs it as improvements.md #36. The engine fix is a separate change.

Testing plan

• tests/agent-docs.test.ts (4 tests), the existing suite, and the link checker.
• Not tested:
  • a live Codex, Cursor or Claude session reading the new files;
  • the Claude @AGENTS.md import (a documented Claude Code feature, not run here).

Stacked on #71.

🤖 Generated with Claude Code

[scott-lowe-vapi]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: identify every gitops API request with a User-Agent #78
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72 👈 (View in Graphite)
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.