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

@@ -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 |
+| Branch | Purpose |
-|------|---------|---------|
+|--------|---------|
-| Feature | `feature/<story-id>-short-description` | `feature/2.1-create-exchange` |
+| `main` | Production-ready code only. Release branches merge here when confirmed good. |
-| Bug fix | `fix/<issue>-short-description` | `fix/matching-self-assignment` |
+| `release/vX.Y.Z` | Release branches. Created from `main`, feature branches merge here. |
-| Chore | `chore/short-description` | `chore/update-dependencies` |
+| `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
 

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
+### Branch Structure
-- `fix/<description>` - Bug fixes
-- `chore/<description>` - Maintenance
 
-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