@chris1807/claude-kit 2.2.2 → 2.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "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/add-to-release.md

@@ -38,7 +38,7 @@ Wait for confirmation.
 
 ## Step 4: Assign and Tag
 
-Use `wit_update_work_items_batch` to:
+Use `wit_work_item_write` (action `update_batch`) to:
 1. Set the Iteration Path to `{project}\Release #{N}` on each new work item
 2. Append `release-{N}` to each work item's tags
 

package/templates/commands/cherry-pick.md

@@ -123,7 +123,7 @@ Cherry-picking:
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Cherry-pick AB#1234, AB#1235 → {Environment}`
    - **description**: List all work items with IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 1b, so whoever merges sees them without opening the work items
-3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
+3. Link all work items to the PR via `wit_work_item_link_write` (action `link_to_pull_request`)
 
 ## Step 6: Pick Who Verifies Each Group (before the merge)
 

package/templates/commands/close-orphan-tasks.md

@@ -16,7 +16,7 @@ All work items live in the **CSI Development** Azure DevOps project (see CLAUDE.
 
 ## Step 1: Find Orphaned Tasks
 
-Use the Azure DevOps MCP `wit_query_by_wiql` with a hierarchy link query. The Source is the parent, the Target is the child Task:
+Use the Azure DevOps MCP `wit_query` (action `wiql`) with a hierarchy link query. The Source is the parent, the Target is the child Task:
 
 ```sql
 SELECT [System.Id]
@@ -31,11 +31,11 @@ MODE (MustContain)
 
 If a **scope** was given, add the matching constraint to the `[Target]` clause (e.g. `AND [Target].[System.AreaPath] UNDER 'CSI Development\\Compass'`, or `AND [Target].[System.Title] CONTAINS 'PAY'`).
 
-> **Note on state names:** Process templates vary. Some projects close tasks to `Done` instead of `Closed`, or use `Resolved`. If the query returns nothing or errors on an unknown state, first confirm the valid states for the Task type via `wit_get_work_item_type`, then adjust the `NOT IN` list and the close target in Step 3 accordingly.
+> **Note on state names:** Process templates vary. Some projects close tasks to `Done` instead of `Closed`, or use `Resolved`. If the query returns nothing or errors on an unknown state, first confirm the valid states for the Task type via `wit_work_item` (action `get_type`), then adjust the `NOT IN` list and the close target in Step 3 accordingly.
 
 If the link query is unsupported or returns no usable pairs, fall back to: query all open Tasks in scope with a flat WIQL, fetch each task's parent via `relations`, and keep only those whose parent state is in the three target states.
 
-Fetch the matched tasks (and their parents) in a batch via `wit_get_work_items_batch_by_ids` to get titles, states, assignees, and parent context.
+Fetch the matched tasks (and their parents) in a batch via `wit_work_item` (action `get_batch`) to get titles, states, assignees, and parent context.
 
 ## Step 2: Present the Candidates
 
@@ -59,11 +59,11 @@ Otherwise, wait for explicit confirmation before proceeding. Never close tasks w
 
 ## Step 3: Close the Tasks
 
-For each confirmed task, use `wit_update_work_items_batch`:
+For each confirmed task, use `wit_work_item_write` (action `update_batch`):
 - **path**: `/fields/System.State`
 - **value**: `Closed` (or the project's terminal Task state confirmed in Step 1)
 
-Then add a comment on each via `wit_add_work_item_comment` so the auto-close is traceable:
+Then add a comment on each via `wit_work_item_comment_write` (action `add`) so the auto-close is traceable:
 
 > Auto-closed by `/close-orphan-tasks` — parent AB#{parentId} is in state "{parentState}".
 

package/templates/commands/create-release.md

@@ -38,13 +38,13 @@ Create a new iteration in Azure DevOps via `work_create_iterations`:
 
 ## Step 4: Assign Work Items to the Release
 
-Use `wit_update_work_items_batch` to set the Iteration Path on each work item to the new release iteration:
+Use `wit_work_item_write` (action `update_batch`) to set the Iteration Path on each work item to the new release iteration:
 - **path**: `/fields/System.IterationPath`
 - **value**: `{project}\Release #{N}`
 
 ## Step 5: Tag Work Items
 
-Use `wit_update_work_items_batch` to add a release tag to each work item:
+Use `wit_work_item_write` (action `update_batch`) to add a release tag to each work item:
 - **path**: `/fields/System.Tags`
 - **value**: append `release-{N}` to existing tags
 

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

@@ -404,7 +404,7 @@ This applies to **User Story**. It does **not** apply to Bug or Hot Fix: neither
 
 ### Call the create API
 
-Call `mcp__azure-devops__wit_create_work_item` with:
+Call `mcp__azure-devops__wit_work_item_write` (action `create`) with:
 
 - **project**: the chosen project
 - **workItemType**: `Feature`, `Bug`, `User Story`, or `Hot Fix` (two words, exact casing)
@@ -431,7 +431,7 @@ If the `Open Questions` section is non-empty, append it as a clearly-labeled HTM
 
 ### 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`.
+If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_work_item_write` (action `update`) **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`.
 
 **Features are never moved.** A Feature stays in `New` and advances only as its child stories are verified and closed — the same rule `/implement` follows.
 
@@ -462,7 +462,7 @@ On `yes`:
    ```
 
    **Wait for the user.** Revise and re-present until approved. Do not create anything before approval.
-5. On approval, create each story with `mcp__azure-devops__wit_create_work_item` in the same project, setting:
+5. On approval, create each story with `mcp__azure-devops__wit_work_item_write` (action `create`) in the same project, setting:
    - `System.Description` and `Microsoft.VSTS.Common.AcceptanceCriteria` — rendered to HTML per the Step 8 rules
    - `Custom.Order` — the wave number
    - `Microsoft.VSTS.Scheduling.StoryPoints` — the agreed points
@@ -489,7 +489,7 @@ For a **Bug**, fetch `Microsoft.VSTS.TCM.ReproSteps` and `Microsoft.VSTS.TCM.Sys
 
 For a **Hot Fix**, fetch `System.Description` and `Microsoft.VSTS.TCM.ReproSteps`, and confirm the narrative is in the former and the reproduction detail in the latter.
 
-If a 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.
+If a check fails the write didn't take — fix it with `wit_work_item_write` (action `update`) before reporting success. Don't report a created item you haven't read back.
 
 After creation, report:
 

package/templates/commands/deploy-release.md

@@ -20,7 +20,7 @@ Resolve branch names from the project's `CLAUDE.md` **Pipeline Configuration** t
 
 ## Step 1: Read the Release
 
-Query Azure DevOps for all work items tagged with `release-{N}` or assigned to the `Release #{N}` iteration using `search_workitem` or `wit_get_work_items_for_iteration`.
+Query Azure DevOps for all work items tagged with `release-{N}` or assigned to the `Release #{N}` iteration using `search_workitem` or `wit_work_item` (action `list_for_iteration`).
 
 Present the release contents:
 
@@ -179,7 +179,7 @@ Cherry-picking commits for Release #{N}:
    - **targetRefName**: `refs/heads/<target-environment-branch>`
    - **title**: `Release #{N} → {Environment}`
    - **description**: List all work items included with their IDs and titles, and — under a `Scripts to run` heading — any deployment scripts found in Step 3b, so whoever merges sees them without opening the work items
-3. Link all work items to the PR via `wit_link_work_item_to_pull_request`
+3. Link all work items to the PR via `wit_work_item_link_write` (action `link_to_pull_request`)
 
 ## Step 8: Pick Who Verifies Each Group (before the merge)
 

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

@@ -230,9 +230,9 @@ Render every Markdown section to HTML first — Azure DevOps description and acc
 
 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.
+1. **Update the parent item** — one `mcp__azure-devops__wit_work_item_write` (action `update`) call with every changed field. Never include `System.State` for a Feature.
 2. **Update existing children** (verdict `Update`) — one call per story, points and `Custom.Order` in the same call as the text changes. If points were set on a story still at or before `Dev Ready`, set `System.State` = `Dev Ready` in that same call.
-3. **Create added children** — `mcp__azure-devops__wit_create_work_item` with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
+3. **Create added children** — `mcp__azure-devops__wit_work_item_write` (action `create`) with description, acceptance criteria, `Custom.Order`, agreed `Microsoft.VSTS.Scheduling.StoryPoints`, and `System.AssignedTo` copied from the Feature if it has an assignee. Then link each to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse`), then move pointed ones to `Dev Ready` in a follow-up call.
 4. **Re-order** any story whose only change is `Custom.Order` — one call each, touching that field alone.
 5. **Retire** stories the user approved — set `System.State` = `Removed`, or remove the parent link, whichever the user chose. **Never delete a work item.**
 6. **Post comments** (if the user said yes) via `mcp__azure-devops__wit_work_item_comment_write` — one short comment per edited item saying what changed and why, and naming the Feature edit that drove it (e.g. `Scope updated via edit of AB#6240: acceptance criteria 2 reworded to cover SSO; re-ordered from wave 3 to wave 2.`).

package/templates/commands/implement.md

@@ -32,7 +32,7 @@ The description and acceptance criteria fields may contain embedded images (scre
 
 ### Comments
 
-Read the work item comments via `wit_list_work_item_comments`. Comments often contain clarifications, scope changes, or additional requirements added after the work item was created. Incorporate any relevant information from comments into your understanding of the work item.
+Read the work item comments via `wit_work_item` (action `list_comments`). Comments often contain clarifications, scope changes, or additional requirements added after the work item was created. Incorporate any relevant information from comments into your understanding of the work item.
 
 ## Step 2: Summarize and Confirm
 
@@ -188,12 +188,14 @@ Remember the `BASE_BRANCH` — you will need it for the PR step.
 
 ### Move the Work Item to Active
 
-Once the branch is created, move the work item (User Story, Bug, Hot Fix, or other single work item — never a Feature) to `Active` via `wit_update_work_item`:
+Once the branch is created, move the work item (User Story, Bug, Hot Fix, or other single work item — never a Feature) to `Active` via `wit_work_item_write` (action `update`):
 - **path**: `/fields/System.State`
 - **value**: `Active`
 
 If the work item is already `Active`, skip the update. If the project's process template does not have an `Active` state (the update call returns an invalid-state error), fall back in this order: `In Progress` → `Doing` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
 
+After the update, **read the work item back** (`wit_work_item`, action `get`) and confirm `System.State` actually changed. If it didn't, say so explicitly — do not proceed reporting the item as in progress when the board still shows it otherwise.
+
 ### Ensure an Open Child Task Exists
 
 The child **Task** is where hours live: Step 10 closes it and logs the hours worked when the PR goes up. So an implementation run must never proceed without one — if there's nothing to close, nothing gets logged.
@@ -264,7 +266,7 @@ Create it? (yes / edit / skip)
 - `edit` → ask what to change (title or hours), revise, re-show, ask again
 - `skip` → continue without a Task, and **warn** that Step 10 will have no Task to close and no hours will be logged for this story
 
-On `yes`, create it with `mcp__azure-devops__wit_create_work_item`:
+On `yes`, create it with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **workItemType**: `Task`
 - **title**: `{PREFIX} - Implement: {short summary of the story}` — reuse the parent's product prefix (`COM`, `PAY`, `CDA`, …), extracted from the parent's title
@@ -275,7 +277,7 @@ On `yes`, create it with `mcp__azure-devops__wit_create_work_item`:
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if the value is an identity object). If the parent is unassigned, leave it unset rather than failing.
   - `System.State` — `Active`, since implementation is starting right now (fall back to the template's in-progress equivalent, or leave it at the default and note it)
 
-Then link it as a child of the work item with `mcp__azure-devops__wit_add_child_work_items` (or `wit_work_items_link` with `System.LinkTypes.Hierarchy-Forward`, parent → task).
+Then link it as a child of the work item with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or `wit_work_item_link_write` (action `link`) with `System.LinkTypes.Hierarchy-Forward`, parent → task).
 
 If the create or link call fails, report it and ask whether to implement without a Task or stop. Don't silently continue — the user needs to know hours won't be tracked.
 
@@ -387,9 +389,9 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
    - **targetRefName**: `refs/heads/{BASE_BRANCH}` (the branch captured in Step 4)
    - **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`
+3. Link the PR to the work item via `wit_work_item_link_write` (action `link_to_pull_request`)
 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`:
+5. **Move the work item to `Code Review`** via `wit_work_item_write` (action `update`):
    - **path**: `/fields/System.State`
    - **value**: `Code Review`
 
@@ -452,7 +454,7 @@ For each task being processed, prompt for completed hours:
 
 **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 in a **single** `wit_update_work_item` call per task:
+Once the user has answered, update each task in a **single** `wit_work_item_write` (action `update`) call per task:
 - `Microsoft.VSTS.Scheduling.CompletedWork` → the agreed value
 - `Microsoft.VSTS.Scheduling.RemainingWork` → `0`
 - `Microsoft.VSTS.Scheduling.OriginalEstimate` → only if it is still empty; set it to the agreed completed hours so the Task isn't left with no estimate at all. Never overwrite an estimate that's already there — the gap between estimate and actual is the useful signal.

package/templates/commands/plan-backlog.md

@@ -27,7 +27,7 @@ If the user types `list`, call `mcp__azure-devops__core_list_projects` and prese
 
 ## Step 2: Query the Backlog
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` to find candidate stories. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) to find candidate stories. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -55,7 +55,7 @@ and stop.
 
 ## Step 3: Filter Out Stories That Already Have Child Tasks
 
-For each candidate from Step 2, fetch the work item with `mcp__azure-devops__wit_get_work_item` expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
+For each candidate from Step 2, fetch the work item with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
 
 Present a one-line summary of what was skipped:
 
@@ -175,7 +175,7 @@ Approve? (yes / edit / skip / cancel-all)
 
 ### 5e. Create the child task
 
-Create the approved task with `mcp__azure-devops__wit_create_work_item`:
+Create the approved task with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **project**: the chosen project
 - **workItemType**: `Task`
@@ -187,7 +187,7 @@ Create the approved task with `mcp__azure-devops__wit_create_work_item`:
   - `System.AreaPath` — copy from the parent
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if its `System.AssignedTo` value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
 
-Then link the new task as a child of the parent with `mcp__azure-devops__wit_add_child_work_items` (or fall back to `wit_work_items_link` with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
+Then link the new task as a child of the parent with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or fall back to `wit_work_item_link_write` (action `link`) with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
 
 If the create or link call fails, report the failure and ask the user whether to continue with the next story or abort the loop.
 

package/templates/commands/plan-sprint.md

@@ -44,7 +44,7 @@ and stop.
 
 ## Step 3: Query the Sprint
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` using the **literal iteration path** from Step 2:
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) using the **literal iteration path** from Step 2:
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -73,7 +73,7 @@ and stop.
 
 ## Step 4: Filter Out Items That Already Have Child Tasks
 
-For each candidate from Step 3, fetch the work item with `mcp__azure-devops__wit_get_work_item` expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
+For each candidate from Step 3, fetch the work item with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. If the item has any `System.LinkTypes.Hierarchy-Forward` relation pointing at a `Task`, mark it as **already broken down** and skip it.
 
 Present a one-line summary of what was skipped:
 
@@ -196,7 +196,7 @@ For unpointed items, the header line reads `(no points — estimated from descri
 
 ### 6e. Create the child task
 
-Create the approved task with `mcp__azure-devops__wit_create_work_item`:
+Create the approved task with `mcp__azure-devops__wit_work_item_write` (action `create`):
 
 - **project**: the chosen project
 - **workItemType**: `Task`
@@ -208,7 +208,7 @@ Create the approved task with `mcp__azure-devops__wit_create_work_item`:
   - `System.AreaPath` — copy from the parent
   - `System.AssignedTo` — copy from the parent (pass the parent's `uniqueName` / email if its `System.AssignedTo` value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
 
-Then link the new task as a child of the parent with `mcp__azure-devops__wit_add_child_work_items` (or fall back to `wit_work_items_link` with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
+Then link the new task as a child of the parent with `mcp__azure-devops__wit_work_item_write` (action `add_child`) (or fall back to `wit_work_item_link_write` (action `link`) with link type `System.LinkTypes.Hierarchy-Forward` from parent → task).
 
 If the create or link call fails, report the failure and ask the user whether to continue with the next item or abort the loop.
 

package/templates/commands/quote-backlog.md

@@ -91,7 +91,7 @@ If the user types `list`, call `mcp__azure-devops__core_list_projects` and prese
 
 ## Step 2: Query the Backlog
 
-Run a WIQL query via `mcp__azure-devops__wit_query_by_wiql` to find candidate items. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
+Run a WIQL query via `mcp__azure-devops__wit_query` (action `wiql`) to find candidate items. "Backlog" means items at the **root iteration path** (not assigned to any sprint).
 
 ```sql
 SELECT [System.Id], [System.Title], [System.State],
@@ -203,7 +203,7 @@ For each item in the batch, do all of 3a–3e before presenting anything. Collec
 
 ### 3a. Fetch the full work item
 
-Fetch with `mcp__azure-devops__wit_get_work_item` expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
+Fetch with `mcp__azure-devops__wit_work_item` (action `get`) expanding `relations`. Capture: title, type, description, acceptance criteria, tags, `System.CreatedBy` (display name + unique name — needed for the comment draft), child items, and any linked PRs, commits, or branches.
 
 ### 3b. Completeness review
 
@@ -368,8 +368,8 @@ Approve? (all / numbers e.g. "1,2,4" / edit N / skip N / apply rewrite N / cance
 
 Only for approved items, in batch order:
 
-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. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_update_work_item`. Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
+1. **Set Story Points and move to Dev Ready** (items with a proposed number): in one `mcp__azure-devops__wit_work_item_write` (action `update`) 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. **Send unquotable User Stories back to Design Review** (approved `User Story` items with **no** proposed points, where the blocker is missing information): set `System.State` = `Design Review` via `mcp__azure-devops__wit_work_item_write` (action `update`). Do this **before** posting the comment in step 4, so the creator's notification arrives with the item already back in their queue. Rules:
 
    - **`User Story` only.** Do not attempt this on a `Bug` or a `Hot Fix` — those types have no `Design Review` state, so the update fails at runtime in the middle of the batch. They take step 3 instead.
    - Only from `Design Approved` — **never move an item backward past the design stage.** An item at `Dev Ready`, or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), keeps its state; note it in the summary instead.
@@ -387,8 +387,8 @@ Only for approved items, in batch order:
    - Skip items whose only finding is **needs to be split** — nothing is missing, so no tag.
    - Touch no other field — points stay empty; assignee, iteration, and state stay as they are.
 
-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.
+4. **Post the comment** (items with an approved draft): add it with `mcp__azure-devops__wit_work_item_comment_write` (action `add`) (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_work_item_write` (action `update`), 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, 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.
 

package/templates/commands/quote.md

@@ -111,7 +111,7 @@ After displaying the estimate, ask the user: *"Want me to set Story Points = {n}
 
 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:
+When the user agrees, in the **same** `wit_work_item_write` (action `update`) 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`, `Testing`, `Staging`, `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.
@@ -134,7 +134,7 @@ In the CSI Development process template, `Bug` and `Hot Fix` have **no design st
 
 > *"I can't size this until {what's missing}. Want me to move AB#{id} back to Design Review so it's out of the next `/quote-backlog` sweep until the creator responds?"*
 
-**Wait for the user.** Only update the work item if they say yes. Then set `System.State` = `Design Review` with `mcp__azure-devops__wit_update_work_item`. Rules:
+**Wait for the user.** Only update the work item if they say yes. Then set `System.State` = `Design Review` with `mcp__azure-devops__wit_work_item_write` (action `update`). Rules:
 
 - **`User Story` only** — never a Bug, Hot Fix, Feature, or Task. A Bug takes 5b; the update would fail on it anyway.
 - **Never move an item backward past the design stage.** Only from `Design Approved`; if it's already `Dev Ready` or anything at `Active` or later (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready for Staging`, `Staging`, `Ready to Deploy`, …), leave the state alone and say so — someone is already working on it, and a state bounce there does real damage.
@@ -146,7 +146,7 @@ In the CSI Development process template, `Bug` and `Hot Fix` have **no design st
 
 > *"I can't size this until {what's missing} — and a Bug has no design state to send it back to. Want me to tag AB#{id} `needs-info` so it drops out of the next `/quote-backlog` sweep? Removing the tag is what re-queues it — a reply alone leaves it excluded, though `/quote-backlog`'s stale-tag audit will surface it."*
 
-**Wait for the user.** Only update the work item if they say yes. Then add the tag with `mcp__azure-devops__wit_update_work_item`. Rules:
+**Wait for the user.** Only update the work item if they say yes. Then add the tag with `mcp__azure-devops__wit_work_item_write` (action `update`). Rules:
 
 - **Append to `System.Tags`, never replace it.** Take the current tag list captured in Step 1, append `needs-info`, and write the whole semicolon-separated list back. Writing the field bare wipes tags someone else set — `release-{N}`, triage labels, scope hints.
 - Already tagged `needs-info` → no-op; say it's already there.

package/templates/commands/rework.md

@@ -36,13 +36,13 @@ Save the PR's `creationDate` as `LAST_PR_DATE` — everything after this timesta
 
 ### New Comments
 
-Read the work item comments via `wit_list_work_item_comments`. Filter to only comments created **after** `LAST_PR_DATE`. These contain the rework feedback.
+Read the work item comments via `wit_work_item` (action `list_comments`). Filter to only comments created **after** `LAST_PR_DATE`. These contain the rework feedback.
 
 For each new comment, check for embedded images (`<img>` tags with `src` URLs pointing to Azure DevOps attachments). **Download and view every embedded image** using WebFetch — they often contain screenshots of bugs, visual issues, or annotated UI showing what needs to change.
 
 ### Description & Acceptance Criteria Changes
 
-Read the work item revisions via `wit_list_work_item_revisions`. Check if the **description** or **acceptance criteria** fields were modified **after** `LAST_PR_DATE`.
+Read the work item revisions via `wit_work_item` (action `list_revisions`). Check if the **description** or **acceptance criteria** fields were modified **after** `LAST_PR_DATE`.
 
 - If changed: extract the **current** description and acceptance criteria, and note what was added or modified
 - If unchanged: still read the current description and acceptance criteria — a comment may reference something that was in the original requirements but missing from the implementation
@@ -236,7 +236,7 @@ Enter the estimated hours for this task (press enter to accept {n}):
 
 If the user provided hours (suggested or overridden):
 
-1. Call `mcp__azure-devops__wit_create_work_item`:
+1. Call `mcp__azure-devops__wit_work_item_write` (action `create`):
    - **workItemType**: `Task`
    - **title**: `Rework AB#{id} — round {N}`
    - **fields**: JSON Patch document setting:
@@ -262,8 +262,9 @@ If the user provided hours (suggested or overridden):
      - `System.AreaPath` — same as the parent
      - `System.IterationPath` — same as the parent
      - `System.AssignedTo` — same as the parent (copy the parent's `System.AssignedTo` value; pass the `uniqueName` / email if the parent's value is an identity object). If the parent is unassigned, leave this field unset rather than failing.
+     - `System.State` — `Active`, since the rework starts right now (fall back to the template's in-progress equivalent, or leave it at the default and note it). A rework Task left at `New` while the work is underway misreports the board.
 
-2. Link the new Task as a child of the parent work item via `wit_work_items_link`:
+2. Link the new Task as a child of the parent work item via `wit_work_item_link_write` (action `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
@@ -282,6 +283,18 @@ 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.
 
+### Move the Work Item to Active
+
+Once you are on the branch, move the work item (User Story, Bug, Hot Fix, or other single work item — **never** a Feature) to `Active` via `wit_work_item_write` (action `update`):
+- **path**: `/fields/System.State`
+- **value**: `Active`
+
+Rework restarts implementation, so the item must leave `Code Review` / `Rework` and go back to in-progress for the duration of this round — Step 12 hands it back to `Code Review` when the fixes are pushed. Without this the item sits in a review state while it is actively being worked, and the board lies.
+
+If the work item is already `Active`, skip the update. If the project's process template does not have an `Active` state (the update call returns an invalid-state error), fall back in this order: `In Progress` → `Doing` → leave the current state and warn the user that the state could not be advanced automatically. Do not silently swallow the error.
+
+After the update, **read the work item back** (`wit_work_item`, action `get`) and confirm `System.State` actually changed. If it didn't, say so explicitly — do not proceed reporting the item as in progress when the board still shows it otherwise.
+
 ## Step 7: Implement
 
 1. **Implement** the rework using backend and/or frontend agents according to the approved plan
@@ -375,9 +388,9 @@ Wait for the user's response before proceeding. Do NOT push until confirmed.
 ## Step 12: Push and Update
 
 1. Push the changes: `git push`
-2. **Do not post a rework summary comment.** Do not add a summary of what changed to the work item Discussion (`wit_add_work_item_comment`) or as a PR thread. The pushed commits and the PR diff are the record of what changed — a prose summary duplicates them and clutters the work item. If the reviewer left specific PR comment threads, reply on those threads directly (that is what `/resolve-feedback` and `/fix-review` do); otherwise post nothing.
+2. **Do not post a rework summary comment.** Do not add a summary of what changed to the work item Discussion (`wit_work_item_comment_write` (action `add`)) or as a PR thread. The pushed commits and the PR diff are the record of what changed — a prose summary duplicates them and clutters the work item. If the reviewer left specific PR comment threads, reply on those threads directly (that is what `/resolve-feedback` and `/fix-review` do); otherwise post nothing.
 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`:
+4. **Move the work item back to `Code Review`** via `wit_work_item_write` (action `update`):
    - **path**: `/fields/System.State`
    - **value**: `Code Review`
 
@@ -440,7 +453,7 @@ For each task being processed, prompt for completed hours:
 
 **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`:
+Once the user has answered, update each task via `wit_work_item_write` (action `update`):
 - `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)

package/templates/commands/track.md

@@ -49,7 +49,7 @@ Deployed to:
 Catch these up? (yes/no)
 ```
 
-If the user says yes, set `System.State` on each lagging item to the expected state via `wit_update_work_item` — never backward, never on a Feature or Task — and report `Was → Now`.
+If the user says yes, set `System.State` on each lagging item to the expected state via `wit_work_item_write` (action `update`) — never backward, never on a Feature or Task — and report `Was → Now`.
 
 ## If Pipeline (e.g., `/track pipeline` or `/track build`):