moai-adk 0.6.0__tar.gz → 0.6.3__tar.gz

{moai_adk-0.6.0 → moai_adk-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.6.0
+Version: 0.6.3
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -23,6 +23,7 @@ Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.45
 Requires-Dist: packaging>=21.0
 Requires-Dist: pyfiglet>=1.0.2
+Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
@@ -512,16 +513,90 @@ uv tool list  # Check current version of moai-adk
 
 ### Upgrading
 
-#### Method 1: MoAI-ADK Built-in Update Command (Simplest)
+#### Method 1: MoAI-ADK Built-in Update Command (Recommended - 3-Stage Workflow, v0.6.3+)
+<!-- @DOC:UPDATE-REFACTOR-002-003 -->
 
+MoAI-ADK's `update` command provides **automatic tool detection** and **intelligent 3-stage workflow** with **70-80% performance improvement** for templates already synchronized:
+
+**Basic 3-Stage Workflow** (automatic tool detection):
 ```bash
-# MoAI-ADK's own update command - also updates agent/Skills templates
+# Stage 1: Package version check
+# Shows version comparison, upgrades if needed
 moai-adk update
 
-# Apply new templates to project after update (optional)
-moai-adk init .
+# Stage 2: Config version comparison (NEW in v0.6.3)
+# Compares package template version with project config
+# If already synchronized, exits early (70-80% faster!)
+
+# Stage 3: Template sync (only if needed)
+# Creates backup → Syncs templates → Updates config
+# Message: "✓ Templates synced!" or "Templates are up to date!"
+```
+
+**Check for updates without applying them**:
+```bash
+# Preview available updates (shows package & config versions)
+moai-adk update --check
+```
+
+**Templates-only mode** (skip package upgrade, useful for manual upgrades):
+```bash
+# If you manually upgraded the package, sync templates only
+# Still performs Stage 2 config comparison for accuracy
+moai-adk update --templates-only
 ```
 
+**CI/CD mode** (auto-confirm all prompts):
+```bash
+# Auto-confirms all prompts - useful in automated pipelines
+# Runs all 3 stages automatically
+moai-adk update --yes
+```
+
+**Force mode** (skip backup creation):
+```bash
+# Update without creating backup (use with caution)
+# Still performs config version comparison
+moai-adk update --force
+```
+
+**How the 3-Stage Workflow Works** (v0.6.3):
+
+| Stage | Condition | Action | Performance |
+|-------|-----------|--------|-------------|
+| **Stage 1** | Package: current < latest | Detects installer → Upgrades package | ~20-30s |
+| **Stage 2** | Config: compare versions | Reads template_version from config.json | ~1s ⚡ **NEW!** |
+| **Stage 3** | Config: package > project | Creates backup → Syncs templates (if needed) | ~10-15s |
+
+**Performance Improvement** (v0.6.3):
+- **Same version case**: 12-18s → 3-4s (**70-80% faster!** ⚡)
+  - Stage 1: ~1s (version check)
+  - Stage 2: ~1s (config comparison)
+  - Stage 3: **skipped** (already synchronized)
+
+- **CI/CD repeated runs**: **-30% cost reduction**
+  - First run: Full sync
+  - Subsequent runs: Only version checks (~3-4s)
+
+**Why 3 stages?**
+Python processes cannot upgrade themselves while running. The 3-stage workflow is necessary for safety AND performance:
+1. **Stage 1**: Package upgrade detection (compares with PyPI)
+2. **Stage 2**: Template sync necessity detection (compares config versions) - NEW v0.6.3
+3. **Stage 3**: Templates and configuration sync (only if necessary)
+
+**Key Improvement in v0.6.3**:
+Previously, all updates would sync templates even if nothing changed. Now, config version comparison (Stage 2) detects when templates are already current, **skipping Stage 3 entirely** (saves 10-15 seconds!)
+
+**Config Version Tracking**:
+```json
+{
+  "project": {
+    "template_version": "0.6.3"  // Tracks last synchronized template version
+  }
+}
+```
+This field allows MoAI-ADK to accurately determine if templates need synchronization without re-syncing everything.
+
 #### Method 2: Upgrade with uv tool command
 
 **Upgrade specific tool (recommended)**
@@ -554,22 +629,20 @@ moai-adk --version
 # 2. Verify project works correctly
 moai-adk doctor
 
-# 3. Apply new templates to existing project (if needed)
-cd your-project
-moai-adk init .  # Keeps existing code, updates only .moai/ structure and templates
-
-# 4. Check updated features in Alfred
+# 3. Check updated features in Alfred
 cd your-project
 claude
 /alfred:0-project  # Verify new features like language selection
 ```
 
-> 💡 **Tip**:
+> 💡 **New 2-Stage Update Workflow**:
 >
-> - `moai-adk update`: Updates MoAI-ADK package version + syncs agent/Skills templates
-> - `moai-adk init .`: Applies new templates to existing project (keeps code safe)
-> - Running both commands completes a full update
-> - When major updates (minor/major) release, run these procedures to utilize new agents/Skills
+> - **Stage 1**: `moai-adk update` detects installer (uv tool, pipx, or pip) and upgrades package
+> - **Stage 2**: `moai-adk update` again to sync templates, config, and agent/Skills
+> - **Smart detection**: Auto-detects whether package upgrade is needed based on version comparison
+> - **CI/CD ready**: Use `moai-adk update --yes` for fully automated updates in pipelines
+> - **Manual upgrade path**: Use `moai-adk update --templates-only` after manually upgrading the package
+> - **Rollback safe**: Automatic backups in `.moai-backups/` before template sync
 
 ---
 
@@ -1641,3 +1714,9 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 - 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---
+
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=modu-ai/moai-adk&type=date&legend=top-left)](https://www.star-history.com/#modu-ai/moai-adk&Date)
+
+---

{moai_adk-0.6.0 → moai_adk-0.6.3}/README.md

@@ -473,16 +473,90 @@ uv tool list  # Check current version of moai-adk
 
 ### Upgrading
 
-#### Method 1: MoAI-ADK Built-in Update Command (Simplest)
+#### Method 1: MoAI-ADK Built-in Update Command (Recommended - 3-Stage Workflow, v0.6.3+)
+<!-- @DOC:UPDATE-REFACTOR-002-003 -->
 
+MoAI-ADK's `update` command provides **automatic tool detection** and **intelligent 3-stage workflow** with **70-80% performance improvement** for templates already synchronized:
+
+**Basic 3-Stage Workflow** (automatic tool detection):
 ```bash
-# MoAI-ADK's own update command - also updates agent/Skills templates
+# Stage 1: Package version check
+# Shows version comparison, upgrades if needed
 moai-adk update
 
-# Apply new templates to project after update (optional)
-moai-adk init .
+# Stage 2: Config version comparison (NEW in v0.6.3)
+# Compares package template version with project config
+# If already synchronized, exits early (70-80% faster!)
+
+# Stage 3: Template sync (only if needed)
+# Creates backup → Syncs templates → Updates config
+# Message: "✓ Templates synced!" or "Templates are up to date!"
+```
+
+**Check for updates without applying them**:
+```bash
+# Preview available updates (shows package & config versions)
+moai-adk update --check
+```
+
+**Templates-only mode** (skip package upgrade, useful for manual upgrades):
+```bash
+# If you manually upgraded the package, sync templates only
+# Still performs Stage 2 config comparison for accuracy
+moai-adk update --templates-only
 ```
 
+**CI/CD mode** (auto-confirm all prompts):
+```bash
+# Auto-confirms all prompts - useful in automated pipelines
+# Runs all 3 stages automatically
+moai-adk update --yes
+```
+
+**Force mode** (skip backup creation):
+```bash
+# Update without creating backup (use with caution)
+# Still performs config version comparison
+moai-adk update --force
+```
+
+**How the 3-Stage Workflow Works** (v0.6.3):
+
+| Stage | Condition | Action | Performance |
+|-------|-----------|--------|-------------|
+| **Stage 1** | Package: current < latest | Detects installer → Upgrades package | ~20-30s |
+| **Stage 2** | Config: compare versions | Reads template_version from config.json | ~1s ⚡ **NEW!** |
+| **Stage 3** | Config: package > project | Creates backup → Syncs templates (if needed) | ~10-15s |
+
+**Performance Improvement** (v0.6.3):
+- **Same version case**: 12-18s → 3-4s (**70-80% faster!** ⚡)
+  - Stage 1: ~1s (version check)
+  - Stage 2: ~1s (config comparison)
+  - Stage 3: **skipped** (already synchronized)
+
+- **CI/CD repeated runs**: **-30% cost reduction**
+  - First run: Full sync
+  - Subsequent runs: Only version checks (~3-4s)
+
+**Why 3 stages?**
+Python processes cannot upgrade themselves while running. The 3-stage workflow is necessary for safety AND performance:
+1. **Stage 1**: Package upgrade detection (compares with PyPI)
+2. **Stage 2**: Template sync necessity detection (compares config versions) - NEW v0.6.3
+3. **Stage 3**: Templates and configuration sync (only if necessary)
+
+**Key Improvement in v0.6.3**:
+Previously, all updates would sync templates even if nothing changed. Now, config version comparison (Stage 2) detects when templates are already current, **skipping Stage 3 entirely** (saves 10-15 seconds!)
+
+**Config Version Tracking**:
+```json
+{
+  "project": {
+    "template_version": "0.6.3"  // Tracks last synchronized template version
+  }
+}
+```
+This field allows MoAI-ADK to accurately determine if templates need synchronization without re-syncing everything.
+
 #### Method 2: Upgrade with uv tool command
 
 **Upgrade specific tool (recommended)**
@@ -515,22 +589,20 @@ moai-adk --version
 # 2. Verify project works correctly
 moai-adk doctor
 
-# 3. Apply new templates to existing project (if needed)
-cd your-project
-moai-adk init .  # Keeps existing code, updates only .moai/ structure and templates
-
-# 4. Check updated features in Alfred
+# 3. Check updated features in Alfred
 cd your-project
 claude
 /alfred:0-project  # Verify new features like language selection
 ```
 
-> 💡 **Tip**:
+> 💡 **New 2-Stage Update Workflow**:
 >
-> - `moai-adk update`: Updates MoAI-ADK package version + syncs agent/Skills templates
-> - `moai-adk init .`: Applies new templates to existing project (keeps code safe)
-> - Running both commands completes a full update
-> - When major updates (minor/major) release, run these procedures to utilize new agents/Skills
+> - **Stage 1**: `moai-adk update` detects installer (uv tool, pipx, or pip) and upgrades package
+> - **Stage 2**: `moai-adk update` again to sync templates, config, and agent/Skills
+> - **Smart detection**: Auto-detects whether package upgrade is needed based on version comparison
+> - **CI/CD ready**: Use `moai-adk update --yes` for fully automated updates in pipelines
+> - **Manual upgrade path**: Use `moai-adk update --templates-only` after manually upgrading the package
+> - **Rollback safe**: Automatic backups in `.moai-backups/` before template sync
 
 ---
 
@@ -1602,3 +1674,9 @@ Start a new experience of **trustworthy AI development** with Alfred! 🤖
 - 🏷️ TAG Guard: Automatic @TAG validation in PreToolUse Hook
 
 ---
+
+## ⭐ Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=modu-ai/moai-adk&type=date&legend=top-left)](https://www.star-history.com/#modu-ai/moai-adk&Date)
+
+---

{moai_adk-0.6.0 → moai_adk-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.6.0"
+version = "0.6.3"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -25,7 +25,8 @@ dependencies = [
     "pyfiglet>=1.0.2",
     "questionary>=2.0.0",
     "gitpython>=3.1.45",
-    "packaging>=21.0"
+    "packaging>=21.0",
+    "pyyaml>=6.0"
 ]
 
 [project.optional-dependencies]