moai-adk 0.32.8__py3-none-any.whl → 0.41.0__py3-none-any.whl

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

@@ -0,0 +1,149 @@
+# Integration Patterns Module
+
+Purpose: Overview of integration patterns for moai-worktree with MoAI-ADK workflow, development tools, and external systems.
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Integration Points:
+- MoAI-ADK Workflow: Seamless integration with /moai:1-plan, /moai:2-run, /moai:3-sync
+- Development Tools: IDEs, editors, terminal emulators, and development servers
+- Git Workflows: Branch management, CI/CD pipelines, and code review processes
+- Team Collaboration: Shared worktrees, code sharing, and coordination patterns
+
+Core Integration Pattern:
+
+The basic integration workflow follows three phases. During the Plan Phase, the /moai:1-plan command auto-creates a worktree for the SPEC. During the Development Phase, use the moai-worktree go command to navigate to the isolated environment and run /moai:2-run for TDD implementation. During the Sync Phase, use moai-worktree sync to update the worktree and /moai:3-sync for documentation synchronization.
+
+---
+
+## Module Architecture
+
+This integration patterns module is organized into focused sub-modules for progressive disclosure:
+
+MoAI-ADK Integration: Refer to moai-adk-integration.md
+- Plan Phase integration with /moai:1-plan
+- Development Phase integration with /moai:2-run
+- Sync Phase integration with /moai:3-sync
+- Automated cleanup workflows
+
+Tools and External Integration: Refer to tools-integration.md
+- IDE integration including VS Code and JetBrains
+- Terminal and shell integration
+- CI/CD pipeline integration
+- Monitoring and analytics
+
+---
+
+## Integration Overview
+
+### MoAI-ADK Workflow Integration
+
+The worktree system integrates deeply with the MoAI Plan-Run-Sync workflow:
+
+Plan Phase (/moai:1-plan):
+- Automatic worktree creation after SPEC generation
+- Template-based environment setup
+- Branch naming conventions applied automatically
+- Worktree-specific configuration files created
+
+Development Phase (/moai:2-run):
+- TDD execution in isolated worktree context
+- Independent dependency management
+- Automatic registry updates for access tracking
+- Development server isolation per worktree
+
+Sync Phase (/moai:3-sync):
+- Worktree synchronization with base branch
+- Conflict detection and resolution
+- Documentation updates from worktree changes
+- PR creation workflow integration
+
+Cleanup Phase:
+- Automatic cleanup of merged worktrees
+- Archive support for completed work
+- Registry maintenance and integrity checks
+
+Detailed Reference: Refer to moai-adk-integration.md for complete workflow patterns
+
+---
+
+### Development Tools Integration
+
+IDE and Editor Integration:
+- VS Code multi-root workspace generation
+- Dynamic workspace updates as worktrees change
+- Worktree-specific IDE settings and configurations
+- Task and debug configuration per worktree
+
+Terminal Integration:
+- Shell prompt customization for worktree awareness
+- Tab completion for worktree commands
+- Navigation aliases and functions
+- Context preservation between terminal sessions
+
+Git Hooks Integration:
+- Post-checkout hooks for worktree detection
+- Pre-push hooks for validation
+- Automatic environment loading
+
+Detailed Reference: Refer to tools-integration.md for tool configuration patterns
+
+---
+
+### External System Integration
+
+CI/CD Pipeline Integration:
+- GitHub Actions workflow templates
+- Parallel testing across worktrees
+- SPEC-aware build processes
+- Automated deployment from worktrees
+
+Monitoring and Analytics:
+- Usage metrics collection
+- Performance tracking
+- Disk usage optimization
+- Team activity monitoring
+
+Detailed Reference: Refer to tools-integration.md for external system patterns
+
+---
+
+## Quick Decision Guide
+
+For automatic SPEC worktree creation, integrate with /moai:1-plan by configuring auto-creation in worktree settings. Refer to moai-adk-integration.md for implementation details.
+
+For IDE integration with worktrees, use VS Code multi-root workspace generation with dynamic worktree folder updates. Refer to tools-integration.md for configuration.
+
+For CI/CD pipeline integration, implement GitHub Actions workflows with SPEC-aware testing patterns. Refer to tools-integration.md for workflow templates.
+
+For team collaboration with shared registries, configure team registry settings with developer-specific worktree prefixes. Refer to moai-adk-integration.md for coordination patterns.
+
+---
+
+## Sub-Module References
+
+MoAI-ADK Integration (moai-adk-integration.md):
+- Complete /moai:1-plan integration patterns
+- TDD-aware /moai:2-run integration
+- Sync Phase automation with /moai:3-sync
+- Post-PR cleanup workflows
+- Team collaboration patterns
+
+Tools Integration (tools-integration.md):
+- VS Code workspace generation
+- Terminal shell integration
+- Git hooks configuration
+- CI/CD pipeline templates
+- Monitoring and analytics setup
+- Resource management patterns
+
+---
+
+Version: 2.0.0
+Last Updated: 2026-01-06
+Module: Integration patterns overview with progressive disclosure to sub-modules

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

@@ -0,0 +1,245 @@
+# MoAI-ADK Integration Module
+
+Purpose: Detailed integration patterns for moai-worktree with MoAI-ADK Plan-Run-Sync workflow including plan phase automation, TDD integration, and cleanup workflows.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+MoAI-ADK Integration Points:
+- /moai:1-plan: Automatic worktree creation after SPEC generation
+- /moai:2-run: TDD execution in isolated worktree environment
+- /moai:3-sync: Worktree sync with documentation updates
+- Cleanup: Automatic removal of merged worktrees
+
+---
+
+## Plan Phase Integration (/moai:1-plan)
+
+### Automatic Worktree Creation
+
+After SPEC creation, the worktree system automatically generates an isolated development environment.
+
+Branch Naming Convention:
+- Pattern: feature/SPEC-{id}-{title-kebab-case}
+- Example: SPEC-001 with title "User Auth" becomes feature/SPEC-001-user-auth
+
+Worktree Path Pattern:
+- Default: ~/workflows/{project-name}/SPEC-{id}
+- Configurable via worktree_root setting
+
+Creation Workflow:
+1. SPEC is created with /moai:1-plan
+2. Worktree new command is invoked automatically if auto_create is enabled
+3. Branch is created from configured base branch (default: main)
+4. Template is applied if specified
+5. Worktree is registered in the central registry
+6. User receives guidance for switching to the new worktree
+
+### Template-Based Setup
+
+Templates provide pre-configured environments for different development scenarios.
+
+Available Template Types:
+- spec-development: Default SPEC development environment
+- backend: Python/Node.js backend setup with testing frameworks
+- frontend: React/Vue frontend setup with build tools
+- full-stack: Combined backend and frontend configuration
+
+Template Configuration Structure:
+- setup_commands: List of commands to run after worktree creation
+- files: Configuration files to create in the worktree
+- env_vars: Environment variables to set in .env.local
+
+---
+
+## Development Phase Integration (/moai:2-run)
+
+### Worktree-Aware TDD
+
+The TDD manager detects worktree environments and adapts its behavior accordingly.
+
+Worktree Detection:
+- Checks if current directory name starts with SPEC-
+- Looks for worktrees directory in path hierarchy
+- Validates against registry for accurate identification
+
+TDD Execution Benefits:
+- Independent test results per worktree
+- Isolated dependency environments
+- No cross-contamination between SPECs
+- Automatic metadata updates in registry
+
+Registry Updates During Development:
+- last_accessed timestamp updated on each worktree access
+- last_tdd_result stored for progress tracking
+- operation_status recorded for debugging
+
+### Development Server Isolation
+
+Each worktree can run independent development servers without port conflicts.
+
+Port Assignment Strategy:
+- Base port calculated from SPEC ID hash
+- Frontend server: base_port + 0
+- Backend server: base_port + 1
+- Database: base_port + 2
+
+Server Management:
+- PID files stored in worktree root for process tracking
+- Automatic cleanup on worktree removal
+- Status command shows running servers per worktree
+
+---
+
+## Sync Phase Integration (/moai:3-sync)
+
+### Automated Worktree Synchronization
+
+Before PR creation or documentation sync, worktrees should be synchronized with their base branch.
+
+Sync Workflow:
+1. Check for uncommitted changes (abort if found without force flag)
+2. Fetch latest changes from remote
+3. Analyze sync needs (commits ahead/behind)
+4. Execute sync using configured strategy (merge, rebase, or squash)
+5. Update registry with sync timestamp
+6. Continue with documentation sync
+
+Conflict Resolution Options:
+- auto-resolve: Automatically resolve simple conflicts using configured strategy
+- interactive: Prompt for manual resolution of each conflict
+- abort: Cancel sync and preserve current state
+
+Include/Exclude Patterns:
+- Use --include to sync only specific directories like src/ or docs/
+- Use --exclude to skip directories like node_modules/ or build/
+
+### Documentation Generation
+
+After worktree sync, documentation updates can be extracted:
+- API documentation from changed endpoints
+- Test coverage reports from test results
+- Architecture updates from structural changes
+- CHANGELOG entries from commit messages
+
+---
+
+## Post-PR Cleanup Workflow
+
+### Automated Cleanup
+
+After successful PR merge, worktrees can be automatically cleaned up.
+
+Cleanup Triggers:
+- Manual cleanup with clean command
+- Automated cleanup when cleanup_merged is enabled
+- Scheduled cleanup for stale worktrees
+
+Cleanup Options:
+1. Remove worktree and branch (default for merged)
+2. Remove worktree, keep branch for reference
+3. Archive worktree to backup location
+4. Skip cleanup and keep for future reference
+
+Registry Maintenance:
+- Completed SPECs recorded with merged_at timestamp
+- Cleanup action documented for audit trail
+- Statistics updated (total_worktrees, merged_worktrees)
+
+---
+
+## Team Collaboration Patterns
+
+### Shared Worktree Registry
+
+For team environments, configure a shared registry accessible to all developers.
+
+Team Registry Configuration:
+- registry_type: Set to "team" for shared mode
+- shared_registry_path: Network-accessible registry location
+- developer_prefix: Automatic prefix for developer-specific worktrees
+
+Synchronization:
+- Local registry syncs with team registry periodically
+- Merge conflicts resolved by timestamp priority
+- Developer can force local or remote on conflict
+
+### Collaborative Development
+
+Multiple developers can coordinate on related SPECs:
+
+Coordination Pattern:
+1. Lead developer creates base worktree with shared contracts
+2. Team members create dependent worktrees with developer flags
+3. Shared contracts directory maintains API agreements
+4. Integration worktree combines work from all team members
+
+Access Levels:
+- read-only: View worktree status and metadata
+- read-write: Full development access
+- admin: Can modify team registry settings
+
+---
+
+## Configuration Reference
+
+### MoAI Configuration Integration
+
+Worktree settings in .moai/config/config.yaml:
+
+worktree section:
+- auto_create: Enable automatic worktree creation (default: true)
+- auto_sync: Enable automatic synchronization (default: true)
+- cleanup_merged: Remove worktrees for merged branches (default: true)
+- worktree_root: Base directory for worktrees (default: ~/workflows/{project})
+- default_base: Default base branch (default: main)
+- sync_strategy: Sync method - merge, rebase, or squash (default: merge)
+- registry_type: local or team (default: local)
+
+Template Settings:
+- template_dir: Custom template location
+- default_template: Template applied when none specified
+
+---
+
+## Error Handling
+
+### Common Integration Errors
+
+Worktree Already Exists:
+- Error: Worktree path already exists for SPEC ID
+- Resolution: Use --force to recreate or choose different SPEC ID
+
+Uncommitted Changes:
+- Error: Worktree has uncommitted changes during sync
+- Resolution: Commit changes first or use --force flag
+
+Merge Conflicts:
+- Error: Conflicts detected during sync operation
+- Resolution: Use --interactive for manual resolution or --auto-resolve
+
+Registry Corruption:
+- Error: Registry file is invalid or inaccessible
+- Resolution: Run repair command or restore from backup
+
+### Recovery Patterns
+
+For failed worktree creation:
+- Partial worktree is automatically cleaned up
+- Registry entry is removed if created
+- Error details logged for debugging
+
+For failed synchronization:
+- Worktree reset to last known good state if backup ref exists
+- Status set to error in registry
+- Manual intervention flag set for user attention
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Module: MoAI-ADK workflow integration patterns for Plan-Run-Sync phases

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

@@ -0,0 +1,310 @@
+# Advanced Parallel Development Module
+
+Purpose: Advanced use cases for parallel development including feature flags, microservices, performance optimization, and development tool integration.
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+
+---
+
+## Quick Reference (30 seconds)
+
+Advanced Patterns:
+- Feature Flags: Test multiple flag configurations in parallel
+- Microservices: Coordinate development across service boundaries
+- Performance: Optimize resources for parallel operations
+- Integration: IDE and shell enhancements for multi-worktree
+
+---
+
+## Feature Flag Development
+
+### Parallel Flag Implementation
+
+Develop feature flags across multiple worktrees for comprehensive testing.
+
+Worktree Strategy:
+- Backend worktree: Flag implementation and storage
+- Frontend worktree: Flag consumption and UI changes
+- Integration worktree: Testing flag combinations
+
+### Backend Flag Implementation
+
+Create feature flags in backend worktree:
+
+Flag Definition:
+- Environment variable based flags
+- Configuration file based flags
+- Database stored flags
+
+Flag Access Pattern:
+- Read from environment with fallback
+- Default to disabled (false) for safety
+- Log flag state for debugging
+
+### Frontend Flag Consumption
+
+Consume flags in frontend worktree:
+
+Flag Provider:
+- Load flags from environment
+- Provide context to components
+- Support hot reload during development
+
+Component Usage:
+- Conditional rendering based on flags
+- Feature gating for new functionality
+- Graceful degradation when disabled
+
+### Integration Testing
+
+Test flag combinations in integration worktree:
+
+Combination Matrix:
+- Test all flag combinations systematically
+- Document expected behavior per combination
+- Automate flag configuration for tests
+
+Test Execution:
+- Set flag environment variables
+- Run integration test suite
+- Record results per configuration
+
+---
+
+## Microservices Parallel Development
+
+### Service-Per-Worktree Pattern
+
+Each microservice developed in dedicated worktree.
+
+Worktree Creation:
+- Create worktree per service
+- Apply microservice template
+- Configure service-specific settings
+
+Service Configuration:
+- Unique port per service
+- Service name in environment
+- Database URL per service
+
+### Service Discovery
+
+Configure service discovery across worktrees.
+
+Gateway Integration:
+- Create gateway worktree for integration
+- Service configuration with URLs and health checks
+- Proxy routing to individual services
+
+Discovery Pattern:
+- Local configuration file
+- Service URLs based on worktree ports
+- Health check endpoints per service
+
+### Parallel Service Testing
+
+Test services independently and together.
+
+Independent Tests:
+- Unit tests in each service worktree
+- Integration tests with mocked dependencies
+- Contract tests for API boundaries
+
+Integrated Tests:
+- Gateway worktree runs full stack
+- End-to-end tests across services
+- Performance tests with realistic load
+
+---
+
+## Performance Optimization
+
+### Resource Monitoring
+
+Monitor resource usage across parallel worktrees.
+
+Metrics Collected:
+- Process count per worktree
+- Disk usage per worktree
+- Memory usage per worktree
+
+System Resources:
+- Overall CPU load
+- Total memory usage
+- Available disk space
+
+### Worktree Optimization
+
+Optimize individual worktrees for better performance.
+
+Cleanup Actions:
+- Remove log files
+- Clean Python and Node caches
+- Run Git garbage collection
+- Compress large files
+
+Optimization Triggers:
+- Scheduled cleanup intervals
+- Before running tests
+- Before creating PR
+
+### Parallel Operation Limits
+
+Configure limits for parallel operations.
+
+Resource-Based Limits:
+- Maximum concurrent syncs based on CPU count
+- Memory threshold for parallel operations
+- Disk I/O limits for large operations
+
+Graceful Degradation:
+- Queue operations when limits reached
+- Sequential fallback under pressure
+- Priority queue for critical operations
+
+---
+
+## IDE Integration
+
+### VS Code Multi-Root Workspace
+
+Configure VS Code for multi-worktree development.
+
+Workspace Structure:
+- Main repository as first folder
+- Each worktree as additional folder
+- Shared settings across workspace
+
+Folder Configuration:
+- Display name matching SPEC ID
+- Relative path to worktree
+- Folder-specific settings override
+
+Settings Per Worktree:
+- Python interpreter path
+- Node modules location
+- Build output directory
+
+### Worktree-Specific Configuration
+
+Configure IDE settings per worktree.
+
+Python Configuration:
+- Virtual environment path
+- Linting settings
+- Formatter configuration
+- Test runner settings
+
+TypeScript Configuration:
+- Node modules path
+- Build configuration
+- Debug configuration
+- Launch settings
+
+### Task Automation
+
+Automate common operations in IDE.
+
+Task Types:
+- Run Tests: Execute test suite for SPEC
+- Sync Worktree: Pull latest changes
+- Switch Worktree: Change active folder
+
+Task Configuration:
+- Command to execute
+- Working directory (worktree path)
+- Presentation settings
+
+---
+
+## Shell Integration
+
+### Enhanced Navigation
+
+Improve shell experience for multi-worktree development.
+
+Switch with Context:
+- Save current worktree on switch
+- Restore context on return
+- Load worktree-specific environment
+
+Quick Toggle:
+- Toggle between last two worktrees
+- Maintain work context
+- Minimal switching overhead
+
+### Status Overview
+
+Display parallel development status.
+
+Worktree Status:
+- List all active worktrees
+- Show running servers per worktree
+- Display uncommitted changes
+
+Server Status:
+- Check PID files for running servers
+- Report server types and ports
+- Alert on stopped servers
+
+### Quick Functions
+
+Shell functions for common operations.
+
+Create and Switch:
+- Create new worktree
+- Immediately switch to it
+- Start development server
+
+Develop in Worktree:
+- Switch to specified worktree
+- Start /moai:2-run
+
+Push from Worktree:
+- Sync worktree
+- Push to remote branch
+
+---
+
+## Troubleshooting Parallel Development
+
+### Common Issues
+
+Port Conflicts:
+- Symptom: Server fails to start
+- Cause: Another worktree using same port
+- Solution: Check port usage, adjust port assignment
+
+Memory Exhaustion:
+- Symptom: Operations fail or slow down
+- Cause: Too many parallel operations
+- Solution: Reduce concurrent worktrees, optimize memory
+
+Disk Space:
+- Symptom: Operations fail with disk errors
+- Cause: Too many large worktrees
+- Solution: Clean old worktrees, compress inactive ones
+
+### Resolution Strategies
+
+Port Conflict Resolution:
+- List running processes per port
+- Identify conflicting worktree
+- Stop conflicting server or adjust port
+
+Memory Optimization:
+- Close unnecessary development servers
+- Reduce parallel sync operations
+- Use shallow clones for temporary worktrees
+
+Disk Space Recovery:
+- Clean build artifacts
+- Remove unused dependencies
+- Archive inactive worktrees
+
+---
+
+Version: 1.0.0
+Last Updated: 2026-01-06
+Module: Advanced parallel development patterns for feature flags, microservices, and optimization