fix: use cross-platform Node script for postinstall symlinks (#577)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

CONTRIBUTING.md

@@ -57,6 +57,11 @@ git pull upstream main
 pnpm install
 ```
 
+This also creates symlink aliases (`.opencode`, `agents`, `AGENTS.md`) so that AI coding tools other than Claude Code can discover project instructions.
+
+> [!NOTE]
+> **Windows users:** Directory symlinks use junctions and work automatically. File symlinks (e.g., `AGENTS.md → CLAUDE.md`) require [Developer Mode](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) enabled. If symlink creation fails, `pnpm install` will log a warning but continue normally — the canonical files (`.claude/`, `CLAUDE.md`) still work fine.
+
 Then build all workspace packages:
 
 ```sh

package.json

@@ -16,7 +16,7 @@
   },
   "scripts": {
     "prepare": "simple-git-hooks",
-    "postinstall": "pnpm link:opencode && pnpm link:agents",
+    "postinstall": "node scripts/link-aliases.mjs",
     "build:packages": "turbo run build --filter='./packages/*'",
     "build:site": "turbo run build --filter=site",
     "build": "turbo run build",
@@ -28,8 +28,7 @@
     "lint": "biome check .",
     "lint:fix": "biome check . --write",
     "lint:fix:file": "biome check --write",
-    "link:opencode": "[ -e .opencode ] || ln -s .claude .opencode",
-    "link:agents": "[ -e AGENTS.md ] || ln -s CLAUDE.md AGENTS.md; [ -e agents ] || ln -s .claude agents",
+    "link:aliases": "node scripts/link-aliases.mjs",
     "size": "node .github/scripts/bundle-size.js | node .github/scripts/bundle-size-report.js",
     "test": "turbo run test",
     "typecheck": "tsc --build"

scripts/link-aliases.mjs

@@ -0,0 +1,37 @@
+/**
+ * Creates symlink aliases so that AI coding tools other than Claude Code
+ * (e.g., OpenCode, Cursor) can discover project instructions.
+ *
+ * Aliases created:
+ *   .opencode  → .claude       (directory)
+ *   agents     → .claude       (directory)
+ *   AGENTS.md  → CLAUDE.md     (file)
+ *
+ * Cross-platform notes:
+ * - Directory symlinks use 'junction' type, which works on Windows without
+ *   elevated privileges or Developer Mode.
+ * - File symlinks ('file' type) require elevated privileges or Developer Mode
+ *   on Windows. If creation fails, we log a warning instead of crashing
+ *   `pnpm install`. The alias is optional — the canonical files still work.
+ */
+import { existsSync, symlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const root = resolve(import.meta.dirname, '..');
+
+const aliases = [
+  { target: '.claude', path: '.opencode', type: 'junction' },
+  { target: '.claude', path: 'agents', type: 'junction' },
+  { target: 'CLAUDE.md', path: 'AGENTS.md', type: 'file' },
+];
+
+for (const alias of aliases) {
+  const fullPath = resolve(root, alias.path);
+  if (existsSync(fullPath)) continue;
+
+  try {
+    symlinkSync(alias.target, fullPath, alias.type);
+  } catch {
+    console.warn(`warning: could not create symlink ${alias.path} → ${alias.target}`);
+  }
+}