Skip to main content

Repository layout

Expected physical layout of a consuming superbuild workspace and responsibilities of each major directory. This repo (superbuild-workflow) defines the convention; product repos implement it.

Consuming superbuild workspace (top level)​

workspace-root/
├── CMakeLists.txt              # Superbuild root — orchestrates subprojects
├── cmake/                      # Shared CMake modules (consumer-owned)
├── conanfile.py / conan/       # Conan workspace recipe and profiles (consumer-owned)
├── CMakePresets.json           # Configure/build/test presets (consumer-owned)
├── AGENTS.md                   # Local agent entry + pointers to tools/ai-rules/
├── src/                        # First-party maintained repositories
├── libs/                       # Third-party or patched deps not from Conan
├── tools/
│   └── ai-rules/               # Submodule: this repository (superbuild-workflow)
├── .cursor/
│   └── rules/                  # Materialized shared adapters + local overlays
├── build/                      # Out-of-tree build (gitignored; typical)
└── ...                         # CI, docs, product-specific tooling

Exact filenames may vary by product, but the roles of src/, libs/, tools/ai-rules/, and .cursor/rules/ are stable.

Directory responsibilities​

Workspace root​

  • Owns superbuild CMake entry point and workspace-wide Conan integration
  • Hosts consumer AGENTS.md (local architecture, exceptions, contacts)
  • Pins tools/ai-rules submodule revision
  • Does not redefine shared workflow policy inline when submodule is present

src/​

First-party software maintained by the organization. Typical patterns:

  • Git submodules per component (src/foo, src/bar)
  • Each component may have its own CMake project added by the superbuild
  • Source of truth for product code lives here or deeper — not in tools/ai-rules/

libs/​

Code that is not pulled via Conan but still built as part of the workspace:

  • Vendored snapshots with local patches
  • Internal forks of third-party libraries
  • Legacy dependencies awaiting Conan migration

Prefer Conan when feasible. Use libs/ deliberately, document rationale in consumer AGENTS.md.

tools/ai-rules/​

Mount point for this repository (ai-workflows/superbuild-workflow).

Contains:

  • AGENTS.md, docs/, templates/, cursor/rules/

Treat as read-only in daily product work. Changes flow upstream to the submodule remote, then roll out via version bump.

.cursor/rules/​

Active Cursor rules for the workspace:

  • Materialized from tools/ai-rules/cursor/rules/
  • Plus local overlays (e.g. 90-project-exceptions.mdc)

Not the canonical store of shared policy — a projection for Cursor's discovery model.

build/ (or preset-defined output dir)​

Out-of-tree build artifacts. Not committed. Consistent across platforms via presets.

This repository's layout (reference)​

superbuild-workflow/          # Remote name; mounted as tools/ai-rules/
├── AGENTS.md
├── README.md
├── docs/
├── cursor/rules/             # Adapter sources for consumers
├── .cursor/rules/            # Governance for editing this repo only
└── templates/

Submodule path convention​

Always mount at tools/ai-rules/ unless a documented organizational exception exists. Consistent paths allow:

  • Shared setup scripts
  • Agent instructions that work across workspaces
  • CI snippets that apply generically

Anti-patterns​

Anti-patternWhy it hurts
Product code in tools/ai-rules/Pollutes shared policy repo
Shared policy only in .cursor/rules/Bypasses review; lost on rematerialize
Random submodule path per productBreaks templates and agent paths
src/ used for vendored upstreamBlurs first-party vs third-party boundaries