Skip to main content

Governance

What belongs in this repository, what belongs in consuming superbuild repos, and how changes are reviewed and recorded.

Source of truth​

ContentAuthoritative location
Shared workflow policyThis repo: AGENTS.md, docs/
Shared Cursor adapter sourcesThis repo: cursor/rules/
Rules for editing this repoThis repo: .cursor/rules/
Product build graph, targets, versionsConsuming superbuild repo
Architecture Decision Records (format)Canonical: a2c-workflow — see adr-conventions.md
Changelog format (CHANGELOG.md)Canonical: a2c-workflow — see changelog-conventions.md
ADR content (decisions)Consumer docs/adr/ per Git repository (superbuild root and each src/ repo)
Repo-specific agent exceptionsConsumer root AGENTS.md, local .cursor/rules/ overlays
Materialized Cursor rules in consumersGenerated from submodule + overlays; not authoritative

If canonical docs and a Cursor adapter disagree, docs win until adapters are fixed here.

What belongs here​

  • Superbuild workspace conventions (src/, libs/, tools/ai-rules/)
  • CMake/Conan workflow policy (not product-specific target lists)
  • AI agent guidance applicable across workspaces
  • Rationale, architecture, governance, workflow process
  • Templates for bootstrapping consumers
  • Thin tool adapters

What belongs in consuming repos​

  • CMake superbuild lists, dependency versions, product options
  • First-party source under src/ (often as nested submodules or subtrees)
  • Vendored or patched third-party code under libs/ when not satisfied via Conan
  • CI job definitions specific to the product
  • docs/adr/ for architecturally significant workspace decisions (format per A2C; ADR-0000 records adoption of superbuild-workflow at tools/ai-rules/)
  • Root CHANGELOG.md (Keep a Changelog; scaffolded by bootstrap) — see changelog-conventions.md
  • Local AGENTS.md sections: team contacts, release process, documented exceptions
  • Local .cursor/rules/ overlays referencing shared policy

What must not happen​

  • Silent edits inside tools/ai-rules/ in a consumer without upstream merge here
  • Duplicating full policy text only in consumer .cursor/rules/ with no submodule
  • Using consumer-specific hacks to "patch" shared templates for one team without documentation
  • Treating Cursor adapters as the only documentation of a policy decision

Change discipline​

Scope​

  • One logical change per commit when possible
  • Avoid drive-by refactors unrelated to the policy change
  • Do not add speculative files, frameworks, or placeholders

Documentation​

When changing semantics of architecture, workflow, governance, build policy, or tool integration:

  • Update the relevant docs/*.md in the same change set
  • Sync README.md and AGENTS.md entry points if user-facing summaries change
  • Update cursor/rules/ adapters if agent-visible behavior changes

Commits and branches​

Use conventional types:

  • feat: new policy or template
  • docs: documentation-only clarification
  • fix: correction of incorrect policy or adapter
  • chore: mechanical changes (hooks, formatting, non-semantic renames)

Body text should state why when not obvious from the diff. Include AI: footer when applicable.

Review expectations​

Reviewers verify:

  • No contradiction across documents
  • Rationale present for non-obvious boundaries
  • Templates still align with docs
  • Consumers can adopt without undeclared breaking layout changes

Submodule consumption rules​

Consumers:

  • Pin tools/ai-rules to a known-good commit for release branches
  • Bump deliberately with commit message noting workflow revision
  • Re-materialize local Cursor adapters after adapter changes

Maintainers of this repo:

  • Avoid force-pushing shared branches consumers track
  • Document breaking changes in merge requests

Editing this repository with AI agents​

Agents must follow .cursor/rules/ in this repo:

  • 00-governance.mdc — authority and commit expectations
  • 10-doc-sync.mdc — documentation coupling
  • 20-change-scope.mdc — minimal diffs

Escalation​

If a consumer team needs a permanent fork of shared policy, that signals either:

  • Missing extension point (add template or overlay pattern here), or
  • Product line divergence that should not share this workflow repo

Resolve by design discussion, not unmarked fork.