[jstirnaman]

Closes #7863.

Related: #7877, #7892, and #7893. This PR partly addresses #7094 by checking generated agent instructions in CI instead of relying on local hooks.

What changed

• build-agent-instructions.js --stage now runs git add on the files the build generates: PLATFORM_REFERENCE.md, .github/instructions/, .claude/rules/, .claude/skills, and the scoped AGENTS.md files.

• The pre-commit build-agent-instructions hook:

  • formats staged instruction sources first
  • builds the adapters
  • stages them with --stage

  lint-markdown-instructions now excludes .agents/instructions/*.md, so two parallel hooks no longer write the same file.

• The hook globs now match files directly under .agents/instructions/, .github/instructions/, and .claude/rules/.

• A new Agent Instructions workflow runs yarn validate:agent-instructions on pull requests that change agent sources, adapters, or the build scripts.

• A separate commit regenerates the stale content adapters on master, so the new check passes. This completes Clarify shared-content stub touches: development watcher versus fresh builds and CI #7863: fix(agents): distinguish shared-content previews from fresh builds #7877 updated the canonical instructions, docs, and skills but not the generated adapters. chore(test): lint Cypress specs with Cypress globals #7892 and feat(agents): add comment-refactoring skill and on-demand comment lint #7893 carry the same change, so they merge cleanly in any order.

Why

Three problems let #7877 merge with stale adapters:

1. The hook never ran. Lefthook's **/*.md requires a subfolder (see the note at the top of lefthook.yml). So .agents/instructions/**/*.md never matched .agents/instructions/content.md, and the build hook was skipped.
2. The output wasn't committed. stage_fixed re-stages only the files the hook matched, not the files it generates. When the hook did run, the regenerated adapters stayed unstaged.
3. A race with the formatter. Pre-commit runs in parallel. The Markdown formatter could rewrite a source after the build had read it, so the committed adapters wouldn't match the committed source.

Hooks can also be skipped with --no-verify, by web edits, or on machines without them installed, so CI now checks the result.

I chose a failing check over having CI regenerate and commit:

• Bot pushes made with the default workflow token don't trigger CI, so the new head would go untested.
• The bot can't push to branches from forks.
• Authors would have to pull a bot commit before their next push.

Impact

• Committing an instruction change also commits its formatted source and the matching adapters.
• Pull requests with stale or invalid adapters fail the new check, with the fix command in the error message.

Verification

• Hook, before: on a throwaway branch, committing an edit to .agents/instructions/content.md reported build-agent-instructions (skip) no matching staged files and committed only the source.
• Hook, after: the same unformatted edit committed the formatted source and all three content adapters. Nothing was left unstaged, and yarn validate:agent-instructions passed.
• CI check: yarn validate:agent-instructions exits 1 on this branch before the regeneration commit and passes after it.
• npx lefthook validate and yarn test:agent-instruction-limits pass. ESLint reports no errors on the build script.

Checklist

• Signed the InfluxData CLA (if necessary)
• Rebased/mergeable
• Local build passes (npx hugo --quiet)

[github-actions]

Vale Style Check Results

Metric	Count
Errors	0
Warnings	1

Warnings (1)

File	Line	Rule	Message
content/AGENTS.md	120	Google.Colons	': S' should be in lowercase.

---

✅ Check passed