bitwarden · kdenney · Jun 9, 2026
@@ -92,6 +92,12 @@
       "source": "./plugins/bitwarden-design-tools",
       "version": "0.1.0",
       "description": "Design toolkit for Bitwarden — non-persona skills for the design lifecycle. Content style guide reference, Figma Dev Mode MCP usage, Bitwarden brand application, design-to-engineering handoff prep, Design System governance, and the Product and Design Jira workflow. Composed by the bitwarden-designer agent and usable standalone."
+    },
+    {
+      "name": "bitwarden-playwright-testing",
+      "source": "./plugins/bitwarden-playwright-testing",
+      "version": "1.0.0",
+      "description": "Automated UI testing framework for Bitwarden web changes using Playwright"
     }
   ]
 }
@@ -15,6 +15,7 @@ A curated collection of plugins for AI-assisted development at Bitwarden. Enable
 | [bitwarden-design-tools](plugins/bitwarden-design-tools/)           | 0.1.0   | Design toolkit: content style guide, Figma Dev Mode MCP, Bitwarden brand application, handoff prep, Design System governance, Product and Design Jira       |
 | [bitwarden-devops-engineer](plugins/bitwarden-devops-engineer/)     | 0.1.3   | DevOps engineering assistant: workflow compliance linting, action security auditing, and org-wide CI/CD remediation                                         |
 | [bitwarden-init](plugins/bitwarden-init/)                           | 1.2.0   | Initialize and enhance CLAUDE.md files with Bitwarden's standardized template format                                                                        |
+| [bitwarden-playwright-testing](plugins/bitwarden-playwright-testing/) | 1.0.0 | Automated UI testing framework for Bitwarden web changes using Playwright                                                                                   |
 | [bitwarden-product-analyst](plugins/bitwarden-product-analyst/)     | 0.1.5   | Product analyst agent for creating comprehensive Bitwarden requirements documents from multiple sources                                                     |
 | [bitwarden-security-engineer](plugins/bitwarden-security-engineer/) | 1.2.0   | Application security engineering: vulnerability triage, threat modeling, and secure code analysis                                                           |
 | [bitwarden-software-engineer](plugins/bitwarden-software-engineer/) | 1.0.0   | Software engineer agent for a Bitwarden product team. Implements stories, tasks, and bugs with code quality, performance, security, and team comms in mind. |

@@ -0,0 +1,28 @@
+{
+  "name": "bitwarden-playwright-testing",
+  "version": "1.0.0",
+  "description": "Automated UI testing framework for Bitwarden web changes using Playwright",
+  "author": {
+    "name": "Bitwarden",
+    "url": "https://github.com/bitwarden"
+  },
+  "homepage": "https://github.com/bitwarden/ai-plugins/tree/main/plugins/bitwarden-playwright-testing",
+  "repository": "https://github.com/bitwarden/ai-plugins",
+  "keywords": [
+    "testing",
+    "web",
+    "playwright",
+    "bitwarden",
+    "ui-testing",
+    "automation"
+  ],
+  "agents": [
+    "./agents/context-gatherer/AGENT.md",
+    "./agents/code-explorer/AGENT.md",
+    "./agents/service-mapper/AGENT.md",
+    "./agents/test-planner/AGENT.md",
+    "./agents/service-manager/AGENT.md",
+    "./agents/test-runner/AGENT.md",
+    "./agents/report-compiler/AGENT.md"
+  ]
+}
@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to bitwarden-playwright-testing will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-28
+
+### Added
+
+- Initial release of the `bitwarden-playwright-testing` plugin
+- `test-web-changes` skill orchestrating a full UI test pipeline from Jira ticket or feature description to HTML report
+- Seven-agent team: `context-gatherer`, `code-explorer`, `service-mapper`, `test-planner`, `service-manager`, `test-runner`, `report-compiler`
+- Skills: `exploring-application-context`, `determining-required-services`, `verifying-environment-health`, `build-test-cases`, `executing-web-tests`, `reading-mailcatcher-api`, `compiling-test-report`
@@ -0,0 +1,161 @@
+# Bitwarden Playwright Testing Plugin
+
+Automated end-to-end UI testing for Bitwarden web changes using Playwright.
+
+## Overview
+
+This plugin provides a single user-facing skill, `test-web-changes`, that orchestrates a seven-agent team to take a Jira ticket, implementation plan, or feature description and turn it into a full Playwright test run. The team gathers context, explores the affected codebases, builds grounded test cases, verifies the local dev environment is ready, executes the tests, and compiles an HTML report with full-page screenshots.
+
+## Prerequisites
+
+**Required Claude Code plugin:** Install the [`playwright-cli`](https://github.com/microsoft/playwright-cli) plugin before using this plugin. Render verification and all browser test execution depend on it.
+
+**Bitwarden dev environment:** Start all required services before invoking the plugin. The plugin only verifies — it never starts, builds, or stops services.
+
+- **Dev infrastructure (containers)**: start Bitwarden's mssql, mailcatcher, and azurite containers via either Docker Compose (`server/dev/docker-compose.yml`) or .NET Aspire (`server/AppHost`).
+- **Application services**: start the web frontend (`clients` Nx workspace, `nx serve web --configuration=commercial`), plus the .NET services your test will touch (typically `Api`, `Identity`, and depending on scope `Billing`, `billing-pricing`, `Admin` / Bitwarden Portal, `Notifications`, `Events`, `Icons`).
+
+The plugin's `verifying-environment-health` skill confirms Docker dev containers, application `/alive` endpoints, and the Angular bootstrap before tests begin. If anything is missing it halts with a hint pointing to what to start.
+
+## Installation
+
+```bash
+/plugin install bitwarden-playwright-testing@bitwarden-marketplace
+```
+
+Restart Claude Code after installing for the plugin to become active.
+
+## Usage
+
+Invoke the team-lead skill:
+
+```bash
+/test-web-changes <jira-ticket-id | feature-plan-path | feature-description> [--confirm]
+```
+
+**Examples:**
+
+```bash
+/test-web-changes PM-1234
+/test-web-changes ~/code/bitwarden/server/plans/PM-1234-billing-ui.md
+/test-web-changes "exempt orgs from billing automation when the flag is set" --confirm
+```
+
+**Flags:**
+
+- `--confirm`: pause after the test plan is built and display the test cases for review before executing.
+
+## How it works
+
+`test-web-changes` runs an eight-task pipeline as the team lead. Each agent returns its artifact as a markdown response; the team lead writes those responses verbatim to `.playwright-testing-artifacts/<slug>/` and dispatches the next agent.
+
+| Task | Agent | Artifact |
+|---|---|---|
+| 1 | `context-gatherer` | `context-<timestamp>.md` |
+| 2 | `code-explorer` | `app-context-<timestamp>.md` |
+| 3 | `service-mapper` | `services-<timestamp>.md` |
+| 4 | `test-planner` | `test-cases-<timestamp>.md` |
+| 5 | *(team lead composes)* | `test-plan-<timestamp>.md` |
+| 6 | `service-manager` *(verifies the environment via `verifying-environment-health`)* | *(no artifact; halts the run on failure)* |
+| 7 | `test-runner` | `test-results-<timestamp>.md` |
+| 8 | `report-compiler` | `report-<timestamp>.html` |
+
+## Agents and skills
+
+### Agents
+
+| Component | Description |
+|---|---|
+| `context-gatherer` | Acquires feature source content (Jira ticket, plan file, or free-form description) and extracts structured context. |
+| `code-explorer` | Reads the context, explores the affected codebases, and produces the Application Context (changed files, routes, selectors, verification points). |
+| `service-mapper` | Reads the Application Context and maps changed file paths to the local services that need to be running. |
+| `test-planner` | Reads context and Application Context artifacts and builds grounded test cases via the `build-test-cases` skill. |
+| `service-manager` | Reads the test plan and dispatches `verifying-environment-health` to confirm Docker dev containers, application `/alive` endpoints, and the Angular bootstrap. Halts the run on any failure. Never starts or stops services. |
+| `test-runner` | Launches the `playwright-cli` agent to execute test cases with guardrails and screenshots, and returns structured results. |
+| `report-compiler` | Compiles an HTML report from the test results. |
+
+### Skills
+
+| Skill | Description |
+|---|---|
+| `test-web-changes` | Team-lead orchestration skill; the only user-facing entry point. |
+| `exploring-application-context` | Surveys changed files, routes, selectors, and verification points across affected repositories. |
+| `determining-required-services` | Maps changed file paths to the local services that need to be running. |
+| `verifying-environment-health` | Verifies Docker dev containers via preflight, application services via the health-check script, and Angular bootstrap via render verification. Halts on the first failure. |
+| `build-test-cases` | Builds Playwright test cases with a web-first policy from plan context. |
+| `executing-web-tests` | Launches the `playwright-cli` agent with guardrails and screenshots. |
+| `reading-mailcatcher-api` | Reads Bitwarden emails via the Mailcatcher REST API for verification links, magic links, and OTP codes. |
+| `compiling-test-report` | Writes an HTML report from agent results. |
+
+## Web-first policy
+
+All test actions (account creation, org setup, form submission) happen through the browser UI. Direct database queries, REST API calls outside the browser, and CLI tools are never permitted during setup or test execution.
+
+## Billing tests
+
+When the plan involves billing flows, `build-test-cases` bakes the Stripe test card and related values directly into the test-case steps, which run through the web UI. A billing-related 400 error during execution halts all testing immediately.
+
+## Out of scope
+
+The following Bitwarden surfaces are not testable via this plugin (no Playwright UI surface):
+
+- **Browser extensions** (`clients/apps/browser/`) — require browser extension testing setup
+- **Desktop app** (`clients/apps/desktop/`) — requires Electron testing setup
+- **CLI** (`clients/apps/cli/`) — command-line tool, no browser UI
+
+## Plugin structure
+
+```
+bitwarden-playwright-testing/
+├── .claude-plugin/
+│   └── plugin.json
+├── README.md
+├── CHANGELOG.md
+├── agents/
+│   ├── context-gatherer/AGENT.md
+│   ├── code-explorer/AGENT.md
+│   ├── service-mapper/AGENT.md
+│   ├── test-planner/AGENT.md
+│   ├── service-manager/AGENT.md
+│   ├── test-runner/AGENT.md
+│   └── report-compiler/AGENT.md
+├── scripts/
+│   └── playwright.config.json           # Sets ignoreHTTPSErrors for dev certs
+└── skills/
+    ├── test-web-changes/SKILL.md        # Team-lead entry point
+    ├── exploring-application-context/
+    │   ├── SKILL.md
+    │   └── references/
+    ├── determining-required-services/
+    │   ├── SKILL.md
+    │   └── references/services.md
+    ├── verifying-environment-health/
+    │   ├── SKILL.md
+    │   └── scripts/
+    │       ├── preflight-check.sh       # Verifies Docker and dev-env preconditions
+    │       └── health-check.sh          # Polls service /alive endpoints
+    ├── build-test-cases/
+    │   ├── SKILL.md
+    │   └── references/billing-test-data.md
+    ├── executing-web-tests/
+    │   └── SKILL.md
+    ├── reading-mailcatcher-api/
+    │   ├── SKILL.md
+    │   └── references/email-patterns.md
+    └── compiling-test-report/
+        ├── SKILL.md
+        └── templates/
+            └── report-template.html
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for plugin development guidelines, structure requirements, versioning rules, and the review process.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+## License
+
+See [LICENSE.txt](../../LICENSE.txt)
@@ -0,0 +1,62 @@
+---
+name: code-explorer
+version: 1.0.0
+description: Planning-phase agent for the test-web-changes team. Reads the context markdown from context-gatherer, calls exploring-application-context, and returns the Application Context as a markdown response for the team lead to persist. Do not invoke directly — dispatched by the test-web-changes skill.
+model: sonnet
+skills:
+  - bitwarden-playwright-testing:exploring-application-context
+color: orange
+user-invocable: false
+tools: Read, Skill, Grep, Glob, Bash(git diff *), Bash(git log *)
+---
+
+You are the codebase exploration agent for the Bitwarden web test pipeline. Read the context markdown, explore the codebase, and return an Application Context markdown response.
+
+Use only the tools listed in your allowlist. Do not request permission to use tools outside it — if you would otherwise need to, report the obstacle in your final output instead.
+
+## Inputs
+
+Your task prompt includes:
+- **Context artifact path**: path to `context-<timestamp>.md` from context-gatherer
+
+## Step 1 — Read context artifact
+
+Read the context markdown file. Extract these sections by their headers:
+- `## Affected Repositories` — list items
+- `## Feature Description` — paragraph text
+- `## Acceptance Criteria` — list items
+
+## Step 2 — Explore application context
+
+Invoke `Skill(bitwarden-playwright-testing:exploring-application-context)`. Pass the text below with no angle-bracket placeholders remaining in the actual call:
+
+```
+The working directory is the bitwarden root. Each repo is a subdirectory.
+
+Affected repos: <comma-separated repos from the context markdown>
+Feature description: <Feature Description section text>
+Acceptance criteria:
+<Acceptance Criteria items as a numbered list>
+
+Return the complete Application Context with two top-level sections: ## States and ## Flows. State and flow definitions follow the state-centric schema documented in the skill.
+```
+
+Wait for the complete Application Context.
+
+## Step 3 — Return app-context as markdown
+
+Your final response is the app-context artifact itself, formatted as markdown. Do not preface or follow your response with any other commentary; the entire response is the artifact content.
+
+The skill serializes the Application Context exactly once. As a defensive backstop only, if the skill output ever contains more than one `## States` section, extract only the content beginning at the LAST `## States` heading — discard all earlier passes and any prose between them. Never concatenate multiple passes.
+
+Return exactly this structure:
+
+```markdown
+## Application Context
+
+<the final ## States … ## Flows block from the skill output — containing exactly two top-level sections>
+```
+
+Do not summarize, reformat, or omit any part of the final block. Downstream agents depend on the full content.
+
+Self-check before returning: your first non-empty line must be `## Application Context`, the response must contain exactly one `## States` section and exactly one `## Flows` section, and no other top-level (`##`) sections. If the self-check fails, surface the failure to the team lead instead of returning a malformed artifact.
@@ -0,0 +1,66 @@
+---
+name: context-gatherer
+version: 1.0.0
+description: Planning-phase agent for the test-web-changes team. Receives a Jira ticket ID, plan file path, or free-form feature description and returns structured context (affected repos, feature description, acceptance criteria) as a markdown response for the team lead to persist. Do not invoke directly — dispatched by the test-web-changes skill.
+model: sonnet
+skills:
+  - bitwarden-atlassian-tools:researching-jira-issues
+color: green
+user-invocable: false
+tools: Read, Skill, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_issue_remote_links, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__search_issues, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_confluence_page_comments, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__get_child_pages, mcp__plugin_bitwarden-atlassian-tools_bitwarden-atlassian__download_attachment
+---
+
+You are the context-gathering agent for the Bitwarden web test pipeline. Acquire the feature source content, extract structured context, and return it as a markdown response.
+
+Use only the tools listed in your allowlist. Do not request permission to use tools outside it — if you would otherwise need to, report the obstacle in your final output instead.
+
+## Inputs
+
+Your task prompt includes:
+- **Input type**: `jira-ticket`, `plan-file`, or `description`
+- **Input value**: the ticket ID, file path, or description text
+
+## Step 1 — Acquire source content
+
+**`jira-ticket`**: Invoke `Skill(bitwarden-atlassian-tools:researching-jira-issues)` with the ticket ID. Wait for the full synthesis including linked issues, sub-tasks, and acceptance criteria.
+
+**`plan-file`**: Read the file at the provided path with the `Read` tool.
+
+**`description`**: Use the input value directly as the source content.
+
+## Step 2 — Extract context
+
+From the source content, identify:
+
+- **Affected repos**: Any of `clients`, `server`, `billing-pricing` referenced by the content. List all that apply.
+- **Feature description**: 1–3 sentences describing what the feature does and why.
+- **Acceptance criteria**: All conditions that must be true for the feature to be complete. For Jira tickets, check the acceptance criteria section, sub-task descriptions, and linked stories.
+
+## Step 3 — Return context as markdown
+
+Return exactly this structure, with every section populated. Do not preface or follow your response with any other commentary:
+
+```markdown
+# Context
+
+**Input Type:** <jira-ticket | plan-file | description>
+**Input Value:** <original value>
+
+## Feature Description
+<1–3 sentences describing what the feature does and why>
+
+## Affected Repositories
+- <repo>
+- <repo>
+
+## Acceptance Criteria
+- <criterion>
+- <criterion>
+
+## Source Summary
+<full Jira synthesis text, file contents, or description — this must be the complete raw source content gathered in step 1.>
+```
+
+Section headers must match exactly (`## Feature Description`, `## Affected Repositories`, `## Acceptance Criteria`, `## Source Summary`) so downstream agents can locate them.
+
+Self-check before returning: your first non-empty line must be `# Context`, and the response must contain the section headers `## Feature Description`, `## Affected Repositories`, `## Acceptance Criteria`, `## Source Summary`.