agentme 0.5.0 → 0.6.0

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

@@ -13,7 +13,7 @@ What tooling and project structure should JavaScript/TypeScript projects follow
 
 ## Decision Outcome
 
-**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a standard layout separating library code (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level Makefiles.**
+**Use a Mise-managed Node.js and pnpm toolchain together with pnpm, tsc, esbuild, eslint, and jest in a module-root layout that follows [agentme-edr-016](../principles/016-cross-language-module-structure.md), with runnable usage examples in sibling `examples/` folders and Makefiles as the only entry points.**
 
 Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
 
@@ -47,29 +47,39 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 #### Project structure
 
 ```
-/                          # workspace root
+/                          # workspace root or parent aggregation root
 ├── .mise.toml             # pinned Node.js and pnpm versions
+├── .gitignore             # MUST ignore dist/ and .cache/
 ├── Makefile               # delegates build/lint/test to /lib and /examples
-├── README.md              # Quick Start first; used as npm registry page
-├── lib/                   # the published npm package
+├── README.md              # workspace overview and quickstart
+├── lib/                   # one JavaScript/TypeScript module root
 │   ├── Makefile           # build, lint, test, publish targets
+│   ├── README.md          # package README used for publishing
 │   ├── package.json       # package manifest
 │   ├── tsconfig.json      # TypeScript config for build and linting
 │   ├── jest.config.js     # Jest config
 │   ├── eslint.config.mjs  # ESLint config (ESLint 9 flat config)
+│   ├── .cache/            # eslint, jest, tsc incremental state, coverage
+│   ├── dist/              # compiled files and packed .tgz artifacts
 │   └── src/               # all TypeScript source files
 │       ├── index.ts       # public API re-exports
 │       └── *.test.ts      # test files co-located with source
-└── examples/              # runnable usage examples
-    ├── Makefile           # build + test all examples in sequence
-    ├── usage-x/           # first example
-    │   └── package.json
-    └── usage-y/           # second example
-        └── package.json
+├── examples/              # runnable usage examples outside the module root
+│   ├── Makefile           # build + test all examples in sequence
+│   ├── usage-x/           # first example
+│   │   └── package.json
+│   └── usage-y/           # second example
+│       └── package.json
+├── tests_integration/     # optional cross-example or cross-module integration tests
+└── 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.
 
+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.
 
 #### lib/Makefile targets
@@ -83,7 +93,7 @@ The commands below assume they are invoked through `mise exec -- make <target>`
 | `lint-fix` | `pnpm exec eslint ./src --fix` |
 | `test` | `pnpm exec jest --verbose` |
 | `test-watch` | `pnpm exec jest --watch` |
-| `clean` | remove `node_modules/` and `dist/` |
+| `clean` | remove `node_modules/`, `dist/`, and `.cache/` |
 | `all` | `build lint test` |
 | `publish` | version-bump with `monotag`, then `npm publish --provenance` |
 
@@ -98,6 +108,12 @@ The commands below assume they are invoked through `mise exec -- make <target>`
 
 Each sub-folder under `examples/` is an independent package. The Makefile installs the locally built `.tgz` pack from `lib/dist/` so examples simulate real external usage.
 
+Examples MUST remain outside the module root and MUST consume the package through the packed artifact in `dist/`, never through `../src` imports or other direct source links.
+
+Module-specific integration tests that are not just runnable examples belong in `lib/tests_integration/` or a sibling `tests_integration/` when they cover multiple modules.
+
+Benchmarks belong in `lib/tests_benchmark/` when they require dedicated harnesses; simple micro-benchmarks may stay co-located only if the local testing stack makes that idiomatic.
+
 The examples folder MUST exist for any libraries and utilities that are published or have more than 500 lines of code
 
 ### Related Skills

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

@@ -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` for linting, feature packages in subdirectories (no `internal/` by default), a `cli/` package for command wiring, and a Makefile as the single entry point for all development tasks, with the Go toolchain and related CLIs sourced from the repository's Mise-managed environment when the repository defines `.mise.toml`.**
+**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.**
 
 A predictable layout and minimal external tooling keep Go projects approachable, fast to build, and easy to distribute as cross-platform binaries.
 
@@ -34,33 +34,40 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 #### Project structure
 
 ```
-/                              # project root (single Go module)
+/                              # project root or Go module root inside a monorepo
 ├── Makefile                   # build, lint, test, publish, and utility targets
+├── README.md                  # module README with usage and development commands
+├── .gitignore                 # MUST ignore dist/ and .cache/
+├── .golangci.yml              # golangci-lint configuration
 ├── go.mod                     # module declaration (github.com/<owner>/<project>)
 ├── go.sum                     # locked dependency checksums
 ├── main.go                    # binary entry point — argument dispatch only, no logic
-├── .golangci.yml              # golangci-lint configuration
-├── .gitignore
-├── README.md
+├── .cache/                    # GOCACHE, GOMODCACHE, golangci-lint cache, coverage
+├── dist/                      # built binaries and packaged outputs
 ├── <feature-a>/               # domain package (e.g. ownership/, changes/, utils/)
 │   ├── *.go                   # business logic
 │   └── *_test.go              # unit tests co-located with source
 ├── <feature-b>/
 │   └── ...
-└── cli/                       # CLI wiring — ties flags to domain packages
-    ├── <feature-a>/
-    │   └── *.go
-    └── <feature-b>/
-        └── *.go
+├── cli/                       # CLI wiring — ties flags to domain packages
+│   ├── <feature-a>/
+│   │   └── *.go
+│   └── <feature-b>/
+│       └── *.go
+├── tests_integration/         # optional integration tests for this module
+├── tests_benchmark/           # optional benchmark harnesses and datasets
+└── examples/                  # optional sibling consumer examples for libraries
 ```
 
 **Key layout rules:**
 
 - One Go module per project (`go.mod` at the project root). In a monorepo, each Go project has its own `go.mod` in its subdirectory. No nested modules within a single project unless explicitly justified.
+- In a multi-module repository, each Go module MUST live in its own folder root with its own `Makefile`, `README.md`, `dist/`, and `.cache/`.
 - `main.go` is solely an argument dispatcher — it reads `os.Args[1]` and delegates to a `cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
 - Business logic lives in named feature packages at the root (e.g., `ownership/`, `changes/`, `utils/`). These packages are importable and testable without any CLI concerns.
 - `cli/` packages own flag parsing, output formatting, and the wiring between flags and domain functions. No business logic lives in `cli/`.
 - Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
+- Consumer examples for reusable libraries belong in a sibling `examples/` folder and MUST import the public module path rather than reaching into internal source paths. Because Go libraries are not typically consumed from a local packaged artifact, local example validation may use a temporary module replacement for resolution, but the import path MUST remain the public module path.
 
 #### go.mod
 
@@ -74,16 +81,16 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 | Target | Description |
 |--------|-------------|
 | `all` | Default; runs `build lint test` in sequence |
-| `build` | `go mod download && go build -o dist/<binary>` |
+| `build` | `go mod download && 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 ./...` |
-| `lint-fix` | `golangci-lint run --fix ./...` |
-| `test` | `go test -cover ./...` — runs all tests with coverage |
+| `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 ./coverage.out` — displays coverage summary |
-| `clean` | Remove `dist/` and any coverage files |
+| `coverage` | `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 |
 
@@ -112,8 +119,10 @@ When the project produces a CLI binary for end-users:
 - Tests are co-located with source: `<feature>/<file>_test.go`.
 - Use `github.com/stretchr/testify` (`assert`, `require`) for test assertions.
 - Run all tests: `go test -cover ./...`
-- Benchmarks: `go test -bench . -benchmem -count 20`
-- Integration or slow tests: guard with `//go:build integration` and skip in unit runs via `-tags=unit`.
+- Benchmarks: keep simple `Benchmark*` functions co-located in `*_test.go`; use `tests_benchmark/` when the benchmark needs dedicated harnesses or datasets.
+- Integration or slow tests: guard with `//go:build integration` and keep them in `tests_integration/` when they are not naturally co-located with one package.
+
+Redirect Go tool caches into `.cache/` using `GOCACHE`, `GOMODCACHE`, and `GOLANGCI_LINT_CACHE` from the module `Makefile` so the repository does not accumulate scattered cache directories.
 
 #### Linting
 

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

@@ -13,9 +13,9 @@ 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 Makefile as the only development entry point.**
+**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.**
 
-A single dependency manager, one canonical config file, and standard targets keep Python projects predictable for contributors and CI.
+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.
 
 ### Implementation Details
 
@@ -35,40 +35,64 @@ All routine commands must run through the project `Makefile`, never by calling `
 
 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 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.
+
+Persistent caches must live under `.cache/`, preferably the module `lib/.cache/` plus a shared root `.cache/uv/` when uv cache sharing is desired.
+
 #### Project structure
 
 ```text
 /
 ├── .mise.toml              # optional but required when the repo uses Mise
-├── Makefile                # single entry point for build/lint/test/run tasks
-├── pyproject.toml          # package metadata + tool config
-├── uv.lock                 # committed lockfile
-├── README.md               # Getting Started near the top
-├── src/
-│   └── <package_name>/
-│       ├── __init__.py
-│       ├── __main__.py     # when the project exposes a CLI
-│       └── ...
-├── tests/
-│   ├── conftest.py         # shared fixtures when needed
-│   └── test_*.py
-└── examples/               # required for libraries and shared utilities
-    ├── Makefile
-    └── basic-usage/
+├── .gitignore
+├── .cache/                 # optional shared uv cache at repo level
+├── .venv/                  # shared uv environment for lib/ and examples/
+├── Makefile                # root entry point; delegates to lib/ and runs examples/
+├── README.md               # workspace/repository overview
+├── lib/                    # everything the published library needs
+│   ├── Makefile            # build, lint, test, publish targets for the library
+│   ├── pyproject.toml      # package metadata + tool config
+│   ├── uv.lock             # committed lockfile for the library
+│   ├── README.md           # package README used for publishing
+│   ├── .cache/             # pytest, Ruff, coverage, Python bytecode cache
+│   ├── src/
+│   │   └── <package_name>/
+│   │       ├── __init__.py
+│   │       ├── __main__.py # when the project exposes a CLI
+│   │       └── ...
+│   ├── tests/
+│   │   ├── conftest.py     # shared fixtures when needed
+│   │   └── test_*.py
+│   ├── tests_integration/  # optional integration tests for this module
+│   ├── tests_benchmark/    # optional benchmark harnesses and datasets
+│   └── dist/               # wheels / sdists built from lib/
+└── examples/               # independent consumer projects
+    ├── example1/
+    │   ├── pyproject.toml
+    │   └── main.py
+    └── example2/
+        ├── pyproject.toml
+        └── main.py
 ```
 
-Use the `src/` layout for import safety and packaging clarity. Keep tests under `tests/` and shared test setup in `tests/conftest.py`. Do not introduce `requirements.txt`, `setup.py`, `setup.cfg`, `tox.ini`, `ruff.toml`, or `pyrightconfig.json` by default; keep project metadata and tool configuration in `pyproject.toml`.
+Keep the repository root clean: source code, tests, distribution artifacts, and package metadata live under `lib/`, while the root contains only orchestration and repository-level files.
+
+Use the `lib/src/` layout for import safety and packaging clarity. Keep tests under `lib/tests/` and shared test setup in `lib/tests/conftest.py`. Do not introduce `requirements.txt`, `setup.py`, `setup.cfg`, `tox.ini`, `ruff.toml`, or `pyrightconfig.json` by default; keep project metadata and tool configuration in `lib/pyproject.toml`.
 
-Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/007-project-quality-standards.md).
+Libraries and shared utilities must include an `examples/` folder and wire example execution into the root `test` flow, following [agentme-edr-007](../principles/007-project-quality-standards.md). Each example directory is its own Python project with its own `pyproject.toml`, and examples must import the library as a consumer would rather than reaching back into `lib/src/` with relative imports. Local example verification must install the wheel built into `lib/dist/`; do not use editable or path-based dependencies back to `lib/`.
 
-#### `pyproject.toml`
+Python keeps unit tests under `lib/tests/` by default because that remains the more common and maintainable convention for typed/package-based projects than co-locating tests beside every source file. Integration tests belong in `lib/tests_integration/`, and benchmark harnesses belong in `lib/tests_benchmark/` when they are more than a single micro-benchmark helper.
+
+#### `lib/pyproject.toml`
 
 - Runtime dependencies belong in `[project.dependencies]`.
 - Development-only tooling belongs in `[dependency-groups].dev`.
-- Configure Ruff, Pyright, and Pytest in `pyproject.toml` under their `tool.*` sections.
-- Commit `uv.lock` and keep it in sync with `pyproject.toml`.
+- Configure Ruff, Pyright, and Pytest in `lib/pyproject.toml` under their `tool.*` sections.
+- Commit `lib/uv.lock` and keep it in sync with `lib/pyproject.toml`.
 - Expose CLI entry points with `[project.scripts]` when the project provides commands.
 
+When Pyright runs from `lib/`, configure it to discover the shared root virtual environment, for example with `venvPath = ".."` and `venv = ".venv"`.
+
 Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
 
 Pyright must run on every lint pass. `typeCheckingMode = "standard"` is the minimum baseline; projects may raise this to `strict` when the codebase is ready.
@@ -79,21 +103,37 @@ Pytest coverage must fail below 80% line and branch coverage, following [agentme
 
 The commands below assume invocation through `mise exec -- make <target>` when the repository uses Mise, or plain `make <target>` inside an activated project environment.
 
+#### Root `Makefile`
+
+The root `Makefile` is the only contract for CI and contributors. It delegates library work to `lib/` and runs each example project in `examples/` against the shared root `.venv/`.
+
 | Target | Description |
 |--------|-------------|
-| `install` | `uv sync --frozen --all-extras --dev` |
-| `build` | `uv sync --frozen --all-extras --dev && uv build` |
-| `lint` | `uv run ruff format --check . && uv run ruff check . && uv run pyright && uv run pip-audit` |
-| `lint-fix` | `uv run ruff format . && uv run ruff check . --fix && uv run pyright && uv run pip-audit` |
-| `test-unit` | `uv run pytest --cov=src/<package_name> --cov-branch --cov-report=term-missing --cov-fail-under=80` |
-| `test-examples` | Run `examples/` through its own `Makefile` when the project is a library/utility |
+| `install` | Run `lib/install` to create or update the shared root `.venv/` |
+| `build` | Run `lib/build` |
+| `lint` | Run `lib/lint` |
+| `lint-fix` | Run `lib/lint-fix` |
+| `test-unit` | Run `lib/test-unit` |
+| `test-examples` | For each `examples/*/pyproject.toml`, sync and run the example serially against the shared root `.venv/` |
 | `test` | Run `test-unit`, then `test-examples` when applicable |
-| `clean` | Remove `.venv/`, `dist/`, `.pytest_cache/`, `.ruff_cache/`, `.coverage`, `htmlcov/` |
+| `clean` | Remove the shared root `.venv/`, root `.cache/`, and delegate cleanup to `lib/` |
 | `all` | `build lint test` |
-| `update-lockfile` | `uv lock --upgrade` |
-| `run` | `uv run python -m <package_name>` or the project CLI entry point |
+
+#### `lib/Makefile`
+
+| 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/` |
+| `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 |
 | `dev` | Same as `run`, optionally with repository-specific dev defaults |
-| `publish` | `uv publish` after versioning and packaging are complete |
+| `publish` | `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).
 
@@ -101,8 +141,8 @@ The root `Makefile` must remain the only contract for CI and contributors, in li
 
 * (REJECTED) **Mixed Python tooling** - Separate tools and config files such as `pip`, `requirements.txt`, `setup.cfg`, `flake8`, and `mypy`.
   * Reason: Increases cognitive load, duplicates configuration, and weakens the standard command surface across projects.
-* (CHOSEN) **uv + `pyproject.toml` + Ruff/Pyright/Pytest toolchain** - One dependency manager, one config file, and one Makefile entry point.
-  * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent.
+* (CHOSEN) **uv + `lib/` package layout + Ruff/Pyright/Pytest toolchain** - One dependency manager, package internals isolated under `lib/`, consumer examples under `examples/`, and one root Makefile contract.
+  * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent while aligning Python repositories with the established JavaScript layout.
 
 ## References
 

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

@@ -13,12 +13,13 @@ compatibility: JavaScript/TypeScript, Node.js 18+
 
 ## Overview
 
-Creates a complete JavaScript/TypeScript library project from scratch. The layout separates
-library source (`lib/`) from runnable usage examples (`examples/`), coordinated by root-level
-Makefiles. Boilerplate is derived from the [filedist](https://github.com/flaviostutz/filedist)
+Creates a complete JavaScript/TypeScript library project from scratch. The layout keeps the
+published package self-contained in its module root (`lib/`), places runnable consumer examples in
+the sibling `examples/` folder, redirects persistent caches into `.cache/`, and uses Makefiles as
+the only entry points. Boilerplate is derived from the [filedist](https://github.com/flaviostutz/filedist)
 project.
 
-Related EDR: [agentme-edr-003](../../003-javascript-project-tooling.md)
+Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
 
 ## Instructions
 
@@ -72,6 +73,7 @@ pnpm = "10.14.0"
 ```
 node_modules/
 dist/
+.cache/
 *.tgz
 .filedist
 ```
@@ -105,24 +107,29 @@ describe('hello', () => {
 ```makefile
 SHELL := /bin/bash
 MISE := mise exec --
+CACHE_DIR := .cache
 
 build: install
 	@rm -rf dist
-  $(MISE) pnpm exec tsc --outDir dist
+  @mkdir -p $(CACHE_DIR)/tsc
+  $(MISE) pnpm exec tsc --incremental --tsBuildInfoFile $(CACHE_DIR)/tsc/tsconfig.tsbuildinfo --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 	@# Create pack for use by examples to simulate real external usage
   $(MISE) pnpm pack --pack-destination dist
 
 build-module: install
 	@rm -rf dist
-  $(MISE) pnpm exec tsc --outDir dist
+  @mkdir -p $(CACHE_DIR)/tsc
+  $(MISE) pnpm exec tsc --incremental --tsBuildInfoFile $(CACHE_DIR)/tsc/tsconfig.tsbuildinfo --outDir dist
 	@-find ./dist \( -regex '.*\.test\..*' -o -regex '.*__tests.*' \) -exec rm -rf {} \; 2> /dev/null
 
 lint:
-  $(MISE) pnpm exec eslint ./src
+  @mkdir -p $(CACHE_DIR)/eslint
+  $(MISE) pnpm exec eslint ./src --cache --cache-location $(CACHE_DIR)/eslint/.eslintcache
 
 lint-fix:
-  $(MISE) pnpm exec eslint ./src --fix
+  @mkdir -p $(CACHE_DIR)/eslint
+  $(MISE) pnpm exec eslint ./src --fix --cache --cache-location $(CACHE_DIR)/eslint/.eslintcache
 
 test-watch:
   $(MISE) pnpm exec jest --watch
@@ -133,6 +140,7 @@ test:
 clean:
 	rm -rf node_modules
 	rm -rf dist
+  rm -rf .cache
 
 all: build lint test
 
@@ -223,6 +231,8 @@ Use this single tsconfig for both build and type-aware linting. Keep `*.test.ts`
 module.exports = {
   testEnvironment: 'node',
   testMatch: ['**/*.test.ts'],
+  cacheDirectory: '<rootDir>/.cache/jest',
+  coverageDirectory: '<rootDir>/.cache/coverage',
   collectCoverageFrom: ['src/**/*.ts', '!src/**/*.test.ts'],
   transform: {
     '^.+\\.tsx?$': [
@@ -323,7 +333,29 @@ console.log(result);
 
 ---
 
-### Phase 5: Create `README.md`
+### Phase 5: Create `README.md` and `lib/README.md`
+
+Keep the repository README focused on the workspace and the module README focused on consumers of
+the published package.
+
+**`README.md`**
+
+```markdown
+# [package-name]
+
+[description]
+
+## Getting Started
+
+```bash
+mise install
+make test
+```
+
+The published module lives in `lib/` and runnable consumer examples live in `examples/`.
+```
+
+**`lib/README.md`**
 
 Quick Start must appear at the top — it is rendered first on the npm registry page.
 
@@ -334,28 +366,37 @@ Quick Start must appear at the top — it is rendered first on the npm registry
 
 ## Quick Start
 
-\`\`\`bash
+```bash
 pnpm add [package-name]
-\`\`\`
+```
 
-\`\`\`typescript
+```typescript
 import { hello } from '[package-name]';
 
 const greeting = hello('world');
 console.log(greeting); // Hello, world!
-\`\`\`
+```
 
 ## Installation
 
-\`\`\`bash
+```bash
 npm install [package-name]
 # or
 pnpm add [package-name]
-\`\`\`
+```
 
 ## Examples
 
-See the [examples/](examples/) folder for complete runnable examples.
+See the sibling `examples/` folder for complete runnable examples that consume the packed artifact
+from `lib/dist/`.
+
+## Development
+
+```bash
+make build
+make lint
+make test
+```
 
 ## License
 
@@ -369,12 +410,13 @@ MIT
 Review all created files and confirm:
 
 - [ ] Root `Makefile` delegates to both `lib/` and `examples/`
+- [ ] `.gitignore` ignores `dist/` and `.cache/`
 - [ ] `lib/src/index.ts` exports at least one symbol
 - [ ] `lib/src/index.test.ts` has at least one passing test
 - [ ] `lib/package.json` has `main`, `types`, and `files` set correctly
 - [ ] `lib/tsconfig.json` includes co-located `src/**/*.test.ts` files for ESLint type-aware parsing
 - [ ] `lib/eslint.config.mjs` points `parserOptions.project` to `tsconfig.json`
-- [ ] `README.md` starts with Quick Start containing a code example
+- [ ] `lib/README.md` starts with Quick Start and ends with module development commands
 - [ ] All `[package-name]` placeholders are replaced with the actual name
 - [ ] Structure matches the layout in [agentme-edr-003](../../003-javascript-project-tooling.md)
 
@@ -384,9 +426,9 @@ Review all created files and confirm:
 
 **Agent action:** Gathers: name=`retry-client`, default Node.js 24, then creates:
 - `./Makefile`, `./.mise.toml`, `./.gitignore`
-- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.mjs`
+- `lib/src/index.ts`, `lib/src/index.test.ts`, `lib/Makefile`, `lib/README.md`, `lib/package.json`, `lib/tsconfig.json`, `lib/jest.config.js`, `lib/eslint.config.mjs`
 - `examples/Makefile`, `examples/usage-basic/package.json`, `examples/usage-basic/index.js`
-- `README.md` (Quick Start first)
+- `README.md` (workspace overview)
 
 All `[package-name]` replaced with `retry-client`.
 

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

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