openspec-playwright 0.2.10 → 0.3.0

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

@@ -2,7 +2,7 @@
 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.24"
@@ -129,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
      () => {
@@ -199,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**:
@@ -225,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**:
@@ -279,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                                          |
 | -------------------- | ------------------------------------ | ---------------------------------------------------------- |
@@ -293,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:**
 
@@ -310,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
@@ -622,7 +621,7 @@ 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
 

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

@@ -10,17 +10,16 @@
 本规范适用于 OpenSpec + openspec-playwright 项目（Claude Code 作为开发工具）。
 
 E2E 工作流前提（由用户确保，非 AI 操作）：
-- OpenSpec CLI：`npm install -g @fission-ai/openspec && openspec init`（提供 `/opsx:propose`、`/opsx:archive` 等命令）
+- 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`
+- Playwright MCP：`claude mcp add playwright npx @playwright/mcp@latest`（用于测试执行 + Healer）
 - 浏览器已安装：`npx playwright install --with-deps`
 - 项目包含 `specs/`、`changes/`、`tests/playwright/` 目录
 
 ## 1. 浏览器操作约束
 
-所有浏览器操作**必须**使用 gstack 的 `/browse`（禁止使用其他 MCP Chrome 工具）。
-
-Claude Code 会根据上下文自动调度 gstack 技能，无需手动路由。
+所有浏览器操作用 gstack 的 `/browse` 探索 + `/qa` 验证，Playwright MCP 执行测试。Claude Code 会根据上下文自动调度，无需手动路由。
 
 **冲突解决**：gstack 任何想直接修改代码的行为，都必须先确认当前 OpenSpec proposal 是否已存在并通过（检查 `changes/<name>/proposal.md` 是否处于 `approved` 状态）。
 
@@ -59,39 +58,54 @@ Claude Code 会根据上下文自动调度 gstack 技能，无需手动路由。
 ## 6. 完整生产工作流（严格执行 + 反馈循环）
 
 ```
-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. 探索与提案
+ 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:propose` → 生成 proposal + scenarios（记录到 `specs/` 和 `changes/`）。对 proposal 进行评审和调整。如需代码探索，单独使用 `/opsx:explore`（不是生成规范）。
+**1. 探索与提案**：现有项目先探索（`/opsx:explore`）再写 proposal（`/opsx:propose`）；新项目（greenfield）直接生成 proposal + scenarios（记录到 `specs/` 和 `changes/`）。
 
-**2. 产品与架构思考**（按需触发，不是每个功能都走）：
+**2. 产品与架构评审**（按需触发）：
 - `/office-hours`：产品方向、范围、优先级不确定时
 - `/plan-ceo-review`：产品战略影响、竞争格局变化时
 - `/plan-eng-review`：架构影响（新增服务、API 契约变更、数据模型重构）时
 
-**3. 设计与实现**：设计审查 → Build（遵守 OpenSpec delta markers），过程中 `/review` 自审。构建完成后，E2E 测试覆盖通过才能继续。
+**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 行分离
+```
 
-**4. E2E 测试生成与执行**：`/opsx:e2e <change-name>` 生成 Playwright 测试并执行 → 执行 `/qa`（真实浏览器 + healer）验证。E2E 通过后进入发布环节。
+**6. E2E 测试生成与执行**：`/opsx:e2e <change-name>` 生成 Playwright 测试 → `/browse` 探索真实 DOM → Healer 自动修复 → `/qa` 真实浏览器验证。E2E 通过后进入发布环节。
 
-**5. 验证通过后**：`/opsx:archive` 永久归档，更新 `specs/`
+**7. 验证通过后归档**：`/opsx:archive` 永久归档，更新 `specs/`
 
-**6. 发布**：`/ship` 或 `/land-and-deploy`
+**8. 发布**：`/ship` 或 `/land-and-deploy`
 
-**7. 迭代回顾**：`/retro`
+**9. 迭代回顾**：`/retro`
 
 ### 反馈循环（生产中必然发生）
 
 | 信号 | 回到 |
 |------|------|
-| 测试失败（App Bug） | 步骤 3 修复后 → 步骤 4 重新测试 |
-| 发现架构问题 | 步骤 2 重新评审 → 步骤 3 修复 |
-| proposal 需调整 | 步骤 1 重新提案 |
+| 测试失败（App Bug） | 回到步骤 4 修复 → 重新测试 |
+| 发现架构问题 | 回到步骤 2 重新评审 → 步骤 4 修复 |
+| Proposal 需调整 | 回到步骤 1 重新提案 |
 | 评审不通过 | 回到对应步骤重新处理 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openspec-playwright",
-  "version": "0.2.10",
+  "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