polylith-cli 1.48.0__tar.gz → 1.48.1__tar.gz

{polylith_cli-1.48.0 → polylith_cli-1.48.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polylith-cli
-Version: 1.48.0
+Version: 1.48.1
 Summary: Python tooling support for the Polylith Architecture
 License: MIT
 Author: David Vujic

{polylith_cli-1.48.0 → polylith_cli-1.48.1}/polylith_cli/.agents/skills/polylith/README.md

@@ -8,7 +8,7 @@
 Two kinds of skill live under this directory; the distinction matters when picking an entry point:
 
 - **Atomic skills (`polylith-*`).** Each maps to one `poly` CLI command (or one focused concept). Safe to load in isolation; individually composable. These cover everyday Polylith workflows — creating bricks, syncing, checking, inspecting, and so on.
-- **Orchestrated skill set (`migrate-project/migrate-*`).** A multi-phase workflow with shared state (`migration/<PROJECT>/state.md`) and a git safety net. **Never load an individual `migrate-*` skill directly** — always load `migrate-orchestrator` and let it drive the phases in order. See [`migrate-project/README.md`](./migrate-project/README.md). This is an advanced, explicit-opt-in workflow used for migrating a **non-Polylith** project into a Polylith workspace, **not** part of daily Polylith use.
+- **Orchestrated skill set (`migrate-project/polylith-migrate-*`).** A multi-phase workflow with shared state (`migration/<PROJECT>/state.md`) and a git safety net. **Never load an individual `polylith-migrate-*` skill directly** — always load `polylith-migrate-orchestrator` and let it drive the phases in order. See [`migrate-project/README.md`](./migrate-project/README.md). This is an advanced, explicit-opt-in workflow used for migrating a **non-Polylith** project into a Polylith workspace, **not** part of daily Polylith use.
 
 ## Available Skills (daily Polylith workflows)
 
@@ -31,4 +31,4 @@ Two kinds of skill live under this directory; the distinction matters when picki
 
 ## Advanced workflow
 
-For migrating an existing **non-Polylith** Python project into a Polylith workspace, see [`migrate-project/README.md`](./migrate-project/README.md). This is a destructive, multi-phase, explicit-opt-in workflow — start with the `migrate-orchestrator` skill, not any individual `migrate-*` sub-skill.
+For migrating an existing **non-Polylith** Python project into a Polylith workspace, see [`migrate-project/README.md`](./migrate-project/README.md). This is a destructive, multi-phase, explicit-opt-in workflow — start with the `polylith-migrate-orchestrator` skill, not any individual `polylith-migrate-*` sub-skill.

polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/README.md

@@ -0,0 +1,111 @@
+# Project Migration Skills
+
+> **Note for contributors:** this README is a **human reference** and a skill **index**. Agents load each `polylith-migrate-*/SKILL.md` independently via the skill loader; this README is **not** auto-loaded with any skill. Anything an agent must know to act has to live in the relevant `SKILL.md` itself, not here.
+
+This directory contains skills for migrating **non-Polylith Python projects** into a Polylith workspace. They cooperate via two artifacts under `migration/<PROJECT>/`:
+
+- `state.md` — a flat `KEY=value` file. Canonical schema lives in [`polylith-migrate-discover/SKILL.md`](./polylith-migrate-discover/SKILL.md).
+- `manifest.md` — a human-readable structural inventory of the source project.
+
+---
+
+## ⚠️ When to use these skills
+
+**Only** when:
+1. A human has **explicitly instructed** to migrate a specific project (e.g., "migrate `projects/my-app` to Polylith").
+2. The target project lives under `projects/<PROJECT>/` of this Polylith workspace.
+3. The goal is to refactor the project into Polylith bricks (bases and components).
+
+**Do not use** for:
+- Automated or unattended migrations.
+- Projects that are already structured as Polylith bricks.
+- Daily Polylith development tasks — for those, see the sibling `polylith-*` skills.
+
+---
+
+## How to invoke
+
+Load the orchestrator and let it drive the rest:
+
+```
+Load the `polylith-migrate-orchestrator` skill and migrate `projects/<project-name>`.
+```
+
+The orchestrator will:
+1. Ask the user for explicit confirmation.
+2. Establish a git safety net (dedicated branch + per-phase commits).
+3. Load and execute each phase skill in order, verifying after each.
+
+> **Why every sub-skill says "do not load directly".** Each `polylith-migrate-<phase>` skill's `description:` starts with a redirect to `polylith-migrate-orchestrator`. This is intentional: it makes the orchestrator the only valid entry point regardless of which sub-skill the agent's fuzzy-match initially favours. The sub-skills depend on state (`migration/<PROJECT>/state.md`) and a git safety net that only the orchestrator sets up.
+
+---
+
+## Downstream installation
+
+When this skill set is installed into another Polylith workspace (e.g. via a skills package), the in-skill `[ENTRY POINT]` / `[Internal sub-skill of polylith-migrate-orchestrator …]` markers in each `description:` are the primary routing signal — they ship with the package.
+
+For an extra-strong signal, downstream consumers should add the following snippet to their own repo-level `AGENTS.md` (or equivalent agent-routing file). It is **not** required — the in-skill markers are usually sufficient — but it removes any ambiguity for agents that read `AGENTS.md` before scanning skill descriptions.
+
+```markdown
+## Polylith migration instructions
+
+When the user asks to migrate a non-Polylith Python project to Polylith
+(e.g. "migrate `projects/<name>` to Polylith"), load the
+`polylith-migrate-orchestrator` skill first and let it drive the workflow.
+
+Never load `polylith-migrate-discover`, `polylith-migrate-extract-to-base`, or any other
+`polylith-migrate-*` sub-skill directly — they are phases the orchestrator
+invokes in order, with per-phase verification and git checkpoints
+between them.
+```
+
+---
+
+## Workflow at a glance
+
+The **authoritative** phase order, numbering, and dependencies live in
+[`polylith-migrate-orchestrator/SKILL.md`](./polylith-migrate-orchestrator/SKILL.md) — it is the
+**single source of truth**. This README intentionally does **not** repeat the
+table, to avoid drift (sub-skills must not hardcode phase numbers either; they
+reference `<N>` from the orchestrator table).
+
+At a glance, the flow is:
+
+> **discover → analyze-imports** (choose `shim`/`shimless`) **→ extract-to-base →
+> update-imports →** *[optional shim sub-track, only when `SHIM_STRATEGY=shim`]* **→
+> prepare-project → verify-stability → isolate-base-and-big-component →
+> split-big-component → extract-standalone-modules →
+> isolate-shared-and-project-logic → distribute-wiring → split-component-internals →
+> refactor-tests → definition-of-done**
+
+### Optional skills (triggered during `polylith-migrate-discover`)
+
+| Skill                                                                                           | Purpose                                                                                              | Trigger / dependency                                                              |
+|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| [`polylith-migrate-convert-linter`](./polylith-migrate-convert-linter/SKILL.md)                                   | Align the project's linter/formatter with the **workspace's** configured tool.                      | `CONVERT_LINTER=yes` in `state.md`. Runs between `polylith-migrate-discover` and `polylith-migrate-analyze-imports`. |
+| [`polylith-migrate-convert-type-checker`](./polylith-migrate-convert-type-checker/SKILL.md)                       | Align the project's type checker with the **workspace's** configured tool.                          | `CONVERT_TYPE_CHECKER=yes` in `state.md`. Runs between `polylith-migrate-discover` and `polylith-migrate-analyze-imports`. |
+| [`polylith-migrate-convert-package-manager`](./polylith-migrate-convert-package-manager/SKILL.md)                 | Convert the project's `pyproject.toml` to uv workspaces. **Opinionated about uv** — only run when the workspace itself uses uv. | `CONVERT_PACKAGE_MANAGER=yes` in `state.md`. Runs between `polylith-migrate-discover` and `polylith-migrate-analyze-imports`. |
+| [`polylith-migrate-dedupe`](./polylith-migrate-dedupe/SKILL.md)                                                   | Identify and apply controlled deduplication discovered during refactoring.                          | User approval. Runs after `polylith-migrate-split-big-component` or `polylith-migrate-extract-standalone-modules`. |
+
+---
+
+## Scope of the four "splitting" skills
+
+These skills overlap in vocabulary but address different scopes. Use this matrix to decide which one applies:
+
+| Skill                                       | Scope                                          | Trigger                                                                   |
+|---------------------------------------------|------------------------------------------------|---------------------------------------------------------------------------|
+| `polylith-migrate-split-big-component`               | Within one project; component → multiple components. | The temporary big component (from `polylith-migrate-isolate-base-and-big-component`) is too large. |
+| `polylith-migrate-extract-standalone-modules`        | Within one project; pulls foundational modules out of the residual. | Residual still contains `consts.py`/`exceptions.py`/`models.py`.  |
+| `polylith-migrate-split-component-internals`         | Within one already-extracted shared component; `core.py` → multiple files. | A component's `core.py` mixes multiple domains internally.      |
+| `polylith-migrate-isolate-shared-and-project-logic`  | Cross-project; separate shared vs project-specific in components used by ≥ 2 projects. | Migrating a 2nd+ project that overlaps with an already-extracted one. |
+
+> 💡 In a fresh migration of a single project, you usually run `polylith-migrate-split-big-component` → `polylith-migrate-extract-standalone-modules` → `polylith-migrate-split-component-internals`, and skip `polylith-migrate-isolate-shared-and-project-logic` until a second project is migrated.
+
+---
+
+## Files in this directory
+
+- `README.md` — this file (human reference + index).
+- `polylith-migrate-orchestrator/SKILL.md` — entry point; defines the phase order and the git safety net.
+- `polylith-migrate-<phase>/SKILL.md` — one per phase referenced in the orchestrator table.

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-analyze-imports → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-analyze-imports}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-analyze-imports
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Analyze the project's import graph to find how the original namespace is referenced, choose the namespace-rewrite strategy (shim vs shimless), detect circular imports, and list symbols exported by the original namespace."
+name: polylith-migrate-analyze-imports
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Analyze the project's import graph to find how the original namespace is referenced, choose the namespace-rewrite strategy (shim vs shimless), detect circular imports, and list symbols exported by the original namespace."
 ---
 
-# Skill: migrate-analyze-imports
+# Skill: polylith-migrate-analyze-imports
 
 ## Goal
 Analyze the project's import graph to:
@@ -13,7 +13,7 @@ Analyze the project's import graph to:
 4. Detect potential circular imports.
 
 This drives the namespace rewrite (phase 4) and, when `SHIM_STRATEGY=shim`, the
-shim sub-track (phase 4b). See the `migrate-orchestrator` table for phase numbers.
+shim sub-track (phase 4b). See the `polylith-migrate-orchestrator` table for phase numbers.
 
 ## Inputs
 - Project name (from `migration/<project-name>/state.md`)
@@ -95,5 +95,5 @@ SHIM_STRATEGY=<shim|shimless>
 git add migration/${PROJECT}/import_analysis.md migration/${PROJECT}/state.md
 git commit -m "migrate(${PROJECT}): phase <N> — analyze-imports"
 ```
-> `<N>` is this phase's number from the `migrate-orchestrator` table (the single
+> `<N>` is this phase's number from the `polylith-migrate-orchestrator` table (the single
 > source of truth) — do not hardcode it.

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-automate-import-updates → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-automate-import-updates}/SKILL.md

@@ -1,21 +1,21 @@
 ---
-name: migrate-automate-import-updates
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Update imports in the new base location to reference the new namespace instead of the original namespace."
+name: polylith-migrate-automate-import-updates
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Update imports in the new base location to reference the new namespace instead of the original namespace."
 ---
 
-# Skill: migrate-automate-import-updates
+# Skill: polylith-migrate-automate-import-updates
 
 ## Goal
 Update imports to reference the new namespace instead of the original namespace, ensuring that the codebase remains functional after the namespace migration.
 
-> **Scope depends on `SHIM_STRATEGY`** (set by `migrate-analyze-imports`):
+> **Scope depends on `SHIM_STRATEGY`** (set by `polylith-migrate-analyze-imports`):
 > - `shim`: rewrite imports **in the new base location only** — external consumers keep
 >   using the original namespace via the shim (phase 4b).
 > - `shimless`: rewrite **every** reference to the original namespace — base internals,
 >   entrypoints / run-scripts, infra (e.g. `alembic/env.py`), and tests — so nothing
 >   imports the old namespace and no shim is needed.
 >
-> Cover **all three reference forms** (see `migrate-analyze-imports`): dotted
+> Cover **all three reference forms** (see `polylith-migrate-analyze-imports`): dotted
 > `from <ns>.<sub> import …`, bare-submodule `from <ns> import <sub>` (incl. multi-name
 > and **mixed** lines), and quoted string paths (`mock.patch("<ns>.x.Y")`, logging
 > dict-config). A naive "`from <ns>.`" replace silently misses the bare and quoted forms.
@@ -26,7 +26,7 @@ Update imports to reference the new namespace instead of the original namespace,
 > names — far more reliably than ad-hoc edits across dozens of files. Keep it as plain
 > functions (no classes), run it over `bases/`, `components/`, `test/`, and the project
 > dir, then verify by grepping for any residual `<ns>` reference. The same helper is
-> reusable for the component-extraction rewrites in `migrate-split-big-component`.
+> reusable for the component-extraction rewrites in `polylith-migrate-split-big-component`.
 
 ## Inputs
 - Project name (from `migration/<project-name>/state.md`)
@@ -73,4 +73,4 @@ git add bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/
 git add migration/${PROJECT}/import_updates.md
 git commit -m "migrate(${PROJECT}): phase <N> — automate-import-updates"
 ```
-> `<N>` is this phase's number from the `migrate-orchestrator` table (the single source of truth) — do not hardcode it.
+> `<N>` is this phase's number from the `polylith-migrate-orchestrator` table (the single source of truth) — do not hardcode it.

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-linter → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-convert-linter}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-convert-linter
-description: "[Internal sub-skill of `migrate-orchestrator` (optional, runs only when opted in during `migrate-discover`). Do not load directly — load `migrate-orchestrator` first.] Align the project's linter and formatter with the **workspace's** configured tool (whatever it is — ruff, black+isort+flake8, pylint, etc.). Removes project-specific config and consolidates rules into the workspace root."
+name: polylith-migrate-convert-linter
+description: "[Internal sub-skill of `polylith-migrate-orchestrator` (optional, runs only when opted in during `polylith-migrate-discover`). Do not load directly — load `polylith-migrate-orchestrator` first.] Align the project's linter and formatter with the **workspace's** configured tool (whatever it is — ruff, black+isort+flake8, pylint, etc.). Removes project-specific config and consolidates rules into the workspace root."
 ---
 
-# Skill: migrate-convert-linter
+# Skill: polylith-migrate-convert-linter
 
 ## Goal
 Align the project with the **workspace's** linter and formatter. This skill is **not** opinionated about ruff — it reads the workspace's configured tool from the root `pyproject.toml` and aligns the project to that.
@@ -17,12 +17,12 @@ From `migration/<PROJECT>/state.md`:
 - `LINTER`, `FORMATTER`
 - `RUN_TEST_CMD` (optional: `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`)
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 
 ### 0. Identify the workspace's tool
-Open the **workspace root** `pyproject.toml` and identify the configured linter and formatter using the same detection table as `migrate-discover` (`[tool.ruff]` → ruff, `[tool.black]` → black, `[tool.flake8]` or `.flake8` → flake8, etc.). Record what you found — every step below refers to "the workspace's linter/formatter" and means **this** tool, not necessarily ruff.
+Open the **workspace root** `pyproject.toml` and identify the configured linter and formatter using the same detection table as `polylith-migrate-discover` (`[tool.ruff]` → ruff, `[tool.black]` → black, `[tool.flake8]` or `.flake8` → flake8, etc.). Record what you found — every step below refers to "the workspace's linter/formatter" and means **this** tool, not necessarily ruff.
 
 If the workspace has no linter configured at all, stop and ask the user how to proceed (introduce ruff? skip linting alignment? abort the conversion?).
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-package-manager → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-convert-package-manager}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-convert-package-manager
-description: "[Internal sub-skill of `migrate-orchestrator` (optional, runs only when opted in during `migrate-discover`). Do not load directly — load `migrate-orchestrator` first.] Convert the project's `pyproject.toml` to PEP 621/uv-workspaces format and register it as a uv-workspace member. **Opinionated about uv** — only applies when the workspace itself uses uv. Skip otherwise."
+name: polylith-migrate-convert-package-manager
+description: "[Internal sub-skill of `polylith-migrate-orchestrator` (optional, runs only when opted in during `polylith-migrate-discover`). Do not load directly — load `polylith-migrate-orchestrator` first.] Convert the project's `pyproject.toml` to PEP 621/uv-workspaces format and register it as a uv-workspace member. **Opinionated about uv** — only applies when the workspace itself uses uv. Skip otherwise."
 ---
 
-# Skill: migrate-convert-package-manager
+# Skill: polylith-migrate-convert-package-manager
 
 > ⚠ **Opinionation gate.** This skill is **explicitly opinionated about uv**. It does not generalize to Poetry, PDM, or Hatch workspaces. If your Polylith workspace uses one of those, **do not run this skill** — align the project to the workspace's manager via a manual step instead, and leave `CONVERT_PACKAGE_MANAGER=no` in `state.md`.
 
@@ -14,7 +14,7 @@ Convert the project's `pyproject.toml` to PEP 621/uv format and register it as a
 Skip this skill if **any** of the following holds:
 - `PACKAGE_MANAGER=uv` already in `migration/<PROJECT>/state.md` (nothing to convert).
 - The workspace root does **not** use uv (this skill does not apply — see the opinionation gate above).
-- `CONVERT_PACKAGE_MANAGER=no` in `state.md` (user opted out during `migrate-discover`).
+- `CONVERT_PACKAGE_MANAGER=no` in `state.md` (user opted out during `polylith-migrate-discover`).
 
 ### Verify the workspace uses uv before proceeding
 Open the **workspace root** `pyproject.toml` and look for `[tool.uv.workspace]` and/or a sibling `uv.lock`. If neither is present, **stop**: this skill does not apply.
@@ -25,7 +25,7 @@ From `migration/<PROJECT>/state.md`:
 - `PACKAGE_MANAGER`
 - `RUN_TEST_CMD` (optional: `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`)
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-type-checker → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-convert-type-checker}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-convert-type-checker
-description: "[Internal sub-skill of `migrate-orchestrator` (optional, runs only when opted in during `migrate-discover`). Do not load directly — load `migrate-orchestrator` first.] Align the project's type checker with the **workspace's** configured tool (whatever it is — mypy, pyright, ty, etc.). Removes project-specific config and consolidates settings into the workspace root."
+name: polylith-migrate-convert-type-checker
+description: "[Internal sub-skill of `polylith-migrate-orchestrator` (optional, runs only when opted in during `polylith-migrate-discover`). Do not load directly — load `polylith-migrate-orchestrator` first.] Align the project's type checker with the **workspace's** configured tool (whatever it is — mypy, pyright, ty, etc.). Removes project-specific config and consolidates settings into the workspace root."
 ---
 
-# Skill: migrate-convert-type-checker
+# Skill: polylith-migrate-convert-type-checker
 
 ## Goal
 Align the project with the **workspace's** type checker. This skill is **not** opinionated about ty — it reads the workspace's configured tool from the root `pyproject.toml` and aligns the project to that.
@@ -17,12 +17,12 @@ From `migration/<PROJECT>/state.md`:
 - `TYPE_CHECKER`
 - `RUN_TEST_CMD` (optional: `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`)
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 
 ### 0. Identify the workspace's tool
-Open the **workspace root** `pyproject.toml` and identify the configured type checker using the same detection table as `migrate-discover` (`[tool.mypy]` or `mypy.ini` → mypy, `[tool.pyright]` or `pyrightconfig.json` → pyright, `[tool.ty]` → ty). Record what you found — every step below refers to "the workspace's type checker" and means **this** tool, not necessarily ty.
+Open the **workspace root** `pyproject.toml` and identify the configured type checker using the same detection table as `polylith-migrate-discover` (`[tool.mypy]` or `mypy.ini` → mypy, `[tool.pyright]` or `pyrightconfig.json` → pyright, `[tool.ty]` → ty). Record what you found — every step below refers to "the workspace's type checker" and means **this** tool, not necessarily ty.
 
 If the workspace has no type checker configured at all, stop and ask the user how to proceed (introduce one? skip type-check alignment? abort the conversion?).
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-dedupe → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-dedupe}/SKILL.md

@@ -1,16 +1,16 @@
 ---
-name: migrate-dedupe
-description: "[Internal sub-skill of `migrate-orchestrator` (optional, runs only when opted in during `migrate-discover`). Do not load directly — load `migrate-orchestrator` first.] Identify and execute controlled deduplication of code during migration (if the user opts in)."
+name: polylith-migrate-dedupe
+description: "[Internal sub-skill of `polylith-migrate-orchestrator` (optional, runs only when opted in during `polylith-migrate-discover`). Do not load directly — load `polylith-migrate-orchestrator` first.] Identify and execute controlled deduplication of code during migration (if the user opts in)."
 ---
 
-# Skill: migrate-dedupe
+# Skill: polylith-migrate-dedupe
 
 > 📐 **Scope vs sibling skills.** This skill is **opportunistic deduplication** that may be triggered any time during refactoring when duplication candidates surface. It is **not** the canonical place for the structural decompositions:
-> - For "split this big component into smaller ones", use `migrate-split-big-component` (it already includes a dedup-analysis subsection — usually sufficient on a first migration).
-> - For "this component's `core.py` mixes domains", use `migrate-split-component-internals`.
-> - For "two projects have overlapping code, split shared from project-specific", use `migrate-isolate-shared-and-project-logic`.
+> - For "split this big component into smaller ones", use `polylith-migrate-split-big-component` (it already includes a dedup-analysis subsection — usually sufficient on a first migration).
+> - For "this component's `core.py` mixes domains", use `polylith-migrate-split-component-internals`.
+> - For "two projects have overlapping code, split shared from project-specific", use `polylith-migrate-isolate-shared-and-project-logic`.
 >
-> Use `migrate-dedupe` when none of the above fits cleanly — e.g., duplication discovered across already-extracted components that don't map to a structural split.
+> Use `polylith-migrate-dedupe` when none of the above fits cleanly — e.g., duplication discovered across already-extracted components that don't map to a structural split.
 
 ## Goal
 Identify duplication candidates during the migration process and execute controlled deduplication for user-approved candidates.
@@ -56,7 +56,7 @@ From `migration/<PROJECT>/state.md`:
 From `migration/<PROJECT>/manifest.md`:
 - Module map of components.
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 
@@ -98,7 +98,7 @@ From `migration/<PROJECT>/manifest.md`:
 | Symptom | Likely cause | Remediation |
 |---------|--------------|-------------|
 | Two pieces of code look identical but operate on different domains (e.g., both are `validate(...)` but one is for users, the other for transactions) | Coincidental similarity, not real duplication. | Classify as "coincidental"; leave both in place. Resist the urge to share. |
-| The candidate shared component would pull in framework-specific dependencies (e.g., a "logging" shared brick that needs both `confluent_kafka_helpers` and `httpx`) | Wrong shared abstraction — you're sharing the union of two project surfaces. | Revert and parameterize instead: keep the shared core minimal and pass project-specific values as arguments. See the "Pattern: Parameterize the shared component" guidance in `migrate-split-big-component`. |
+| The candidate shared component would pull in framework-specific dependencies (e.g., a "logging" shared brick that needs both `confluent_kafka_helpers` and `httpx`) | Wrong shared abstraction — you're sharing the union of two project surfaces. | Revert and parameterize instead: keep the shared core minimal and pass project-specific values as arguments. See the "Pattern: Parameterize the shared component" guidance in `polylith-migrate-split-big-component`. |
 | Tests break after deduplication because `mock.patch("<old.path>")` no longer hits anything | Patch strings reference the pre-dedup module path. | Update patch strings to the new shared module path. Validate by deliberately breaking the patched function and confirming the test fails. |
 
 ## Done When

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-definition-of-done → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-definition-of-done}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-definition-of-done
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Define the criteria for completing the migration process."
+name: polylith-migrate-definition-of-done
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Define the criteria for completing the migration process."
 ---
 
-# Skill: migrate-definition-of-done
+# Skill: polylith-migrate-definition-of-done
 
 ## Done When
 
@@ -23,7 +23,7 @@ description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directl
 
 ### Tests
 - Tests are moved from `projects/<PROJECT>/tests/` to workspace level (**required**).
-- Unit-test layout — **one** of the following (see `migrate-refactor-tests`):
+- Unit-test layout — **one** of the following (see `polylith-migrate-refactor-tests`):
   - **Per-brick (theme-aligned):** `loose` → `test/bases/<TARGET_TOP_NS>/<base>/` and `test/components/<TARGET_TOP_NS>/<component>/`; `tdd` → `bases/<base>/test/<TARGET_TOP_NS>/<base>/` and `components/<component>/test/<TARGET_TOP_NS>/<component>/`. **Or**
   - **Workspace-level service dir** `test/<svc>_service/` — valid when shared test helpers can't cheaply become fixtures (the namespace-merge hazard makes a per-brick split unsafe otherwise). Record the chosen layout in `state.md`.
 - Integration tests live in a shared location (e.g., `test/integration/` or `test/<svc>_service/integration/`).
@@ -31,7 +31,7 @@ description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directl
 - `RUN_TEST_CMD` points to the test root **and collects the same number of tests as the pre-migration baseline**.
 
 ### Infrastructure
-- Infrastructure folders are moved to `infra/<folder>/<project-name>/`, **or** the move is **deferred with a documented rationale** in `state.md` when the deploy cannot be verified in the migration environment (see `migrate-prepare-project`). Either way, `alembic/` stays with `alembic.ini` in the project.
+- Infrastructure folders are moved to `infra/<folder>/<project-name>/`, **or** the move is **deferred with a documented rationale** in `state.md` when the deploy cannot be verified in the migration environment (see `polylith-migrate-prepare-project`). Either way, `alembic/` stays with `alembic.ini` in the project.
 
 ### Interfaces
 - Each component defines its public API via `__init__.py`.
@@ -39,7 +39,7 @@ description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directl
 
 ### Linting and Type-Checking
 - Linting/formatting and type-checking use the workspace's configured tool(s).
-- `RUN_LINT_CMD` and `RUN_TYPECHECK_CMD` pass **if set**. They may be intentionally empty when the project's pre-migration baseline already failed these gates (recorded in `migrate-discover`); **pre-existing** violations are not the migration's responsibility — note them as a follow-up rather than blocking the migration.
+- `RUN_LINT_CMD` and `RUN_TYPECHECK_CMD` pass **if set**. They may be intentionally empty when the project's pre-migration baseline already failed these gates (recorded in `polylith-migrate-discover`); **pre-existing** violations are not the migration's responsibility — note them as a follow-up rather than blocking the migration.
 
 ### Dependencies
 - Workspace root `pyproject.toml` contains all third-party dependencies with version constraints.
@@ -55,13 +55,13 @@ These checks go beyond per-phase verification and exercise the migrated project
 
 ### 1. Baseline test count restored
 
-Compare collected test count to the baseline recorded by `migrate-discover`:
+Compare collected test count to the baseline recorded by `polylith-migrate-discover`:
 
 ```bash
 <RUN_TEST_CMD_with --collect-only -q | tail -1>
 ```
 
-The count must **equal** the baseline. A lower count means `pytest` discovery is misconfigured (see `migrate-refactor-tests` failure modes). A higher count means tests were inadvertently duplicated during the move.
+The count must **equal** the baseline. A lower count means `pytest` discovery is misconfigured (see `polylith-migrate-refactor-tests` failure modes). A higher count means tests were inadvertently duplicated during the move.
 
 ### 2. No undocumented shims remain
 
@@ -80,9 +80,9 @@ Inspect `migration/<PROJECT>/shims.md` (if it exists):
 
 | Symptom | Likely cause | Remediation |
 |---------|--------------|-------------|
-| `RUN_TEST_CMD` passes but collected test count is lower than the baseline from `migrate-discover` | `pytest` discovery is misconfigured after the test reorganisation. | Update `[tool.pytest.ini_options].testpaths` (or pass paths explicitly in `RUN_TEST_CMD`). Run `pytest --collect-only` and diff against baseline collection. See `migrate-refactor-tests` for details. |
-| `poly check` is green and tests pass, but a base imports something that no longer exists at the expected path | Entrypoint wiring regression introduced while moving code into bases/components. | Verify each base's entrypoint module imports cleanly and that its wiring matches the original. Revisit `migrate-distribute-wiring`. |
-| `migration/shims.md` still lists active shims | Shims from `migrate-extract-to-base` (namespace change) were never removed. | Either rewrite imports to the new namespace and delete the shims, or schedule shim removal as a follow-up PR and note it in the migration branch description. Do not merge with undocumented shims. |
+| `RUN_TEST_CMD` passes but collected test count is lower than the baseline from `polylith-migrate-discover` | `pytest` discovery is misconfigured after the test reorganisation. | Update `[tool.pytest.ini_options].testpaths` (or pass paths explicitly in `RUN_TEST_CMD`). Run `pytest --collect-only` and diff against baseline collection. See `polylith-migrate-refactor-tests` for details. |
+| `poly check` is green and tests pass, but a base imports something that no longer exists at the expected path | Entrypoint wiring regression introduced while moving code into bases/components. | Verify each base's entrypoint module imports cleanly and that its wiring matches the original. Revisit `polylith-migrate-distribute-wiring`. |
+| `migration/shims.md` still lists active shims | Shims from `polylith-migrate-extract-to-base` (namespace change) were never removed. | Either rewrite imports to the new namespace and delete the shims, or schedule shim removal as a follow-up PR and note it in the migration branch description. Do not merge with undocumented shims. |
 
 ## Commit
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-detect-circular-imports → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-detect-circular-imports}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: migrate-detect-circular-imports
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Detect and report circular imports introduced by the namespace migration."
+name: polylith-migrate-detect-circular-imports
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Detect and report circular imports introduced by the namespace migration."
 ---
 
-# Skill: migrate-detect-circular-imports
+# Skill: polylith-migrate-detect-circular-imports
 
-> ⛓ **Conditional phase (4b).** Runs **only when `SHIM_STRATEGY=shim`** (chosen in `migrate-analyze-imports`). On the **shimless** path this phase is **skipped** — a pure namespace rename introduces no base↔shim cycles. See the `migrate-orchestrator` workflow.
+> ⛓ **Conditional phase (4b).** Runs **only when `SHIM_STRATEGY=shim`** (chosen in `polylith-migrate-analyze-imports`). On the **shimless** path this phase is **skipped** — a pure namespace rename introduces no base↔shim cycles. See the `polylith-migrate-orchestrator` workflow.
 
 ## Goal
 Detect and report circular imports introduced by the namespace migration, particularly between the new base location and the compatibility shim.
@@ -45,4 +45,4 @@ Detect and report circular imports introduced by the namespace migration, partic
 git add migration/${PROJECT}/circular_imports.md
 git commit -m "migrate(${PROJECT}): phase <N> — detect-circular-imports"
 ```
-> `<N>` is this phase's number from the `migrate-orchestrator` table (the single source of truth) — do not hardcode it.
+> `<N>` is this phase's number from the `polylith-migrate-orchestrator` table (the single source of truth) — do not hardcode it.

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-discover → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-discover}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-discover
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Create `migration/<PROJECT>/state.md` and `migration/<PROJECT>/manifest.md` by inspecting the existing project under `projects/<PROJECT>/`."
+name: polylith-migrate-discover
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Create `migration/<PROJECT>/state.md` and `migration/<PROJECT>/manifest.md` by inspecting the existing project under `projects/<PROJECT>/`."
 ---
 
-# Skill: migrate-discover
+# Skill: polylith-migrate-discover
 
 ## Goal
 Inspect the project and create two artifacts that drive every subsequent migration phase:
@@ -32,7 +32,7 @@ TYPE_CHECKER=<mypy|pyright|ty|none>
 POLY_CMD_PREFIX=<poetry poly|pipenv run poly|pdm run poly|hatch run poly|uv run poly|poly>
 BRICK_IMPORT_MECHANISM=<editable-root|pytest-pythonpath|other — how the workspace exposes <TARGET_TOP_NS>.* bricks for import>
 
-SHIM_STRATEGY=<shim|shimless — chosen in phase 2 (migrate-analyze-imports); may be empty at discover>
+SHIM_STRATEGY=<shim|shimless — chosen in phase 2 (polylith-migrate-analyze-imports); may be empty at discover>
 
 CONVERT_LINTER=<yes|no>
 CONVERT_TYPE_CHECKER=<yes|no>
@@ -53,13 +53,13 @@ GIT_BASE_SHA=<commit SHA of the migration branch start point>
 | `PROJECT_DIR` | Project subfolder path. | The orchestrator's `<PROJECT>`. |
 | `ORIG_TOP_NS` | Current top-level Python package name. | First non-`tests` directory under `projects/<PROJECT>/src/` or `projects/<PROJECT>/`. |
 | `TARGET_TOP_NS` | Desired Polylith namespace. | `workspace.toml` `[tool.polylith].namespace`, or `ORIG_TOP_NS` if no workspace exists yet. |
-| `INITIAL_BASE_NAME` | Name of the **single temporary base** used to hold all code during early phases. Becomes the **default base name** in `migrate-isolate-base-and-big-component`. Final migrations usually contain *several* bases — this is just the starting one. | Derived from `[project.name]`, confirmed by user. |
+| `INITIAL_BASE_NAME` | Name of the **single temporary base** used to hold all code during early phases. Becomes the **default base name** in `polylith-migrate-isolate-base-and-big-component`. Final migrations usually contain *several* bases — this is just the starting one. | Derived from `[project.name]`, confirmed by user. |
 | `ALIAS` | Short alias shown in `poly info` / `poly deps` tables. Optional. | Derived, confirmed by user. |
 | `GROUP` | Polylith project group. Optional. | Asked from user. |
 | `PACKAGE_MANAGER` / `LINTER` / `FORMATTER` / `TYPE_CHECKER` | Detected tooling. | Detection table below. |
 | `POLY_CMD_PREFIX` | Prefix every `poly …` command in later skills uses. | Derived from `PACKAGE_MANAGER`. |
 | `BRICK_IMPORT_MECHANISM` | How the workspace makes `<TARGET_TOP_NS>.*` bricks importable for tests/dev. `editable-root` (root project is editable-installed; e.g. Hatch `dev-mode-dirs`), `pytest-pythonpath` (root `[tool.pytest.ini_options].pythonpath = ["bases","components","development"]`), or `other`. | Step 4: confirmed/established below. |
-| `SHIM_STRATEGY` | `shim` or `shimless` — chosen in phase 2 (`migrate-analyze-imports`). May be empty at discover. | `migrate-analyze-imports`. |
+| `SHIM_STRATEGY` | `shim` or `shimless` — chosen in phase 2 (`polylith-migrate-analyze-imports`). May be empty at discover. | `polylith-migrate-analyze-imports`. |
 | `CONVERT_*` | Whether the user opted in to a tooling conversion. | Asked from user. |
 | `RUN_TEST_CMD` etc. | The exact shell commands the migration verifies against after each phase. | Derived from project config, confirmed by user if ambiguous. |
 | `GIT_BRANCH` / `GIT_BASE_SHA` | Set by the orchestrator's Phase 0; recorded here so later skills know where to roll back to. | Orchestrator. |
@@ -177,7 +177,7 @@ Read the **workspace root** `pyproject.toml` to determine the workspace's standa
 - If the project's `LINTER`/`FORMATTER` already matches the workspace's → set `CONVERT_LINTER=no` (skip).
 - If the project's `TYPE_CHECKER` already matches the workspace's → set `CONVERT_TYPE_CHECKER=no` (skip).
 - If the project's `PACKAGE_MANAGER` is already `uv` **and** the workspace uses uv → set `CONVERT_PACKAGE_MANAGER=no` (skip).
-- If the workspace does **not** use uv, `migrate-convert-package-manager` does not apply at all — set `CONVERT_PACKAGE_MANAGER=no` and skip the question below.
+- If the workspace does **not** use uv, `polylith-migrate-convert-package-manager` does not apply at all — set `CONVERT_PACKAGE_MANAGER=no` and skip the question below.
 
 ### 6. Create `manifest.md`
 
@@ -249,7 +249,7 @@ Wait for the user's response. Update `state.md` with corrections and the `CONVER
 |---------|--------------|-------------|
 | Derived `INITIAL_BASE_NAME` collides with an existing brick under `bases/<TARGET_TOP_NS>/` or `components/<TARGET_TOP_NS>/` | Two projects derive the same base name from a generic `[project.name]`. | Append a project-specific suffix (e.g., `payment_api` instead of `payment`) and re-confirm with the user. Check before writing `state.md`. |
 | Project has no detectable test command | No `pytest` / `make test` / CI config that reveals a runnable test command. | Ask the user explicitly. If none exists, set `RUN_TEST_CMD=` empty and record that **every later phase loses its primary safety check** — flag the heightened risk and, after each phase, verify that each base's entrypoint module imports cleanly and its wiring matches the original. |
-| Multiple linters or formatters are configured simultaneously (e.g., black + ruff format both active) | Project history accumulated tools without a cleanup. | Record both in `state.md` (comma-separated values are acceptable in this one case), and flag for resolution during `migrate-convert-linter`. Do **not** silently pick one. |
+| Multiple linters or formatters are configured simultaneously (e.g., black + ruff format both active) | Project history accumulated tools without a cleanup. | Record both in `state.md` (comma-separated values are acceptable in this one case), and flag for resolution during `polylith-migrate-convert-linter`. Do **not** silently pick one. |
 | Baseline test command resolves the wrong Python (e.g. "incompatible with the project's Python requirement") | Project `requires-python` disagrees with the workspace root `requires-python` / `.python-version`. | Reconcile per step 4.2 — align the workspace version (confirm with user) or record a per-command `--python <X>` override in the verification commands. |
 | `ModuleNotFoundError: No module named '<TARGET_TOP_NS>'` once code is in a base | The workspace doesn't expose bricks (e.g. root `[tool.uv] package = false` with `dev-mode-dirs` that never takes effect). | Establish `BRICK_IMPORT_MECHANISM` per step 4.3 — add a root pytest `pythonpath`, or make the root editable-installable. |
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-distribute-wiring → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-distribute-wiring}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-distribute-wiring
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Distribute app-wiring code from the residual component into the appropriate bases and shared components."
+name: polylith-migrate-distribute-wiring
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Distribute app-wiring code from the residual component into the appropriate bases and shared components."
 ---
 
-# Skill: migrate-distribute-wiring
+# Skill: polylith-migrate-distribute-wiring
 
 ## Goal
 Distribute app-wiring code from the residual component into the appropriate bases and shared components.
@@ -18,7 +18,7 @@ From `migration/<PROJECT>/state.md`:
 From `migration/<PROJECT>/manifest.md`:
 - Current module map, including what remains in the residual component.
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-extract-standalone-modules → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-extract-standalone-modules}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-extract-standalone-modules
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Extract foundational modules (e.g., `consts.py`, `exceptions.py`, or similar) from the residual component into standalone components."
+name: polylith-migrate-extract-standalone-modules
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Extract foundational modules (e.g., `consts.py`, `exceptions.py`, or similar) from the residual component into standalone components."
 ---
 
-# Skill: migrate-extract-standalone-modules
+# Skill: polylith-migrate-extract-standalone-modules
 
 ## Goal
 Extract **foundational modules** (e.g., `consts.py`, `exceptions.py`, `models.py`) from the residual component into standalone components. This skill is for zero-dependency or low-dependency modules that serve as building blocks for other components.
@@ -17,7 +17,7 @@ From `migration/<PROJECT>/state.md`:
 From `migration/<PROJECT>/manifest.md`:
 - Current module map, including what remains in the residual component.
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 

{polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-extract-to-base → polylith_cli-1.48.1/polylith_cli/.agents/skills/polylith/migrate-project/polylith-migrate-extract-to-base}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: migrate-extract-to-base
-description: "[Internal sub-skill of `migrate-orchestrator`. Do not load directly — load `migrate-orchestrator` first, which drives all phases.] Extract all application code from `projects/<PROJECT>/` into a temporary migration base."
+name: polylith-migrate-extract-to-base
+description: "[Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Extract all application code from `projects/<PROJECT>/` into a temporary migration base."
 ---
 
-# Skill: migrate-extract-to-base
+# Skill: polylith-migrate-extract-to-base
 
 ## Goal
 Extract all application code from `projects/<PROJECT>/` into a temporary migration base (`bases/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>/`).
@@ -19,7 +19,7 @@ From `migration/<PROJECT>/state.md`:
 From `migration/<PROJECT>/manifest.md`:
 - Directory tree and module map.
 
-> All inputs from `state.md` are assumed to satisfy the validation rules in `migrate-discover` (`### Validation rules`). Validate before proceeding.
+> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.
 
 ## Steps
 
@@ -48,17 +48,17 @@ From `migration/<PROJECT>/manifest.md`:
 ### 6. Handle Namespace Changes
 If `TARGET_TOP_NS != ORIG_TOP_NS`, the migration orchestrator will handle this in subsequent phases:
 
-1. `migrate-generate-shim` will create a compatibility shim at `projects/${PROJECT}/${ORIG_TOP_NS}/__init__.py` that re-exports from `${TARGET_TOP_NS}.${INITIAL_BASE_NAME}`.
-2. `migrate-automate-import-updates` will update imports in the new base location (at `bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/`) to reference the new namespace.
-3. `migrate-update-tests` will update test files to use the compatibility shim.
+1. `polylith-migrate-generate-shim` will create a compatibility shim at `projects/${PROJECT}/${ORIG_TOP_NS}/__init__.py` that re-exports from `${TARGET_TOP_NS}.${INITIAL_BASE_NAME}`.
+2. `polylith-migrate-automate-import-updates` will update imports in the new base location (at `bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/`) to reference the new namespace.
+3. `polylith-migrate-update-tests` will update test files to use the compatibility shim.
 
 ### 7. Use Shims if Needed
 - If imports break during this phase, add minimal temporary shims to re-export names from the new brick API.
 - Track shims in `migration/shims.md`.
-- Note that comprehensive shim generation will be handled in the `migrate-generate-shim` phase.
+- Note that comprehensive shim generation will be handled in the `polylith-migrate-generate-shim` phase.
 
 ## Verify
-- `RUN_TEST_CMD` succeeds with the same pass/fail counts as the pre-migration baseline recorded in `migrate-discover`.
+- `RUN_TEST_CMD` succeeds with the same pass/fail counts as the pre-migration baseline recorded in `polylith-migrate-discover`.
 - If set, `RUN_LINT_CMD` and `RUN_TYPECHECK_CMD` succeed.
 - Run `POLY_CMD_PREFIX check` to validate the workspace structure.
 - Run `POLY_CMD_PREFIX sync` to synchronize the `[tool.polylith.bricks]` table with actual imports.
@@ -67,8 +67,8 @@ If `TARGET_TOP_NS != ORIG_TOP_NS`, the migration orchestrator will handle this i
 
 | Symptom | Likely cause | Remediation |
 |---------|--------------|-------------|
-| `ModuleNotFoundError: No module named '<ORIG_TOP_NS>.<x>'` after move | `TARGET_TOP_NS != ORIG_TOP_NS` and imports weren't rewritten or shimmed. | This is resolved by later phases per `SHIM_STRATEGY` (chosen in `migrate-analyze-imports`): `shimless` rewrites every reference in `migrate-automate-import-updates` (phase 4); `shim` adds a re-export shim under `ORIG_TOP_NS` in the phase 4b sub-track (`migrate-generate-shim`). To keep this phase green in the meantime, add a minimal temporary shim and record it in `migration/shims.md` (step 7). |
-| `RUN_TEST_CMD` collects 0 tests after the move | Test files moved but `pytest` rootdir / `testpaths` still points at the old `projects/<PROJECT>/tests` location. | Update `pyproject.toml` `[tool.pytest.ini_options].testpaths` or pass explicit dirs in `RUN_TEST_CMD`. (Note: `migrate-prepare-project` moves tests properly — if extract-to-base touched tests at all, consider undoing that part.) |
+| `ModuleNotFoundError: No module named '<ORIG_TOP_NS>.<x>'` after move | `TARGET_TOP_NS != ORIG_TOP_NS` and imports weren't rewritten or shimmed. | This is resolved by later phases per `SHIM_STRATEGY` (chosen in `polylith-migrate-analyze-imports`): `shimless` rewrites every reference in `polylith-migrate-automate-import-updates` (phase 4); `shim` adds a re-export shim under `ORIG_TOP_NS` in the phase 4b sub-track (`polylith-migrate-generate-shim`). To keep this phase green in the meantime, add a minimal temporary shim and record it in `migration/shims.md` (step 7). |
+| `RUN_TEST_CMD` collects 0 tests after the move | Test files moved but `pytest` rootdir / `testpaths` still points at the old `projects/<PROJECT>/tests` location. | Update `pyproject.toml` `[tool.pytest.ini_options].testpaths` or pass explicit dirs in `RUN_TEST_CMD`. (Note: `polylith-migrate-prepare-project` moves tests properly — if extract-to-base touched tests at all, consider undoing that part.) |
 | `poly check` reports "brick imports another brick that is not in `[tool.polylith.bricks]`" | Step 3 only added the base; imports inside the base may pull in components not yet listed. | Run `POLY_CMD_PREFIX sync --quiet` to populate the rest, then re-run `check`. |
 | Editable install / build fails (`error: package directory '<x>' does not exist`) | The base move broke the previous `[tool.setuptools]` or `[tool.hatch.build]` `packages` setting in `projects/<PROJECT>/pyproject.toml`. | Update `packages` to point at the new `<TARGET_TOP_NS>` namespace, or remove the explicit `packages` setting and let Polylith's build hook handle it. |
 | Verification fails and you can't quickly diagnose | Phase commit not yet made. | `git reset --hard HEAD` to roll back to the previous phase's commit and consult the user. |