@chris1807/claude-kit 2.1.48 → 2.1.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.48",
+  "version": "2.1.50",
   "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/commands/create-work-item.md

@@ -195,6 +195,8 @@ For a **Bug**, **User Story**, or **Hot Fix**, every work item this command crea
 
 Estimate using the same rubric as `/quote`: the **modified Fibonacci scale** (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** in a codebase they know. Don't pad for ramp-up, routine architectural decisions, or stack familiarity — only for things a senior cannot shortcut: genuinely novel work, unresolved open questions, cross-team coordination, external dependencies. If the work looks larger than 21 points, recommend splitting the item instead of proposing a number.
 
+Repetition and boilerplate are assisted work — price them near the bottom of the range and size the item by its hardest distinct problem, not by how many files it touches. The full assisted / not-assisted breakdown lives in `/quote` Step 2; that file is the authority if the two ever drift.
+
 Present the estimate:
 
 ```
@@ -320,9 +322,27 @@ A description that is one long paragraph of plain prose is not acceptable — ev
 - **Key terms, values, and outcomes** in each sentence are wrapped in `**bold**` (renders as `<strong>...</strong>`). Bold the noun phrase that carries the claim, not the whole sentence.
 - **Code identifiers** — method names, class names, field names, file paths, route paths, JSON keys, env vars, commit hashes, IDs, literal values like `true` / `null` / numeric thresholds — are wrapped in `` `code spans` `` (renders as `<code>...</code>`).
 - **Lists** are used instead of comma-separated prose whenever the draft contains 2+ parallel items (steps, files, references, acceptance criteria).
-- **Section headings** (`### Description`, `### Acceptance Criteria`, etc.) are kept — they become `<h3>` and structure the rendered output.
+- **Section headings** *inside a field's own content* are kept — they become `<h3>` and structure the rendered output. The draft's **top-level** section headings are different: they are routing labels, not content, and the heading is dropped when its section becomes its own field (see below).
+
+Apply this pass to every section (Description, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Open Questions). Apply it equally to Bugs, Hot Fixes, and User Stories.
+
+### Split the draft into fields — acceptance criteria never go in the description
+
+The Step 3 draft is **one document for the user to read**, not the shape of one field. Before rendering, split it section by section and route each section to its own Azure DevOps field:
+
+| Draft section | Goes to | Notes |
+|---|---|---|
+| `### Description` | `System.Description` | Plus the mockup `<img>`, user-supplied images, `Production Impact` (Hot Fix), `Out of Scope`, and `Open Questions` |
+| `### Acceptance Criteria` | `Microsoft.VSTS.Common.AcceptanceCriteria` | **Never** also in the description |
+| `### Steps to Reproduce` | `Microsoft.VSTS.TCM.ReproSteps` (Bug / Hot Fix) | Falls back to the description only if the type doesn't expose the field |
+| `### Expected Behavior`, `### Actual Behavior` | `Microsoft.VSTS.TCM.ReproSteps` | Rendered beneath the repro steps |
+| `### Out of Scope`, `### Environment / Scope`, `### Open Questions` | `System.Description` | These keep their `<h3>` headings — they have no field of their own |
 
-Apply this pass to every section (Description, Acceptance Criteria, Steps to Reproduce, Expected/Actual Behavior, Environment/Scope, Open Questions). Apply it equally to Bugs and User Stories.
+**The rendered `System.Description` must not contain an "Acceptance Criteria" heading or its criteria** — not as `<h3>`, not as `<strong>`, not as a bolded line, not "for readability", not "so it reads as a complete document". Azure DevOps renders the AC field as its own section on the work item form, so a copy in the description gives the reader two lists that drift apart while leaving the real field empty. It also breaks estimation: an empty AC field is exactly what `/quote`, `/quote-backlog`, and `/plan-backlog` read to decide an item can't be sized, so criteria in the wrong field make a fully-specified story look unestimable and bounce it back to its creator.
+
+**Drop the section's own heading when it becomes a field.** `Microsoft.VSTS.Common.AcceptanceCriteria` holds the criteria list alone — an `<ol>` or `<ul>`, not `<h3>Acceptance Criteria</h3>` followed by the list. Same for `ReproSteps`. The field label is already on the form.
+
+**Always write the AC field explicitly — never leave the placeholder.** Some process templates seed a new item's `Microsoft.VSTS.Common.AcceptanceCriteria` with tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. That is a **placeholder, not content**, and it reads as non-empty to every downstream sweep — an item carrying it looks like it has acceptance criteria when it has none. Include the field in the create call for every Bug, Hot Fix, and User Story; writing it is what clears the placeholder.
 
 ### Call the create API
 
@@ -333,7 +353,7 @@ Call `mcp__azure-devops__wit_create_work_item` with:
 - **title**: the approved title (with prefix)
 - **fields**: a JSON Patch document setting:
   - `System.Description` — the rendered HTML description (with embedded mockup `<img>` and any user-supplied images)
-  - `Microsoft.VSTS.Common.AcceptanceCriteria` — the rendered HTML acceptance criteria block
+  - `Microsoft.VSTS.Common.AcceptanceCriteria` — the rendered criteria list and **only** the criteria (no `<h3>Acceptance Criteria</h3>` wrapper, and no copy of it in `System.Description`). Always include this field for a Bug, Hot Fix, or User Story — writing it is what clears the process template's placeholder tip
   - `Microsoft.VSTS.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped, and **always** for a Feature)
   - For Features:
     - Render `Business Value`, `Scope`, `Out of Scope`, and `Success Criteria` into the description. Put `Success Criteria` in `Microsoft.VSTS.Common.AcceptanceCriteria` **only if** the process template exposes that field on Feature — if the create call rejects it, fold the block into the description and retry rather than dropping it.
@@ -392,6 +412,13 @@ If a story fails to create or link, report which ones succeeded and which didn't
 
 ## Step 10: Confirm
 
+**Read the item back first.** Fetch it with `mcp__azure-devops__wit_work_item` (`action: get`, fields `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria`) and check two things:
+
+1. The criteria are in `Microsoft.VSTS.Common.AcceptanceCriteria` — not the placeholder tip, not empty.
+2. `System.Description` contains no "Acceptance Criteria" heading and none of the criteria.
+
+If either check fails the write didn't take — fix it with `wit_update_work_item` before reporting success. Don't report a created item you haven't read back.
+
 After creation, report:
 
 ```
@@ -402,6 +429,7 @@ Created AB#{id}: {title}
   State: {Dev Ready | New}
   URL: {work item URL}
   Mockup attached: {yes / no}
+  Acceptance criteria: {n} criteria in the AC field (verified — none in the description)
   Open questions: {count}
 {Features only:}
   Child stories: {n created | none — add them later with /plan-backlog}

package/templates/commands/edit-work-item.md

@@ -44,6 +44,11 @@ Present what exists today, so the user is editing against reality and not memory
 {end for Bugs}
 ```
 
+**Two things read as "this item has acceptance criteria" when it doesn't.** Check for both before showing the item, and say plainly which one you found:
+
+- **The field holds the process template's placeholder** — tip text like `💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`. Treat that as **empty** and display it as `(none — placeholder text only)`.
+- **The criteria are in `System.Description`** under an "Acceptance Criteria" heading, with the real field empty or placeholder-filled. This is the misfiled case. Display the criteria where they actually live, flag it, and offer the repair described in Step 7 — moving them costs the user nothing and unblocks estimation.
+
 For a **Feature**, append the current wave layout:
 
 ```
@@ -195,6 +200,15 @@ Default the comment question to **yes** for any item past `New`, and **no** for
 
 Render every Markdown section to HTML first — Azure DevOps description and acceptance criteria fields do not render Markdown. Use the conversion table and the **emphasis and code spans** rules from `/create-work-item` Step 8: bold the noun phrase carrying each claim, wrap identifiers in `<code>`, use lists for 2+ parallel items, keep `### Headings` as `<h3>`. Preserve existing `<img>` tags exactly.
 
+**Route each section to its own field**, per the field-routing table in `/create-work-item` Step 8. The rule that matters most here: **acceptance criteria go in `Microsoft.VSTS.Common.AcceptanceCriteria`, never in `System.Description`.** When you rewrite AC, write the criteria list alone into that field — no `<h3>Acceptance Criteria</h3>` wrapper — and make sure the description you write back carries no copy of them. Editing an item is the moment this gets silently undone: it is easy to render the whole reviewed document into the description and leave the AC field as it was.
+
+**Repair misfiled criteria when you find them.** If Step 2 found the criteria living in the description (or the AC field holding only placeholder tip text), fix it as part of this edit even when the user didn't ask — it is the same content, moved to the field Azure DevOps and every kit sweep actually read:
+
+- Write the criteria into `Microsoft.VSTS.Common.AcceptanceCriteria`, overwriting the placeholder.
+- Strip the "Acceptance Criteria" heading and its list out of `System.Description` in the same call, so the two fields don't both hold a copy.
+- Say so in the change set and in the Step 8 confirmation: `Acceptance criteria: moved from Description → AC field (3 criteria)`. Never move criteria silently; the user needs to see that the description shrank.
+- This is a **move, not a rewrite** — the criteria text is unchanged unless the user separately approved a reword.
+
 Apply writes in this order, so a failure partway through leaves the most useful state behind:
 
 1. **Update the parent item** — one `mcp__azure-devops__wit_update_work_item` call with every changed field. Never include `System.State` for a Feature.

package/templates/commands/implement.md

@@ -194,9 +194,9 @@ Propose the hours from the parent's Story Points (this mirrors `/plan-backlog` S
 | 13 | 48 hrs  |
 | 21 | 75 hrs  |
 
-Calibrated for a **senior developer** at ~6 productive hours per day — the discount is already in the numbers, so don't apply a second one. Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
+Calibrated for a **senior developer working with Claude assistance** at ~6 productive hours per day — both discounts are already in the numbers, so don't apply a second one. Boilerplate, tests for specified behavior, and mechanical refactors are assisted work; the hours that remain are the human ones (novel decisions, verification, review, UAT). Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
 
-If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — using the same senior calibration. Say which basis you used.
+If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — using the same senior-with-Claude calibration. Say which basis you used.
 
 Show the proposal and **wait for the user**:
 

package/templates/commands/plan-backlog.md

@@ -108,21 +108,23 @@ Fetch the work item again (Description and Acceptance Criteria fields) if not al
 
 ### 5b. Map Story Points → total hour budget
 
-> **Assume a senior developer is the implementer.** The hour budget below already discounts for senior-level speed — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast. Do not add a separate "experience" discount on top of these numbers.
+> **Assume a senior developer working with Claude assistance is the implementer.** The hour budget below already discounts for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
+>
+> The hours that survive the assist are the human ones: understanding the requirement, the genuinely novel decisions, verification, review turnaround, and UAT. If a budget looks large only because the story touches many files, it's too large.
 
-Use this mapping (calibrated for a senior developer at ~6 productive hours per day):
+Use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
 | Points | Hour budget | Notes |
 |--------|-------------|-------|
 | 1  |  3 hrs  | trivial change |
 | 2  |  6 hrs  | small, one-layer change |
 | 3  | 10 hrs  | one feature slice, modest tests |
-| 5  | 16 hrs  | cross-layer or new component (routine for a senior) |
-| 8  | 28 hrs  | multi-area, real unknowns even for a senior |
+| 5  | 16 hrs  | cross-layer or new component (routine for an assisted senior) |
+| 8  | 28 hrs  | multi-area, real unknowns the assist doesn’t remove |
 | 13 | 48 hrs  | large feature — should probably be split |
 | 21 | 75 hrs  | very large — almost certainly split |
 
-If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the story has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where seniority doesn't help.
+If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the story has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where neither seniority nor the assist helps.
 
 ### 5c. Draft the single task
 

package/templates/commands/plan-sprint.md

@@ -125,21 +125,23 @@ Fetch the work item again (Description and Acceptance Criteria fields — Repro
 
 ### 6b. Derive the hour budget
 
-> **Assume a senior developer is the implementer.** The hour budget below already discounts for senior-level speed — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast. Do not add a separate "experience" discount on top of these numbers.
+> **Assume a senior developer working with Claude assistance is the implementer.** The hour budget below already discounts for both — no ramp-up time, no time spent learning the stack, routine cross-layer work is fast, and boilerplate/tests/mechanical refactors are assisted. Do not add a separate "experience" or "Claude" discount on top of these numbers.
+>
+> The hours that survive the assist are the human ones: understanding the requirement, the genuinely novel decisions, verification, review turnaround, and UAT. If a budget looks large only because the story touches many files, it's too large.
 
-**If the item has Story Points**, use this mapping (calibrated for a senior developer at ~6 productive hours per day):
+**If the item has Story Points**, use this mapping (calibrated for a senior developer with Claude assistance, at ~6 productive hours per day):
 
 | Points | Hour budget | Notes |
 |--------|-------------|-------|
 | 1  |  3 hrs  | trivial change |
 | 2  |  6 hrs  | small, one-layer change |
 | 3  | 10 hrs  | one feature slice, modest tests |
-| 5  | 16 hrs  | cross-layer or new component (routine for a senior) |
-| 8  | 28 hrs  | multi-area, real unknowns even for a senior |
+| 5  | 16 hrs  | cross-layer or new component (routine for an assisted senior) |
+| 8  | 28 hrs  | multi-area, real unknowns the assist doesn’t remove |
 | 13 | 48 hrs  | large feature — should probably be split |
 | 21 | 75 hrs  | very large — almost certainly split |
 
-If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the item has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where seniority doesn't help.
+If the points value isn't on the Fibonacci scale, round to the nearest entry above. If the item has tags like `spike`, `research`, or `unknown-stack`, add 20–30% on top — those are the cases where neither seniority nor the assist helps.
 
 **If the item has no Story Points**, estimate the hours directly from the description, acceptance criteria, and repro steps — judge which row of the table the work most resembles and use that hour budget. Mark the proposal `(no points — estimated from description)` and suggest `/quote AB#{id}` in the final summary. Do **not** set Story Points on the item — that's the user's call.
 

package/templates/commands/quote-backlog.md

@@ -145,7 +145,7 @@ Score the item against this checklist:
 |-------|---------------------------|
 | **Title prefix** | Follows the project's `PREFIX - Title` convention (e.g. `COM -`, `PAY -`) |
 | **Description** | States what is being built and why — not just a one-line restatement of the title |
-| **Acceptance criteria** | Present, testable, unambiguous. Each AC could become a UAT step. Record whether the field is **empty** or merely **weak** — that distinction decides whether AC can be rewritten (3g) or must go back to the creator (3f) |
+| **Acceptance criteria** | Present, testable, unambiguous. Each AC could become a UAT step. Record whether the field is **empty** or merely **weak** — that distinction decides whether AC can be rewritten (3g) or must go back to the creator (3f). Two traps: the process template's **placeholder tip text** counts as **empty**, and criteria are sometimes **misfiled into `System.Description`** with the AC field left empty — check the description before declaring AC missing, and say where they actually are in the comment |
 | **Design artifacts** (User Story) | For UI work: a mockup, screenshot, or design link is attached or referenced (the story is Design Approved — the design should be findable) |
 | **Repro steps** (Bug) | The steps to reproduce, the expected result, and the actual result are all present. A bug swept at `New` has had no design pass, so this is the row that decides whether it's estimable — **a bug with no repro steps is a blocking gap** |
 | **Scope** | Small enough to point (would land at ≤ 21); no hidden second feature buried in the AC |
@@ -182,7 +182,11 @@ This is read-only reconnaissance. Skip it for non-technical items or when the co
 
 Use the **modified Fibonacci scale**: `1, 2, 3, 5, 8, 13, 21`. Anything larger than 21 is flagged as "needs to be split" rather than given a number.
 
-> **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack — that's already priced into the rubric. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies. Do not apply a second seniority discount on top of the rubric.
+> **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack — that's already priced into the rubric. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies. Do not apply a second seniority discount, or a second Claude-assistance discount, on top of the rubric.
+
+**Assisted work — price near the bottom of the range:** boilerplate and scaffolding, tests for already-specified behavior, mechanical refactors, applying a known pattern across many files, CRUD/forms/screens that mirror something already in the repo. Repetition is cheap — size the item by its hardest distinct problem, not by how many files it touches.
+
+**Not assisted — never discount:** thin or missing AC, novel design with no precedent, third-party integrations, cross-team dependencies, production data migrations, security/compliance review, hand-verified infra or pipeline work, and human wall-time for review/UAT/deploy gates. These are what justify 8 points and above.
 
 | Points | Looks like |
 |--------|-----------|
@@ -316,7 +320,7 @@ Only for approved items, in batch order:
 4. **Post the comment** (items with an approved draft): add it with `mcp__azure-devops__wit_add_work_item_comment` (or the server's work-item comment tool). Use the mention syntax the server supports so the creator is notified; otherwise lead with their display name as drafted. For a story that just moved to Design Review, the comment must say so — the creator needs to know why it left their Design Approved column. For a bug that just got the `needs-info` tag, the comment must say that too, and say that removing the tag re-queues it.
 5. **Apply the rewrite** (only items the user marked `apply rewrite N`): update `System.Description` (and `System.Title` if the rewrite included one) via `wit_update_work_item`, and adjust the comment to say the rewrite was applied ("rewrote the description/AC per the above — please review") rather than suggesting it. Never apply a rewrite the user didn't explicitly mark.
 
-   **Guard on `Microsoft.VSTS.Common.AcceptanceCriteria`:** write it only if the item's AC field was **non-empty** when fetched in 3a. Re-check the fetched value at write time — if it was blank, drop AC from the update payload and write the other fields. Blank means no criteria at all: empty string, whitespace, or an empty HTML shell like `<div></div>` or `<p><br></p>`.
+   **Guard on `Microsoft.VSTS.Common.AcceptanceCriteria`:** write it only if the item's AC field was **non-empty** when fetched in 3a. Re-check the fetched value at write time — if it was blank, drop AC from the update payload and write the other fields. Blank means no criteria at all: empty string, whitespace, an empty HTML shell like `<div></div>` or `<p><br></p>`, **or the process template's placeholder tip text** (`💡 Tip: Add "@serena rewrite" to Description for AI suggestions  Define acceptance criteria: - [ ]  - [ ]  - [ ]`). The placeholder is the one that bites — it is a stored, non-empty field value that means the exact opposite of what its length suggests.
 
 If a write fails, report the failure and ask whether to continue with the remaining items or stop.
 

package/templates/commands/quote.md

@@ -16,6 +16,29 @@ Use the **modified Fibonacci scale** for story points: `1, 2, 3, 5, 8, 13, 21`.
 
 > **Assume a senior developer working with Claude assistance is the implementer.** Don't pad for ramp-up, routine architectural decisions, or familiarity with the stack. A senior is expected to read the codebase, find existing patterns, and resolve ordinary unknowns without help — that effort is already priced into the rubric below. Only pad for things a senior *cannot* shortcut: genuinely novel work, missing AC, cross-team coordination, or external dependencies.
 
+**Claude assistance is part of the baseline, so price these near the bottom of their range** — the rubric already assumes them, don't discount a second time:
+
+- Boilerplate and scaffolding — DTOs, mappers, interfaces, request/response models, registrations.
+- Writing tests for behavior that's already specified.
+- Mechanical refactors, renames, and applying a known pattern across many files.
+- CRUD endpoints, forms, tables, and screens that mirror something already in the repo.
+- Migrations and scripts with an obvious shape.
+
+**Volume of similar code is cheap.** A story whose size comes mostly from repetition — six more fields, four more columns, another slice of an existing pattern — should not earn points for its file count. Size it by the hardest distinct problem in it, not by how much typing it implies.
+
+**Claude assistance does not compress these — never discount them:**
+
+- Ambiguous, thin, or missing acceptance criteria (see the *not estimable* rule below).
+- Genuinely novel design decisions with no precedent in the codebase.
+- Third-party integrations, external APIs, and anything gated on another system's behavior.
+- Cross-team coordination, sign-off, or a dependency on someone else's work landing first.
+- Data migrations against production data, and anything needing a rollback plan.
+- Security, compliance, or privacy review.
+- Infrastructure, pipeline, and environment work that has to be verified by hand.
+- Human wall-time: code review turnaround, UAT, and deploy gates.
+
+These are what dominate an estimate at 8 points and above. If a big number is driven purely by code volume rather than by items on this list, the estimate is probably too high.
+
 Rough sizing rubric (calibrated for a senior developer, assisted by Claude, working in a codebase they know):
 
 | Points | Looks like |
@@ -30,7 +53,9 @@ Rough sizing rubric (calibrated for a senior developer, assisted by Claude, work
 
 Adjust upward for: unclear acceptance criteria, missing UX, data migrations, cross-team coordination, security/compliance review, or anything tagged `spike`/`research`.
 
-Adjust downward for: pure config changes, mechanical refactors with good test coverage, work that mirrors an existing implementation, or anything where the senior will recognize the pattern immediately.
+Adjust downward for: pure config changes, mechanical refactors with good test coverage, work that mirrors an existing implementation, repetition of an established pattern, or anything where the senior will recognize the pattern immediately.
+
+State the assist in the reasoning when it moved the number — e.g. "5 rather than 8: the three new endpoints follow `PaymentsController` exactly, so the volume is assisted work; the only real unknown is the reconciliation rule." That makes the estimate reviewable instead of asserted.
 
 If the item has child items, size each child as well and present the parent's total as the sum (rounded to the nearest Fibonacci number).