moai-adk 0.34.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

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

@@ -1,12 +1,12 @@
 ---
-name: moai:3-sync
 description: "Synchronize documentation with Phase 0.5 quality verification and finalize PR"
 argument-hint: "Mode target path - Mode: auto (default)|force|status|project, target path: Synchronization target path"
-allowed-tools: Task, AskUserQuestion, TodoWrite
+type: workflow
+allowed-tools: Task, AskUserQuestion, TodoWrite, Bash, Read, Write, Edit, Glob, Grep
 model: inherit
 ---
 
-##  Pre-execution Context
+## Pre-execution Context
 
 !git status --porcelain
 !git diff --name-only HEAD
@@ -14,7 +14,7 @@ model: inherit
 !git log --oneline -10
 !find .moai/specs -name "spec.md" -type f 2>/dev/null
 
-##  Essential Files
+## Essential Files
 
 @.moai/config/config.yaml
 @.moai/specs/
@@ -22,7 +22,7 @@ model: inherit
 
 ---
 
-#  MoAI-ADK Step 3: Document Synchronization (+Optional PR Ready)
+# MoAI-ADK Step 3: Document Synchronization (+Optional PR Ready)
 
 User Interaction Architecture: AskUserQuestion must be used at COMMAND level only. Subagents via Task() are stateless and cannot interact with users. Collect all approvals BEFORE delegating to agents.
 
@@ -32,7 +32,7 @@ Batched Design: All AskUserQuestion calls follow batched design principles (1-4
 
 ---
 
-##  Command Purpose
+## Command Purpose
 
 [HARD] This command orchestrates ONLY - delegates all sync work to manager-docs agent
 
@@ -41,12 +41,14 @@ Document sync target: $ARGUMENTS
 Agent Delegation Pattern:
 
 Correct Approach [HARD]:
+
 - Invoke Task() with subagent_type="manager-docs"
 - Pass complete context including changed files and verification results
 - Let manager-docs agent determine implementation strategy
 - WHY: Specialized agent has domain expertise and handles all complexity
 
 Forbidden Approach:
+
 - Direct file manipulation using Edit, Write, Read tools
 - Direct bash execution of document updates
 - WHY: Bypasses quality controls and loses context-specific error handling
@@ -56,16 +58,29 @@ Step 1 (Analysis & Planning) leads to Step 2 (Document Sync via Agent) leads to
 
 ---
 
-##  Execution Modes
+## Execution Modes
 
 This command supports 4 operational modes:
 
-| Mode               | Scope                   | PR Processing         | Use Case                            |
-| ------------------ | ----------------------- | --------------------- | ----------------------------------- |
-| auto (default) | Smart selective sync    | PR Ready conversion   | Daily development workflow          |
-| force          | Full project re-sync    | Full regeneration     | Error recovery, major refactoring   |
-| status         | Status check only       | Report only           | Quick health check                  |
-| project        | Integrated project-wide | Project-level updates | Milestone completion, periodic sync |
+- **auto** (default): Smart selective sync
+  - Scope: Selectively syncs changed files only
+  - PR Processing: PR Ready conversion
+  - Use Case: Daily development workflow
+
+- **force**: Full project re-sync
+  - Scope: Complete regeneration of all documentation
+  - PR Processing: Full regeneration
+  - Use Case: Error recovery, major refactoring
+
+- **status**: Status check only
+  - Scope: Read-only health check
+  - PR Processing: Report only
+  - Use Case: Quick health check
+
+- **project**: Integrated project-wide
+  - Scope: Project-wide documentation updates
+  - PR Processing: Project-level updates
+  - Use Case: Milestone completion, periodic sync
 
 Command usage examples:
 
@@ -80,13 +95,19 @@ Command usage examples:
 
 ---
 
-##  Associated Agents
+## Associated Agents
+
+- **manager-docs**: Synchronize Living Documents with code changes
+  - Responsible for analyzing Git changes and executing documentation updates
+  - Handles SPEC synchronization and domain-specific documentation
 
-| Agent           | Purpose                                         |
-| --------------- | ----------------------------------------------- |
-| manager-docs    | Synchronize Living Documents with code changes  |
-| manager-quality | Verify project integrity and TRUST 5 compliance |
-| manager-git     | Handle Git operations and commit management     |
+- **manager-quality**: Verify project integrity and TRUST 5 compliance
+  - Performs automated code review and quality validation
+  - Ensures documentation meets quality standards
+
+- **manager-git**: Handle Git operations and commit management
+  - Creates commits for documentation changes
+  - Manages PR transitions and branch operations
 
 ---
 
@@ -99,6 +120,7 @@ This command uses agent execution patterns defined in CLAUDE.md (lines 96-120).
 Command implements sequential chaining through 3 core phases:
 
 Phase Flow:
+
 - Phase 1: Analysis & Planning (manager-docs analyzes changed files and sync scope)
 - Phase 2: Execute Sync (manager-docs updates documentation, manager-quality validates)
 - Phase 3: Git Operations & PR (manager-git creates commits and prepares PR if applicable)
@@ -106,6 +128,7 @@ Phase Flow:
 Each phase receives outputs from previous phases as context.
 
 WHY: Sequential execution ensures documentation consistency and validation
+
 - Phase 2 requires analysis results from Phase 1 to determine sync scope
 - Phase 3 requires validated documentation from Phase 2 before commit
 - PR creation requires successful commit from Phase 3
@@ -117,6 +140,7 @@ IMPACT: Skipping phases would create inconsistent documentation or invalid commi
 Limited parallel execution within Phase 2 for independent documentation files
 
 WHY: Some documentation files can be generated simultaneously
+
 - Multiple markdown files without cross-references can be updated in parallel
 - Index updates and validation must remain sequential
 
@@ -127,6 +151,7 @@ IMPACT: Full parallel execution would risk broken cross-references and index inc
 Not applicable - command typically completes quickly in single execution
 
 WHY: Documentation sync is fast operation (usually under 2 minutes)
+
 - Most sync operations complete in first attempt
 - File system operations are atomic and recoverable
 - No long-running processes requiring checkpoints
@@ -139,55 +164,61 @@ Refer to CLAUDE.md "Agent Chaining Patterns" (lines 96-120) for complete pattern
 
 ---
 
-##  Execution Philosophy: "Sync → Verify → Commit"
-
-`/moai:3-sync` performs documentation synchronization through complete agent delegation:
+## Execution Philosophy: "Sync to Verify to Commit"
 
-```
-User Command: /moai:3-sync [mode] [path]
-    ↓
-/moai:3-sync Command
-    └─ Task(subagent_type="manager-docs" or "manager-quality" or "manager-git")
-        ├─ Phase 1: Analysis & Planning (manager-docs)
-        ├─ Phase 2: Execute Sync (manager-docs + manager-quality)
-        └─ Phase 3: Git Operations & PR (manager-git)
-            ↓
-        Output: Synchronized docs + commit + PR Ready (conditional)
-```
+/moai:3-sync performs documentation synchronization through complete agent delegation:
 
-### Key Principle: Zero Direct Tool Usage
+Execution Flow:
 
-[HARD] This command uses ONLY Task(), AskUserQuestion(), and TodoWrite():
+- User Command: /moai:3-sync [mode] [path]
+- /moai:3-sync Command delegates to Task with subagent_type set to manager-docs or manager-quality or manager-git
+  - Phase 1: Analysis and Planning (manager-docs)
+  - Phase 2: Execute Sync (manager-docs plus manager-quality)
+  - Phase 3: Git Operations and PR (manager-git)
+- Output: Synchronized docs plus commit plus PR Ready (conditional)
 
-Permitted Tools:
-- Task() for orchestration [HARD]
-- AskUserQuestion() for user interaction AT COMMAND LEVEL ONLY [HARD]
-  - WHY: Subagents via Task() are stateless and cannot interact with users
-  - CORRECT: Collect approvals before Task() calls, pass choices as parameters
-- TodoWrite() for progress tracking [HARD]
+### Tool Usage Guidelines
 
-Forbidden Tools (All delegated to agents):
-- Read (delegated) - All file reading operations must be performed by specialized agents
-- Write (delegated) - All file writing operations must be performed by specialized agents
-- Edit (delegated) - All file editing operations must be performed by specialized agents
-- Bash (delegated) - All bash execution must be performed by specialized agents
+This command has access to all tools for flexibility:
 
-WHY: Zero direct tool usage maintains clean separation of concerns. Each tool type has a specialized agent that understands context-specific requirements.
+- Task() for agent orchestration (recommended for complex tasks)
+- AskUserQuestion() for user interaction at command level
+- TodoWrite() for progress tracking
+- Read, Write, Edit, Bash, Glob, Grep for direct operations when needed
 
-IMPACT: Direct tool usage would bypass quality controls, specialized agent expertise, and error recovery mechanisms. Delegation ensures consistent execution patterns.
-
-All complexity is handled by specialized agents (manager-docs, manager-quality, manager-git).
+Agent delegation is recommended for complex tasks that benefit from specialized expertise. Direct tool usage is permitted when appropriate for simpler operations.
 
 ---
 
 ---
 
-##  Output Format
+## Output Format
 
-All command execution outputs must use semantic XML sections for clarity and consistency:
+### Output Format Rules
 
-XML Structure Format:
-```
+[HARD] User-Facing Reports: Always use Markdown formatting for user communication. Never display XML tags to users.
+WHY: Users expect readable formatted text, not markup
+IMPACT: XML tags in user output create confusion and reduce comprehension
+
+[HARD] Internal Agent Data: XML tags are reserved for agent-to-agent data transfer only.
+WHY: XML structure enables automated parsing for downstream agent coordination
+IMPACT: Using XML for user output degrades user experience
+
+### User-Facing Output (Markdown)
+
+Progress reports must use Markdown with clear sections:
+
+- **Analysis**: Project state assessment and findings
+- **Plan**: Synchronization strategy and rationale
+- **Execution**: Actions taken and files modified
+- **Verification**: Quality gate results
+- **Completion**: Summary and next steps
+
+### Internal Agent Communication (XML)
+
+For agent-to-agent data transfer only (never displayed to users):
+
+```xml
 <analysis>Detailed assessment of project state, identified changes, and validation results</analysis>
 <plan>Synchronization strategy including scope, affected documents, and approach rationale</plan>
 <execution>Concrete actions taken: files updated, reports generated, status changes recorded</execution>
@@ -195,20 +226,19 @@ XML Structure Format:
 <completion>Summary of outcomes, generated reports locations, and next steps for user</completion>
 ```
 
-Required Elements:
+Required Elements for Internal Communication:
+
 - Analysis must detail all findings from project validation and Git analysis
 - Plan must explain strategy choice including WHY and IMPACT of decisions
 - Execution must track all agent actions and file modifications
 - Verification must report all quality gates and their outcomes
 - Completion must guide user toward next meaningful action
 
-WHY: XML sections provide machine-parseable structure and enable audit trails. Clear sections ensure user can understand command progress at any point.
-
-IMPACT: Unstructured output reduces comprehension and prevents automated processing of results.
+WHY: XML sections provide machine-parseable structure for agent coordination and enable audit trails.
 
 ---
 
-##  OVERALL WORKFLOW STRUCTURE
+## OVERALL WORKFLOW STRUCTURE
 
 ```
 ┌──────────────────────────────────────────────────────────┐
@@ -244,7 +274,7 @@ IMPACT: Unstructured output reduces comprehension and prevents automated process
 
 ---
 
-##  PHASE 1: Analysis & Planning
+## PHASE 1: Analysis & Planning
 
 Goal: Gather project context, verify project status, and get user approval.
 
@@ -297,8 +327,8 @@ Gather context for synchronization planning:
    - Execute: `git status --porcelain` to identify modified files
    - Execute: `git diff --name-only HEAD` to list changed file paths
    - Categorize: Count Python files, test files, documents, SPEC files separately
-   WHY: Git state determines synchronization scope and impact analysis
-   IMPACT: Incomplete Git analysis leads to partial synchronization
+     WHY: Git state determines synchronization scope and impact analysis
+     IMPACT: Incomplete Git analysis leads to partial synchronization
 
 2. [HARD] Read Project Configuration:
 
@@ -308,8 +338,8 @@ Gather context for synchronization planning:
    - Extract: `git_strategy.mode` value (must be Personal or Team)
    - Extract: `language.conversation_language` value (determines document language)
    - Extract: `git_strategy.spec_git_workflow` value
-   WHY: Configuration drives workflow behavior and language output
-   IMPACT: Missing configuration values cause workflow misalignment and language errors
+     WHY: Configuration drives workflow behavior and language output
+     IMPACT: Missing configuration values cause workflow misalignment and language errors
 
 3. [HARD] Determine Synchronization Mode:
 
@@ -319,8 +349,8 @@ Gather context for synchronization planning:
    - If empty: Default to auto mode
    - Parse optional flags: --auto-merge, --skip-pre-check, --skip-quality-check
    - Parse special flags: --worktree, --branch
-   WHY: Mode determines scope and processing strategy
-   IMPACT: Invalid mode selection produces incorrect synchronization behavior
+     WHY: Mode determines scope and processing strategy
+     IMPACT: Invalid mode selection produces incorrect synchronization behavior
 
 4. [SOFT] Handle Worktree Detection:
 
@@ -331,8 +361,8 @@ Gather context for synchronization planning:
    - If in worktree: Extract SPEC ID from current path (format: SPEC-{DOMAIN}-{NUMBER})
    - Alternative: Check worktree registry at `~/worktrees/{PROJECT_NAME}/.moai-worktree-registry.json`
    - Store: `$WORKTREE_MODE=true` and `$CURRENT_SPEC_ID` for later use
-   WHY: Worktree context enables specialized cleanup and workflow options
-   IMPACT: Missing worktree detection prevents proper exit handling but does not block sync
+     WHY: Worktree context enables specialized cleanup and workflow options
+     IMPACT: Missing worktree detection prevents proper exit handling but does not block sync
 
 5. [SOFT] Handle Branch Detection:
 
@@ -341,8 +371,8 @@ Gather context for synchronization planning:
    - Check: Is --branch flag present in arguments OR is current branch not main
    - Execute: `git branch --show-current` to get current branch name
    - Store: `$BRANCH_MODE=true` and `$CURRENT_BRANCH` for later use
-   WHY: Branch context enables proper merge and cleanup operations
-   IMPACT: Missing branch detection reduces workflow automation but does not prevent sync
+     WHY: Branch context enables proper merge and cleanup operations
+     IMPACT: Missing branch detection reduces workflow automation but does not prevent sync
 
 6. [HARD] Handle Status Mode Early Exit:
 
@@ -354,8 +384,8 @@ Gather context for synchronization planning:
    - Report: Synchronization recommendation
    - If status mode: Execute Phase 0.5 quality verification before reporting
    - Exit: Command completes with success code (no further phases)
-   WHY: Status mode serves quick health check without making changes, but still validates project quality
-   IMPACT: Skipping quality check in status mode reduces visibility of project health
+     WHY: Status mode serves quick health check without making changes, but still validates project quality
+     IMPACT: Skipping quality check in status mode reduces visibility of project health
 
 Result: Project context gathered. Synchronization mode established. Ready for quality verification (Phase 0.5).
 
@@ -375,16 +405,48 @@ This phase automatically detects the project language and runs appropriate quali
 ```
 Detect Project Language
     ↓
-Language-specific tool execution
-    ├── Test Runner (pytest/jest/go test/cargo test/etc.)
+Language-specific tool execution (PARALLEL)
+    ┌── Test Runner (pytest/jest/go test/cargo test/etc.)
     ├── Linter (ruff/eslint/golangci-lint/clippy/etc.)
     └── Type Checker (mypy/tsc/go vet/etc.)
     ↓
+Result Collection & Aggregation
+    ↓
 code-review invocation (manager-quality)
     ↓
 Quality Report
 ```
 
+### Parallel Quality Verification Implementation
+
+After language detection, execute test runner, linter, and type checker simultaneously:
+
+Step 1 - Launch Background Tasks:
+
+1. Test Runner: Use Bash tool with run_in_background set to true for language-specific test command
+2. Linter: Use Bash tool with run_in_background set to true for language-specific lint command
+3. Type Checker: Use Bash tool with run_in_background set to true for language-specific type check command
+
+Step 2 - Collect Results:
+
+1. Use TaskOutput tool to collect results from all three background tasks
+2. Wait for all tasks to complete (timeout: 180 seconds per task for test runner, 120 seconds for others)
+3. Handle partial failures gracefully - continue with available results
+
+Step 3 - Aggregate Results:
+
+1. Parse output from each tool into structured result
+2. Determine status for each tool: PASS, FAIL, WARN, SKIP
+3. If test runner has failures: Prompt user via AskUserQuestion before proceeding
+
+Step 4 - Proceed to Code Review:
+
+1. Pass aggregated results to manager-quality
+2. Generate comprehensive quality report
+
+WHY: Parallel execution reduces Phase 0.5 time from 60-90 seconds to 20-40 seconds (2-3x speedup)
+IMPACT: Significantly faster quality verification without sacrificing thoroughness
+
 ---
 
 #### Task 1.2.5.1: Detect Project Language
@@ -459,6 +521,7 @@ Language Detection Rules (check in order, first match wins):
     - Skip language-specific tools, proceed directly to code-review
 
 Log detection result:
+
 - Print to user: "Project language detection: [detected_language]"
 
 ---
@@ -703,16 +766,19 @@ Result: Quality verification complete. All issues documented. Ready for project
 WHY: Partial scans miss issues in unmodified sections. Comprehensive scanning ensures quality gates pass.
 
 Verification Requirements:
+
 - Project integrity assessment (identify broken references, inconsistencies)
 - Complete issues detection with precise locations
 - Resolution recommendations for discovered issues
 
 Output Requirements:
+
 - Complete issue list with file locations and line numbers
 - Project integrity status: Healthy or Issues Detected
 - Severity classification for each issue: Critical, High, Medium, Low
 
 Storage:
+
 - Store complete response in `$PROJECT_VALIDATION_RESULTS`
 - Format must be machine-parseable for downstream agent processing
 
@@ -785,7 +851,6 @@ Present synchronization plan and get user decision:
    ```
 
 2. Ask for user approval using AskUserQuestion:
-
    - `question`: "Synchronization plan is ready. How would you like to proceed?"
    - `header`: "Plan Approval"
    - `multiSelect`: false
@@ -805,7 +870,7 @@ Result: User decision captured. Command proceeds or exits.
 
 ---
 
-##  PHASE 2: Execute Document Synchronization
+## PHASE 2: Execute Document Synchronization
 
 Goal: Synchronize documents with code changes, update SPECs, verify quality.
 
@@ -836,7 +901,7 @@ IMPACT: Missing backup eliminates recovery option if sync produces errors
    - README.md (if exists) - Project documentation
    - docs/ directory (if exists) - Additional documentation
    - .moai/specs/ directory - SPEC definitions
-   WHY: Backing up all critical files enables complete state restoration
+     WHY: Backing up all critical files enables complete state restoration
 
 4. [HARD] Verify Backup Integrity:
 
@@ -846,7 +911,7 @@ IMPACT: Missing backup eliminates recovery option if sync produces errors
    - Verify: Backup directory is not empty
    - If empty: Print error message and exit with failure code
    - If complete: Print success message and continue
-   WHY: Verification confirms backup is usable for recovery
+     WHY: Verification confirms backup is usable for recovery
 
 Result: Safety backup created and verified. Ready for synchronization phase.
 
@@ -876,24 +941,20 @@ Previous analysis results:
 Task Instructions:
 
 1. Living Document synchronization:
-
    - Reflect changed code in documentation
    - Auto-generate/update API documentation
    - Update README (if needed)
    - Synchronize Architecture documents
 
 2. Project improvements:
-
    - Fix project issues (if possible)
    - Restore broken references
 
 3. SPEC synchronization:
-
    - Ensure SPEC documents match implementation
    - Update EARS statements if needed
 
 4. Domain-based documentation:
-
    - Detect changed domains (frontend/backend/devops/database/ml/mobile)
    - Generate domain-specific documentation updates
 
@@ -950,7 +1011,6 @@ After successful synchronization, update SPEC status to completed:
    ```
 
 2. Verify status updates:
-
    - Check results from batch update
    - Record version changes and status transitions
    - Include status changes in sync report
@@ -972,7 +1032,7 @@ Integration: Status updates are included in the Git commit from Phase 3 with det
 
 ---
 
-##  PHASE 3: Git Operations & PR
+## PHASE 3: Git Operations & PR
 
 Goal: Commit changes, transition PR (if Team mode), optionally auto-merge.
 
@@ -1044,12 +1104,10 @@ Verify:
 For Team mode projects only:
 
 1. Check if Team mode:
-
    - Read: `git_strategy.mode` from config
    - IF Personal → Skip to next phase
 
 2. Transition PR to Ready:
-
    - Use Task tool:
      - `subagent_type`: "manager-git"
      - `description`: "Transition PR to Ready for Review"
@@ -1064,17 +1122,14 @@ For Team mode projects only:
 If `--auto-merge` flag is set:
 
 1. Check CI/CD status:
-
    - Execute: `gh pr checks`
    - IF failing → Print warning and skip merge
 
 2. Check merge conflicts:
-
    - Execute: `gh pr view --json mergeable`
    - IF conflicts exist → Print warning and skip merge
 
 3. Execute auto-merge:
-
    - Execute: `gh pr merge --squash --delete-branch`
 
 4. Branch cleanup:
@@ -1084,7 +1139,7 @@ If `--auto-merge` flag is set:
 
 ---
 
-##  PHASE 4: Completion & Next Steps
+## PHASE 4: Completion & Next Steps
 
 Goal: Report results and guide user to next action.
 
@@ -1222,7 +1277,7 @@ Use AskUserQuestion to guide next steps:
 
 ---
 
-##  Graceful Exit (User Aborts)
+## Graceful Exit (User Aborts)
 
 If user chooses to abort in PHASE 1:
 
@@ -1248,15 +1303,34 @@ Exit command with code 0.
 
 ---
 
-##  Quick Reference
+## Quick Reference
+
+Workflow Scenarios:
+
+- **Daily development** (auto mode)
+  - Entry Point: `/moai:3-sync`
+  - Key Phases: Phase 0.5 (QV) → Phase 1 → Analysis → Phase 2 → Sync → Phase 3 → Git
+  - Expected Outcome: PR Ready + docs synced
+
+- **Error recovery** (force mode)
+  - Entry Point: `/moai:3-sync force`
+  - Key Phases: Phase 0.5 (QV) → Full project re-sync
+  - Expected Outcome: All docs regenerated
+
+- **Quick health check** (status mode)
+  - Entry Point: `/moai:3-sync status`
+  - Key Phases: Phase 0.5 (QV) → Status check only
+  - Expected Outcome: Health report
+
+- **Milestone completion** (project mode)
+  - Entry Point: `/moai:3-sync project`
+  - Key Phases: Phase 0.5 (QV) → Integrated sync
+  - Expected Outcome: Project-wide updates
 
-| Scenario             | Mode    | Entry Point                 | Key Phases                                                    | Expected Outcome          |
-| -------------------- | ------- | --------------------------- | ------------------------------------------------------------- | ------------------------- |
-| Daily development    | auto    | `/moai:3-sync`              | Phase 0.5 (QV) → Phase 1 → Analysis → Phase 2 → Sync → Phase 3 → Git | PR Ready + docs synced    |
-| Error recovery       | force   | `/moai:3-sync force`        | Phase 0.5 (QV) → Full project re-sync                         | All docs regenerated      |
-| Quick health check   | status  | `/moai:3-sync status`       | Phase 0.5 (QV) → Status check only                            | Health report             |
-| Milestone completion | project | `/moai:3-sync project`      | Phase 0.5 (QV) → Integrated sync                              | Project-wide updates      |
-| Auto-merge workflow  | auto    | `/moai:3-sync --auto-merge` | Phase 0.5 (QV) → PR auto-merge + cleanup                      | Branch merged and deleted |
+- **Auto-merge workflow** (auto mode with flag)
+  - Entry Point: `/moai:3-sync --auto-merge`
+  - Key Phases: Phase 0.5 (QV) → PR auto-merge + cleanup
+  - Expected Outcome: Branch merged and deleted
 
 Note: Phase 0.5 = Quality Verification (pytest, ruff, mypy, code-review)
 
@@ -1315,7 +1389,7 @@ Important:
 - No emojis in any AskUserQuestion fields
 - Always provide clear next step options
 
-##  EXECUTION DIRECTIVE
+## EXECUTION DIRECTIVE
 
 You must NOW execute the command following the "OVERALL WORKFLOW STRUCTURE" described above.