moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/commands/alfred/2-run.md

@@ -1,7 +1,7 @@
 ---
 name: alfred:2-run
-description: "Implement all SPECs with SPEC ID to implement (e.g. SPEC-001) or all - Execute planned work (TDD implementation, prototyping, documentation, etc.)" 
-argument-hint: "SPEC-ID - All with SPEC ID to implement (e.g. SPEC-001) or all “SPEC Implementation”
+description: "Execute TDD implementation cycle"
+argument-hint: "SPEC-ID - All with SPEC ID to implement (e.g. SPEC-001) or all \"SPEC Implementation\""
 allowed-tools:
   - Read
   - Write
@@ -20,17 +20,24 @@ allowed-tools:
 ---
 
 # ⚒️ MoAI-ADK Phase 2: Run the plan - Flexible implementation strategy
-> Interactive prompts rely on `Skill("moai-alfred-tui-survey")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
+
+> **Critical Note**: ALWAYS invoke `Skill("moai-alfred-ask-user-questions")` before using `AskUserQuestion` tool. This skill provides up-to-date best practices, field specifications, and validation rules for interactive prompts.
+>
+> **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-002:CMD-RUN -->
+
+**4-Step Workflow Integration**: This command implements Step 3 of Alfred's workflow (Task Execution with TodoWrite tracking). See CLAUDE.md for full workflow details.
 
 ## 🎯 Command Purpose
 
-Analyze SPEC documents to execute planned tasks. It supports not only TDD implementation but also various execution scenarios such as prototyping and documentation work.
+Execute planned tasks based on SPEC document analysis. Supports TDD implementation, prototyping, and documentation work.
 
 **Run on**: $ARGUMENTS
 
-## 💡 Execution philosophy: “Plan → Run → Sync”
+## 💡 Execution philosophy: "Plan → Run → Sync"
 
-`/alfred:2-run` is a general-purpose command that does not simply "build" code, but **performs** a planned task.
+`/alfred:2-run` performs planned tasks through various execution strategies.
 
 ### 3 main scenarios
 
@@ -55,259 +62,358 @@ Analyze SPEC documents to execute planned tasks. It supports not only TDD implem
 → API documentation, tutorials, guides, etc.
 ```
 
-> **Standard two-step workflow** (see `CLAUDE.md` - "Alfred Command Execution Pattern" for details)
-
 ## 📋 Execution flow
 
 1. **SPEC Analysis**: Requirements extraction and complexity assessment
-2. **Establishment of implementation strategy**: Determine the optimized approach for each language (TDD, prototype, documentation, etc.)
+2. **Implementation Strategy**: Determine optimized approach (TDD, prototype, documentation)
 3. **User Confirmation**: Review and approve action plan
-4. **Execute work**: Perform work according to the approved plan
-5. **Git Operations**: Creating step-by-step commits with git-manager
+4. **Execute Task**: Perform work according to approved plan
+5. **Git Operations**: Create step-by-step commits with git-manager
 
 ## 🧠 Associated Skills & Agents
 
-| Agent | Core Skill | Purpose |
-| ----- | -------- | ------- |
+| Agent                  | Core Skill                       | Purpose                                 |
+| ---------------------- | -------------------------------- | --------------------------------------- |
 | implementation-planner | `moai-alfred-language-detection` | Detect language and design architecture |
-| tdd-implementer | `moai-essentials-debug` | Implement TDD (RED → GREEN → REFACTOR) |
-| quality-gate | `moai-alfred-trust-validation` | Verify TRUST 5 principles |
-| git-manager | `moai-alfred-git-workflow` | Commit and manage Git workflows |
+| tdd-implementer        | `moai-essentials-debug`          | Implement TDD (RED → GREEN → REFACTOR)  |
+| quality-gate           | `moai-alfred-trust-validation`   | Verify TRUST 5 principles               |
+| git-manager            | `moai-alfred-git-workflow`       | Commit and manage Git workflows         |
 
 **Note**: TUI Survey Skill is used for user confirmations during the run phase and is shared across all interactive prompts.
 
 ## 🔗 Associated Agent
 
-- **Phase 1**: implementation-planner (📋 technical architect) - SPEC analysis and establishment of execution strategy
-- **Phase 2**: tdd-implementer (🔬 senior developer) - Dedicated to execution work
-- **Phase 2.5**: quality-gate (🛡️ Quality Assurance Engineer) - TRUST principle verification (automatically)
-- **Phase 3**: git-manager (🚀 Release Engineer) - Dedicated to Git commits
+- **Phase 1**: implementation-planner (📋 technical architect) - SPEC analysis and execution strategy
+- **Phase 2**: tdd-implementer (🔬 senior developer) - Task execution
+- **Phase 2.5**: quality-gate (🛡️ Quality Assurance Engineer) - TRUST principle verification (automatic)
+- **Phase 3**: git-manager (🚀 Release Engineer) - Git commits
 
-## 💡 Example of use
+## 💡 Example Usage
 
 Users can run commands as follows:
 - `/alfred:2-run SPEC-001` - Run a specific SPEC
 - `/alfred:2-run all` - Run all SPECs in batches
 - `/alfred:2-run SPEC-003 --test` - Run only tests
 
-## 🔍 STEP 1: SPEC analysis and execution plan establishment
-
-First, the specified SPEC is analyzed to establish an action plan and receive user confirmation.
-
-**The implementation-planner agent automatically loads and analyzes the required documents.**
-
-### 🔍 Browse the code base (recommended)
-
-**If you need to understand existing code structure or find similar patterns** Use the Explore agent first:
-
-```
-Invoking the Task tool (Explore agent):
-- subagent_type: "Explore"
-- description: "Explore existing code structures and patterns"
-- prompt: "Please explore existing code related to SPEC-$ARGUMENTS:
- - Similar function implementation code (src/)
- - Test patterns for reference (tests/)
- - Architectural patterns and design patterns
- - Use 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
-
-### ⚙️ How to call an agent
-
-**In STEP 1, we call the implementation-planner agent using the Task tool**:
-
-```
-Task tool call example:
-- 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
- 4. Step-by-step execution plan
- 5. Risks and response plans
-6. Create action plan and use `Skill("moai-alfred-tui-survey")` to confirm the next action with the user
- (Optional) Explore results: $EXPLORE_RESULTS"
-```
-
-### SPEC analysis in progress
-
-1. **SPEC document analysis**
- - Requirements extraction and complexity assessment
- - Check technical constraints
- - Dependency and impact scope analysis
- - (Optional) Identify existing code structure based on Explore results
-
-2. **Establish execution strategy**
- - Detect project language and optimize execution strategy
- - Determine approach (TDD, prototyping, documentation, etc.)
- - Estimate expected work scope and time
-
-3. **Check and specify library versions (required)**
- - **Web search**: Check the latest stable versions of all libraries to be used through `WebSearch`
- - **Specify versions**: Specify the exact version for each library in the implementation plan report (e.g. `fastapi>=0.118.3`)
- - **Stability priority**: Exclude beta/alpha versions, select only production stable versions
- - **Check compatibility**: Verify version compatibility between libraries
- - **Search keyword examples**:
-     - `"FastAPI latest stable version 2025"`
-     - `"SQLAlchemy 2.0 latest stable version 2025"`
-     - `"React 18 latest stable version 2025"`
-
-4. **Report action plan**
- - Present step-by-step action plan
- - Identify potential risk factors
- - Set quality gate checkpoints
- - **Specify library version (required)**
-
-### User verification steps
-
-After reviewing the action plan, select one of the following:
-- **"Proceed"** or **"Start"**: Start executing the task as planned
-- **"Modify [Content]"**: Request a plan modification
-- **"Abort"**: Stop the task
-
 ---
 
-## 🚀 STEP 2: Execute task (after user approval)
-
-After user approval (gathered through `Skill("moai-alfred-tui-survey")`), **call the tdd-implementer agent using the Task tool**.
-
-### ⚙️ How to call an agent
+## 🔍 YOUR TASK: STEP 1 - SPEC Analysis and Execution Planning
+
+Your task is to analyze SPEC requirements and create an execution plan. Follow these steps:
+
+### STEP 1.1: Determine if Codebase Exploration is Needed
+
+Read the SPEC document at `.moai/specs/SPEC-$ARGUMENTS/spec.md`.
+
+IF the SPEC requires understanding existing code patterns (architecture, similar implementations, test patterns), THEN:
+  - Invoke the Explore agent using the Task tool
+  - Set subagent_type to "Explore"
+  - Set description to "Explore existing code structures and patterns"
+  - Pass prompt: "SPEC-$ARGUMENTS와 관련된 기존 코드를 탐색해주세요: 유사한 기능 구현 코드 (src/), 참고할 테스트 패턴 (tests/), 아키텍처 패턴 및 디자인 패턴, 현재 라이브러리 및 버전 (package.json, requirements.txt). 상세도 수준: medium"
+  - Store exploration results in memory for next step
+
+IF the SPEC does not require codebase exploration (greenfield implementation, simple feature), THEN:
+  - Skip exploration phase
+  - Proceed directly to STEP 1.2
+
+### STEP 1.2: Create Implementation Plan
+
+Invoke the implementation-planner agent using the Task tool:
+  - Set subagent_type to "implementation-planner"
+  - Set description to "SPEC analysis and establishment of execution strategy"
+  - Pass prompt including:
+    - SPEC ID ($ARGUMENTS)
+    - Requirements extraction and complexity assessment
+    - Library and tool selection (use WebFetch for latest stable versions)
+    - TAG chain design
+    - Step-by-step execution plan
+    - Risk factors and mitigation strategies
+    - (Optional) Exploration results from STEP 1.1 if available
+  - Request that the agent creates an action plan report
+
+The implementation-planner agent will:
+  1. Analyze SPEC requirements and assess complexity
+  2. Check technical constraints and dependencies
+  3. Detect project language and optimize execution strategy
+  4. Search for latest stable library versions using WebFetch
+  5. Design TAG chain and execution sequence
+  6. Create step-by-step action plan with risk assessment
+  7. Generate execution plan report
+
+### STEP 1.3: Present Plan to User for Approval
+
+After the implementation-planner completes the execution plan, invoke `Skill("moai-alfred-ask-user-questions")` first.
+
+Then use the AskUserQuestion tool to obtain explicit user approval:
+  - Present the implementation plan in plain text format
+  - Ask "Implementation plan is ready. How would you like to proceed?"
+  - Provide these options:
+    - "Proceed with TDD" - Start RED → GREEN → REFACTOR cycle
+    - "Research First" - Invoke Explore agent to study existing code patterns
+    - "Modify Strategy" - Request changes to implementation approach
+    - "Postpone" - Save plan and return later
+  - Wait for user response
+
+**Response handling:**
+
+IF user selects "Proceed with TDD", THEN:
+  - Display "Starting RED phase..."
+  - Proceed to STEP 2 (TDD Implementation)
+
+IF user selects "Research First", THEN:
+  - Display "Codebase exploration complete. Plan updated."
+  - Invoke Explore agent to analyze existing codebase
+  - Pass exploration results back to implementation-planner
+  - Re-generate updated plan with research insights
+  - Present updated plan for approval again (recursive - return to STEP 1.3)
+
+IF user selects "Modify Strategy", THEN:
+  - Display "Plan modified. Please review updated strategy."
+  - Collect strategy modification requests from user
+  - Update implementation plan with requested changes
+  - Present updated plan for approval again (recursive - return to STEP 1.3)
+
+IF user selects "Postpone", THEN:
+  - Display "Plan saved. Resume with `/alfred:2-run SPEC-{ID}`"
+  - Save plan to `.moai/specs/SPEC-{ID}/plan.md`
+  - Create git commit with message "plan(spec): Save implementation plan for SPEC-{ID}"
+  - Stop execution
+  - User can resume later by running `/alfred:2-run SPEC-{ID}`
 
-**STEP 2 calls tdd-implementer using the Task tool**:
-
-```
-Task tool call example:
-- subagent_type: "tdd-implementer"
-- description: "Execute task"
-- prompt: "Please execute the task according to the plan approved in STEP 1.
- For TDD scenario:
- - Perform RED → GREEN → REFACTOR cycle,
- Perform the following for each TAG:
- 1. RED Phase: Write a test that fails with the @TEST:ID tag
- 2. GREEN Phase: Minimal implementation with the @CODE:ID tag
- 3. REFACTOR Phase: Improve code quality
- 4. Verify TAG completion conditions and proceed to the next TAG
-
-Execute on: $ARGUMENTS"
-```
-
-## 🔗 TDD optimization for each language
-
-### Project language detection and optimal routing
-
-`tdd-implementer` automatically detects the language of your project and selects the optimal TDD tools and workflow:
-
-- **Language detection**: Analyze project files (package.json, pyproject.toml, go.mod, etc.)
-- **Tool selection**: Automatically select the optimal test framework for each language
-- **TAG application**: Write @TAG annotations directly in code files
-- **Run cycle**: RED → GREEN → REFACTOR sequential process
-
-### TDD tool mapping
-
-#### Backend/System
-
-| SPEC Type | Implementation language | Test Framework | Performance Goals | Coverage Goals |
-|-----------|-----------|-------------------|-----------|---------------|
-| **CLI/System** | TypeScript | jest + ts-node | < 18ms | 95%+ |
-| **API/Backend** | TypeScript | Jest + SuperTest | < 50ms | 90%+ |
-| **Frontend** | TypeScript | Jest + Testing Library | < 100ms | 85%+ |
-| **Data Processing** | TypeScript | Jest + Mock | < 200ms | 85%+ |
-| **Python Project** | Python | pytest + mypy | Custom | 85%+ |
-
-#### Mobile Framework
-
-| SPEC Type | Implementation language | Test Framework | Performance Goals | Coverage Goals |
-|-----------|-----------|-------------------|-----------|---------------|
-| **Flutter App** | Dart | flutter test + widget test | < 100ms | 85%+ |
-| **React Native** | TypeScript | Jest + RN Testing Library | < 100ms | 85%+ |
-| **iOS App** | Swift | XCTest + XCUITest | < 150ms | 80%+ |
-| **Android App** | Kotlin | JUnit + Espresso | < 150ms | 80%+ |
-
-## 🚀 Optimized agent collaboration structure
-
-- **Phase 1**: `implementation-planner` agent analyzes SPEC and establishes execution strategy
-- **Phase 2**: `tdd-implementer` agent executes tasks (TDD cycle, prototyping, documentation, etc.)
-- **Phase 2.5**: `quality-gate` agent verifies TRUST principle and quality verification (automatically)
-- **Phase 3**: `git-manager` agent processes all commits at once after task completion
-- **Single responsibility principle**: Each agent is responsible only for its own area of expertise
-- **Inter-agent call prohibited**: Each agent runs independently, sequential calls are made only at the command level
-
-## 🔄 Step 2 Workflow Execution Order
-
-### Phase 1: Analysis and planning phase
-
-The `implementation-planner` agent does the following:
-
-1. **SPEC document analysis**: Requirements extraction and complexity assessment of specified SPEC ID
-2. **Library selection**: Check the latest stable version and verify compatibility through WebFetch
-3. **TAG chain design**: Determine TAG order and dependency
-4. **Establishment of implementation strategy**: Step-by-step implementation plan and risk identification
-5. **Create action plan**: Create a structured plan and, via `Skill("moai-alfred-tui-survey")`, collect user approval before proceeding
+---
 
-### Phase 2: Task execution phase (after approval)
+## 🚀 YOUR TASK: STEP 2 - Execute Task (After User Approval)
+
+Your task is to execute the approved implementation plan. Follow these steps:
+
+### STEP 2.1: Check Domain Readiness (Optional - Before Implementation)
+
+Read the SPEC metadata to identify required domains.
+
+IF SPEC frontmatter contains `domains:` field OR `.moai/config.json` has `stack.selected_domains`, THEN:
+  - For each domain in the list:
+    - IF domain is "frontend", THEN invoke Task with subagent_type "Explore" and prompt: "You are consulting as frontend-expert for TDD implementation. SPEC: [SPEC-{ID}]. Provide implementation readiness check: Component structure recommendations, State management approach, Testing strategy, Accessibility requirements, Performance optimization tips. Output: Brief advisory for tdd-implementer (3-4 key points)"
+    - IF domain is "backend", THEN invoke Task with subagent_type "Explore" and prompt: "You are consulting as backend-expert for TDD implementation. SPEC: [SPEC-{ID}]. Provide implementation readiness check: API contract validation, Database schema requirements, Authentication/authorization patterns, Error handling strategy, Async processing considerations. Output: Brief advisory for tdd-implementer (3-4 key points)"
+    - IF domain is "devops", THEN invoke Task with subagent_type "Explore" and domain-specific readiness check
+    - IF domain is "database", THEN invoke Task with subagent_type "Explore" and database-specific readiness check
+    - IF domain is "data-science", THEN invoke Task with subagent_type "Explore" and data-science-specific readiness check
+    - IF domain is "mobile", THEN invoke Task with subagent_type "Explore" and mobile-specific readiness check
+  - Store all domain expert feedback in memory
+  - Save advisory to `.moai/specs/SPEC-{ID}/plan.md` under "## Domain Expert Advisory (Implementation Phase)" section
+
+IF no domains specified OR domain expert unavailable, THEN:
+  - Skip advisory phase
+  - Continue to STEP 2.2 (implementation proceeds regardless)
+
+### STEP 2.2: Invoke TDD Implementer Agent
+
+Invoke the tdd-implementer agent using the Task tool:
+  - Set subagent_type to "tdd-implementer"
+  - Set description to "Execute task with TDD implementation"
+  - Pass prompt including:
+    - SPEC ID ($ARGUMENTS)
+    - Language settings (conversation_language, conversation_language_name)
+    - Code and technical output must be in English
+    - Code comments language rules (local project vs package code)
+    - Test descriptions and documentation language
+    - Skill invocation instructions (moai-alfred-language-detection, language-specific skills, debug, refactor)
+    - Approved plan from STEP 1
+    - Domain expert advisory from STEP 2.1 (if available)
+    - TDD cycle instructions: RED → GREEN → REFACTOR
+    - For each TAG: Write failing test (@TEST:ID) → Minimal implementation (@CODE:ID) → Code quality improvement
+    - TAG completion verification and progression
+
+The tdd-implementer agent will:
+  1. Detect project language and select optimal TDD tools
+  2. Execute RED phase: Write failing tests with @TEST:ID tags, verify test failure
+  3. Execute GREEN phase: Write minimal implementation with @CODE:ID tags, verify test pass
+  4. Execute REFACTOR phase: Improve code quality (remove duplication, explicit naming, structured logging/exception handling)
+  5. Verify TAG completion conditions and proceed to next TAG
+  6. Repeat cycle for all TAGs in the plan
+
+### STEP 2.3: Monitor TDD Cycle Progress
+
+During tdd-implementer execution:
+  - Initialize TodoWrite with all tasks from the implementation plan
+  - Set initial status to "pending" for all tasks
+  - For each task:
+    - Update TodoWrite status from "pending" to "in_progress" (exactly ONE task at a time)
+    - Monitor tdd-implementer progress
+    - Update TodoWrite status from "in_progress" to "completed" when task finishes
+  - Track RED → GREEN → REFACTOR cycle completion for each TAG
+
+IF tdd-implementer encounters errors or test failures, THEN:
+  - Keep task in "in_progress" status
+  - Invoke Skill("moai-essentials-debug") for troubleshooting
+  - Log error details
+  - Attempt fix and retry
+  - IF error persists after retry, THEN escalate to user for manual intervention
+
+### STEP 2.4: Quality Gate Verification (Automatic)
+
+After tdd-implementer completes all tasks, automatically invoke the quality-gate agent:
+  - Set subagent_type to "quality-gate"
+  - Set description to "TRUST principle verification and quality validation"
+  - Pass prompt to verify:
+    - TRUST principles (Test coverage ≥ 85%, Readable code, Unified architecture, Secured, Traceable @TAG chain)
+    - Code style (run linter: ESLint/Pylint)
+    - Test coverage (run language-specific coverage tools)
+    - TAG chain integrity (check orphan TAGs, missing TAGs)
+    - Dependency security (check vulnerabilities)
+
+The quality-gate agent will generate a verification report.
+
+**Handle verification results:**
+
+IF verification result is PASS (0 Critical, ≤5 Warnings), THEN:
+  - Display "Quality gate passed."
+  - Create quality report
+  - Proceed to STEP 3 (Git operations)
+
+IF verification result is WARNING (0 Critical, ≥6 Warnings), THEN:
+  - Display warning message with details
+  - Use AskUserQuestion to ask: "Quality gate has warnings. How would you like to proceed?"
+    - Option 1: "Continue to Git commit" - Accept warnings and proceed to STEP 3
+    - Option 2: "Fix warnings first" - Return to tdd-implementer to address warnings
+  - Wait for user response
+  - IF user selects "Continue", THEN proceed to STEP 3
+  - IF user selects "Fix warnings first", THEN return to STEP 2.2 with warning details
+
+IF verification result is CRITICAL (≥1 Critical), THEN:
+  - Display "Quality gate blocked. Critical issues found."
+  - Block Git commits
+  - Generate detailed report with file:line information
+  - Display report to user
+  - Recommend re-invoking tdd-implementer to fix critical issues
+  - Stop execution
+  - Wait for user to fix issues and re-run command
+
+IF user passed `--skip-quality-check` flag, THEN:
+  - Skip quality gate verification
+  - Display "Quality gate skipped (user requested)."
+  - Proceed directly to STEP 3
 
-The `tdd-implementer` agent performs **TAG-by-TAG** after user approval (based on TDD scenario):
+---
 
-1. **RED Phase**: Write a failing test (add @TEST:ID tag) and check for failure
-2. **GREEN Phase**: Write minimal code that passes the test (add @CODE:ID tag)
-3. **REFACTOR Phase**: Improve code quality (without changing functionality)
-4. **TAG completion confirmation**: Verify the completion conditions of each TAG and proceed to the next TAG
+## 🚀 YOUR TASK: STEP 3 - Git Operations (After Quality Gate)
+
+Your task is to create Git commits for all completed work. Follow these steps:
+
+### STEP 3.1: Invoke Git Manager Agent
+
+Invoke the git-manager agent using the Task tool:
+  - Set subagent_type to "git-manager"
+  - Set description to "Create Git commits for completed implementation"
+  - Pass prompt including:
+    - SPEC ID ($ARGUMENTS)
+    - List of all completed tasks from TodoWrite
+    - TDD cycle phases (RED → GREEN → REFACTOR)
+    - Quality gate results
+    - Git strategy from `.moai/config.json` (team mode: GitFlow with develop branch)
+    - Request structured commits with proper tagging
+
+The git-manager agent will:
+  1. Create checkpoint backup before starting Git operations
+  2. Create structured commits for each TDD phase:
+     - RED commit: "test(SPEC-{ID}): Add failing tests for {feature}"
+     - GREEN commit: "feat(SPEC-{ID}): Implement {feature}"
+     - REFACTOR commit: "refactor(SPEC-{ID}): Improve {aspect}"
+  3. Apply Git strategy based on mode (team: feature branch → develop, solo: direct to main)
+  4. Verify commits created successfully
+  5. Display commit summary to user
+
+### STEP 3.2: Handle Git Strategy (Team Mode)
+
+Read Git configuration from `.moai/config.json`:
+  - Read `git_strategy.team.use_gitflow` field
+  - Read `git_strategy.team.develop_branch` field (default: "develop")
+
+IF use_gitflow is true, THEN:
+  - Verify current branch is feature branch (feature/SPEC-*)
+  - Verify develop branch exists
+  - Do NOT create PR to main (forbidden)
+  - Wait for user to manually merge develop → main when ready
+  - Display: "Commits created on feature branch. Run `/alfred:3-sync` to create PR targeting develop."
+
+IF use_gitflow is false (solo mode), THEN:
+  - Commit directly to current branch
+  - Push to remote if configured
+  - Display: "Commits created and pushed."
+
+### STEP 3.3: Verify Commit Success
+
+After git-manager completes:
+  - Run `git log --oneline -5` to verify commits were created
+  - Check commit messages follow the format:
+    ```
+    {type}(SPEC-{ID}): {description}
+
+    {detailed explanation if needed}
+
+    🤖 Generated with Claude Code
+
+    Co-Authored-By: 🎩 Alfred@MoAI
+    ```
+  - Verify commit author and timestamp
+  - Display commit summary to user
+
+IF commits were not created successfully, THEN:
+  - Display error message
+  - Show git status output
+  - Recommend manual Git operations
+  - Stop execution
 
-### Phase 2.5: Quality verification gate (automatic execution)
+---
 
-After the job execution is complete, the `quality-gate` agent **automatically** performs quality verification.
+## 🎯 YOUR TASK: STEP 4 - Next Steps (Final)
 
-**Automatic execution conditions**:
-- Automatically invoked upon completion of task execution
-- Manually invoked upon user request
+Your task is to guide the user on what to do next. Follow these steps:
 
-**Verification items**:
-- **TRUST principle verification**: Trust-checker script execution and result parsing
- - T (Testable): Test coverage ≥ 85%
- - R (Readable): Code readability (file≤300 LOC, function≤50 LOC, Complexity≤10)
- - U (Unified): Architectural integrity
- - S (Secured): No security vulnerabilities
- - T (Traceable): @TAG chain integrity
-- **Code style**: Run and verify linter (ESLint/Pylint)
-- **Test Coverage**: Run language-specific coverage tools and verify goal achievement
-- **TAG chain verification**: Check orphan TAGs, missing TAGs
-- **Dependency verification**: Check security vulnerabilities
+### STEP 4.1: Present Next Steps Options
 
-**How ​​it works**: When Alfred completes job execution, it automatically calls the quality-gate agent to perform quality verification.
+After STEP 3 completes successfully, invoke `Skill("moai-alfred-ask-user-questions")` first.
 
-**Handling verification results**:
+Then use the AskUserQuestion tool to ask the user:
+  - Ask "Implementation is complete. What would you like to do next?"
+  - Provide these options:
+    - "Synchronize Documentation" - Proceed to /alfred:3-sync for documentation synchronization
+    - "Implement More Features" - Continue with /alfred:2-run SPEC-XXX for next feature
+    - "New Session" - Execute /clear for better context management (recommended after large implementations)
+    - "Complete" - Finish current session
+  - Wait for user response
 
-✅ **PASS (0 Critical, 5 or less Warnings)**:
-- Proceed to Phase 3 (Git work)
-- Create a quality report
+**Response handling:**
 
-⚠️ **WARNING (0 Critical, 6 or more Warnings)**:
-- Display warning
-- User choice: "Continue" or "Re-verify after modification"
+IF user selects "Synchronize Documentation", THEN:
+  - Display "Starting documentation synchronization..."
+  - Inform user to run: `/alfred:3-sync auto`
+  - Explain that this will verify TAGs, update docs, and prepare for PR merge
 
-❌ **CRITICAL (1 or more Critical)**:
-- Block Git commits
-- Detailed report on items requiring improvement (including file: line information)
-- Recommended tdd-implementer re-invocation
+IF user selects "Implement More Features", THEN:
+  - Display "Ready for next feature implementation..."
+  - Inform user to run: `/alfred:2-run SPEC-YYY` for another feature
+  - Note that current session context will be maintained
 
-**Skip verification option**: To skip quality verification, use the `--skip-quality-check` option.
+IF user selects "New Session", THEN:
+  - Display "Clearing session for better context management..."
+  - Explain that this is recommended after large implementations
+  - Inform user they can run any command in the next session
 
-### Phase 3: Git operations (git-manager)
+IF user selects "Complete", THEN:
+  - Display "Implementation workflow complete!"
+  - Recommend running `/alfred:3-sync` manually when ready
+  - Suggest reviewing work or planning next features
 
-After the `git-manager` agent completes the task **at once**:
+### STEP 4.2: Display Summary
 
-1. **Create checkpoint**: Backup point before starting work
-2. **Structured Commit**: Step-by-step commit creation (RED→GREEN→REFACTOR for TDD)
-3. **Final synchronization**: Apply Git strategy for each mode and remote synchronization
+After user responds, display a plain text summary:
+  - SPEC ID implemented
+  - Number of TAGs completed
+  - Number of commits created
+  - Quality gate result (PASS/WARNING/CRITICAL)
+  - Next recommended action based on user selection
 
+---
 
 ## 📋 STEP 1 Execution Guide: SPEC Analysis and Planning
 
@@ -326,13 +432,13 @@ Alfred calls the implementation-planner agent to check the SPEC document and cre
 
 #### TypeScript execution criteria
 
-| SPEC characteristics | execution language | Reason |
-|-----------|-----------|------|
-| CLI/System Tools | TypeScript | High performance (18ms), type safety, SQLite3 integration |
-| API/Backend | TypeScript | Node.js ecosystem, Express/Fastify compatibility |
-| Frontend | TypeScript | React/Vue native support |
-| data processing | TypeScript | High-performance asynchronous processing, type safety |
-| User Python Project | Python tool support | MoAI-ADK provides Python project development tools |
+| SPEC characteristics | execution language  | Reason                                                    |
+| -------------------- | ------------------- | --------------------------------------------------------- |
+| CLI/System Tools     | TypeScript          | High performance (18ms), type safety, SQLite3 integration |
+| API/Backend          | TypeScript          | Node.js ecosystem, Express/Fastify compatibility          |
+| Frontend             | TypeScript          | React/Vue native support                                  |
+| data processing      | TypeScript          | High-performance asynchronous processing, type safety     |
+| User Python Project  | Python tool support | MoAI-ADK provides Python project development tools        |
 
 #### Approach
 
@@ -359,16 +465,16 @@ Present your plan in the following format:
 
 ### 📦 Library version (required - based on web search)
 **Backend dependencies** (example):
-| package | Latest stable version | installation command |
-|--------|--------------|----------|
-| FastAPI | 0.118.3 | fastapi>=0.118.3 |
-| SQLAlchemy | 2.0.43 | sqlalchemy>=2.0.43 |
+| package    | Latest stable version | installation command |
+| ---------- | --------------------- | -------------------- |
+| FastAPI    | 0.118.3               | fastapi>=0.118.3     |
+| SQLAlchemy | 2.0.43                | sqlalchemy>=2.0.43   |
 
 **Frontend dependency** (example):
 | package | Latest stable version | installation command |
-|--------|--------------|----------|
-| React | 18.3.1 | react@^18.3.1 |
-| Vite | 7.1.9 | vite@^7.1.9 |
+| ------- | --------------------- | -------------------- |
+| React   | 18.3.1                | react@^18.3.1        |
+| Vite    | 7.1.9                 | vite@^7.1.9          |
 
 **Important Compatibility Information**:
 - [Specific Version Requirements]
@@ -386,7 +492,7 @@ Present your plan in the following format:
 
 ---
 **Approval Request**: Do you want to proceed with the above plan?
- (Choose between “Proceed,” “Modify [Content],” or “Abort”)
+ (Choose between "Proceed," "Modify [Content]," or "Abort")
 ```
 
 ---
@@ -397,7 +503,7 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the tdd-i
 
 ### TDD step-by-step guide
 
-1. **RED**: Writing failure tests with Given/When/Then structure. Follow test file rules for each language and simply record failure logs. 
+1. **RED**: Writing failure tests with Given/When/Then structure. Follow test file rules for each language and simply record failure logs.
 2. **GREEN**: Add only the minimal implementation that makes the tests pass. Optimization is postponed to the REFACTOR stage.
 3. **REFACTOR**: Removal of duplication, explicit naming, structured logging/exception handling enhancements. Split into additional commits if necessary.
 
@@ -408,6 +514,47 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the tdd-i
 
 > TRUST 5 principles provide only basic recommendations, so if you need a structure that exceeds `simplicity_threshold`, proceed with the basis in SPEC or ADR.
 
+## 🔗 TDD optimization for each language
+
+### Project language detection and optimal routing
+
+`tdd-implementer` automatically detects the language of your project and selects the optimal TDD tools and workflow:
+
+- **Language detection**: Analyze project files (package.json, pyproject.toml, go.mod, etc.)
+- **Tool selection**: Automatically select the optimal test framework for each language
+- **TAG application**: Write @TAG annotations directly in code files
+- **Run cycle**: RED → GREEN → REFACTOR sequential process
+
+### TDD tool mapping
+
+#### Backend/System
+
+| SPEC Type           | Implementation language | Test Framework         | Performance Goals | Coverage Goals |
+| ------------------- | ----------------------- | ---------------------- | ----------------- | -------------- |
+| **CLI/System**      | TypeScript              | jest + ts-node         | < 18ms            | 95%+           |
+| **API/Backend**     | TypeScript              | Jest + SuperTest       | < 50ms            | 90%+           |
+| **Frontend**        | TypeScript              | Jest + Testing Library | < 100ms           | 85%+           |
+| **Data Processing** | TypeScript              | Jest + Mock            | < 200ms           | 85%+           |
+| **Python Project**  | Python                  | pytest + mypy          | Custom            | 85%+           |
+
+#### Mobile Framework
+
+| SPEC Type        | Implementation language | Test Framework             | Performance Goals | Coverage Goals |
+| ---------------- | ----------------------- | -------------------------- | ----------------- | -------------- |
+| **Flutter App**  | Dart                    | flutter test + widget test | < 100ms           | 85%+           |
+| **React Native** | TypeScript              | Jest + RN Testing Library  | < 100ms           | 85%+           |
+| **iOS App**      | Swift                   | XCTest + XCUITest          | < 150ms           | 80%+           |
+| **Android App**  | Kotlin                  | JUnit + Espresso           | < 150ms           | 80%+           |
+
+## 🚀 Optimized agent collaboration structure
+
+- **Phase 1**: `implementation-planner` agent analyzes SPEC and establishes execution strategy
+- **Phase 2**: `tdd-implementer` agent executes tasks (TDD cycle, prototyping, documentation, etc.)
+- **Phase 2.5**: `quality-gate` agent verifies TRUST principle and quality verification (automatically)
+- **Phase 3**: `git-manager` agent processes all commits at once after task completion
+- **Single responsibility principle**: Each agent is responsible only for its own area of expertise
+- **Inter-agent call prohibited**: Each agent runs independently, sequential calls are made only at the command level
+
 ## Agent role separation
 
 ### implementation-planner dedicated area
@@ -420,11 +567,11 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the tdd-i
 
 ### tdd-implementer dedicated area
 
-- Execute tasks (TDD, prototyping, documentation, etc.) 
- - Write and run tests (TDD scenarios) 
- - Add and manage TAG comments 
- - Improve code quality (refactoring) 
- - Run language-specific linters/formatters
+- Execute tasks (TDD, prototyping, documentation, etc.)
+- Write and run tests (TDD scenarios)
+- Add and manage TAG comments
+- Improve code quality (refactoring)
+- Run language-specific linters/formatters
 
 ### Quality-gate dedicated area
 
@@ -453,7 +600,7 @@ Only if the user selects **"Proceed"** or **"Start"** will Alfred call the tdd-i
 
 ## 🧠 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