@chris1807/claude-kit 2.1.29 → 2.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.29",
+  "version": "2.1.31",
   "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/implement.md

@@ -1,13 +1,15 @@
 Implement work item AB#$ARGUMENTS. Follow this workflow:
 
-## Ultracode (scaled to the change)
+## Ultracode (opt-in — ask the user)
 
-This command orchestrates its analysis phases with the `Workflow` tool, but **scaled to the size of the work** — `/implement` is the daily driver and spans one-line config tweaks to full features, so it does not blanket-fan-out the way `/rework` does. The slash command runs in the main loop, which has the `Workflow` tool.
+This command **can** orchestrate its analysis phases with the `Workflow` tool, but only if the user opts in. The user is asked once, as part of the Step 2 confirmation, whether to use Ultracode effort for this run. Do not fan out before that answer, and do not silently decide for the user.
 
-The rule:
+- **If the user says yes:** apply the fan-out rules below — review (Step 8) runs as the find → adversarially-verify pipeline, and exploration / per-AC coverage (Steps 3, 7) fan out when the change is non-trivial (a full-stack story, multiple subsystems, or several acceptance criteria; skip the fan-out for a trivial single-file or config change).
+- **If the user says no:** run every phase sequentially in the main loop — same steps, same gates, no `Workflow` calls.
 
-- **Code review (Step 8) always fans out** — the find → adversarially-verify pipeline. Review is bounded by the diff, so cost scales with the change, and review quality matters as much for fresh code as for rework.
-- **Exploration and per-AC coverage (Steps 3, 7) fan out only when the change is non-trivial** — a full-stack story, multiple subsystems, or several acceptance criteria. For a trivial single-file or config change, skip the fan-out and run those steps lean in the main loop. Judge this from the plan in Step 3.
+When recommending a default in the Step 2 prompt, suggest **yes** for multi-subsystem / multi-AC work and **no** for trivial changes.
+
+The remaining rules apply whenever Ultracode is in use:
 - **Never fan out an interactive gate or a write.** Every user prompt (Steps 2, 3-approval, 8-decisions, 9) and every git / work-item mutation (Steps 4, 5, 10) stays in the **main loop**. Workflow agents here are **read-only analysts** — they use MCP read tools, `Read`, and `Grep`, and return structured findings. They do not write code, create/close work items, switch branches, or ask the user anything.
 - **Stay in the loop between phases** — one short workflow per phase, read its results, present/await the user, then continue.
 
@@ -48,13 +50,15 @@ Present a summary of the work item to the user:
 {acceptance criteria — numbered list}
 
 Does this look correct? Do you have any additional context or requirements?
+
+Use **Ultracode effort** for this run? Ultracode fans out exploration, AC-coverage checks, and code review across parallel agents — more thorough, but slower and more token-hungry. (yes / no — suggested: {yes for multi-subsystem / multi-AC work, no for trivial changes})
 ```
 
-**Wait for the user to respond.** Do NOT proceed until the user confirms or provides additional context. If they add context, incorporate it into the plan.
+**Wait for the user to respond.** Do NOT proceed until the user confirms or provides additional context. If they add context, incorporate it into the plan. Record the Ultracode answer — it governs whether the `Workflow` fan-outs in Steps 3, 7, and 8 run at all.
 
 ## Step 3: Explore & Plan
 
-> **Ultracode (non-trivial only):** If the work is full-stack, spans multiple subsystems, or has several acceptance criteria, fan out the exploration with `Workflow` — one read-only agent per subsystem/area, each returning the relevant files and how they relate to the requirements, plus one agent per acceptance criterion reporting what already exists and what's missing. Synthesize into a single plan in the main loop. For a trivial single-file or config change, skip the fan-out and explore directly. Either way, the plan synthesis and the approval gate stay in the main loop.
+> **Ultracode (if opted in, non-trivial only):** If the work is full-stack, spans multiple subsystems, or has several acceptance criteria, fan out the exploration with `Workflow` — one read-only agent per subsystem/area, each returning the relevant files and how they relate to the requirements, plus one agent per acceptance criterion reporting what already exists and what's missing. Synthesize into a single plan in the main loop. For a trivial single-file or config change, skip the fan-out and explore directly. Either way, the plan synthesis and the approval gate stay in the main loop.
 
 1. **Explore** the codebase to map relevant files
 2. **Plan** the implementation approach
@@ -164,11 +168,11 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
    Do not advance to Step 8 with any AC unverified.
 
-   > **Ultracode (non-trivial only):** When the story has several acceptance criteria, fan out this check with `Workflow` — one read-only agent per AC, each returning `{ac, covered: bool, evidence, gap?}`. Collect the results in the main loop and act on any `covered: false`. For a story with one or two ACs, just check them directly.
+   > **Ultracode (if opted in, non-trivial only):** When the story has several acceptance criteria, fan out this check with `Workflow` — one read-only agent per AC, each returning `{ac, covered: bool, evidence, gap?}`. Collect the results in the main loop and act on any `covered: false`. For a story with one or two ACs, just check them directly.
 
 ## Step 8: Code Review
 
-> **Ultracode (always):** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension — correctness/quality, security, Clean Architecture compliance, and CLAUDE.md adherence — each scoped to the diff and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it, and drop any finding the majority refute. Only confirmed findings reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules. The fix/decision loop below stays in the main loop — workflow agents never edit code.
+> **Ultracode (if opted in):** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension — correctness/quality, security, Clean Architecture compliance, and CLAUDE.md adherence — each scoped to the diff and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it, and drop any finding the majority refute. Only confirmed findings reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules. The fix/decision loop below stays in the main loop — workflow agents never edit code.
 
 Review the diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. Review is read-only — it reports findings, you act on them.
 

package/templates/commands/rework.md

@@ -1,10 +1,15 @@
 Rework work item AB#$ARGUMENTS based on feedback received after the last pull request. Follow this workflow:
 
-## Always Use Ultracode
+## Ultracode (opt-in — ask the user)
 
-This command **always orchestrates its analysis-heavy phases with the `Workflow` tool** — you do not wait to be asked, and you do not need the `ultracode` keyword. The slash command runs in the main loop, which has the `Workflow` tool, so fan-out is available throughout.
+This command **can** orchestrate its analysis-heavy phases with the `Workflow` tool, but only if the user opts in. The user is asked once, as part of the Step 3 confirmation, whether to use Ultracode effort for this run. Do not fan out before that answer, and do not silently decide for the user.
 
-What this means in practice:
+- **If the user says yes:** apply the fan-out rules below and the per-step **Ultracode** callouts throughout this document.
+- **If the user says no:** run every phase sequentially in the main loop — same steps, same gates, no `Workflow` calls. Skip the per-step **Ultracode** callouts.
+
+The one exception is Step 2 (gathering feedback), which runs **before** the Step 3 prompt — run it in the main loop regardless; only fan it out if the user already opted in via the `ultracode` keyword in their invocation.
+
+When Ultracode is in use, these rules apply:
 
 - **Fan out the read / analyze / verify work** — gathering feedback (Step 2), exploring the codebase (Step 4), and reviewing + verifying the diff and AC coverage (Steps 9–10) are run as `Workflow` scripts with one agent per independent unit (per comment, per subsystem, per review dimension, per acceptance criterion). Each agent returns **structured findings** via a `schema`; you synthesize the results in the main loop.
 - **Never fan out an interactive gate or a write.** Every user prompt (Steps 3, 4-approval, 5, 10-decisions, 11) and every work-item or git mutation (Step 5 create, Step 6 branch, Step 7 implement, Step 12 push/close) stays in the **main loop**. Workflow agents here are **read-only analysts** — they use MCP read tools, `Read`, and `Grep`, and they return data. They do not create or close work items, switch branches, write code, or ask the user anything.
@@ -27,7 +32,7 @@ Save the PR's `creationDate` as `LAST_PR_DATE` — everything after this timesta
 
 ## Step 2: Gather Rework Feedback
 
-> **Ultracode:** Fan out the gathering with `Workflow` — one agent per new comment (parse its text and **download + view every embedded image** via `WebFetch`), plus one agent analyzing the description / acceptance-criteria revisions since `LAST_PR_DATE`. Each agent returns a structured feedback item (`{source, summary, imageObservations, referencedAC?}`). Synthesize them into the Step 3 list in the main loop. Reading and image analysis are independent per comment — this is the fan-out unit.
+> **Ultracode (if opted in):** Fan out the gathering with `Workflow` — one agent per new comment (parse its text and **download + view every embedded image** via `WebFetch`), plus one agent analyzing the description / acceptance-criteria revisions since `LAST_PR_DATE`. Each agent returns a structured feedback item (`{source, summary, imageObservations, referencedAC?}`). Synthesize them into the Step 3 list in the main loop. Reading and image analysis are independent per comment — this is the fan-out unit.
 
 ### New Comments
 
@@ -72,13 +77,15 @@ Present a summary of the rework feedback to the user. **Every feedback item must
 {description/acceptance criteria changes since last PR, or "No changes to description or acceptance criteria since last PR"}
 
 Does this capture the rework correctly? Any feedback items that should be flagged as scope-creep (separate work item) instead of being addressed here?
+
+Use **Ultracode effort** for this rework? Ultracode fans out exploration, AC-coverage checks, and code review across parallel agents — more thorough, but slower and more token-hungry. (yes / no — suggested: {yes for multi-file / multi-AC rework, no for a small targeted fix})
 ```
 
-**Wait for the user to respond.** Do NOT proceed until the user confirms the AC mapping. If they reclassify any item as scope-creep, drop it from the plan and note it in the final summary. If they add context, incorporate it.
+**Wait for the user to respond.** Do NOT proceed until the user confirms the AC mapping. Record the Ultracode answer — it governs whether the `Workflow` fan-outs in Steps 4, 9, and 10 run at all. If they reclassify any item as scope-creep, drop it from the plan and note it in the final summary. If they add context, incorporate it.
 
 ## Step 4: Explore & Plan
 
-> **Ultracode:** Fan out the exploration with `Workflow` — one read-only agent per subsystem touched by the last PR (and per new area the feedback implies), each returning the relevant files and how they relate to the feedback. In the same pass, fan out **one agent per acceptance criterion** to report whether the current code covers it and what's missing. Synthesize all findings into a single plan in the main loop, then present it. Exploration and per-AC coverage analysis are independent — fan them out; the plan synthesis and the approval gate stay in the main loop.
+> **Ultracode (if opted in):** Fan out the exploration with `Workflow` — one read-only agent per subsystem touched by the last PR (and per new area the feedback implies), each returning the relevant files and how they relate to the feedback. In the same pass, fan out **one agent per acceptance criterion** to report whether the current code covers it and what's missing. Synthesize all findings into a single plan in the main loop, then present it. Exploration and per-AC coverage analysis are independent — fan them out; the plan synthesis and the approval gate stay in the main loop.
 
 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
@@ -240,7 +247,7 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 3. **Environment configuration parity** — if the rework added or changed any key in `appsettings.*.json` or `.env*`, verify every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React — whichever exist in the repo) has a corresponding entry. Present a (key × environment) table. Prompt the user to fill in any missing values (real, placeholder, or empty) **before pushing**, or to explicitly confirm the omission is intentional (e.g., supplied via a pipeline variable group, Key Vault, or App Configuration).
 4. **Acceptance Criteria check** — re-read the work item's full Acceptance Criteria (the same list captured in Step 3). For each AC, identify the test or piece of code that proves it's met. If any AC has no covering test or visible code path, flag it before moving on.
 
-   > **Ultracode:** Fan out this check with `Workflow` — one read-only agent per acceptance criterion, each returning `{ac, covered: bool, evidence, gap?}`. Collect the results in the main loop and act on any `covered: false`.
+   > **Ultracode (if opted in):** Fan out this check with `Workflow` — one read-only agent per acceptance criterion, each returning `{ac, covered: bool, evidence, gap?}`. Collect the results in the main loop and act on any `covered: false`.
 
    ```
    ⚠ AC #{n} ({short form}) has no covering test or clear code path.
@@ -251,7 +258,7 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 ## Step 10: Code Review
 
-> **Ultracode:** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension — correctness/quality, security, Clean Architecture compliance, CLAUDE.md adherence, and regression risk from the rework — each scoped to the files changed since the last PR and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it, and drop any finding the majority refute. Only confirmed findings reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules. The fix/decision loop below stays in the main loop — workflow agents never edit code.
+> **Ultracode (if opted in):** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension — correctness/quality, security, Clean Architecture compliance, CLAUDE.md adherence, and regression risk from the rework — each scoped to the files changed since the last PR and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it, and drop any finding the majority refute. Only confirmed findings reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules. The fix/decision loop below stays in the main loop — workflow agents never edit code.
 
 Review the rework diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. Focus the review on the files changed since the last PR — call out any regression risk introduced by the rework. Review is read-only — it reports findings, you act on them.