empathy-framework 4.1.1__tar.gz → 4.4.0__tar.gz

{empathy_framework-4.1.1 → empathy_framework-4.4.0}/CHANGELOG.md

@@ -5,9 +5,483 @@ All notable changes to the Empathy Framework will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.4.0] - 2026-01-19
+
+### Added - PRODUCTION-READY AGENT TEAM SYSTEM 🚀🎯
+
+#### Real LLM Agent Execution
+- **Real LLM Agent Execution** - Meta-workflow agents now execute with real LLM calls
+  - Integrated Anthropic client for Claude model execution
+  - Accurate token counting and cost tracking from actual API usage
+  - Progressive tier escalation (CHEAP → CAPABLE → PREMIUM) with real execution
+  - Graceful fallback to simulation when API key not available
+  - Full telemetry integration via UsageTracker
+  - **Files**: `src/empathy_os/meta_workflows/workflow.py`
+
+- **AskUserQuestion Tool Integration** - Form collection now supports real tool invocation
+  - Callback-based pattern for AskUserQuestion tool injection
+  - Interactive mode: Uses callback when provided (Claude Code context)
+  - Default mode: Graceful fallback to question defaults
+  - `set_callback()` method for runtime configuration
+  - Maintains full backward compatibility with existing tests
+  - **Files**: `src/empathy_os/meta_workflows/form_engine.py`
+
+#### Enhanced Agent Team UX
+- **Skill-based invocation** for agent teams
+  - `/release-prep` - Invoke release preparation agent team
+  - `/test-coverage` - Invoke test coverage boost agent team
+  - `/test-maintenance` - Invoke test maintenance agent team
+  - `/manage-docs` - Invoke documentation management agent team
+  - Skills work directly in Claude Code as slash commands
+
+- **Natural language agent creation**
+  - `empathy meta-workflow ask "your request"` - Describe what you need
+  - Auto-suggests appropriate agent teams based on intent
+  - `--auto` flag for automatic execution of best match
+  - Intent detection with confidence scoring
+
+- **Intent detection system** (`intent_detector.py`)
+  - Analyzes natural language requests
+  - Maps to appropriate meta-workflow templates
+  - Keyword and phrase pattern matching
+  - Confidence scoring for match quality
+
+- **Integrated skills**
+  - Updated `/test` to suggest `/test-coverage` and `/test-maintenance`
+  - Updated `/security-scan` to suggest `/release-prep`
+  - Updated `/docs` to suggest `/manage-docs`
+
+#### Built-in Templates & Infrastructure
+- **Built-in meta-workflow templates** (`builtin_templates.py`)
+  - `release-prep`: Comprehensive release readiness assessment
+  - `test-coverage-boost`: Multi-agent test generation with gap analysis
+  - `test-maintenance`: Automated test lifecycle management
+  - `manage-docs`: Documentation sync and gap detection
+  - All templates use Socratic form collection and progressive tier escalation
+
+- **Enhanced TemplateRegistry**
+  - `load_template()` now checks built-in templates first
+  - `list_templates()` includes built-in templates
+  - `is_builtin()` method to identify built-in templates
+
+- **Migration documentation**
+  - `docs/CREWAI_MIGRATION.md`: Complete migration guide with examples
+  - Before/after code comparisons
+  - FAQ for common migration questions
+
+### Architecture
+
+**Execution Flow (Production Ready)**:
+```text
+User Request
+    ↓
+MetaOrchestrator (analyzes task complexity + domain)
+    ↓
+SocraticFormEngine (asks questions via AskUserQuestion callback)
+    ↓
+DynamicAgentCreator (generates agent team from responses)
+    ↓
+Real LLM Execution (Anthropic client with tier escalation)
+    ↓
+UsageTracker (telemetry + cost tracking)
+    ↓
+PatternLearner (stores in files + memory)
+```
+
+### Changed - DEPENDENCY OPTIMIZATION 📦
+
+- **CrewAI moved to optional dependencies**
+  - CrewAI and LangChain removed from core dependencies
+  - Reduces install size and dependency conflicts
+  - Install with `pip install empathy-framework[crewai]` if needed
+  - The "Crew" workflows never actually used CrewAI library
+
+- `SocraticFormEngine` now accepts `ask_user_callback` parameter for tool integration
+- `MetaWorkflow._execute_at_tier()` now uses real LLM execution by default
+- Added `_execute_llm_call()` method using Anthropic client
+- `_simulate_llm_call()` retained as fallback for testing/no-API scenarios
+
+### Deprecated
+
+- **Crew-based workflows deprecated** in favor of meta-workflow system:
+  - `ReleasePreparationCrew` → Use `empathy meta-workflow run release-prep`
+  - `TestCoverageBoostCrew` → Use `empathy meta-workflow run test-coverage-boost`
+  - `TestMaintenanceCrew` → Use `empathy meta-workflow run test-maintenance`
+  - `ManageDocumentationCrew` → Use `empathy meta-workflow run manage-docs`
+  - All deprecated workflows emit `DeprecationWarning` when instantiated
+  - See [docs/CREWAI_MIGRATION.md](docs/CREWAI_MIGRATION.md) for migration guide
+
+### Migration Notes
+
+**From v4.2.1**: No breaking changes. Existing code continues to work:
+- Tests using mock execution still work
+- Form engine without callback uses defaults (backward compatible)
+- Real execution only attempted when `mock_execution=False`
+- Deprecated workflows continue to work
+
+**To enable real execution**:
+```python
+# Set ANTHROPIC_API_KEY environment variable
+# Then use mock_execution=False
+result = workflow.execute(mock_execution=False)
+```
+
+**To migrate from Crew workflows**:
+```bash
+# Instead of using ReleasePreparationCrew
+empathy meta-workflow run release-prep
+
+# Instead of using TestCoverageBoostCrew
+empathy meta-workflow run test-coverage-boost
+```
+
+**Benefits of meta-workflows over Crew workflows**:
+- Smaller dependency footprint (no CrewAI/LangChain required)
+- Interactive configuration via Socratic questioning
+- Automatic cost optimization with progressive tier escalation
+- Session context for learning preferences
+- 125+ tests covering the system
+
+---
+
+## [4.2.1] - 2026-01-18
+
+### Added - MAJOR FEATURE 🎭
+
+- **Complete Socratic Agent Generation System** (18,253 lines in 34 files)
+  - **LLM Analyzer** (`llm_analyzer.py`): Intent analysis and workflow recommendations using LLM
+  - **Semantic Search** (`embeddings.py`): TF-IDF vectorization for workflow discovery
+  - **Visual Editor** (`visual_editor.py`): React Flow-based drag-and-drop workflow designer
+  - **MCP Server** (`mcp_server.py`): Model Context Protocol integration for Claude Code
+  - **Domain Templates** (`domain_templates.py`): Pre-built templates with auto-detection
+  - **A/B Testing** (`ab_testing.py`): Workflow variation testing framework
+  - **Collaboration** (`collaboration.py`): Multi-user workflow editing
+  - **Explainer** (`explainer.py`): Workflow explanation system
+  - **Feedback** (`feedback.py`): User feedback collection
+  - **Web UI** (`web_ui.py`): Interactive web interface components
+  - **Files**: `src/empathy_os/socratic/` (19 modules)
+
+- **10 New CLI Skills** (882 lines)
+  - `/cache` - Hybrid cache diagnostics and optimization
+  - `/cost-report` - LLM API cost tracking and analysis
+  - `/crew` - CrewAI workflow management
+  - `/deps` - Dependency health, security, and update checks
+  - `/docs` - Documentation generation and maintenance
+  - `/init` - Project initialization with best practices
+  - `/memory` - Memory system analysis and debugging
+  - `/perf` - Performance profiling and optimization
+  - `/refactor` - Safe code refactoring with workflow support
+  - `/security-scan` - Comprehensive security and quality checks
+  - **Files**: `.claude/commands/*.md` (10 skill files)
+
+- **Comprehensive Documentation** (1,488 lines)
+  - `docs/META_WORKFLOWS.md` (989 lines): Complete user guide with examples
+  - `docs/WORKFLOW_TEMPLATES.md` (499 lines): Template creation guide
+
+- **Expanded Test Suite** (4,743 lines for Socratic + 2,521 lines for meta-workflows)
+  - 15 test files for Socratic system
+  - 6 test files for meta-workflows
+  - 125+ unit tests passing
+  - End-to-end integration tests
+
+### Changed
+
+- **Dependencies Updated** (from dependabot recommendations)
+  - pytest: 7.0,<9.0 → 7.0,<10.0 (allows pytest 9.x)
+  - pytest-asyncio: 0.21,<1.0 → 0.21,<2.0 (allows 1.x)
+  - pytest-cov: 4.0,<5.0 → 4.0,<8.0 (allows newer versions)
+  - pre-commit: 3.0,<4.0 → 3.0,<5.0 (allows pre-commit 4.x)
+
+### Summary
+
+**Total additions**: 31,056 lines across 74 files
+- Socratic system: 18,253 lines (source + tests)
+- Meta-workflow docs/tests: 4,009 lines
+- CLI skills: 882 lines
+- Version bump: 6 lines
+
+---
+
+## [4.2.0] - 2026-01-17
+
+### Added - MAJOR FEATURE 🚀
+
+- **Meta-Workflow System**: Intelligent workflow orchestration through interactive forms, dynamic agent creation, and pattern learning
+  - **Socratic Form Engine**: Interactive requirements gathering via `AskUserQuestion` with batched questions (max 4 at a time)
+  - **Dynamic Agent Creator**: Generates agent teams from workflow templates based on form responses with configurable tier strategies
+  - **Template Registry**: Reusable workflow templates with built-in `python_package_publish` template (8 questions, 8 agent rules)
+  - **Pattern Learning**: Analyzes historical executions for optimization insights with memory integration support
+  - **Hybrid Storage Architecture**: Combines file-based persistence with memory-based semantic querying for intelligent recommendations
+  - **Memory Integration**: Optional UnifiedMemory integration for rich semantic queries and context-aware recommendationsa
+  - **CLI Interface**: 10 commands for managing meta-workflows
+    - `empathy meta-workflow list-templates` - List available workflow templates
+    - `empathy meta-workflow inspect <template_id>` - Inspect template details
+    - `empathy meta-workflow run <template_id>` - Execute a meta-workflow from template
+    - `empathy meta-workflow analytics [template_id]` - Show pattern learning insights
+    - `empathy meta-workflow list-runs` - List historical executions
+    - `empathy meta-workflow show <run_id>` - Show detailed execution report
+    - `empathy meta-workflow cleanup` - Clean up old execution results
+    - `empathy meta-workflow search-memory <query>` - Search memory for patterns (NEW)
+    - `empathy meta-workflow session-stats` - Show session context statistics (NEW)
+    - `empathy meta-workflow suggest-defaults <template_id>` - Get suggested defaults based on history (NEW)
+  - **Progressive Tier Escalation**: Agent-level tier strategies (CHEAP_ONLY, PROGRESSIVE, CAPABLE_FIRST)
+  - **Files**: `src/empathy_os/meta_workflows/` (7 new modules, ~2,500 lines)
+    - `models.py` - Core data structures (MetaWorkflowTemplate, AgentSpec, FormSchema, etc.)
+    - `form_engine.py` - Socratic form collection via AskUserQuestion
+    - `agent_creator.py` - Dynamic agent generation from templates
+    - `workflow.py` - MetaWorkflow orchestrator with 5-stage execution
+    - `pattern_learner.py` - Analytics and optimization with memory integration
+    - `template_registry.py` - Template loading/saving/validation
+    - `cli_meta_workflows.py` - CLI commands
+
+- **Comprehensive Test Suite**: 200+ tests achieving 78.60% overall coverage with real data (no mocks)
+  - **Meta-workflow tests** (105 tests, 59.53% coverage)
+    - Core data structures and models (26 tests, 98.68% coverage)
+    - Form engine and question batching (12 tests, 91.07% coverage)
+    - Agent creator and rule matching (20 tests, 100% coverage)
+    - Workflow orchestration (17 tests, 93.03% coverage)
+    - Pattern learning and analytics (20 tests, 61.54% coverage)
+    - End-to-end integration tests (10 tests, full lifecycle validation)
+  - **Memory search tests** (30 tests, ~80% coverage)
+    - Basic search functionality (query, filters, scoring)
+    - Relevance algorithm validation
+    - Edge cases and error handling
+  - **Session context tests** (35 tests, ~85% coverage)
+    - Choice recording and retrieval
+    - Default suggestions with validation
+    - Session statistics and TTL expiration
+  - **Core framework tests** (expanded 28 tests, 72.49% → 78.60% overall coverage)
+    - **Pattern Library** (76.80% coverage, +13 tests): Validation, filtering, linking, relationships
+    - **EmpathyOS Core** (44.07% coverage, +15 tests): Async workflows, shared library integration, empathy levels
+    - **Persistence** (100% coverage, 22 tests): JSON/SQLite operations, state management, metrics collection
+    - **Agent Monitoring** (98.51% coverage, 36 tests): Metrics tracking, team stats, alerting
+    - **Feedback Loops** (97.14% coverage, 34 tests): Loop detection, virtuous/vicious cycles, interventions
+  - **Files**: `tests/unit/meta_workflows/` (6 test modules), `tests/unit/memory/test_memory_search.py`, `tests/unit/test_pattern_library.py`, `tests/unit/test_core.py`, `tests/unit/test_persistence.py`, `tests/unit/test_agent_monitoring.py`, `tests/unit/test_feedback_loops.py`, `tests/integration/test_meta_workflow_e2e.py`
+
+- **Security Features**: OWASP Top 10 compliant with comprehensive security review
+  - ✅ No `eval()` or `exec()` usage (AST-verified)
+  - ✅ Path traversal protection via `_validate_file_path()` on all file operations
+  - ✅ Specific exception handling (no bare `except:`)
+  - ✅ Input validation at all boundaries (template IDs, file paths, run IDs)
+  - ✅ Memory classification as INTERNAL with PII scrubbing enabled
+  - ✅ Graceful fallback when memory unavailable
+  - **Documentation**: `META_WORKFLOW_SECURITY_REVIEW.md`
+
+- **Pattern Learning & Analytics**:
+  - Agent count analysis (min/max/average)
+  - Tier performance tracking by agent role
+  - Cost analysis with tier breakdown
+  - Failure pattern detection
+  - Memory-enhanced recommendations (when memory available)
+  - Semantic search for similar executions (requires memory)
+  - Comprehensive analytics reports
+
+### Architecture
+
+**Execution Flow**:
+
+```text
+Template Selection
+    ↓
+Socratic Form (AskUserQuestion)
+    ↓
+Agent Team Generation (from form responses)
+    ↓
+Progressive Execution (tier escalation per agent)
+    ↓
+File Storage + Memory Storage (hybrid)
+    ↓
+Pattern Learning & Analytics
+```
+
+**Hybrid Storage Benefits**:
+
+- **Files**: Persistent, human-readable JSON/text, easy backup
+- **Memory**: Semantic search, natural language queries, relationship modeling
+- **Graceful Fallback**: Works without memory, enhanced intelligence when available
+
+### Migration Guide
+
+Meta-workflows are opt-in. To use:
+
+```python
+from empathy_os.meta_workflows import (
+    TemplateRegistry,
+    MetaWorkflow,
+    FormResponse,
+)
+
+# Load template
+registry = TemplateRegistry()
+template = registry.load_template("python_package_publish")
+
+# Create workflow
+workflow = MetaWorkflow(template=template)
+
+# Execute (interactive form will be shown)
+result = workflow.execute()
+
+# Or provide responses programmatically
+response = FormResponse(
+    template_id="python_package_publish",
+    responses={
+        "has_tests": "Yes",
+        "test_coverage_required": "90%",
+        "quality_checks": ["Linting (ruff)", "Type checking (mypy)"],
+        "version_bump": "minor",
+    },
+)
+result = workflow.execute(form_response=response, mock_execution=True)
+
+print(f"Created {len(result.agents_created)} agents")
+print(f"Total cost: ${result.total_cost:.2f}")
+```
+
+**With Memory Integration** (optional):
+
+```python
+from empathy_os.memory.unified import UnifiedMemory
+from empathy_os.meta_workflows import PatternLearner, MetaWorkflow
+
+# Initialize memory
+memory = UnifiedMemory(user_id="agent@company.com")
+learner = PatternLearner(memory=memory)
+
+# Create workflow with memory integration
+workflow = MetaWorkflow(template=template, pattern_learner=learner)
+
+# Execute - automatically stores in files + memory
+result = workflow.execute(form_response=response)
+
+# Memory-enhanced queries
+similar = learner.search_executions_by_context(
+    query="successful workflows with high test coverage",
+    limit=5,
+)
+
+# Smart recommendations
+recommendations = learner.get_smart_recommendations(
+    template_id="python_package_publish",
+    form_response=new_response,
+)
+```
+
+### Performance
+
+- **Test Execution**: 7.55s (full suite of 105 tests)
+- **Integration Tests**: 4.99s (10 tests)
+- **Pattern Analysis**: ~50-100ms (100 executions)
+- **Memory Write**: +10-20ms per execution (negligible overhead)
+
+### Original Tests Summary (Days 1-5)
+
+- ✅ **105 meta-workflow tests passing** (95 unit + 10 integration, 100% pass rate)
+- ✅ **59.53% coverage** on meta-workflows (exceeds 53% requirement)
+- ✅ **90-100% coverage** on core modules (models, agent_creator, workflow, form_engine)
+- ✅ No regressions in existing functionality
+- ✅ Security tests validate AST analysis and path traversal prevention
+
+### Documentation
+
+- ✅ `DAY_5_COMPLETION_SUMMARY.md` - Day 5 deliverables and status
+- ✅ `META_WORKFLOW_SECURITY_REVIEW.md` - Comprehensive security audit
+- ✅ `MEMORY_INTEGRATION_SUMMARY.md` - Memory architecture and benefits
+- ✅ Inline docstrings - All public APIs documented
+- ✅ CLI help text - All commands documented
+
+- **Memory Search Implementation**: Full keyword-based search with relevance scoring
+  - `UnifiedMemory.search_patterns()` - Search patterns with query, pattern_type, and classification filters
+  - **Relevance scoring algorithm**: Exact phrase matches (10 points), keyword in content (2 points), keyword in metadata (1 point)
+  - **Filtering capabilities**: By pattern_type and classification
+  - **Graceful fallback**: Returns empty list when memory unavailable
+  - **Files**: `src/empathy_os/memory/unified.py` (+165 lines)
+  - **Tests**: `tests/unit/memory/test_memory_search.py` (30 tests, ~80% coverage)
+    - Basic search functionality (query, pattern_type, classification filters)
+    - Relevance scoring validation
+    - Edge cases (empty query, special characters, very long queries)
+    - Helper method validation (_get_all_patterns with invalid JSON, nested directories)
+
+- **Session Context Tracking**: Short-term memory for personalized workflow experiences
+  - `SessionContext` class for tracking form choices and suggesting defaults
+  - **Choice recording**: Track user selections per template and question
+  - **Default suggestions**: Intelligent defaults based on recent history
+  - **TTL-based expiration**: Configurable time-to-live (default: 1 hour)
+  - **Session statistics**: Track choice counts and workflow execution metadata
+  - **Validation**: Choice validation against form schema
+  - **Files**: `src/empathy_os/meta_workflows/session_context.py` (340 lines)
+  - **Tests**: `tests/unit/meta_workflows/test_session_context.py` (35 tests, ~85% coverage)
+    - Choice recording with/without memory
+    - Default suggestion with schema validation
+    - Recent choice retrieval
+    - Session statistics
+    - TTL expiration
+    - Edge cases (invalid choices, missing schema)
+
+- **Additional Production-Ready Workflow Templates**: 4 comprehensive templates for common use cases
+  - **code_refactoring_workflow**: Safe code refactoring with validation, testing, and review
+    - 8 questions (scope, type, tests, coverage, style, safety, backup, review)
+    - 8 agents (analyzer, test runners, planner, refactorer, enforcer, reviewer, validator)
+    - Cost range: $0.15-$2.50
+    - Use cases: Safe refactoring, modernize code, improve quality
+  - **security_audit_workflow**: Comprehensive security audit with vulnerability scanning
+    - 9 questions (scope, compliance, severity, dependencies, scans, config, reports, issues)
+    - 8 agents (vuln scanner, dependency checker, secret detector, OWASP validator, config auditor, compliance validator, report generator, issue creator)
+    - Cost range: $0.25-$3.00
+    - Use cases: Security audits, compliance validation, vulnerability assessment
+  - **documentation_generation_workflow**: Automated documentation creation
+    - 10 questions (doc types, audience, examples, format, style, diagrams, README, links)
+    - 9 agents (code analyzer, API doc generator, example generator, user guide writer, diagram generator, README updater, link validator, formatter, quality reviewer)
+    - Cost range: $0.20-$2.80
+    - Use cases: API docs, user guides, architecture documentation
+  - **test_creation_management_workflow**: Enterprise-level test creation and management
+    - 12 questions (scope, test types, framework, coverage, quality checks, inspection mode, updates, data strategy, parallel execution, reports, CI integration, documentation)
+    - 11 agents (test analyzer, unit test generator, integration test creator, e2e test designer, quality validator, test updater, fixture manager, performance test creator, report generator, CI integration specialist, documentation writer)
+    - Cost range: $0.30-$3.50
+    - Use cases: Comprehensive test suites, test quality improvement, CI/CD integration, enterprise testing
+  - **Files**: `.empathy/meta_workflows/templates/` (4 template JSON files)
+  - **All templates validated**: JSON schema conformance, CLI testing completed
+
+### Tests
+
+- ✅ **170+ tests passing** (105 original + 65 new, 100% pass rate)
+- ✅ **62%+ estimated coverage** overall
+- ✅ **Memory search tests**: 30 tests (~80% coverage)
+- ✅ **Session context tests**: 35 tests (~85% coverage)
+- ✅ **Template validation**: All 5 templates load successfully
+- ✅ **CLI validation**: All commands tested and working
+- ✅ No regressions in existing functionality
+- ✅ Security tests validate AST analysis and path traversal prevention
+
+### CLI Testing Validation
+
+- ✅ `empathy meta-workflow list-templates` - Shows all 4 templates
+- ✅ `empathy meta-workflow inspect <template_id>` - Detailed template view
+- ✅ `empathy meta-workflow list-runs` - Shows execution history
+- ✅ `empathy meta-workflow analytics <template_id>` - Pattern learning insights
+- **Documentation**: `TEST_RESULTS_SUMMARY.md` - Complete CLI testing report
+
+### Quality Assurance
+
+- ✅ **Production-ready**: Zero quality compromises
+- ✅ **Extended testing**: Additional 3+ hours of quality validation
+- ✅ **OWASP Top 10 compliance**: Security hardened implementation
+- ✅ **Comprehensive documentation**: User guides, API docs, security reviews
+- **Report**: `QA_PUBLISH_REPORT.md` - Quality assurance and publish readiness
+
+### Future Enhancements
+
+**Deferred to v4.3.0**:
+
+- Real LLM integration (replace mock execution with actual API calls)
+- Telemetry integration for meta-workflow cost tracking
+- Cross-template pattern recognition
+- Advanced session context features (preference learning, workflow suggestions)
+
+---
+
 ## [4.1.1] - 2026-01-17
 
-### Added
+### Changes
 
 - **Progressive CLI Integration**: Integrated progressive workflow commands into main empathy CLI
   - `empathy progressive list` - List all saved progressive workflow results

{empathy_framework-4.1.1 → empathy_framework-4.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: empathy-framework
-Version: 4.1.1
-Summary: AI collaboration framework with progressive tier escalation (70-85% cost savings), meta-orchestration, dynamic agent composition (6 patterns), intelligent caching (85% hit rate), tier routing, XML-enhanced prompts, persistent memory, and multi-agent orchestration. Production workflows: Progressive Test Generation, Release Prep, Test Coverage Boost.
+Version: 4.4.0
+Summary: AI collaboration framework with real LLM agent execution, AskUserQuestion tool integration, Socratic agent generation, progressive tier escalation (70-85% cost savings), meta-orchestration, dynamic agent composition (6 patterns), intelligent caching (85% hit rate), semantic workflow discovery, visual workflow editor, MCP integration for Claude Code, and multi-agent orchestration.
 Author-email: Patrick Roebuck <admin@smartaimemory.com>
 Maintainer-email: Smart-AI-Memory <admin@smartaimemory.com>
 License: # Fair Source License, version 0.9
@@ -176,9 +176,6 @@ Requires-Dist: rich<14.0.0,>=13.0.0
 Requires-Dist: typer<1.0.0,>=0.9.0
 Requires-Dist: pyyaml<7.0,>=6.0
 Requires-Dist: anthropic<1.0.0,>=0.25.0
-Requires-Dist: crewai<1.0.0,>=0.1.0
-Requires-Dist: langchain<2.0.0,>=0.1.0
-Requires-Dist: langchain-core<2.0.0,>=1.2.6
 Provides-Extra: anthropic
 Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "anthropic"
 Provides-Extra: openai
@@ -200,6 +197,8 @@ Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "agents"
 Requires-Dist: marshmallow<5.0.0,>=4.1.2; extra == "agents"
 Provides-Extra: crewai
 Requires-Dist: crewai<1.0.0,>=0.1.0; extra == "crewai"
+Requires-Dist: langchain<2.0.0,>=0.1.0; extra == "crewai"
+Requires-Dist: langchain-core<2.0.0,>=1.2.6; extra == "crewai"
 Provides-Extra: cache
 Requires-Dist: sentence-transformers<4.0.0,>=2.0.0; extra == "cache"
 Requires-Dist: torch<3.0.0,>=2.0.0; extra == "cache"
@@ -251,9 +250,9 @@ Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.0; extra == "docs"
 Requires-Dist: mkdocs-with-pdf<1.0.0,>=0.9.3; extra == "docs"
 Requires-Dist: pymdown-extensions<11.0,>=10.0; extra == "docs"
 Provides-Extra: dev
-Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
-Requires-Dist: pytest-asyncio<1.0,>=0.21; extra == "dev"
-Requires-Dist: pytest-cov<5.0,>=4.0; extra == "dev"
+Requires-Dist: pytest<10.0,>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio<2.0,>=0.21; extra == "dev"
+Requires-Dist: pytest-cov<8.0,>=4.0; extra == "dev"
 Requires-Dist: pytest-xdist<4.0,>=3.5.0; extra == "dev"
 Requires-Dist: pytest-testmon<3.0,>=2.1.0; extra == "dev"
 Requires-Dist: pytest-picked<1.0,>=0.5.0; extra == "dev"
@@ -262,7 +261,7 @@ Requires-Dist: mypy<2.0,>=1.0; extra == "dev"
 Requires-Dist: ruff<1.0,>=0.1; extra == "dev"
 Requires-Dist: coverage<8.0,>=7.0; extra == "dev"
 Requires-Dist: bandit<2.0,>=1.7; extra == "dev"
-Requires-Dist: pre-commit<4.0,>=3.0; extra == "dev"
+Requires-Dist: pre-commit<5.0,>=3.0; extra == "dev"
 Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "dev"
 Requires-Dist: fastapi<1.0.0,>=0.109.1; extra == "dev"
 Provides-Extra: developer
@@ -373,11 +372,77 @@ Dynamic: license-file
 pip install empathy-framework[developer]  # Lightweight for individual developers
 ```
 
-## What's New in v4.0.0 🎭 **PARADIGM SHIFT**
+## What's New in v4.2.0 🤖 **META-WORKFLOW SYSTEM**
 
-### **Meta-Orchestration: AI Agents That Compose Themselves**
+### **Intelligent Workflow Orchestration Through Forms + Dynamic Agents**
 
-**The breakthrough:** Instead of manually wiring agent workflows, v4.0 introduces a meta-orchestration system that analyzes tasks, selects optimal agent teams, chooses composition patterns, and learns from outcomes.
+**The breakthrough:** v4.2 introduces a meta-workflow system that combines Socratic forms (interactive questions), dynamic agent team creation, and pattern learning for self-improving workflows.
+
+**How it works:**
+
+1. 🎯 **Template Selection** - Choose from pre-built workflow templates (e.g., `python_package_publish`)
+2. 📝 **Socratic Forms** - Answer interactive questions about your workflow requirements
+3. 🤖 **Dynamic Agent Creation** - System generates optimized agent team based on your responses
+4. ⚡ **Progressive Execution** - Agents execute with tier escalation (cheap → capable → premium)
+5. 🧠 **Pattern Learning** - System learns from outcomes to optimize future workflows
+
+**Quick Start:**
+
+```bash
+# Run meta-workflow with interactive form
+empathy meta-workflow run python_package_publish
+
+# View pattern learning insights
+empathy meta-workflow analytics python_package_publish
+
+# List historical executions
+empathy meta-workflow list-runs
+```
+
+**Example workflow:**
+
+```python
+from empathy_os.meta_workflows import TemplateRegistry, MetaWorkflow, FormResponse
+
+# Load template
+registry = TemplateRegistry()
+template = registry.load_template("python_package_publish")
+
+# Create workflow
+workflow = MetaWorkflow(template=template)
+
+# Execute with form responses
+response = FormResponse(
+    template_id="python_package_publish",
+    responses={
+        "has_tests": "Yes",
+        "test_coverage_required": "90%",
+        "quality_checks": ["Linting (ruff)", "Type checking (mypy)"],
+        "version_bump": "minor",
+    },
+)
+result = workflow.execute(form_response=response, mock_execution=True)
+
+print(f"✅ Created {len(result.agents_created)} agents")
+print(f"💰 Total cost: ${result.total_cost:.2f}")
+```
+
+**Key Features:**
+
+- ✅ **Interactive forms** via `AskUserQuestion` (batched, max 4 at a time)
+- ✅ **Dynamic agent generation** from templates based on responses
+- ✅ **Hybrid storage** - files (persistent) + memory (semantic queries)
+- ✅ **Pattern learning** - analyzes historical executions for optimization
+- ✅ **7 CLI commands** - list, run, analytics, show, export, validate
+- ✅ **Security hardened** - OWASP Top 10 compliant, AST-verified
+
+---
+
+## What's in v4.0.0 🎭 **META-ORCHESTRATION**
+
+### **AI Agents That Compose Themselves**
+
+**The concept:** Instead of manually wiring agent workflows, v4.0 introduces a meta-orchestration system that analyzes tasks, selects optimal agent teams, chooses composition patterns, and learns from outcomes.
 
 **What this means:**