moai-adk 0.9.0__py3-none-any.whl → 0.15.1__py3-none-any.whl

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

@@ -1,10 +1,6 @@
 ---
 name: alfred:3-sync
-description: "Document synchronization + PR Ready conversion"
-# Translations:
-# - ko: "문서 동기화 + PR Ready 전환"
-# - ja: "ドキュメント同期 + PR Ready変換"
-# - zh: "文档同步 + PR Ready转换"
+description: "Synchronize documentation and finalize PR"
 argument-hint: 'Mode target path - Mode: auto (default)|force|status|project, target
   path: Synchronization target path'
 allowed-tools:
@@ -23,6 +19,12 @@ allowed-tools:
 
 # 📚 MoAI-ADK Step 3: Document Synchronization (+Optional PR Ready)
 > **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-003:CMD-SYNC -->
+
+**4-Step Workflow Integration**: This command implements Step 4 of Alfred's workflow (Report & Commit with conditional report generation). See CLAUDE.md for full workflow details.
 
 ## 🚀 START HERE
 
@@ -161,13 +163,13 @@ STEP 1 consists of **two independent phases** to provide flexible workflow based
 Invoking the Task tool (Explore agent):
 - subagent_type: "Explore"
 - description: "Scan entire TAG system"
-- prompt: "Please scan @TAG system throughout the project:
- - @SPEC TAG location (.moai/specs/)
- - @TEST TAG location (tests/)
- - @CODE TAG location (src/)
- - @DOC TAG location (docs/)
- - Detect orphan TAGs and broken references
- thoroughness level: very thorough"
+- prompt: "프로젝트 전체에서 @TAG 시스템을 스캔해주세요:
+ - @SPEC TAG 위치 (.moai/specs/)
+ - @TEST TAG 위치 (tests/)
+ - @CODE TAG 위치 (src/)
+ - @DOC TAG 위치 (docs/)
+ - 고아 TAG 및 끊긴 참조 감지
+ 상세도 수준: very thorough"
 ```
 
 **Note**: For simple changes, skip Phase A and proceed directly to Phase B.
@@ -186,54 +188,54 @@ This phase is **always required** and runs **two agents sequentially**:
 1. Tag-agent call (TAG verification - FULL PROJECT SCOPE):
    - subagent_type: "tag-agent"
 - description: "Verify TAG system across entire project"
- - prompt: "Please perform a COMPREHENSIVE TAG system verification across the ENTIRE PROJECT.
+ - prompt: "전체 프로젝트에서 포괄적인 @TAG 시스템 검증을 수행해주세요.
 
- **Required scope**: Scan all source files, not just changed files.
+ **필수 범위**: 변경된 파일만이 아니라 모든 소스 파일을 스캔합니다.
 
- **Verification items**:
- 1. @SPEC TAGs in .moai/specs/ directory
- 2. @TEST TAGs in tests/ directory
- 3. @CODE TAGs in src/ directory
- 4. @DOC TAGs in docs/ directory
+ **검증 항목**:
+ 1. .moai/specs/ 디렉토리의 @SPEC TAG
+ 2. tests/ 디렉토리의 @TEST TAG
+ 3. src/ 디렉토리의 @CODE TAG
+ 4. docs/ 디렉토리의 @DOC TAG
 
- **Orphan detection** (MANDATORY):
- - Detect @CODE TAGs without matching @SPEC
- - Detect @SPEC TAGs without matching @CODE
- - Detect @TEST TAGs without matching @SPEC
- - Detect @DOC TAGs without matching @SPEC/@CODE
+ **고아 감지** (필수):
+ - 매칭되는 @SPEC이 없는 @CODE TAG 감지
+ - 매칭되는 @CODE가 없는 @SPEC TAG 감지
+ - 매칭되는 @SPEC이 없는 @TEST TAG 감지
+ - 매칭되는 @SPEC/@CODE가 없는 @DOC TAG 감지
 
- **Output format**: Provide complete list of orphan TAGs with locations.
+ **출력 형식**: 고아 TAG의 전체 목록을 위치와 함께 제공합니다.
 
- (Optional) Explore results: $EXPLORE_RESULTS"
+ (선택사항) 탐색 결과: $EXPLORE_RESULTS"
 
 2. doc-syncer call (synchronization plan):
    - subagent_type: "doc-syncer"
    - description: "Establish a document synchronization plan"
-   - prompt: """You are doc-syncer agent.
+   - prompt: """당신은 doc-syncer 에이전트입니다.
 
-LANGUAGE CONFIGURATION:
-- conversation_language: {{CONVERSATION_LANGUAGE}}
-- language_name: {{CONVERSATION_LANGUAGE_NAME}}
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
 
-CRITICAL INSTRUCTION:
-Documentation updates MUST respect conversation_language:
-- User-facing documentation (README, guides): {{CONVERSATION_LANGUAGE}}
-- SPEC documents (spec.md, plan.md, acceptance.md): {{CONVERSATION_LANGUAGE}}
-- Code comments: {{CONVERSATION_LANGUAGE}} (when not technical keywords)
-- Technical documentation and YAML frontmatter: English
+중요 지시사항:
+문서 업데이트는 대화_언어를 반드시 존중해야 합니다:
+- 사용자 대면 문서 (README, 가이드): {{CONVERSATION_LANGUAGE}}
+- SPEC 문서 (spec.md, plan.md, acceptance.md): {{CONVERSATION_LANGUAGE}}
+- 코드 주석: {{CONVERSATION_LANGUAGE}} (기술 키워드 제외)
+- 기술 문서 및 YAML 프론트매터: 영어
 
-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
+스킬 호출:
+필요 시 명시적 Skill() 호출 사용:
+- Skill("moai-foundation-tags") - TAG 체인 검증
+- Skill("moai-foundation-trust") - 품질 게이트 검사
+- Skill("moai-alfred-tag-scanning") - TAG 인벤토리 업데이트
 
-TASK:
-Please analyze Git changes and establish a document synchronization plan.
-Ensure all documentation updates align with the conversation_language setting.
+작업:
+Git 변경사항을 분석하고 문서 동기화 계획을 수립해주세요.
+모든 문서 업데이트가 대화_언어 설정과 일치하는지 확인합니다.
 
 $ARGUMENTS
-(Optional) TAG validation results: $TAG_VALIDATION_RESULTS"""
+(선택사항) TAG 검증 결과: $TAG_VALIDATION_RESULTS"""
 ```
 
 **Note**:
@@ -301,12 +303,45 @@ To skip pre-verification, use the `/alfred:3-sync --skip-pre-check` option.
 
 ---
 
-### User verification steps
+### 🎯 Synchronization Plan Approval (DECISION POINT 1)
+
+After completing synchronization analysis and establishing a plan, Alfred invokes AskUserQuestion to gather user approval:
+
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "Synchronization plan is ready. How would you like to proceed?",
+            "header": "Plan Approval",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "✅ Proceed with Sync",
+                    "description": "Execute document synchronization as planned"
+                },
+                {
+                    "label": "🔄 Request Modifications",
+                    "description": "Specify changes to the synchronization strategy"
+                },
+                {
+                    "label": "🔍 Review Details",
+                    "description": "Re-examine TAG validation results and changes"
+                },
+                {
+                    "label": "❌ Abort",
+                    "description": "Cancel synchronization, keep current state"
+                }
+            ]
+        }
+    ]
+)
+```
 
-After reviewing your sync plan, `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)` presents the following options for user decision:
-- **"Proceed"** or **"Start"**: Start synchronization as planned
-- **"Modify [Contents]"**: Request modifications to your sync plan
-- **"Abort"**: Abort the sync operation
+**Response Processing**:
+- **✅ Proceed with Sync** (`answers["0"] === "Proceed"`) → Execute Phase 2 (document synchronization)
+- **🔄 Request Modifications** (`answers["0"] === "Modifications"`) → Collect feedback and re-analyze
+- **🔍 Review Details** (`answers["0"] === "Review"`) → Display TAG validation results, then re-present decision
+- **❌ Abort** (`answers["0"] === "Abort"`) → Stop synchronization, maintain current branches
 
 ---
 
@@ -314,6 +349,170 @@ After reviewing your sync plan, `AskUserQuestion tool (documented in moai-alfred
 
 After user approval (collected via `AskUserQuestion tool (documented in moai-alfred-interactive-questions skill)`), the doc-syncer agent performs **Living Document synchronization and @TAG updates**, and optionally executes PR Ready transitions only in team mode.
 
+---
+
+### 2.0.5 Domain-Based Sync Routing (Automatic - During Sync)
+
+**Purpose**: Route documentation sync to domain-specific experts based on changed files
+
+**When to run**: During doc-syncer execution, after analyzing git changes
+
+**Detection Logic**:
+
+Alfred analyzes changed files to determine which domains were modified:
+
+```bash
+# Get list of changed files
+git diff --name-only HEAD~1 HEAD
+
+# Domain detection by file patterns
+```
+
+**File Pattern → Domain Mapping**:
+
+| File Patterns | Domain | Sync Focus |
+|---------------|--------|-----------|
+| `src/components/*`, `src/pages/*`, `*.tsx`, `*.jsx`, `*.vue` | Frontend | Component documentation, Storybook, UI architecture |
+| `src/api/*`, `src/models/*`, `src/routes/*`, `src/services/*` | Backend | API documentation (OpenAPI), schema docs, error handling |
+| `Dockerfile`, `docker-compose.yml`, `.github/workflows/*`, `terraform/*`, `k8s/*` | DevOps | Deployment docs, CI/CD status, infrastructure diagrams |
+| `src/database/*`, `migrations/*`, `*.sql`, `schema/*` | Database | Schema documentation, migration logs, query optimization |
+| `notebooks/*`, `src/pipelines/*`, `*.ipynb`, `src/models/ml/*` | Data Science | Pipeline documentation, model cards, data validation |
+| `src/mobile/*`, `ios/*`, `android/*`, `*.swift`, `*.kt` | Mobile | Platform-specific docs, app lifecycle, native modules |
+
+**Automatic Invocation Pattern**:
+
+```python
+# Pseudo-code for domain detection from git changes
+changed_files = git_diff("HEAD~1", "HEAD")
+
+detected_domains = []
+if any(".tsx" in f or ".jsx" in f or "src/components/" in f for f in changed_files):
+    detected_domains.append("frontend")
+if any("src/api/" in f or "src/models/" in f or "src/routes/" in f for f in changed_files):
+    detected_domains.append("backend")
+if any("Dockerfile" in f or ".github/workflows/" in f or "docker-compose" in f for f in changed_files):
+    detected_domains.append("devops")
+# ... repeat for all domains
+
+# Invoke domain-specific sync for each detected domain
+for domain in detected_domains:
+    Task(
+        subagent_type="Explore",
+        prompt=f"Generate domain-specific sync report for {domain} changes"
+    )
+```
+
+**Example Invocation** (Frontend + Backend detected):
+
+```python
+# Frontend sync
+Task(
+    subagent_type="Explore",
+    prompt="""You are frontend-expert providing sync documentation.
+
+Changed Files: [src/components/Dashboard.tsx, src/pages/Home.vue]
+
+Provide frontend-specific documentation:
+1. Component documentation updates
+2. Storybook story generation
+3. UI architecture diagram updates
+4. Accessibility compliance notes
+
+Output format: Markdown document for .moai/reports/sync-frontend.md"""
+)
+
+# Backend sync
+Task(
+    subagent_type="Explore",
+    prompt="""You are backend-expert providing sync documentation.
+
+Changed Files: [src/api/auth.py, src/models/user.py, src/routes/users.py]
+
+Provide backend-specific documentation:
+1. OpenAPI spec generation
+2. Schema documentation updates
+3. Error handling documentation
+4. API endpoint examples
+
+Output format: Markdown document for .moai/reports/sync-backend.md"""
+)
+```
+
+**Output Storage Structure**:
+
+```
+.moai/reports/
+├── sync-report-2025-10-23.md          # Combined sync report
+├── sync-frontend-2025-10-23.md        # Frontend-specific sync
+├── sync-backend-2025-10-23.md         # Backend-specific sync
+└── sync-devops-2025-10-23.md          # DevOps-specific sync
+```
+
+**Combined Sync Report Format**:
+
+```markdown
+## 📚 Documentation Sync Report - 2025-10-23
+
+### Changed Files Summary
+- Frontend: 3 files (components, pages)
+- Backend: 5 files (api, models, routes)
+- DevOps: 1 file (Dockerfile)
+
+### Domain-Specific Sync Results
+
+#### 🎨 Frontend Sync
+- ✅ Component documentation: Dashboard.tsx documented
+- ✅ Storybook stories: 2 stories generated
+- ✅ UI architecture: Component hierarchy diagram updated
+- 📄 Details: [sync-frontend-2025-10-23.md](./sync-frontend-2025-10-23.md)
+
+#### ⚙️ Backend Sync
+- ✅ OpenAPI spec: /api/auth endpoints documented
+- ✅ Schema documentation: User model fields updated
+- ✅ Error handling: 401/403 response examples added
+- 📄 Details: [sync-backend-2025-10-23.md](./sync-backend-2025-10-23.md)
+
+#### 🚀 DevOps Sync
+- ✅ Dockerfile: Multi-stage build documented
+- ✅ Deployment: Railway configuration updated
+- 📄 Details: [sync-devops-2025-10-23.md](./sync-devops-2025-10-23.md)
+
+### @TAG Verification
+- ✅ All changed files have @TAG references
+- ✅ SPEC → CODE → TEST → DOC chain intact
+
+### Next Steps
+- Review domain-specific sync reports
+- Update README.md with new features
+- Create PR for documentation changes
+```
+
+**Integration with doc-syncer**:
+
+```python
+# doc-syncer orchestrates domain-specific sync
+Task(
+    subagent_type="doc-syncer",
+    prompt="""You are doc-syncer agent.
+
+DOMAIN SYNC RESULTS:
+{domain_sync_results}
+
+Consolidate all domain-specific sync reports into master sync report.
+Ensure @TAG chain integrity across all domains.
+Update .moai/reports/sync-report-{date}.md
+
+$ARGUMENTS"""
+)
+```
+
+**Graceful Degradation**:
+- If no domain detected → Standard sync (no domain-specific reports)
+- If domain expert unavailable → Use generic sync templates
+- Multi-domain changes → Generate separate reports, combine into master
+
+---
+
 ### Phase 2 Details: SPEC Completion Processing (Automatic)
 
 The doc-syncer agent automatically determines whether TDD implementation is complete and updates SPEC metadata.
@@ -330,9 +529,132 @@ The doc-syncer agent automatically determines whether TDD implementation is comp
 
 **If conditions are not met**: Phase 2 detailed work is automatically skipped
 
+---
+
+### Phase 2-1: SPEC Document Synchronization (CRITICAL)
+
+**IMPORTANT**: Any code or file changes MUST be reflected in SPEC documents to maintain specification alignment.
+
+#### When to synchronize SPEC documents:
+
+1. **After code modifications**:
+   - Functional changes to implemented features
+   - Bug fixes that alter expected behavior
+   - Performance optimizations with observable changes
+   - API/function signature changes
+   - New dependencies or external integrations
+
+2. **After requirement clarifications**:
+   - Acceptance criteria refinements
+   - Edge case discoveries during implementation
+   - User feedback incorporation
+   - Security/compliance adjustments
+
+3. **After structural changes**:
+   - File organization or module restructuring
+   - New configuration options
+   - Breaking API changes
+   - Database schema modifications
+
+#### SPEC documents requiring update:
+
+All files in `.moai/specs/SPEC-{ID}/` must be synchronized:
+
+- **spec.md**: Update EARS requirements if implementation differs from specification
+- **plan.md**: Revise implementation strategy if approach changed
+- **acceptance.md**: Update acceptance criteria if new test cases or edge cases discovered
+
+#### Synchronization rules:
+
+**Code ↔ SPEC Comparison**:
+```
+1. Review Git diff for changed files
+2. Identify functional impacts:
+   ├─ Signature changes (parameters, return values)
+   ├─ Behavior changes (logic flow, edge cases)
+   ├─ Performance characteristics (latency, throughput changes)
+   └─ External dependencies (new APIs, services)
+3. Map changes to SPEC requirements:
+   ├─ Verify each changed function matches EARS statement
+   ├─ Check if acceptance criteria still valid
+   └─ Identify any spec-to-code divergence
+4. Update SPEC documents:
+   ├─ Correct EARS statements to match actual implementation
+   ├─ Add discovered edge cases to acceptance criteria
+   ├─ Update plan.md with implementation changes
+   └─ Maintain TAG references (@SPEC, @CODE, @TEST consistency)
+```
+
+#### Example: When synchronization is needed
+
+**Scenario 1: Bug Fix Changes Behavior**
+```
+Git change: Fixed database connection retry logic
+- Was: Max 3 retries with 1-second delay
+- Now: Max 5 retries with exponential backoff
+
+SPEC update required:
+- spec.md: Update EARS statement for retry behavior
+- acceptance.md: Add test case for exponential backoff
+- Update @CODE TAG location if function moved
+```
+
+**Scenario 2: API Signature Changes**
+```
+Git change: Refactored authentication function signature
+- Was: validate_token(token: str) -> bool
+- Now: validate_token(token: str, ttl: int = 3600) -> dict
+
+SPEC update required:
+- spec.md: Update function requirements for new TTL parameter
+- acceptance.md: Add test cases for TTL validation
+- plan.md: Document reason for signature change
+```
+
+**Scenario 3: New Edge Cases Discovered**
+```
+Git change: Added null-check validation during testing
+- Discovered: Special handling needed for empty strings
+
+SPEC update required:
+- spec.md: Add EARS statement for empty string edge case
+- acceptance.md: Add test case for empty string handling
+- Link with @TEST TAG from test file
+```
+
+#### SPEC-Code Divergence Detection:
+
+**Anti-pattern: Code without matching SPEC**
+```
+❌ WRONG: Code changes exist but SPEC documents unchanged
+- Function behavior diverges from specification
+- Acceptance criteria becomes inaccurate
+- @TAG chain breaks (CODE exists without matching SPEC reference)
+
+✅ CORRECT: Code changes synchronized to SPEC
+- SPEC documents updated to match implementation
+- All EARS statements verified against actual code
+- @TAG chain maintained: SPEC ↔ CODE ↔ TEST ↔ DOC
+```
+
+#### SPEC Synchronization Checklist (doc-syncer responsibility):
+
+Before marking sync as complete:
+- [ ] All changed code files reviewed against SPEC
+- [ ] EARS statements match implementation behavior
+- [ ] Acceptance criteria valid for current code
+- [ ] Edge cases discovered during implementation added to SPEC
+- [ ] @CODE/@TEST TAGs point to correct locations
+- [ ] @SPEC TAG references updated if files reorganized
+- [ ] HISTORY section updated if version changed
+- [ ] No spec-code divergence remains
+
+---
+
 ## function
 
 - **Automatic Document Synchronization**: The doc-syncer agent performs Living Document synchronization and @TAG updates. Optionally implements the PR Ready transition only in team mode.
+- **SPEC-Code Alignment**: doc-syncer verifies that SPEC documents match implemented code and updates them when changes are detected.
 
 ## Synchronization output
 
@@ -590,6 +912,85 @@ Report synchronization results in a structured format:
 3. Orphan TAG cleanup
 ```
 
+## 🎯 PR Merge Strategy Selection (DECISION POINT 2)
+
+After document synchronization completes successfully, Alfred checks team mode and invokes AskUserQuestion for PR merge strategy:
+
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "Document synchronization complete. How would you like to handle the PR?",
+            "header": "PR Merge Strategy",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "🤖 Auto-Merge (Recommended)",
+                    "description": "Automatically merge PR and clean up branch (team mode)"
+                },
+                {
+                    "label": "📋 Manual Review",
+                    "description": "Keep PR in Ready state for manual review and merge"
+                },
+                {
+                    "label": "✏️ Keep as Draft",
+                    "description": "Maintain PR in draft state for further refinement"
+                },
+                {
+                    "label": "🔄 New Cycle",
+                    "description": "Save changes and start new feature (skip PR for now)"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**Response Processing**:
+- **🤖 Auto-Merge** (`answers["0"] === "Auto-Merge"`) → Execute PR auto-merge with CI checks, update develop branch
+- **📋 Manual Review** (`answers["0"] === "Manual"`) → Transition PR to Ready state, notify reviewers
+- **✏️ Keep as Draft** (`answers["0"] === "Draft"`) → Leave PR in draft, ready for refinement
+- **🔄 New Cycle** (`answers["0"] === "New"`) → Skip PR handling, proceed to next feature planning
+
+---
+
+## Final Step
+
+After PR strategy is confirmed, Alfred invokes AskUserQuestion to ask the user what to do next:
+
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "Documentation synchronization complete. What would you like to do next?",
+            "header": "Next Steps",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "📋 Create Next SPEC",
+                    "description": "Start new feature planning with /alfred:1-plan"
+                },
+                {
+                    "label": "📤 Merge PR",
+                    "description": "Review and merge PR to develop branch"
+                },
+                {
+                    "label": "🔄 Start New Session",
+                    "description": "Execute /clear for fresh session (recommended for performance)"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**User Responses**:
+- **📋 Create Next SPEC**: Proceed to `/alfred:1-plan` for creating next SPEC
+- **📤 Merge PR**: Manual PR review and merge on GitHub
+- **🔄 Start New Session**: Execute `/clear` to start fresh session (recommended for performance)
+
+---
+
 ## Next steps guidance
 
 ### Development cycle complete
@@ -670,7 +1071,7 @@ Report synchronization results in a structured format:
 
 ## 🧠 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
 

moai_adk/templates/.claude/commands/alfred/9-feedback.md

@@ -1,6 +1,6 @@
 ---
 name: alfred:9-feedback
-description: "Interactive GitHub Issue creation - Step-by-step dialog to create issues without command arguments"
+description: "Create GitHub issues interactively"
 allowed-tools:
 - Bash(gh:*)
 - Task