moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-foundation-core/modules/delegation-advanced.md

@@ -0,0 +1,279 @@
+# Delegation Advanced Patterns
+
+Purpose: Error handling, recovery strategies, and hybrid delegation patterns for complex workflows.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [delegation-patterns.md](delegation-patterns.md)
+
+---
+
+## Error Handling and Recovery
+
+### Resilient Delegation Pattern
+
+```python
+from typing import Optional
+import asyncio
+
+class ResilientDelegation:
+    """Handle delegation failures with retry and fallback."""
+
+    def __init__(self):
+        self.max_retries = 3
+        self.retry_delay = 5  # seconds
+
+    async def delegate_with_retry(
+        self,
+        agent_type: str,
+        prompt: str,
+        context: dict,
+        fallback_agent: Optional[str] = None
+    ):
+        """Delegate with automatic retry and fallback."""
+
+        for attempt in range(self.max_retries):
+            try:
+                result = await Task(
+                    subagent_type=agent_type,
+                    prompt=prompt,
+                    context=context
+                )
+                return result
+
+            except AgentExecutionError as e:
+                if attempt < self.max_retries - 1:
+                    delay = self.retry_delay * (2 ** attempt)
+                    await asyncio.sleep(delay)
+                    continue
+
+                if fallback_agent:
+                    return await self._fallback_delegation(
+                        fallback_agent, prompt, context, original_error=e
+                    )
+
+                raise
+
+            except ContextTooLargeError as e:
+                compressed_context = self._compress_context(context)
+                return await Task(
+                    subagent_type=agent_type,
+                    prompt=prompt,
+                    context=compressed_context
+                )
+
+    async def _fallback_delegation(
+        self,
+        fallback_agent: str,
+        prompt: str,
+        context: dict,
+        original_error: Exception
+    ):
+        """Execute fallback delegation."""
+        fallback_context = {
+            **context,
+            "original_error": str(original_error),
+            "fallback_mode": True
+        }
+
+        return await Task(
+            subagent_type=fallback_agent,
+            prompt=f"[FALLBACK] {prompt}",
+            context=fallback_context
+        )
+```
+
+Usage:
+```python
+delegator = ResilientDelegation()
+
+result = await delegator.delegate_with_retry(
+    agent_type="code-backend",
+    prompt="Implement complex feature",
+    context=large_context,
+    fallback_agent="support-debug"
+)
+```
+
+---
+
+## Hybrid Delegation Patterns
+
+### Sequential + Parallel Combination
+
+```python
+async def hybrid_workflow(spec_id: str):
+    """Combine sequential and parallel patterns."""
+
+    # Phase 1: Sequential (SPEC → Design)
+    spec = await Task(
+        subagent_type="workflow-spec",
+        prompt=f"Generate SPEC {spec_id}"
+    )
+
+    design = await Task(
+        subagent_type="api-designer",
+        prompt="Design API",
+        context={"spec_id": spec.id}
+    )
+
+    execute_clear()
+
+    # Phase 2: Parallel (Implementation)
+    impl_results = await Promise.all([
+        Task(
+            subagent_type="code-backend",
+            prompt="Backend",
+            context={"spec_id": spec.id, "api": design}
+        ),
+        Task(
+            subagent_type="code-frontend",
+            prompt="Frontend",
+            context={"spec_id": spec.id, "api": design}
+        ),
+        Task(
+            subagent_type="data-database",
+            prompt="Database",
+            context={"spec_id": spec.id, "api": design}
+        )
+    ])
+
+    backend, frontend, database = impl_results
+
+    # Phase 3: Sequential (Testing → QA)
+    tests = await Task(
+        subagent_type="core-quality",
+        prompt="Integration tests",
+        context={
+            "spec_id": spec.id,
+            "backend": backend.summary,
+            "frontend": frontend.summary,
+            "database": database.summary
+        }
+    )
+
+    qa = await Task(
+        subagent_type="core-quality",
+        prompt="Quality validation",
+        context={
+            "spec_id": spec.id,
+            "tests": tests.results,
+            "coverage": tests.coverage
+        }
+    )
+
+    return {
+        "spec": spec,
+        "design": design,
+        "backend": backend,
+        "frontend": frontend,
+        "database": database,
+        "tests": tests,
+        "qa": qa
+    }
+```
+
+---
+
+### Conditional + Parallel Combination
+
+```python
+async def conditional_parallel_workflow(requests: list):
+    """Route multiple requests in parallel based on analysis."""
+
+    # Phase 1: Parallel analysis
+    analyses = await Promise.all([
+        Task(
+            subagent_type="plan",
+            prompt=f"Analyze request",
+            context={"request": req}
+        )
+        for req in requests
+    ])
+
+    # Phase 2: Conditional routing (grouped by type)
+    security_tasks = []
+    feature_tasks = []
+    bug_tasks = []
+
+    for analysis in analyses:
+        if analysis.category == "security":
+            security_tasks.append(
+                Task(
+                    subagent_type="security-expert",
+                    prompt="Handle security issue",
+                    context={"analysis": analysis}
+                )
+            )
+        elif analysis.category == "feature":
+            feature_tasks.append(
+                Task(
+                    subagent_type="code-backend",
+                    prompt="Implement feature",
+                    context={"analysis": analysis}
+                )
+            )
+        elif analysis.category == "bug":
+            bug_tasks.append(
+                Task(
+                    subagent_type="support-debug",
+                    prompt="Debug issue",
+                    context={"analysis": analysis}
+                )
+            )
+
+    # Phase 3: Parallel execution by category
+    results = await Promise.all([
+        *security_tasks,
+        *feature_tasks,
+        *bug_tasks
+    ])
+
+    return results
+```
+
+---
+
+## Context Compression Strategies
+
+```python
+class ContextCompressor:
+    """Compress context when exceeding limits."""
+
+    def compress_for_agent(self, context: dict, agent_type: str) -> dict:
+        """Compress context based on agent requirements."""
+
+        # Remove non-essential fields
+        essential_fields = self._get_essential_fields(agent_type)
+        compressed = {k: v for k, v in context.items() if k in essential_fields}
+
+        # Compress large text fields
+        for key, value in compressed.items():
+            if isinstance(value, str) and len(value) > 5000:
+                compressed[key] = self._summarize_text(value)
+
+            elif isinstance(value, list) and len(value) > 100:
+                compressed[key] = value[:50] + ["... (truncated)"] + value[-10:]
+
+        return compressed
+
+    def _summarize_text(self, text: str, max_length: int = 1000) -> str:
+        """Summarize long text to key points."""
+        paragraphs = text.split("\n\n")
+        if len(paragraphs) > 2:
+            summary = paragraphs[0] + "\n\n...\n\n" + paragraphs[-1]
+            return summary[:max_length] if len(summary) > max_length else summary
+        return text[:max_length]
+```
+
+---
+
+## Works Well With
+
+- [delegation-patterns.md](delegation-patterns.md) - Overview
+- [delegation-implementation.md](delegation-implementation.md) - Basic patterns
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06

moai_adk/templates/.claude/skills/moai-foundation-core/modules/delegation-implementation.md

@@ -0,0 +1,267 @@
+# Delegation Implementation Patterns
+
+Purpose: Detailed implementation patterns for agent delegation including context optimization and workflow examples.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Parent: [delegation-patterns.md](delegation-patterns.md)
+
+---
+
+## Context Passing Optimization
+
+### Efficient Context Structure
+
+```python
+class ContextManager:
+    """Optimize context passing between agents."""
+
+    def __init__(self):
+        self.max_context_size = 50_000  # 50K tokens
+        self.optimal_size = 30_000       # 30K tokens
+
+    def prepare_context(self, full_data: dict, agent_type: str) -> dict:
+        """Prepare optimized context for specific agent."""
+
+        context_requirements = {
+            "code-backend": ["spec_id", "api_design", "database_schema"],
+            "code-frontend": ["spec_id", "api_endpoints", "ui_requirements"],
+            "security-expert": ["spec_id", "threat_model", "security_requirements"],
+            "core-quality": ["spec_id", "code_summary", "test_strategy"],
+            "workflow-docs": ["spec_id", "api_spec", "code_summary"]
+        }
+
+        required_fields = context_requirements.get(agent_type, [])
+        optimized_context = {
+            field: full_data.get(field)
+            for field in required_fields
+            if field in full_data
+        }
+
+        if "code_summary" in required_fields:
+            optimized_context["code_summary"] = self._compress_code_summary(
+                full_data.get("full_code", "")
+            )
+
+        estimated_tokens = self._estimate_tokens(optimized_context)
+        if estimated_tokens > self.optimal_size:
+            optimized_context = self._further_compress(optimized_context)
+
+        return optimized_context
+
+    def _compress_code_summary(self, full_code: str) -> dict:
+        """Compress code to summary (functions, classes, key logic)."""
+        return {
+            "functions": extract_function_signatures(full_code),
+            "classes": extract_class_definitions(full_code),
+            "key_logic": extract_main_flow(full_code)
+        }
+
+    def _estimate_tokens(self, context: dict) -> int:
+        """Estimate token count of context."""
+        import json
+        json_str = json.dumps(context)
+        return len(json_str) // 4  # Rough estimate
+```
+
+Usage:
+```python
+context_manager = ContextManager()
+
+full_data = {
+    "spec_id": "SPEC-001",
+    "full_code": "... 50KB of code ...",
+    "api_design": {...},
+    "database_schema": {...}
+}
+
+backend_context = context_manager.prepare_context(full_data, "code-backend")
+# Result: Only spec_id, api_design, database_schema (~25K tokens)
+
+result = await Task(
+    subagent_type="code-backend",
+    prompt="Implement backend",
+    context=backend_context
+)
+```
+
+---
+
+## Full Sequential Workflow
+
+```python
+async def implement_feature_sequential(feature_description: str):
+    """Complete sequential workflow with context passing."""
+
+    # Phase 1: SPEC Generation
+    spec_result = await Task(
+        subagent_type="workflow-spec",
+        prompt=f"Generate SPEC for: {feature_description}",
+        context={
+            "feature": feature_description,
+            "requirements": ["TRUST 5 compliance", "≥85% coverage"]
+        }
+    )
+
+    execute_clear()
+
+    # Phase 2: API Design
+    api_result = await Task(
+        subagent_type="api-designer",
+        prompt="Design REST API for feature",
+        context={
+            "spec_id": spec_result.spec_id,
+            "requirements": spec_result.requirements,
+            "constraints": ["RESTful", "JSON", "OpenAPI 3.1"]
+        }
+    )
+
+    # Phase 3: Backend Implementation
+    backend_result = await Task(
+        subagent_type="code-backend",
+        prompt="Implement backend with TDD",
+        context={
+            "spec_id": spec_result.spec_id,
+            "api_design": api_result.openapi_spec,
+            "database_schema": api_result.database_schema
+        }
+    )
+
+    # Phase 4: Frontend Implementation
+    frontend_result = await Task(
+        subagent_type="code-frontend",
+        prompt="Implement UI components",
+        context={
+            "spec_id": spec_result.spec_id,
+            "api_endpoints": api_result.endpoints,
+            "ui_requirements": spec_result.ui_requirements
+        }
+    )
+
+    # Phase 5: Integration Testing
+    integration_result = await Task(
+        subagent_type="core-quality",
+        prompt="Run integration tests",
+        context={
+            "spec_id": spec_result.spec_id,
+            "backend_endpoints": backend_result.endpoints,
+            "frontend_components": frontend_result.components
+        }
+    )
+
+    # Phase 6: Documentation
+    docs_result = await Task(
+        subagent_type="workflow-docs",
+        prompt="Generate comprehensive documentation",
+        context={
+            "spec_id": spec_result.spec_id,
+            "api_spec": api_result.openapi_spec,
+            "backend_code": backend_result.code_summary,
+            "frontend_code": frontend_result.code_summary,
+            "test_results": integration_result.test_report
+        }
+    )
+
+    return {
+        "spec": spec_result,
+        "api": api_result,
+        "backend": backend_result,
+        "frontend": frontend_result,
+        "tests": integration_result,
+        "docs": docs_result
+    }
+```
+
+---
+
+## Token Management in Sequential Flow
+
+```python
+def sequential_with_token_management():
+    """Sequential flow with strategic /clear execution."""
+
+    # Phase 1: Heavy context (SPEC generation)
+    spec = Task(subagent_type="workflow-spec", ...)  # ~30K tokens
+    execute_clear()  # Save 45-50K tokens
+
+    # Phase 2: Fresh context (implementation)
+    impl = Task(
+        subagent_type="workflow-tdd",
+        context={"spec_id": spec.id}  # Minimal context
+    )  # ~80K tokens
+
+    # Phase 3: Final phase
+    docs = Task(
+        subagent_type="workflow-docs",
+        context={"spec_id": spec.id, "summary": impl.summary}
+    )  # ~25K tokens
+
+    # Total: ~135K (within 200K budget)
+```
+
+---
+
+## Complex Conditional Logic
+
+```python
+async def advanced_conditional_routing(request: dict):
+    """Multi-criteria conditional routing."""
+
+    analysis = await Task(
+        subagent_type="plan",
+        prompt="Analyze request complexity",
+        context=request
+    )
+
+    if analysis.complexity == "high" and analysis.security_critical:
+        return await sequential_secure_workflow(analysis)
+
+    elif analysis.complexity == "high":
+        return await parallel_workflow(analysis)
+
+    elif analysis.complexity == "low":
+        return await single_agent_workflow(analysis)
+
+    elif analysis.performance_critical:
+        return await performance_optimized_workflow(analysis)
+
+    else:
+        return await standard_workflow(analysis)
+
+async def sequential_secure_workflow(analysis):
+    """High-complexity security workflow."""
+    security_review = await Task(
+        subagent_type="security-expert",
+        prompt="Security architecture review"
+    )
+
+    implementation = await Task(
+        subagent_type="code-backend",
+        prompt="Implement with security controls",
+        context={"security_requirements": security_review}
+    )
+
+    penetration_test = await Task(
+        subagent_type="security-expert",
+        prompt="Penetration testing",
+        context={"implementation": implementation}
+    )
+
+    return {
+        "security_review": security_review,
+        "implementation": implementation,
+        "penetration_test": penetration_test
+    }
+```
+
+---
+
+## Works Well With
+
+- [delegation-patterns.md](delegation-patterns.md) - Overview
+- [delegation-advanced.md](delegation-advanced.md) - Error handling
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06