@agentlee5/agent-skills 1.0.0

package/documents/SKILL_WORKFLOW_COMPOSITION_MATRIX.md

@@ -0,0 +1,537 @@
+# 🔗 Skill-Workflow Composition Matrix
+
+**Purpose**: Maps all 250+ Leeway Skills to workflow templates  
+**Status**: ✅ FRAMEWORK READY (Auto-populated during Week 2)  
+**Sync Level**: 1:1 mapping (Skills ↔ Workflows)  
+**Update Frequency**: Real-time as workflows are acquired
+
+---
+
+## Executive Summary
+
+The **Skill-Workflow Composition Matrix** ensures every workflow automatically loads the required skills and every skill knows its workflow contexts.
+
+### Key Innovation
+
+**Before**: "I have 250 skills... which ones do I use for X?"  
+**After**: "I need workflow X... here are the 5-10 skills it requires. Load them."
+
+---
+
+## 🏗️ Matrix Structure
+
+```
+Workflow ID  │  Workflow Name          │  Skill IDs Required  │  Skill Count │  Composition Pattern
+────────────┼─────────────────────────┼──────────────────────┼──────────────┼─────────────────────
+workflow…   │ Sequential Task Exec    │ [skill.1, skill.2]   │  2           │ Sequential
+workflow…   │ CI Failure Recovery     │ [skill.3, skill.4]   │  2           │ Event-Driven
+...
+```
+
+---
+
+## 📊 Sample Entries (Week 1 Foundation)
+
+### Category: Automation & Orchestration (8 workflows)
+
+#### `workflow.sequential-task-chain`
+
+```yaml
+id: workflow.sequential-task-chain
+name: "Sequential Task Execution"
+skills_required:
+  - skill.task-planning # Decompose goal into steps
+  - skill.task-execution # Execute each step
+  - skill.state-management # Maintain execution state
+  - skill.output-validation # Verify each step result
+  - skill.error-recovery # Handle failures
+skill_count: 5
+coverage: 100%
+framework: LangGraph
+pattern: sequential
+execution_order: linear
+```
+
+**Why these skills**:
+
+- Task planning breaks work into ordered steps
+- Task execution runs each step
+- State management tracks progress
+- Output validation ensures quality
+- Error recovery handles problems
+
+#### `workflow.hierarchical-delegation`
+
+```yaml
+id: workflow.hierarchical-delegation
+name: "Multi-Agent Hierarchical Orchestration"
+skills_required:
+  - skill.delegation-strategy # Decide who does what
+  - skill.task-decomposition # Break into delegatable pieces
+  - skill.agent-management # Coordinate agents
+  - skill.validation-logic # Check agent results
+  - skill.result-aggregation # Combine outputs
+skill_count: 5
+coverage: 100%
+framework: CrewAI
+pattern: hierarchical
+delegation_depth: 2-3
+```
+
+#### `workflow.event-router`
+
+```yaml
+id: workflow.event-router
+name: "Event-Driven Workflow Router"
+skills_required:
+  - skill.event-detection # Identify event types
+  - skill.routing-logic # Map events to workflows
+  - skill.context-extraction # Get event data
+  - skill.workflow-invocation # Start appropriate workflow
+skill_count: 4
+coverage: 100%
+framework: GitHub Agentics, CrewAI Flow
+pattern: event-driven
+event_types: ["github", "webhook", "schedule"]
+```
+
+### Category: Analysis & Insights (7 workflows)
+
+#### `workflow.daily-report-generation`
+
+```yaml
+id: workflow.daily-report-generation
+name: "Daily Status Report"
+skills_required:
+  - skill.metrics-collection # Gather KPIs
+  - skill.data-aggregation # Combine data sources
+  - skill.trend-analysis # Identify patterns
+  - skill.report-generation # Format report
+  - skill.notification-sending # Deliver report
+skill_count: 5
+coverage: 100%
+framework: GitHub Agentics
+pattern: scheduled (daily)
+```
+
+#### `workflow.research-synthesis`
+
+```yaml
+id: workflow.research-synthesis
+name: "Research Paper Analysis & Synthesis"
+skills_required:
+  - skill.web-research # Find papers/articles
+  - skill.document-extraction # Parse PDFs/docs
+  - skill.content-summarization # Extract key points
+  - skill.insight-synthesis # Combine insights
+  - skill.bibliography-creation # Organize references
+skill_count: 5
+coverage: 100%
+framework: CrewAI
+pattern: sequential with parallel research
+```
+
+### Category: Code Quality (6 workflows)
+
+#### `workflow.ci-failure-recovery`
+
+```yaml
+id: workflow.ci-failure-recovery
+name: "CI Failure Diagnosis & Automatic Fix"
+skills_required:
+  - skill.ci-log-analysis # Parse CI output
+  - skill.error-diagnosis # Identify root cause
+  - skill.code-fix-generator # Write solution
+  - skill.test-validation # Verify fix works
+  - skill.pr-creation # Create PR with fix
+skill_count: 5
+coverage: 100%
+framework: GitHub Agentics
+pattern: event-driven (on CI failure)
+dependencies: ["skill.git-operations", "skill.code-testing"]
+```
+
+#### `workflow.code-review-workflow`
+
+```yaml
+id: workflow.code-review-workflow
+name: "Comprehensive Code Review"
+skills_required:
+  - skill.code-analysis # Surface-level review
+  - skill.architecture-review # System design check
+  - skill.security-scanning # Vulnerability scan
+  - skill.performance-analysis # Speed/memory check
+  - skill.review-writing # Generate feedback
+skill_count: 5
+coverage: 100%
+framework: AutoGen
+pattern: multi-agent (parallel reviews, then aggregation)
+```
+
+### Category: Product & Growth (5 workflows)
+
+#### `workflow.user-feedback-analysis`
+
+```yaml
+id: workflow.user-feedback-analysis
+name: "User Feedback → Insights → Priorities"
+skills_required:
+  - skill.feedback-collection # Gather feedback
+  - skill.sentiment-analysis # Understand sentiment
+  - skill.theme-extraction # Identify patterns
+  - skill.prioritization # Rank by impact
+  - skill.action-items-creation # Create tasks
+skill_count: 5
+coverage: 100%
+framework: CrewAI
+pattern: sequential with NLP
+```
+
+---
+
+## 🔍 Complete Mapping Template
+
+For each of the 50+ workflows, create an entry:
+
+```yaml
+---
+workflow_id: workflow.[name]
+workflow_name: "[Human-readable name]"
+framework: [GitHub Agentics | CrewAI | AutoGen | LangGraph | SuperAGI]
+pattern: [sequential | hierarchical | event-driven | fsm | dag | crew]
+trigger: [schedule | event | manual | api]
+
+required_skills:
+  - id: skill.skill-id-1
+    role: "Performs X in step Y"
+    essential: true
+    substitutable: false
+
+  - id: skill.skill-id-2
+    role: "Performs X in step Y"
+    essential: true
+    substitutable: false
+
+optional_skills:
+  - id: skill.skill-id-optional-1
+    role: "Enhances X if available"
+    substitutable: true
+
+skill_coverage: 100% # % of required skills in registry
+total_skills: 5
+composition_steps:
+  - step: 1
+    skills: [skill-id-1]
+    requires_output_from: []
+    output: "[Description]"
+
+  - step: 2
+    skills: [skill-id-2]
+    requires_output_from: [1]
+    output: "[Description]"
+
+success_metrics:
+  - "All steps completed"
+  - "All outputs validated"
+
+failure_modes:
+  - "Missing skill → Auto-fail with suggestion"
+  - "Skill validation error → Retry or skip"
+  - "Execution timeout → Escalate to human"
+
+estimated_duration: "5min - 30min"
+resource_requirements:
+  - "API keys: [which ones]"
+  - "Disk space: [amount]"
+  - "Memory: [amount]"
+
+example_invocation:
+  input: { ... }
+  expected_output: { ... }
+```
+
+---
+
+## 📈 Skill Utilization by Workflow
+
+### High-Utilization Skills (Expected)
+
+These core skills appear in **many workflows**:
+
+```
+skill.task-execution              → 15+ workflows
+skill.state-management            → 12+ workflows
+skill.output-validation           → 11+ workflows
+skill.error-recovery              → 10+ workflows
+skill.summarization               → 10+ workflows
+skill.report-generation           → 8+ workflows
+skill.api-integration             → 8+ workflows
+skill.data-aggregation            → 7+ workflows
+skill.notification-sending        → 7+ workflows
+skill.authentication              → 6+ workflows
+```
+
+### Specialized Skills (Expected)
+
+These domain-specific skills appear in **specific workflows**:
+
+```
+skill.ci-log-analysis             → 3 workflows (CI-focused)
+skill.security-scanning           → 4 workflows (security-focused)
+skill.test-framework-interaction  → 4 workflows (testing-focused)
+skill.market-analysis             → 2 workflows (growth-focused)
+skill.codebase-navigation         → 5 workflows (code-analysis)
+```
+
+---
+
+## 🔄 Bidirectional Index
+
+### Skill → Workflows Lookup
+
+```python
+# When Agent Lee loads a skill:
+skill_id = "skill.code-analysis"
+
+# It knows about these workflows:
+workflows_using_skill = [
+    "workflow.code-review-workflow",
+    "workflow.pr-review",
+    "workflow.dependency-audit",
+    "workflow.security-scanning",
+    "workflow.architecture-review"
+]
+```
+
+### Workflow → Skills Lookup
+
+```python
+# When Agent Lee loads a workflow:
+workflow_id = "workflow.ci-failure-recovery"
+
+# It loads these skills:
+required_skills = [
+    "skill.ci-log-analysis",
+    "skill.error-diagnosis",
+    "skill.code-fix-generator",
+    "skill.test-validation",
+    "skill.pr-creation"
+]
+```
+
+---
+
+## 📊 Coverage Analysis
+
+### Skills per Workflow (Distribution)
+
+```
+Workflows with 1-3 skills:   5 workflows  (10%)
+Workflows with 4-6 skills:   25 workflows (50%)
+Workflows with 7-10 skills:  15 workflows (30%)
+Workflows with 10+ skills:   5 workflows  (10%)
+
+Average: 6.2 skills per workflow
+```
+
+### Skill Duplication Analysis (Dedup Strategy)
+
+```
+Core skills used in 10+ workflows:
+  → Keep as separate, highly-reusable skills
+
+Specialized skills used in 2-3 workflows:
+  → Bundle into sub-workflows within main workflow
+
+One-off skills:
+  → Create smaller micro-workflows
+```
+
+---
+
+## 🛠️ Auto-Population Strategy (Week 2)
+
+### Process
+
+1. **Parse each WORKFLOW.md**
+   - Extract skill_bundle metadata
+   - Validate skills exist in registry
+
+2. **Cross-reference skills**
+   - Build bidirectional index
+   - Detect missing skills (gap analysis)
+
+3. **Identify substitutable skills**
+   - Skills with similar responsibilities
+   - Create fallback chains
+
+4. **Generate mapping JSON**
+
+   ```json
+   {
+     "version": "1.0.0",
+     "total_workflows": 50,
+     "total_skill_references": 312,
+     "unique_skills_used": 187,
+     "avg_skills_per_workflow": 6.2,
+     "workflows": {
+       "workflow.sequential-task-chain": {
+         "skills_required": ["skill.x", "skill.y"],
+         "skills_missing": [],
+         "coverage": 100
+       }
+     },
+     "skills": {
+       "skill.task-execution": {
+         "used_in_workflows": ["workflow.a", "workflow.b"],
+         "count": 25
+       }
+     }
+   }
+   ```
+
+5. **Gap analysis report**
+   - Skills referenced but not in registry: \_\_\_
+   - Workflows fully covered: \_\_\_
+   - Workflows partially covered: \_\_\_
+   - Recommendations: \_\_\_
+
+---
+
+## 🎯 Expected Outcomes
+
+### Week 2 Completion Checklist
+
+- [ ] All 50+ workflows have documented skill bundles
+- [ ] Skill-to-workflow bidirectional index created
+- [ ] Gap analysis identifies missing skills
+- [ ] Fallback/substitution chains defined
+- [ ] Coverage report shows 80%+ of skills in registry
+- [ ] Composition matrix JSON finalized
+- [ ] Agent Lee can load workflows with automatic skill loading
+- [ ] Workflows tested with actual skill execution
+
+---
+
+## 🚀 Usage Examples
+
+### Example 1: Load Workflow with Auto-Skill-Loading
+
+```python
+# Agent Lee MCP tool invocation
+agent_lee.load_workflow("workflow.ci-failure-recovery")
+
+# System automatically:
+# 1. Loads workflow definition
+# 2. Extracts required skills: [skill.ci-log-analysis, skill.error-diagnosis, ...]
+# 3. Loads each skill from skill registry
+# 4. Validates all skills are present
+# 5. Initializes workflow execution environment
+# 6. Returns ready-to-execute workflow
+```
+
+### Example 2: Query Skill Usage
+
+```python
+# Find all workflows using a skill
+workflows = matrix.get_workflows_by_skill("skill.code-analysis")
+# Returns: ["workflow.code-review", "workflow.security-scan", ...]
+```
+
+### Example 3: Check Coverage
+
+```python
+# Check if workflow is fully supported
+coverage = matrix.get_workflow_coverage("workflow.research-synthesis")
+# Returns: {
+#   "total_required": 5,
+#   "present": 5,
+#   "coverage": "100%",
+#   "missing": []
+# }
+```
+
+---
+
+## 📋 Workflow-Skill Composition Examples
+
+### Simple Sequential Workflow
+
+```
+Workflow: "Sequential Task Chain"
+Steps: 1 → 2 → 3 → 4 → 5
+
+Step 1: Plan
+  Skills: [skill.task-planning]
+  Input: overall_goal
+  Output: ordered_task_list
+
+Step 2: Execute Task 1
+  Skills: [skill.task-execution]
+  Input: task_1
+  Output: task_1_result
+
+Step 3: Execute Task 2
+  Skills: [skill.task-execution]
+  Input: task_2 (depends on task_1_result)
+  Output: task_2_result
+
+... (Steps 4-5 similar)
+
+Final: Validate All Results
+  Skills: [skill.output-validation]
+  Input: [task_1_result...task_5_result]
+  Output: final_report
+```
+
+### Complex Hierarchical Workflow
+
+```
+Workflow: "Hierarchical Delegation"
+
+Manager Agent
+  Skills: [skill.delegation-strategy, skill.validation-logic]
+
+  Delegates to Team A:
+    Skills: [skill.research, skill.analysis]
+    Task: "Research X"
+
+  Delegates to Team B:
+    Skills: [skill.development, skill.testing]
+    Task: "Build Solution"
+
+  Validates & Aggregates:
+    Skills: [skill.result-aggregation, skill.reporting]
+    Final Output: Executive Summary
+```
+
+---
+
+## 📊 Matrix Statistics (Post-Week 2)
+
+| Metric                            | Target | Status     |
+| --------------------------------- | ------ | ---------- |
+| Workflows in matrix               | 50+    | ⏳ Pending |
+| Total skill references            | 300+   | ⏳ Pending |
+| Unique skills used                | 200+   | ⏳ Pending |
+| Average skills/workflow           | 6-8    | ⏳ Pending |
+| Workflows fully covered (100%)    | 45+    | ⏳ Pending |
+| Skill coverage (across workflows) | 80%+   | ⏳ Pending |
+| Bidirectional index entries       | 300+   | ⏳ Pending |
+
+---
+
+## 🎖️ Success Metrics
+
+✅ **Matrix Complete**: Every workflow maps to required skills  
+✅ **No Orphans**: Every skill appears in at least one workflow  
+✅ **Auto-Loading**: Agent Lee automatically loads skill bundles  
+✅ **Gap Analysis**: Missing skills clearly identified  
+✅ **Composition Validated**: Workflows tested with skill execution
+
+---
+
+**Status**: ✅ **FRAMEWORK READY | AUTO-POPULATION IN WEEK 2**
+
+**Next**: Begin Week 1 execution to acquire workflows, then Week 2 to build this matrix.
+