Skip to main content

Workflow

How shared workflow policy is changed, reviewed, rolled out to consuming superbuild repositories, and how local exceptions are handled.

Principles​

  1. Upstream first — shared policy changes land in ai-workflows/superbuild-workflow before consumers rely on them
  2. Docs with semantics — behavior or boundary changes include documentation updates in the same change set
  3. Submodule as delivery — consumers take revisions via tools/ai-rules/ submodule pointer
  4. Explicit exceptions — local deviations are documented in the consumer, not hidden in forked shared files

Change lifecycle​

Discover → Propose (here) → Review → Merge → Tag/commit → Consumer submodule bump → Verify

1. Discovery​

Sources:

  • Maintainer editing this repo
  • Developer hitting friction in a consuming workspace
  • AI agent noticing inconsistency between docs and practice
  • Build/CI failure traced to ambiguous policy

When discovery happens in a consumer, treat it as input to this repository unless the issue is purely local (e.g. one product's proprietary module layout).

2. Implement in this repository​

  1. Identify affected docs and adapters (cursor/rules/, templates)
  2. Make a focused change set
  3. Update AGENTS.md / README.md if entry-point semantics change
  4. Commit with a clear message (see governance.md)

3. Review​

Reviewers check:

4. Rollout to consumers​

Consumers update the submodule:

cd tools/ai-rules
git fetch origin
git checkout <desired-commit-or-tag>
cd ../..
git add tools/ai-rules
git commit -m "chore: bump ai-rules workflow to <revision>"

Then re-run or verify setup steps (e.g. materialize Cursor rules from templates/setup-dev.template.sh pattern).

Pinning: Production branches often pin to a tested commit. Integration branches may track main more aggressively.

5. Verification​

After bump:

  • Confirm tools/ai-rules/AGENTS.md revision matches expectation
  • Re-materialize .cursor/rules/ if adapter files changed
  • Run representative configure/build on Windows, Linux, and/or macOS as appropriate
  • Update consumer AGENTS.md only if local exception docs need adjustment

Fixing a problem found in one consumer​

SituationAction
Shared policy was wrong or unclearFix docs/rules here; bump submodule in all consumers that need it
Consumer violated shared policyFix consumer; optionally clarify docs here if agents keep misreading
Legitimate one-off exceptionDocument in consumer AGENTS.md + local overlay; consider whether policy should generalize

Never "fix" shared semantics only in .cursor/rules/ of a consumer without upstreaming.

Local exception handling​

Exceptions are allowed when:

  • The exception is documented (what, why, scope, owner)
  • The exception lives in local overlay rules or consumer AGENTS.md
  • Shared files under tools/ai-rules/ remain unmodified (read-only checkout discipline)

If an exception becomes common across workspaces, promote it to shared policy here and remove redundant local overlays.

Emergency/temporary divergence​

Sometimes a consumer must pin an old submodule revision while others advance. That is normal. Document the pin reason and target date for realignment in the consumer's AGENTS.md.

Do not maintain a long-lived git fork of this repository inside a consumer.

Communication​

For team-visible changes:

  • Note summary in merge request description
  • Mention submodule bump requirement for consumers
  • Call out breaking changes to adapter filenames or required directory layout