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

moai_adk/templates/.claude/skills/moai-workflow-worktree/modules/worktree-commands.md

@@ -0,0 +1,296 @@
+# Worktree Commands Module
+
+Purpose: Complete CLI command reference for Git worktree management with detailed usage examples and advanced options.
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Command Categories:
+- Creation: new - Create isolated worktree
+- Navigation: list, switch, go - Browse and navigate
+- Management: sync, remove, clean - Maintain worktrees
+- Status: status - Check worktree state
+- Configuration: config - Manage settings
+
+Quick Start:
+1. Create worktree: moai-worktree new SPEC-001 "User Authentication"
+2. Switch to worktree: moai-worktree switch SPEC-001
+3. Or use shell eval: eval $(moai-worktree go SPEC-001)
+
+---
+
+## Creation Commands
+
+### moai-worktree new - Create Worktree
+
+Create a new isolated Git worktree for SPEC development.
+
+Syntax: moai-worktree new <spec-id> [description] [options]
+
+Arguments:
+- spec-id: SPEC identifier (e.g., SPEC-001, SPEC-AUTH-001)
+- description: Optional description for the worktree
+
+Options:
+- --branch <name>: Create specific branch instead of auto-generated
+- --base <branch>: Base branch for new worktree (default: main)
+- --template <name>: Use predefined template
+- --shallow: Create shallow clone for faster setup
+- --depth <number>: Clone depth for shallow clone
+- --force: Force creation even if worktree exists
+
+Examples:
+- Basic creation: moai-worktree new SPEC-001 "User Auth System"
+- Custom branch: moai-worktree new SPEC-002 "Payment" --branch feature/payment-gateway
+- From develop: moai-worktree new SPEC-003 "API Refactor" --base develop
+- With template: moai-worktree new SPEC-004 "Frontend" --template frontend
+- Fast creation: moai-worktree new SPEC-005 "Bug Fixes" --shallow --depth 1
+
+Auto-Generated Branch Pattern:
+- Format: feature/SPEC-{ID}-{description-kebab-case}
+- Example: SPEC-001 becomes feature/SPEC-001-user-authentication
+
+---
+
+## Navigation Commands
+
+### moai-worktree list - List Worktrees
+
+Display all registered worktrees with their status and metadata.
+
+Syntax: moai-worktree list [options]
+
+Options:
+- --format <format>: Output format (table, json, csv)
+- --status <status>: Filter by status (active, merged, stale)
+- --sort <field>: Sort by field (name, created, modified, status)
+- --reverse: Reverse sort order
+- --verbose: Show detailed information
+
+Examples:
+- Table format: moai-worktree list
+- JSON output: moai-worktree list --format json
+- Active only: moai-worktree list --status active
+- Sort by date: moai-worktree list --sort created
+- Detailed: moai-worktree list --verbose
+
+### moai-worktree switch - Switch to Worktree
+
+Change current working directory to the specified worktree.
+
+Syntax: moai-worktree switch <spec-id> [options]
+
+Options:
+- --auto-sync: Automatically sync before switching
+- --force: Force switch even with uncommitted changes
+- --new-terminal: Open in new terminal window
+
+Examples:
+- Basic switch: moai-worktree switch SPEC-001
+- With sync: moai-worktree switch SPEC-002 --auto-sync
+- Force switch: moai-worktree switch SPEC-003 --force
+
+### moai-worktree go - Get Worktree Path
+
+Output the cd command for shell integration.
+
+Syntax: moai-worktree go <spec-id> [options]
+
+Options:
+- --absolute: Show absolute path
+- --relative: Show relative path from current directory
+- --export: Export as environment variable
+
+Shell Integration Methods:
+- eval pattern (recommended): eval $(moai-worktree go SPEC-001)
+- source pattern: moai-worktree go SPEC-001 | source
+- manual cd: cd $(moai-worktree go SPEC-001 --absolute)
+
+---
+
+## Management Commands
+
+### moai-worktree sync - Synchronize Worktree
+
+Synchronize worktree with its base branch.
+
+Syntax: moai-worktree sync <spec-id> [options]
+
+Arguments:
+- spec-id: Worktree identifier (or --all for all worktrees)
+
+Options:
+- --auto-resolve: Automatically resolve simple conflicts
+- --interactive: Interactive conflict resolution
+- --dry-run: Show what would be synced without doing it
+- --force: Force sync even with uncommitted changes
+- --include <pattern>: Include only specific files
+- --exclude <pattern>: Exclude specific files
+
+Examples:
+- Sync specific: moai-worktree sync SPEC-001
+- Sync all: moai-worktree sync --all
+- Interactive: moai-worktree sync SPEC-001 --interactive
+- Preview: moai-worktree sync SPEC-001 --dry-run
+- Include pattern: moai-worktree sync SPEC-001 --include "src/"
+- Exclude pattern: moai-worktree sync SPEC-001 --exclude "node_modules/"
+
+Conflict Resolution:
+When conflicts detected, choose from:
+1. Keep worktree version
+2. Accept base branch version
+3. Open merge tool
+4. Skip file
+5. Abort sync
+
+### moai-worktree remove - Remove Worktree
+
+Remove a worktree and clean up its registration.
+
+Syntax: moai-worktree remove <spec-id> [options]
+
+Options:
+- --force: Force removal without confirmation
+- --keep-branch: Keep the branch after removing worktree
+- --backup: Create backup before removal
+- --dry-run: Show what would be removed without doing it
+
+Examples:
+- Interactive: moai-worktree remove SPEC-001
+- Force: moai-worktree remove SPEC-001 --force
+- Keep branch: moai-worktree remove SPEC-001 --keep-branch
+- With backup: moai-worktree remove SPEC-001 --backup
+- Preview: moai-worktree remove SPEC-001 --dry-run
+
+### moai-worktree clean - Clean Up Worktrees
+
+Remove worktrees for merged branches or stale worktrees.
+
+Syntax: moai-worktree clean [options]
+
+Options:
+- --merged-only: Only remove worktrees with merged branches
+- --stale: Remove worktrees not updated in specified days
+- --days <number>: Stale threshold in days (default: 30)
+- --interactive: Interactive selection of worktrees to remove
+- --dry-run: Show what would be cleaned without doing it
+- --force: Skip confirmation prompts
+
+Examples:
+- Merged only: moai-worktree clean --merged-only
+- Stale (30 days): moai-worktree clean --stale
+- Custom threshold: moai-worktree clean --stale --days 14
+- Interactive: moai-worktree clean --interactive
+- Preview: moai-worktree clean --dry-run
+- Force: moai-worktree clean --force
+
+---
+
+## Status and Configuration
+
+### moai-worktree status - Show Worktree Status
+
+Display detailed status information about worktrees.
+
+Syntax: moai-worktree status [spec-id] [options]
+
+Arguments:
+- spec-id: Specific worktree (optional, shows current if not specified)
+
+Options:
+- --all: Show status of all worktrees
+- --sync-check: Check if worktrees need sync
+- --detailed: Show detailed Git status
+- --format <format>: Output format (table, json)
+
+Examples:
+- Current worktree: moai-worktree status
+- Specific worktree: moai-worktree status SPEC-001
+- All with sync check: moai-worktree status --all --sync-check
+- Detailed Git status: moai-worktree status SPEC-001 --detailed
+- JSON output: moai-worktree status --all --format json
+
+Status Output Includes:
+- Worktree path and branch
+- Commits ahead/behind base
+- Modified and untracked files
+- Sync status and last sync time
+
+### moai-worktree config - Configuration Management
+
+Manage moai-worktree configuration settings.
+
+Syntax: moai-worktree config <action> [key] [value]
+
+Actions:
+- get [key]: Get configuration value
+- set <key> <value>: Set configuration value
+- list: List all configuration
+- reset [key]: Reset to default value
+- edit: Open configuration in editor
+
+Configuration Keys:
+- worktree_root: Root directory for worktrees
+- auto_sync: Enable automatic sync (true/false)
+- cleanup_merged: Auto-cleanup merged worktrees (true/false)
+- default_base: Default base branch (main/develop)
+- template_dir: Directory for worktree templates
+- sync_strategy: Sync strategy (merge, rebase, squash)
+
+Examples:
+- List all: moai-worktree config list
+- Get value: moai-worktree config get worktree_root
+- Set value: moai-worktree config set auto_sync true
+- Reset: moai-worktree config reset worktree_root
+- Edit: moai-worktree config edit
+
+---
+
+## Advanced Usage
+
+### Batch Operations
+
+Sync all active worktrees:
+- Use shell loop with list --format json and jq to extract IDs
+- Run sync for each ID in sequence or parallel
+
+Clean all merged worktrees:
+- moai-worktree clean --merged-only --force
+
+Create worktrees from SPEC list:
+- Read SPEC IDs from file
+- Run new command for each
+
+### Shell Aliases
+
+Recommended aliases for .bashrc or .zshrc:
+- mw: Short for moai-worktree
+- mwl: List worktrees
+- mws: Switch to worktree
+- mwg: Navigate with eval pattern
+- mwsync: Sync current worktree
+- mwclean: Clean merged worktrees
+
+### Git Hooks Integration
+
+Post-checkout hook actions:
+- Detect worktree environment
+- Update last access time in registry
+- Check if sync needed with base branch
+- Load worktree-specific environment
+
+Pre-push hook actions:
+- Detect if pushing from worktree
+- Check for uncommitted changes
+- Verify sync status with base
+- Update registry with push timestamp
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+Module: Complete CLI command reference with usage examples

moai_adk/templates/.claude/skills/moai-workflow-worktree/modules/worktree-management.md

@@ -0,0 +1,217 @@
+# Worktree Management Module
+
+Purpose: Core architecture and management patterns for Git worktree operations including registry management, lifecycle control, and resource optimization.
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Core Components:
+- Registry: Central worktree database and metadata tracking
+- Manager: Core operations including create, sync, remove, and cleanup
+- Models: Data structures for worktree metadata
+- Lifecycle: Worktree creation, maintenance, and removal patterns
+
+Key Patterns:
+- Automatic registration and tracking
+- Atomic operations with rollback
+- Resource optimization and cleanup
+- Conflict detection and resolution
+
+---
+
+## Module Architecture
+
+This worktree management module is organized into focused sub-modules:
+
+Registry Architecture: Refer to registry-architecture.md
+- Registry file structure and schema
+- Atomic operations with backup and rollback
+- Concurrent access protection with locking
+- Validation and integrity checks
+
+Resource Optimization: Refer to resource-optimization.md
+- Disk space management and analysis
+- Memory-efficient operations
+- Performance optimization patterns
+- Error handling and recovery
+
+---
+
+## Core Architecture
+
+### Component Overview
+
+WorktreeManager: Central coordinator for all worktree operations.
+- Accepts repository path and worktree root directory
+- Maintains references to RegistryManager and GitManager
+- Provides unified interface for all operations
+
+RegistryManager: Handles persistent storage of worktree metadata.
+- JSON-based registry file storage
+- Atomic updates with backup/rollback
+- Concurrent access protection
+
+GitManager: Interfaces with Git for worktree operations.
+- Creates and removes Git worktrees
+- Manages branch operations
+- Handles sync and merge operations
+
+### Manager Operations
+
+Core Operations:
+- create_worktree: Create new isolated worktree with optional template
+- sync_worktree: Synchronize worktree with base branch
+- remove_worktree: Remove worktree and clean up registration
+- switch_worktree: Change to specified worktree directory
+- cleanup_worktrees: Batch cleanup based on criteria
+
+Query Operations:
+- list_worktrees: Return all worktrees matching optional filters
+- get_worktree: Return specific worktree by ID
+- get_current_worktree: Detect and return current worktree context
+- get_worktree_status: Return detailed status for worktree
+
+Detailed Reference: Refer to registry-architecture.md for registry patterns
+
+---
+
+## Lifecycle Management
+
+### Creation Workflow
+
+Complete worktree creation follows these steps:
+
+1. Validate Input: Check SPEC ID format and uniqueness
+2. Determine Configuration: Branch name, base branch, template selection
+3. Create Worktree Path: Establish directory structure
+4. Create Git Worktree: Use git worktree add command
+5. Apply Template: Run setup commands and create files if template specified
+6. Register Worktree: Add entry to central registry
+7. Post-Creation Hooks: Execute any configured post-creation actions
+
+On Failure:
+- Partial worktree directory is removed
+- Registry entry is not created or removed if partially created
+- Error details captured for debugging
+
+### Synchronization Workflow
+
+Worktree sync with base branch follows these steps:
+
+1. Check Prerequisites: Verify no uncommitted changes (unless forced)
+2. Fetch Updates: Get latest changes from remote
+3. Analyze Needs: Determine commits ahead/behind
+4. Execute Strategy: Merge, rebase, or squash based on configuration
+5. Resolve Conflicts: Auto-resolve or interactive based on options
+6. Update Registry: Record sync timestamp and result
+7. Post-Sync Hooks: Execute any configured post-sync actions
+
+Sync Strategies:
+- merge: Preserve history with merge commit
+- rebase: Linear history by replaying commits
+- squash: Combine all changes into single commit
+
+### Cleanup Workflow
+
+Worktree cleanup based on various criteria:
+
+Finding Cleanup Candidates:
+- Merged worktrees: Branch merged to base branch
+- Stale worktrees: Not accessed within threshold days
+- Large worktrees: Exceeding size threshold
+
+Cleanup Process:
+1. Identify candidates based on criteria
+2. Sort by priority (merged first, then stale, then large)
+3. Interactive selection if requested
+4. Remove each worktree with optional backup
+5. Update registry and statistics
+
+Detailed Reference: Refer to resource-optimization.md for optimization patterns
+
+---
+
+## Registry Overview
+
+### Registry Purpose
+
+The registry is the central database tracking all worktrees and their metadata.
+
+Storage Location: ~/.worktrees/{PROJECT_NAME}/.moai-worktree-registry.json
+
+Registry Contents:
+- version: Schema version for compatibility
+- created_at: Registry creation timestamp
+- last_updated: Most recent modification timestamp
+- config: Global worktree configuration
+- worktrees: Map of SPEC ID to worktree metadata
+- statistics: Aggregated usage statistics
+
+### Worktree Entry Structure
+
+Each worktree entry contains:
+
+Identity:
+- id: SPEC identifier
+- description: Human-readable description
+- path: Absolute filesystem path
+
+Git State:
+- branch: Feature branch name
+- base_branch: Branch created from
+- commits_ahead: Commits ahead of base
+- commits_behind: Commits behind base
+
+Status:
+- status: active, merged, stale, or error
+- created_at: Creation timestamp
+- last_accessed: Most recent access
+- last_sync: Most recent synchronization
+
+Metadata:
+- template: Template used for creation
+- developer: Creator identifier
+- priority: Development priority
+- tags: Categorization tags
+
+Detailed Reference: Refer to registry-architecture.md for complete schema
+
+---
+
+## Quick Decision Guide
+
+For creating a new worktree, use create_worktree with SPEC ID, description, and optional template. The system handles branch creation, registration, and setup automatically.
+
+For synchronizing a worktree, use sync_worktree with SPEC ID. Configure strategy (merge, rebase, squash) and conflict resolution (auto-resolve, interactive) as needed.
+
+For cleaning up worktrees, use cleanup_worktrees with appropriate filters. Target merged branches first, then stale worktrees, then large worktrees.
+
+For registry maintenance, the system handles most operations automatically. Manual intervention only needed for corruption recovery or registry migration.
+
+---
+
+## Sub-Module References
+
+Registry Architecture (registry-architecture.md):
+- Complete registry JSON schema
+- Atomic update patterns with rollback
+- Concurrent access protection with file locking
+- Schema validation and integrity checks
+- Data migration patterns
+
+Resource Optimization (resource-optimization.md):
+- Disk usage analysis and cleanup
+- Memory-efficient streaming operations
+- Performance optimization techniques
+- Comprehensive error handling
+- Recovery patterns for common failures
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+Module: Worktree management overview with progressive disclosure to sub-modules