fix(agents): stage regenerated adapters on commit and validate them in CI

.claude/rules/content.md

@@ -25,7 +25,11 @@ the `docs` CLI or direct editing.
   examples.
 - Do not hardcode production docs URLs when a relative link or `relref` works.
 - Shared files have no frontmatter. A stub's `source:` must begin `/shared/`.
-  Direct shared edits require touching every source stub; `docs edit` finds them.
+  Identify every consumer before editing shared content. When previewing changes
+  with a running `hugo server`, touch each consuming stub or restart the server
+  because the watcher doesn't rebuild consumers automatically after shared-source
+  changes. Fresh builds, including CI builds and checks, don't require touching
+  consumer stubs. Edit stub content only when its frontmatter needs to change.
 - Use resource-ownership language for import/write/load guidance and write
   recommendations in InfluxData's first-person plural voice.
 

.github/instructions/content.instructions.md

@@ -24,7 +24,11 @@ the `docs` CLI or direct editing.
   examples.
 - Do not hardcode production docs URLs when a relative link or `relref` works.
 - Shared files have no frontmatter. A stub's `source:` must begin `/shared/`.
-  Direct shared edits require touching every source stub; `docs edit` finds them.
+  Identify every consumer before editing shared content. When previewing changes
+  with a running `hugo server`, touch each consuming stub or restart the server
+  because the watcher doesn't rebuild consumers automatically after shared-source
+  changes. Fresh builds, including CI builds and checks, don't require touching
+  consumer stubs. Edit stub content only when its frontmatter needs to change.
 - Use resource-ownership language for import/write/load guidance and write
   recommendations in InfluxData's first-person plural voice.
 

.github/workflows/pr-agent-instructions.yml

@@ -0,0 +1,55 @@
+name: Agent Instructions
+
+# Fails when generated agent instruction adapters don't match their
+# .agents/ sources. The commit hook regenerates and stages them, but
+# --no-verify, web edits, and missing hooks bypass it.
+
+on:
+  pull_request:
+    paths:
+      - 'AGENTS.md'
+      - '.agents/**'
+      - '.claude/rules/**'
+      - '.claude/skills'
+      - '.github/instructions/**'
+      - 'api-docs/AGENTS.md'
+      - 'assets/AGENTS.md'
+      - 'content/AGENTS.md'
+      - 'layouts/AGENTS.md'
+      - 'PLATFORM_REFERENCE.md'
+      - 'data/products.yml'
+      - 'helper-scripts/build-agent-instructions.js'
+      - 'helper-scripts/validate-agent-instructions.js'
+      - 'helper-scripts/agent-instruction-limits.js'
+      - '.github/workflows/pr-agent-instructions.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pr-agent-instructions-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate generated agent instructions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Setup docs environment
+        env:
+          CYPRESS_INSTALL_BINARY: 0
+        uses: ./.github/actions/setup-docs-env
+
+      - name: Validate agent instructions and generated adapters
+        run: |
+          if ! yarn validate:agent-instructions; then
+            echo '::error::Agent instruction adapters are out of date or invalid. Run yarn build:agent:instructions and commit the result.'
+            git status --short
+            git diff --stat
+            exit 1
+          fi

content/AGENTS.md

@@ -24,7 +24,11 @@
   examples.
 - Do not hardcode production docs URLs when a relative link or `relref` works.
 - Shared files have no frontmatter. A stub's `source:` must begin `/shared/`.
-  Direct shared edits require touching every source stub; `docs edit` finds them.
+  Identify every consumer before editing shared content. When previewing changes
+  with a running `hugo server`, touch each consuming stub or restart the server
+  because the watcher doesn't rebuild consumers automatically after shared-source
+  changes. Fresh builds, including CI builds and checks, don't require touching
+  consumer stubs. Edit stub content only when its frontmatter needs to change.
 - Use resource-ownership language for import/write/load guidance and write
   recommendations in InfluxData's first-person plural voice.
 
@@ -113,5 +117,5 @@
   frontmatter, malformed shortcodes, h1 in content body
 - **WARNING**: Missing semantic line feeds, skipped heading levels, missing
   `weight`, long CLI options not used
 - **INFO**: Suggestions, code block missing language identifier, opportunities
   to use shared content

helper-scripts/build-agent-instructions.js

@@ -8,6 +8,7 @@ import path from 'path';
 import process from 'process';
 import matter from 'gray-matter';
 import yaml from 'js-yaml';
+import { execFileSync } from 'child_process';
 import { pathToFileURL } from 'url';
 
 export {
@@ -47,20 +48,36 @@ const SCOPED_AGENTS = [
   { dir: 'content', title: 'Documentation Content' },
   { dir: 'layouts', title: 'Hugo Layouts and Shortcodes' },
 ];
+const GENERATED_PATHS = [
+  'PLATFORM_REFERENCE.md',
+  '.github/instructions',
+  '.claude/rules',
+  '.claude/skills',
+  ...SCOPED_AGENTS.map(({ dir }) => `${dir}/AGENTS.md`),
+];
 
 if (import.meta.url === pathToFileURL(process.argv[1]).href) {
   (async () => {
     try {
       await buildPlatformReference();
       await buildAgentInstructionAdapters();
       ensureClaudeSkillsSymlink();
+      if (process.argv.includes('--stage')) stageGeneratedFiles();
     } catch (error) {
       console.error('Error generating agent instructions:', error);
       process.exitCode = 1;
     }
   })();
 }
 
+function stageGeneratedFiles() {
+  const existingPaths = GENERATED_PATHS.filter((generatedPath) =>
+    fs.existsSync(path.join(PROJECT_ROOT, generatedPath))
+  );
+  execFileSync('git', ['add', '--', ...existingPaths], { cwd: PROJECT_ROOT });
+  console.log('✅ Staged generated agent instruction files');
+}
+
 async function buildAgentInstructionAdapters() {
   const instructions = readCanonicalInstructions();
 

lefthook.yml

@@ -69,13 +69,22 @@ pre-commit:
       glob: "assets/js/*.js"
       run: yarn eslint {staged_files}
       fail_text: "Debug helpers found! Remove debug imports and calls before committing."
+    # Formats instruction sources before building so adapters match the
+    # committed sources; lint-markdown-instructions excludes them to avoid a
+    # parallel write. --stage adds the generated adapters to the commit.
     build-agent-instructions:
       glob:
         - "AGENTS.md"
-        - ".agents/instructions/**/*.md"
+        - ".agents/instructions/*.md"
         - ".agents/skills/**/SKILL.md"
         - "data/products.yml"
-      run: yarn build:agent:instructions
+      run: |
+        sources=$(echo '{staged_files}' | tr ' ' '\n' | grep '^\.agents/instructions/' | tr '\n' ' ' | sed 's/ $//')
+        if [ -n "$sources" ]; then
+          .ci/remark/remark.sh $sources --output --quiet || \
+            echo "⚠️  Remark found formatting issues in instruction sources. Automatic formatting applied."
+        fi
+        yarn build:agent:instructions --stage
       stage_fixed: true
     # Auto-fix markdown formatting for instruction and README files (like prettier).
     # The wrapper at .ci/remark/remark.sh runs the local Node install when present
@@ -92,6 +101,8 @@ pre-commit:
         - "assets/AGENTS.md"
         - "content/AGENTS.md"
         - "layouts/AGENTS.md"
+      exclude:
+        - ".agents/instructions/*.md"
       run: |
         # Shortcode .md files contain Hugo template syntax that remark-lint would
         # escape, so filter content/ and layouts/ paths before running remark.
@@ -214,10 +225,10 @@ pre-push:
       tags: lint
       glob:
         - "AGENTS.md"
-        - ".agents/instructions/**/*.md"
+        - ".agents/instructions/*.md"
         - ".agents/skills/**/SKILL.md"
-        - ".github/instructions/**/*.md"
-        - ".claude/rules/**/*.md"
+        - ".github/instructions/*.md"
+        - ".claude/rules/*.md"
         - "api-docs/AGENTS.md"
         - "assets/AGENTS.md"
         - "content/AGENTS.md"