OpenSpec Playwright — Summary

OpenSpec Playwright (openspec-pw) is an npm CLI tool that integrates OpenSpec's spec-driven development lifecycle with Playwright E2E test automation for Claude Code projects. It installs a single /opsx:e2e command that drives a three-agent pipeline: Explorer (reads OpenSpec specs, navigates real DOM, extracts selectors), Planner (generates test-plan.md), and Generator (writes verified Playwright .spec.ts files). A Healer agent using Playwright MCP auto-repairs test failures. The tool ships a vision-check subcommand that uses a local Ollama VLM for screenshot-based layout anomaly detection. With 4 stars and active development (last commit May 2026, v0.3.26), it is the most operationally complete OpenSpec extension in the corpus — it adds actual test execution infrastructure rather than just planning artifacts.

Compared to seeds: closest to openspec (same change lifecycle, same /opsx command namespace) but adds a full E2E test generation and execution layer — something no seed implements. The openspec-pw doctor and openspec-pw audit commands make this closer to spec-kit (which has validation hooks) than to any other seed.

OpenSpec Playwright — Overview

Origin

Created by GitHub user wxhou. Published May 2026, version 0.3.26. Active development (published to npm as openspec-playwright).

Philosophy

From README:

"A setup tool that integrates OpenSpec's spec-driven development with Playwright's three-agent test pipeline for automated E2E verification."

The core insight: OpenSpec generates planning artifacts (specs, tasks) but stops at implementation. OpenSpec Playwright extends the lifecycle into automated E2E verification — converting OpenSpec spec files directly into Playwright test cases, with the DOM as the ground truth for selectors.

Pipeline Architecture

/opsx:e2e <change-name>
│
├── 1. Select change → read openspec/changes/<name>/specs/
├── 2. Detect auth → check specs for login/auth markers
├── 3. Validate env → run seed.spec.ts
├── 4. Explore app → /browse explores real DOM
│   ├── Read app-knowledge.md
│   ├── Extract routes from specs
│   ├── Navigate + snapshot + screenshot
│   └── Write app-exploration.md
│   └── Extract patterns → update app-knowledge.md
├── 5. Planner → generates test-plan.md
├── 6. Generator → creates <name>.spec.ts
│   └── Verifies selectors in real browser before writing
├── 7. Configure auth → auth.setup.ts
├── 8. Configure playwright.config.ts
├── 9. Execute tests
├── 10. Healer → auto-heals failures via MCP
└── 11. Report → openspec/reports/playwright-e2e-<name>.md

Two Modes

• Change mode (/opsx:e2e <name>): reads OpenSpec specs to derive routes and test cases
• All mode (/opsx:e2e all): full app exploration, generates Page Objects, no OpenSpec change required

Vision Check

Optional VLM-powered layout validation using Ollama local model:

• Multi-viewport screenshot analysis
• Baseline diff detection
• HTML report generation

OpenSpec Playwright — Architecture

Distribution

• Type: npm-package (openspec-playwright)
• Binary: openspec-pw
• Install: npm install -g openspec-playwright

Runtime Requirements

• Node.js >= 20
• Claude Code with .claude/ directory
• gstack (for exploration + browser QA): git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack
• OpenSpec initialized: openspec init
• Playwright MCP: claude mcp add playwright npx @playwright/mcp@latest
• Playwright browsers: npx playwright install --with-deps
• Ollama (optional, for vision-check)

Directory Structure

openspec-playwright (npm package)
├── bin/
│   └── openspec-pw.js      # CLI entry point
├── src/
│   ├── cli.ts
│   ├── commands/           # CLI command implementations
│   └── ...
└── templates/              # Installed to tests/playwright/
    ├── seed.spec.ts
    ├── auth.setup.ts
    ├── credentials.yaml
    ├── app-knowledge.md
    ├── pages/BasePage.ts
    ├── e2e-command.md      # /opsx:e2e command file
    ├── test-plan.md
    ├── report.md
    └── ...

Project layout after openspec-pw init:
tests/playwright/
├── seed.spec.ts             # Env validation
├── auth.setup.ts            # Session recording
├── global.teardown.ts       # Optional post-test cleanup
├── credentials.yaml         # Test users
├── app-knowledge.md         # Cross-change selector patterns
└── changes/<name>/
    └── <name>.spec.ts

openspec/changes/<name>/specs/playwright/
├── app-exploration.md       # Routes + verified selectors
└── test-plan.md

openspec/reports/
└── playwright-e2e-<name>-<timestamp>.md

Key Dependency: gstack

gstack provides the /browse skill used by the Explorer agent to navigate the real DOM and extract selectors. Without gstack, the exploration phase cannot run.

Authentication

Supports API login (preferred) and UI login (fallback). Multi-user support for role-based tests via credentials.yaml.

OpenSpec Playwright — Components

CLI Binary: openspec-pw

Claude Code Command (1)

Installed by openspec-pw init to .claude/commands/opsx/CLAUDE.md.

Agents (3 — conceptual roles within /opsx:e2e pipeline)

Templates (13)

MCP Integration

• @playwright/mcp — used by Healer agent for browser automation
• Must be installed separately: claude mcp add playwright npx @playwright/mcp@latest

OpenSpec Playwright — Uniqueness

differs_from_seeds

Closest seed: openspec (same change lifecycle, /opsx command namespace). The architectural delta is a complete E2E test generation and execution layer that no seed implements: OpenSpec covers proposal → specs → tasks → apply; this extends the lifecycle to include explore → plan tests → generate tests → execute → heal → report. The Healer agent (auto-repairing failing tests via Playwright MCP browser control) is unique in the entire corpus. The vision-check subcommand using a local Ollama VLM for screenshot-based layout validation has no parallel anywhere in the seed set. The closest seed for validation discipline is spec-kit which has PostToolUse hooks running tests after edits, but spec-kit doesn't generate the tests from spec artifacts — the test generation from spec files is the key distinction here.

Positioning

"OpenSpec's missing last mile." OpenSpec produces planning artifacts and stops at implementation. OpenSpec Playwright completes the verification loop by deriving Playwright tests directly from the same spec files that drove the implementation, ensuring the E2E test suite reflects the current feature spec.

Observable Failure Modes

1. gstack dependency: the Explorer phase requires gstack which is not an npm package — it's a git clone with a custom setup script. This external dependency is fragile and may become stale.
2. Ollama for vision-check: requires a local Ollama installation with a VLM model downloaded. Not suitable for CI without containerized Ollama.
3. Selector drift: app-knowledge.md accumulates selectors that may become stale as the app evolves. No automatic staleness detection.
4. Regression scope confusion: the command warns heavily against running full Playwright test suite — but team members unfamiliar with the tool may run npx playwright test directly, executing all change tests simultaneously.
5. Healer loops: if the Healer cannot repair a failure after several MCP calls, there is no documented bail-out condition.