agentme 0.9.0 → 0.11.0

package/.xdrs/agentme/edrs/application/019-ml-dataset-structure.md

@@ -17,13 +17,13 @@ How should ML datasets be organized on disk so they are self-describing, easy to
 
 **A standard root layout with mandatory README.md and dataset.schema.json, plus type-specific conventions for data files**
 
-Every dataset must live in its own named folder and include a README and a JSON Schema file. Data files are organized according to three dataset types, each with its own placement rule.
+Every dataset MUST live in its own named folder and include a README and a JSON Schema file. Data files are organized according to three dataset types, each with its own placement rule.
 
 ### Details
 
 #### 01-root-structure-is-mandatory
 
-Every dataset must follow this root layout:
+Every dataset MUST follow this root layout:
 
 ```
 /[name-of-dataset]/
@@ -33,13 +33,13 @@ Every dataset must follow this root layout:
     ...                (additional files depending on dataset type)
 ```
 
-- `README.md` must explain what the dataset is about, the procedures used to create it, remarks on data quality, and instructions on how to consume it with examples.
-- `dataset.schema.json` must be a valid [JSON Schema](https://json-schema.org/) document describing the structure of the dataset's primary data.
-- The dataset folder name must be lowercase, using hyphens as separators.
+- `README.md` MUST explain what the dataset is about, the procedures used to create it, remarks on data quality, and instructions on how to consume it with examples.
+- `dataset.schema.json` MUST be a valid [JSON Schema](https://json-schema.org/) document describing the structure of the dataset's primary data.
+- The dataset folder name MUST be lowercase, using underscores as separators (e.g. `my_dataset`).
 
 #### 02-file-annotation-pairs-must-use-data-folder
 
-Datasets where each item is a file paired with structured JSON output (e.g. image labeling, document data extraction, medical records with known features) must store all files inside the `data/` subfolder. Each data file must have a sibling JSON annotation file named with the same filename suffixed with `.json`.
+Datasets where each item is a file paired with structured JSON output (e.g. image labeling, document data extraction, medical records with known features) MUST store all files inside the `data/` subfolder. Each data file MUST have a sibling JSON annotation file named with the same filename suffixed with `.json`.
 
 ```
 /[name-of-dataset]/
@@ -56,11 +56,11 @@ Datasets where each item is a file paired with structured JSON output (e.g. imag
 
 Placing the annotation file next to its source file (same name + `.json`) keeps them adjacent even in large directories, making it easy to iterate pairs programmatically.
 
-Subdirectories inside `data/` are allowed when the number of files warrants grouping, but the `.json` sibling convention must be preserved at each level.
+Subdirectories inside `data/` are allowed when the number of files warrants grouping, but the `.json` sibling convention MUST be preserved at each level.
 
 #### 03-tabular-datasets-must-use-csv-files-at-root
 
-Datasets composed of column-oriented tabular data must place CSV files at the root of the dataset folder. All tabular files must conform to the schema defined in `dataset.schema.json`, which must describe columns as named attributes with their types.
+Datasets composed of column-oriented tabular data MUST place CSV files at the root of the dataset folder. All tabular files MUST conform to the schema defined in `dataset.schema.json`, which MUST describe columns as named attributes with their types.
 
 ```
 /[name-of-dataset]/
@@ -70,11 +70,11 @@ Datasets composed of column-oriented tabular data must place CSV files at the ro
     README.md
 ```
 
-Multiple CSV files are allowed when they represent different slices or splits of the same schema (e.g. train/test splits, subsets by source). All files in the same dataset must share the same column schema.
+Multiple CSV files are allowed when they represent different slices or splits of the same schema (e.g. train/test splits, subsets by source). All files in the same dataset MUST share the same column schema.
 
 #### 04-complex-structured-datasets-must-use-jsonl
 
-Datasets with complex or heterogeneous per-record structures (e.g. LLM workflow evaluation sets, Q&A pairs, input → expected_output pairs) must use JSONL files (one JSON object per line) placed at the root of the dataset folder. Each line must conform to the schema defined in `dataset.schema.json`.
+Datasets with complex or heterogeneous per-record structures (e.g. LLM workflow evaluation sets, Q&A pairs, input → expected_output pairs) MUST use JSONL files (one JSON object per line) placed at the root of the dataset folder. Each line MUST conform to the schema defined in `dataset.schema.json`.
 
 ```
 /[name-of-dataset]/
@@ -84,11 +84,11 @@ Datasets with complex or heterogeneous per-record structures (e.g. LLM workflow
     README.md
 ```
 
-Multiple JSONL files are allowed when they represent different splits or categories (e.g. easy vs. edge cases). All files in the same dataset must conform to the same line schema.
+Multiple JSONL files are allowed when they represent different splits or categories (e.g. easy vs. edge cases). All files in the same dataset MUST conform to the same line schema.
 
 #### 05-referenced-files-must-live-in-data-folder
 
-When any dataset type (tabular, JSONL, or annotation-pair) contains references to external files as part of the data (e.g. a JSONL record that includes a file path), those referenced files must be stored inside the `data/` subfolder of the dataset. Paths inside data records must be relative to the dataset root.
+When any dataset type (tabular, JSONL, or annotation-pair) contains references to external files as part of the data (e.g. a JSONL record that includes a file path), those referenced files MUST be stored inside the `data/` subfolder of the dataset. Paths inside data records MUST be relative to the dataset root.
 
 ## References
 

package/.xdrs/agentme/edrs/application/020-ai-agent-xdrs-knowledge-layer.md

@@ -0,0 +1,99 @@
+---
+name: agentme-edr-policy-020-ai-agent-xdrs-knowledge-layer
+description: Defines how to integrate XDRS as the runtime knowledge source of truth for AI agents — covering document placement, AGENTS.md setup, file tools, and local sandbox configuration. Apply only when the project explicitly uses XDRS to govern agent behavior.
+apply-to: AI agent projects that use XDRS as the source of truth for policies and skills
+valid-from: 2026-05-27
+---
+
+# agentme-edr-policy-020: AI agent XDRS knowledge layer
+
+## Context and Problem Statement
+
+AI agents need access to project-specific policies and skills at runtime to produce consistent, governed outputs. XDRS provides a file-system-based structure for capturing these decisions, but there is no standard pattern for embedding XDRS documents in agent libraries, wiring the agent to consult them, or sandboxing file access securely.
+
+How should an AI agent project integrate XDRS as its runtime source of truth for policies and skills?
+
+## Decision Outcome
+
+**Embed XDRS documents in `lib/data/.xdrs/`, instruct the agent to consult them via `AGENTS.md`, equip the agent with sandboxed file tools, and use the deepagents framework when a local sandbox is required.**
+
+This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-018](018-ai-agent-development-standards.md) in general.
+
+### Details
+
+#### 01-xdrs-knowledge-layer
+
+XDRS documents are the source of truth for all policies and skills that the agent must follow during its tasks. The agent MUST consult XDRS before acting, not rely on general knowledge alone.
+
+**Placing XDRS documents in the library**
+
+- 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`).
+- They MUST be embedded in the package data manifest (e.g. `pyproject.toml` `[tool.hatch.build] include` or equivalent) so they are available at runtime.
+- When exposed through a deepagents sandbox, they MUST be mounted at `/.xdrs/` inside the sandbox (see rule `03-local-sandbox`).
+
+**AGENTS.md — mandatory XDRS consultation**
+
+Place an `AGENTS.md` file at the root of the deepagents sandbox (i.e. alongside `/.xdrs/`). This file instructs the agent to always consult XDRS before acting. Its content MUST follow the xdrs-core AGENTS.md template:
+
+```markdown
+# AGENTS.md
+
+**Purpose:** This file is intentionally brief. All decisions and working instructions are captured as Policies or Skills in the XDRS structure.
+
+## Policy Consultation in XDRS Is Mandatory For Every Request
+
+Before answering **any** request you MUST:
+
+1. Read the XDRS root index at `/.xdrs/index.md` to identify relevant Policies and Skills.
+2. Read the relevant Policy and Skill files.
+3. Base your actions on those Policies and Skills.
+
+This rule has NO exceptions. Do not answer from general knowledge alone when a Policy may exist on the topic.
+```
+
+The agent system prompt MUST reference `AGENTS.md` so the agent loads it at startup. Example:
+
+```
+Read /AGENTS.md and follow all instructions in it before proceeding.
+```
+
+#### 02-agent-file-tools
+
+Every agent that uses the XDRS knowledge layer MUST use the file tools provided by the deepagents framework. Do not implement hand-rolled alternatives — see [agentme-edr-policy-018-ai-agent-development-standards.[09-local-sandbox]](018-ai-agent-development-standards.md) for the full sandbox and tool requirements.
+
+These tools operate over two sandboxed roots (configured in rule `03-local-sandbox`):
+
+| Root | Content | Source |
+|---|---|---|
+| `data_root` | Static files shipped with the library (`lib/data/`) | Resolved via `importlib.resources` at workflow startup |
+| `temp_root` | Dynamic files generated for the current workflow run | Temporary directory created by `tempfile.mkdtemp()` at workflow startup |
+
+`temp_root` MUST be created at workflow startup and cleaned up in the same `try/finally` block. Pass it explicitly into the workflow; do not read it from a global variable.
+
+#### 03-local-sandbox
+
+Follow [agentme-edr-policy-018-ai-agent-development-standards.[09-local-sandbox]](018-ai-agent-development-standards.md) for the general deepagents sandbox setup. When XDRS is in use, add the following mounts to the sandbox configuration:
+
+| Source | Content | Deepagents sandbox path |
+|---|---|---|
+| `lib/data/.xdrs/` | XDRS Policy and Skill documents | `/.xdrs/` (read-only) |
+| Generated at startup | `AGENTS.md` instructing the agent to consult XDRS | `/AGENTS.md` (read-only) |
+
+XDRS documents MUST always be mounted at `/.xdrs/`. `AGENTS.md` MUST always be placed at the sandbox root (`/AGENTS.md`).
+
+Example XDRS mount additions:
+
+```python
+from importlib.resources import files
+from pathlib import Path
+
+data_root = str(files("myagent").joinpath("data"))
+agents_md = Path(temp_root) / "AGENTS.md"
+agents_md.write_text(_AGENTS_MD)  # content from xdrs-core AGENTS.md template; see rule 01-xdrs-knowledge-layer
+
+# Add these mounts alongside the base mounts from agentme-edr-018 rule 09-local-sandbox:
+xdrs_mounts = [
+    {"src": f"{data_root}/.xdrs", "dst": "/.xdrs",    "readonly": True},
+    {"src": str(agents_md),       "dst": "/AGENTS.md", "readonly": True},
+]
+```

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