Skip to content

Commit e93625d

Browse files
DavidVujicDavidVujic
committed
feat: add Agent skills
1 parent 9e875ad commit e93625d

15 files changed

Lines changed: 1023 additions & 0 deletions

File tree

‎.agents/skills/polylith/README.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
2+
# Polylith Skills
3+
4+
> **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.
5+
6+
## Available Skills
7+
8+
| Skill | Command | Purpose |
9+
|---------------------------|--------------------|----------------------------------------------------------------------------------------------------------|
10+
| [Workspace Setup](./workspace_setup/SKILL.md) | `poly create workspace` | Initialize a Polylith workspace (`workspace.toml`, top-level dirs). |
11+
| [Component Creation](./component_creation/SKILL.md) | `poly create component` | Create a reusable brick (business logic, domain, capability). |
12+
| [Base Creation](./base_creation/SKILL.md) | `poly create base` | Create an entry-point brick (HTTP API, CLI, Lambda handler). |
13+
| [Project Management](./project_management/SKILL.md) | `poly create project` | Create a deployable project that references bricks. |
14+
| [Brick Removal](./brick_removal/SKILL.md) | — | Safely delete a component or base (no `poly remove` exists). |
15+
| [Sync](./sync/SKILL.md) | `poly sync` | Update each project's brick list to match actual imports. |
16+
| [Workspace Inspection](./workspace_inspection/SKILL.md) | `poly info` | Show brick × project usage (which projects use which bricks). |
17+
| [Dependency Visualization](./dependency_visualization/SKILL.md) | `poly deps` | Show brick × brick dependencies and interface compliance. |
18+
| [Testing](./testing/SKILL.md) | `poly test diff` | List bricks/projects affected by **test-code** changes since a tag. |
19+
| [Diff](./diff/SKILL.md) | `poly diff` | List bricks whose **implementation** changed since a tag. |
20+
| [Check](./check/SKILL.md) | `poly check` | Validate the workspace (CI gate; exits 1 on failure). |
21+
| [Libs](./libs/SKILL.md) | `poly libs` | Inspect third-party libraries per project. |
22+
| [Concepts](./concepts/SKILL.md) | — | Provides foundational knowledge about Polylith architecture and terminology. |
23+
24+
---
25+
26+
## For humans — getting started
27+
28+
1. **Set up the workspace** — [Workspace Setup](./workspace_setup/SKILL.md).
29+
2. **Understand the basics** — [Concepts](./concepts/SKILL.md).
30+
3. **Create bricks** — [Component Creation](./component_creation/SKILL.md) and [Base Creation](./base_creation/SKILL.md).
31+
4. **Create deployable projects** — [Project Management](./project_management/SKILL.md).
32+
5. **Remove bricks safely** — [Brick Removal](./brick_removal/SKILL.md).
33+
6. **Sync brick usage** — [Sync](./sync/SKILL.md).
34+
7. **Inspect** — [Workspace Inspection](./workspace_inspection/SKILL.md) (brick × project) and [Dependency Visualization](./dependency_visualization/SKILL.md) (brick × brick).
35+
8. **Validate** — [Check](./check/SKILL.md) (CI gate) and [Libs](./libs/SKILL.md) (library inspection).
36+
9. **Diff between releases** — [Diff](./diff/SKILL.md) and [Testing](./testing/SKILL.md).

‎.agents/skills/polylith/base_creation/SKILL.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
name: polylith-base-creation
3+
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.
4+
---
5+
6+
# Base Creation Skill
7+
8+
> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *base*, *namespace*, and *theme*. If they're unfamiliar, load `polylith-concepts` first.
9+
10+
## Quick command
11+
12+
```bash
13+
uv run poly create base --name api
14+
```
15+
16+
**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`.
17+
18+
> A **base** is the entry point of a deployable application. For non-entry-point reusable code (business logic, capabilities), use `polylith-component-creation` instead.
19+
20+
## Command reference
21+
22+
| Option | Required | Default | Description |
23+
|-----------------|----------|---------|--------------------------------------------|
24+
| `--name` | yes | — | Name of the base (also the package name). |
25+
| `--description` | no | `""` | Optional human-readable description. |
26+
27+
## What gets created (loose theme)
28+
29+
```
30+
bases/<namespace>/api/
31+
├── __init__.py # Public interface — empty; add re-exports here
32+
└── core.py # Implementation — empty; user fills it in
33+
```
34+
35+
If `[tool.polylith.test].enabled = true` in `workspace.toml`, the CLI also creates `test/bases/<namespace>/api/test_core.py`.
36+
37+
For the `tdd` theme layout (`bases/api/{src,test}/<namespace>/api/...`), load the `polylith-workspace-setup` skill.
38+
39+
## Examples
40+
41+
```bash
42+
# Minimal
43+
uv run poly create base --name api
44+
45+
# With description
46+
uv run poly create base --name consumer --description "Kafka order consumer"
47+
```
48+
49+
## Notes for the agent
50+
- `core.py` is **empty boilerplate** — there is no FastAPI/Typer/Lambda scaffolding. Fill it in manually after creation if asked.
51+
- `__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`.
52+
- 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).
53+
- The same command works for both `loose` and `tdd` themes — the CLI reads `[tool.polylith.structure].theme` from `workspace.toml`.
54+
55+
## Verification
56+
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.

‎.agents/skills/polylith/brick_removal/SKILL.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: polylith-brick-removal
3+
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.
4+
---
5+
6+
# Brick Removal Skill
7+
8+
> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *component*, *base*, and *development project*. If they're unfamiliar, load `polylith-concepts` first.
9+
10+
There is no `poly remove` CLI command. Removing a brick is a manual process.
11+
12+
## Steps to remove a brick
13+
14+
1. **Delete the source code:**
15+
Delete the brick's directory under `components/<namespace>/<name>` or `bases/<namespace>/<name>`.
16+
2. **Delete the tests:**
17+
Delete the brick's test directory under `test/components/<namespace>/<name>` or `test/bases/<namespace>/<name>`.
18+
3. **Remove from projects:**
19+
Search across all `projects/*/pyproject.toml` files and remove the brick from the `[tool.polylith.bricks]` section.
20+
4. **Remove from the development project:**
21+
Remove the brick from the `[tool.polylith.bricks]` section in the root `pyproject.toml` (the development project).
22+
5. **Sync and Check:**
23+
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.
24+
25+
## Notes for the agent
26+
- Always use your directory and file tools to verify the paths before deleting.
27+
- If `poly check` fails after removal, it means another brick was depending on the removed brick. You must fix the importing brick.

‎.agents/skills/polylith/check/SKILL.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
name: polylith-check
3+
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.
4+
---
5+
6+
# Check Skill
7+
8+
## Quick command
9+
10+
```bash
11+
uv run poly check
12+
```
13+
14+
**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`.
15+
16+
> ⚠ **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.
17+
> ⚠ **Exit code 1 = failure** — this is the right command to wrap in CI.
18+
19+
## Typical CI usage
20+
21+
```bash
22+
uv run poly sync --quiet # Make sure brick lists are current (--quiet avoids the interactive prompt)
23+
uv run poly check # Validate; build fails if non-zero
24+
25+
# (Optional) scope test runs to bricks whose implementation changed.
26+
# `poly diff --bricks --short` emits a comma-separated list, which becomes a
27+
# pytest `-k` expression (`log,message` → `pytest -k "log or message"`).
28+
changes="$(uv run poly diff --bricks --short)"
29+
[ -n "$changes" ] && uv run pytest -k "${changes//,/ or }"
30+
```
31+
32+
> 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.
33+
34+
## What it verifies
35+
- Every brick imported by another brick is listed in the consuming project's `[tool.polylith.bricks]`.
36+
- Every third-party library imported by a project's bricks is declared in that project's `dependencies` and present in the lock file.
37+
38+
## Command reference
39+
40+
| Option | Default | Description |
41+
|----------------|---------|---------------------------------------------------------------------------------------------------------|
42+
| `--strict` | `false` | Stricter name/version matching across projects (catches version drift). |
43+
| `--verbose` | `false` | Print extra context, including lock-file lookups. |
44+
| `--quiet` | `false` | Suppress output. Exit code unchanged. |
45+
| `--alias` | — | Comma-separated `import_name=package_name` aliases. |
46+
| `--directory` | cwd | Limit the check to projects whose path matches this directory. |
47+
48+
## Examples
49+
50+
```bash
51+
# Standard CI gate
52+
uv run poly check
53+
54+
# One project only
55+
uv run poly check --directory projects/user_api
56+
```
57+
58+
## Common failure modes & Auto-Fixes
59+
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`).
60+
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`.
61+
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).

‎.agents/skills/polylith/component_creation/SKILL.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
name: polylith-component-creation
3+
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.
4+
---
5+
6+
# Component Creation Skill
7+
8+
> 💡 **Terminology:** this skill uses Polylith terms like *brick*, *component*, *namespace*, and *theme*. If they're unfamiliar, load `polylith-concepts` first.
9+
10+
## Quick command
11+
12+
```bash
13+
uv run poly create component --name user_service
14+
```
15+
16+
**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`.
17+
18+
> 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.
19+
20+
## Command reference
21+
22+
| Option | Required | Default | Description |
23+
|-----------------|----------|---------|---------------------------------------------------|
24+
| `--name` | yes | — | Name of the component (also the package name). |
25+
| `--description` | no | `""` | Optional human-readable description. |
26+
27+
## What gets created (loose theme)
28+
29+
```
30+
components/<namespace>/user_service/
31+
├── __init__.py # Public interface — empty; add re-exports here
32+
└── core.py # Implementation — empty; user fills it in
33+
```
34+
35+
If `[tool.polylith.test].enabled = true` in `workspace.toml`, the CLI also creates `test/components/<namespace>/user_service/test_core.py`.
36+
37+
For the `tdd` theme layout (`components/user_service/{src,test}/<namespace>/user_service/...`), load `polylith-workspace-setup`.
38+
39+
## Examples
40+
41+
```bash
42+
# Minimal
43+
uv run poly create component --name user_service
44+
45+
# With description
46+
uv run poly create component --name greeting --description "Greeting domain"
47+
```
48+
49+
## Notes for the agent
50+
- 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`:
51+
```python
52+
# components/<namespace>/user_service/__init__.py
53+
from <namespace>.user_service.core import create_user, get_user
54+
```
55+
- 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.
56+
- 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`).
57+
58+
## Verification
59+
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.

‎.agents/skills/polylith/concepts/SKILL.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
name: polylith-concepts
3+
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.
4+
---
5+
6+
# Polylith Concepts & Glossary
7+
8+
## Glossary
9+
10+
### Bricks
11+
The fundamental units of code in Polylith — **components** and **bases**. Bricks are reusable, isolated, and organized under a single **namespace**.
12+
13+
### Components
14+
Reusable, isolated bricks that implement business logic or capabilities. Components are consumed by bases and by other components, never the other way around.
15+
16+
### Bases
17+
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.
18+
19+
### Namespace
20+
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.
21+
22+
### Workspace
23+
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.
24+
25+
### Projects
26+
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.
27+
28+
### Development Project
29+
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/`.
30+
31+
### Dependencies
32+
- The **development project** (root `pyproject.toml`) holds **all** dependencies, including dev-only ones.
33+
- Each **project** under `projects/` holds only its **production** dependencies.
34+
- 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.
35+
36+
## Package & Dependency Management mapping
37+
38+
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:
39+
40+
| Tool | Detection signal | Command prefix |
41+
|-------------------------------|------------------------------------------------------------------------|-------------------|
42+
| **uv** (recommended) | `uv.lock` present, or `[tool.uv]` in `pyproject.toml` | `uv run poly …` |
43+
| **Poetry** | `[tool.poetry]` in `pyproject.toml`, `poetry.lock` | `poetry poly …` (via `poetry-polylith-plugin`) |
44+
| **PDM** | `[tool.pdm]` in `pyproject.toml`, `pdm.lock` | `pdm run poly …` |
45+
| **Hatch** | `[tool.hatch]` in `pyproject.toml` | `hatch run poly …`|
46+
| **Rye** | `requirements.lock` + `[tool.rye]` | `rye run poly …` |
47+
| **Activated virtualenv** | `$VIRTUAL_ENV` set, or none of the above | `poly …` |
48+
49+
If multiple signals are present, prefer the lock file that exists, then `[tool.<x>]` markers, then plain `poly`.
50+
51+
## Themes
52+
53+
`[tool.polylith.structure].theme` controls the on-disk brick layout:
54+
55+
- **`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.
56+
- **`tdd`** — each brick is its own directory with `src/` and `test/` siblings.
57+
58+
> The CLI default for `poly create workspace --theme` is **`tdd`**. Always pass `--theme loose` explicitly when loose is wanted.

0 commit comments

Comments
 (0)