moai-adk 0.8.2__tar.gz → 0.8.3__tar.gz

{moai_adk-0.8.2 → moai_adk-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.8.2
+Version: 0.8.3
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -255,7 +255,7 @@ my-project/
 │   │       ├── 1-plan.md           # SPEC authoring
 │   │       ├── 2-run.md            # TDD implementation
 │   │       └── 3-sync.md           # Documentation sync
-│   ├── skills/                     # 58 Claude Skills
+│   ├── skills/                     # 55+ Claude Skills
 │   │   ├── moai-foundation-*       # 6 Foundation tier
 │   │   ├── moai-essentials-*       # 4 Essentials tier
 │   │   ├── moai-alfred-*           # 7 Alfred tier
@@ -617,7 +617,7 @@ uv tool update
 
 ```bash
 # Reinstall specific version (e.g., 0.4.2)
-uv tool install moai-adk==0.4.2
+uv tool install moai-adk
 ```
 
 ### Verify After Update
@@ -1868,7 +1868,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
-**TAG Guard (New in v0.4.11)**:
+**TAG Guard**:
 Automatically detects missing @TAG annotations in changed files:
 
 - Scans staged, modified, and untracked files
@@ -1999,15 +1999,16 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
+| **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
+| **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
+| **v0.7.0**  | 🌍 Complete language localization system (English, Korean, Japanese, Chinese, Spanish)           | 2025-10-26 |
+| **v0.6.3**  | ⚡ 3-Stage update workflow: 70-80% performance improvement via parallel operations               | 2025-10-25 |
+| **v0.6.0**  | 🏗️ Major architecture refactor + Enhanced SPEC metadata structure (7 required + 9 optional)      | 2025-10-24 |
 | **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
-| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
-| **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |
-| **v0.4.8**  | 🚀 Release automation + PyPI deployment + Skills refinement                                      | 2025-10-23 |
-| **v0.4.7**  | 📖 Korean language optimization + SPEC-First principle documentation                             | 2025-10-22 |
-| **v0.4.6**  | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
 
-> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
+> 📦 **Install Now**: `uv tool install moai-adk` or `pip install moai-adk`
 
 ---
 
@@ -2015,7 +2016,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (58 Skills)                         |
+| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
 | Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
@@ -2029,8 +2030,8 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | ------------------------ | -------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                      |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues               |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/                       |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases             |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project         |
 
 ---
@@ -2039,7 +2040,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 > **"No CODE without SPEC"**
 
-MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 56 Claude Skills together guarantee:
+MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 55+ Claude Skills together guarantee:
 
 - ✅ **SPEC → TEST (TDD) → CODE → DOCS consistency**
 - ✅ **Complete history tracking with @TAG system**

{moai_adk-0.8.2 → moai_adk-0.8.3}/README.md

@@ -215,7 +215,7 @@ my-project/
 │   │       ├── 1-plan.md           # SPEC authoring
 │   │       ├── 2-run.md            # TDD implementation
 │   │       └── 3-sync.md           # Documentation sync
-│   ├── skills/                     # 58 Claude Skills
+│   ├── skills/                     # 55+ Claude Skills
 │   │   ├── moai-foundation-*       # 6 Foundation tier
 │   │   ├── moai-essentials-*       # 4 Essentials tier
 │   │   ├── moai-alfred-*           # 7 Alfred tier
@@ -577,7 +577,7 @@ uv tool update
 
 ```bash
 # Reinstall specific version (e.g., 0.4.2)
-uv tool install moai-adk==0.4.2
+uv tool install moai-adk
 ```
 
 ### Verify After Update
@@ -1828,7 +1828,7 @@ Hooks are **event-driven** scripts that trigger automatically at specific points
 - Editing critical files (`CLAUDE.md`, `config.json`)
 - Mass edits (10+ files at once via MultiEdit)
 
-**TAG Guard (New in v0.4.11)**:
+**TAG Guard**:
 Automatically detects missing @TAG annotations in changed files:
 
 - Scans staged, modified, and untracked files
@@ -1959,15 +1959,16 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
+| **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
+| **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
+| **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
+| **v0.7.0**  | 🌍 Complete language localization system (English, Korean, Japanese, Chinese, Spanish)           | 2025-10-26 |
+| **v0.6.3**  | ⚡ 3-Stage update workflow: 70-80% performance improvement via parallel operations               | 2025-10-25 |
+| **v0.6.0**  | 🏗️ Major architecture refactor + Enhanced SPEC metadata structure (7 required + 9 optional)      | 2025-10-24 |
 | **v0.5.7**  | 🎯 SPEC → GitHub Issue automation + CodeRabbit integration + Auto PR comments                    | 2025-10-27 |
 | **v0.4.11** | ✨ TAG Guard system + CLAUDE.md formatting improvements + Code cleanup                           | 2025-10-23 |
-| **v0.4.10** | 🔧 Hook robustness improvements + Bilingual documentation + Template language config             | 2025-10-23 |
-| **v0.4.9**  | 🎯 Hook JSON schema validation fixes + Comprehensive tests (468/468 passing)                     | 2025-10-23 |
-| **v0.4.8**  | 🚀 Release automation + PyPI deployment + Skills refinement                                      | 2025-10-23 |
-| **v0.4.7**  | 📖 Korean language optimization + SPEC-First principle documentation                             | 2025-10-22 |
-| **v0.4.6**  | 🎉 Complete Skills v2.0 (100% Production-Ready) + 85,000 lines official docs + 300+ TDD examples | 2025-10-22 |
 
-> 📦 **Install Now**: `uv tool install moai-adk==0.4.11` or `pip install moai-adk==0.4.11`
+> 📦 **Install Now**: `uv tool install moai-adk` or `pip install moai-adk`
 
 ---
 
@@ -1975,7 +1976,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (58 Skills)                         |
+| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
 | Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
@@ -1989,8 +1990,8 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 | ------------------------ | -------------------------------------------------------- |
 | **GitHub Repository**    | https://github.com/modu-ai/moai-adk                      |
 | **Issues & Discussions** | https://github.com/modu-ai/moai-adk/issues               |
-| **PyPI Package**         | https://pypi.org/project/moai-adk/ (Latest: v0.4.11)     |
-| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases/tag/v0.4.11 |
+| **PyPI Package**         | https://pypi.org/project/moai-adk/                       |
+| **Latest Release**       | https://github.com/modu-ai/moai-adk/releases             |
 | **Documentation**        | See `.moai/`, `.claude/`, `docs/` within project         |
 
 ---
@@ -1999,7 +2000,7 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 > **"No CODE without SPEC"**
 
-MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 56 Claude Skills together guarantee:
+MoAI-ADK is not simply a code generation tool. Alfred SuperAgent with its 19-member team and 55+ Claude Skills together guarantee:
 
 - ✅ **SPEC → TEST (TDD) → CODE → DOCS consistency**
 - ✅ **Complete history tracking with @TAG system**

{moai_adk-0.8.2 → moai_adk-0.8.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.8.2"
+version = "0.8.3"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0"
 readme = "README.md"
 requires-python = ">=3.13"

{moai_adk-0.8.2 → moai_adk-0.8.3}/src/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-0.8.2 → moai_adk-0.8.3}/src/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-0.8.2/src/moai_adk/templates → moai_adk-0.8.3}/src/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-0.8.2 → moai_adk-0.8.3}/src/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-0.8.2 → moai_adk-0.8.3}/src/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-0.8.2/src/moai_adk/templates → moai_adk-0.8.3}/src/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-0.8.2/src/moai_adk/templates → moai_adk-0.8.3}/src/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-0.8.2 → moai_adk-0.8.3}/src/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-0.8.2 → moai_adk-0.8.3}/src/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**