@chris1807/claude-kit 2.1.45 → 2.1.47

package/README.md

@@ -28,7 +28,7 @@ Every session Claude learns from your feedback and gets better at helping you sp
 | **Global Agents** | 10 | `~/.claude/agents/` (your machine, all projects) | backend, frontend, legacy (Lucee/CFML), mockup, reviewer, test-runner, build-validator, lint-checker, azure-ops, security-auditor |
 | **Project Agents** | 2 | `.claude/agents/` (in the project) | deployer, db-admin |
 | **Hooks** | 9 | `.claude/hooks/` (in the project) | Secret blocker, sensitive data blocker (Bash + MCP + output), protected files, auto-format, test suggestions, UAT reminder, self-improve |
-| **Slash Commands** | 23 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/deep-review`, `/resolve-feedback`, `/fix-review`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/plan-backlog`, `/plan-sprint`, `/quote-backlog`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain` |
+| **Slash Commands** | 24 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/deep-review`, `/resolve-feedback`, `/fix-review`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/plan-backlog`, `/plan-sprint`, `/quote-backlog`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain`, `/create-work-item`, `/edit-work-item` |
 | **MCP Servers** | Up to 6 | `.mcp.json` (in the project) | **Azure DevOps** (work items, repos, pipelines, wiki), Playwright, MongoDB/SQL/Postgres, Teams, Stripe, Azure CLI |
 | **Workflow Template** | 1 | Appended to `CLAUDE.md` | Documents the full development process |
 | **Settings** | 1 | `.claude/settings.json` (in the project) | Registers all hooks and MCP servers |
@@ -652,6 +652,8 @@ Claude reviews for:
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated) |
 | `/quote` | `/quote AB#1234` | Estimate a work item in story points (senior-calibrated Fibonacci rubric) |
 | `/explain` | `/explain AB#1234` | Summarize and explain a work item in plain language |
+| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, or User Story — proposes story points (user must agree), creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves |
+| `/edit-work-item` | `/edit-work-item AB#1234 [what to change]` | Revise an existing work item field-by-field. On a Feature, cascades into its child stories — updates, adds, retires, and re-sequences `Custom.Order` waves — with a safety gate on anything already past Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged feature/work branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks --dry-run` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.45",
+  "version": "2.1.47",
   "description": "Claude Code starter kit for Azure DevOps teams — agents, hooks, MCP servers, slash commands, and end-to-end work item → PR → release → deploy workflow automation",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 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.
+This command walks the user through creating a Feature, 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. For a Feature it can also draft and create the child User Stories that make the Feature implementable.
 
 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.
 
@@ -11,20 +11,23 @@ Ask the user:
 ```
 What type of work item do you want to create?
 
-  1. Bug
-  2. User Story
+  1. Bug          — something deployed is behaving wrong
+  2. User Story   — one shippable slice of user-facing behavior
+  3. Feature      — a container for several related user stories
 
-Reply with 1, 2, "bug", or "user story".
+Reply with 1, 2, 3, "bug", "user story", or "feature".
 ```
 
-**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.
+**Wait for the user's response.** Map the answer to `Bug`, `User Story`, or `Feature`. If the user types something else, ask again — do not guess.
+
+If the requirements clearly span several independently shippable slices, say so and recommend `Feature` — but the type is still the user's call.
 
 ## Step 2: Gather Requirements
 
 Ask the user to describe the requirements:
 
 ```
-Describe the {bug | user story} in your own words. Include:
+Describe the {feature | 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
@@ -53,6 +56,38 @@ For each image found, plan to embed it in the final description as an `<img src=
 
 Translate the user's free-form requirements into a structured work item draft. The shape depends on the type:
 
+### For a Feature:
+
+```
+## Draft: {Prefix} - {proposed title}
+
+**Type:** Feature
+
+### Description
+{2–4 sentences describing the capability being delivered and who it serves.
+A Feature is a container — describe the outcome, not the implementation.}
+
+### Business Value
+{Why this is worth building — the problem it removes or the opportunity it opens.}
+
+### Scope
+- {each coherent, independently shippable chunk of work — these become the
+  child User Stories in Step 9}
+- ...
+
+### Out of Scope
+- {anything the user mentioned that shouldn't ride along with this feature}
+
+### Success Criteria
+1. {observable, feature-level outcome that proves the capability landed}
+2. ...
+
+### Open Questions
+- {anything ambiguous that you couldn't infer}
+```
+
+A Feature carries **no story points** and **never moves to `Dev Ready`** — sizing and state live on its child stories. Step 4 is skipped for Features.
+
 ### For a User Story:
 
 ```
@@ -146,7 +181,9 @@ Approve this draft? (yes / suggest changes / cancel)
 
 ## Step 4: Propose Story Points
 
-Every work item this command creates gets a story point estimate — proposed automatically, applied only with the user's agreement.
+**Skip this step entirely for a Feature.** A Feature's size is the sum of its child stories — the Feature itself gets no `StoryPoints` value and stays in `New`. Its stories are pointed in Step 9. Go to Step 5.
+
+For a **Bug** or **User Story**, every work item this command creates gets a story point estimate — proposed automatically, applied only with the user's agreement.
 
 Estimate using the same rubric as `/quote`: the **modified Fibonacci scale** (`1, 2, 3, 5, 8, 13, 21`), calibrated for a **senior developer working with Claude assistance** in a codebase they know. Don't pad for ramp-up, routine architectural decisions, or stack familiarity — only for things a senior cannot shortcut: genuinely novel work, unresolved open questions, cross-team coordination, external dependencies. If the work looks larger than 21 points, recommend splitting the item instead of proposing a number.
 
@@ -167,9 +204,9 @@ Agree? (yes / different number / skip)
 
 Points are never written without the user's explicit agreement.
 
-## Step 5: Offer a Mockup (User Stories only — skip for Bugs)
+## Step 5: Offer a Mockup (User Stories and Features — 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:
+If the work item type is **User Story** or **Feature** 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)
@@ -222,14 +259,17 @@ Before creating anything in Azure DevOps, present a final summary and ask for on
 ## Ready to Create
 
 **Title:**     {Prefix} - {title}
-**Type:**      {Bug | User Story}
+**Type:**      {Feature | Bug | User Story}
 **Project:**   {project}
 {for Bugs:}
 **Priority:**  {n}
 **Severity:**  {n - Label}
 {end for Bugs}
-**Story Points:** {n (agreed) | skipped}
-**Initial State:** {Dev Ready (pointed) | New (no points)}
+{for Features:}
+**Scope items:** {count} — offered as child stories after creation
+{end for Features}
+**Story Points:** {n (agreed) | skipped | n/a — Features aren't pointed}
+**Initial State:** {Dev Ready (pointed) | New (no points) | New (Feature)}
 **Mockup:**    {Embedded | Not requested | Skipped (non-UI)}
 **Images:**    {count} user-supplied image(s) embedded in description
 **Open Questions:** {count}
@@ -278,12 +318,16 @@ Apply this pass to every section (Description, Acceptance Criteria, Steps to Rep
 Call `mcp__azure-devops__wit_create_work_item` with:
 
 - **project**: the chosen project
-- **workItemType**: `Bug` or `User Story`
+- **workItemType**: `Feature`, `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
-  - `Microsoft.VSTS.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped)
+  - `Microsoft.VSTS.Scheduling.StoryPoints` — the points agreed in Step 4 (omit entirely if the user skipped, and **always** for a Feature)
+  - For Features:
+    - Render `Business Value`, `Scope`, `Out of Scope`, and `Success Criteria` into the description. Put `Success Criteria` in `Microsoft.VSTS.Common.AcceptanceCriteria` **only if** the process template exposes that field on Feature — if the create call rejects it, fold the block into the description and retry rather than dropping it.
+    - `Microsoft.VSTS.Common.BusinessValue` — only if the user supplied a number. Never invent one.
+    - Omit `Microsoft.VSTS.Scheduling.StoryPoints` entirely.
   - 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)
@@ -295,7 +339,46 @@ If the `Open Questions` section is non-empty, append it to the description as a
 
 If story points were agreed in Step 4, set `System.State` to `Dev Ready` via `mcp__azure-devops__wit_update_work_item` **after** the item is created (a separate call — new items start in `New`, and some process templates reject a non-initial state in the create call). If the state transition is rejected, report the error and leave the state as-is — don't silently retry through intermediate states. Items created without points stay in `New`.
 
-## Step 9: Confirm
+**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.
+
+## Step 9: Offer Child User Stories (Features only)
+
+Skip this step for Bugs and User Stories.
+
+A Feature is a container — `/implement AB#{id}` on a Feature implements its **child User Stories in `Custom.Order` waves**, so a Feature with no children can't be worked. After the Feature is created, ask:
+
+```
+Draft child user stories for this feature now? (yes / no — I'll add them later)
+```
+
+**Wait for the user.** On `no`, skip to Step 10 and point them at `/plan-backlog` for later.
+
+On `yes`:
+
+1. Turn each bullet from the Feature's **Scope** section into a candidate User Story using the User Story draft shape from Step 3 — plain-language description plus testable acceptance criteria. Keep each one independently shippable; if a bullet is really two stories, split it.
+2. Assign each story a **`Custom.Order`** value. Stories that can be built in parallel share the same number; a story that depends on an earlier one gets a higher number. Start at `1` and increment per wave. This field drives the wave ordering in `/implement` — a story with no value lands in a catch-all wave, so set it on every story.
+3. Propose story points for each using the Step 4 rubric.
+4. Present the whole set for approval at once:
+
+   | # | Order | Proposed Title | Points | Summary |
+   |---|-------|----------------|--------|---------|
+
+   ```
+   Approve these child stories? (yes / change N / drop N / cancel)
+   ```
+
+   **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:
+   - `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
+   - `System.AssignedTo` — copied from the Feature if the Feature has an assignee; otherwise leave unset
+6. Link each story to the Feature as a child via `mcp__azure-devops__wit_work_item_link_write` (`System.LinkTypes.Hierarchy-Reverse` from the story to the Feature).
+7. Move each pointed story to `Dev Ready` in a follow-up update, per the Step 8 rule. **The Feature's state is never changed.**
+
+If a story fails to create or link, report which ones succeeded and which didn't — don't roll back the Feature.
+
+## Step 10: Confirm
 
 After creation, report:
 
@@ -303,11 +386,16 @@ After creation, report:
 Created AB#{id}: {title}
   Project: {project}
   Type: {type}
-  Story Points: {n | not set}
+  Story Points: {n | not set | n/a (Feature)}
   State: {Dev Ready | New}
   URL: {work item URL}
   Mockup attached: {yes / no}
   Open questions: {count}
+{Features only:}
+  Child stories: {n created | none — add them later with /plan-backlog}
+    AB#{id} (order {n}, {p} pts) — {title}
+    ...
+{end Features only}
 
 Next steps:
   /explain AB#{id}     — re-read the item in plain language
@@ -315,4 +403,13 @@ Next steps:
   /implement AB#{id}   — start working on it
 ```
 
+For a **Feature**, use these next steps instead:
+
+```
+Next steps:
+  /explain AB#{id}     — re-read the feature in plain language
+  /plan-backlog        — propose child Tasks for the Dev Ready stories
+  /implement AB#{id}   — implement the child stories in Custom.Order waves
+```
+
 Do not assign the work item, set an iteration, or add tags unless the user explicitly asks — those are downstream decisions.

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

@@ -0,0 +1,237 @@
+Edit an existing Azure DevOps work item. Usage: `/edit-work-item <work-item-id> [what to change]`
+
+This command revises a work item that already exists — title, description, acceptance criteria, points, priority/severity, order. On a **Feature** it treats the Feature and its child User Stories as **one unit**: a change to the Feature's scope cascades into the children, new stories are drafted for new scope, stories that fell out of scope are retired, and `Custom.Order` is re-sequenced so the implementation waves still make sense.
+
+Parse `$ARGUMENTS`:
+- **Work item ID** — accept `AB#1234`, `#1234`, or `1234`. Required. If missing, ask for it and stop.
+- **Change request** — any remaining text is the user's description of what to change (e.g. `/edit-work-item AB#6240 add SSO to the scope, drop the CSV export story`). Optional — if absent, Step 3 asks for it.
+- **`--dry-run`** — do every step including the full change set, but make no writes. Report what would have changed and stop.
+
+## Step 1: Fetch the Work Item
+
+Read the work item with `expand: Relations` so links and children come back. Collect:
+
+- `System.Title`, `System.WorkItemType`, `System.State`, `System.AssignedTo`, `System.Tags`
+- `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`
+- `Microsoft.VSTS.Scheduling.StoryPoints`, `Custom.Order`
+- For Bugs / Hot Fixes: `Microsoft.VSTS.TCM.ReproSteps`, `Microsoft.VSTS.Common.Priority`, `Microsoft.VSTS.Common.Severity`
+- Parent, children, and **linked pull requests** (`ArtifactLink` relations)
+- Comments — recent discussion often explains why a field says what it says
+
+If the work item is not found, report the error and stop.
+
+### If the item is a Feature
+
+Also fetch every child via `wit_work_item` `get_batch` with fields `System.Id`, `System.Title`, `System.WorkItemType`, `System.State`, `System.AssignedTo`, `Custom.Order`, `Microsoft.VSTS.Scheduling.StoryPoints`, `System.Description`, `Microsoft.VSTS.Common.AcceptanceCriteria`. Children are the `System.LinkTypes.Hierarchy-Forward` relations. You need their full text — you cannot judge whether a story still fits the revised scope from its title alone.
+
+## Step 2: Show the Current Item
+
+Present what exists today, so the user is editing against reality and not memory:
+
+```
+## AB#{id}: {title}
+
+**Type:** {type}   **State:** {state}   **Points:** {n | not set}   **Assigned:** {name | unassigned}
+**Linked PRs:** {#id (status), ... | none}
+
+### Description
+{current description, rendered as readable text}
+
+### Acceptance Criteria
+{current AC}
+{for Bugs:}
+**Priority:** {n}   **Severity:** {n - Label}
+{end for Bugs}
+```
+
+For a **Feature**, append the current wave layout:
+
+```
+### Child Stories (current Custom.Order waves)
+
+| Wave | Order | Story | Title | Points | State |
+|------|-------|-------|-------|--------|-------|
+| 1 | 1 | AB#6242 | ... | 3 | Dev Ready |
+| 1 | 1 | AB#6243 | ... | 2 | Dev Ready |
+| 2 | 2 | AB#6244 | ... | 5 | Code Review |
+| 3 | — | AB#6245 | ... | 3 | New |  ← no Custom.Order set
+```
+
+## Step 3: Gather the Change Request
+
+If the user supplied a change request inline, restate your reading of it in one line and move on. Otherwise ask:
+
+```
+What should change on AB#{id}?
+
+Describe it however you like — "the scope should also cover SSO", "tighten AC 3",
+"this is really two stories", "bump severity to 2". You can paste image URLs or
+links; they'll be preserved.
+```
+
+**Wait for the user's response.** Ask at most one targeted clarifying question if the request is ambiguous about *which* field or *which* child it touches.
+
+Scan the response for images and links and preserve them exactly as `/create-work-item` Step 2 describes — an edit must never silently strip an image, attachment URL, or reference link that is already in the description.
+
+## Step 4: Draft the Change Set
+
+Produce a **field-level diff**, not a rewritten item. For every field you propose to touch, show before and after. Fields not listed are not touched.
+
+```
+## Proposed Changes — AB#{id}
+
+**Title**
+  - {current}
+  + {proposed}
+
+**Description**
+  {a readable summary of what's being added, removed, or reworded — not a raw dump}
+
+**Acceptance Criteria**
+  - 3. {removed criterion}
+  + 3. {new criterion}
+  + 4. {added criterion}
+
+**Story Points:** {n} → {m}   ({one-line rationale})
+**Priority / Severity:** {n} → {m}   (Bugs only)
+
+**Unchanged:** {list the fields you deliberately left alone}
+```
+
+Rules for the draft:
+
+- **Preserve, don't regenerate.** Keep existing wording that the change request doesn't touch. Never drop existing `<img>` tags, attachment URLs, or reference links.
+- **Points follow the `/quote` rubric** — modified Fibonacci (`1, 2, 3, 5, 8, 13, 21`), calibrated for a senior developer working with Claude assistance. Only propose a change if the scope actually moved. If the revised item now looks bigger than 21 points, recommend splitting it into a Feature instead of writing the number.
+- **Never point a Feature** and never change a Feature's `System.State`.
+- **Prefix rule holds** — if the title changes, it keeps its `PREFIX - ` prefix from the project's CLAUDE.md table.
+
+### If the item is a Feature — cascade to the children
+
+This is the point of the command. After drafting the Feature's own changes, evaluate **every child story against the revised scope** and classify each one:
+
+| Verdict | Meaning | Action |
+|---------|---------|--------|
+| **Unchanged** | Still correct under the new scope | Leave it entirely alone |
+| **Update** | Still belongs, but its title / description / AC / points no longer match | Draft a field-level diff for it |
+| **Add** | The revised scope introduces work no existing story covers | Draft a new User Story (`/create-work-item` Step 3 shape) with proposed points |
+| **Retire** | The revised scope no longer includes this work | Propose `System.State` = `Removed`, or unlinking from the Feature — user picks |
+| **Split** | The story now carries two independently shippable slices | Propose narrowing the existing story and adding a sibling |
+
+Then **re-sequence `Custom.Order`**, because adding, retiring, or re-scoping stories usually breaks the wave plan:
+
+1. Rebuild the dependency picture across the surviving + added stories: a story that needs another story's work merged first must land in a **later** wave.
+2. Stories with no dependency on each other share a wave (same `Custom.Order` value) so `/implement` runs them in parallel.
+3. Number waves as **consecutive integers starting at 1**, no gaps. Stories that previously had no `Custom.Order` get one now.
+4. **Only write `Custom.Order` where the value actually changes.** A re-sequence that renumbers every story to the same value it already had is not a change — don't issue the write.
+5. Stories already past `Dev Ready` (see the safety gate below) keep their existing order unless the user explicitly says otherwise — moving an in-flight story between waves has no effect on work that's already done and only confuses the record.
+
+Present the cascade as one table, old order → new order:
+
+```
+### Child Story Changes
+
+| Story | Title | Verdict | Order | Points | State | Notes |
+|-------|-------|---------|-------|--------|-------|-------|
+| AB#6242 | ... | Unchanged | 1 | 3 | Dev Ready | — |
+| AB#6243 | ... | Update    | 1 | 2 → 3 | Dev Ready | AC 2 reworded for SSO |
+| AB#6244 | ... | Unchanged | 2 → 2 | 5 | Code Review | in flight — order held |
+| (new)   | ... | Add       | 2 | 5 | → Dev Ready | covers new SSO scope |
+| AB#6245 | ... | Retire    | — | 3 | New | dropped from scope → Removed |
+
+### Resulting Waves
+
+| Wave | Order | Stories |
+|------|-------|---------|
+| 1 | 1 | AB#6242, AB#6243 |
+| 2 | 2 | AB#6244, (new SSO story) |
+```
+
+Show the field-level diff for every story marked **Update**, and the full draft for every story marked **Add**, below the table. The user is approving specific text, not a summary.
+
+## Step 5: Safety Gate — In-Flight Work
+
+Before asking for approval, check the state of everything you propose to write and flag anything that is **past `Dev Ready`** in the workflow (`Active`, `Code Review`, `Ready for Testing`, `Testing`, `Ready to Deploy`, `Deployed`, `Closed`) or has a **linked pull request**.
+
+Editing the acceptance criteria of a story that is already implemented silently invalidates a PR that was reviewed against the old criteria. So for each such item, call it out explicitly:
+
+```
+⚠️  AB#6244 is in **Code Review** with PR #142 open.
+
+Changing its acceptance criteria now means the open PR no longer matches the story.
+  1. Edit it anyway — I'll note the change in a work item comment
+  2. Leave it alone and put the new behavior in a new story
+  3. Use /rework AB#6244 instead — that's the flow built for post-PR changes
+
+Which?
+```
+
+**Wait for the user on each flagged item.** Default to option 2 if the user is vague — adding a story is always recoverable; rewriting an implemented one is not.
+
+Never move an item **backward** through the workflow. If setting points on an item that is already past `Dev Ready`, set the points only, leave the state alone, and say so.
+
+## Step 6: Approve
+
+```
+## Ready to Apply — AB#{id}
+
+**Feature/item changes:** {n} field(s)
+**Child stories:** {a} updated, {b} added, {c} retired, {d} re-ordered, {e} unchanged
+**In-flight items being edited:** {list | none}
+**Post a comment recording this change on each edited item?** {yes | no}
+
+Apply these changes? (yes / edit / cancel)
+```
+
+**Wait for the user.**
+- `yes` → Step 7
+- `edit` → ask which part to revise, revise it, re-show the diff from Step 4, then return here
+- `cancel` → abort with no writes and confirm "Cancelled — nothing was changed."
+
+If `--dry-run` was passed, stop here instead and report the change set as final output. Make no writes.
+
+Default the comment question to **yes** for any item past `New`, and **no** for items still in `New` (nobody has looked at them yet).
+
+## Step 7: Apply
+
+Render every Markdown section to HTML first — Azure DevOps description and acceptance criteria fields do not render Markdown. Use the conversion table and the **emphasis and code spans** rules from `/create-work-item` Step 8: bold the noun phrase carrying each claim, wrap identifiers in `<code>`, use lists for 2+ parallel items, keep `### Headings` as `<h3>`. Preserve existing `<img>` tags exactly.
+
+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.
+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.
+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.`).
+
+Touch no field that wasn't in the approved change set. Assignee, iteration, and tags stay as they are unless the user asked.
+
+If any write fails, stop, report exactly which items were changed and which weren't, and do not retry blindly — a half-applied re-sequence needs the user to see the real state before you try again.
+
+## Step 8: Confirm
+
+```
+Updated AB#{id}: {title}
+  Type: {type}
+  Fields changed: {list}
+  Points: {n → m | unchanged}
+  State: {state} {(unchanged — Features are never moved) | (→ Dev Ready)}
+  URL: {work item URL}
+
+{Features only:}
+  Child stories:
+    updated:   AB#{id} ({what changed})
+    added:     AB#{id} — {title} (order {n}, {p} pts, Dev Ready)
+    retired:   AB#{id} — {title} (Removed)
+    re-ordered: AB#{id} (wave {old} → {new})
+    unchanged: {count}
+
+  Resulting waves: {1: AB#..., AB#... | 2: AB#...}
+{end Features only}
+
+Next steps:
+  /explain AB#{id}     — re-read the item as it now stands
+  /implement AB#{id}   — {implement the child stories in Custom.Order waves | start working on it}
+```
+
+If nothing ended up changing (the user cancelled every proposed edit at the safety gate), say that plainly rather than reporting a successful edit.

package/templates/commands/implement.md

@@ -161,6 +161,78 @@ Once the branch is created, move the work item (User Story, Bug, Hot Fix, or oth
 
 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.
 
+### 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.
+
+Right after moving the work item to `Active`, look at its child Tasks (relations of type `System.LinkTypes.Hierarchy-Forward` whose target's `System.WorkItemType` is `Task`). A Task counts as **open** if its state is **not** `Closed`, `Done`, or `Removed`.
+
+**Never do this for a Feature.** Features don't carry Tasks of their own — the Feature path creates them per child story in F4.
+
+#### If an open child Task already exists
+
+Use it. **Do not create a second one** — one Task per story, always. Two touch-ups, then move on:
+
+- If it's still `New`, move it to `Active` alongside the parent.
+- If `Microsoft.VSTS.Scheduling.OriginalEstimate` is empty, propose hours (below) and, once the user agrees, set both `OriginalEstimate` and `RemainingWork` to that value.
+
+If **more than one** open Task exists, don't guess — list them and ask which one this run should log against. Leave the others alone.
+
+#### If there is no open child Task, create exactly one
+
+This includes the case where child Tasks exist but every one of them is already closed — a closed Task is not somewhere to log new work.
+
+Propose the hours from the parent's Story Points (this mirrors `/plan-backlog` Step 5b — keep the two tables in sync):
+
+| Points | Hour budget |
+|--------|-------------|
+| 1  |  3 hrs  |
+| 2  |  6 hrs  |
+| 3  | 10 hrs  |
+| 5  | 16 hrs  |
+| 8  | 28 hrs  |
+| 13 | 48 hrs  |
+| 21 | 75 hrs  |
+
+Calibrated for a **senior developer** at ~6 productive hours per day — the discount is already in the numbers, so don't apply a second one. Round non-Fibonacci point values up to the nearest row. Add 20–30% for `spike` / `research` / `unknown-stack` tags.
+
+If the work item has **no Story Points**, estimate the hours from the plan just approved in Step 3 — files to create and modify, plus the unit tests listed — using the same senior calibration. Say which basis you used.
+
+Show the proposal and **wait for the user**:
+
+```
+AB#{id} has no open child Task — one is needed to log hours against.
+
+| Task title                                   | Hours |
+|----------------------------------------------|-------|
+| {PREFIX} - Implement: {short summary}        |  16   |
+
+Basis: {n} story points → {n}h  (or: no points — estimated from the approved plan)
+
+Create it? (yes / edit / skip)
+```
+
+- `yes` → create it
+- `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`:
+
+- **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
+- **fields**:
+  - `Microsoft.VSTS.Scheduling.OriginalEstimate` — the agreed hours (as a number)
+  - `Microsoft.VSTS.Scheduling.RemainingWork` — the same value
+  - `System.AreaPath` and `System.IterationPath` — copy from the parent
+  - `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).
+
+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.
+
+Remember the Task ID. Step 10 closes it.
+
 ## Step 5: Implement
 
 1. **Implement** using backend and/or frontend agents according to the approved plan
@@ -275,11 +347,13 @@ Wait for the user's response before proceeding. Do NOT create a PR until confirm
 
    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.
 
-> **PR completion closes the Task only.** When this PR is later completed/merged, only the child **Task** may be closed — never the parent User Story or Bug. Azure DevOps's "Complete associated work items" option transitions *every* linked work item (including the parent this PR is linked to), so do **not** enable it when completing the PR. Close the child Task explicitly instead; the parent stays in `Code Review` until QA/UAT and any sibling Tasks are done.
+> **Only the Task ever gets closed — never the parent.** The child Task is closed here, at PR creation (step 4 above). When the PR is later completed/merged, do **not** enable Azure DevOps's "Complete associated work items" option: it transitions *every* linked work item, including the parent this PR is linked to. The parent User Story or Bug stays in `Code Review` until QA/UAT and any sibling Tasks are done.
 
 ### 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.
+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`).
+
+There should be at least one open Task — Step 4 guarantees it. If there are **no** child Tasks at all (the user chose `skip` in Step 4, or the create call failed), create one now so the work that just shipped is recorded: same fields and prefix convention as Step 4, hours proposed the same way, then close it in the same pass. Say plainly that you're creating it after the fact.
 
 For each child Task, capture:
 - ID, title, state
@@ -330,12 +404,15 @@ 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 in a **single** `wit_update_work_item` 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.
 - `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`.
+Confirm with a summary line per task: `Closed AB#xxxx — {hours}h logged (estimate was {n}h)`.
+
+**The Task closes now, at PR creation — not at merge.** The work is done and the hours are known; waiting until merge means the hours get logged days later, or not at all.
 
 ## Feature Workflow (ordered story waves)
 
@@ -393,6 +470,18 @@ 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.
 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:
+
+     ```
+     Stories in this wave with no open child Task:
+
+     | Story    | Task title                              | Hours | Basis   |
+     |----------|-----------------------------------------|-------|---------|
+     | AB#1235  | COM - Implement: export endpoint        |  10   | 3 pts   |
+     | AB#1236  | COM - Implement: export screen          |  16   | 5 pts   |
+
+     Create these? (yes / edit N / skip N / skip all)
+     ```
    - **Single-story wave** → implement directly on the feature branch in the main loop (Step 5).
    - **Multi-story wave** → isolate each story in its own worktree so parallel agents never clobber each other:
 
@@ -420,6 +509,6 @@ Present **one combined UAT checklist grouped by story** (Step 9 rules). Wait for
 
 1. Push the feature branch and create **one PR**: title `AB#{feature-id}: {feature title}`, source `feature/...`, target `BASE_BRANCH`.
 2. Link the **Feature and every implemented story** to the PR.
-3. Run **Closing Related Tasks** (Step 10) once, covering the child Tasks of every implemented story — one combined table, then the usual per-task hour prompts.
+3. Run **Closing Related Tasks** (Step 10) once, covering the child Tasks of every implemented story — one combined table, then the usual per-task hour prompts. Every story that got a Task in F4 has one to close here; a story whose Task creation was skipped gets one created and closed now, as in Step 10.
 4. Move each implemented story to `Code Review` (same fallback rules as Step 10). **Do not change the Feature's state** — the Feature is a parent container; it advances only when its child stories are verified/closed, not when the PR goes up for review.
-5. The Step 10 PR-completion rule applies unchanged: when the PR merges, only child **Tasks** may be closed — never the stories or the Feature.
+5. The Step 10 closing rule applies unchanged: only child **Tasks** are ever closed — here at PR creation, never the stories and never the Feature. Don't enable "Complete associated work items" when the PR is merged; it would transition the stories and the Feature along with the Tasks.

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -232,7 +232,9 @@ Hot Fix work items follow the same automated checks (build, lint, tests, review)
 
 Running `/implement` on a **Feature** implements its child User Stories in **waves** driven by the `Custom.Order` field: stories sharing the same order value are implemented **in parallel** (one agent per story, each in an isolated git worktree), and waves run sequentially in ascending order so later stories build on earlier ones. All work merges into a single `feature/AB#<id>-...` branch; quality checks, code review, UAT, and one PR happen at the feature level, and every implemented story is linked to that PR. Stories without a `Custom.Order` value run in a final catch-all wave (flagged for confirmation first).
 
-**Work item states:** `/implement` moves the work item to `Active` when implementation starts — for a single work item (User Story, Bug, Hot Fix) right after the branch is created; for a Feature, each child story goes `Active` as its wave begins. When the PR is created, each implemented child **User Story** moves to `Code Review` — the **Feature's state is never changed**. The Feature is a parent container; it advances only as its child stories are verified/closed. When the PR merges, only child **Tasks** are closed — never the stories or the Feature.
+**Work item states:** `/implement` moves the work item to `Active` when implementation starts — for a single work item (User Story, Bug, Hot Fix) right after the branch is created; for a Feature, each child story goes `Active` as its wave begins. When the PR is created, each implemented child **User Story** moves to `Code Review` — the **Feature's state is never changed**. The Feature is a parent container; it advances only as its child stories are verified/closed. Only child **Tasks** are ever closed — never the stories or the Feature.
+
+**Hours live on the Task.** `/implement` will not implement a story that has no open child Task: if there isn't one, it proposes a title and an hour estimate (from the story's points, same mapping `/plan-backlog` uses) and creates it once the user agrees — exactly one per story, inheriting the parent's assignee, area, and iteration. When the PR is created, that Task is closed with the hours worked logged to `CompletedWork` and `RemainingWork` zeroed. Closing happens at **PR creation**, not at merge, so hours are recorded while they're still known. Never enable Azure DevOps's "Complete associated work items" when merging — it transitions the parent too.
 
 #### Slash Commands Reference
 
@@ -240,7 +242,7 @@ All deployment and release operations are available as slash commands:
 
 | Command | Usage | What It Does |
 |---|---|---|
-| `/implement` | `/implement AB#1234` | Summarize work item → approve plan → implement → PR. On a Feature: child stories in `Custom.Order` waves, same-order stories in parallel |
+| `/implement` | `/implement AB#1234` | Summarize work item → approve plan → ensure an open child Task with hours → implement → PR (closes the Task, logs hours). On a Feature: child stories in `Custom.Order` waves, same-order stories in parallel |
 | `/review` | `/review 142` | Automated code review on a PR |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "commit message"` | Commit, push, trigger pipeline |
@@ -255,7 +257,8 @@ All deployment and release operations are available as slash commands:
 | `/plan-sprint` | `/plan-sprint [project]` | Sweep the current sprint for stories/bugs with no child tasks → propose one child task with hours per item |
 | `/quote-backlog` | `/quote-backlog [project]` | Sweep backlog for Design Approved items without points → review completeness, check for duplicates, suggest rewrites, propose points + creator comments (10 at a time, approval-gated). Pointed items move to Dev Ready; items that can't be quoted move back to **Design Review** so the next sweep skips them |
 | `/quote` | `/quote AB#1234` | Estimate story points for one work item; on approval, sets the points and moves the item to Dev Ready. If it can't be estimated, offers to move it back to **Design Review** |
-| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Bug or User Story — proposes story points (user must agree) and creates pointed items in Dev Ready |
+| `/create-work-item` | `/create-work-item [description]` | Interactively draft and create a Feature, Bug, or User Story — proposes story points (user must agree) and creates pointed items in Dev Ready; on a Feature, also drafts its child stories with `Custom.Order` waves |
+| `/edit-work-item` | `/edit-work-item AB#1234 [what to change]` | Revise an existing work item field-by-field. On a Feature, cascades the change into its child stories — updates, adds, retires, and re-sequences `Custom.Order` waves — with a safety gate on anything already past Dev Ready |
 | `/cleanup-branches` | `/cleanup-branches` | Delete merged branches |
 | `/close-orphan-tasks` | `/close-orphan-tasks [scope] [--dry-run]` | Close open Tasks whose parent is Ready to Deploy / Deployed / Closed |