Skip to main content

Migration assistant CLI (eai-supmig)

PyPI package eai-supmig ships a contract-first migration assistant for legacy Google repo superbuilds. Import package: eai_supmig.

V1 scope​

  • Multi-repo workspace with manifest in separate Git repository
  • Manifest parsing with <include> resolution from .repo/manifests/ (or repo manifest when available)
  • First-party under src/, third-party under extlib/, extlibs/, or libs/
  • Conan detection (shallow scan)
  • Build environment matrix capture
  • Migration contract (YAML) + human summaries
  • Optional tools/ai-rules submodule and Cursor rule materialization
  • If tools/ai-rules/ is already a git checkout, bootstrap reuses it (no submodule add)
  • Grounded AI prompt files for follow-on work

Not a full migration engine — preparation and standardization only.

Install​

pip install eai-supmig
# or from this clone:
pip install -e ".[dev]"

Commands​

CommandPurpose
eai-supmig assessInspect workspace; write .migration/migration-contract.yaml and summary
eai-supmig planRead contract; write .migration/migration-plan.md
eai-supmig bootstrapCreate folders, optional submodule, Cursor wrappers, next-steps
eai-supmig resetRemove migration artifacts for a clean restart (tools/ai-rules/ never deleted)
eai-supmig promptWrite prompts/01-analyze-legacy-superbuild.md (+ optional follow-up)
eai-supmig doctorValidate prerequisites and artifacts
eai-supmig workflowShow entry path, gates, Phase 0 sign-off, next milestone
eai-supmig workflow preferencesSet auto-commit at checkpoints (--auto-commit / --no-auto-commit)
eai-supmig workflow sign-offRecord human Phase 0 approval after deliverables are complete
eai-supmig workflow parity-sign-off src/...Record per-project Phase 3 or 6 parity validation in the project status doc
eai-supmig workflow complete <gate>Mark a later gate complete (manual until auto-detection exists)
eai-supmig workflow target [src/...]Show or set the current first-party project (--scaffold creates status doc)
eai-supmig workflow complete-project [gate]Mark project progress for a gate and advance to the next project

eai-supmig --version prints the installed CLI version (--json for machine-readable output).

Module invocation: python -m eai_supmig assess (same subcommands).

All commands accept --workspace PATH (default: current directory) and support --json where useful.

Assess parameters: the first assess run stores --os, --compilers, --build-types, and --manual-deps in .migration/assess-params.yaml and in migration-contract.yaml metadata. Later assess calls with no flags reuse those values and print a reuse note.

Workflow tracking: each CLI run appends to .migration/cli-journal.yaml and refreshes .migration/workflow-state.yaml with entry path (inventory-first vs bootstrap-first), gates complete, Phase 0 deliverables, human sign-off, src migration order, current project, and next milestone (policy Phase N). Use eai-supmig workflow for a full summary; after Phase 0 review run eai-supmig workflow sign-off. During Phase 2+, set the active project with eai-supmig workflow target src/... (scaffolds docs/migration/projects/<slug>.md by default) and record progress with eai-supmig workflow complete-project. For vs_parity and retire_legacy, parity sign-off is tracked separately from Phase 0: check the boxes in the project status doc or run eai-supmig workflow parity-sign-off (--phase 3 for VS parity, --phase 6 for final validation). When every project finishes a gate, that workspace gate is marked complete automatically. The CLI prints a Phase 2+ handoff to @prompts/02-execute-next-step.md after sign-off and target changes. Shown after other commands and in doctor --json under workflow.

When your shell is already inside the consumer workspace, Next: lines omit --workspace (including from subdirectories under a Google repo checkout). After prompt, the CLI prints how to start a new agent chat with @prompts/01-analyze-legacy-superbuild.md as the opening message.

The analyze prompt requires a dual-source dependency graph: CMake and Visual Studio .sln / .vcxproj inputs merged into docs/migration/dependency-graph.md (see legacy-superbuild-assessment.md).

First-party vs third-party: docs/migration/inventory.md (created at bootstrap or prompt) states that extlib/ / libs/ are integrated, not migrated like src/. The analyze prompt and generated plan repeat this scope so Phase 0 output is not misread.

Clean restart: eai-supmig reset deletes .migration/, prompts/, and docs/migration/ (plus materialized Cursor adapter rules). It never removes tools/ai-rules/ — including a manual git clone used for upstream development. Use eai-supmig reset --dry-run first, then re-run assess/plan/prompt or bootstrap. Only the ## Migration order section of inventory.md defines execution order; manifest listing tables are not migration sequence.

Version control​

Commit migration artifacts at checkpoints so multi-day work stays consistent across machines and agents. After most commands, eai-supmig prints a Commit checkpoint section when git has pending changes.

What to commit​

PathCommit?When
prompts/YesAfter eai-supmig prompt — freezes handoff text across machines
docs/migration/YesAfter Phase 0 deliverables; again after sign-off and per-project updates
Bootstrap integration (AGENTS.md, .gitmodules, .cursor/rules/)YesAfter bootstrap when adopting the workflow
src/ and root build filesYesSmall scoped commits per project gate
.migration/OptionalRegeneratable; commit for audit if your team wants shared workflow state

Do not commit tools/ai-rules/ source edits in the consumer — upstream policy changes belong in superbuild-workflow.

Auto-commit preference​

Before assess, plan, bootstrap, prompt, or workflow mutations, choose:

eai-supmig workflow preferences --auto-commit      # git commit at checkpoints
eai-supmig workflow preferences --no-auto-commit     # reminders only (default choice)

Mutating commands are blocked until this preference is set (interactive TTY prompts once; use --json CI runs with an explicit workflow preferences step first).

When auto-commit is enabled, the CLI runs conventional commits for checkpoint paths. When disabled, the CLI and .cursor/rules/90-local-migration.mdc remind you (and agents) to commit manually before continuing.

Suggested rhythm​

  1. bootstrap → commit integration scaffolding.
  2. assess → plan → prompt → commit prompts/ and optional .migration/.
  3. Complete Phase 0 in docs/migration/ → commit → workflow sign-off → commit again.
  4. Each Phase 2+ step → commit docs/migration/projects/<slug>.md with related src/ changes.

Tell your agent​

After eai-supmig workflow (or most mutating commands), the CLI prints Next: with the shell command and Tell your agent: with exact copy-paste wording for Cursor chat. Generated prompts/ files and .cursor/rules/90-local-migration.mdc embed the same mapping table.

You tell your agentAgent must run
Phase 0 inventory is approved. Run eai-supmig workflow sign-off …eai-supmig workflow sign-off
Run eai-supmig workflow and summarize the migration status.eai-supmig workflow
Set the active migration project to src/foo. Run eai-supmig workflow target src/foo.eai-supmig workflow target src/foo
VS/CMake parity for src/foo is validated. Run eai-supmig workflow parity-sign-off src/foo --phase 3.parity sign-off Phase 3
Final parity validation for src/foo is complete. Run … --phase 6.parity sign-off Phase 6
Mark src/foo complete for the current gate. Run eai-supmig workflow complete-project.eai-supmig workflow complete-project
Run eai-supmig assess / plan / prompt / doctor for this workspace.matching subcommand

Casual phrases (sign off, next step, set target, yes, move on, next library) should map to the row above — agents must not hand-edit .migration/workflow-state.yaml.

After you finish a project for the active gate, yes / move on / next target means the agent runs eai-supmig workflow complete-project in the shell before starting the next src/ library. Do not skip that step because the user wants to continue.

Command order​

Two supported entry paths. doctor is always last — it expects contract, plan, prompts, and (optionally) tools/ai-rules/.

Attach shared policy and local migration folders before inventory. Phase 0 assessment is easier when tools/ai-rules/docs/legacy-superbuild-assessment.md, docs/migration/, and Cursor adapters are already on disk for humans and AI.

bootstrap does not require a prior assess; it only warns if the contract is missing.

cd /path/to/legacy-superbuild
eai-supmig bootstrap --with-ai-rules --with-cursor --yes
eai-supmig assess --os linux,windows,macos --compilers gcc,msvc,clang
eai-supmig plan
eai-supmig prompt
eai-supmig doctor

Then complete Phase 0 in docs/migration/ (dependency graph, leaf-first migration order) before changing build files. See legacy-superbuild-migration.md.

Alternative: read-only inspection first​

Run assess (and optionally plan) before bootstrap when you want a minimal, read-only first pass: only .migration/ artifacts from manifest/Conan scans, no submodule, no new AGENTS.md, no Cursor rule copies. Useful for:

  • Evaluating an unfamiliar workspace before committing workflow integration
  • CI or auditor runs that must not modify submodules or IDE config
  • Producing a contract YAML to review in isolation
cd /path/to/legacy-superbuild
eai-supmig assess --os linux,windows,macos --compilers gcc,msvc,clang
eai-supmig plan
eai-supmig bootstrap --with-ai-rules --with-cursor --yes
eai-supmig prompt
eai-supmig doctor

After bootstrap, re-run assess if the workspace changed materially (new submodule checkout, new paths).

Policy note​

legacy-superbuild-migration.md describes Phase 0 (inventory) before Phase 1 (submodule bootstrap) as the migration program order. The CLI allows bootstrap first because attaching tools/ai-rules/ supports Phase 0 work; it does not replace inventory or an agreed migration order.

Output layout​

<workspace>/
├── .migration/
│   ├── migration-contract.yaml
│   ├── migration-summary.md
│   ├── migration-plan.md
│   ├── bootstrap-summary.md
│   └── next-steps.md
├── prompts/
│   ├── 01-analyze-legacy-superbuild.md
│   └── 02-execute-next-step.md
├── tools/ai-rules/          # manual clone or optional submodule
└── .cursor/rules/           # optional materialized adapters

Contract schema​

See migration-contract.yaml fields: metadata, manifest inventory, workspace classification, dependency model, build environment matrix, migration intent, open questions, readiness.