agentme 0.9.0 → 0.11.0

package/.filedist-package.yml

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

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

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-018-ai-agent-development-standards
-description: Defines the standard toolchain, framework, evaluation approach, and context management patterns for building AI agents. Use when scaffolding, reviewing, or extending AI agent projects.
+description: Defines the standard toolchain, framework, evaluation approach, and workflow patterns for building AI agents with Python and LangGraph. Use when scaffolding, reviewing, or extending AI agent projects.
 apply-to: AI agent projects built with Python
 valid-from: 2026-05-26
 ---
@@ -9,13 +9,13 @@ valid-from: 2026-05-26
 
 ## Context and Problem Statement
 
-AI agent projects vary widely in how they choose frameworks, manage context, evaluate outputs, and expose policies to the agent at runtime. Without a shared baseline, projects accumulate incompatible patterns for LLM provider abstraction, flow design, dataset-driven testing, and knowledge delivery.
+AI agent projects vary widely in how they choose frameworks, manage context, evaluate outputs, and structure workflows. Without a shared baseline, projects accumulate incompatible patterns for LLM provider abstraction, flow design, and dataset-driven testing.
 
 Which tools, frameworks, and design patterns should AI agent projects follow to ensure reproducibility, testability, and maintainability?
 
 ## Decision Outcome
 
-**Use Python with LangGraph for flow orchestration, MLflow for experiment tracking and local evaluation, and a file-system-based XDRS knowledge layer that the agent queries at runtime via explicit file tools.**
+**Use Python with LangGraph for flow orchestration and MLflow for experiment tracking and local evaluation.**
 
 ### Details
 
@@ -54,7 +54,7 @@ Use **MLflow** for all agent observability and evaluation:
 
 #### 04-dataset-driven-accuracy-measurement
 
-Every agent pipeline MUST have a companion evaluation dataset and an MLflow experiment that measures accuracy against it. Datasets and evals are organized per-workflow following rule `09-workflow-structure` and rule `10-workflow-evals`.
+Every agent pipeline MUST have a companion evaluation dataset and an MLflow experiment that measures accuracy against it. Datasets and evals are organized per-workflow following rule `07-workflow-structure` and rule `08-workflow-evals`.
 
 - Store evaluation datasets under `evals/<workflow>/` (sibling of `lib/` and `examples/`), following [agentme-edr-019](019-ml-dataset-structure.md) for structure and format. For MLflow input/output pairs, use the JSONL format described in `agentme-edr-019.04-complex-structured-datasets-must-use-jsonl`.
 - Write evaluation scripts under `evals/<workflow>/` that load the dataset, run each input through the live agent (against real LLMs, not mocks), compare outputs to expected values, and log per-sample and aggregate metrics to an MLflow experiment.
@@ -80,50 +80,7 @@ graph TD
     C -->|fail| B
 ```
 
-#### 06-xdrs-knowledge-layer
-
-When an agent must follow elaborate procedures, decision frameworks, or domain rules:
-
-**Static files distributed with the library**
-
-- All static files accessed by agents at runtime (XDRS documents, reference tables, domain dictionaries, lookup files) MUST live under a `data/` folder inside the library source tree (`lib/data/`) and be embedded in the package data manifest (e.g. `pyproject.toml` `[tool.hatch.build] include` or equivalent).
-- XDRS Policy and Skill documents MUST be placed at `lib/data/.xdrs/`, using the standard XDRS scope/type/subject folder structure (following `_core-adr-policy-001`).
-- Other static context data (reference tables, domain dictionaries, structured lookup files) MUST be placed under `lib/data/` in an appropriate sub-folder (e.g. `lib/data/context/`).
-- The agent system prompt MUST NOT inline procedure text. It MUST instruct the agent to read specific paths and follow the instructions found there. Example:
-
-  ```
-  Before answering, read and follow the instructions in data/.xdrs/_local/edrs/procedures/triage.md.
-  ```
-
-**Dynamic context generated per workflow instantiation**
-
-- Context files that are generated at runtime per workflow run (unpacked archives, fetched documents, intermediate outputs) MUST be written to a temporary directory created via the OS temp API (`tempfile.mkdtemp()` in Python).
-- The temporary directory MUST be created at the start of the workflow run and passed into the workflow state so all nodes share the same path.
-- The temporary directory MUST be deleted (including all contents) when the workflow run finishes, whether it succeeds or fails, using a `try/finally` block or a context manager.
-- The agent file tools MUST be configured with the temporary directory path at workflow startup so the agent can read from it during the run.
-
-- The agent file tools MUST expose `data/` (for static files) and the temporary directory (for dynamic files) as sandboxed readable roots (see rule `07-agent-file-tools`).
-
-#### 07-agent-file-tools
-
-Every agent that uses the XDRS knowledge layer or file-based context MUST be equipped with at least the following tools:
-
-| Tool | Purpose |
-|---|---|
-| `read_file(path)` | Read the full content of a file by path |
-| `search_files(directory, pattern)` | Glob-search for files matching a pattern under a directory |
-| `grep_file(path, query)` | Search for lines matching a string or regex within a file |
-
-Implement these tools as LangChain `@tool`-decorated functions with explicit path sandboxing. Two sandboxed roots MUST be configured:
-
-| Root | Content | Source |
-|---|---|---|
-| `DATA_ROOT` | Static files shipped with the library (`lib/data/`) | Package data; resolved via `importlib.resources` or a path relative to the installed package |
-| `TEMP_ROOT` | Dynamic files generated for the current workflow run | Temporary directory created by `tempfile.mkdtemp()` at workflow startup |
-
-Resolve all paths against the appropriate root. Reject any path that would escape its root (no `../` traversal). `TEMP_ROOT` MUST be passed into the tool factory at workflow startup, not read from a global variable.
-
-#### 08-verification-steps
+#### 06-verification-steps
 
 Agent flows MUST include at least one explicit verification node before producing final output:
 
@@ -132,27 +89,40 @@ Agent flows MUST include at least one explicit verification node before producin
 - On failure, the verification node MUST route back to the relevant generation node, not silently pass through.
 - Log verification results (pass/fail, score, reason) as MLflow metrics on the current run.
 
-#### 09-workflow-structure
+#### 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`.
 
-#### 10-workflow-evals
+#### 08-workflow-evals
 
 For each workflow `<workflow>` there MUST be a corresponding eval directory:
 
@@ -168,8 +138,8 @@ The `evals/<workflow>/Makefile` MUST define:
 
 | Target | Behaviour |
 |---|---|
-| `test-eval` | Runs all eval slices for the workflow |
-| `test-eval-<slice>` | Runs one named slice (e.g. `test-eval-simple`, `test-eval-complex`) |
+| `eval` | Runs all eval slices for the workflow |
+| `eval-<slice>` | Runs one named slice (e.g. `eval-simple`, `eval-complex`) |
 
 Each `eval_<slice>.py` script MUST:
 
@@ -177,5 +147,28 @@ Each `eval_<slice>.py` script MUST:
 - Run every input through the live workflow against real LLMs.
 - Log per-sample and aggregate metrics to an MLflow experiment that runs locally.
 
-The module root Makefile `make eval` target MUST delegate to `test-eval` in every `evals/<workflow>/Makefile`.
+The module root Makefile `make eval` target MUST delegate to `eval` in every `evals/<workflow>/Makefile`.
+
+#### 09-local-sandbox
+
+When a workflow node or tool requires a **local sandbox** — an isolated environment where the agent can read files, glob-search directories, and execute shell commands — use the **[deepagents](https://github.com/deepagents/deepagents) framework** to provide that sandbox.
+
+**When to apply this rule**
+
+Use deepagents whenever ANY of the following is true for a workflow or tool:
+- The agent needs to execute shell commands or scripts in a controlled environment.
+- The agent needs to list, read, or search files across multiple directories at runtime.
+- The agent operates on user-supplied or generated file trees that must not escape a sandboxed boundary.
+
+**Integration requirements**
+
+- Initialize the sandbox at the start of the workflow run and shut it down in the same `try/finally` block.
+- Pass the sandbox handle into the LangGraph workflow state so all nodes share the same sandbox instance.
+- 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