docs: add AGENTS.md (CLAUDE.md symlink) for AI coding agents#20
Merged
Conversation
Adds a concise operating manual for AI coding agents contributing to this repo. It references README.md for domain context rather than duplicating it, and codifies the contribution norms: schema.ts is the source of truth and schema.json is regenerated (never hand-edited) in the same commit; keep changes small and scoped; open PRs for human review rather than self-merging agent-generated changes; respect the experimental/SEP-2127 status; treat the schema as a public contract. CLAUDE.md is a symlink to AGENTS.md so Claude Code loads it automatically while AGENTS.md stays the portable, tool-agnostic entry point.
- Mention npm run format:check in the local pre-push checks - Don't imply an examples/Server/invalid dir exists; reference parallel dirs - Soften graduation/archival to conditional framing matching the README - Phrase the open-PR-for-review guidance neutrally
Drop the What-this-repo-is, Layout, and Working-in-this-repo sections and the FAQ -- they restated the README (domain, layout, schema build/validate workflow, $schema convention, graduation plan). AGENTS.md now points to the README for all mechanics and keeps only the contribution conduct the README doesn't cover (open PRs for human review, stay small/scoped, respect the experimental spec-tracked status, treat the schema as a public contract).
dsp-ant
approved these changes
Jun 8, 2026
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
2 participants
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.
What & why
Adds an
AGENTS.md(with aCLAUDE.mdsymlink) at the repo root — a concise operating manual for AI coding agents contributing to this repository.It is deliberately minimal and non-duplicative:
README.mdremains the source of truth for everything mechanical (what a Server Card is, the layout, thenpm run generate/check/validate/formatworkflow, theschema.ts→schema.jsonregeneration rule, the$schemaURL convention, the graduation plan), andAGENTS.mdpoints to it rather than restating it.AGENTS.mdadds only the contribution conduct the README doesn't cover:AGENTS.mdis the portable, tool-agnostic entry point;CLAUDE.mdis a symlink to it so Claude Code loads it automatically — one file, two entry points, zero duplication.Verification
npm run checkpasses (schema.json in sync,tsc --noEmitclean):✓ schema.json is up to datenpm run validatepasses:All 7 example(s) passed.npm run format:checkpasses (the newAGENTS.mdis Prettier-clean):All matched files use Prettier code style!AGENTS.md+CLAUDE.mdsymlink; noschema.ts/schema.json/examples touchedCLAUDE.mdis a symlink toAGENTS.md(verifiedls -l:CLAUDE.md -> AGENTS.md), no content duplicationAGENTS.mdreferencesREADME.mdfor all mechanics and only adds contribution conduct (verified by re-reading both files side by side after a fresh-eyes review)build,CodeQL, andAnalyze (actions)all pass (re-confirmed after each revision)🤖 Opened by an AI coding agent for human review — not to be self-merged (per the contribution norms in this very PR). Please review and merge if it looks good.