Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (43 loc) · 2.57 KB

AGENTS.md

File metadata and controls

52 lines (43 loc) · 2.57 KB

Agent Instructions

Review guidelines

Respect documented author intent and check for companion PRs.

  • Read the PR body before the diff. If it has sections like "Design decisions", "Companion PRs", "Cross-repo", or "Intent", treat them as the author's binding statement of design — constraints, not code to second-guess. Do not raise a finding that would contradict a documented choice.
  • Assume work often spans multiple repos in this org. "Missing caller", "dead code", and "unused export" findings are often wrong because the caller lives in a companion PR. Before flagging dead or missing code, check whether the PR description references companion PRs in other repos.
  • When author intent is unclear, ask a question rather than request a change.

Translation safety

Localized content under i18n/** is generated by the translation pipeline and must not be rewritten by AI reviewers or generic fixer agents.

  • Do not edit i18n/** translation content unless the user explicitly asks for a translation cleanup in this repository.
  • Do not "complete coverage", regenerate localized docs, or replace translated prose as part of review feedback or CI-fix work.
  • If a translation issue is found, report the exact file/line and recommend the translation pipeline or node scripts/check-translation-safety.js.
  • Never commit visible locale markers such as DE:, HI:, AR:, or placeholder prefixes such as Ubersetzt -, Translated -, مترجم -, or अनुवादित -.

Frontmatter quoting policy

The MDX frontmatter description: value is ALWAYS double-quoted (description: "...") — in every locale and in the English source. This is an enforced, deterministic policy, not a style preference, and it applies to everyone who generates or edits docs (the translation pipeline, AI reviewers, and CI-fix agents alike).

  • Never remove the quotes from a description, and never "simplify" description: "..." to an unquoted value. Many descriptions contain a colon; an unquoted colon makes YAML read the value as a mapping pair, which breaks the frontmatter and fails the production build.
  • When writing or translating frontmatter, keep description double-quoted and escape any internal " as \".
  • The canonical form is produced by node scripts/validate-frontmatter.js --fix and enforced in CI by node scripts/validate-frontmatter.js --check --changed. Do not hand-roll a different quoting style — run the fixer.
  • Do not raise a review finding asking to drop these quotes; it would contradict this policy and the CI gate.