moai-adk 0.8.0__py3-none-any.whl → 0.15.0__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
 
@@ -102,87 +104,147 @@ 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)
 
-**If your TAG chain is complex or extensive**, utilize the Explore agent first:
+**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)
+
+#### How to invoke Explore agent:
 
 ```
 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"
 ```
 
-**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)
 
-### ⚙️ How to call an agent
+**Call tag-agent and doc-syncer to verify TAG integrity and plan synchronization.**
 
-**In STEP 1, call doc-syncer and tag-agent using the Task tool**:
+This phase is **always required** and runs **two agents sequentially**:
+
+#### How to invoke agents:
 
 ```
 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 에이전트입니다.
+
+언어 설정:
+- 대화_언어: {{CONVERSATION_LANGUAGE}}
+- 언어명: {{CONVERSATION_LANGUAGE_NAME}}
 
-LANGUAGE CONFIGURATION:
-- conversation_language: {{CONVERSATION_LANGUAGE}}
-- language_name: {{CONVERSATION_LANGUAGE_NAME}}
+중요 지시사항:
+문서 업데이트는 대화_언어를 반드시 존중해야 합니다:
+- 사용자 대면 문서 (README, 가이드): {{CONVERSATION_LANGUAGE}}
+- SPEC 문서 (spec.md, plan.md, acceptance.md): {{CONVERSATION_LANGUAGE}}
+- 코드 주석: {{CONVERSATION_LANGUAGE}} (기술 키워드 제외)
+- 기술 문서 및 YAML 프론트매터: 영어
 
-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
+스킬 호출:
+필요 시 명시적 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**:
+- **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**
@@ -254,6 +316,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.
@@ -270,9 +496,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
 
@@ -530,6 +879,43 @@ Report synchronization results in a structured format:
 3. Orphan TAG cleanup
 ```
 
+## Final Step
+
+After document synchronization completes, Alfred automatically invokes AskUserQuestion to ask the user what to do next:
+
+```python
+AskUserQuestion(
+    questions=[
+        {
+            "question": "문서 동기화가 완료되었습니다. 다음으로 뭘 하시겠습니까?",
+            "header": "다음 단계",
+            "multiSelect": false,
+            "options": [
+                {
+                    "label": "📋 다음 스펙 작성",
+                    "description": "/alfred:1-plan으로 새로운 기능 SPEC 작성"
+                },
+                {
+                    "label": "📤 PR 병합",
+                    "description": "GitHub에서 PR 검토 및 병합 진행"
+                },
+                {
+                    "label": "🔄 새 세션 시작",
+                    "description": "성능 최적화를 위해 /clear 실행"
+                }
+            ]
+        }
+    ]
+)
+```
+
+**User Responses**:
+- **📋 다음 스펙 작성**: Proceed to `/alfred:1-plan` for creating next SPEC
+- **📤 PR 병합**: Manual PR review and merge on GitHub
+- **🔄 새 세션 시작**: Execute `/clear` to start fresh session (recommended for performance)
+
+---
+
 ## Next steps guidance
 
 ### Development cycle complete
@@ -610,7 +996,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