agentic 0.1.0 → 0.2.0

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

@@ -0,0 +1,181 @@
+# Architecture Review: Agent Self-Assembly System (v0.2.0)
+
+## Review Summary
+
+This review evaluates the newly implemented agent self-assembly system, which enables Agentic agents to dynamically configure themselves based on task requirements and persist for future use. The implementation represents a significant enhancement to the framework's capabilities, enabling more intelligent and reusable agent compositions.
+
+## Key Components
+
+### 1. AgentAssemblyEngine
+- **Purpose**: Analyzes task requirements and assembles appropriate agents
+- **Key Features**:
+  - Task requirement analysis
+  - Capability selection via pluggable strategies
+  - Agent building with selected capabilities
+  - Existing agent discovery and reuse
+- **Architectural Patterns**:
+  - Factory pattern for agent creation
+  - Strategy pattern for composition approaches
+  - Observer pattern for performance tracking
+
+### 2. PersistentAgentStore
+- **Purpose**: Stores and retrieves agent configurations
+- **Key Features**:
+  - Versioned agent storage
+  - Agent filtering and discovery
+  - Metadata management
+  - Name and ID-based lookups
+- **Architectural Patterns**:
+  - Repository pattern for agent storage
+  - Semantic versioning for agent evolution
+  - Observer pattern for storage events
+
+### 3. CapabilityOptimizer
+- **Purpose**: Improves capability implementations and compositions
+- **Key Features**:
+  - Performance analysis of capabilities
+  - Suggestion generation for improvements
+  - LLM-assisted optimization
+  - Integration with the learning system
+- **Architectural Patterns**:
+  - Strategy pattern for optimization approaches
+  - Observer pattern for performance tracking
+  - Factory pattern for suggestion generation
+
+### 4. AgentCapabilityRegistry
+- **Purpose**: Manages capability specifications and providers
+- **Key Features**:
+  - Capability registration and discovery
+  - Version management
+  - Capability composition
+  - Provider management
+- **Architectural Patterns**:
+  - Singleton pattern for global access
+  - Factory pattern for capability creation
+  - Composite pattern for capability composition
+
+### 5. LlmAssistedCompositionStrategy
+- **Purpose**: Uses LLM to select optimal capabilities for tasks
+- **Key Features**:
+  - LLM prompt generation for capability selection
+  - Response parsing and validation
+  - Fallback to default strategy
+  - Dependency resolution
+- **Architectural Patterns**:
+  - Strategy pattern for composition algorithm
+  - Adapter pattern for LLM integration
+  - Chain of responsibility for fallback behavior
+
+## Architectural Assessment
+
+### Strengths
+
+1. **Modularity and Separation of Concerns**
+   - Components have clear, focused responsibilities
+   - Interfaces between components are well-defined
+   - Subsystems can evolve independently
+
+2. **Extensibility**
+   - Strategy pattern enables pluggable composition approaches
+   - Repository pattern allows different storage backends
+   - Factory pattern facilitates agent creation variations
+
+3. **Integration with Existing Systems**
+   - Seamless integration with the learning system
+   - Compatible with existing agent and task systems
+   - Maintains backward compatibility
+
+4. **Error Handling and Resilience**
+   - Graceful degradation when optimal solutions unavailable
+   - Comprehensive logging throughout the system
+   - Fallback strategies for critical failures
+
+5. **Capability Composition**
+   - Rich composition model for building complex capabilities
+   - Dependency management for capability relationships
+   - Version control for capability evolution
+
+### Areas for Improvement
+
+1. **Code Organization**
+   - Some methods are lengthy and could be decomposed
+   - Certain components have multiple responsibilities
+   - Some duplication in capability inference logic
+
+2. **Centralized Registry Pattern**
+   - Singleton registry creates global state
+   - Potential bottleneck at scale
+   - May complicate testing scenarios
+
+3. **Storage Implementation**
+   - File-based storage has inherent limitations
+   - Limited transaction support
+   - Potential scalability concerns with many agents
+
+4. **Documentation Gaps**
+   - Missing specific ADRs for the self-assembly system
+   - Limited examples for capability composition
+   - Few guidelines for custom strategy creation
+
+5. **Capability Inference**
+   - Current implementation uses basic pattern matching
+   - Could benefit from more sophisticated NLP or LLM techniques
+   - Limited contextual understanding of requirements
+
+## Recommendations
+
+### Short-term Improvements
+
+1. **Create Formal ADRs**
+   - Document architectural decisions for the self-assembly system
+   - Clarify the capability composition model
+   - Define the strategy pattern implementation
+
+2. **Method Refactoring**
+   - Decompose larger methods into focused helpers
+   - Extract common patterns into shared utilities
+   - Improve naming consistency across components
+
+3. **Enhanced Test Coverage**
+   - Add more comprehensive integration tests
+   - Test different composition strategies in isolation
+   - Create benchmarks for performance-critical operations
+
+### Long-term Enhancements
+
+1. **Advanced Capability Inference**
+   - Implement more sophisticated requirement analysis
+   - Consider dedicated LLM for capability inference
+   - Add capability compatibility checking
+
+2. **Alternative Storage Options**
+   - Support for database-backed agent storage
+   - Distributed storage for multi-environment setups
+   - Improved query capabilities for agent discovery
+
+3. **Registry Optimization**
+   - Consider registry partitioning for scalability
+   - Add registry event system for change notifications
+   - Implement capability hot-reloading
+
+4. **Capability Management Tools**
+   - Enhanced CLI for capability development
+   - Visual tools for capability composition
+   - Performance analysis dashboards
+
+## Architectural Decision Alignment
+
+The implementation aligns well with existing architectural principles:
+- Maintains object-oriented approach throughout
+- Preserves Ruby idioms and conventions
+- Follows established patterns from the codebase
+- Supports the extension system philosophy
+- Emphasizes developer experience and usability
+
+## Conclusion
+
+The agent self-assembly system represents a significant architectural enhancement to the Agentic framework. It demonstrates thoughtful design, appropriate use of patterns, and good integration with existing systems. While there are opportunities for refinement, the foundation is solid and provides a strong basis for future development.
+
+The system successfully achieves its primary goals of enabling dynamic agent composition based on task requirements and persisting those agents for future use. The integration with the learning system creates a particularly powerful feedback loop for ongoing improvement.
+
+As the system evolves, focusing on enhanced capability inference, improved storage options, and formalized documentation will help maximize its potential.

data/.architecture/reviews/cli_command_duplication.md

@@ -0,0 +1,98 @@
+# Architecture Review: CLI Command Duplication Issue
+
+## Review Purpose
+To analyze the current CLI implementation which has duplicate command definitions leading to confusion in the command line help output.
+
+## System Context
+Agentic is a Ruby gem providing a command-line tool for building and running AI agents in a plan-and-execute fashion. The CLI is built using Thor and provides commands for creating plans, executing them, and managing configuration.
+
+## Current Issue
+The CLI implementation has duplicate command definitions appearing in the help output. Commands related to agent management and configuration appear both as top-level commands and as subcommands, causing confusion for users.
+
+## Individual Member Reviews
+
+### API Design Specialist
+
+#### Findings
+- Duplicate command definitions create a confusing developer experience
+- The CLI help output shows multiple instances of the same commands with different paths
+- There is inconsistency in the command output formatting between implementations
+- The duplicates send conflicting signals about the proper command organization
+
+#### Recommendations
+- Select a single, consistent approach to command organization
+- Standardize on subcommands for logically grouped functionality
+- Ensure commands follow a clear hierarchy that reflects their relationships
+- Consider user expectations and mental models when organizing commands
+
+### Ruby Systems Architect
+
+#### Findings
+- Two implementations of the same functionality exist in the codebase:
+  1. Nested classes within the main CLI class (enhanced UI with colorization)
+  2. Standalone files in the cli/ directory (simpler implementation)
+- Both implementations are being loaded and registered as commands
+- The implementation is not DRY (Don't Repeat Yourself)
+- Zeitwerk autoloading may be contributing to the issue by loading both implementations
+
+#### Recommendations
+- Choose one implementation approach and remove the duplicate
+- Refactor to properly utilize Thor's subcommand functionality
+- Ensure Zeitwerk loading is properly configured for Thor classes
+- Consider moving all command implementations to standalone files for maintainability
+
+### CLI Implementation Expert
+
+#### Findings
+- Thor's subcommand registration is functioning correctly, but multiple command sources exist
+- Both standalone files and nested classes are being recognized by Thor
+- The enhanced UI implementations have better user experience with colorization and box output
+- The duplicate registrations are likely causing confusion in command discovery
+
+#### Recommendations
+- Keep the enhanced UI implementation as it provides better user experience
+- Remove or deactivate the simpler implementations in standalone files
+- Review the Thor documentation to ensure proper subcommand registration
+- Consider adding command namespaces to better organize related commands
+
+## Consolidated Analysis
+
+### Key Findings
+1. The CLI is registering two implementations of the same commands - one from nested classes within CLI.rb and another from standalone files
+2. The nested implementations have enhanced UI with colorization and box output
+3. The standalone implementations have simpler output
+4. Both are being loaded due to how Thor processes command registration and Zeitwerk's autoloading
+
+### Trade-offs Analysis
+**Option 1: Keep nested classes only**
+- Pros: Enhanced UI, centralized code location
+- Cons: Larger file size, less modular
+
+**Option 2: Use standalone files only**
+- Pros: Better modularity, separation of concerns
+- Cons: Currently has simpler UI, would need enhancement
+
+**Option 3: Hybrid approach with delegation**
+- Pros: Clean architecture, separation of UI from logic
+- Cons: More complex, requires additional refactoring
+
+### Recommendations
+1. **Short-term fix**: Choose the nested class implementation and remove or disable the standalone files
+2. **Long-term solution**: Refactor to a hybrid approach where:
+   - Standalone files contain the core command logic
+   - UI presentation layer is separated
+   - Commands are clearly organized in a hierarchical structure
+
+## Action Items
+1. Remove or disable the standalone CLI command files (agent.rb, config.rb)
+2. Update the requires in agentic.rb to reflect this change
+3. Consider renaming the nested classes for clarity
+4. Document the CLI command structure in the README or documentation
+5. Add comprehensive tests for CLI command functionality
+
+## Review Participants
+- API Design Specialist
+- Ruby Systems Architect
+- CLI Implementation Expert
+
+Date: May 22, 2024

data/.architecture/templates/adr.md

@@ -0,0 +1,105 @@
+# ADR-XXX: [Title]
+
+## Status
+
+[Draft | Proposed | Accepted | Deprecated | Superseded]
+
+If superseded, link to the new ADR: [New ADR Link]
+
+## Context
+
+[Describe the context and problem statement that led to this decision. Include any relevant constraints, requirements, or background information. Reference the architectural review findings if applicable.]
+
+## Decision Drivers
+
+* [Driver 1: Briefly describe a factor influencing the decision]
+* [Driver 2: ...]
+* [Driver n: ...]
+
+## Decision
+
+[Describe the decision that was made. Be clear and precise about the architectural change being implemented.]
+
+**Architectural Components Affected:**
+* [Component 1]
+* [Component 2]
+* [...]
+
+**Interface Changes:**
+* [Detail any changes to public interfaces]
+
+## Consequences
+
+### Positive
+
+* [Positive consequence 1]
+* [Positive consequence 2]
+* [...]
+
+### Negative
+
+* [Negative consequence 1]
+* [Negative consequence 2]
+* [...]
+
+### Neutral
+
+* [Neutral consequence 1]
+* [Neutral consequence 2]
+* [...]
+
+## Implementation
+
+[Provide a high-level implementation plan, including any phasing or migration strategies.]
+
+**Phase 1: [Phase Name]**
+* [Implementation step 1]
+* [Implementation step 2]
+* [...]
+
+**Phase 2: [Phase Name]**
+* [Implementation step 1]
+* [Implementation step 2]
+* [...]
+
+## Alternatives Considered
+
+### [Alternative 1]
+
+[Describe alternative approach]
+
+**Pros:**
+* [Pro 1]
+* [Pro 2]
+
+**Cons:**
+* [Con 1]
+* [Con 2]
+
+### [Alternative 2]
+
+[Describe alternative approach]
+
+**Pros:**
+* [Pro 1]
+* [Pro 2]
+
+**Cons:**
+* [Con 1]
+* [Con 2]
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [...]
+
+**Testing Approach:**
+* [Describe how the implementation of this decision will be tested]
+
+## References
+
+* [Architectural Review X.Y.Z](link-to-review)
+* [Reference 1](link)
+* [Reference 2](link)

data/.architecture/templates/implementation_roadmap.md

@@ -0,0 +1,125 @@
+# Implementation Roadmap for Version X.Y.Z
+
+## Overview
+
+This document outlines the implementation plan for architectural changes identified in the recalibration plan for version X.Y.Z. It breaks down high-level architectural changes into implementable tasks, assigns them to specific versions, and establishes acceptance criteria.
+
+## Target Versions
+
+This roadmap covers the following versions:
+- **X.Y.Z**: [Brief description of focus]
+- **X.Y.(Z+1)**: [Brief description of focus]
+- **X.(Y+1).0**: [Brief description of focus]
+
+## Implementation Areas
+
+### [Area 1: e.g., Component Decomposition]
+
+**Overall Goal**: [Describe the high-level architectural goal for this area]
+
+#### Tasks for Version X.Y.Z
+
+| Task ID | Description | Dependencies | Complexity | Owner | Tests Required |
+|---------|-------------|--------------|------------|-------|----------------|
+| [A1.1] | [Detailed task description] | [Dependencies] | [Low/Medium/High] | [Owner] | [Test requirements] |
+| [A1.2] | [...] | [...] | [...] | [...] | [...] |
+
+**Acceptance Criteria**:
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [...]
+
+#### Tasks for Version X.Y.(Z+1)
+
+| Task ID | Description | Dependencies | Complexity | Owner | Tests Required |
+|---------|-------------|--------------|------------|-------|----------------|
+| [A1.3] | [Detailed task description] | [Dependencies] | [Low/Medium/High] | [Owner] | [Test requirements] |
+| [A1.4] | [...] | [...] | [...] | [...] | [...] |
+
+**Acceptance Criteria**:
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [...]
+
+### [Area 2: e.g., Security Enhancements]
+
+**Overall Goal**: [Describe the high-level architectural goal for this area]
+
+#### Tasks for Version X.Y.Z
+
+| Task ID | Description | Dependencies | Complexity | Owner | Tests Required |
+|---------|-------------|--------------|------------|-------|----------------|
+| [B1.1] | [Detailed task description] | [Dependencies] | [Low/Medium/High] | [Owner] | [Test requirements] |
+| [B1.2] | [...] | [...] | [...] | [...] | [...] |
+
+**Acceptance Criteria**:
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [...]
+
+## Implementation Approach
+
+### Breaking vs. Non-Breaking Changes
+
+[Describe the approach to handling breaking changes, including deprecation policy, backward compatibility strategies, etc.]
+
+### Feature Flags
+
+[Document any feature flags that will be used to control the rollout of new architectural components]
+
+| Flag Name | Purpose | Default Value | Removal Version |
+|-----------|---------|---------------|-----------------|
+| [Flag name] | [Purpose] | [true/false] | [Version] |
+
+### Migration Support
+
+[Detail any migration utilities, scripts, or guidance that will be provided to help users adapt to architectural changes]
+
+## Testing Strategy
+
+### Component Tests
+
+[Describe the approach to testing individual architectural components]
+
+### Integration Tests
+
+[Describe the approach to testing integration between components]
+
+### Migration Tests
+
+[Describe the approach to testing migration paths from previous versions]
+
+## Documentation Plan
+
+| Document | Update Required | Responsible | Deadline |
+|----------|-----------------|-------------|----------|
+| [Document name] | [Description of update needed] | [Responsible person] | [Date] |
+
+## Risk Assessment
+
+| Risk | Impact | Likelihood | Mitigation Strategy |
+|------|--------|------------|---------------------|
+| [Risk description] | [High/Medium/Low] | [High/Medium/Low] | [Mitigation approach] |
+
+## Timeline
+
+| Milestone | Target Date | Dependencies | Owner |
+|-----------|-------------|--------------|-------|
+| [Milestone description] | [Date] | [Dependencies] | [Owner] |
+
+## Progress Tracking
+
+Progress on this implementation roadmap will be tracked in:
+- [Link to tracking tool/document]
+- [Link to relevant GitHub projects/issues]
+
+## Appendices
+
+### A. Architecture Diagrams
+
+[Include or link to relevant architecture diagrams]
+
+### B. Relevant ADRs
+
+- [ADR-XXX: Title](link-to-adr)
+- [ADR-YYY: Title](link-to-adr)

data/.architecture/templates/progress_tracking.md

@@ -0,0 +1,89 @@
+# Architectural Changes Progress Tracking
+
+## Overview
+
+This document tracks the implementation progress of architectural changes identified in the recalibration plan for version X.Y.Z. It is updated regularly to reflect current status and any adjustments to the implementation approach.
+
+**Last Updated**: [DATE]
+
+## Executive Summary
+
+| Category | Total Items | Completed | In Progress | Not Started | Deferred |
+|----------|-------------|-----------|-------------|-------------|----------|
+| Architectural Changes | [Number] | [Number] | [Number] | [Number] | [Number] |
+| Implementation Improvements | [Number] | [Number] | [Number] | [Number] | [Number] |
+| Documentation Enhancements | [Number] | [Number] | [Number] | [Number] | [Number] |
+| Process Adjustments | [Number] | [Number] | [Number] | [Number] | [Number] |
+| **TOTAL** | [Number] | [Number] | [Number] | [Number] | [Number] |
+
+**Completion Percentage**: [X%]
+
+## Detailed Status
+
+### Architectural Changes
+
+| ID | Recommendation | Priority | Status | Target Version | Actual Version | Notes |
+|----|---------------|----------|--------|----------------|----------------|-------|
+| A1 | [Brief description] | [Priority] | [Not Started/In Progress/Completed/Deferred] | [Version] | [Actual version or N/A] | [Current status notes] |
+
+### Implementation Improvements
+
+| ID | Recommendation | Priority | Status | Target Version | Actual Version | Notes |
+|----|---------------|----------|--------|----------------|----------------|-------|
+| I1 | [Brief description] | [Priority] | [Not Started/In Progress/Completed/Deferred] | [Version] | [Actual version or N/A] | [Current status notes] |
+
+### Documentation Enhancements
+
+| ID | Recommendation | Priority | Status | Target Version | Actual Version | Notes |
+|----|---------------|----------|--------|----------------|----------------|-------|
+| D1 | [Brief description] | [Priority] | [Not Started/In Progress/Completed/Deferred] | [Version] | [Actual version or N/A] | [Current status notes] |
+
+### Process Adjustments
+
+| ID | Recommendation | Priority | Status | Target Version | Actual Version | Notes |
+|----|---------------|----------|--------|----------------|----------------|-------|
+| P1 | [Brief description] | [Priority] | [Not Started/In Progress/Completed/Deferred] | [Version] | [Actual version or N/A] | [Current status notes] |
+
+## Implementation Adjustments
+
+This section documents any adjustments made to the implementation approach since the original recalibration plan.
+
+| ID | Original Approach | Adjusted Approach | Rationale | Impact |
+|----|-------------------|-------------------|-----------|--------|
+| [ID] | [Description] | [Description] | [Reason for change] | [Impact of change] |
+
+## Milestone Progress
+
+| Milestone | Target Date | Status | Actual/Projected Completion | Notes |
+|-----------|-------------|--------|---------------------------|-------|
+| [Milestone] | [Date] | [Not Started/In Progress/Completed/Delayed] | [Date] | [Notes] |
+
+## Blocked Items
+
+| ID | Blocker Description | Impact | Owner | Resolution Plan | Projected Resolution Date |
+|----|---------------------|--------|-------|-----------------|---------------------------|
+| [ID] | [Description] | [Impact] | [Owner] | [Plan] | [Date] |
+
+## Recently Completed Items
+
+| ID | Description | Completion Date | Implemented In | Implementation Notes |
+|----|-------------|-----------------|----------------|----------------------|
+| [ID] | [Description] | [Date] | [Version] | [Notes] |
+
+## Next Check-in
+
+The next progress check-in meeting is scheduled for [DATE].
+
+## Appendices
+
+### A. Test Coverage Report
+
+[Summary of test coverage for implemented architectural changes]
+
+### B. Documentation Status
+
+[Summary of documentation updates status]
+
+### C. Quality Metrics
+
+[Key quality metrics for implemented architectural changes]

data/.architecture/templates/recalibration_plan.md

@@ -0,0 +1,70 @@
+# Architectural Recalibration Plan: Version X.Y.Z
+
+## Overview
+
+This document outlines the action plan derived from the architectural review of version X.Y.Z. It categorizes and prioritizes recommendations to guide implementation across upcoming releases.
+
+## Review Summary
+
+- Review Date: [DATE]
+- Review Document: [LINK TO REVIEW]
+- Participants: [LIST OF PARTICIPANTS]
+
+## Action Items
+
+### Architectural Changes
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| A1 | [Brief description] | [Critical/High/Medium/Low] | [Owner] | [Version] | [Dependencies] | [Additional context] |
+
+### Implementation Improvements
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| I1 | [Brief description] | [Critical/High/Medium/Low] | [Owner] | [Version] | [Dependencies] | [Additional context] |
+
+### Documentation Enhancements
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| D1 | [Brief description] | [Critical/High/Medium/Low] | [Owner] | [Version] | [Dependencies] | [Additional context] |
+
+### Process Adjustments
+
+| ID | Recommendation | Priority | Owner | Target Version | Dependencies | Notes |
+|----|---------------|----------|-------|----------------|--------------|-------|
+| P1 | [Brief description] | [Critical/High/Medium/Low] | [Owner] | [Version] | [Dependencies] | [Additional context] |
+
+## 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 | [Description] | [Low/Medium/High] | [Timeframe] |
+
+## 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-XXX | [Title] | [Draft/Proposed/Accepted] | [Owner] | [Date] |
+
+## Timeline
+
+Overview of the recalibration implementation timeline:
+
+- Analysis & Prioritization: [Start Date] - [End Date]
+- Architectural Plan Update: [Start Date] - [End Date]
+- Documentation Refresh: [Start Date] - [End Date]
+- Implementation Roadmapping: [Start Date] - [End Date]
+
+## Next Steps
+
+Immediate next actions to be taken:
+
+1. [Action 1]
+2. [Action 2]
+3. [Action 3]