polylith-cli 1.45.3__tar.gz → 1.47.0__tar.gz

{polylith_cli-1.45.3 → polylith_cli-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polylith-cli
-Version: 1.45.3
+Version: 1.47.0
 Summary: Python tooling support for the Polylith Architecture
 License: MIT
 Author: David Vujic

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/README.md

@@ -0,0 +1,36 @@
+
+# Polylith Skills
+
+> **Note for contributors:** this README is a **human reference**. The agent loads each `*/SKILL.md` independently via the skill loader; this file is **not** auto-loaded with any skill. Anything an agent must know to act has to live in the relevant `SKILL.md` itself, not here.
+
+## Available Skills
+
+| Skill                     | Command            | Purpose                                                                                                  |
+|---------------------------|--------------------|----------------------------------------------------------------------------------------------------------|
+| [Workspace Setup](./workspace_setup/SKILL.md)             | `poly create workspace` | Initialize a Polylith workspace (`workspace.toml`, top-level dirs).                  |
+| [Component Creation](./component_creation/SKILL.md)       | `poly create component` | Create a reusable brick (business logic, domain, capability).                        |
+| [Base Creation](./base_creation/SKILL.md)                 | `poly create base`      | Create an entry-point brick (HTTP API, CLI, Lambda handler).                         |
+| [Project Management](./project_management/SKILL.md)       | `poly create project`   | Create a deployable project that references bricks.                                  |
+| [Brick Removal](./brick_removal/SKILL.md)                 | —                       | Safely delete a component or base (no `poly remove` exists).                         |
+| [Sync](./sync/SKILL.md)                                   | `poly sync`             | Update each project's brick list to match actual imports.                            |
+| [Workspace Inspection](./workspace_inspection/SKILL.md)   | `poly info`             | Show brick × project usage (which projects use which bricks).                        |
+| [Dependency Visualization](./dependency_visualization/SKILL.md) | `poly deps`       | Show brick × brick dependencies and interface compliance.                            |
+| [Testing](./testing/SKILL.md)                             | `poly test diff`        | List bricks/projects affected by **test-code** changes since a tag.                  |
+| [Diff](./diff/SKILL.md)                                   | `poly diff`             | List bricks whose **implementation** changed since a tag.                            |
+| [Check](./check/SKILL.md)                                 | `poly check`            | Validate the workspace (CI gate; exits 1 on failure).                                |
+| [Libs](./libs/SKILL.md)                                   | `poly libs`             | Inspect third-party libraries per project.                                           |
+| [Concepts](./concepts/SKILL.md)                           | —                       | Provides foundational knowledge about Polylith architecture and terminology.           |
+
+---
+
+## For humans — getting started
+
+1. **Set up the workspace** — [Workspace Setup](./workspace_setup/SKILL.md).
+2. **Understand the basics** — [Concepts](./concepts/SKILL.md).
+3. **Create bricks** — [Component Creation](./component_creation/SKILL.md) and [Base Creation](./base_creation/SKILL.md).
+4. **Create deployable projects** — [Project Management](./project_management/SKILL.md).
+5. **Remove bricks safely** — [Brick Removal](./brick_removal/SKILL.md).
+6. **Sync brick usage** — [Sync](./sync/SKILL.md).
+7. **Inspect** — [Workspace Inspection](./workspace_inspection/SKILL.md) (brick × project) and [Dependency Visualization](./dependency_visualization/SKILL.md) (brick × brick).
+8. **Validate** — [Check](./check/SKILL.md) (CI gate) and [Libs](./libs/SKILL.md) (library inspection).
+9. **Diff between releases** — [Diff](./diff/SKILL.md) and [Testing](./testing/SKILL.md).

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/base_creation/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: polylith-base-creation
+description: Create a Polylith base with `poly create base` — the entry point of a deployable application (HTTP API, CLI, message-queue consumer, AWS Lambda handler, GCP Cloud Function, scheduled job). Use when the user wants to add a service, API, endpoint, handler, or any new entry point to a Polylith workspace.
+---
+
+# Base Creation Skill
+
+> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *base*, *namespace*, and *theme*. If they're unfamiliar, load `polylith-concepts` first.
+
+## Quick command
+
+```bash
+uv run poly create base --name api
+```
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> A **base** is the entry point of a deployable application. For non-entry-point reusable code (business logic, capabilities), use `polylith-component-creation` instead.
+
+## Command reference
+
+| Option          | Required | Default | Description                                |
+|-----------------|----------|---------|--------------------------------------------|
+| `--name`        | yes      | —       | Name of the base (also the package name).  |
+| `--description` | no       | `""`    | Optional human-readable description.       |
+
+## What gets created (loose theme)
+
+```
+bases/<namespace>/api/
+├── __init__.py     # Public interface — empty; add re-exports here
+└── core.py         # Implementation — empty; user fills it in
+```
+
+If `[tool.polylith.test].enabled = true` in `workspace.toml`, the CLI also creates `test/bases/<namespace>/api/test_core.py`.
+
+For the `tdd` theme layout (`bases/api/{src,test}/<namespace>/api/...`), load the `polylith-workspace-setup` skill.
+
+## Examples
+
+```bash
+# Minimal
+uv run poly create base --name api
+
+# With description
+uv run poly create base --name consumer --description "Kafka order consumer"
+```
+
+## Notes for the agent
+- `core.py` is **empty boilerplate** — there is no FastAPI/Typer/Lambda scaffolding. Fill it in manually after creation if asked.
+- `__init__.py` is also empty. By Polylith convention it should re-export the brick's public symbols, so consumers import `from <namespace>.api import …` rather than reaching into `core.py`.
+- A new base is **not** wired into any project. To wire it: load `polylith-sync` and run `poly sync`, or run `poly create project` (the interactive prompt will offer to attach the base).
+- The same command works for both `loose` and `tdd` themes — the CLI reads `[tool.polylith.structure].theme` from `workspace.toml`.
+
+## Verification
+After creation, verify the base exists using your file tools (e.g., check `bases/<namespace>/<name>/__init__.py`). Then, you will likely need to populate `core.py` and `__init__.py` using your file writing tools since they are created empty.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/brick_removal/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: polylith-brick-removal
+description: Safely remove a Polylith brick (component or base) from the workspace. Use when the user wants to delete, remove, or tear down a component or base.
+---
+
+# Brick Removal Skill
+
+> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *component*, *base*, and *development project*. If they're unfamiliar, load `polylith-concepts` first.
+
+There is no `poly remove` CLI command. Removing a brick is a manual process.
+
+## Steps to remove a brick
+
+1. **Delete the source code:**
+   Delete the brick's directory under `components/<namespace>/<name>` or `bases/<namespace>/<name>`.
+2. **Delete the tests:**
+   Delete the brick's test directory under `test/components/<namespace>/<name>` or `test/bases/<namespace>/<name>`.
+3. **Remove from projects:**
+   Search across all `projects/*/pyproject.toml` files and remove the brick from the `[tool.polylith.bricks]` section.
+4. **Remove from the development project:**
+   Remove the brick from the `[tool.polylith.bricks]` section in the root `pyproject.toml` (the development project).
+5. **Sync and Check:**
+   Run `poly sync` (load `polylith-sync`) and `poly check` (load `polylith-check`) to ensure the workspace is valid and no other bricks were importing the deleted brick.
+
+## Notes for the agent
+- Always use your directory and file tools to verify the paths before deleting.
+- If `poly check` fails after removal, it means another brick was depending on the removed brick. You must fix the importing brick.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/check/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: polylith-check
+description: Validate a Polylith workspace with `poly check` — the canonical CI gate. Verifies brick imports against project `pyproject.toml`s, third-party library declarations vs. the lock file, and (under `--strict`) cross-project version consistency. Exits 1 on failure. Use when the user wants to lint, validate, verify, or CI-gate a Polylith workspace.
+---
+
+# Check Skill
+
+## Quick command
+
+```bash
+uv run poly check
+```
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> ⚠ **Run `poly sync` first** if bricks have been added/removed since the last commit, otherwise sync-related findings will dominate the report. Load `polylith-sync` if needed.
+> ⚠ **Exit code 1 = failure** — this is the right command to wrap in CI.
+
+## Typical CI usage
+
+```bash
+uv run poly sync --quiet                          # Make sure brick lists are current (--quiet avoids the interactive prompt)
+uv run poly check                                 # Validate; build fails if non-zero
+
+# (Optional) scope test runs to bricks whose implementation changed.
+# `poly diff --bricks --short` emits a comma-separated list, which becomes a
+# pytest `-k` expression (`log,message` → `pytest -k "log or message"`).
+changes="$(uv run poly diff --bricks --short)"
+[ -n "$changes" ] && uv run pytest -k "${changes//,/ or }"
+```
+
+> Use `poly diff` (implementation diff) for "run tests for what changed". Use `poly test diff --short` if you specifically want to scope on **test-code** changes — load `polylith-testing` for that variant. Both feed the same `pytest -k` recipe.
+
+## What it verifies
+- Every brick imported by another brick is listed in the consuming project's `[tool.polylith.bricks]`.
+- Every third-party library imported by a project's bricks is declared in that project's `dependencies` and present in the lock file.
+
+## Command reference
+
+| Option         | Default | Description                                                                                             |
+|----------------|---------|---------------------------------------------------------------------------------------------------------|
+| `--strict`     | `false` | Stricter name/version matching across projects (catches version drift).                                 |
+| `--verbose`    | `false` | Print extra context, including lock-file lookups.                                                       |
+| `--quiet`      | `false` | Suppress output. Exit code unchanged.                                                                   |
+| `--alias`      | —       | Comma-separated `import_name=package_name` aliases.                                                     |
+| `--directory`  | cwd     | Limit the check to projects whose path matches this directory.                                          |
+
+## Examples
+
+```bash
+# Standard CI gate
+uv run poly check
+
+# One project only
+uv run poly check --directory projects/user_api
+```
+
+## Common failure modes & Auto-Fixes
+1. **Missing Brick Error:** If the error says a brick imports another brick that isn't in `[tool.polylith.bricks]` → run `poly sync` (load `polylith-sync`).
+2. **Missing Dependency Error:** If the error says a brick imports a third-party library not listed in the project's `dependencies` → load `polylith-dependency-management` and add the library to the project's `pyproject.toml`.
+3. **Version Drift Error:** Under `--strict`, if versions of the same library diverge between projects → inspect `pyproject.toml` or load `polylith-libs` to find the drift, then align versions (or rely on a single root lock file).

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/component_creation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: polylith-component-creation
+description: Create a Polylith component with `poly create component` — a reusable, isolated brick implementing business logic, a feature, a domain module, or a capability. Use when adding non-entry-point code that bases or other components will import.
+---
+
+# Component Creation Skill
+
+> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *component*, *namespace*, and *theme*. If they're unfamiliar, load `polylith-concepts` first.
+
+## Quick command
+
+```bash
+uv run poly create component --name user_service
+```
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> A **component** is reusable, non-entry-point code (business logic, domain features, capabilities). For entry points (HTTP API, CLI, Lambda handler), use `polylith-base-creation` instead.
+
+## Command reference
+
+| Option          | Required | Default | Description                                       |
+|-----------------|----------|---------|---------------------------------------------------|
+| `--name`        | yes      | —       | Name of the component (also the package name).    |
+| `--description` | no       | `""`    | Optional human-readable description.              |
+
+## What gets created (loose theme)
+
+```
+components/<namespace>/user_service/
+├── __init__.py     # Public interface — empty; add re-exports here
+└── core.py         # Implementation — empty; user fills it in
+```
+
+If `[tool.polylith.test].enabled = true` in `workspace.toml`, the CLI also creates `test/components/<namespace>/user_service/test_core.py`.
+
+For the `tdd` theme layout (`components/user_service/{src,test}/<namespace>/user_service/...`), load `polylith-workspace-setup`.
+
+## Examples
+
+```bash
+# Minimal
+uv run poly create component --name user_service
+
+# With description
+uv run poly create component --name greeting --description "Greeting domain"
+```
+
+## Notes for the agent
+- Both `core.py` and `__init__.py` are **empty boilerplate**. The component is not "ready" — the user fills in `core.py`, then re-exports its public API from `__init__.py`:
+  ```python
+  # components/<namespace>/user_service/__init__.py
+  from <namespace>.user_service.core import create_user, get_user
+  ```
+- Consumers import via the public interface (`from <namespace>.user_service import create_user`), never via `core.py` directly. `poly deps --interface` (load `polylith-dependency-visualization`) flags violations.
+- A new component is **not** automatically used by any project. It is registered in a project once a base (or another component already in the project) imports it — then run `poly sync` (load `polylith-sync`).
+
+## Verification
+After creation, verify the component exists using your file tools (e.g., check `components/<namespace>/<name>/__init__.py`). Then, you will likely need to populate `core.py` and `__init__.py` using your file writing tools since they are created empty.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/concepts/SKILL.md

@@ -0,0 +1,58 @@
+---
+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.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/dependency_management/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: polylith-dependency-management
+description: Add or manage third-party dependencies in a Polylith workspace. Use when the user wants to install a new library (e.g., requests, fastapi) for a brick or project.
+---
+
+# Dependency Management Skill
+
+> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *project*, and *development project*. If they're unfamiliar, load `polylith-concepts` first.
+
+Polylith manages third-party dependencies differently than standard Python projects.
+
+## Rules for adding dependencies
+
+1. **The Development Project (Root):**
+   **Every** third-party library used anywhere in the workspace must be added to the root `pyproject.toml` (the development project). This ensures local REPLs, tests, and the shared lockfile work correctly. Use your package manager (e.g., `uv add <package>`, `poetry add <package>`) at the workspace root.
+2. **Deployable Projects (`projects/<name>`):**
+   If a library is required for production by a specific deployable project, it must **also** be added to that project's `pyproject.toml` under `projects/<name>/`. Do this by manually editing the `dependencies` array in `projects/<name>/pyproject.toml`.
+
+> ⚠ **Never add dependencies to a brick's directory.** Bricks do not have their own `pyproject.toml` files.
+
+## Example Workflow: Adding `requests` to an `api` project
+
+1. Install it at the root so the lockfile updates and it's available for local development:
+   ```bash
+   uv add requests
+   ```
+2. Manually add it to the deployable project that needs it:
+   Edit `projects/api/pyproject.toml`. 
+   
+   **Important Versioning Rule:** Before adding the dependency to the project, check the root `pyproject.toml`. If it contains a `[tool.uv.workspace]` section (e.g., `members = ["projects/*"]`), then `uv workspaces` is enabled. 
+   
+   If `uv workspaces` is enabled, **do not specify the version** in the project's `pyproject.toml`. Just use the package name, because versions are centrally pinned in the root. If workspaces are not enabled, then you should specify the version.
+   
+   ```toml
+   # WITH uv/poetry workspaces enabled (Recommended):
+   dependencies = [
+       "requests"
+   ]
+   
+   # WITHOUT workspaces enabled:
+   dependencies = [
+       "requests>=2.31.0"
+   ]
+   ```
+3. Run `poly check` (load `polylith-check`) to verify the workspace is valid. `poly check` will catch if a project imports `requests` but forgot to declare it in its `pyproject.toml`.
+
+## Notes for the agent
+- Use `poly libs` (load `polylith-libs`) to inspect current dependency usage across projects.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/dependency_visualization/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: polylith-dependency-visualization
+description: Visualize **brick × brick** dependencies with `poly deps` — find circular dependencies, inspect a brick's public interface, and detect interface-bypass violations. Use for "what depends on what", "circular deps", "interface violation". For brick × project usage, use `polylith-workspace-inspection`.
+---
+
+# Dependency Visualization Skill
+
+## Quick command
+
+```bash
+uv run poly deps
+```
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> **`poly deps` vs `poly info`:**
+> - `poly deps` → **brick × brick** (dependencies between bricks; interface compliance).
+> - `poly info` → **brick × project** (which projects use which brick). Load `polylith-workspace-inspection`.
+> ⚠ `poly deps` does **not** fail on warnings (circular deps, interface violations are informational). For pass/fail, use `poly check` (load `polylith-check`).
+
+## Command reference
+
+| Option         | Default | Description                                                                                  |
+|----------------|---------|----------------------------------------------------------------------------------------------|
+| `--brick`      | —       | Restrict output to the named brick.                                                          |
+| `--interface`  | `false` | Show the brick's public interface and flag bricks that bypass it.                            |
+| `--save`       | `false` | Persist the report to a file under the workspace's output dir.                               |
+| `--directory`  | cwd     | Restrict analysis to projects whose path matches this directory.                             |
+
+## Examples
+
+```bash
+# Full matrix
+uv run poly deps
+
+# One brick + interface compliance check
+uv run poly deps --brick message --interface
+
+# Save report
+uv run poly deps --save
+```
+
+### Output format
+
+```
+                         d   g
+                         a   r           m
+                         t   e           e   s
+                         a   e   k       s   c
+                         b   t   a       s   h
+                         a   i   f   l   a   e
+                         s   n   k   o   g   m
+  brick                  e   g   a   g   e   a
+ ─────────────────────────────────────────────
+  greeting               -   -   -   -   -   -
+  kafka                  -   -   -   ✔   -   -
+  message                ✔   -   ✔   -   -   ✔
+  greet_api              -   ✔   -   ✔   -   -
+```
+
+`✔` = row brick imports column brick.
+
+### Warning messages
+
+```
+ℹ brick_a is used by brick_b and also uses brick_a.        # circular
+ℹ Found in brick_a: helloworld is not part of the public interface of brick_b.   # interface violation
+```
+
+## Fixing an interface violation
+
+When `--interface` reports a violation:
+1. Identify the offending import in the violating brick (e.g. `from <ns>.brick_b.internal import helloworld`).
+2. Add `helloworld` to `<ns>/brick_b/__init__.py`:
+   ```python
+   from <ns>.brick_b.internal import helloworld
+   ```
+3. Update the importer to `from <ns>.brick_b import helloworld`.
+4. Re-run `poly deps --interface` to confirm.
+
+## Notes for the agent
+- Circular deps usually mean two bricks share a concept that should be extracted into a third brick — flag this for the user; don't silently break the cycle by hiding imports.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/diff/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: polylith-diff
+description: List Polylith bricks whose **implementation** changed since a git tag using `poly diff`. Use for release notes, selective deploys ("which projects need rebuilding?"), and PR scope review. For TEST-code diffs, use `polylith-testing` instead.
+---
+
+# Diff Skill
+
+## Quick command
+
+```bash
+# Human-readable (default)
+uv run poly diff
+
+# Pipe-friendly: comma-separated list of changed bricks (use this in scripts)
+uv run poly diff --bricks --short
+```
+
+> **Agent rule of thumb:** when the goal is to *do something* with the result (run pytest, drive a deploy script, render a list), reach for `--bricks --short` first. The default output is for human readers.
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> **`poly diff` vs `poly test diff`:**
+> - `poly diff` → brick **implementation** changes since a tag (drives releases/deploys).
+> - `poly test diff` → **test-code** changes since a tag (drives selective test runs). Load `polylith-testing`.
+
+## Tag selection
+- Default: latest git tag matching `[tool.polylith.tag.patterns].stable` from `workspace.toml` (e.g. `stable-*`).
+- `--since <ref>` — pin a specific tag, branch, or commit-ish. The CLI tries to resolve `<ref>` as a configured pattern key first, then falls through to using it literally with `git diff <ref>`.
+
+## Command reference
+
+| Option       | Default             | Description                                                                                                |
+|--------------|---------------------|------------------------------------------------------------------------------------------------------------|
+| `--since`    | latest matching tag | Reference tag (or branch/commit) to diff against.                                                          |
+| `--short`    | `false`             | Compact output. Combined with `--bricks`, emits a comma-separated list of brick names — pipe-friendly.     |
+| `--bricks`   | `false`             | Print the list of bricks that changed (human-readable on its own; CSV when paired with `--short`).         |
+| `--deps`     | `false`             | With `--bricks`, also print bricks that **depend on** the changed bricks (transitive impact).              |
+
+## Examples
+
+```bash
+# Default: against latest stable-* tag
+uv run poly diff
+
+# Selective deploy: every brick changed (incl. transitive consumers) since a release tag
+uv run poly diff --since stable-4 --bricks --deps
+
+# Pipe-friendly: comma-separated names of bricks changed vs. main
+uv run poly diff --since main --bricks --short
+```
+
+## Running tests for changed bricks
+
+The established Polylith pattern is to feed `--bricks --short` straight into `pytest -k`: brick names become an `or`-expression that pytest matches against test IDs, so the agent doesn't need to resolve namespace / theme / base-vs-component.
+
+```bash
+changes="$(uv run poly diff --bricks --short)"
+[ -n "$changes" ] && uv run pytest -k "${changes//,/ or }"
+```
+
+Example: `--bricks --short` outputs `log,message` → pytest runs as `pytest -k "log or message"`, collecting every test whose ID contains `log` or `message` (matches `test/components/<ns>/log/...` and `test/bases/<ns>/log/...` alike).
+
+> ⚠ `pytest -k` does **substring** matching, so a brick named `log` will also match tests whose name contains `log` (e.g. an unrelated `logger` brick or a `test_login` function). For short/generic brick names, fall back to passing explicit test directories.
+
+## Notes for the agent
+- Operates on git's view of the working tree — uncommitted changes since the tag count as changed.
+- If no matching tag exists and `--since` isn't passed, the command prints `No matching tags or commits found in repository.` and exits 0. Guard scripts so they don't run `pytest -k ""` (which would collect nothing or, worse, every test depending on the version).
+- Map changed bricks → projects with `poly info` (load `polylith-workspace-inspection`) to drive selective deploys.

polylith_cli-1.47.0/polylith_cli/.agents/skills/polylith/libs/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: polylith-libs
+description: Inspect third-party libraries used per Polylith project with `poly libs`. Use when the user wants to see dependency usage, audit version drift across projects, find which projects use a given library, or compare library declarations vs. the lock file. Read-only — for a CI gate use `polylith-check` instead.
+---
+
+# Libs Skill
+
+## Quick command
+
+```bash
+uv run poly libs
+```
+
+**Command prefix:** If you do not know the package manager, list lock files with `ls uv.lock poetry.lock pdm.lock 2>/dev/null` (a `pyproject.toml` is always present, so it tells you nothing on its own). Use `uv run poly` (uv), `poetry poly` (poetry), `pdm run poly` (pdm), `hatch run poly` (hatch), or `poly` (activated venv). Examples below use `uv run`.
+
+> `poly libs` **reports**; `poly check` **fails the build**. Use `libs` for inspection, `check` for CI (load `polylith-check`).
+
+## Prerequisites
+- A Polylith workspace with at least one project.
+- A lock file at the root (`uv.lock`, `poetry.lock`, or `pdm.lock`).
+
+## Command reference
+
+| Option         | Default | Description                                                                                            |
+|----------------|---------|--------------------------------------------------------------------------------------------------------|
+| `--strict`     | `false` | Stricter matching of names and versions across projects.                                               |
+| `--directory`  | cwd     | Limit output to projects whose path matches this directory.                                            |
+| `--alias`      | —       | Comma-separated `import_name=package_name` aliases.                                                    |
+| `--short`      | `false` | Compact view — useful for wide workspaces.                                                             |
+| `--save`       | `false` | Persist the report to a file under the workspace's output dir.                                         |
+
+## Examples
+
+```bash
+# Full library × project matrix
+uv run poly libs
+
+# Strict version-drift detection
+uv run poly libs --strict
+
+# Compact view for many projects
+uv run poly libs --short
+```
+
+## How to read it
+- Rows are third-party libraries; columns are projects.
+- `✔` = the library is used by that project.
+- A library used by multiple projects with **different versions** = version drift. Fix by aligning versions in the relevant project `pyproject.toml`s, or by relying on a central lock file (uv workspaces).
+
+## Notes for the agent
+- `poly libs` is **read-only** — it never modifies `pyproject.toml` or the lock file.