[Phase 1.2] Schema Design & Validation (Days 3-5)

[mfittko]

🏗️ Schema Design & Validation (Days 3-5)

Component: Configuration System | Critical Path: Enables all configuration and validation
Parent Issue: #2 | Timeline: Days 3-5 of Phase 1

🎯 Objective

Design and implement comprehensive configuration schema system with Zod validation for agents, workflows, and tools.

📋 Tasks

2.1 Core Configuration Schema

• 2.1.1 Design AgentConfig schema with Zod validation

  • Agent name, instructions, model selection
  • Tool permissions and guardrails
  • Handoff configuration and routing rules
  • Memory and context management settings

• 2.1.2 Create WorkflowSettings schema for execution patterns

  • Entry point agent definition
  • Workflow patterns (handoff_chain, parallel, conditional)
  • Timeout and resource limits
  • Output format preferences

• 2.1.3 Define ToolConfig schema for different tool types

  • Built-in tools (file_ops, git, web_search)
  • MCP server tool configurations
  • Custom function tool definitions
  • Security permissions and access controls

2.2 Configuration Loading & Validation

• 2.2.1 Create ConfigLoader class with file format support

  • Support JSON and YAML configuration files
  • Handle include/import for modular configs
  • Environment variable substitution
  • Config file discovery and cascading

• 2.2.2 Implement detailed schema validation with user-friendly errors

  • Clear error messages with line numbers
  • Suggestions for common configuration mistakes
  • Validation warnings for potentially dangerous settings
  • Schema evolution and version compatibility

• 2.2.3 Add configuration merge support (defaults + user config)

  • Default configuration templates
  • User config overlay and inheritance
  • Environment-specific overrides
  • Validation of merged final configuration

• 2.2.4 Create validation CLI command

  • agents-cli validate --config <file> command
  • Detailed validation output with suggestions
  • Dry-run mode for testing configurations
  • Schema documentation generation

2.3 Example Configurations

• 2.3.1 Create comprehensive code review workflow example

  • Multi-agent handoff chain (reviewer → security → architect)
  • File access permissions and git tools
  • Structured output formatting for IDEs
  • Error handling and recovery patterns

• 2.3.2 Create architecture review workflow example

  • Single agent with comprehensive analysis tools
  • Directory traversal and pattern recognition
  • Documentation generation and recommendations
  • Integration with development workflows

• 2.3.3 Create minimal single-agent example

  • Simple "hello world" agent configuration
  • Basic tool usage demonstration
  • Clear documentation and comments
  • Testing and validation examples

• 2.3.4 Generate schema documentation from Zod definitions

  • Auto-generated JSON schema documentation
  • Configuration reference with examples
  • IDE integration (JSON schema for autocomplete)
  • Website documentation with interactive examples

✅ Definition of Done

• All configuration schemas defined with Zod
• ConfigLoader handles JSON/YAML with validation
• agents-cli validate command works with clear errors
• Example configurations validate and demonstrate features
• Schema documentation generated and accessible
• Configuration merging and defaults work correctly
• Environment variable substitution functional
• IDE autocomplete support via JSON schema

🔗 Dependencies

• Requires: Project Setup ([Phase 1.1] Project Setup & Infrastructure (Days 1-2) #3) completion
• Blocks: All workflow execution components

📚 References

• Zod Schema Validation
• JSON Schema Specification
• OpenAI Agents SDK Configuration Patterns

Note: This schema system is the foundation for all configuration-driven functionality.