Make AGENTS.md the source of truth with CLAUDE.md as a symlink

.claude/agents/code-simplifier.md

@@ -18,7 +18,7 @@ Find overly complex code and suggest simpler alternatives.
 ## Rules
 
 - Read the code before suggesting changes.
-- Respect the project's conventions (see `CLAUDE.md`).
+- Respect the project's conventions (see `AGENTS.md`).
 - Ensure suggestions maintain correctness — simplification must not break behavior.
 - Consider WASM constraints when suggesting alternatives.
 

.claude/agents/pr-reviewer.md

@@ -411,7 +411,7 @@ if [ -n "$NUMBER" ]; then
     # to distinguish pending/no-output from command failures.
     #
     # Query the *full* check set — not `--required`. Branch protection's
-    # required list in this repo omits gates that CLAUDE.md still treats as PR
+    # required list in this repo omits gates that AGENTS.md still treats as PR
     # gates (e.g. `Analyze (rust)`, `vitest`, CodeQL, browser/integration
     # tests), so a `--required`-only query can report clean CI while one of
     # those failed and hide a real regression.
@@ -460,7 +460,7 @@ Classify CI by `bucket`, not by the `gh pr checks` exit code, over the
   in step 8a's "Cross-cutting / body-level findings" section. This applies to
   **any** failed check, not just required ones — a failed non-required gate
   (`vitest`, `Analyze (rust)`, integration tests, CodeQL) is still a real
-  regression CLAUDE.md treats as a PR gate. Note in the finding whether the
+  regression AGENTS.md treats as a PR gate. Note in the finding whether the
   check name appears in `$required_names` (merge-blocking under branch
   protection) or not (a failing gate branch protection doesn't enforce). That
   finding feeds the verdict rules below, so a PR with any failed CI cannot fall
@@ -501,7 +501,7 @@ For each changed file, evaluate:
 - No Tokio or runtime-specific deps in `crates/trusted-server-core`
 - Fastly-specific APIs only in `crates/trusted-server-adapter-fastly`
 
-#### Convention compliance (from CLAUDE.md)
+#### Convention compliance (from AGENTS.md)
 
 - `expect("should ...")` instead of `unwrap()` in production code
 - `error-stack` (`Report<E>`) with `derive_more::Display` for errors (not thiserror/anyhow)
@@ -921,7 +921,7 @@ pure-renaming suggestions don't need that disclaimer.
 
 The targeted preflight above narrows clippy to the touched adapter. That's
 deliberately cheap so verification stays fast for one-line edits. But
-CLAUDE.md's required CI gates include the full target-matched clippy alias
+AGENTS.md's required CI gates include the full target-matched clippy alias
 chain, all four adapter test aliases, and the cross-adapter parity suite, and
 the targeted run won't catch issues that appear only under another adapter's
 target or feature set, in `--tests`, or in a downstream crate. Use the full
@@ -946,7 +946,7 @@ gate when **any** of these is true:
 ```
 
 **JS/TS suggestions** (run from the package root in a subshell so the
-worktree's cwd is unaffected). CLAUDE.md's JS-side build pipeline also runs
+worktree's cwd is unaffected). AGENTS.md's JS-side build pipeline also runs
 `node build-all.mjs` to re-bundle the per-integration IIFEs; skipping it
 means a suggestion that edits `src/integrations/*/index.ts` could compile
 under `vitest` but break the runtime bundle the Rust crate `include_str!`s

.claude/commands/review-changes.md

@@ -3,7 +3,7 @@ Review all staged and unstaged changes in the working tree.
 1. Run `git diff` and `git diff --cached` to see all changes.
 2. Review each changed file for:
    - Correctness and logic errors
-   - Style violations (see CLAUDE.md conventions)
+   - Style violations (see AGENTS.md conventions)
    - Missing error handling
    - Security concerns (hardcoded secrets, injection risks)
    - Missing or incorrect tests

.github/pull_request_template.md

@@ -35,7 +35,7 @@ Closes #
 
 ## Checklist
 
-- [ ] Changes follow [CLAUDE.md](/CLAUDE.md) conventions
+- [ ] Changes follow [AGENTS.md](/AGENTS.md) conventions
 - [ ] No `unwrap()` in production code — use `expect("should ...")`
 - [ ] Uses `tracing` macros (not `println!`)
 - [ ] New code has tests

.github/workflows/format.yml

@@ -9,6 +9,36 @@ permissions:
   contents: read
 
 jobs:
+  check-claude-md-symlink:
+    name: CLAUDE.md symlink guard
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # AGENTS.md is the source of truth and CLAUDE.md must stay a symlink to
+      # it. A checkout with core.symlinks=false (the Git for Windows default)
+      # materializes the symlink as a plain text file containing "AGENTS.md";
+      # if that file is committed, agents silently load it as the entire
+      # project instructions. Guard the tree entry so the broken form cannot
+      # land (see issue #1091).
+      - name: Verify CLAUDE.md is a symlink to AGENTS.md
+        shell: bash
+        run: |
+          mode=$(git ls-tree HEAD CLAUDE.md | awk '{print $1}')
+          if [ "$mode" != "120000" ]; then
+            echo "::error file=CLAUDE.md::CLAUDE.md must be a symlink to AGENTS.md (tree mode 120000), found mode ${mode:-<missing>}. This usually means a checkout with core.symlinks=false committed the materialized text file; re-add the symlink with core.symlinks=true."
+            exit 1
+          fi
+          target=$(git cat-file blob HEAD:CLAUDE.md)
+          if [ "$target" != "AGENTS.md" ]; then
+            echo "::error file=CLAUDE.md::CLAUDE.md must point at AGENTS.md, found '${target}'."
+            exit 1
+          fi
+          if [ ! -f AGENTS.md ]; then
+            echo "::error file=AGENTS.md::CLAUDE.md points at AGENTS.md, but AGENTS.md does not exist."
+            exit 1
+          fi
+
   format-rust:
     name: cargo fmt
     runs-on: ubuntu-latest