agentic 0.1.0 → 0.2.0

data/.architecture/principles.md

@@ -0,0 +1,151 @@
+# Architectural Principles for Agentic
+
+## Core Principles
+
+### 1. Domain Agnostic Design
+- **Principle**: The framework should not be tied to any specific domain or use case
+- **Application**: All domain-specific logic must be externalized through adapters and plugins
+- **Validation**: New features should work across multiple domains without modification
+
+### 2. Progressive Automation
+- **Principle**: Start with human oversight and gradually automate based on confidence and learning
+- **Application**: All automated decisions should have configurable confidence thresholds
+- **Validation**: Human intervention points should be clearly defined and measurable
+
+### 3. Extensibility Through Interfaces
+- **Principle**: All extension points must be interface-based with clear contracts
+- **Application**: Use composition over inheritance, dependency injection, and plugin patterns
+- **Validation**: Extensions should not require modifying core framework code
+
+### 4. Observable and Debuggable
+- **Principle**: All system behavior should be observable, traceable, and debuggable
+- **Application**: Comprehensive logging, metrics, and state introspection capabilities
+- **Validation**: Any system state or decision should be explainable through tooling
+
+### 5. Fault Tolerance and Graceful Degradation
+- **Principle**: System should handle failures gracefully and provide meaningful recovery
+- **Application**: Retry policies, circuit breakers, fallback strategies, and detailed error context
+- **Validation**: System should continue operating with reduced functionality when components fail
+
+### 6. Performance and Resource Consciousness
+- **Principle**: Efficient use of computational resources and LLM API costs
+- **Application**: Caching, connection pooling, request batching, and resource monitoring
+- **Validation**: Performance impact should be measurable and within acceptable thresholds
+
+### 7. Security by Design
+- **Principle**: Security considerations integrated throughout the architecture, not added afterwards
+- **Application**: Content filtering, permission models, audit logging, and secure defaults
+- **Validation**: Security implications should be evaluated for all architectural decisions
+
+### 8. Learning and Adaptation
+- **Principle**: System should improve over time through execution history and feedback
+- **Application**: Execution history capture, pattern recognition, and strategy optimization
+- **Validation**: Demonstrable improvement in performance metrics over time
+
+## Design Patterns and Practices
+
+### Registry Pattern
+- Used for: Agent capabilities, plugins, verification strategies
+- Enables: Dynamic discovery, version management, dependency resolution
+- Implementation: Thread-safe singletons with clear lifecycle management
+
+### Observer Pattern
+- Used for: Task state changes, execution monitoring, event notifications
+- Enables: Loose coupling between components, extensible monitoring
+- Implementation: Thread-safe notification with error isolation
+
+### Strategy Pattern
+- Used for: Verification approaches, composition strategies, adaptation methods
+- Enables: Pluggable behavior, A/B testing, progressive enhancement
+- Implementation: Interface-based with factory registration
+
+### Factory Pattern
+- Used for: Agent construction, task creation, component instantiation
+- Enables: Complex object creation, dependency injection, configuration management
+- Implementation: Builder pattern with fluent interfaces
+
+### Extension Pattern
+- Used for: Domain adapters, plugins, protocol handlers
+- Enables: Third-party extensions, domain specialization, protocol adaptation
+- Implementation: Interface contracts with validation and lifecycle management
+
+## Quality Attributes
+
+### Maintainability
+- **Requirement**: Code should be easy to understand, modify, and extend
+- **Implementation**: Clear separation of concerns, comprehensive documentation, consistent patterns
+- **Measurement**: Code complexity metrics, documentation coverage, contributor onboarding time
+
+### Reliability
+- **Requirement**: System should behave predictably and handle errors gracefully
+- **Implementation**: Comprehensive testing, error handling, retry mechanisms, fallback strategies
+- **Measurement**: Error rates, recovery success rates, system uptime
+
+### Performance
+- **Requirement**: Efficient resource utilization and responsive execution
+- **Implementation**: Caching, pooling, batching, lazy loading, performance monitoring
+- **Measurement**: Response times, resource usage, throughput metrics
+
+### Security
+- **Requirement**: Protect against malicious inputs and unauthorized access
+- **Implementation**: Input validation, content filtering, permission models, audit logging
+- **Measurement**: Security scan results, penetration testing, audit trail completeness
+
+### Scalability
+- **Requirement**: Handle increasing loads and complexity gracefully
+- **Implementation**: Async execution, resource pooling, modular architecture, performance optimization
+- **Measurement**: Load testing results, resource utilization curves, response time degradation
+
+### Usability
+- **Requirement**: Easy for developers to understand, use, and debug
+- **Implementation**: Clear APIs, comprehensive documentation, good error messages, debugging tools
+- **Measurement**: Developer onboarding time, API adoption rates, support request volume
+
+## Architectural Constraints
+
+### Technical Constraints
+- **Ruby Language**: Must follow Ruby idioms and conventions
+- **Gem Packaging**: Standard Ruby gem structure and distribution
+- **Threading**: Thread-safe implementations where required
+- **Dependencies**: Minimal external dependencies, well-justified additions
+
+### Operational Constraints
+- **LLM API Usage**: Efficient use of external LLM services
+- **Resource Limits**: Reasonable memory and CPU usage
+- **Configuration**: Environment-based configuration without code changes
+- **Logging**: Structured logging compatible with common tools
+
+### Business Constraints
+- **Open Source**: MIT license compatibility
+- **Community**: Developer-friendly APIs and documentation
+- **Maintenance**: Sustainable codebase for long-term maintenance
+- **Adoption**: Easy integration into existing Ruby applications
+
+## Decision-Making Framework
+
+### Architectural Decision Criteria
+1. **Alignment with Core Principles**: Does the decision support our architectural principles?
+2. **Quality Attribute Impact**: How does it affect maintainability, reliability, performance, security?
+3. **Extensibility Impact**: Does it enhance or constrain future extensibility?
+4. **Implementation Complexity**: Is the complexity justified by the benefits?
+5. **Community Impact**: How does it affect the developer experience?
+
+### Review Process
+1. **Individual Review**: Each member reviews against their expertise area
+2. **Cross-Perspective Analysis**: Identify conflicts and trade-offs
+3. **Consensus Building**: Reach agreement on balanced recommendations
+4. **Documentation**: Capture decisions, rationale, and consequences
+5. **Validation**: Define success criteria and monitoring approach
+
+### Change Management
+1. **Impact Assessment**: Evaluate breaking changes and migration requirements
+2. **Phased Implementation**: Break large changes into manageable phases
+3. **Backward Compatibility**: Maintain compatibility where possible
+4. **Migration Support**: Provide tools and documentation for transitions
+5. **Communication**: Clear communication of changes and timelines
+
+## Conclusion
+
+These principles guide all architectural decisions in the Agentic framework. They ensure that the system remains maintainable, extensible, and valuable to the Ruby community while fulfilling its mission as a domain-agnostic AI agent orchestration platform.
+
+All architectural changes should be evaluated against these principles, and any conflicts should be explicitly documented and justified in the relevant ADR.

data/.architecture/recalibration/0-2-0.md

@@ -0,0 +1,92 @@
+# Architectural Recalibration Plan: Version 0.2.0
+
+## Overview
+
+This document outlines the action plan derived from the architectural review of version 0.2.0. It categorizes and prioritizes recommendations to guide implementation across upcoming releases.
+
+## Review Summary
+
+- Review Date: 2025-05-21
+- Review Document: [.architecture/reviews/0-2-0.md](../.architecture/reviews/0-2-0.md)
+- Participants: Alex Rivera (Systems Architect), Jamie Chen (Domain Expert), Morgan Taylor (Security Specialist), Sam Rodriguez (Maintainability Expert), Jordan Lee (Performance Specialist), Taylor Kim (AI Engineer)
+
+## Action Items
+
+### Architectural Changes
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| A1 | Extract dependency management from PlanOrchestrator into a dedicated DependencyGraph class | High | TBD | 0.3.0 | None | Core architectural improvement for cleaner separation of concerns |
+| A2 | Create clear boundaries between planning, execution, and learning subsystems | High | TBD | 0.3.0 | None | Introduces proper interfaces between major subsystems |
+| A3 | Implement domain event system for component communication | Medium | TBD | 0.3.0 | None | Enables looser coupling between components |
+| A4 | Design and implement multi-agent orchestration patterns | Medium | TBD | 0.4.0 | A1 | Enables complex agent interactions and communications |
+| A5 | Create service registry for dynamic discovery | Low | TBD | 0.5.0 | None | Improves service location and discoverability |
+
+### Implementation Improvements
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| I1 | Implement content safety filtering for inputs and outputs | High | TBD | 0.3.0 | None | Critical security enhancement |
+| I2 | Add permission model for controlling agent capabilities | High | TBD | 0.3.0 | None | Improves security posture |
+| I3 | Implement response caching for LLM interactions | Medium | TBD | 0.3.0 | None | Performance optimization |
+| I4 | Add connection pooling for API clients | Medium | TBD | 0.3.0 | None | Performance optimization |
+| I5 | Implement request batching for compatible operations | Medium | TBD | 0.4.0 | I3, I4 | Advanced performance optimization |
+| I6 | Create comprehensive evaluation framework | High | TBD | 0.3.0 | None | Enables measurement of agent performance |
+| I7 | Implement observability infrastructure | High | TBD | 0.3.0 | None | Critical for production-ready systems |
+
+### Documentation Enhancements
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| D1 | Create comprehensive quick-start guides and examples | High | TBD | 0.2.1 | None | Improves developer experience and onboarding |
+| D2 | Enhance interface documentation with usage examples | Medium | TBD | 0.2.1 | None | Improves developer experience |
+| D3 | Create MAINTAINING.md with architectural guidance | Medium | TBD | 0.2.1 | None | Helps new contributors understand architecture |
+| D4 | Document complex agent orchestration patterns | Medium | TBD | 0.4.0 | A4 | Documents multi-agent capabilities |
+
+### Process Adjustments
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| P1 | Standardize testing patterns across all components | Medium | TBD | 0.3.0 | None | Improves consistency and maintainability |
+| P2 | Establish process for tracking architectural metric improvements | Medium | TBD | 0.3.0 | None | Enables data-driven architectural decisions |
+
+## Technical Debt Items
+
+Items identified in the review that won't be addressed immediately but should be tracked:
+
+| ID | Description | Impact | Potential Resolution Timeframe |
+|----|-------------|--------|--------------------------------|
+| TD1 | Large method complexity in PlanOrchestrator | Medium | 0.4.0 |
+| TD2 | Inconsistent testing approach across modules | Medium | 0.3.0 |
+| TD3 | External dependencies not properly isolated | Low | 0.5.0 |
+
+## Decision Records
+
+List of Architectural Decision Records (ADRs) that need to be created or updated based on the review:
+
+| ADR ID | Title | Status | Owner | Target Completion |
+|--------|-------|--------|-------|-------------------|
+| ADR-001 | Dependency Management for Tasks | Draft | TBD | 2025-06-15 |
+| ADR-002 | Implementation of System Boundaries | Draft | TBD | 2025-06-15 |
+| ADR-003 | Content Safety Filtering Approach | Draft | TBD | 2025-06-15 |
+| ADR-004 | Agent Permission Model | Draft | TBD | 2025-06-15 |
+| ADR-005 | Evaluation Framework Design | Draft | TBD | 2025-06-15 |
+| ADR-006 | Observability Infrastructure | Draft | TBD | 2025-06-15 |
+
+## Timeline
+
+Overview of the recalibration implementation timeline:
+
+- Analysis & Prioritization: 2025-05-22 - 2025-05-29
+- Architectural Plan Update: 2025-05-30 - 2025-06-12
+- Documentation Refresh: 2025-06-13 - 2025-06-19
+- Implementation Roadmapping: 2025-06-20 - 2025-06-30
+
+## Next Steps
+
+Immediate next actions to be taken:
+
+1. Assign owners to each action item
+2. Schedule kickoff meeting for architectural plan updates
+3. Begin drafting ADRs for high-priority architectural changes
+4. Create implementation tasks for documentation enhancements (D1-D3) for immediate release

data/.architecture/recalibration/agent_self_assembly.md

@@ -0,0 +1,238 @@
+# Agent Self-Assembly Recalibration
+
+## Overview
+
+This document outlines the architectural recalibration plan following the review of the agent self-assembly system implemented in version 0.2.0. The recalibration process addresses findings from the architectural review and establishes a roadmap for refinement and enhancement.
+
+## Review Analysis & Prioritization
+
+### Key Strengths to Leverage
+
+1. **Modular Design**
+   - Clean separation of concerns between components
+   - Well-defined interfaces for component interactions
+   - Extensible architecture with pluggable strategies
+
+2. **Pattern Application**
+   - Effective use of Factory, Strategy, and Repository patterns
+   - Consistent application of design principles
+   - Composition-based approach to capability management
+
+3. **Learning System Integration**
+   - Strong connection with existing learning components
+   - Performance-based optimization capabilities
+   - Feedback loop for continuous improvement
+
+### Areas for Improvement
+
+#### High Priority
+
+1. **Method Decomposition**
+   - Large methods in `AgentAssemblyEngine` need refactoring
+   - `analyze_requirements` and related methods should be simplified
+   - Capability inference logic could be extracted and enhanced
+
+2. **Documentation Gaps**
+   - Formal ADRs for all components were missing
+   - API documentation for key interfaces could be improved
+   - Examples for advanced usage scenarios are limited
+
+3. **Test Coverage**
+   - More comprehensive integration tests needed
+   - Edge case coverage should be expanded
+   - Performance benchmarks are lacking
+
+#### Medium Priority
+
+1. **Registry Pattern Refinement**
+   - Consider alternatives to global singleton
+   - Improve thread safety for concurrent access
+   - Add registry partitioning for scalability
+
+2. **Storage Limitations**
+   - File-based storage has inherent limitations
+   - Lack of transactional support
+   - Limited scalability for many agents
+
+3. **Capability Inference**
+   - Basic pattern matching is limited
+   - No contextual understanding of requirements
+   - Missing support for domain-specific inference
+
+#### Low Priority
+
+1. **Advanced Composition**
+   - Limited support for composition constraints
+   - No formal validation of composed capabilities
+   - Missing optimization of composition chains
+
+2. **Governance**
+   - No capability approval workflows
+   - Limited controls on capability creation
+   - No usage tracking for governance
+
+## Architectural Plan Updates
+
+### Immediate Refinements (0.2.1)
+
+1. **Method Refactoring**
+   - Extract helper methods from large methods in `AgentAssemblyEngine`
+   - Create dedicated classes for requirement analysis and inference
+   - Improve naming consistency across components
+
+2. **Documentation Enhancements**
+   - Complete ADRs for all components
+   - Add comprehensive API documentation
+   - Create tutorials for common usage patterns
+
+3. **Test Improvements**
+   - Add integration tests for complex workflows
+   - Improve edge case coverage
+   - Add performance benchmarks
+
+### Near-term Enhancements (0.3.0)
+
+1. **Registry Improvements**
+   - Add registry event system for change notifications
+   - Improve concurrency handling
+   - Consider namespace support for capabilities
+
+2. **Storage Enhancements**
+   - Design database-backed storage adapter
+   - Implement improved filtering and querying
+   - Add transaction support for critical operations
+
+3. **Capability Inference Enhancement**
+   - Implement more sophisticated pattern recognition
+   - Add context-aware capability selection
+   - Support for domain-specific inference rules
+
+### Long-term Vision (1.0+)
+
+1. **Advanced Composition**
+   - Formal composition validation framework
+   - Constraint-based composition engine
+   - Automated composition optimization
+
+2. **Governance Framework**
+   - Capability approval workflows
+   - Usage analytics and reporting
+   - Access control and permissions
+
+3. **Multi-environment Support**
+   - Distributed registry architecture
+   - Cloud-based agent storage
+   - Cross-environment capability sharing
+
+## Documentation Refresh
+
+### Updated Documentation
+
+1. **New ADRs**
+   - ADR-014: Agent Capability Registry
+   - ADR-015: Persistent Agent Store
+   - ADR-016: Agent Assembly Engine
+
+2. **Clarification Documents**
+   - Capability and Tools Distinction
+   - Agent Self-Assembly Implementation Summary
+
+3. **API Documentation**
+   - Enhanced documentation for all public interfaces
+   - Clear examples for common operations
+   - Guidance on extending the system
+
+### Documentation Gaps to Address
+
+1. **Advanced Usage Examples**
+   - Custom composition strategy implementation
+   - Complex capability composition patterns
+   - Integration with external systems
+
+2. **Architectural Guidance**
+   - Best practices for capability design
+   - Scaling guidelines for large deployments
+   - Performance optimization recommendations
+
+3. **Migration Guidelines**
+   - Transitioning from tools to capabilities
+   - Upgrading existing agents to use the assembly system
+   - Migrating between storage implementations
+
+## Implementation Roadmap
+
+### 0.2.1 (Next Release)
+
+1. **Refactoring**
+   - Extract smaller methods from `AgentAssemblyEngine`
+   - Create `RequirementAnalyzer` class
+   - Improve naming consistency
+
+2. **Documentation**
+   - Complete all ADRs
+   - Update README with capability system overview
+   - Add examples for common operations
+
+3. **Testing**
+   - Add integration tests for end-to-end workflows
+   - Improve test coverage for edge cases
+   - Add performance benchmarks
+
+### 0.3.0 (Q3 2023)
+
+1. **Registry Enhancements**
+   - Implement registry events system
+   - Add namespace support
+   - Improve concurrency handling
+
+2. **Storage Improvements**
+   - Design database adapter interface
+   - Implement SQL-based storage adapter
+   - Add advanced querying capabilities
+
+3. **Inference Enhancements**
+   - Implement NLP-based requirement analysis
+   - Add context-aware capability selection
+   - Support for domain-specific inference
+
+### 1.0.0 (Q1 2024)
+
+1. **Advanced Composition**
+   - Implement composition validation framework
+   - Add constraint-based composition
+   - Create composition optimization engine
+
+2. **Governance System**
+   - Implement capability approval workflows
+   - Add usage analytics
+   - Create capability marketplace
+
+3. **Enterprise Features**
+   - Multi-environment support
+   - Cloud integration
+   - Enterprise-grade security
+
+## Progress Tracking
+
+Progress on this recalibration will be tracked through:
+
+1. **GitHub Issues**
+   - Create issues for each refinement task
+   - Track progress through milestones
+   - Link implementations to corresponding issues
+
+2. **Version Documentation**
+   - Update version documentation with completed items
+   - Maintain changelog with architectural improvements
+   - Document architectural decisions for significant changes
+
+3. **Review Updates**
+   - Schedule quarterly architectural reviews
+   - Update recalibration plan based on findings
+   - Track progress against recalibration goals
+
+## Conclusion
+
+The agent self-assembly system represents a significant architectural advancement for the Agentic framework. This recalibration plan addresses the findings from the architectural review and establishes a clear path forward for refinement and enhancement.
+
+By focusing on immediate refinements while planning for longer-term enhancements, we can incrementally improve the system while maintaining architectural integrity. The recalibration process will ensure that the agent self-assembly system continues to evolve in alignment with the framework's architectural principles and user needs.

data/.architecture/recalibration/cli_command_structure.md

@@ -0,0 +1,91 @@
+# Architectural Recalibration: CLI Command Structure
+
+## Review Analysis & Prioritization
+
+Based on the architectural review of the CLI command duplication issue, we have identified the following key areas for recalibration:
+
+### High Priority
+1. **Eliminate command duplication** - Address the immediate issue of duplicate commands appearing in the CLI help output
+2. **Standardize on a single implementation approach** - Choose between nested classes or standalone files
+3. **Ensure proper Thor configuration** - Fix the way commands are registered and loaded
+
+### Medium Priority
+1. **Improve CLI command organization** - Establish a clear hierarchy for commands
+2. **Enhance user experience** - Maintain the enhanced UI with colorization and box output
+3. **Document CLI structure** - Create clear documentation for the command structure
+
+### Low Priority
+1. **Refactor to a hybrid approach** - Consider a long-term solution with better separation of concerns
+2. **Add comprehensive testing** - Ensure all CLI commands are thoroughly tested
+
+## Architectural Plan Update
+
+### Selected Approach
+After careful consideration of the trade-offs, we have decided to **standardize on the nested class implementation** in the short term. This approach provides the enhanced UI that creates a better user experience, while still maintaining the proper command hierarchy.
+
+### Technical Implementation Plan
+
+1. **Command Structure**
+   - Keep the hierarchical command structure with top-level commands and logical subcommands
+   - Maintain the enhanced UI with colorization and box output
+   - Ensure consistent command naming and behavior
+
+2. **Implementation Details**
+   - Remove the standalone CLI command files (agent.rb, config.rb)
+   - Update requires in agentic.rb to not load these files
+   - Ensure the nested classes (AgentCommands, ConfigCommands) handle all functionality
+   - Verify Thor's subcommand registration is properly configured
+
+3. **Long-term Considerations**
+   - Consider a future refactoring to a more modular approach
+   - Evaluate the possibility of separating UI presentation from command logic
+   - Maintain backward compatibility with existing command structure
+
+## Documentation Refresh
+
+We will update the following documentation to reflect the changes:
+
+1. **README.md**
+   - Update the CLI usage section to clearly show the command hierarchy
+   - Add examples of all available commands and their usage
+
+2. **CLAUDE.md**
+   - Document the CLI command structure and implementation approach
+   - Provide guidance for future developers working on CLI commands
+
+3. **Code Documentation**
+   - Add thorough YARD comments to all CLI-related classes and methods
+   - Document the intended command hierarchy and organization
+
+## Implementation Roadmap
+
+### Phase 1: Immediate Fix (Current Version 0.2.0)
+1. Remove or comment out requires for standalone CLI files in agentic.rb
+2. Verify that only the nested class implementations are being registered
+3. Test all CLI commands to ensure they work as expected
+4. Update basic documentation to reflect current command structure
+
+### Phase 2: Cleanup (Next Minor Version)
+1. Completely remove the standalone CLI files if they are no longer needed
+2. Refactor nested classes for improved readability and maintenance
+3. Add comprehensive tests for all CLI commands
+4. Update all documentation with detailed CLI usage information
+
+### Phase 3: Long-term Refactoring (Future Major Version)
+1. Evaluate a hybrid approach with better separation of concerns
+2. Consider moving to standalone files with enhanced UI capabilities
+3. Implement a more modular architecture for the CLI components
+4. Ensure backward compatibility with existing command structure
+
+## Progress Tracking
+
+We will track progress on this recalibration using the following metrics:
+
+1. **Command Duplication**: Verify that duplicate commands no longer appear in CLI help output
+2. **Test Coverage**: Ensure all CLI commands have appropriate test coverage
+3. **Documentation Completeness**: Check that all CLI commands are properly documented
+4. **User Experience**: Collect feedback on the clarity and usability of the CLI
+
+## Conclusion
+
+This recalibration plan addresses the immediate issue of CLI command duplication while setting the stage for longer-term improvements to the CLI architecture. By standardizing on the nested class implementation in the short term, we maintain the enhanced user experience while eliminating confusion. The longer-term plan allows for a more modular approach that better separates concerns while maintaining backward compatibility.