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

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:
+
+- ✅ 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)
 
-**If the user request is unclear or requires understanding of existing code** Use the Explore agent first:
+#### 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)
+
+**Call the spec-builder agent to analyze project and create SPEC documents.**
 
-**STEP 1 calls the spec-builder agent using the Task tool**:
+This phase is **always required** regardless of whether Phase A was executed.
+
+#### How to invoke spec-builder:
 
 ```
 Call the Task tool:
@@ -154,6 +202,12 @@ All SPEC documents and analysis must be generated in conversation_language.
 - If conversation_language is 'ja' (Japanese): Generate ALL analysis, plans, and SPEC documents in Japanese
 - If conversation_language is other language: Follow the specified language
 
+SKILL INVOCATION:
+Use explicit Skill() calls when needed:
+- Skill("moai-foundation-specs") for SPEC structure guidance
+- Skill("moai-foundation-ears") for EARS syntax requirements
+- Skill("moai-alfred-spec-metadata-validation") for metadata validation
+
 TASK:
 Please analyze the project document and suggest SPEC candidates.
 Run in analysis mode, and must include the following:
@@ -166,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**
@@ -218,6 +274,13 @@ ALL SPEC documents MUST be generated in conversation_language:
 YAML frontmatter and @TAG identifiers MUST remain in English.
 Code examples and technical keywords can be mixed (code in English, narrative in user language).
 
+SKILL INVOCATION:
+Use explicit Skill() calls when needed:
+- Skill("moai-foundation-specs") for SPEC structure guidance
+- Skill("moai-foundation-ears") for EARS syntax requirements
+- Skill("moai-alfred-spec-metadata-validation") for metadata validation
+- Skill("moai-alfred-tag-scanning") for TAG chain references
+
 TASK:
 Please fill out the SPEC document according to the plan approved in STEP 1.
 Create a specification for the EARS structure."""
@@ -372,7 +435,7 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the spec-
 ### State-driven Requirements
 - When the WHILE token is in an unexpired state, the system must allow access to the protected resource.
 
-### Constraints
+### Unwanted Behaviors
 - If the IF token has expired, the system must return a 401 Unauthorized response.
 ```
 
@@ -414,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
 
@@ -460,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]
@@ -484,11 +547,11 @@ author: @username
 ### Optional (Optional function)
 - If WHERE [condition], the system can [operate]
 
-### Constraints
-- IF [condition], the system must be [constrained]
+### Unwanted Behaviors
+- 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
@@ -630,7 +693,7 @@ done
 **CodeRabbit review includes:**
 - ✅ YAML frontmatter validation (7 required fields)
 - ✅ HISTORY section structure and completeness
-- ✅ EARS requirements clarity (Ubiquitous/Event/State/Optional/Constraints)
+- ✅ EARS requirements clarity (Ubiquitous/Event-driven/State-driven/Optional/Unwanted Behaviors)
 - ✅ Acceptance criteria quality (Given-When-Then scenarios)
 - ✅ @TAG system compliance (SPEC/TEST/CODE/DOC traceability)
 - ✅ Documentation and formatting

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**
@@ -202,6 +252,13 @@ Code and technical output MUST be in English.
 Code comments MAY be in {{CONVERSATION_LANGUAGE}} if appropriate.
 Test descriptions and documentation can use {{CONVERSATION_LANGUAGE}}.
 
+SKILL INVOCATION:
+Use explicit Skill() calls when needed:
+- Skill("moai-alfred-language-detection") for project language detection
+- Skill("moai-lang-python") or language-specific Skills for best practices
+- Skill("moai-essentials-debug") when tests fail
+- Skill("moai-essentials-refactor") during REFACTOR phase
+
 TASK: Execute the task according to the plan approved in STEP 1.
 
 For TDD scenario:

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)
+
+**Call tag-agent and doc-syncer to verify TAG integrity and plan synchronization.**
 
-### ⚙️ How to call an agent
+This phase is **always required** and runs **two agents sequentially**:
 
-**In STEP 1, call doc-syncer and tag-agent using the Task tool**:
+#### How to invoke agents:
 
 ```
 1. Tag-agent call (TAG verification - FULL PROJECT SCOPE):
@@ -175,6 +222,12 @@ Documentation updates MUST respect conversation_language:
 - Code comments: {{CONVERSATION_LANGUAGE}} (when not technical keywords)
 - Technical documentation and YAML frontmatter: English
 
+SKILL INVOCATION:
+Use explicit Skill() calls when needed:
+- Skill("moai-foundation-tags") for TAG chain validation
+- Skill("moai-foundation-trust") for quality gate checks
+- Skill("moai-alfred-tag-scanning") for TAG inventory updates
+
 TASK:
 Please analyze Git changes and establish a document synchronization plan.
 Ensure all documentation updates align with the conversation_language setting.
@@ -183,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/.moai/cache/version-check.json

@@ -0,0 +1,9 @@
+{
+  "current": "0.8.1",
+  "latest": "0.8.1",
+  "update_available": false,
+  "upgrade_command": "",
+  "release_notes_url": "https://github.com/modu-ai/moai-adk/releases",
+  "is_major_update": false,
+  "last_check": "2025-10-29T08:52:11.240503+00:00"
+}