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

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

@@ -1,10 +1,6 @@
 ---
 name: alfred:1-plan
-description: "Planning (brainstorming, plan writing, design discussion) + Branch/PR creation"
-# Translations:
-# - ko: "계획 수립 (브레인스토밍, 설계 논의) + 브랜치/PR 생성"
-# - ja: "計画策定（ブレインストーミング、設計議論）+ ブランチ/PR作成"
-# - zh: "规划（头脑风暴、设计讨论）+ 分支/PR创建"
+description: "Define specifications and create development branch"
 argument-hint: Title 1 Title 2 ... | SPEC-ID modifications
 allowed-tools:
 - Read
@@ -22,6 +18,12 @@ allowed-tools:
 
 # 🏗️ MoAI-ADK Step 1: Establish a plan (Plan) - Always make a plan first and then proceed.
 > **Note**: Interactive prompts use `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` for TUI selection menus. The skill is loaded on-demand when user interaction is required.
+>
+> **Batched Design**: All AskUserQuestion calls follow batched design principles (1-4 questions per call) to minimize user interaction turns. See CLAUDE.md section "Alfred Command Completion Pattern" for details.
+
+<!-- @CODE:ALF-WORKFLOW-001:CMD-PLAN -->
+
+**4-Step Workflow Integration**: This command implements Steps 1-2 of Alfred's workflow (Intent Understanding → Plan Creation). See CLAUDE.md for full workflow details.
 
 ## 🎯 Command Purpose
 
@@ -109,63 +111,132 @@ 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:
+
+### 📋 STEP 1 Workflow Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 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.**
 
-**The spec-builder agent automatically loads and analyzes the required documents.**
+#### When to use Phase A:
 
-### 🔍 Explore the codebase (optional)
+- ✅ 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):
 - subagent_type: "Explore"
 - description: "Explore related files in the codebase"
-- prompt: "Please find all files related to the following keywords: $ARGUMENTS
- - File location (src/, tests/, docs/)
- - Relevant SPEC document (.moai/specs/)
- - Existing implementation code
-          thoroughness level: medium"
+- prompt: "다음 키워드와 관련된 모든 파일을 찾아주세요: $ARGUMENTS
+ - 파일 위치 (src/, tests/, docs/)
+ - 관련 SPEC 문서 (.moai/specs/)
+ - 기존 구현 코드
+ 상세도 수준: 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:
 - subagent_type: "spec-builder"
 - description: "Analyze the plan and establish a plan"
-- prompt: """You are spec-builder agent.
-
-LANGUAGE CONFIGURATION:
-- conversation_language: {{CONVERSATION_LANGUAGE}}
-- language_name: {{CONVERSATION_LANGUAGE_NAME}}
-
-CRITICAL INSTRUCTION:
-All SPEC documents and analysis must be generated in conversation_language.
-- If conversation_language is 'ko' (Korean): Generate ALL analysis, plans, and SPEC documents in Korean
-- 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
-
-TASK:
-Please analyze the project document and suggest SPEC candidates.
-Run in analysis mode, and must include the following:
-1. In-depth analysis of product/structure/tech.md
-2. Identify SPEC candidates and Determine priorities
-3. Design EARS structure
-4. Wait for user approval
-
-User input: $ARGUMENTS
-(Optional) Explore results: $EXPLORE_RESULTS"""
+- prompt: """당신은 spec-builder 에이전트입니다.
+
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
+
+중요 지시사항:
+SPEC 문서는 이중 언어 구조를 따라야 합니다 (사용자 언어 + 영어 요약):
+
+conversation_language == 'ko' (한국어)인 경우:
+- YAML 메타데이터: 영어만 사용
+- 제목 (@SPEC 태그): 한국어 주요, 영어 버전은 하단에 기재
+- 주요 내용 (분석, 요구사항, EARS): 한국어
+- SUMMARY 섹션: 영어 (국제 기여자를 위해 100-200단어)
+- HISTORY: 한국어 (새로운 항목), 주요 버전에는 영어 요약
+
+conversation_language == 'ja' (일본어)인 경우:
+- 한국어와 동일한 이중 언어 패턴 사용
+- 주요 내용: 일본어
+- SUMMARY: 영어
+
+다른 언어인 경우:
+- 주요 내용: 사용자 지정 언어
+- SUMMARY: 영어 (항상)
+
+스킬 호출:
+필요 시 명시적 Skill() 호출 사용:
+- Skill("moai-foundation-specs") - SPEC 구조 가이드
+- Skill("moai-foundation-ears") - EARS 문법 요구사항
+- Skill("moai-alfred-spec-metadata-validation") - 메타데이터 검증
+
+작업:
+프로젝트 문서를 분석하여 SPEC 후보자를 제시해주세요.
+분석 모드로 실행하며, 다음을 포함해야 합니다:
+1. product/structure/tech.md의 심층 분석
+2. SPEC 후보자 식별 및 우선순위 결정
+3. EARS 구조 설계
+4. 사용자 승인 대기
+
+사용자 입력: $ARGUMENTS
+(선택사항) 탐색 결과: $EXPLORE_RESULTS"""
 ```
 
+**Note**: If Phase A was executed, pass the exploration results via `$EXPLORE_RESULTS` variable.
+
 ### Plan analysis progress
 
 1. **Project document analysis**
@@ -203,29 +274,58 @@ After user approval (collected via `AskUserQuestion tool (documented in moai-alf
 1. Call spec-builder (create plan):
    - subagent_type: "spec-builder"
    - description: "Create SPEC document"
-   - prompt: """You are spec-builder agent.
+   - prompt: """당신은 spec-builder 에이전트입니다.
+
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
 
-LANGUAGE CONFIGURATION:
-- conversation_language: {{CONVERSATION_LANGUAGE}}
-- language_name: {{CONVERSATION_LANGUAGE_NAME}}
+중요 지시사항:
+모든 SPEC 문서는 대화_언어로 작성되어야 합니다:
+- spec.md: 전체 문서를 대화_언어로 작성
+- plan.md: 전체 문서를 대화_언어로 작성
+- acceptance.md: 전체 문서를 대화_언어로 작성
 
-CRITICAL INSTRUCTION:
-ALL SPEC documents MUST be generated in conversation_language:
-- spec.md: Full document in conversation_language
-- plan.md: Full document in conversation_language
-- acceptance.md: Full document in conversation_language
+YAML 프론트매터와 @TAG 식별자는 반드시 영어로 유지합니다.
+코드 예제와 기술 키워드는 혼합 가능 (코드는 영어, 설명은 사용자 언어).
 
-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() 호출 사용:
+- Skill("moai-foundation-specs") - SPEC 구조 가이드
+- Skill("moai-foundation-ears") - EARS 문법 요구사항
+- Skill("moai-alfred-spec-metadata-validation") - 메타데이터 검증
+- Skill("moai-alfred-tag-scanning") - TAG 체인 참조
 
-TASK:
-Please fill out the SPEC document according to the plan approved in STEP 1.
-Create a specification for the EARS structure."""
+작업:
+STEP 1에서 승인된 계획에 따라 SPEC 문서를 작성해주세요.
+EARS 구조에 대한 명세를 작성합니다."""
 
 2. Invoke git-manager (Git task):
    - subagent_type: "git-manager"
-   - description: "Create Git branch/PR"
-   - prompt: "After completing the plan, please create a branch and Draft PR."
+   - description: "Create Git branch/PR with duplicate prevention"
+   - prompt: """당신은 git-manager 에이전트입니다.
+
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
+
+중요 지시사항 (팀 모드 중복 방지):
+GitHub Issue 또는 PR을 만들기 전에:
+1. 항상 제목에 SPEC-ID가 있는 기존 Issue를 확인하세요
+2. 항상 feature/SPEC-{ID} 브랜치명의 기존 PR을 확인하세요
+3. Issue가 존재하면 → 업데이트, 중복 생성 금지
+4. PR이 존재하면 → 업데이트, 중복 생성 금지
+5. 둘 다 존재하면 → 최신 SPEC 버전으로 모두 업데이트
+6. 레이블 필터 실패 시 대체 검색 사용 (일부 Issue는 레이블 없을 수 있음)
+7. 항상 레이블 추가: "spec", "planning", + 우선순위 레이블
+
+git-manager.md의 "SPEC 작성 시" 섹션에서 자세한 중복 방지 프로토콜과 코드 예제를 참고하세요.
+
+작업:
+완성된 SPEC 문서에 대해 기능 브랜치(feature/SPEC-{SPEC_ID})와 Draft PR(→ develop)을 생성합니다.
+GitHub 엔티티를 생성하기 전에 중복 방지 프로토콜을 구현합니다.
+
+출력 언어: {{CONVERSATION_LANGUAGE}}"""
 ```
 
 ## function
@@ -372,7 +472,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.
 ```
 
@@ -380,7 +480,7 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the spec-
 
 #### YAML Front Matter Schema
 
-> **📋 SPEC Metadata Standard (SSOT)**: `.moai/memory/spec-metadata.md`
+> **📋 SPEC Metadata Standard (SSOT)**: Skill("moai-alfred-spec-metadata-extended")
 
 **Metadata that must be included** at the top of the spec.md file:
 - **7 required fields**: id, version, status, created, updated, author, priority
@@ -407,14 +507,14 @@ priority: high
 - **author**: GitHub @ prefix is required before ID (e.g. `@Goos`)
 - **priority**: critical | high | medium | low
 
-**Full field description and validation methods**: see `.moai/memory/spec-metadata.md`
+**Full field description and validation methods**: see Skill("moai-alfred-spec-metadata-extended")
 
 #### HISTORY section (required)
 
 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
 
@@ -441,10 +541,10 @@ You must include a HISTORY section **right after the YAML Front Matter**:
 
 **HISTORY writing rules**:
 - **Version system**: v0.0.1 (INITIAL) → v0.1.0 (implementation complete) → v1.0.0 (stabilization)
- - Detailed version system: See `.moai/memory/spec-metadata.md#version-system`
+ - Detailed version system: See Skill("moai-alfred-spec-metadata-extended") for version-system guide
 - **Version order**: Latest version on top (reverse order)
 - **Change type tag**: INITIAL, ADDED, CHANGED, IMPLEMENTATION COMPLETED, BREAKING, DEPRECATED, REMOVED, FIXED
- - Detailed description: See `.moai/memory/spec-metadata.md#history-writing-guide`
+ - Detailed description: See Skill("moai-alfred-spec-metadata-extended") for history-writing-guide
 - **Required items**: Version, date, AUTHOR, changes
 - **Optional items**: REVIEW, SCOPE, CONTEXT, MIGRATION
 
@@ -460,7 +560,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 +584,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 +730,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
@@ -647,7 +747,7 @@ See `.coderabbit.yaml` for detailed SPEC review checklist.
 
 ## 🧠 Context Management
 
-> For more information: `.moai/memory/development-guide.md` - see section "Context Engineering"
+> For more information: Skill("moai-alfred-dev-guide") - see section "Context Engineering"
 
 ### Core strategy of this command
 
@@ -657,6 +757,43 @@ See `.coderabbit.yaml` for detailed SPEC review checklist.
 
 ---
 
+## Final Step
+
+After plan creation completes, Alfred automatically invokes AskUserQuestion to ask the user what to do next:
+
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "스펙 작성이 완료되었습니다. 다음으로 뭘 하시겠습니까?",
+            "header": "다음 단계",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "🔨 구현 시작",
+                    "description": "/alfred:2-run SPEC-XXX로 TDD 구현 진행"
+                },
+                {
+                    "label": "📝 스펙 수정",
+                    "description": "SPEC 문서 검토 후 수정"
+                },
+                {
+                    "label": "🔄 새 세션 시작",
+                    "description": "성능 최적화를 위해 /clear 실행"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**User Responses**:
+- **🔨 구현 시작**: Proceed to `/alfred:2-run SPEC-XXX` for TDD implementation
+- **📝 스펙 수정**: Review and modify SPEC documents before implementation
+- **🔄 새 세션 시작**: Execute `/clear` to start fresh session (recommended for performance)
+
+---
+
 ## Next steps
 
 **Recommendation**: For better performance and context management, start a new chat session with the `/clear` or `/new` command before proceeding to the next step.