agentme 0.3.3 → 0.6.0

package/.xdrs/agentme/edrs/application/skills/003-create-golang-project/SKILL.md

@@ -12,9 +12,9 @@ compatibility: Go 1.21+
 
 ## Overview
 
-Creates a complete Go CLI project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md). Business logic lives in named feature packages; CLI wiring lives in `cli/<feature>/`; `main.go` is a thin dispatcher. The project builds cross-platform static binaries via a Makefile.
+Creates a complete Go CLI project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md). Business logic lives in named feature packages; CLI wiring lives in `cli/<feature>/`; `main.go` is a thin dispatcher. The module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
 
-Related EDR: [agentme-edr-010](../../010-golang-project-tooling.md)
+Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -83,11 +83,16 @@ func main() {
 SHELL := /bin/bash
 
 BINARY := [binary]
+CACHE_DIR := .cache
+export GOCACHE := $(abspath $(CACHE_DIR)/go-build)
+export GOMODCACHE := $(abspath $(CACHE_DIR)/go-mod)
+export GOLANGCI_LINT_CACHE := $(abspath $(CACHE_DIR)/golangci-lint)
 
 all: build lint test
 
 build: install
 	@mkdir -p dist
+	@mkdir -p $(GOCACHE) $(GOMODCACHE)
 	go build -o dist/$(BINARY) .
 
 build-all: build-arch-os-darwin-amd64 build-arch-os-darwin-arm64 build-arch-os-linux-amd64 build-arch-os-linux-arm64 build-arch-os-windows-amd64
@@ -113,6 +118,7 @@ build-arch-os:
 	@if [ "${ARCH}" == "" ]; then echo "ENV ARCH is required"; exit 1; fi
 	@echo "Compiling $(BINARY) for ${OS}-${ARCH}..."
 	@mkdir -p dist/${OS}-${ARCH}
+	@mkdir -p $(GOCACHE) $(GOMODCACHE)
 	go mod download
 	GOOS=${OS} GOARCH=${ARCH} CGO_ENABLED=0 go build -a -o dist/${OS}-${ARCH}/$(BINARY) .
 	@echo "Done"
@@ -130,15 +136,16 @@ test:
 	go test -cover ./...
 
 test-coverage:
-	go test -coverprofile=coverage.out ./...
-	go tool cover -func coverage.out
+	@mkdir -p $(CACHE_DIR)
+	go test -coverprofile=$(CACHE_DIR)/coverage.out ./...
+	go tool cover -func $(CACHE_DIR)/coverage.out
 
 benchmark:
 	go test -bench . -benchmem -count 5 ./...
 
 clean:
 	rm -rf dist
-	rm -f coverage.out
+	rm -rf .cache
 
 start:
 	go run ./ [subcommand]
@@ -164,6 +171,7 @@ run:
 
 ```
 dist/
+.cache/
 coverage.out
 *.pprof
 .DS_Store
@@ -182,10 +190,10 @@ coverage.out
 
 ## Development
 
-    make build    # compile binary to dist/
-    make lint     # run golangci-lint
-    make test     # run tests with coverage
-    make start    # run locally with default args
+	make build    # compile binary to dist/
+	make lint     # run golangci-lint with cache in .cache/
+	make test     # run tests with coverage artifacts in .cache/
+	make start    # run locally with default args
 ```
 
 ---
@@ -306,6 +314,8 @@ Fix any compile or lint errors before finishing.
 - Business logic only in `[feature]/` packages — no flag parsing, no `fmt.Println` for diagnostics.
 - `cli/[feature]/` owns flags, output, and calls domain. No logic here beyond reading flags and printing results.
 - All tests co-located (`*_test.go` next to the file under test).
+- Use `tests_integration/` for integration flows and `tests_benchmark/` when benchmarks need dedicated harnesses or datasets.
 - Log with `logrus`; never use `fmt.Println` for diagnostic/debug output.
 - All development tasks go through `make` targets — never run `go` directly for routine ops.
 - Do not create an `internal/` package unless explicitly justified (importability is preferred).
+- If the project is a reusable library, place consumer examples in a sibling `examples/` folder outside the module root and keep them on the public module import path.

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

@@ -0,0 +1,363 @@
+---
+name: 005-create-python-project
+description: >
+  Scaffolds the initial boilerplate structure for a Python library or CLI project following the
+  standard tooling and layout defined in agentme-edr-014. Activate this skill when the user asks
+  to create, scaffold, or initialize a new Python package, CLI, library, or similar project
+  structure.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+compatibility: Python 3.12+
+---
+
+## Overview
+
+Creates a complete Python project from scratch using `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 EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+
+## Instructions
+
+### Phase 1: Gather information
+
+Ask for or infer from context:
+
+- **Package name** - Python distribution/import name, e.g. `my_tool`
+- **Short description** - one sentence
+- **Author** name or GitHub username
+- **Python version** - default `3.13`
+- **Project kind** - `library` or `cli`
+- **Primary entry point** - first module or command name to scaffold
+- **GitHub repo URL** - optional, for project metadata
+- **Confirm target directory** - default: current workspace root
+
+### Phase 2: Create root files
+
+Create these files first.
+
+**`./Makefile`**
+
+```makefile
+SHELL := /bin/bash
+ROOT_DIR := $(abspath .)
+export UV_PROJECT_ENVIRONMENT := $(ROOT_DIR)/.venv
+export UV_CACHE_DIR := $(ROOT_DIR)/.cache/uv
+
+all: build lint test
+
+install:
+	$(MAKE) -C lib install
+
+build:
+	$(MAKE) -C lib build
+
+lint:
+	$(MAKE) -C lib lint
+
+lint-fix:
+	$(MAKE) -C lib lint-fix
+
+test: test-unit test-examples
+
+test-unit:
+	$(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
+
+lint: install
+	uv run --project . ruff format --check .
+	uv run --project . ruff check .
+	uv run --project . pyright
+	uv run --project . pip-audit
+
+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 --project . --upgrade
+
+clean:
+	rm -rf dist .cache
+```
+
+**`lib/pyproject.toml`**
+
+Replace placeholders such as `[package-name]`, `[description]`, `[author]`, and `[python-version]`.
+
+```toml
+[project]
+name = "[package-name]"
+version = "0.0.1"
+description = "[description]"
+readme = "README.md"
+requires-python = ">=[python-version]"
+dependencies = []
+
+[[project.authors]]
+name = "[author]"
+
+[project.optional-dependencies]
+dev = []
+
+[dependency-groups]
+dev = [
+  "pip-audit>=2.9.0",
+  "pyright>=1.1.400",
+  "pytest>=8.4.0",
+  "pytest-cov>=6.1.0",
+  "ruff>=0.11.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.pyright]
+include = ["src", "tests"]
+venvPath = ".."
+venv = ".venv"
+typeCheckingMode = "standard"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+```
+
+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.
+
+**`lib/README.md`**
+
+This README is the published package README referenced by `lib/pyproject.toml`.
+
+````markdown
+# [package-name]
+
+[description]
+
+## Getting Started
+
+```sh
+uv sync --dev
+make test
+```
+
+```python
+from [package-name] import hello
+
+print(hello("world"))
+```
+
+## Development
+
+```sh
+make build
+make lint
+make test
+```
+````
+
+### Phase 4: Create the package and tests inside `lib/`
+
+Create this baseline structure.
+
+**`lib/src/[package_name]/__init__.py`**
+
+```python
+from .core import hello
+
+__all__ = ["hello"]
+```
+
+**`lib/src/[package_name]/core.py`**
+
+```python
+def hello(name: str) -> str:
+    return f"Hello, {name}!"
+```
+
+**`lib/src/[package_name]/__main__.py`**
+
+Use this only for CLI-oriented projects.
+
+```python
+from .core import hello
+
+
+def main() -> None:
+    print(hello("world"))
+
+
+if __name__ == "__main__":
+    main()
+```
+
+**`lib/tests/test_core.py`**
+
+```python
+from [package_name].core import hello
+
+
+def test_hello() -> None:
+    assert hello("world") == "Hello, world!"
+```
+
+If two or more test files need shared fixtures, create `lib/tests/conftest.py` and move shared setup there.
+
+If the module needs slower end-to-end coverage, place those tests in `lib/tests_integration/`. Put dedicated benchmark harnesses in `lib/tests_benchmark/`.
+
+### Phase 5: Create examples for libraries and utilities
+
+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/pyproject.toml`**
+
+```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
+from [package_name] import hello
+
+
+print(hello("world"))
+```
+
+Examples must import the package as a consumer would. Avoid relative imports back into `lib/src/`.
+
+### Phase 6: Verify
+
+After creating the files:
+
+1. Run `make install`.
+2. Run `make lint-fix`.
+3. Run `make test`.
+4. Run `make build`.
+5. Fix all failures before finishing.
+
+## Examples
+
+**Input:** "Create a Python library called `event_tools`"
+- 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 `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
+
+- [agentme-edr-014](../../014-python-project-tooling.md)
+- [_core-adr-003 - Skill standards](../../../../../_core/adrs/principles/003-skill-standards.md)

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

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-005-monorepo-structure
+description: Defines the standard monorepo layout, naming, and build conventions using shared areas, Mise, and Makefiles. Use when creating or reviewing monorepos.
+---
+
 # agentme-edr-005: Monorepo structure
 
 ## Context and Problem Statement
@@ -8,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
 
@@ -18,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
 ```
@@ -37,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.
 
@@ -45,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
 
@@ -56,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.
 
@@ -79,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`).
 
@@ -95,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/006-github-pipelines.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-006-github-ci-cd-pipelines
+description: Defines the standard GitHub Actions workflow split for CI, release tagging, and publishing. Use when configuring project automation.
+---
+
 # agentme-edr-006: GitHub CI/CD pipelines
 
 ## Context and Problem Statement
@@ -129,7 +134,7 @@ jobs:
 
 *Why rebuild on publish:* The checkout is done from the exact tag commit. Rebuilding ensures the published artifact matches exactly what is tagged, rather than relying on a prior CI artifact.
 
-*Why `id-token: write`:* Required for npm provenance attestation via `npm publish --provenance`, as specified in [agentme-edr-003](003-javascript-project-tooling.md).
+*Why `id-token: write`:* Required for npm provenance attestation via `npm publish --provenance`, as specified in [agentme-edr-003](../application/003-javascript-project-tooling.md).
 
 ---
 

package/.xdrs/agentme/edrs/devops/008-common-targets.md

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-008-common-development-script-names
+description: Defines standard development command names and lifecycle groups across projects, regardless of the underlying runner. Use when designing build, lint, test, and release entry points.
+---
+
 # agentme-edr-008: Common development script names
 
 ## Context and Problem Statement