Skip to main content

Architecture

This document describes the layered model for shared superbuild workflow policy, how repositories relate, and how humans and AI agents consume the same canonical content.

Layered model​

┌─────────────────────────────────────────────────────────────┐
│  Canonical shared workflow (this repo)                      │
│  GitLab: ai-workflows/superbuild-workflow                   │
│  AGENTS.md + docs/ + templates/ + cursor/rules/ (adapters)  │
└───────────────────────────┬─────────────────────────────────┘
                            │ Git submodule
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Consuming superbuild repository                            │
│  CMake superbuild, src/, libs/, product policy              │
│  Mount: tools/ai-rules/                                     │
│  Root AGENTS.md (local + pointers to shared policy)         │
└───────────────────────────┬─────────────────────────────────┘
                            │ materialize / symlink
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Local tool adapters (per consuming repo)                   │
│  e.g. .cursor/rules/ — shared adapters + local overlays     │
└─────────────────────────────────────────────────────────────┘

Layer 1: Canonical shared workflow repository​

This repository holds portable policy: Markdown documentation, AGENTS.md, governance, rationale, and thin tool adapters. It is versioned independently and consumed by reference (submodule), not by copy-paste.

Responsibilities:

  • Define superbuild workspace conventions
  • Define CMake/Conan policy at the workflow level
  • Define how AI tools should interpret the workspace
  • Evolve shared policy with review and clear history

Layer 2: Consuming superbuild repository​

Each product or program workspace is its own Git repository (or meta-repo) with:

  • A CMake superbuild root that coordinates builds
  • First-party repositories under src/
  • Non-Conan third-party or patched code under libs/ when required
  • Submodule mount of this repo at tools/ai-rules/
  • A root AGENTS.md describing local architecture, contacts, and documented exceptions

The consuming repo owns product-specific build graphs, versioning, and release. It does not own shared workflow policy.

Layer 3: Local tool adapters​

Tools such as Cursor read project-local rule files (e.g. .cursor/rules/*.mdc). Those files should be:

  • Materialized from tools/ai-rules/cursor/rules/ (copy or symlink), and/or
  • Extended with local overlay rules for repo-specific exceptions

Adapters are not authoritative. They summarize and direct agents to tools/ai-rules/AGENTS.md and docs/.

Remote name vs local mount path​

ContextPathMeaning
GitLab / remoteai-workflows/superbuild-workflowRepository identity and purpose
Consuming workspacetools/ai-rules/Where shared policy lives in the tree

The remote name answers what the repository is. The local path answers where it is used in a superbuild workspace (under tools/, alongside other workflow tooling). Agents and humans should treat tools/ai-rules/ as the local alias for this repository's content.

Human and AI dual use​

The same files serve:

  • Humans reading architecture, rationale, and governance to understand intent and boundaries
  • AI agents using AGENTS.md and docs as instructions and context for edits

Imperative rules alone are insufficient. Rationale and governance documents explain why policy exists so agents and developers do not optimize locally against global goals (e.g. silently forking rules, bypassing Conan, or editing submodule content in place).

Data flow for policy changes​

  1. Problem or improvement identified (any consumer or here)
  2. Change implemented in this repository with doc updates
  3. Tagged or committed revision consumed via submodule bump
  4. Consumers materialize updated adapters; local overlays unchanged unless exception docs need updates

See workflow.md and governance.md.