Rationale

Why a dedicated, submodule-mounted, documentation-first workflow repository exists for superbuild workspaces.

Problem

Superbuild workspaces combine:

• Multiple Git repositories under one build orchestration root
• CMake as the cross-platform build language
• Conan for dependencies and toolchains
• Increasing use of AI coding agents that need consistent, repository-wide guidance

Without a shared workflow layer, each workspace reinvents directory layout, build conventions, and agent instructions. Drift accumulates. Fixes in one product do not propagate. Agents receive contradictory or missing context.

Why a dedicated Git repository

A separate repository:

• Versions policy independently from product release cadence
• Centralizes review for workflow changes affecting many workspaces
• Provides a single bump point (submodule revision) for rollout
• Separates concerns — product repos ship software; this repo ships workflow

Embedding workflow docs only inside one product repo makes other workspaces second-class. A monolithic "rules" folder copied into each repo has no authoritative upstream.

Why Git submodule at tools/ai-rules/

Submodules give:

• Exact revision pinning per consumer (stability) or remote tracking (rapid uptake)
• Physical presence in the tree so agents and scripts resolve paths without network calls
• Clear boundary — tools/ai-rules/ is obviously shared infrastructure, not product src/

Alternatives considered:

Approach	Weakness
Copy rules into each repo	No upstream; silent forks; merge pain
npm/pip-style package of markdown	Extra tooling; agents expect tree paths
GitLab wiki / external docs	Not in repo context; agents miss offline/local copy
User-global IDE settings only	Not team-visible; not reviewable; not portable across machines

Submodule at a fixed path is a pragmatic balance for C++ superbuild teams already using Git submodules for src/ components.

Why Markdown + AGENTS.md, not only Cursor rules

Cursor .mdc rules are:

• Tool-specific format and discovery mechanics
• Easy to overgrow into duplicated policy text
• Poor long-term archive for human architects

Portable Markdown:

• Readable in GitLab, editors, and diff reviews without Cursor
• Consumable by Claude Code, Copilot instructions, custom agents, and future tools
• Supports narrative rationale, tables, and diagrams

Cursor rules in cursor/rules/ are adapters: short, composable, pointing to canonical docs.

Why changes must be made here first

If shared policy is edited only in a consuming repo's materialized copy:

• The submodule pointer still points at old upstream content
• The next submodule update overwrites local edits
• Other consumers never receive the fix
• History blames the wrong repository

Central changes preserve audit trail and enable intentional rollout.

Local overlays vs silent forks

Consuming repos legitimately need exceptions (legacy module, platform-specific fork, experimental target). Those belong in:

• Documented sections of the consumer's root AGENTS.md
• Local .cursor/rules/ overlay files (see templates/project-local-rule.template.mdc)

They do not belong as unmarked edits inside tools/ai-rules/ without upstreaming.

Why governance and rationale matter

Agents excel at local optimization. Without explicit why, they may:

• Add Visual Studio project files when policy says CMake-only
• Patch submodule files instead of opening an upstream change
• Expand scope with speculative abstractions

Rationale documents constrain interpretation. Governance documents define ownership. Together they reduce harmful "helpful" changes.

Why multi-tool support

Teams use Cursor, CLI agents, GitLab Duo, and other tools concurrently. Tool-agnostic core docs avoid lock-in and duplicated maintenance per vendor.

Summary

This repository exists because shared superbuild workflow policy is a product of its own — it deserves version control, review, portable documentation, and thin per-tool adapters, consumed deliberately via submodule rather than copied or forked.