@isummation/kasauti-cli 0.2.0 → 0.4.0

package/README.md

@@ -1,12 +1,157 @@
 # @isummation/kasauti-cli
 
-Command line for [Kasauti](https://gitlab.isummation.com/isummation-product/kasauti) test management: explore, author, run, and report and fix defects. Used by people, CI and AI agents. Output is Markdown; add `--json` for scripts. Node 20+, no dependencies.
+Command line for **Kasauti** test management, and the **Kasauti plugin for Claude Code**.
+
+- People and scripts use the `kasauti` command to explore, write and run test cases and to report and fix defects.
+- Claude Code gets the Kasauti tools (MCP) and three playbooks: explore a screen into test cases, run tests, fix defects.
+
+Output is Markdown, which people and AI agents both read easily; add `--json` for scripts. Needs Node.js 20 or later; no dependencies.
+
+## Install
+
+```bash
+npm install -g @isummation/kasauti-cli
+```
+
+Or run it once without installing: `npx @isummation/kasauti-cli --help`.
+
+## What you need from Kasauti
+
+- **The API URL**, for example `https://kasauti-api.your-company.com`. It's the API's address, not the web app's; your Kasauti admin can tell you, and the web app shows it under **Settings → API tokens & agents**.
+- **A token**, created in the web app under **Settings → API tokens & agents**. It is shown once, so copy it then.
+  - **Personal** token: for the `kasauti` command as yourself, and for CI.
+  - **Agent** token: for Claude Code. Everything it writes is marked as the agent, its test cases start as drafts for a person to approve, and it can't verify fixes.
+  - A token works only on the Kasauti server it was created on, and has your role there (tester or developer).
+
+## Use the CLI
 
 ```bash
-npm install -g @isummation/kasauti-cli      # needs access to the @isummation npm org
-kasauti login https://<kasauti-api> --token <token>
-kasauti map SHOP
-kasauti --help
+kasauti login https://kasauti-api.your-company.com --token <personal token>   # saved to ~/.kasauti.json, readable only by you
+kasauti whoami
+kasauti projects
+kasauti map SHOP                 # screens / endpoints with coverage and open defects
+kasauti get SHOP-D7              # anything by key, with full context
+kasauti defects SHOP --mine
+kasauti result SHOP-R5 SHOP-12 failed -m "Total shows twice" --attach shot.png
+kasauti --help                   # every command
 ```
 
-`KASAUTI_URL` and `KASAUTI_TOKEN` override the saved login (that is how CI uses it). Full guide: `docs/using-kasauti-in-your-project.md` in the Kasauti repository.
+Keys name everything. The letter after the project code says what a key is:
+
+| Key | What it is |
+|---|---|
+| `SHOP-12` | test case (no letter) |
+| `SHOP-A3` | area: a screen, endpoint or module |
+| `SHOP-SC4` | scenario: a user goal |
+| `SHOP-R5` | run: cases being executed |
+| `SHOP-P2` | plan: a saved set of cases |
+| `SHOP-M1` | milestone |
+| `SHOP-D7` | defect |
+
+`KASAUTI_URL` and `KASAUTI_TOKEN` in the environment take precedence over the saved login. CI uses them: store both as secret CI variables and no login step is needed.
+
+## Connect Claude Code
+
+**1. Install the plugin**
+
+```bash
+kasauti plugin install           # for all your projects; --scope local for the current project only
+```
+
+This runs `claude plugin marketplace add` and `claude plugin install` for the copy of the plugin inside this package. If the `claude` command isn't on your PATH, it prints the two commands to run yourself.
+
+**2. Give Claude Code the URL and an agent token.** The plugin reads them from two environment variables, `KASAUTI_URL` and `KASAUTI_TOKEN`. `kasauti login` does **not** set them: it only configures the `kasauti` command. Without them, the plugin calls `http://localhost:3001` with no token.
+
+Set them where Claude Code starts. The commands below ask for the token without showing it, so it stays out of your shell history.
+
+- **Linux, WSL, macOS with bash**: add them to `~/.bashrc`:
+
+  ```bash
+  read -rsp "Kasauti agent token: " T && printf '\nexport KASAUTI_URL=https://kasauti-api.your-company.com\nexport KASAUTI_TOKEN=%s\n' "$T" >> ~/.bashrc && unset T && echo
+  ```
+
+- **macOS with zsh (the default)**: the same command with `~/.zshrc` instead of `~/.bashrc`.
+
+- **fish**:
+
+  ```fish
+  set -Ux KASAUTI_URL https://kasauti-api.your-company.com
+  read -s -P "Kasauti agent token: " T; and set -Ux KASAUTI_TOKEN $T; and set -e T
+  ```
+
+- **Windows (Claude Code running on Windows itself, in PowerShell)**:
+
+  ```powershell
+  [Environment]::SetEnvironmentVariable('KASAUTI_URL', 'https://kasauti-api.your-company.com', 'User')
+  $t = Read-Host 'Kasauti agent token' -AsSecureString
+  [Environment]::SetEnvironmentVariable('KASAUTI_TOKEN', [Net.NetworkCredential]::new('', $t).Password, 'User'); Remove-Variable t
+  ```
+
+  If you use Claude Code inside **WSL** (including VS Code connected to WSL), use the bash setup above instead: Windows variables don't reach it.
+
+To change a value later, edit the line in that file rather than running the command again, which would add a second copy.
+
+**3. Restart Claude Code.** It reads the variables only when it starts. In a terminal, open a new one. In **VS Code** (and other editors), close every window and reopen the editor; reloading a window isn't enough. For VS Code with WSL, if it still shows the old state, run `wsl --shutdown` in Windows and reopen.
+
+**4. Check.** In Claude Code, run `/mcp`: `kasauti` should show as connected. Then ask *"List my Kasauti projects"*. In a terminal, `echo $KASAUTI_URL` should print your URL.
+
+### Keep an agent to one project
+
+If you're on several projects, give each repository its own token **limited to that project**. The agent then can't read or change any other project, even by mistake: other projects don't exist for that token, and it can't create tokens or do admin work.
+
+1. Create the token in the web app (**Settings → API tokens & agents**, pick the project), or with the CLI:
+
+   ```bash
+   kasauti token claude-code-shop --agent claude-code --project SHOP
+   ```
+
+2. Put it in the repository's `.claude/settings.local.json`. Claude Code applies its `env` only in this repository, over the variables from your shell, so your other repositories keep their own tokens:
+
+   ```json
+   {
+     "env": {
+       "KASAUTI_URL": "https://kasauti-api.your-company.com",
+       "KASAUTI_TOKEN": "kst_…"
+     }
+   }
+   ```
+
+   `settings.local.json` is for you alone: Claude Code adds it to the repository's `.gitignore` when it creates the file. Check it is ignored before you save a token in it; never put a token in the shared `.claude/settings.json`.
+
+3. Restart Claude Code in that repository and run `/mcp`. Asking *"List my Kasauti projects"* should show only that project.
+
+Deleting the project deletes its tokens. Revoke a token under **Settings → API tokens & agents**.
+
+### Update
+
+```bash
+npm update -g @isummation/kasauti-cli
+kasauti plugin update
+```
+
+Claude Code loads the plugin from the npm install folder, so the next session uses the new version. Switching Node.js versions (nvm, fnm, volta) moves that folder: install the CLI for the new version and run `kasauti plugin install` again.
+
+### Remove
+
+```bash
+claude plugin uninstall kasauti@kasauti
+claude plugin marketplace remove kasauti
+npm uninstall -g @isummation/kasauti-cli
+```
+
+### Without the plugin (Cursor and other MCP clients)
+
+Kasauti is a standard MCP server over HTTP: URL `<KASAUTI_URL>/mcp`, header `Authorization: Bearer <agent token>`. `kasauti mcp-config` prints the Claude Code command for your settings. You get the tools, without the playbooks.
+
+## Troubleshooting
+
+| What you see | Fix |
+|---|---|
+| `/mcp`: kasauti failed, `HTTP 401` or `Invalid or expired token` | `KASAUTI_TOKEN` isn't set where Claude Code started, was created on a different Kasauti server, or was revoked. Set it (step 2) and restart Claude Code fully. |
+| `/mcp` shows `http://localhost:3001/mcp` | `KASAUTI_URL` isn't set where Claude Code started. Set it and restart Claude Code fully. |
+| `Error 401` from `kasauti` | Log in again with a valid token, or check the `KASAUTI_TOKEN` you exported. |
+| `Error 404` for a project that exists | You aren't assigned to it; ask a Kasauti admin. |
+| `Error 403 … needs the tester role` or `needs a human` | Your role can't do that; agent tokens can't verify fixes or approve drafts. |
+| `Cannot reach …` | Wrong `KASAUTI_URL` (use the API address), or no network route to it. |
+| `kasauti plugin install`: `No bundled plugin here` | The `kasauti` on your PATH isn't this npm package. Run `npm install -g @isummation/kasauti-cli`. |
+| The plugin vanished after switching Node.js versions | Run `kasauti plugin install` again. |

package/kasauti.mjs

@@ -5,14 +5,18 @@ import { parseArgs } from 'node:util';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, join, extname } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
 const CONFIG = process.env.KASAUTI_CONFIG ?? join(homedir(), '.kasauti.json');
 const HELP = `kasauti <command> [args] [--json]
 
 Setup
   login <url> --token T                  save URL + a personal token (Settings → API tokens) to ~/.kasauti.json
-  token <name> [--agent NAME]            create a personal (or agent) API token
+  token <name> [--agent NAME] [--project CODE]  create a personal (or agent) API token, optionally limited to one project
   whoami | projects | mcp-config
+  plugin install|update [--scope user|local]   add the bundled Claude Code plugin (skills + MCP) to Claude Code
+  plugin path                            where the bundled plugin is, for manual setup
 
 Explore
   map <PROJECT>                          area tree with coverage and open defects
@@ -51,13 +55,14 @@ const { values: o, positionals: args } = parseArgs({
   allowPositionals: true,
   options: {
     json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
-    token: { type: 'string' }, agent: { type: 'string' },
+    token: { type: 'string' }, agent: { type: 'string' }, project: { type: 'string' },
     title: { type: 'string' }, route: { type: 'string' }, kind: { type: 'string' }, parent: { type: 'string' }, notes: { type: 'string' },
     ref: { type: 'string' }, key: { type: 'string' }, area: { type: 'string' }, scenario: { type: 'string' }, narrative: { type: 'string' },
     type: { type: 'string' }, status: { type: 'string' }, tag: { type: 'string' }, plan: { type: 'string' }, cases: { type: 'string' },
     env: { type: 'string' }, message: { type: 'string', short: 'm' }, attach: { type: 'string', multiple: true }, duration: { type: 'string' },
     case: { type: 'string' }, run: { type: 'string' }, url: { type: 'string' }, actual: { type: 'string' }, expected: { type: 'string' },
     steps: { type: 'string' }, severity: { type: 'string' }, commit: { type: 'string' }, pr: { type: 'string' }, mine: { type: 'boolean' }, force: { type: 'boolean' },
+    scope: { type: 'string' },
   },
 });
 
@@ -122,7 +127,7 @@ switch (cmd) {
     break;
   }
   case 'token': {
-    const r = await api('POST', '/tokens', clean({ name: need(sub, '<name>'), kind: o.agent ? 'agent' : 'user', agentName: o.agent }), { md: false });
+    const r = await api('POST', '/tokens', clean({ name: need(sub, '<name>'), kind: o.agent ? 'agent' : 'user', agentName: o.agent, project: o.project }), { md: false });
     print(o.json ? r : `Token (shown once): ${r.token}\nUse: export KASAUTI_TOKEN=${r.token}`);
     break;
   }
@@ -133,6 +138,43 @@ switch (cmd) {
     print(`claude mcp add --transport http kasauti ${url}/mcp --header "Authorization: Bearer <agent token>"\n\nCreate an agent token with: kasauti token claude-code --agent claude-code`);
     break;
   }
+  case 'plugin': {
+    // The npm package ships the plugin as a one-plugin marketplace (see bundle-plugin.mjs), so installing it
+    // needs no access to the Kasauti git repository.
+    const dir = fileURLToPath(new URL('./plugin', import.meta.url));
+    if (!existsSync(join(dir, '.claude-plugin', 'marketplace.json'))) die('No bundled plugin here (running from a git checkout?). Install the CLI from npm: npm install -g @isummation/kasauti-cli');
+    if (sub === 'path') { print(dir); break; }
+    if (sub !== 'install' && sub !== 'update') die('Usage: kasauti plugin install|update|path [--scope user|local]');
+    // Not 'project': that would commit this machine's npm path into the repo's .claude/settings.json.
+    const scope = o.scope ?? 'user';
+    if (!['user', 'local'].includes(scope)) die('--scope must be user (all your projects) or local (this project, not committed)');
+    const steps = sub === 'install'
+      ? [['plugin', 'marketplace', 'add', dir, '--scope', scope], ['plugin', 'install', 'kasauti@kasauti', '--scope', scope]]
+      : [['plugin', 'marketplace', 'update', 'kasauti'], ['plugin', 'update', 'kasauti@kasauti']];
+    const quote = (x) => (/\s/.test(x) ? `"${x}"` : x);
+    const show = (a) => `claude ${a.map(quote).join(' ')}`;
+    // claude is a .cmd shim on Windows, which only runs through a shell (so paths with spaces get quoted)
+    const win = process.platform === 'win32';
+    const claude = (a) => spawnSync('claude', win ? a.map(quote) : a, { stdio: 'inherit', shell: win });
+    const probe = spawnSync('claude', ['--version'], { stdio: 'ignore', shell: win });
+    if (probe.error || probe.status) die(`Claude Code isn't on the PATH. Install it, or run these yourself:\n${steps.map(show).join('\n')}`);
+    for (const [i, a] of steps.entries()) {
+      console.log(`$ ${show(a)}`);
+      let r = claude(a);
+      // already added (e.g. a reinstall): refresh it from the folder instead
+      if (r.status && i === 0 && sub === 'install') r = claude(['plugin', 'marketplace', 'update', 'kasauti']);
+      if (r.status) die(`Failed: ${show(a)}`);
+    }
+    // The plugin's MCP server only sees environment variables, not ~/.kasauti.json: say so when they're missing.
+    const missing = ['KASAUTI_URL', 'KASAUTI_TOKEN'].filter((v) => !process.env[v]);
+    if (missing.length)
+      console.log(`\nNot set yet: ${missing.join(', ')}. The plugin reads both from the environment (kasauti login only configures this CLI),\n` +
+        `so until then it calls http://localhost:3001 without a token. Set them, e.g. in ~/.bashrc:\n` +
+        `  export KASAUTI_URL=${config().url}\n  export KASAUTI_TOKEN=<an agent token from Settings → API tokens & agents>\n` +
+        `Details: https://www.npmjs.com/package/@isummation/kasauti-cli#connect-claude-code`);
+    print(`\nDone. Restart Claude Code (in VS Code: close every window), then check /mcp lists kasauti as connected.\nAfter upgrading the CLI (npm update -g @isummation/kasauti-cli), run: kasauti plugin update`);
+    break;
+  }
   case 'map': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/map`)); break;
   case 'get': print(await api('GET', `/k/${need(sub, '<KEY>')}`)); break;
   case 'activity': print(await api('GET', `/projects/${need(sub, '<PROJECT>')}/activity`)); break;

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@isummation/kasauti-cli",
-  "version": "0.2.0",
-  "description": "Kasauti test management CLI for humans, CI and AI agents",
+  "version": "0.4.0",
+  "description": "Kasauti test management CLI for humans, CI and AI agents, with the Claude Code plugin",
   "type": "module",
   "bin": {
     "kasauti": "./kasauti.mjs"
   },
   "files": [
     "kasauti.mjs",
+    "plugin",
     "README.md"
   ],
+  "scripts": {
+    "prepack": "node bundle-plugin.mjs"
+  },
   "engines": {
     "node": ">=20"
   },
@@ -19,7 +23,7 @@
     "directory": "packages/cli"
   },
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org/"
   }
 }

package/plugin/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "kasauti",
+  "owner": {
+    "name": "iSummation"
+  },
+  "plugins": [
+    {
+      "name": "kasauti",
+      "source": "./kasauti",
+      "description": "Kasauti test management for AI agents",
+      "version": "0.4.0"
+    }
+  ],
+  "description": "Kasauti test management plugin for Claude Code"
+}

package/plugin/kasauti/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "kasauti",
+  "version": "0.4.0",
+  "description": "Kasauti test management: explore screens into test cases, run them, file defects with evidence, and fix defects for tester verification.",
+  "author": {
+    "name": "iSummation"
+  }
+}

package/plugin/kasauti/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "kasauti": {
+      "type": "http",
+      "url": "${KASAUTI_URL:-http://localhost:3001}/mcp",
+      "headers": { "Authorization": "Bearer ${KASAUTI_TOKEN}" }
+    }
+  }
+}

package/plugin/kasauti/AGENTS.md

@@ -0,0 +1,19 @@
+# Kasauti (test management) — instructions for AI agents
+
+Copy this section into a product repo's `AGENTS.md` / `CLAUDE.md` / Cursor rules so any agent harness can use Kasauti.
+
+Kasauti tracks this project's test cases, runs and defects. Use the `kasauti` MCP server (`$KASAUTI_URL/mcp`, bearer `$KASAUTI_TOKEN`)
+or the `kasauti` CLI (`npm install -g @isummation/kasauti-cli`, then `kasauti --help`; output is Markdown, add `--json` for JSON). The project code is **DEMO** <!-- change me -->.
+
+Keys: `DEMO-12` case · `DEMO-A3` area (screen/endpoint) · `DEMO-SC4` scenario · `DEMO-R5` run · `DEMO-D7` defect.
+
+- **Start** with `kasauti map DEMO` (MCP `project_map`), then `kasauti get <KEY>`.
+- **Fixing bugs:** `kasauti defects DEMO` → `kasauti defect claim DEMO-D7` → `kasauti get DEMO-D7` (repro steps, evidence, linked case)
+  → reproduce → fix + test → commit mentioning the key → `kasauti defect resolve DEMO-D7 -m "<root cause and change>" --commit <sha>`.
+  Reopened defects first; read their comments. Can't reproduce? Comment and `kasauti defect release DEMO-D7`.
+- **Testing a screen:** create or update the area (`kasauti area DEMO --title … --route /path`), scenarios and cases (use stable `ref`s),
+  `kasauti run start DEMO --title … --area DEMO-A3`, then `kasauti run next DEMO-R5` / `kasauti result DEMO-R5 DEMO-12 failed -m "…" --attach shot.png`,
+  and `kasauti defect report DEMO --title … --case DEMO-12 --run DEMO-R5` for failures.
+- Long text fields are **Markdown**: numbered repro steps, `code` for values, fenced blocks for logs and stack traces. Raw HTML is not rendered. Screenshots testers paste appear as `![name](<KASAUTI_URL>/attachments/<id>)`: download them with your token to see what they saw.
+- **Never** mark results you didn't observe. You can't verify fixes or approve draft cases; humans do that.
+- Your token carries its owner's role. A developer's token can claim, resolve and comment on defects; exploring and running tests needs a tester's token.

package/plugin/kasauti/skills/explore-screen/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: explore-screen
+description: Explore a web app screen in a browser, record its scenarios and test cases in Kasauti, execute them, and report results and defects with evidence. Use when asked to "explore", "test", "find scenarios for" or "write test cases for" a page/screen/URL, or to run exploratory testing on a frontend project.
+---
+
+# Explore a screen into Kasauti
+
+You need two tools: a **browser** (Claude in Chrome, Playwright MCP, or `playwright-cli`) and **Kasauti** (the `kasauti` MCP tools, or the `kasauti` CLI with the same verbs). Keys look like `DEMO-A3` (area), `DEMO-SC4` (scenario), `DEMO-12` (case), `DEMO-R5` (run), `DEMO-D7` (defect).
+
+## 1. Orient
+1. `project_map` for the project. It returns the base URL and the areas that already exist, with their coverage. Don't re-create what's there.
+2. If the target screen is already an area, `get` it. Read the **Agent notes** (login, test data, selectors) and the existing scenarios and cases.
+
+## 2. Map the screen
+3. Open the screen in the browser. If you're redirected to login, follow the area notes or ask the user.
+4. `upsert_area` with:
+   - `title`: a human name.
+   - `route`: the URL pattern with params generalized, e.g. `/orders/:id`.
+   - `kind: screen`.
+   - `parent`: set it for nested screens.
+   - `notes`: anything the next agent needs (how to get there, required data, flaky bits).
+5. Identify the **user goals** the screen supports, not individual widgets. Typical set: the happy path, validation and errors, empty and loading states, permissions, and navigation out. `upsert_scenario` once per goal, with a short Given/When/Then `narrative`.
+
+## 3. Write concrete cases
+6. `upsert_cases` in one batch per scenario. Each case should have:
+   - a `ref` that's stable across sessions, e.g. `orders-detail/cancel-confirm`;
+   - a specific `title` that states the expected behaviour;
+   - `steps` with `action`, optional `data`, and an `expected` on every step that checks something;
+   - `behavior` (positive/negative), `severity` and `layer: e2e`.
+
+   Keep cases independent and repeatable. Put setup in `preconditions`.
+7. Your cases land as **drafts**. That's expected: a human approves them. Don't try to set `status: actual`.
+
+## 4. Execute
+8. `start_run` with `area` set to this screen (or `scenario`) and a descriptive title, e.g. "Exploratory: Orders detail (Chrome)".
+9. Loop: `next_case` → do the steps in the browser → `report_result` with:
+   - `status`: passed / failed / blocked (blocked when you can't reach the precondition);
+   - `steps`: the 1-based step results, at least for the failing step;
+   - `comment`: actual vs expected, the exact error text, the URL;
+   - `attachments`: for failures, a screenshot (base64 PNG) plus console errors and failing network calls as text files.
+10. For each failure, `report_defect` with:
+    - `case` and `run`, so the failing result and its evidence are linked;
+    - a symptom-style `title`;
+    - `actualResult`, `expected`, numbered `reproSteps`, `url`, and `environment` (browser and build).
+
+    Re-reporting the same problem is safe: it adds an occurrence, and it reopens the defect if it had been marked fixed.
+11. Bugs you notice outside any case (console errors, broken links): file them as defects with `area` set.
+12. `complete_run`, then summarise for the user: the area key, the scenarios and cases created, pass/fail counts, the defect keys, and anything you couldn't test.
+
+## Rules
+- Never guess results. If you didn't observe it, mark the case `blocked` and explain why.
+- Don't create accounts, payments or other irreversible actions on shared environments unless the area notes say it's safe.
+- Prefer updating existing areas, scenarios and cases (same `ref` or `key`) over creating near-duplicates.

package/plugin/kasauti/skills/fix-defects/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: fix-defects
+description: Pick up open defects from Kasauti, reproduce them, fix the code in this repository, and mark them fixed for tester verification. Use when asked to "fix open bugs/defects/issues", "work the Kasauti queue", fix a specific defect key like DEMO-D7, or handle reopened defects.
+---
+
+# Fix Kasauti defects
+
+Kasauti holds the bug; this repo holds the code. You move a defect from `open` to `in_progress` (claimed), then to `fixed`. A **human tester** moves it to `verified`, or reopens it. You can't verify.
+
+## 1. Choose work
+1. `list_defects` for the project (the default is unresolved). If the user named a key, use that one.
+   - Do reopened defects first (`reopened > 0`). Their comments say why the last fix wasn't enough.
+   - Then go by severity (blocker → critical → major).
+2. `claim_defect` before you touch code. If it says someone else is working on it, pick another. Don't use `force` unless the user tells you to.
+
+## 2. Understand
+3. `get <defect key>` returns the full bundle: actual vs expected, repro steps, URL, environment, the linked case's steps, failing results with stack traces, evidence links (screenshots and logs, fetch them with the same token), and the comment thread.
+4. Find the code behind the area/route: `get <area key>` gives the route or endpoint. Search the repo for it.
+
+## 3. Reproduce, then fix
+5. Reproduce first. Use a browser (Playwright MCP / `playwright-cli`) for UI bugs, or a request or failing test for APIs. If it doesn't reproduce, `comment` with what you tried and `release_defect` it. Don't mark it fixed.
+6. Fix the root cause. Add or adjust an automated test that fails before the fix and passes after.
+   - If the project uses the Kasauti Playwright reporter, tag the test with the case key, e.g. `test('… @DEMO-12')`.
+7. Run the relevant tests. Commit with the defect key in the message, e.g. `fix(profile): persist display name (DEMO-D7)`.
+
+## 4. Hand back
+8. `resolve_defect` with:
+   - `notes`: the root cause, what changed, and how to check it (one short paragraph a tester can follow);
+   - `commit`: the SHA; `prUrl` if you opened a PR.
+
+   This queues a retest of the linked case in the project's **Defect verification** run.
+9. Tell the user which defects you moved to fixed and which you released, and why.
+
+## Rules
+- One defect, one focused change. Don't bundle unrelated fixes under one defect.
+- If the "defect" is actually expected behaviour, `comment` your reasoning and leave the status for a human (they can mark it invalid).
+- Never mark a defect fixed without running the code path.

package/plugin/kasauti/skills/run-tests/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: run-tests
+description: Report automated test results (Playwright, or any framework, or API checks) into Kasauti, and design API test cases from endpoints. Use for backend/API projects, CI reporting, importing an OpenAPI spec, or "run the suite and record results in Kasauti".
+---
+
+# Automated and API testing with Kasauti
+
+## Playwright projects
+Add the reporter once:
+```ts
+// playwright.config.ts
+reporter: [['list'], ['@isummation/kasauti-playwright-reporter', { project: 'DEMO' }]],
+```
+Then run with `KASAUTI_URL` and `KASAUTI_TOKEN` set (in CI, use an agent token stored as a secret).
+- Tests tagged with a case key (`test('login works @DEMO-12', …)`) report into that case.
+- Untagged tests are matched by file/describe path + title. The first time they run, they're created as **draft automated cases**.
+- Each run creates a run (`source: automation`) and completes it. Set `KASAUTI_RUN=DEMO-R5` to report into an existing run instead.
+
+## Other frameworks
+Post results directly, in batches of up to 1000:
+```
+POST /runs                       {"project":"DEMO","title":"CI #123","source":"automation"}
+POST /k/DEMO-R5/results/bulk     {"results":[{"case":"DEMO-12","status":"passed","durationMs":120},
+                                             {"title":"refund > partial","suite":"API/Refunds","status":"failed","stacktrace":"..."}]}
+POST /k/DEMO-R5/complete
+```
+Statuses: passed, failed, blocked, skipped, invalid.
+
+## Backend / API projects
+1. Import the API surface once, and re-import when it changes (it's idempotent):
+   - `kasauti import openapi DEMO openapi.yaml`
+
+   This creates one **endpoint area** per operation (`route: "POST /orders"`), grouped under a module area per tag.
+2. `project_map` to see the endpoints with no cases.
+3. Per endpoint, `upsert_scenario` for the behaviours (create succeeds, validation, auth, not found, idempotency, pagination…). Then `upsert_cases` with `layer: api`. Steps are the request (`action: "POST /orders"`, `data`: the body) and `expected` is the status and key fields.
+4. Execute with an agent run:
+   - `start_run` with `area` set to the module area;
+   - for each case, call the API (curl/fetch against the project base URL);
+   - `report_result` with the response status/body excerpt in `comment`;
+   - `report_defect` on failure (put the request/response in `actualResult`).
+5. If you write automated tests for these cases, tag them with the case keys so CI results land on the same cases.