atelier-python-monorepo_skill

Overview

This skill describes a modern Python monorepo architecture using uv workspaces and mise for version and task orchestration. It explains repo layout, workspace configuration, cross-package imports, and practical commands for dependency management. The guidance focuses on clear dependency direction, single lockfile practices, and shared developer tooling.

How this skill works

The skill inspects and documents how uv manages a unified workspace: a single pyproject.toml root workspace with members, a shared uv.lock, and a consolidated virtual environment. It shows how packages and apps reference each other by distribution name, how mise pins the Python version and defines task runners, and which uv commands install, link, and run tasks across the workspace. It also enforces rules to prevent packages from depending on apps and avoids circular dependencies.

When to use it

• Setting up a new multi-app Python repository that shares libraries across services.
• Migrating multiple small repos into a single monorepo to centralize CI and dependency management.
• Configuring workspace-level tooling like linters, type checkers, and test runners with a single lock file.
• Adding or linking workspace packages and ensuring cross-package imports resolve correctly.
• Standardizing Python version and task definitions across all projects using mise.

Best practices

• Keep one uv.lock at the repository root to ensure reproducible installs across all members.
• Declare shared dev-dependencies (ruff, pytest, type checkers) in the root pyproject dev-dependencies.
• Pin Python in .mise.toml to maintain consistent runtime and tooling versions across CI and developer machines.
• Follow strict dependency direction: apps may depend on packages; packages must never depend on apps.
• Use namespace packages or clear package naming to avoid import collisions and simplify cross-package imports.

Example use cases

• Create an API app that imports domain models from packages/core and utilities from packages/utils.
• Add a new shared library and link it into an existing app with uv add --package my-app.
• Run workspace-wide checks with mise run check that chains lint, typecheck, and test tasks.
• Upgrade dependency versions across the monorepo using uv lock --upgrade and then uv sync to apply.
• Build lightweight multi-stage Docker images for apps by relying on the single lockfile and pinned Python version.