@chris1807/claude-kit 2.2.0 → 2.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "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

@@ -73,7 +73,7 @@ When asked to promote code from one environment to the next:
 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
+4. Once the user confirms the merge, advance the carried User Stories / Bugs / Hot Fixes to the environment's state (`test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`; **`dev` sets no state** — items stay at `Code Review` and the developer sets `Ready for Testing` by hand) — never backward, never a Feature or Task. The `/promote` command documents the full gate-check and state rules
 
 ### Deploy Release
 

package/templates/commands/cherry-pick.md

@@ -11,12 +11,12 @@ Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** t
 | 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` |
+| `dev` | Dev | `Code Review` (merged to `main`) | *(no change — stays `Code Review`)* |
 | `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**.
+`Ready for Testing`, `Ready for Staging` and `Ready to Deploy` are set by the developer, QA, and stakeholders — **never by this command**. A `main → dev` deploy therefore sets **no state**: items stay at `Code Review` until the developer has checked the change on Dev and moves it to `Ready for Testing` by hand.
 
 ## Step 1: Read the Work Items and Gate-Check Them
 
@@ -327,7 +327,8 @@ This step runs **by itself** the moment the pipeline reports success — do not
 
 For every cherry-picked work item of type **User Story**, **Bug**, or **Hot Fix**, one `wit_work_item_write` update per item setting both fields:
 
-1. `System.State` → the target's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`).
+1. `System.State` → the target's state (`Testing` / `Staging` / `Deployed`).
+   - **A cherry-pick to `dev` sets no state.** Items stay at `Code Review`; the developer sets `Ready for Testing` by hand. Update the assignee only.
    - **Never move backward** — an item already past the target state keeps it; note it.
    - 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.

package/templates/commands/deploy-release.md

@@ -11,12 +11,12 @@ Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** t
 | Branch | Environment | Gate — items should already be in… | State set after the PR merges |
 |---|---|---|---|
 | `main` | — (compare branch) | — | — |
-| `dev` | Dev | `Code Review` (merged to `main`) | `Ready for Testing` |
+| `dev` | Dev | `Code Review` (merged to `main`) | *(no change — stays `Code Review`)* |
 | `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**. If the project's table has different environments, confirm the type's states with `mcp__azure-devops__wit_work_item` (`action: get_type`) and map them the same way: a "Ready for X" gate → an "in X" state.
+`Ready for Testing`, `Ready for Staging` and `Ready to Deploy` are set by the developer, QA, and stakeholders — **never by this command**. A `main → dev` deploy therefore sets **no state**: items stay at `Code Review` until the developer has checked the change on Dev and moves it to `Ready for Testing` by hand. If the project's table has different environments, confirm the type's states with `mcp__azure-devops__wit_work_item` (`action: get_type`) and map them the same way: a "Ready for X" gate → an "in X" state.
 
 ## Step 1: Read the Release
 
@@ -387,7 +387,8 @@ This step runs **by itself** the moment the pipeline reports success — do not
 
 For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, one `wit_work_item_write` update per item (or the batch variant) setting both fields:
 
-1. `System.State` → the target environment's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`).
+1. `System.State` → the target environment's state (`Testing` / `Staging` / `Deployed`).
+   - **A deploy to `dev` sets no state.** Items stay at `Code Review`; the developer sets `Ready for Testing` by hand. Update the assignee only.
    - **Never move backward.** An item already past the target state (e.g. `Deployed` when deploying to `staging`) keeps its state; note it.
    - Items skipped in Step 6 (conflict) or dropped in Step 3 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 with the rest. Don't silently swallow it.

package/templates/commands/implement.md

@@ -82,6 +82,35 @@ Reply with your Ultracode choice (and any added context). Say **ready** once you
 
 1. **Explore** the codebase to map relevant files
 2. **Plan** the implementation approach
+3. **Re-analyze the plan as an architect** — the pass below, before the user sees anything
+
+### Architect Review (runs before the plan is presented)
+
+The draft plan is a first answer, not the answer. Re-read it cold — as an experienced architect who did not write it and who cares what this codebase looks like a year from now. This happens on **every** plan, before the user sees anything.
+
+> **Ultracode (if opted in):** run this as a separate `Workflow` agent so the review is actually independent. Give it the work item, the acceptance criteria, and the draft plan — but **not** your reasoning for the plan — and have it read the affected files itself. A reviewer who has seen the author's justification anchors to it. Without ultracode, run the pass in the main loop, but answer each question from the code, not from the plan's own prose.
+
+Each question below is about a cost that is cheap now and expensive once the code exists:
+
+| # | Question | What a bad answer looks like |
+|---|----------|------------------------------|
+| 1 | **Does this already exist?** A service, hook, component, or extension method that already does this, or is one call away. | A new `PaymentExportService` beside the `ExportService` that already handles three other exports |
+| 2 | **Is each piece in the right layer?** Domain / Application / Infrastructure / API boundaries hold — no business rules in a controller, no Mongo or EF types in Domain, no HTTP concepts below API. | An `IMongoCollection<T>` parameter on a Domain method |
+| 3 | **What is the simplest plan that still meets every AC?** State it, then adopt it or say in one line why the heavier one is needed. | An interface with exactly one implementation, added "for testability" |
+| 4 | **What else touches the files being modified?** Name the callers. A change to a shared contract, DTO, or response shape is a breaking change until proven otherwise. | Editing a shared DTO with no note about its other consumers |
+| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change. | A non-nullable field added with no default and no backfill |
+| 6 | **How does it fail?** Partial failure, concurrent callers, a retried request. Is the operation idempotent, and does it need to be? | A multi-step write with no story for a crash between steps |
+| 7 | **Does it hold at real data volume?** Queries inside loops, unbounded result sets, a missing index, a list endpoint with no paging. | A `foreach` over accounts issuing one query each |
+| 8 | **Is it safe?** Authorization on every new endpoint, and **no sensitive field** (TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, any `Encrypted*`) read, logged, returned, or projected — see the sensitive-data rule in CLAUDE.md. | A new endpoint returning a whole entity because it was convenient |
+| 9 | **Can it be tested without heavy mocking?** A test needing five mocks is telling you the seams are in the wrong place. | A test plan that starts "mock the repository, the clock, and the HTTP client" |
+| 10 | **Can it be undone?** `/rollback` reverts commits; it does not un-migrate data or un-send an email. Flag anything one-way. | A destructive migration with no reverse path |
+
+**Two hard limits on this pass:**
+
+- **It may not grow the scope.** It exists to simplify, correct, and de-risk — not to add caching, abstraction layers, or features nobody asked for. Anything outside the acceptance criteria goes in *Risks / Considerations*, or becomes a separate work item you mention. It is never folded into the plan silently.
+- **It may not invent findings.** If the plan survives every question, say so in one line. A manufactured concern to look thorough spends the user's attention at the one gate that is supposed to protect it.
+
+Apply what the pass finds, then report it in the plan as the **Architect Review** section below. The pass is never skipped; only its output scales — on a one-file config change most rows answer themselves and the report is two lines.
 
 Present the plan to the user:
 
@@ -115,6 +144,10 @@ List every test file you will add or modify and the scenarios each covers (happy
 ### Risks / Considerations
 - {any potential issues or trade-offs}
 
+### Architect Review
+{One line per change the review made: what the draft said → what it says now → why.}
+{If nothing changed: "Reviewed against every question — no changes." plus the one that came closest to a finding and why it is fine.}
+
 Approve this plan? (yes / no / suggest changes)
 ```
 
@@ -362,7 +395,7 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
 
    If the project's process template does not have a `Code Review` state (the update call returns an invalid-state error), fall back in this order: `Resolved` → `In Review` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
 
-> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review` until it is promoted: merging this PR into `main` deploys nothing, and the item advances to `Ready for Testing` → `Testing` → `Staging` → `Deployed` as `/promote` and `/deploy-release` carry it through `dev → test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
+> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review`: merging this PR into `main` deploys nothing, and promoting to `dev` deploys the code but **leaves the state alone** — the developer moves it to `Ready for Testing` once they have checked it on Dev. From there `/promote` and `/deploy-release` advance it to `Testing` → `Staging` → `Deployed` across `test → staging → prod` (see **Work Item States ↔ Environments** in CLAUDE.md).
 
 ### Closing Related Tasks
 
@@ -482,7 +515,7 @@ Capture `BASE_BRANCH` and create `feature/AB#{feature-id}-{sanitized-title}` per
 
 For each wave in ascending order:
 
-1. **Explore & plan** each story in the wave (Step 3 rules; Ultracode fan-outs apply per story if opted in). Present **one combined plan** with a section per story — each section covering approach, files, unit tests, and agents — plus a note on any files touched by more than one story in the wave (a conflict warning). **One approval gate per wave**; wait for the user.
+1. **Explore & plan** each story in the wave (Step 3 rules; Ultracode fan-outs apply per story if opted in). Present **one combined plan** with a section per story — each section covering approach, files, unit tests, and agents — plus a note on any files touched by more than one story in the wave (a conflict warning). The **Architect Review** runs on the combined wave plan before you present it, and the shared-file conflicts are exactly what question 4 is for. **One approval gate per wave**; wait for the user.
 2. **Implement:**
    - **Move every story in the wave to `Active`** first (same rules and fallbacks as "Move the Work Item to Active" in Step 4). The Feature's state is never changed.
    - **Ensure each story in the wave has an open child Task** (Step 4's "Ensure an Open Child Task Exists" rules, applied per story — Tasks hang off the stories, never off the Feature). Batch the proposals into **one** table covering the whole wave and take a single approval, so parallel agents never wait on a prompt:

package/templates/commands/promote.md

@@ -11,12 +11,12 @@ Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** t
 | Branch | Environment | Gate — items should already be in… | State set after the PR merges |
 |---|---|---|---|
 | `main` | — (compare branch) | — | — |
-| `dev` | Dev | `Code Review` (merged to `main`) | `Ready for Testing` |
+| `dev` | Dev | `Code Review` (merged to `main`) | *(no change — stays `Code Review`)* |
 | `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**.
+`Ready for Testing`, `Ready for Staging` and `Ready to Deploy` are set by the developer, QA, and stakeholders — **never by this command**. A `main → dev` deploy therefore sets **no state**: items stay at `Code Review` until the developer has checked the change on Dev and moves it to `Ready for Testing` by hand.
 
 ## Step 1: Determine Source and Target
 
@@ -321,7 +321,8 @@ This step runs **by itself** the moment the pipeline reports success — do not
 
 For every carried work item of type **User Story**, **Bug**, or **Hot Fix**, one `wit_work_item_write` update per item setting both fields:
 
-1. `System.State` → the target's state (`Ready for Testing` / `Testing` / `Staging` / `Deployed`).
+1. `System.State` → the target's state (`Testing` / `Staging` / `Deployed`).
+   - **`main → dev` sets no state.** Items stay at `Code Review` — the developer sets `Ready for Testing` by hand once they have checked it on Dev. Update the assignee only, and show the state as `Code Review (unchanged — developer sets Ready for Testing)`.
    - **Never move backward** — an item already past the target state keeps it; note it.
    - An invalid-state error means this project's template differs — confirm with `get_type`, report the item, continue with the rest. Don't silently swallow it.
 2. `System.AssignedTo` → the person approved for that item's prefix group. Pass the identity's `uniqueName` / email, not the display name; if the update rejects it, resolve with `core_get_identity_ids` and retry once. A `Leave the current assignee alone` group keeps its assignee — never clear a field the user didn't ask you to clear.
@@ -339,7 +340,7 @@ Report both fields, so a wrong assignment is easy to put back:
 | AB#1240 | Ready for Staging → Staging | Chris Waters → Pat Ruiz |
 | AB#1250 | Deployed (unchanged — already ahead) | unchanged |
 
-Next: {the human step — "QA tests on Test and sets Ready for Staging" / "stakeholders verify on Staging and set Ready to Deploy" / "verify in production, then Close"}.
+Next: {the human step — "the developer checks it on Dev and sets Ready for Testing" / "QA tests on Test and sets Ready for Staging" / "stakeholders verify on Staging and set Ready to Deploy" / "verify in production, then Close"}.
 ```
 
 If the user said `stop watching`, or an update fails, leave the rest alone, say exactly which items were and were not updated, and note that `/track` will flag the lag later.

package/templates/commands/rework.md

@@ -107,6 +107,37 @@ Reply with your Ultracode choice (and any reclassifications or context). Say **r
 
 1. **Explore** the codebase to map relevant files — focus on files changed in the last PR and any new areas needed
 2. **Plan** the rework approach
+3. **Re-analyze the plan as an architect** — the pass below, before the user sees anything
+
+### Architect Review (runs before the plan is presented)
+
+The draft plan is a first answer, not the answer. Re-read it cold — as an experienced architect who did not write it and who cares what this codebase looks like a year from now. This happens on **every** rework plan, before the user sees anything.
+
+> **Ultracode:** run this as a separate `Workflow` agent so the review is actually independent. Give it the work item, the acceptance criteria, the rework feedback, and the draft plan — but **not** your reasoning for the plan — and have it read the affected files itself. A reviewer who has seen the author's justification anchors to it.
+
+Each question below is about a cost that is cheap now and expensive once the code exists:
+
+| # | Question | What a bad answer looks like |
+|---|----------|------------------------------|
+| 1 | **Does this already exist?** A service, hook, component, or extension method that already does this, or is one call away. | A new `PaymentExportService` beside the `ExportService` that already handles three other exports |
+| 2 | **Is each piece in the right layer?** Domain / Application / Infrastructure / API boundaries hold — no business rules in a controller, no Mongo or EF types in Domain, no HTTP concepts below API. | An `IMongoCollection<T>` parameter on a Domain method |
+| 3 | **What is the simplest plan that still meets every AC?** State it, then adopt it or say in one line why the heavier one is needed. | An interface with exactly one implementation, added "for testability" |
+| 4 | **What else touches the files being modified?** Name the callers. A change to a shared contract, DTO, or response shape is a breaking change until proven otherwise. | Editing a shared DTO with no note about its other consumers |
+| 5 | **What happens to data that already exists?** New required fields, schema changes, and backfills each need an answer for rows written before this change. | A non-nullable field added with no default and no backfill |
+| 6 | **How does it fail?** Partial failure, concurrent callers, a retried request. Is the operation idempotent, and does it need to be? | A multi-step write with no story for a crash between steps |
+| 7 | **Does it hold at real data volume?** Queries inside loops, unbounded result sets, a missing index, a list endpoint with no paging. | A `foreach` over accounts issuing one query each |
+| 8 | **Is it safe?** Authorization on every new endpoint, and **no sensitive field** (TIN, SSN, EIN, TaxId, BankAccountNumber, RoutingNumber, any `Encrypted*`) read, logged, returned, or projected — see the sensitive-data rule in CLAUDE.md. | A new endpoint returning a whole entity because it was convenient |
+| 9 | **Can it be tested without heavy mocking?** A test needing five mocks is telling you the seams are in the wrong place. | A test plan that starts "mock the repository, the clock, and the HTTP client" |
+| 10 | **Can it be undone?** `/rollback` reverts commits; it does not un-migrate data or un-send an email. Flag anything one-way. | A destructive migration with no reverse path |
+| 11 | **Cause or symptom?** Rework feedback reports an instance. Does this plan fix why it happened, or only the case that was reported? | Special-casing the one date the tester tried |
+| 12 | **What did the original PR get right that this could undo?** It passed review once. Name what this change puts back at risk, and the regression test that pins it. | A rewrite of a method whose edge cases were the point of the original review |
+
+**Two hard limits on this pass:**
+
+- **It may not grow the scope.** It exists to simplify, correct, and de-risk — not to add caching, abstraction layers, or features nobody asked for. Anything outside the acceptance criteria goes in *Risks / Considerations*, or becomes a separate work item you mention. It is never folded into the plan silently.
+- **It may not invent findings.** If the plan survives every question, say so in one line. A manufactured concern to look thorough spends the user's attention at the one gate that is supposed to protect it.
+
+Apply what the pass finds, then report it in the plan as the **Architect Review** section below. The pass is never skipped; only its output scales — on a one-file config change most rows answer themselves and the report is two lines.
 
 Present the plan to the user:
 
@@ -151,6 +182,10 @@ If any row reads "⚠ Not yet covered," fix the plan before presenting it — do
 ### Risks / Considerations
 - {any potential issues or trade-offs}
 
+### Architect Review
+{One line per change the review made: what the draft said → what it says now → why.}
+{If nothing changed: "Reviewed against every question — no changes." plus the one that came closest to a finding and why it is fine.}
+
 Approve this plan? (yes / no / suggest changes)
 ```
 

package/templates/commands/track.md

@@ -16,12 +16,12 @@ Work item states track environments. Use this to spot **state lag** — an item
 | Commits are on… | State should be at least… |
 |---|---|
 | `main` | `Code Review` |
-| `dev` | `Ready for Testing` |
+| `dev` | `Code Review` |
 | `test` | `Testing` |
 | `staging` | `Staging` |
 | `prod` | `Deployed` |
 
-`Ready for Staging` and `Ready to Deploy` are human sign-offs and are never "lag". Only User Stories, Bugs, and Hot Fixes are checked — Features and Tasks have no environment state.
+`Ready for Testing`, `Ready for Staging` and `Ready to Deploy` are human sign-offs and are never "lag" — an item sitting at `Code Review` with commits on `dev` is waiting on the developer, not behind. Only User Stories, Bugs, and Hot Fixes are checked — Features and Tasks have no environment state.
 
 ## If Release (e.g., `/track release 24`):
 

package/templates/commands/where.md

@@ -88,6 +88,6 @@ Open PRs:
 - PR #<n> → <target branch> (<status>)
 ```
 
-Finally, compare the work item's state with its furthest environment (`dev` → `Ready for Testing`, `test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`). If the state lags — e.g. commits on `staging` but the item is still `Testing` — add one line: `⚠ State lags environment: Testing, expected at least Staging — /track AB#<id> can catch it up.`
+Finally, compare the work item's state with its furthest environment (`dev` → `Code Review`, `test` → `Testing`, `staging` → `Staging`, `prod` → `Deployed`). If the state lags — e.g. commits on `staging` but the item is still `Testing` — add one line: `⚠ State lags environment: Testing, expected at least Staging — /track AB#<id> can catch it up.`
 
 That's it — read-only. Do not modify branches, push, create PRs, or change states.

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -161,19 +161,19 @@ feature/AB#1234-...  ──PR──▸  main  ──PR──▸  dev  ──PR
 
 #### Work Item States ↔ Environments
 
-Every environment in the chain has a work item state, so the board shows where each story physically is. The **"Ready for …" states are human gates** — QA or stakeholders set them when something passes; the slash commands never do. The **environment states** (`Testing`, `Staging`, `Deployed`) are set by the promotion commands once the PR into that branch has merged and its CD pipeline has come back green.
+Every environment in the chain has a work item state, so the board shows where each story physically is. The **"Ready for …" states are human gates** — the developer, QA, or stakeholders set them when something passes; the slash commands never do. The **environment states** (`Testing`, `Staging`, `Deployed`) are set by the promotion commands once the PR into that branch has merged and its CD pipeline has come back green.
 
 | Branch | Environment | Gate — items should already be in… | Set once the PR into this branch merges |
 |---|---|---|---|
 | `main` | — | `Code Review` (the `/implement` PR is open) | *(no change — nothing deployed)* |
-| `dev` | Dev | `Code Review` (merged to `main`) | `Ready for Testing` |
+| `dev` | Dev | `Code Review` (merged to `main`) | *(no change — stays `Code Review`)* |
 | `test` | Test | `Ready for Testing` | `Testing` |
 | `staging` | Staging | `Ready for Staging` | `Staging` |
 | `prod` | Production | `Ready to Deploy` | `Deployed` |
 
 `/qa` is the exception that proves the rule: it tests a work item in a browser and posts a pass/fail comment, but it **never writes a state** — not even `Ready for Testing`.
 
-Human-only transitions — no slash command ever makes these: `Testing → Ready for Staging` (QA sign-off), `Staging → Ready to Deploy` (stakeholder / UAT sign-off), `Deployed → Closed` (verified in production).
+Human-only transitions — no slash command ever makes these: `Code Review → Ready for Testing` (the developer confirms the change on Dev), `Testing → Ready for Staging` (QA sign-off), `Staging → Ready to Deploy` (stakeholder / UAT sign-off), `Deployed → Closed` (verified in production).
 
 How the commands use this table: