agentic 0.1.0 → 0.2.0

data/.architecture/templates/version_comparison.md

@@ -0,0 +1,124 @@
+# Architectural Comparison: Version X.Y.Z to A.B.C
+
+## Overview
+
+This document provides a comprehensive comparison of the architectural changes between version X.Y.Z and version A.B.C of the Agentic gem. It highlights key changes, their impact, and provides guidance for adapting existing implementations.
+
+## Summary of Changes
+
+### Major Architectural Changes
+
+* [Change 1: Brief description of a significant architectural change]
+* [Change 2: ...]
+* [...]
+
+### New Components
+
+| Component | Purpose | Key Features | Related ADRs |
+|-----------|---------|--------------|-------------|
+| [Component Name] | [Brief description] | [List key features] | [ADR-XXX] |
+
+### Modified Components
+
+| Component | Type of Change | Before | After | Rationale |
+|-----------|----------------|--------|-------|-----------|
+| [Component Name] | [Interface/Implementation/Behavior] | [Previous state] | [New state] | [Why changed] |
+
+### Removed Components
+
+| Component | Replacement (if any) | Migration Path | Rationale |
+|-----------|----------------------|----------------|-----------|
+| [Component Name] | [Replacement component] | [How to migrate] | [Why removed] |
+
+## Architectural Diagrams
+
+### Before (Version X.Y.Z)
+
+[Include before diagram or link to it]
+
+### After (Version A.B.C)
+
+[Include after diagram or link to it]
+
+## Impact Analysis
+
+### Developer Experience
+
+* [Impact 1: How the changes affect developers using the gem]
+* [Impact 2: ...]
+* [...]
+
+**Migration Effort:** [Low/Medium/High]
+
+### Performance Characteristics
+
+| Aspect | Before | After | Change Impact |
+|--------|--------|-------|---------------|
+| [Performance metric] | [Previous value] | [New value] | [Better/Worse/Neutral] |
+
+### Security Posture
+
+| Aspect | Before | After | Change Impact |
+|--------|--------|-------|---------------|
+| [Security aspect] | [Previous state] | [New state] | [Better/Worse/Neutral] |
+
+### Maintainability Metrics
+
+| Metric | Before | After | Change Impact |
+|--------|--------|-------|---------------|
+| [Maintainability metric] | [Previous value] | [New value] | [Better/Worse/Neutral] |
+
+### Observability Capabilities
+
+| Capability | Before | After | Change Impact |
+|------------|--------|-------|---------------|
+| [Observability feature] | [Previous state] | [New state] | [Better/Worse/Neutral] |
+
+## Implementation Details
+
+### Review Recommendations Addressed
+
+| Review ID | Recommendation | Implementation Approach | Deviation (if any) |
+|-----------|----------------|-------------------------|--------------------|
+| [ID from review] | [Original recommendation] | [How it was implemented] | [How implementation differed from recommendation] |
+
+### Review Recommendations Deferred
+
+| Review ID | Recommendation | Rationale for Deferral | Planned Version |
+|-----------|----------------|------------------------|-----------------|
+| [ID from review] | [Original recommendation] | [Why deferred] | [Future version] |
+
+## Migration Guide
+
+### Breaking Changes
+
+* [Breaking change 1: Description and mitigation]
+* [Breaking change 2: ...]
+* [...]
+
+### Upgrade Steps
+
+1. [Step 1: What to do first when upgrading]
+2. [Step 2: ...]
+3. [...]
+
+### Code Examples
+
+#### Before (Version X.Y.Z)
+
+```ruby
+# Example code showing usage in previous version
+```
+
+#### After (Version A.B.C)
+
+```ruby
+# Example code showing equivalent usage in new version
+```
+
+## References
+
+* [Architectural Review for X.Y.Z](link-to-review)
+* [Recalibration Plan](link-to-plan)
+* [ADR-XXX: Title](link-to-adr)
+* [ADR-YYY: Title](link-to-adr)

data/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bundle exec rspec:*)",
+      "Bash(bundle exec rake:*)",
+      "Bash(bundle exec:*)",
+      "Bash(ls:*)",
+      "Bash(touch:*)"
+    ],
+    "deny": []
+  },
+  "enableAllProjectMcpServers": false
+}

data/.claude-sessions/001-task-class-architecture-implementation.md

@@ -0,0 +1,129 @@
+# Agentic Framework Session Summary - May 19, 2024
+
+## Primary Request and Intent
+The user requested to design and implement a Task class for the Agentic framework, a Ruby gem for building and running AI agents in a plan-and-execute fashion. The primary intent was to create a robust architecture for the Task component that follows good design principles with careful consideration of task execution, error handling, and inter-component communication.
+
+## Key Technical Concepts
+- Plan-and-execute AI agent framework in Ruby
+- Task class as core execution unit
+- Result-oriented failure handling
+- Observable pattern for state change notification
+- Dependency management and minimization
+- Architectural Decision Records (ADRs)
+- Task input/output handling
+- Prompt generation
+- Integration testing for components
+- Thread-safety in Observable implementation
+
+## Files and Code Sections
+- `/Users/valentinostoll/src/agentic/CLAUDE.md`
+  - Updated with development approach guidelines and architectural evolution principles
+  - Added guidelines for maintaining architecture documentation and implementation strategy
+
+- `/Users/valentinostoll/src/agentic/ArchitectureConsiderations.md`
+  - Core architectural vision and system layers
+  - Updated Runtime Layer components to include TaskResult and TaskFailure
+  - Added Observable pattern and result-oriented failure handling principles
+  - Updated "Next Steps" section to reflect completed work
+
+- `/Users/valentinostoll/src/agentic/ArchitecturalFeatureBuilder.md`
+  - Consolidates architectural design approach
+  - Provides guidelines for feature implementation
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/` (Created directory)
+  - Contains specialized architecture documents
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/task_output_handling.md`
+  - Details standardized output structure and usage patterns
+  - Defines component responsibilities for output handling
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/task_input_handling.md`
+  - Defines input structure and sources
+  - Outlines input processing patterns and validation
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/prompt_generation.md`
+  - Specifies prompt structure and generation components
+  - Defines template management and optimization
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/task_failure_handling.md`
+  - Documents result-oriented failure handling approach
+  - Provides TaskResult and TaskFailure class designs
+  - Explains failure recovery strategies
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/task_observable_pattern.md`
+  - Details Observable pattern implementation
+  - Explains integration with system components
+  - Covers thread safety and error handling
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/self_implementation_exercise.md`
+  - Meta example of using Agentic to implement itself
+  - Demonstrates full workflow of the system
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/architecture_alignment.md`
+  - Analyzes consistency across architectural documents
+  - Recommends standardization of terminology and interfaces
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/adr_001_observer_pattern_implementation.md`
+  - Formal decision record for implementing custom Observable
+  - Evaluates options and documents rationale
+
+- `/Users/valentinostoll/src/agentic/lib/agentic/task_result.rb`
+  - Implements TaskResult class to encapsulate execution outcomes
+  ```ruby
+  class TaskResult
+    attr_reader :task_id, :success, :output, :failure
+    
+    def initialize(task_id:, success:, output: nil, failure: nil)
+      @task_id = task_id
+      @success = success
+      @output = output
+      @failure = failure
+    end
+    
+    # Methods for checking success/failure and serialization
+  end
+  ```
+
+- `/Users/valentinostoll/src/agentic/lib/agentic/task_failure.rb`
+  - Implements TaskFailure to capture execution failures
+  ```ruby
+  class TaskFailure
+    attr_reader :message, :type, :timestamp, :context
+    
+    def initialize(message:, type:, context: {})
+      @message = message
+      @type = type
+      @timestamp = Time.now
+      @context = context
+    end
+    
+    # Methods for serialization and creation from exceptions
+  end
+  ```
+
+- `/Users/valentinostoll/src/agentic/lib/agentic/observable.rb`
+  - Custom implementation of Observable pattern
+  ```ruby
+  module Observable
+    def add_observer(observer)
+      @_observers ||= []
+      @_observers << observer unless @_observers.include?(observer)
+    end
+    
+    # Methods for observer management and notification
+  end
+  ```
+
+- `/Users/valentinostoll/src/agentic/lib/agentic/task.rb`
+  - Core Task class implementation
+  - Uses Observable pattern
+  - Implements result-oriented failure handling
+
+- Unit and integration tests for all implemented components
+
+## Pending Tasks
+- Update ArchitecturalFeatureBuilder.md with lessons from implementation:
+  - Dependency minimization principle
+  - Result-oriented error handling
+  - Observable state transitions
+  - Creating Architectural Decision Records

data/.claude-sessions/002-plan-orchestrator-interface-review.md

@@ -0,0 +1,105 @@
+# Agentic Framework Session Summary - May 20, 2024
+
+## Primary Request and Intent
+The user requested a critical review of changes made to the `PlanOrchestrator` class from the perspective of a software architect. The changes involved making three previously private methods public to facilitate testing without using `send(:method_name)`. After providing this review, the user asked to document these architectural observations in an Architecture Decision Record (ADR). The intent was to critically evaluate the design choices, document the decision rationale, and provide recommendations for future improvements.
+
+## Key Technical Concepts
+- Ruby method visibility (public vs private)
+- Encapsulation principles in object-oriented design
+- Testing anti-patterns (using `send(:method_name)` to test private methods)
+- Architecture Decision Records (ADRs) as a documentation practice
+- Separation of concerns and component-based design
+- Command/Query Separation principle
+- Task orchestration and dependency management
+- Test coupling to implementation details
+- Async Ruby for concurrent task execution
+- Balancing pragmatic solutions vs architectural ideals
+
+## Files and Code Sections
+- `/Users/valentinostoll/src/agentic/lib/agentic/plan_orchestrator.rb`
+  - This is the core implementation file that was changed, where three methods were moved from private to public
+  - The key methods that were made public:
+  ```ruby
+  # Checks if all dependencies for a task are met
+  # @param task_id [String] ID of the task to check
+  # @return [Boolean] True if all dependencies are met, false otherwise
+  def all_dependencies_met?(task_id)
+    deps = @dependencies[task_id] || []
+    deps.all? do |dep_id|
+      @execution_state[:completed].include?(dep_id)
+    end
+  end
+
+  # Finds tasks that are eligible for execution (have no dependencies)
+  # @return [Array<String>] IDs of eligible tasks
+  def find_eligible_tasks
+    @dependencies.select do |task_id, deps|
+      deps.empty? && @execution_state[:pending].include?(task_id)
+    end.keys
+  end
+  
+  # Determines the overall status of the plan
+  # @return [Symbol] The overall status (:completed, :in_progress, or :partial_failure)
+  def overall_status
+    if @execution_state[:failed].any?
+      :partial_failure
+    elsif @execution_state[:pending].empty? && @execution_state[:in_progress].empty?
+      :completed
+    else
+      :in_progress
+    end
+  end
+  ```
+
+- `/Users/valentinostoll/src/agentic/.architecture-review/adr_003_plan_orchestrator_interface.md`
+  - New ADR created to document the interface design decision
+  - Captures the context, options considered, decision, and consequences
+  - Details four alternatives that were considered:
+    1. Making the methods public (implemented solution)
+    2. Creating test-specific interfaces or subclasses
+    3. Refactoring to introduce proper abstractions (recommended long-term solution)
+    4. Using alternative testing approaches focused on observable behavior
+  - Acknowledges architectural debt while providing pragmatic solution
+  - Recommends future work to extract proper component abstractions
+
+## Problem Solving
+The primary problem addressed was the tension between proper encapsulation and effective testing in the `PlanOrchestrator` class. The immediate solution was making three private methods public to avoid using the `send(:method_name)` testing anti-pattern. However, this approach creates architectural debt by exposing implementation details that should ideally remain encapsulated.
+
+The architectural review identified several concerns with the approach:
+1. Boundary clarity issues (implementation details exposed in public API)
+2. Test-driven design tension (tests accessing implementation details)
+3. Missing abstraction layer (need for proper component separation)
+4. Command/query separation violation
+5. Test coupling to implementation details
+
+While the implemented approach solved the immediate problem, the ADR acknowledged that introducing proper abstractions would be the better long-term solution. The document outlined specific future work recommendations, including extracting dependency resolution, plan status management, and execution state management into dedicated components.
+
+## Architectural Observations
+1. The current `PlanOrchestrator` has multiple responsibilities that could be better separated:
+   - Task dependency resolution
+   - Execution state management
+   - Status reporting
+   - Task execution coordination
+
+2. A component-based approach would improve separation of concerns:
+   - DependencyResolver - Manages task dependencies and eligibility
+   - ExecutionStateManager - Tracks task states and transitions
+   - StatusReporter - Provides plan status information
+   - TaskExecutor - Handles the actual execution of tasks
+
+3. Testing should focus on observable behavior rather than implementation details:
+   - Verify task execution order respects dependencies
+   - Confirm correct plan status reporting for different scenarios
+   - Test proper handling of task failures and retries
+   - Validate concurrent execution behavior
+
+## Key Principles Reinforced
+1. Minimal public interfaces - Only expose what clients truly need
+2. Tell, Don't Ask - Prefer command-based interfaces over query-based
+3. Law of Demeter - Limit knowledge of object internals
+4. Single Responsibility Principle - Classes should have only one reason to change
+5. Proper encapsulation - Hide implementation details
+6. Component-based design - Use composition over inheritance
+
+## Outcome
+The ADR document was created and saved, balancing the pragmatic short-term solution with proper architectural guidance for future improvements. The document follows the established ADR format in the codebase and provides a clear path toward better long-term architectural solutions.

data/.claude-sessions/architecture-governance-implementation.md

@@ -0,0 +1,37 @@
+# Architecture Governance Implementation
+
+## Session Summary
+
+The session focused on implementing architectural governance practices for the Agentic Ruby gem, including:
+
+1. **Architectural Review System**: 
+   - Architecture review for version 0.2.0 with multi-perspective analysis
+   - Team of specialized architecture members evaluating different aspects
+   - Collaborative findings and prioritized improvement suggestions
+
+2. **AI Engineer Role**:
+   - Added specialized role focused on AI/ML product development
+   - Expanded capabilities to include evaluations, metrics, observability, and agent orchestration
+   - Provided unique user-centered perspective on the architecture
+
+3. **Post-Review Recalibration Process**:
+   - 5-phase process to translate findings into action
+   - Standardized templates for documentation
+   - Sample recalibration plan based on 0.2.0 review
+   - CLAUDE.md updates for process documentation
+
+## Key Files Modified
+
+- `.architecture/members.yml`: Added AI Engineer role with specialized capabilities
+- `.architecture/reviews/0-2-0.md`: Comprehensive architectural review
+- `.architecture/recalibration_process.md`: Detailed 5-phase process
+- `.architecture/templates/`: Standardized documentation templates
+- `.architecture/recalibration/0-2-0.md`: Sample implementation plan
+- `CLAUDE.md`: Updated with recalibration process information
+
+## Next Steps
+
+All requested implementations have been completed. Potential next steps include:
+- Assigning owners to action items in the recalibration plan
+- Drafting ADRs for high-priority architectural changes
+- Creating implementation roadmap for the next version

data/.claude-sessions/architecture-review-session.md

@@ -0,0 +1,27 @@
+# Architecture Review Practice Implementation
+
+This session documented the implementation of a new architectural design review practice for the Agentic gem, including:
+
+1. Directory Structure:
+   - Created `.architecture` with `decisions` and `reviews` subdirectories
+   - Moved existing architectural files to `.architecture/decisions`
+
+2. Review File Format:
+   - Version-based naming (e.g., `0-2-0.md`)
+   - Template includes sections for team member reviews and collaborative analysis
+
+3. Architecture Members System:
+   - Defined 5 specialized roles in `.architecture/members.yml`
+   - Members include Systems Architect, Domain Expert, Security Specialist, Maintainability Expert, and Performance Specialist
+   - Each member has defined specialties and domains of expertise
+
+4. Review Process:
+   - Three phases: individual member reviews, collaborative discussion, final consolidated report
+   - Process initiated with "Start architecture review" command
+   - Results in comprehensive analysis across multiple architectural perspectives
+
+5. Documentation:
+   - Updated CLAUDE.md with the architecture review process details
+   - Created templates for review documents
+
+This implementation establishes a structured approach to architecture reviews that leverages multiple specialized perspectives for thorough analysis.

data/ArchitecturalFeatureBuilder.md

@@ -0,0 +1,136 @@
+# Architectural Feature Builder Guide
+
+This document consolidates the architectural design approach for the Agentic framework, providing a streamlined guide for feature implementation.
+
+## Architectural Philosophy
+
+Agentic is designed as a domain-agnostic, self-improving framework for AI agent orchestration following these principles:
+- Extensibility through well-defined interfaces
+- Progressive automation with human oversight
+- Learning capability through execution history
+- Separation of concerns with clearly defined responsibilities
+
+## Feature Implementation Process
+
+### 1. Design Phase
+
+When designing a new feature:
+
+1. **Reference Architecture**: Consult ArchitectureConsiderations.md for overall system design
+2. **Component Placement**: Identify which layer(s) the feature belongs to
+3. **Interface Definition**: Define clear interfaces before implementation
+4. **Dependency Management**: Minimize dependencies between components
+5. **Extension Points**: Identify where the feature should support extension
+
+### 2. Implementation Phase
+
+When implementing a feature:
+
+1. **Class Structure**:
+   - Define attributes with clear visibility (public/private)
+   - Implement lifecycle methods (initialization, execution, completion)
+   - Add observability hooks (logging, metrics)
+   - Include verification points
+
+2. **Communication Patterns**:
+   - Use event-driven communication where appropriate
+   - Implement clear state transitions
+   - Maintain immutability where possible
+   - Include support for serialization/deserialization
+
+3. **Service Integration**:
+   - Define clear boundaries between services
+   - Implement retry and error handling
+   - Support for asynchronous operation
+   - Include metrics collection
+
+### 3. Verification Phase
+
+When verifying a feature:
+
+1. **Automated Testing**:
+   - Unit tests for individual components
+   - Integration tests for component interaction
+   - System tests for end-to-end workflows
+
+2. **Manual Verification**:
+   - Identify human intervention points
+   - Verify error handling and recovery
+   - Assess performance characteristics
+   - Confirm extensibility
+
+## Task Class Design Example
+
+The Task class exemplifies the architectural approach:
+
+### Core Requirements
+
+1. **Functionality**:
+   - Represent a unit of work in the system
+   - Support execution by an agent
+   - Enable verification of results
+   - Track execution state and history
+
+2. **Communication**:
+   - Interface with agents for execution
+   - Communicate with verification systems
+   - Support dependency resolution
+   - Provide metrics for observability
+
+3. **Extensibility**:
+   - Support custom execution strategies
+   - Allow plugin-based verification
+   - Enable domain-specific behaviors
+   - Support various input/output formats
+
+### Implementation Considerations
+
+1. **State Management**:
+   - Maintain clear task lifecycle (pending, in_progress, completed, failed)
+   - Track timestamps for performance analysis
+   - Support retries with history
+   - Record verification results and confidence scores
+
+2. **Integration Points**:
+   - Agent execution interface
+   - Verification hub integration
+   - Metrics collection system
+   - Human intervention portal
+
+3. **Separation of Concerns**:
+   - Task should focus on state and lifecycle
+   - Execution details belong in agents
+   - Verification logic belongs in verifiers
+   - Dependency resolution in specialized resolvers
+
+## Feature Implementation Checklist
+
+For each new feature:
+
+- [ ] Design aligns with overall architecture
+- [ ] Clear separation of concerns
+- [ ] Well-defined interfaces
+- [ ] Appropriate error handling
+- [ ] Metrics and observability
+- [ ] Extension points identified
+- [ ] Human intervention points defined
+- [ ] Testing strategy established
+- [ ] Documentation prepared
+
+## Iteration Approach
+
+1. Start with a minimal implementation focused on core functionality
+2. Add verification and observability
+3. Enhance with extension points
+4. Refine based on testing and feedback
+5. Document thoroughly
+
+When iterating on architectural design:
+1. Update ArchitectureConsiderations.md with any changes
+2. Ensure backward compatibility or provide migration path
+3. Communicate changes to all stakeholders
+4. Update relevant tests and documentation
+
+## Conclusion
+
+This guide provides a structured approach to feature development within the Agentic framework. By following these guidelines, contributors can ensure their implementations align with the overall architectural vision while maintaining quality, extensibility, and consistency across the system.