agentme 0.5.0 → 0.7.0

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

@@ -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,51 +209,70 @@ 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 ./...
+   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
    ```
 
    **Node.js / TypeScript:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   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
    ```
 
    **Python:**
    ```makefile
-   .PHONY: build lint test
+   .PHONY: all build lint test clean
+
+   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
    ```
 
-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
 

package/.xdrs/agentme/edrs/principles/016-cross-language-module-structure.md

@@ -0,0 +1,133 @@
+---
+name: agentme-edr-016-cross-language-module-structure
+description: Defines the baseline module-root structure, artifact locations, cache placement, README expectations, examples layout, and test folder conventions across languages. Use when creating or reviewing buildable modules.
+---
+
+# agentme-edr-016: Cross-language module structure
+
+## Context and Problem Statement
+
+The language-specific tooling EDRs currently describe similar module layouts in different ways, which causes drift in example placement, cache folders, README expectations, and test organization.
+
+What baseline structure rules must every buildable module follow regardless of language?
+
+## Decision Outcome
+
+**Standardize every buildable module around its own folder root, with `dist/`, `.cache/`, sibling consumer examples, a module README, and predictable test locations.**
+
+Language-specific EDRs may add ecosystem details, but they must not redefine these baseline folder responsibilities.
+
+### Implementation Details
+
+#### 1. Every buildable or publishable module MUST own its folder root
+
+A module is the smallest independently buildable, testable, or publishable unit. It MUST live in its own folder and that folder MUST contain:
+
+- a `Makefile` following [agentme-edr-008](../devops/008-common-targets.md)
+- a `README.md` for the module itself
+- all configuration files required to build, lint, test, package, or publish that module
+- its generated `dist/` directory when the module produces distributable artifacts
+- a module-local `.cache/` when tool caches are not intentionally shared with a parent aggregation root
+
+Example module root:
+
+```text
+<module>/
+├── Makefile
+├── README.md
+├── dist/
+├── .cache/
+└── ... language-specific sources and config ...
+```
+
+#### 2. Parent folders are aggregation roots, not hidden implementation buckets
+
+Parent folders such as a repository root, an application folder, or `lib/` may aggregate multiple modules. They may also hold shared consumer examples or multi-module test harnesses.
+
+They MUST keep the public aggregation obvious: deleting an aggregation folder should remove a coherent API surface or entry-point area, not scatter unrelated internal implementation across the repository.
+
+Recommended aggregation pattern:
+
+```text
+<parent>/
+├── <module-a>/
+├── <module-b>/
+├── examples/
+├── tests_integration/
+└── tests_benchmark/
+```
+
+#### 3. Build and publish outputs MUST go to `dist/`
+
+Distributable outputs such as packages, wheels, archives, generated binaries, or packed example inputs MUST be written under the module's `dist/` folder.
+
+`dist/` MUST be gitignored.
+
+#### 4. Persistent tool caches MUST live under `.cache/`
+
+Tool-generated caches and disposable machine-local state MUST be redirected into the nearest intended `.cache/` folder, either at monorepo level or module level.
+
+Examples include:
+
+- linter caches
+- test runner caches
+- transpiler incremental state
+- formatter caches
+- dependency-manager caches when local caching is desired
+
+If a tool cannot natively choose its cache path, the module `Makefile` MUST wrap or clean that tool so persistent cache files do not remain scattered outside `.cache/` after standard targets run.
+
+`.cache/` MUST be gitignored.
+
+#### 5. Consumer examples MUST sit outside the module they exercise
+
+Examples that demonstrate how to consume a library or reusable module MUST live in a sibling `examples/` folder under the nearest aggregation root, not inside the module folder itself.
+
+Examples MUST exercise the module through its public distribution surface:
+
+- use the package built into `dist/` when the ecosystem supports local packaged artifacts
+- otherwise use the public module path or equivalent consumer-facing import surface, never relative source-file imports or direct references to internal implementation paths
+
+Example:
+
+```text
+lib/
+└── mymodule/
+
+examples/
+└── using-mymodule/
+```
+
+#### 6. Every module README MUST explain both usage and development
+
+Each module MUST contain a `README.md` that shows how to use the module as a consumer.
+
+The end of the README MUST also include short developer instructions for that module, covering at least the standard build, lint, and test entry points.
+
+Repository-level READMEs may describe the workspace, but they do not replace the module README.
+
+#### 7. Unit, integration, and benchmark tests use predictable locations
+
+Unit tests SHOULD be co-located with the file they exercise when that is idiomatic and common for the language.
+
+When co-location is uncommon or awkward for the ecosystem, unit tests SHOULD live under `<module>/tests/`.
+
+Integration tests MUST live in one of these locations:
+
+- `<module>/tests_integration/` when they cover one module
+- `<parent>/tests_integration/` when they cover multiple sibling modules
+
+Benchmark tests MUST live in one of these locations:
+
+- co-located with the source when the language has a first-class benchmark convention there
+- `<module>/tests_benchmark/` for module-specific harnesses or datasets
+- `<parent>/tests_benchmark/` when they cover multiple sibling modules
+
+#### 8. Module Makefiles MUST expose the shared target vocabulary
+
+Every module `Makefile` MUST expose the common target names from [agentme-edr-008](../devops/008-common-targets.md). At minimum, modules MUST provide `build`, `lint`, and `test`, and SHOULD also provide `all`, `clean`, and `lint-fix` when meaningful.
+
+## References
+
+- [agentme-edr-005](../devops/005-monorepo-structure.md) - Monorepo aggregation and delegation rules
+- [agentme-edr-008](../devops/008-common-targets.md) - Shared Makefile target names

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.5.0",
+  "version": "0.7.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.26.0",