agentme 0.10.0 → 0.11.0

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

@@ -19,7 +19,7 @@ What tooling and project structure should JavaScript/TypeScript projects follow
 
 Clear, consistent tooling and layout enable fast onboarding, reliable CI pipelines, and a predictable developer experience across projects.
 
-### Implementation Details
+### Details
 
 #### Tooling
 
@@ -46,6 +46,23 @@ Use a single `lib/tsconfig.json` for both build and type-aware linting. Keep co-
 
 When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `module` is `nodenext`. `ts-jest` still runs in CommonJS mode by default, so `lib/jest.config.js` MUST configure the `ts-jest` transform with an inline `tsconfig` override that sets `module: 'commonjs'`. Do not use the deprecated `globals['ts-jest']` configuration style.
 
+#### Coverage
+
+Jest must enforce 80% line and branch coverage, following [agentme-edr-004](../principles/004-unit-test-requirements.md). Configure thresholds in `lib/jest.config.js`:
+
+```js
+coverageThreshold: {
+  global: {
+    lines: 80,
+    branches: 80,
+  },
+},
+coverageProvider: 'v8',
+coverageDirectory: '.cache/coverage',
+```
+
+Builds that miss the threshold must not be merged.
+
 #### Project structure
 
 ```
@@ -64,8 +81,14 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 │   ├── .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
+│       ├── index.ts       # public API re-exports from app/
+│       ├── adapters/      # I/O boundary layer (following agentme-edr-021)
+│       │   ├── cli/       # inbound: CLI bootstrap and entry point
+│       │   ├── http/      # inbound: HTTP server bootstrap and handlers
+│       │   └── connectors/ # outbound: one folder per external resource
+│       ├── app/           # core business logic
+│       │   └── *.test.ts  # test files co-located with source
+│       └── shared/        # infrastructure-agnostic utilities
 ├── examples/              # runnable usage examples outside the module root
 │   ├── Makefile           # build + test all examples in sequence
 │   ├── usage-x/           # first example
@@ -78,9 +101,20 @@ When `tsconfig.json` extends `@tsconfig/node24/tsconfig.json`, the default `modu
 
 The root `Makefile` delegates every target to `/lib` then `/examples` in sequence. Parent Makefiles should call child Makefiles directly, and each module Makefile is responsible for running its actual tool commands through `mise exec --`.
 
+Internal source code MUST be organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities). The public API entry point (`index.ts`) re-exports from `app/`.
+
 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.
+All tool caches, incremental state files, and workspace-local config outputs MUST be written under `.cache/`. This applies to every tool without exception. Cache and state paths MUST be declared in the tool's own configuration file — never on the command line — so that the location is enforced regardless of how the tool is invoked:
+
+| Tool | Config file | Setting | Value |
+|------|------------|---------|-------|
+| **Jest** | `jest.config.js` | `cacheDirectory` | `.cache/jest` |
+| **ESLint** | `eslint.config.mjs` | `cache: true, cacheLocation: '.cache/eslint'` | (set in config object) |
+| **TypeScript** | `tsconfig.json` | `tsBuildInfoFile` | `.cache/tsbuildinfo` |
+| **Jest coverage** | `jest.config.js` | `coverageDirectory` | `.cache/coverage` |
+
+No tool MUST write cache or state files to the project root, `src/`, or any other directory outside `.cache/`. Passing cache paths as Makefile or CLI flags instead of config-file settings is not allowed.
 
 Contributors and CI MUST invoke the commands below as `make <target>`. The Makefile recipes themselves MUST call the underlying tools through `mise exec -- <tool> ...`.
 
@@ -93,7 +127,7 @@ Contributors and CI MUST invoke the commands below as `make <target>`. The Makef
 | `build-module` | `mise exec -- pnpm exec tsc ...` only (no pack) |
 | `lint` | `mise exec -- pnpm exec eslint ./src` |
 | `lint-fix` | `mise exec -- pnpm exec eslint ./src --fix` |
-| `test` | `mise exec -- pnpm exec jest --verbose` |
+| `test` | `mise exec -- pnpm exec jest --verbose --coverage` |
 | `test-watch` | `mise exec -- pnpm exec jest --watch` |
 | `clean` | remove `node_modules/`, `dist/`, and `.cache/` |
 | `all` | `build lint test` |
@@ -120,5 +154,7 @@ The examples folder MUST exist for any libraries and utilities that are publishe
 
 ## References
 
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Coverage and unit-test baseline
+- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Internal adapter/application layer separation for applications
 - [001-create-javascript-project](skills/001-create-javascript-project/SKILL.md) — scaffolds a new project following this structure
 

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

@@ -19,7 +19,7 @@ What tooling and project structure should Go projects follow to ensure consisten
 
 A predictable layout and minimal external tooling keep Go projects approachable, fast to build, and easy to distribute as cross-platform binaries.
 
-### Implementation Details
+### Details
 
 #### Tooling
 
@@ -47,16 +47,25 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 ├── main.go                    # binary entry point — argument dispatch only, no logic
 ├── .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>/
+├── adapters/                  # I/O boundary layer (following agentme-edr-021)
+│   ├── cli/                   # inbound: CLI wiring — flag parsing, output formatting
+│   │   └── *.go               # subfolders per feature only when complexity warrants it
+│   ├── http/                  # inbound: HTTP server bootstrap and handlers
 │   │   └── *.go
+│   └── connectors/            # outbound: one folder per external resource
+│       ├── postgres/
+│       │   └── *.go
+│       └── stripe-api/
+│           └── *.go
+├── app/                       # core business logic packages
+│   ├── <feature-a>/
+│   │   ├── *.go
+│   │   └── *_test.go
 │   └── <feature-b>/
-│       └── *.go
+│       ├── *.go
+│       └── *_test.go
+├── shared/                    # infrastructure-agnostic utilities shared across adapters and app
+│   └── *.go
 ├── tests_integration/         # optional integration tests for this module
 ├── tests_benchmark/           # optional benchmark harnesses and datasets
 └── examples/                  # optional sibling consumer examples for libraries
@@ -64,12 +73,16 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 
 **Key layout rules:**
 
+- Internal source code is organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
 - 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/`.
+- `main.go` is solely an argument dispatcher — it reads `os.Args[1]` and delegates to an `adapters/cli/<feature>/Run*()` function. No domain logic lives in `main.go`.
+- Business logic lives in named feature packages under `app/` (e.g., `app/ownership/`, `app/changes/`). These packages are importable and testable without any CLI or adapter concerns.
+- `adapters/cli/` packages own flag parsing, output formatting, and the wiring between flags and `app/` functions. No business logic lives in adapter packages.
+- Outbound adapters live under `adapters/connectors/` with one subfolder per external resource, named descriptively (e.g., `postgres/`, `stripe-api/`, `redis-cache/`).
+- `shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
 - Packages are flat by default; sub-packages are only introduced when a feature package itself exceeds ~400 lines or has clearly separable sub-concerns.
+- Application MAY import from Adapters when it simplifies the design (pragmatic coupling per edr-021 rule 05).
 - 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
@@ -94,7 +107,8 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 | `test-unit` | `mise exec -- go test -cover ./...` — alias for unit tests only (same here; integration tests get a separate tag) |
 | `coverage` | `mise exec -- go tool cover -func .cache/coverage.out` — displays coverage summary |
 | `clean` | Remove `dist/` and `.cache/` |
-| `start` | `mise exec -- go run ./ <default-args>` — launch the binary locally for dev use |
+| `run` | `mise exec -- go run ./ <default-args>` — launch the binary locally |
+| `run-http` | `mise exec -- go run ./ http` — launch the HTTP inbound adapter |
 | `publish` | Tag with `mise exec -- npx -y monotag ...`, then push tag + binaries to GitHub Releases |
 
 The required invocation pattern is:
@@ -125,7 +139,16 @@ When the project produces a CLI binary for end-users:
 - 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.
+All tool caches, incremental state files, and build outputs MUST be written under `.cache/`. Neither `go` nor `golangci-lint` support a project-level config file for cache paths, so environment variables are the only available mechanism. These MUST be declared as top-level exports at the top of the module `Makefile` (not passed as per-recipe CLI flags or inline env overrides) so they apply to every recipe consistently:
+
+| Tool | Mechanism | Makefile export |
+|------|-----------|------------------|
+| **Go build cache** | `GOCACHE` env var | `export GOCACHE := $(CURDIR)/.cache/go-build` |
+| **Go module cache** | `GOMODCACHE` env var | `export GOMODCACHE := $(CURDIR)/.cache/go-mod` |
+| **golangci-lint cache** | `GOLANGCI_LINT_CACHE` env var | `export GOLANGCI_LINT_CACHE := $(CURDIR)/.cache/golangci-lint` |
+| **Test coverage output** | `-coverprofile` flag in `test` target | `.cache/coverage.out` |
+
+No tool MUST write cache or state files to the project root or any directory outside `.cache/`. Passing cache paths as per-recipe environment overrides instead of top-level Makefile exports is not allowed.
 
 #### Linting
 
@@ -151,8 +174,9 @@ Use `github.com/sirupsen/logrus` for structured logging. Set the log level from
 
 #### CLI flag parsing
 
-Use the standard library `flag` package for CLI flags. Each `cli/<feature>` package defines its own `FlagSet`, parses it from `os.Args[2:]`, and calls the corresponding domain function.
+Use the standard library `flag` package for CLI flags. Each `adapters/cli/<feature>` package defines its own `FlagSet`, parses it from `os.Args[2:]`, and calls the corresponding `app/` function.
 
 ## References
 
+- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Defines the adapter/application separation that this layout follows
 - [003-create-golang-project](skills/003-create-golang-project/SKILL.md) — scaffolds a new Go project following this structure

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

@@ -19,7 +19,7 @@ What tooling and project structure should Python projects follow to ensure consi
 
 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
+### Details
 
 #### Tooling
 
@@ -40,14 +40,24 @@ The repository root MUST define a `.mise.toml` that pins Python and uv. Contribu
 
 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.
+All tool caches, incremental state files, and workspace-local outputs MUST be written under `.cache/`. Cache paths MUST be declared in the tool's own configuration file — never on the command line or as Makefile CLI flags — so the location is enforced regardless of how the tool is invoked. Configure the following in `lib/pyproject.toml`:
+
+| Tool | Config section | Setting | Value |
+|------|---------------|---------|-------|
+| **Ruff** | `[tool.ruff]` | `cache-dir` | `".cache/ruff"` |
+| **pytest** | `[tool.pytest.ini_options]` | `cache_dir` | `".cache/pytest"` |
+| **coverage** | `[tool.coverage.run]` | `data_file` | `".cache/.coverage"` |
+| **coverage HTML** | `[tool.coverage.html]` | `directory` | `".cache/coverage-html"` |
+| **uv** | `[tool.uv]` in `lib/pyproject.toml` | `cache-dir` | `".cache/uv"` |
+
+No tool MUST write cache or state files to the project root, `src/`, `tests/`, or any directory outside `.cache/`. Passing cache paths as CLI flags or Makefile recipe-level env overrides instead of `pyproject.toml` settings is not allowed.
 
 #### Project structure
 
 ```text
 /
 ├── .mise.toml              # required; pins Python and uv
-├── .gitignore
+├── .gitignore              # MUST ignore .venv/, dist/, .cache/, __pycache__/
 ├── .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/
@@ -61,8 +71,12 @@ Persistent caches must live under `.cache/`, preferably the module `lib/.cache/`
 │   ├── src/
 │   │   └── <package_name>/
 │   │       ├── __init__.py
-│   │       ├── __main__.py # when the project exposes a CLI
-│   │       └── ...
+│   │       ├── adapters/       # I/O boundary layer (following agentme-edr-021)
+│   │       │   ├── cli/        # inbound: CLI bootstrap and entry point
+│   │       │   ├── http/       # inbound: HTTP server bootstrap
+│   │       │   └── connectors/ # outbound: one folder per external resource
+│   │       ├── app/            # core business logic
+│   │       └── shared/         # infrastructure-agnostic utilities
 │   ├── tests/
 │   │   ├── conftest.py     # shared fixtures when needed
 │   │   └── test_*.py
@@ -82,6 +96,8 @@ Keep the repository root clean: source code, tests, distribution artifacts, and
 
 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`.
 
+Internal source code MUST be organized following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md): `adapters/` (inbound and outbound I/O boundaries), `app/` (business logic), and `shared/` (infrastructure-agnostic utilities).
+
 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.
@@ -98,6 +114,48 @@ When Pyright runs from `lib/`, configure it to discover the shared root virtual
 
 Ruff is the default formatter and linter. Do not add Black, isort, or Flake8 unless another XDR for that repository explicitly requires them.
 
+All Python projects must configure the following sections in `lib/pyproject.toml`. The cache-related settings are mandatory per the `.cache/` policy above:
+
+```toml
+[tool.pytest.ini_options]
+cache_dir = ".cache/pytest"
+
+[tool.coverage.run]
+data_file = ".cache/.coverage"
+
+[tool.coverage.html]
+directory = ".cache/coverage-html"
+
+[tool.uv]
+cache-dir = ".cache/uv"
+
+[tool.ruff]
+cache-dir = ".cache/ruff"
+output-format = "grouped"
+line-length = 120
+target-version = "py311"
+src = ["src", "tests", "tests_integration"]
+
+[tool.ruff.format]
+docstring-code-format = true
+line-ending = "lf"
+
+[tool.ruff.lint]
+task-tags = ["TODO"]
+select = ["ERA", "FAST", "ANN", "ASYNC", "S", "BLE", "FBT", "B", "A", "COM",
+  "C4", "DTZ", "T10", "DJ", "EM", "EXE", "FIX", "INT", "ISC", "ICN", "LOG", "G",
+  "INP", "PIE", "T20", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SIM", "SLOT", "TID",
+  "TC", "ARG", "PTH", "FLY", "I", "C90", "NPY", "PD", "N", "PERF", "E", "W",
+  "D", "F", "PGH", "PL", "UP", "FURB", "RUF", "TRY"]
+ignore = ["ANN002", "ANN003", "ANN401", "D100", "D101", "D102", "D103", "D104",
+  "D105", "D106", "D107", "COM812", "D203", "D213", "D400", "D401", "D404", "D415", "FIX002"]
+
+[tool.ruff.lint.pycodestyle]
+ignore-overlong-task-comments = true
+```
+
+Adjust `target-version` to match the project's minimum supported Python version. The `cache-dir` keeps Ruff's cache under `.cache/ruff` alongside other tool caches. The `src` list must include every directory that contains importable Python code. The `select` list enables a broad set of rules covering style, correctness, performance, security, and documentation. The `ignore` list suppresses rules that are either too noisy or conflict with the chosen docstring style.
+
 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).

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

@@ -19,7 +19,7 @@ What structure and interface rules should distributable CLI tools follow so they
 
 This keeps the user-facing command predictable while preserving a clean library API for embedding, testing, and automation.
 
-### Implementation Details
+### Details
 
 #### CLI command surface
 
@@ -32,34 +32,34 @@ This keeps the user-facing command predictable while preserving a clean library
   - `--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
+#### CLI to application 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.
+- Structure the software as `cli -> app` — the CLI adapter delegates to the application layer, following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md).
+- The CLI layer must only parse arguments, load config, call the application layer, and format output.
+- Domain logic must live in the application layer 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 application API.
+- Organize the application layer by action so the mapping stays direct and obvious.
+  - `extract` command -> `app/extract(...)`
+  - `validate` command -> `app/validate(...)`
+- Avoid one generic `run()` entry point that hides action-specific contracts behind switches or string commands.
 
-#### Library API shape
+#### Application 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.
+- Each CLI action should map to a dedicated exported application function with typed inputs and outputs appropriate for the language.
+- Application APIs should accept in-memory options objects or typed parameters, not require config files or environment variables unless application-level config-file support is an explicit requirement.
+- The CLI layer is responsible for translating flags, positional arguments, and config-file contents into application inputs.
+- The application layer 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.
+- By default, config-file discovery and loading must happen in the CLI layer, not in the application 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.
+- The application layer must not depend on the presence of the config file; it should receive parsed configuration values from the CLI layer.
+- The application layer may load or parse config files only when that behavior is an explicit requirement of the application contract for non-CLI consumers as well.
 
 #### Output and progress
 
@@ -73,14 +73,14 @@ This keeps the user-facing command predictable while preserving a clean library
 
 - 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.
+- The application layer 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.
+- `README.md` must include at least 2 application 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.
+- Examples must use the public command and public application API, not internal modules or private files.
 
 #### Distribution and versioning
 
@@ -93,12 +93,13 @@ This keeps the user-facing command predictable while preserving a clean library
 ## 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.
+  * Reason: Makes the tool hard to test, hard to reuse programmatically, and inconsistent across commands.
+* (CHOSEN) **Thin CLI adapter over action-oriented application APIs** - Keep the CLI responsible for user interaction and the application layer responsible for the actual behavior.
+  * Reason: Preserves a clean programmatic API, keeps command behavior discoverable, and makes the CLI-to-application mapping easy to maintain.
 
 ## References
 
+- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) - Defines the adapter/application separation that the CLI layer follows
 - [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

package/.xdrs/agentme/edrs/application/018-ai-agent-development-standards.md

@@ -91,22 +91,35 @@ Agent flows MUST include at least one explicit verification node before producin
 
 #### 07-workflow-structure
 
-Agent logic MUST be organized as named workflows. Each workflow is an independent LangGraph `StateGraph` with a defined start node and end node, connecting agents, states, routes, and decision nodes.
+Agent logic MUST be organized as named workflows following [agentme-edr-021](021-pragmatic-hexagonal-architecture.md). Each workflow is an independent LangGraph `StateGraph` with a defined start node and end node, connecting agents, states, routes, and decision nodes.
 
-For each workflow named `<workflow>`, create:
+Workflows live inside `app/workflows/` (the application layer), while external integrations such as LLM providers, vector stores, and third-party APIs live under `adapters/connectors/` (the outbound adapter layer). Inbound interfaces (HTTP API, CLI) live under `adapters/` as inbound adapters.
+
+For each workflow named `<workflow>`, the full project layout is:
 
 ```text
-lib/
-  workflows/
-    <workflow>/
-      graph.py        # StateGraph definition; entry point for the workflow
-      agents.py       # LangChain agent definitions used by this workflow
-      states.py       # Typed state dataclasses / TypedDicts
-      routes.py       # Conditional edge functions
+lib/src/<package_name>/
+  adapters/
+    http/                      # inbound: API server that triggers workflows
+    cli/                       # inbound: CLI entry point (if applicable)
+    connectors/                # outbound: external resource integrations
+      openai/                  # LLM provider connector
+      azure-openai/            # alternative LLM provider connector
+      postgres/                # database connector (if applicable)
+      vector-store/            # vector DB connector (if applicable)
+  app/
+    workflows/
+      <workflow>/
+        graph.py               # StateGraph definition; entry point for the workflow
+        agents.py              # LangChain agent definitions used by this workflow
+        states.py              # Typed state dataclasses / TypedDicts
+        routes.py              # Conditional edge functions
+  shared/                      # infrastructure-agnostic utilities
 ```
 
-- `graph.py` MUST define and compile the `StateGraph` and expose a `graph` object that callers invoke.
-- Additional modules (tools, prompts, schemas) MAY be added inside `lib/workflows/<workflow>/` when they are specific to that workflow. Shared utilities belong in `lib/<module>/`.
+- `app/workflows/<workflow>/graph.py` MUST define and compile the `StateGraph` and expose a `graph` object that callers invoke.
+- Tool calls within workflow nodes that interact with external systems MUST use connectors from `adapters/connectors/`, not inline API calls.
+- Additional modules (prompts, schemas) MAY be added inside `app/workflows/<workflow>/` when they are specific to that workflow. Shared utilities belong in `shared/`.
 - Each workflow MUST be documented with a Mermaid diagram in the project `README.md` following rule `05-flow-documentation`.
 
 #### 08-workflow-evals
@@ -154,3 +167,8 @@ Use deepagents whenever ANY of the following is true for a workflow or tool:
 - If the host-side code needs to pass files into the sandbox (e.g. generated config or input data), create a temporary directory with `tempfile.mkdtemp()`, write the files there, and mount it into the sandbox. Clean it up in the `finally` block.
 - Replace hand-rolled `read_file`, `search_files`, and `grep_file` tool implementations with the equivalent tools provided by deepagents.
 
+## References
+
+- [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Adapter/application layer separation that defines the project layout
+- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
+- [agentme-edr-019](019-ml-dataset-structure.md) — ML dataset structure for eval datasets

package/.xdrs/agentme/edrs/application/021-pragmatic-hexagonal-architecture.md

@@ -0,0 +1,112 @@
+---
+name: agentme-edr-policy-021-pragmatic-hexagonal-architecture
+description: Defines a pragmatic variant of Hexagonal Architecture for organizing application source code into Adapters (inbound/outbound I/O boundaries) and Application (business logic) layers, with explicit naming conventions and folder structure. Use when designing or reviewing the internal layout of application modules.
+apply-to: All application projects
+valid-from: 2026-05-28
+---
+
+# agentme-edr-policy-021: Pragmatic hexagonal architecture
+
+## Context and Problem Statement
+
+Applications often mix business logic with infrastructure concerns (database access, HTTP handling, environment variable reading), making code hard to test, refactor, and reuse.
+
+How should application source code be organized to separate business logic from infrastructure while avoiding unnecessary abstraction layers?
+
+## Decision Outcome
+
+**Organize application source code into three conceptual layers — External (not in codebase), Adapters (inbound/outbound I/O boundaries), and Application (business logic exposed as typed library interfaces) — following a pragmatic variant of Hexagonal Architecture that avoids unnecessary abstractions.**
+
+### Details
+
+#### 01-three-layer-separation
+
+Every application is conceptually divided into three layers:
+
+| Layer | Description |
+|-------|-------------|
+| **External** | Systems outside the codebase boundary (databases, third-party APIs, message brokers, filesystems, users) |
+| **Adapters** | Bridge between External and Application — translate external protocols into application calls and vice versa |
+| **Application** | Business logic that delegates I/O to adapters |
+
+#### 02-adapter-naming-conventions
+
+**Inbound adapters** receive external requests or events and trigger application logic. Each gets a flat folder under `adapters/`:
+
+- `cli/` — command-line interface entry point
+- `http/` — HTTP/REST server
+- `grpc/` — gRPC server
+- `ws/` — WebSocket server
+- `kafka/` — Kafka consumer
+- `mqtt/` — MQTT subscriber
+- Additional inbound adapters are allowed with descriptive names
+
+**Outbound adapters** are called by the application to reach external systems. They live under `adapters/connectors/` with one subfolder per external resource, named descriptively:
+
+- e.g.: `stripe-api/`, `config-file/`, `s3-datalake/`, `whatsapp/`, `postgres/`, `redis-cache/`
+
+**Clarification:** "inbound" means the adapter triggers application logic in response to an external stimulus. "Outbound" means the application calls the adapter to interact with an external system.
+
+#### 03-application-layer-rules
+
+- Expose functionality as typed library interfaces
+- All inputs must be explicitly passed as typed parameters
+- No global variables, no direct environment variable access in `app/` or `shared/`
+- Business logic with well-defined input/output behavior
+- Group related logic into subfolders (aggregation roots)
+- Environment variables must be read only in the bootstrap/entry-point layer of inbound adapters, converted into typed configuration objects, and passed explicitly to all other components
+
+#### 04-mandatory-folder-structure
+
+```text
+mysystem/
+  Makefile             # targets to run different inbound interfaces (e.g. run-http, run-cli)
+  src/
+    adapters/          # mandatory
+      cli/             # if CLI exists — bootstrap/entry point for CLI
+      http/            # if HTTP server exists — bootstrap/entry point for HTTP
+      grpc/            # if gRPC exists
+      connectors/      # if external resource access exists
+        postgres/      # one folder per external resource
+        stripe-api/
+    app/               # mandatory — core business logic
+      feature1.ts
+      feature-group/   # optional subfolders for grouping
+    shared/            # utilities and functions shared among adapters and app
+      logging.ts
+      errors.ts
+```
+
+`shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
+
+#### 05-pragmatic-coupling
+
+- Application MAY import from Adapters when it simplifies the design
+- Avoid excessive abstractions, interface types, and indirection layers
+- Only introduce interfaces or abstract types when building a framework where the extra complexity demonstrably pays off
+- Prefer concrete implementations over abstract ports — skip the purism of classic Hexagonal Architecture in favor of practicality
+- Some coupling between Application and Adapters is acceptable and expected
+
+#### 06-bootstrap-and-entry-points
+
+- Each inbound adapter folder (`cli/`, `http/`, `grpc/`, etc.) contains the bootstrap and entry point for that interface
+- The project root Makefile must have targets to run the different inbound interfaces following [agentme-edr-008](../devops/008-common-targets.md) extension conventions (e.g. `run-http`, `run-grpc`)
+- Bootstrap code lives in the adapter that receives inbound requests, not in a separate wiring layer
+
+#### 07-minimum-complexity-threshold
+
+- Trivial scripts and single-purpose tools (fewer than ~300 lines with a single I/O boundary) MAY skip this layering
+- All other projects MUST use this structure from the start
+
+#### 08-examples-of-data-flow
+
+```text
+HTTP request  →  adapters/http/     →  app/create-user     →  adapters/connectors/postgres/
+CLI command   →  adapters/cli/      →  app/create-dir      →  adapters/connectors/local-fs/
+Kafka message →  adapters/kafka/    →  app/process-event   →  adapters/connectors/stripe-api/
+```
+
+## References
+
+- [agentme-edr-016](../principles/016-cross-language-module-structure.md) — Defines the module-root structure (Makefile, dist/, .cache/) that wraps this internal layout
+- [agentme-edr-002](../principles/002-coding-best-practices.md) — File size limits and code organization practices that complement this architecture

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

@@ -1,9 +1,9 @@
 ---
 name: agentme-edr-skill-001-create-javascript-project
 description: >
-  Scaffolds the initial boilerplate structure for a JavaScript/TypeScript library project following
+  Scaffolds the initial boilerplate structure for a JavaScript/TypeScript project following
   the standard tooling and layout defined in agentme-edr-003. Activate this skill when the user
-  asks to create, scaffold, or initialize a new JavaScript or TypeScript library project, npm
+  asks to create, scaffold, or initialize a new JavaScript or TypeScript project, npm
   package, or similar project structure.
 metadata:
   author: flaviostutz
@@ -13,13 +13,14 @@ compatibility: JavaScript/TypeScript, Node.js 18+
 
 ## Overview
 
-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.
+Creates a complete JavaScript/TypeScript project from scratch. The layout keeps the
+package self-contained in its module root (`lib/`), organizes internal code following
+[agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md) (`adapters/`, `app/`, `shared/`),
+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 EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-003](../../003-javascript-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -82,7 +83,7 @@ dist/
 
 ### Phase 3: Create `lib/`
 
-**`lib/src/index.ts`** — public API entry point:
+**`lib/src/app/hello.ts`** — business logic:
 
 ```typescript
 export const hello = (name: string): string => {
@@ -90,10 +91,10 @@ export const hello = (name: string): string => {
 };
 ```
 
-**`lib/src/index.test.ts`** — co-located unit test:
+**`lib/src/app/hello.test.ts`** — co-located unit test:
 
 ```typescript
-import { hello } from './index';
+import { hello } from './hello';
 
 describe('hello', () => {
   it('should return a greeting', () => {
@@ -102,6 +103,20 @@ describe('hello', () => {
 });
 ```
 
+**`lib/src/index.ts`** — public API re-export from `app/`:
+
+```typescript
+export { hello } from './app/hello';
+```
+
+**`lib/src/adapters/`** — create empty directories for the hexagonal structure:
+
+- `lib/src/adapters/` — inbound adapters (add `cli/`, `http/`, etc. as needed)
+- `lib/src/adapters/connectors/` — outbound adapters (one folder per external resource)
+- `lib/src/shared/` — infrastructure-agnostic utilities
+
+Create a placeholder `.gitkeep` in `lib/src/adapters/` and `lib/src/shared/` so the directories are tracked.
+
 **`lib/Makefile`**:
 
 ```makefile

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 module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
+Creates a complete Go project from scratch, following the layout from [agentme-edr-010](../../010-golang-project-tooling.md) and [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md). Business logic lives in `app/<feature>/` packages; CLI wiring lives in `adapters/cli/`; outbound integrations live in `adapters/connectors/`; `main.go` is a thin dispatcher. The module root owns its `Makefile`, `README.md`, `dist/`, and `.cache/` folders.
 
-Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-010](../../010-golang-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -67,7 +67,7 @@ import (
 	"fmt"
 	"os"
 
-	cli[Feature] "[module]/cli/[feature]"
+	cli "[module]/adapters/cli"
 )
 
 func main() {
@@ -78,7 +78,7 @@ func main() {
 
 	switch os.Args[1] {
 	case "[subcommand]":
-		cli[Feature].Run(os.Args)
+		cli.Run[Feature](os.Args)
 	default:
 		fmt.Printf("Unknown command: %s\n", os.Args[1])
 		fmt.Println("Usage: [binary] [[feature]]")
@@ -216,7 +216,7 @@ coverage.out
 
 ### Phase 3: Create the feature package
 
-**`[feature]/[feature].go`** (replace `[feature]`, `[Feature]`):
+**`app/[feature]/[feature].go`** (replace `[feature]`, `[Feature]`):
 
 ```go
 package [feature]
@@ -246,7 +246,7 @@ func Run(opts Options) (Result, error) {
 }
 ```
 
-**`[feature]/[feature]_test.go`** (replace `[feature]`, `[Feature]`):
+**`app/[feature]/[feature]_test.go`** (replace `[feature]`, `[Feature]`):
 
 ```go
 package [feature]
@@ -267,12 +267,12 @@ func Test[Feature]Run(t *testing.T) {
 
 ---
 
-### Phase 4: Create the CLI package
+### Phase 4: Create the CLI adapter
 
-**`cli/[feature]/[feature].go`** (replace `[module]`, `[feature]`, `[Feature]`, `[subcommand]`):
+**`adapters/cli/[feature].go`** (replace `[module]`, `[feature]`, `[Feature]`, `[subcommand]`):
 
 ```go
-package cli[Feature]
+package cli
 
 import (
 	"flag"
@@ -280,11 +280,11 @@ import (
 	"os"
 
 	"github.com/sirupsen/logrus"
-	"[module]/[feature]"
+	"[module]/app/[feature]"
 )
 
-// Run parses CLI flags for the [subcommand] command and calls the domain package.
-func Run(args []string) {
+// Run[Feature] parses CLI flags for the [subcommand] command and calls the domain package.
+func Run[Feature](args []string) {
 	fs := flag.NewFlagSet("[subcommand]", flag.ExitOnError)
 	verbose := fs.Bool("verbose", false, "Show verbose logs during processing")
 
@@ -309,6 +309,21 @@ func Run(args []string) {
 }
 ```
 
+**`shared/logging.go`** (optional, scaffold if needed):
+
+```go
+package shared
+
+import "github.com/sirupsen/logrus"
+
+// SetupLogging configures the global log level.
+func SetupLogging(verbose bool) {
+	if verbose {
+		logrus.SetLevel(logrus.DebugLevel)
+	}
+}
+```
+
 ---
 
 ### Phase 5: Verify and run
@@ -327,8 +342,10 @@ Fix any compile or lint errors before finishing.
 ## Conventions and reminders
 
 - `main.go` dispatches only — no logic.
-- 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.
+- Business logic only in `app/<feature>/` packages — no flag parsing, no `fmt.Println` for diagnostics.
+- `adapters/cli/` owns flag parsing, output formatting, and the wiring between flags and `app/` functions. No business logic lives in adapter packages.
+- Outbound adapters live under `adapters/connectors/` with one subfolder per external resource (e.g., `postgres/`, `stripe-api/`, `redis-cache/`).
+- `shared/` must contain only infrastructure-agnostic utilities — not business rules or domain logic.
 - 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.

package/.xdrs/agentme/edrs/application/skills/005-create-python-project/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: agentme-edr-skill-005-create-python-project
 description: >
-  Scaffolds the initial boilerplate structure for a Python library or CLI project following the
-  standard tooling and layout defined in agentme-edr-014. Activate this skill when the user asks
-  to create, scaffold, or initialize a new Python package, CLI, library, or similar project
-  structure.
+  Scaffolds the initial boilerplate structure for a Python project following the standard tooling
+  and layout defined in agentme-edr-014. Activate this skill when the user asks to create,
+  scaffold, or initialize a new Python package, CLI, or similar project structure.
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -14,11 +13,12 @@ compatibility: Python 3.12+
 ## Overview
 
 Creates a complete Python project from scratch using Mise, `uv`, `pyproject.toml`, Ruff,
-Pyright, Pytest, and Makefiles. The default layout keeps the library self-contained under `lib/`,
-uses a shared root `.venv/`, redirects persistent caches into `.cache/`, and places runnable
-consumer projects under the sibling `examples/` folder.
+Pyright, Pytest, and Makefiles. The layout keeps the package self-contained under `lib/`,
+organizes internal code following [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
+(`adapters/`, `app/`, `shared/`), uses a shared root `.venv/`, redirects persistent caches into
+`.cache/`, and places runnable consumer projects under the sibling `examples/` folder.
 
-Related EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md)
+Related EDRs: [agentme-edr-014](../../014-python-project-tooling.md), [agentme-edr-016](../../../principles/016-cross-language-module-structure.md), [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md)
 
 ## Instructions
 
@@ -30,7 +30,6 @@ Ask for or infer from context:
 - **Short description** - one sentence
 - **Author** name or GitHub username
 - **Python version** - default `3.13`
-- **Project kind** - `library` or `cli`
 - **Primary entry point** - first module or command name to scaffold
 - **GitHub repo URL** - optional, for project metadata
 - **Confirm target directory** - default: current workspace root
@@ -105,6 +104,7 @@ The root `Makefile` keeps the repository clean by delegating package work to `li
 .venv/
 dist/
 .cache/
+__pycache__/
 ```
 
 **`./README.md`**
@@ -214,11 +214,28 @@ requires = ["hatchling>=1.27.0"]
 build-backend = "hatchling.build"
 
 [tool.ruff]
-line-length = 100
+cache-dir = ".cache/ruff"
+output-format = "grouped"
+line-length = 120
 target-version = "py313"
+src = ["src", "tests", "tests_integration"]
+
+[tool.ruff.format]
+docstring-code-format = true
+line-ending = "lf"
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "B", "UP"]
+task-tags = ["TODO"]
+select = ["ERA", "FAST", "ANN", "ASYNC", "S", "BLE", "FBT", "B", "A", "COM",
+  "C4", "DTZ", "T10", "DJ", "EM", "EXE", "FIX", "INT", "ISC", "ICN", "LOG", "G",
+  "INP", "PIE", "T20", "PYI", "PT", "Q", "RSE", "RET", "SLF", "SIM", "SLOT", "TID",
+  "TC", "ARG", "PTH", "FLY", "I", "C90", "NPY", "PD", "N", "PERF", "E", "W",
+  "D", "F", "PGH", "PL", "UP", "FURB", "RUF", "TRY"]
+ignore = ["ANN002", "ANN003", "ANN401", "D100", "D101", "D102", "D103", "D104",
+  "D105", "D106", "D107", "COM812", "D203", "D213", "D400", "D401", "D404", "D415", "FIX002"]
+
+[tool.ruff.lint.pycodestyle]
+ignore-overlong-task-comments = true
 
 [tool.pyright]
 include = ["src", "tests"]
@@ -267,29 +284,37 @@ make test
 
 ### Phase 4: Create the package and tests inside `lib/`
 
-Create this baseline structure.
+Create this baseline structure following [agentme-edr-021](../../021-pragmatic-hexagonal-architecture.md).
 
 **`lib/src/[package_name]/__init__.py`**
 
 ```python
-from .core import hello
+from .app.hello import hello
 
 __all__ = ["hello"]
 ```
 
-**`lib/src/[package_name]/core.py`**
+**`lib/src/[package_name]/app/__init__.py`**
+
+```python
+```
+
+**`lib/src/[package_name]/app/hello.py`**
 
 ```python
 def hello(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-**`lib/src/[package_name]/__main__.py`**
+**`lib/src/[package_name]/adapters/__init__.py`**
 
-Use this only for CLI-oriented projects.
+```python
+```
+
+**`lib/src/[package_name]/adapters/cli/__init__.py`**
 
 ```python
-from .core import hello
+from [package_name].app.hello import hello
 
 
 def main() -> None:
@@ -300,10 +325,17 @@ if __name__ == "__main__":
     main()
 ```
 
-**`lib/tests/test_core.py`**
+**`lib/src/[package_name]/shared/__init__.py`**
+
+```python
+```
+
+Create empty `adapters/connectors/` directory with a `.gitkeep` for outbound adapters.
+
+**`lib/tests/test_hello.py`**
 
 ```python
-from [package_name].core import hello
+from [package_name].app.hello import hello
 
 
 def test_hello() -> None:
@@ -314,9 +346,9 @@ If two or more test files need shared fixtures, create `lib/tests/conftest.py` a
 
 If the module needs slower end-to-end coverage, place those tests in `lib/tests_integration/`. Put dedicated benchmark harnesses in `lib/tests_benchmark/`.
 
-### Phase 5: Create examples for libraries and utilities
+### Phase 5: Create examples
 
-If the project is a library or shared utility, add an `examples/` directory with one subdirectory per runnable consumer example. Each example must be its own Python project.
+Add an `examples/` directory with one subdirectory per runnable consumer example. Each example must be its own Python project.
 
 **`examples/basic-usage/pyproject.toml`**
 
@@ -355,14 +387,15 @@ After creating the files:
 
 ## Examples
 
-**Input:** "Create a Python library called `event_tools`"
+**Input:** "Create a Python project called `event_tools`"
 - Create `Makefile`, `README.md`, `lib/pyproject.toml`, `lib/Makefile`, `lib/src/event_tools/`, `lib/tests/`, and `examples/`
+- Scaffold `adapters/`, `app/`, `shared/` directories inside `lib/src/event_tools/`
 - Add `lib/README.md`, `.cache/` handling, and install examples from the built wheel in `lib/dist/`
 - Configure `uv`, Ruff, Pyright, Pytest, `pytest-cov`, and `pip-audit`
 - Verify with `make lint-fix`, `make test`, and `make build`
 
 **Input:** "Scaffold a Python CLI package"
-- Add `lib/src/<package_name>/__main__.py`
+- Add CLI entry point in `lib/src/<package_name>/adapters/cli/__init__.py`
 - Add `[project.scripts]` in `lib/pyproject.toml` when the command name must differ from the module name
 - Keep the same Makefile and quality checks
 

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

@@ -20,7 +20,7 @@ What monorepo structure, naming conventions, tooling, and build standards should
 For step-by-step scaffolding instructions see [skill 002-monorepo-setup](skills/002-monorepo-setup/SKILL.md).
 Module folder responsibilities, artifact locations, and test-folder conventions follow [agentme-edr-016](../principles/016-cross-language-module-structure.md).
 
-### Implementation Details
+### Details
 
 #### 01-top-level-directory-layout
 

package/.xdrs/agentme/edrs/devops/006-github-pipelines.md

@@ -19,7 +19,7 @@ What GitHub Actions workflows should every project follow to ensure a safe, pred
 
 Separating these concerns eliminates accidental publishes from CI runs, ensures monotag has access to the full git history, and makes each workflow independently auditable and re-runnable.
 
-### Implementation Details
+### Details
 
 #### Workflow overview
 

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

@@ -19,7 +19,7 @@ What standard set of Makefile target names and execution rules should projects a
 
 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
+### Details
 
 #### 01-every-project-must-have-root-makefile
 

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

@@ -19,7 +19,7 @@ How should projects execute development commands so the command surface stays pr
 
 This keeps local development and CI aligned, reduces indirection, and lets contributors understand project behavior by reading one command surface.
 
-### Implementation Details
+### Details
 
 - Every project MUST use a root `Makefile` as the authoritative entry point for developer and pipeline commands.
 - The target names in that `Makefile` MUST follow [agentme-edr-008](008-common-targets.md).

package/.xdrs/agentme/edrs/governance/013-contributing-guide-requirements.md

@@ -19,7 +19,7 @@ What contributor workflow guidance must every project publish so contributors kn
 
 Projects must keep a `CONTRIBUTING.md` file at the repository root. The file must explain where bugs, feature discussions, and code changes belong so contributors follow a predictable workflow before opening pull requests.
 
-### Implementation Details
+### Details
 
 - Every project **MUST** have a root `CONTRIBUTING.md`.
 - The guide **MUST** direct bug reports to issues.

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

@@ -32,6 +32,7 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-018](application/018-ai-agent-development-standards.md) - **AI agent development standards** - Standard toolchain, framework, evaluation, and workflow patterns for AI agent projects built with Python and LangGraph
 - [agentme-edr-019](application/019-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 - [agentme-edr-020](application/020-ai-agent-xdrs-knowledge-layer.md) - **AI agent XDRS knowledge layer** - How to integrate XDRS as the runtime source of truth for policies and skills in AI agents (apply only when the project explicitly uses XDRS)
+- [agentme-edr-021](application/021-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules
 - [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**
 
 ## Devops

package/.xdrs/agentme/edrs/observability/011-service-health-check-endpoint.md

@@ -19,7 +19,7 @@ How should services expose their health status and validate operational readines
 
 All services must expose a `GET /health` endpoint that validates external dependencies using read-only operations and returns structured status with appropriate HTTP codes.
 
-### Implementation Details
+### Details
 
 **Endpoint contract:**
 

package/.xdrs/agentme/edrs/principles/002-coding-best-practices.md

@@ -17,7 +17,7 @@ What coding practices should be followed across all languages and projects to ke
 
 **Apply a set of language-agnostic structural and organizational practices that keep files small, logic decomposed, types co-located, tests co-located, and documentation always in sync.**
 
-### Implementation Details
+### Details
 
 #### 01-keep-files-short
 

package/.xdrs/agentme/edrs/principles/004-unit-test-requirements.md

@@ -17,7 +17,7 @@ What unit testing practices should be followed to ensure tests are meaningful, r
 
 **Every test must assert behavior, run offline without external dependencies, enforce 80% coverage, centralize shared setup, and prefer real code over mocks.**
 
-### Implementation Details
+### Details
 
 #### 01-must-have-at-least-one-assertion-per-test
 

package/.xdrs/agentme/edrs/principles/007-project-quality-standards.md

@@ -19,7 +19,7 @@ Every project must meet six minimum quality standards: a Getting Started section
 
 These standards form a non-negotiable baseline. Individual projects may raise the bar but must never fall below it.
 
-### Implementation Details
+### Details
 
 #### 01-readme-must-have-getting-started
 
@@ -31,7 +31,7 @@ These standards form a non-negotiable baseline. Individual projects may raise th
 
 **Required README structure:**
 
-```markdown
+````markdown
 # Project Name
 
 One-line description.
@@ -46,7 +46,7 @@ npm install my-package
 import { myFunction } from "my-package";
 myFunction({ input: "value" });
 ```
-```
+````
 
 ---
 

package/.xdrs/agentme/edrs/principles/009-error-handling.md

@@ -17,7 +17,7 @@ What error handling practices should be followed across all languages and projec
 
 **Follow a set of consistent error handling practices: catch only where you can handle, return errors as values at interfaces, centralize repetitive catch logic, communicate failure clearly at process and service boundaries, and exercise error paths with dedicated tests.**
 
-### Implementation Details
+### Details
 
 #### 01-catch-only-where-handled
 

package/.xdrs/agentme/edrs/principles/012-continuous-xdr-enrichment.md

@@ -19,7 +19,7 @@ Question: What policy should developers follow to continuously enrich XDRs so re
 
 Developers must treat reusable missing guidance discovered during implementation as an XDR gap to be proposed and reviewed, not as permanent prompt-only context or repeated vibe coding.
 
-### Implementation Details
+### Details
 
 - The main objective is sharing, discussing, and converging practices across teams. Controlled divergence during exploration is acceptable, but recurring successful decisions must be converged into shared XDRs.
 - The non _local scope exists to share practices across projects, company areas, and functionally organized teams. Decisions placed in `_local` should be truly specific to the needs of a single application or repository.
@@ -43,4 +43,4 @@ Developers must treat reusable missing guidance discovered during implementation
 - [_core-adr-001](../../../_core/adrs/principles/001-xdrs-core.md)
 - [_core-article-001](../../../_core/adrs/principles/articles/001-xdrs-overview.md)
 - [agentme-article-001](articles/001-continuous-xdr-improvement.md)
-- [002-write-policy skill](../../../../.github/skills/002-write-policy/SKILL.md)
+- [002-write-policy skill](../../../_core/adrs/principles/skills/002-write-policy/SKILL.md)

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

@@ -19,7 +19,7 @@ What baseline structure rules must every buildable module follow regardless of l
 
 Language-specific EDRs may add ecosystem details, but they must not redefine these baseline folder responsibilities.
 
-### Implementation Details
+### Details
 
 #### 01-module-must-own-folder-root
 

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

@@ -2,13 +2,13 @@
 
 ## Overview
 
-This article explains how architects, engineers and business professionals should recognize, organize, and promote reusable delivery decisions into XDRs as a continuous improvement activity. It is aimed at people working with coding agents, vibe-coding loops, or SDD-oriented delivery who need a practical path from task friction to shared documentation.
+A practical guide for recognizing recurring delivery decisions and promoting them into shared XDRs. Intended for engineers, architects, and business professionals working with coding agents or SDD-oriented delivery.
 
-Continuous improvement matters because delivery decisions do not stay correct forever. Team structures change, platforms evolve, tools mature, and the trade-offs behind earlier choices shift over time. If XDRs are not revisited and improved continuously, previously useful decisions become stale guidance and eventually turn into a form of legacy documentation that misleads delivery instead of guiding it.
+## Content
 
-Continuous improvement also keeps the target state explicit. As XDRs evolve across projects and tracks, teams need a clear shared view of where they are trying to converge, what remains intentionally different, and what should be treated as technical debt on the path toward that target. Keeping XDRs current reduces confusion about the desired future state and helps each project evolve toward it deliberately instead of drifting through ad hoc local decisions.
+Delivery decisions do not stay correct forever. Team structures change, platforms evolve, tools mature, and the trade-offs behind earlier choices shift over time. If XDRs are not revisited and improved continuously, previously useful decisions become stale guidance that misleads delivery instead of guiding it.
 
-## Content
+Keeping XDRs current also makes the target state explicit. Teams need a clear shared view of where they are converging, what remains intentionally different, and what is technical debt on the path to that target.
 
 ### Start from delivery friction
 
@@ -90,4 +90,4 @@ If the same clarification would likely be needed in another feature, by another
 - [_core-adr-001](../../../../_core/adrs/principles/001-xdrs-core.md) - XDR structure, numbering, and mandatory template
 - [_core-article-001](../../../../_core/adrs/principles/articles/001-xdrs-overview.md) - XDR introduction and general adoption guidance
 - [agentme-edr-012](../012-continuous-xdr-enrichment.md) - Shared-first XDR enrichment policy and 80% coverage target
-- [002-write-policy skill](../../../../../.github/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs
+- [002-write-policy skill](../../../../_core/adrs/principles/skills/002-write-policy/SKILL.md) - Step-by-step procedure for drafting new XDRs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.34.1"