From 7580c39a8435c095058040abb90a81c91a653010 Mon Sep 17 00:00:00 2001
From: Phil Skentelbery <phil@thesatelliteoflove.com>
Date: Mon, 22 Dec 2025 12:27:05 -0700
Subject: [PATCH] docs: update git workflow to release-based branching

- Rename master to main
- Add release branch workflow (release/vX.Y.Z)
- Feature branches now created from release branches
- Release branches merge to main when confirmed good
---
 .claude/agents/developer.md | 36 +++++++++++++++++++++++++++---------
 CLAUDE.md                   | 26 +++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 14 deletions(-)

diff --git a/.claude/agents/developer.md b/.claude/agents/developer.md
index f243274..75c317c 100644
--- a/.claude/agents/developer.md
+++ b/.claude/agents/developer.md
@@ -191,15 +191,32 @@ exclude_lines = [
 
 ## Git Workflow
 
-Follow trunk-based development with short-lived feature branches.
+Release-based workflow with feature branches.
 
-### Branch Naming
+### Branch Structure
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Feature | `feature/<story-id>-short-description` | `feature/2.1-create-exchange` |
-| Bug fix | `fix/<issue>-short-description` | `fix/matching-self-assignment` |
-| Chore | `chore/short-description` | `chore/update-dependencies` |
+| Branch | Purpose |
+|--------|---------|
+| `main` | Production-ready code only. Release branches merge here when confirmed good. |
+| `release/vX.Y.Z` | Release branches. Created from `main`, feature branches merge here. |
+| `feature/<story-id>-description` | Feature branches. Created from a release branch. |
+| `fix/<description>` | Bug fix branches. Created from a release branch. |
+| `chore/<description>` | Maintenance branches. Created from a release branch. |
+
+### Workflow
+
+1. **Check current release branch**: Verify which release branch you should work from
+2. **Create feature branch**: Branch from the release branch (e.g., `git checkout -b feature/2.1-create-exchange release/v0.1.0`)
+3. **Develop**: Write tests, implement, commit
+4. **Merge to release**: When story is complete, merge feature branch to the release branch
+5. **Delete feature branch**: Clean up after merge
+
+### Branch Rules
+
+- Release branches are always created from `main`
+- Feature/fix/chore branches are always created from a release branch
+- Never commit directly to `main`
+- Never merge feature branches directly to `main`
 
 ### Commit Practices
 
@@ -231,12 +248,13 @@ for creating new gift exchanges.
 Story: 2.1
 ```
 
-### Merge to Main
+### Merge to Release Branch
 
 - Ensure all tests pass before merging
 - Ensure coverage threshold is met
-- Merge feature branches to `main` when story is complete
+- Merge feature branches to the release branch when story is complete
 - Delete feature branch after merge
+- The coordinator will handle merging release branches to `main`
 
 ## Key Reference Documents
 
diff --git a/CLAUDE.md b/CLAUDE.md
index fd68c76..d3ffe9a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,10 +46,26 @@ uv run mypy src            # Type check
 
 ## Git Workflow
 
-Trunk-based development with short-lived branches:
+Release-based workflow with feature branches:
 
-- `feature/<story-id>-description` - New features
-- `fix/<description>` - Bug fixes
-- `chore/<description>` - Maintenance
+### Branch Structure
 
-Merge to `main` when complete. Delete branch after merge.
+- `main` - Production-ready code only. Release branches merge here when confirmed good.
+- `release/vX.Y.Z` - Release branches. Created from `main`, feature branches merge here.
+- `feature/<story-id>-description` - Feature branches. Created from a release branch.
+- `fix/<description>` - Bug fix branches. Created from a release branch.
+- `chore/<description>` - Maintenance branches. Created from a release branch.
+
+### Workflow
+
+1. **Start a release**: Create `release/vX.Y.Z` from `main`
+2. **Develop features**: Create `feature/` branches from the release branch
+3. **Complete features**: Merge feature branches back to the release branch
+4. **Ship release**: When release is confirmed good, merge release branch to `main`
+
+### Rules
+
+- Release branches are always created from `main`
+- Feature/fix/chore branches are always created from a release branch
+- Never commit directly to `main`
+- Delete feature branches after merging to release