chore: Improve AGENTS.md

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

Author: gjenkins8

AGENTS.md

@@ -1,9 +1,17 @@
 # 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.
+Enabling 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 is currently supporting v3 and v4 versions, based on on the `dev-v3` and `main` branches respectively.
+
+## Build and test
+
 ```bash
 make build              # Build binary
 make test               # Run all tests (style + unit)
@@ -14,35 +22,63 @@ golangci-lint run       # Direct linting
 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 (Cobra-based)
+- `pkg/` - Public API
   - `action/` - Core operations (install, upgrade, rollback)
   - `chart/v2/` - Stable chart format
   - `engine/` - Template rendering (Go templates + Sprig)
   - `registry/` - OCI support
   - `storage/` - Release backends (Secrets/ConfigMaps/SQL)
-- `/internal/` - Private implementation
+- `internal/` - Private implementations
   - `chart/v3/` - Next-gen chart format
 
-## Development Guidelines
+## 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:
+
+- 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
+  - this includes CLI output
+- functional behaviour (as implied or documented) must not be modified in a way that would break existing users' expectations
+
+### 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/charts/v2`, v3 (under development) in `internal/charts/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