moai-adk 0.35.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-workflow-project/reference.md

@@ -0,0 +1,275 @@
+# moai-workflow-project Reference
+
+Progressive Disclosure Level 2: Extended documentation for advanced users and integrators.
+
+---
+
+## API Reference
+
+### Core Classes
+
+MoaiMenuProject:
+- Purpose: Unified interface for all project management operations
+- Initialization: `MoaiMenuProject(project_path: str)`
+- Primary Methods:
+  - `initialize_complete_project(language, user_name, domains, project_type, optimization_enabled)` - Full project setup
+  - `generate_documentation_from_spec(spec_data)` - SPEC-driven doc generation
+  - `optimize_project_templates(options)` - Template optimization
+  - `get_project_status()` - Comprehensive status report
+  - `update_language_settings(settings)` - Language configuration update
+
+DocumentationManager:
+- Purpose: Template-based documentation generation
+- Key Methods:
+  - `generate_docs(project_type, language)` - Generate documentation set
+  - `update_docs_from_spec(spec_data)` - Update from SPEC data
+  - `export_docs(format, language)` - Multi-format export (md, html, pdf)
+  - `detect_project_type()` - Auto-detect project type
+
+LanguageInitializer:
+- Purpose: Language detection and configuration
+- Key Methods:
+  - `detect_project_language()` - Analyze project for language
+  - `create_multilingual_documentation_structure(language)` - Setup multilingual docs
+  - `localize_agent_prompts(base_prompt, language)` - Prompt localization
+  - `calculate_token_cost_impact(language)` - Token cost analysis
+
+TemplateOptimizer:
+- Purpose: Template analysis and optimization
+- Key Methods:
+  - `analyze_project_templates()` - Comprehensive template analysis
+  - `create_optimized_templates(options)` - Apply optimizations
+  - `create_backup()` - Create template backup
+  - `restore_from_backup(backup_id)` - Restore from backup
+
+---
+
+## Configuration Options
+
+### Project Configuration Schema
+
+```yaml
+project:
+  name: "string"              # Project display name
+  type: "string"              # web_application, mobile_app, cli_tool, library, ml_project
+  initialized_at: "datetime"  # ISO 8601 timestamp
+  version: "string"           # Semantic version
+
+language:
+  conversation_language: "string"   # en, ko, ja, zh, es, fr, de
+  agent_prompt_language: "string"   # english (cost-optimized) or localized
+  documentation_language: "string"  # Primary documentation language
+  code_comments: "string"           # Code comment language
+
+menu_system:
+  version: "string"           # Menu system version
+  fully_initialized: boolean  # Complete initialization status
+  modules_enabled: []         # List of enabled modules
+```
+
+### Optimization Options Schema
+
+```yaml
+backup_first: boolean                    # Create backup before optimization
+apply_size_optimizations: boolean        # Reduce template file sizes
+apply_performance_optimizations: boolean # Improve template performance
+apply_complexity_optimizations: boolean  # Reduce template complexity
+preserve_functionality: boolean          # Maintain all existing features
+max_complexity_score: number             # Maximum allowed complexity (1-10)
+```
+
+### Language Configuration Presets
+
+Supported Languages with Token Impact:
+
+| Language | Code | Locale       | Token Cost Impact |
+|----------|------|--------------|-------------------|
+| English  | en   | en_US.UTF-8  | 0% (baseline)     |
+| Korean   | ko   | ko_KR.UTF-8  | +20%              |
+| Japanese | ja   | ja_JP.UTF-8  | +25%              |
+| Chinese  | zh   | zh_CN.UTF-8  | +15%              |
+| Spanish  | es   | es_ES.UTF-8  | +5%               |
+| French   | fr   | fr_FR.UTF-8  | +5%               |
+| German   | de   | de_DE.UTF-8  | +5%               |
+
+---
+
+## Integration Patterns
+
+### Pattern 1: SPEC-Driven Documentation Workflow
+
+```python
+# Integration with /moai:1-plan and /moai:3-sync
+from moai_workflow_project import MoaiMenuProject
+
+# Initialize project system
+project = MoaiMenuProject("/path/to/project")
+
+# After /moai:1-plan generates SPEC
+spec_data = load_spec("SPEC-001")
+
+# Generate documentation from SPEC
+docs_result = project.generate_documentation_from_spec(spec_data)
+
+# Automatically creates:
+# - Feature documentation with requirements
+# - API documentation with endpoint details
+# - Architecture documentation
+# - Multilingual versions if configured
+```
+
+### Pattern 2: CI/CD Integration
+
+```python
+# Integration with GitHub Actions or similar
+from moai_workflow_project import MoaiMenuProject
+
+def ci_documentation_check(project_path: str) -> dict:
+    """Run documentation validation in CI pipeline."""
+    project = MoaiMenuProject(project_path)
+
+    # Get current documentation status
+    status = project.get_project_status()
+
+    # Validate completeness
+    validation_result = {
+        "docs_complete": status.documentation_completion >= 0.9,
+        "language_configured": status.language_configured,
+        "templates_optimized": status.templates_optimized,
+        "warnings": status.warnings,
+        "errors": status.errors
+    }
+
+    return validation_result
+```
+
+### Pattern 3: Multi-Project Template Sharing
+
+```python
+# Share optimized templates across projects
+from moai_workflow_project import TemplateOptimizer
+
+# Optimize master templates
+master_optimizer = TemplateOptimizer("/templates/master")
+optimized = master_optimizer.create_optimized_templates({
+    "backup_first": True,
+    "apply_all_optimizations": True
+})
+
+# Deploy to multiple projects
+for project_path in project_list:
+    project = MoaiMenuProject(project_path)
+    project.import_templates(optimized.templates)
+```
+
+### Pattern 4: Language-Aware Agent Delegation
+
+```python
+# Integrate with Alfred's delegation patterns
+def delegate_with_language_context(task: str, language: str):
+    """Delegate task with proper language context."""
+    project = MoaiMenuProject(".")
+
+    # Get localized prompt
+    localized_task = project.language_initializer.localize_agent_prompts(
+        base_prompt=task,
+        language=language
+    )
+
+    # Token cost analysis
+    cost_impact = project.language_initializer.calculate_token_cost_impact(language)
+
+    return {
+        "localized_task": localized_task,
+        "estimated_token_overhead": cost_impact
+    }
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+Issue: Documentation generation fails with template not found:
+- Cause: Template directory missing or corrupted
+- Solution: Run `project.template_optimizer.restore_from_backup()` or reinstall templates
+- Prevention: Always enable `backup_first` option before optimization
+
+Issue: Language detection returns incorrect language:
+- Cause: Insufficient language indicators in project files
+- Solution: Manually set language in configuration: `project.update_language_settings({"language.conversation_language": "ko"})`
+- Prevention: Include language comments in main source files
+
+Issue: Template optimization causes functionality loss:
+- Cause: Aggressive optimization removed necessary content
+- Solution: Restore from backup: `project.template_optimizer.restore_from_backup(backup_id)`
+- Prevention: Set `preserve_functionality: True` in optimization options
+
+Issue: Multilingual documentation structure incomplete:
+- Cause: Partial initialization or interrupted process
+- Solution: Re-run `project.language_initializer.create_multilingual_documentation_structure(language)`
+- Prevention: Ensure stable connection during initialization
+
+Issue: High token cost for non-English languages:
+- Cause: Localized agent prompts increase token usage
+- Solution: Use `agent_prompt_language: "english"` with `conversation_language: "ko"` for cost optimization
+- Prevention: Configure language settings before heavy usage
+
+### Diagnostic Commands
+
+```python
+# Full diagnostic report
+status = project.get_project_status()
+print(f"Initialization: {status.initialization_complete}")
+print(f"Language: {status.language_configuration}")
+print(f"Documentation: {status.documentation_completion}%")
+print(f"Templates: {status.template_status}")
+print(f"Errors: {status.errors}")
+print(f"Warnings: {status.warnings}")
+```
+
+### Log Locations
+
+- Project logs: `.moai/logs/project.log`
+- Template optimization logs: `.moai/logs/template-optimizer.log`
+- Language initialization logs: `.moai/logs/language-init.log`
+
+---
+
+## External Resources
+
+### Official Documentation
+
+- MoAI-ADK Documentation: https://github.com/moai-adk/docs
+- Claude Code Skills Guide: https://docs.anthropic.com/claude-code/skills
+- SPEC-First TDD Methodology: See `moai-foundation-core/modules/spec-first-tdd.md`
+
+### Related Skills
+
+- moai-foundation-core - Core execution patterns and SPEC workflow
+- moai-foundation-claude - Claude Code integration patterns
+- moai-workflow-docs - Unified documentation management
+- moai-workflow-templates - Template optimization strategies
+- moai-library-nextra - Advanced documentation architecture
+
+### Template Resources
+
+- Documentation Templates: `/templates/doc-templates/`
+- Product Template: `/templates/doc-templates/product-template.md`
+- Technical Template: `/templates/doc-templates/tech-template.md`
+- Structure Template: `/templates/doc-templates/structure-template.md`
+
+### Version History
+
+| Version | Date       | Changes                                           |
+|---------|------------|---------------------------------------------------|
+| 2.0.0   | 2025-11-27 | Integrated modular architecture                   |
+| 1.5.0   | 2025-11-20 | Added template optimization module                |
+| 1.0.0   | 2025-11-15 | Initial release with documentation management     |
+
+---
+
+Status: Reference Documentation Complete
+Last Updated: 2025-12-06
+Skill Version: 2.0.0

moai_adk/templates/.claude/skills/moai-workflow-project/schemas/config-schema.json

@@ -0,0 +1,316 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://moai-adk.github.io/schemas/moai-menu-project-config.json",
+  "title": "MoAI Menu Project Configuration",
+  "description": "Unified configuration schema for menu project management system",
+  "type": "object",
+  "version": "1.0.0",
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Configuration version following semantic versioning",
+      "default": "1.0.0"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "created_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Configuration creation timestamp"
+        },
+        "updated_at": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Configuration last update timestamp"
+        },
+        "migration_history": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "from_version": {"type": "string"},
+              "to_version": {"type": "string"},
+              "timestamp": {"type": "string", "format": "date-time"},
+              "description": {"type": "string"}
+            }
+          }
+        }
+      }
+    },
+    "project_settings": {
+      "type": "object",
+      "description": "Core project configuration",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "Project display name"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["web", "mobile", "desktop", "api", "library", "cli"],
+          "description": "Project type classification"
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Brief project description"
+        },
+        "author": {
+          "type": "string",
+          "description": "Project author or team"
+        },
+        "license": {
+          "type": "string",
+          "enum": ["MIT", "Apache-2.0", "GPL-3.0", "BSD-3-Clause", "ISC", "UNLICENSED"],
+          "description": "Project license type"
+        }
+      },
+      "required": ["name", "type"]
+    },
+    "batch_questions": {
+      "type": "object",
+      "description": "Batch questions processing configuration",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable batch questions functionality"
+        },
+        "max_questions": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 100,
+          "default": 50,
+          "description": "Maximum number of questions to process in batch"
+        },
+        "timeout_seconds": {
+          "type": "integer",
+          "minimum": 30,
+          "maximum": 3600,
+          "default": 300,
+          "description": "Timeout for batch processing in seconds"
+        },
+        "retry_attempts": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 10,
+          "default": 3,
+          "description": "Number of retry attempts for failed questions"
+        },
+        "output_format": {
+          "type": "string",
+          "enum": ["json", "yaml", "markdown", "csv"],
+          "default": "json",
+          "description": "Default output format for batch results"
+        },
+        "caching": {
+          "type": "object",
+          "properties": {
+            "enabled": {"type": "boolean", "default": true},
+            "ttl_hours": {"type": "integer", "minimum": 1, "default": 24},
+            "max_cache_size_mb": {"type": "integer", "minimum": 1, "default": 100}
+          }
+        }
+      }
+    },
+    "documentation": {
+      "type": "object",
+      "description": "Documentation generation and management settings",
+      "properties": {
+        "auto_generate": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically generate documentation on changes"
+        },
+        "format": {
+          "type": "string",
+          "enum": ["markdown", "html", "pdf", "all"],
+          "default": "markdown",
+          "description": "Documentation output format"
+        },
+        "include_api_docs": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include API documentation"
+        },
+        "include_examples": {
+          "type": "boolean",
+          "default": true,
+          "description": "Include code examples in documentation"
+        },
+        "template_engine": {
+          "type": "string",
+          "enum": ["jinja2", "handlebars", "mustache"],
+          "default": "jinja2",
+          "description": "Template engine for documentation generation"
+        },
+        "output_directory": {
+          "type": "string",
+          "default": "docs",
+          "description": "Directory for generated documentation"
+        },
+        "custom_templates": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "type": "string",
+              "description": "Path to custom template file"
+            }
+          }
+        }
+      }
+    },
+    "language_config": {
+      "type": "object",
+      "description": "Language and localization settings",
+      "properties": {
+        "default_language": {
+          "type": "string",
+          "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+          "default": "en",
+          "description": "Default language code (ISO 639-1)"
+        },
+        "supported_languages": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+          },
+          "uniqueItems": true,
+          "description": "List of supported language codes"
+        },
+        "auto_detect": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically detect user language preference"
+        },
+        "fallback_language": {
+          "type": "string",
+          "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+          "default": "en",
+          "description": "Fallback language when translation not available"
+        },
+        "translation_service": {
+          "type": "object",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "enum": ["google", "azure", "aws", "deepl", "local"],
+              "default": "local"
+            },
+            "api_key": {
+              "type": "string",
+              "description": "API key for translation service (if required)"
+            },
+            "cache_enabled": {
+              "type": "boolean",
+              "default": true
+            }
+          }
+        }
+      },
+      "required": ["default_language"]
+    },
+    "template_optimizer": {
+      "type": "object",
+      "description": "Template optimization and management settings",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable template optimization"
+        },
+        "optimization_level": {
+          "type": "string",
+          "enum": ["none", "basic", "aggressive", "maximum"],
+          "default": "basic",
+          "description": "Template optimization level"
+        },
+        "minification": {
+          "type": "boolean",
+          "default": false,
+          "description": "Minimize template output size"
+        },
+        "caching": {
+          "type": "object",
+          "properties": {
+            "enabled": {"type": "boolean", "default": true},
+            "strategy": {
+              "type": "string",
+              "enum": ["memory", "disk", "redis"],
+              "default": "memory"
+            },
+            "ttl_minutes": {"type": "integer", "minimum": 1, "default": 60}
+          }
+        },
+        "validation": {
+          "type": "object",
+          "properties": {
+            "strict_mode": {"type": "boolean", "default": false},
+            "check_syntax": {"type": "boolean", "default": true},
+            "check_security": {"type": "boolean", "default": true}
+          }
+        },
+        "custom_variables": {
+          "type": "object",
+          "description": "Custom template variables and their default values",
+          "additionalProperties": true
+        }
+      }
+    },
+    "project_initializer": {
+      "type": "object",
+      "description": "Project initialization configuration",
+      "properties": {
+        "default_template": {
+          "type": "string",
+          "description": "Default project template to use"
+        },
+        "auto_dependencies": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically install dependencies"
+        },
+        "git_init": {
+          "type": "boolean",
+          "default": true,
+          "description": "Initialize Git repository"
+        },
+        "create_virtual_env": {
+          "type": "boolean",
+          "default": true,
+          "description": "Create Python virtual environment"
+        },
+        "license_template": {
+          "type": "string",
+          "description": "Default license template"
+        },
+        "package_managers": {
+          "type": "object",
+          "properties": {
+            "python": {
+              "type": "object",
+              "properties": {
+                "enabled": {"type": "boolean", "default": true},
+                "tool": {"type": "string", "enum": ["pip", "poetry", "pipenv"], "default": "pip"}
+              }
+            },
+            "node": {
+              "type": "object",
+              "properties": {
+                "enabled": {"type": "boolean", "default": false},
+                "tool": {"type": "string", "enum": ["npm", "yarn", "pnpm"], "default": "npm"}
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "required": ["version", "project_settings"],
+  "additionalProperties": false
+}