agentme 0.6.0 → 0.7.0

package/.xdrs/agentme/edrs/application/003-javascript-project-tooling.md

@@ -23,14 +23,14 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 
 | Tool | Purpose |
 |------|---------|
-| **Mise** | Tool version management for Node.js, pnpm, and project CLIs |
+| **Mise** | Mandatory tool version management and command runner for Node.js, pnpm, and project CLIs |
 | **pnpm** | Package manager — strict linking, workspace support, fast installs |
 | **tsc** | TypeScript compilation — type checking, declaration generation |
 | **esbuild** | Bundling — fast bundling for distribution or single-binary outputs |
 | **eslint** | Linting — code style and quality enforcement |
 | **jest** | Testing — unit and integration test runner |
 
-All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root must define a `.mise.toml` that pins at least Node.js and pnpm, and Makefile targets must run through `mise exec --` or an activated Mise shell.
+All commands are run exclusively through Makefiles, not through `package.json` scripts. The repository root MUST define a `.mise.toml` that pins at least Node.js and pnpm. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...` so command behavior does not depend on an activated shell. Using host-installed `node`, `pnpm`, or other project CLIs directly for routine project work is not allowed.
 
 #### ESLint
 
@@ -74,35 +74,35 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 └── tests_benchmark/       # optional benchmark harnesses
 ```
 
-The root `Makefile` delegates every target to `/lib` then `/examples` in sequence and is expected to execute module commands inside the repository's Mise-managed environment.
+The root `Makefile` delegates every target to `/lib` then `/examples` in sequence. Parent Makefiles should call child Makefiles directly, and each module Makefile is responsible for running its actual tool commands through `mise exec --`.
 
 When a repository contains multiple JavaScript/TypeScript packages, each package MUST live in its own module folder such as `lib/my-package/` or `services/my-service/`, each with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 
 Persistent caches MUST live under `.cache/`. Recommended locations are Jest `cacheDirectory`, ESLint `--cache-location`, TypeScript `tsBuildInfoFile`, and coverage outputs.
 
-The commands below assume they are invoked through `mise exec -- make <target>` or from an activated Mise shell.
+Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
 
 #### lib/Makefile targets
 
 | Target | Description |
 |--------|-------------|
-| `install` | `pnpm install --frozen-lockfile` |
-| `build` | compile with `tsc`, strip test files from `dist/`, then `pnpm pack` for local use by examples |
-| `build-module` | compile with `tsc` only (no pack) |
-| `lint` | `pnpm exec eslint ./src` |
-| `lint-fix` | `pnpm exec eslint ./src --fix` |
-| `test` | `pnpm exec jest --verbose` |
-| `test-watch` | `pnpm exec jest --watch` |
+| `install` | `mise exec -- pnpm install --frozen-lockfile` |
+| `build` | `mise exec -- pnpm exec tsc ...`, strip test files from `dist/`, then `mise exec -- pnpm pack` for local use by examples |
+| `build-module` | `mise exec -- pnpm exec tsc ...` only (no pack) |
+| `lint` | `mise exec -- pnpm exec eslint ./src` |
+| `lint-fix` | `mise exec -- pnpm exec eslint ./src --fix` |
+| `test` | `mise exec -- pnpm exec jest --verbose` |
+| `test-watch` | `mise exec -- pnpm exec jest --watch` |
 | `clean` | remove `node_modules/`, `dist/`, and `.cache/` |
 | `all` | `build lint test` |
-| `publish` | version-bump with `monotag`, then `npm publish --provenance` |
+| `publish` | `mise exec -- npx -y monotag ...`, then `mise exec -- npm publish --provenance` |
 
 #### lib/package.json key fields
 
 - `"main"`: `dist/index.js`
 - `"types"`: `dist/index.d.ts`
 - `"files"`: `["dist/**", "package.json", "README.md"]`
-- `"scripts"`: empty — all commands are driven by the Makefile
+- `"scripts"`: empty by default. If reverse compatibility requires scripts, each script must be a direct one-line delegation to one Makefile target.
 
 #### examples/
 

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-010-go-project-tooling-and-structure
-description: Defines the standard Go project toolchain, layout, and Makefile workflow for agentme-based projects. Use when scaffolding or reviewing Go projects.
+description: Defines the standard Go project toolchain, layout, and Makefile workflow using Mise for agentme-based projects. Use when scaffolding or reviewing Go projects.
 ---
 
 # agentme-edr-010: Go project tooling and structure
@@ -13,7 +13,7 @@ What tooling and project structure should Go projects follow to ensure consisten
 
 ## Decision Outcome
 
-**Use the standard Go toolchain (`go build`, `go test`) with `golangci-lint`, module-root folder responsibilities from [agentme-edr-016](../principles/016-cross-language-module-structure.md), feature packages in subdirectories, a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks.**
+**Use a Mise-managed Go toolchain with `go build`, `go test`, and `golangci-lint`, module-root folder responsibilities from [agentme-edr-016](../principles/016-cross-language-module-structure.md), feature packages in subdirectories, a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks.**
 
 A predictable layout and minimal external tooling keep Go projects approachable, fast to build, and easy to distribute as cross-platform binaries.
 
@@ -23,18 +23,19 @@ A predictable layout and minimal external tooling keep Go projects approachable,
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Mandatory tool version management and command runner for Go, `golangci-lint`, and project CLIs |
 | **go toolchain** | Compilation, testing, formatting (`go build`, `go test`, `go fmt`, `go vet`, `go mod`) |
 | **golangci-lint** | Linting — aggregates many linters in one fast run; configured via `.golangci.yml` |
 | **monotag** | Version tagging from git history for the `publish` target |
 
-All commands are run exclusively through the Makefile, never ad-hoc.
-When the repository has a root `.mise.toml`, `go`, `golangci-lint`, and any other Go-related CLIs used by the project **MUST** be pinned there and resolved from the Mise-managed environment rather than the host machine.
+All commands are run exclusively through the Makefile, never ad-hoc. The project root **MUST** define a `.mise.toml` that pins `go`, `golangci-lint`, and any other Go-related CLIs used by the project. Contributors and CI **MUST** bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe **MUST** execute the underlying tool through `mise exec -- <tool> ...`.
 Direct installation of project-required Go CLIs with `go install ...@latest` as a repair step is **NOT** allowed unless an XDR for that repository explicitly permits it.
 
 #### Project structure
 
 ```
 /                              # project root or Go module root inside a monorepo
+├── .mise.toml                 # pinned Go, golangci-lint, and related CLIs
 ├── Makefile                   # build, lint, test, publish, and utility targets
 ├── README.md                  # module README with usage and development commands
 ├── .gitignore                 # MUST ignore dist/ and .cache/
@@ -74,36 +75,36 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 - Module path: `github.com/<owner>/<project>` (or the relevant VCS path for the project)
 - Use the latest stable Go version (e.g. `go 1.24`).
 - Separate `require` blocks: direct dependencies first, then `// indirect` dependencies.
-- If the repository uses Mise, the Go version declared in `go.mod` and the Go version pinned in `.mise.toml` **MUST** stay aligned.
+- The Go version declared in `go.mod` and the Go version pinned in `.mise.toml` **MUST** stay aligned.
 
 #### Makefile targets
 
 | Target | Description |
 |--------|-------------|
 | `all` | Default; runs `build lint test` in sequence |
-| `build` | `go mod download && go build -o dist/<binary>` with Go caches redirected into `.cache/` |
+| `build` | `mise exec -- go mod download && mise exec -- go build -o dist/<binary>` with Go caches redirected into `.cache/` |
 | `build-all` | Cross-compile for all target platforms (darwin/linux/windows × amd64/arm64) |
 | `build-arch-os` | Compile for a specific `OS` and `ARCH` environment variable pair; output to `dist/${OS}-${ARCH}/<binary>` |
-| `install` | `go mod download` |
-| `lint` | `golangci-lint run ./...` with its cache redirected into `.cache/` |
-| `lint-fix` | `golangci-lint run --fix ./...` with its cache redirected into `.cache/` |
-| `test` | `go test -cover ./...` — runs all tests with coverage and stores disposable outputs under `.cache/` |
-| `test-unit` | `go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
-| `coverage` | `go tool cover -func .cache/coverage.out` — displays coverage summary |
+| `install` | `mise exec -- go mod download` |
+| `lint` | `mise exec -- golangci-lint run ./...` with its cache redirected into `.cache/` |
+| `lint-fix` | `mise exec -- golangci-lint run --fix ./...` with its cache redirected into `.cache/` |
+| `test` | `mise exec -- go test -cover ./...` — runs all tests with coverage and stores disposable outputs under `.cache/` |
+| `test-unit` | `mise exec -- go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
+| `coverage` | `mise exec -- go tool cover -func .cache/coverage.out` — displays coverage summary |
 | `clean` | Remove `dist/` and `.cache/` |
-| `start` | `go run ./ <default-args>` — launch the binary locally for dev use |
-| `publish` | Tag with `monotag`, then push tag + binaries to GitHub Releases |
+| `start` | `mise exec -- go run ./ <default-args>` — launch the binary locally for dev use |
+| `publish` | Tag with `mise exec -- npx -y monotag ...`, then push tag + binaries to GitHub Releases |
 
-When the repository uses Mise, the intended invocation pattern is:
+The required invocation pattern is:
 
 ```sh
-mise install
-mise exec -- make build
-mise exec -- make test
-mise exec -- make lint
+make setup
+make build
+make test
+make lint
 ```
 
-Using `make build`, `make test`, or `make lint` from an already activated Mise shell is equivalent.
+The Makefile recipes themselves must use `mise exec --` for the underlying tool commands.
 
 #### Cross-platform binary distribution
 

package/.xdrs/agentme/edrs/application/014-python-project-tooling.md

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-014-python-project-tooling-and-structure
-description: Defines the standard Python project toolchain, layout, and Makefile workflow using uv, ruff, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
+description: Defines the standard Python project toolchain, layout, and Makefile workflow using Mise, uv, ruff, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
 ---
 
 # agentme-edr-014: Python project tooling and structure
@@ -13,7 +13,7 @@ What tooling and project structure should Python projects follow to ensure consi
 
 ## Decision Outcome
 
-**Use a uv-managed Python project with `pyproject.toml`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `pip-audit`, and a layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md): a module root under `lib/`, runnable consumer examples in sibling `examples/`, and standardized `dist/` and `.cache/` locations.**
+**Use a Mise-managed Python and uv toolchain with `pyproject.toml`, `ruff`, `pyright`, `pytest`, `pytest-cov`, `pip-audit`, and a layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md): a module root under `lib/`, runnable consumer examples in sibling `examples/`, and standardized `dist/` and `.cache/` locations.**
 
 A single dependency manager, isolated package internals under `lib/`, and a standard Makefile contract keep Python projects predictable for contributors and CI while keeping the repository root clean.
 
@@ -23,6 +23,7 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 
 | Tool | Purpose |
 |------|---------|
+| **Mise** | Mandatory tool version management and command runner for Python, uv, and project CLIs |
 | **uv** | Dependency management, lockfile management, virtualenv sync, build, publish |
 | **pyproject.toml** | Single source of truth for package metadata and tool configuration |
 | **ruff** | Formatting, import sorting, linting, and common code-quality checks |
@@ -33,7 +34,7 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 
 All routine commands must run through the project `Makefile`, never by calling `uv`, `ruff`, `pytest`, or `pyright` directly in docs, CI, or daily development workflows.
 
-When the repository defines a root `.mise.toml`, Python and uv must be pinned there and commands should run through `mise exec --` or an activated Mise shell.
+The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`. Using host-installed `python`, `uv`, or other project CLIs directly for routine project work is not allowed.
 
 The root `.venv/` is the canonical environment location for both the library and all examples. Subdirectory commands must set `UV_PROJECT_ENVIRONMENT` to the workspace root `.venv/` instead of creating nested virtual environments.
 
@@ -43,7 +44,7 @@ Persistent caches must live under `.cache/`, preferably the module `lib/.cache/`
 
 ```text
 /
-├── .mise.toml              # optional but required when the repo uses Mise
+├── .mise.toml              # required; pins Python and uv
 ├── .gitignore
 ├── .cache/                 # optional shared uv cache at repo level
 ├── .venv/                  # shared uv environment for lib/ and examples/
@@ -101,7 +102,7 @@ Pytest coverage must fail below 80% line and branch coverage, following [agentme
 
 #### Makefile targets
 
-The commands below assume invocation through `mise exec -- make <target>` when the repository uses Mise, or plain `make <target>` inside an activated project environment.
+Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
 
 #### Root `Makefile`
 
@@ -109,6 +110,7 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
 
 | Target | Description |
 |--------|-------------|
+| `setup` | Run `mise install`, then `lib/install` to create or update the shared root `.venv/` |
 | `install` | Run `lib/install` to create or update the shared root `.venv/` |
 | `build` | Run `lib/build` |
 | `lint` | Run `lib/lint` |
@@ -123,17 +125,17 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
 
 | Target | Description |
 |--------|-------------|
-| `install` | `uv sync --project . --frozen --all-extras --dev` using the shared root `.venv/` |
-| `build` | `uv sync --project . --frozen --all-extras --dev && uv build --project . --out-dir dist` |
-| `lint` | `uv run --project . ruff format --check . && uv run --project . ruff check . && uv run --project . pyright && uv run --project . pip-audit`, with caches redirected into `.cache/` |
-| `lint-fix` | `uv run --project . ruff format . && uv run --project . ruff check . --fix && uv run --project . pyright && uv run --project . pip-audit`, with caches redirected into `.cache/` |
-| `test-unit` | `uv run --project . pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80`, with pytest and coverage outputs stored under `.cache/` |
+| `install` | `mise exec -- uv sync --project . --frozen --all-extras --dev` using the shared root `.venv/` |
+| `build` | `mise exec -- uv sync --project . --frozen --all-extras --dev && mise exec -- uv build --project . --out-dir dist` |
+| `lint` | `mise exec -- uv run --project . ruff format --check . && mise exec -- uv run --project . ruff check . && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `lint-fix` | `mise exec -- uv run --project . ruff format . && mise exec -- uv run --project . ruff check . --fix && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `test-unit` | `mise exec -- uv run --project . pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80`, with pytest and coverage outputs stored under `.cache/` |
 | `clean` | Remove `dist/` and `.cache/` inside `lib/` |
 | `all` | `build lint test-unit` |
-| `update-lockfile` | `uv lock --project . --upgrade` |
-| `run` | `uv run --project . python -m <package_name>` or the project CLI entry point |
+| `update-lockfile` | `mise exec -- uv lock --project . --upgrade` |
+| `run` | `mise exec -- uv run --project . python -m <package_name>` or the project CLI entry point |
 | `dev` | Same as `run`, optionally with repository-specific dev defaults |
-| `publish` | `uv publish --project .` after versioning and packaging are complete |
+| `publish` | `mise exec -- uv publish --project .` after versioning and packaging are complete |
 
 The root `Makefile` must remain the only contract for CI and contributors, in line with [agentme-edr-008](../devops/008-common-targets.md).
 

package/.xdrs/agentme/edrs/application/skills/001-create-javascript-project/SKILL.md

@@ -39,7 +39,7 @@ Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agent
 
 **`./Makefile`**
 
-Delegates every make target to `/lib` then `/examples` in sequence:
+Delegates every make target to `/lib` then `/examples` in sequence. Child Makefiles own the actual `mise exec -- <tool>` calls:
 
 ```makefile
 SHELL := /bin/bash
@@ -47,13 +47,13 @@ MISE := mise exec --
 %:
 	@echo ''
 	@echo '>>> Running /lib:$@...'
-  @$(MISE) $(MAKE) -C lib $@
+  @$(MAKE) -C lib $@
 	@echo ''
 	@echo '>>> Running /examples:$@...'
-  @STAGE=dev $(MISE) $(MAKE) -C examples $@
+  @STAGE=dev $(MAKE) -C examples $@
 
 publish:
-  @$(MISE) $(MAKE) -C lib publish
+  @$(MAKE) -C lib publish
 
 setup:
   mise install

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

@@ -35,6 +35,16 @@ Ask for (or infer from context):
 
 ### Phase 2: Create root files
 
+**`./.mise.toml`** (replace `[go-version]` and `[golangci-lint-version]`):
+
+```toml
+[tools]
+go = "[go-version]"
+golangci-lint = "[golangci-lint-version]"
+```
+
+Pin any additional project CLIs used by the Makefile here as well. Use an explicit `golangci-lint` version rather than `latest`.
+
 **`go.mod`** (replace `[module]`, `[go-version]`):
 
 ```
@@ -81,6 +91,7 @@ func main() {
 
 ```makefile
 SHELL := /bin/bash
+MISE := mise exec --
 
 BINARY := [binary]
 CACHE_DIR := .cache
@@ -90,10 +101,14 @@ export GOLANGCI_LINT_CACHE := $(abspath $(CACHE_DIR)/golangci-lint)
 
 all: build lint test
 
+setup:
+	mise install
+	$(MAKE) install
+
 build: install
 	@mkdir -p dist
 	@mkdir -p $(GOCACHE) $(GOMODCACHE)
-	go build -o dist/$(BINARY) .
+	$(MISE) 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
 	@echo "All platform builds complete"
@@ -119,36 +134,36 @@ build-arch-os:
 	@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) .
+	$(MISE) go mod download
+	GOOS=${OS} GOARCH=${ARCH} CGO_ENABLED=0 $(MISE) go build -a -o dist/${OS}-${ARCH}/$(BINARY) .
 	@echo "Done"
 
 install:
-	go mod download
+	$(MISE) go mod download
 
 lint:
-	golangci-lint run ./...
+	$(MISE) golangci-lint run ./...
 
 lint-fix:
-	golangci-lint run --fix ./...
+	$(MISE) golangci-lint run --fix ./...
 
 test:
-	go test -cover ./...
+	$(MISE) go test -cover ./...
 
 test-coverage:
 	@mkdir -p $(CACHE_DIR)
-	go test -coverprofile=$(CACHE_DIR)/coverage.out ./...
-	go tool cover -func $(CACHE_DIR)/coverage.out
+	$(MISE) go test -coverprofile=$(CACHE_DIR)/coverage.out ./...
+	$(MISE) go tool cover -func $(CACHE_DIR)/coverage.out
 
 benchmark:
-	go test -bench . -benchmem -count 5 ./...
+	$(MISE) go test -bench . -benchmem -count 5 ./...
 
 clean:
 	rm -rf dist
 	rm -rf .cache
 
 start:
-	go run ./ [subcommand]
+	$(MISE) go run ./ [subcommand]
 ```
 
 **`.golangci.yml`**:
@@ -190,6 +205,7 @@ coverage.out
 
 ## Development
 
+	make setup
 	make build    # compile binary to dist/
 	make lint     # run golangci-lint with cache in .cache/
 	make test     # run tests with coverage artifacts in .cache/
@@ -300,7 +316,7 @@ func Run(args []string) {
 After creating all files, run the following in the project root:
 
 ```bash
-go mod tidy
+make setup
 make all
 ```
 
@@ -316,6 +332,6 @@ Fix any compile or lint errors before finishing.
 - 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.
+- All development tasks go through `make` targets. The Makefile recipes call `mise exec -- go ...` and related tools directly.
 - 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

@@ -13,10 +13,10 @@ 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.
+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 EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
@@ -39,16 +39,31 @@ 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
+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:
 	$(MAKE) -C lib install
 
@@ -70,9 +85,9 @@ 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; \
+			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
 
@@ -82,9 +97,7 @@ clean:
 	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`.
+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`**
 
@@ -106,6 +119,7 @@ Keep this README focused on the repository or workspace. Put Getting Started nea
 ## Getting Started
 
 ```sh
+make setup
 make test
 ```
 
@@ -121,6 +135,7 @@ artifacts, and library-specific Makefile targets.
 
 ```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
@@ -133,34 +148,34 @@ PACKAGE_NAME ?= your_package
 all: build lint test-unit
 
 install:
-	uv sync --project . --frozen --all-extras --dev
+	$(MISE) uv sync --project . --frozen --all-extras --dev
 
 build: install
 	rm -rf dist
-	uv build --project . --out-dir dist
+	$(MISE) 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
+	$(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
-	uv run --project . ruff format .
-	uv run --project . ruff check . --fix
-	uv run --project . pyright
-	uv run --project . pip-audit
+	$(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
-	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
+	$(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
-	uv run --project . python -m $(PACKAGE_NAME)
+	$(MISE) uv run --project . python -m $(PACKAGE_NAME)
 
 dev: run
 
 update-lockfile:
-	uv lock --project . --upgrade
+	$(MISE) uv lock --project . --upgrade
 
 clean:
 	rm -rf dist .cache
@@ -231,7 +246,7 @@ This README is the published package README referenced by `lib/pyproject.toml`.
 ## Getting Started
 
 ```sh
-uv sync --dev
+make setup
 make test
 ```
 
@@ -331,11 +346,12 @@ Examples must import the package as a consumer would. Avoid relative imports bac
 
 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.
+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
 
@@ -352,7 +368,7 @@ After creating the files:
 
 ## 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.

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

@@ -83,6 +83,7 @@ Repository, application, and module Makefiles **MUST** define at minimum: `all`,
 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.
 
@@ -91,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.
 

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Defines standard Makefile target names and the mandatory tool-execution flow using Mise. Use when designing build, lint, test, and release entry points.
 ---
 
 # agentme-edr-008: Common development script names
@@ -9,46 +9,67 @@ description: Defines standard development command names and lifecycle groups acr
 
 Software projects use a wide variety of commands and tooling to perform the same fundamental tasks — building, testing, linting, and deploying. This diversity is amplified across language ecosystems, meaning developers must re-learn project-specific conventions every time they switch contexts. CI pipelines suffer from the same fragmentation, each one requiring bespoke scripts.
 
-What standard set of command names and conventions should projects adopt so that any developer or CI pipeline can immediately operate on any project without needing to read documentation first?
+What standard set of Makefile target names and execution rules should projects adopt so that any developer or CI pipeline can immediately operate on any project without needing to read documentation first?
 
 ## Decision Outcome
 
-**Every project must expose its development actions using a defined set of standardized script names, grouped by lifecycle phase. These names apply regardless of the script runner used — Makefile, npm scripts, shell scripts, or any other tool — so that `build`, `test`, `lint`, and related commands work predictably across all projects and languages.**
+**Every project must expose its development actions through a root `Makefile` using a defined set of standardized target names. Makefile recipes must run explicit tool commands through `mise exec --`, so developers and CI use the same entry point and can see the real command path without extra script indirection.**
 
-Standardizing script names removes the cognitive overhead of learning per-project conventions, makes CI pipelines reusable across projects, and gives new developers an immediately operational entry point. The names are the contract; the underlying runner is an implementation detail.
+Standardizing both the target names and the execution chain removes per-project guesswork, makes CI pipelines reusable, and keeps tooling behavior visible in one place.
 
 ### Implementation Details
 
-#### 1. Every project MUST have a root-level entry point exposing the standard script names
+#### 1. Every project MUST have a root `Makefile` exposing the standard target names
 
-The project root must contain a single authoritative entry point — a `Makefile`, `package.json` scripts section, a shell wrapper, or equivalent — that exposes the standard target names defined in rule 2. Developers and CI pipelines must invoke actions through this entry point exclusively, never by calling underlying tools directly.
+The project root must contain a single authoritative `Makefile` that exposes the standard target names defined in rule 3. Developers and CI pipelines must invoke routine actions through this `Makefile`, never by calling underlying tools directly in documentation, CI, or daily workflow commands.
 
-**Preferred runner: Makefile.** A `Makefile` is the default recommended choice because it is language-agnostic, universally available, and provides a consistent invocation syntax (`make <target>`) across all ecosystems.
+`make <target>` is the shared contract across projects and languages.
 
-**Alternative runners** are acceptable when a Makefile is not practical for the project's ecosystem:
+- The root `Makefile` must be the entry point for both developers and pipelines.
+- The root `Makefile` must expose at minimum the common targets defined in this XDR.
+- Reverse-compatibility wrappers are allowed when an ecosystem expects them, but they must stay trivial.
+	- Allowed: `package.json` script `"test": "make test"`
+	- Not allowed: `make test` -> `npm run test` -> tool command
+- Project logic must not live in npm scripts, Mise tasks, shell wrappers, or other secondary runners when the same logic belongs in the `Makefile`.
 
-| Runner | Invocation example | When appropriate |
-|--------|--------------------|------------------|
-| Makefile | `make build` | Default; recommended for all projects |
-| npm scripts | `npm run build` | Pure Node.js/frontend projects without a Makefile |
-| Shell script | `./dev.sh build` | Projects where `make` is unavailable or impractical |
-| Other (Taskfile, just, etc.) | `task build` | When agreed upon at the project or org level |
+*Why:* The project entry point must stay language-agnostic and obvious. A developer should be able to inspect the `Makefile` and immediately see which real tool commands will run.
 
-Whichever runner is chosen, the **target names** defined in rule 2 must be used unchanged. The runner is an implementation detail; the names are the shared contract.
+#### 2. Makefile recipes MUST use the explicit tool-execution chain
 
-*Why:* A single entry point means developers and CI pipelines use near-identical commands regardless of the underlying language or tooling. Any tooling change is then contained to the entry-point file and does not require updating CI pipelines or developer documentation.
+After a checkout, the only assumed prerequisites are `make` and [Mise](https://mise.jdx.dev/). The standard execution flow is:
+
+```text
+make <target>
+	-> Makefile recipe
+		-> mise exec -- <tool> [tool arguments]
+			-> explicit tool command
+```
+
+- The `setup` target must run `mise install` and any small project-specific bootstrap needed before normal targets work.
+- Routine targets such as `build`, `lint`, `test`, `run`, and `publish` must be invoked as `make <target>` by both contributors and CI.
+- Each Makefile recipe must call the real underlying command directly through `mise exec --`.
+- Makefile recipes must not add extra script layers such as `npm run`, `pnpm run`, `yarn run`, `mise run`, `mise tasks`, or shell aliases when those layers only forward to another command.
+- Calling the actual tool is allowed even when that tool itself launches another program as part of its normal interface.
+	- Allowed: `mise exec -- pnpm exec eslint ./src`
+	- Allowed: `mise exec -- go test -cover ./...`
+	- Allowed: `mise exec -- uv run --project . pytest`
+	- Disallowed: `mise exec -- pnpm run lint`
+	- Disallowed: `mise run lint`
+	- Disallowed: `make lint` implemented as `./scripts/lint.sh` when the shell script only forwards to one visible tool command
+
+*Why:* This keeps the execution path inspectable, avoids hidden logic spread across multiple scripting systems, and makes CI behave the same way as local development.
 
 ---
 
-#### 2. Standard script groups and names
+#### 3. Standard target groups and names
 
-Scripts are organized into five lifecycle groups. Projects must use these names regardless of the script runner in use. Extensions are allowed (see rule 4) but the core names must not be repurposed.
+Targets are organized into five lifecycle groups. Projects must use these names unchanged. Extensions are allowed (see rule 5) but the core names must not be repurposed.
 
 ##### Developer group
 
-| Script | Purpose |
+| Target | Purpose |
 |--------|---------|
-| `setup` | Install any tools required on the developer machine (e.g., nvm, brew, python, golang). Typically run once per project checkout. In CI, tooling is usually pre-provisioned via runner images or workflow steps instead. |
+| `setup` | Run `mise install` and any small project bootstrap needed before normal targets work. This is the first command after checkout. |
 | `all` | Alias that runs `build`, `lint`, and `test` in sequence. Must be the default target (i.e., running `make` or the runner with no arguments invokes `all`). Used by developers as a fast pre-push check to verify the software meets minimum quality standards in one command. |
 | `clean` | Remove all temporary or generated files created during build, lint, or test (e.g., `node_modules`, virtual environments, compiled binaries, generated files). Used both locally and in CI for a clean slate. |
 | `dev` | Run the software locally for development (e.g., start a Node.js API server, open a Jupyter notebook, launch a React dev server). May have debugging tools, verbose logging, or hot reloading features enabled. |
@@ -57,7 +78,7 @@ Scripts are organized into five lifecycle groups. Projects must use these names
 
 ##### Build group
 
-| Script | Purpose |
+| Target | Purpose |
 |--------|---------|
 | `build` | Install dependencies, compile, and package the software. The full `install → compile → package` workflow. |
 | `install` | Download and install all project dependencies. Assumes the language runtime is already available (installed via `setup`). |
@@ -67,13 +88,13 @@ Scripts are organized into five lifecycle groups. Projects must use these names
 
 ##### Lint group
 
-| Script | Purpose |
+| Target | Purpose |
 |--------|---------|
 | `lint` | Run **all static quality checks** outside of tests. This MUST include: code formatting validation, code style enforcement, code smell detection, static analysis, dependency audits for known CVEs, security vulnerability scans (e.g., SAST), and project/configuration structure checks. All checks must be non-destructive (read-only); fixes are handled by `lint-fix`. |
 | `lint-fix` | Automatically fix linting and formatting issues where possible. || `lint-format` | *(Optional)* Check code formatting only (e.g., Prettier, gofmt, Black). |
 ##### Test group
 
-| Script | Purpose |
+| Target | Purpose |
 |--------|---------|
 | `test` | Run **all tests** required for the project. This MUST include unit tests (with coverage enforcement — the build MUST fail if coverage thresholds are not met) and integration/end-to-end tests. Normally delegates to `test-unit` and `test-integration` in sequence. |
 | `test-unit` | Run unit tests only, including coverage report generation and coverage threshold enforcement. |
@@ -82,7 +103,7 @@ Scripts are organized into five lifecycle groups. Projects must use these names
 
 ##### Release group
 
-| Script | Purpose |
+| Target | Purpose |
 |--------|---------|
 | `release` | Determine the next version (e.g., via semantic versioning and git tags), generate changelogs and release notes, tag the repository, and create a release artifact. Normally invokes `docgen`. |
 | `docgen` | Generate documentation (API docs, static sites, changelogs, example outputs). |
@@ -103,9 +124,9 @@ Two environment variables have defined semantics and must be used consistently.
 
 ---
 
-#### 4. Extending scripts with prefixes
+#### 5. Extending targets with prefixes
 
-Projects may add custom scripts beyond the standard set. Custom scripts must be named by prefixing a standard script name with a descriptive qualifier, keeping the naming intuitive and consistent with the group it belongs to.
+Projects may add custom targets beyond the standard set. Custom targets must be named by prefixing a standard target name with a descriptive qualifier, keeping the naming intuitive and consistent with the group it belongs to.
 
 **Examples:**
 
@@ -121,13 +142,13 @@ start-debugger    # launch the software with a visual debugger attached
 deploy-infra      # deploy only the infrastructure layer
 ```
 
-The prefix convention ensures developers can infer the purpose of any script without documentation.
+The prefix convention ensures developers can infer the purpose of any target without documentation.
 
 ---
 
-#### 5. Monorepo usage
+#### 6. Monorepo usage
 
-In a monorepo, each module has its own `Makefile` with its own `build`, `lint`, `test`, and `deploy` targets scoped to that module. Parent-level Makefiles (at the application or repo root) delegate to module Makefiles in sequence.
+In a monorepo, each module has its own `Makefile` with its own `build`, `lint`, `test`, and `deploy` targets scoped to that module. Parent-level Makefiles (at the application or repo root) delegate to child Makefiles in sequence. The parent Makefile should call `$(MAKE) -C <child> <target>` directly, while each child `Makefile` runs its actual tool commands through `mise exec --`.
 
 ```makefile
 # root Makefile — delegates to all modules
@@ -146,12 +167,12 @@ A developer can run `make test` at the repo root to test everything, or `cd modu
 
 ---
 
-#### 6. Quick-reference — commands a developer can always rely on
+#### 7. Quick-reference — commands a developer can always rely on
 
-Any project following this EDR supports the following actions. Examples show Makefile syntax; substitute your project's runner (e.g., `npm run build`, `./dev.sh build`) if a Makefile is not used.
+Any project following this EDR supports the following actions through the root `Makefile`.
 
 ```sh
-# install required development tools
+# install the pinned toolchain and project bootstrap
 make setup
 
 # build the software (install deps, compile, package)
@@ -188,25 +209,13 @@ make clean
 make all
 ```
 
-**Equivalent examples for npm scripts and shell:**
-
-```sh
-# npm scripts (package.json)
-npm run build
-npm run test
-npm run lint
-STAGE=dev npm run deploy
-
-# shell wrapper
-./dev.sh build
-./dev.sh test
-STAGE=dev ./dev.sh deploy
-```
-
 ## Considered Options
 
-* (REJECTED) **Language-native entry points only** - Use `npm run`, `python -m`, `go run` etc. directly as the standard without a unifying name convention
+* (REJECTED) **Language-native entry points only** - Use `npm run`, `python -m`, `go run`, and similar tool-specific commands directly as the standard surface
   * Reason: Ties CI pipelines and developer muscle memory to language-specific tooling; breaks the abstraction when the underlying tool changes; target names vary per ecosystem
 
-* (CHOSEN) **Standardized script names, runner-agnostic** - A common, language-agnostic command vocabulary that must be used regardless of whether the runner is a Makefile, npm scripts, a shell wrapper, or another tool; with Makefile as the preferred default
-  * Reason: Separating the names (the contract) from the runner (the implementation) gives every developer and CI pipeline a predictable interface while allowing each project to choose the most practical runner for its ecosystem.
+* (REJECTED) **Runner-agnostic targets with multiple primary runners** - Keep the target names standard but allow Makefile, npm scripts, shell wrappers, or other runners as equivalent first-class entry points
+	* Reason: Preserves naming consistency but still spreads behavior across multiple scripting systems, which hides the real command path and weakens CI standardization.
+
+* (CHOSEN) **Standardized Makefile targets with Mise-managed explicit tool execution** - Use `make <target>` as the only routine entry point, keep target names standard, and run the actual underlying tool commands through `mise exec --`
+	* Reason: This keeps names, execution flow, and tool versions equally predictable while avoiding script indirection.

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

@@ -220,13 +220,13 @@ For each module inside an application:
    all: build lint test
 
    build:
-   	go build ./...
+   mise exec -- go build ./...
 
    lint:
-   	golangci-lint run ./...
+   mise exec -- golangci-lint run ./...
 
    test:
-   	go test ./... -cover
+   mise exec -- go test ./... -cover
 
    clean:
 	rm -rf dist .cache
@@ -239,13 +239,13 @@ For each module inside an application:
    all: build lint test
 
    build:
-   	npm run build
+   mise exec -- pnpm exec tsc --project tsconfig.json
 
    lint:
-   	npm run lint
+   mise exec -- pnpm exec eslint ./src
 
    test:
-   	npm test
+   mise exec -- pnpm exec jest --verbose
 
    clean:
 	rm -rf dist .cache
@@ -258,13 +258,13 @@ For each module inside an application:
    all: build lint test
 
    build:
-   	pip install -e .
+   mise exec -- uv build --project . --out-dir dist
 
    lint:
-   	ruff check .
+   mise exec -- uv run --project . ruff check .
 
    test:
-   	pytest
+   mise exec -- uv run --project . pytest
 
    clean:
 	rm -rf dist .cache

package/README.md

@@ -80,27 +80,25 @@ This is useful when you want to:
 
 ## Development
 
-Install [Mise](https://mise.jdx.dev/getting-started.html), then sync the pinned toolchain:
+Install [Mise](https://mise.jdx.dev/getting-started.html), then bootstrap the repository through the root `Makefile`:
 
 ```sh
-mise install
+make setup
 ```
 
-Use the root `Makefile` as the entry point for local verification inside the Mise-managed environment:
+Use the root `Makefile` as the entry point for local verification:
 
 ```sh
-mise exec -- make build
-mise exec -- make lint
-mise exec -- make test
+make build
+make lint
+make test
 ```
 
-Running `make build`, `make lint`, or `make test` from an already activated Mise shell is equivalent.
-
 What these targets do:
 
-- `mise exec -- make build` installs dependencies and creates a local npm package in `dist/`.
-- `mise exec -- make lint` runs the repository lint target.
-- `mise exec -- make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
+- `make build` installs dependencies and creates a local npm package in `dist/`.
+- `make lint` runs the repository lint target.
+- `make test` rebuilds the package and validates the consumer extraction flow through the runnable example in `examples/`.
 
 ## Repository Map
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",