agentme 0.5.0 → 0.7.0

package/.xdrs/agentme/edrs/application/skills/005-create-python-project/SKILL.md

@@ -13,11 +13,12 @@ compatibility: Python 3.12+
 
 ## Overview
 
-Creates a complete Python project from scratch using `uv`, `pyproject.toml`, Ruff, Pyright,
-Pytest, and Makefiles. The default layout uses `src/<package_name>/`, `tests/`, and `examples/`
-for libraries and shared utilities.
+Creates a complete Python project from scratch using Mise, `uv`, `pyproject.toml`, Ruff,
+Pyright, Pytest, and Makefiles. The default layout keeps the library self-contained under `lib/`,
+uses a shared root `.venv/`, redirects persistent caches into `.cache/`, and places runnable
+consumer projects under the sibling `examples/` folder.
 
-Related EDR: [agentme-edr-014](../../014-python-project-tooling.md)
+Related EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -38,58 +39,149 @@ Ask for or infer from context:
 
 Create these files first.
 
+**`./.mise.toml`**
+
+```toml
+[tools]
+python = "3.13"
+uv = "latest"
+```
+
+Replace `3.13` with the chosen Python version and pin any additional project CLIs used by the project here.
+
 **`./Makefile`**
 
 ```makefile
 SHELL := /bin/bash
-
-PACKAGE_NAME ?= your_package
 MISE := mise exec --
+ROOT_DIR := $(abspath .)
+export UV_PROJECT_ENVIRONMENT := $(ROOT_DIR)/.venv
+export UV_CACHE_DIR := $(ROOT_DIR)/.cache/uv
 
 all: build lint test
 
+setup:
+	mise install
+	$(MAKE) install
+
 install:
-	uv sync --frozen --all-extras --dev
+	$(MAKE) -C lib install
 
-build: install
-	uv build
+build:
+	$(MAKE) -C lib build
 
 lint:
-	uv run ruff format --check .
-	uv run ruff check .
-	uv run pyright
-	uv run pip-audit
+	$(MAKE) -C lib lint
 
 lint-fix:
-	uv run ruff format .
-	uv run ruff check . --fix
-	uv run pyright
-	uv run pip-audit
+	$(MAKE) -C lib lint-fix
 
 test: test-unit test-examples
 
 test-unit:
-	uv run pytest --cov=src/$(PACKAGE_NAME) --cov-branch --cov-report=term-missing --cov-fail-under=80
+	$(MAKE) -C lib test-unit
+
+test-examples: build
+	@for dir in examples/*; do \
+		if [ -f "$$dir/pyproject.toml" ]; then \
+			echo ">>> Running $$dir"; \
+			UV_PROJECT_ENVIRONMENT="$(UV_PROJECT_ENVIRONMENT)" UV_CACHE_DIR="$(UV_CACHE_DIR)" $(MISE) uv sync --project "$$dir" --frozen || exit 1; \
+			UV_PROJECT_ENVIRONMENT="$(UV_PROJECT_ENVIRONMENT)" UV_CACHE_DIR="$(UV_CACHE_DIR)" $(MISE) uv pip install --python "$(UV_PROJECT_ENVIRONMENT)/bin/python" lib/dist/*.whl || exit 1; \
+			UV_PROJECT_ENVIRONMENT="$(UV_PROJECT_ENVIRONMENT)" UV_CACHE_DIR="$(UV_CACHE_DIR)" $(MISE) uv run --project "$$dir" python main.py || exit 1; \
+		fi; \
+	done
+
+clean:
+	$(MAKE) -C lib clean
+	rm -rf .cache
+	rm -rf .venv
+```
+
+The root `Makefile` keeps the repository clean by delegating package work to `lib/` and treating each example directory as an independent consumer project. Child Makefiles own the actual `mise exec -- <tool>` calls.
+
+**`./.gitignore`**
+
+```gitignore
+.venv/
+dist/
+.cache/
+```
+
+**`./README.md`**
+
+Keep this README focused on the repository or workspace. Put Getting Started near the top.
+
+````markdown
+# [package-name]
+
+[description]
+
+## Getting Started
+
+```sh
+make setup
+make test
+```
+
+The published package lives in `lib/` and runnable consumer examples live in `examples/`.
+````
+
+### Phase 3: Create `lib/`
+
+`lib/` contains everything the library needs: source, tests, package metadata, lockfile, build
+artifacts, and library-specific Makefile targets.
 
-test-examples:
-	@if [ -d examples ]; then $(MAKE) -C examples test PACKAGE_NAME=$(PACKAGE_NAME); else echo "No examples/ directory. Skipping"; fi
+**`lib/Makefile`**
 
-run:
-	uv run python -m $(PACKAGE_NAME)
+```makefile
+SHELL := /bin/bash
+MISE := mise exec --
+ROOT_DIR := $(abspath ..)
+export UV_PROJECT_ENVIRONMENT := $(ROOT_DIR)/.venv
+export UV_CACHE_DIR := $(ROOT_DIR)/.cache/uv
+export RUFF_CACHE_DIR := $(abspath .cache/ruff)
+export PYTHONPYCACHEPREFIX := $(abspath .cache/pycache)
+export COVERAGE_FILE := $(abspath .cache/coverage)
+
+PACKAGE_NAME ?= your_package
+
+all: build lint test-unit
+
+install:
+	$(MISE) uv sync --project . --frozen --all-extras --dev
+
+build: install
+	rm -rf dist
+	$(MISE) uv build --project . --out-dir dist
+
+lint: install
+	$(MISE) uv run --project . ruff format --check .
+	$(MISE) uv run --project . ruff check .
+	$(MISE) uv run --project . pyright
+	$(MISE) uv run --project . pip-audit
+
+lint-fix: install
+	$(MISE) uv run --project . ruff format .
+	$(MISE) uv run --project . ruff check . --fix
+	$(MISE) uv run --project . pyright
+	$(MISE) uv run --project . pip-audit
+
+test-unit: install
+	$(MISE) uv run --project . pytest -o cache_dir=.cache/pytest --cov=src/$(PACKAGE_NAME) --cov-branch --cov-report=term-missing --cov-report=html:.cache/htmlcov --cov-fail-under=80
+
+run: install
+	$(MISE) uv run --project . python -m $(PACKAGE_NAME)
 
 dev: run
 
 update-lockfile:
-	uv lock --upgrade
+	$(MISE) uv lock --project . --upgrade
 
 clean:
-	rm -rf .venv dist .pytest_cache .ruff_cache .coverage htmlcov
-	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+	rm -rf dist .cache
 ```
 
-If the repository already uses Mise, adapt the commands to `$(MISE) uv ...` and pin both Python and uv in `.mise.toml`.
-
-**`./pyproject.toml`**
+**`lib/pyproject.toml`**
 
 Replace placeholders such as `[package-name]`, `[description]`, `[author]`, and `[python-version]`.
 
@@ -130,7 +222,7 @@ select = ["E", "F", "I", "B", "UP"]
 
 [tool.pyright]
 include = ["src", "tests"]
-venvPath = "."
+venvPath = ".."
 venv = ".venv"
 typeCheckingMode = "standard"
 
@@ -139,28 +231,14 @@ testpaths = ["tests"]
 addopts = "-q"
 ```
 
-Use `pyproject.toml` as the single configuration file. Do not add `requirements.txt`,
-`setup.py`, `setup.cfg`, `ruff.toml`, or `pyrightconfig.json` by default.
-
-**`./.gitignore`**
-
-```gitignore
-.venv/
-dist/
-build/
-.pytest_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-__pycache__/
-*.pyc
-```
+Use `lib/pyproject.toml` as the single configuration file for the package. Do not add
+`requirements.txt`, `setup.py`, `setup.cfg`, `ruff.toml`, or `pyrightconfig.json` by default.
 
-**`./README.md`**
+**`lib/README.md`**
 
-Put Getting Started near the top.
+This README is the published package README referenced by `lib/pyproject.toml`.
 
-```markdown
+````markdown
 # [package-name]
 
 [description]
@@ -168,7 +246,7 @@ Put Getting Started near the top.
 ## Getting Started
 
 ```sh
-uv sync --dev
+make setup
 make test
 ```
 
@@ -177,13 +255,21 @@ from [package-name] import hello
 
 print(hello("world"))
 ```
+
+## Development
+
+```sh
+make build
+make lint
+make test
 ```
+````
 
-### Phase 3: Create the package and tests
+### Phase 4: Create the package and tests inside `lib/`
 
 Create this baseline structure.
 
-**`src/[package_name]/__init__.py`**
+**`lib/src/[package_name]/__init__.py`**
 
 ```python
 from .core import hello
@@ -191,14 +277,14 @@ from .core import hello
 __all__ = ["hello"]
 ```
 
-**`src/[package_name]/core.py`**
+**`lib/src/[package_name]/core.py`**
 
 ```python
 def hello(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-**`src/[package_name]/__main__.py`**
+**`lib/src/[package_name]/__main__.py`**
 
 Use this only for CLI-oriented projects.
 
@@ -214,7 +300,7 @@ if __name__ == "__main__":
     main()
 ```
 
-**`tests/test_core.py`**
+**`lib/tests/test_core.py`**
 
 ```python
 from [package_name].core import hello
@@ -224,26 +310,27 @@ def test_hello() -> None:
     assert hello("world") == "Hello, world!"
 ```
 
-If two or more test files need shared fixtures, create `tests/conftest.py` and move shared setup there.
+If two or more test files need shared fixtures, create `lib/tests/conftest.py` and move shared setup there.
 
-### Phase 4: Create examples for libraries and utilities
+If the module needs slower end-to-end coverage, place those tests in `lib/tests_integration/`. Put dedicated benchmark harnesses in `lib/tests_benchmark/`.
 
-If the project is a library or shared utility, add an `examples/` directory and execute it from the root `test` target.
+### Phase 5: Create examples for libraries and utilities
 
-**`examples/Makefile`**
+If the project is a library or shared utility, add an `examples/` directory with one subdirectory per runnable consumer example. Each example must be its own Python project.
 
-```makefile
-test:
-	$(MAKE) -C basic-usage run PACKAGE_NAME=$(PACKAGE_NAME)
-```
-
-**`examples/basic-usage/Makefile`**
+**`examples/basic-usage/pyproject.toml`**
 
-```makefile
-run:
-	uv run python main.py
+```toml
+[project]
+name = "basic-usage"
+version = "0.0.0"
+requires-python = ">=[python-version]"
+dependencies = []
 ```
 
+The root `test-examples` target installs the wheel built into `lib/dist/` before running each
+example. Do not point examples back to `../../lib` or `lib/src/`.
+
 **`examples/basic-usage/main.py`**
 
 ```python
@@ -253,34 +340,37 @@ from [package_name] import hello
 print(hello("world"))
 ```
 
-Examples must import the built package as a consumer would. Avoid relative imports back into `src/`.
+Examples must import the package as a consumer would. Avoid relative imports back into `lib/src/`.
 
-### Phase 5: Verify
+### Phase 6: Verify
 
 After creating the files:
 
-1. Run `uv lock`.
-2. Run `make lint-fix`.
-3. Run `make test`.
-4. Run `make build`.
-5. Fix all failures before finishing.
+1. Run `make setup`.
+2. Run `make install`.
+3. Run `make lint-fix`.
+4. Run `make test`.
+5. Run `make build`.
+6. Fix all failures before finishing.
 
 ## Examples
 
 **Input:** "Create a Python library called `event_tools`"
-- Create `pyproject.toml`, `Makefile`, `src/event_tools/`, `tests/`, and `examples/`
+- Create `Makefile`, `README.md`, `lib/pyproject.toml`, `lib/Makefile`, `lib/src/event_tools/`, `lib/tests/`, and `examples/`
+- Add `lib/README.md`, `.cache/` handling, and install examples from the built wheel in `lib/dist/`
 - Configure `uv`, Ruff, Pyright, Pytest, `pytest-cov`, and `pip-audit`
 - Verify with `make lint-fix`, `make test`, and `make build`
 
 **Input:** "Scaffold a Python CLI package"
-- Add `src/<package_name>/__main__.py`
-- Add `[project.scripts]` in `pyproject.toml` when the command name must differ from the module name
+- Add `lib/src/<package_name>/__main__.py`
+- Add `[project.scripts]` in `lib/pyproject.toml` when the command name must differ from the module name
 - Keep the same Makefile and quality checks
 
 ## Edge Cases
 
-- If the repository already has a root `.mise.toml`, pin Python and uv there instead of assuming host-installed tools.
+- Pin Python and uv in the root `.mise.toml`; do not assume host-installed tools.
 - If the project is fewer than 100 lines and explicitly marked as a spike or experiment, examples and linting may be skipped only when another applicable XDR allows it.
+- If an example needs extra dependencies, keep them in that example's `pyproject.toml`; do not move them into `lib/pyproject.toml` unless the library truly needs them.
 - If the user asks for an app with framework-specific needs such as FastAPI or Django, keep this baseline and add the framework config on top instead of replacing it.
 
 ## References

package/.xdrs/agentme/edrs/devops/005-monorepo-structure.md

@@ -13,9 +13,10 @@ What monorepo structure, naming conventions, tooling, and build standards should
 
 ## Decision Outcome
 
-**Adopt a standardized monorepo layout with top-level application folders, a shared library area, Mise-managed tooling, and Makefiles at every level so any contributor can build, lint, and test any part of the monorepo with a single, predictable command.**
+**Adopt a standardized monorepo layout with top-level application folders that aggregate independent module roots, shared parent-level example and test areas, Mise-managed tooling, and Makefiles at every level.**
 
 For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/002-monorepo-setup/SKILL.md).
+Module folder responsibilities, artifact locations, and test-folder conventions follow [agentme-edr-016](../principles/016-cross-language-module-structure.md).
 
 ### Policies
 
@@ -23,16 +24,26 @@ For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/
 
 ```
 /
+├── .cache/               # Optional shared cache for repo-level tooling
 ├── shared/               # Resources shared across ALL applications
 │   ├── libs/             # Reusable libraries consumed by applications
 │   └── scripts/          # Build/CI/dev scripts used across applications
 │
 ├── <application>/        # One folder per application or project
 │   ├── README.md         # REQUIRED
-│   ├── <module>/         # One folder per compilable module
+│   ├── Makefile          # REQUIRED
+│   ├── <module>/         # One folder per buildable/publishable module
+│   │   ├── Makefile      # REQUIRED
+│   │   ├── README.md     # REQUIRED
+│   │   ├── dist/         # REQUIRED when the module publishes/builds artifacts
+│   │   └── .cache/       # REQUIRED when caches are not shared above
+│   ├── examples/         # Optional sibling consumer examples for modules in this app
+│   ├── tests_integration/# Optional cross-module integration tests for this app
+│   ├── tests_benchmark/  # Optional cross-module benchmarks for this app
 │   └── shared/           # Resources shared by modules within THIS application
 │
 ├── Makefile              # Root Makefile coordinating all areas
+├── .gitignore            # MUST ignore dist/ and .cache/
 ├── README.md             # REQUIRED — onboarding and quickstart guide
 └── .mise.toml            # Mise tool version configuration
 ```
@@ -42,6 +53,7 @@ For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/
 - Represent a cohesive unit with its own lifecycle (e.g., `mymobileapp`, `graph-visualizer`).
 - **MUST** depend only on resources in `/shared/`. Direct cross-application dependencies are forbidden; use published artifacts (container images, published libraries) instead.
 - **MUST** contain a `README.md` with: purpose, architecture overview, how to build, and how to run.
+- **MAY** contain `examples/`, `tests_integration/`, and `tests_benchmark/` when those artifacts apply to multiple modules inside the application.
 
 *Why:* Isolating applications prevents implicit coupling and makes the `shared/` boundary explicit and intentional.
 
@@ -50,6 +62,9 @@ For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/
 - A module is a subfolder inside an application that is independently compilable and produces a build artifact.
 - May depend on sibling modules within the same application or on `/shared/` resources.
 - **MUST NOT** depend on modules from other applications.
+- **MUST** contain its own `Makefile`, `README.md`, and language/tooling configuration.
+- **MUST** keep build outputs under `dist/` and persistent caches under `.cache/`, following [agentme-edr-016](../principles/016-cross-language-module-structure.md).
+- **MUST NOT** keep consumer examples inside the module folder; those belong in a sibling `examples/` folder at the nearest parent aggregation root.
 
 #### 4. Naming conventions
 
@@ -61,9 +76,14 @@ For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/
 
 A `Makefile` **MUST** be present at the repository root, in every application folder, and in every module folder.
 
-Each Makefile **MUST** define at minimum: `build`, `lint`, and `test` targets.
+All Makefiles **MUST** use the shared target vocabulary from [agentme-edr-008](008-common-targets.md).
+
+Repository, application, and module Makefiles **MUST** define at minimum: `all`, `build`, `lint`, `test`, and `clean`.
+
+Module Makefiles **SHOULD** also provide `lint-fix` and `install` when the underlying tooling supports them.
 
 The root `Makefile` **MUST** also define a `setup` target that guides a new contributor to prepare their machine.
+The root `setup` target **MUST** run `mise install` and any small repository bootstrap required before routine targets work.
 
 *Why:* Makefiles provide a universal, stack-agnostic entry point regardless of programming language.
 
@@ -72,11 +92,11 @@ The root `Makefile` **MUST** also define a `setup` target that guides a new cont
 - [Mise](https://mise.jdx.dev/) **MUST** be used to pin all tool versions (compilers, runtimes, CLI tools).
 - A `.mise.toml` **MUST** exist at the repository root.
 - Every language runtime or CLI referenced by any module `Makefile`, CI workflow, or README command **MUST** be pinned in `.mise.toml`.
-- Contributors run `mise install` once after cloning.
+- Contributors and CI run `make setup` after cloning or checkout; this target must call `mise install`.
 - Agents and contributors **MUST** check `.mise.toml` before using a system-installed compiler, runtime, or CLI.
-- When `.mise.toml` exists, all build, test, lint, and code-generation commands **MUST** run inside the Mise-managed environment, preferably via `mise exec -- <command>` or an activated Mise shell.
+- When `.mise.toml` exists, all build, test, lint, and code-generation commands **MUST** run through `make <target>`, and the Makefile recipes **MUST** execute the underlying tools via `mise exec -- <command>`.
 - If a required tool is missing, the first remediation step **MUST** be to update `.mise.toml` or run `mise install`, not to install ad-hoc global tools with language-specific installers such as `go install`, `npm install -g`, `pip install --user`, or `cargo install`.
-- Root and module `Makefile` targets **SHOULD** work correctly when invoked through `mise exec -- make <target>`.
+- Root and module `Makefile` targets **MUST** work when invoked as plain `make <target>` after `make setup`.
 
 *Why:* Eliminates "works on my machine" build failures by ensuring identical tool versions across all environments.
 
@@ -84,7 +104,11 @@ The root `Makefile` **MUST** also define a `setup` target that guides a new cont
 
 The root `README.md` **MUST** include: overview, machine setup, quickstart, and a repository map.
 
-#### 8. Git tagging and artifact versioning
+#### 8. Root `.gitignore`
+
+The repository root **MUST** ignore `dist/` and `.cache/` so module artifacts and tool caches are never committed accidentally.
+
+#### 9. Git tagging and artifact versioning
 
 All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g., `graphvisualizer/renderer/1.0.0`, `shared/libs/mylib/2.1.0`).
 
@@ -100,10 +124,14 @@ All releases **MUST** be tagged using the format `<module-name>/<semver>` (e.g.,
 |---|---|---|
 | Lowercase folder/file names | All | Yes |
 | `README.md` per application | Application folders | Yes |
-| `Makefile` with `build`, `lint`, `test` | All modules and applications | Yes |
+| `README.md` per module | Module folders | Yes |
+| `Makefile` with `all`, `build`, `lint`, `test`, `clean` | Root, applications, modules | Yes |
 | Root `Makefile` with `setup` target | Repository root | Yes |
 | Root `README.md` with setup + quickstart | Repository root | Yes |
+| Ignore `dist/` and `.cache/` | Repository root | Yes |
 | Mise `.mise.toml` at root | Repository root | Yes |
 | Applications depend only on `/shared/` | Application folders | Yes |
 | Modules depend only on siblings or `/shared/` | Module folders | Yes |
+| Module outputs live in `dist/` | Module folders | Yes |
+| Persistent caches live in `.cache/` | Repo or module folders | Yes |
 | Git tags follow `<module-name>/<semver>` format | All modules | Yes |