moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-alfred-clone-pattern/examples.md

@@ -0,0 +1,354 @@
+# Clone Pattern Examples
+
+## Basic Usage Examples
+
+### Example 1: Large-Scale Migration
+
+**Scenario**: Migrate project from v0.14.0 to v0.15.2
+
+```python
+# Alfred's analysis
+task = UserRequest(
+    type="migration",
+    description="Migrate entire MoAI-ADK project from v0.14.0 to v0.15.2",
+    scope="entire_project",
+    steps=8,
+    domains=["config", "hooks", "permissions", "documentation"],
+    uncertainty=0.8  # High uncertainty - new structure
+)
+
+# Decision: Apply Clone pattern
+if should_create_clone(task):
+    clone = create_clone(
+        task_description="Migrate v0.14.0 project structure to v0.15.2",
+        context_scope="full",
+        learning_enabled=True
+    )
+    
+    # Clone executes autonomously:
+    # 1. Analyzes current structure
+    # 2. Creates migration plan
+    # 3. Backs up critical files
+    # 4. Applies migration incrementally
+    # 5. Validates each step
+    # 6. Handles conflicts automatically
+    # 7. Creates PR for review
+    # 8. Saves learnings to memory
+```
+
+**Clone's Execution Log**:
+```
+Phase 1: Structure Analysis
+- Found 47 files needing updates
+- Identified 3 breaking changes
+- Created backup: .moai/backup/v0.14.0/
+
+Phase 2: Migration Planning
+- Planned 8-step incremental migration
+- Estimated risk: medium
+- Created rollback checkpoints
+
+Phase 3: Execution
+- Step 1: Updated config.json structure ✅
+- Step 2: Migrated hook files ✅
+- Step 3: Updated permissions ✅
+- Step 4: Fixed import paths ✅
+- Step 5: Updated documentation ✅
+- Step 6: Validated all tests ✅
+- Step 7: Created PR ✅
+- Step 8: Saved learnings ✅
+
+Result: Migration completed successfully
+Time: 45 minutes (vs estimated 2 hours manual)
+Issues: 2 minor conflicts resolved automatically
+```
+
+### Example 2: Parallel File Refactoring
+
+**Scenario**: Update import statements across 150+ Python files
+
+```python
+# Alfred's analysis
+task = UserRequest(
+    type="refactoring",
+    description="Update all import statements from old package structure",
+    files_affected=150,
+    pattern_change="from moai.adk import X → from moai_adk import X",
+    complexity="high",
+    parallelizable=True
+)
+
+# Decision: Apply Clone pattern with parallel processing
+if should_create_clone(task):
+    # Create 3 clones for parallel processing
+    file_batches = split_files_into_batches("/src", batch_size=50)
+    
+    clones = [
+        create_clone(f"Update imports in batch {i+1}: {batch}")
+        for i, batch in enumerate(file_batches)
+    ]
+    
+    # Execute in parallel
+    results = parallel_execute(clones)
+    
+    # Merge results
+    merge_refactoring_results(results)
+```
+
+**Parallel Execution Results**:
+```
+Clone 1: Files 1-50
+- Updated 1,247 import statements
+- Fixed 47 broken imports
+- Time: 12 minutes
+
+Clone 2: Files 51-100  
+- Updated 1,156 import statements
+- Fixed 38 broken imports
+- Time: 11 minutes
+
+Clone 3: Files 101-150
+- Updated 1,089 import statements
+- Fixed 42 broken imports
+- Time: 13 minutes
+
+Total Time: 13 minutes (vs 45 minutes sequential)
+Success Rate: 100%
+Tests: All passing
+```
+
+### Example 3: Architecture Exploration
+
+**Scenario**: Evaluate different architecture approaches for new feature
+
+```python
+# Alfred's analysis
+task = UserRequest(
+    type="exploration",
+    description="Evaluate 3 different architectures for new feature X",
+    options=["microservices", "monolith", "modular_monolith"],
+    evaluation_criteria=["performance", "maintainability", "scalability", "development_speed"],
+    independence="high"  # Each architecture can be evaluated separately
+)
+
+# Decision: Apply Clone pattern for parallel exploration
+if task.independence > 0.7:
+    clones = []
+    
+    for architecture in task.options:
+        clone = create_clone(
+            f"Evaluate {architecture} architecture for feature X",
+            context_scope="full"
+        )
+        clones.append(clone)
+    
+    # Execute all clones in parallel
+    evaluation_results = parallel_execute(clones)
+    
+    # Synthesize results
+    recommendation = synthesize_evaluations(evaluation_results)
+```
+
+**Evaluation Results**:
+```
+Clone 1: Microservices Architecture
+- Performance: Excellent (9/10)
+- Maintainability: Good (7/10)
+- Scalability: Excellent (9/10)
+- Development Speed: Poor (4/10)
+- Recommendation: Best for large-scale, long-term projects
+
+Clone 2: Monolith Architecture  
+- Performance: Good (7/10)
+- Maintainability: Poor (4/10)
+- Scalability: Poor (3/10)
+- Development Speed: Excellent (9/10)
+- Recommendation: Good for small projects, quick MVP
+
+Clone 3: Modular Monolith
+- Performance: Good (8/10)
+- Maintainability: Good (8/10)
+- Scalability: Good (7/10)
+- Development Speed: Good (7/10)
+- Recommendation: Balanced approach, recommended for current project
+
+Final Recommendation: Modular Monolith (best balance for current needs)
+```
+
+## Advanced Examples
+
+### Example 4: Multi-Phase Project Restructuring
+
+**Scenario**: Complete project restructuring with multiple phases
+
+```python
+# Complex multi-step task requiring strategic decisions
+complex_task = UserRequest(
+    type="restructuring",
+    description="Restructure entire project for better maintainability",
+    phases=[
+        "directory_reorganization",
+        "package_refactoring", 
+        "documentation_update",
+        "test_migration",
+        "ci_cd_update",
+        "deployment_changes"
+    ],
+    estimated_duration="2-3 days",
+    risk_level="high"
+)
+
+# Create master clone for coordination
+master_clone = create_clone(
+    "Coordinate project restructuring across 6 phases",
+    context_scope="full",
+    learning_enabled=True
+)
+
+# Master clone creates specialist clones for each phase
+phase_clones = []
+for phase in complex_task.phases:
+    phase_clone = master_clone.create_sub_clone(
+        f"Execute {phase} phase",
+        dependencies=get_phase_dependencies(phase)
+    )
+    phase_clones.append(phase_clone)
+
+# Execute with dependency management
+execution_plan = master_clone.create_execution_plan(phase_clones)
+results = master_clone.execute_with_dependencies(execution_plan)
+```
+
+### Example 5: Learning-Based Optimization
+
+**Scenario**: Use previous learnings to optimize current task
+
+```python
+# Check for similar previous tasks
+previous_learnings = load_clone_learnings("migration")
+
+current_task = UserRequest(
+    type="migration",
+    description="Migrate from v0.15.2 to v0.16.0",
+    similarity_score=calculate_similarity(current_task, previous_learnings)
+)
+
+if current_task.similarity_score > 0.8:
+    # Use optimized approach based on learnings
+    optimized_approach = apply_learnings(
+        previous_learnings,
+        current_task
+    )
+    
+    clone = create_clone(
+        "Optimized migration based on previous experience",
+        learning_strategy="incremental_improvement"
+    )
+    
+    # Clone starts with proven approach
+    clone.apply_pre_validated_strategy(optimized_approach)
+```
+
+## Error Handling Examples
+
+### Example 6: Clone Recovery from Failure
+
+**Scenario**: Clone encounters unexpected conflict
+
+```python
+# Clone encounters merge conflict
+try:
+    clone.execute_migration_step()
+except MergeConflict as conflict:
+    # Auto-recovery attempt 1: Analyze conflict
+    conflict_analysis = clone.analyze_conflict(conflict)
+    
+    if conflict_analysis.resolvable_automatically:
+        # Apply automatic resolution
+        resolution = clone.resolve_conflict_automatically(conflict)
+        clone.continue_execution()
+    else:
+        # Save state and escalate to main Alfred
+        clone.save_failure_state(conflict)
+        clone.report_to_main_alfred({
+            "status": "blocked",
+            "conflict": conflict_analysis,
+            "suggestions": ["manual_resolution", "alternative_approach"]
+        })
+```
+
+## Performance Optimization Examples
+
+### Example 7: Resource-Efficient Clone Usage
+
+**Scenario**: Optimize clone usage for resource management
+
+```python
+# Resource monitoring during clone execution
+resource_monitor = CloneResourceMonitor()
+
+def create_resource_aware_clone(task_description):
+    """Create clone with resource constraints"""
+    return create_clone(
+        task_description,
+        resource_limits={
+            "max_tokens": 10000,
+            "max_execution_time": 1800,  # 30 minutes
+            "max_memory_usage": "512MB"
+        },
+        checkpoint_strategy="incremental"
+    )
+
+# Batch processing to minimize resource usage
+tasks = get_pending_tasks()
+optimized_batches = optimize_for_resources(tasks)
+
+for batch in optimized_batches:
+    clones = [create_resource_aware_clone(task) for task in batch]
+    
+    # Monitor resource usage
+    with resource_monitor:
+        results = parallel_execute(clones)
+        
+        # Adjust batch size based on performance
+        if resource_monitor.average_usage() > 0.8:
+            batch_size = max(1, batch_size - 1)
+        elif resource_monitor.average_usage() < 0.5:
+            batch_size = min(4, batch_size + 1)
+```
+
+## Integration Examples
+
+### Example 8: Integration with Git Workflow
+
+**Scenario**: Clone integrates with GitFlow for proper branch management
+
+```python
+# Clone creates proper GitFlow branches
+def create_gitflow_clone(feature_spec):
+    clone = create_clone(
+        f"Implement {feature_spec.id}",
+        git_integration=True
+    )
+    
+    # Clone handles Git workflow automatically
+    clone.setup_gitflow_environment({
+        "feature_branch": f"feature/{feature_spec.id}",
+        "target_branch": "develop",
+        "pr_template": "standard_feature_pr"
+    })
+    
+    return clone
+
+# Clone execution includes Git operations
+clone.execute_with_gitflow([
+    "create_feature_branch",
+    "implement_changes", 
+    "run_tests",
+    "create_commit",
+    "push_to_remote",
+    "create_pr",
+    "wait_for_review",
+    "merge_to_develop"
+])
+```

moai_adk/templates/.claude/skills/moai-alfred-clone-pattern/reference.md

@@ -0,0 +1,158 @@
+# Clone Pattern Reference
+
+## API Specification
+
+### Core Functions
+
+#### `should_create_clone(task) -> bool`
+**Description**: Determine if Clone pattern should be applied based on task characteristics
+
+**Parameters**:
+- `task` (Task): Task object with the following attributes:
+  - `domain` (str): Task domain (e.g., "ui", "backend", "db", "security", "ml")
+  - `steps` (int): Number of steps required
+  - `files` (int): Number of files affected
+  - `parallelizable` (bool): Whether task can be parallelized
+  - `uncertainty` (float): Uncertainty level (0.0-1.0)
+
+**Returns**: `bool` - True if Clone pattern should be used
+
+**Logic**:
+```python
+return (
+    task.domain not in ["ui", "backend", "db", "security", "ml"]
+    AND (
+        task.steps >= 5
+        or task.files >= 100
+        or task.parallelizable
+        or task.uncertainty > 0.5
+    )
+)
+```
+
+#### `create_clone(task_description, context_scope="full", learning_enabled=True) -> CloneInstance`
+**Description**: Create an autonomous Alfred Clone instance
+
+**Parameters**:
+- `task_description` (str): Clear, specific task description with defined goals
+- `context_scope` (str, optional): Context range - "full" or "domain" (default: "full")
+- `learning_enabled` (bool, optional): Whether to save learning memory (default: True)
+
+**Returns**: `CloneInstance` - Independent executable clone
+
+**Clone Capabilities**:
+- Full project context access
+- All MoAI-ADK tools available
+- All 55 Skills accessible
+- TRUST 5 principles enforced
+- @TAG chain integrity maintained
+
+### Decision Matrix
+
+| Task Type | Domain Expertise | Steps | Files | Parallelizable | Uncertainty | Use Clone |
+|-----------|------------------|-------|-------|----------------|-------------|-----------|
+| Large Migration | No | 8+ | 50+ | Yes | High | ✅ |
+| UI Component Design | Yes | 3 | 5 | No | Low | ❌ (Use Specialist) |
+| Import Refactoring | No | 2 | 200+ | Yes | Medium | ✅ |
+| Database Optimization | Yes | 6 | 10 | No | Medium | ❌ (Use Specialist) |
+| Architecture Exploration | No | 5+ | 20+ | Yes | High | ✅ |
+
+## Integration Points
+
+### 4-Step Workflow Logic
+- **Step 1 (Intent Understanding)**: Clone pattern decision made here
+- **Step 2 (Plan Creation)**: Task delegated to clone if pattern applies
+- **Step 3 (Task Execution)**: Clone executes autonomously
+- **Step 4 (Report & Commit)**: Clone reports back to main Alfred
+
+### TRUST 5 Principles
+All clones must adhere to TRUST 5 principles:
+1. **Test First**: Implement tests before code
+2. **Readable**: Maintain clear, documented code
+3. **Unified**: Follow project conventions
+4. **Secured**: No security vulnerabilities
+5. **Trackable**: Complete @TAG chain
+
+### @TAG System
+- Clones maintain @TAG chain integrity
+- All decisions documented with @TAG references
+- Clone learnings tagged with @CLONE-LEARNING
+
+## Error Handling
+
+### Clone Failure Recovery
+1. **Auto-recovery**: Clone attempts self-debugging first
+2. **Context preservation**: Failed state saved for analysis
+3. **Main Alfred intervention**: Only if auto-recovery fails
+4. **Rollback capability**: Always maintain rollback path
+
+### Memory Management
+```python
+# Clone learning storage structure
+{
+  "migration": [
+    {
+      "timestamp": "2025-11-05T10:30:00Z",
+      "success": true,
+      "approach_used": "incremental_migration",
+      "pitfalls_discovered": ["config_conflicts", "hook_compatibility"],
+      "optimization_tips": ["pre_validation", "backup_critical_files"]
+    }
+  ]
+}
+```
+
+## Performance Considerations
+
+### Resource Usage
+- **Token cost**: Clones use tokens like any Claude session
+- **Time efficiency**: Parallel processing reduces overall time
+- **Memory**: Learning storage is minimal (JSON structure)
+
+### Optimization Tips
+1. **Batch similar tasks**: Create clones for related work items
+2. **Limit concurrent clones**: 3-4 clones maximum for resource efficiency
+3. **Reuse learnings**: Check memory before creating new clones
+4. **Cleanup old data**: Remove learnings older than 6 months
+
+## Security & Safety
+
+### Clone Constraints
+- Cannot modify clone creation logic itself
+- Must maintain TRUST 5 principles
+- Cannot access other clone sessions
+- Limited to project-scoped actions
+
+### Safety Mechanisms
+1. **Context isolation**: Each clone has isolated context
+2. **Permission inheritance**: Clones inherit main Alfred's permissions
+3. **Audit trail**: All actions logged with @TAG references
+4. **Emergency stop**: Main Alfred can terminate any clone
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Clone not responding
+**Solution**: Check context scope, recreate with broader permissions
+
+**Issue**: Clone making wrong decisions
+**Solution**: Review task description clarity, add specific constraints
+
+**Issue**: Parallel clones conflicting
+**Solution**: Use non-overlapping file scopes, implement coordination
+
+**Issue**: Learning not saving
+**Solution**: Check .moai/memory/ directory permissions
+
+### Debug Commands
+```bash
+# Check clone learnings
+cat .moai/memory/clone-learnings.json
+
+# Verify clone permissions
+ls -la .moai/
+
+# Check @TAG integrity
+find . -name "*.py" -exec grep "@TAG" {} \;
+```