Add CLAUDE.md symlinks for cross-platform AI tool compatibility

.github/workflows/test.yml

@@ -56,6 +56,17 @@ jobs:
       - name: Lint
         run: bun run lint
 
+  check-agents-md:
+    name: Check AGENTS.md Symlinks
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Check CLAUDE.md symlinks exist
+        run: bash scripts/check-agents-md.sh
+
   typecheck:
     name: Type Check
     runs-on: ubuntu-latest

package.json

@@ -35,6 +35,8 @@
     "lint:check": "biome lint .",
     "check": "biome check --write .",
     "check:ci": "biome check .",
+    "link-agents": "bash scripts/link-agents-md.sh",
+    "check:agents": "bash scripts/check-agents-md.sh",
     "prepublishOnly": "bun run build"
   },
   "keywords": [

scripts/check-agents-md.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Checks that every AGENTS.md (except root) has a CLAUDE.md symlink.
+# Used in CI to catch missing symlinks.
+
+set -euo pipefail
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+missing=0
+
+find "$root" -name AGENTS.md -not -path "$root/AGENTS.md" | sort | while read -r agents; do
+  dir="$(dirname "$agents")"
+  link="$dir/CLAUDE.md"
+  rel="${link#$root/}"
+
+  if [ ! -L "$link" ]; then
+    echo "missing symlink: $rel -> AGENTS.md"
+    echo "  run: bun run link-agents"
+    missing=1
+  fi
+done
+
+if [ "$missing" -eq 1 ]; then
+  exit 1
+fi

scripts/link-agents-md.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Creates CLAUDE.md symlinks for all AGENTS.md files (except root).
+# Re-run whenever you add a new AGENTS.md.
+
+set -euo pipefail
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+
+find "$root" -name AGENTS.md -not -path "$root/AGENTS.md" | while read -r agents; do
+  dir="$(dirname "$agents")"
+  link="$dir/CLAUDE.md"
+  if [ -L "$link" ]; then
+    echo "exists: ${link#$root/}"
+  elif [ -f "$link" ]; then
+    echo "skip (real file): ${link#$root/}"
+  else
+    ln -s AGENTS.md "$link"
+    echo "created: ${link#$root/}"
+  fi
+done

src/cache/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/cli/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/middleware/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/sandbox/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/setup/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/skills/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/tools/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

src/utils/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md