feat: YAML anchors, aliases and templating support in docker-agent (DRY)

[leonavevor]

Overview

Add support for YAML anchors and aliases (per YAML 1.2.2 spec) to enable reusable configuration fragments within the same file or across multiple YAML files. This allows common blocks?such as system prompts, tool configurations, authentication parameters, and agent definitions to be defined once and referenced multiple times, following the DRY (Don't Repeat Yourself) principle.

Motivation

Currently, docker-agent config files often contain duplicated blocks of YAML, especially when multiple agents share common settings:

• Code duplication: System prompts, model parameters, tool definitions, and authentication configs are repeated across agents
• Maintenance burden: Updating a shared setting requires changes in multiple places, increasing the risk of inconsistency
• Scalability issues: As the number of agents grows, config files become harder to maintain and validate
• Lack of OOP principles: No inheritance or composition patterns for configuration reuse

Examples of current pain points:

• "I need to specify the same system prompt for 5 different agents, and now if I want to update it, I have to edit 5 places"
• "Currently, I have to work around this by manually copy-pasting large YAML blocks and hoping they stay in sync"
• "This is needed for large multi-agent deployments where consistency is critical"

Use Cases

1. Common System Prompts: Define a base system prompt once and reuse it across multiple agents with minor variations

   prompts:
     base_prompt: &base_prompt |
       You are a helpful assistant...
   
   agents:
     agent1:
       instructions: *base_prompt
     agent2:
       instructions: *base_prompt

2. Shared Tool Configurations: Define tool specs (Docker, Kubernetes, file system) once and reference them across agents

   tools:
     docker_config: &docker_config
       type: docker
       timeout: 30
       allowed_commands: [ps, run, stop]
   
   agents:
     devops_agent:
       tools:
         - *docker_config
     deployment_agent:
       tools:
         - *docker_config

3. Reusable Model/Provider Settings: Define model parameters once for consistency across agents

   defaults:
     model_config: &model_config
       model: openai/gpt-4
       temperature: 0.7
       max_tokens: 4096
   
   agents:
     code_reviewer:
       <<: *model_config
     documentation_writer:
       <<: *model_config

4. Cross-File Imports: Reference fragments from external YAML files to organize large configurations

   # main.yaml
   agents:
     - name: agent1
       config: !include ./configs/common-prompts.yaml#/base_prompt

5. Authentication/Credentials Reuse: Define credentials once and reuse across multiple agents/tools

   credentials:
     github_token: &github_token
       type: oauth
       provider: github
   
   agents:
     github_agent:
       auth: *github_token
     code_review_agent:
       auth: *github_token

Proposed Solution

Option 1: Native YAML Anchors & Aliases (Recommended)

• Leverage Go's built-in YAML parsing (via gopkg.in/yaml.v3) which already supports anchors and aliases
• Document anchor/alias syntax in the agent config schema and user guides
• Add validation to ensure circular references are prevented
• Update agent-schema.json to document anchor usage patterns

Option 2: Enhanced Templating Layer

• Implement a custom YAML preprocessor that:
  • Resolves !include directives to load external files
  • Supports !merge for deep merging of objects
  • Allows variable substitution: ${variable_name}
  • Processes templates before YAML parsing

Option 3: Hybrid Approach

• Use native YAML anchors for same-file reuse (simplest, no extra tooling)
• Add optional !include directive for cross-file references
• Support environment variable substitution for dynamic values

Implementation Details

For Option 1 (Recommended):

• Update config parser in pkg/config/latest to validate and document anchor usage
• Add examples to examples/ directory showing anchor patterns
• Document in config schema that circular anchor references will error
• No code changes needed?YAML library already handles anchors

For Option 3 (Enhanced):

• Add preprocessor in pkg/config/ to handle !include and variable substitution
• Update schema validation to support new directives
• Add CLI flag: --allow-external-includes for security

Alternatives

Current Workarounds:

1. Manual copy-paste: Users duplicate config blocks and manage them separately (error-prone)

Standard Solutions in Similar Tools:

• GitLab CI: Uses YAML anchors and aliases natively (see GitLab blog on reusable templates)
• Docker Compose: Supports YAML anchors and aliases natively

Related Issues

• Agent schema versioning: pkg/config/latest patterns
• Config validation and error messages
• Documentation for advanced config patterns

Additional Context

Benefits of YAML Anchors/Templating:

• ? DRY Principle: Single source of truth for shared configuration
• ? OOP Composition: Inherit/compose config blocks like classes
• ? Maintainability: Update once, changes apply everywhere
• ? Scalability: Easier to manage 10+ agents with shared settings
• ? Consistency: Ensures all agents using the same base config stay synchronized
• ? Standard Practice: Widely used in Kubernetes, GitLab CI, Docker Compose
• ? No Performance Impact: Preprocessing happens at load time, not runtime

References:

• YAML 1.2.2 Spec: https://yaml.org/spec/1.2.2/#3222-anchors-and-aliases
• Educational Resource: https://www.educative.io/blog/advanced-yaml-syntax-cheatsheet#YAML-Anchors-and-Alias
• GitLab CI Reusable Templates: https://about.gitlab.com/blog/how-to-build-reusable-ci-templates/

Example Use Case - Before & After:

BEFORE (with duplication):

agents:
  agent1:
    instructions: "You are a Kubernetes expert..."
    model: openai/gpt-4
    tools: [kubectl, docker]
  
  agent2:
    instructions: "You are a Kubernetes expert..."
    model: openai/gpt-4
    tools: [kubectl, docker]

AFTER (with anchors):

defaults:
  k8s_agent: &k8s_agent
    instructions: "You are a Kubernetes expert..."
    model: openai/gpt-4
    tools: [kubectl, docker]

agents:
  agent1:
    <<: *k8s_agent
  agent2:
    <<: *k8s_agent

---

Expanded Use Cases & Examples

1. System Prompts with Role-Based Variations

Problem: Multiple agents need similar core instructions but with role-specific variations.

prompts:
  base_system: &base_system |
    You are an expert AI assistant.
    - Always provide accurate, helpful responses
    - Ask for clarification when needed
    - Cite your sources
  
  code_persona: &code_persona |
    <<: *base_system
    You specialize in software development.
    - Follow best practices (SOLID, DRY, KISS)
    - Consider performance and security implications
  
  devops_persona: &devops_persona |
    <<: *base_system
    You specialize in infrastructure and DevOps.
    - Prioritize security, reliability, and scalability
    - Consider disaster recovery and monitoring

agents:
  code_reviewer:
    instructions: *code_persona
    model: openai/gpt-4
    
  devops_engineer:
    instructions: *devops_persona
    model: openai/gpt-4
    
  documentation_writer:
    instructions: *base_system
    model: openai/gpt-3.5-turbo