@chris1807/claude-kit 2.3.8 → 2.3.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.3.8",
+  "version": "2.3.9",
   "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/agents/global/backend.md

@@ -2,7 +2,7 @@
 name: backend
 description: Writes .NET 10/C# backend code following Clean Architecture across Domain, Application, Infrastructure, and API layers. Handles controllers, services, interfaces, DTOs, and repositories (MongoDB + SQL Server).
 tools: Read, Write, Edit, Glob, Grep, Bash
-model: inherit
+model: sonnet
 ---
 
 # Backend Developer

package/templates/agents/global/frontend.md

@@ -2,7 +2,7 @@
 name: frontend
 description: Writes React/TypeScript frontend code with MUI 6, Redux Toolkit, React Hook Form, and TanStack Query. Implements UI matching the HTML mockups.
 tools: Read, Write, Edit, Glob, Grep, Bash
-model: inherit
+model: sonnet
 ---
 
 # Frontend Developer

package/templates/commands/autopilot.md

@@ -26,7 +26,7 @@ Autopilot executes `/implement`'s steps, so read them first: `.claude/commands/i
 Run implement.md from Step 0 through Step 11, or F1 through F8 for a Feature. **This file wins every conflict with implement.md.** Three overrides apply throughout:
 
 1. **Gates resolve without asking.** Where implement.md says to wait, ask, or prompt, or offers a `(yes / no / …)` choice, apply that gate's row in the Gate Table. For a prompt the table doesn't list, take the answer implement.md suggests (its "suggested", "recommended", or "press enter to accept" value). If it suggests none, take the option that changes the least and is easiest to undo. Log the decision either way.
-2. **Ultracode is on.** Invoking `/autopilot` is the opt-in. Use the `Workflow` tool wherever implement.md's Ultracode callouts apply, at the scale they set: fan out for non-trivial work, stay lean for a one-file change. implement.md's Ultracode rules hold unchanged. Workflow agents are read-only analysts, and every write stays in the main loop.
+2. **Ultracode is off, always.** Autopilot never calls the `Workflow` tool, whatever the size of the change, and skips every Ultracode callout in implement.md. An unattended run multiplies cost the most, so it runs lean. implement.md's **Model Tiers** still apply: implementers run on Sonnet, and the main loop takes a piece over when one gets stuck.
 3. **The run ends one of three ways:** a PR ready for review, a draft PR with open items (**Unfinished Work**), or a **Hard Stop**. There is no other outcome.
 
 Open with this block, then start Step 0 without waiting:
@@ -54,8 +54,8 @@ Each row is a prompt in implement.md and the decision autopilot makes instead. L
 | 0d | The worktree is already locked. | Hard Stop. Another session may be editing it, and two unwatched edit streams in one folder can't be untangled afterward. If the lock is stale: `git worktree unlock "{WT}"`. |
 | **Work item and plan** | | |
 | 2 | Summary: "Does this look correct? Any added context?" | Print the summary, with the effort recommendation as information only, and continue. Resolve gaps with the **Ambiguity Rule**. |
-| 2 | Use Ultracode? | Yes (override 2). |
-| 3 | Approve this plan? | Run the Architect Review as an independent agent (see **Independent Checks**), apply what it finds, print the final plan, and continue. The plan goes in the PR thread. |
+| 2 | Use Ultracode? | No (override 2). |
+| 3 | Approve this plan? | Run the Architect Review (see **Independent Checks**), apply what it finds, print the final plan, and continue. The plan goes in the PR thread. |
 | **Branch and Task** | | |
 | 4 | The open Task has no estimate. Proposed hours OK? | Set the proposed hours on `OriginalEstimate` and `RemainingWork`. |
 | 4 | More than one open Task. Which one? | The one in `Active`, then the one titled `{PREFIX} - Implement…`, then the lowest id. Leave the others alone and name them in the final report. |
@@ -75,7 +75,7 @@ Each row is a prompt in implement.md and the decision autopilot makes instead. L
 | **Feature** | | |
 | F1 | No implementable child stories. Implement the Feature itself? | Yes, through Steps 2–11, if the Feature's own description or AC describes buildable work. Otherwise Hard Stop. |
 | F2 | Feature summary and wave plan. Look correct? | Print it and continue. Stories with no `Custom.Order` run in the final wave, in id order. |
-| F4.1 | Approve this wave's plan? | Run the Architect Review agent on the combined wave plan, apply what it finds, and continue. |
+| F4.1 | Approve this wave's plan? | Run the Architect Review on the combined wave plan, apply what it finds, and continue. |
 | F4.2 | Create these Tasks? | Yes, for every story in the wave. |
 | F6 | Combined UAT | As Step 9, grouped by story. |
 
@@ -96,8 +96,8 @@ Each human check in `/implement` gets a stand-in that doesn't share the author's
 
 | `/implement` relies on | Autopilot uses |
 |---|---|
-| The user reading the plan | The Architect Review as a separate `Workflow` agent on **every** plan, trivial or not (implement.md's Ultracode variant). It gets the work item, the AC, and the draft plan, but never the reasoning behind the plan, and it reads the code itself. Apply each finding unless it grows the scope or contradicts an AC. Log every finding you decline, with the reason. |
-| The user choosing which review findings to fix | The find → adversarially-verify review, on every round. Only verified findings count. |
+| The user reading the plan | The Architect Review in the main loop on **every** plan (implement.md's non-Ultracode variant). Answer each question from the code, not from the plan's own prose. Apply each finding unless it grows the scope or contradicts an AC. Log every finding you decline, with the reason. |
+| The user choosing which review findings to fix | One `reviewer` agent (Sonnet) on the diff, launched with the `Agent` tool so it doesn't share the author's reasoning. Give it the work item, the AC, and the worktree path, but not the plan's justification. Before fixing a finding, check it against the code yourself and drop it if it doesn't hold; that check is what "verified" means below. Later rounds review only the diff the fixes introduced. |
 | The user doing UAT | Every AC traced to a test or code path (Step 7.4), the full test suite including any E2E specs the repo has, and the UAT checklist handed to the reviewer in the PR. |
 
 ## Environment Config Rule (Step 7.3)

package/templates/commands/implement.md

@@ -16,6 +16,19 @@ The remaining rules apply whenever Ultracode is in use:
 
 If the `Workflow` tool is unavailable, run each phase sequentially in the main loop — the output is identical, just slower.
 
+## Model Tiers (token efficiency)
+
+Most of a run's tokens go to subagents re-reading their context on every turn, not to the code they write. The main loop runs on the session model and does the work that needs frontier judgment. Everything else runs on Sonnet, which costs half as much per input and output token:
+
+| Work | Model | How |
+|---|---|---|
+| Summary, plan, synthesis, gates, conflict resolution, fixing review findings | Session model | The main loop |
+| Architect Review (Step 3) | Session model | Omit `model` on its `Workflow` agent. It is the one analysis pass where a stronger reviewer changes the outcome |
+| Exploration, per-AC coverage, review finders, review verifiers | Sonnet | `model: 'sonnet'` on every other `Workflow` `agent()` call. `agentType: 'reviewer'` is already Sonnet |
+| Implementation | Sonnet | The `backend` and `frontend` agents are Sonnet by frontmatter. A `general-purpose` implementer gets `model: "sonnet"` on its `Agent` call |
+
+**Escalation keeps quality up.** The plan the implementer follows was written by the main loop, and the code is reviewed afterward. If an implementer reports it is blocked, or the same build or test failure survives two of its attempts, stop delegating that piece: the main loop fixes it directly. Don't relaunch a Sonnet agent on a problem it has already failed twice.
+
 ## Step 0: Set Up the Ticket's Workspace
 
 Developers run several Claude Code sessions against the same repo at once, one per ticket. If every session `git checkout`s in the folder it started in, they clobber each other's working tree. So each ticket gets its own **git worktree** in a sibling folder, `../{repo}-AB{id}` (e.g. `../CSIPay-AB5373`), and every later step runs there. The folder the session started in is never checked out, committed to, or edited.
@@ -406,7 +419,7 @@ Remember the Task ID. Step 10 closes it.
 
 **In a worktree**, install frontend dependencies first — only if the approved plan touches the frontend. A new worktree has no `node_modules`, so run `npm install` in its client folder (`cd "{WT}/{client folder}" && npm install`). A backend-only plan skips the install; `dotnet build` restores its own packages. Steps 6–7 then skip the uninstalled client folder and report it as `frontend skipped — untouched by this change, not installed in the worktree` rather than failing on it.
 
-1. **Implement** using backend and/or frontend agents according to the approved plan — each agent is told to work only in `WT` (Step 0f)
+1. **Implement** using backend and/or frontend agents according to the approved plan — each agent is told to work only in `WT` (Step 0f). They run on Sonnet; see **Model Tiers** for when the main loop takes a piece over
 2. **Write the unit tests** listed in the plan's "Unit Tests" section alongside the implementation — not after
 3. **Generate mockup** if there are UI changes
 
@@ -443,7 +456,9 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 ## Step 8: Code Review
 
-> **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.
+> **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 **one** independent skeptic agent (`model: 'sonnet'`) prompted to *refute* it, and drop the finding if it does. 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.
+>
+> **Re-reviews are scoped to the fix.** After fixing findings, review only the diff the fixes introduced (`git diff` against the commit reviewed last time), not the whole change again. The first review already covered everything else.
 
 Review the diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. Review is read-only — it reports findings, you act on them.
 
@@ -464,8 +479,8 @@ Present the confirmed findings to the user grouped by severity:
 Address must-fix items? (yes / select / skip)
 ```
 
-- `yes` → fix every must-fix item, then re-run the review (the Step 8 find → verify workflow) on the updated diff
-- `select` → ask which items to address; fix only those, then re-run the review workflow
+- `yes` → fix every must-fix item, then re-run the review (the Step 8 find → verify workflow) on the fix diff only
+- `select` → ask which items to address; fix only those, then re-run the review workflow on the fix diff only
 - `skip` → proceed without fixes (only allowed if there are no must-fix items, or the user explicitly overrides)
 
 Loop until the review reports no must-fix items, or the user explicitly accepts remaining findings. Do not proceed to UAT with unresolved must-fix items unless the user overrides.
@@ -699,7 +714,7 @@ For each wave in ascending order:
      git -C "{WT}" worktree add "{scratchpad}/wt-{story-id}" -b "story/AB#{story-id}-{sanitized-title}" "{feature-branch}"
      ```
 
-     Launch **one implementation agent per story, all in a single message** so they run concurrently (`backend`/`frontend`/`general-purpose` per the approved plan; if a story needs both backend and frontend work, give one agent the whole story rather than splitting it). Each agent's prompt must include: the approved plan for its story, the story's full AC, its worktree path, and these rules — work **only** inside your worktree, implement the plan plus its unit tests, run the tests you added, commit to the story branch, and report what you changed. Agents never push, never create PRs, never touch work items, and never ask the user anything.
+     Launch **one implementation agent per story, all in a single message** so they run concurrently (`backend`/`frontend` per the approved plan; if a story needs both backend and frontend work, give one `general-purpose` agent the whole story with `model: "sonnet"` rather than splitting it — see **Model Tiers**). Each agent's prompt must include: the approved plan for its story, the story's full AC, its worktree path, and these rules — work **only** inside your worktree, implement the plan plus its unit tests, run the tests you added, commit to the story branch, and report what you changed. Agents never push, never create PRs, never touch work items, and never ask the user anything.
    - **Merge back (main loop):** merge each story branch into the feature branch in the Feature's worktree (`git -C "{WT}" merge --no-ff "story/…"`), resolving conflicts yourself using both stories' plans as the guide. Then `git worktree remove` and delete the story branch. Merge in `Custom.Order`-then-ID order so conflict resolution is deterministic.
 3. **Wave gate:** run Step 6 (build validation) and Step 7.1–7.2 (full test suite + lint) on the merged feature branch, in the Feature's worktree. Fix failures before starting the next wave — the next wave branches from this merged, green state.
 

package/templates/commands/rework.md

@@ -15,10 +15,23 @@ When Ultracode is in use, these rules apply:
 - **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 0 worktree, Step 5 create, Step 6 branch, Step 7 implement, Step 12 push/PR/close, Step 13 cleanup) 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.
 - **Give every Workflow agent the ticket's worktree path** (Step 0) — that is where the code under analysis lives, not the folder the session started in.
 - **Stay in the loop between phases.** Run one `Workflow` per phase, read its results, present/await the user as the steps require, then launch the next phase's workflow. This is several short workflows in sequence — not one monolithic run that tries to swallow the approval gates.
-- **Review uses the canonical find → adversarially-verify pipeline** (Step 10): fan out per dimension, then spawn skeptic verifiers per finding and drop findings the majority refute, so only confirmed issues reach the user.
+- **Review uses the canonical find → adversarially-verify pipeline** (Step 10): fan out per dimension, then spawn one skeptic verifier per finding and drop the findings it refutes, so only confirmed issues reach the user.
 
 If the `Workflow` tool is somehow unavailable, fall back to running each phase sequentially in the main loop — the output is identical, just slower.
 
+## Model Tiers (token efficiency)
+
+Most of a run's tokens go to subagents re-reading their context on every turn, not to the code they write. The main loop runs on the session model and does the work that needs frontier judgment. Everything else runs on Sonnet, which costs half as much per input and output token:
+
+| Work | Model | How |
+|---|---|---|
+| Feedback synthesis, plan, gates, fixing review findings | Session model | The main loop |
+| Architect Review (Step 4) | Session model | Omit `model` on its `Workflow` agent. It is the one analysis pass where a stronger reviewer changes the outcome |
+| Feedback gathering, exploration, per-AC coverage, review finders, review verifiers | Sonnet | `model: 'sonnet'` on every other `Workflow` `agent()` call. `agentType: 'reviewer'` is already Sonnet |
+| Implementation | Sonnet | The `backend` and `frontend` agents are Sonnet by frontmatter. A `general-purpose` implementer gets `model: "sonnet"` on its `Agent` call |
+
+**Escalation keeps quality up.** The plan the implementer follows was written by the main loop, and the code is reviewed afterward. If an implementer reports it is blocked, or the same build or test failure survives two of its attempts, stop delegating that piece: the main loop fixes it directly. Don't relaunch a Sonnet agent on a problem it has already failed twice.
+
 ## Step 1: Find the Latest Pull Request
 
 Handle `$ARGUMENTS` as either `1234` or `AB#1234` — strip the `AB#` prefix when calling the MCP API. If it also says "work in place" or "no worktree", strip that and remember it for Step 0.
@@ -415,7 +428,7 @@ After the update, **read the work item back** (`wit_work_item`, action `get`) an
 
 **In a worktree**, install frontend dependencies first — only if the approved plan touches the frontend. A new worktree has no `node_modules`, so run `npm install` in its client folder (`cd "{WT}/{client folder}" && npm install`). A backend-only plan skips the install; `dotnet build` restores its own packages. Steps 8–9 then skip the uninstalled client folder and report it as `frontend skipped — untouched by this rework, not installed in the worktree` rather than failing on it.
 
-1. **Implement** the rework using backend and/or frontend agents according to the approved plan — each agent is told to work only in `WT` (Step 0e)
+1. **Implement** the rework using backend and/or frontend agents according to the approved plan — each agent is told to work only in `WT` (Step 0e). They run on Sonnet; see **Model Tiers** for when the main loop takes a piece over
 2. **Write the unit tests** listed in the plan's "Unit Tests" section alongside the implementation — not after. Include any regression test that would have caught the original issue
 3. **Generate mockup** if there are UI changes
 
@@ -444,7 +457,9 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
 ## Step 10: Code Review
 
-> **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.
+> **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 **one** independent skeptic agent (`model: 'sonnet'`) prompted to *refute* it, and drop the finding if it does. 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.
+>
+> **Re-reviews are scoped to the fix.** After fixing findings, review only the diff the fixes introduced (`git diff` against the commit reviewed last time), not the whole change again. The first review already covered everything else.
 
 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.
 
@@ -465,8 +480,8 @@ Present the confirmed findings to the user grouped by severity:
 Address must-fix items? (yes / select / skip)
 ```
 
-- `yes` → fix every must-fix item, then re-run the review (the Step 10 find → verify workflow) on the updated diff
-- `select` → ask which items to address; fix only those, then re-run the review workflow
+- `yes` → fix every must-fix item, then re-run the review (the Step 10 find → verify workflow) on the fix diff only
+- `select` → ask which items to address; fix only those, then re-run the review workflow on the fix diff only
 - `skip` → proceed without fixes (only allowed if there are no must-fix items, or the user explicitly overrides)
 
 Loop until the review reports no must-fix items, or the user explicitly accepts remaining findings. Do not proceed to UAT with unresolved must-fix items unless the user overrides.

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -49,11 +49,11 @@ Ultracode is **opt-in**. It is on only when a system-reminder confirms it, when
 
 Short, single-query operations (`/track`, `/explain`, `/close-orphan-tasks`) do **not** need ultracode — they are already one pass and gain nothing from fan-out. Reach for `Workflow` when the work-list is large and the per-item work is independent.
 
-**`/rework` always uses ultracode** — it does not wait to be asked. It fans out feedback gathering, codebase exploration, per-acceptance-criterion coverage checks, and the find → adversarially-verify review, while keeping every approval gate and write in the main loop.
+**`/implement` and `/rework` ask** — once, at their first confirmation, with a suggestion: yes for multi-subsystem / multi-AC work, no for a small targeted change. When on, they fan out exploration, per-acceptance-criterion coverage, and the find → verify review, while keeping every approval gate and write in the main loop.
 
-**`/implement` uses ultracode scaled to the change** — its code review always fans out (find → adversarially-verify), but exploration and per-AC coverage fan out only for non-trivial / full-stack stories; a one-line config change runs lean. It's the daily driver, so it doesn't blanket-fan-out like `/rework`.
+**`/autopilot` never uses it.** An unattended run is where fan-out costs the most, so it runs lean: the Architect Review runs in the main loop, and one Sonnet `reviewer` agent stands in for the user's review.
 
-**`/autopilot` always uses it**, at `/implement`'s scale — invoking the command is the opt-in. With no human approving the plan or choosing review fixes, the independent Architect Review agent and the find → adversarially-verify review are what stand in for that scrutiny.
+**Model tiers.** In `/implement`, `/rework`, and `/autopilot`, the main loop (your session model) plans, synthesizes, and fixes review findings. Implementers (`backend`, `frontend`) and every Workflow analyst run on Sonnet, except the Architect Review, which stays on the session model. If a Sonnet implementer is blocked or fails the same way twice, the main loop takes that piece over.
 
 **`/plan-backlog`, `/plan-sprint`, and `/quote-backlog` use it opt-in** — only when ultracode is on.