@chris1807/claude-kit 2.1.41 → 2.1.43

package/README.md

@@ -649,7 +649,7 @@ Claude reviews for:
 | `/status` | `/status release 24` | Check status of a release, pipeline, work item, or 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 Design Approved items without points → review completeness, check for duplicates, propose points + creator comments (10 at a time, approval-gated) |
+| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated) |
 | `/quote` | `/quote AB#1234` | Estimate a work item in story points (senior-calibrated Fibonacci rubric) |
 | `/explain` | `/explain AB#1234` | Summarize and explain a work item in plain language |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged feature/work branches |

package/package.json

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

@@ -142,9 +142,32 @@ After presenting the draft, ask:
 Approve this draft? (yes / suggest changes / cancel)
 ```
 
-**Wait for the user.** If they suggest changes, revise the draft and present it again — repeat until they approve or cancel. Do NOT proceed to mockup or project selection until approved.
+**Wait for the user.** If they suggest changes, revise the draft and present it again — repeat until they approve or cancel. Do NOT proceed to story points, mockup, or project selection until approved.
 
-## Step 4: Offer a Mockup (User Stories only — skip for Bugs)
+## Step 4: Propose Story Points
+
+Every work item this command creates gets a story point estimate — proposed automatically, applied only with the user's agreement.
+
+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.
+
+Present the estimate:
+
+```
+**Proposed estimate:** {n} story points
+- {one-line rationale: scope / layers touched / test burden}
+
+Agree? (yes / different number / skip)
+```
+
+**Wait for the user.**
+
+- `yes` → the agreed points are set at creation, and the item is moved to **Dev Ready** after creation (Step 8)
+- a different number → use the user's number (their call wins); same Dev Ready behavior
+- `skip` → create the item without points; it stays in the default `New` state and can be pointed later with `/quote`
+
+Points are never written without the user's explicit agreement.
+
+## Step 5: Offer a Mockup (User Stories only — skip for Bugs)
 
 If the work item type is **User Story** and the requirements appear to involve UI (a screen, a form, a button, a workflow), ask:
 
@@ -167,7 +190,7 @@ If any step fails (mockup generation, screenshot, upload), report the failure to
 
 Continue without a mockup.
 
-## Step 5: Choose the Project
+## Step 6: Choose the Project
 
 ### Detect the default project
 
@@ -191,7 +214,7 @@ If no default is found, ask without a preselection and offer to list projects vi
 
 **Wait for the user's response.** Validate the project name by calling `mcp__azure-devops__core_list_projects` if the response is ambiguous or doesn't match a known project.
 
-## Step 6: Final Confirmation
+## Step 7: Final Confirmation
 
 Before creating anything in Azure DevOps, present a final summary and ask for one last confirmation:
 
@@ -205,6 +228,8 @@ Before creating anything in Azure DevOps, present a final summary and ask for on
 **Priority:**  {n}
 **Severity:**  {n - Label}
 {end for Bugs}
+**Story Points:** {n (agreed) | skipped}
+**Initial State:** {Dev Ready (pointed) | New (no points)}
 **Mockup:**    {Embedded | Not requested | Skipped (non-UI)}
 **Images:**    {count} user-supplied image(s) embedded in description
 **Open Questions:** {count}
@@ -213,11 +238,11 @@ Create this work item now? (yes / edit / cancel)
 ```
 
 **Wait for the user.**
-- `yes` → proceed to Step 7
-- `edit` → ask which field to revise (title, description, AC, priority, severity, project, mockup), revise it, then re-show this summary
+- `yes` → proceed to Step 8
+- `edit` → ask which field to revise (title, description, AC, priority, severity, story points, project, mockup), revise it, then re-show this summary
 - `cancel` → abort with no work item created and confirm "Cancelled — no work item created."
 
-## Step 7: Render to HTML and Create
+## Step 8: Render to HTML and Create
 
 ### Render Markdown sections to HTML
 
@@ -258,6 +283,7 @@ Call `mcp__azure-devops__wit_create_work_item` with:
 - **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.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped)
   - For Bugs:
     - `Microsoft.VSTS.TCM.ReproSteps` — the rendered HTML repro steps (Azure DevOps puts repro steps in this field for the Bug template; if the project uses the Agile template instead, fold repro steps into Description)
     - `Microsoft.VSTS.Common.Priority` — the chosen Priority (1–4)
@@ -265,7 +291,11 @@ Call `mcp__azure-devops__wit_create_work_item` with:
 
 If the `Open Questions` section is non-empty, append it to the description as a clearly-labeled HTML block (`<h3>Open Questions</h3><ul>...</ul>`) so the assignee can address it later.
 
-## Step 8: Confirm
+### Move to Dev Ready (pointed items only)
+
+If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_update_work_item` **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
+
+## Step 9: Confirm
 
 After creation, report:
 
@@ -273,13 +303,15 @@ After creation, report:
 Created AB#{id}: {title}
   Project: {project}
   Type: {type}
+  Story Points: {n | not set}
+  State: {Dev Ready | New}
   URL: {work item URL}
   Mockup attached: {yes / no}
   Open questions: {count}
 
 Next steps:
   /explain AB#{id}     — re-read the item in plain language
-  /quote AB#{id}       — estimate story points
+  /quote AB#{id}       — {re-estimate | set story points (skipped at creation)}
   /implement AB#{id}   — start working on it
 ```
 

package/templates/commands/quote-backlog.md

@@ -7,10 +7,11 @@ This command walks the **backlog** of a chosen Azure DevOps project, finds user
 3. **Looks at the code when it makes sense** — to validate the described approach and suggest changes.
 4. **Proposes a story point estimate** — using the same senior-calibrated rubric as `/quote`.
 5. **Drafts a comment for the item's creator** when issues are found.
+6. **Suggests a rewrite** of the description/acceptance criteria when they need work — offered to the creator in the comment, or applied directly if the user chooses.
 
 **Hard batch limit: 10 items per run.** If more qualify, process the first 10 (by backlog rank) and report how many remain.
 
-**Nothing is written to Azure DevOps — no points, no comments — until the user has seen the full batch and approved.** This command never modifies code, never changes work item state, and never reassigns items.
+**Nothing is written to Azure DevOps — no points, no comments — until the user has seen the full batch and approved.** This command never modifies code and never reassigns items. The only state change it makes: when approved points are written to an item, that item also moves to **Dev Ready** (see Step 5).
 
 Treat `$ARGUMENTS` as an optional project name (e.g. `/quote-backlog CSI Development`). If provided, skip the project prompt in Step 1.
 
@@ -120,7 +121,7 @@ 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 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 on top of the rubric.
 
 | Points | Looks like |
 |--------|-----------|
@@ -151,9 +152,19 @@ If 3b–3d surfaced anything — gaps, a duplicate, a suggested approach change
 
 Keep it professional and brief — findings only, no filler. Items with no issues get **no comment**; don't post "looks good" noise.
 
+### 3g. Draft a suggested rewrite (when needed)
+
+If the completeness review found the **description or acceptance criteria** to be vague, contradictory, or structurally weak — not just missing one detail — draft a full rewrite that preserves the creator's intent:
+
+- **Description**: what is being built, why, and for whom — written from what the item, its links, and the code reconnaissance establish. Never invent requirements; where intent is unknowable, leave an explicit `{question for creator}` placeholder instead of guessing.
+- **Acceptance criteria**: a numbered, testable list — each criterion something UAT could verify.
+- **Title**: only if it violates the `PREFIX - Title` convention or misdescribes the work.
+
+The rewrite is a *suggestion*: by default it travels inside the creator comment (3f) under a "Suggested rewrite:" heading so the creator stays in control of their item. It is applied directly to the work item only if the user explicitly chooses that in Step 4. Skip this for items that are Complete or only missing a one-line answer — a rewrite should earn its place.
+
 ### Ultracode mode (optional fan-out)
 
-Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 3a–3f is independent per item, so fan out **one agent per item** with the `Workflow` tool. Each agent does the full 3a–3f pass and returns a structured result (item id, creator, completeness verdict, duplicate findings, code notes, proposed points, draft comment) — use a `schema` so each agent returns validated JSON.
+Only when **ultracode is on** (a system-reminder confirms it, or the user typed `ultracode`): the analysis in 3a–3g is independent per item, so fan out **one agent per item** with the `Workflow` tool. Each agent does the full 3a–3g pass and returns a structured result (item id, creator, completeness verdict, duplicate findings, code notes, proposed points, draft comment, suggested rewrite) — use a `schema` so each agent returns validated JSON.
 
 **Never fan out Step 4 or Step 5** — presentation, approval, and every write stay sequential in the main loop. If ultracode is off, analyze the batch one item at a time; the output is identical either way.
 
@@ -165,27 +176,30 @@ Show the whole batch **before writing anything**. Start with the summary table:
 Quote sweep — {project} backlog, Design Approved without Story Points
 Batch: {n} of {total} qualifying items{ — run /quote-backlog again for the next 10}
 
-| #  | ID       | Title                                  | Completeness  | Points | Comment |
-|----|----------|----------------------------------------|---------------|--------|---------|
-| 1  | AB#4611  | COM - Payment reminder emails          | Complete      |   5    | —       |
-| 2  | AB#4614  | COM - Bulk close inactive accounts     | Minor gaps    |   8    | yes     |
-| 3  | AB#4617  | PAY - Refund webhook handling          | Blocking gaps |   —    | yes     |
-| 4  | AB#4620  | COM - Export audit log                 | Already done? |   —    | yes     |
+| #  | ID       | Title                                  | Completeness  | Points | Comment | Rewrite |
+|----|----------|----------------------------------------|---------------|--------|---------|---------|
+| 1  | AB#4611  | COM - Payment reminder emails          | Complete      |   5    | —       | —       |
+| 2  | AB#4614  | COM - Bulk close inactive accounts     | Minor gaps    |   8    | yes     | —       |
+| 3  | AB#4617  | PAY - Refund webhook handling          | Blocking gaps |   —    | yes     | yes     |
+| 4  | AB#4620  | COM - Export audit log                 | Already done? |   —    | yes     | —       |
 ```
 
-Then a detail block per item — estimate reasoning (2–3 bullets), completeness findings, duplicate evidence with links/IDs, code notes, and the **full text of any draft comment**. The user must be able to read every word that would be posted.
+Then a detail block per item — estimate reasoning (2–3 bullets), completeness findings, duplicate evidence with links/IDs, code notes, the **full text of any draft comment**, and the **full text of any suggested rewrite**. The user must be able to read every word that would be posted.
+
+Note above the prompt: **items that get points will also move to Dev Ready** — approving the points approves the state change.
 
 Then ask:
 
 ```
-Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / cancel)
+Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cancel)
 ```
 
 **Wait for the user.**
 
-- `all` → apply every proposed write (points and comments) in Step 5
+- `all` → apply every proposed write (points and comments) in Step 5; rewrites stay inside the comments as suggestions
 - `1,2,4` → apply only those items; the rest are recorded as skipped
-- `edit N` → ask what to change on item N (points value or comment text), revise, re-show that item, ask again
+- `edit N` → ask what to change on item N (points value, comment text, or rewrite text), revise, re-show that item, ask again
+- `apply rewrite N` → write item N's rewrite directly onto the work item in Step 5 (instead of only suggesting it in the comment)
 - `skip N` → drop item N, re-ask for the rest
 - `cancel` → stop with **zero changes** to Azure DevOps
 
@@ -193,8 +207,9 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / cancel)
 
 Only for approved items, in batch order:
 
-1. **Set Story Points** (items with a proposed number): update `Microsoft.VSTS.Scheduling.StoryPoints` via `mcp__azure-devops__wit_update_work_item`. Touch no other field — state, assignee, iteration, and tags stay as they are.
+1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_update_work_item` call, set `Microsoft.VSTS.Scheduling.StoryPoints` **and** `System.State` = `Dev Ready`. The state change applies only to `User Story`, `Bug`, and `Hot Fix` types, and never moves an item backward — if an item is somehow already past Dev Ready, set the points only and note it. Touch no other field — assignee, iteration, and tags stay as they are.
 2. **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.
+3. **Apply the rewrite** (only items the user marked `apply rewrite N`): update `System.Description` and/or `Microsoft.VSTS.Common.AcceptanceCriteria` 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.
 
 If a write fails, report the failure and ask whether to continue with the remaining items or stop.
 
@@ -204,8 +219,9 @@ If a write fails, report the failure and ask whether to continue with the remain
 ## Quote Sweep Complete — {project}
 
 Items analyzed:   {n} (of {total} qualifying — {remaining} left for the next run)
-  ✓ Points set:   {n_pointed}  (total {sum} pts)
+  ✓ Points set:   {n_pointed}  (total {sum} pts — each moved to Dev Ready)
   ✓ Comments:     {n_comments} posted to creators
+  ✓ Rewrites:     {n_rewrites_applied} applied, {n_rewrites_suggested} suggested in comments
   ⏭ Skipped:      {n_skipped} ({reasons: user skipped / blocking gaps / possible duplicate})
 
 Pointed items:
@@ -222,4 +238,4 @@ Next steps:
   /quote AB#{id}             — re-estimate a single item after the creator responds
 ```
 
-Do not change item state, create tasks, or assign items — those are downstream decisions (`/plan-backlog` picks up once items are pointed and Dev Ready).
+Do not create tasks or assign items — those are downstream decisions. Pointed items are now Dev Ready, so `/plan-backlog` picks them up on its next run. Make no state change other than the points→Dev Ready move described in Step 5.

package/templates/commands/quote.md

@@ -14,9 +14,9 @@ Capture: title, type, description, acceptance criteria, attached child items, an
 
 Use the **modified Fibonacci scale** for story points: `1, 2, 3, 5, 8, 13, 21`. Anything that feels larger than 21 should be flagged as "needs to be split" rather than given a number.
 
-> **Assume a senior developer 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.
+> **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.
 
-Rough sizing rubric (calibrated for a senior developer working in a codebase they know):
+Rough sizing rubric (calibrated for a senior developer, assisted by Claude, working in a codebase they know):
 
 | Points | Looks like |
 |--------|-----------|
@@ -64,8 +64,15 @@ If an existing `Story Points` value is already set on the work item and your est
 
 If the work looks larger than 21 points, do not assign a number — instead report `**Estimate:** needs to be split` and suggest 2–4 candidate split points based on the acceptance criteria.
 
-## Step 4: Offer to Persist
+## Step 4: Offer to Persist (Points + Dev Ready)
 
-After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}?"*
+After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}? (This will also move it to Dev Ready.)"*
 
 Only update the work item if the user explicitly says yes. Do not modify anything otherwise.
+
+When the user agrees, in the **same** `wit_update_work_item` call:
+
+1. Set `Microsoft.VSTS.Scheduling.StoryPoints` to the agreed value (the user's number wins if they adjusted it).
+2. Set `System.State` to `Dev Ready` — **but only if** the work item type is `User Story`, `Bug`, or `Hot Fix` **and** the item is not already past Dev Ready in the workflow (e.g. `Active`, `Code Review`, `Ready to Deploy`). Never move an item backward — if it's already past Dev Ready, set the points only and mention the state was left alone.
+
+**Never change the state of a Feature or a Task** — if the sized item is a Feature, persist points only (or per-child points on the children, each of which does get Dev Ready if it qualifies).

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -105,6 +105,14 @@ Claude maintains persistent memory across sessions in `~/.claude/projects/.../me
 8. **Track** work items via the Azure DevOps MCP server
 9. **Learn** — Claude saves what worked for next time
 
+### Story Points & Dev Ready Policy
+
+These rules apply to **every** command or flow that creates or estimates work items:
+
+1. **Every work item Claude creates gets a proposed story point estimate** — User Stories and Bugs are never created unpointed by default. Estimates use the modified Fibonacci scale (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** — no ramp-up padding; pad only for what seniority + Claude can't shortcut (novel work, missing AC, cross-team coordination, external dependencies).
+2. **The user must agree before points are written.** Claude proposes the number with a one-line rationale; the user confirms, adjusts (their number wins), or skips. Points are never set silently.
+3. **Setting points moves the item to Dev Ready.** Any time story points are written to a **User Story**, **Bug**, or **Hot Fix**, `System.State` is set to `Dev Ready` in the same update. Never for Features or Tasks (a Feature's state is never touched; Tasks carry hour estimates, not points), and never backward — an item already past Dev Ready keeps its state, with a note.
+
 ### Branching Strategy
 
 #### Target Branch-to-Environment Mapping
@@ -244,7 +252,9 @@ All deployment and release operations are available as slash commands:
 | `/status` | `/status release 24` | Check release, pipeline, or work item status |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose child tasks with hours |
 | `/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 Design Approved items without points → review completeness, check for duplicates, propose points + creator comments (10 at a time, approval-gated) |
+| `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated; approved points also move the item to Dev Ready) |
+| `/quote` | `/quote AB#1234` | Estimate story points for one work item; on approval, sets the points and moves the item to Dev Ready |
+| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Bug or User Story — proposes story points (user must agree) and creates pointed items in Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks [scope] [--dry-run]` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |