agentme 0.1.1

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

@@ -0,0 +1,110 @@
+# agentme-edr-002: Coding best practices
+
+## Context and Problem Statement
+
+Without consistent coding standards, codebases tend to accumulate large, hard-to-navigate files, tangled logic, and documentation that drifts out of sync with the implementation. This leads to slower onboarding, harder maintenance, and higher defect rates.
+
+What coding practices should be followed across all languages and projects to keep code readable, maintainable, and well-structured?
+
+## Decision Outcome
+
+**Apply a set of language-agnostic structural and organizational practices that keep files small, logic decomposed, types co-located, tests co-located, and documentation always in sync.**
+
+### Implementation Details
+
+#### 1. Keep files short — split at 400 lines
+
+A file must not exceed **400 lines**. When a file grows beyond this limit, split related functions or types into separate, focused modules.
+
+One exception are test files, which normally are bigger than the tested resources.
+
+*Why:* Large files make navigation slow, increase merge conflicts, and obscure the single-responsibility principle.
+
+**Example (TypeScript):**
+
+```
+# before — one bloated file
+src/
+  orders.ts          # 650 lines: validation, pricing, persistence, notifications
+
+# after — split by responsibility
+src/
+  orders/
+    validation.ts    # 120 lines
+    pricing.ts       #  95 lines
+    persistence.ts   # 110 lines
+    notifications.ts #  80 lines
+    index.ts         #  30 lines  (re-exports the public API)
+```
+
+---
+
+#### 2. Apply the Template Method pattern for large multi-section functions
+
+When a function's main logic contains well-defined sections and **any individual section exceeds ~20 lines**, extract each section into its own named function. The outer function becomes an orchestrator that calls the extracted helpers in sequence.
+
+*Why:* Named sub-functions serve as inline documentation, are independently testable, and reduce cognitive load.
+
+**Example (Python):**
+
+```python
+# before — one long function with implicit sections
+def process_order(order):
+    # --- validate ---          (~25 lines)
+    if not order.items:
+        raise ValueError("empty order")
+    # ... more validation ...
+
+    # --- calculate price ---   (~30 lines)
+    subtotal = sum(i.price * i.qty for i in order.items)
+    # ... discounts, taxes ...
+
+    # --- persist ---           (~22 lines)
+    db.save(order)
+    # ... audit log ...
+
+# after — template method style
+def process_order(order):
+    _validate_order(order)
+    total = _calculate_price(order)
+    _persist_order(order, total)
+
+def _validate_order(order): ...
+def _calculate_price(order) -> Decimal: ...
+def _persist_order(order, total): ...
+```
+
+---
+
+#### 3. Keep README, tests, and examples in sync with implementation
+
+Every change to a public interface, behavior, or configuration option must be reflected in:
+
+- `README.md` — update usage examples, option tables, and feature descriptions.
+- Unit/integration tests — update or add tests that cover the changed behavior.
+- `examples/` resources — update runnable examples so they continue to work.
+
+*Why:* Stale documentation and broken examples erode trust and waste time for consumers of the code.
+
+---
+
+#### 4. Declare types in the file where they are used — unless shared
+
+If a type (struct, interface, class, typedef, etc.) is used in only **one** file, declare it in that same file. Move a type to a shared module only when it is referenced in two or more files.
+
+*Why:* Co-locating a type with its sole consumer removes the need to navigate to a separate types file and makes the type's purpose immediately obvious from context.
+
+---
+
+#### 5. Keep test files next to the files they test
+
+Where the language ecosystem supports it (e.g. JavaScript/TypeScript, Go, Rust), place test files **beside** the source file they cover and use a consistent naming convention rather than mirroring the source tree in a separate `tests/` folder.
+
+**Recommended naming conventions:**
+
+| Language / ecosystem | Source file      | Test file              |
+|----------------------|------------------|------------------------|
+| TypeScript / JS      | `app.ts`         | `app.test.ts`          |
+| Go                   | `handler.go`     | `handler_test.go`      |
+| Rust                 | `parser.rs`      | inline `#[cfg(test)]`  |
+| Python               | `service.py`     | `service_test.py` (same directory, or `tests/` when the ecosystem convention dictates otherwise) |

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

@@ -0,0 +1,97 @@
+# agentme-edr-004: Unit test requirements
+
+## Context and Problem Statement
+
+Without clear unit testing standards, test suites become inconsistent — tests lack assertions, coverage is spotty, setup code is duplicated, and mocks bypass real logic.
+
+What unit testing practices should be followed to ensure tests are meaningful, reliable, and maintainable?
+
+## Decision Outcome
+
+**Every test must assert behavior, run offline without external dependencies, enforce 80% coverage, centralize shared setup, and prefer real code over mocks.**
+
+### Implementation Details
+
+#### 1. MUST have at least one assertion per test
+
+```typescript
+// bad — no assertion; passes even when code is broken
+it("processes the order", () => { processOrder(mockOrder); });
+
+// good
+it("processes the order and returns a confirmation id", () => {
+  const result = processOrder(mockOrder);
+  expect(result.confirmationId).toBeDefined();
+});
+```
+
+---
+
+#### 2. MUST run offline — no external resource dependencies
+
+Unit tests must not depend on any external resources: no network calls, no running databases, no external APIs, no file system paths outside the repo. Tests must pass with only static code available.
+
+```typescript
+// bad — hits a real HTTP endpoint
+it("fetches user", async () => {
+  const user = await fetch("https://api.example.com/users/1").then(r => r.json());
+  expect(user.id).toBe(1);
+});
+
+// good — uses a fake/in-memory implementation
+it("fetches user", async () => {
+  const client = new UserClient({ transport: new InMemoryTransport(fixtures.users) });
+  const user = await client.getUser(1);
+  expect(user.id).toBe(1);
+});
+```
+
+---
+
+#### 3. MUST maintain at least 80% line/branch coverage, enforced in CI
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: { coverage: { provider: "v8", thresholds: { lines: 80, branches: 80 } } },
+});
+```
+
+Builds that miss the threshold must not be merged.
+
+---
+
+#### 4. SHOULD extract shared setup into a test utility module
+
+When setup logic is repeated across two or more test files, centralize it (`src/test-utils/`, `internal/testutil/`, `tests/conftest.py`).
+
+```typescript
+// src/test-utils/order-factory.ts
+export function makeOrder(overrides: Partial<Order> = {}): Order {
+  return { id: "ord-1", items: [{ sku: "A", qty: 1, price: 10 }], status: "pending", ...overrides };
+}
+```
+
+---
+
+#### 5. SHOULD avoid mocks — prefer real code execution
+
+Use the lowest-cost alternative that exercises real behavior:
+
+1. **Real implementation** — always prefer this
+2. **In-memory / lightweight fake** — e.g. in-memory DB, stub HTTP server
+3. **Recorded fixture** — replay captured real responses
+4. **Mock / stub** — only for external APIs, irreversible operations, or hardware I/O
+
+```typescript
+// bad — mocks internal logic; passes even when pricing is broken
+jest.mock("../pricing", () => ({ calculateTotal: () => 99 }));
+
+// good — exercises the real pricing module
+it("charges the correct amount", () => {
+  const order = makeOrder({ items: [{ sku: "A", qty: 1, price: 99 }] });
+  expect(checkout(order)).toBe(99);
+});
+```
+
+When a mock is unavoidable, keep it narrow (one boundary point) and add a comment explaining why.

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

@@ -0,0 +1,156 @@
+# agentme-edr-007: Project quality standards
+
+## Context and Problem Statement
+
+Without a baseline quality bar, projects within the same organization can diverge significantly in documentation completeness, test coverage, linting discipline, and structural clarity. New developers encounter confusion, quality regressions slip through, and standards drift over time.
+
+What minimum quality standards must every project in the organization meet to ensure it is understandable, maintainable, and consistently verifiable?
+
+## Decision Outcome
+
+Every project must meet six minimum quality standards: a Getting Started section in its README, unit tests that run on every release, compliance with workspace XDRs, active linting enforcement, a structure that is clear to new developers, and — for libraries and utilities — a runnable examples folder verified on every test run.
+
+These standards form a non-negotiable baseline. Individual projects may raise the bar but must never fall below it.
+
+---
+
+### 1. README MUST have a Getting Started section
+
+`README.md` must include a **Getting Started** section in the first 20 lines with the minimal steps to install and use the project.
+
+**Required content:**
+- Installation or setup command(s)
+- At least one runnable usage example (code snippet, CLI command, or API call)
+
+**Required README structure:**
+
+```markdown
+# Project Name
+
+One-line description.
+
+## Getting Started
+
+```sh
+npm install my-package
+```
+
+```ts
+import { myFunction } from "my-package";
+myFunction({ input: "value" });
+```
+```
+
+---
+
+### 2. Unit tests MUST run on every release
+
+A unit test suite must run automatically before every release. Failing tests must block the release — no silent skips or overrides.
+
+**Requirements:**
+- A `make test` target must exist and run the full suite
+- CI/CD must invoke it before publish/deploy
+- Test failures block the release
+
+**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
+
+**Reference:** [agentme-edr-004](004-unit-test-requirements.md) for detailed unit test requirements.
+
+---
+
+### 3. The project MUST comply with all applicable workspace XDRs
+
+All XDRs that apply to the project's scope (as listed in [.xdrs/index.md](../../../../index.md)) must be followed. A deviation requires a project-local XDR documenting the override.
+
+**Requirements:**
+- Review applicable XDRs before any significant implementation
+- If an XDR conflicts with project needs, create a `_local` XDR documenting the deviation
+
+---
+
+### 4. The project MUST have linting enforcing code style, formatting, and best practices
+
+Projects larger than 10 files or 200 lines of code must have a linter configured and actively enforced. Lint failures block CI builds.
+
+**Requirements:**
+- `make lint` runs the linter with zero-warning tolerance
+- `make lint-fix` auto-fixes fixable issues
+- Linter config is checked in (e.g., `.eslintrc.js`, `pyproject.toml`, `.golangci.yml`)
+- CI runs `make lint` before merging or releasing
+
+**Exception:** Projects with fewer than 100 lines of code, or whose `README.md` prominently marks them as a **Spike** or **Experiment**, are exempt from this requirement. Such projects must never be deployed to production.
+
+**Reference:** [agentme-edr-003](003-javascript-project-tooling.md) for JavaScript-specific tooling.
+
+---
+
+### 5. The project structure MUST be easily understood by new developers
+
+Directory and file layout must be self-explanatory: source code, tests, configuration, and examples must be clearly separated and named.
+
+**Requirements:**
+- Directory names must reflect their purpose (`src/`, `lib/`, `tests/`, `examples/`, `docs/`)
+- README must describe the top-level layout if non-obvious
+- No orphaned or unexplained directories or files at the project root
+
+**Example layout (TypeScript project):**
+
+```
+/
+├── README.md
+├── Makefile
+├── lib/
+│   └── src/
+│       ├── index.ts
+│       └── *.test.ts
+└── examples/
+    └── basic-usage/
+```
+
+---
+
+### 6. Libraries and utilities MUST have a runnable examples folder verified on every test run
+
+Projects that are libraries or shared utilities must include an `examples/` directory. Each subdirectory represents a usage scenario and must be independently runnable. Examples are executed as part of `make test`.
+
+**Requirements:**
+- `examples/` must contain at least one subdirectory per major usage scenario
+- Each scenario subdirectory must have a `Makefile` with a `run` target
+- Examples must import the library as an external consumer (not via relative `../src` imports)
+- `make test` in the root must run all examples; failures block CI and releases
+
+**Directory layout:**
+
+```
+/
+├── Makefile
+├── lib/src/
+└── examples/
+    ├── Makefile
+    ├── basic-usage/
+    │   ├── Makefile      # targets: run
+    │   └── main.ts
+    └── advanced-usage/
+        ├── Makefile      # targets: run
+        └── main.ts
+```
+
+**Root Makefile:**
+
+```makefile
+test: test-unit test-examples
+
+test-unit:
+	$(MAKE) -C lib test
+
+test-examples:
+	$(MAKE) -C examples
+```
+
+**Examples Makefile:**
+
+```makefile
+all:
+	$(MAKE) -C basic-usage run
+	$(MAKE) -C advanced-usage run
+```

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

@@ -0,0 +1,327 @@
+# agentme-edr-009: Error handling
+
+## Context and Problem Statement
+
+Poor error handling is one of the most common sources of production incidents. Errors that are silently swallowed hide bugs; exceptions leaked through public interfaces force callers to know internal implementation details; scattered `catch` blocks spread fragile logic across the codebase; processes that exit with code `0` despite failure mislead orchestrators; and untested error paths mean breakages are only discovered in production.
+
+What error handling practices should be followed across all languages and projects to produce systems that fail loudly, communicate failure clearly, and remain easy to reason about?
+
+## Decision Outcome
+
+**Follow a set of consistent error handling practices: catch only where you can handle, return errors as values at interfaces, centralize repetitive catch logic, communicate failure clearly at process and service boundaries, and exercise error paths with dedicated tests.**
+
+### Implementation Details
+
+#### 1. Catch exceptions only where they can be properly handled
+
+Never catch an exception unless the catching site can genuinely recover from it, translate it into a meaningful domain error, or enrich it with context before re-throwing. Do **not** swallow exceptions silently. When suppressing an exception is intentional, always add a comment explaining exactly why, or log it at an appropriate level.
+
+*Why:* Swallowed exceptions hide bugs and make incidents impossible to diagnose. Every silent `catch` is a future mystery.
+
+**Examples:**
+
+```typescript
+// bad — swallowed silently
+try {
+  await saveOrder(order);
+} catch (e) {
+  // nothing here
+}
+
+// bad — caught but not handled or re-thrown
+try {
+  await saveOrder(order);
+} catch (e) {
+  console.log("error"); // no context, no rethrow, no recovery
+}
+
+// good — caught, enriched, re-thrown
+try {
+  await saveOrder(order);
+} catch (e) {
+  throw new OrderPersistenceError(`Failed to save order ${order.id}`, { cause: e });
+}
+
+// good — intentional suppression with explanation
+try {
+  await evictCache(key);
+} catch (e) {
+  // Cache eviction is best-effort; a failure here does not affect correctness.
+  logger.warn({ err: e, key }, "cache eviction failed, continuing");
+}
+```
+
+```python
+# bad
+try:
+    save_order(order)
+except Exception:
+    pass  # no explanation
+
+# good — intentional suppression documented
+try:
+    evict_cache(key)
+except CacheError:
+    # Cache eviction is best-effort; failure does not affect correctness.
+    logger.warning("cache eviction failed for key=%s", key, exc_info=True)
+```
+
+---
+
+#### 2. Avoid exposing exceptions as part of public interfaces — return error values instead
+
+At module and service boundaries, prefer returning a value that signals success or failure (e.g., a result type, a discriminated union, or a `(value, error)` tuple as in Go) over throwing exceptions. This forces callers to explicitly acknowledge and handle the error case before using the result.
+
+*Why:* Exceptions are invisible in signatures. A caller who doesn't know an exception can be thrown will never write a handler. Explicit error return values make the contract visible and encourage handling at the call site.
+
+**Examples:**
+
+```typescript
+// bad — exception leaks from a public function
+async function fetchUser(id: string): Promise<User> {
+  const row = await db.query("SELECT * FROM users WHERE id = $1", [id]);
+  if (!row) throw new Error("user not found"); // caller must know this can throw
+  return row;
+}
+
+// good — result type makes the error case explicit
+type Result<T, E = Error> = { ok: true; value: T } | { ok: false; error: E };
+
+async function fetchUser(id: string): Promise<Result<User, "not-found" | "db-error">> {
+  try {
+    const row = await db.query("SELECT * FROM users WHERE id = $1", [id]);
+    if (!row) return { ok: false, error: "not-found" };
+    return { ok: true, value: row };
+  } catch (e) {
+    logger.error({ err: e, userId: id }, "db query failed");
+    return { ok: false, error: "db-error" };
+  }
+}
+
+// caller is forced to check
+const result = await fetchUser(id);
+if (!result.ok) {
+  // handle not-found or db-error
+  return;
+}
+use(result.value);
+```
+
+```go
+// Go — idiomatic error return
+func FetchUser(id string) (*User, error) {
+    row, err := db.QueryRow("SELECT * FROM users WHERE id = $1", id)
+    if err != nil {
+        return nil, fmt.Errorf("fetchUser %s: %w", id, err)
+    }
+    return row, nil
+}
+
+// caller must inspect error before using value
+user, err := FetchUser(id)
+if err != nil {
+    return err
+}
+```
+
+```python
+# good — use a result-like pattern or explicit sentinel returns
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+@dataclass
+class Ok(Generic[T]):
+    value: T
+
+@dataclass
+class Err:
+    error: str
+
+def fetch_user(user_id: str) -> Ok[User] | Err:
+    try:
+        row = db.query("SELECT * FROM users WHERE id = %s", (user_id,))
+        if row is None:
+            return Err("not-found")
+        return Ok(row)
+    except DBError as e:
+        logger.error("db query failed", exc_info=True, extra={"user_id": user_id})
+        return Err("db-error")
+```
+
+---
+
+#### 3. Centralise repetitive catch logic into utility helpers
+
+If the same `try/catch` pattern (e.g., logging, classifying HTTP errors, wrapping exceptions) appears in multiple places, extract it into a shared utility. Do not copy-paste catch blocks across the codebase.
+
+*Why:* Scattered catch blocks drift out of sync — one gets updated, the others don't. A central utility is tested once and applied everywhere consistently.
+
+**Examples:**
+
+```typescript
+// bad — copy-pasted http error handling across many call sites
+try {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+} catch (e) {
+  logger.error({ err: e }, "request failed");
+  throw e;
+}
+
+// good — one utility used everywhere
+async function httpGet<T>(url: string): Promise<Result<T, HttpError>> {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) return { ok: false, error: new HttpError(res.status, url) };
+    return { ok: true, value: (await res.json()) as T };
+  } catch (e) {
+    logger.error({ err: e, url }, "http request failed");
+    return { ok: false, error: new HttpError(0, url, e as Error) };
+  }
+}
+```
+
+```python
+# good — a decorator that handles and logs DB errors uniformly
+def handle_db_errors(fn):
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except DBError as e:
+            logger.error("db error in %s", fn.__name__, exc_info=True)
+            return Err("db-error")
+    return wrapper
+
+@handle_db_errors
+def fetch_user(user_id: str): ...
+
+@handle_db_errors
+def save_order(order: Order): ...
+```
+
+---
+
+#### 4. Communicate failure clearly at process and service boundaries
+
+Every system boundary must signal failure explicitly:
+
+- **OS processes** must exit with a **non-zero exit code** when something went wrong. Exit code `0` means success.
+- **HTTP services** must return a **non-2xx/3xx status code** on error, accompanied by a response body that describes the problem without exposing internal system details (stack traces, SQL queries, internal paths, etc.).
+- **All error responses** should be logged to the console/structured logger, especially system-level or unexpected errors. Operational teams must be able to find the cause from logs alone.
+
+*Why:* Orchestrators, CI runners, load balancers, and callers all rely on these signals to detect failures automatically. A process or service that reports success on failure leads to silent data corruption and missed alerts.
+
+**Examples:**
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail  # exit immediately on error, unset variable, or pipe failure
+
+run_migration() {
+  ./bin/migrate up || { echo "Migration failed" >&2; exit 1; }
+}
+
+run_migration
+```
+
+```typescript
+// HTTP handler — bad: always 200, internals leaked
+app.post("/orders", async (req, res) => {
+  try {
+    const order = await createOrder(req.body);
+    res.json(order);
+  } catch (e) {
+    res.status(200).json({ error: e.stack }); // wrong status, stack leaked
+  }
+});
+
+// HTTP handler — good: correct status, safe message, logged internally
+app.post("/orders", async (req, res) => {
+  const result = await createOrder(req.body);
+  if (!result.ok) {
+    if (result.error === "validation") {
+      return res.status(400).json({ error: "Invalid order data" });
+    }
+    logger.error({ error: result.error }, "unexpected error creating order");
+    return res.status(500).json({ error: "Internal server error" });
+  }
+  res.status(201).json(result.value);
+});
+```
+
+```python
+# FastAPI — good error response
+@app.post("/orders", status_code=201)
+def create_order_endpoint(payload: OrderRequest):
+    result = create_order(payload)
+    if isinstance(result, Err):
+        if result.error == "validation":
+            raise HTTPException(status_code=400, detail="Invalid order data")
+        logger.error("unexpected error creating order: %s", result.error)
+        raise HTTPException(status_code=500, detail="Internal server error")
+    return result.value
+```
+
+---
+
+#### 5. Write test cases for error scenarios
+
+Every module that handles errors must have dedicated test cases that verify the error paths. Do not only test the happy path.
+
+*Why:* Error handling code is the code most likely to be broken and the code least likely to be exercised in manual testing. Without automated tests, regressions in error paths go undetected until production.
+
+Typical error scenarios to cover:
+
+- The dependency (DB, HTTP service, file system) is unavailable or times out.
+- The input is invalid, missing, or out of range.
+- A partial failure occurs (some items processed, some not).
+- The system is in an unexpected state (e.g., record not found, duplicate key).
+
+**Examples:**
+
+```typescript
+// good — dedicated tests for error scenarios
+describe("fetchUser", () => {
+  it("returns ok:true with the user when found", async () => {
+    db.query.mockResolvedValue(mockUser);
+    const result = await fetchUser("123");
+    expect(result).toEqual({ ok: true, value: mockUser });
+  });
+
+  it("returns ok:false with 'not-found' when the user does not exist", async () => {
+    db.query.mockResolvedValue(null);
+    const result = await fetchUser("999");
+    expect(result).toEqual({ ok: false, error: "not-found" });
+  });
+
+  it("returns ok:false with 'db-error' when the db throws", async () => {
+    db.query.mockRejectedValue(new Error("connection refused"));
+    const result = await fetchUser("123");
+    expect(result).toEqual({ ok: false, error: "db-error" });
+  });
+});
+```
+
+```python
+# good
+def test_fetch_user_found(mock_db):
+    mock_db.query.return_value = sample_user
+    result = fetch_user("123")
+    assert isinstance(result, Ok)
+    assert result.value == sample_user
+
+def test_fetch_user_not_found(mock_db):
+    mock_db.query.return_value = None
+    result = fetch_user("999")
+    assert isinstance(result, Err)
+    assert result.error == "not-found"
+
+def test_fetch_user_db_error(mock_db):
+    mock_db.query.side_effect = DBError("connection refused")
+    result = fetch_user("123")
+    assert isinstance(result, Err)
+    assert result.error == "db-error"
+```