@playcraft/cli 0.0.41 → 0.0.43

package/project-template/.claude/skills/playwright-cli/references/test-generation.md

@@ -0,0 +1,138 @@
+# Test Generation
+
+Generate Playwright test code automatically as you interact with the browser.
+
+## How It Works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code.
+This code appears in the output and can be copied directly into your test files.
+
+## Example Workflow
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+## Building a Test File
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("login flow", async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto("https://example.com/login");
+  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com");
+  await page.getByRole("textbox", { name: "Password" }).fill("password123");
+  await page.getByRole("button", { name: "Sign In" }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+## Best Practices
+
+### 1. Use Semantic Locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole("button", { name: "Submit" }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator("#submit-btn").click();
+```
+
+### 2. Explore Before Recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### 3. Add Assertions Manually
+
+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
+
+- `toBeVisible()` — element is rendered and visible
+- `toHaveText(text)` — element text content matches
+- `toHaveValue(value) / toBeEmpty()` — input/select value matches
+- `toBeChecked() / toBeUnchecked()` — checkbox state matches
+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
+
+Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
+
+When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
+
+Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
+
+```bash
+# Get a stable locator for an element ref to use in the assertion
+playwright-cli --raw generate-locator e5
+# getByRole('button', { name: 'Submit' })
+
+# Capture expected text content for toHaveText
+playwright-cli --raw eval "el => el.textContent" e5
+
+# Capture expected input value for toHaveValue/toBeEmpty
+playwright-cli --raw eval "el => el.value" e5
+
+# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
+# (whole page, or use a ref to scope to a region)
+playwright-cli --raw snapshot
+playwright-cli --raw snapshot e5
+```
+
+```typescript
+// Generated action
+await page.getByRole("button", { name: "Submit" }).click();
+
+// Manual assertions using the outputs above:
+await expect(page.getByRole("alert", { name: "Success" })).toBeVisible();
+await expect(page.getByTestId("main-header")).toHaveText("Welcome, user");
+await expect(page.getByRole("textbox", { name: "Email" })).toHaveValue(
+  "user@example.com",
+);
+await expect(
+  page.getByRole("checkbox", { name: "Enable notifications" }),
+).toBeChecked();
+
+// toMatchAriaSnapshot on the whole page, finds a matching region
+await expect(page).toMatchAriaSnapshot(`
+  - heading "Welcome, user"
+  - link /\\d+ new messages?/
+  - button "Sign out"
+`);
+
+// toMatchAriaSnapshot scoped to a region
+await expect(page.getByRole("navigation")).toMatchAriaSnapshot(`
+  - link "Home"
+  - link /\\d+ new messages?/
+  - link "Profile"
+`);
+```

package/project-template/.claude/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,142 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category        | Details                                            |
+| --------------- | -------------------------------------------------- |
+| **Actions**     | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM**         | Full DOM snapshot before/after each action         |
+| **Screenshots** | Visual state at each step                          |
+| **Network**     | All requests, responses, headers, bodies, timing   |
+| **Console**     | All console.log, warn, error messages              |
+| **Timing**      | Precise timing for each operation                  |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature                 | Trace       | Video       | Screenshot       |
+| ----------------------- | ----------- | ----------- | ---------------- |
+| **Format**              | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection**      | Yes         | No          | No               |
+| **Network details**     | Yes         | No          | No               |
+| **Step-by-step replay** | Yes         | Continuous  | Single frame     |
+| **File size**           | Medium      | Large       | Small            |
+| **Best for**            | Debugging   | Demos       | Quick capture    |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/project-template/.claude/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,157 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1. Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2. Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3. Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async (page) => {
+  await page.screencast.start({
+    path: "video.webm",
+    size: { width: 1280, height: 800 },
+  });
+  await page.goto("https://demo.playwright.dev/todomvc");
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter("Adding Todo Items", {
+    description: "We will add several items to the todo list.",
+    duration: 2000,
+  });
+
+  // Perform action
+  await page
+    .getByRole("textbox", { name: "What needs to be done?" })
+    .pressSequentially("Walk the dog", { delay: 60 });
+  await page
+    .getByRole("textbox", { name: "What needs to be done?" })
+    .press("Enter");
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter("Verifying Results", {
+    description: "Checking the item appeared in the list.",
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page
+    .getByRole("textbox", { name: "What needs to be done?" })
+    .pressSequentially("Buy groceries", { delay: 60 });
+  await page
+    .getByRole("textbox", { name: "What needs to be done?" })
+    .press("Enter");
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText("Walk the dog").boundingBox();
+  await page.screencast.showOverlay(
+    `
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `,
+    { duration: 2000 },
+  );
+
+  await page.screencast.stop();
+};
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method                                                                         | Use Case                                                                       |
+| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })`                             | Custom HTML overlay — use for callouts, labels, highlights                     |
+| `disposable.dispose()`                                                         | Remove a sticky overlay added without duration                                 |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()`            | Temporarily hide/show all overlays                                             |
+
+## Tracing vs Video
+
+| Feature  | Video                | Tracing                                  |
+| -------- | -------------------- | ---------------------------------------- |
+| Output   | WebM file            | Trace file (viewable in Trace Viewer)    |
+| Shows    | Visual recording     | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis                      |
+| Size     | Larger               | Smaller                                  |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/project-template/.cursor/rules/playcraft-orchestrator.mdc

@@ -7,17 +7,59 @@ alwaysApply: true
 
 You are the **orchestrator** for a PlayCraft playable ad project. Do not role-play PM, Designer, TA, Developer, and Reviewer in one session when `@agent` invoke is available.
 
-## Invoke `@developer` (`integration` only)
+## Invoke `@developer` (`ui_pass` / `gameplay_pass` only)
 
-Sub-agents start a **fresh session** — they do not see your `playcraft skills match` output. Before spawn (after TA Wave 2 `done`):
+Sub-agents start a **fresh session** — they do not see your `playcraft skills match` output.
+
+**Before `ui_pass`** (after TA Wave 2 `done`):
 
 1. Confirm PM ran `playcraft skills link --from-atom-plan --prune` (or run it before spawn).
 2. Read `docs/atom-plan.json` → `atoms[]` where `assignTo: Developer` and `skillRef` is non-null.
 3. Optional 30s spot-check: `ta-log` Compliance green + contract paths exist under `assets/`.
-4. In the **first message** to `@developer`, paste skillRef list and require: read `.claude/skills/<skillRef>/SKILL.md` + `ref/` first; **only if** `test -f .claude/skills/<skillRef>/SKILL.md` fails, use `playcraft skills read` (uses `playcraft.config.json` `skillsDir`); then `playcraft skills scaffold --atoms … --out ./game`.
+4. In the **first message** to `@developer`, paste skillRef list; require Skill Preflight + **UI Pass Plan** (not full gameplay yet).
 5. Ban hand-written PGS that ignores linked Skill `ref/`.
 
-Integration STOP invalid without **§ Skill Preflight** (each row: `linked` or `cli-fallback`).
+**Before `gameplay_pass`** (after `ui_review` pass):
+
+1. Confirm `devStatus: ui_ready` and UI Diff Report passed (or max rounds reached).
+2. Invoke `@developer` for gameplay only — UI shell must not be rewritten unless UI Diff items remain open.
+
+UI Pass STOP invalid without **§ Skill Preflight** + **§ UI Pass Plan**. Gameplay Pass STOP invalid without **§ Gameplay Pass Plan**.
+
+## Gate pre-check: Reviewer `design_check`
+
+Before **Gate #1** and **Gate #2b** (not #2a), invoke `@reviewer` with mode `design_check`:
+
+1. PM or Designer STOP with gate materials ready.
+2. Invoke `@reviewer design_check` — soft checklist only (completeness, no subjective quality).
+3. If fail → route to PM/Designer per report → re-invoke Reviewer → then run Gate.
+
+## Dispatching Principle: WHAT + Skill Refs, not HOW
+
+**Orchestrator 不是全知全能的指挥官。** Sub-agents 有完整的 `.claude/agents/<role>.md` + `refs/` + Skills 体系。
+
+**调度时只传递：**
+1. **目标**：需要完成哪些 atoms / review mode
+2. **关键约束/提醒**：如 `mediaGroups` 中有可复用资产
+3. **上游依赖状态**：哪些 Wave 已完成
+
+**禁止调度时：**
+- 写出详细生产步骤（agent 自己读 refs/ 和 Skills）
+- 越俎代庖选择 prompt/model/工具（agent 按 Skill Preflight 决定）
+- 跳过 agent 自身的 Step 0 流程
+
+## Post-STOP 验证（必须，在阶段转换前）
+
+Sub-agent STOP 返回后，orchestrator **必须验证** 再转阶段：
+
+| 验证项                                    | 方法                                                                                 | 失败处理           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |
+| Atom status 已全部更新                    | `atom-plan.json` → 该 agent 所有 atoms 的 `status ≠ pending`                         | 要求补全           |
+| actualOutput 非空且文件存在               | `atoms[].actualOutput` 对应文件在磁盘上存在                                          | 要求补全           |
+| Skill Context 已填写                      | `atom-plan.md` 对应区域不含 `"(Pending"`                                              | 要求回填           |
+| Skill Preflight 已完成                    | TA: `ta-log.md` § Skill Preflight; Developer: `developer-log.md` § Skill Preflight   | 拒绝 STOP，重新入 |
+| Plan section 已完成                       | `ui_pass`: § UI Pass Plan; `gameplay_pass`: § Gameplay Pass Plan                    | 拒绝 STOP，重新入 |
+| mediaGroups 处置已记录（Designer/TA）     | `ta-log.md` § mediaGroups Reuse 或 `designer-log` 有处置记录                         | 要求补充           |
 
 ## Before every decision
 
@@ -31,10 +73,10 @@ Integration STOP invalid without **§ Skill Preflight** (each row: `linked` or `
 
 | Gate | When | Action |
 | ---- | ---- | ------ |
-| #1 | handoff `gate_pending: "1"` or `gates.#1 = pending` | `AskUserQuestion` → pass → `stage: style_exploration` → `@designer` |
-| #2a | `gate_pending: "2a"` | `AskUserQuestion` → `selectedMcOption` → resume `@designer` |
-| #2b | `gate_pending: "2b"` | Confirm MC+ASR → `stage: production` → invoke `@designer` Ph.2 **only** |
-| #3 | Reviewer pass, `devStatus: ready` | Show **devUrl** via `AskUserQuestion` — user never runs `npm run dev` |
+| #1 | handoff `gate_pending: "1"` after Reviewer `design_check` pass | `AskUserQuestion` → pass → `stage: style_exploration` → `@designer` |
+| #2a | `gate_pending: "2a"` | `AskUserQuestion` → `selectedMcOption` → resume `@designer` (no Reviewer pre-check) |
+| #2b | `gate_pending: "2b"` after Reviewer `design_check` pass | Confirm MC+ASR → `stage: production` → invoke `@designer` Ph.2 **only** |
+| #3 | Reviewer `load_check` pass, `devStatus: ready` | Show **devUrl** via `AskUserQuestion` — user never runs `npm run dev` |
 
 Sub-agents **must not** use `AskUserQuestion` or set mainline `stage`. See `docs/team/agent-conduct.md`.
 
@@ -45,9 +87,9 @@ After **Technical Artist** or **Developer** subagent STOP, `.claude/hooks/valida
 - **Claude Code**: `.claude/settings.json` → `SubagentStop`
 - **Cursor**: `.cursor/hooks.json` → `subagentStop`
 
-If intake validation fails, the subagent **cannot stop** until `logs/ta-log.md` or `logs/developer-log.md` § **Upstream Intake** is complete. Do **not** invoke the next role until handoff shows a successful STOP (or re-invoke the same agent to fix intake).
+If intake validation fails, the subagent **cannot stop** until `logs/ta-log.md` or `logs/developer-log.md` § **Upstream Intake** + correct Plan section is complete. Do **not** invoke the next role until handoff shows a successful STOP (or re-invoke the same agent to fix intake).
 
-**Serial spawn after Gate #2b:** `@designer` → (Wave 1 done) `@technical-artist` → (Wave 2 done) `stage: integration` + `@developer`. **Never** spawn `@developer` during `production`.
+**Serial spawn after Gate #2b:** `@designer` → (Wave 1 done) `@technical-artist` → (Wave 2 done) `stage: ui_pass` + `@developer`. **Never** spawn `@developer` during `production`.
 
 ## Stage sync on handoff
 
@@ -55,33 +97,41 @@ When executing `next_orchestrator_action`, **also** update `stage` / gates (sub-
 
 | Action substring | Must write |
 | ---------------- | ---------- |
+| `Invoke @reviewer design_check Gate #1` | Stay `pm`; Reviewer audit only |
 | `Run Gate #1` | After pass: `stage: style_exploration`, `gates.#1 = passed` |
-| `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` (stage stays `style_exploration`) |
+| `Run Gate #2a` | `gates.#2a = passed`, set `selectedMcOption`, resume `@designer` |
+| `Invoke @reviewer design_check Gate #2b` | Stay `style_exploration`; Reviewer audit only |
 | `Run Gate #2b` | `stage: production`, `gates.#2b = passed`, invoke `@designer` Ph.2 only |
 | `Invoke @technical-artist` | Wave 1 `done` → invoke TA (stay `production`) |
-| `Set stage=integration` / invoke `@developer` | Wave 2 `done` → `stage: integration` |
-| `Invoke @reviewer` | `stage: review` |
-| `Set stage=rework` | `stage: rework` + invoke routed agents |
+| `Set stage=ui_pass` / invoke `@developer` | Wave 2 `done` → `stage: ui_pass` |
+| `Invoke @reviewer ui_diff` | `stage: ui_review` |
+| `Set stage=ui_rework` | `stage: ui_rework` + invoke routed agents |
+| `Set stage=gameplay_pass` | UI convergence done → `stage: gameplay_pass` |
+| `Invoke @reviewer load_check` | Before Gate #3 |
 | `Run Gate #3` | `gates.#3 = pending` → accept → `stage: done` |
 
 ## Handoff × stage matrix
 
 | stage | gate_pending | Typical `next_orchestrator_action` |
 | ----- | ------------ | ------------------------------------ |
-| `pm` | `"1"` | Run Gate #1 |
+| `pm` | `"1"` | Invoke `@reviewer design_check Gate #1` → Run Gate #1 |
 | `style_exploration` | `"2a"` | Run Gate #2a |
-| `style_exploration` | `"2b"` | Run Gate #2b → `stage: production` → `@designer` Ph.2 |
+| `style_exploration` | `"2b"` | Invoke `@reviewer design_check Gate #2b` → Run Gate #2b → `stage: production` → `@designer` Ph.2 |
 | `production` | null, Wave 1 pending | `@designer` Ph.2 |
 | `production` | null, Wave 1 done | `Invoke @technical-artist` |
-| `production` | null, Wave 2 done | `Set stage=integration, invoke @developer` |
-| `integration` | null, `devStatus: ready` | Invoke `@reviewer` |
-| `integration` | null, `blocked_upstream` | Re-invoke per `devBlockers.routeTo` → `@developer` |
-| `review` | — (fail handoff) | Set `stage: rework`, invoke routed agents |
-| `rework` | null | Fixes → `@developer` → `@reviewer` |
-| `review` | `"3"` or pass | Gate #3 devUrl |
+| `production` | null, Wave 2 done | `Set stage=ui_pass, invoke @developer` |
+| `ui_pass` | null, `devStatus: ui_ready` | Invoke `@reviewer ui_diff` |
+| `ui_pass` | null, `blocked_upstream` | Re-invoke per `devBlockers.routeTo` → `@developer` |
+| `ui_review` | — (fail) | Set `stage: ui_rework`, invoke routed agents |
+| `ui_rework` | null | Fixes → `@developer` → `@reviewer ui_diff` |
+| `ui_review` | — (pass or 5 rounds) | Set `stage: gameplay_pass, invoke @developer` |
+| `gameplay_pass` | null, `devStatus: ready` | Invoke `@reviewer load_check` |
+| `gameplay_pass` | load_check fail | Re-invoke `@developer` → `@reviewer load_check` |
+| `gameplay_pass` | load_check pass | Gate #3 devUrl |
 
 ## Stage shortcuts
 
-- Gate #2b → `@designer` only; Wave 1 done → `@technical-artist`; Wave 2 done → `integration` + `@developer`
-- Review fail → **you** set `stage: rework` (Reviewer does not)
+- Gate #2b → `@designer` only; Wave 1 done → `@technical-artist`; Wave 2 done → `ui_pass` + `@developer`
+- UI fail → **you** set `stage: ui_rework` (Reviewer does not)
+- `uiReworkRound` max 5 — then proceed to `gameplay_pass` or escalate to user
 - `done` = user accepts devUrl; **not** `playcraft build`

package/project-template/.cursor/rules/playcraft-subagent-boundary.mdc

@@ -15,4 +15,4 @@ When editing project outputs as a **sub-agent** (PM / Designer / TA / Developer
 - **Do not** change mainline `stage` — use `next_orchestrator_action` in handoff.
 - R/W matrix: `docs/team/collaboration.md`.
 
-Designer: read `selectedMcOption` before ASR (UI + element state sheets). TA: only after Production Pipeline Wave 1 `done`. Developer: only in `integration`; complete `developer-log.md` § Skill Preflight before `game/` edits; never `devStatus: ready` with open `devBlockers`.
+Designer: read `selectedMcOption` before ASR (UI + element state sheets). TA: only after Production Pipeline Wave 1 `done`. Developer: only in `ui_pass` / `gameplay_pass` / `ui_rework`; complete `developer-log.md` § Skill Preflight + stage-appropriate Plan before `game/` edits; `ui_pass` → `devStatus: ui_ready`; `gameplay_pass` → `devStatus: ready`; never either with open `devBlockers`.