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

moai_adk/core/config/migration.py

@@ -34,7 +34,7 @@ def migrate_config_to_nested_structure(config: dict[str, Any]) -> dict[str, Any]
     if "conversation_language" in config and "language" not in config:
         # Extract conversation language from legacy location
         conversation_language = config.pop("conversation_language", "en")
-        locale = config.pop("locale", None)
+        config.pop("locale", None)  # Remove legacy locale field
 
         # Map language codes to language names
         language_names = {

moai_adk/core/issue_creator.py

@@ -214,7 +214,7 @@ class GitHubIssueCreator:
         footer += f"**Priority**: {config.priority.value}  \n"
         if config.category:
             footer += f"**Category**: {config.category}  \n"
-        footer += f"**Created via**: `/alfred:9-feedback`"
+        footer += "**Created via**: `/alfred:9-feedback`"
 
         return body + footer
 
@@ -276,7 +276,9 @@ class IssueCreatorFactory:
         )
 
     @staticmethod
-    def create_feature_issue(title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM) -> IssueConfig:
+    def create_feature_issue(
+        title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM
+    ) -> IssueConfig:
         """Create a feature request issue configuration."""
         return IssueConfig(
             issue_type=IssueType.FEATURE,
@@ -287,7 +289,9 @@ class IssueCreatorFactory:
         )
 
     @staticmethod
-    def create_improvement_issue(title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM) -> IssueConfig:
+    def create_improvement_issue(
+        title: str, description: str, priority: IssuePriority = IssuePriority.MEDIUM
+    ) -> IssueConfig:
         """Create an improvement issue configuration."""
         return IssueConfig(
             issue_type=IssueType.IMPROVEMENT,

moai_adk/core/tags/__init__.py

@@ -14,43 +14,42 @@ This module provides TAG validation functionality for:
 """
 
 # Component 1: Pre-commit validator
+# Component 2: CI/CD validator
+from .ci_validator import CIValidator
 from .pre_commit_validator import (
     PreCommitValidator,
-    ValidationResult,
     ValidationError,
+    ValidationResult,
     ValidationWarning,
 )
 
-# Component 2: CI/CD validator
-from .ci_validator import CIValidator
-
-# Component 3: Central validation system
-from .validator import (
-    ValidationConfig,
-    TagValidator,
-    DuplicateValidator,
-    OrphanValidator,
-    ChainValidator,
-    FormatValidator,
-    CentralValidator,
-    CentralValidationResult,
-    ValidationIssue,
-    ValidationStatistics,
-)
-
 # Component 4: Documentation & Reporting
 from .reporter import (
-    TagInventory,
-    TagMatrix,
+    CoverageAnalyzer,
+    CoverageMetrics,
     InventoryGenerator,
     MatrixGenerator,
-    CoverageAnalyzer,
-    StatisticsGenerator,
     ReportFormatter,
     ReportGenerator,
-    CoverageMetrics,
-    StatisticsReport,
     ReportResult,
+    StatisticsGenerator,
+    StatisticsReport,
+    TagInventory,
+    TagMatrix,
+)
+
+# Component 3: Central validation system
+from .validator import (
+    CentralValidationResult,
+    CentralValidator,
+    ChainValidator,
+    DuplicateValidator,
+    FormatValidator,
+    OrphanValidator,
+    TagValidator,
+    ValidationConfig,
+    ValidationIssue,
+    ValidationStatistics,
 )
 
 __all__ = [

moai_adk/core/tags/ci_validator.py

@@ -13,15 +13,13 @@ Used by GitHub Actions workflow to validate TAGs on every PR.
 
 import json
 import os
-from pathlib import Path
-from typing import List, Dict, Any, Optional, Tuple
+from typing import Any, Dict, List, Optional
+
 import requests
 
 from .pre_commit_validator import (
     PreCommitValidator,
     ValidationResult,
-    ValidationError,
-    ValidationWarning,
 )
 
 
@@ -357,8 +355,8 @@ class CIValidator(PreCommitValidator):
 
 def main():
     """CLI entry point for CI/CD validation"""
-    import sys
     import argparse
+    import sys
 
     parser = argparse.ArgumentParser(
         description="Validate TAG annotations in GitHub PR"

moai_adk/core/tags/cli.py

@@ -15,15 +15,15 @@ Usage:
     moai-adk validate-tags --no-duplicates --no-orphans
 """
 
-import sys
 import argparse
+import sys
 from pathlib import Path
 from typing import Optional
 
 from .validator import (
+    CentralValidationResult,
     CentralValidator,
     ValidationConfig,
-    CentralValidationResult,
 )
 
 

moai_adk/core/tags/pre_commit_validator.py

@@ -15,7 +15,7 @@ import re
 import subprocess
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import List, Tuple, Dict, Set, Optional
+from typing import Dict, List, Optional, Tuple
 
 
 @dataclass
@@ -160,7 +160,7 @@ class PreCommitValidator:
         for tag, locations in tag_locations.items():
             if len(locations) > 1:
                 errors.append(ValidationError(
-                    message=f"Duplicate TAG found",
+                    message="Duplicate TAG found",
                     tag=tag,
                     locations=locations
                 ))
@@ -220,7 +220,7 @@ class PreCommitValidator:
             if domain not in tags_by_type["TEST"]:
                 for filepath, line_num in locations:
                     warnings.append(ValidationWarning(
-                        message=f"CODE TAG without corresponding TEST",
+                        message="CODE TAG without corresponding TEST",
                         tag=f"@CODE:{domain}",
                         location=(filepath, line_num)
                     ))
@@ -230,7 +230,7 @@ class PreCommitValidator:
             if domain not in tags_by_type["CODE"]:
                 for filepath, line_num in locations:
                     warnings.append(ValidationWarning(
-                        message=f"TEST TAG without corresponding CODE",
+                        message="TEST TAG without corresponding CODE",
                         tag=f"@TEST:{domain}",
                         location=(filepath, line_num)
                     ))
@@ -302,8 +302,8 @@ class PreCommitValidator:
 
 def main():
     """CLI entry point for pre-commit hook"""
-    import sys
     import argparse
+    import sys
 
     parser = argparse.ArgumentParser(
         description="Validate TAG annotations in git staged files"

moai_adk/core/tags/reporter.py

@@ -23,14 +23,12 @@ Usage:
     print(f"Generated reports: {result.inventory_path}, {result.matrix_path}")
 """
 
-import re
 import json
+import re
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import List, Dict, Set, Tuple, Optional, Any
 from datetime import datetime
-import fnmatch
-
+from pathlib import Path
+from typing import Dict, List, Set
 
 # ============================================================================
 # Data Models

moai_adk/core/tags/validator.py

@@ -22,14 +22,14 @@ Usage:
     report = validator.create_report(result, format="json")
 """
 
-import re
 import json
+import re
 import time
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
-from pathlib import Path
-from typing import List, Dict, Set, Tuple, Optional, Any
 from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Tuple
 
 
 @dataclass

moai_adk/templates/.claude/commands/alfred/1-plan.md

@@ -109,13 +109,59 @@ Users can run commands like this:
 
 ## 🔍 STEP 1: Project analysis and planning
 
-Analyze project documents to propose SPEC candidates, establish implementation strategies, and receive user confirmation.
+STEP 1 consists of **two independent phases** to provide flexible workflow based on user request clarity:
 
-**The spec-builder agent automatically loads and analyzes the required documents.**
+### 📋 STEP 1 Workflow Overview
 
-### 🔍 Explore the codebase (optional)
+```
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 1: Project Analysis & Planning                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Phase A (OPTIONAL)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ 🔍 Explore Agent                        │               │
+│  │ • Find relevant files by keywords       │               │
+│  │ • Locate existing SPEC documents        │               │
+│  │ • Identify implementation patterns      │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (exploration results)                              │
+│                    ↓                                        │
+│  Phase B (REQUIRED)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ ⚙️ spec-builder Agent                   │               │
+│  │ • Analyze project documents             │               │
+│  │ • Propose SPEC candidates               │               │
+│  │ • Design EARS structure                 │               │
+│  │ • Request user approval                 │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (user approval via AskUserQuestion)                │
+│                    ↓                                        │
+│              PROCEED TO STEP 2                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key Points**:
+- **Phase A is optional** - Skip if user provides clear SPEC title
+- **Phase B is required** - Always runs to analyze project and create SPEC
+- **Results flow forward** - Exploration results (if any) are passed to spec-builder
+
+---
+
+### 🔍 Phase A: Codebase Exploration (OPTIONAL)
+
+**Use the Explore agent when user request is unclear or needs context.**
+
+#### When to use Phase A:
 
-**If the user request is unclear or requires understanding of existing code** Use the Explore agent first:
+- ✅ User uses vague keywords ("where is...", "find me...", "related to...")
+- ✅ Need to understand existing code structure before planning
+- ✅ Feature spans multiple files or modules
+- ❌ User provides clear SPEC title (skip to Phase B)
+
+#### How to invoke Explore agent:
 
 ```
 Invoking the Task tool (Explore agent):
@@ -125,18 +171,20 @@ Invoking the Task tool (Explore agent):
  - File location (src/, tests/, docs/)
  - Relevant SPEC document (.moai/specs/)
  - Existing implementation code
-          thoroughness level: medium"
+ thoroughness level: medium"
 ```
 
-**Criteria for using the Explore Agent**:
-- ✅ Users use keywords like “where am”, “find me”, etc.
-- ✅ Need to understand existing code structure
-- ✅ Investigate features across multiple files
-- ❌ Given a clear SPEC title (straight into spec-builder)
+**Note**: If user provides clear SPEC title, skip Phase A and proceed directly to Phase B.
 
-### ⚙️ How to call an agent
+---
+
+### ⚙️ Phase B: SPEC Planning (REQUIRED)
 
-**STEP 1 calls the spec-builder agent using the Task tool**:
+**Call the spec-builder agent to analyze project and create SPEC documents.**
+
+This phase is **always required** regardless of whether Phase A was executed.
+
+#### How to invoke spec-builder:
 
 ```
 Call the Task tool:
@@ -172,6 +220,8 @@ User input: $ARGUMENTS
 (Optional) Explore results: $EXPLORE_RESULTS"""
 ```
 
+**Note**: If Phase A was executed, pass the exploration results via `$EXPLORE_RESULTS` variable.
+
 ### Plan analysis progress
 
 1. **Project document analysis**
@@ -427,7 +477,7 @@ priority: high
 You must include a HISTORY section **right after the YAML Front Matter**:
 
 ```markdown
-# @SPEC:AUTH-001: JWT-based authentication system
+# @SPEC:DOMAIN-NNN: JWT-based authentication system
 
 ## HISTORY
 
@@ -473,7 +523,7 @@ updated: 2025-09-15
 author: @username
 ---
 
-# @SPEC:AUTH-001: [SPEC title]
+# @SPEC:DOMAIN-NNN: [SPEC title]
 
 ## HISTORY
 [Change history by version – see example above]
@@ -501,7 +551,7 @@ author: @username
 - IF [condition], the system must [respond appropriately with error handling or quality gates]
 
 ## Traceability (@TAG)
-- **SPEC**: @SPEC:AUTH-001
+- **SPEC**: @SPEC:DOMAIN-NNN
 - **TEST**: tests/auth/test_service.py
 - **CODE**: src/auth/service.py
 - **DOC**: docs/api/authentication.md

moai_adk/templates/.claude/commands/alfred/2-run.md

@@ -96,13 +96,59 @@ Users can run commands as follows:
 
 ## 🔍 STEP 1: SPEC analysis and execution plan establishment
 
-First, the specified SPEC is analyzed to establish an action plan and receive user confirmation.
+STEP 1 consists of **two independent phases** to provide flexible workflow based on task complexity:
 
-**The implementation-planner agent automatically loads and analyzes the required documents.**
+### 📋 STEP 1 Workflow Overview
 
-### 🔍 Browse the code base (recommended)
+```
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 1: SPEC Analysis & Planning                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Phase A (OPTIONAL)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ 🔍 Explore Agent                        │               │
+│  │ • Browse existing codebase              │               │
+│  │ • Find similar implementations          │               │
+│  │ • Identify patterns & architecture      │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (exploration results)                              │
+│                    ↓                                        │
+│  Phase B (REQUIRED)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ ⚙️ implementation-planner Agent         │               │
+│  │ • Analyze SPEC requirements             │               │
+│  │ • Design execution strategy             │               │
+│  │ • Create implementation plan            │               │
+│  │ • Request user approval                 │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (user approval via AskUserQuestion)                │
+│                    ↓                                        │
+│              PROCEED TO STEP 2                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key Points**:
+- **Phase A is optional** - Skip if you don't need to explore existing code
+- **Phase B is required** - Always runs to analyze SPEC and create execution plan
+- **Results flow forward** - Exploration results (if any) are passed to implementation-planner
+
+---
+
+### 🔍 Phase A: Codebase Exploration (OPTIONAL)
+
+**Use the Explore agent when you need to understand existing code before planning.**
+
+#### When to use Phase A:
 
-**If you need to understand existing code structure or find similar patterns** Use the Explore agent first:
+- ✅ Need to understand existing code structure/patterns
+- ✅ Need to find similar function implementations for reference
+- ✅ Need to understand project architectural rules
+- ✅ Need to check libraries and versions being used
+
+#### How to invoke Explore agent:
 
 ```
 Invoking the Task tool (Explore agent):
@@ -112,35 +158,39 @@ Invoking the Task tool (Explore agent):
  - Similar function implementation code (src/)
  - Test patterns for reference (tests/)
  - Architectural patterns and design patterns
- - Use Current libraries and versions (package.json, requirements.txt)
+ - Current libraries and versions (package.json, requirements.txt)
  thoroughness level: medium"
 ```
 
-**When to use the Explore Agent**:
-- ✅ When you need to understand the existing code structure/pattern
-- ✅ When you need to refer to how a similar function is implemented
-- ✅ When you need to understand the architectural rules of the project
-- ✅ Check the library and version being used
+**Note**: If you skip Phase A, proceed directly to Phase B.
 
-### ⚙️ How to call an agent
+---
+
+### ⚙️ Phase B: Execution Planning (REQUIRED)
 
-**In STEP 1, we call the implementation-planner agent using the Task tool**:
+**Call the implementation-planner agent to analyze SPEC and establish execution strategy.**
+
+This phase is **always required** regardless of whether Phase A was executed.
+
+#### How to invoke implementation-planner:
 
 ```
-Task tool call example:
+Task tool call:
 - subagent_type: "implementation-planner"
 - description: "SPEC analysis and establishment of execution strategy"
 - prompt: "Please analyze the SPEC of $ARGUMENTS and establish an execution plan.
  It must include the following:
  1. SPEC requirements extraction and complexity assessment
  2. Library and tool selection (using WebFetch)
-          3. TAG chain design
+ 3. TAG chain design
  4. Step-by-step execution plan
  5. Risks and response plans
-6. Create action plan and use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` to confirm the next action with the user
+ 6. Create action plan and use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` to confirm the next action with the user
  (Optional) Explore results: $EXPLORE_RESULTS"
 ```
 
+**Note**: If Phase A was executed, pass the exploration results via `$EXPLORE_RESULTS` variable.
+
 ### SPEC analysis in progress
 
 1. **SPEC document analysis**

moai_adk/templates/.claude/commands/alfred/3-sync.md

@@ -102,15 +102,60 @@ Users can run the command as follows:
 
 ## 🔍 STEP 1: Analyze synchronization scope and establish plan
 
-Analyze project status to determine synchronization scope, develop a systematic synchronization plan, and receive user confirmation.
+STEP 1 consists of **two independent phases** to provide flexible workflow based on project complexity:
 
-**The tag-agent performs comprehensive TAG verification (full project scope), and doc-syncer analyzes Git changes and establishes synchronization plan.**
+### 📋 STEP 1 Workflow Overview
 
-⚠️ **Important**: Tag-agent must verify the ENTIRE PROJECT for TAG orphans, not just changed files. Full-project scope is MANDATORY.
+```
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 1: Synchronization Analysis & Planning                │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Phase A (OPTIONAL)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ 🔍 Explore Agent                        │               │
+│  │ • Navigate complex TAG chains           │               │
+│  │ • Scan entire TAG system                │               │
+│  │ • Identify orphan TAGs                  │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (exploration results)                              │
+│                    ↓                                        │
+│  Phase B (REQUIRED)                                         │
+│  ┌─────────────────────────────────────────┐               │
+│  │ ⚙️ tag-agent + doc-syncer Agents        │               │
+│  │ • Verify TAG integrity (full project)   │               │
+│  │ • Analyze Git changes                   │               │
+│  │ • Create synchronization plan           │               │
+│  │ • Request user approval                 │               │
+│  └─────────────────────────────────────────┘               │
+│                    ↓                                        │
+│          (user approval via AskUserQuestion)                │
+│                    ↓                                        │
+│              PROCEED TO STEP 2                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key Points**:
+- **Phase A is optional** - Skip for simple single-SPEC changes
+- **Phase B is required** - Always runs to verify TAGs and plan sync
+- **Results flow forward** - Exploration results (if any) are passed to tag-agent
+- **⚠️ Important**: tag-agent verifies ENTIRE PROJECT, not just changed files
+
+---
 
-### 🔍 TAG chain navigation (optional)
+### 🔍 Phase A: TAG Chain Navigation (OPTIONAL)
+
+**Use the Explore agent for complex or extensive TAG chains.**
+
+#### When to use Phase A:
+
+- ✅ Large projects (100+ files)
+- ✅ Need comprehensive TAG chain integrity verification
+- ✅ Changes span multiple SPECs or modules
+- ❌ Simple changes to a single SPEC (skip to Phase B)
 
-**If your TAG chain is complex or extensive**, utilize the Explore agent first:
+#### How to invoke Explore agent:
 
 ```
 Invoking the Task tool (Explore agent):
@@ -120,20 +165,22 @@ Invoking the Task tool (Explore agent):
  - @SPEC TAG location (.moai/specs/)
  - @TEST TAG location (tests/)
  - @CODE TAG location (src/)
-          - @DOC TAG location (docs/)
+ - @DOC TAG location (docs/)
  - Detect orphan TAGs and broken references
- Thoroughness level: very thorough"
+ thoroughness level: very thorough"
 ```
 
-**Explore Agent When to Use**:
-- ✅ Large projects (100+ files)
-- ✅ When TAG chain integrity verification is required
-- ✅ Changes across multiple SPECs
-- ❌ Simple changes to a single SPEC
+**Note**: For simple changes, skip Phase A and proceed directly to Phase B.
+
+---
+
+### ⚙️ Phase B: TAG Verification & Sync Planning (REQUIRED)
 
-### ⚙️ How to call an agent
+**Call tag-agent and doc-syncer to verify TAG integrity and plan synchronization.**
 
-**In STEP 1, call doc-syncer and tag-agent using the Task tool**:
+This phase is **always required** and runs **two agents sequentially**:
+
+#### How to invoke agents:
 
 ```
 1. Tag-agent call (TAG verification - FULL PROJECT SCOPE):
@@ -189,6 +236,13 @@ $ARGUMENTS
 (Optional) TAG validation results: $TAG_VALIDATION_RESULTS"""
 ```
 
+**Note**:
+- **Sequential execution**: Run tag-agent first, then doc-syncer
+- **Results flow**: TAG validation results from tag-agent are passed to doc-syncer via `$TAG_VALIDATION_RESULTS`
+- **Phase A results**: If Phase A was executed, exploration results are passed to tag-agent via `$EXPLORE_RESULTS`
+
+---
+
 ### Synchronization analysis in progress
 
 1. **Check project status**

moai_adk/templates/.claude/hooks/alfred/core/version_cache.py

@@ -149,7 +149,7 @@ class VersionCache:
 
             return True
 
-        except (OSError, TypeError) as e:
+        except (OSError, TypeError):
             # Graceful degradation on write errors
             return False