@playcraft/cli 0.0.40 → 0.0.42

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/hooks.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "hooks": {
+    "subagentStop": [
+      {
+        "command": "node .claude/hooks/validate-atom-plan.mjs",
+        "timeout": 30,
+        "failClosed": false
+      },
+      {
+        "command": "node .claude/hooks/validate-workflow-stop.mjs",
+        "timeout": 30,
+        "failClosed": false
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,137 @@
+---
+description: PlayCraft playable ad orchestrator — gates, stages, sub-agent spawn only
+alwaysApply: true
+---
+
+# PlayCraft Orchestrator
+
+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` (`ui_pass` / `gameplay_pass` only)
+
+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; require Skill Preflight + **UI Pass Plan** (not full gameplay yet).
+5. Ban hand-written PGS that ignores linked Skill `ref/`.
+
+**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
+
+1. Read `docs/project-state.md` → parse **`## Agent handoff`** YAML + Gates table + **Production Pipeline** waves.
+2. If `gate_pending` non-null and `waiting_for: user_gate` → **Gate only** — do **not** invoke sub-agents.
+3. If `subagent_stop: true` and `waiting_for: orchestrator` → execute **only** `next_orchestrator_action`.
+4. Follow `CLAUDE.md` Orchestration Protocol and `docs/team/collaboration.md` § Gate Protocol, § Agent Handoff.
+5. Before invoke: reset handoff (`subagent_stop: false`, `waiting_for: none`, `subagent: <target>`).
+
+## Gates (only you ask the user)
+
+| Gate | When | Action |
+| ---- | ---- | ------ |
+| #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`.
+
+## Workflow STOP hooks (Claude Code + Cursor)
+
+After **Technical Artist** or **Developer** subagent STOP, `.claude/hooks/validate-workflow-stop.mjs` runs automatically:
+
+- **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** + 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: ui_pass` + `@developer`. **Never** spawn `@developer` during `production`.
+
+## Stage sync on handoff
+
+When executing `next_orchestrator_action`, **also** update `stage` / gates (sub-agents never do this):
+
+| 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` |
+| `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=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"` | Invoke `@reviewer design_check Gate #1` → Run Gate #1 |
+| `style_exploration` | `"2a"` | Run Gate #2a |
+| `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=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 → `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

@@ -0,0 +1,18 @@
+---
+description: PlayCraft sub-agent file boundaries — no user gates, STOP protocol
+globs: .claude/agents/**,docs/**,logs/**,assets/**,game/**
+alwaysApply: false
+---
+
+# Sub-Agent Boundary
+
+When editing project outputs as a **sub-agent** (PM / Designer / TA / Developer / Reviewer):
+
+- **Do not** `AskUserQuestion` or ask the user to choose Gate options.
+- On gate-ready work: update `## Agent handoff` YAML + `gates.#*` = `pending` + Progress Checkpoint → **STOP** (see `## Runtime` in your agent file).
+- If `subagent_stop: true` for your role → do not duplicate work; wait for orchestrator.
+- Read `docs/team/agent-conduct.md` and your `.claude/agents/<role>.md` § Runtime + § Agent Conduct.
+- **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 `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`.