openspec-playwright 0.2.9 → 0.3.0

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

@@ -2,10 +2,10 @@
 name: openspec-e2e
 description: Run Playwright E2E verification for an OpenSpec change. Use when the user wants to validate that the implementation works end-to-end by running Playwright tests generated from the specs.
 license: MIT
-compatibility: Requires openspec CLI, Playwright (with browsers installed), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`).
+compatibility: Requires openspec CLI, Playwright (with browsers installed), /browse (gstack, for exploration), and @playwright/mcp (globally installed via `claude mcp add playwright npx @playwright/mcp@latest`, for test execution + Healer).
 metadata:
   author: openspec-playwright
-  version: "2.22"
+  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
@@ -118,8 +129,8 @@ expect((await post.json()).likeCount).toBeGreaterThan(0); // verify persistence
 - Announce: "Mode: full app exploration + Page Object discovery"
 - **Goal**: Discover new routes, extract selectors, and build `pages/*.ts` Page Objects — accumulated asset for future Change tests
 - **Route discovery** (in order):
-  1. **sitemap.xml**: `browser_navigate(${BASE_URL}/sitemap.xml)` → parse URLs
-  2. **Link extraction**: Navigate to `${BASE_URL}/` → `browser_evaluate` extracts all `<a href>`:
+  1. **sitemap.xml**: `$B goto ${BASE_URL}/sitemap.xml` → parse URLs
+  2. **Link extraction**: Navigate to `${BASE_URL}/` → `$B js` extracts all `<a href>`:
      ```javascript
      // Extract all internal links from current page
      () => {
@@ -188,16 +199,16 @@ Explore to collect real DOM data before writing test plan. This eliminates blind
 
 #### 4.1. Verify BASE_URL + Read app-knowledge.md
 
-1. **Verify BASE_URL**: `browser_navigate(BASE_URL)` → if HTTP 5xx → **STOP: backend error. Fix app first.**
+1. **Verify BASE_URL**: `$B goto <BASE_URL>` → if HTTP 5xx → **STOP: backend error. Fix app first.**
 2. **Read app-knowledge.md**: known risks, project conventions
 3. **Routes** (from Step 1): use already-discovered routes — no need to re-extract
 
-#### 4.2. Explore each route via Playwright MCP
+#### 4.2. Explore each route via /browse
 
 For each route:
 
 ```
-browser_navigate → browser_console_messages → browser_snapshot → browser_take_screenshot
+$B goto <url> → $B console → $B snapshot → $B screenshot
 ```
 
 **After navigating, check for app-level errors**:
@@ -214,43 +225,42 @@ browser_navigate → browser_console_messages → browser_snapshot → browser_t
 
 ```
 // 1. Initial capture
-await browser_navigate(`${BASE_URL}/<route>`);
-await new Promise(r => setTimeout(r, 1500)); // wait for SPA hydration
-const url1 = await browser_evaluate(() => window.location.href);
+$B goto <url>
+$B wait --networkidle    // wait for SPA hydration
+$B js "window.location.href"    // url1
+$B wait 2000
 
 // 2. Observe stability
-await new Promise(r => setTimeout(r, 2000));
-const url2 = await browser_evaluate(() => window.location.href);
-const msgs = await browser_console_messages();
+$B js "window.location.href"    // url2
+$B console --errors
 
 // 3. Detect
 if (url1 !== url2) {
-  → ❌ URL changed — redirect loop (ERR_TOO_MANY_REDIRECTS)
-  → Is this route protected without valid auth.storageState?
+  → ❌ URL changed — redirect loop
+  → Is this route protected without valid auth?
     → Yes → auth.setup.ts is broken → fix auth first
     → No → App middleware bug → mark route ❌ skip, record as App Bug
 }
-if (msgs.filter(m => m.type === 'warning' || m.type === 'error').length > 10) {
+if (console errors/warnings > 10) {
   → ❌ Excessive console errors — page refresh / JS crash loop
   → Mark route ❌ skip, record as App Bug
 }
 ```
 
-**Network monitoring**: After navigating, use `browser_network_requests` to check for failed API calls. Failed requests (status ≥ 400) on a route indicate an API/backend issue — record in `app-exploration.md` for reference.
+**Network monitoring**: After navigating, use `$B network` to check for failed API calls. Failed requests (status ≥ 400) on a route indicate an API/backend issue — record in `app-exploration.md` for reference.
 
 **For guest routes** (no auth):
 
-```javascript
-// Navigate directly
-await browser_navigate(`${BASE_URL}/<route>`);
+```
+$B goto <url>
 ```
 
 **For protected routes** (auth required):
 
-```javascript
+```
 // Option A: use existing storageState (recommended)
 // Option B: navigate to /login first, fill form, then navigate to target
-// Option C: use browser_run_code to set auth cookies directly
+// Option C: $B cookie to set auth cookies directly
 ```
 
 **If credentials are not yet available**:
@@ -268,7 +278,7 @@ Wait for page stability:
 
 #### 4.3. Parse the snapshot
 
-From `browser_snapshot` output, extract **interactive elements** for each route:
+From `$B snapshot` output, extract **interactive elements** for each route:
 
 | Element type         | What to capture                      | Selector priority                                          |
 | -------------------- | ------------------------------------ | ---------------------------------------------------------- |
@@ -282,7 +292,7 @@ From `browser_snapshot` output, extract **interactive elements** for each route:
 
 #### 4.3.1. Detect special elements
 
-From `browser_snapshot` + `browser_evaluate`, identify these special elements per route:
+From `$B snapshot` + `$B js`, identify these special elements per route:
 
 **Special element detection matrix:**
 
@@ -299,9 +309,9 @@ From `browser_snapshot` + `browser_evaluate`, identify these special elements pe
 | Drag-and-drop | drag events in JS | Simulate DnD via coordinate clicks | Low |
 | Date picker | specific `data-testid` or class patterns | Click triggers → evaluate value | Low (skip unless specs mention) |
 | Infinite scroll | Dynamic row insertion | Count elements before/after scroll | Low (skip unless specs mention dynamic lists/pagination) |
-| WebSocket / SSE | No DOM signal | Check `browser_console_messages` for WS events | Low (check only if app uses real-time features) |
+| WebSocket / SSE | No DOM signal | Check `$B console --errors` for WS events | Low (check only if app uses real-time features) |
 
-**For each detected special element, capture via `browser_evaluate` with targeted DOM queries:**
+**For each detected special element, capture via `$B js` with targeted DOM queries:**
 - Canvas: `getContext('webgl2'/'webgl'/'2d')`, `width`, `height`
 - Iframe: `src` attribute → use `frameLocator` in tests
 - CAPTCHA: `.g-recaptcha`, `.h-captcha`, `[data-sitekey]`, canvas+slider detection
@@ -316,8 +326,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>`
@@ -383,7 +391,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 +438,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 +503,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 +514,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 +592,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.
 
@@ -615,13 +621,13 @@ Auth required. To set up:
 
 **Idempotency**: If `auth.setup.ts` already exists → verify format, update only if stale.
 
-**Post-auth re-exploration**: If Step 4 skipped protected routes due to missing auth, re-run exploration for those routes now that auth is configured. Navigate to each protected route with auth context → `browser_snapshot` → update `app-exploration.md`. Selectors verified now are better than guesses used during test generation.
+**Post-auth re-exploration**: If Step 4 skipped protected routes due to missing auth, re-run exploration for those routes now that auth is configured. Navigate to each protected route with auth context → `$B snapshot` → update `app-exploration.md`. Selectors verified now are better than guesses used during test generation.
 
 ### 8. Configure playwright.config.ts
 
 **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):
 
@@ -882,7 +888,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/README.md

@@ -20,7 +20,7 @@ openspec-pw init          # Install Playwright E2E integration
 
 ## Supported AI Coding Assistants
 
-Claude Code — E2E workflow is driven by SKILL.md using Playwright MCP tools (`/opsx:e2e <change-name>`).
+Claude Code — E2E workflow is driven by SKILL.md using /browse (exploration) + Playwright MCP (test execution).
 
 ## Usage
 
@@ -52,7 +52,7 @@ openspec-pw uninstall     # Remove integration from the project
   │
   ├── 3. Validate env → run seed.spec.ts
   │
-  ├── 4. Explore app → Playwright MCP explores real DOM
+  ├── 4. Explore app → /browse explores real DOM
   │       ├─ Read app-knowledge.md (project-level knowledge)
   │       ├─ Extract routes from specs
   │       ├─ Navigate each route → snapshot → screenshot
@@ -77,13 +77,10 @@ openspec-pw uninstall     # Remove integration from the project
 ## Prerequisites
 
 1. **Node.js >= 20**
-2. **OpenSpec** initialized: `npm install -g @fission-ai/openspec && openspec init`
-3. **Claude Code** with `.claude/` directory
-
-After prerequisites, install Playwright MCP:
-```bash
-claude mcp add playwright npx @playwright/mcp@latest
-```
+2. **Claude Code** with `.claude/` directory
+3. **gstack** (for exploration + browser QA): `git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`
+4. **OpenSpec** initialized: `npm install -g @fission-ai/openspec && openspec init`
+5. **Playwright MCP** (for test execution + Healer): `claude mcp add playwright npx @playwright/mcp@latest`
 
 ## What `openspec-pw init` Does
 
@@ -101,14 +98,15 @@ Run through these steps in order when using the E2E workflow for the first time:
 | Step | Command | If it fails |
 |------|---------|-------------|
 | 1. Install CLI | `npm install -g openspec-playwright` | Check Node.js version `node -v` (needs >= 20) |
-| 2. Install OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
-| 3. Initialize E2E | `openspec-pw init` | Run `openspec-pw doctor` to see what's missing |
-| 4. Install Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` to confirm installation |
-| 5. Install browsers | `npx playwright install --with-deps` | macOS may need `xcode-select --install` first |
-| 6. Start dev server | `npm run dev` (in a separate terminal) | Confirm port, set `BASE_URL` if non-standard |
-| 7. Validate env | `npx playwright test tests/playwright/seed.spec.ts` | Check `webServer` in `playwright.config.ts` |
-| 8. Configure auth (if needed) | See "Authentication" below | Debug with `npx playwright test --project=setup` |
-| 9. Run first E2E | `/opsx:e2e <change-name>` | Check `openspec/reports/` for the report |
+| 2. Install gstack | `git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup` | Requires Bun: `curl -fsSL https://bun.sh/install | bash` |
+| 3. Install OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
+| 4. Initialize E2E | `openspec-pw init` | Run `openspec-pw doctor` to see what's missing |
+| 5. Install Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` to confirm installation |
+| 6. Install browsers | `npx playwright install --with-deps` | macOS may need `xcode-select --install` first |
+| 7. Start dev server | `npm run dev` (in a separate terminal) | Confirm port, set `BASE_URL` if non-standard |
+| 8. Validate env | `npx playwright test tests/playwright/seed.spec.ts` | Check `webServer` in `playwright.config.ts` |
+| 9. Configure auth (if needed) | See "Authentication" below | Debug with `npx playwright test --project=setup` |
+| 10. Run first E2E | `/opsx:e2e <change-name>` | Check `openspec/reports/` for the report |
 
 ## Authentication
 

package/README.zh-CN.md

@@ -13,13 +13,10 @@ npm install -g openspec-playwright
 ## 前置条件
 
 1. **Node.js >= 20**
-2. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
-3. **Claude Code** 且项目中有 `.claude/` 目录
-
-安装 Playwright MCP：
-```bash
-claude mcp add playwright npx @playwright/mcp@latest
-```
+2. **Claude Code** 且项目中有 `.claude/` 目录
+3. **gstack**（用于探索 + 浏览器 QA）：`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`
+4. **OpenSpec** 已初始化: `npm install -g @fission-ai/openspec && openspec init`
+5. **Playwright MCP**（用于测试执行 + Healer）：`claude mcp add playwright npx @playwright/mcp@latest`
 
 ## 初始化
 
@@ -33,7 +30,7 @@ openspec-pw init          # 安装 Playwright E2E 集成
 
 ## 支持的 AI 编码助手
 
-Claude Code — E2E 工作流由 SKILL.md 驱动，使用 Playwright MCP 工具（`/opsx:e2e <change-name>`）。
+Claude Code — E2E 工作流由 SKILL.md 驱动，使用 /browse（探索）+ Playwright MCP（测试执行）。
 
 ## 使用
 
@@ -65,7 +62,7 @@ openspec-pw uninstall     # 移除项目中的集成
   │
   ├── 3. 验证环境 → 运行 seed.spec.ts
   │
-  ├── 4. 探索应用 → Playwright MCP 探索真实 DOM
+  ├── 4. 探索应用 → /browse 探索真实 DOM
   │       ├─ 读取 app-knowledge.md（项目级知识）
   │       ├─ 从 specs 提取路由
   │       ├─ 遍历每个路由 → snapshot → screenshot
@@ -102,14 +99,15 @@ openspec-pw uninstall     # 移除项目中的集成
 | 步骤 | 命令 | 失败时快速修复 |
 |------|------|----------------|
 | 1. 安装 CLI | `npm install -g openspec-playwright` | 检查 Node.js 版本 `node -v`（需 >= 20） |
-| 2. 安装 OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
-| 3. 初始化 E2E | `openspec-pw init` | 运行 `openspec-pw doctor` 查看具体缺失项 |
-| 4. 安装 Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` 确认安装成功 |
-| 5. 安装浏览器 | `npx playwright install --with-deps` | macOS 可能需先运行 `xcode-select --install` |
-| 6. 启动开发服务器 | `npm run dev`（在另一个终端） | 确认端口，配置 `BASE_URL` |
-| 7. 验证环境 | `npx playwright test tests/playwright/seed.spec.ts` | 检查 `playwright.config.ts` 中的 `webServer` 配置 |
-| 8. 配置认证（如需要） | 见下方"认证配置" | `npx playwright test --project=setup` 调试 |
-| 9. 运行第一个 E2E | `/opsx:e2e <change-name>` | 查看 `openspec/reports/` 中的报告 |
+| 2. 安装 gstack | `git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup` | 需要 Bun：`curl -fsSL https://bun.sh/install \| bash` |
+| 3. 安装 OpenSpec | `npm install -g @fission-ai/openspec && openspec init` | `npm cache clean -f && npm install -g @fission-ai/openspec` |
+| 4. 初始化 E2E | `openspec-pw init` | 运行 `openspec-pw doctor` 查看具体缺失项 |
+| 5. 安装 Playwright MCP | `claude mcp add playwright npx @playwright/mcp@latest` | `claude mcp list` 确认安装成功 |
+| 6. 安装浏览器 | `npx playwright install --with-deps` | macOS 可能需先运行 `xcode-select --install` |
+| 7. 启动开发服务器 | `npm run dev`（在另一个终端） | 确认端口，配置 `BASE_URL` |
+| 8. 验证环境 | `npx playwright test tests/playwright/seed.spec.ts` | 检查 `playwright.config.ts` 中的 `webServer` 配置 |
+| 9. 配置认证（如需要） | 见下方"认证配置" | `npx playwright test --project=setup` 调试 |
+| 10. 运行第一个 E2E | `/opsx:e2e <change-name>` | 查看 `openspec/reports/` 中的报告 |
 
 ## 认证配置
 

package/employee-standards.md

@@ -1,50 +1,111 @@
-# 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 操作）：
+- gstack：`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`（提供 `/browse` 探索 + `/qa` 浏览器验证）
+- OpenSpec CLI：`npm install -g @fission-ai/openspec && openspec init`（提供变更管理能力）
+- openspec-playwright：`openspec-pw init`（提供 `/opsx:e2e` 命令）
+- Playwright MCP：`claude mcp add playwright npx @playwright/mcp@latest`（用于测试执行 + Healer）
+- 浏览器已安装：`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` 探索 + `/qa` 验证，Playwright MCP 执行测试。Claude Code 会根据上下文自动调度，无需手动路由。
 
-## 二、上下文管理
+**冲突解决**：gstack 任何想直接修改代码的行为，都必须先确认当前 OpenSpec proposal 是否已存在并通过（检查 `changes/<name>/proposal.md` 是否处于 `approved` 状态）。
 
-**文件读取完整**：超过 500 行的文件，不要假设单次读取覆盖了完整文件——根据需要分次读取相关段落，或编辑前重新读取完整文件。超过 10 条消息后，编辑任何文件前强制重新读取。
+## 2. 代码质量（强制执行）
+**lint + typecheck 后才能算成功**。动手前，先探索项目用什么工具：查看 `package.json` scripts、`Makefile`、`pyproject.toml`、`justfile` 等，找到该语言的 lint + typecheck 命令并执行。工具不存在时，明确告知用户，不得假装成功。
 
-**OpenSpec 阶段隔离**：`specs/playwright/`、`tests/playwright/`（seed 除外）和 `test-plan.md` 由 `/opsx:e2e` 显式触发，不由 explore/propose/continue/apply/verify 等阶段自动推断。E2E 工作流是独立的。
+**拒绝"够用就行"**。架构缺陷、状态重复、模式不一致——必须说出来并修复。
 
-**重构前清死代码**：未使用的 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. 探索与提案
+ 2. 产品与架构评审（按需触发）
+ 3. 设计审查
+ 4. 实现 → /opsx:apply
+ 5. 自审 → /opsx:verify /design-review /review
+ 6. E2E 测试 → /opsx:e2e <change-name> → /browse 探索 + /qa 验证
+ 7. 验证通过后归档 → /opsx:archive
+ 8. 发布 → /ship 或 /land-and-deploy
+ 9. 迭代回顾 → /retro
+```
 
-**不主动推送**：除非用户明确要求，否则不推送代码。
+### 步骤详解
 
-**中文回复**：用中文回复用户。
+**1. 探索与提案**：现有项目先探索（`/opsx:explore`）再写 proposal（`/opsx:propose`）；新项目（greenfield）直接生成 proposal + scenarios（记录到 `specs/` 和 `changes/`）。
+
+**2. 产品与架构评审**（按需触发）：
+- `/office-hours`：产品方向、范围、优先级不确定时
+- `/plan-ceo-review`：产品战略影响、竞争格局变化时
+- `/plan-eng-review`：架构影响（新增服务、API 契约变更、数据模型重构）时
+
+**3. 设计审查**：在实现前进行设计评审，确保方案合理。评审通过后开始实现。
+
+**4. 实现**：执行 `/opsx:apply` 进行实现 → `lint + typecheck` 通过才算成功。
+
+**5. 自审**：`/opsx:verify` `/design-review` `/review` 自审实现代码，确保质量。**设计审查后**，对 HTML/CSS 文件执行 CSS 结构审计（防止 `/design-review` 靠截图漏检间距问题）：
+
+```
+两步式审计：
+1. 确定间距基准 — 查 CSS variables / Tailwind spacing / Bootstrap $spacer
+   grep 'gap:|padding:|margin:' *.html → 提取值 → 对比基准，列低于基准的项
+2. 检查 margin hack — 同一 grid/flex 容器中相邻元素各自用 margin 硬撑间距
+   信号：两个子元素的 margin 和 > 基准间距 2 倍 → 应改为 grid 行或 gap 控制
+   例：.desc{margin-b:36}+.btn{margin-t:80} 在同一 row → grid 行分离
+```
+
+**6. E2E 测试生成与执行**：`/opsx:e2e <change-name>` 生成 Playwright 测试 → `/browse` 探索真实 DOM → Healer 自动修复 → `/qa` 真实浏览器验证。E2E 通过后进入发布环节。
+
+**7. 验证通过后归档**：`/opsx:archive` 永久归档，更新 `specs/`
+
+**8. 发布**：`/ship` 或 `/land-and-deploy`
+
+**9. 迭代回顾**：`/retro`
+
+### 反馈循环（生产中必然发生）
+
+| 信号 | 回到 |
+|------|------|
+| 测试失败（App Bug） | 回到步骤 4 修复 → 重新测试 |
+| 发现架构问题 | 回到步骤 2 重新评审 → 步骤 4 修复 |
+| Proposal 需调整 | 回到步骤 1 重新提案 |
+| 评审不通过 | 回到对应步骤重新处理 |

package/package.json

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

package/templates/test-plan.md

@@ -217,7 +217,7 @@ Bypass OTP UI entirely and test the protected endpoint directly.
 
 **Test approach:**
 ```
-1. Identify drag handle and drop target via Playwright MCP snapshot
+1. Identify drag handle and drop target via /browse snapshot
 2. Use `page.dragAndDrop()` or `locator.dragTo()`
 3. If custom implementation uses JS events, use `page.evaluate()` to dispatch events
 4. Assert: target state reflects the drag result