agentme 0.3.3 → 0.6.0

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

@@ -1,3 +1,8 @@
+---
+name: agentme-edr-003-javascript-project-tooling-and-structure
+description: Defines the standard JavaScript and TypeScript project toolchain and layout using Mise, pnpm, TypeScript, ESLint, Jest, and Makefiles. Use when scaffolding or reviewing JavaScript projects.
+---
+
 # agentme-edr-003: JavaScript project tooling and structure
 
 ## Context and Problem Statement
@@ -8,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.
 
@@ -42,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
@@ -78,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` |
 
@@ -93,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

@@ -1,3 +1,8 @@
+---
+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.
+---
+
 # agentme-edr-010: Go project tooling and structure
 
 ## Context and Problem Statement
@@ -8,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.
 
@@ -29,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
 
@@ -69,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 |
 
@@ -107,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

@@ -0,0 +1,152 @@
+---
+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.
+---
+
+# agentme-edr-014: Python project tooling and structure
+
+## Context and Problem Statement
+
+Python projects often drift into mixed dependency managers, duplicated configuration files, and ad hoc quality checks, which makes onboarding and CI pipelines inconsistent.
+
+What tooling and project structure should Python projects follow to ensure consistency, quality, and ease of development?
+
+## 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.**
+
+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
+
+#### Tooling
+
+| Tool | Purpose |
+|------|---------|
+| **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 |
+| **pyright** | Static type checking |
+| **pytest** | Test runner |
+| **pytest-cov** | Coverage reporting and threshold enforcement |
+| **pip-audit** | Dependency CVE audit |
+
+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 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
+├── .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
+```
+
+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). 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/`.
+
+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 `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.
+
+Pytest coverage must fail below 80% line and branch coverage, following [agentme-edr-004](../principles/004-unit-test-requirements.md).
+
+#### 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.
+
+#### 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` | 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 the shared root `.venv/`, root `.cache/`, and delegate cleanup to `lib/` |
+| `all` | `build lint test` |
+
+#### `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 --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).
+
+## Considered Options
+
+* (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 + `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
+
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) - Coverage and unit-test baseline
+- [agentme-edr-007](../principles/007-project-quality-standards.md) - Examples and quality requirements
+- [agentme-edr-008](../devops/008-common-targets.md) - Standard Makefile target names
+- [005-create-python-project](skills/005-create-python-project/SKILL.md) - Scaffold a project following this EDR

package/.xdrs/agentme/edrs/application/015-cli-tool-standards.md

@@ -0,0 +1,107 @@
+---
+name: agentme-edr-015-cli-tool-standards
+description: Defines how distributable CLI tools should separate command handling from library logic and expose consistent command behavior. Use when designing or reviewing CLI interfaces.
+applied-to: Distributable CLI tools and their standalone libraries
+---
+
+# agentme-edr-015: CLI tool standards
+
+## Context and Problem Statement
+
+CLI projects often mix command parsing, business logic, config loading, and output formatting in one entry point, making them hard to reuse as libraries and inconsistent to operate.
+
+What structure and interface rules should distributable CLI tools follow so they remain discoverable, scriptable, and reusable outside the command line?
+
+## Decision Outcome
+
+**Use a command-oriented CLI as a thin adapter over a standalone library, with CLI-owned config discovery, mandatory help/version/verbose flags, and consistent progress and exit behavior.**
+
+This keeps the user-facing command predictable while preserving a clean library API for embedding, testing, and automation.
+
+### Implementation Details
+
+#### CLI command surface
+
+- CLI tools should default to the format `[tool] [command] [options] [arguments]`.
+- Example: `filedist extract --packages=test mydir`
+- A single-action tool may omit `[command]` only when adding a subcommand would be artificial and there is no meaningful action split.
+- Every CLI tool must expose:
+  - `--help` on the root command
+  - `--version` on the root command
+  - `--verbose` on the root command and on subcommands when flags are parsed per command
+- Root `--help` output must list all available commands, key options, and usage examples. Command-specific help must describe that command's arguments and options.
+
+#### CLI to library separation
+
+- Structure the software as `cli -> lib`.
+- The CLI layer must only parse arguments, load config, call the library, and format output.
+- Domain logic must live in the library and be usable without CLI globals such as `argv`, `stdout`, or process exit handlers.
+- Every feature available through the CLI must also be available through the library API.
+- Organize the library by action so the mapping stays direct and obvious.
+  - `extract` command -> `extract(...)`
+  - `validate` command -> `validate(...)`
+- Avoid one generic library `run()` entry point that hides action-specific contracts behind switches or string commands.
+
+#### Library API shape
+
+- Each CLI action should map to a dedicated exported API with typed inputs and outputs appropriate for the language.
+- Library APIs should accept in-memory options objects or typed parameters, not require config files or environment variables unless library-level config-file support is an explicit requirement.
+- The CLI layer is responsible for translating flags, positional arguments, and config-file contents into library inputs.
+- The library should return explicit results and errors so the CLI can decide what to print and which exit code to use.
+
+#### Configuration
+
+- Prefer flags and positional arguments for simple inputs.
+- When configuration becomes long, nested, or repetitive, support a config file instead of pushing all values into flags.
+- By default, config-file discovery and loading must happen in the CLI layer, not in the library layer.
+- When a config file is supported, the CLI should try to load a JSON config file from `[cwd]/.[cli-name]rc` by default.
+- The CLI should also support an explicit config path flag such as `--config`.
+- For JavaScript tools, `cosmiconfig` is an acceptable implementation. Equivalent discovery libraries are acceptable in other ecosystems.
+- The library must not depend on the presence of the config file; it should receive parsed configuration values from the CLI layer.
+- The library may load or parse config files only when that behavior is an explicit requirement of the library contract for non-CLI consumers as well.
+
+#### Output and progress
+
+- Standard output must show a start message when work begins and a result message when work completes successfully.
+- When processing is long-running or multi-stage, print concise intermediate progress messages.
+- `--verbose` must reveal more internal detail about what the tool is doing without changing the meaning of the command result.
+- Default output should stay concise and readable for humans.
+- Errors should be written to standard error with an actionable message. Stack traces or raw internal errors should stay hidden by default and may be shown in verbose mode.
+
+#### Exit behavior
+
+- Exit with `0` only when the requested action completed successfully.
+- Exit with `1` when the requested action could not be completed.
+- The library should surface failure as return values, result objects, or language-idiomatic errors; the CLI is responsible for converting that outcome into user-facing messages and process exit codes.
+
+#### Documentation
+
+- `README.md` must include at least 4 CLI usage examples.
+- `README.md` must include at least 2 library API examples for the same operation also available through the CLI.
+- If the tool supports config files, at least 1 README example should show config-file usage.
+- Examples must use the public command and public library API, not internal modules or private files.
+
+#### Distribution and versioning
+
+- The implementation language is project-dependent, but the packaging and entry-point strategy must match how users are expected to run the tool.
+- Choose language tooling that stays compatible with ecosystem launchers such as `npx`, `pnpm dlx`, `uvx`, or equivalent distribution commands for that ecosystem.
+- `--version` must print the same version declared in the published package or release artifact metadata.
+- Do not hard-code a second version string that can drift from the published package version.
+- Language-specific project structure and packaging rules still apply and should be combined with this XDR, especially [agentme-edr-003](003-javascript-project-tooling.md), [agentme-edr-010](010-golang-project-tooling.md), and [agentme-edr-014](014-python-project-tooling.md).
+
+## Considered Options
+
+* (REJECTED) **Ad hoc CLIs with embedded business logic** - Keep parsing, processing, config loading, and output formatting inside a single entry point.
+  * Reason: Makes the tool hard to test, hard to reuse as a library, and inconsistent across commands.
+* (CHOSEN) **Thin CLI adapter over action-oriented library APIs** - Keep the CLI responsible for user interaction and the library responsible for the actual behavior.
+  * Reason: Preserves a clean programmatic API, keeps command behavior discoverable, and makes the CLI-to-library mapping easy to maintain.
+
+## References
+
+- [agentme-edr-003](003-javascript-project-tooling.md) - JavaScript project packaging and structure
+- [agentme-edr-007](../principles/007-project-quality-standards.md) - README and examples baseline
+- [agentme-edr-008](../devops/008-common-targets.md) - Standard command names for project entry points
+- [agentme-edr-009](../principles/009-error-handling.md) - Process error signaling and error handling expectations
+- [agentme-edr-010](010-golang-project-tooling.md) - Go CLI structure and verbose logging baseline
+- [agentme-edr-014](014-python-project-tooling.md) - Python packaging and CLI entry-point guidance
+- [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) - Example JSON configuration discovery library for JavaScript CLIs

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`.