agentme 0.10.0 → 0.12.0

package/.filedist-package.yml

@@ -1,5 +1,5 @@
 sets:
-  - package: xdrs-core@0.28.0
+  - package: xdrs-core@0.28.1
   # - package: git:https://github.com/flaviostutz/xdrs-core.git@main
     selector:
       files:

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

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-014-python-project-tooling-and-structure
-description: Defines the standard Python project toolchain, layout, and Makefile workflow using Mise, uv, ruff, pyright, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
+description: Defines the standard Python project toolchain, layout, and Makefile workflow using Mise, uv, ruff, ty, pytest, and pip-audit. Use when scaffolding or reviewing Python projects.
 apply-to: Python projects
 valid-from: 2026-05-25
 ---
@@ -15,11 +15,11 @@ What tooling and project structure should Python projects follow to ensure consi
 
 ## Decision Outcome
 
-**Use a Mise-managed Python and uv toolchain 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.**
+**Use a Mise-managed Python and uv toolchain with `pyproject.toml`, `ruff`, `ty`, `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
+### Details
 
 #### Tooling
 
@@ -29,25 +29,35 @@ A single dependency manager, isolated package internals under `lib/`, and a stan
 | **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 |
+| **ty** | 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.
+All routine commands must run through the project `Makefile`, never by calling `uv`, `ruff`, `pytest`, or `ty` directly in docs, CI, or daily development workflows.
 
 The repository root MUST define a `.mise.toml` that pins Python and uv. Contributors and CI MUST bootstrap with `make setup` or `mise install`, then invoke routine work with `make <target>`. Each Makefile recipe MUST execute the underlying tool through `mise exec -- <tool> ...`, following [agentme-edr-017](../devops/017-tool-execution-and-scripting.md). Using routine project CLI commands directly outside the Makefile contract is not allowed.
 
 The root `.venv/` is the canonical environment location for both the library and all examples. Subdirectory commands must set `UV_PROJECT_ENVIRONMENT` to the workspace root `.venv/` instead of creating nested virtual environments.
 
-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,11 +71,15 @@ 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
+│   │   └── *_test.py       # e.g. hello_test.py (named after the tested file)
 │   ├── tests_integration/  # optional integration tests for this module
 │   ├── tests_benchmark/    # optional benchmark harnesses and datasets
 │   └── dist/               # wheels / sdists built from lib/
@@ -80,7 +94,9 @@ Persistent caches must live under `.cache/`, preferably the module `lib/.cache/`
 
 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`.
+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 `ty.toml` 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/`.
 
@@ -90,15 +106,58 @@ Python keeps unit tests under `lib/tests/` by default because that remains the m
 
 - 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.
+- Configure Ruff, ty, 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"`.
+When ty runs from `lib/`, it auto-discovers the virtual environment via the `VIRTUAL_ENV` environment variable or the `UV_PROJECT_ENVIRONMENT` export set in the Makefile. No additional venv configuration is required in `pyproject.toml`.
 
 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.
+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"
+python_files = "*_test.py"
+
+[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.
+
+ty must run on every lint pass. The default rule set is the minimum baseline; projects may enable stricter rules as the codebase matures.
 
 Pytest coverage must fail below 80% line and branch coverage, following [agentme-edr-004](../principles/004-unit-test-requirements.md).
 
@@ -129,8 +188,8 @@ The root `Makefile` is the only contract for CI and contributors. It delegates l
 |--------|-------------|
 | `install` | `mise exec -- uv sync --project . --frozen --all-extras --dev` using the shared root `.venv/` |
 | `build` | `mise exec -- uv sync --project . --frozen --all-extras --dev && mise exec -- uv build --project . --out-dir dist` |
-| `lint` | `mise exec -- uv run --project . ruff format --check . && mise exec -- uv run --project . ruff check . && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
-| `lint-fix` | `mise exec -- uv run --project . ruff format . && mise exec -- uv run --project . ruff check . --fix && mise exec -- uv run --project . pyright && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `lint` | `mise exec -- uv run --project . ruff format --check . && mise exec -- uv run --project . ruff check . && mise exec -- uv run --project . ty check && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
+| `lint-fix` | `mise exec -- uv run --project . ruff format . && mise exec -- uv run --project . ruff check . --fix && mise exec -- uv run --project . ty check && mise exec -- uv run --project . pip-audit`, with caches redirected into `.cache/` |
 | `test-unit` | `mise exec -- 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` |
@@ -145,7 +204,7 @@ The root `Makefile` must remain the only contract for CI and contributors, in li
 
 * (REJECTED) **Mixed Python tooling** - Separate tools and config files such as `pip`, `requirements.txt`, `setup.cfg`, `flake8`, and `mypy`.
   * Reason: Increases cognitive load, duplicates configuration, and weakens the standard command surface across projects.
-* (CHOSEN) **uv + `lib/` package layout + Ruff/Pyright/Pytest toolchain** - One dependency manager, package internals isolated under `lib/`, consumer examples under `examples/`, and one root Makefile contract.
+* (CHOSEN) **uv + `lib/` package layout + Ruff/ty/Pytest toolchain** - One dependency manager, package internals isolated under `lib/`, consumer examples under `examples/`, and one root Makefile contract.
   * Reason: Keeps packaging, dependency locking, static analysis, security auditing, and test execution consistent while aligning Python repositories with the established JavaScript layout.
 
 ## References

package/.xdrs/agentme/edrs/application/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