Skip to content

AI rules maintenance

This repository uses a governed content pipeline to keep human documentation and AI/editor instructions aligned.

Source-of-truth layers

Layer Path Purpose
Human documentation docs/, README.md Explains the standard for humans
Repo policy .repo-policy.yml in downstream repos Defines the adopted profile, commands, quality gates, release, deploy, and governance settings
Standards AI rule templates ai/rules/*.md Canonical AI/editor source maintained in this standards repo
Downstream AI rule source .rulesync/rules/*.md Canonical AI/editor source after templates are copied into an application repo
Rulesync config rulesync.jsonc Defines generated targets

Rulesync is mandatory for every repository that adopts repo-standards, regardless of implementation language or deployment provider. Node/TypeScript repositories pin Rulesync in their existing devDependencies. Non-Node repositories should use a small private, tooling-only package.json so the Rulesync version is reproducible without changing the application runtime. | Generated agent instructions | AGENTS.md | Generated by Rulesync; universal agent instructions | | Generated Cursor rules | .cursor/rules/*.mdc | Generated by Rulesync | | Generated Antigravity rules | .agents/rules/*.md | Generated by Rulesync | | Generated Antigravity memories | .agents/memories/*.md | Generated by Rulesync when the Antigravity target is enabled |

Operating rule

When a standard changes, update the content at the correct layer:

  1. Update human-facing docs when the change affects how a person understands or applies the standard.
  2. Update ai/rules/*.md when the change affects how coding agents or editors should behave.
  3. Run Rulesync after changing AI rule source.
  4. Commit generated AI/editor outputs only when they are generated outputs in a downstream application repo.
  5. Never hand-edit generated AI/editor outputs as the source of truth.

Core rule: Docs explain the standard. Rulesync rules operationalize the standard for AI agents and editors. Generated AI/editor files are never edited directly.

Change decision guide

Ask this question for every standards PR:

Did this change what a future coding agent should do?

If yes:

  1. Update the relevant human docs.
  2. Update the relevant ai/rules/*.md source file.
  3. Run npx rulesync generate in any downstream repo where generated outputs are committed.
  4. Commit generated outputs in the downstream repo.
  5. Confirm the AI rules workflow passes.

If no:

  1. Update docs only.
  2. Explain in the PR why AI rules did not need to change.

Examples

Change Human docs AI rule source Notes
CI command policy changes docs/concepts.md, CI docs, or profile docs ai/rules/00-org.md or language rule Agent behavior probably changes
Node/TypeScript standards change docs/profiles.md, Node/TypeScript docs ai/rules/10-typescript.md Keep .nvmrc, package manager, and checks guidance aligned
Python standards change docs/profiles.md, Python docs ai/rules/20-python.md Keep Ruff, pytest, coverage, and typechecking guidance aligned
Deployment safety policy changes docs/deployment/*.md ai/rules/00-org.md First migration should preserve deploy behavior
Secret, license, or governance policy changes Governance/security docs ai/rules/00-org.md Agent safety behavior changes
New repo profile added docs/profiles.md, template docs Relevant AI rule file Add detection/profile guidance if applicable
Typo-only docs fix Affected doc only Usually none Explain no AI behavior changed if challenged

Ownership matrix

Area Human docs AI rule source Generated output
General engineering behavior docs/concepts.md, docs/ai-rules-maintenance.md ai/rules/00-org.md AGENTS.md, editor outputs
TypeScript/Node standards docs/profiles.md, Node/CI docs ai/rules/10-typescript.md AGENTS.md, editor outputs
Python standards docs/profiles.md, Python/CI docs ai/rules/20-python.md AGENTS.md, editor outputs
Deployment safety docs/deployment/*.md ai/rules/00-org.md AGENTS.md, editor outputs
Repo policy/profile selection docs/profiles.md, docs/detection.md ai/rules/00-org.md AGENTS.md, editor outputs
Secrets and license behavior Security/governance docs ai/rules/00-org.md AGENTS.md, editor outputs

Generated file policy

Generated AI/editor outputs must not be edited directly as source material.

In downstream repositories, use:

npx rulesync generate

Then review and commit generated outputs.

In this standards repository, ai/rules/*.md are the canonical rule templates. Generated local Rulesync outputs such as AGENTS.md, .cursor/, and .agents/ should not normally be committed here unless the standards repository intentionally adopts itself as a downstream consumer.

Docs / AI rule sync check

The Docs / AI Rule Sync check warns when docs, templates, profiles, or standards files change without corresponding AI rule source changes.

It is warning-only by default. Repos may make it strict after the standard stabilizes.

Run locally:

python3 scripts/check_docs_ai_rule_sync.py --base-ref main

Strict mode (fails when docs change without AI rule source changes):

python3 scripts/check_docs_ai_rule_sync.py --base-ref main --strict

Copy the workflow template from templates/workflows/docs-ai-rule-sync.yml to enable this check in CI.

Pull request expectations

Every standards PR should answer:

  • Did human-facing docs change?
  • Did AI/editor behavior change?
  • If AI/editor behavior changed, which ai/rules/*.md files were updated?
  • If generated outputs changed, were they generated by Rulesync rather than edited directly?
  • If docs changed without AI rule changes, why was no AI rule update needed?

The PR template includes a Standards sync checklist to reinforce these expectations.