@chris1807/claude-kit 2.1.4 → 2.1.8

package/bin/cli.js

@@ -178,7 +178,7 @@ async function main() {
       choices: [
         { name: 'Project Agents (deployer, db-admin, devops-tracker)', value: 'agents', checked: true },
         { name: 'Hooks (secret blocker, auto-format, test suggestions)', value: 'hooks', checked: true },
-        { name: 'Slash Commands (11 commands — implement, review, deploy, releases, cherry-pick, promote, rollback, status, cleanup)', value: 'commands', checked: true },
+        { name: 'Slash Commands (implement, review, deploy, releases, cherry-pick, promote, rollback, status, cleanup, create-work-item, …)', value: 'commands', checked: true },
         { name: 'MCP Servers (Playwright, DB, Teams, Stripe, Azure, Azure DevOps)', value: 'mcp', checked: true },
         { name: 'Settings (hook registration)', value: 'settings', checked: true },
         { name: 'CLAUDE.md Workflow Section', value: 'workflow', checked: true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.4",
+  "version": "2.1.8",
   "description": "Claude Code starter kit — agents, hooks, MCP servers, slash commands, and workflow automation",
   "type": "module",
   "bin": {

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

@@ -0,0 +1,275 @@
+Create a new Azure DevOps work item interactively. Usage: `/create-work-item`
+
+This command walks the user through creating a Bug or User Story, develops an acceptance-criteria-ready plan, optionally embeds a UI mockup in the description, and creates the item in the chosen Azure DevOps project.
+
+Treat `$ARGUMENTS` as an optional rough description that the user may have typed inline (e.g. `/create-work-item users should be able to export payments`). If provided, skip the initial "describe your requirements" prompt in Step 2 and use it as the starting requirements text — but still confirm with the user before proceeding.
+
+## Step 1: Choose Work Item Type
+
+Ask the user:
+
+```
+What type of work item do you want to create?
+
+  1. Bug
+  2. User Story
+
+Reply with 1, 2, "bug", or "user story".
+```
+
+**Wait for the user's response.** Map the answer to either `Bug` or `User Story`. If the user types something else, ask again — do not guess.
+
+## Step 2: Gather Requirements
+
+Ask the user to describe the requirements:
+
+```
+Describe the {bug | user story} in your own words. Include:
+
+- What the user is trying to do (or what is broken)
+- Why it matters / who is affected
+- Any constraints, edge cases, or steps to reproduce (for bugs)
+- Links to related work items, PRs, or docs if relevant
+- You can also paste image URLs, screenshot links, or attachment URLs —
+  they will be preserved in the description
+
+You can paste as much detail as you want — I'll structure it.
+```
+
+**Wait for the user's response.** If the response is very short or vague, ask one targeted clarifying question (e.g. "Does this apply to all users or only admins?"). Don't interrogate — one round of clarification is enough.
+
+### Preserve user-supplied images and links
+
+Scan the user's response for:
+
+- Direct image URLs (`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.svg`)
+- Azure DevOps attachment URLs (e.g. `https://dev.azure.com/.../_apis/wit/attachments/...`)
+- Markdown image syntax (`![alt](url)`)
+- Pasted screenshot blob paths or local file paths to images
+
+For each image found, plan to embed it in the final description as an `<img src="{url}">` tag, with the user's surrounding text preserved as context. For non-image links (docs, PRs, related work items), preserve them as `<a href="{url}">{url}</a>` in the relevant section of the draft. Do not strip these — they are often the only ground truth for the requirement.
+
+## Step 3: Develop the Plan
+
+Translate the user's free-form requirements into a structured work item draft. The shape depends on the type:
+
+### For a User Story:
+
+```
+## Draft: {Prefix} - {proposed title}
+
+**Type:** User Story
+
+### Description
+{2–4 sentences in plain language. Explain the user-facing behavior and the
+business or user value. Avoid implementation detail — that lives in tasks.}
+
+### Acceptance Criteria
+1. {Given/When/Then or numbered behavior — must be testable}
+2. ...
+3. ...
+
+### Out of Scope
+- {anything the user mentioned but that shouldn't block this story}
+
+### Open Questions
+- {anything ambiguous that you couldn't infer — list as questions, not assumptions}
+```
+
+### For a Bug:
+
+```
+## Draft: {Prefix} - {proposed title}
+
+**Type:** Bug
+**Priority:** {1 | 2 | 3 | 4}
+**Severity:** {1 - Critical | 2 - High | 3 - Medium | 4 - Low}
+
+### Description
+{1–2 sentences describing the observed problem in plain language.}
+
+### Steps to Reproduce
+1. ...
+2. ...
+3. ...
+
+### Expected Behavior
+{what should happen}
+
+### Actual Behavior
+{what does happen}
+
+### Acceptance Criteria
+1. {behavioral check that proves the bug is fixed — must be testable}
+2. {regression guard if applicable}
+
+### Environment / Scope
+- {where the bug occurs — browser, environment, role, data condition}
+
+### Open Questions
+- {anything you couldn't infer}
+```
+
+**Inferring Priority and Severity for Bugs:**
+
+Propose initial values based on the requirements, then let the user override during approval. Use this rubric:
+
+| Severity | Looks like |
+|----------|-----------|
+| **1 - Critical** | Production is down, data loss, security breach, or blocking all users |
+| **2 - High** | Major feature broken, no workaround, affects many users |
+| **3 - Medium** | Feature partially broken, workaround exists, or affects some users |
+| **4 - Low** | Cosmetic, minor inconvenience, or affects few users |
+
+| Priority | Looks like |
+|----------|-----------|
+| **1** | Drop everything — fix immediately |
+| **2** | Next sprint at the latest |
+| **3** | Normal queue |
+| **4** | Nice to have / fix when convenient |
+
+Severity describes user impact; Priority describes scheduling urgency. They are independent — a Sev 2 can be Priority 3 if a workaround exists.
+
+### Title Prefix
+
+The title MUST start with one of the product prefixes from the project's CLAUDE.md (e.g. `COM`, `CDA`, `PAY`, `AUD`, `SER`, `PSSF`, `TPS`). If the project CLAUDE.md does not define a prefix table, ask the user which prefix to use before drafting. Format is `PREFIX - Title Here`.
+
+### Approval
+
+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.
+
+## Step 4: 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:
+
+```
+Want me to generate an HTML mockup and embed it in the description? (yes / no)
+```
+
+If the work item is clearly non-UI (background job, data migration, API-only change), skip this step and note "No mockup — non-UI work."
+
+### If the user says yes:
+
+1. Delegate to the **mockup** agent to generate an HTML mockup based on the draft. Brief the agent with the draft description and acceptance criteria.
+2. Save the mockup HTML to a temporary path, then render it to PNG using Playwright (`mcp__playwright__browser_navigate` to the file path, then `mcp__playwright__browser_take_screenshot`).
+3. Upload the PNG as a work item attachment via the Azure DevOps API. Capture the returned attachment URL.
+4. Append an `<img>` tag to the work item description pointing at the attachment URL, with a caption like `Mockup — generated {date}`.
+
+If any step fails (mockup generation, screenshot, upload), report the failure to the user and ask whether to proceed without the mockup or abort.
+
+### If the user says no:
+
+Continue without a mockup.
+
+## Step 5: Choose the Project
+
+### Detect the default project
+
+Before prompting, attempt to detect the default Azure DevOps project from CLAUDE.md, in this order:
+
+1. **Project CLAUDE.md** — read `<current-repo>/CLAUDE.md`. Look for an explicit `project: <name>` declaration, a "Work items live in **<Project Name>**" sentence, or a `## Pipeline Configuration` table with project references.
+2. **Parent CLAUDE.md** — read `<parent-dir>/CLAUDE.md` (e.g. `~/Projects/CLAUDE.md`). Look for the same patterns. The CSI parent CLAUDE.md, for example, declares: "Work items for both **COMPASS** and **CSI Pay** live in the **CSI Development** Azure DevOps project."
+3. **Prefix mapping** — if the title prefix chosen in Step 3 is in a known mapping (e.g. `COM`, `CDA`, `PAY` → `CSI Development`), use that.
+
+If a default is found, present it pre-selected:
+
+```
+Which Azure DevOps project should this be created in?
+
+  Default: {detected project}   ← press enter to accept
+
+Or specify a different project name.
+```
+
+If no default is found, ask without a preselection and offer to list projects via `mcp__azure-devops__core_list_projects`.
+
+**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
+
+Before creating anything in Azure DevOps, present a final summary and ask for one last confirmation:
+
+```
+## Ready to Create
+
+**Title:**     {Prefix} - {title}
+**Type:**      {Bug | User Story}
+**Project:**   {project}
+{for Bugs:}
+**Priority:**  {n}
+**Severity:**  {n - Label}
+{end for Bugs}
+**Mockup:**    {Embedded | Not requested | Skipped (non-UI)}
+**Images:**    {count} user-supplied image(s) embedded in description
+**Open Questions:** {count}
+
+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
+- `cancel` → abort with no work item created and confirm "Cancelled — no work item created."
+
+## Step 7: Render to HTML and Create
+
+### Render Markdown sections to HTML
+
+Azure DevOps description and acceptance criteria fields are HTML — they do not render Markdown. Before submitting, convert the draft sections:
+
+| Markdown                  | HTML                                          |
+|---------------------------|-----------------------------------------------|
+| `1. item\n2. item`        | `<ol><li>item</li><li>item</li></ol>`         |
+| `- item\n- item`          | `<ul><li>item</li><li>item</li></ul>`         |
+| `**bold**`                | `<strong>bold</strong>`                       |
+| `\n\n` (paragraph break)  | `</p><p>`                                     |
+| `\n` (single newline)     | `<br>`                                        |
+| `` `code` ``              | `<code>code</code>`                           |
+| `### Heading`             | `<h3>Heading</h3>`                            |
+| `[text](url)`             | `<a href="url">text</a>`                      |
+| `![alt](url)`             | `<img src="url" alt="alt">`                   |
+
+Wrap each top-level section in `<p>...</p>`. Preserve any user-supplied `<img>` tags from Step 2 as-is.
+
+### Call the create API
+
+Call `mcp__azure-devops__wit_create_work_item` with:
+
+- **project**: the chosen project
+- **workItemType**: `Bug` or `User Story`
+- **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
+  - 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)
+    - `Microsoft.VSTS.Common.Severity` — the chosen Severity (`1 - Critical`, `2 - High`, `3 - Medium`, `4 - Low`)
+
+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
+
+After creation, report:
+
+```
+Created AB#{id}: {title}
+  Project: {project}
+  Type: {type}
+  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
+  /implement AB#{id}   — start working on it
+```
+
+Do not assign the work item, set an iteration, or add tags unless the user explicitly asks — those are downstream decisions.

package/templates/commands/implement.md

@@ -174,4 +174,69 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
    - **title**: `AB#{id}: {work item title}`
    - **labels**: `["hotfix"]` if the work item type is Hot Fix
 3. Link the PR to the work item via `wit_link_work_item_to_pull_request`
-4. Update the work item status in Azure DevOps
+4. **Close related Tasks and log hours** — see "Closing Related Tasks" below.
+5. **Move the work item to `Code Review`** via `wit_update_work_item`:
+   - **path**: `/fields/System.State`
+   - **value**: `Code Review`
+
+   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.
+
+### Closing Related Tasks
+
+After the PR is created, find every child Task of this work item (relations of type `System.LinkTypes.Hierarchy-Forward` where the target's `System.WorkItemType` is `Task`). Skip this step if there are no child Tasks.
+
+For each child Task, capture:
+- ID, title, state
+- `Microsoft.VSTS.Scheduling.OriginalEstimate`
+- `Microsoft.VSTS.Scheduling.CompletedWork`
+- `Microsoft.VSTS.Scheduling.RemainingWork`
+
+Present:
+
+```
+## Close Related Tasks
+
+| Task ID | Title | State | Original | Completed | Remaining |
+|---------|-------|-------|----------|-----------|-----------|
+| AB#xxxx | ...   | Active | 4 | 0 | 4 |
+| AB#yyyy | ...   | Active | 2 | 1 | 1 |
+
+Close all related tasks and log completed hours? (yes / no / select)
+```
+
+- `yes` → walk through every child Task in sequence
+- `no`  → skip closing tasks entirely
+- `select` → ask which task IDs to process; only those get prompted
+
+For each task being processed, prompt for completed hours:
+
+- **If `CompletedWork` is empty or `0`:**
+
+  ```
+  AB#xxxx ({title})
+    Original estimate: {n}h
+    Completed:         0h
+    Remaining:         {n}h
+
+  Enter completed hours (suggested: {OriginalEstimate}h, press enter to accept):
+  ```
+
+- **If `CompletedWork` is already set (non-zero):**
+
+  ```
+  AB#xxxx ({title})
+    Original estimate: {n}h
+    Completed:         {current}h   ← already logged
+    Remaining:         {m}h
+
+  Update completed hours to (press enter to keep {current}, or enter new value):
+  ```
+
+**Wait for the user's response on every task.** Accept the suggested/current value (enter), a new numeric value, or `skip` to leave that one untouched.
+
+Once the user has answered, update each task via `wit_update_work_item`:
+- `Microsoft.VSTS.Scheduling.CompletedWork` → the agreed value
+- `Microsoft.VSTS.Scheduling.RemainingWork` → `0`
+- `System.State` → `Closed` (fall back to `Done` if the project's task template uses Agile; warn if neither is valid)
+
+Confirm with a summary line per task: `Closed AB#xxxx — {hours}h logged`.

package/templates/commands/quote.md

@@ -1,4 +1,4 @@
-Fetch a work item and display it as a formatted quote block. Usage: `/quote <work-item-id>`
+Fetch a work item and estimate the effort in story points. Usage: `/quote <work-item-id>`
 
 Parse `$ARGUMENTS` to extract the work item ID. Accept formats like `AB#1234`, `#1234`, or just `1234`.
 
@@ -8,32 +8,62 @@ Read the work item from Azure DevOps using the project from the current repo's C
 
 If the work item is not found, report the error and stop.
 
-## Step 2: Display the Quote
+Capture: title, type, description, acceptance criteria, attached child items, any existing `Story Points` / `Effort` field value, and any tags that hint at scope (e.g. `spike`, `research`, `infra`).
 
-Format the work item as a quote block:
+## Step 2: Size the Work
+
+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.
+
+Rough sizing rubric (calibrate against what you can see in the repo, not abstract complexity):
+
+| Points | Looks like |
+|--------|-----------|
+| **1** | Trivial change — copy tweak, single config value, one-line fix. No new tests needed. |
+| **2** | Small, well-understood change in one file or one layer. Existing patterns cover it. |
+| **3** | Touches a couple of files / one feature slice. Some new tests. No architectural questions. |
+| **5** | Crosses layers (e.g. API + UI), or introduces a new component/endpoint following existing patterns. Real test coverage needed. |
+| **8** | Multi-area change with meaningful new logic, migrations, or non-trivial edge cases. Some unknowns the implementer will need to resolve. |
+| **13** | Large feature, several moving parts, or significant unknowns. Likely benefits from being split. |
+| **21** | Very large / high uncertainty. Should almost certainly be split into multiple stories. |
+
+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, or work that mirrors an existing implementation.
+
+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).
+
+## Step 3: Display the Estimate
+
+Output a compact estimate — not a quote block. Format:
 
 ```
-> **AB#{id}: {title}**
-> **Type:** {type} | **State:** {state} | **Assigned To:** {assignedTo}
->
-> {description text, stripped of HTML tags, truncated to ~500 chars if long}
->
-> **Acceptance Criteria:**
-> {acceptance criteria, stripped of HTML tags, truncated to ~500 chars if long}
+**AB#{id}: {title}**
+**Estimate:** {points} story points{ — confidence: low/medium/high}
+
+**Reasoning:**
+- {bullet on scope / files / layers touched}
+- {bullet on unknowns or risk}
+- {bullet on test/doc burden}
+
+**Comparable to:** {one-line analogy to a similar past story, or "no obvious comparable in recent work"}
 ```
 
-- Strip all HTML tags from description and acceptance criteria fields, preserving line breaks as `> ` prefixed lines
-- If description or acceptance criteria is empty, omit that section
-- If the work item has child items, append:
+If child items were sized, append:
 
 ```
->
-> **Child Items:** {count}
-> | ID | Title | State |
-> |----|-------|-------|
-> | AB#{id} | {title} | {state} |
+**Child breakdown:**
+| AB# | Title | Points |
+|-----|-------|--------|
+| ... | ...   | ...    |
+| **Total** |  | **{sum}** |
 ```
 
-- If the work item has tags, include them: `> **Tags:** {comma-separated tags}`
+If an existing `Story Points` value is already set on the work item and your estimate differs, call that out explicitly: `**Existing estimate:** {n} (yours differs — {why})`.
+
+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
+
+After displaying the estimate, ask the user: *"Want me to set Story Points = {n} on AB#{id}?"*
 
-That's it — just display the quote. Do not modify anything.
+Only update the work item if the user explicitly says yes. Do not modify anything otherwise.

package/templates/commands/rework.md

@@ -97,7 +97,69 @@ Approve this plan? (yes / no / suggest changes)
 
 **Wait for the user to approve the plan.** Do NOT start implementation until the user approves. If they suggest changes, revise the plan and present it again.
 
-## Step 5: Switch to Existing Branch
+## Step 5: Create Rework Task as a Child
+
+Every rework round gets its own Task work item, parented under the original User Story / Bug. This keeps the rework effort visible on the board and gives the team a clean record of how many rounds an item went through.
+
+### Suggest hours
+
+Estimate the rework effort from the approved plan. Use this rubric — calibrate against scope, not abstract complexity:
+
+| Hours | Looks like |
+|-------|-----------|
+| **0.5** | Trivial — copy tweak, single config value, one-line fix. No new tests. |
+| **1**   | One file, well-understood change. Maybe one new/updated test. |
+| **2**   | 2–3 files, one layer, follows existing patterns. Some new tests. |
+| **4**   | Multiple files across layers, or new logic in one area. Real test coverage. |
+| **8**   | Most of a day — meaningful new logic, several files, edge cases. |
+| **16**  | Two days — significant rework, multiple unknowns to resolve. |
+| **24+** | Three days or more — flag that this rework probably should have been a fresh story. |
+
+Adjust upward for: ambiguous feedback, missing UX, data migrations, regression risk in unrelated areas. Adjust downward for: pure config changes or mechanical fixes.
+
+### Prompt the user
+
+```
+## Rework Task
+
+**Title:**       Rework AB#{id} — round {N}
+**Parent:**      AB#{id} ({title})
+**Description:** {1–2 sentence summary of the rework feedback addressed}
+
+**Suggested hours:** {n}
+  Based on: {one line — files touched / scope / unknowns}
+
+Enter the estimated hours for this task (press enter to accept {n}):
+```
+
+`{N}` is the rework round — count how many existing child Tasks already exist on the parent with a title matching `Rework AB#{id}` and add 1.
+
+**Wait for the user's response.** Accept the suggestion (enter), accept a different number, or `cancel` to skip task creation. Do not proceed to branch switch until this is resolved.
+
+### Create the task
+
+If the user provided hours (suggested or overridden):
+
+1. Call `mcp__azure-devops__wit_create_work_item`:
+   - **workItemType**: `Task`
+   - **title**: `Rework AB#{id} — round {N}`
+   - **fields**: JSON Patch document setting:
+     - `System.Description` — short summary of the rework feedback + link to the most recent PR
+     - `Microsoft.VSTS.Scheduling.OriginalEstimate` — the agreed hours
+     - `Microsoft.VSTS.Scheduling.RemainingWork` — the agreed hours
+     - `System.AreaPath` — same as the parent
+     - `System.IterationPath` — same as the parent
+
+2. Link the new Task as a child of the parent work item via `wit_work_items_link`:
+   - **type**: `Child` (the parent → child link from the parent's perspective; equivalent to `Parent` from the task's perspective)
+   - **source**: parent work item ID
+   - **target**: new task ID
+
+3. Confirm to the user: `Created task AB#{taskId} (parent: AB#{id}, est: {hours}h)`.
+
+If the user cancels, skip task creation and proceed — note "No rework task created" in the final summary.
+
+## Step 6: Switch to Existing Branch
 
 The work item already has a branch from the previous PR. Switch to it:
 
@@ -107,26 +169,26 @@ The work item already has a branch from the previous PR. Switch to it:
 
 If the PR was completed/merged and the branch was deleted, create a new branch from the PR's target branch following the same naming convention as `/implement` Step 4.
 
-## Step 6: Implement
+## Step 7: Implement
 
 1. **Implement** the rework using backend and/or frontend agents according to the approved plan
 2. **Write the unit tests** listed in the plan's "Unit Tests" section alongside the implementation — not after. Include any regression test that would have caught the original issue
 3. **Generate mockup** if there are UI changes
 
-## Step 7: Build Validation
+## Step 8: Build Validation
 
 Run a build check **before** any other quality checks. Use the `build-validator` agent to verify that all projects compile successfully.
 
 - If the build fails, **fix the errors immediately** and re-run until the build passes
 - Do NOT proceed to review, tests, or lint until the build is clean
 
-## Step 8: Quality Checks
+## Step 9: Quality Checks
 
 1. **Review** code for quality, security, and Clean Architecture compliance
 2. **Run the full test suite** — every unit test in the repo, plus integration tests. Not just the tests added in this rework. A failure in an unrelated test means this rework broke something else; treat it as a regression, fix it, and re-run until the entire suite is green
 3. **Run lint** — ESLint and dotnet format
 
-## Step 9: UAT Gate
+## Step 10: UAT Gate
 
 ### If Hot Fix:
 Skip manual UAT. Present an abbreviated confirmation:
@@ -158,8 +220,75 @@ Did manual testing pass?
 
 Wait for the user's response before proceeding. Do NOT push until confirmed.
 
-## Step 10: Push and Update
+## Step 11: Push and Update
 
 1. Push the changes: `git push`
 2. Add a comment on the existing PR summarizing what was changed in the rework
-3. Update the work item status in Azure DevOps if needed
+3. **Close related Tasks and log hours** — see "Closing Related Tasks" below. This includes the rework Task created in Step 5 as well as any other child Tasks that became `Completed` as a result of this rework round.
+4. **Move the work item back to `Code Review`** via `wit_update_work_item`:
+   - **path**: `/fields/System.State`
+   - **value**: `Code Review`
+
+   Rework is triggered by reviewer feedback, so the item was likely in `Active` / `In Progress` / `Rework` while the fixes were being made. Pushing the rework hands it back to the reviewer, so it belongs in `Code Review` again.
+
+   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. Do not silently swallow the error.
+
+### Closing Related Tasks
+
+After pushing, find every child Task of this work item (relations of type `System.LinkTypes.Hierarchy-Forward` where the target's `System.WorkItemType` is `Task`). Skip this step if there are no child Tasks.
+
+For each child Task, capture:
+- ID, title, state
+- `Microsoft.VSTS.Scheduling.OriginalEstimate`
+- `Microsoft.VSTS.Scheduling.CompletedWork`
+- `Microsoft.VSTS.Scheduling.RemainingWork`
+
+Present:
+
+```
+## Close Related Tasks
+
+| Task ID | Title | State | Original | Completed | Remaining |
+|---------|-------|-------|----------|-----------|-----------|
+| AB#xxxx | Rework AB#{id} — round 2 | Active | 4 | 0 | 4 |
+| AB#yyyy | ...                      | Active | 2 | 1 | 1 |
+
+Close all related tasks and log completed hours? (yes / no / select)
+```
+
+- `yes` → walk through every child Task in sequence
+- `no`  → skip closing tasks entirely
+- `select` → ask which task IDs to process; only those get prompted
+
+For each task being processed, prompt for completed hours:
+
+- **If `CompletedWork` is empty or `0`:**
+
+  ```
+  AB#xxxx ({title})
+    Original estimate: {n}h
+    Completed:         0h
+    Remaining:         {n}h
+
+  Enter completed hours (suggested: {OriginalEstimate}h, press enter to accept):
+  ```
+
+- **If `CompletedWork` is already set (non-zero):**
+
+  ```
+  AB#xxxx ({title})
+    Original estimate: {n}h
+    Completed:         {current}h   ← already logged
+    Remaining:         {m}h
+
+  Update completed hours to (press enter to keep {current}, or enter new value):
+  ```
+
+**Wait for the user's response on every task.** Accept the suggested/current value (enter), a new numeric value, or `skip` to leave that one untouched.
+
+Once the user has answered, update each task via `wit_update_work_item`:
+- `Microsoft.VSTS.Scheduling.CompletedWork` → the agreed value
+- `Microsoft.VSTS.Scheduling.RemainingWork` → `0`
+- `System.State` → `Closed` (fall back to `Done` if the project's task template uses Agile; warn if neither is valid)
+
+Confirm with a summary line per task: `Closed AB#xxxx — {hours}h logged`.