@yemi33/minions 0.1.2082 → 0.1.2084

package/playbooks/qa-session-setup.md

@@ -24,9 +24,41 @@ A user asked Minions to QA the following target and flows:
 - **Runner hint (optional explicit runner):** `{{runner_hint}}`
 - **Capture:** `{{capture}}`
 - **Mode:** `{{session_mode}}`
+- **Role (multi-project fan-out):** `{{role}}` *(empty = single-project session, behave as if `primary`)*
+- **Primary project (multi-project fan-out):** `{{primary_project}}`
+- **Co-services JSON (multi-project fan-out):** `{{co_services_json}}`
 
 {{additional_context}}
 
+## Multi-project fan-out (W-mpq6xqzj000606d0)
+
+When the user picks **multiple projects** from the QA Session form, the engine
+queues one SETUP work item **per project** in parallel. Each WI sees the same
+target/flows/managed_spawn_name, but with a different `{{role}}` value:
+
+- **`{{role}} == "primary"`** *(or empty for single-project sessions)*: you are
+  the orchestrator. You own the canonical `{{managed_spawn_name}}` (no suffix)
+  and your work item's wiPath is the one that gets the DRAFT phase queued
+  on it once **all** SETUP WIs succeed. If `{{co_services_json}}` is non-empty
+  (e.g. `["api","worker"]`), the DRAFT and EXECUTE agents will poll each of
+  those co-services' managed-spawn health (name = `{{managed_spawn_name}}-<project>`)
+  via `/api/managed-processes/by-name` before treating the system as ready.
+- **`{{role}} == "co-service"`**: you are a supporting service (DB, API,
+  worker, etc.). Your managed-spawn `name` MUST be `{{managed_spawn_name}}-<your-project>`
+  (the engine appends `-<project>` automatically when computing the spec name).
+  You do **not** write tests, do not queue DRAFT — just stand up your service,
+  declare its healthcheck, and exit clean. The primary's DRAFT/EXECUTE will
+  reach you over the network (use a deterministic port; document it in
+  `managed-spawn.json` `ports[]`).
+
+Any co-service SETUP that fails (sidecar invalid, healthcheck miss, build
+error) **fails the entire session** with `failure_class: 'qa-session-setup-failed'`
+and a per-project error JSON in `session.error`. The primary's WI does NOT
+get the DRAFT phase queued in that case.
+
+For single-project sessions (`{{co_services_json}}` empty or `[]`), ignore
+this section — the original single-WI flow applies unchanged.
+
 ## What "qa-session-setup" means
 
 A `qa-session-setup` task is the **first** of three chained work items the

package/prompts/cc-system.md

@@ -186,25 +186,33 @@ When the user describes a UI/E2E flow they want validated against a *live, runni
 - `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.
+- `project` — REQUIRED (legacy single-project form) when multiple projects are configured (mirrors `/api/work-items`). Omit for the central path. **Multi-project form (W-mpq6xqzj000606d0):** pass `projects: string[]` (≤5) instead of `project` to QA across multiple services in parallel. The first entry is the **primary** (owns DRAFT/EXECUTE and the canonical managed-spawn name); the rest are **co-services** (each gets a SETUP work item that stands up its dev-up command, named `qa-session-<id>-<project>`). All co-services must pass first-healthcheck before DRAFT fires; any failure fails the whole session. Use this when the user says "QA the api+worker against PR #X" or "smoke test the full stack on `develop`".
 
-**Worked example — PR target, confirm mode (default):**
+**Worked example — PR target, confirm mode (default), single project:**
 ```
 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"}'
+  -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},"projects":["MyApp"]}'
 ```
 
-**Worked example — current worktree, auto mode, video capture:**
+**Worked example — current worktree, auto mode, video capture, single project:**
 ```
 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"}'
+  -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},"projects":["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`.
+**Worked example — multi-project fan-out (primary + 2 co-services):**
+```
+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":"branch","branch":"develop"},"flowsRaw":"Place an order on the storefront and verify it shows up in the admin panel within 5 seconds.","mode":"confirm","capture":{"video":true,"logs":true},"projects":["storefront","api","worker"]}'
+```
+
+**Response:** `{ sessionId, state: "spawning", setupWorkItemId, managedSpawnName, projects? }`. `setupWorkItemId` is the **primary's** WI id; `projects` is the canonical array (single-project sessions omit it). 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.