agentme 0.16.0 → 0.17.0

package/.xdrs/agentme/edrs/application/010-golang-project-tooling.md

@@ -82,7 +82,7 @@ Direct installation of project-required Go CLIs with `go install ...@latest` as
 - 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).
+- Application MAY import from Adapters when it simplifies the design (pragmatic coupling per edr-022 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

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

@@ -1,6 +1,6 @@
 ---
 name: agentme-edr-policy-018-ai-llm-development-standards
-description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-019, for workflow patterns see agentme-edr-020.
+description: Defines the standard framework, provider configuration, observability approach, and LLM mocking patterns for simple LLM calls in Python. Use when building, reviewing, or scaffolding any code that makes direct LLM calls using LangChain, manages prompt context, or handles conversation history. For agentic patterns see agentme-edr-019, for workflow patterns see agentme-edr-021.
 apply-to: Python projects that make direct LLM calls, manage prompt context, or handle conversation threads
 valid-from: 2026-06-05
 ---
@@ -29,7 +29,7 @@ Three distinct tiers of LLM-based computation are recognized in this policy. Eve
 
 These tiers nest: in general, 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-019](019-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-020](020-ai-workflow-development-standards.md) for Workflow implementation standards.
+See [agentme-edr-019](019-ai-agents-development-standards.md) for Agent implementation standards and [agentme-edr-021](021-ai-workflow-development-standards.md) for Workflow implementation standards.
 
 ### Details
 
@@ -174,8 +174,8 @@ prompt = PromptTemplate.from_file(
 ## References
 
 - [agentme-edr-019](019-ai-agents-development-standards.md) — Agent implementation standards (deepagents, tool-invocation loops)
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, MLflow run-level tracking)
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow implementation standards (LangGraph, 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
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/019-ai-agents-development-standards.md

@@ -1,7 +1,7 @@
 ---
 name: agentme-edr-policy-019-ai-agents-development-standards
-description: Defines the standard framework and patterns for building AI agents with tool-invocation loops using the deepagents framework. Use when building agents where the LLM autonomously decides which tools to call and when to stop. For simple LLM calls see agentme-edr-018, for workflow orchestration see agentme-edr-020.
-apply-to: AI agent projects that use tool-invocation loops where the LLM decides which tools to call and when to stop
+description: Defines the structural patterns and design decisions for building AI agents with tool-invocation loops using the deepagents framework: framework selection, sandbox setup, state naming, agent naming, composition patterns, and system prompt structure. Use when designing or scaffolding a new agent. For tool definitions, error handling, observability, and testing see agentme-edr-020. For simple LLM calls see agentme-edr-018, for workflow orchestration see agentme-edr-021.
+apply-to: AI agent projects — consult when designing agent structure, choosing sandbox approach, defining naming conventions, and composing multi-agent systems
 valid-from: 2026-06-05
 ---
 
@@ -9,9 +9,9 @@ valid-from: 2026-06-05
 
 ## Context and Problem Statement
 
-AI applications often need to give LLMs the ability to autonomously choose and invoke tools to accomplish tasks. Without standardized patterns for agent implementation, projects end up with incompatible approaches to tool definition, state management, and runtime environments.
+AI applications often need to give LLMs the ability to autonomously choose and invoke tools to accomplish tasks. Without standardized structural patterns for agent design, projects end up with incompatible approaches to framework selection, sandbox setup, state management, naming, composition, and system prompts.
 
-Which framework should be used for building agents with tool-invocation loops, and what are the essential patterns for agent state, tools, and execution environments?
+Which framework should be used for building agents, how should agents be sandboxed, named, composed, and how should their system prompts be structured?
 
 ## Decision Outcome
 
@@ -87,84 +87,9 @@ def run_file_analysis_agent(input_files: List[Path]) -> AnalysisResult:
 **State type naming:**
 
 - Agent state types MUST end with `_agent_state` suffix (e.g., `file_analyzer_agent_state`)
-- Follow [agentme-edr-020](020-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
+- Follow [agentme-edr-021](021-ai-workflow-development-standards.md) rule `11-state-type-conventions` when agents are used as workflow nodes
 
-#### 04-tool-definition-patterns
-
-Tools provided to agents MUST follow these patterns:
-
-**Tool signature:**
-
-```python
-from typing import Any, Dict
-
-def tool_name(arg1: str, arg2: int) -> Dict[str, Any]:
-    """
-    Brief description of what the tool does.
-    
-    Args:
-        arg1: Description of arg1
-        arg2: Description of arg2
-    
-    Returns:
-        Dictionary with tool execution results
-    """
-    # Tool implementation
-    return {"status": "success", "result": ...}
-```
-
-**Tool requirements:**
-
-- Tool names MUST be descriptive action verbs (e.g., `search_files`, `execute_command`, `read_document`)
-- Tool docstrings MUST clearly describe the tool's purpose, arguments, and return value (the LLM reads these)
-- Tools MUST return structured data (dictionaries or dataclasses), not bare strings or untyped values
-- Tools MUST handle errors gracefully and return error information in the result structure, not raise exceptions
-- Tools that interact with external systems MUST be placed in `adapters/connectors/` per [agentme-edr-026](026-pragmatic-hexagonal-architecture.md)
-
-**Error handling in tools:**
-
-```python
-def search_files(pattern: str, directory: str = ".") -> Dict[str, Any]:
-    """Search for files matching a glob pattern."""
-    try:
-        matches = list(Path(directory).glob(pattern))
-        return {
-            "status": "success",
-            "matches": [str(m) for m in matches],
-            "count": len(matches)
-        }
-    except Exception as e:
-        return {
-            "status": "error",
-            "error_message": str(e),
-            "error_type": type(e).__name__
-        }
-```
-
-#### 05-agent-error-handling-and-recovery
-
-Agents MUST implement robust error handling:
-
-**Maximum iteration limits:**
-
-- Every agent MUST have a maximum iteration limit to prevent infinite loops
-- The default maximum SHOULD be configurable and logged when reached
-- When the maximum is reached, the agent MUST return a structured failure result, not raise an exception
-
-**Tool failure handling:**
-
-- When a tool returns an error, the agent MUST be able to observe the error and decide on recovery actions
-- Tools MUST NOT raise exceptions for expected failures (network errors, file not found, etc.)
-- Agents MAY implement retry logic with exponential backoff for transient failures
-
-**Terminal states:**
-
-Agents MUST recognize and handle three terminal states:
-- **Success**: Goal achieved, task complete
-- **Failure**: Goal cannot be achieved, give up gracefully
-- **Timeout**: Maximum iterations reached, return partial results if possible
-
-#### 06-agent-naming-conventions
+#### 04-agent-naming-conventions
 
 Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` describes what the agent does:
 
@@ -179,93 +104,14 @@ Agent class names MUST follow the pattern `<Purpose>Agent` where `<Purpose>` des
 - `MyAgent` (not descriptive)
 - `Agent1` (numbered, not semantic)
 
-When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-020](020-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
-
-#### 07-agent-observability
-
-Agent execution MUST be observable through logging and tracing:
-
-- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
-- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
-- For LLM calls within agents, follow [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability`.
-- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
-- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`.
+When agents are used as nodes in workflows, the node name MUST use the `_agent` suffix per [agentme-edr-021](021-ai-workflow-development-standards.md) rule `09-node-naming-conventions`.
 
-**Example structured log entry:**
-
-```json
-{
-  "timestamp": "2026-06-05T10:30:45Z",
-  "agent": "FileAnalyzerAgent",
-  "iteration": 3,
-  "tool_selected": "search_files",
-  "tool_args": {"pattern": "*.py"},
-  "tool_result_status": "success",
-  "decision": "continue"
-}
-```
-
-#### 08-agent-unit-testing
-
-Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
-
-Because agents drive a tool-invocation loop — where the LLM decides which tools to call — the fake model must return **tool-call messages** followed by a final answer. Use **`GenericFakeChatModel`** for this:
-
-```python
-from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
-from langchain_core.messages import AIMessage
-
-def test_file_analyzer_agent_calls_search_then_stops():
-    # Iteration 1: LLM requests a tool call
-    tool_call_msg = AIMessage(
-        content="",
-        tool_calls=[{
-            "name": "search_files",
-            "args": {"pattern": "*.py", "directory": "/workspace"},
-            "id": "call_1"
-        }]
-    )
-    # Iteration 2: LLM produces a final answer after observing the tool result
-    final_msg = AIMessage(content="Found 3 Python files matching the pattern.")
-
-    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
-
-    agent = FileAnalyzerAgent(model=fake_model)
-    result = agent.run(directory="/workspace")
-
-    assert result.status == "success"
-    assert "3 Python files" in result.summary
-```
-
-Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
-
-**`mock_deep_agent`**
-
-Place `mock_deep_agent` in a shared test utilities module (e.g., `tests/helpers.py`) so all test files that need it can import it from one location and mock deep_agent instances when needed.
-
-**Example usage:**
-
-```python
-from tests.helpers import mock_deep_agent
-
-def test_workflow_calls_subagent(mocker):
-    mock_deep_agent(
-        mocker,
-        "mypackage.nodes.analysis_node.create_workflow_agent",
-        output={"status": "success", "findings": ["issue A"]}
-    )
-
-    result = run_analysis_workflow(input_data)
-
-    assert result.findings == ["issue A"]
-```
-
-#### 09-agent-composition
+#### 05-agent-composition
 
 When multiple agents are needed:
 
 - **Single agent with multiple tools:** Use when tools share a common goal and context (e.g., a code analysis agent with `read_file`, `search_code`, and `analyze_pattern` tools).
-- **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-020](020-ai-workflow-development-standards.md).
+- **Multiple agents as workflow nodes:** Use when agents have distinct responsibilities and outputs that feed into each other. Orchestrate them using LangGraph per [agentme-edr-021](021-ai-workflow-development-standards.md).
 - Do NOT create nested agent loops (agent calling agent autonomously). Use workflows for multi-agent orchestration.
 
 **Decision criteria:**
@@ -276,11 +122,74 @@ When multiple agents are needed:
 | Multiple workflow-orchestrated agents | Each agent has a distinct goal; outputs flow between agents; deterministic sequencing needed |
 | Nested agents (FORBIDDEN) | Never — always use workflow orchestration instead |
 
+#### 06-agent-system-prompt-structure
+
+Every agent system prompt MUST follow this XML-section template. Sections must appear in this order. Required sections must always be present; optional sections may be omitted when they genuinely do not apply; never reorder them.
+
+```xml
+<OBJECTIVE>
+[A one or two-sentence summary of the agent's main deliverable.
+e.g.: Split the incoming file list into logical batches for parallel processing.]
+</OBJECTIVE>
+
+<ROLE>
+[Defines who the agent is, its area of expertise, and its core persona.
+If running inside a workflow, define exactly which node in WORKFLOW_CONTEXT this agent corresponds to.
+e.g.: You are the batch_planning_agent (see WORKFLOW_CONTEXT). You are an expert at partitioning large file sets into balanced, directory-aware batches.]
+</ROLE>
+
+<INPUT>
+[All inputs for this agent invocation. For standalone agents: list only the agent-specific inputs. For workflow agents: list workflow-level inputs shared across all agents first, then agent-specific inputs such as judge outcomes, counters, or intermediate results from upstream nodes.]
+</INPUT>
+
+<!-- Optional: include when the agent follows a non-trivial sequence of steps -->
+<STEPS>
+[Numbered list or chronological steps detailing how the agent should process an incoming request.
+e.g.:
+1. Analyse the file list and group files by directory.
+2. Assign files to batches respecting the size constraints.
+3. Emit the JSON output described in OUTPUT_FORMAT.]
+</STEPS>
+
+<!-- Optional: include when tool use needs explicit guidance -->
+<TOOL_GUIDANCE>
+[Explicit instructions on when and how to use external tools, preventing the agent from guessing or using the wrong sequence.
+e.g.: Do not call any tools. All reasoning is done in-context using the INPUT fields only.]
+</TOOL_GUIDANCE>
+
+<!-- Optional: include when hard constraints need to be stated explicitly -->
+<GUARDRAILS>
+[Hard, non-negotiable constraints the agent must never violate.
+e.g.: NEVER create batches with fewer than 5 or more than 20 files. NEVER split files from the same directory across different batches unless unavoidable.]
+</GUARDRAILS>
+
+<OUTPUT_FORMAT>
+[A templated example or JSON schema specifying exactly how the final response should look.
+e.g.: Respond with a JSON object matching this schema: ...]
+</OUTPUT_FORMAT>
+
+<!-- Workflow-only: omit this section for standalone (non-workflow) agents -->
+<WORKFLOW_CONTEXT>
+[A detailed prose or diagram description of the overall workflow graph so the agent understands its role within the larger flow. Reference the specific node name that maps to this agent. Include enough detail about upstream and downstream nodes so the agent can reason about its context.]
+</WORKFLOW_CONTEXT>
+```
+
+**Rules:**
+
+| Section | Required? | Notes |
+|---|---|---|
+| `<OBJECTIVE>` | Required | One or two sentences summarising the agent's main deliverable. |
+| `<ROLE>` | Required | Agent persona and expertise. When inside a workflow, MUST reference its node name from `<WORKFLOW_CONTEXT>`. |
+| `<INPUT>` | Required | List ALL inputs. For workflow agents: workflow-level inputs first, then agent-specific inputs. |
+| `<STEPS>` | Optional | Include when the agent follows a non-trivial numbered sequence of steps. |
+| `<TOOL_GUIDANCE>` | Optional | Include when tool use order or conditions need explicit direction. |
+| `<GUARDRAILS>` | Optional | Hard constraints that must never be violated. |
+| `<OUTPUT_FORMAT>` | Required | MUST include a concrete schema or templated example; do not leave it vague. |
+| `<WORKFLOW_CONTEXT>` | Conditional | MUST be omitted for standalone agents. MUST be present when the agent runs as a node inside a LangGraph workflow. |
+
 ## References
 
 - [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
-- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow development standards (using agents as workflow nodes)
+- [agentme-edr-020](020-ai-agents-quality-standards.md) — Agent implementation quality standards (tool definitions, error handling, observability, unit testing)
 - [agentme-edr-014](014-python-project-tooling.md) — Python project tooling and structure
-- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/020-ai-agents-quality-standards.md

@@ -0,0 +1,182 @@
+---
+name: agentme-edr-policy-020-ai-agents-quality-standards
+description: Defines implementation quality standards for AI agents: tool definition patterns, error handling and recovery, observability, and unit testing. Apply alongside agentme-edr-019 when implementing or reviewing agent code. For agent architecture and structural decisions (framework, sandbox, naming, composition, system prompts) see agentme-edr-019.
+apply-to: AI agent implementation code — apply when writing tools, error handlers, logging, and unit tests for agents
+valid-from: 2026-06-09
+---
+
+# agentme-edr-policy-020: AI agents quality standards
+
+## Context and Problem Statement
+
+Beyond selecting the right framework and structural patterns, agent implementations require consistent standards for how tools are defined, how errors are handled, how execution is observed, and how agents are tested. Without these standards, agents become hard to debug, unreliable, and untestable.
+
+How should agent tools be defined, what error handling must agents implement, how should agent execution be observed, and how should agents be unit tested?
+
+## Decision Outcome
+
+**Agent implementations MUST follow the tool definition, error handling, observability, and unit testing standards defined here, alongside the structural decisions in [agentme-edr-019](019-ai-agents-development-standards.md).**
+
+### Details
+
+#### 01-tool-definition-patterns
+
+Tools provided to agents MUST follow these patterns:
+
+**Tool signature:**
+
+```python
+from typing import Any, Dict
+
+def tool_name(arg1: str, arg2: int) -> Dict[str, Any]:
+    """
+    Brief description of what the tool does.
+    
+    Args:
+        arg1: Description of arg1
+        arg2: Description of arg2
+    
+    Returns:
+        Dictionary with tool execution results
+    """
+    # Tool implementation
+    return {"status": "success", "result": ...}
+```
+
+**Tool requirements:**
+
+- Tool names MUST be descriptive action verbs (e.g., `search_files`, `execute_command`, `read_document`)
+- Tool docstrings MUST clearly describe the tool's purpose, arguments, and return value (the LLM reads these)
+- Tools MUST return structured data (dictionaries or dataclasses), not bare strings or untyped values
+- Tools MUST handle errors gracefully and return error information in the result structure, not raise exceptions
+- Tools that interact with external systems MUST be placed in `adapters/connectors/` per [agentme-edr-026](026-pragmatic-hexagonal-architecture.md)
+
+**Error handling in tools:**
+
+```python
+def search_files(pattern: str, directory: str = ".") -> Dict[str, Any]:
+    """Search for files matching a glob pattern."""
+    try:
+        matches = list(Path(directory).glob(pattern))
+        return {
+            "status": "success",
+            "matches": [str(m) for m in matches],
+            "count": len(matches)
+        }
+    except Exception as e:
+        return {
+            "status": "error",
+            "error_message": str(e),
+            "error_type": type(e).__name__
+        }
+```
+
+#### 02-agent-error-handling-and-recovery
+
+Agents MUST implement robust error handling:
+
+**Maximum iteration limits:**
+
+- Every agent MUST have a maximum iteration limit to prevent infinite loops
+- The default maximum SHOULD be configurable and logged when reached
+- When the maximum is reached, the agent MUST return a structured failure result, not raise an exception
+
+**Tool failure handling:**
+
+- When a tool returns an error, the agent MUST be able to observe the error and decide on recovery actions
+- Tools MUST NOT raise exceptions for expected failures (network errors, file not found, etc.)
+- Agents MAY implement retry logic with exponential backoff for transient failures
+
+**Terminal states:**
+
+Agents MUST recognize and handle three terminal states:
+- **Success**: Goal achieved, task complete
+- **Failure**: Goal cannot be achieved, give up gracefully
+- **Timeout**: Maximum iterations reached, return partial results if possible
+
+#### 03-agent-observability
+
+Agent execution MUST be observable through logging and tracing:
+
+- Log each iteration of the perceive → plan → act → observe cycle with iteration number and tool selection.
+- Use structured logging (JSON) with fields: `iteration`, `tool_selected`, `tool_result_status`, `decision`.
+- For LLM calls within agents, follow [agentme-edr-018](018-ai-llm-development-standards.md) rule `03-llm-observability`.
+- When agents run as workflow nodes, MLflow tracking from the parent workflow automatically captures agent-level traces.
+- The project Makefile MUST expose a `dev-mlflow` target to start a local MLflow tracking server for development inspection, per [agentme-edr-008](../devops/008-common-targets.md) rule `09-ai-project-dev-targets`.
+
+**Example structured log entry:**
+
+```json
+{
+  "timestamp": "2026-06-05T10:30:45Z",
+  "agent": "FileAnalyzerAgent",
+  "iteration": 3,
+  "tool_selected": "search_files",
+  "tool_args": {"pattern": "*.py"},
+  "tool_result_status": "success",
+  "decision": "continue"
+}
+```
+
+#### 04-agent-unit-testing
+
+Agent LLM calls are external API calls and MUST be mocked in unit tests per [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking`.
+
+Because agents drive a tool-invocation loop — where the LLM decides which tools to call — the fake model must return **tool-call messages** followed by a final answer. Use **`GenericFakeChatModel`** for this:
+
+```python
+from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
+from langchain_core.messages import AIMessage
+
+def test_file_analyzer_agent_calls_search_then_stops():
+    # Iteration 1: LLM requests a tool call
+    tool_call_msg = AIMessage(
+        content="",
+        tool_calls=[{
+            "name": "search_files",
+            "args": {"pattern": "*.py", "directory": "/workspace"},
+            "id": "call_1"
+        }]
+    )
+    # Iteration 2: LLM produces a final answer after observing the tool result
+    final_msg = AIMessage(content="Found 3 Python files matching the pattern.")
+
+    fake_model = GenericFakeChatModel(messages=iter([tool_call_msg, final_msg]))
+
+    agent = FileAnalyzerAgent(model=fake_model)
+    result = agent.run(directory="/workspace")
+
+    assert result.status == "success"
+    assert "3 Python files" in result.summary
+```
+
+Agents MUST be designed so that the LLM instance is injectable (constructor parameter) to allow test doubles. See [agentme-edr-018](018-ai-llm-development-standards.md) rule `04-unit-test-mocking` for the injectable LLM pattern.
+
+**`mock_deep_agent`**
+
+Place `mock_deep_agent` in a shared test utilities module (e.g., `tests/helpers.py`) so all test files that need it can import it from one location and mock deep_agent instances when needed.
+
+**Example usage:**
+
+```python
+from tests.helpers import mock_deep_agent
+
+def test_workflow_calls_subagent(mocker):
+    mock_deep_agent(
+        mocker,
+        "mypackage.nodes.analysis_node.create_workflow_agent",
+        output={"status": "success", "findings": ["issue A"]}
+    )
+
+    result = run_analysis_workflow(input_data)
+
+    assert result.findings == ["issue A"]
+```
+
+## References
+
+- [agentme-edr-019](019-ai-agents-development-standards.md) — Agent development standards (framework, sandbox, naming, composition, system prompts)
+- [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards (LangChain configuration, mocking patterns)
+- [agentme-edr-026](026-pragmatic-hexagonal-architecture.md) — Hexagonal architecture (tool placement in adapters/connectors)
+- [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking

package/.xdrs/agentme/edrs/application/{020-ai-workflow-development-standards.md → 021-ai-workflow-development-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-020-ai-workflow-development-standards
+name: agentme-edr-policy-021-ai-workflow-development-standards
 description: Defines the standard toolchain, framework, observability, and workflow patterns for building LangGraph workflows in Python. Use when scaffolding, reviewing, or extending AI workflow projects that orchestrate LLM calls, agents, and algorithmic nodes. For simple LLM calls see agentme-edr-018, for agentic patterns see agentme-edr-019.
 apply-to: AI workflow projects using LangGraph StateGraph built with Python
 valid-from: 2026-06-05
 ---
 
-# agentme-edr-policy-020: AI workflow development standards
+# agentme-edr-policy-021: AI workflow development standards
 
 ## Context and Problem Statement
 
@@ -37,7 +37,7 @@ Use **MLflow** for all workflow observability and evaluation:
 
 #### 04-dataset-driven-accuracy-measurement
 
-Eval dataset and implementation requirements are defined in [agentme-edr-021](021-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
+Eval dataset and implementation requirements are defined in [agentme-edr-028](028-ai-eval-standards.md). Testing requirements (when evals are required, release gates) are defined in [agentme-edr-007](../principles/007-project-quality-standards.md) rule `09-ai-project-testing-requirements`.
 
 #### 05-flow-documentation
 
@@ -101,7 +101,7 @@ lib/src/<package_name>/
 
 #### 08-workflow-evals
 
-Eval folder structure and script requirements are defined in [agentme-edr-021](021-ai-eval-standards.md).
+Eval folder structure and script requirements are defined in [agentme-edr-028](028-ai-eval-standards.md).
 
 #### 09-node-naming-conventions
 
@@ -258,5 +258,5 @@ result = graph.invoke(input_state, config={"thread_id": "session-123"})
 - [agentme-edr-026](026-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-024](024-ml-dataset-structure.md) — ML dataset structure for eval datasets
-- [agentme-edr-021](021-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
+- [agentme-edr-028](028-ai-eval-standards.md) — AI eval standards: folder structure, script requirements, and MLflow tracking
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards including AI-tier testing requirements (rule `09-ai-project-testing-requirements`)

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

@@ -17,7 +17,7 @@ How should an AI agent project integrate XDRS as its runtime source of truth for
 
 **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-019](019-ai-agents-development-standards.md) or [agentme-edr-020](020-ai-workflow-development-standards.md) in general.
+This policy MUST only be applied when the project explicitly chooses XDRS as its knowledge governance layer. It is not required by [agentme-edr-019](019-ai-agents-development-standards.md) or [agentme-edr-021](021-ai-workflow-development-standards.md) in general.
 
 ### Details
 
@@ -59,7 +59,7 @@ 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.
+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-019 rule 02-local-sandbox](019-ai-agents-development-standards.md) for the full sandbox and tool requirements.
 
 These tools operate over two sandboxed roots (configured in rule `03-local-sandbox`):
 
@@ -72,7 +72,7 @@ These tools operate over two sandboxed roots (configured in rule `03-local-sandb
 
 #### 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:
+Follow [agentme-edr-019 rule 02-local-sandbox](019-ai-agents-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 |
 |---|---|---|
@@ -92,8 +92,13 @@ 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-019 rule 02-local-sandbox:
-xdrs_mounts = [
-    {"src": f"{data_root}/.xdrs", "dst": "/.xdrs",    "readonly": True},
-    {"src": str(agents_md),       "dst": "/AGENTS.md", "readonly": True},
-]
+# (mount_paths uses {src: dst} dict format per agentme-edr-019)
+sandbox = Sandbox(
+    mount_paths={
+        tmp_dir: "/workspace",
+        f"{data_root}/.xdrs": "/.xdrs",
+        str(agents_md): "/AGENTS.md",
+    },
+    virtual_mode=True,
+)
 ```

package/.xdrs/agentme/edrs/application/{021-ai-eval-standards.md → 028-ai-eval-standards.md}

@@ -1,11 +1,11 @@
 ---
-name: agentme-edr-policy-021-ai-eval-standards
+name: agentme-edr-policy-028-ai-eval-standards
 description: Defines how to structure, write, and run eval tests for AI projects — folder layout, script requirements, and MLflow tracking. Use when implementing evals for LLM, Agent, or Workflow projects. For when evals are required see agentme-edr-007 rule 09-ai-project-testing-requirements.
 apply-to: Python AI projects (LLM, Agent, or Workflow tier) that implement eval testing
 valid-from: 2026-06-05
 ---
 
-# agentme-edr-policy-021: AI eval standards
+# agentme-edr-policy-028: AI eval standards
 
 ## Context and Problem Statement
 
@@ -86,5 +86,6 @@ with mlflow.start_run():
 - [agentme-edr-007](../principles/007-project-quality-standards.md) — Project quality standards: when evals are required per AI tier (rule `09-ai-project-testing-requirements`) and statistical model eval targets (rule `07-statistical-models-must-have-eval-targets`)
 - [agentme-edr-018](018-ai-llm-development-standards.md) — LLM development standards: LangChain framework and observability
 - [agentme-edr-019](019-ai-agents-development-standards.md) — Agent development standards
-- [agentme-edr-020](020-ai-workflow-development-standards.md) — Workflow development standards
+- [agentme-edr-021](021-ai-workflow-development-standards.md) — Workflow development standards
+
 - [agentme-edr-024](024-ml-dataset-structure.md) — ML dataset structure for eval datasets

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

@@ -32,9 +32,10 @@ Language and framework-specific tooling and project structure.
 - [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-llm-development-standards.md) - **AI LLM development standards** - Standard framework (LangChain) and patterns for simple LLM calls with explicit configuration (no environment variables)
-- [agentme-edr-019](application/019-ai-agents-development-standards.md) - **AI agents development standards** - Standard framework (deepagents) and patterns for agentic tool-invocation loops
-- [agentme-edr-020](application/020-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
-- [agentme-edr-021](application/021-ai-eval-standards.md) - **AI eval standards** - Folder structure, script requirements, and MLflow tracking for eval tests across LLM, Agent, and Workflow tiers
+- [agentme-edr-019](application/019-ai-agents-development-standards.md) - **AI agents development standards** - Structural patterns for agents: framework selection, sandbox setup, naming conventions, composition, and system prompt structure
+- [agentme-edr-020](application/020-ai-agents-quality-standards.md) - **AI agents implementation quality standards** - Tool definition patterns, error handling, observability, and unit testing for agents
+- [agentme-edr-021](application/021-ai-workflow-development-standards.md) - **AI workflow development standards** - Standard toolchain (LangGraph), evaluation, and testing patterns for workflow projects
+- [agentme-edr-028](application/028-ai-eval-standards.md) - **AI eval standards** - Folder structure, script requirements, and MLflow tracking for eval tests across LLM, Agent, and Workflow tiers
 - [agentme-edr-024](application/024-ml-dataset-structure.md) - **ML dataset structure** - Standard folder layout and file conventions for ML datasets
 - [agentme-edr-025](application/025-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-026](application/026-pragmatic-hexagonal-architecture.md) - **Pragmatic hexagonal architecture** - Organize application layers as External/Adapters/Application with practical coupling rules

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

@@ -244,7 +244,7 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 |---|---|---|---|
 | **LLM** ([agentme-edr-018](../application/018-ai-llm-development-standards.md)) | Not required | Not required; SHOULD be used when critical prompts are in use to measure accuracy and detect model drift | Not required |
 | **Agent** ([agentme-edr-019](../application/019-ai-agents-development-standards.md)) | Not required | Not required; MAY be used | Not required |
-| **Workflow** ([agentme-edr-020](../application/020-ai-workflow-development-standards.md)) | **Required** — see below | **Required** before every release; failed evals block release | Advised |
+| **Workflow** ([agentme-edr-021](../application/021-ai-workflow-development-standards.md)) | **Required** — see below | **Required** before every release; failed evals block release | Advised |
 
 **Workflow unit test requirements:**
 
@@ -260,4 +260,4 @@ AI projects are classified into three tiers — LLM, Agent, and Workflow — def
 - Evals MUST be executed before every release.
 - Accuracy below project-defined thresholds MUST block the release. Thresholds MUST be documented in the eval Makefile or README.
 - Evals MUST run against real LLM providers (not mocks) to capture model drift.
-- For eval folder structure and script requirements, see [agentme-edr-021](../application/021-ai-eval-standards.md).
+- For eval folder structure and script requirements, see [agentme-edr-028](../application/028-ai-eval-standards.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentme",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "",
   "dependencies": {
     "filedist": "^0.35.0"