Summary

Adds comprehensive documentation to warn users about git's single-process limitation when using multiple worktrees. While worktrees safely isolate branches and working directories, git itself is not designed for concurrent operations, and running multiple git commands simultaneously across different worktrees can corrupt the repository.

This addresses a critical safety gap where users may assume that because worktrees allow multiple branches to be checked out simultaneously, it's safe to run git operations in parallel.

Changes

1. README.md - Prominent Safety Warning Section

• Added highly visible warning immediately after the Features section
• Clearly distinguishes what's safe (worktree isolation) vs unsafe (concurrent git commands)
• Explains shared git data structures that can be corrupted
• Provides safe practices for AI agents and sequential operations
• Links to detailed documentation

2. docs/BEST_PRACTICES.md - Comprehensive Safety Guide (New File)

A 400+ line detailed guide covering:

• Git's single-process design and why concurrent operations are dangerous
• What's shared vs isolated in worktrees (with directory structure diagrams)
• Safe vs unsafe patterns with concrete code examples
• 4 common corruption scenarios with detailed explanations
• 4 safe parallel development workflows
• AI agent coordination strategies with locking mechanisms
• Step-by-step recovery procedures from corruption
• Related issues and additional resources

3. AGENTS.md - AI Agent Safety Section

• Added prominent safety section at the top of the existing agent guide
• Critical safety rules for coordinating multiple AI agents
• Safe vs unsafe AI agent workflows with examples
• Using auto-worktree session management for coordination
• Tool-specific configuration (Claude Code, VS Code, Cursor)
• Recovery procedures specific to AI agent scenarios

4. aw.sh - CLI Help Text Warning

• Added styled safety warning to the help command output
• Yellow, bold warning header for visibility
• Clear distinction: "Worktrees are safe, but git is NOT designed for concurrent operations"
• Bulleted list of safe practices
• Reference to detailed documentation

Key Principles

The documentation emphasizes:

1. Worktrees are safe for isolation (multiple branches checked out)
2. Concurrent git commands are dangerous (can corrupt shared .git/ data)
3. Only run one AI agent per repository at a time
4. Disable background git operations in IDEs during active work

What's Shared vs Isolated

Shared across all worktrees (corruption risk):

• .git/objects/ - Object database
• .git/refs/ - Branch references
• .git/config - Repository configuration
• .git/hooks/ - Git hooks
• Pack files and garbage collection

Isolated per worktree (safe):

• Working directory files
• .git/HEAD - Current branch pointer
• .git/index - Staging area
• Worktree-specific logs

Testing

All validations passed:

• ✅ ShellCheck validation
• ✅ Go lint validation (golangci-lint, go vet, go fmt)
• ✅ Go tests (all packages)

Related Issues

Closes #176
Related to #174, #168, #170, #175

🤖 Generated with Claude Code