@chamba/claude-extras 0.6.2 → 0.7.0

package/README.md

@@ -20,8 +20,8 @@ Check the MCP server's version the same way: `npx @chamba/mcp --version`.
 
 It installs into `~/.claude/`:
 
-- **Slash commands**: `/ticket`, `/workspace`, `/map`, `/worktrees`, `/orq`, `/recall`, `/vault`
-- **Subagents**: `planner`, `implementer`, `reviewer`, `tester`
+- **Slash commands**: `/ticket`, `/workspace`, `/map`, `/qa`, `/worktrees`, `/orq`, `/recall`, `/vault`
+- **Subagents**: `planner`, `implementer`, `reviewer`, `tester`, `qa`
 - **Hooks**: warn on destructive commands, validate worktree edits
 
 …and registers the `chamba` MCP server in `~/.claude.json`. It never overwrites your
@@ -51,6 +51,7 @@ fast/cheap ones.** These ship pre-configured — you only change what you want.
 | **reviewer** | `claude-opus-4-7` | high | Critical audit; deep reasoning, doesn't need the very latest model. |
 | **implementer** | `claude-sonnet-4-6` | medium | Executes clear specs; speed matters, medium reasoning is enough. |
 | **tester** | `claude-sonnet-4-6` | medium | Tests over already-implemented code; same profile. |
+| **qa** | `claude-opus-4-7` | high | Acceptance QA: reasons about criteria and drives the running app. |
 | **summarizer** | `claude-haiku-4-5` | low | Summaries are mechanical; a fast, cheap model is perfect. |
 | **researcher** | `claude-opus-4-7` | high | Research + synthesis; high reasoning, doesn't need Opus 4.8. |
 
@@ -202,6 +203,39 @@ Re-run it as the project grows — it updates its own notes in place and **never
 note you edited by hand** (it only rewrites notes marked `source: chamba`). It's opt-in;
 on a big monorepo, mapping everything is expensive.
 
+## Acceptance QA with the `qa` agent
+
+For user-facing tickets, the **planner** adds a `## QA plan` to the plan (local seed, test
+users, URLs, login steps, and the expected behaviour per acceptance criterion), and
+`/ticket` runs a final **acceptance-QA** phase: the `qa` subagent validates each criterion
+against the **running app**, not the code. It **adapts to the project** — if the repo has
+Playwright/Cypress (or a browser MCP) it drives the browser; otherwise it runs the repos
+from the worktree, applies the local seed, and co-pilots with you, asking you to log in and
+telling you what to click while you watch. It reports PASS/FAIL per criterion and never
+commits.
+
+Run it on its own to test or re-test without redoing the ticket:
+
+```
+/qa TICKET-123                    # locate the worktree, run the QA plan
+/qa -p ./plans/T-123.md TICKET-123
+```
+
+Backend-only tickets get no QA phase.
+
+**Enabling browser-driven QA (Claude Code).** Cursor has a built-in browser; Claude Code
+doesn't, so add a Playwright MCP — at **user scope** so it leaves no trace in your repo.
+In `~/.claude.json`:
+
+```json
+{ "mcpServers": { "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } }
+```
+
+Run `npx playwright install chromium` once — the browsers land in your **user cache**
+(`~/.cache/ms-playwright`). Both the MCP and the browsers live outside the project;
+nothing is added to your `package.json` or `node_modules`. chamba never bundles or runs a
+browser itself — the `qa` agent uses whatever is available and co-pilots when nothing is.
+
 ## License
 
 MIT

package/assets/agents/planner.md

@@ -19,6 +19,14 @@ map + relevant notes). Produce a concrete, reviewable plan — do not write code
   resolves. Only list questions that would actually change the plan — not
   implementation details the implementer can settle. Never invent scope to paper
   over them.
+- If the ticket is **user-facing** (a UI change or a flow only verifiable in the
+  running app), add a `## QA plan` section so the **qa** agent can validate it:
+  state whether an acceptance-QA phase is needed and why; the **setup** (local
+  seed/fixtures, test users with their roles/context, how to run the app from the
+  worktree, and any E2E/browser tooling the repo already has); and, per acceptance
+  criterion, the URL/entry point, the login steps, and the expected behaviour.
+  Finish with a concrete step-by-step. If the change isn't user-facing, omit the
+  section — don't invent QA for a backend-only change.
 
 Return the plan as structured markdown. The orchestrator runs it through
 `chamba_review_plan` and the reviewer subagent, then resolves any `## Open

package/assets/agents/qa.md

@@ -0,0 +1,44 @@
+---
+name: qa
+description: Acceptance QA — exercises the running app and validates the ticket's acceptance criteria
+---
+
+You are the **qa** agent. You act as a human QA: you validate the ticket's
+acceptance criteria against the **running app**, not against the code. You work
+from the plan's `## QA plan` section and the acceptance criteria. Everything you do
+is **local and non-destructive** — never commit, push, or touch production.
+
+**First, adapt to the project — don't assume a stack.** Inspect the repos in the
+worktree and decide how to run the test by their nature:
+
+- **Browser E2E already in the project** (a `playwright`/`@playwright/test`/`cypress`
+  dependency or config, or a browser MCP available to you) → use it to drive the
+  browser and walk each acceptance criterion, capturing screenshots as evidence.
+- **No E2E tooling** → run the app yourself: start the relevant repos from the
+  worktree in the terminal (their `dev`/`start` scripts, docker-compose, etc.),
+  apply the **local** seed if one is needed, and co-pilot the test with me — give me
+  the exact step-by-step, drive what you can, and tell me precisely what to click and
+  what I should see.
+
+**Keep the repo clean.** If you need a browser and the project has none, prefer a
+Playwright MCP if one is configured — it runs via `npx` and installs its browser to my
+**user cache**, leaving no trace in the repo. You may run `npx playwright install
+chromium` (also user cache) to get the browser. Do NOT add Playwright to the project's
+`package.json` or commit spec files unless I ask; if you write a driver script, put it
+in a temp path outside the repo and delete it when done.
+
+Then:
+
+1. **Set up.** Apply the seed / fixtures the plan calls for (local only), and create
+   the test users with the roles/context it specifies. State exactly what you seeded.
+2. **Run the app** from the worktree and confirm it's up (the URL/entry point).
+3. **Log in.** When the flow needs auth, pause and ask me to log in with the test
+   user (near-final env, manual step). Wait for me — I'm watching.
+4. **Walk each acceptance criterion.** For each one: go to its URL, do the steps, and
+   check the actual behaviour against the plan's expected outcome. Capture evidence
+   (screenshot, response, log).
+5. **Report PASS/FAIL per acceptance criterion** — honestly, with what you observed.
+   Never mark PASS without seeing it. List anything you couldn't test and why.
+
+If the plan has no `## QA plan` and the ticket isn't user-facing, say so and skip —
+don't invent a QA phase.

package/assets/commands/qa.md

@@ -0,0 +1,25 @@
+---
+description: Run acceptance QA for a ticket — validate its acceptance criteria against the running app
+argument-hint: "[-p <plan-path>] <ticket> [repo ...]"
+---
+
+Run acceptance QA for ticket **$ARGUMENTS** — standalone, to test or re-test a
+ticket without re-running the whole `/ticket` flow.
+
+Parse the arguments: if they start with `-p`/`--plan`, the next token is a plan
+file to read the `## QA plan` and acceptance criteria from. The first non-flag token
+is the ticket id; any remaining tokens are repos to scope to.
+
+1. Locate the code under test: call `chamba_list_worktrees` and use the worktree for
+   this ticket if one exists; otherwise use the current checkout. All QA runs there.
+2. Get the acceptance criteria and QA setup:
+   - from the `-p` plan file if given (its `## QA plan` + acceptance criteria); else
+   - `chamba_load_context` for the ticket and infer the acceptance criteria from the
+     ticket + workspace. If you still can't tell what to verify, ask me for the
+     ticket text before going further.
+3. Delegate to the **qa** subagent to run it: it detects the project's tooling
+   (Playwright/Cypress/browser MCP, how to run the app, the seed mechanism), sets up
+   the local seed and test users, runs the app, asks me to log in when needed, and
+   walks each acceptance criterion against the running app.
+4. Report **PASS/FAIL per acceptance criterion** with the evidence. Everything is
+   local and non-destructive — do NOT commit, push, or touch production.

package/assets/commands/ticket.md

@@ -66,16 +66,23 @@ the workspace.
    misses orphans whose name doesn't contain the deleted symbol — rely on the
    build/typechecker/dead-code tool, not just grep. Fix what comes back, then
    re-verify (max 3 rounds).
-8. Call `chamba_summarize_to_vault` with a summary of what changed.
-9. STOP and report for my review. The report MUST include:
-   - the repos touched and why;
-   - per repo, what changed and the test + verify results;
-   - an **acceptance-criteria checklist**: every AC of the ticket marked
-     **Delivered** or **Not delivered**. Anything the plan marked
-     **needs-approval**, or any AC you could not deliver without a deferred
-     decision, goes under **"Needs your decision"** with what's pending and why —
-     never omit it;
-   - the `.code-workspace` to open, and the suggested commit +
-     `git merge --no-ff` commands.
-   Do NOT commit, merge or push — I review, commit and send to my company's code
-   review by hand.
+8. **Acceptance QA** — only if the plan has a `## QA plan`. Delegate to the **qa**
+   subagent to run it from the worktree: set up the local seed and test users, run
+   the app, and validate each acceptance criterion against the **running app** —
+   driving the browser if the project has E2E tooling, otherwise co-piloting with me
+   (it asks me to log in and tells me what to click while I watch). It reports
+   PASS/FAIL per criterion. If there's no `## QA plan`, skip this step. This is the
+   only interactive touchpoint at the end.
+9. Call `chamba_summarize_to_vault` with a summary of what changed.
+10. STOP and report for my review. The report MUST include:
+    - the repos touched and why;
+    - per repo, what changed and the test + verify results;
+    - an **acceptance-criteria checklist**: every AC of the ticket marked
+      **Delivered** or **Not delivered** (fold in the qa agent's PASS/FAIL when a QA
+      phase ran). Anything the plan marked **needs-approval**, or any AC you could
+      not deliver or verify without a deferred decision, goes under **"Needs your
+      decision"** with what's pending and why — never omit it;
+    - the `.code-workspace` to open, and the suggested commit +
+      `git merge --no-ff` commands.
+    Do NOT commit, merge or push — I review, commit and send to my company's code
+    review by hand.

package/dist/cli.js

@@ -88,7 +88,8 @@ var AGENT_ROLE_BY_FILE = {
   "planner.md": "planner",
   "implementer.md": "implementer",
   "reviewer.md": "reviewer",
-  "tester.md": "tester"
+  "tester.md": "tester",
+  "qa.md": "qa"
 };
 var CLAUDE_CODE_EFFORT = {
   low: "low",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chamba/claude-extras",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Optional Claude Code extras for chamba: slash commands, subagents and hooks installer",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
   ],
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
-    "@chamba/adapters": "0.6.2",
-    "@chamba/core": "0.6.2"
+    "@chamba/adapters": "0.7.0",
+    "@chamba/core": "0.7.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",