Polylith Migrate Orchestrator

Skill: polylith-migrate-orchestrator

🧭 You are in the right place. This is the entry point for migrating a non-Polylith Python project into a Polylith workspace. If you arrived here from a fuzzy match on a sub-skill name (e.g., polylith-migrate-discover, polylith-migrate-extract-to-base), stay here — those sub-skills depend on state and a git safety net that only this orchestrator sets up. Loading them in isolation is undefined behaviour. Execute the phases below in order.

Goal

Define and execute the workflow for migrating a non-Polylith Python project to a Polylith workspace. This skill must be explicitly invoked by a human with the project name/path.

Usage

To migrate a project, load the polylith-migrate-orchestrator skill and provide the project name (the subdirectory under projects/):

Load the `polylith-migrate-orchestrator` skill and migrate `projects/<project-name>`.

💡 How sub-skills are loaded. Each phase points to another skill named polylith-migrate-<phase> (e.g., polylith-migrate-discover, polylith-migrate-extract-to-base). Load each via your skill loader before executing the phase. Do not interleave phases — finish and verify one before starting the next.

Pre-flight

0. User Confirmation

Ask the user to confirm the project path and migration intent before doing anything else:

You are about to migrate `projects/<project-name>` to Polylith. This will refactor
the project into bases and components and move files. Proceed? (yes/no)

If the user declines, abort:

Migration aborted by user.

Phase 0. Safety Net (git checkpoint)

Migration is destructive — files move, directories are deleted, pyproject.tomls are rewritten. Before loading polylith-migrate-discover, establish rollback points:

1. Confirm the working tree is clean:

   git status

   If there are uncommitted changes, ask the user to commit/stash before proceeding. Do not start a migration on top of a dirty tree. (If the repo has no commits yet, create an initial baseline commit so there is a GIT_BASE_SHA to roll back to.)
2. Secret-hygiene precondition (do this before any phase stages files). Later phases stage changes broadly, and the migration creates untracked files mid-flow (e.g. .venv/ from uv sync/poetry install, regenerated lock files). A "clean" tracked tree can still leave untracked secrets (.env*, *.pem, *.key, *_rsa, *service-account*.json, credential files) that a broad stage would commit. Before proceeding:
   • Confirm .gitignore covers .venv/, .env*, and common secret material.
   • Review git status --porcelain for untracked sensitive files; have the user remove, relocate, or ignore them. Do not start until no untracked secret material remains stageable.
3. Create a dedicated migration branch:

   git checkout -b migrate/<project-name>

4. After each completed phase, commit per that phase's ## Commit section. The commit message follows the pattern migrate(<project-name>): phase <N> — <phase-name> so phases can be located in git log later.
   • Stage narrowly. Prefer scoped git add <path> over git add -A, limiting the stage to migration-relevant paths (the bricks/components/bases touched, the project dir, and migration/<project-name>/). Where a phase's ## Commit section still shows git add -A, first run git status --porcelain and exclude anything matching secret patterns (.env*, *.pem, *.key, *_rsa, *service-account*.json, credential files) or build artifacts (.venv/, caches). Never stage a file you have not accounted for.

   git add <scoped paths> && git commit -m "migrate(<project-name>): phase <N> — <phase-name>"

   This gives the user (and the agent) a discrete, named rollback point per phase. If a later phase fails verification, the agent can git reset --hard HEAD~1 to back out exactly one phase without losing earlier progress.

5. Record the branch name and starting commit SHA in migration/<project-name>/state.md (the polylith-migrate-discover skill defines that file).

⚠ Never git reset --hard past the start of the migration branch without explicit user approval — the user's pre-migration work lives there. ⚠ Because phases may stage broadly, a git reset --hard HEAD before a commit also discards untracked work. This is a second reason to stage narrowly (step 4).

Workflow

The table below is the single source of truth for phase order and numbering. Execute phases top to bottom. Verify each phase's Verify section before starting the next, and commit between phases (see Phase 0 step 3). Where a sub-skill's own ## Commit section or description: hardcodes a different phase number, ignore that number — use the # from this table in the commit message.

Main line (always run)

Conditional namespace-shim sub-track (phase 4b)

polylith-migrate-analyze-imports (phase 2) sets a SHIM_STRATEGY in state.md:

• shimless (recommended when imports are submodule-qualified — e.g. from <ns>.<sub> import … — and <ns>/__init__.py exports little or nothing; a top-level re-export shim would resolve nothing there): phase 4 rewrites all references — base internals, entrypoints, infra, and tests — directly to the new namespace. Skip the sub-track below.

• shim (a top-level re-export shim is viable): after phase 4, run this sub-track before phase 5, then continue the main line:

  #	Phase	Skill	Depends on
  4b.i	Generate compatibility shim	polylith-migrate-generate-shim	3, 4
  4b.ii	Detect circular imports	polylith-migrate-detect-circular-imports	4b.i
  4b.iii	Resolve circular imports	polylith-migrate-resolve-circular-imports	4b.ii
  4b.iv	Update test files	polylith-migrate-update-tests	4b.iii

Dependency note (why this is a post-extraction sub-track): the shim re-exports the original namespace from the new base location, so it can only be generated after polylith-migrate-extract-to-base (phase 3) and after the base's own imports point at the new namespace (polylith-migrate-automate-import-updates, phase 4). A shim generated before extraction would re-export from a location that does not exist yet.