@chris1807/claude-kit 2.3.10 → 2.3.12

package/README.md

@@ -700,7 +700,7 @@ Claude reviews for:
 | `/promote` | `/promote main dev` | PR to promote all code to the next branch in the chain (`main → dev → test → staging → prod`) → ask who verifies → advance + assign on a green pipeline |
 | `/rollback` | `/rollback AB#1234 prod` | Revert specific commits on an environment via PR |
 | `/track` | `/track release 24` | Check status of a release, pipeline, work item, or environment; flags work items whose state lags their environment |
-| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft — you sign in once in the browser window) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment on the work item (never a state change). Environments: `local`, `dev`, `test`, `staging` |
+| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft — you sign in once in the browser window) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment on the work item (never a state change). Environments: `local` (starts the API and client if they aren't running, and posts no comment), `dev`, `test`, `staging` |
 | `/repro` | `/repro AB#1234 [env] [--as=<user>] [--verify]` | Follow a bug's repro steps in a real browser. Before a fix: confirm it reproduces (with intermittency counts) and list the code to read. After the fix is deployed: prove it's gone, checked against a control run on a build without the fix. Mode is picked from where the fix commits are; posts a result comment (never a state change) |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose one child task with hours per story |
 | `/plan-sprint` | `/plan-sprint [project] [--next]` | Sweep the current sprint (or the next one with `--next`) for stories/bugs with no child tasks → propose one child task with hours per item |

package/package.json

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

@@ -221,18 +221,46 @@ No commits at all → `No commits found referencing this work item — nothing t
 
 ### For `local`
 
-No commit or pipeline gate — you are testing the working tree. Instead, probe the local App URL. If nothing answers:
+No commit or pipeline gate — you are testing the working tree. Instead, make sure the app is running there, and **start whatever isn't**. Nobody should have to open two terminals before `/qa` will run.
 
+**Which tree.** Serve the current directory, unless `git worktree list` shows the item's branch (`*AB#<id>-*`) checked out in a sibling worktree. Then serve that worktree instead, and say so. Check whether the chosen tree contains the item's commits (`git log --grep="AB#<id>"` on its `HEAD`). If not, warn but continue. The user may be mid-implementation, which is a legitimate reason to run `/qa local`.
+
+**1. Probe.** Probe the local App URL, and the API URL if the row has one. Any HTTP status means the server is up, even a 404 or 401. Only `000` (refused or timed out) means it is down:
+
+```bash
+curl -sk -o /dev/null -w '%{http_code}' --max-time 3 "{url}"
 ```
-Nothing is listening on {local-url}.
 
-/qa doesn't manage dev servers — start the app first:
-  {the project's start commands, e.g. `dotnet run --project src/API` and `npm run dev`}
+If everything answers, proceed and record `already running` for each server. You can't tell which tree a server you didn't start is serving, so say once: `Reusing the servers already running — make sure they're serving {tree}.`
+
+**2. Find the start command** for each server that is down. Use the `**Local start:**` block in `## Environment URLs` if the project has one. Otherwise infer it:
+
+- **API** → `Glob("**/Properties/launchSettings.json")`, skipping `bin/`, `obj/`, and test projects. Pick the profile whose `applicationUrl` contains the API URL's port. The command is `dotnet run --project {csproj} --launch-profile {profile}`.
+- **Client** → `Glob("**/package.json")`, skipping `node_modules`. Pick the package whose `scripts` has `dev` (else `start`) and whose dev-server port matches the App URL's port. The port comes from `vite.config.*`, the script itself, or the framework default. Use the package manager named by its lockfile.
+
+If there is exactly one candidate, use it, and after the run suggest saving it as a `**Local start:**` block. If there are none, or more than one, ask the user and list the candidates. Never guess between two APIs.
+
+**Check where the client sends API calls**, whether you started it or not. Grep the client's dev-mode env file (`.env.development`, `.env.local`) for the single base-URL key, and echo **only that value**. If it is an absolute URL other than the local API URL, warn: `The local client calls {value}, not the local API — backend changes in this tree won't be exercised.` Then continue.
+
+**3. Start it in the background**, from the chosen tree, with Bash `run_in_background`. Never start it in the foreground: a dev server doesn't exit, so the call hangs until it times out. Start the API first, because the client usually proxies to it. If the client folder has no `node_modules` (a fresh worktree never does), install first: `npm ci` when there's a lockfile, `npm install` otherwise. Use the equivalent command for pnpm or yarn.
+
+**4. Wait until it answers.** Wait with `Monitor`, using an until-loop on the step 1 probe. Never use a foreground `sleep`. Allow 3 minutes for the API, because a first `dotnet run` builds, and 90 seconds for the client. Watch the background task too. If it exits before the URL answers, the start failed, so stop:
 
-Then re-run /qa AB#{id} local.
 ```
+Couldn't start the {API | client} for /qa local.
+
+  {command}   (in {dir})
+  {exited with code {n} | didn't answer on {url} within {timeout}}
 
-Also check whether the working tree actually contains the item's commits (`git log --grep="AB#<id>"` on `HEAD`). If not, warn but continue — the user may be mid-implementation, which is a legitimate reason to run `/qa local`.
+Last lines of its output:
+  {up to 20 lines}
+
+Fix it and re-run /qa AB#{id} local, or start it yourself — /qa reuses a running server.
+```
+
+Omit any output line that carries a connection string, key, or token, because dev servers sometimes log their configuration. `address already in use` means something else holds the port. `lsof -iTCP:{port} -sTCP:LISTEN` names it. Say what it is and stop. **Never kill a process you didn't start.**
+
+**5. Leave them running.** Servers started by `/qa` stay up for the rest of the session, so a re-run or `/repro … local` reuses them. Record each one's background task id for the report. Stop them (`TaskStop`) only when the user asks. They end with the session anyway.
 
 ## Step 6: Scope the Affected Screens, Then Get Approval
 
@@ -267,6 +295,7 @@ Target: {environment} — {app-url}
 Role: {role} ({USERNAME_VAR} | you'll sign in yourself in the browser window | Microsoft, unattended from {USERNAME_VAR})
 Impersonating: {persona} ({role}) | {search term} — ad-hoc user, READ-ONLY run | none
 Build: {n} of {n} commits on `{branch}`, {pipeline} run {id} green
+       | local working tree {dir} — API {started by /qa | already running}, client {started by /qa | already running}
 Baseline for attributing failures: {baseline-env} — {baseline-url}
 
 Screens the story touched:
@@ -326,7 +355,8 @@ Only filter 1's output can drive a `FAIL` verdict. A run that finds nothing but
 ```
 QA — AB#{id}: {title}
 {type} · {state} · {environment} — {app-url}
-Build: {pipeline} run {id} · succeeded · commit {sha7}
+Build: {pipeline} run {id} · succeeded · commit {sha7}  |  local working tree {dir} · commit {sha7}
+Local servers: API {started by /qa (task {id}) | already running}, client {…} — the ones /qa started are still running; say "stop servers" to stop them
 Signed in as: {role} ({from USERNAME_VAR | signed in by you | Microsoft, from USERNAME_VAR}) — value not shown
 Impersonating: {persona | search term} as {role} | none
 Screens tested: {n} · {route list}
@@ -363,10 +393,13 @@ Screens tested: {n} · {route list}
 
 Verdict: PASS | PASS WITH FINDINGS | FAIL | INCOMPLETE
 Work item state unchanged — `Ready for Staging` is yours to set.
+Local run — nothing posted to AB#{id}.        ← `local` only; Step 9 is skipped
 ```
 
 ## Step 9: Comment on the Work Item
 
+**`local` skips this step.** Draft nothing, preview nothing, ask nothing, and don't read the item's comments to look for an earlier run. The run ends at the Step 8 report. The comment exists to record a result at a build other people can reach, for whoever later sets `Ready for Staging`. A local run tests one developer's working tree, often with uncommitted changes, so it would record a build that nobody else can open. Ask about a comment only on `dev`, `test`, or `staging`. If the user asks you to post a local result anyway, run this step as written.
+
 Draft the comment, preview it, and **wait**. Before drafting, check the item's existing comments for a prior `/qa` result on the same commit SHA — three runs should not leave three near-identical comments. If one exists: `A /qa comment already exists for commit {sha7} ({date}). Post an updated one anyway? (yes / skip)`.
 
 > **Why this comment is not the redundant kind.** `/rework` deliberately posts no summary comment, because the commits and the diff are already the record of what changed. A QA result duplicates nothing: it is the outcome of *executing* the software at a specific build in a specific environment, which exists in no diff, no PR, and no pipeline log. It is precisely the evidence the person who later sets `Ready for Staging` needs. Don't delete this step by applying the `/rework` rule uniformly.

package/templates/commands/repro.md

@@ -58,7 +58,7 @@ Find the fix's commits the way `/qa` Step 5a does: linked PRs → `lastMergeComm
 | some | not all | **reproduce** — the fix exists but isn't fully on {environment}, so this run confirms the bug on the old build |
 | some | all | **verify-fix** |
 
-For `local`, also count it as verify-fix when the current branch matches `*AB#<id>-*` and the working tree has uncommitted changes — that is a fix in progress. Remind the user that the running dev server must be serving this working tree.
+For `local`, also count it as verify-fix when the current branch matches `*AB#<id>-*` and the working tree has uncommitted changes — that is a fix in progress. A server that `/qa`'s local step starts already serves this tree. If it reuses one that was already running, remind the user that it must be serving this working tree.
 
 **Overrides.** `--reproduce` always wins. `--verify` on a target that lacks some fix commits is refused: verifying a fix that isn't deployed only tests the old build.
 
@@ -70,7 +70,7 @@ Run /repro AB#{id} {environment} to confirm the bug on this build, or verify whe
 fix is: {environments whose branch has every commit, or "nowhere yet"}.
 ```
 
-**Verify-fix on `dev` / `test` / `staging`** → also run `/qa` **Step 5b**. The pipeline that deployed the fix must be green. Being merged is not being deployed. **`local`, either mode** → run `/qa` Step 5's `local` probe. Reproduce mode on a deployed environment needs no pipeline gate, because it tests whatever is there.
+**Verify-fix on `dev` / `test` / `staging`** → also run `/qa` **Step 5b**. The pipeline that deployed the fix must be green. Being merged is not being deployed. **`local`, either mode** → run `/qa` Step 5's `local` section. It starts the API and client if they aren't already running. Reproduce mode on a deployed environment needs no pipeline gate, because it tests whatever is there.
 
 **Pick the control** — verify-fix only. The control is what tells *fixed* apart from *these steps never triggered it*. Take the first one of these that applies:
 
@@ -233,7 +233,7 @@ Next: {REPRODUCED → `/implement AB#{id}`
 
 ## Step 9: Comment on the Work Item
 
-Draft the comment, preview it, and **wait**, exactly as in `/qa` Step 9. Before drafting, check the existing comments for a `/repro` result with the **same mode and commit**. If one exists: `A /repro {mode} comment already exists for commit {sha7} ({date}). Post an updated one anyway? (yes / skip)`.
+Draft the comment, preview it, and **wait**, exactly as in `/qa` Step 9. `/qa` skips its comment on `local`, but `/repro` does not, on any environment. Before drafting, check the existing comments for a `/repro` result with the **same mode and commit**. If one exists: `A /repro {mode} comment already exists for commit {sha7} ({date}). Post an updated one anyway? (yes / skip)`.
 
 This comment matters more than `/qa`'s, because the next `/repro` reads it. A `REPRODUCED` here becomes the control that lets a later verify-fix say `FIXED` rather than `FIXED — UNCONFIRMED`. So **always include the script and the signature** — they are what make two runs comparable.
 

package/templates/infrastructure/CLAUDE-WORKFLOW.md

@@ -395,7 +395,7 @@ All deployment and release operations are available as slash commands:
 | `/rollback` | `/rollback AB#1234 prod` | Revert commits on an environment |
 | `/track` | `/track release 24` | Check release, pipeline, environment, or work item status; flags work items whose state lags their environment |
 | `/where` | `/where AB#1234` | Show which environment branches contain a work item's commits |
-| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment (never a state change) |
+| `/qa` | `/qa AB#1234 [env] [--as=<user>]` | Verify the item is fully deployed with a green pipeline → open the app in a real browser → sign in (app login form, or Microsoft) and optionally impersonate a user → full regression of the screens the story touched → pass/fail comment, except on `local` (never a state change) |
 | `/repro` | `/repro AB#1234 [env] [--as=<user>]` | Follow a bug's repro steps in a real browser. Before the fix: confirm it reproduces and point at the code to read. After the fix is deployed: prove the bug is gone, against a control run on a build without the fix → result comment (never a state change) |
 | `/plan-backlog` | `/plan-backlog [project]` | Sweep backlog for Dev Ready stories with points and no tasks → propose child tasks with hours |
 | `/plan-sprint` | `/plan-sprint [project] [--next]` | Sweep the current sprint (or the next one with `--next`) for stories/bugs with no child tasks → propose one child task with hours per item |
@@ -482,6 +482,10 @@ Add this to your project's `CLAUDE.md` — **above the `## Claude Kit Workflow`
 | test | Test | https://test.myapp.example.com | https://test.api.myapp.example.com |
 | staging | Staging | https://staging.myapp.example.com | https://staging.api.myapp.example.com |
 
+**Local start:** (optional — paths from the repo root)
+- API: `dotnet run --project src/API/API.csproj --launch-profile https`
+- Client: `npm run dev` in `Client/`
+
 **Sign-in:** `form` at `/login` — app-issued JWT, no SSO. Signed-in landing: `/dashboard`.
 
 **Test accounts** — each developer sets the values on their own machine; never write a password here.
@@ -506,6 +510,7 @@ Add this to your project's `CLAUDE.md` — **above the `## Claude Kit Workflow`
 - **There is no `prod` row, deliberately.** `/qa` and `/repro` refuse production: an unattended run signs in and clicks through live member data.
 - **Include the rows below the one you test.** The row immediately below the target serves the pre-change build. That is how `/qa` tells a regression this story caused from a bug that was already there, and how `/repro` runs its *control*: it proves the steps still trigger the bug on a build without the fix, so a clean run on the fixed build means **fixed**, not *never triggered*.
 - **App URL is required; API URL is optional** — it is used to attribute a failing network call to the backend rather than the screen.
+- **`Local start:`** is optional. On `local`, `/qa` and `/repro` probe the local row's URLs and start any server that doesn't answer. They run it in the background from the working tree under test, wait for it to come up, and leave it running for the rest of the session. A server that is already running is reused, never restarted. Without this block, the commands are inferred: the API from the `Properties/launchSettings.json` profile whose `applicationUrl` has the API port, and the client from the `package.json` with a `dev` (else `start`) script on the App URL's port. Add the block when inference picks the wrong project or finds more than one.
 - **`Sign-in:`** starts with the method, then optional prose: the login route, the landing page, and an element that only exists once you're signed in.
   - `` `form` `` — the app's own login form, with no MFA. If the developer has set the role's credential variables, the `qa` agent fills the form in itself. If not, the developer signs in by hand in the browser window — see Test accounts below.
   - `` `microsoft` `` — Entra ID / MSAL redirect. Name the app's sign-in button and the signed-in marker. **By default the person running the command signs in by hand**, once, in the Chromium window Playwright opens. MFA is fine, and no credential enters any transcript. Playwright MCP keeps a persistent browser profile, so later runs reuse that session until it expires. For a fully unattended run, give the role's row credential variables **and** state on the `Sign-in:` line that the account is a cloud-only, **MFA-exempt** QA account. The agent then types them into the Microsoft page itself.