Polylith Migrate Discover

Skill: polylith-migrate-discover

Goal

Inspect the project and create two artifacts that drive every subsequent migration phase:

• migration/<PROJECT>/state.md — a flat KEY=value file (see schema below).
• migration/<PROJECT>/manifest.md — a human-readable structural inventory.

💡 <PROJECT> is the project subfolder name (e.g., api for projects/api/). Use that exact string everywhere — paths, filenames, branch names.

Canonical state.md schema

All later skills read state.md as a flat KEY=value file. Use exactly this format — no markdown tables, no fenced TOML, no inline comments. One key per line.

# migration/<PROJECT>/state.md
PROJECT_DIR=projects/<PROJECT>
ORIG_TOP_NS=<current import namespace>
TARGET_TOP_NS=<desired Polylith namespace, defaults to ORIG_TOP_NS>
INITIAL_BASE_NAME=<snake_case base name for the temporary migration base>
ALIAS=<short kebab-case alias for poly info/deps tables, or empty>
GROUP=<polylith project group, or empty>

PACKAGE_MANAGER=<poetry|pipenv|pip|uv|setuptools>
LINTER=<flake8|pylint|ruff|none>
FORMATTER=<black|isort|ruff|none>
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 (polylith-migrate-analyze-imports); may be empty at discover>

CONVERT_LINTER=<yes|no>
CONVERT_TYPE_CHECKER=<yes|no>
CONVERT_PACKAGE_MANAGER=<yes|no>

RUN_TEST_CMD=<full command to run tests>
RUN_LINT_CMD=<full command to run linting, or empty>
RUN_TYPECHECK_CMD=<full command to run type checking, or empty>

GIT_BRANCH=<migration branch name created in orchestrator Phase 0>
GIT_BASE_SHA=<commit SHA of the migration branch start point>

Field reference

Deriving INITIAL_BASE_NAME and ALIAS from [project.name]

Validation rules

When any later phase loads state.md, validate before proceeding:

1. File exists at migration/<PROJECT>/state.md.
2. Format: every line is one of: blank, # comment, or KEY=value. No markdown tables, no fenced TOML, no inline comments after a value.
3. Schema coverage: every key from the schema above is present. A value may be empty (for optional keys), but the key line must exist.
4. Enumerations: PACKAGE_MANAGER, LINTER, FORMATTER, TYPE_CHECKER, BRICK_IMPORT_MECHANISM, SHIM_STRATEGY (when set), and the three CONVERT_* flags use only the documented values.
5. Required non-empty: PROJECT_DIR, ORIG_TOP_NS, TARGET_TOP_NS, INITIAL_BASE_NAME, PACKAGE_MANAGER, POLY_CMD_PREFIX, BRICK_IMPORT_MECHANISM, RUN_TEST_CMD, GIT_BRANCH, GIT_BASE_SHA must all be non-empty. (SHIM_STRATEGY may be empty until phase 2 sets it.)
6. Consistency: POLY_CMD_PREFIX matches PACKAGE_MANAGER per the mapping table.

If validation fails, abort the phase, surface the offending line(s) to the user, and ask them to fix state.md before retrying. Never silently coerce values.

Steps

Run these in order. Every step writes to state.md or manifest.md. Do not skip the confirmation gates (steps 4 and 7).

1. Record project metadata

Read projects/<PROJECT>/pyproject.toml (or setup.cfg/setup.py) and fill in PROJECT_DIR, ORIG_TOP_NS, TARGET_TOP_NS, and the derived INITIAL_BASE_NAME, ALIAS per the tables above.

2. Detect tooling

Scan project config files and fill in PACKAGE_MANAGER, LINTER, FORMATTER, TYPE_CHECKER:

3. Derive POLY_CMD_PREFIX

Map PACKAGE_MANAGER to the command prefix:

4. Discover verification commands

1. Check for Virtualenv: Verify if the project has a virtualenv or if dependencies are installed. For example:

   • For uv: Check for uv.lock or .venv. If no virtualenv exists, guide the user to run uv sync.
   • For pdm: Run pdm venv list to check for a virtualenv. If none exists, guide the user to run pdm install.
   • For poetry: Run poetry env list to check for a virtualenv. If none exists, guide the user to run poetry install.
   • For pip: Check if a venv or .venv directory exists. If not, guide the user to create and activate one.

2. Reconcile the Python version: Compare the project's requires-python with the workspace's (requires-python in the root pyproject.toml and the root .python-version). If they disagree (e.g. project >=3.13, workspace >=3.12), the baseline test command can silently resolve the wrong interpreter. Resolve before establishing the baseline by either:

   • aligning the workspace (bump the root requires-python / .python-version) — confirm with the user, as it affects every project; or
   • recording a per-command interpreter override in the verification commands (e.g. uv run --python 3.13 …).

3. Establish the brick-import mechanism: Tests and entrypoints import bricks as <TARGET_TOP_NS>.<brick> from bases/ and components/. Confirm the workspace actually exposes them — this is a prerequisite for RUN_TEST_CMD to work after code is moved into a base (phase 3+). Inspect the root pyproject.toml:

   • If the root project is editable-installed so the namespace resolves (e.g. Hatch dev-mode-dirs = ["components","bases","development", …] and the root is actually installed — not [tool.uv] package = false), set BRICK_IMPORT_MECHANISM=editable-root.
   • Otherwise add pythonpath = ["bases","components","development"] to the root [tool.pytest.ini_options] and set BRICK_IMPORT_MECHANISM=pytest-pythonpath.
   • Sanity-check in the workspace env: <package-manager> run python -c "import <TARGET_TOP_NS>" (once at least one brick exists, e.g. after phase 3). It must succeed.

   ⚠ Common trap: a root pyproject.toml with both dev-mode-dirs and [tool.uv] package = false looks configured but installs nothing — <TARGET_TOP_NS>.* is then unimportable and every post-extract-to-base test run fails with ModuleNotFoundError: No module named '<TARGET_TOP_NS>'. Prefer pytest-pythonpath (it avoids changing the install model), or make the root installable.

4. Verify RUN_TEST_CMD: Run the test command in the project's directory to ensure it works.

   ⚠ You are executing untrusted code. Running the project's tests and the install/sync commands below executes arbitrary code from the project (e.g. setup.py, conftest.py, build hooks) and from resolved third-party packages (post-install scripts). Only run these on a project the user trusts; do not proceed on an unknown or untrusted codebase.

   For example:

   • For uv: Run uv run pytest tests --collect-only -q | tail -1. If the command fails, guide the user to install test dependencies (e.g., uv sync --extra tests).
   • For pdm: Run pdm run pytest tests --collect-only -q | tail -1. If the command fails, guide the user to install test dependencies (e.g., pdm install --group tests).
   • For poetry: Run poetry run pytest tests --collect-only -q | tail -1. If the command fails, guide the user to install test dependencies (e.g., poetry install --with tests).
   • For pip: Run python -m pytest tests --collect-only -q | tail -1. If the command fails, guide the user to install test dependencies (e.g., pip install -e ".[tests]").

5. Record Baseline: Record the baseline test count (e.g., number of tests collected) in state.md. If the command differs (e.g., python -m pytest), update RUN_TEST_CMD to match the working command.

6. Inspect Config Files: Inspect Makefile, Justfile, tox.ini, pyproject.toml [tool.pytest.ini_options], and CI config (.github/workflows/*.yml, .circleci/config.yml, etc.) to identify the project's existing commands. Fill RUN_TEST_CMD, and RUN_LINT_CMD / RUN_TYPECHECK_CMD when present. If a command can't be found, leave the value empty.

   🔒 Never store secrets in state.md. state.md is committed. When a derived command embeds a credential (an inline token, a --token=… flag, a database URL with a password, an API key), do not copy the literal value. Reference the environment variable name instead (e.g. RUN_TEST_CMD=DATABASE_URL=$DATABASE_URL uv run pytest …), and have the user supply the secret via their environment at run time. Redact any literal credential before writing the file. The same applies to manifest.md — it captures structure, not secrets.

7. Proceed Only After Verification: Only proceed to the next phase if RUN_TEST_CMD succeeds. If it fails, guide the user to resolve the issue before continuing.