From 8609181447ad6e78b38cfacbafb56b672b457b86 Mon Sep 17 00:00:00 2001
From: Jeroen Schweitzer <jpmschweitzer@gmail.com>
Date: Sun, 11 Jan 2026 19:37:20 +0100
Subject: [PATCH] docs: add mandatory release procedure to AGENTS.md

Document the correct order for creating releases:
1. Update pyproject.toml version
2. Update CHANGELOG.md
3. Commit version bump
4. Create tag
5. Push with --tags

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 AGENTS.md | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0bfb379..6f58020 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -184,18 +184,28 @@ cat ../webber-sandbox/TASKS.md
 ## Versioning & Releases
 
 Uses prefixed tags:
-- `api/v0.3.0` → Triggers API Docker build
-- `cli/v0.1.0` → Triggers CLI build (future)
+- `api/vX.Y.Z` → Triggers API Docker build
+- `cli/vX.Y.Z` → Triggers CLI build (future)
+
+### MANDATORY Release Procedure
+
+**NEVER push a tag before updating version files.** Follow this exact order:
 
 ```bash
-# API release
-cd webber-api
-# Update version in pyproject.toml
-git add -A && git commit -m "chore: release api v0.3.0"
-git tag api/v0.3.0
+# 1. Update version in pyproject.toml
+# 2. Update CHANGELOG.md with release notes
+# 3. Commit the version bump
+git add -A && git commit -m "chore: release api vX.Y.Z"
+
+# 4. Create the tag (AFTER the commit)
+git tag api/vX.Y.Z
+
+# 5. Push everything together
 git push origin main --tags
 ```
 
+**Why this matters:** Pushing a tag before the version commit requires deleting and recreating the tag, which can trigger CI/CD pipelines prematurely and cause deployment issues.
+
 ---
 
 ## Troubleshooting