moai-adk 0.9.0__py3-none-any.whl → 0.15.1__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
 
@@ -167,11 +169,11 @@ STEP 1 consists of **two independent phases** to provide flexible workflow based
 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"
 ```
 
 **Note**: If user provides clear SPEC title, skip Phase A and proceed directly to Phase B.
@@ -190,34 +192,47 @@ This phase is **always required** regardless of whether Phase A was executed.
 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
-
-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:
-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.
@@ -259,36 +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 에이전트입니다.
 
-LANGUAGE CONFIGURATION:
-- conversation_language: {{CONVERSATION_LANGUAGE}}
-- language_name: {{CONVERSATION_LANGUAGE_NAME}}
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
 
-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
+중요 지시사항:
+모든 SPEC 문서는 대화_언어로 작성되어야 합니다:
+- spec.md: 전체 문서를 대화_언어로 작성
+- plan.md: 전체 문서를 대화_언어로 작성
+- acceptance.md: 전체 문서를 대화_언어로 작성
 
-YAML frontmatter and @TAG identifiers MUST remain in English.
-Code examples and technical keywords can be mixed (code in English, narrative in user language).
+YAML 프론트매터와 @TAG 식별자는 반드시 영어로 유지합니다.
+코드 예제와 기술 키워드는 혼합 가능 (코드는 영어, 설명은 사용자 언어).
 
-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
+스킬 호출:
+필요 시 명시적 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
@@ -407,15 +444,72 @@ Present your plan in the following format:
 - **Branches/PR**: [Git operations by mode]
 
 ---
-**Approval Request**: Would you like to proceed with creating a plan with the above plan?
- (Choose between “Proceed,” “Modify [Content],” or “Abort”)
+
+## Plan Approval Decision Point
+
+After the planning phase is complete, Alfred uses `AskUserQuestion` tool (documented in moai-alfred-interactive-questions skill) to obtain explicit user approval before proceeding to SPEC creation.
+
+**Example AskUserQuestion Call**:
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "Plan development is complete. Would you like to proceed with SPEC creation based on this plan?",
+            "header": "Plan Approval",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "✅ Proceed with SPEC Creation",
+                    "description": "Create SPEC files in .moai/specs/SPEC-{ID}/ based on approved plan"
+                },
+                {
+                    "label": "🔄 Request Modifications",
+                    "description": "Specify changes to the plan before SPEC creation"
+                },
+                {
+                    "label": "⏸️ Save as Draft",
+                    "description": "Save plan as draft without creating SPEC files yet"
+                },
+                {
+                    "label": "❌ Cancel",
+                    "description": "Discard plan and return to planning phase"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**Response Processing**:
+- **"✅ Proceed with SPEC Creation"** (`answers["0"] === "✅ Proceed with SPEC Creation"`) → Execute Phase 2
+  - Invoke spec-builder agent with approved plan
+  - Create spec.md, plan.md, acceptance.md files in `.moai/specs/SPEC-{ID}/`
+  - Initialize @SPEC TAG system
+  - Create feature branch via git-manager
+  - Create Draft PR for review
+
+- **"🔄 Request Modifications"** (`answers["0"] === "🔄 Request Modifications"`) → Repeat planning phase
+  - Collect modification requests from user
+  - Update plan based on feedback
+  - Re-present plan for approval (recursive decision)
+
+- **"⏸️ Save as Draft"** (`answers["0"] === "⏸️ Save as Draft"`) → Save without SPEC
+  - Save plan to `.moai/specs/SPEC-{ID}/plan.md` with status: draft
+  - Commit with message "draft(spec): WIP SPEC-{ID} - {title}"
+  - User can resume with `/alfred:1-plan resume SPEC-{ID}`
+
+- **"❌ Cancel"** (`answers["0"] === "❌ Cancel"`) → End task
+  - Discard plan artifacts
+  - Return user to initial planning prompt
+  - No files created or modified
+
 ```
 
 ---
 
 ## 🚀 STEP 2 Implementation Guide: Create a Plan (After Approval)
 
-Only if the user selects **"Proceed"** or **"Start"** will Alfred call the spec-builder agent to begin building the SPEC document.
+Only if the user selects **"✅ Proceed with SPEC Creation"** will Alfred call the spec-builder agent to begin building the SPEC document.
 
 ### EARS specification writing guide
 
@@ -443,7 +537,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
@@ -470,7 +564,7 @@ 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)
 
@@ -504,10 +598,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
 
@@ -710,7 +804,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
 
@@ -720,6 +814,64 @@ See `.coderabbit.yaml` for detailed SPEC review checklist.
 
 ---
 
+## Final Step
+
+After SPEC creation completes, Alfred automatically invokes AskUserQuestion to ask the user what to do next:
+
+**Example AskUserQuestion Call**:
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "SPEC creation is complete. What would you like to do next?",
+            "header": "Next Steps",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "🔨 Start Implementation",
+                    "description": "Proceed to /alfred:2-run SPEC-XXX for TDD implementation"
+                },
+                {
+                    "label": "📝 Review SPEC",
+                    "description": "Review and modify SPEC documents before implementation"
+                },
+                {
+                    "label": "🔄 New Session",
+                    "description": "Execute /clear for better context management (recommended)"
+                },
+                {
+                    "label": "❌ Cancel",
+                    "description": "Return to planning phase"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**Response Processing**:
+- **"🔨 Start Implementation"** (`answers["0"] === "🔨 Start Implementation"`) → Proceed to `/alfred:2-run`
+  - Display: "Starting TDD implementation workflow..."
+  - User can execute: `/alfred:2-run SPEC-XXX`
+  - Continue to next phase without session break
+
+- **"📝 Review SPEC"** (`answers["0"] === "📝 Review SPEC"`) → Review generated SPEC
+  - Display: "📁 SPEC files created in `.moai/specs/SPEC-XXX/`"
+  - Show files: spec.md, plan.md, acceptance.md
+  - User can modify and then run `/alfred:2-run SPEC-XXX`
+
+- **"🔄 New Session"** (`answers["0"] === "🔄 New Session"`) → Clear and restart
+  - Display: "⏳ Clearing session for better context management..."
+  - Note: Improves performance for large projects
+  - Next session: User can run `/alfred:2-run SPEC-XXX`
+
+- **"❌ Cancel"** (`answers["0"] === "❌ Cancel"`) → Return to planning
+  - Display: "Returning to planning phase..."
+  - SPEC files preserved for future use
+  - User can create more SPECs with `/alfred:1-plan`
+
+---
+
 ## 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.