@chris1807/claude-kit 2.1.54 → 2.1.55

package/README.md

@@ -209,9 +209,9 @@ your-project/                      ← Project-specific
 │   │   ├── deploy.md              # /deploy "commit message"
 │   │   ├── create-release.md      # /create-release 23
 │   │   ├── deploy-release.md      # /deploy-release 23 staging
-│   │   ├── cherry-pick.md         # /cherry-pick AB#1234 production
-│   │   ├── promote.md             # /promote staging production
-│   │   ├── rollback.md            # /rollback AB#1234 production
+│   │   ├── cherry-pick.md         # /cherry-pick AB#1234 prod
+│   │   ├── promote.md             # /promote main dev
+│   │   ├── rollback.md            # /rollback AB#1234 prod
 │   │   ├── add-to-release.md      # /add-to-release 24 AB#4599
 │   │   ├── status.md              # /status release 24
 │   │   ├── cleanup-branches.md    # /cleanup-branches
@@ -305,7 +305,7 @@ Claude automatically:
 1. Runs pre-flight checks (dotnet build, tsc)
 2. Stages and commits with the provided message
 3. Pushes the current branch
-4. Triggers the CD pipeline if on an environment branch
+4. Triggers the CD pipeline if on an environment branch (`dev`, `test`, `staging`, `prod`) — never on `main`, which has no pipeline
 
 ### Create a Release
 
@@ -325,31 +325,36 @@ Claude automatically:
 ```
 
 Claude automatically:
-1. Finds all work items in Release #23
+1. Finds all work items in Release #23 and checks each against the environment's gate state (`Ready for Staging` here)
 2. Cherry-picks their commits into `release/23-to-staging`
-3. Creates a PR targeting the staging branch
+3. Creates a PR targeting the `staging` branch — merging it triggers the Staging pipeline
 4. Links all work items to the PR
+5. After you reply `merged`, moves the work items to `Staging`
+
+The same command walks a release through `test` → `staging` → `prod`; with no environment given it picks the next one.
 
 ### Cherry-Pick Work Items
 
 ```
-/cherry-pick AB#1234 AB#1235 production
+/cherry-pick AB#1234 AB#1235 prod
 ```
 
-Cherry-picks specific work items to an environment without a formal release.
+Cherry-picks specific work items to an environment without a formal release. Same gate check and post-merge state advance as `/deploy-release`. `main` is also a valid target — that's how a hot fix that went straight to `prod` is brought back into the compare branch.
 
 ### Promote an Environment
 
 ```
-/promote staging production
+/promote main dev
+/promote staging prod
+/promote                  ← auto-detects from the current branch
 ```
 
-Creates a PR to promote all code from staging to production. Shows a summary of all included commits before confirming.
+Creates a PR to promote all code from one branch to the next in the chain (`main → dev → test → staging → prod`). Shows every commit and work item before confirming, gate-checks the work items, and advances their states after you reply `merged`. `main → dev` is the usual first hop after feature PRs merge — nothing has deployed before that.
 
 ### Rollback a Deployment
 
 ```
-/rollback AB#1234 production
+/rollback AB#1234 prod
 /rollback last staging
 ```
 
@@ -411,15 +416,30 @@ Finds and deletes branches that have been fully merged. Protects environment bra
 
 ### Target State (All Projects)
 
-Every project should converge to this standard. Each long-lived branch maps to an Azure subscription and environment:
+`main` is the **compare branch** — the default branch, the one feature PRs target, and the one every environment is compared against. **Merging into `main` deploys nothing.** Each environment has its own branch, and a PR merging into that branch is what triggers its CD pipeline:
+
+| Branch | Environment | Deploys When |
+|--------|-------------|-------------|
+| `main` | — (compare / integration) | **Never** — a PR merging into `main` does not deploy |
+| `dev` | Development | PR merged into `dev` |
+| `test` | Test (QA) | PR merged into `test` |
+| `staging` | Staging | PR merged into `staging` |
+| `prod` | Production | PR merged into `prod` |
+
+> **Note:** A project that hasn't migrated yet (e.g. one that still has only `main` and `develop`) keeps working — every command reads the project's Pipeline Configuration table and uses the branch you're on. No branch names are hardcoded.
+
+### Work Item States Follow the Environments
+
+Every environment has a work item state, and the promotion commands keep them in sync. The "Ready for …" states are human sign-offs; the commands never set them.
 
-| Branch | Azure Subscription | Environment | Deploys When |
-|--------|-------------------|-------------|-------------|
-| `develop` | Dev | Development | PR merged into `develop` |
-| `staging` | Staging | Staging | PR merged into `staging` |
-| `main` | Production | Production | PR merged into `main` (with approval gate) |
+| Promotion | Gate (item should already be…) | State after the PR merges |
+|-----------|-------------------------------|---------------------------|
+| `main → dev` | `Code Review` | `Ready for Testing` |
+| `dev → test` | `Ready for Testing` | `Testing` |
+| `test → staging` | `Ready for Staging` (QA sign-off) | `Staging` |
+| `staging → prod` | `Ready to Deploy` (stakeholder sign-off) | `Deployed` |
 
-> **Note:** Some projects are not yet in sync — they may use `master` instead of `main`, or lack a `staging` branch. All commands work dynamically with whatever branch you're on. No branch names are hardcoded.
+`/deploy-release`, `/cherry-pick`, and `/promote` check the gate before creating the PR, then ask you to reply `merged` once the PR completes and advance the states. `/status` flags anything whose state lags the branch it's on.
 
 ### Branch Naming
 
@@ -439,11 +459,12 @@ The branch is always created off the **current branch** — no assumptions are m
 
 ### Code Promotion Flow
 
-Code flows through environments via PRs, never by direct push:
+Code flows through environments via PRs, never by direct push. Every merge **after** `main` deploys:
 
 ```
-feature/AB#1234-... ──PR──▸ develop ──PR──▸ staging ──PR──▸ main
-   (work branch)            (Dev)          (Staging)      (Production)
+feature/AB#1234-... ──PR──▸ main ──PR──▸ dev ──PR──▸ test ──PR──▸ staging ──PR──▸ prod
+   (work branch)          (compare,     (Dev)       (Test)        (Staging)      (Production)
+                          no deploy)
 ```
 
 ---
@@ -462,8 +483,8 @@ claude
 ```
 
 ```
-# Switch to the develop branch first
-git checkout develop
+# Start from the compare branch
+git checkout main
 
 # Implement the work item
 /implement AB#1234
@@ -478,9 +499,15 @@ Claude will:
 6. Implement using backend and/or frontend agents
 7. Run all quality checks (build, lint, tests, review)
 8. Generate a UAT checklist and **pause for you to manually test**
-9. After you confirm "testing passed", create a PR targeting `develop`
+9. After you confirm "testing passed", create a PR targeting `main`, close the child Task with its hours, and move the work item to `Code Review`
 
-The PR merges into `develop`, which triggers the Dev environment CD pipeline.
+The PR merges into `main`. **That merge deploys nothing** — `main` is the compare branch. The work reaches Dev when `main` is promoted:
+
+```
+/promote main dev
+```
+
+Merge that PR, reply `merged`, and the work items move to `Ready for Testing`.
 
 ### Step 2: Deploy Changes (Quick Commits)
 
@@ -490,11 +517,11 @@ For smaller changes that don't need the full `/implement` workflow:
 /deploy "Fix typo in dashboard header"
 ```
 
-This commits, pushes, and triggers the pipeline if you're on an environment branch. If you're on a feature branch, it just pushes — the pipeline triggers on PR merge.
+This commits, pushes, and triggers the pipeline if you're on an environment branch (`dev`, `test`, `staging`, `prod`). On `main` or a feature branch it just pushes — nothing deploys until the work is promoted.
 
 ### Step 3: Group Work Items into a Release
 
-Once multiple work items are merged to `develop` and tested in Dev, group them into a release:
+Once multiple work items are merged to `main` and smoke-tested on Dev, group them into a release:
 
 ```
 /create-release 23
@@ -508,23 +535,24 @@ Claude will:
 2. Show you the list and ask for confirmation
 3. Create a `Release #23` iteration in Azure DevOps
 4. Assign all work items to the iteration and tag them with `release-23`
-5. Tell you how to deploy: `/deploy-release 23 staging` or `/deploy-release 23 production`
+5. Tell you how to deploy: `/deploy-release 23 test`, then `staging`, then `prod`
 
-### Step 4: Deploy a Release to Staging
+### Step 4: Deploy a Release to Test, then Staging
 
 ```
-/deploy-release 23 staging
+/deploy-release 23 test
 ```
 
 Claude will:
-1. Find all work items tagged `release-23`
-2. Find their associated commits on the `develop` branch
-3. Create a release branch: `release/23-to-staging`
+1. Find all work items tagged `release-23` and check each is at the gate for Test (`Ready for Testing`)
+2. Find their associated commits on `dev`
+3. Create a release branch: `release/23-to-test`
 4. Cherry-pick all commits for each work item
-5. Create a PR from `release/23-to-staging` → `staging`
+5. Create a PR from `release/23-to-test` → `test`
 6. Link all work items to the PR
+7. After you reply `merged`, move the work items to `Testing`
 
-After the PR is reviewed and merged, the Staging CD pipeline triggers automatically.
+After the PR is reviewed and merged, the Test CD pipeline triggers automatically. QA tests there and sets each passing item to `Ready for Staging`; then `/deploy-release 23 staging` repeats the process (gate `Ready for Staging`, state after merge `Staging`).
 
 ### Step 5: Test on Staging
 
@@ -532,45 +560,46 @@ QA and stakeholders test on the Staging environment. If issues are found, fix th
 
 ### Step 6: Deploy a Release to Production
 
-When staging testing passes:
+When stakeholders have verified on Staging and set the items to `Ready to Deploy`:
 
 ```
-/deploy-release 23 production
+/deploy-release 23 prod
 ```
 
-Same process — cherry-picks the release's commits to a PR targeting the production branch. After merge, the Production CD pipeline triggers (with approval gate).
+Same process — gate `Ready to Deploy`, cherry-picks from `staging` into a PR targeting `prod`. After merge, the Production CD pipeline triggers; reply `merged` and the items move to `Deployed`.
 
 ### Selective Deployment
 
-If staging has 5 user stories but only 3 are ready for production:
+If staging has 5 user stories but only 3 are `Ready to Deploy`:
 
 **Option A: Create a smaller release**
 ```
 /create-release 24
 ```
-Include only the 3 ready stories, then `/deploy-release 24 production`.
+Include only the 3 ready stories, then `/deploy-release 24 prod`.
 
 **Option B: Cherry-pick specific items**
 ```
-/cherry-pick AB#1234 AB#1235 AB#1236 production
+/cherry-pick AB#1234 AB#1235 AB#1236 prod
 ```
 This cherry-picks just those 3 work items without creating a formal release.
 
 ### Promoting Without a Release
 
-To promote **all** code from one environment to the next (no cherry-picking):
+To promote **all** code from one branch to the next (no cherry-picking):
 
 ```
-/promote staging production
+/promote main dev
+/promote staging prod
 ```
 
-This creates a PR from `staging` → production branch containing everything. Use this when all staging code is ready for production.
+This creates a PR from the source branch to the next one in the chain containing everything. `main → dev` is the everyday first hop; `staging → prod` is for when everything on staging is approved.
 
 You can also auto-detect the next environment:
 ```
 /promote
 ```
-If you're on the `staging` branch, it auto-detects `staging → production`.
+If you're on `main`, it auto-detects `main → dev`; on `staging`, `staging → prod`.
 
 ### Hot Fix Workflow
 
@@ -578,7 +607,7 @@ For critical production issues:
 
 1. Switch to the production branch:
    ```
-   git checkout main
+   git checkout prod
    ```
 2. Run `/implement` with the Hot Fix work item:
    ```
@@ -587,7 +616,8 @@ For critical production issues:
 3. Claude creates a `hotfix/AB#9999-fix-crash-on-submit` branch
 4. Automated checks still run (build, lint, tests, review)
 5. **Manual UAT is skipped** — you get an abbreviated confirmation instead
-6. PR targets the production branch directly with a `hotfix` label
+6. PR targets `prod` directly with a `hotfix` label — merging it deploys straight to production
+7. Then bring the fix back to `main` (a second PR from the same branch, or `/cherry-pick AB#9999 main`) so the next `main → dev` promotion doesn't overwrite it
 
 ### Rollback a Deployment
 
@@ -595,7 +625,7 @@ If a deployment causes issues:
 
 **Revert specific work items:**
 ```
-/rollback AB#1234 production
+/rollback AB#1234 prod
 ```
 
 **Revert the most recent deployment:**
@@ -605,12 +635,12 @@ If a deployment causes issues:
 
 Claude will:
 1. Find the commits to revert
-2. Create a revert branch (e.g., `revert/2026-03-21-on-production`)
+2. Create a revert branch (e.g., `revert/2026-09-06-on-prod`)
 3. Run `git revert` on each commit
 4. Run pre-flight checks on the reverted code
 5. Create a PR targeting the environment branch
 
-Merge the PR to deploy the rollback.
+Merge the PR to deploy the rollback. Work item states are left alone — Claude tells you which items were reverted so you can decide. If the reverted commits are also on `main`, the next promotion brings them back unless the revert is applied there too.
 
 ### Code Review
 
@@ -639,14 +669,14 @@ Claude reviews for:
 | `/deep-review` | `/deep-review 142` | Deep, Ultracode-orchestrated review: checks out the branch, builds/tests it, verifies every requirement, checks for regressions, flags out-of-scope changes, then comments + votes |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/fix-review` | `/fix-review 142` | Fix everything flagged on a PR — human reviewer comments and automated `/review` findings alike: implement in severity order, validate, push, resolve threads |
-| `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on environment branch |
+| `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on an environment branch (`dev`/`test`/`staging`/`prod`) — never on `main` |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 iteration with tags |
-| `/deploy-release` | `/deploy-release 23 staging` | Cherry-pick release work items to environment via PR |
+| `/deploy-release` | `/deploy-release 23 staging` | Gate-check → cherry-pick release work items to environment via PR → advance states after `merged` |
 | `/add-to-release` | `/add-to-release 24 AB#4599` | Add work items to an existing release |
-| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 production` | Cherry-pick specific work items to environment via PR |
-| `/promote` | `/promote staging production` | PR to promote all code between environments |
-| `/rollback` | `/rollback AB#1234 production` | Revert specific commits on an environment via PR |
-| `/status` | `/status release 24` | Check status of a release, pipeline, work item, or environment |
+| `/cherry-pick` | `/cherry-pick AB#1234 AB#1235 prod` | Gate-check → cherry-pick specific work items to environment via PR → advance states after `merged` |
+| `/promote` | `/promote main dev` | PR to promote all code to the next branch in the chain (`main → dev → test → staging → prod`) → advance states after `merged` |
+| `/rollback` | `/rollback AB#1234 prod` | Revert specific commits on an environment via PR |
+| `/status` | `/status release 24` | Check status of a release, pipeline, work item, or environment; flags work items whose state lags their environment |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose one child task with hours per story |
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for unpointed items ready to estimate — stories in `Design Approved`, bugs in `New` (bugs have no design states) → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Also audits the drop-out queue — tagged bugs and stories bounced to Design Review — for items whose creator answered but which nobody returned to the sweep |
@@ -725,7 +755,7 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 | Memory Type | Purpose | Example |
 |-------------|---------|---------|
 | **user** | Who you are, preferences, expertise | "Senior .NET dev, prefers terse responses" |
-| **feedback** | What to do / avoid (self-improving) | "Always push to both main and develop" |
+| **feedback** | What to do / avoid (self-improving) | "Never enable 'Complete associated work items' when merging a PR" |
 | **project** | Decisions, priorities, blockers | "Using Stripe instead of Dwolla because..." |
 | **reference** | URLs, credentials, external resources | "Staging URL: https://..." |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.54",
+  "version": "2.1.55",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

package/templates/agents/project/deployer.md

@@ -23,8 +23,8 @@ You deploy code changes to Azure environments. Follow the standard sequence for
 
    | File family | Parallel files to check |
    |-------------|------------------------|
-   | `appsettings.json` | `appsettings.Development.json`, `appsettings.Staging.json`, `appsettings.QA.json`, `appsettings.Production.json` |
-   | `.env` | `.env.development`, `.env.staging`, `.env.qa`, `.env.production`, `.env.local`, `.env.example` |
+   | `appsettings.json` | `appsettings.Development.json`, `appsettings.Test.json`, `appsettings.QA.json`, `appsettings.Staging.json`, `appsettings.Production.json` |
+   | `.env` | `.env.development`, `.env.test`, `.env.qa`, `.env.staging`, `.env.production`, `.env.local`, `.env.example` |
 
    Present a (key × environment) table to the user. For any missing cell, prompt the user to supply a value (real, placeholder, or empty) before pushing, or to confirm the omission is intentional because the key is wired through a pipeline variable group, Key Vault, or App Configuration for that environment. Do NOT push until every missing entry is either filled in or explicitly skipped by the user.
 
@@ -47,10 +47,11 @@ Push only the current branch. Do NOT cross-push to other branches — deployment
 
 ### Step 4: Trigger Pipeline (Conditional)
 
-Only trigger the CD pipeline if you are pushing directly to an environment branch (the branch a CD pipeline watches). Check the project's CLAUDE.md or pipeline configuration for which branches map to which environments.
+Only trigger the CD pipeline if you are pushing directly to an environment branch (the branch a CD pipeline watches). Check the project's CLAUDE.md **Pipeline Configuration** table for which branches map to which environments. The standard layout is `main` (compare branch — **no pipeline, merging into it deploys nothing**) followed by the environment branches `dev → test → staging → prod`, each deploying when a PR merges into it.
 
-- **On an environment branch** (e.g., `develop`, `staging`, `main`): Trigger the appropriate CD pipeline using the Azure DevOps MCP server.
-- **On a feature/hotfix/bugfix/story/work branch**: Do NOT trigger the pipeline. It will trigger automatically when the PR is merged into the target branch.
+- **On an environment branch** (`dev`, `test`, `staging`, `prod` — a row with pipeline IDs): Trigger the listed CD pipeline(s) using the Azure DevOps MCP server.
+- **On `main`**: Do NOT trigger anything. Report that the change will deploy when `main` is promoted to `dev`.
+- **On a feature/hotfix/bugfix/story/work branch**: Do NOT trigger the pipeline. The work deploys when it is promoted after the PR merges into `main`.
 
 ### Step 5: Monitor
 
@@ -69,9 +70,10 @@ These operations are performed when the user explicitly requests promotions, che
 
 When asked to promote code from one environment to the next:
 
-1. Create a PR from the source branch to the target branch (e.g., `develop` → `staging`, or `staging` → `main`)
-2. Include a summary of all changes being promoted
+1. Create a PR from the source branch to the next branch in the chain (`main` → `dev`, `dev` → `test`, `test` → `staging`, `staging` → `prod`)
+2. Include a summary of all changes being promoted and the work items they carry
 3. After PR is merged, the CD pipeline for the target environment triggers automatically
+4. Once the user confirms the merge, advance the carried User Stories / Bugs / Hot Fixes to the environment's state (`dev` → `Ready for Testing`, `test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`) — never backward, never a Feature or Task. The `/promote` command documents the full gate-check and state rules
 
 ### Deploy Release
 
@@ -86,6 +88,7 @@ When asked to deploy a release (e.g., "deploy release #23 to staging"):
 7. Push the release branch and create a PR to the target environment branch
 8. Link all work items to the PR
 9. After merge, the CD pipeline triggers automatically
+10. Once the user confirms the merge, advance the carried work items to the environment's state (see Promote to Environment, item 4)
 
 ### Cherry-Pick Deployment (Ad-Hoc)
 
@@ -97,6 +100,7 @@ When asked to deploy specific stories/commits outside of a formal release:
 4. If conflicts arise, STOP and report them — do not resolve automatically
 5. Push the cherry-pick branch and create a PR to the target environment branch
 6. After merge, the CD pipeline triggers automatically
+7. Once the user confirms the merge, advance the carried work items to the environment's state (see Promote to Environment, item 4)
 
 ### Rollback
 
@@ -108,6 +112,8 @@ When asked to roll back a deployment:
 4. Run pre-flight checks (Step 1) on the reverted code
 5. Push and create a PR to the environment branch
 6. For production rollbacks, treat as urgent — flag to the user immediately
+7. Do not change work item states on a rollback — tell the user which items were reverted and let them decide
+8. If the reverted commits are also on `main`, warn that the next promotion brings them back unless the revert is applied to `main` too
 
 ---
 

package/templates/commands/cherry-pick.md

@@ -2,35 +2,47 @@ Cherry-pick specific work items to an environment. Usage: `/cherry-pick <work-it
 
 Parse `$ARGUMENTS` to extract:
 - **Work item IDs**: one or more IDs (e.g., "AB#1234 AB#1235" or "1234, 1235")
-- **Target environment**: the environment to deploy to (e.g., "staging", "production")
+- **Target environment**: the environment to deploy to (`dev`, `test`, `staging`, `prod`/`production`) or its branch. `main` is also a valid target — that is how a hot fix that went straight to `prod` gets brought back into the compare branch.
 
-## Step 1: Read the Work Items
+## Environment ↔ State Reference
 
-Fetch each work item from Azure DevOps via MCP. Present the list:
+Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** table — never hardcode them. The first row is the compare branch (`main`; **merging into it deploys nothing**); the rows below are the environment branches in promotion order, and a PR merging into one of them triggers its pipeline:
+
+| Branch | Environment | Gate — items should already be in… | State set after the PR merges |
+|---|---|---|---|
+| `main` | — (compare branch) | — | *(no change)* |
+| `dev` | Dev | `Code Review` (merged to `main`) | `Ready for Testing` |
+| `test` | Test | `Ready for Testing` | `Testing` |
+| `staging` | Staging | `Ready for Staging` | `Staging` |
+| `prod` | Production | `Ready to Deploy` | `Deployed` |
+
+`Ready for Staging` and `Ready to Deploy` are set by QA and stakeholders — **never by this command**.
+
+## Step 1: Read the Work Items and Gate-Check Them
+
+Fetch each work item from Azure DevOps via MCP. Compare each one's `System.State` with the target's gate and annotate anything behind it (QA or a stakeholder hasn't signed off) or ahead of it (already been through this environment). Features and Tasks are listed but not gate-checked.
 
 ```
 ## Cherry-Pick to {environment}
 
-| ID | Type | Title | State |
-|----|------|-------|-------|
-| AB#1234 | User Story | Add payment export | Ready for Testing |
-| AB#1235 | Bug | Fix login redirect | Ready for Testing |
+| ID | Type | Title | State | Gate ({gate state}) |
+|----|------|-------|-------|---------------------|
+| AB#1234 | User Story | Add payment export | Ready to Deploy | ✓ |
+| AB#1235 | Bug | Fix login redirect | Staging | ⚠ behind — stakeholders haven't set Ready to Deploy |
 
-Cherry-pick {count} work items to {environment}? (yes/no)
+Cherry-pick {count} work items to {environment}? Items behind the gate: include / drop / cancel
 ```
 
-Wait for confirmation.
+Wait for confirmation. `drop` removes flagged items from this cherry-pick only.
 
 ## Step 2: Find Commits
 
-For each work item, find associated commits using `repo_search_commits` with `includeWorkItems: true`, or by searching for `AB#{id}` in commit messages on the source branch.
+For each work item, find associated commits using `repo_search_commits` with `includeWorkItems: true`, or by searching for `AB#{id}` in commit messages on the source branch (the environment one step before the target — e.g. `staging` when targeting `prod`, `main` when targeting `dev`).
 
 If no commits are found for a work item, STOP and report which work item has no associated commits.
 
 ## Step 3: Create Cherry-Pick Branch
 
-Determine the target environment branch. Do NOT hardcode branch names — check the project's CLAUDE.md or pipeline configuration.
-
 ```bash
 git checkout <target-environment-branch>
 git pull origin <target-environment-branch>
@@ -61,7 +73,7 @@ Options:
 Which option? (1 / 2 / 3)
 ```
 
-- **Option 1:** Run `git cherry-pick --skip` and continue with remaining work items. Note the skipped item in the summary.
+- **Option 1:** Run `git cherry-pick --skip` and continue with remaining work items. Note the skipped item in the summary — it does **not** get its state advanced in Step 7.
 - **Option 2:** Run `git cherry-pick --abort`, delete the cherry-pick branch, and switch back to the original branch.
 - **Option 3:** Wait for the user to resolve conflicts and run `git cherry-pick --continue`, then proceed.
 
@@ -82,7 +94,7 @@ Cherry-picking:
    - **description**: List all work items with IDs and titles
 3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
 
-## Step 6: Present Summary
+## Step 6: Present Summary and Wait for the Merge
 
 ```
 Cherry-pick PR created for {environment}.
@@ -92,5 +104,22 @@ Work items:
 - AB#1234: Add payment export
 - AB#1235: Fix login redirect
 
-Merge the PR to trigger the CD pipeline for {environment}.
+Merging the PR triggers the CD pipeline for {environment}.
+Reply `merged` once the PR is complete and the pipeline is green — I'll move these {count} work items to `{state after merge}`. (Or `skip`.)
 ```
+
+When the target is `main`, there is no pipeline and no state change — say so and stop here.
+
+## Step 7: Advance Work Item States (after `merged`)
+
+When the user replies `merged`:
+
+1. **Confirm the PR is actually completed** via the Azure DevOps MCP. If it isn't, say so and wait.
+2. For every cherry-picked work item of type **User Story**, **Bug**, or **Hot Fix**, set `System.State` to the target's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`) via `wit_update_work_item`.
+   - **Never move backward** — an item already past the target state keeps it; note it.
+   - **Never touch a Feature or Task.**
+   - Skipped (conflict) or dropped items are not on the branch — leave them alone.
+   - An invalid-state error means this project's template differs — confirm with `get_type`, report the item, continue. Don't silently swallow it.
+3. Report a `Was → Now` table per item and the next human step.
+
+If the user replies `skip`, leave the states alone and note that `/status` will flag the lag later.

package/templates/commands/cleanup-branches.md

@@ -12,9 +12,9 @@ git branch -r --merged
 ```
 
 Exclude protected branches — never delete these:
-- `main`, `master`, `develop`, `development`
-- `staging`, `Staging`
-- `Dev`, `QA`
+- The compare branch: `main`, `master`
+- The environment branches: `dev`, `test`, `staging`, `prod` (any casing — `Dev`, `Test`, `Staging`, `Prod`)
+- Legacy names still in use on unmigrated projects: `develop`, `development`, `QA`
 - Any branch listed in the project's CLAUDE.md Pipeline Configuration table
 
 ## Step 2: Identify Candidates
@@ -33,13 +33,13 @@ Present the list:
 ### Branches to delete ({count}):
 | Branch | Last Commit | Merged Into |
 |--------|-------------|-------------|
-| story/AB#4521-admin-export | 2026-03-18 | develop |
-| bugfix/AB#4589-login-plus-sign | 2026-03-19 | develop |
-| release/24-to-staging | 2026-03-21 | staging |
-| cherry-pick/2026-03-22-to-production | 2026-03-22 | main |
+| story/AB#4521-admin-export | 2026-09-01 | main |
+| bugfix/AB#4589-login-plus-sign | 2026-09-02 | main |
+| release/24-to-staging | 2026-09-05 | staging |
+| cherry-pick/2026-09-06-to-prod | 2026-09-06 | prod |
 
 ### Protected (will NOT be deleted):
-- main, develop, staging
+- main, dev, test, staging, prod
 
 Delete {count} merged branches? (yes/no)
 ```
@@ -69,5 +69,5 @@ Deleted:
 - story/AB#4521-admin-export (local + remote)
 - bugfix/AB#4589-login-plus-sign (local + remote)
 - release/24-to-staging (remote only)
-- cherry-pick/2026-03-22-to-production (remote only)
+- cherry-pick/2026-09-06-to-prod (remote only)
 ```

package/templates/commands/create-release.md

@@ -11,7 +11,7 @@ If `$ARGUMENTS` is provided, use it as the release name (e.g., `$ARGUMENTS` = "2
 Ask the user which work items to include. They may provide:
 - A list of work item IDs (e.g., "AB#1234, AB#1235, AB#1236")
 - A query (e.g., "all completed user stories in the current sprint")
-- A state filter (e.g., "all items in Ready for Testing")
+- A state filter (e.g., "all items in Ready for Testing" for a release heading to Test, "all items in Ready for Staging" for one heading to Staging)
 
 Use the Azure DevOps MCP to search/query for the specified work items. Present the list for confirmation:
 
@@ -60,6 +60,9 @@ Work items assigned:
 - AB#1235: Fix login redirect
 - AB#1236: View history
 
-To deploy this release to staging:  /deploy-release {N} staging
-To deploy this release to production: /deploy-release {N} production
+Deploy it one environment at a time — each merge deploys, and the command advances the work items' states after you confirm the merge:
+  /deploy-release {N} test      → items go to Testing
+  /deploy-release {N} staging   → items go to Staging   (after QA sets Ready for Staging)
+  /deploy-release {N} prod      → items go to Deployed  (after stakeholders set Ready to Deploy)
+`/deploy-release {N}` with no environment picks the next one automatically.
 ```

package/templates/commands/deep-review.md

@@ -111,7 +111,7 @@ Verify the change is safe beyond the lines it touched.
 Specifically check:
 - **Changed shared code** — for every public method/class/interface/DTO the diff modifies, find its other callers and confirm the change is backward-compatible or all callers were updated.
 - **Test fallout** — any failing test from Step 4 in an area this PR didn't intend to change is a regression; surface it as **critical**.
-- **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an environment — verify it exists rather than assume it.
+- **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Test/QA/Staging/Production for backend; `.env.development`/`.env.test`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an environment — verify it exists rather than assume it.
 
 ## Step 7: Detect Unwanted / Out-of-Scope Changes — and Confirm With the User