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.

5. Determine tooling-conversion eligibility

Read the workspace root pyproject.toml to determine the workspace's standard linter, formatter, type checker, and package manager.

• 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, polylith-migrate-convert-package-manager does not apply at all — set CONVERT_PACKAGE_MANAGER=no and skip the question below.

6. Create manifest.md

Write migration/<PROJECT>/manifest.md using exactly this template — fixed headings, fixed shapes. Later phases parse this file by heading.

# migration/<PROJECT>/manifest.md

## Directory tree

<output of a `directory_tree` call on `projects/<PROJECT>/`, fenced as a code block>

## Module map

| Path | Role |
|------|------|
| `<relative path>` | <one-line description: "FastAPI route handlers", "Kafka consumer", "domain model", etc.> |

## Entrypoints

- `<path>`: <entrypoint type — FastAPI app / CLI main / Lambda handler / worker run / scheduled job>

## Tests

- Root: `<path>` (relative to project)
- File count: <n>
- Fixture files: `<path>`, `<path>`, …

## Infrastructure

- `<path>`: <type — Dockerfile / k8s manifest / Helm chart / alembic config / deploy script>

⚠ Keep the five ## headings literal. Downstream phases reference them by name; renaming a heading silently breaks input discovery.

7. Present derived values, then confirm with the user

Do not proceed past this step without explicit user confirmation. Present the derived state in one block:

Derived from projects/<PROJECT>/:
  INITIAL_BASE_NAME = <value>     ← initial base name; you will likely add more bases later
  ALIAS             = <value>     ← short alias for poly info/deps tables (optional)
  GROUP             = <value>     ← project group (optional)

Detected tooling:
  PACKAGE_MANAGER = <value>
  LINTER          = <value>
  FORMATTER       = <value>
  TYPE_CHECKER    = <value>

Verification commands:
  RUN_TEST_CMD       = <value>
  RUN_LINT_CMD       = <value or empty>
  RUN_TYPECHECK_CMD  = <value or empty>

Optional conversions you can opt into:
  - Convert linter/formatter to match workspace standard?     (default: no)
  - Convert type checker to match workspace standard?         (default: no)
  - Convert package manager to uv (workspace-uv only)?        (default: no)

Confirm the values above, or correct any of them.

Wait for the user's response. Update state.md with corrections and the CONVERT_* answers.

Common failure modes

Done When

The following artifacts and conditions all hold:

• migration/<PROJECT>/state.md exists and contains every key in the schema (empty values where N/A, but no missing keys).
• migration/<PROJECT>/manifest.md exists with all five sections (directory tree, module map, entrypoints, tests, infrastructure).
• The user has explicitly confirmed INITIAL_BASE_NAME, ALIAS, GROUP, and the three CONVERT_* flags.
• RUN_TEST_CMD is set and runs successfully on the project's current code (the migration's baseline pass-rate), with the Python version reconciled (step 4.2).
• BRICK_IMPORT_MECHANISM is set and the workspace can import <TARGET_TOP_NS>.* (step 4.3).
• GIT_BRANCH and GIT_BASE_SHA are populated (from orchestrator Phase 0).

Commit

After verification passes, commit this phase to the migration branch:

git add -A && git commit -m "migrate(<PROJECT>): phase <N> — discover"

Substitute <PROJECT>, <N>, and <phase-name> from state.md and the orchestrator's phase table. Do not proceed to the next phase without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.