Skip to main content

Multi-root development (migration + upstream)

Develop superbuild-workflow while working on a legacy superbuild migration in one Cursor window. Both trees are visible to you and to AI agents.

Workspace file​

Open this file in Cursor (File → Open Workspace from File…):

ai-workflows/esysrepo-migration.code-workspace
Folder in sidebarPathRole
esysrepo-dev (migration)libesys/esysrepo_devConsumer superbuild under migration (manifest, src/, .migration/, docs/migration/)
superbuild-workflow (upstream)ai-workflows/superbuild-workflowPolicy docs, eai-supmig source, CI, release tooling

Paths are relative to the workspace file location under ai-workflows/. Adjust the esysrepo-dev entry if your consumer checkout lives elsewhere.

Why two roots?​

  • tools/ai-rules/ in the consumer is a pinned checkout (submodule or manual clone) for builds and team rollout.
  • superbuild-workflow is the editable upstream where you commit policy and CLI changes.

A single-folder session only shows one side. Multi-root gives agents context for both “what we’re migrating” and “what the tool/policy says”.

Daily workflow​

  1. Open esysrepo-migration.code-workspace.

  2. Edit superbuild-workflow (upstream) on develop (docs, src/eai_supmig/, tests).

  3. Run tests in upstream: pytest -q, ruff check src tests.

  4. Try commands against the consumer root (esysrepo-dev (migration)):

    cd <esysrepo-dev>
    pip install -e "<path-to-upstream-superbuild-workflow>[dev]"
    eai-supmig doctor --workspace .

  5. When upstream is ready: push superbuild-workflow, ff-merge master, tag if releasing.

  6. Bump tools/ai-rules/ in the consumer to the new revision (submodule pointer or re-clone).

Do not treat long-lived edits under tools/ai-rules/ as upstream — commit in superbuild-workflow (upstream) only.

Agent context​

In this workspace, agents should:

  1. Read esysrepo-dev/AGENTS.md and .migration/ for local migration state.
  2. Read superbuild-workflow/AGENTS.md and docs/legacy-superbuild-migration.md for shared policy.
  3. Prefer one bounded migration step in the consumer; prefer upstream commits for methodology and eai-supmig fixes.

Optional: live tools/ai-rules/ during heavy upstream work​

Normally keep tools/ai-rules/ as a normal git checkout. For intense parallel work you can temporarily junction it to your upstream clone (Windows example — backup first):

# From esysrepo_dev root; only if tools/ai-rules is not a submodule you need to preserve
Rename-Item tools\ai-rules tools\ai-rules.pinned
New-Item -ItemType Junction -Path tools\ai-rules -Target C:\project\libesesys\ai-workflows\superbuild-workflow

Restore the pinned checkout before sharing the consumer repo with others.