Skip to main content

Superbuild integration plan

How to introduce tools/ai-rules/ (submodule: ai-workflows/superbuild-workflow) into a legacy consuming superbuild and roll out shared workflow policy without silent divergence.

What belongs where​

ConcernLocation
Shared migration policy and methodologytools/ai-rules/docs/ (this repo)
Workspace inventory, per-project status, parity logsConsumer docs/migration/
Local build commands, preset names, profile pathsConsumer root AGENTS.md
Local migration exceptionsConsumer AGENTS.md + .cursor/rules/90-*-local.mdc
Product CMake, Conan, presetsConsumer repo root and src/

Do not copy migration docs out of the submodule and edit them locally as the primary policy path.

Phase 1: Submodule introduction​

Add submodule​

cd <superbuild-root>
git submodule add ssh://git@gitlab-ai/libesys/ai-workflows/superbuild-workflow.git tools/ai-rules
git submodule update --init --recursive

Pin to a tested commit on release branches; document revision in consumer AGENTS.md.

Establish consumer AGENTS.md​

From templates/repo-AGENTS.template.md:

  • Point to tools/ai-rules/AGENTS.md
  • Document local preset names and Conan profiles
  • Add Migration section linking to local docs/migration/ and shared tools/ai-rules/docs/legacy-superbuild-migration.md

Materialize Cursor rules​

Use templates/setup-dev.template.sh pattern:

# Copy or symlink shared adapters
tools/ai-rules/cursor/rules/*.mdc  →  .cursor/rules/

Add local overlay for migration status pointers if needed (do not duplicate full migration spec).

CI and clone discipline​

Ensure CI and developer docs use:

git clone --recursive <url>
# or
git submodule update --init --recursive
Phase 0 assessment (consumer docs/migration/)
        ↓
Phase 1 submodule + AGENTS.md + Cursor materialization
        ↓
Phase 2–3 per-project CMake (see legacy-superbuild-migration.md)
        ↓
Phase 4 Conan (workspace)
        ↓
Phase 5 presets unified
        ↓
Phase 6 validation; retire .vcxproj
        ↓
Bump tools/ai-rules when shared policy evolves

Submodule can land in Phase 1 before CMake refactors complete. Shared policy guides execution; it does not require a finished migration.

Updating shared workflow during migration​

When migration reveals a gap in shared policy:

  1. Propose change in ai-workflows/superbuild-workflow (upstream)
  2. Merge and tag/commit
  3. Bump consumer submodule pointer
  4. Re-materialize .cursor/rules/ if adapters changed
  5. Continue migration with updated policy

Never accumulate permanent edits inside tools/ai-rules/ in the consumer without upstreaming.

Governance during migration​

ActivityRule
Per-project migration commitsSmall, scoped, in src/<project> or superbuild root
Migration status updatesConsumer docs/migration/projects/<name>.md
Shared methodology changeUpstream superbuild-workflow first
Local exception (e.g. one project stays VS-only temporarily)Document in consumer AGENTS.md with exit date
Submodule pinRecord in consumer commit message: chore: bump ai-rules to <sha>

Team responsibilities​

RoleResponsibility
Workflow maintainerssuperbuild-workflow docs, templates, adapters
Superbuild integratorsSubmodule pin, presets, Conan workspace, CI
Project ownersPer-project CMake migration, parity validation
All developersUse presets/Conan; stop editing .vcxproj for migrated projects

Communication checklist​

When submodule is introduced, announce:

  • Path: tools/ai-rules/
  • Required reading: AGENTS.md, docs/legacy-superbuild-migration.md
  • Local migration tracker: docs/migration/
  • Preset commands (once available)
  • Rule: shared policy changes go upstream

Exit criteria (workflow integration complete)​

  • tools/ai-rules/ submodule present and pinned
  • Root AGENTS.md references shared policy and local migration docs
  • Cursor shared rules materialized; local overlay documented if any
  • CI initializes submodules
  • Team knows bump process for tools/ai-rules/

This is independent of build migration complete (Phase 6) — integration can finish early in the program.