chore: Improve AGENTS.md

Signed-off-by: George Jenkins <gvjenkins@gmail.com>

Author: gjenkins8

AGENTS.md

@@ -1,48 +1,88 @@
 # AGENTS.md
 
 ## Overview
-Helm is a package manager for Kubernetes written in Go, supporting v3 (stable) and v4 (unstable) APIs.
 
-## Build & Test
+Helm is a package manager for Kubernetes written in Go. It enables users to define, install, and upgrade complex Kubernetes applications using charts.
+This document provides an overview of the codebase structure, development guidelines, and key patterns for contributors.
+
+The codebase supports both a SDK for advanced users, and a CLI for direct end user usage.
+
+The project currently supports Helm v3 and Helm v4 versions, based on the `dev-v3` and `main` branches respectively.
+
+## Build and test
+
 ```bash
 make build              # Build binary
 make test               # Run all tests (style + unit)
 make test-unit          # Unit tests only
 make test-coverage      # With coverage
-make test-style         # Linting
-golangci-lint run       # Direct linting
+make test-style         # Linting (wraps golangci-lint)
 go test -run TestName   # Specific test
 ```
 
-## Code Structure
-- `/cmd/helm/` - CLI entry point (Cobra-based)
-- `/pkg/` - Public API
+## Code structure
+
+Major packages:
+
+- `cmd/helm/` - CLI entry point, wires CLI flags to `pkg/cmd/` commands
+- `pkg/` - Public API
   - `action/` - Core operations (install, upgrade, rollback)
+  - `cmd/` - Cobra command implementations bridging CLI flags to `pkg/action/`
   - `chart/v2/` - Stable chart format
   - `engine/` - Template rendering (Go templates + Sprig)
+  - `kube/` - Kubernetes client abstraction layer
   - `registry/` - OCI support
+  - `release/` - Release types and interfaces (`v1/`, `common/`)
+  - `repo/` - Chart repository indexing and interaction
   - `storage/` - Release backends (Secrets/ConfigMaps/SQL)
-- `/internal/` - Private implementation
+- `internal/` - Private implementations
   - `chart/v3/` - Next-gen chart format
+  - `release/v2/` - Release package for chart v3 support
+
+## Development
+
+### Compatibility
+
+Changes are required to maintain backward compatibility as described in [HIP-0004: Document backwards-compatibility rules](https://helm.sh/community/hips/hip-0004).
+
+Typically this means that:
 
-## Development Guidelines
+- the signatures of public APIs ie. those in the `pkg/` directory should not change
+- CLI commands and parameters should not be removed or changed in a way that would break existing scripts or workflows
+- functional behaviour (as implied or documented) must not be modified in a way that would break existing users' expectations
+
+An exception to the above is where incompatiby changes are needed to fix a security vulnerability, where minimal breaking changes may be made to address the issue.
+
+### Code standards
 
-### Code Standards
 - Use table-driven tests with testify
 - Golden files in `testdata/` for complex output
 - Mock Kubernetes clients for action tests
 - All commits must include DCO sign-off: `git commit -s`
 
 ### Branching
-- `main` - Helm v4 development
-- `dev-v3` - Helm v3 stable (backport from main)
 
-### Dependencies
+Standard workflow is for PR development changes to the `main` branch. Minor release branches are cut from `main`, then maintained for critical fixes via patch releases.
+Bug and security fixes are also backported to `dev-v3` where applicable.
+
+Development branches:
+
+- `main` - Helm v4
+- `dev-v3` - Helm v3 (backport security and bugfixes from main)
+
+Release branches:
+
+- `release-v3.X` - Release branches for v3.X versions
+- `release-v4.X` - Release branches for v4.X versions
+
+### Major dependencies
+
 - `k8s.io/client-go` - Kubernetes interaction
 - `github.com/spf13/cobra` - CLI framework
 - `github.com/Masterminds/sprig` - Template functions
 
-### Key Patterns
-- **Actions**: Operations in `/pkg/action/` use shared Configuration
-- **Dual Chart Support**: v2 (stable) in `/pkg/`, v3 (dev) in `/internal/`
-- **Storage Abstraction**: Pluggable release storage backends
+### Key patterns
+
+- **Actions**: High-level operations live in `pkg/action/`, typlically using a shared Configuration
+- **Chart versions**: Charts v2 (stable) in `pkg/chart/v2`, v3 (under development) in `internal/chart/v3`
+- **Plugins and extensibility**: Enabling additional functionality via plugins and extension points, such as custom template functions or storage backends is preferred over incorporating into Helm's codebase