@yemi33/minions 0.1.2071 → 0.1.2073

package/prompts/cc-system.md

@@ -152,6 +152,49 @@ curl -s http://localhost:{{dashboard_port}}/api/work-items
 curl -s http://localhost:{{dashboard_port}}/api/status
 ```
 
+## QA Sessions — natural-language → POST /api/qa/session
+
+When the user describes a UI/E2E flow they want validated against a *live, running* app instance — "QA the login flow on PR #1234", "smoke test the homepage", "test the checkout flow on the `develop` branch", "validate the signup journey on my current worktree", etc. — dispatch a QA Session via `POST /api/qa/session` instead of opening an `implement` or `test` work item. The session pipeline boots the dev-up command as a managed-spawn, drafts a runner-native test (Playwright or Maestro) from the natural-language flows, then executes it against the live target and captures the requested artifacts.
+
+**When to use this endpoint:**
+
+- The user wants a behavioural / end-to-end check ("does the login form actually work", "make sure the cart adds items"). Use `/api/qa/session`.
+- The user wants a code change, unit/integration tests in the repo, or an investigation. Keep using `/api/work-items` with `type: "fix"`, `"implement"`, `"test"`, `"explore"`.
+- The user explicitly says "QA …", "smoke test …", "test the … flow", "validate the … journey", or names a concrete UI walkthrough against a live app. Use `/api/qa/session`.
+
+**Body shape (mirrors `engine/qa-sessions.js#validateSpec`):**
+
+- `target` — REQUIRED object describing what to QA against. `target.kind` is one of:
+  - `pr` — needs `target.prId` (e.g. `"github:yemi33/minions#2911"` or `"ado:office/iss/constellation#5215493"`).
+  - `branch` — needs `target.branch` (e.g. `"develop"`).
+  - `commit` — needs `target.sha` (full 40-char SHA).
+  - `current` — uses the user's current worktree. `target.worktree` is optional; the SETUP agent falls back to `MINIONS_AGENT_CWD` when empty.
+- `flowsRaw` — REQUIRED natural-language description of the steps to test (≤4000 chars). Paste the user's own description verbatim where possible; the runner adapter translates it into the runner-native script.
+- `mode` — `"confirm"` (default — pauses at `awaiting-approval` so the user can review the drafted test before EXECUTE fires) or `"auto"` (chains straight from DRAFT to EXECUTE). Pick `"confirm"` unless the user said "just run it" / "no review needed" / "auto".
+- `capture` — optional `{ video?: bool, screenshots?: bool, logs?: bool }`. Default is everything false. Set what the user asked for.
+- `runner` — optional kebab-case name to force a specific runner (`"playwright"`, `"maestro"`, or a plugin). Omit to let the engine auto-detect (Maestro wins when the project has `.maestro/`; Playwright is the safe default).
+- `project` — REQUIRED when multiple projects are configured (mirrors `/api/work-items`). Omit for the central path.
+
+**Worked example — PR target, confirm mode (default):**
+```
+curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
+  -H 'Content-Type: application/json' \
+  -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"target":{"kind":"pr","prId":"github:yemi33/MyApp#1234"},"flowsRaw":"Open the homepage, click Login, enter test@example.com / hunter2, and verify the dashboard renders with the user'\''s name in the header.","mode":"confirm","capture":{"screenshots":true,"logs":true},"project":"MyApp"}'
+```
+
+**Worked example — current worktree, auto mode, video capture:**
+```
+curl -s -X POST http://localhost:{{dashboard_port}}/api/qa/session \
+  -H 'Content-Type: application/json' \
+  -H 'X-CC-Turn-Id: {{cc_turn_id}}' \
+  -d '{"target":{"kind":"current"},"flowsRaw":"Add three items to the cart, go to checkout, complete the payment form with the Stripe test card, and verify the success page.","mode":"auto","capture":{"video":true,"screenshots":true},"project":"MyApp"}'
+```
+
+**Response:** `{ sessionId, state: "spawning", setupWorkItemId, managedSpawnName }`. Tell the user the session id so they can watch it at `/qa` and steer it via the `/approve` (run the drafted test), `/edit` (re-draft with feedback), `/dismiss` (accept the draft without running), `/cancel` (give up), or `/kill` (cancel + tear down the managed-spawn) endpoints listed in `GET /api/routes`.
+
+**Do not also dispatch a `/api/work-items` `implement` or `test` for the same QA request.** The QA Session pipeline owns its own SETUP → DRAFT → EXECUTE work items end-to-end; firing a parallel work-item is the same double-dispatch class that the "Never both" rule above forbids. If the user asks for both a QA pass AND a code change, do them as two separate, sequential calls — QA Session for the behavioural check, work-item for the fix.
+
 **Required fields per endpoint** — the server returns `{ error: "..." }` if missing. Common cases:
 - `POST /api/work-items`: `title` REQUIRED. `description` recommended. `project` REQUIRED when multiple projects are configured (server returns the list of known names if you guess wrong). `type` defaults to `implement`; valid values: `fix`, `implement`, `implement:large`, `setup`, `explore`, `ask`, `review`, `test`, `verify`. Agent hint via `agent` (string) or `agents` (array).
   - Exempt from the `project` requirement (these run rootless or via central paths): `ask`, `explore`, `plan`, `plan-to-prd`, `meeting`. (`docs` is intentionally NOT exempt — it's write-capable and lands in `WORKTREE_REQUIRING_TYPES`, so it needs a real project worktree. For minions-repo docs work, pass `project: "minions"` explicitly.) `setup` is also in the project-required set — it operates inside a real project worktree but produces no PR. Every other type needs a project worktree, so the server rejects project-less creates with `400 { error, knownProjects }` when ≠1 project is configured.

package/routing.md

@@ -22,6 +22,9 @@ How the engine decides who handles what. Parsed by engine.js — keep the table
 | docs | lambert | _any_ |
 | setup | dallas | _any_ |
 | qa-validate | dallas | ralph |
+| qa-session-setup | dallas | ralph |
+| qa-session-draft | dallas | ralph |
+| qa-session-execute | dallas | ralph |
 
 Notes:
 - `_author_` means route to the PR author