agentme 0.5.0 → 0.6.0

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

@@ -14,10 +14,11 @@ 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.
+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
 
@@ -42,54 +43,130 @@ Create these files first.
 
 ```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
 
 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)" uv sync --project "$$dir" --frozen || exit 1; \
+			UV_PROJECT_ENVIRONMENT="$(UV_PROJECT_ENVIRONMENT)" UV_CACHE_DIR="$(UV_CACHE_DIR)" 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)" 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.
+
+If the repository already uses Mise, wrap the delegated commands with `mise exec --` and pin both Python and uv in `.mise.toml`.
+
+**`./.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 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.
+
+**`lib/Makefile`**
+
+```makefile
+SHELL := /bin/bash
+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:
+	uv sync --project . --frozen --all-extras --dev
+
+build: install
+	rm -rf dist
+	uv build --project . --out-dir dist
 
-test-examples:
-	@if [ -d examples ]; then $(MAKE) -C examples test PACKAGE_NAME=$(PACKAGE_NAME); else echo "No examples/ directory. Skipping"; fi
+lint: install
+	uv run --project . ruff format --check .
+	uv run --project . ruff check .
+	uv run --project . pyright
+	uv run --project . pip-audit
 
-run:
-	uv run python -m $(PACKAGE_NAME)
+lint-fix: install
+	uv run --project . ruff format .
+	uv run --project . ruff check . --fix
+	uv run --project . pyright
+	uv run --project . pip-audit
+
+test-unit: install
+	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
+	uv run --project . python -m $(PACKAGE_NAME)
 
 dev: run
 
 update-lockfile:
-	uv lock --upgrade
+	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 +207,7 @@ select = ["E", "F", "I", "B", "UP"]
 
 [tool.pyright]
 include = ["src", "tests"]
-venvPath = "."
+venvPath = ".."
 venv = ".venv"
 typeCheckingMode = "standard"
 
@@ -139,28 +216,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.
+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.
 
-**`./.gitignore`**
+**`lib/README.md`**
 
-```gitignore
-.venv/
-dist/
-build/
-.pytest_cache/
-.ruff_cache/
-.coverage
-htmlcov/
-__pycache__/
-*.pyc
-```
+This README is the published package README referenced by `lib/pyproject.toml`.
 
-**`./README.md`**
-
-Put Getting Started near the top.
-
-```markdown
+````markdown
 # [package-name]
 
 [description]
@@ -177,13 +240,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 +262,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 +285,7 @@ if __name__ == "__main__":
     main()
 ```
 
-**`tests/test_core.py`**
+**`lib/tests/test_core.py`**
 
 ```python
 from [package_name].core import hello
@@ -224,26 +295,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.
-
-### Phase 4: Create examples for libraries and utilities
+If two or more test files need shared fixtures, create `lib/tests/conftest.py` and move shared setup there.
 
-If the project is a library or shared utility, add an `examples/` directory and execute it from the root `test` target.
+If the module needs slower end-to-end coverage, place those tests in `lib/tests_integration/`. Put dedicated benchmark harnesses in `lib/tests_benchmark/`.
 
-**`examples/Makefile`**
+### Phase 5: Create examples for libraries and utilities
 
-```makefile
-test:
-	$(MAKE) -C basic-usage run PACKAGE_NAME=$(PACKAGE_NAME)
-```
+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.
 
-**`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,13 +325,13 @@ 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`.
+1. Run `make install`.
 2. Run `make lint-fix`.
 3. Run `make test`.
 4. Run `make build`.
@@ -268,19 +340,21 @@ After creating the files:
 ## 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.
 - 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,7 +76,11 @@ 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.
 
@@ -84,7 +103,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 +123,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 |

package/.xdrs/agentme/edrs/devops/skills/002-monorepo-setup/SKILL.md

@@ -14,11 +14,11 @@ metadata:
 ## Overview
 
 Creates or extends a monorepo that follows the standard layout from [agentme-edr-005](../../005-monorepo-structure.md):
-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.
+top-level application folders, independent module roots, sibling example and multi-module test
+areas, 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.
 
-Related EDRs: [agentme-edr-005](../../005-monorepo-structure.md), [agentme-edr-013](../../../governance/013-contributing-guide-requirements.md)
+Related EDRs: [agentme-edr-005](../../005-monorepo-structure.md), [agentme-edr-013](../../../governance/013-contributing-guide-requirements.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -51,10 +51,12 @@ golangci-lint = "1.57"
 Coordinates `build`, `lint`, and `test` across all applications. Also exposes a `setup` target.
 
 ```makefile
-.PHONY: build lint test setup
+.PHONY: all build lint test clean setup
 
 APPS := <app1> <app2>   # replace with actual application names
 
+all: build lint test
+
 build:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) build &&) true
 
@@ -64,12 +66,25 @@ lint:
 test:
 	$(foreach app,$(APPS),$(MAKE) -C $(app) test &&) true
 
+clean:
+   $(foreach app,$(APPS),$(MAKE) -C $(app) clean &&) true
+   rm -rf .cache
+
 setup:
 	@echo "Install Mise: https://mise.jdx.dev/getting-started.html"
 	@echo "Then run: mise install"
 	@echo "See README.md for full setup instructions."
 ```
 
+#### Root `.gitignore`
+
+Must ignore shared artifact and cache folders:
+
+```gitignore
+dist/
+.cache/
+```
+
 #### Root `README.md`
 
 Must include four sections:
@@ -162,10 +177,12 @@ For each application:
 3. **Create `<app>/Makefile`** that delegates to each module:
 
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
 
    MODULES := <module1> <module2>   # replace with actual module names
 
+   all: build lint test
+
    build:
    	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) build &&) true
 
@@ -174,10 +191,16 @@ For each application:
 
    test:
    	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) test &&) true
+
+   clean:
+   	$(foreach mod,$(MODULES),$(MAKE) -C $(mod) clean &&) true
+   	rm -rf .cache
    ```
 
 4. **Create `<app>/shared/`** — leave empty if no cross-module shared code exists yet.
 
+5. **Create sibling aggregation folders when needed**: `<app>/examples/`, `<app>/tests_integration/`, and `<app>/tests_benchmark/` for artifacts that apply to multiple modules.
+
 ---
 
 ### Phase 5: Scaffold each module
@@ -186,11 +209,15 @@ For each module inside an application:
 
 1. **Create the module folder** using lowercase, hyphen-separated names (e.g., `data-loader`).
 
-2. **Create `<app>/<module>/Makefile`** with the three required targets, adapted to the module's language:
+2. **Create `<app>/<module>/README.md`** with consumer usage first and short developer commands at the end.
+
+3. **Create `<app>/<module>/Makefile`** with the common targets, adapted to the module's language. Redirect persistent caches into `.cache/` and write distributable artifacts to `dist/`.
 
    **Go:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	go build ./...
@@ -200,11 +227,16 @@ For each module inside an application:
 
    test:
    	go test ./... -cover
+
+   clean:
+	rm -rf dist .cache
    ```
 
    **Node.js / TypeScript:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	npm run build
@@ -214,11 +246,16 @@ For each module inside an application:
 
    test:
    	npm test
+
+   clean:
+	rm -rf dist .cache
    ```
 
    **Python:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   all: build lint test
 
    build:
    	pip install -e .
@@ -228,9 +265,14 @@ For each module inside an application:
 
    test:
    	pytest
+
+   clean:
+	rm -rf dist .cache
    ```
 
-3. **Add source files** appropriate to the language, placing them inside the module folder.
+4. **Add source files** appropriate to the language, placing them inside the module folder.
+
+5. **Place module-specific integration tests and benchmarks predictably**: `<module>/tests_integration/` and `<module>/tests_benchmark/` when they are not co-located by language convention.
 
 ---
 
@@ -242,8 +284,10 @@ After scaffolding, run the following checks and fix any issues:
 - `make lint` at the repository root passes.
 - `make test` at the repository root passes.
 - All folder and file names are lowercase and use hyphens.
+- The root `.gitignore` ignores `dist/` and `.cache/`.
 - A `CONTRIBUTING.md` exists at the repository root and covers bugs, feature discussions, pull requests, Conventional Comments, and small focused changes.
 - Every application folder has a `README.md` covering all four required sections.
+- Every module folder has a `README.md`, `Makefile`, `dist/` location, and `.cache/` strategy.
 - A `.mise.toml` exists at the repository root with all required tool versions pinned.
 
 ---
@@ -256,8 +300,10 @@ After scaffolding, run the following checks and fix any issues:
 pcb-devices/
 ├── README.md
 ├── Makefile
+├── examples/
 ├── shared/
 └── firmware/
+   ├── README.md
     └── Makefile
 ```
 

package/.xdrs/agentme/edrs/index.md

@@ -13,6 +13,7 @@ Foundational standards, principles, and guidelines.
 - [agentme-edr-007](principles/007-project-quality-standards.md) - **Project quality standards**
 - [agentme-edr-009](principles/009-error-handling.md) - **Error handling**
 - [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy**
+- [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure**
 
 ## Articles