@chris1807/claude-kit 2.1.25 → 2.1.27

package/README.md

@@ -28,7 +28,7 @@ Every session Claude learns from your feedback and gets better at helping you sp
 | **Global Agents** | 13 | `~/.claude/agents/` (your machine, all projects) | backend, frontend, legacy (Lucee/CFML), manager, mockup, reviewer, test-runner, build-validator, lint-checker, uat-generator, azure-ops, security-auditor, api-tester |
 | **Project Agents** | 3 | `.claude/agents/` (in the project) | deployer, db-admin, devops-tracker |
 | **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** | 13 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/resolve-feedback`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain` |
+| **Slash Commands** | 13 | `.claude/commands/` (in the project) | `/implement`, `/review`, `/deep-review`, `/resolve-feedback`, `/deploy`, `/create-release`, `/deploy-release`, `/add-to-release`, `/cherry-pick`, `/promote`, `/rollback`, `/status`, `/cleanup-branches`, `/close-orphan-tasks`, `/quote`, `/explain` |
 | **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 |
@@ -637,6 +637,7 @@ Claude reviews for:
 |---------|-------|-------------|
 | `/implement` | `/implement AB#1234` | Read work item → summarize → approve plan → implement → quality checks → UAT → PR |
 | `/review` | `/review 142` | Full code review on a PR with inline comments |
+| `/deep-review` | `/deep-review 142` | Deep, Ultracode-orchestrated review: checks out the branch, builds/tests it, verifies every requirement, checks for regressions, flags out-of-scope changes, then comments + votes |
 | `/resolve-feedback` | `/resolve-feedback 142` | Address unresolved PR comment threads, push fixes, reply + resolve threads |
 | `/deploy` | `/deploy "message"` | Commit, push, trigger pipeline if on environment branch |
 | `/create-release` | `/create-release 23` | Group work items into Release #23 iteration with tags |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chris1807/claude-kit",
-  "version": "2.1.25",
+  "version": "2.1.27",
   "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/deep-review.md

@@ -0,0 +1,196 @@
+Deeply review PR #$ARGUMENTS in the current project — a local, checkout-based, Ultracode-orchestrated version of `/review`. Does everything `/review` does, plus: checks out the branch, verifies every requirement is implemented, confirms nothing else broke, and flags any changes the developer made that fall outside the work item. Follow this workflow:
+
+## Always Use Ultracode
+
+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 is the deep-review counterpart to `/review`: where `/review` reads the PR diff over MCP, `/deep-review` checks the branch out locally and runs a far more exhaustive, multi-agent analysis.
+
+What this means in practice:
+
+- **Fan out the read / analyze / verify work** — rework-context detection (Step 2), per-acceptance-criterion coverage (Step 5), regression analysis (Step 6), scope/unwanted-change detection (Step 7), and the review dimensions (Step 8) are run as `Workflow` scripts with one agent per independent unit (per prior PR, per acceptance criterion, per impacted subsystem, per review dimension). Each agent returns **structured findings** via a `schema`; you synthesize the results in the main loop.
+- **Never fan out an interactive gate, a write, or a vote.** Every user prompt (Steps 7, 9, 10) and every PR mutation — posting comments, voting (Steps 10–11) — stays in the **main loop**. Workflow agents here are **read-only analysts** — they use MCP read tools, `Read`, `Grep`, and `Bash` for read-only inspection (builds, tests, `git diff`), and they return data. They do not post comments, vote, switch branches, write code, or ask the user anything.
+- **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 8): fan out per dimension, then spawn skeptic verifiers per finding and drop findings the majority refute, so only confirmed issues reach the user. Use the `reviewer` agent type for the dimension agents (`agentType: 'reviewer'`) so they inherit its review rules.
+
+If the `Workflow` tool is somehow unavailable, fall back to running each phase sequentially in the main loop — the output is identical, just slower.
+
+## Step 1: Resolve the PR, Work Item, and Branch
+
+Handle `$ARGUMENTS` as a PR id (e.g. `142`).
+
+1. **Read the PR** via `repo_get_pull_request_by_id` — capture the **source branch**, **target branch**, title, description, and status.
+2. **Read the linked work item** and gather the full description and acceptance criteria. Download and view every embedded image in the description / acceptance criteria via `WebFetch` — visual requirements (mockups, expected UI, error states) are part of the spec and you cannot verify "implemented properly" without seeing them.
+3. **Read the full diff** via `repo_get_pull_request_changes` — understand every file the PR touches. This is the canonical list of what the developer changed.
+
+## Step 2: Check Out the Branch Locally
+
+Unlike `/review`, this command works against the real working tree so it can build, test, and inspect the full code — not just the diff hunks.
+
+1. Stash or confirm a clean working tree first. If the working tree is dirty, **stop and tell the user** — do not stash their work without asking.
+2. `git fetch` then `git checkout <source-branch>` and `git pull` to get the exact code under review.
+3. Compute the review diff range against the target branch: `git merge-base <target-branch> HEAD` → use `git diff <merge-base>..HEAD` as the authoritative diff for all later steps. This is more reliable than the MCP diff for local analysis and matches what will actually merge.
+4. Confirm to the user which branch and commit you are reviewing:
+
+   ```
+   Reviewing PR #{id} — {title}
+     Source branch: {source}  @ {short-sha}
+     Target branch: {target}
+     Work item:     AB#{wi} — {wi title}
+     Files changed: {n}
+   ```
+
+If checkout fails (branch deleted after merge, etc.), tell the user and offer to fall back to a diff-only review (the `/review` behavior) instead.
+
+## Step 3: Detect Rework Context — do this BEFORE judging acceptance criteria
+
+A small diff does not mean a small feature. The PR you are reviewing may be a rework that only addresses targeted feedback, while the bulk of the implementation already shipped in earlier PRs. Judging acceptance criteria against the current diff alone will produce false "not met" findings.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per PR linked to the work item, each fetching its details and classifying it. Synthesize in the main loop.
+
+For each PR linked to the work item (via `relations` / artifact links), fetch its details and classify:
+- **This PR** — the one being reviewed.
+- **Prior merged PRs** — `status: completed` and merged before this PR was created. Their changes are already in the target branch.
+- **Prior abandoned PRs** — ignore for acceptance-criteria coverage; their code is not in the target branch.
+
+Also scan the work item comments for rework feedback posted after the most recent prior merged PR. That feedback is what the current PR is expected to address.
+
+Treat the PR as a **rework** if any prior merged PR exists for this work item, OR if the work item has rework feedback comments dated after a prior PR. Otherwise treat it as an **initial PR**.
+
+## Step 4: Build and Test the Checked-Out Branch
+
+Because the branch is local, prove it actually works before judging it — a PR that does not build or whose tests fail is not mergeable regardless of how the code reads.
+
+1. **Build** every affected project with the `build-validator` agent. Record pass/fail and any errors.
+2. **Run the full test suite** with the `test-runner` agent — every unit test in the repo, plus integration tests, not just tests touched by this PR. A failure in an unrelated test is a regression signal for Step 6.
+3. **Run lint** — ESLint and `dotnet format` via the `lint-checker` agent.
+
+Capture the results; do not fix anything (this command is read-only on the code). Build/test/lint failures become findings in the Step 8 summary, flagged **critical**.
+
+## Step 5: Verify Every Requirement Is Implemented — Deep AC Coverage
+
+This is the core of `/deep-review`: confirm **nothing in the spec was missed** and everything was **implemented properly**, not just superficially present.
+
+> **Ultracode:** Fan out with `Workflow` — **one agent per acceptance criterion**. Each agent reads the relevant code in the checked-out tree and returns `{ac, status, evidence, gaps}` where:
+> - `status` ∈ `met-this-pr` | `met-prior-pr` | `partial` | `not-met` | `not-applicable`
+> - `evidence` — the specific file(s)/line(s) and test(s) that prove the AC is satisfied
+> - `gaps` — anything required by the AC (including details only visible in the embedded images) that is missing, stubbed, or only partially done
+>
+> Evaluate coverage against the **cumulative work**, not just this diff:
+> - **Initial PR**: every AC must be satisfied by this PR's diff.
+> - **Rework PR**: an AC may be satisfied by (prior merged PRs already in the target branch) + (this PR's diff). Mark those `met-prior-pr` — do not flag them as missing — but re-check any AC whose area this PR's diff touches, for regression.
+>
+> Collect all results in the main loop. Any `partial` or `not-met` AC is a blocking finding.
+
+For a rework PR with a small diff, also ask the focused question: **does this diff correctly address the rework feedback, and does it avoid regressing the prior implementation?** — not "does this diff implement every AC from scratch?"
+
+## Step 6: Confirm It Didn't Break Other Code — Regression Analysis
+
+Verify the change is safe beyond the lines it touched.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per subsystem or shared component the diff could affect (callers of changed methods, shared DTOs/interfaces, database schema or query shape changes, public API contracts, config/env changes). Each agent returns `{area, impact, risk, evidence}`. Seed the agents with: (a) the full-suite test results from Step 4, (b) the list of changed symbols, and (c) `grep` for usages of every changed public symbol. Synthesize a regression risk table in the main loop.
+
+Specifically check:
+- **Changed shared code** — for every public method/class/interface/DTO the diff modifies, find its other callers and confirm the change is backward-compatible or all callers were updated.
+- **Test fallout** — any failing test from Step 4 in an area this PR didn't intend to change is a regression; surface it as **critical**.
+- **Environment configuration parity** — if the diff adds or changes any key in `appsettings.*.json` or `.env*`, every parallel environment file (Development/Staging/QA/Production for backend; `.env.development`/`.env.staging`/`.env.production`/`.env.example` for React) must have a corresponding entry, or the omission must be called out. Build a (key × environment) table and flag any missing cell as **critical**. A pipeline variable group, Key Vault, or App Configuration counts as a valid source for an environment — verify it exists rather than assume it.
+
+## Step 7: Detect Unwanted / Out-of-Scope Changes — and Confirm With the User
+
+The developer should have changed **only** what the work item requires. Catch anything extra — accidental commits, debug code, unrelated refactors, formatting churn, vendored files, secrets, commented-out blocks, or scope creep.
+
+> **Ultracode:** Fan out with `Workflow` — one agent per changed file (or per logical group of files). Each agent answers: *does this change map to an acceptance criterion or the work item's stated intent?* and returns `{file, mapsToAC, classification, rationale}` where `classification` ∈ `in-scope` | `incidental-ok` (e.g. an unavoidable import or a generated file) | `out-of-scope` | `suspicious` (debug code, leftover TODO, commented-out blocks, stray console/Debug logging, unrelated dependency bumps, large reformat-only diffs). Synthesize in the main loop into a single scope table.
+
+Present every out-of-scope or suspicious change to the user and **wait for a decision** — do not silently fold these into the review:
+
+```
+## Out-of-Scope / Unexpected Changes in PR #{id}
+
+These changes do not map to any acceptance criterion on AB#{wi}:
+
+| # | File | What changed | Why it looks out of scope |
+|---|------|--------------|---------------------------|
+| 1 | {file} | {summary} | {e.g. unrelated refactor of an untouched module} |
+| 2 | {file} | {summary} | {e.g. leftover console.log / commented-out code} |
+| 3 | {file} | {summary} | {e.g. dependency bump unrelated to this work item} |
+
+For each, tell me how to treat it:
+- "ok 1,3"        → accepted as intentional; I won't flag them
+- "flag 2"        → I'll raise it as a review finding (severity I'll pick by type)
+- "ok all" / "flag all"
+```
+
+**Wait for the user's response.** Items the user marks `ok` are dropped from the findings. Items marked `flag` (or anything genuinely dangerous — a committed secret, disabled security check, or `.env` with real values — which you should flag as **critical** regardless of the user's call, while telling them why) carry into the Step 8 review summary. If there are no out-of-scope or suspicious changes, state that and skip the prompt.
+
+## Step 8: Review for Quality — find → adversarially-verify
+
+> **Ultracode:** Run the review as a `Workflow` find → verify pipeline. **Find:** fan out one agent per dimension (below), each scoped to the Step 2 diff range and returning structured findings. **Verify:** for each finding, spawn independent skeptic agents prompted to *refute* it (default to refuted if uncertain); drop any finding the majority refute. Only confirmed findings reach the user. Use `agentType: 'reviewer'` for the dimension agents.
+
+Review dimensions:
+- Clean Architecture boundaries (Domain has no infrastructure dependencies)
+- Tenant/`organizationId` enforcement on all database queries
+- Missing unit or integration tests for new code
+- `any` types in TypeScript (should be properly typed)
+- Security issues (OWASP Top 10, hardcoded secrets, SQL/NoSQL injection, exposed PII)
+- Error handling (are exceptions caught appropriately?)
+- Naming conventions and code style consistency
+- Breaking changes or backwards compatibility issues (cross-reference Step 6)
+- **CLAUDE.md compliance** — sensitive-data rules, work-item prefix conventions, branching, anything the project's CLAUDE.md mandates
+
+Fold in the carried-over findings from Steps 4 (build/test/lint), 5 (AC gaps), 6 (regressions, env parity), and 7 (flagged out-of-scope changes).
+
+## Step 9: Draft the Comments and Summary
+
+**Draft (do not post yet) the inline comments** for every confirmed finding. For each, capture: file path, line number, severity, and the exact comment body.
+
+**Draft (do not post yet) the PR-level summary comment** with:
+- **PR type**: Initial PR or Rework (and if rework, the prior merged PR numbers and the rework feedback addressed)
+- **Build / Test / Lint**: pass/fail from Step 4
+- Overall assessment (ready to merge / needs changes)
+- Count of issues by severity (critical / warning / suggestion)
+- **Acceptance criteria checklist** — each item marked `met (this PR)` / `met (prior PR #N)` / `partial` / `not met` / `not applicable`, with the evidence or gap from Step 5
+- **Regression assessment** — from Step 6 (impacted areas + result)
+- **Out-of-scope changes** — what was found and how it was dispositioned in Step 7
+- **Rework feedback checklist** (rework PRs only) — each item addressed / not addressed
+- Test coverage assessment
+
+## Step 10: Preview Everything and Wait for Approval
+
+**Preview every comment to me and wait for approval before posting anything to the PR.** Show:
+
+```
+Deep review drafted — nothing has been posted to PR #{id} yet.
+
+## Inline comments ({count})
+1. {file}:{line} [{severity}] — {comment body}
+2. ...
+
+## PR summary comment
+{full summary body as it will appear on the PR}
+
+Reply with one of:
+- "approve" → post all inline comments and the summary exactly as shown above
+- "skip"    → post nothing
+- "edit <number>: <new text>" or "skip <numbers>" → revise/drop specific items, then I'll re-preview before posting
+```
+
+**Wait for my response. Never post any comment to the PR until I reply "approve".** If I edit or skip individual items, apply the changes and re-preview the full set before asking again. "skip" with no numbers means post nothing at all — move directly to Step 11 without posting.
+
+## Step 11: Post and Vote
+
+If I approved, post the inline comments and the summary to the PR. If I skipped, post nothing. Either way, then ask me:
+
+```
+{Comments posted to PR #{id}. | No comments posted (skipped).}
+- PR type: {Initial | Rework of prior PR(s) #N, #M}
+- Build/Test/Lint: {pass | fail — detail}
+- X critical issues
+- Y warnings
+- Z suggestions
+- Acceptance criteria: A met this PR, B met in prior PRs, C partial, D not met
+- Regressions: {none | detail}
+- Out-of-scope changes: {none | E accepted, F flagged}
+- Rework feedback (if rework): G/H addressed
+
+Approve, Request Changes, or skip the vote?
+```
+
+Wait for my response before submitting any vote on the PR. Then restore the user's original branch if you switched away from it in Step 2 (tell them before doing so).

package/templates/commands/implement.md

@@ -1,5 +1,18 @@
 Implement work item AB#$ARGUMENTS. Follow this workflow:
 
+## Ultracode (scaled to the change)
+
+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.
+
+The rule:
+
+- **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.
+- **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.
+
+If the `Workflow` tool is unavailable, run each phase sequentially in the main loop — the output is identical, just slower.
+
 ## Step 1: Read the Work Item
 
 Read the work item from Azure DevOps via MCP. Extract:
@@ -41,6 +54,8 @@ Does this look correct? Do you have any additional context or requirements?
 
 ## 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.
+
 1. **Explore** the codebase to map relevant files
 2. **Plan** the implementation approach
 
@@ -140,11 +155,24 @@ Run a build check **before** any other quality checks. Use the `build-validator`
 
    Present a (key × environment) table. For every missing cell, prompt the user for a value (real, placeholder, or empty) **before creating the PR**. The PR should not be opened until every environment file is accounted for, or the user explicitly confirms the omission is intentional (e.g., the key is supplied via a pipeline variable group, Key Vault, or App Configuration for that environment).
 
+4. **Acceptance Criteria check** — re-read the work item's full Acceptance Criteria. 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:
+
+   ```
+   ⚠ AC #{n} ({short form}) has no covering test or clear code path.
+     Add coverage now, or call this out to the user before UAT.
+   ```
+
+   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.
+
 ## Step 8: Code Review
 
-Spawn the `reviewer` agent to review the diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. The agent is read-only — it reports findings, you act on them.
+> **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.
+
+Review the diff for quality, security, Clean Architecture compliance, and CLAUDE.md adherence. Review is read-only — it reports findings, you act on them.
 
-Present the findings to the user grouped by severity:
+Present the confirmed findings to the user grouped by severity:
 
 ```
 ## Code Review Findings
@@ -161,11 +189,11 @@ Present the findings to the user grouped by severity:
 Address must-fix items? (yes / select / skip)
 ```
 
-- `yes` → fix every must-fix item, then re-run the reviewer agent on the updated diff
-- `select` → ask which items to address; fix only those, then re-run the reviewer agent
+- `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
 - `skip` → proceed without fixes (only allowed if there are no must-fix items, or the user explicitly overrides)
 
-Loop until the reviewer 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.
+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.
 
 ## Step 9: UAT Gate
 

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -48,7 +48,11 @@ Ultracode is **opt-in**. It is on only when a system-reminder confirms it, when
 
 Short, single-query operations (`/status`, `/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. `/plan-backlog` uses it opt-in (only when ultracode is on).
+**`/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` 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`.
+
+**`/plan-backlog` uses it opt-in** — only when ultracode is on.
 
 ### Sensitive Data Policy