fix(build): rewrite rule-relative links when inlining rules into AGENTS.md

packages/react-best-practices-build/src/build.ts

@@ -4,7 +4,7 @@
  */
 
 import { readdir, readFile, writeFile } from 'fs/promises'
-import { join } from 'path'
+import { dirname, join, relative, sep } from 'path'
 import { Rule, Section, GuidelinesDocument, ImpactLevel } from './types.js'
 import { parseRuleFile, RuleFile } from './parser.js'
 import { SKILLS, SkillConfig, DEFAULT_SKILL } from './config.js'
@@ -276,8 +276,25 @@ async function buildSkill(skillConfig: SkillConfig) {
   // Generate markdown
   const markdown = generateMarkdown(sections, metadata, skillConfig)
 
+  // Rule bodies are authored inside rulesDir, so their same-directory links
+  // (e.g. ./async-defer-await.md) break once inlined into the output file.
+  // Rewrite them to stay valid relative to the output location.
+  const rulesPrefix = relative(dirname(skillConfig.outputFile), skillConfig.rulesDir)
+    .split(sep)
+    .join('/')
+  const rewritten = rulesPrefix
+    ? markdown.replace(
+        /\]\(\.\/([\w.-]+\.md)(#[^)]*)?\)/g,
+        (_match, file, anchor) => {
+          const target = `${rulesPrefix}/${file}`
+          const prefixed = target.startsWith('..') ? target : `./${target}`
+          return `](${prefixed}${anchor ?? ''})`
+        }
+      )
+    : markdown
+
   // Write output
-  await writeFile(skillConfig.outputFile, markdown, 'utf-8')
+  await writeFile(skillConfig.outputFile, rewritten, 'utf-8')
 
   console.log(
     `  ✓ Built AGENTS.md with ${sections.length} sections and ${ruleData.length} rules`

skills/react-best-practices/AGENTS.md

@@ -113,7 +113,7 @@ Waterfalls are the #1 performance killer. Each sequential await adds full networ
 
 When a branch uses `await` for a flag or remote value and also requires a **cheap synchronous** condition (local props, request metadata, already-loaded state), evaluate the cheap condition **first**. Otherwise you pay for the async call even when the compound condition can never be true.
 
-This is a specialization of [Defer Await Until Needed](./async-defer-await.md) for `flag && cheapCondition` style checks.
+This is a specialization of [Defer Await Until Needed](./rules/async-defer-await.md) for `flag && cheapCondition` style checks.
 
 **Incorrect:**
 
@@ -216,7 +216,7 @@ async function updateResource(resourceId: string, userId: string) {
 
 This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
 
-For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./async-cheap-condition-before-await.md).
+For `await getFlag()` combined with a cheap synchronous guard (`flag && someCondition`), see [Check Cheap Conditions Before Async Flags](./rules/async-cheap-condition-before-await.md).
 
 ### 1.3 Dependency-Based Parallelization
 
@@ -889,7 +889,7 @@ Safe exceptions:
 
 - Process-wide singletons that do not store request- or user-specific mutable data
 
-For static assets and config, see [Hoist Static I/O to Module Level](./server-hoist-static-io.md).
+For static assets and config, see [Hoist Static I/O to Module Level](./rules/server-hoist-static-io.md).
 
 ### 3.4 Cross-Request LRU Caching