Polylith Migrate Prepare Project

Skill: polylith-migrate-prepare-project

Goal

Clean up the project subfolder (projects/<PROJECT>/) and consolidate dependencies. After this step, the project subfolder should contain only:

• Project pyproject.toml (with brick references).
• Task runners (Makefile, Justfile).
• Project-specific config (e.g., alembic.ini and its alembic/ directory).
• Compatibility shim (only when SHIM_STRATEGY=shim).

Inputs

From migration/<PROJECT>/state.md:

• PROJECT_DIR
• TARGET_TOP_NS
• ALIAS (optional: GROUP)
• Verification commands.

From migration/<PROJECT>/manifest.md:

• Infra files list.

All inputs from state.md are assumed to satisfy the validation rules in polylith-migrate-discover (### Validation rules). Validate before proceeding.

Steps

1. Verify Project Subfolder

• Run directory_tree on projects/${PROJECT}/ to confirm only infra and config files remain.

2. Update pyproject.toml

• Add brick references to [tool.polylith.bricks]:

  [tool.polylith.bricks]
  "../../bases/${TARGET_TOP_NS}/${INITIAL_BASE_NAME}" = "${TARGET_TOP_NS}/${INITIAL_BASE_NAME}"

• Register the project alias and group in workspace.toml (if provided):

  [tool.polylith.projects.alias]
  ${PROJECT} = "${ALIAS}"
  
  [tool.polylith.projects.groups]
  ${GROUP} = ["${PROJECT}"]

3. Move Tests to Workspace Level

• Move tests/ to test/<test-dir>/, where <test-dir> is a valid Python package name. ⚠ ${PROJECT} frequently contains hyphens (e.g. order-management-api), which are illegal in a package name and break pytest's package-style import. Derive an underscore name — the workspace's <svc>_service convention is a good default (e.g. order_management_service). Record <test-dir> in state.md.
• If the moved tests import the old package by name (e.g. from tests.fixtures import … / from tests.helpers import …), rewrite those to the new name (from <test-dir>.fixtures import …). Brick imports (<TARGET_TOP_NS>.*) are absolute and need no change.
• Update RUN_TEST_CMD in migration/${PROJECT}/state.md to point to the new location.
• Update mock patch strings in test files if paths changed.

Per-brick test redistribution (test/<theme>/<ns>/<brick>/) is handled later in polylith-migrate-refactor-tests — this step only lifts tests to the workspace level. See that skill for the shared-helper / namespace-merge caveats before splitting further.

4. Move Infrastructure Folders

• Move deployment infra folders (e.g., helm/, k8s/, kustomize/, skaffold/) to infra/<folder>/${PROJECT}/.
• 🔒 Secret & .gitignore check before the move. Infra folders frequently carry secret material (e.g. values-secret.yaml, *.env, sealed-secret sources, TLS keys). Two hazards when relocating them:
  • .gitignore scope shifts. Ignore rules scoped to the old path stop matching at the new infra/<folder>/${PROJECT}/ path, so a previously-ignored secret file can become tracked after the move. Verify the destination is still covered by .gitignore for anything that was ignored at the source.
  • Inline secrets. Scan the moved manifests/values for inline credentials before committing. Do not commit newly-tracked secrets; have the user move them to an ignored path or a secret manager first.
• Keep alembic/ together with alembic.ini in the project — do not split them. alembic.ini's script_location points at alembic/ relatively, and alembic/env.py imports the project's bricks; separating them breaks migrations. (Alembic is project-specific config, which the project subfolder is allowed to keep.) ⚠ alembic.ini commonly holds a sqlalchemy.url with DB credentials — if it is not already tracked, do not newly commit it with a literal credential; reference an env var instead.
• ⚠ Deploy-path breakage: moving infra breaks deploy scripts / skaffold / CI that hardcode the old paths. If you cannot verify the deploy in the migration environment (no deploy / manifest-diff cycle available), it is acceptable to defer the infra move and document it in state.md rather than relocate blindly. Otherwise, update the referencing scripts and record the change. Prefer updating references over committing a symlink: a committed symlink can point outside the repo and behaves inconsistently across checkouts/OSes — if you must use one as a transition, keep it within the repo, record it in state.md, and schedule its removal.