[AB#555] docs: add AGENTS.md for AI coding assistants

Root-level AI agent instructions that complement .github/copilot-instructions.md.
Provides quick-start guidance, architecture overview, and critical Windows
development constraints.

Multiple locations ensure broader AI tool compatibility:
- AGENTS.md (root) - discovered by most AI systems
- .github/copilot-instructions.md - GitHub Copilot specific

Author: ChronosMasterOfAllTime

.github/copilot-instructions.md

@@ -3,27 +3,32 @@
 ## Branch Structure
 
 ### Active Branches
+
 - **`main`** - Active development for v3.x (Go rewrite) - **USE THIS FOR ALL PRS**
 - **`master`** - Legacy v2.x maintenance only (bash-based)
 
 ### PR Guidelines
+
 ✅ Target `main` for: features, bug fixes, docs, improvements
 ❌ Target `master` only for: critical v2.x security patches
 
 ### Branch Naming
+
 - `fix/issue/NNN` - Bug fixes
-- `feature/description` - New features  
+- `feature/description` - New features
 - `docs/description` - Documentation
 - `refactor/description` - Code refactoring
 
 ## Project Architecture
 
 ### Tech Stack
+
 - Language: Go (100% rewritten from bash in v3.x)
 - CLI Framework: Cobra
 - Testing: Go testing + some legacy BATS
 
 ### Directory Structure
+
 ```
 cmd/              # CLI commands (Cobra-based)
 ├── core/        # Version management (install, use, list, info)
@@ -57,6 +62,7 @@ Windows uses `.bat` files instead of bash scripts for shims.
 **Batch File Constraints** (Reference: Issue #555):
 
 ❌ **NEVER DO**:
+
 ```bat
 # BAD - Breaks CMD parsing!
 if "%var%"=="value" (
@@ -69,6 +75,7 @@ for %%a in (%*) do (...)
 ```
 
 ✅ **ALWAYS DO**:
+
 ```bat
 # GOOD - Use subroutines
 if "%var%"=="value" call :subroutine
@@ -80,21 +87,24 @@ exit /b 0
 ```
 
 **Key Rules**:
+
 1. NO goto/labels inside parenthesized `if (...)` blocks
-2. NO raw `%*` expansion in `for` loops  
+2. NO raw `%*` expansion in `for` loops
 3. Use single-line conditionals when possible: `if "%DEBUG%"=="1" echo on`
 4. Always propagate exit codes: `exit /b %ERRORLEVEL%`
 5. Use subroutines with `call :label` for complex logic
 
 **Testing on macOS/Linux**:
+
 - Go tests validate template logic ✅
 - Cannot execute `.bat` files on Unix
 - CI runs Windows tests automatically
 
 ## Key Implementation Patterns
 
 ### Shim System Flow
-1. User runs `go version` 
+
+1. User runs `go version`
 2. Hits shim at `~/.goenv/shims/go` (or `go.bat` on Windows)
 3. Shim executes `goenv exec go version`
 4. `goenv exec` resolves current version from:
@@ -106,12 +116,14 @@ exit /b 0
 5. Executes actual Go binary from resolved version
 
 ### Shim Generation
+
 - Triggered by `goenv rehash`
 - Auto-rehashes after `goenv install` and `go install`
 - Scans all versions for binaries
 - Creates platform-specific wrapper (bash or .bat)
 
 ### Version Resolution
+
 - `internal/resolver/resolver.go` - Core logic
 - Smart precedence handling
 - Walks directory tree for `.go-version`
@@ -138,20 +150,23 @@ make build
 ## Common Development Tasks
 
 ### Adding a New Command
+
 1. Create in appropriate `cmd/<category>/` directory
 2. Use Cobra framework pattern
 3. Add to parent command's `init()`
 4. Write tests in `<name>_test.go`
 5. Update documentation
 
 ### Modifying Shim Templates
+
 1. Edit `internal/shims/manager.go`
 2. Update `createUnixShim()` OR `createWindowsShim()`
 3. ⚠️ Windows changes require extra care - see constraints above
 4. Test: `go test ./internal/shims/... ./cmd/shims/...`
 5. Consider Windows batch file gotchas
 
 ### Adding Platform Support
+
 1. Update `internal/utils/` for OS detection
 2. Add platform-specific shim generator
 3. Update install scripts
@@ -160,20 +175,23 @@ make build
 ## Code Style
 
 ### Conventional Commits
+
 ```
 feat(area): description
-fix(area): description  
+fix(area): description
 docs(area): description
 refactor(area): description
 test(area): description
 ```
 
 ### Error Handling
+
 - Use `internal/errors` package
 - Provide context: `errors.FailedTo("action", err)`
 - User-friendly messages
 
 ### Configuration
+
 - Respect environment variables (`GOENV_*`)
 - Use `internal/config` for paths
 - Support `GOENV_ROOT` customization
@@ -214,6 +232,7 @@ GitHub Actions builds release binaries for all platforms.
 ## Issue Resolution Checklist
 
 When fixing issues:
+
 1. ✅ Read issue thoroughly including comments
 2. ✅ Identify affected files/components
 3. ✅ Check for similar issues in issue tracker
@@ -227,6 +246,7 @@ When fixing issues:
 ## Windows-Specific Issue Patterns
 
 Common Windows issues to watch for:
+
 - Batch file syntax errors (goto/label problems)
 - Path separators (use `filepath.Join`)
 - Line endings (CRLF vs LF - see `.gitattributes`)