agentme 0.7.0 → 0.7.3

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

@@ -30,7 +30,7 @@ Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelin
 | **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. 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.
+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> ...`, following [agentme-edr-017](../devops/017-tool-execution-and-scripting.md). Calling project tools directly in docs, CI, or daily workflows instead of `make <target>` is not allowed.
 
 #### ESLint
 

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

@@ -28,7 +28,7 @@ A predictable layout and minimal external tooling keep Go projects approachable,
 | **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. 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> ...`.
+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> ...`, following [agentme-edr-017](../devops/017-tool-execution-and-scripting.md).
 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

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

@@ -34,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.
 
-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 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> ...`, following [agentme-edr-017](../devops/017-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract 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.
 

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

@@ -94,7 +94,7 @@ The root `setup` target **MUST** run `mise install` and any small repository boo
 - Every language runtime or CLI referenced by any module `Makefile`, CI workflow, or README command **MUST** be pinned in `.mise.toml`.
 - 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 through `make <target>`, and the Makefile recipes **MUST** execute the underlying tools via `mise exec -- <command>`.
+- 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>`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
 - 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 **MUST** work when invoked as plain `make <target>` after `make setup`.
 

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

@@ -13,7 +13,7 @@ What standard set of Makefile target names and execution rules should projects a
 
 ## Decision Outcome
 
-**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.**
+**Every project must expose its development actions through a root `Makefile` using a defined set of standardized target names. Target implementation and tool-execution rules follow [agentme-edr-017](017-tool-execution-and-scripting.md), which requires `mise exec --` before routine tool commands.**
 
 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.
 
@@ -34,9 +34,9 @@ The project root must contain a single authoritative `Makefile` that exposes the
 
 *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.
 
-#### 2. Makefile recipes MUST use the explicit tool-execution chain
+#### 2. Makefile recipes MUST use the shared Mise execution rules
 
-After a checkout, the only assumed prerequisites are `make` and [Mise](https://mise.jdx.dev/). The standard execution flow is:
+After a checkout, the shared execution flow is:
 
 ```text
 make <target>
@@ -47,13 +47,14 @@ make <target>
 
 - 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 --`.
+- Each Makefile recipe must call the real underlying command through `mise exec --`, following [agentme-edr-017](017-tool-execution-and-scripting.md).
 - 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: `pnpm run lint`
+	- Disallowed: `pnpm exec eslint ./src`
 	- Disallowed: `mise run lint`
 	- Disallowed: `make lint` implemented as `./scripts/lint.sh` when the shell script only forwards to one visible tool command
 
@@ -219,3 +220,8 @@ make all
 
 * (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.
+
+## References
+
+- [agentme-edr-005](005-monorepo-structure.md) - Monorepo layout and delegation structure
+- [agentme-edr-017](017-tool-execution-and-scripting.md) - Tool-execution rules for Makefile targets and CI

package/.xdrs/agentme/edrs/devops/017-tool-execution-and-scripting.md

@@ -0,0 +1,64 @@
+---
+name: agentme-edr-017-tool-execution-and-scripting
+description: Defines how Makefiles, CI pipelines, and optional wrapper scripts execute project commands. Use when designing project automation or command entry points.
+---
+
+# agentme-edr-017: Tool execution and scripting
+
+## Context and Problem Statement
+
+Projects often hide build, lint, and test behavior behind multiple scripting layers, making it hard for developers and CI pipelines to see what actually runs.
+
+How should projects execute development commands so the command surface stays predictable and the underlying operations stay obvious?
+
+## Decision Outcome
+
+**Use Makefiles as the only authoritative command entry point, with targets named by [agentme-edr-008](008-common-targets.md) and implemented with `mise exec --` before the real tool command.**
+
+This keeps local development and CI aligned, reduces indirection, and lets contributors understand project behavior by reading one command surface.
+
+### Implementation Details
+
+- Every project MUST use a root `Makefile` as the authoritative entry point for developer and pipeline commands.
+- The target names in that `Makefile` MUST follow [agentme-edr-008](008-common-targets.md).
+- CI pipelines MUST run `make <target>` from the relevant root instead of calling language-specific scripts such as `npm run`, `pnpm run`, shell wrappers, or secondary task runners.
+- A Makefile target MUST execute the real operation through `mise exec --` before invoking the tool itself, so it always uses the version pinned in `.mise.toml`. Avoid intermediate script layers that hide the actual command.
+- Every Makefile target MUST start by echoing a concise summary of the target and folder or context, using fewer than 10 words. When delegating to another Makefile, echo the child path and delegated target before invoking it.
+- Direct delegation to another Makefile is allowed when traversing repo, app, or module boundaries, for example `$(MAKE) -C lib build`.
+- Calling the actual tool binary through its native executable launcher is allowed when that is the direct command under `mise exec --`, for example `mise exec -- pnpm exec eslint ./src`, `mise exec -- uv run pyright`, `mise exec -- go test`, or `mise exec -- npx -y monotag`.
+- Makefile targets MUST use `mise exec --` consistently before routine tool commands and MUST NOT call `npm run`, `pnpm run`, `yarn run`, `just`, `task`, or similar abstraction layers for routine project commands.
+- Tool installation and environment preparation MUST be handled explicitly in developer setup instructions and CI workflow steps, using ecosystem-specific installation steps such as `actions/setup-node`, `actions/setup-go`, `astral-sh/setup-uv`, system package managers, or pinned install commands such as `mise install`.
+- `package.json` scripts are optional and MAY exist only as direct reverse-compatibility aliases to one Make target, for example `"test": "make test"`. They MUST stay one-to-one and add no extra orchestration.
+- README examples, contributing guides, and pipeline snippets SHOULD show `make <target>` as the primary way to operate the project.
+
+Allowed:
+
+- `make lint` running `mise exec -- pnpm exec eslint ./src`
+- `make test` running `mise exec -- go test ./...`
+- `make build` running `mise exec -- uv build --project . --out-dir dist`
+- Root Makefile delegating to module Makefiles with `$(MAKE) -C <module> <target>`
+- A target beginning with `echo ">>> ./lib: lint"`
+
+Disallowed:
+
+- `make lint` running `pnpm run lint`
+- `make test` running `mise exec -- make test`
+- `make lint` running `pnpm exec eslint ./src` without `mise exec --`
+- CI running `npm run build` when the project already defines `make build`
+- `package.json` scripts that chain multiple operations instead of forwarding to one Make target
+
+## Considered Options
+
+* (REJECTED) **Runner-agnostic command entry points** - Allow Makefiles, package-manager scripts, shell wrappers, and task runners as equivalent project entry points.
+  * Reason: Preserves multiple abstraction layers and weakens the guarantee that developers and CI execute the same visible commands.
+* (CHOSEN) **Makefile-first Mise-managed execution** - Standardize on Makefiles for entry points and require targets to run the underlying commands through `mise exec --`.
+  * Reason: Keeps the command surface small, readable, and consistent across languages while ensuring the pinned tool versions from `.mise.toml` are always used.
+
+## References
+
+- [agentme-edr-005](005-monorepo-structure.md) - Monorepo layout and Makefile hierarchy
+- [agentme-edr-006](006-github-pipelines.md) - CI/CD workflows should call Make targets
+- [agentme-edr-008](008-common-targets.md) - Standard target names
+- [agentme-edr-003](../application/003-javascript-project-tooling.md) - JavaScript tooling commands inside Makefiles
+- [agentme-edr-010](../application/010-golang-project-tooling.md) - Go tooling commands inside Makefiles
+- [agentme-edr-014](../application/014-python-project-tooling.md) - Python tooling commands inside Makefiles

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

@@ -8,12 +8,12 @@ Propose changes via pull request. All changes must be verified for clarity and n
 
 Foundational standards, principles, and guidelines.
 
-- [agentme-edr-002](principles/002-coding-best-practices.md) - **Coding best practices**
-- [agentme-edr-004](principles/004-unit-test-requirements.md) - **Unit test requirements**
-- [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**
+- [agentme-edr-002](principles/002-coding-best-practices.md) - **Coding best practices** - Keep files small, tests nearby, and docs synchronized
+- [agentme-edr-004](principles/004-unit-test-requirements.md) - **Unit test requirements** - Define minimum unit-test coverage and naming expectations
+- [agentme-edr-007](principles/007-project-quality-standards.md) - **Project quality standards** - Require build, lint, and test verification before completion
+- [agentme-edr-009](principles/009-error-handling.md) - **Error handling** - Standardize explicit errors, logging, and propagation rules
+- [agentme-edr-012](principles/012-continuous-xdr-enrichment.md) - **Continuous xdr improvement policy** - Promote recurring delivery lessons into reusable XDRs
+- [agentme-edr-016](principles/016-cross-language-module-structure.md) - **Cross-language module structure** - Organize modules consistently across supported languages
 
 ## Articles
 
@@ -25,28 +25,29 @@ Synthetic views combining agentme XDRs and skills around a specific topic.
 
 Language and framework-specific tooling and project structure.
 
-- [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
-- [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
-- [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
-- [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards**
+- [agentme-edr-003](application/003-javascript-project-tooling.md) - **JavaScript project tooling and structure** - Scaffold JavaScript libraries with the standard toolchain *(includes skill: [001-create-javascript-project](application/skills/001-create-javascript-project/SKILL.md))*
+- [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** - Scaffold Go CLIs and libraries with the standard layout *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
+- [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
+- [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards** - Define command UX and behavior for CLI tools
 - [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ## Devops
 
 Repository structure, build conventions, and CI/CD pipelines.
 
-- [agentme-edr-005](devops/005-monorepo-structure.md) - **Monorepo structure** *(includes skill: [002-monorepo-setup](devops/skills/002-monorepo-setup/SKILL.md))*
-- [agentme-edr-006](devops/006-github-pipelines.md) - **GitHub CI/CD pipelines**
-- [agentme-edr-008](devops/008-common-targets.md) - **Common development script names**
+- [agentme-edr-005](devops/005-monorepo-structure.md) - **Monorepo structure** - Standardize monorepo layout, tooling, and package boundaries *(includes skill: [002-monorepo-setup](devops/skills/002-monorepo-setup/SKILL.md))*
+- [agentme-edr-006](devops/006-github-pipelines.md) - **GitHub CI/CD pipelines** - Define required CI stages and workflow structure
+- [agentme-edr-008](devops/008-common-targets.md) - **Common development script names** - Reuse standard build, lint, and test target names
+- [agentme-edr-017](devops/017-tool-execution-and-scripting.md) - **Tool execution and scripting** - Run tools consistently across shells, Makefiles, and CI
 
 ## Governance
 
 Contribution and collaboration standards shared across projects.
 
-- [agentme-edr-013](governance/013-contributing-guide-requirements.md) - **Contributing guide requirements**
+- [agentme-edr-013](governance/013-contributing-guide-requirements.md) - **Contributing guide requirements** - Define the minimum structure for CONTRIBUTING guides
 
 ## Observability
 
 Health, metrics, logging, and monitoring standards.
 
-- [agentme-edr-011](observability/011-service-health-check-endpoint.md) - **Service health check endpoint**
+- [agentme-edr-011](observability/011-service-health-check-endpoint.md) - **Service health check endpoint** - Expose a standard runtime health-check endpoint for services

package/.xdrs/agentme/edrs/principles/articles/001-continuous-xdr-improvement.md

@@ -51,7 +51,7 @@ Good opening questions:
 
 ### How should you organize the XDR?
 
-Follow the XDR template from [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md). Keep the document small, explicit, and decision-focused.
+Follow the XDR template from [_core-adr-002](../../../../_core/adrs/principles/002-xdr-standards.md). Keep the document small, explicit, and decision-focused.
 
 Use this checklist:
 

package/.xdrs/index.md

@@ -10,6 +10,7 @@ XDRs in scopes listed last override the ones listed first
 
 Decisions about how XDRs work
 [View _core ADRs Index](_core/adrs/index.md)
+[View _core BDRs Index](_core/bdrs/index.md)
 
 ---
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "agentme",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",
-    "xdrs-core": "^0.16.0"
+    "xdrs-core": "^0.17.0"
   },
   "bin": "bin/filedist.js",
   "files": [