eai-supmig 0.2.1

Contract-first migration assistant for legacy Google-repo superbuild workspaces

superbuild-workflow

Authoritative shared workflow repository for superbuild-style software workspaces.

GitLab path: ai-workflows/superbuild-workflow Local mount in consuming repos: tools/ai-rules/

This repository is not a product superbuild. It defines how superbuild workspaces are structured, built, governed, and assisted by AI tools. Consuming repositories coordinate multiple Git repositories under a CMake/Conan superbuild and mount this repo as a submodule for shared policy.

What this is

• Portable workflow documentation (Markdown, AGENTS.md)
• Shared AI guidance for humans and coding agents
• Rationale and governance for how shared policy evolves
• Cursor adapter rules (thin wrappers over canonical docs)
• Templates for bootstrapping consuming repositories
• Migration assistant CLI (eai-supmig) — contract-first prep for legacy Google-repo superbuilds

Migration assistant (eai-supmig)

Install and run from a legacy superbuild workspace (recommended order — see docs/migration-assistant.md for the read-only alternative):

pip install eai-supmig
# or from this clone:
pip install -e ".[dev]"
eai-supmig bootstrap --with-ai-rules --with-cursor --yes
eai-supmig assess
eai-supmig plan
eai-supmig prompt
eai-supmig doctor

Module invocation: python -m eai_supmig assess

See docs/migration-assistant.md and docs/package-publishing.md.

What this is not

• A consuming product superbuild or application codebase
• A replacement for a consuming repo's CMake superbuild
• The sole source of truth for Cursor-specific rules (adapters only)
• A place to fork shared policy silently from a consumer

Architectural principle

Layer	Role
This repo (tools/ai-rules/ in consumers)	Canonical shared workflow policy
Consuming superbuild repo	Product workspace, build orchestration, local exceptions
Local tool adapters (e.g. .cursor/rules/)	Materialized or symlinked rules; overlays only

Plain Markdown and AGENTS.md are the long-term authoritative content. Cursor .mdc files in cursor/rules/ are adapters, not the primary source of truth.

Documentation portal

Published documentation is mirrored to ai-workflows/docs-portal via GitLab downstream pipelines. Edit docs here first; see docs/portal-integration.md and docs/workflow-manifest.yaml.

Repository layout

superbuild-workflow/
├── README.md                 # This file
├── AGENTS.md                 # Agent-oriented entry point (authoritative)
├── pyproject.toml            # Python package (eai-supmig)
├── src/eai_supmig/           # Migration assistant implementation
├── tests/                    # Unit tests
├── docs/                     # Portable workflow documentation
│   ├── architecture.md
│   ├── rationale.md
│   ├── workflow.md
│   ├── governance.md
│   ├── cursor-integration.md
│   ├── alternative-tool-integration.md
│   ├── repository-layout.md
│   ├── cmake-conan-policy.md
│   └── superbuild-philosophy.md
├── cursor/rules/             # Shared Cursor adapter rule sources
├── .cursor/rules/            # Governance rules for this repo itself
└── templates/                # Templates for consuming repos

Consuming repositories

A typical superbuild workspace:

1. Adds this repo as a Git submodule at tools/ai-rules/
2. Maintains a root AGENTS.md that references shared policy and documents local exceptions
3. Materializes Cursor rules from tools/ai-rules/cursor/rules/ into .cursor/rules/ (copy or symlink)
4. Keeps repo-specific overlays in local .cursor/rules/ without changing shared policy here

See docs/repository-layout.md and templates/ for details.

Getting started

As a maintainer of this repo

1. Clone and run ./scripts/setup-dev.sh (installs pre-commit + commit-msg gitlint)
2. Check out develop for day-to-day work — see docs/development-workflow.md
3. Read AGENTS.md and docs/governance.md
4. Use docs/commit-messages.md for commit format
5. Propose shared workflow changes here first; update docs in the same change set
6. Fast-forward master from develop when CI is green (or after review if CI is not yet configured)
7. Use .cursor/rules/ when editing with Cursor in this repository

As a consumer

1. Add the submodule:

   git submodule add <gitlab-url>/ai-workflows/superbuild-workflow.git tools/ai-rules
   

2. Copy or adapt templates/repo-AGENTS.template.md to your root AGENTS.md

3. Run or adapt templates/setup-dev.template.sh to materialize Cursor rules and initialize submodules

4. Point agents and developers at tools/ai-rules/AGENTS.md and relevant docs/

How to update shared workflow

1. Change policy here first — never treat a consuming repo's local copy as the source of truth
2. Keep changes coherent — one logical change per commit; update rationale/governance docs when semantics change
3. Release via submodule — consumers update with git submodule update --remote tools/ai-rules (or pin to a specific commit)
4. Document local exceptions — in the consumer's root AGENTS.md and local overlay rules, not by forking shared files

See docs/workflow.md for the full change and rollout process.

Documentation index

Document	Purpose
architecture.md	Layered model, remote vs local paths
rationale.md	Why centralized shared workflow exists
workflow.md	How changes flow from discovery to rollout
governance.md	What belongs here vs in consumers
cursor-integration.md	Cursor adapter usage
alternative-tool-integration.md	Non-Cursor AI tools
repository-layout.md	Expected consuming repo layout
cmake-conan-policy.md	Build and dependency policy
superbuild-philosophy.md	Multi-repo coordination model
legacy-superbuild-migration.md	Phased migration from legacy CMake / .vcxproj
legacy-superbuild-assessment.md	Pre-migration inventory
visual-studio-to-cmake-mapping.md	VS project → CMake target mapping
conan-cmake-rollout.md	Incremental Conan and presets
superbuild-integration-plan.md	tools/ai-rules/ submodule rollout
development-workflow.md	Branches, pre-commit, ff-merge to master
commit-messages.md	Conventional Commits (gitlint)
commit-checklist.md	Pre-commit checklist
migration-assistant.md	eai-supmig CLI for legacy superbuild prep
package-publishing.md	PyPI / GitLab package CI

License

This repository is licensed under the MIT License. Shared workflow content may be used in consuming superbuild workspaces via the tools/ai-rules/ submodule.