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.
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_DIRLINTER, FORMATTERRUN_TEST_CMD (optional: RUN_LINT_CMD, RUN_TYPECHECK_CMD)
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 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?).
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:
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.
1---2name: polylith-migrate-convert-linter3description: [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.4---56# Skill: polylith-migrate-convert-linter78## Goal9Align 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.1011## When to Skip12Skip this step if the project's `LINTER` and `FORMATTER` in `migration/<PROJECT>/state.md` already match the workspace's tools.1314## Inputs15From `migration/<PROJECT>/state.md`:16- `PROJECT_DIR`17- `LINTER`, `FORMATTER`18- `RUN_TEST_CMD` (optional: `RUN_LINT_CMD`, `RUN_TYPECHECK_CMD`)1920> All inputs from `state.md` are assumed to satisfy the validation rules in `polylith-migrate-discover` (`### Validation rules`). Validate before proceeding.2122## Steps2324### 0. Identify the workspace's tool25Open 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.2627If the workspace has no linter configured at all, stop and ask the user how to proceed (introduce ruff? skip linting alignment? abort the conversion?).2829### 1. Remove Project-Specific Configs and Dependencies30- Remove the following sections from the project's `pyproject.toml`:31 - `[tool.black]`, `[tool.isort]`, `[tool.flake8]`, `[tool.pylint.*]`, `[tool.autopep8]`, `[tool.pycodestyle]`32- Remove standalone config files: `.flake8`, `.pylintrc`, `.isort.cfg`, and lint sections in `setup.cfg` or `tox.ini`.33- Remove old linter/formatter dependencies from the project's `pyproject.toml`:34 - `flake8`, `flake8-*` plugins, `pylint`, `pylint-*` plugins, `black`, `isort`, `autopep8`, `pyflakes`, `pycodestyle`, `bandit`3536### 2. Assess Workspace Linting Config37- Review the workspace root's linting and formatting configuration.38- Identify any project-specific rules or ignores that differ from the workspace's standards.3940### 3. Merge Project-Specific Rules41- If the project has unique linting rules or ignores, merge them into the workspace root's linting configuration (e.g., `[tool.ruff]`).42- For conflicts (e.g., stricter rules in the project), ask the user to provide guidance on whether to:43 - Adopt the project's rules in the workspace.44 - Suppress the project's rules in favor of the workspace's.45 - Defer the decision and document the conflict in `migration/<PROJECT>/state.md`.4647### 4. Run Workspace Linting and Formatting Tools48- Run the workspace's linting tool to assess violations:49 - **Few new violations**: Fix them now.50 - **Many new violations**: Ask the user whether to fix, suppress, or defer.51- Run the workspace's formatting tool to reformat the code.5253### 5. Update `state.md`54- Set `LINTER` and `FORMATTER` to the workspace's tool(s).55- Update `RUN_LINT_CMD` to use the workspace's linting and formatting commands.5657## Verify58- The workspace's linting tool passes (or remaining violations are user-approved).59- The workspace's formatting tool passes.60- `RUN_TEST_CMD` succeeds.61- If set, `RUN_TYPECHECK_CMD` succeeds.6263## Common failure modes6465| Symptom | Likely cause | Remediation |66|---------|--------------|-------------|67| 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`. |68| 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. |69| 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. |7071## Done When72- No project-specific linter/formatter config files or dependencies remain.73- Project-specific linting rules are merged into the workspace root's configuration.74- `LINTER` and `FORMATTER` in `migration/<PROJECT>/state.md` match the workspace's tools.75- Tests pass via the workspace's tooling.7677## Commit7879After verification passes, commit this phase to the migration branch:8081```bash82git add -A && git commit -m "migrate(<PROJECT>): phase optional — convert-linter"83```8485Substitute `<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.
davidvujic