moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

moai_adk/tag_system/validator.py

@@ -0,0 +1,200 @@
+"""TAG validator module for TAG System v2.0.
+
+Implements T1: TAG Pattern Definition with format validation,
+SPEC-ID validation, and verb validation.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Tuple
+
+# TAG pattern: @SPEC SPEC-ID [verb]
+# SPEC-ID format: SPEC-{DOMAIN}-{NUMBER}
+# DOMAIN: Uppercase letters and digits, at least 1 char
+# NUMBER: 3 digits
+SPEC_ID_PATTERN = re.compile(r"^SPEC-[A-Z0-9]+-\d{3}$")
+
+# Valid TAG verbs
+VALID_VERBS = {"impl", "verify", "depends", "related"}
+
+# Default verb when not specified
+DEFAULT_VERB = "impl"
+
+
+@dataclass(frozen=True)
+class TAG:
+    """Represents a single TAG annotation.
+
+    Attributes:
+        spec_id: SPEC identifier (e.g., "SPEC-AUTH-001")
+        verb: TAG relationship verb (impl, verify, depends, related)
+        file_path: Path to the file containing the TAG
+        line: Line number where TAG appears
+    """
+
+    spec_id: str
+    file_path: Path
+    line: int
+    verb: str = field(default=DEFAULT_VERB)
+
+    def __post_init__(self) -> None:
+        """Validate TAG fields after initialization."""
+        # Normalize verb to lowercase
+        if self.verb != self.verb.lower():
+            object.__setattr__(self, "verb", self.verb.lower())
+
+
+def validate_spec_id_format(spec_id: str) -> bool:
+    """Validate SPEC-ID format: SPEC-{DOMAIN}-{NUMBER}.
+
+    Args:
+        spec_id: SPEC identifier to validate
+
+    Returns:
+        True if SPEC-ID matches required format, False otherwise
+
+    Examples:
+        >>> validate_spec_id_format("SPEC-AUTH-001")
+        True
+        >>> validate_spec_id_format("spec-auth-001")
+        False
+        >>> validate_spec_id_format("SPEC-AUTH-1")
+        False
+    """
+    return isinstance(spec_id, str) and bool(SPEC_ID_PATTERN.match(spec_id))
+
+
+def validate_verb(verb: str) -> bool:
+    """Validate TAG verb.
+
+    Args:
+        verb: Verb to validate
+
+    Returns:
+        True if verb is valid, False otherwise
+
+    Examples:
+        >>> validate_verb("impl")
+        True
+        >>> validate_verb("invalid")
+        False
+    """
+    return isinstance(verb, str) and verb in VALID_VERBS
+
+
+def get_default_verb() -> str:
+    """Get default TAG verb.
+
+    Returns:
+        Default verb string ("impl")
+    """
+    return DEFAULT_VERB
+
+
+def validate_tag(tag: TAG) -> Tuple[bool, List[str]]:
+    """Validate complete TAG.
+
+    Args:
+        tag: TAG to validate
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+        - is_valid: True if TAG is valid
+        - error_messages: List of validation errors (empty if valid)
+
+    Examples:
+        >>> tag = TAG("SPEC-AUTH-001", Path("test.py"), 1, "impl")
+        >>> is_valid, errors = validate_tag(tag)
+        >>> is_valid
+        True
+    """
+    errors = []
+
+    # Validate SPEC-ID format
+    if not validate_spec_id_format(tag.spec_id):
+        errors.append(
+            f"Invalid SPEC-ID format: '{tag.spec_id}'. "
+            f"Expected format: SPEC-{{DOMAIN}}-{{NUMBER}} (e.g., SPEC-AUTH-001)"
+        )
+
+    # Validate verb
+    if not validate_verb(tag.verb):
+        errors.append(f"Invalid verb: '{tag.verb}'. Valid verbs: {', '.join(sorted(VALID_VERBS))}")
+
+    return len(errors) == 0, errors
+
+
+def parse_tag_string(comment: str, file_path: Path, line: int) -> TAG | None:
+    """Parse TAG from comment string.
+
+    Args:
+        comment: Comment string to parse
+        file_path: Path to the file containing the comment
+        line: Line number of the comment
+
+    Returns:
+        TAG object if valid TAG found, None otherwise
+
+    Examples:
+        >>> comment = "# @SPEC SPEC-AUTH-001"
+        >>> tag = parse_tag_string(comment, Path("test.py"), 1)
+        >>> tag.spec_id
+        'SPEC-AUTH-001'
+        >>> tag.verb
+        'impl'
+    """
+    if not isinstance(comment, str):
+        return None
+
+    # Remove leading whitespace and comment character
+    comment = comment.strip()
+
+    # Check if comment starts with #
+    if not comment.startswith("#"):
+        # Not a comment
+        return None
+
+    # Remove # and leading whitespace
+    comment = comment[1:].strip()
+
+    # Check for @SPEC prefix
+    if not comment.startswith("@SPEC"):
+        return None
+
+    # Remove @SPEC prefix
+    comment = comment[5:].strip()  # len("@SPEC") == 5
+
+    # Split into parts
+    parts = comment.split()
+
+    if not parts:
+        return None
+
+    # First part is SPEC-ID
+    spec_id = parts[0]
+
+    # Validate SPEC-ID format
+    if not validate_spec_id_format(spec_id):
+        return None
+
+    # Second part (if present) is verb
+    verb = DEFAULT_VERB
+    if len(parts) > 1 and parts[1] in VALID_VERBS:
+        verb = parts[1]
+
+    return TAG(spec_id=spec_id, file_path=file_path, line=line, verb=verb)
+
+
+__all__ = [
+    "TAG",
+    "VALID_VERBS",
+    "DEFAULT_VERB",
+    "validate_spec_id_format",
+    "validate_verb",
+    "get_default_verb",
+    "validate_tag",
+    "parse_tag_string",
+]

moai_adk/templates/.claude/agents/moai/builder-agent.md

@@ -1,10 +1,26 @@
 ---
 name: builder-agent
-description: Use PROACTIVELY when creating new sub-agents or generating agent blueprints from requirements. Specialized in Claude Code official sub-agent standards and Chapter 04 best practices.
-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, Task, Skill, mcpcontext7resolve-library-id, mcpcontext7get-library-docs
+description: |
+  Agent creation specialist. Use PROACTIVELY for creating sub-agents, agent blueprints, and custom agent definitions.
+  MUST INVOKE when ANY of these keywords appear in user request:
+  EN: create agent, new agent, agent blueprint, sub-agent, agent definition, custom agent
+  KO: 에이전트생성, 새에이전트, 에이전트블루프린트, 서브에이전트, 에이전트정의, 커스텀에이전트
+  JA: エージェント作成, 新エージェント, エージェントブループリント, サブエージェント
+  ZH: 创建代理, 新代理, 代理蓝图, 子代理, 代理定义
+tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
 model: inherit
 permissionMode: bypassPermissions
 skills: moai-foundation-claude, moai-workflow-project
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "uv run \"{{PROJECT_DIR}}\"/.claude/hooks/moai/post_tool__code_formatter.py"
+          timeout: 30
+        - type: command
+          command: "uv run \"{{PROJECT_DIR}}\"/.claude/hooks/moai/post_tool__linter.py"
+          timeout: 30
 ---
 
 # Agent Factory
@@ -30,7 +46,7 @@ delegates_to: ["mcp-context7", "core-quality"] # Research and validation delegat
 requires_approval: true # User approval before agent finalization
 
 performance:
-avg_execution_time_seconds: 960 # ~16 minutes per complex agent (20% improvement)
+avg_execution_time_seconds: 960
 context_heavy: true # Loads templates, skills database, patterns
 mcp_integration: ["context7"] # MCP tools for documentation research
 optimization_version: "v2.0" # Optimized skill configuration

moai_adk/templates/.claude/agents/moai/builder-command.md

@@ -1,10 +1,26 @@
 ---
 name: builder-command
-description: Use PROACTIVELY when creating or optimizing custom slash commands. Maximizes reuse through asset discovery and match scoring. Specialized in command creation, parameter validation, and workflow automation.
-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, Task, Skill, mcpcontext7resolve-library-id, mcpcontext7get-library-docs
+description: |
+  Slash command creation specialist. Use PROACTIVELY for custom commands, command optimization, and workflow automation.
+  MUST INVOKE when ANY of these keywords appear in user request:
+  EN: create command, slash command, custom command, command optimization, new command
+  KO: 커맨드생성, 슬래시커맨드, 커스텀커맨드, 커맨드최적화, 새커맨드
+  JA: コマンド作成, スラッシュコマンド, カスタムコマンド, コマンド最適化
+  ZH: 创建命令, 斜杠命令, 自定义命令, 命令优化
+tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, Task, Skill, mcp__context7__resolve-library-id, mcp__context7__get-library-docs
 model: inherit
 permissionMode: bypassPermissions
 skills: moai-foundation-claude, moai-workflow-project, moai-workflow-templates
+hooks:
+  PostToolUse:
+    - matcher: "Write|Edit"
+      hooks:
+        - type: command
+          command: "uv run \"{{PROJECT_DIR}}\"/.claude/hooks/moai/post_tool__code_formatter.py"
+          timeout: 30
+        - type: command
+          command: "uv run \"{{PROJECT_DIR}}\"/.claude/hooks/moai/post_tool__linter.py"
+          timeout: 30
 ---
 
 # Command Factory Orchestration Metadata (v1.0)
@@ -65,7 +81,7 @@ delegates_to: [builder-agent, builder-skill, manager-quality, Plan]
 requires_approval: true
 
 performance:
-avg_execution_time_seconds: 900 # ~15 minutes for full workflow
+avg_execution_time_seconds: 900
 context_heavy: true
 mcp_integration: [context7]
 optimization_version: "v1.0"
@@ -316,8 +332,8 @@ Goal: Gather latest documentation and best practices
 Fetch official Claude Code documentation for custom slash commands:
 
 Use Context7 MCP integration:
-- First resolve library ID for "claude-code" using mcpcontext7resolve-library-id
-- Then fetch custom slash commands documentation using mcpcontext7get-library-docs with topic "custom-slash-commands" and mode "code"
+- First resolve library ID for "claude-code" using mcp__context7__resolve-library-id
+- Then fetch custom slash commands documentation using mcp__context7__get-library-docs with topic "custom-slash-commands" and mode "code"
 - Store latest command creation standards for reference
 
 ### Step 2.2: WebSearch for Best Practices
@@ -503,22 +519,36 @@ Execute template selection based on the determined reuse strategy:
 
 ### Step 5.2: Generate Frontmatter
 
+IMPORTANT: Command name is automatically derived from file path structure:
+- `.claude/commands/{namespace}/{command-name}.md` → `/{namespace}:{command-name}`
+- Example: `.claude/commands/moai/fix.md` → `/moai:fix`
+
+DO NOT include a `name` field in frontmatter - it is not officially supported.
+
 ```yaml
 ---
-name: { command_name } # kebab-case
 description: "{command_description}"
 argument-hint: "{argument_format}"
+type: {workflow|utility|local}
 allowed-tools:
   - Task
   - AskUserQuestion
   - TodoWrite # Optional, based on complexity
-model: { model_choice } # haiku or sonnet based on complexity
-skills:
-  - { skill_1 }
-  - { skill_2 }
+model: { model_choice } # haiku, sonnet, or inherit
 ---
 ```
 
+Supported frontmatter fields (official Claude Code documentation):
+- `description` - Command description shown in /help
+- `argument-hint` - Argument syntax hint for autocomplete
+- `allowed-tools` - Tools this command can invoke
+- `model` - Override default model for this command
+- `hooks` - Hook definitions for command execution
+- `disable-model-invocation` - Prevent Skill tool invocation
+
+MoAI-ADK extension field:
+- `type` - Command classification (workflow, utility, local)
+
 ### Step 5.3: Generate Required Sections
 
 [HARD] Generate all 12 required sections to ensure complete command specification
@@ -582,10 +612,9 @@ Section 4: Associated Agents & Skills
 ```markdown
 ## Associated Agents & Skills
 
-| Agent/Skill | Purpose |
-| ----------- | ------- |
+Associated agents and skills for this command:
 
-{agent_skill_table_rows}
+{agent_skill_list}
 ```
 
 Section 5: Agent Invocation Patterns (NEW)
@@ -720,6 +749,24 @@ Output: {expected_output}
   IMPACT: Complex multi-agent workflows remain coherent and recoverable
 ```
 
+### Selective Exceptions: Read-Only Tool Access
+
+Certain commands are allowed direct read-only tool usage for performance optimization:
+
+Command-specific tool exceptions:
+- moai:1-plan: Glob tool allowed for SPEC ID uniqueness validation (read-only; file creation delegated to agent)
+
+[HARD] Exception Requirements:
+- Only read-only operations may be performed directly
+- File creation/modification MUST be delegated to agents
+- Error handling logic MUST be included
+- Exception scope MUST be clearly documented in the command
+
+WHY: Selective read-only exceptions provide 30-40% performance improvement for validation-heavy operations
+IMPACT: Commands remain auditable while gaining speed benefits for non-destructive checks
+
+```
+
 Sections 7-9: Phase Workflow
 
 ```markdown
@@ -745,10 +792,9 @@ Section 10: Quick Reference
 ```markdown
 ## Quick Reference
 
-| Scenario | Entry Point | Key Phases | Expected Outcome |
-| -------- | ----------- | ---------- | ---------------- |
+Quick reference scenarios:
 
-{scenario_table_rows}
+{scenario_list}
 
 Version: {version}
 Last Updated: 2025-12-07