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

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

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

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

@@ -3,7 +3,14 @@
 
 > **Note for contributors:** this README is a **human reference**. The agent loads each `*/SKILL.md` independently via the skill loader; this file 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.
 
-## Available Skills
+## Skill loading model
+
+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.
+
+## Available Skills (daily Polylith workflows)
 
 | Skill                     | Command            | Purpose                                                                                                  |
 |---------------------------|--------------------|----------------------------------------------------------------------------------------------------------|
@@ -15,22 +22,13 @@
 | [Sync](./polylith-sync/SKILL.md)                                   | `poly sync`             | Update each project's brick list to match actual imports.                            |
 | [Workspace Inspection](./polylith-workspace-inspection/SKILL.md)   | `poly info`             | Show brick × project usage (which projects use which bricks).                        |
 | [Dependency Visualization](./polylith-dependency-visualization/SKILL.md) | `poly deps`       | Show brick × brick dependencies and interface compliance.                            |
+| [Dependency Management](./polylith-dependency-management/SKILL.md) | —                       | Add or manage third-party libraries for a brick or project.                          |
 | [Testing](./polylith-testing/SKILL.md)                             | `poly test diff`        | List bricks/projects affected by **test-code** changes since a tag.                  |
 | [Diff](./polylith-diff/SKILL.md)                                   | `poly diff`             | List bricks whose **implementation** changed since a tag.                            |
 | [Check](./polylith-check/SKILL.md)                                 | `poly check`            | Validate the workspace (CI gate; exits 1 on failure).                                |
 | [Libs](./polylith-libs/SKILL.md)                                   | `poly libs`             | Inspect third-party libraries per project.                                           |
-| [Concepts](./polylith-concepts/SKILL.md)                           | —                       | Provides foundational knowledge about Polylith architecture and terminology.           |
-
----
+| [Concepts](./polylith-concepts/SKILL.md)                           | —                       | Foundational knowledge about Polylith architecture and terminology.                  |
 
-## For humans — getting started
+## Advanced workflow
 
-1. **Set up the workspace** — [Workspace Setup](./workspace_setup/SKILL.md).
-2. **Understand the basics** — [Concepts](./concepts/SKILL.md).
-3. **Create bricks** — [Component Creation](./component_creation/SKILL.md) and [Base Creation](./base_creation/SKILL.md).
-4. **Create deployable projects** — [Project Management](./project_management/SKILL.md).
-5. **Remove bricks safely** — [Brick Removal](./brick_removal/SKILL.md).
-6. **Sync brick usage** — [Sync](./sync/SKILL.md).
-7. **Inspect** — [Workspace Inspection](./workspace_inspection/SKILL.md) (brick × project) and [Dependency Visualization](./dependency_visualization/SKILL.md) (brick × brick).
-8. **Validate** — [Check](./check/SKILL.md) (CI gate) and [Libs](./libs/SKILL.md) (library inspection).
-9. **Diff between releases** — [Diff](./diff/SKILL.md) and [Testing](./testing/SKILL.md).
+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.

polylith_cli-1.48.0/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 `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 [`migrate-discover/SKILL.md`](./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 `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 `migrate-<phase>` skill's `description:` starts with a redirect to `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 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
+`migrate-orchestrator` skill first and let it drive the workflow.
+
+Never load `migrate-discover`, `migrate-extract-to-base`, or any other
+`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
+[`migrate-orchestrator/SKILL.md`](./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 `migrate-discover`)
+
+| Skill                                                                                           | Purpose                                                                                              | Trigger / dependency                                                              |
+|-------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| [`migrate-convert-linter`](./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 `migrate-discover` and `migrate-analyze-imports`. |
+| [`migrate-convert-type-checker`](./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 `migrate-discover` and `migrate-analyze-imports`. |
+| [`migrate-convert-package-manager`](./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 `migrate-discover` and `migrate-analyze-imports`. |
+| [`migrate-dedupe`](./migrate-dedupe/SKILL.md)                                                   | Identify and apply controlled deduplication discovered during refactoring.                          | User approval. Runs after `migrate-split-big-component` or `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                                                                   |
+|---------------------------------------------|------------------------------------------------|---------------------------------------------------------------------------|
+| `migrate-split-big-component`               | Within one project; component → multiple components. | The temporary big component (from `migrate-isolate-base-and-big-component`) is too large. |
+| `migrate-extract-standalone-modules`        | Within one project; pulls foundational modules out of the residual. | Residual still contains `consts.py`/`exceptions.py`/`models.py`.  |
+| `migrate-split-component-internals`         | Within one already-extracted shared component; `core.py` → multiple files. | A component's `core.py` mixes multiple domains internally.      |
+| `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 `migrate-split-big-component` → `migrate-extract-standalone-modules` → `migrate-split-component-internals`, and skip `migrate-isolate-shared-and-project-logic` until a second project is migrated.
+
+---
+
+## Files in this directory
+
+- `README.md` — this file (human reference + index).
+- `migrate-orchestrator/SKILL.md` — entry point; defines the phase order and the git safety net.
+- `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/SKILL.md

@@ -0,0 +1,99 @@
+---
+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."
+---
+
+# Skill: migrate-analyze-imports
+
+## Goal
+Analyze the project's import graph to:
+1. Find **every** reference to the original namespace (in all three forms — see below).
+2. Choose the namespace-rewrite strategy: `SHIM_STRATEGY=shim|shimless`.
+3. List symbols exported by the original namespace's `__init__.py`.
+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.
+
+## Inputs
+- Project name (from `migration/<project-name>/state.md`)
+- Original namespace `ORIG_TOP_NS` (from `migration/<project-name>/state.md`)
+
+## The three reference forms (cover all of them)
+A namespace rewrite is **incomplete** unless it covers every form below. A naive
+"replace `from <ns>.` " misses forms 2 and 3:
+
+1. **Dotted import** — `from ${ORIG_TOP_NS}.<sub> import …`, `import ${ORIG_TOP_NS}.<sub>`.
+2. **Bare submodule import** — `from ${ORIG_TOP_NS} import <sub>` — single, multi-name
+   (`a, b, c`), and **mixed** lines where only some names move. Easy to miss: there is
+   no dot after the namespace.
+3. **Quoted string module paths** — `mock.patch("${ORIG_TOP_NS}.x.Y")`, logging
+   dict-config `"${ORIG_TOP_NS}.logging.HealthFilter"`, `importlib` / `getattr`
+   targets. Not import statements, but they must be rewritten too.
+
+> ⚠ Do **not** rewrite unquoted local variables that merely share a name with the
+> namespace (e.g. a FastAPI `app = FastAPI()` instance's `app.include_router(...)`).
+> Target import statements and quoted module paths only.
+
+## Steps
+
+### 1. Identify references to the original namespace
+1. Search for all three forms above across **all** `.py` files in the project (and
+   `pyproject.toml` / config files for string paths).
+2. Record the paths and statements in `migration/${PROJECT}/import_analysis.md`,
+   grouped as: **internal** (inside `${ORIG_TOP_NS}/`), **external consumers**
+   (entrypoints, `alembic`, scripts), and **tests**. The external + test groups are
+   what the strategy decision below hinges on.
+
+### 2. List symbols exported by the original namespace
+1. Inspect `${ORIG_TOP_NS}/__init__.py` (typically `projects/${PROJECT}/src/${ORIG_TOP_NS}/__init__.py`
+   or `projects/${PROJECT}/${ORIG_TOP_NS}/__init__.py`) and list public symbols
+   (not starting with `_`).
+2. Record them, and **note whether `__init__.py` is effectively empty** (docstring only).
+
+### 3. Decide the rewrite strategy (`SHIM_STRATEGY`)
+Choose based on the findings and record it in `state.md`:
+
+- **`shimless`** — when imports are predominantly **submodule-qualified**
+  (`from ${ORIG_TOP_NS}.<sub> import …` / `from ${ORIG_TOP_NS} import <sub>`) and
+  `${ORIG_TOP_NS}/__init__.py` exports little or nothing. A single top-level
+  re-export shim would resolve **none** of those submodule paths, and a full package
+  shim mirroring every module is high-effort/high-risk. Phase 4 rewrites **all**
+  references (internal + external + tests) directly to the new namespace, and the
+  **phase 4b sub-track is skipped**.
+- **`shim`** — when consumers import top-level symbols (`from ${ORIG_TOP_NS} import X`)
+  that a single `${ORIG_TOP_NS}/__init__.py` re-export can satisfy, and you want to
+  defer rewriting external consumers. Run the phase 4b sub-track after phase 4.
+- **When in doubt, prefer `shimless`** — it leaves no transitional shim to remove
+  later (the definition-of-done forbids undocumented shims), at the cost of a wider
+  but mechanical rewrite. Confirm with the user if the consumer surface is large.
+
+Record:
+```
+SHIM_STRATEGY=<shim|shimless>
+```
+
+### 4. Detect potential circular imports
+1. Inspect the import graph for cycles — especially base ↔ shim once a shim is in
+   place (`shim` strategy only).
+2. Record any chains in `import_analysis.md`. A pure namespace rename (shimless)
+   preserves the original graph, so cycles there usually mean the project already had
+   them.
+
+## Output
+- `migration/<project-name>/import_analysis.md` with: references by form & group,
+  exported symbols, the chosen strategy + rationale, and circular-import chains (if any).
+- `SHIM_STRATEGY` set in `migration/<project-name>/state.md`.
+
+## Verify
+1. `migration/<project-name>/import_analysis.md` exists and is not empty.
+2. It records all three reference forms, the exported symbols, and any cycles.
+3. `SHIM_STRATEGY` is set in `state.md` (`shim` or `shimless`) with a recorded rationale.
+
+## Commit
+```bash
+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
+> source of truth) — do not hardcode it.

polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-automate-import-updates/SKILL.md

@@ -0,0 +1,76 @@
+---
+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."
+---
+
+# Skill: 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`):
+> - `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
+> `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.
+>
+> 💡 **Script the rewrite for anything non-trivial.** A small text-in → text-out helper
+> (a pure function: file text + an `{old → new}` mapping → rewritten text) handles all
+> three forms — including splitting a mixed bare-import line into moved vs. not-moved
+> 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`.
+
+## Inputs
+- Project name (from `migration/<project-name>/state.md`)
+- Original namespace (from `migration/<project-name>/state.md`)
+- New namespace (from `migration/<project-name>/state.md`)
+- Import analysis report (from `migration/<project-name>/import_analysis.md`)
+
+## Steps
+
+### 1. Identify files in the new base location importing from the original namespace
+1. Review the import analysis report to identify files in the new base location (at `bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}/`) that import from the original namespace.
+
+### 2. Update imports to reference the new namespace
+1. For each file in the new base location that imports from the original namespace:
+   - Replace `from ${ORIG_TOP_NS} import ...` with `from ${TARGET_TOP_NS}.${INITIAL_BASE_NAME}.<module> import ...`
+   - Replace `import ${ORIG_TOP_NS}` with `import ${TARGET_TOP_NS}.${INITIAL_BASE_NAME}`
+
+Example:
+```python
+# Before
+from myproject.core import MyClass
+import myproject.utils
+
+# After
+from mynamespace.mybase.core import MyClass
+import mynamespace.mybase.utils
+```
+
+### 3. Record updated files
+1. Record all updated files in `migration/${PROJECT}/import_updates.md`.
+
+## Output
+- Updated files in the new base location
+- A report file: `migration/<project-name>/import_updates.md` listing all updated files
+
+## Verify
+1. Confirm that all files listed in `migration/<project-name>/import_updates.md` have been updated.
+2. Check that no files in the new base location import from the original namespace.
+3. Verify that the codebase remains functional by running the test command from `migration/<project-name>/state.md`.
+
+## Commit
+```bash
+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.

polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-linter/SKILL.md

@@ -0,0 +1,85 @@
+---
+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."
+---
+
+# Skill: 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.
+
+## When to Skip
+Skip this step if the project's `LINTER` and `FORMATTER` in `migration/<PROJECT>/state.md` already match the workspace's tools.
+
+## Inputs
+From `migration/<PROJECT>/state.md`:
+- `PROJECT_DIR`
+- `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.
+
+## 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.
+
+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?).
+
+### 1. Remove Project-Specific Configs and Dependencies
+- Remove the following sections from the project's `pyproject.toml`:
+  - `[tool.black]`, `[tool.isort]`, `[tool.flake8]`, `[tool.pylint.*]`, `[tool.autopep8]`, `[tool.pycodestyle]`
+- Remove standalone config files: `.flake8`, `.pylintrc`, `.isort.cfg`, and lint sections in `setup.cfg` or `tox.ini`.
+- Remove old linter/formatter dependencies from the project's `pyproject.toml`:
+  - `flake8`, `flake8-*` plugins, `pylint`, `pylint-*` plugins, `black`, `isort`, `autopep8`, `pyflakes`, `pycodestyle`, `bandit`
+
+### 2. Assess Workspace Linting Config
+- Review the workspace root's linting and formatting configuration.
+- Identify any project-specific rules or ignores that differ from the workspace's standards.
+
+### 3. Merge Project-Specific Rules
+- If the project has unique linting rules or ignores, merge them into the workspace root's linting configuration (e.g., `[tool.ruff]`).
+- For conflicts (e.g., stricter rules in the project), ask the user to provide guidance on whether to:
+  - Adopt the project's rules in the workspace.
+  - Suppress the project's rules in favor of the workspace's.
+  - Defer the decision and document the conflict in `migration/<PROJECT>/state.md`.
+
+### 4. Run Workspace Linting and Formatting Tools
+- Run the workspace's linting tool to assess violations:
+  - **Few new violations**: Fix them now.
+  - **Many new violations**: Ask the user whether to fix, suppress, or defer.
+- Run the workspace's formatting tool to reformat the code.
+
+### 5. Update `state.md`
+- Set `LINTER` and `FORMATTER` to the workspace's tool(s).
+- Update `RUN_LINT_CMD` to use the workspace's linting and formatting commands.
+
+## Verify
+- The workspace's linting tool passes (or remaining violations are user-approved).
+- The workspace's formatting tool passes.
+- `RUN_TEST_CMD` succeeds.
+- If set, `RUN_TYPECHECK_CMD` succeeds.
+
+## Common failure modes
+
+| Symptom | Likely cause | Remediation |
+|---------|--------------|-------------|
+| The workspace's linter surfaces hundreds of violations the project's old linter didn't catch | Stricter ruleset; not a "fix everything now" situation. | Ask the user: fix now, suppress via `[tool.<linter>]` ignores in the project subsection, or defer in a follow-up branch. Do **not** auto-fix silently — record the decision in `state.md`. |
+| Project-specific lint rules are stricter than the workspace's standard | Project had higher discipline; lowering it would regress quality. | Add the project's rule as a per-path override in the workspace's lint config (most linters support per-directory rule overrides). Do not weaken the rule globally. |
+| Old linter config file (`.flake8`, `.pylintrc`, etc.) lingers and confuses developers' local editors | Step 1 missed a config file. | Delete it; mention in the commit message so reviewers update their editor configs. |
+
+## Done When
+- No project-specific linter/formatter config files or dependencies remain.
+- Project-specific linting rules are merged into the workspace root's configuration.
+- `LINTER` and `FORMATTER` in `migration/<PROJECT>/state.md` match the workspace's tools.
+- Tests pass via the workspace's tooling.
+
+## Commit
+
+After verification passes, commit this phase to the migration branch:
+
+```bash
+git add -A && git commit -m "migrate(<PROJECT>): phase optional — convert-linter"
+```
+
+Substitute `<PROJECT>` from `state.md`. This is an **optional** skill off the numbered main line, so the commit uses the literal `phase optional` label (no `<N>`). Do not proceed without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.

polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-package-manager/SKILL.md

@@ -0,0 +1,104 @@
+---
+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."
+---
+
+# Skill: 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`.
+
+## Goal
+Convert the project's `pyproject.toml` to PEP 621/uv format and register it as a uv-workspace member. This makes the project share the workspace's single lock file and virtual environment, preventing version skew.
+
+## When to Skip
+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`).
+
+### 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.
+
+## Inputs
+From `migration/<PROJECT>/state.md`:
+- `PROJECT_DIR`
+- `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.
+
+## Steps
+
+### 1. Ask for User Approval
+- Ask the user if they want to convert the project's `pyproject.toml` to PEP 621/uv format.
+- Record their choice in `state.md`:
+  ```text
+  CONVERT_PACKAGE_MANAGER=<yes|no>
+  ```
+
+### 2. Rewrite `pyproject.toml` to PEP 621/uv Format
+- Move `[tool.poetry.dependencies]` to `[project] dependencies`. Keep only **runtime** (non-dev, non-test) dependencies in the project, listed **without version constraints**.
+- Remove Poetry-specific sections: `[tool.poetry]`, `[tool.poetry.group.*]`, `[[tool.poetry.source]]`, and `[build-system]` with `poetry-core`.
+- Add a `[build-system]` with `hatchling` (or the workspace's build backend).
+- Preserve `[tool.*]` sections for other tools (e.g., pytest, ruff, mypy).
+- Add `[tool.uv]` only if project-level uv configuration is needed.
+
+### 3. Register as a Workspace Member
+- Add the project path to the workspace root `pyproject.toml` under `[tool.uv.workspace] members`.
+  Example:
+  ```toml
+  members = ["projects/example-service-b"]
+  ```
+
+### 4. Consolidate Dependencies
+- Add all **third-party runtime dependencies with version constraints** to the workspace root `pyproject.toml` `[project] dependencies`.
+- Move all dev/test/tooling dependencies to the workspace root `[dependency-groups]` (e.g., `dev = [...]`, `test = [...]`).
+- Ensure the project's `pyproject.toml` lists runtime dependencies **without version numbers**.
+
+### 5. Lock and Sync
+- Run `uv lock` from the workspace root to regenerate `uv.lock` with the new member.
+- Run `uv sync` to install all dependencies into the shared `.venv`.
+- Resolve any version conflicts that arise during `uv lock`.
+
+### 6. Delete Old Lock Files
+- Remove `poetry.lock`, `Pipfile.lock`, and generated `requirements*.txt` from the project directory.
+
+### 7. Update Verification Commands
+- Replace any `poetry run`, `pipenv run`, or bare commands with `uv run` equivalents in `migration/<PROJECT>/state.md`.
+  Example:
+  ```text
+  RUN_TEST_CMD=uv run pytest <test-dirs>
+  RUN_LINT_CMD=uv run ruff check <dirs>
+  ```
+- Update `PACKAGE_MANAGER=uv` in `state.md`.
+
+## Verify
+- Run the updated `RUN_TEST_CMD` and confirm the same pass/fail counts as before the conversion.
+- If set, run `RUN_LINT_CMD` and `RUN_TYPECHECK_CMD`.
+- Ensure `uv lock` and `uv sync` succeed from the workspace root.
+
+## Common failure modes
+
+| Symptom | Likely cause | Remediation |
+|---------|--------------|-------------|
+| Workspace root does not use uv (no `[tool.uv.workspace]`, no `uv.lock`) | This skill does not apply — the opinionation gate at the top of this file rules it out. | Stop. Set `CONVERT_PACKAGE_MANAGER=no` in `state.md`. Align the project to the workspace's actual manager (Poetry/PDM/Hatch) via a manual step instead. |
+| `uv lock` fails with "no version satisfies …" after adding the project as a workspace member | Project's old version constraints conflict with the workspace root's pins. | Relax the workspace root's range, or, if the project legitimately needs a different version, pin it explicitly in the project's `pyproject.toml`. As a last resort, exclude the project from the workspace and use a separate environment. |
+| Project depends on a private/internal package that the workspace root doesn't know about | Private index or path-dependency not declared at the root. | Add the dependency (and its source — `[tool.uv.sources]` or `[[tool.uv.index]]`) to the workspace root `pyproject.toml`. |
+
+## Done When
+- The project is listed as a workspace member in the root `pyproject.toml`.
+- `uv lock` and `uv sync` succeed from the workspace root.
+- Old lock files (`poetry.lock`, `Pipfile.lock`, generated `requirements*.txt`) are deleted from the project directory.
+- `PACKAGE_MANAGER=uv` is recorded in `migration/<PROJECT>/state.md`.
+- Verification commands in `state.md` use `uv run`.
+- Tests pass via `uv run`.
+
+## Commit
+
+After verification passes, commit this phase to the migration branch:
+
+```bash
+git add -A && git commit -m "migrate(<PROJECT>): phase optional — convert-package-manager"
+```
+
+Substitute `<PROJECT>` from `state.md`. This is an **optional** skill off the numbered main line, so the commit uses the literal `phase optional` label (no `<N>`). Do not proceed without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.

polylith_cli-1.48.0/polylith_cli/.agents/skills/polylith/migrate-project/migrate-convert-type-checker/SKILL.md

@@ -0,0 +1,83 @@
+---
+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."
+---
+
+# Skill: 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.
+
+## When to Skip
+Skip this step if the project's `TYPE_CHECKER` in `migration/<PROJECT>/state.md` already matches the workspace's type-checking tool.
+
+## Inputs
+From `migration/<PROJECT>/state.md`:
+- `PROJECT_DIR`
+- `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.
+
+## 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.
+
+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?).
+
+### 1. Remove Old Configs and Dependencies
+- Remove the following sections from `pyproject.toml`:
+  - `[tool.mypy]`, `[[tool.mypy.overrides]]`, `[mypy-*]`, `[tool.pyright]`, `[tool.pytype]`
+- Remove standalone config files: `mypy.ini`, `.mypy.ini`, `pyrightconfig.json`.
+- Remove old type checker dependencies from `pyproject.toml`:
+  - `mypy`, `mypy-extensions`, `types-*` stub packages, `pyright`, `pytype`, `sqlalchemy-stubs`, `django-stubs`.
+
+### 2. Clean Up Type Ignore Comments
+- Remove `# type: ignore[<mypy-code>]` comments that reference mypy-specific error codes.
+- Leave comments that suppress real issues and document them in `state.md`.
+
+### 3. Adopt Workspace Type-Checking Config
+- The workspace root `pyproject.toml` may define the type-checking configuration. The project inherits this config.
+- Add project-specific overrides if needed.
+
+### 4. Run the Workspace's Type-Checking Tool
+- Run the workspace's type-checking tool to assess errors:
+  - **Same or fewer errors**: No action needed.
+  - **New errors**: Ask the user whether to fix, suppress, or adjust the config.
+  - **Missing stub errors**: Silence with per-module ignores in the workspace's type-checking config.
+
+### 5. Update `state.md`
+- Set `TYPE_CHECKER` to the workspace's type-checking tool.
+- Update `RUN_TYPECHECK_CMD` to use the workspace's type-checking command.
+
+## Verify
+- The workspace's type-checking tool runs cleanly (or remaining errors are user-approved).
+- `RUN_TEST_CMD` succeeds.
+- If set, `RUN_LINT_CMD` succeeds.
+
+## Common failure modes
+
+| Symptom | Likely cause | Remediation |
+|---------|--------------|-------------|
+| The workspace's checker surfaces type errors the old checker didn't | Stricter type rules expose real bugs that were always there. | Fix the bugs now where cheap (small handful). For systemic gaps, suppress per-module in the workspace's checker config and document the debt in `state.md`. Do **not** blanket-ignore at file scope. |
+| Stub packages (`types-*`, `django-stubs`, `sqlalchemy-stubs`) were required by the old checker but the new one bundles its own | Dependency carryover. | Remove the stub packages from `pyproject.toml`. Re-run the workspace's checker to confirm it picks up its own stubs. |
+| `# type: ignore[<old-code>]` comments still reference the old checker's error codes | Step 2 missed some. | Strip the `[<code>]` bracket. If the suppression is still needed, leave a bare `# type: ignore` **with a comment explaining why**; otherwise remove the suppression entirely. |
+
+## Done When
+- No old type checker config files remain.
+- Old type checker dependencies are removed from `pyproject.toml`.
+- Stale `# type: ignore` comments referencing tool-specific codes are removed (or documented if intentionally kept).
+- `TYPE_CHECKER` in `migration/<PROJECT>/state.md` matches the workspace's type-checking tool.
+- The workspace's type-checking tool runs cleanly or known issues are documented in `state.md`.
+- Tests pass via the workspace's tooling.
+
+## Commit
+
+After verification passes, commit this phase to the migration branch:
+
+```bash
+git add -A && git commit -m "migrate(<PROJECT>): phase optional — convert-type-checker"
+```
+
+Substitute `<PROJECT>` from `state.md`. This is an **optional** skill off the numbered main line, so the commit uses the literal `phase optional` label (no `<N>`). Do not proceed without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.