v2.1.1: adopt AGENTS.md cross-tool standard#4
Merged
Conversation
Make AGENTS.md the canonical agent-instructions file (read by Cursor, Codex, Copilot, Gemini CLI, and others). CLAUDE.md becomes a one-line @AGENTS.md import so Claude Code loads the same content with no duplicate file and no drift. Fix the stale README version badge (2.0.0 -> 2.1.1) and bump VERSION. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces cross-tool agent support by creating a canonical AGENTS.md file containing project instructions for AI tools, and updates CLAUDE.md to import it. It also bumps the project version to 2.1.1 across VERSION, README.md, and CHANGELOG.md. However, Claude Code does not support transclusion or import directives like @AGENTS.md in CLAUDE.md, so it is recommended to use a git symbolic link instead to avoid losing instructions for Claude Code.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Comment on lines
+1
to
+5
| @AGENTS.md | ||
|
|
||
| An open, AI-friendly knowledge base for edtech founders, built by ASU ScaleU. The knowledge lives in `data/` as markdown. When answering a founder's question, read the relevant file rather than leaning on training data for facts about regulations, companies, funding, learning science, or operator experience. | ||
|
|
||
| ## Knowledge base | ||
|
|
||
| - `data/` — regulatory (FERPA, COPPA, state privacy, accreditation, accessibility), competitive landscape, funding landscape, buyer personas, procurement, pilot benchmarks, ESSA evidence tiers | ||
| - `data/research/` — hundreds of peer-reviewed learning-science papers across the major topics. Cite specific papers with author, year, and DOI. Index (with the current count) in `data/research/README.md`. | ||
| - `data/operator-lessons.md` — dozens of operator and investor lessons distilled from Lenny's Podcast and Lenny's Newsletter, mapped to edtech. Practitioner experience, not peer-reviewed; don't present it as research. | ||
| - `data/ai-native-framework.md` — AI-native vs. bolted-on: criteria, the removal test, architecture patterns, pricing models, and the Karpathy hierarchy. Use it to classify a founder's AI posture. | ||
| - `data/higher-ed-jobs-atlas.md` and `data/founder-traps.md` — ScaleU's SXSW EDU 2026 higher-ed framework: validated jobs across the student journey with saturation analysis, and the structural patterns founders miss. | ||
| - `data/demand-validation.md` and `data/jtbd-interviews.md` — the demand-validation toolkit: the 5-question diagnostic with scoring and depth probes, and the JTBD Switch interview method for discovering and validating real demand. | ||
| - `data/defensibility-moats.md` — how an edtech product stays defensible when LLMs can replicate features (exposure spectrum, four moats, the AI-substitution durability test). | ||
| - `data/ai-risk-and-trust.md` — AI's effect on learners and trust, with design responses. Practitioner signals from the ASU+GSV 2026 summit, not peer-reviewed; don't present as research. | ||
| - `data/buyer-demand-signals.md` — the durable jobs institutional buyers switch for. Practitioner signals, not peer-reviewed. | ||
| - `ETHOS.md` — the seven principles, starting with "validate demand, not interest." | ||
|
|
||
| Always cite the source: a named regulation, a paper's DOI, or the named operator. | ||
|
|
||
| ## For contributors | ||
|
|
||
| ### Updating data files | ||
|
|
||
| Edit the relevant markdown in `data/`. Keep the existing structure and formatting. For regulatory data, note the update date at the bottom of the file. For the competitive landscape, verify company status before updating. | ||
|
|
||
| ### Adding research papers | ||
|
|
||
| Append to the relevant topic file in `data/research/`. Follow the table format — Title, Takeaway, Type, Year, Citations, DOI — and sort by citations descending. If the topic doesn't exist, create a new file and add it to `data/research/README.md`. | ||
| <!-- Canonical, cross-tool project instructions live in AGENTS.md (the AGENTS.md standard, | ||
| read by Cursor, Codex, Copilot, Gemini CLI, and others). The import above loads them into | ||
| Claude Code, which reads CLAUDE.md but not AGENTS.md. Edit AGENTS.md, not this file. --> |
There was a problem hiding this comment.
Claude Code reads CLAUDE.md as a plain text file and does not support transclusion or import directives like @AGENTS.md. As a result, Claude Code will only see the literal text @AGENTS.md and will not receive any of the actual instructions or guidelines for the repository.
To maintain a single source of truth without duplicating content, you can use a git symbolic link so that both files point to the same content:
ln -sf AGENTS.md CLAUDE.mdThis ensures that any tool reading CLAUDE.md (like Claude Code) or AGENTS.md (like Cursor, Copilot, etc.) will see the full instructions.
Make the v2.1.1 cross-tool claim true instead of aspirational. Codex and Cursor read AGENTS.md at the repo root natively; add thin pointers for the rest so no agent is left answering from stale training data: - GEMINI.md imports AGENTS.md (@./AGENTS.md) - .github/copilot-instructions.md points GitHub Copilot to AGENTS.md - CLAUDE.md keeps its @AGENTS.md import; the explanation moves into a visible blockquote so it renders on GitHub instead of a hidden comment Fix doc-accuracy issues surfaced by review: - research-table format in AGENTS.md, CONTRIBUTING.md, ARCHITECTURE.md now shows the leading # column the real tables and CI require, so a contributor who follows the docs passes CI - ARCHITECTURE.md "Study Type" -> "Type"; add an agent-instructions section - README "How to use it" names AGENTS.md so the feature is discoverable - validate.yml fails CI if the README badge and VERSION ever disagree again Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Summary
Adopt the AGENTS.md cross-tool standard as the single source of truth for agent instructions, and deliver the coverage it advertises, shipped as v2.1.1.
Claude Code reads
CLAUDE.md, notAGENTS.md; Codex and Cursor readAGENTS.mdat the repo root natively; Gemini CLI readsGEMINI.md; GitHub Copilot reads.github/copilot-instructions.md. Rather than overstate coverage, this PR ships a thin pointer for each tool so every one of them loads the same directive — answer from the citeddata/files, not stale training data.AGENTS.mdholds the only copy of the content; the pointers carry no content, so nothing drifts.Documentation
Cross-tool instruction files (single content source =
AGENTS.md):AGENTS.md(new) — canonical instructions. Read natively by Codex and Cursor.CLAUDE.md—@AGENTS.mdimport; explanation moved from a hidden HTML comment into a visible blockquote so it renders on GitHub.GEMINI.md(new) —@./AGENTS.mdimport for Gemini CLI..github/copilot-instructions.md(new) — points GitHub Copilot toAGENTS.md.Accuracy + discoverability:
README.md— version badge2.0.0→2.1.1; "How to use it" now namesAGENTS.mdas the instruction file agents read.ARCHITECTURE.md— new "Agent instructions" section; research-table columns corrected (Study Type→Type, leading#column added).CONTRIBUTING.md/AGENTS.md— research-table format now shows the leading#column the real tables and CI require (a contributor following the docs no longer fails CI).VERSION—2.1.0→2.1.1.CHANGELOG.md—2.1.1 (2026-06-13)entry; prior entries preserved..github/workflows/validate.yml— new step fails CI if the README version badge andVERSIONdisagree, so the badge can't silently drift again.Documentation coverage
All counts verified accurate (376 papers, 19 topics, 71 operator lessons, 7 principles, 15 jobs);
validate.ymldata/research checks are unaffected (nodata/content changed). The cross-tool claim is now backed by a real instruction file for each named tool.Review
This PR was reviewed with a 25-agent recall pass (
/code-reviewxhigh). It caught that the original v2.1.1 commit overstated cross-tool coverage (Gemini CLI / default Copilot do not readAGENTS.mdwithout their own file) and a pre-existing research-table doc/CI mismatch. Both are fixed here. Remaining known tradeoff (not a defect):CLAUDE.md/GEMINI.mdhave no inline fallback if their import fails — deliberate, to keepAGENTS.mdthe single source.🤖 Generated with Claude Code