polylith-concepts - SKILL.md Agent Skill

name: polylith-concepts description: Provides foundational knowledge about Polylith architecture, including the glossary (bases, components, projects, workspaces), theme layouts, and package manager mapping. Use this when you need to understand Polylith terminology or how the repository is structured conceptually before taking action.

Polylith Concepts & Glossary

Glossary

Bricks

The fundamental units of code in Polylith — components and bases. Bricks are reusable, isolated, and organized under a single namespace.

Components

Reusable, isolated bricks that implement business logic or capabilities. Components are consumed by bases and by other components, never the other way around.

Bases

Bricks that serve as the entry point of a deployable application — for example HTTP APIs, CLIs, message-queue consumers, AWS Lambda handlers, GCP Cloud Functions, or scheduled jobs. A base wires together components and exposes the application to its runtime.

Namespace

The top-level Python package name under which all bricks live (e.g. mycompany). Defined once in [tool.polylith].namespace in workspace.toml; shared by every brick.

Workspace

The root directory of a Polylith repository. Contains workspace.toml, the root pyproject.toml (which is the development project), the bases/, components/, projects/, and development/ directories, and a single shared lock file.

Projects

Lightweight pyproject.toml configurations under projects/<name>/ that reference bricks to produce deployable artifacts (Docker images, wheels, Lambda packages). Projects contain no Python source code of their own.

Development Project

The root pyproject.toml itself — a single, unified Python environment that includes every brick and every dependency (production and dev). Used for local development, REPL sessions, and notebooks under development/.

Dependencies

The development project (root pyproject.toml) holds all dependencies, including dev-only ones.
Each project under projects/ holds only its production dependencies.
With uv workspaces, individual projects don't need to pin third-party versions — the root pyproject.toml and the shared lock file pin versions centrally.

Package & Dependency Management mapping

The poly CLI is package-manager-agnostic — only the command prefix changes. Each SKILL.md repeats the prefix detection rule inline so the agent doesn't need this README to act. The full table:

Tool	Detection signal	Command prefix
uv (recommended)	`uv.lock` present, or `[tool.uv]` in `pyproject.toml`	`uv run poly …`
Poetry	`[tool.poetry]` in `pyproject.toml`, `poetry.lock`	`poetry poly …` (via `poetry-polylith-plugin`)
PDM	`[tool.pdm]` in `pyproject.toml`, `pdm.lock`	`pdm run poly …`
Hatch	`[tool.hatch]` in `pyproject.toml`	`hatch run poly …`
Rye	`requirements.lock` + `[tool.rye]`	`rye run poly …`
Activated virtualenv	`$VIRTUAL_ENV` set, or none of the above	`poly …`

If multiple signals are present, prefer the lock file that exists, then [tool.<x>] markers, then plain poly.

Themes

[tool.polylith.structure].theme controls the on-disk brick layout:

loose (recommended) — flat <bricks_dir>/<namespace>/<brick>/ directories with tests in a top-level test/ folder. Used by python-polylith itself and by most public examples.
tdd — each brick is its own directory with src/ and test/ siblings.

The CLI default for poly create workspace --theme is tdd. Always pass --theme loose explicitly when loose is wanted.