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

moai_adk/templates/.claude/skills/moai-project-config-manager/README.md

@@ -0,0 +1,87 @@
+# moai-project-config-manager
+
+## Overview
+
+The `moai-project-config-manager` skill provides comprehensive configuration management for MoAI projects, handling all `.moai/config.json` CRUD operations with robust validation, error handling, and intelligent merge strategies.
+
+## Key Features
+
+- **Complete CRUD Operations**: Create, Read, Update, Delete configuration sections
+- **Validation Engine**: Pre-save validation for all configuration changes
+- **Merge Strategy**: Preserve unmodified sections while updating selected ones
+- **Error Recovery**: Handle missing files, invalid JSON, permission issues
+- **Batch Updates**: Handle multiple setting changes in single operation
+- **Backup & Restore**: Automatic backup before major changes
+- **Interactive Workflows**: User-friendly setting modification with TUI surveys
+
+## Quick Start
+
+```python
+# Interactive configuration management
+Skill("moai-project-config-manager")
+
+# Programmatic update
+Skill("moai-project-config-manager", action="update", changes={
+    "language": {
+        "conversation_language": "en",
+        "conversation_language_name": "English"
+    }
+})
+
+# Validate configuration
+Skill("moai-project-config-manager", action="validate")
+```
+
+## Configuration Sections Managed
+
+1. **Language Settings**: Conversation language and agent prompt language
+2. **User Settings**: User nickname and preferences
+3. **GitHub Settings**: Auto-delete branches and SPEC git workflow
+4. **Report Generation**: Enable/Minimal/Disable with token optimization
+5. **Project Domains**: Multi-select domain configuration
+
+## Files
+
+- `SKILL.md` - Main skill documentation and workflow guide
+- `reference.md` - Complete API reference and schema documentation
+- `examples.md` - Comprehensive usage examples and integration patterns
+- `validate.py` - Skill structure validation script
+
+## Integration
+
+This skill integrates seamlessly with Alfred commands:
+- `/alfred:0-project` - Project initialization and setting updates
+- `/alfred:1-plan` - Configuration-aware planning
+- `/alfred:2-run` - Configuration-guided execution
+- `/alfred:3-sync` - Configuration synchronization
+
+## Validation
+
+Run the included validation script to verify skill structure:
+
+```bash
+python3 validate.py
+```
+
+## Size and Complexity
+
+- **Total Documentation**: ~62KB (vs 600+ lines of original command)
+- **Structured Approach**: Modular, reusable, maintainable
+- **Comprehensive Coverage**: All configuration management workflows
+- **Error Handling**: Robust error recovery and validation
+- **Performance**: Optimized for fast operations and minimal resource usage
+
+## Benefits
+
+1. **Reduced Complexity**: Extracted 600+ line command into focused skill
+2. **Reusability**: Can be used across different Alfred commands
+3. **Maintainability**: Clear separation of concerns and documentation
+4. **Reliability**: Comprehensive validation and error handling
+5. **User Experience**: Interactive workflows with clear feedback
+
+---
+
+**Generated by**: skill-factory agent  
+**Created**: 2025-11-05  
+**Version**: 1.0.0  
+**Status**: Production Ready

moai_adk/templates/.claude/skills/moai-project-config-manager/SKILL.md

@@ -0,0 +1,552 @@
+---
+name: moai-project-config-manager
+version: 1.0.0
+created: 2025-11-05
+updated: 2025-11-05
+status: active
+description: Complete config.json CRUD operations with validation, merge strategy, and error recovery
+freedom: medium
+type: project
+tags: [project, configuration, management, validation, crud]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - AskUserQuestion
+  - Bash
+---
+
+# Project Configuration Manager - Skill Guide
+
+## Skill Metadata
+
+| Field | Value |
+| ----- | ----- |
+| **Skill Name** | moai-project-config-manager |
+| **Version** | 1.0.0 (2025-11-05) |
+| **Core Function** | Configuration file lifecycle management |
+| **Scope** | All `.moai/config.json` operations |
+| **Freedom** | Medium (guided automation) |
+
+---
+
+## What It Does
+
+**Purpose**: Centralized management of all MoAI project configuration operations with robust validation, error handling, and intelligent merge strategies.
+
+**Key capabilities**:
+- ✅ **Complete CRUD**: Create, Read, Update, Delete configuration sections
+- ✅ **Validation Engine**: Pre-save validation for all configuration changes
+- ✅ **Merge Strategy**: Preserve unmodified sections while updating selected ones
+- ✅ **Error Recovery**: Handle missing files, invalid JSON, permission issues
+- ✅ **Batch Updates**: Handle multiple setting changes in single operation
+- ✅ **Backup & Restore**: Automatic backup before major changes
+- ✅ **Interactive Workflows**: User-friendly setting modification with TUI surveys
+
+---
+
+## Core Configuration Structure
+
+The skill manages these main configuration sections:
+
+### 1. Language Settings
+```json
+"language": {
+  "conversation_language": "ko|en|ja|zh",
+  "conversation_language_name": "한국어|English|日本語|中文",
+  "agent_prompt_language": "english|localized"
+}
+```
+
+### 2. User Settings
+```json
+"user": {
+  "nickname": "string (max 20 chars)"
+}
+```
+
+### 3. GitHub Settings
+```json
+"github": {
+  "auto_delete_branches": true|false,
+  "spec_git_workflow": "feature_branch|develop_direct|per_spec"
+}
+```
+
+### 4. Report Generation
+```json
+"report_generation": {
+  "enabled": true|false,
+  "auto_create": true|false,
+  "user_choice": "Enable|Minimal|Disable"
+}
+```
+
+### 5. Project Domains
+```json
+"stack": {
+  "selected_domains": ["frontend", "backend", "data", "devops", "security"]
+}
+```
+
+---
+
+## Workflow: Configuration Management Operations
+
+### Phase 1: Load & Validate
+
+**Always validate before operations**:
+
+```python
+# 1. Check file existence
+if not Path(".moai/config.json").exists():
+    raise ConfigError("Configuration file not found")
+
+# 2. Validate JSON structure
+try:
+    config = json.loads(Path(".moai/config.json").read_text())
+except json.JSONDecodeError as e:
+    raise ConfigError(f"Invalid JSON in config.json: {e}")
+
+# 3. Validate required sections
+required_sections = ["language", "github", "report_generation"]
+for section in required_sections:
+    if section not in config:
+        raise ConfigError(f"Missing required section: {section}")
+```
+
+### Phase 2: Interactive Setting Selection
+
+**Present setting modification options**:
+
+```
+## Current Project Settings
+
+✅ **Language**: [current value]
+✅ **Nickname**: [current value] 
+✅ **Agent Prompt Language**: [current value]
+✅ **GitHub Auto-delete Branches**: [current value]
+✅ **SPEC Git Workflow**: [current value]
+✅ **Report Generation**: [current value]
+✅ **Selected Domains**: [current values]
+
+Which settings would you like to modify?
+```
+
+**Multi-select options** (AskUserQuestion):
+1. "🌍 Language & Agent Prompt Language"
+2. "👤 Nickname"
+3. "🔧 GitHub Settings" 
+4. "📊 Report Generation"
+5. "🎯 Project Domains"
+
+### Phase 3: Collect New Values (Batched Questions)
+
+**Language Section** (if selected):
+```python
+Question 1: "Which conversation language do you prefer?"
+Options: ["English", "한국어", "日本語", "中文"]
+
+Question 2: "Which agent prompt language should Alfred use?"
+Options: ["English (Global Standard)", "Selected Language (Localized)"]
+```
+
+**Nickname Section** (if selected):
+```python
+Question: "What would you like your nickname to be?"
+Type: text_input (max 20 characters)
+```
+
+**GitHub Section** (if selected):
+```python
+Question 1: "Auto-delete branches after merge?"
+Options: ["Yes, enable", "No, disable", "Keep current"]
+
+Question 2: "SPEC git workflow preference?"
+Options: ["Feature Branch + PR", "Direct Commit to Develop", "Decide per SPEC", "Keep current"]
+```
+
+**Report Generation Section** (if selected):
+```python
+Question: "Report generation preference?"
+Options: [
+  "📊 Enable (Full reports with 50-60 tokens)",
+  "⚡ Minimal (Essential reports with 20-30 tokens)", 
+  "🚫 Disable (No automatic reports, 0 tokens)"
+]
+```
+
+**Project Domains Section** (if selected):
+```python
+Question: "Select project domains?"
+Options: ["frontend", "backend", "data", "devops", "security", "Clear all", "Keep current"]
+Multi-select: true
+```
+
+### Phase 4: Intelligent Merge & Update
+
+**Update strategy - preserve unmodified sections**:
+
+```python
+def merge_config_updates(config, updates):
+    """Merge user updates into existing config"""
+    new_config = copy.deepcopy(config)
+    
+    for section, changes in updates.items():
+        if section in new_config:
+            new_config[section].update(changes)
+        else:
+            new_config[section] = changes
+    
+    return new_config
+```
+
+**Update mappings**:
+
+**Language Updates**:
+```python
+language_code_map = {
+    "English": "en", "한국어": "ko", "日本語": "ja", "中文": "zh"
+}
+agent_language_map = {
+    "English (Global Standard)": "english",
+    "Selected Language (Localized)": "localized"
+}
+```
+
+**GitHub Updates**:
+```python
+workflow_map = {
+    "Feature Branch + PR": "feature_branch",
+    "Direct Commit to Develop": "develop_direct", 
+    "Decide per SPEC": "per_spec"
+}
+```
+
+**Report Updates**:
+```python
+report_map = {
+    "📊 Enable": {"enabled": True, "auto_create": True, "user_choice": "Enable"},
+    "⚡ Minimal": {"enabled": True, "auto_create": False, "user_choice": "Minimal"},
+    "🚫 Disable": {"enabled": False, "auto_create": False, "user_choice": "Disable"}
+}
+```
+
+### Phase 5: Validation & Save
+
+**Pre-save validation**:
+```python
+def validate_config(config):
+    """Validate configuration before saving"""
+    errors = []
+    
+    # Validate language codes
+    valid_languages = ["en", "ko", "ja", "zh"]
+    if config.get("language", {}).get("conversation_language") not in valid_languages:
+        errors.append("Invalid conversation language")
+    
+    # Validate nickname length
+    nickname = config.get("user", {}).get("nickname", "")
+    if len(nickname) > 20:
+        errors.append("Nickname exceeds 20 characters")
+    
+    # Validate GitHub workflow
+    valid_workflows = ["feature_branch", "develop_direct", "per_spec"]
+    if config.get("github", {}).get("spec_git_workflow") not in valid_workflows:
+        errors.append("Invalid SPEC git workflow")
+    
+    return errors
+```
+
+**Atomic save with backup**:
+```python
+def save_config_safely(config):
+    """Save configuration with automatic backup"""
+    # Create backup
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    backup_path = f".moai/config.backup.{timestamp}.json"
+    shutil.copy2(".moai/config.json", backup_path)
+    
+    try:
+        # Validate before save
+        errors = validate_config(config)
+        if errors:
+            raise ConfigError(f"Validation failed: {errors}")
+        
+        # Atomic write
+        with open(".moai/config.json.tmp", "w") as f:
+            json.dump(config, f, indent=2, ensure_ascii=False)
+        
+        os.replace(".moai/config.json.tmp", ".moai/config.json")
+        
+    except Exception as e:
+        # Restore from backup on error
+        shutil.copy2(backup_path, ".moai/config.json")
+        raise ConfigError(f"Save failed, restored backup: {e}")
+```
+
+---
+
+## Error Handling & Recovery
+
+### Common Error Scenarios
+
+**1. Missing Configuration File**
+```python
+if not Path(".moai/config.json").exists():
+    # Create default configuration
+    default_config = create_default_config()
+    save_config_safely(default_config)
+    return "Created new configuration file with defaults"
+```
+
+**2. Invalid JSON**
+```python
+try:
+    config = json.loads(config_content)
+except json.JSONDecodeError:
+    # Try to repair common JSON issues
+    repaired = attempt_json_repair(config_content)
+    if repaired:
+        config = json.loads(repaired)
+        save_config_safely(config)
+    else:
+        raise ConfigError("Cannot repair invalid JSON")
+```
+
+**3. Permission Issues**
+```python
+try:
+    save_config_safely(config)
+except PermissionError:
+    # Try to fix permissions
+    os.chmod(".moai", 0o755)
+    os.chmod(".moai/config.json", 0o644)
+    save_config_safely(config)
+except Exception as e:
+    raise ConfigError(f"Permission denied: {e}")
+```
+
+### Validation Rules
+
+**Language Settings**:
+- `conversation_language`: Must be one of ["en", "ko", "ja", "zh"]
+- `conversation_language_name`: Must match language code
+- `agent_prompt_language`: Must be "english" or "localized"
+
+**User Settings**:
+- `nickname`: Max 20 characters, no special chars
+
+**GitHub Settings**:
+- `auto_delete_branches`: Must be boolean
+- `spec_git_workflow`: Must be one of ["feature_branch", "develop_direct", "per_spec"]
+
+**Report Settings**:
+- `enabled`: Must be boolean
+- `auto_create`: Must be boolean
+- `user_choice`: Must be one of ["Enable", "Minimal", "Disable"]
+
+**Domain Settings**:
+- `selected_domains`: Must be array of valid domain strings
+
+---
+
+## Usage Examples
+
+### Basic Configuration Update
+```python
+# Load current configuration
+Skill("moai-project-config-manager")
+
+# Interactive workflow:
+# 1. Display current settings
+# 2. User selects sections to modify
+# 3. Collect new values
+# 4. Validate and merge changes
+# 5. Save with backup
+```
+
+### Programmatic Updates
+```python
+# Direct configuration update (non-interactive)
+updates = {
+    "language": {
+        "conversation_language": "en",
+        "conversation_language_name": "English"
+    }
+}
+
+Skill("moai-project-config-manager", action="update", changes=updates)
+```
+
+### Configuration Validation
+```python
+# Validate existing configuration
+result = Skill("moai-project-config-manager", action="validate")
+if result.errors:
+    print(f"Configuration errors: {result.errors}")
+else:
+    print("Configuration is valid")
+```
+
+### Configuration Backup
+```python
+# Create manual backup
+backup_path = Skill("moai-project-config-manager", action="backup")
+print(f"Configuration backed up to: {backup_path}")
+```
+
+---
+
+## Best Practices
+
+### 1. Always Validate
+- Validate before every save operation
+- Check JSON structure, required fields, and value constraints
+- Provide clear error messages for validation failures
+
+### 2. Preserve Data
+- Always use merge strategy, never overwrite entire config
+- Create backups before major changes
+- Maintain backward compatibility
+
+### 3. User Experience
+- Show current values before asking for changes
+- Group related settings together
+- Use clear, descriptive option labels
+- Provide progress feedback during operations
+
+### 4. Error Recovery
+- Automatic backup creation
+- Graceful degradation on errors
+- Clear error messages with recovery suggestions
+- Rollback capability for failed operations
+
+---
+
+## Integration Points
+
+### With Alfred Commands
+- **`/alfred:0-project`**: Use for project initialization and setting updates
+- **`/alfred:1-plan`**: Access configuration for planning decisions
+- **`/alfred:2-run`**: Use configuration during execution
+- **`/alfred:3-sync`**: Update configuration based on project changes
+
+### With Other Skills
+- **`moai-alfred-ask-user-questions`**: Use for interactive setting collection
+- **`moai-skill-factory`**: Integrate with skill configuration management
+- **Domain-specific skills**: Respect configuration settings for behavior
+
+---
+
+## Configuration Schema Reference
+
+Complete configuration schema with validation rules:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "language": {
+      "type": "object",
+      "properties": {
+        "conversation_language": {
+          "type": "string",
+          "enum": ["en", "ko", "ja", "zh"]
+        },
+        "conversation_language_name": {
+          "type": "string",
+          "enum": ["English", "한국어", "日本語", "中文"]
+        },
+        "agent_prompt_language": {
+          "type": "string", 
+          "enum": ["english", "localized"]
+        }
+      },
+      "required": ["conversation_language", "conversation_language_name", "agent_prompt_language"]
+    },
+    "user": {
+      "type": "object",
+      "properties": {
+        "nickname": {
+          "type": "string",
+          "maxLength": 20,
+          "pattern": "^[a-zA-Z0-9가-힣ぁ-ゔ一-龯\\s]+$"
+        }
+      }
+    },
+    "github": {
+      "type": "object",
+      "properties": {
+        "auto_delete_branches": {"type": "boolean"},
+        "spec_git_workflow": {
+          "type": "string",
+          "enum": ["feature_branch", "develop_direct", "per_spec"]
+        }
+      }
+    },
+    "report_generation": {
+      "type": "object",
+      "properties": {
+        "enabled": {"type": "boolean"},
+        "auto_create": {"type": "boolean"},
+        "user_choice": {
+          "type": "string",
+          "enum": ["Enable", "Minimal", "Disable"]
+        }
+      }
+    },
+    "stack": {
+      "type": "object",
+      "properties": {
+        "selected_domains": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["frontend", "backend", "data", "devops", "security"]
+          }
+        }
+      }
+    }
+  },
+  "required": ["language", "github", "report_generation"]
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Configuration not saving**:
+1. Check file permissions on `.moai/` directory
+2. Verify JSON syntax with online validator
+3. Check for disk space availability
+4. Look for backup files in `.moai/`
+
+**Validation errors**:
+1. Review error messages for specific constraint violations
+2. Check configuration schema reference
+3. Verify all required fields are present
+4. Ensure data types match schema
+
+**Merge conflicts**:
+1. Recent changes may overwrite manual edits
+2. Check backup files for previous versions
+3. Use `action="diff"` to see changes before applying
+4. Manual edit may be required for complex conflicts
+
+### Debug Mode
+
+Enable debug logging:
+```python
+Skill("moai-project-config-manager", debug=True)
+```
+
+This provides detailed output for:
+- Configuration loading steps
+- Validation process details
+- Merge operation results
+- Save operation status