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

moai_adk/templates/.claude/skills/moai-worktree/SKILL.md

@@ -1,411 +0,0 @@
----
-name: moai-worktree
-description: Git worktree management for parallel SPEC development with isolated workspaces, automatic registration, and seamless MoAI-ADK integration
-version: 1.0.0
-modularized: true
-category: workflow
-updated: 2025-11-29
-status: active
-tags:
- - git
- - worktree
- - parallel
- - development
- - spec
- - isolation
-allowed-tools: Read, Grep, Glob
----
-
-# MoAI Worktree Management
-
-Git worktree management system for parallel SPEC development with isolated workspaces, automatic registration, and seamless MoAI-ADK integration.
-
-Core Philosophy: Each SPEC deserves its own isolated workspace to enable true parallel development without context switching overhead.
-
-## Quick Reference (30 seconds)
-
-What is MoAI Worktree Management?
-A specialized Git worktree system that creates isolated development environments for each SPEC, enabling parallel development without conflicts.
-
-Key Features:
-- Isolated Workspaces: Each SPEC gets its own worktree with independent Git state
-- Automatic Registration: Worktree registry tracks all active workspaces
-- Parallel Development: Multiple SPECs can be developed simultaneously
-- Seamless Integration: Works with `/moai:1-plan`, `/moai:2-run`, `/moai:3-sync` workflow
-- Smart Synchronization: Automatic sync with base branch when needed
-- Cleanup Automation: Automatic cleanup of merged worktrees
-
-Quick Access:
-- CLI commands → [Worktree Commands Module](modules/worktree-commands.md)
-- Management patterns → [Worktree Management Module](modules/worktree-management.md)
-- Parallel workflow → [Parallel Development Module](modules/parallel-development.md)
-- Integration guide → [Integration Patterns Module](modules/integration-patterns.md)
-- Troubleshooting → [Troubleshooting Module](modules/troubleshooting.md)
-
-Use Cases:
-- Multiple SPECs development in parallel
-- Isolated testing environments
-- Feature branch isolation
-- Code review workflows
-- Experimental feature development
-
----
-
-## Implementation Guide (5 minutes)
-
-### 1. Core Architecture - Worktree Management System
-
-Purpose: Create isolated Git worktrees for parallel SPEC development.
-
-Key Components:
-
-1. Worktree Registry - Central registry tracking all worktrees
-2. Manager Layer - Core worktree operations (create, switch, remove, sync)
-3. CLI Interface - User-friendly command interface
-4. Models - Data structures for worktree metadata
-5. Integration Layer - MoAI-ADK workflow integration
-
-Registry Structure:
-```json
-{
- "worktrees": {
- "SPEC-001": {
- "id": "SPEC-001",
- "path": "/Users/goos/worktrees/MoAI-ADK/SPEC-001",
- "branch": "feature/SPEC-001-user-auth",
- "created_at": "2025-11-29T22:00:00Z",
- "last_sync": "2025-11-29T22:30:00Z",
- "status": "active",
- "base_branch": "main"
- }
- },
- "config": {
- "worktree_root": "/Users/goos/worktrees/MoAI-ADK",
- "auto_sync": true,
- "cleanup_merged": true
- }
-}
-```
-
-File Structure:
-```
-~/worktrees/MoAI-ADK/
- .moai-worktree-registry.json # Central registry
- SPEC-001/ # Worktree directory
- .git # Git worktree metadata
- (project files) # Complete project copy
- SPEC-002/ # Another worktree
- .git
- (project files)
-```
-
-Detailed Reference: [Worktree Management Module](modules/worktree-management.md)
-
----
-
-### 2. CLI Commands - Complete Command Interface
-
-Purpose: Provide intuitive CLI commands for worktree management.
-
-Core Commands:
-
-```bash
-# Create new worktree for SPEC
-moai-worktree new SPEC-001 "User Authentication System"
-
-# List all worktrees
-moai-worktree list
-
-# Switch to specific worktree
-moai-worktree switch SPEC-001
-
-# Get worktree path for shell integration
-eval $(moai-worktree go SPEC-001)
-
-# Sync worktree with base branch
-moai-worktree sync SPEC-001
-
-# Remove worktree
-moai-worktree remove SPEC-001
-
-# Clean up merged worktrees
-moai-worktree clean
-
-# Show worktree status
-moai-worktree status
-
-# Configuration management
-moai-worktree config get
-moai-worktree config set worktree_root ~/my-worktrees
-```
-
-Command Categories:
-
-1. Creation: `new` - Create isolated worktree
-2. Navigation: `list`, `switch`, `go` - Browse and navigate
-3. Management: `sync`, `remove`, `clean` - Maintain worktrees
-4. Status: `status` - Check worktree state
-5. Configuration: `config` - Manage settings
-
-Shell Integration:
-```bash
-# Direct switching
-moai-worktree switch SPEC-001
-
-# Shell eval pattern (recommended)
-eval $(moai-worktree go SPEC-001)
-
-# Output example:
-# cd /Users/goos/worktrees/MoAI-ADK/SPEC-001
-```
-
-Detailed Reference: [Worktree Commands Module](modules/worktree-commands.md)
-
----
-
-### 3. Parallel Development Workflow - Isolated SPEC Development
-
-Purpose: Enable true parallel development without context switching.
-
-Workflow Integration:
-
-```
-1. Plan Phase (/moai:1-plan):
- SPEC creation
- moai-worktree new SPEC-XXX
- Automatic worktree setup
-
-2. Development Phase:
- Isolated worktree environment
- Independent Git state
- Zero context switching
-
-3. Sync Phase (/moai:3-sync):
- moai-worktree sync SPEC-XXX
- Clean integration
- Conflict resolution
-
-4. Cleanup Phase:
- moai-worktree clean
- Automatic cleanup
- Registry maintenance
-```
-
-Parallel Development Benefits:
-
-1. Context Isolation: Each SPEC has its own Git state, files, and environment
-2. Zero Switching Cost: Instant switching between worktrees
-3. Independent Development: Work on multiple SPECs simultaneously
-4. Safe Experimentation: Isolated environment for experimental features
-5. Clean Integration: Automatic sync and conflict resolution
-
-Example Workflow:
-```bash
-# Create SPEC-001 worktree
-moai-worktree new SPEC-001 "User Authentication"
-cd $(moai-worktree go SPEC-001)
-
-# Develop in isolation
-/moai:2-run SPEC-001
-
-# Create another worktree
-cd /path/to/main/repo
-moai-worktree new SPEC-002 "Payment Integration"
-cd $(moai-worktree go SPEC-002)
-
-# Parallel development on SPEC-002
-/moai:2-run SPEC-002
-
-# Switch back and continue
-moai-worktree switch SPEC-001
-# Continue development...
-
-# Sync and integrate
-moai-worktree sync SPEC-001
-moai-worktree sync SPEC-002
-```
-
-Detailed Reference: [Parallel Development Module](modules/parallel-development.md)
-
----
-
-### 4. Integration Patterns - MoAI-ADK Workflow Integration
-
-Purpose: Seamless integration with MoAI-ADK Plan-Run-Sync workflow.
-
-Integration Points:
-
-1. Plan Phase Integration (`/moai:1-plan`):
- ```bash
- # After SPEC creation
- moai-worktree new SPEC-{SPEC_ID}
-
- # Output guidance
- echo "1. Switch to worktree: moai-worktree switch SPEC-{SPEC_ID}"
- echo "2. Or use shell eval: eval $(moai-worktree go SPEC-{SPEC_ID})"
- ```
-
-2. Development Phase (`/moai:2-run`):
- - Worktree isolation provides clean development environment
- - Independent Git state prevents conflicts
- - Automatic registry tracking
-
-3. Sync Phase (`/moai:3-sync`):
- ```bash
- # Before PR creation
- moai-worktree sync SPEC-{SPEC_ID}
-
- # After PR merge
- moai-worktree clean --merged-only
- ```
-
-Auto-Detection Patterns:
-
-```bash
-# Check if worktree environment
-if [ -f "../.moai-worktree-registry.json" ]; then
- SPEC_ID=$(basename $(pwd))
- echo "Detected worktree environment: $SPEC_ID"
-fi
-
-# Auto-sync on status check
-moai-worktree status
-# Automatically syncs if out of date
-```
-
-Configuration Integration:
-```json
-{
- "moai": {
- "worktree": {
- "auto_create": true,
- "auto_sync": true,
- "cleanup_merged": true,
- "worktree_root": "~/worktrees/{PROJECT_NAME}"
- }
- }
-}
-```
-
-Detailed Reference: [Integration Patterns Module](modules/integration-patterns.md)
-
----
-
-## Advanced Implementation (10+ minutes)
-
-### Multi-Developer Worktree Coordination
-
-Shared Worktree Registry:
-```bash
-# Team worktree configuration
-moai-worktree config set registry_type team
-moai-worktree config set shared_registry ~/team-worktrees/MoAI-ADK/
-
-# Developer-specific worktrees
-moai-worktree new SPEC-001 --developer alice
-moai-worktree new SPEC-001 --developer bob
-
-# Team coordination
-moai-worktree list --all-developers
-moai-worktree status --team-overview
-```
-
-### Advanced Synchronization Strategies
-
-Selective Sync Patterns:
-```bash
-# Sync only specific files
-moai-worktree sync SPEC-001 --include "src/"
-
-# Exclude specific patterns
-moai-worktree sync SPEC-001 --exclude "node_modules/"
-
-# Auto-resolve conflicts
-moai-worktree sync SPEC-001 --auto-resolve
-
-# Interactive conflict resolution
-moai-worktree sync SPEC-001 --resolve-interactive
-```
-
-### Worktree Templates and Presets
-
-Custom Worktree Templates:
-```bash
-# Create worktree with specific setup
-moai-worktree new SPEC-001 --template frontend
-# Includes: npm install, eslint setup, pre-commit hooks
-
-moai-worktree new SPEC-002 --template backend
-# Includes: virtual environment, test setup, database config
-
-# Custom template configuration
-moai-worktree config set templates.frontend.setup "npm install && npm run setup"
-moai-worktree config set templates.backend.setup "python -m venv venv && source venv/bin/activate && pip install -r requirements.txt"
-```
-
-### Performance Optimization
-
-Optimized Worktree Operations:
-```bash
-# Fast worktree creation (shallow clone)
-moai-worktree new SPEC-001 --shallow --depth 1
-
-# Background sync
-moai-worktree sync SPEC-001 --background
-
-# Parallel operations
-moai-worktree sync --all --parallel
-
-# Caching for faster operations
-moai-worktree config set enable_cache true
-moai-worktree config set cache_ttl 3600
-```
-
----
-
-## Works Well With
-
-Commands:
-- moai:1-plan - SPEC creation with automatic worktree setup
-- moai:2-run - Development in isolated worktree environment
-- moai:3-sync - Integration with automatic worktree sync
-- moai:9-feedback - Worktree workflow improvements
-
-Skills:
-- moai-foundation-core - Parallel development patterns
-- moai-workflow-project - Project management integration
-- moai-workflow-spec - SPEC-driven development
-- moai-git-strategy - Git workflow optimization
-
-Tools:
-- Git worktree - Native Git worktree functionality
-- Rich CLI - Formatted terminal output
-- Click framework - Command-line interface framework
-
----
-
-## Quick Decision Matrix
-
-| Scenario | Primary Pattern | Supporting |
-|----------|------------------|------------|
-| New SPEC development | Worktree isolation + Auto-setup | Integration with /moai:1-plan |
-| Parallel development | Multiple worktrees + Shell integration | Fast switching patterns |
-| Team coordination | Shared registry + Developer prefixes | Conflict resolution |
-| Code review | Isolated review worktrees | Clean sync patterns |
-| Experimental features | Temporary worktrees + Auto-cleanup | Safe experimentation |
-
-Module Deep Dives:
-- [Worktree Commands](modules/worktree-commands.md) - Complete CLI reference
-- [Worktree Management](modules/worktree-management.md) - Core architecture
-- [Parallel Development](modules/parallel-development.md) - Workflow patterns
-- [Integration Patterns](modules/integration-patterns.md) - MoAI-ADK integration
-- [Troubleshooting](modules/troubleshooting.md) - Problem resolution
-
-Full Examples: [examples.md](examples.md)
-External Resources: [reference.md](reference.md)
-
----
-
-Version: 1.0.0
-Last Updated: 2025-11-29
-Status: Active (Complete modular architecture)