feat: introduce develop branch as integration branch

.github/workflows/release-drafter.yml

@@ -2,7 +2,7 @@ name: Release Drafter
 
 on:
   push:
-    branches: [main]
+    branches: [develop, main]
   pull_request:
     types: [opened, reopened, synchronize]
   workflow_dispatch:

.github/workflows/validate.yml

@@ -2,9 +2,9 @@ name: Validate
 
 on:
   push:
-    branches: [main]
+    branches: [main, develop]
   pull_request:
-    branches: [main]
+    branches: [main, develop]
   workflow_call:
 
 jobs:

CLAUDE.md

@@ -46,7 +46,10 @@ tools, dotfiles, credentials, MCPs, and Claude Code configuration all included.
 - **Terraform** for infrastructure as code
 
 ### Git & GitHub Workflow
-- Always branch from `main`, never commit directly
+- **Branch model:** `main` = latest release (always stable). `develop` = integration branch.
+- Always branch from `develop`, never commit directly to `main` or `develop`
+- PRs always target `develop`
+- `main` is only updated via the develop→main release PR opened by `/publish-release`
 - Always open a PR for review before merging
 - Commit messages should be descriptive — explain *why*, not just *what*
 - Conventional commits style: `feat:`, `fix:`, `docs:`, `chore:`

CONTRIBUTING.md

@@ -34,10 +34,22 @@ If you've found something that is broken or outdated in a way that affects every
 Fork and clone to the standard path:
 ```bash
 git clone git@github.com:<YOUR_FORK>/mac-dev-setup ~/Repos/<YOUR_GITHUB_USERNAME>/mac-dev-setup
+cd ~/Repos/<YOUR_GITHUB_USERNAME>/mac-dev-setup
+git checkout develop
 ```
 
 ---
 
+## Branch Model
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Always equals the latest published release — stable, never directly committed to |
+| `develop` | Integration branch — all PRs target here |
+| `feature/*`, `fix/*`, etc. | Short-lived branches off `develop` |
+
+PRs go to `develop`. When enough changes accumulate for a release, `develop` is promoted to `main` via the `/publish-release` skill, which opens the develop→main PR automatically.
+
 ## Development Workflow
 
 Run `shellcheck` on any modified scripts before committing:
@@ -100,13 +112,19 @@ release gate.
 
 > Only the repo owner publishes releases.
 
-1. Update `CHANGELOG.md` — move items from `[Unreleased]` into the new version section if needed.
-2. Run the bump script:
-   ```bash
-   ./scripts/bump-version.sh patch   # or minor / major
-   ```
-3. Push the commit and tag:
-   ```bash
-   git push && git push --tags
-   ```
-4. The release pipeline runs automatically: validate → VM acceptance → draft release notes → publish.
+Releases are handled by the `/publish-release` Claude Code skill, which automates the full flow:
+
+1. Bumps version on `develop`, commits `chore: release v<version>`
+2. Opens a PR: `develop → main`
+3. Owner approves and merges the PR
+4. Tags `main` with `v<version>` and pushes the tag
+5. Release pipeline fires automatically: validate → VM acceptance → publish
+
+To trigger manually:
+```bash
+# In Claude Code
+/publish-release 1.0.0
+
+# Or via bump script directly (then follow the steps above)
+./scripts/bump-version.sh patch   # or minor / major / set <version>
+```

claude-skills/publish-release/SKILL.md

@@ -1,65 +1,82 @@
 ---
 name: publish-release
-description: Publish a new versioned release for a repository. Handles VERSION bump, CHANGELOG promotion, git commit, tag, and push to trigger the release pipeline.
+description: Publish a new versioned release. Bumps version on develop, opens a develop→main PR, merges it, tags main, and triggers the release pipeline.
 ---
 
 Publish a new release based on the user's request: $ARGUMENTS
 
 ## Parse the request
 
 Extract from the user's message:
-- **version**: the version string (e.g. `1.0.0`, `0.1.0-beta.1`, `2.1.0-rc.1`). Strip any leading `v`.
+- **version**: explicit version string (e.g. `1.0.0`, `0.2.0-beta.1`) OR a bump level (`patch`, `minor`, `major`). Strip any leading `v`.
 - **repo**: optional repository name. If not specified, use the current working directory. If named, look under `~/Repos` for a matching directory.
 
 If the version is ambiguous or missing, ask the user to confirm before proceeding.
 
 ## Pre-flight checks
 
 1. Confirm you are in the correct repository directory (or `cd` to it)
-2. Run `git status` — the working tree must be clean with no uncommitted changes
-3. Run `git checkout main && git pull` — must be on `main` and up to date with `origin/main`
+2. Run `git status` — the working tree must be clean
+3. Run `git checkout develop && git pull` — must be on `develop` and up to date
 4. Confirm `VERSION` file exists in the repo root
 5. Read the current version from `VERSION` and show it to the user before proceeding
 
-## Execute the release
+## Step 1 — Bump version on develop
 
-Run the bump script with the appropriate subcommand:
+Run the bump script:
 
 ```bash
-# For patch/minor/major increments
+# Explicit version (including pre-release)
+./scripts/bump-version.sh set <version>
+
+# Or a relative increment
 ./scripts/bump-version.sh patch   # or minor / major
+```
 
-# For explicit versions including pre-release
-./scripts/bump-version.sh set <version>
+The script updates `VERSION`, commits with `chore: release v<version>`, and creates an annotated tag locally. **Do not push the tag yet** — push only the commit:
+
+```bash
+git push origin develop
 ```
 
-The script will:
-- Update `VERSION`
-- Promote `[Unreleased]` in `CHANGELOG.md` to the new version with today's date
-- Commit with message `chore: release v<version>`
-- Create an annotated tag `v<version>`
+## Step 2 — Open develop → main PR
+
+```bash
+gh pr create \
+  --base main \
+  --head develop \
+  --title "chore: release v<version>" \
+  --body "Promotes develop to main for release v<version>.
+
+After merging, the tag will be pushed to trigger the release pipeline."
+```
+
+Show the user the PR URL and ask them to approve and merge it.
+
+## Step 3 — Tag main after merge
 
-## Push
+After the user confirms the PR is merged:
 
 ```bash
-git push && git push --tags
+git checkout main && git pull
+git tag -a "v<version>" -m "Release v<version>"
+git push origin "v<version>"
 ```
 
-## Confirm pipeline triggered
+## Step 4 — Confirm pipeline triggered
 
-After pushing, run:
 ```bash
 gh run list --limit 3
 ```
 
 Show the user the release pipeline URL and confirm the tag was pushed. Let them know:
-- If the version contains `-` (e.g. `-beta.1`, `-rc.1`) it will be published as a **pre-release** in GitHub and will not show as the latest version
-- If it is a stable version (e.g. `1.0.0`) it will become the **latest** release after the pipeline passes
+- If the version contains `-` (e.g. `-beta.1`, `-rc.1`) it is published as a **pre-release** and will not show as the latest version
+- If it is a stable version (e.g. `1.0.0`) it becomes the **latest** release after all pipeline gates pass
 
 ## Summary
 
 Tell the user:
-- What version was tagged
+- What version was tagged on `main`
 - That the pipeline is running: validate → VM acceptance → publish
 - Where to watch it: `https://github.com/amcheste/mac-dev-setup/actions`
-- That a GitHub Release will be created automatically if all gates pass
+- That `main` now equals the new release and `develop` is ready for the next cycle