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

moai_adk/templates/.claude/skills/moai-project-template-optimizer/README.md

@@ -0,0 +1,49 @@
+# Project Template Optimizer
+
+Handle template comparison and optimization workflows including backup detection, smart merging, and update completion reporting.
+
+## Purpose
+
+Manages intelligent template comparison and optimization workflows, detecting existing backups, comparing template versions, and performing smart merges that preserve user customizations while maintaining the latest template structure.
+
+## Core Workflow
+
+1. **Backup Discovery** - Find and analyze existing project backups
+2. **Template Comparison** - Compare current files with backup and package templates  
+3. **Smart Merge** - Preserve user customizations while applying template updates
+4. **Update Completion** - Report changes and maintain synchronization
+
+## When to Use
+
+- After moai-adk version updates
+- When template conflicts are detected
+- During project optimization workflows
+- When synchronizing local and package templates
+
+## Quick Start
+
+```bash
+# Run template optimization
+Skill("moai-project-template-optimizer")
+
+# Alfred will:
+# 1. Scan for backups in .moai-backups/
+# 2. Compare template versions
+# 3. Propose smart merge strategy
+# 4. Execute with user approval
+```
+
+## Features
+
+- **Automatic Backup Detection** - Finds existing project backups
+- **Intelligent Comparison** - Analyzes differences between versions
+- **Smart Merging** - Preserves user customizations
+- **Conflict Resolution** - Handles template vs user content conflicts
+- **Update Reporting** - Comprehensive change documentation
+
+## Files Structure
+
+- `SKILL.md` - Complete workflow documentation
+- `examples.md` - Practical usage examples
+- `reference.md` - Technical implementation details
+- `README.md` - This overview

moai_adk/templates/.claude/skills/moai-project-template-optimizer/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: moai-project-template-optimizer
+description: Handle template comparison and optimization workflows including backup detection, smart merging, and update completion reporting
+version: 1.0.0
+freedom: medium
+type: project
+tags: [project, template, optimization, backup, merge, comparison]
+tier: alfred
+---
+
+# MoAI Project Template Optimizer
+
+This skill manages intelligent template comparison and optimization workflows, detecting existing backups, comparing template versions, and performing smart merges that preserve user customizations while maintaining the latest template structure.
+
+## Core Responsibility
+
+Handle comprehensive template optimization workflows including:
+- Backup discovery and analysis in `.moai-backups/` directory
+- Template comparison between current files and backup versions
+- Smart merge procedures that preserve user customizations
+- Template default detection and user content extraction
+- Version management and HISTORY section updates
+- Configuration updates with optimization flags
+- Rollback capability and restore operations
+
+## Workflow Phases
+
+### Phase 1: Backup Discovery & Analysis
+
+**Purpose**: Automatically discover and analyze existing project backups
+**Trigger**: Skill invocation or moai-adk version update detection
+
+**Process**:
+1. **Backup Directory Scan**
+   ```bash
+   # Check for .moai-backups/ directory
+   if [ -d ".moai-backups/" ]; then
+       # List available backups with timestamps
+       ls -la .moai-backups/ | grep "backup-"
+   fi
+   ```
+
+2. **Backup Content Analysis**
+   - Read backup metadata and configuration files
+   - Identify template files vs user customizations
+   - Analyze backup creation timestamps and versions
+   - Detect backup completeness and integrity
+
+3. **Backup Selection Strategy**
+   - Most recent backup (default)
+   - User-specified backup version
+   - Backup with specific features or configurations
+
+### Phase 2: Template Comparison Engine
+
+**Purpose**: Detect differences between current templates and backup versions
+**Method**: Intelligent file comparison with template-aware parsing
+
+**Comparison Matrix**:
+```
+File Type          | Comparison Strategy     | Merge Priority
+------------------ | ----------------------- | --------------
+.claude/settings.json | Structured JSON diff   | Template defaults
+.moai/config.json   | User config preservation | User customizations
+CLAUDE.md          | Section-based diff      | User content
+Hook files         | Code-aware diff         | Template updates
+Skills             | Content analysis        | Template defaults
+```
+
+**Difference Detection**:
+1. **Template Default Detection**: Identify original template content
+2. **User Customization Extraction**: Isolate user modifications
+3. **Version Compatibility Check**: Ensure merge compatibility
+4. **Conflict Identification**: Flag unresolvable differences
+
+### Phase 3: Smart Merge Algorithm
+
+**Purpose**: Preserve user customizations while updating template structure
+**Strategy**: Three-way merge with intelligence
+
+**Merge Process**:
+1. **Extraction Phase**
+   ```python
+   # Extract user customizations from backup
+   user_customizations = extract_user_content(backup_files)
+   
+   # Get latest template defaults
+   template_defaults = get_current_templates()
+   
+   # Analyze current project state
+   current_state = analyze_current_project()
+   ```
+
+2. **Merge Strategy**
+   - **Template defaults**: Always use latest template version
+   - **User configurations**: Preserve from backup with compatibility updates
+   - **Custom content**: Extract and merge with new structure
+   - **Deprecated features**: Flag and offer migration options
+
+3. **Conflict Resolution**
+   - Template conflicts: Prefer latest template
+   - User config conflicts: Preserve user choice with warnings
+   - Structural conflicts: Create merge report with resolution options
+
+### Phase 4: Template Default Detection
+
+**Purpose**: Identify and preserve only non-template content during updates
+**Method**: Pattern recognition and content analysis
+
+**Detection Patterns**:
+```
+Template Indicators          | User Content Indicators
+---------------------------- | -------------------------
+"{{PROJECT_NAME}}"          | Specific project names
+"{{CONVERSATION_LANGUAGE}}" | Actual language codes
+"src/moai_adk/templates/"  | Custom file paths
+Template placeholders       | Real configuration values
+Default examples           | Custom implementations
+```
+
+**Content Classification**:
+1. **Template Content**: Default placeholders, examples, standard structure
+2. **User Content**: Custom configurations, specific implementations, personal settings
+3. **Mixed Content**: Template files with user modifications (requires careful extraction)
+
+### Phase 5: Version Management & History
+
+**Purpose**: Maintain version tracking and update history sections
+**Output**: Comprehensive update reports and history tracking
+
+**Version Tracking**:
+```json
+{
+  "template_version": "0.17.0",
+  "previous_version": "0.16.0",
+  "update_timestamp": "2025-11-05T12:00:00Z",
+  "backup_used": "backup-2025-10-15-v0.16.0",
+  "optimization_applied": true
+}
+```
+
+**HISTORY Section Updates**:
+- Document template version changes
+- Track optimization procedures applied
+- Record user customizations preserved
+- Note any manual interventions required
+
+### Phase 6: Configuration Updates
+
+**Purpose**: Update project configuration with optimization flags and metadata
+**Target**: `.moai/config.json` and related configuration files
+
+**Optimization Configuration**:
+```json
+{
+  "template_optimization": {
+    "last_optimized": "2025-11-05T12:00:00Z",
+    "backup_version": "backup-2025-10-15-v0.16.0",
+    "template_version": "0.17.0",
+    "customizations_preserved": ["language", "team_settings", "domains"],
+    "optimization_flags": {
+      "merge_applied": true,
+      "conflicts_resolved": 0,
+      "user_content_extracted": true
+    }
+  }
+}
+```
+
+## Usage Patterns
+
+### Standard Template Optimization
+```python
+# Complete optimization workflow
+Skill("moai-project-template-optimizer")
+
+# Executes: Backup Discovery → Template Comparison → Smart Merge → Configuration Update
+```
+
+### Backup Analysis Only
+```python
+# Analyze existing backups without making changes
+Skill("moai-project-template-optimizer", mode="analyze_only")
+```
+
+### Specific Backup Restoration
+```python
+# Restore from specific backup
+Skill("moai-project-template-optimizer", 
+       mode="restore", 
+       backup="backup-2025-10-15-v0.16.0")
+```
+
+### Rollback Operation
+```python
+# Rollback to previous state
+Skill("moai-project-template-optimizer", mode="rollback")
+```
+
+## Error Handling & Validation
+
+### Backup Validation
+- Backup directory existence and accessibility
+- Backup file integrity and completeness
+- Version compatibility checks
+- Required file presence validation
+
+### Merge Validation
+- Template version compatibility matrix
+- User configuration validation
+- File permission and accessibility checks
+- Dependency verification for updated templates
+
+### Rollback Validation
+- Rollback point availability
+- State restoration verification
+- Configuration consistency checks
+- Error recovery mechanisms
+
+## Integration Points
+
+### With Alfred Commands
+- `/alfred:0-project`: Post-initialization template optimization
+- `/alfred:3-sync`: Template synchronization after updates
+- moai-adk update workflows: Automatic optimization triggers
+
+### With Other Skills
+- `moai-alfred-autofixes`: Uses auto-fix safety protocols
+- `moai-project-language-initializer`: Preserves language configurations
+- `moai-alfred-ask-user-questions`: User confirmation workflows
+
+### With Package Templates
+- Template source: `src/moai_adk/templates/`
+- Synchronization: Local project paths
+- Version tracking: Template version management
+
+## Best Practices
+
+### For Template Updates
+- Always create backup before optimization
+- Verify user customizations preservation
+- Test merge results before finalizing
+- Document all changes for audit trail
+
+### For Backup Management
+- Regular backup creation schedules
+- Automated cleanup of old backups
+- Backup integrity verification
+- Version labeling consistency
+
+### For User Experience
+- Clear progress reporting during optimization
+- Detailed before/after analysis reports
+- User confirmation for major changes
+- Rollback options always available
+
+## Performance Optimizations
+
+### Efficient Comparison
+- Hash-based file comparison for speed
+- Incremental backup analysis
+- Parallel file processing for large projects
+- Caching of template default patterns
+
+### Smart Merge Optimization
+- Conflict prediction and prevention
+- User customization pattern caching
+- Template version compatibility matrix
+- Merge operation batching
+
+## Reporting & Analytics
+
+### Optimization Reports
+```
+Template Optimization Report
+Generated: 2025-11-05T12:00:00Z
+
+Backup Analysis:
+- Backups found: 3
+- Selected backup: backup-2025-10-15-v0.16.0
+- Backup integrity: 100%
+
+Template Comparison:
+- Files compared: 47
+- Differences found: 12
+- Conflicts detected: 0
+
+Smart Merge Results:
+- User customizations preserved: 8
+- Template updates applied: 12
+- Files modified: 15
+
+Configuration Updates:
+- Optimization flags set: true
+- Version tracking updated: true
+- History section updated: true
+
+Performance:
+- Total time: 2.3 seconds
+- Success rate: 100%
+```
+
+### Analytics Tracking
+- Optimization frequency and success rates
+- Common customization patterns
+- Template update adoption metrics
+- User satisfaction indicators
+
+## Implementation Notes
+
+This skill consolidates complex template optimization workflows into a focused, intelligent system that:
+
+- **Reduces complexity**: From 700+ lines to optimized skill implementation
+- **Improves reliability**: Automated backup and merge procedures
+- **Enhances user experience**: Smart customization preservation
+- **Maintains traceability**: Comprehensive version tracking and reporting
+- **Provides flexibility**: Multiple operation modes and rollback options
+
+The skill serves as the foundation for template lifecycle management and can be extended with additional optimization patterns as template structures evolve.

moai_adk/templates/.claude/skills/moai-project-template-optimizer/examples.md

@@ -0,0 +1,58 @@
+# Examples
+
+## Template Optimization Workflow
+
+### Basic Template Comparison
+```bash
+# Detect available backups
+ls -la .moai-backups/
+# backup-20251105-143022.tar.gz
+
+# Start optimization workflow
+Skill("moai-project-template-optimizer")
+
+# Alfred will:
+# 1. Detect backup files
+# 2. Compare with current templates
+# 3. Identify differences
+# 4. Propose smart merge strategy
+```
+
+### Smart Merge Example
+```python
+# Template optimization decision process
+def optimize_templates():
+    backup = find_latest_backup()
+    current = read_current_templates()
+    package = read_package_templates()
+    
+    # Analyze differences
+    differences = compare_all(backup, current, package)
+    
+    # Smart merge strategy
+    for diff in differences:
+        if diff.type == "user_customization":
+            # Preserve user changes
+            preserve_user_content(diff)
+        elif diff.type == "template_update":
+            # Apply package template updates
+            apply_template_update(diff)
+        elif diff.type == "conflict":
+            # Ask user for resolution
+            resolve_with_user_input(diff)
+```
+
+### Backup Analysis Example
+```
+Detected backup: backup-20251105-143022.tar.gz
+Created: 2025-11-05 14:30:22
+Size: 2.4MB
+Contents: 15 files, 3 directories
+
+Analysis:
+- 5 files have user customizations
+- 3 files need template updates
+- 2 files have conflicts requiring resolution
+
+Recommended action: Smart merge with user confirmation
+```

moai_adk/templates/.claude/skills/moai-project-template-optimizer/reference.md

@@ -0,0 +1,123 @@
+# Reference
+
+## Template Optimization Process
+
+### Phase 1: Backup Discovery
+```bash
+# Find backup files
+find .moai-backups/ -name "backup-*.tar.gz" -type f
+
+# Analyze backup contents
+tar -tzf backup-20251105-143022.tar.gz | head -20
+```
+
+### Phase 2: Comparison Analysis
+```python
+def compare_templates(backup_path, current_path, package_path):
+    """Compare template versions"""
+    
+    comparison = {
+        "backup_only": [],      # Files only in backup
+        "current_only": [],     # Files only in current  
+        "package_only": [],     # Files only in package
+        "all_three": [],        # Files in all versions
+        "differences": []       # Files with content differences
+    }
+    
+    # Perform detailed comparison
+    # ... comparison logic
+    
+    return comparison
+```
+
+### Phase 3: Smart Merge Strategy
+```python
+def smart_merge_strategy(comparison_result):
+    """Determine optimal merge approach"""
+    
+    strategy = {
+        "preserve_user": [],    # Keep user customizations
+        "update_template": [],  # Apply template updates
+        "resolve_conflict": []  # Need user input
+    }
+    
+    for file_info in comparison_result.differences:
+        if file_info.has_user_customizations:
+            if file_info.template_has_updates:
+                strategy["resolve_conflict"].append(file_info)
+            else:
+                strategy["preserve_user"].append(file_info)
+        else:
+            strategy["update_template"].append(file_info)
+    
+    return strategy
+```
+
+## Integration Points
+
+### With Alfred Commands
+- `/alfred:0-project` - Initial project setup optimization
+- Template updates - Automatic detection and optimization
+- Version upgrades - Template migration workflows
+
+### With Template System
+- Package templates - Source of truth for latest versions
+- Local templates - User customizations and modifications
+- Backup system - Rollback and recovery capabilities
+
+## File Locations
+
+### Template Paths
+- **Package Templates**: `src/moai_adk/templates/.claude/`
+- **Local Templates**: `.claude/`
+- **Backup Storage**: `.moai-backups/`
+
+### Critical Files to Monitor
+- `.claude/settings.json` - Claude Code configuration
+- `.claude/hooks/` - Hook scripts
+- `.moai/config.json` - MoAI project configuration
+- Template directories and files
+
+## Conflict Resolution Patterns
+
+### User Customizations vs Template Updates
+```python
+def resolve_template_conflict(file_path, backup_content, current_content, template_content):
+    """Resolve conflicts between user customizations and template updates"""
+    
+    # Identify user customizations
+    user_changes = diff_files(backup_content, current_content)
+    
+    # Identify template updates  
+    template_changes = diff_files(backup_content, template_content)
+    
+    # Check for conflicts
+    conflicts = find_conflicts(user_changes, template_changes)
+    
+    if not conflicts:
+        # No conflicts - merge both
+        return merge_changes(current_content, template_changes)
+    else:
+        # Conflicts exist - need user input
+        return request_user_resolution(file_path, conflicts)
+```
+
+### Configuration File Merging
+```python
+def merge_config_files(backup_config, current_config, template_config):
+    """Smart merge for configuration files"""
+    
+    merged = {}
+    
+    # Preserve user settings
+    for key, value in current_config.items():
+        if key not in template_config or current_config[key] != template_config[key]:
+            merged[key] = value
+    
+    # Add new template settings
+    for key, value in template_config.items():
+        if key not in merged:
+            merged[key] = value
+    
+    return merged
+```