moai-adk 0.8.0__py3-none-any.whl → 0.8.2__py3-none-any.whl

moai_adk/core/template_engine.py

@@ -0,0 +1,253 @@
+"""
+Template engine for parameterizing GitHub templates and other configuration files.
+
+Supports Jinja2-style templating with variable substitution and conditional sections.
+Enables users to customize MoAI-ADK templates for their own projects.
+
+@TAG:TEMPLATE-ENGINE-001 - Template variable substitution system
+@TAG:GITHUB-CUSTOMIZATION-001 - GitHub template parameterization
+"""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from jinja2 import (
+    Environment,
+    FileSystemLoader,
+    StrictUndefined,
+    TemplateNotFound,
+    TemplateRuntimeError,
+    TemplateSyntaxError,
+)
+
+
+class TemplateEngine:
+    """
+    Jinja2-based template engine for MoAI-ADK configuration and GitHub templates.
+
+    Supports:
+    - Variable substitution: {{PROJECT_NAME}}, {{SPEC_DIR}}, etc.
+    - Conditional sections: {{#ENABLE_TRUST_5}}...{{/ENABLE_TRUST_5}}
+    - File-based and string-based template rendering
+    """
+
+    def __init__(self, strict_undefined: bool = False):
+        """
+        Initialize the template engine.
+
+        Args:
+            strict_undefined: If True, raise error on undefined variables.
+                             If False, render undefined variables as empty strings.
+        """
+        self.strict_undefined = strict_undefined
+        self.undefined_behavior = StrictUndefined if strict_undefined else None
+
+    def render_string(
+        self,
+        template_string: str,
+        variables: Dict[str, Any]
+    ) -> str:
+        """
+        Render a Jinja2 template string with provided variables.
+
+        Args:
+            template_string: The template content as a string
+            variables: Dictionary of variables to substitute
+
+        Returns:
+            Rendered template string
+
+        Raises:
+            TemplateSyntaxError: If template syntax is invalid
+            TemplateRuntimeError: If variable substitution fails in strict mode
+        """
+        try:
+            env = Environment(
+                undefined=self.undefined_behavior,
+                trim_blocks=False,
+                lstrip_blocks=False
+            )
+            template = env.from_string(template_string)
+            return template.render(**variables)
+        except (TemplateSyntaxError, TemplateRuntimeError) as e:
+            raise RuntimeError(f"Template rendering error: {e}")
+
+    def render_file(
+        self,
+        template_path: Path,
+        variables: Dict[str, Any],
+        output_path: Optional[Path] = None
+    ) -> str:
+        """
+        Render a Jinja2 template file with provided variables.
+
+        Args:
+            template_path: Path to the template file
+            variables: Dictionary of variables to substitute
+            output_path: If provided, write rendered content to this path
+
+        Returns:
+            Rendered template content
+
+        Raises:
+            FileNotFoundError: If template file doesn't exist
+            TemplateSyntaxError: If template syntax is invalid
+            TemplateRuntimeError: If variable substitution fails in strict mode
+        """
+        if not template_path.exists():
+            raise FileNotFoundError(f"Template file not found: {template_path}")
+
+        template_dir = template_path.parent
+        template_name = template_path.name
+
+        try:
+            env = Environment(
+                loader=FileSystemLoader(str(template_dir)),
+                undefined=self.undefined_behavior,
+                trim_blocks=False,
+                lstrip_blocks=False
+            )
+            template = env.get_template(template_name)
+            rendered = template.render(**variables)
+
+            if output_path:
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                output_path.write_text(rendered, encoding='utf-8')
+
+            return rendered
+        except TemplateNotFound:
+            raise FileNotFoundError(f"Template not found in {template_dir}: {template_name}")
+        except (TemplateSyntaxError, TemplateRuntimeError) as e:
+            raise RuntimeError(f"Template rendering error in {template_path}: {e}")
+
+    def render_directory(
+        self,
+        template_dir: Path,
+        output_dir: Path,
+        variables: Dict[str, Any],
+        pattern: str = "**/*.{md,yml,yaml,json}"
+    ) -> Dict[str, str]:
+        """
+        Render all template files in a directory.
+
+        Args:
+            template_dir: Source directory containing templates
+            output_dir: Destination directory for rendered files
+            variables: Dictionary of variables to substitute
+            pattern: Glob pattern for files to process (default: template files)
+
+        Returns:
+            Dictionary mapping input paths to rendered content
+
+        Raises:
+            FileNotFoundError: If template directory doesn't exist
+        """
+        if not template_dir.exists():
+            raise FileNotFoundError(f"Template directory not found: {template_dir}")
+
+        results = {}
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+        for template_file in template_dir.glob(pattern):
+            if template_file.is_file():
+                relative_path = template_file.relative_to(template_dir)
+                output_file = output_dir / relative_path
+
+                try:
+                    rendered = self.render_file(template_file, variables, output_file)
+                    results[str(relative_path)] = rendered
+                except Exception as e:
+                    raise RuntimeError(f"Error rendering {relative_path}: {e}")
+
+        return results
+
+    @staticmethod
+    def get_default_variables(config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Extract template variables from project configuration.
+
+        Args:
+            config: Project configuration dictionary (from .moai/config.json)
+
+        Returns:
+            Dictionary of template variables
+        """
+        github_config = config.get("github", {}).get("templates", {})
+        project_config = config.get("project", {})
+
+        return {
+            # Project information
+            "PROJECT_NAME": project_config.get("name", "MyProject"),
+            "PROJECT_DESCRIPTION": project_config.get("description", ""),
+            "PROJECT_MODE": project_config.get("mode", "team"),  # team or personal
+
+            # Directory structure
+            "SPEC_DIR": github_config.get("spec_directory", ".moai/specs"),
+            "DOCS_DIR": github_config.get("docs_directory", ".moai/docs"),
+            "TEST_DIR": github_config.get("test_directory", "tests"),
+
+            # Feature flags
+            "ENABLE_TRUST_5": github_config.get("enable_trust_5", True),
+            "ENABLE_TAG_SYSTEM": github_config.get("enable_tag_system", True),
+            "ENABLE_ALFRED_COMMANDS": github_config.get("enable_alfred_commands", True),
+
+            # Language configuration
+            "CONVERSATION_LANGUAGE": project_config.get("conversation_language", "en"),
+            "CONVERSATION_LANGUAGE_NAME": project_config.get("conversation_language_name", "English"),
+
+            # Additional metadata
+            "MOAI_VERSION": config.get("moai", {}).get("version", "0.7.0"),
+        }
+
+
+class TemplateVariableValidator:
+    """
+    Validates template variables for completeness and correctness.
+    Ensures all required variables are present before rendering.
+    """
+
+    REQUIRED_VARIABLES = {
+        "PROJECT_NAME": str,
+        "SPEC_DIR": str,
+        "DOCS_DIR": str,
+        "TEST_DIR": str,
+    }
+
+    OPTIONAL_VARIABLES = {
+        "PROJECT_DESCRIPTION": (str, type(None)),
+        "PROJECT_MODE": str,
+        "ENABLE_TRUST_5": bool,
+        "ENABLE_TAG_SYSTEM": bool,
+        "ENABLE_ALFRED_COMMANDS": bool,
+        "CONVERSATION_LANGUAGE": str,
+        "CONVERSATION_LANGUAGE_NAME": str,
+    }
+
+    @classmethod
+    def validate(cls, variables: Dict[str, Any]) -> tuple[bool, list[str]]:
+        """
+        Validate template variables.
+
+        Args:
+            variables: Dictionary of variables to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        errors = []
+
+        # Check required variables
+        for var_name, var_type in cls.REQUIRED_VARIABLES.items():
+            if var_name not in variables:
+                errors.append(f"Missing required variable: {var_name}")
+            elif not isinstance(variables[var_name], var_type):
+                errors.append(f"Invalid type for {var_name}: expected {var_type.__name__}, got {type(variables[var_name]).__name__}")
+
+        # Check optional variables (if present)
+        for var_name, var_type in cls.OPTIONAL_VARIABLES.items():
+            if var_name in variables:
+                if not isinstance(variables[var_name], var_type):
+                    type_names = " or ".join(t.__name__ for t in var_type) if isinstance(var_type, tuple) else var_type.__name__
+                    errors.append(f"Invalid type for {var_name}: expected {type_names}, got {type(variables[var_name]).__name__}")
+
+        return len(errors) == 0, errors

moai_adk/templates/.claude/agents/alfred/cc-manager.md

@@ -34,9 +34,32 @@ model: sonnet
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates Claude Code configuration requirements to English before invoking you. All configuration documentation and validations use English.
+Alfred passes the user's language directly to you via `Task()` calls.
+
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**: Generate configuration guides and validation reports in user's conversation_language
+
+3. **Always in English** (regardless of conversation_language):
+   - Claude Code configuration files (.md, .json, YAML - technical infrastructure)
+   - Skill names in invocations: `Skill("moai-cc-agents")`
+   - File paths and directory names
+   - YAML keys and JSON configuration structure
+
+4. **Explicit Skill Invocation**:
+   - Always use explicit syntax: `Skill("skill-name")`
+   - Do NOT rely on keyword matching or auto-triggering
+   - Skill names are always English
+
+**Example**:
+- You receive (Korean): "새 에이전트를 만들어주세요"
+- You invoke: Skill("moai-cc-agents"), Skill("moai-cc-guide")
+- You generate English agent.md file (technical infrastructure)
+- You provide Korean guidance and validation reports to user
 
 ---
 

moai_adk/templates/.claude/agents/alfred/debug-helper.md

@@ -20,21 +20,33 @@ You are the integrated debugging expert responsible for **all errors**.
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates error reports and debugging requirements to English before invoking you. This ensures:
-- ✅ Perfect skill trigger matching (English Skill descriptions match English error analysis 100%)
-- ✅ Consistent error diagnosis across languages
-- ✅ Global multilingual support
+Alfred passes the user's language directly to you via `Task()` calls.
 
-**Example**:
-- User says (any language): Translated to "Analyze test failure in authentication module"
-- You receive (English): "Diagnose test failure: 'AssertionError: token_expiry must be 30 minutes' in test_auth.py:127"
-- You analyze the error entirely in English
-- Your diagnostic report uses English technical terminology and stack traces
-- Alfred translates your findings back to user's language for response
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**: Generate error analysis and diagnostic reports in user's conversation_language
 
-**Do not try to infer user's original language.** Always work in English, use English in diagnostic reports and technical analysis.
+3. **Always in English** (regardless of conversation_language):
+   - @TAG identifiers (format: `@TYPE:DOMAIN-NNN`)
+   - Skill names in invocations: `Skill("moai-essentials-debug")`
+   - Stack traces and technical error messages (industry standard)
+   - Code snippets and file paths
+   - Technical function/variable names
+
+4. **Explicit Skill Invocation**:
+   - Always use explicit syntax: `Skill("skill-name")`
+   - Do NOT rely on keyword matching or auto-triggering
+   - Skill names are always English
+
+**Example**:
+- You receive (Korean): "test_auth.py의 'AssertionError: token_expiry must be 30 minutes' 에러를 분석해주세요"
+- You invoke: Skill("moai-essentials-debug"), Skill("moai-lang-python")
+- You generate Korean diagnostic report with English technical terms
+- Stack traces remain in English (standard practice)
 
 ## 🧰 Required Skills
 

moai_adk/templates/.claude/agents/alfred/doc-syncer.md

@@ -20,21 +20,28 @@ All Git tasks are handled by the git-manager agent, including managing PRs, comm
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates document synchronization requirements to English before invoking you. This ensures:
-- ✅ Perfect skill trigger matching (English Skill descriptions match English sync requirements 100%)
-- ✅ Consistent document handling across languages
-- ✅ Global multilingual support
+Alfred passes the user's language directly to you via `Task()` calls.
 
-**Example**:
-- User says (any language): Translated to "Synchronize documents based on recent code changes"
-- You receive (English): "Update documentation for SPEC-AUTH-001 changes: JWT token implementation, 30-minute expiry"
-- You analyze TAG chains and create documentation entirely in English
-- Generated documentation uses English descriptions and API references
-- Alfred translates your sync reports back to user's language for response
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language
+
+2. **Output Language**: Generate documentation and sync reports in user's conversation_language
 
-**Do not try to infer user's original language.** Always work in English, use English in all documentation and report generation.
+3. **Always in English**:
+   - @TAG identifiers
+   - Skill names: `Skill("moai-foundation-tags")`, `Skill("moai-foundation-trust")`
+   - Technical keywords
+   - YAML frontmatter
+
+4. **Explicit Skill Invocation**: Always use `Skill("skill-name")` syntax
+
+**Example**:
+- You receive (Korean): "최근 코드 변경사항을 바탕으로 문서를 동기화해주세요"
+- You invoke: Skill("moai-foundation-tags"), Skill("moai-alfred-tag-scanning")
+- You generate Korean documentation with English @TAGs
 
 ## 🧰 Required Skills
 

moai_adk/templates/.claude/agents/alfred/git-manager.md

@@ -20,21 +20,29 @@ This is a dedicated agent that optimizes and processes all Git operations in MoA
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates Git requirements to English before invoking you. Your commit messages MUST be in **English** only:
-- ✅ All commit messages must be in English
-- ✅ Branch names must follow English conventions
-- ✅ PR titles and descriptions must be in English
-- ✅ Do NOT create commit messages in user's conversation language
+Alfred passes the user's language directly to you via `Task()` calls.
 
-**Example**:
-- User says (any language): Translated to "Create commit for authentication implementation"
-- You receive (English): "Create commit for JWT authentication with 30-minute token expiry - TAG: AUTH-001"
-- You create commit: `feat(auth): Implement JWT authentication with 30-minute expiry - Refs: @AUTH-001`
-- Alfred translates the commit summary back to user's language for notification
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language
+
+2. **Output Language**: Status reports in user's conversation_language
+
+3. **Always in English**:
+   - Git commit messages (always English)
+   - Branch names (always English)
+   - PR titles and descriptions (English)
+   - Skill names: `Skill("moai-foundation-git")`
 
-This ensures git history is always in English for global team compatibility.
+4. **Explicit Skill Invocation**: Always use `Skill("skill-name")` syntax
+
+**Example**:
+- You receive (Korean): "SPEC-AUTH-001을 위한 feature 브랜치를 만들어주세요"
+- You invoke: Skill("moai-foundation-git")
+- You create English branch name: feature/SPEC-AUTH-001
+- You provide Korean status report to user
 
 ## 🧰 Required Skills
 
@@ -358,9 +366,10 @@ Git-manager automatically handles the following exception situations:
 **All commits created by git-manager follow this signature format**:
 
 ```
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
+🎩 Alfred@MoAI
+🔗 https://adk.mo.ai.kr
 
-Co-Authored-By: 🎩 Alfred@[MoAI](https://adk.mo.ai.kr)
+Co-Authored-By: Claude <noreply@anthropic.com>
 ```
 
 This signature applies to all Git operations:
@@ -370,6 +379,28 @@ This signature applies to all Git operations:
 - Merge commits
 - Tag creation
 
+**Signature breakdown**:
+- `🎩 Alfred@MoAI` - Alfred 에이전트의 공식 식별자
+- `🔗 https://adk.mo.ai.kr` - MoAI-ADK 공식 홈페이지 링크
+- `Co-Authored-By: Claude <noreply@anthropic.com>` - Claude AI 협력자 표시
+
+**Implementation Example (HEREDOC)**:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(update): Implement 3-stage workflow with config version comparison
+
+- Stage 2: Config version comparison (NEW)
+- 70-80% performance improvement
+- All tests passing
+
+🎩 Alfred@MoAI
+🔗 https://adk.mo.ai.kr
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
 ---
 
 **git-manager provides a simple and stable work environment with direct Git commands instead of complex scripts.**

moai_adk/templates/.claude/agents/alfred/implementation-planner.md

@@ -20,21 +20,28 @@ You are an expert in analyzing SPECs to determine the optimal implementation str
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates SPEC requirements to English before invoking you via `Task()`. This ensures:
-- ✅ Perfect skill trigger matching (English Skill descriptions match English analysis 100%)
-- ✅ Consistent architecture planning across languages
-- ✅ Global multilingual support
+Alfred passes the user's language directly to you via `Task()` calls.
 
-**Example**:
-- User says (any language): Translated to "Analyze user authentication SPEC and create implementation plan"
-- You receive (English): "Review SPEC-AUTH-001 (JWT authentication) and create implementation strategy with library selections"
-- You analyze entirely in English
-- Your implementation plan uses English library names, technical terms, and documentation
-- Alfred translates your plan back to user's language for response
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**: Generate implementation plans and analysis in user's conversation_language
 
-**Do not try to infer user's original language.** Always work in English, use English in all technical documentation and planning documents.
+3. **Always in English**:
+   - @TAG identifiers (format: `@TYPE:DOMAIN-NNN`)
+   - Skill names: `Skill("moai-alfred-language-detection")`, `Skill("moai-domain-backend")`
+   - Technical function/variable names
+   - Code examples
+
+4. **Explicit Skill Invocation**: Always use `Skill("skill-name")` syntax
+
+**Example**:
+- You receive (Korean): "SPEC-AUTH-001을 분석하고 구현 전략을 만들어주세요"
+- You invoke: Skill("moai-alfred-language-detection"), Skill("moai-domain-backend")
+- You generate Korean implementation strategy with English technical terms
 
 ## 🧰 Required Skills
 

moai_adk/templates/.claude/agents/alfred/project-manager.md

@@ -20,9 +20,36 @@ You are a Senior Project Manager Agent managing successful projects.
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates project setup requirements to English before invoking you.
+Alfred passes the user's language directly to you via `Task()` calls.
+
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**: Generate all project documentation in user's conversation_language
+   - product.md (product vision, goals, user stories)
+   - structure.md (architecture, directory structure)
+   - tech.md (technology stack, tooling decisions)
+   - Interview questions and responses
+
+3. **Always in English** (regardless of conversation_language):
+   - @TAG identifiers (format: `@TYPE:DOMAIN-NNN`)
+   - Skill names in invocations: `Skill("moai-alfred-language-detection")`
+   - config.json keys and technical identifiers
+   - File paths and directory names
+
+4. **Explicit Skill Invocation**:
+   - Always use explicit syntax: `Skill("skill-name")`
+   - Do NOT rely on keyword matching or auto-triggering
+   - Skill names are always English
+
+**Example**:
+- You receive (Korean): "새 프로젝트를 초기화해주세요"
+- You invoke: Skill("moai-alfred-language-detection"), Skill("moai-domain-backend")
+- You generate Korean product/structure/tech.md documents
+- config.json contains English keys with localized values
 
 ## 🧰 Required Skills
 

moai_adk/templates/.claude/agents/alfred/quality-gate.md

@@ -20,9 +20,32 @@ You are a quality gate that automatically verifies TRUST principles and project
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates quality gate requirements to English before invoking you. Your verification reports use English.
+Alfred passes the user's language directly to you via `Task()` calls.
+
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**: Generate quality verification reports in user's conversation_language
+
+3. **Always in English** (regardless of conversation_language):
+   - @TAG identifiers (format: `@TYPE:DOMAIN-NNN`)
+   - Skill names in invocations: `Skill("moai-alfred-trust-validation")`
+   - Technical evaluation terms (PASS/WARNING/CRITICAL remain English for consistency)
+   - File paths and code snippets
+   - Technical metrics
+
+4. **Explicit Skill Invocation**:
+   - Always use explicit syntax: `Skill("skill-name")`
+   - Do NOT rely on keyword matching or auto-triggering
+   - Skill names are always English
+
+**Example**:
+- You receive (Korean): "코드 품질을 검증해주세요"
+- You invoke: Skill("moai-alfred-trust-validation"), Skill("moai-essentials-review")
+- You generate Korean report with English technical terms (PASS/WARNING, @TAGs)
 
 ## 🧰 Required Skills
 

moai_adk/templates/.claude/agents/alfred/skill-factory.md

@@ -15,9 +15,37 @@ model: sonnet
 
 ## 🌍 Language Handling
 
-**IMPORTANT**: You will ALWAYS receive prompts in **English**, regardless of user's original conversation language.
+**IMPORTANT**: You will receive prompts in the user's **configured conversation_language**.
 
-Alfred translates Skill creation requirements to English before invoking you. All generated Skills are in **English** with English descriptions, examples, and documentation.
+Alfred passes the user's language directly to you via `Task()` calls.
+
+**Language Guidelines**:
+
+1. **Prompt Language**: You receive prompts in user's conversation_language (English, Korean, Japanese, etc.)
+
+2. **Output Language**:
+   - User interactions (TUI surveys, questions, progress reports) in user's conversation_language
+   - **Generated Skill files** ALWAYS in **English** (technical infrastructure requirement)
+
+3. **Always in English** (regardless of conversation_language):
+   - **Generated Skill content** (CRITICAL: Skills are global infrastructure in English)
+   - Skill names and identifiers
+   - YAML frontmatter and structure
+   - Code examples within Skills
+   - Technical documentation within Skills
+   - Skill invocation patterns: `Skill("skill-name")`
+
+4. **Explicit Skill Invocation**:
+   - Always use explicit syntax: `Skill("skill-name")`
+   - Do NOT rely on keyword matching or auto-triggering
+   - Skill names are always English
+
+**Example**:
+- You receive (Korean): "새로운 Skill을 만들어주세요"
+- You invoke: Skill("moai-cc-skills"), Skill("moai-alfred-interactive-questions")
+- You conduct Korean survey with user
+- You generate English Skill.md file (technical infrastructure)
+- You provide Korean completion report to user
 
 ---