openspec-playwright 0.2.8 → 0.2.10

package/.claude/skills/openspec-e2e/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`).
 metadata:
   author: openspec-playwright
-  version: "2.20"
+  version: "2.24"
 ---
 
 ## Input
@@ -44,13 +44,7 @@ Both modes update `app-knowledge.md` and `app-exploration.md`. All `.spec.ts` fi
 用户操作 → 浏览器 UI → 后端 → 数据库 → UI 反馈
 ```
 
-**API only as fallback** — Use `page.request` only when UI genuinely cannot cover the scenario:
-
-- Triggering HTTP 5xx/4xx error responses (hard to reach via UI)
-- Edge cases requiring pre-condition data that UI cannot set up
-- Cases where Step 4 exploration confirmed no UI element exists
-
-**Setup vs Assertion**: API is acceptable for **setup/precondition** (preparing test data). Every **final assertion** about visible UI state must use UI selectors — never use `page.request` to assert something the user can see on screen.
+**API only as fallback** — See **Mock data rule** below. `page.request` is acceptable for pre-condition setup (preparing test data) and API-level mocking via `page.route()`. Every **final assertion** about visible UI state must use UI selectors — never use `page.request` to assert something the user can see on screen.
 
 **Decision rule (per assertion)**:
 
@@ -71,7 +65,24 @@ Is the assertion about a computed/counted/calculated value?
   → No  → UI assertion is sufficient
 ```
 
-**Examples where API assertion is required:**
+**Mock data rule:**
+
+- **Frontend: forbidden.** UI interactions must use real browser + real app data. Mocking frontend code (JS variables, component state, module-level stubs) hides real integration issues. If the frontend cannot reach a scenario through normal UI flow → **ask the user**.
+- **API: allowed at HTTP level.** Use `page.route()` to intercept and mock API responses (status codes, body data, latency) when:
+  - Triggering HTTP 5xx/4xx error responses (hard to reach via UI)
+  - Edge cases requiring pre-condition data that UI cannot set up
+  - Third-party API failures (payment, SMS, email providers)
+  - **Scope: API level only** — `page.route()` intercepts HTTP; do NOT mock at the database or backend service level. Mocking below the HTTP layer bypasses the real API contract and produces false confidence.
+- **User consent required.** Before using `page.route()` mocking, stop and ask:
+  ```
+  API mocking needed for: <reason>
+  Mocked endpoint: <URL or pattern>
+  Expected behavior: <what the test verifies>
+  Reply **yes** to proceed, or tell me to find a UI-based approach instead.
+  ```
+  If the user says no → attempt a UI-based approach or skip that test case.
+
+**Examples where API assertion is required:
 
 ```typescript
 // ❌ UI-only assertion — hides calculation bugs
@@ -316,8 +327,6 @@ Record findings in `app-exploration.md` → **Special Elements Detected** table.
 
 Output: `openspec/changes/<name>/specs/playwright/app-exploration.md`
 
-Template: read from `.claude/skills/openspec-e2e/templates/app-exploration.md` (project-local skill directory)
-
 Key fields per route:
 
 - **URL**: `${BASE_URL}<path>`
@@ -349,7 +358,7 @@ After writing `app-exploration.md`, extract **project-level shared knowledge** a
 | Common Selector Patterns | New patterns discovered that apply across routes                          |
 | SPA Routing              | SPA framework, routing behavior                                           |
 | Project Conventions      | BASE_URL, auth method, multi-user roles                                   |
-| Selector Fixes           | Healed selectors (see Step 9) — route, old selector, new selector, reason |
+| Selector Fixes           | Healed selectors (see Step 9) — route, old → new selector, reason, date |
 
 Append only new/changed items — preserve existing content.
 
@@ -383,7 +392,7 @@ Reply **yes** to proceed, or tell me to exclude routes or adjust strategies.
 
 **Create test cases**: functional requirement → test case, with `@role` and `@auth` tags. Reference verified selectors from app-exploration.md.
 
-Template: `.claude/skills/openspec-e2e/templates/test-plan.md`
+If a test case requires `page.route()` API mocking → append `⚠️ API Mock` flag to the test case line in the summary, with reason.
 
 **Idempotency**: If test-plan.md exists → read and use, **but you MAY supplement missing test cases**. "Do not regenerate" means: do not discard existing cases, but you CAN add new ones discovered during Step 4 exploration that weren't in the original spec (e.g., empty states, error paths found during DOM exploration).
 
@@ -430,8 +439,6 @@ If the user requests changes → update test-plan.md → re-display summary →
 
 **Page Object pattern** — read before writing any page file:
 
-Read: `.claude/skills/openspec-e2e/templates/e2e-test.ts` → LoginPage example
-
 ```typescript
 // ✅ 正确：getters + async actions + this.click/fill
 export class LoginPage extends BasePage {
@@ -497,7 +504,7 @@ Is this assertion about a visible UI result?
 
 **Test coverage — empty states**: For list/detail pages, explore the empty state. If the app shows a "no data" UI when the list is empty, generate a test to verify it. Empty states are often missing from specs but are real user paths.
 
-**Test coverage — special elements**: Check `app-exploration.md` → **Special Elements Detected** table. For each special element, generate tests using templates from `.claude/skills/openspec-e2e/templates/test-plan.md` → **Special Element Test Cases**:
+**Test coverage — special elements**: Check `app-exploration.md` → **Special Elements Detected** table. For each special element, generate tests using the following strategies:
 - Canvas: screenshot + boundingBox → dimensions > 0, or 2D pixel verification
 - WebGL: screenshot only (no pixel comparison — rendering varies)
 - Iframe: `frameLocator` + assert inner content visible
@@ -508,7 +515,7 @@ Is this assertion about a visible UI result?
 **Test coverage — AI-opaque elements**: For CAPTCHA, OTP, slider CAPTCHA, file upload, and drag-drop — elements that Playwright cannot reliably automate:
 
 1. Mark the element in `app-exploration.md` → **Special Elements Detected** table with type and automation strategy
-2. Generate the test using the appropriate strategy from `.claude/skills/openspec-e2e/templates/test-plan.md` → **AI-Opaque Elements** section:
+2. Generate the test using the appropriate strategy:
    - **CAPTCHA**: Bypass via `auth.setup.ts` storageState, or skip with `test.skip()`, or verify via API
    - **OTP**: Use pre-verified test credentials (`E2E_OTP_CODE` env var), or development bypass flag
    - **File upload**: Use `page.setInputFiles()` with fixture files
@@ -586,7 +593,7 @@ test('user can login', async ({ page }) => {
 | `getByRole`, `getByTestId`, `getByLabel` | CSS class (`'.notification-bell'`), CSS ID (`'#avatarBtn'`) |
 | `waitForSelector(targetElement)` | hardcoded `200ms` / `500ms` delays |
 
-See `.claude/skills/openspec-e2e/templates/e2e-test.ts` for full examples of Page Object pattern, UI-first flows, error paths, auth guards, session handling, and visual regression.
+See above for Page Object pattern, LoginPage example, and BasePage utilities.
 
 If the file exists → diff against test-plan, add only missing test cases.
 
@@ -621,7 +628,7 @@ Auth required. To set up:
 
 **Output**: `playwright.config.ts` (project root; or `tests/playwright/playwright.config.ts` if config already exists there)
 
-If missing → generate from `.claude/skills/openspec-e2e/templates/playwright.config.ts`.
+If missing → generate a minimal `playwright.config.ts` with webServer, projects, and reporters.
 
 **Auto-detect BASE_URL** (in priority order):
 
@@ -660,6 +667,10 @@ If tests fail → use Playwright MCP tools to inspect UI, fix selectors, re-run.
 | `browser_take_screenshot`  | Visually compare before/after fixes             |
 | `browser_run_code`         | Execute custom fix logic (optional)             |
 
+**Before Phase 1 — check accumulated knowledge:**
+
+Read `tests/playwright/app-knowledge.md` → **Selector Fixes** table. If the failing test's selector or route matches a known fix, use it directly (skip Phase 2). If partial match → use as the top candidate in Phase 2 Step 5a. If file does not exist → skip.
+
 **Healer — Phase 1: Triage**
 
 When a test fails, classify before attempting repair.
@@ -761,9 +772,29 @@ After Triage classifies failure as "Test Bug" or "Ambiguous":
    - Data values differ (e.g., expected "¥1000" but got "¥999" → **Phase 3**, could be rounding, discount, or calculation bug)
    - Missing elements after interaction (e.g., "after creating order, success message should appear" → no message → **Phase 3**)
 
-5. If selector issue → find equivalent stable selector from snapshot
+5. If selector issue → generate candidate list, then select:
+
+   **5a. Extract candidates** — identify the target element from the failing test's assertion, then from the snapshot list all selectors for that element:
+
+   First check `app-knowledge.md` → **Common Selector Patterns** for project-specific conventions (e.g., if project uses Tailwind and `.btn-primary` is listed as preferred → treat it as Fair or higher, not Fragile).
+
+   ```
+   Target: <element from failing assertion, e.g. "button with text 'Submit'">
+   Candidates (stable → fragile):
+   - getByRole(button, { name: 'Submit' })   ← Stable (semantic)
+   - getByText('Submit')                       ← Fair (unique text)
+   - getByLabel('Email')                       ← Fair (form fields)
+   - locator('#submit')                         ← Fair (id attribute)
+   - locator('.btn-primary')                   ← Fragile (style class) — upgrade if listed in Common Selector Patterns
+   - locator('button:nth-child(3)')            ← Fragile (DOM order)
+   ```
+
+   Stability: `getByRole` > `getByText`/`getByLabel` > `locator('#id')` > `locator('.class')` > `locator('nth-child')`. Upgrade stability if `app-knowledge.md` → **Common Selector Patterns** explicitly lists the selector as preferred for this project.
+
+   **5b. Select top candidate** — pick the highest-stability candidate that matches the target. Output: `SELECTED: <selector> — reason: <why this one>`.
+
 6. Apply fix → re-run **only that test** (attempt 1/3)
-7. If healed → append to `app-knowledge.md` → **Selector Fixes** table (route, old → new selector, reason)
+7. If healed → append to `app-knowledge.md` → **Selector Fixes** table (route, old → new selector, reason, date)
 
 **Element Missing handling (when browser_snapshot shows element not found):**
 
@@ -858,7 +889,7 @@ Read report at `openspec/reports/playwright-e2e-<name>-<timestamp>.md`. Present:
 - Human Escalations (if any, with user decision)
 - Recommendations with `file:line` references
 
-Report template: `.claude/skills/openspec-e2e/templates/report.md`
+Generate report based on the structure described in Step 11.
 
 **Update tasks.md**:
 - If 0 active App Bugs → find E2E-related items, append `✅ Verified via Playwright E2E (<timestamp>)`.

package/employee-standards.md

@@ -1,50 +1,97 @@
-# Claude Code Employee-Grade Configuration
+# Claude Code Employee-Grade Configuration + gstack + openspec-playwright 生产闭环
 
 > 员工级行为规范，适用于 OpenSpec 项目。
-> 遵循 OpenSpec 规范驱动开发流程（详见 /openspec/）。
+> 严格遵循 OpenSpec 规范驱动开发 + gstack 角色化虚拟工程团队 + Playwright 自动 E2E 验证。
 
 ---
 
-## 一、代码质量
+## 0. 适用范围
 
-**lint + typecheck 后才能算成功**。动手前，先探索项目用什么工具：查看 `package.json` scripts、`Makefile`、`pyproject.toml`、`justfile` 等，找到该语言的 lint + typecheck 命令并执行。工具不存在时，明确告知用户，不得假装成功。
+本规范适用于 OpenSpec + openspec-playwright 项目（Claude Code 作为开发工具）。
 
-**拒绝'够用就行'**。架构缺陷、状态重复、模式不一致——说出来并修复。
+E2E 工作流前提（由用户确保，非 AI 操作）：
+- OpenSpec CLI：`npm install -g @fission-ai/openspec && openspec init`（提供 `/opsx:propose`、`/opsx:archive` 等命令）
+- openspec-playwright：`openspec-pw init`（提供 `/opsx:e2e` 命令）
+- Playwright MCP：`claude mcp add playwright npx @playwright/mcp@latest`
+- 浏览器已安装：`npx playwright install --with-deps`
+- 项目包含 `specs/`、`changes/`、`tests/playwright/` 目录
 
-**安全防护因语言/场景而异**。写 Go 时想内存安全，写 Python 时想反序列化，写 Web 时参考 [OWASP Top 10](https://owasp.org/Top10/)，写 API 时参考 [OWASP API Top 10](https://owasp.org/API-Security/)。先了解所用场景的风险模型。
+## 1. 浏览器操作约束
 
----
+所有浏览器操作**必须**使用 gstack 的 `/browse`（禁止使用其他 MCP Chrome 工具）。
 
-## 二、上下文管理
+Claude Code 会根据上下文自动调度 gstack 技能，无需手动路由。
 
-**文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖了完整文件——根据需要分次读取相关段落，或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
+**冲突解决**：gstack 任何想直接修改代码的行为，都必须先确认当前 OpenSpec proposal 是否已存在并通过（检查 `changes/<name>/proposal.md` 是否处于 `approved` 状态）。
 
-**OpenSpec 阶段隔离**：`specs/playwright/`、`tests/playwright/`（seed 除外）和 `test-plan.md` 由 `/opsx:e2e` 显式触发，不由 explore/propose/continue/apply/verify 等阶段自动推断。E2E 工作流是独立的。
+## 2. 代码质量（强制执行）
+**lint + typecheck 后才能算成功**。动手前，先探索项目用什么工具：查看 `package.json` scripts、`Makefile`、`pyproject.toml`、`justfile` 等，找到该语言的 lint + typecheck 命令并执行。工具不存在时，明确告知用户，不得假装成功。
 
-**重构前清死代码**：未使用的 import/export/prop/console.log 先删掉，单独提交，再做重构。
+**拒绝"够用就行"**。架构缺陷、状态重复、模式不一致——必须说出来并修复。
 
----
+**安全防护**：写 Go 时关注内存安全，写 Python 时关注反序列化，写 Web/API 时参考 OWASP Top 10 / OWASP API Top 10。先了解所用场景的风险模型。
+
+## 3. 上下文管理
+**文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖完整内容——根据需要分次读取或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
 
-## 三，大规模任务
+**OpenSpec 阶段隔离**：`specs/playwright/`、`tests/playwright/`（seed 除外）和 `test-plan.md` 由 `/opsx:e2e` 显式触发，不由 explore/propose/continue/apply/verify 等阶段自动推断。E2E 工作流是独立的。
+
+**重构前清死代码**：未使用的 import/export/prop/console.log 先删掉，单独提交，再做重构。
 
+## 4. 大规模任务处理
 **子 Agent 并行化**：任务涉及超过 5 个独立文件时，启动并行子 agent（每个 5-8 个文件），每个拥有独立 token budget。
 
 **分阶段执行**：每个阶段不超过 5 个文件，完成后验证，等待用户批准再继续。
 
-**200 行以上修改必须走 OpenSpec**：代码改动超过 200 行时，禁止直接修改，必须通过 OpenSpec 工作流。
+**200 行以上修改必须走 OpenSpec**：代码改动超过 200 行时，禁止直接修改，必须通过 OpenSpec 工作流（/opsx:propose）。
 
----
+## 5. 工具限制与编辑安全
+**搜索要全**：重命名时，用 Grep 覆盖调用、类型、字符串、`import`、barrel file、测试 mock，不得假设一次覆盖所有情况。
 
-## 四、工具限制
+**编辑要求**：编辑后重新读取文件确认变更正确应用。同一文件连续编辑不超过 3 次，中间必须重新读取。变更完成后，明确告知用户可能遗漏的区域（动态引用、测试 mock 等），提示人工复查。
 
-**搜索要全**：重命名时，用 Grep 覆盖调用、类型、字符串、`import`、barrel file、测试 mock，不得假设一次覆盖所有情况。
+**不主动推送**：除非用户明确要求，否则不推送代码。
+
+**中文回复**：用中文回复用户。
 
 ---
 
-## 五、编辑安全
+## 6. 完整生产工作流（严格执行 + 反馈循环）
 
-**编辑要求**：编辑后重新读取文件确认变更正确应用。同一文件连续编辑不超过 3 次，中间必须重新读取。变更完成后，明确告知用户可能遗漏的区域（动态引用、测试 mock 等），提示人工复查。
+```
+1. 探索与提案 → /opsx:propose → 生成 proposal + scenarios
+2. 产品与架构思考（按需触发）
+3. 设计审查 → Build（遵守 OpenSpec delta markers）→ /review 自审
+4. E2E 测试 → /opsx:e2e <change-name> → /qa（真实浏览器 + healer）
+5. 验证通过后 → /opsx:archive
+6. 发布 → /ship 或 /land-and-deploy
+7. 迭代回顾 → /retro
+```
 
-**不主动推送**：除非用户明确要求，否则不推送代码。
+### 步骤详解
 
-**中文回复**：用中文回复用户。
+**1. 探索与规范**：`/opsx:propose` → 生成 proposal + scenarios（记录到 `specs/` 和 `changes/`）。对 proposal 进行评审和调整。如需代码探索，单独使用 `/opsx:explore`（不是生成规范）。
+
+**2. 产品与架构思考**（按需触发，不是每个功能都走）：
+- `/office-hours`：产品方向、范围、优先级不确定时
+- `/plan-ceo-review`：产品战略影响、竞争格局变化时
+- `/plan-eng-review`：架构影响（新增服务、API 契约变更、数据模型重构）时
+
+**3. 设计与实现**：设计审查 → Build（遵守 OpenSpec delta markers），过程中 `/review` 自审。构建完成后，E2E 测试覆盖通过才能继续。
+
+**4. E2E 测试生成与执行**：`/opsx:e2e <change-name>` 生成 Playwright 测试并执行 → 执行 `/qa`（真实浏览器 + healer）验证。E2E 通过后进入发布环节。
+
+**5. 验证通过后**：`/opsx:archive` 永久归档，更新 `specs/`
+
+**6. 发布**：`/ship` 或 `/land-and-deploy`
+
+**7. 迭代回顾**：`/retro`
+
+### 反馈循环（生产中必然发生）
+
+| 信号 | 回到 |
+|------|------|
+| 测试失败（App Bug） | 步骤 3 修复后 → 步骤 4 重新测试 |
+| 发现架构问题 | 步骤 2 重新评审 → 步骤 3 修复 |
+| proposal 需调整 | 步骤 1 重新提案 |
+| 评审不通过 | 回到对应步骤重新处理 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "OpenSpec + Playwright E2E verification setup tool for Claude Code",
   "type": "module",
   "bin": {