temp/docs/reference/actors_examples.md

# Actor YAML Examples

## Overview

This document provides comprehensive examples of actor YAML configurations, demonstrating various use cases and patterns. Each example is aligned with the CleverAgents specification and shows best practices for actor design.

**Related Documentation:**
- [Actor YAML Schema Reference](./actors_schema.md) - Complete schema documentation
- **Module:** `cleveragents.actor.schema`
- **Schema Version:** 1.0

---

## Table of Contents

1. [Simple LLM Actors](#simple-llm-actors)
2. [Strategist Actors](#strategist-actors)
3. [Executor Actors](#executor-actors)
4. [Reviewer Actors](#reviewer-actors)
5. [Estimation Actors](#estimation-actors)
6. [Tool-Only Actors](#tool-only-actors)
7. [Validation-Node Actors](#validation-node-actors)
8. [Graph Workflows](#graph-workflows)
9. [Hierarchical Actor Graphs](#hierarchical-actor-graphs)
10. [Strategy Actor with Subplan Spawning](#strategy-actor-with-subplan-spawning)

---

## Simple LLM Actors

### Minimal Code Reviewer

**File:** `examples/actors/simple_llm.yaml`

A basic LLM actor with system prompt, memory, and context configuration.

```yaml
name: assistants/code_reviewer
type: llm
description: Reviews Python code for best practices, style, and potential bugs
version: "1.0"

model: gpt-4
system_prompt: |
  You are an expert Python code reviewer. Review code for:
  - PEP 8 style compliance
  - Best practices and design patterns
  - Potential bugs and edge cases
  - Performance considerations
  - Security vulnerabilities

  Provide constructive feedback with specific suggestions for improvement.

context_view: reviewer
memory:
  enabled: true
  max_messages: 20
  max_tokens: 4000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
  include_dirs:
    - "src/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
  max_context_tokens: 8000
```

**Use Cases:**
- Code review assistants
- Documentation reviewers
- Simple conversational agents
- Single-purpose analysis tools

---

## Strategist Actors

### Planning & Decomposition Actor

**Purpose:** Breaks down high-level goals into actionable subplans.

```yaml
name: strategists/task_planner
type: llm
description: Analyzes requirements and creates detailed execution plans
version: "1.0"

model: gpt-4
system_prompt: |
  You are a strategic planning expert. Your role is to:

  1. Analyze the user's high-level goal
  2. Break it down into concrete, actionable steps
  3. Identify dependencies between steps
  4. Suggest parallel execution opportunities
  5. Estimate effort and risk for each step
  6. Recommend tools and resources needed

  Think carefully about edge cases and potential obstacles.
  Provide clear, specific instructions for each step.

context_view: strategist
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
    - "requirements.txt"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 32000

tools:
  - files/read_file
  - files/list_directory
  - git/get_status
```

**Key Features:**
- Large context window for complex planning
- Read-only tools for information gathering
- Strategist context view for high-level perspective
- Extended memory for multi-turn planning

**Use Cases:**
- Strategize phase of plan execution
- Project decomposition
- Task dependency analysis
- Multi-project coordination

---

## Executor Actors

### Implementation & Execution Actor

**Purpose:** Executes concrete tasks with write capabilities.

```yaml
name: executors/code_writer
type: llm
description: Implements code changes based on detailed specifications
version: "1.0"

model: gpt-4
system_prompt: |
  You are an expert software engineer. Your role is to:

  1. Read and understand the specification
  2. Implement clean, well-tested code
  3. Follow project conventions and style guides
  4. Write comprehensive docstrings and comments
  5. Consider edge cases and error handling

  Always verify your changes don't break existing tests.
  Write new tests for new functionality.

context_view: executor
memory:
  enabled: true
  max_messages: 30
  max_tokens: 8000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
    - "CONTRIBUTING.md"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 16000

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - git/add
  - testing/run_pytest
```

**Key Features:**
- Write-capable tools for code modification
- Executor context view for implementation focus
- Testing tools for verification
- Project-aware context filtering

**Use Cases:**
- Execute phase of plan execution
- Code implementation tasks
- File system operations
- Test-driven development

---

## Reviewer Actors

### Code Quality & Standards Reviewer

**Purpose:** Reviews changes for quality, standards compliance, and correctness.

```yaml
name: reviewers/quality_gate
type: llm
description: Reviews code changes for quality, standards, and correctness
version: "1.0"

model: gpt-4
system_prompt: |
  You are a senior code reviewer and quality expert. Review changes for:

  **Code Quality:**
  - Clean code principles
  - SOLID design patterns
  - DRY (Don't Repeat Yourself)
  - Proper error handling

  **Standards:**
  - Project coding standards
  - Documentation completeness
  - Type hints and static typing
  - Test coverage

  **Correctness:**
  - Logic errors
  - Edge cases
  - Race conditions
  - Security vulnerabilities

  Provide specific, actionable feedback with examples.

context_view: reviewer
memory:
  enabled: true
  max_messages: 40
  max_tokens: 12000

context:
  include_files:
    - "README.md"
    - "CONTRIBUTING.md"
    - "docs/coding_standards.md"
  include_dirs:
    - "src/"
    - "tests/"
    - "docs/"
  max_context_tokens: 24000

tools:
  - files/read_file
  - files/list_directory
  - git/diff
  - testing/run_pytest
  - linting/run_ruff
  - linting/run_pyright
```

**Key Features:**
- Read-only + linting tools
- Reviewer context view
- Large context for thorough review
- Access to coding standards

**Use Cases:**
- Apply phase review gate
- Pull request review
- Quality assurance
- Standards compliance checking

---

## Estimation Actors

### Structured Estimation Reporter

**File:** `examples/actors/estimator.yaml`

This actor is intended for the optional `estimation_actor` slot on actions. It uses
`context_view: strategist`, declares `role_hint: estimation`, and defines
`response_format` with an `EstimationReport` JSON-schema metadata object. Runtime
provider-level structured-output enforcement is planned in a future follow-up.

---

## LLM Actors with Tools

### Strategist with File Access

**File:** `examples/actors/llm_with_tools.yaml`

An LLM actor with tool access for strategic planning and analysis.

```yaml
name: strategists/task_planner
type: llm
description: Strategic planning and task decomposition
version: "1.0"

model: gpt-4
system_prompt: |
  You are a strategic planner. Break down complex goals into actionable steps.
  Use available tools to analyze the codebase and understand the context.

context_view: strategist

tools:
  - files/read_file
  - files/list_directory

memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000

context:
  include_files:
    - "README.md"
    - "pyproject.toml"
  include_dirs:
    - "src/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
  max_context_tokens: 16000
```

**Use Cases:**
- Strategic planners with file access
- Analysts needing codebase inspection
- Planning agents that need to read documentation

**Key Features:**
- Read-only file tools for safety
- Large memory buffer for complex planning
- Strategist context view

---

## Tool-Only Actors

### File Operations Toolkit

**File:** `examples/actors/tool_collection.yaml`

**Purpose:** Provides a reusable collection of file operation tools without LLM interaction.

```yaml
name: utilities/file_ops
type: tool
description: Collection of file system operation tools
version: "1.0"

tools:
  - files/read_file
  - files/write_file
  - files/create_directory
  - files/delete_file
  - files/move_file
  - files/copy_file
  - files/list_directory
```

**Key Features:**
- No LLM required
- Pure tool collection
- Reusable across multiple actors
- Minimal configuration

**Use Cases:**
- Shared tool libraries
- Utility tool bundles
- Tool composition in graph actors
- Testing tool collections

### Git Operations Toolkit

```yaml
name: utilities/git_ops
type: tool
description: Collection of Git operation tools
version: "1.0"

tools:
  - git/status
  - git/add
  - git/commit
  - git/diff
  - git/log
  - git/branch
```

---

## Validation-Node Actors

### Validation & Linting Actor

**Purpose:** Runs validation checks without modifying code.

```yaml
name: validators/python_checker
type: llm
description: Validates Python code for correctness and style
version: "1.0"

model: gpt-4
system_prompt: |
  You are a validation expert. Your role is to:

  1. Run all configured validators and linters
  2. Analyze the results
  3. Categorize issues by severity
  4. Provide clear explanations of each issue
  5. Suggest specific fixes

  Focus on actionable feedback. Explain WHY something is an issue.

context_view: reviewer
memory:
  enabled: false

context:
  include_files:
    - "pyproject.toml"
    - "ruff.toml"
  include_dirs:
    - "src/"
  max_context_tokens: 8000

tools:
  - files/read_file
  - linting/run_ruff
  - linting/run_pyright
  - testing/run_pytest
  - security/run_bandit
```

**Key Features:**
- Read-only + validation tools
- No memory (stateless validation)
- Reviewer context view
- Security scanning included

**Use Cases:**
- Apply phase validation gate
- Pre-commit validation
- CI/CD quality checks
- Security scanning

---

## Graph Workflows

### Linear Graph: Three-Step Review

**File:** `examples/actors/simple_graph.yaml`

**Purpose:** Simple linear workflow with three sequential steps.

```yaml
name: workflows/simple_review
type: graph
description: Linear workflow for code review in three steps
version: "1.0"

model: gpt-4

route:
  nodes:
    - id: analyzer
      type: agent
      name: Code Analyzer
      description: Analyzes code structure and patterns
      config:
        model: gpt-4
        prompt: "Analyze the code structure and identify patterns"
        tools:
          - files/read_file
          - files/list_directory

    - id: reviewer
      type: agent
      name: Code Reviewer
      description: Reviews code for quality issues
      config:
        model: gpt-4
        prompt: "Review code for quality, style, and best practices"
        tools:
          - files/read_file

    - id: reporter
      type: agent
      name: Report Generator
      description: Generates summary report
      config:
        model: gpt-4
        prompt: "Generate a comprehensive review report"
        tools:
          - files/write_file

  edges:
    - from_node: analyzer
      to_node: reviewer
    - from_node: reviewer
      to_node: reporter

  entry_node: analyzer
  exit_nodes:
    - reporter

context_view: reviewer
memory:
  enabled: true
  max_messages: 50
  max_tokens: 16000
```

**Key Features:**
- Linear execution flow
- Three sequential agent nodes
- Single entry and exit point
- Shared context and memory

**Use Cases:**
- Simple multi-step workflows
- Pipeline processing
- Sequential analysis tasks

---

### Complex Graph: Test-Driven Development

**File:** `examples/actors/graph_workflow.yaml`

**Purpose:** Complex workflow with conditional routing, retry logic, and subgraphs.

```yaml
name: workflows/test_driven_dev
type: graph
description: Test-driven development workflow with automated testing and feedback loops
version: "1.0"

model: gpt-4

route:
  nodes:
    # Entry: Planning
    - id: planner
      type: agent
      name: Test Planner
      description: Plans test cases based on requirements
      config:
        model: gpt-4
        prompt: |
          You are a test planning expert. Analyze the requirements and create
          a comprehensive test plan covering unit tests, integration tests,
          and edge cases.
        tools:
          - files/read_file
          - files/list_directory

    # Write tests first
    - id: test_writer
      type: agent
      name: Test Writer
      description: Writes test cases based on the plan
      config:
        model: gpt-4
        prompt: |
          You are a test writing expert. Write pytest tests based on the plan.
          Follow best practices: descriptive names, docstrings, fixtures,
          and test one thing per test.
        tools:
          - files/write_file
          - files/read_file

    # Run the tests (should fail initially)
    - id: run_tests
      type: tool
      name: Test Runner
      description: Executes pytest test suite
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    # Check test results - CONDITIONAL
    - id: check_results
      type: conditional
      name: Test Result Checker
      description: Routes based on test pass/fail status
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False"
            route_to: implementation_writer

    # Write implementation to make tests pass
    - id: implementation_writer
      type: agent
      name: Implementation Writer
      description: Writes code to make the tests pass
      config:
        model: gpt-4
        prompt: |
          You are an implementation expert. Write clean, well-documented code
          that makes the failing tests pass. Follow SOLID principles.
        tools:
          - files/write_file
          - files/read_file

    # Run tests again after implementation
    - id: rerun_tests
      type: tool
      name: Test Rerunner
      description: Re-executes tests after implementation
      config:
        tool_name: testing/run_pytest
        parameters:
          verbose: true
          coverage: true

    # Verify tests pass - CONDITIONAL with RETRY
    - id: verify_tests
      type: conditional
      name: Test Verification
      description: Verify tests pass after implementation
      config:
        conditions:
          - check: "state.get('tests_passed') == True"
            route_to: code_review
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) < 3"
            route_to: debug_failures
          - check: "state.get('tests_passed') == False and state.get('retry_count', 0) >= 3"
            route_to: escalate

    # Debug test failures
    - id: debug_failures
      type: agent
      name: Debugger
      description: Analyzes and fixes test failures
      config:
        model: gpt-4
        prompt: |
          You are a debugging expert. Analyze the test failures and fix the
          implementation. Look for logic errors, edge cases, type mismatches,
          and missing error handling.
        tools:
          - files/read_file
          - files/write_file

    # Code review (subgraph)
    - id: code_review
      type: subgraph
      name: Code Reviewer
      description: Runs code review workflow
      config:
        actor_path: examples/actors/simple_llm.yaml

    # Escalate if tests keep failing
    - id: escalate
      type: tool
      name: Escalation Handler
      description: Escalates persistent failures to human
      config:
        tool_name: notifications/send_alert
        parameters:
          channel: engineering
          priority: high

  edges:
    - from_node: planner
      to_node: test_writer
    - from_node: test_writer
      to_node: run_tests
    - from_node: run_tests
      to_node: check_results
    - from_node: implementation_writer
      to_node: rerun_tests
    - from_node: rerun_tests
      to_node: verify_tests
    - from_node: debug_failures
      to_node: rerun_tests

  entry_node: planner
  exit_nodes:
    - code_review
    - escalate

context_view: strategist
memory:
  enabled: true
  max_messages: 100
  max_tokens: 16000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "requirements.txt"
    - "pyproject.toml"
  include_dirs:
    - "src/"
    - "tests/"
  exclude_patterns:
    - "**/__pycache__/**"
    - "*.pyc"
    - "**/.pytest_cache/**"
    - "**/htmlcov/**"
  max_context_tokens: 32000

env_vars:
  PYTEST_ARGS: --verbose --cov --cov-report=html
  MAX_RETRIES: "3"
```

**Key Features:**
- **Conditional routing** based on test results
- **Retry logic** with configurable max attempts
- **Subgraph invocation** for code review
- **Escalation path** for persistent failures
- **Tool nodes** for test execution
- **Agent nodes** for planning, writing, debugging
- **Multiple exit points** (success or escalation)

**Use Cases:**
- Test-driven development workflows
- Multi-stage validation pipelines
- Workflows with retry and error handling
- Complex agentic loops

---

## Hierarchical Actor Graphs

### Graph with Subgraph: Multi-Level Planning

**Purpose:** Demonstrates hierarchical composition with nested subgraphs.

```yaml
name: workflows/hierarchical_planner
type: graph
description: Multi-level planning with strategic and tactical subgraphs
version: "1.0"

model: gpt-4

route:
  nodes:
    # Top-level strategic planner
    - id: strategic_planner
      type: agent
      name: Strategic Planner
      description: High-level goal decomposition
      config:
        model: gpt-4
        prompt: |
          You are a strategic planner. Break down the high-level goal into
          major phases. For each phase, define success criteria and
          dependencies.
        tools:
          - files/read_file

    # Tactical planning subgraph
    - id: tactical_planning
      type: subgraph
      name: Tactical Planner
      description: Detailed task planning for each phase
      config:
        actor_path: examples/actors/tactial_planner.yaml
        context_override:
          context_view: strategist
          max_context_tokens: 16000

    # Parallel execution coordinator
    - id: execution_coordinator
      type: agent
      name: Execution Coordinator
      description: Coordinates parallel task execution
      config:
        model: gpt-4
        prompt: |
          You are an execution coordinator. Identify which tasks can run
          in parallel and which have dependencies. Create execution plan.
        tools:
          - files/read_file

    # Task execution subgraph (invoked multiple times)
    - id: task_executor
      type: subgraph
      name: Task Executor
      description: Executes individual tasks
      config:
        actor_path: examples/actors/task_executor.yaml
        parallel: true
        max_parallel: 3

    # Results aggregation
    - id: results_aggregator
      type: agent
      name: Results Aggregator
      description: Collects and summarizes results
      config:
        model: gpt-4
        prompt: |
          Aggregate results from all task executions. Identify successes,
          failures, and any issues that need attention.
        tools:
          - files/read_file
          - files/write_file

    # Quality review subgraph
    - id: quality_review
      type: subgraph
      name: Quality Reviewer
      description: Comprehensive quality review
      config:
        actor_path: examples/actors/quality_reviewer.yaml

  edges:
    - from_node: strategic_planner
      to_node: tactical_planning
    - from_node: tactical_planning
      to_node: execution_coordinator
    - from_node: execution_coordinator
      to_node: task_executor
    - from_node: task_executor
      to_node: results_aggregator
    - from_node: results_aggregator
      to_node: quality_review

  entry_node: strategic_planner
  exit_nodes:
    - quality_review

context_view: strategist
memory:
  enabled: true
  max_messages: 200
  max_tokens: 32000
  summarize_old: true

context:
  include_files:
    - "README.md"
    - "ARCHITECTURE.md"
  include_dirs:
    - "src/"
    - "docs/"
    - "tests/"
  max_context_tokens: 64000
```

**Key Features:**
- **Three levels of hierarchy**: Strategic → Tactical → Execution
- **Subgraph composition**: Each level invokes specialized subgraphs
- **Parallel execution**: Task executor runs multiple tasks concurrently
- **Context override**: Each subgraph can customize context settings
- **Large context window**: Supports complex multi-level planning

**Use Cases:**
- Large-scale project planning
- Multi-team coordination
- Complex system refactoring
- Hierarchical decomposition tasks

---

### Multi-Level Planner/Executor Graph

**Purpose:** Separate planning and execution phases with feedback loops.

```yaml
name: workflows/planner_executor_loop
type: graph
description: Iterative planning and execution with feedback
version: "1.0"

model: gpt-4

route:
  nodes:
    # Phase 1: Planning
    - id: requirements_analyzer
      type: agent
      name: Requirements Analyzer
      description: Analyzes and clarifies requirements
      config:
        model: gpt-4
        prompt: "Analyze requirements and identify ambiguities"
        tools:
          - files/read_file

    - id: plan_generator
      type: subgraph
      name: Plan Generator
      description: Generates detailed execution plan
      config:
        actor_path: examples/actors/strategists/task_planner.yaml

    # Phase 2: Execution
    - id: executor_pool
      type: subgraph
      name: Executor Pool
      description: Parallel task execution
      config:
        actor_path: examples/actors/executors/code_writer.yaml
        parallel: true
        max_parallel: 5

    # Phase 3: Validation
    - id: validator
      type: subgraph
      name: Validator
      description: Validates execution results
      config:
        actor_path: examples/actors/validators/python_checker.yaml

    # Phase 4: Decision Point - CONDITIONAL
    - id: validation_check
      type: conditional
      name: Validation Check
      description: Decides next action based on validation
      config:
        conditions:
          - check: "state.get('validation_passed') == True"
            route_to: final_review
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) < 3"
            route_to: issue_analyzer
          - check: "state.get('validation_passed') == False and state.get('iteration', 0) >= 3"
            route_to: escalate_to_human

    # Feedback Loop: Analyze Issues
    - id: issue_analyzer
      type: agent
      name: Issue Analyzer
      description: Analyzes validation failures
      config:
        model: gpt-4
        prompt: "Analyze validation failures and suggest fixes"
        tools:
          - files/read_file

    # Feedback Loop: Replanning
    - id: replanner
      type: subgraph
      name: Replanner
      description: Creates corrective plan
      config:
        actor_path: examples/actors/strategists/task_planner.yaml
        context_override:
          additional_context: "Previous execution failed. Focus on issues."

    # Final Review
    - id: final_review
      type: subgraph
      name: Final Reviewer
      description: Comprehensive final review
      config:
        actor_path: examples/actors/reviewers/quality_gate.yaml

    # Escalation
    - id: escalate_to_human
      type: tool
      name: Human Escalation
      description: Escalates to human intervention
      config:
        tool_name: notifications/send_alert
        parameters:
          priority: high

  edges:
    # Planning phase
    - from_node: requirements_analyzer
      to_node: plan_generator

    # Execution phase
    - from_node: plan_generator
      to_node: executor_pool

    # Validation phase
    - from_node: executor_pool
      to_node: validator
    - from_node: validator
      to_node: validation_check

    # Feedback loop
    - from_node: issue_analyzer
      to_node: replanner
    - from_node: replanner
      to_node: executor_pool  # Back to execution

  entry_node: requirements_analyzer
  exit_nodes:
    - final_review
    - escalate_to_human

context_view: strategist
memory:
  enabled: true
  max_messages: 150
  max_tokens: 24000
  summarize_old: true
```

**Key Features:**
- **Multi-phase workflow**: Requirements → Plan → Execute → Validate → Review
- **Feedback loop**: Failed validation triggers replanning and re-execution
- **Iteration limiting**: Maximum 3 attempts before human escalation
- **Parallel execution**: Multiple executors run concurrently
- **Context preservation**: Memory carries through iterations

**Use Cases:**
- Iterative development workflows
- Self-correcting automation
- Quality-gated deployment pipelines
- Complex refactoring with validation

---

---

## Strategy Actor with Subplan Spawning

### Strategist Using `builtin/plan-subplan`

**File:** `examples/actors/strategy_with_subplan.yaml`

**Purpose:** Demonstrates a strategy actor that emits `SUBPLAN_SPAWN` or
`SUBPLAN_PARALLEL_SPAWN` decisions using the built-in `builtin/plan-subplan` tool.

```yaml
name: strategists/subplan_coordinator
type: llm
description: Strategy actor that decomposes goals into child subplans
version: "1.0"

model: gpt-4
context_view: strategist

tools:
  - builtin/plan-subplan
```

**Key Features:**

- Uses `builtin/plan-subplan` to emit typed subplan decisions
- Supports serial (`SUBPLAN_SPAWN`) and parallel (`SUBPLAN_PARALLEL_SPAWN`) spawning
- Optional `DecisionService` injection for persistent decision recording
- `merge_strategy`, `max_parallel`, `dependencies`, and `context_view` are all
  configurable per spawn call

**Use Cases:**

- Decomposing large plans into independently executable child plans
- Coordinating parallel workstreams with dependency tracking
- Recording auditable decision trees for plan explain output

---

## Best Practices

### Naming Conventions

✅ **Good:**
- `assistants/code_reviewer`
- `strategists/task_planner`
- `executors/code_writer`
- `workflows/test_driven_dev`

❌ **Bad:**
- `CodeReviewer` (not namespaced)
- `assistant-1` (not descriptive)
- `my_actor` (ambiguous namespace)

### Context Configuration

- **Strategist actors**: Large context (32k-64k tokens), broad file access
- **Executor actors**: Medium context (16k tokens), focused on implementation
- **Reviewer actors**: Medium-large context (24k tokens), access to standards
- **Validation actors**: Small context (8k tokens), focused on specific checks

### Memory Settings

- **Simple tasks**: Disable memory or use small buffer (10-20 messages)
- **Planning tasks**: Large memory (50-100 messages) with summarization
- **Execution tasks**: Medium memory (20-40 messages)
- **Stateless validators**: Disable memory

### Tool Selection

- **Read-only actors**: Only query tools (read, list, diff, status)
- **Write actors**: Full tool access (read, write, create, delete)
- **Validators**: Read + linting/testing tools only

---

## Testing Your Actors

All example actors in `examples/actors/` are validated through automated tests:

1. **Schema Validation** (`features/actor_schema.feature`)
   - Ensures YAML structure is valid
   - Validates required fields present
   - Checks namespaced names format

2. **Loading Tests** (`robot/actor_schema.robot`)
   - Loads each example file
   - Verifies parsing succeeds
   - Checks expected fields

3. **Integration Tests**
   - Tests actor invocation
   - Validates tool execution
   - Checks context assembly

Run tests with:
```bash
nox -s unit_tests        # Behave tests
nox -s integration_tests # Robot tests
```

---

## Related Documentation

- [Actor YAML Schema Reference](./actors_schema.md) - Complete schema specification
- [Skill Registry](./skill_registry.md) - Skills used by actors
- [Tool Router](./tool_router.md) - Tools available to actors
- Specification: Actor section (lines 8800+)

---

**Last Updated:** 2026-02-18  
**Schema Version:** 1.0