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

"language": {
  "conversation_language": "ko|en|ja|zh",
  "conversation_language_name": "한국어|English|日本語|中文",
  "agent_prompt_language": "english|localized"
}

2. User Settings

"user": {
  "nickname": "string (max 20 chars)"
}

3. GitHub Settings

"github": {
  "auto_delete_branches": true|false,
  "spec_git_workflow": "feature_branch|develop_direct|per_spec"
}

4. Report Generation

"report_generation": {
  "enabled": true|false,
  "auto_create": true|false,
  "user_choice": "Enable|Minimal|Disable"
}

5. Project Domains

"stack": {
  "selected_domains": ["frontend", "backend", "data", "devops", "security"]
}

---

Workflow: Configuration Management Operations

Phase 1: Load & Validate

Always validate before operations:

# 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):

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):

Question: "What would you like your nickname to be?"
Type: text_input (max 20 characters)

GitHub Section (if selected):

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):

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):

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:

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:

language_code_map = {
    "English": "en", "한국어": "ko", "日本語": "ja", "中文": "zh"
}
agent_language_map = {
    "English (Global Standard)": "english",
    "Selected Language (Localized)": "localized"
}

GitHub Updates:

workflow_map = {
    "Feature Branch + PR": "feature_branch",
    "Direct Commit to Develop": "develop_direct", 
    "Decide per SPEC": "per_spec"
}

Report Updates:

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:

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:

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

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

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

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

# 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

# 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

# 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

# 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:

{
  "$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:

Skill("moai-project-config-manager", debug=True)

This provides detailed output for:

• Configuration loading steps
• Validation process details
• Merge operation results
• Save operation status