@chris1807/claude-kit 2.2.1 → 2.2.3

package/package.json

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

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