agentme 0.13.0 → 0.14.0

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

@@ -1,7 +1,7 @@
 ---
 name: agentme-edr-policy-018-ai-agent-development-standards
-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
+description: Defines the standard toolchain, framework, evaluation approach, testing strategy, and workflow patterns for building AI agents (tool-invocation loops) and LangGraph workflows in Python. Use when scaffolding, reviewing, or extending AI agent or workflow projects. For raw LLM calls and provider configuration, see agentme-edr-024.
+apply-to: AI agent and LangGraph workflow projects built with Python
 valid-from: 2026-05-26
 ---
 
@@ -17,49 +17,41 @@ Which tools, frameworks, and design patterns should AI agent projects follow to
 
 **Use Python with LangGraph for flow orchestration and MLflow for experiment tracking and local evaluation.**
 
+This policy covers the **Agent** and **Workflow** tiers of the three-tier conceptual model defined in [agentme-edr-024](024-llm-development-standards.md). For the definition of LLM, Agent, and Workflow, and for the LangChain framework rules that govern direct LLM calls, see [agentme-edr-024](024-llm-development-standards.md).
+
 ### Details
 
 #### 01-language-and-framework
 
-All agent projects MUST be implemented in Python, following [agentme-edr-014](014-python-project-tooling.md) for project structure, tooling, and Makefile conventions.
+All agent and workflow projects MUST be implemented in Python, following [agentme-edr-014](014-python-project-tooling.md) for project structure, tooling, and Makefile conventions.
 
 Agent flows MUST be built with **LangGraph**. Use LangGraph `StateGraph` to model each distinct workflow as an explicit directed graph with typed state.
 
-#### 02-llm-provider-compatibility
-
-Agent code MUST be compatible with both **OpenAI** and **Azure OpenAI** providers without code changes. Achieve this by:
-
-- Using the `langchain-openai` package which supports both providers through environment variables.
-- Selecting the provider by setting `OPENAI_API_TYPE=azure` (Azure OpenAI) or omitting it (OpenAI).
-- Never hardcoding provider-specific URLs, deployment names, or API versions in code; inject them through environment variables or a configuration object.
-
-Minimum required environment variable surface:
-
-| Variable | Purpose |
-|---|---|
-| `OPENAI_API_KEY` | API key (both providers) |
-| `OPENAI_API_BASE` / `AZURE_OPENAI_ENDPOINT` | Endpoint (Azure only) |
-| `OPENAI_API_VERSION` | API version (Azure only) |
-| `AZURE_OPENAI_DEPLOYMENT` | Deployment/model name (Azure only) |
-| `OPENAI_MODEL` | Model name (OpenAI only) |
+For all direct LLM calls within agent and workflow nodes, use LangChain per [agentme-edr-024](024-llm-development-standards.md).
 
 #### 03-observability-and-experiment-tracking
 
-Use **MLflow** for all agent observability and evaluation:
+Use **MLflow** for all agent and workflow observability and evaluation:
 
-- Wrap each agent run with `mlflow.start_run()` to capture traces, parameters, and metrics locally.
-- Enable LangChain auto-tracing via `mlflow.langchain.autolog()` at entry point startup.
+- Wrap each agent or workflow run with `mlflow.start_run()` to capture traces, parameters, and metrics locally.
 - Log run parameters (model name, temperature, prompt version) and output metrics (accuracy, latency, token counts) using `mlflow.log_param` / `mlflow.log_metric`.
 - Run a local MLflow tracking server with `mlflow ui` to inspect runs during development. Do not require a remote MLflow server for local development.
+- For LangChain-level auto-tracing of individual LLM calls, see [agentme-edr-024](024-llm-development-standards.md) rule `03-llm-observability`.
 
 #### 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 `07-workflow-structure` and rule `08-workflow-evals`.
 
+- **Evals** measure model accuracy and performance against expected outputs. They are REQUIRED before every release to verify the workflow meets specified accuracy thresholds. They run against real LLM providers to capture model drift. They log metrics to MLflow and MUST have project-defined quality thresholds that block releases when not met.
+- **Integration tests** verify that workflows execute end-to-end with real connectors and real models, using pass/fail assertions. They are ADVISED but not required. They validate wiring, error handling, and system integration, not model accuracy. See rule `13-three-tier-testing-strategy` for integration test guidelines.
+
+**Eval requirements:**
+
 - 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.
 - Add a `make eval` Makefile target in the module root Makefile (the same Makefile that sits alongside `lib/` and `examples/`) that delegates to all per-workflow eval targets.
 - Evaluation MUST run against real LLM providers, not recorded responses, to capture model drift. MLflow tracking MUST work locally without a remote server.
+- Evals MUST be executed before every release. Failed eval runs with accuracy below project-defined thresholds MUST block the release.
 
 #### 05-flow-documentation
 
@@ -149,7 +141,31 @@ Each `eval_<slice>.py` script MUST:
 
 The module root Makefile `make eval` target MUST delegate to `eval` in every `evals/<workflow>/Makefile`.
 
-#### 09-local-sandbox
+#### 09-node-naming-conventions
+
+LangGraph node names MUST follow a suffix convention that communicates the node's role at a glance. Names MUST be action-oriented and descriptive.
+
+| Suffix | Node type | When to use |
+|---|---|---|
+| `_llm` | LLM call | Any node whose primary action is a direct LLM inference call |
+| `_step` | Algorithmic step | Deterministic logic with no LLM involvement (transformation, validation, routing) |
+| `_tool` | Tool/API call | A node that wraps a single external tool or API (e.g. a REST endpoint, DB query) |
+| `_agent` | Subgraph agent | A node that invokes a nested subgraph containing its own tool-invocation cycle and LLM calls; prefer the **deepagents** library for these nodes |
+
+The Python function implementing the node SHOULD share the same name as the node alias passed to `add_node`, so that graph definitions and stack traces remain unambiguous:
+
+```python
+def draft_doc_llm(state): ...
+graph.add_node("draft_doc_llm", draft_doc_llm)
+
+# Tool node — calls the Stripe API
+def stripe_api_tool(state): ...
+graph.add_node("stripe_api_tool", stripe_api_tool)
+```
+
+Names MUST NOT use generic labels such as `node1`, `process`, or `run`. Each name must clearly express what action the node performs.
+
+#### 10-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.
 
@@ -167,8 +183,127 @@ Use deepagents whenever ANY of the following is true for a workflow or tool:
 - If the host-side code needs to pass files into the sandbox (e.g. generated config or input data), create a temporary directory with `tempfile.mkdtemp()`, write the files there, and mount it into the sandbox. Clean it up in the `finally` block.
 - Replace hand-rolled `read_file`, `search_files`, and `grep_file` tool implementations with the equivalent tools provided by deepagents.
 
+#### 11-state-type-conventions
+
+All TypedDict and dataclass types that represent LangGraph node or workflow state MUST end with `_state` in their name. This suffix signals at a glance that the type is a state boundary, not a plain data model.
+
+**Naming reference:**
+
+| Owner | Naming pattern | Example |
+|---|---|---|
+| Single agent / agent subgraph | `<agent_name>_agent_state` | `reviewer_agent_state` |
+| Full workflow (`StateGraph`) | `<workflow_name>_workflow_state` | `document_workflow_state` |
+| Named group of nodes sharing state | `<group_responsibility>_state` | `retrieval_pipeline_state` |
+
+**Boundary rules:**
+
+- Each agent or agent subgraph MUST define its own dedicated state type. Do not reuse or extend a generic state across unrelated agents.
+- Each workflow (`StateGraph`) MUST define its own top-level state type. The workflow state is the authoritative boundary for that graph's inputs and outputs.
+- When a group of nodes (not a full workflow and not a single agent) shares a state type, the type name MUST clearly reflect the shared responsibility. Generic names such as `shared_state`, `common_state`, or `global_state` are FORBIDDEN.
+- Large workflows MUST NOT use a single monolithic state that all nodes read and write. Split the state into per-phase or per-agent state types scoped to the subgraph or set of nodes that produce or consume each field.
+
+State type names SHOULD align with the agent or node names defined in rule `09-node-naming-conventions` (e.g., an agent node named `draft_doc_agent` has a state type named `draft_doc_agent_state`).
+
+#### 12-workflow-naming-conventions
+
+LangGraph `StateGraph` instances and their enclosing classes MUST be given a meaningful name that conveys the workflow's input, output, and/or behavior. The name MUST end with `Workflow` (PascalCase class) or `_workflow` (snake_case variable or directory).
+
+Choose a name that summarises what the workflow consumes, processes, and produces — avoid generic labels such as `Pipeline`, `Flow`, `Graph`, or `Process`.
+
+| Context | Pattern | Example |
+|---|---|---|
+| Python class | `<DescriptiveName>Workflow` | `FileMapJudgeReduceWorkflow` |
+| Python variable / instance | `<descriptive_name>_workflow` | `file_map_judge_reduce_workflow` |
+| Directory under `app/workflows/` | `<descriptive_name>_workflow` | `financial_report_analysis_workflow/` |
+
+**Good names** communicate purpose at a glance:
+
+- `FileMapJudgeReduceWorkflow` — maps files, judges each, then reduces results
+- `FinancialReportAnalysisWorkflow` — analyses financial report inputs
+- `MarketingCampaignExecutorWorkflow` — executes a marketing campaign end-to-end
+
+**Bad names** (FORBIDDEN): `MainWorkflow`, `AgentGraph`, `ProcessFlow`, `Workflow1`, `RunGraph`.
+
+#### 13-three-tier-testing-strategy
+
+AI agent and workflow projects recognize three distinct testing tiers, each with its own purpose, tooling, and execution model:
+
+| Tier | Purpose | Model source | External APIs | File naming | When to run | Required |
+|---|---|---|---|---|---|---|
+| **Unit tests** | Test workflow logic, routing, and state management in isolation | Mocked (FakeListChatModel) | Mocked or faked | `<name>_test.py` | On every commit | **Required** |
+| **Integration tests** | Verify end-to-end wiring with real models and real external connectors | Real LLM providers | Real connectors | `<name>_integration_test.py` | Before releases or on a schedule | Advised |
+| **Evals** | Measure model accuracy and performance against expected outputs | Real LLM providers | Real connectors | `eval_<slice>.py` (see rule 08) | Before every release | **Required** |
+
+**Unit test requirements (REQUIRED):**
+
+- MUST use mocked LLM providers (see [agentme-edr-024](024-llm-development-standards.md) rule `04-unit-test-mocking`).
+- MUST run offline with no external dependencies per [agentme-edr-004](../principles/004-unit-test-requirements.md) rule `02-must-run-offline`.
+- MUST achieve 80% code coverage per [agentme-edr-004](../principles/004-unit-test-requirements.md) rule `03-must-maintain-80-percent-coverage`.
+- MUST test workflow routing logic, conditional edges, state transformations, and error handling.
+- Files MUST be named `<name>_test.py` and placed alongside the source file per [agentme-edr-004](../principles/004-unit-test-requirements.md) rule `04-must-place-test-files-alongside-source`.
+- MUST achieve 80% coverage of workflow graph edges and branches per rule `14-workflow-graph-coverage`.
+
+**Integration test guidelines (ADVISED):**
+
+Integration tests are advised but not required. See [agentme-edr-007](../principles/007-project-quality-standards.md) rule `08-integration-tests-are-advised` for general integration testing guidelines.
+
+For AI agent and workflow projects specifically, when integration tests are implemented:
+
+- SHOULD use real LLM providers configured via environment variables
+- MAY use smaller, faster models (e.g., `gpt-3.5-turbo`) instead of production models to reduce cost and latency
+- SHOULD verify workflow execution with pass/fail assertions, not accuracy metrics (accuracy is measured by evals)
+
+**Eval requirements (REQUIRED):**
+
+Evals are REQUIRED for all agent and workflow projects. See rule `04-dataset-driven-accuracy-measurement` and rule `08-workflow-evals` for full requirements.
+
+- Evals MUST run against real LLM providers to capture model drift and log metrics to MLflow for tracking model performance over time.
+- Evals MUST be executed before every release to verify the workflow meets specified accuracy thresholds.
+- Failed eval runs with accuracy below project-defined thresholds MUST block the release.
+
+#### 13-workflow-graph-coverage
+
+LangGraph Workflows MUST achieve **80% coverage of workflow graph edges and branches** during unit-tests.
+
+**Graph edge coverage** measures whether each transition (edge) in the `StateGraph` is exercised by at least one test. This ensures that routing logic, conditional edges, and error paths are tested.
+
+**Requirements:**
+
+- Every conditional edge (e.g., `add_conditional_edges`) MUST have test cases covering each possible branch.
+- Every node→node transition MUST be exercised by at least one test.
+- Error handling paths (e.g., nodes that route to error states or retry nodes) MUST be tested with inputs that trigger those paths.
+- Use mocked LLM responses in unit tests to control which branches are taken (see [agentme-edr-024](024-llm-development-standards.md) rule `04-unit-test-mocking`).
+
+**Example:**
+
+```python
+def test_workflow_approval_path():
+    """Test the workflow takes the approval path when LLM returns APPROVE."""
+    fake_llm = FakeListChatModel(responses=["APPROVE"])
+    workflow = DocumentWorkflow(llm=fake_llm)
+    
+    result = workflow.invoke({"document": sample_doc})
+    
+    assert result["status"] == "approved"
+    assert "verify_approved" in result["_visited_nodes"]
+
+def test_workflow_rejection_path():
+    """Test the workflow takes the rejection path when LLM returns REJECT."""
+    fake_llm = FakeListChatModel(responses=["REJECT"])
+    workflow = DocumentWorkflow(llm=fake_llm)
+    
+    result = workflow.invoke({"document": sample_doc})
+    
+    assert result["status"] == "rejected"
+    assert "handle_rejection" in result["_visited_nodes"]
+```
+
+When measuring coverage, use the same 80% threshold: at least 80% of graph edges must be covered by unit tests.
+
 ## References
 
+- [agentme-edr-024](024-llm-development-standards.md) — LLM development standards: LangChain framework, provider compatibility, LLM observability, unit test mocking, and the LLM / Agent / Workflow conceptual model
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Unit test requirements including coverage, offline execution, and test file placement
 - [agentme-edr-021](021-pragmatic-hexagonal-architecture.md) — Adapter/application layer separation that defines the project layout
 - [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
 - [agentme-edr-019](019-ml-dataset-structure.md) — ML dataset structure for eval datasets

package/.xdrs/agentme/edrs/application/024-llm-development-standards.md

@@ -0,0 +1,116 @@
+---
+name: agentme-edr-policy-024-llm-development-standards
+description: Defines the standard framework, provider compatibility, observability approach, and unit testing patterns for LLM-based applications in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls, manages prompt context, or handles conversation history.
+apply-to: Python projects that make LLM calls, manage prompt context, or handle conversation threads
+valid-from: 2026-06-03
+---
+
+# agentme-edr-policy-024: LLM development standards
+
+## Context and Problem Statement
+
+LLM-based applications can be built at different levels of abstraction — from a single prompt call to a full autonomous agent or a complex multi-step workflow. Without a shared vocabulary and a prescribed framework, projects mix incompatible patterns for invoking models, managing context, and tracing requests.
+
+Which framework should be used for LLM calls, how should providers be configured, and what is the canonical meaning of "LLM", "agent", and "workflow" in this codebase?
+
+## Decision Outcome
+
+**Use LangChain as the standard framework for all direct LLM interactions. Adopt a strict three-tier conceptual model — LLM / Agent / Workflow — that maps each tier to a specific library.**
+
+### Conceptual model
+
+Three distinct tiers of LLM-based computation are recognized in this project. Every component MUST be classified into exactly one tier:
+
+| Tier | What it is | Library |
+|---|---|---|
+| **LLM** | A request → response prompt exchange with a model. May include a conversation history or thread. No autonomous decision-making. | `langchain` / `langchain-openai` |
+| **Agent** | An LLM-based flow driven by a tool-invocation loop that the LLM itself plans and executes. The LLM decides which tools to call and when to stop. | `deepagents` |
+| **Workflow** | A directed graph of nodes that mixes LLM-based nodes (simple LLM calls or agentic loops) with deterministic algorithmic nodes. The graph topology is defined in code, not chosen by the LLM at runtime. | `langgraph` |
+
+These tiers nest: a Workflow may contain Agent nodes; an Agent uses LLM calls internally. The tier of a component is determined by its outermost controlling structure.
+
+See [agentme-edr-018](018-ai-agent-development-standards.md) for Agent and Workflow implementation standards.
+
+### Details
+
+#### 01-conceptual-model
+
+Every component that interacts with an LLM MUST be classified as exactly one of the three tiers defined in the conceptual model table above: **LLM**, **Agent**, or **Workflow**.
+
+- Do NOT use the word "agent" to describe a component that only makes a single LLM call without a tool-invocation loop.
+- Do NOT use the word "workflow" to describe a component that is purely an LLM call with no graph structure.
+- When designing a new feature, identify the correct tier first. The tier determines which library and patterns apply (LangChain, deepagents, or LangGraph).
+
+#### 02-llm-framework
+
+All direct LLM calls MUST use **LangChain** via the `langchain` and `langchain-openai` packages.
+
+- Use `langchain-openai` as the provider integration layer. It supports both OpenAI and Azure OpenAI through environment variables, with no code changes required to switch.
+- Select the provider by setting `OPENAI_API_TYPE=azure` for Azure OpenAI or omitting it for OpenAI.
+- Never hardcode provider-specific URLs, deployment names, or API versions in code; inject them through environment variables or a configuration object.
+
+Minimum required environment variable surface:
+
+| Variable | Purpose |
+|---|---|
+| `OPENAI_API_KEY` | API key (both providers) |
+| `OPENAI_API_BASE` / `AZURE_OPENAI_ENDPOINT` | Endpoint (Azure only) |
+| `OPENAI_API_VERSION` | API version (Azure only) |
+| `AZURE_OPENAI_DEPLOYMENT` | Deployment/model name (Azure only) |
+| `OPENAI_MODEL` | Model name (OpenAI only) |
+
+LangChain chain or runnable definitions MUST be placed in `app/workflows/<workflow>/agents.py` (for workflow-scoped LLM calls) or in the appropriate application layer module. Do not inline LLM construction in adapter or CLI code.
+
+#### 03-llm-observability
+
+Enable LangChain auto-tracing at every application entry point by calling `mlflow.langchain.autolog()` during startup, before any LLM call is made.
+
+- This captures inputs, outputs, token counts, and latency for every LangChain chain or runnable automatically.
+- Pair with `mlflow.start_run()` at the workflow or agent level to group LLM traces under a named experiment run (see [agentme-edr-018](018-ai-agent-development-standards.md) for run-level MLflow instrumentation).
+- Do not disable autolog in production unless there is an explicit performance justification documented in the codebase.
+
+#### 04-unit-test-mocking
+
+LLM provider calls are external API calls and MUST be mocked in unit tests per [agentme-edr-004](../principles/004-unit-test-requirements.md) rule `06-should-avoid-mocks`. Mocking LLM providers enables offline test execution while testing workflow logic, routing, and state management.
+
+Use **LangChain's `FakeListChatModel`** or a custom `GenericFakeChatModel` wrapper for unit testing LLM calls:
+
+```python
+from langchain_core.language_models.fake_chat_models import FakeListChatModel
+
+# Unit test with mocked LLM responses
+def test_document_workflow_routing():
+    fake_llm = FakeListChatModel(responses=[
+        "APPROVE",
+        "The document meets all quality criteria."
+    ])
+    
+    workflow = DocumentWorkflow(llm=fake_llm)
+    result = workflow.run(input_doc)
+    
+    assert result.status == "approved"
+    assert "quality criteria" in result.reasoning
+```
+
+**Mocking boundaries:**
+
+- Mocks are ONLY for unit tests (required). Integration tests SHOULD use real LLM providers when implemented (see [agentme-edr-018](018-ai-agent-development-standards.md) rule `13-three-tier-testing-strategy`).
+- Evals MUST use real LLM providers to capture model drift and are REQUIRED before every release (see [agentme-edr-018](018-ai-agent-development-standards.md) rule `04-dataset-driven-accuracy-measurement`).
+- Mock the LLM provider at the construction boundary (dependency injection), not by patching internal LangChain methods.
+- Test files MUST follow the naming convention `<name>_test.py` for unit tests (see [agentme-edr-018](018-ai-agent-development-standards.md) rule `13-three-tier-testing-strategy` for integration test naming).
+
+When workflows or agents require injectable LLM instances, accept the LLM as a constructor parameter or configuration field:
+
+```python
+class DocumentWorkflow:
+    def __init__(self, llm: Optional[BaseChatModel] = None):
+        self.llm = llm or ChatOpenAI(model="gpt-4")
+```
+
+This allows unit tests to inject `FakeListChatModel` while production code uses the real provider.
+
+## References
+
+- [agentme-edr-018](018-ai-agent-development-standards.md) — Agent and Workflow implementation standards (LangGraph, deepagents, MLflow run-level tracking)
+- [agentme-edr-004](../principles/004-unit-test-requirements.md) — Unit test requirements including external API mocking guidance
+- [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure

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

@@ -31,8 +31,9 @@ Language and framework-specific tooling and project structure.
 - [agentme-edr-010](application/010-golang-project-tooling.md) - **Go project tooling and structure** - Scaffold Go CLIs and libraries with the standard layout *(includes skill: [003-create-golang-project](application/skills/003-create-golang-project/SKILL.md))*
 - [agentme-edr-014](application/014-python-project-tooling.md) - **Python project tooling and structure** - Scaffold Python packages and CLIs with the standard layout *(includes skill: [005-create-python-project](application/skills/005-create-python-project/SKILL.md))*
 - [agentme-edr-015](application/015-cli-tool-standards.md) - **CLI tool standards** - Define command UX and behavior for CLI tools
-- [agentme-edr-018](application/018-ai-agent-development-standards.md) - **AI agent development standards** - Standard toolchain, framework, evaluation, and workflow patterns for AI agent projects built with Python and LangGraph
+- [agentme-edr-018](application/018-ai-agent-development-standards.md) - **AI agent development standards** - Standard toolchain, framework, evaluation, and workflow patterns for AI agent and LangGraph workflow projects built with Python
 - [agentme-edr-019](application/019-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
+- [agentme-edr-024](application/024-llm-development-standards.md) - **LLM development standards** - Default framework (LangChain), provider compatibility, observability, and conceptual model (LLM / Agent / Workflow) for LLM-based applications
 - [agentme-edr-020](application/020-ai-agent-xdrs-knowledge-layer.md) - **AI agent XDRS knowledge layer** - How to integrate XDRS as the runtime source of truth for policies and skills in AI agents (apply only when the project explicitly uses XDRS)
 - [agentme-edr-021](application/021-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules
 - [004-select-relevant-xdrs](application/skills/004-select-relevant-xdrs/SKILL.md) - **Select relevant XDRs**

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

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-007-project-quality-standards
-description: Defines minimum project quality standards for README onboarding, testing, linting, XDR compliance, and runnable examples. Use when scaffolding or reviewing projects.
+description: Defines minimum project quality standards for README onboarding, testing (unit and integration), linting, XDR compliance, and runnable examples. Use when scaffolding or reviewing projects.
 apply-to: All projects
 valid-from: 2026-05-25
 ---
@@ -15,7 +15,7 @@ What minimum quality standards must every project in the organization meet to en
 
 ## 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.
+Every project must meet the 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. Integration tests are advised but not required. Projects with statistical models must have evaluation targets with performance thresholds.
 
 These standards form a non-negotiable baseline. Individual projects may raise the bar but must never fall below it.
 
@@ -189,3 +189,44 @@ eval:
 	  --min-f1 $(EVAL_MIN_F1) \
 	  || (echo "Evaluation failed: metrics below threshold"; exit 1)
 ```
+
+---
+
+#### 08-integration-tests-are-advised
+
+Integration tests verify end-to-end system behavior with real external dependencies (databases, APIs, message queues, file systems, cloud services). While not required, integration tests are strongly advised for projects that interact with external systems.
+
+**When to implement integration tests:**
+
+- The project makes calls to external APIs or services
+- The project reads from or writes to databases
+- The project integrates with third-party systems (payment processors, authentication providers, etc.)
+- The project's behavior depends on the interaction between multiple components or services
+- Unit tests alone cannot adequately verify system integration points
+
+**Integration test guidelines (when implemented):**
+
+- SHOULD verify end-to-end execution with real external dependencies or containerized equivalents (e.g., postgres in Docker, localstack for AWS services)
+- SHOULD use pass/fail assertions to validate expected behavior and error handling
+- SHOULD be isolated from unit tests to allow independent execution
+- Files SHOULD be named with a clear integration test suffix (e.g., `<name>_integration_test.py`, `<name>.integration.test.ts`)
+- MAY be run less frequently than unit tests (e.g., nightly, before releases) to manage execution time and external dependency costs
+- MAY use smaller or cheaper configurations of external services when available (e.g., smaller database instances, development-tier API keys)
+
+**Makefile target:**
+
+When integration tests exist, provide a dedicated `make test-integration` target:
+
+```makefile
+test: test-unit
+
+test-unit:
+	# Run fast offline unit tests
+	pytest lib/src/
+
+test-integration:
+	# Run integration tests with real dependencies
+	pytest lib/src/ -m integration
+```
+
+Projects are not required to implement integration tests, but when present, they SHOULD follow these conventions for consistency across the codebase.

package/package.json

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