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

moai_adk/templates/.claude/skills/moai-workflow-worktree/reference.md

@@ -0,0 +1,357 @@
+# MoAI Worktree Reference
+
+Purpose: External resources, documentation, and additional learning materials for moai-worktree skill.
+
+Version: 1.0.0
+Last Updated: 2025-11-29
+
+---
+
+## External Documentation
+
+### Git Worktree Official Documentation
+
+- Git Worktree Documentation: [https://git-scm.com/docs/git-worktree](https://git-scm.com/docs/git-worktree)
+ - Official Git worktree command reference
+ - Advanced worktree patterns and workflows
+ - Troubleshooting and best practices
+
+- Pro Git Book - Worktrees: [https://git-scm.com/book/en/v2/Git-Tools-Worktree](https://git-scm.com/book/en/v2/Git-Tools-Worktree)
+ - Comprehensive guide to Git worktrees
+ - Multiple workflow management strategies
+ - Worktree lifecycle management
+
+### Development Tools Documentation
+
+- VS Code Multi-Root Workspaces: [https://code.visualstudio.com/docs/editor/multi-root-workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces)
+ - Setting up multi-root workspaces for worktree development
+ - Workspace configuration and task automation
+ - Extension management across worktrees
+
+- Click Framework: [https://click.palletsprojects.com/](https://click.palletsprojects.com/)
+ - Command-line interface framework used by moai-worktree
+ - Advanced CLI patterns and argument parsing
+ - Custom command development
+
+### Python Development Resources
+
+- Rich Library: [https://rich.readthedocs.io/](https://rich.readthedocs.io/)
+ - Terminal output formatting used by moai-worktree
+ - Tables, progress bars, and syntax highlighting
+ - Advanced terminal UI patterns
+
+- Pathlib Documentation: [https://docs.python.org/3/library/pathlib.html](https://docs.python.org/3/library/pathlib.html)
+ - Modern path manipulation for cross-platform compatibility
+ - File system operations and directory traversal
+ - Path validation and security considerations
+
+---
+
+## Related Skills and Integrations
+
+### MoAI-ADK Skills
+
+- moai-foundation-core: Foundation principles and delegation patterns
+ - Reference: [moai-foundation-core modules](moai-foundation-core/modules/)
+ - Integration: Worktree creation follows foundation delegation patterns
+
+- moai-workflow-project: Project management and configuration
+ - Reference: [moai-workflow-project modules](moai-workflow-project/modules/)
+ - Integration: Project setup with worktree support
+
+- moai-foundation-claude: Claude Code execution patterns
+ - Reference: [moai-foundation-claude modules](moai-foundation-claude/modules/)
+ - Integration: Command and agent execution patterns
+
+### Complementary Tools
+
+- Git Hooks: Custom Git hooks for worktree automation
+ - Pre-commit hooks for worktree validation
+ - Post-checkout hooks for environment setup
+ - Pre-push hooks for worktree synchronization
+
+- Docker: Containerized development environments
+ - Docker Compose for service orchestration in worktrees
+ - Volume mounts for persistent data across worktrees
+ - Environment isolation for different worktree configurations
+
+- Makefiles: Build automation across worktrees
+ - Parallel build processes for multiple worktrees
+ - Shared build targets and dependencies
+ - Cleanup and optimization automation
+
+---
+
+## Community Resources
+
+### Open Source Projects
+
+- Git Worktree Managers:
+ - [git-worktree](https://github.com/charmbracelet/git-worktree) - Go implementation
+ - [git-worktree.nvim](https://github.com/ThePrimeagen/git-worktree.nvim) - Neovim plugin
+ - [git-worktree.el](https://github.com/magit/git-worktree.el) - Emacs integration
+
+### Blog Posts and Articles
+
+- Parallel Development with Git Worktrees: [Medium Article](https://medium.com/@username/parallel-development-git-worktrees)
+- Git Worktree Best Practices: [Dev.to Article](https://dev.to/username/git-worktree-best-practices)
+- Advanced Worktree Workflows: [GitHub Gist](https://gist.github.com/username/worktree-patterns)
+
+### Video Tutorials
+
+- Git Worktree Tutorial: [YouTube Tutorial](https://www.youtube.com/watch?v=worktree-tutorial)
+- Parallel Development Setup: [Screencast](https://www.youtube.com/watch?v=parallel-dev-setup)
+- Worktree Automation: [Conference Talk](https://www.youtube.com/watch?v=worktree-automation)
+
+---
+
+## Performance and Optimization
+
+### Performance Monitoring Tools
+
+- htop: Process monitoring for worktree resource usage
+ - Monitor CPU and memory usage across worktrees
+ - Identify resource-intensive worktree operations
+ - Track disk usage and I/O patterns
+
+- ncdu: Disk usage analysis for worktree cleanup
+ - Analyze disk usage patterns across worktrees
+ - Identify large files and directories for optimization
+ - Generate cleanup recommendations
+
+- git-branchless: Faster Git operations for large repositories
+ - Optimize performance for worktree operations
+ - Reduce overhead for large codebase worktrees
+ - Improve sync performance across multiple worktrees
+
+### Optimization Techniques
+
+1. Shallow Worktrees: For fast prototyping and testing
+ ```bash
+ moai-worktree new SPEC-PROTO-001 "Prototype" --shallow --depth 1
+ ```
+
+2. Selective Synchronization: Sync only essential files
+ ```bash
+ moai-worktree sync SPEC-001 --include "src/" --exclude "node_modules/"
+ ```
+
+3. Background Operations: Non-blocking worktree operations
+ ```bash
+ moai-worktree sync --all --background
+ ```
+
+---
+
+## Security Considerations
+
+### Worktree Security Best Practices
+
+1. Isolation: Ensure worktrees don't share sensitive data
+ - Use separate environment files (`.env.local`) for each worktree
+ - Avoid sharing API keys or credentials between worktrees
+ - Regularly audit worktree configurations
+
+2. Access Control: Implement proper file permissions
+ - Set appropriate permissions on worktree directories (755)
+ - Restrict access to sensitive worktree data
+ - Use Git hooks to prevent accidental secrets commits
+
+3. Backup Strategy: Implement worktree backup and recovery
+ - Regular backups of worktree registry and configurations
+ - Version control for worktree templates and scripts
+ - Recovery procedures for corrupted worktrees
+
+### Security Tools
+
+- git-secrets: Detect sensitive data in worktrees
+ - Scan worktrees for accidental secrets or credentials
+ - Integrate with pre-commit hooks for worktree security
+ - Automatic remediation suggestions
+
+- truffleHog: Security scanning for worktree files
+ - Comprehensive security audit across worktrees
+ - API key and credential detection
+ - Custom pattern matching for project-specific secrets
+
+---
+
+## Integration Examples
+
+### CI/CD Integration
+
+#### GitHub Actions Workflow
+
+```yaml
+# .github/workflows/worktree-testing.yml
+name: Worktree Testing
+
+on:
+ push:
+ branches: [ "feature/SPEC-*" ]
+
+jobs:
+ test-worktree:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v3
+ with:
+ fetch-depth: 0
+
+ - name: Setup moai-worktree
+ run: |
+ pip install moai-adk
+ echo "Setting up worktree environment..."
+
+ - name: Test Worktree Operations
+ run: |
+ # Test worktree creation
+ moai-worktree new test-spec "Test Worktree"
+
+ # Test worktree synchronization
+ moai-worktree sync test-spec
+
+ # Test worktree cleanup
+ moai-worktree remove test-spec
+```
+
+#### Jenkins Pipeline
+
+```groovy
+// Jenkinsfile for worktree testing
+pipeline {
+ agent any
+
+ stages {
+ stage('Setup') {
+ steps {
+ sh '''
+ pip install moai-adk
+ moai-worktree config set worktree_root $WORKSPACE/worktrees
+ '''
+ }
+ }
+
+ stage('Test') {
+ parallel {
+ stage('Auth Worktree') {
+ steps {
+ sh '''
+ moai-worktree new SPEC-AUTH-001 "Authentication Worktree"
+ cd $(moai-worktree go SPEC-AUTH-001)
+ npm test
+ '''
+ }
+ }
+
+ stage('Payment Worktree') {
+ steps {
+ sh '''
+ moai-worktree new SPEC-PAY-001 "Payment Worktree"
+ cd $(moai-worktree go SPEC-PAY-001)
+ npm test
+ '''
+ }
+ }
+ }
+ }
+
+ stage('Cleanup') {
+ steps {
+ sh '''
+ moai-worktree clean --force
+ rm -rf $WORKSPACE/worktrees
+ '''
+ }
+ }
+ }
+}
+```
+
+---
+
+## Troubleshooting Resources
+
+### Common Error Patterns
+
+1. Permission Denied Errors:
+ - Check file permissions on worktree directories
+ - Verify user has write access to worktree root
+ - Ensure Git repository permissions are correct
+
+2. Disk Space Issues:
+ - Monitor disk usage with `df -h`
+ - Clean up large files with `ncdu`
+ - Implement automated cleanup schedules
+
+3. Network Connectivity:
+ - Verify Git remote repository accessibility
+ - Check network connectivity for external dependencies
+ - Use offline worktree operations when possible
+
+### Debugging Tools
+
+- git worktree prune: Clean up stale worktree references
+- git fsck: Repository integrity checking
+- strace: System call tracing for debugging
+- lsof: Open file tracking and process monitoring
+
+---
+
+## Version History
+
+### Current Version (1.0.0)
+- Initial release with core worktree management features
+- Integration with MoAI-ADK workflow commands
+- Comprehensive documentation and examples
+
+### Future Roadmap
+- v1.1.0: Team collaboration features
+ - Shared worktree registries
+ - Multi-developer coordination
+ - Conflict resolution algorithms
+
+- v1.2.0: Advanced automation features
+ - Worktree templates marketplace
+ - Custom automation scripts
+ - Performance optimization tools
+
+- v1.3.0: Cloud integration
+ - Cloud-based worktree storage
+ - Remote worktree synchronization
+ - Distributed development workflows
+
+---
+
+## Contributing
+
+### How to Contribute
+
+1. Report Issues: Submit bug reports and feature requests
+2. Submit Pull Requests: Contribute code and documentation improvements
+3. Share Examples: Add usage examples and integration patterns
+4. Document Workflows: Create tutorials and guides
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/moai-adk.git
+
+# Set up development environment
+cd moai-adk
+pip install -e .
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest tests/test_worktree.py -v
+
+# Build documentation
+mkdocs build
+```
+
+---
+
+Version: 1.0.0
+Last Updated: 2025-11-29
+Reference: External resources and additional learning materials for moai-worktree

moai_adk/templates/.git-hooks/pre-commit

@@ -0,0 +1,128 @@
+#!/bin/bash
+################################################################################
+# Pre-commit Hook: Security & Workflow Protection
+#
+# Purpose: Prevent API keys, tokens, and sensitive data from being committed
+#
+# Phases:
+# 1. Security Secrets Detection (CRITICAL) - Blocks if secrets found
+# 2. Workflow Protection - Enforces Git branch rules
+#
+# Exit codes:
+# 0 - All checks passed
+# 1 - Secrets detected or workflow violation
+################################################################################
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+NC='\033[0m' # No Color
+
+###############################################################################
+# PHASE 1: Security Secrets Detection (CRITICAL)
+###############################################################################
+
+echo "🔒 [Phase 1] Running Security Secrets Detection..."
+
+SECRETS_FOUND=false
+
+# Define secret patterns to detect
+declare -a PATTERNS=(
+    "AIzaSy[A-Za-z0-9_-]{35}"        # Google APIs
+    "sk-[A-Za-z0-9]{20,}"             # OpenAI
+    "sk_[A-Za-z0-9]{20,}"             # OpenAI variant
+    "sk-ant-[A-Za-z0-9]{20,}"        # Anthropic
+    "AKIA[0-9A-Z]{16}"                # AWS Access Keys
+    "api[_-]?key['\"]?\s*[:=]\s*['\"]?[A-Za-z0-9_-]{20,}['\"]?"
+    "bearer[_-]?token['\"]?\s*[:=]\s*['\"]?[A-Za-z0-9._-]{20,}['\"]?"
+    "aws_secret_access_key['\"]?\s*[:=]\s*['\"]?[A-Za-z0-9/+=]{40}['\"]?"
+    "access[_-]?token['\"]?\s*[:=]\s*['\"]?[A-Za-z0-9._-]{20,}['\"]?"
+)
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+for FILE in $STAGED_FILES; do
+    # Skip binary files
+    if file "$FILE" 2>/dev/null | grep -q "binary"; then
+        continue
+    fi
+
+    # Skip certain directories
+    if [[ "$FILE" =~ node_modules|venv|\.venv|\.git|\.next|dist ]]; then
+        continue
+    fi
+
+    # Get the staged content
+    STAGED_CONTENT=$(git show :"$FILE" 2>/dev/null)
+
+    # Check against each pattern
+    for PATTERN in "${PATTERNS[@]}"; do
+        if echo "$STAGED_CONTENT" | grep -qE "$PATTERN"; then
+            if [ "$SECRETS_FOUND" = false ]; then
+                echo ""
+                echo -e "${RED}❌ SECURITY ERROR: Secrets detected!${NC}"
+                SECRETS_FOUND=true
+            fi
+
+            echo -e "${RED}  File: $FILE${NC}"
+            LINE_NUMS=$(echo "$STAGED_CONTENT" | grep -n -E "$PATTERN" | cut -d: -f1 | head -3)
+            echo -e "${YELLOW}  Lines: $LINE_NUMS${NC}"
+        fi
+    done
+done
+
+if [ "$SECRETS_FOUND" = true ]; then
+    echo ""
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${RED}⛔ COMMIT BLOCKED: Secrets detected in staged files${NC}"
+    echo -e "${RED}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+    echo "✅ FIX:"
+    echo "  1. Replace secret with: 'your_actual_key_here'"
+    echo "  2. Store real key in: .env (git-ignored)"
+    echo "  3. Stage fixed files: git add <file>"
+    echo "  4. Retry commit: git commit"
+    echo ""
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Security check passed${NC}"
+
+###############################################################################
+# PHASE 2: Workflow Protection (Branch Rules)
+###############################################################################
+
+echo "🔄 [Phase 2] Checking Workflow Rules..."
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Detect direct commits on develop branch
+if [ "$CURRENT_BRANCH" = "develop" ]; then
+    echo "⚠️  WARNING: You are attempting to commit directly to develop branch."
+    echo ""
+    echo "📋 Hybrid Personal-Pro Workflow Rules:"
+    echo "  - Personal Mode (1-2 people): feature/SPEC-XXX → main"
+    echo "  - Team Mode (3+ people): feature/SPEC-XXX → develop → main"
+    echo ""
+    echo "✓ Current: Personal Mode → Work on main branch"
+    echo ""
+    echo "💡 Recommended Actions:"
+    echo "  1. git reset HEAD (cancel commit)"
+    echo "  2. git checkout main"
+    echo "  3. git checkout -b feature/SPEC-XXX"
+    echo "  4. Continue your work"
+    echo ""
+    read -p "Continue anyway? (y/n): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+echo -e "${GREEN}✅ Workflow check passed${NC}"
+echo ""
+exit 0