Initial public beta — webtest-orch v0.1.0-beta

End-to-end web app testing skill for Claude Code. Splits into:
- BOOTSTRAP — LLM-driven exploration via Playwright MCP on first run
- REPLAY — deterministic `npx playwright test` on subsequent runs (~zero LLM tokens)
- HYBRID — replay existing + explore new flows

Image-budget protection: all browser work delegated to Task subagents,
parent chat never receives inline images.

Includes 9 black-box scripts, 7 reference docs, 6 templates, 3 examples,
plus standard OSS files (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, CHANGELOG,
issue/PR templates).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: CreatmanCEO

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,42 @@
+---
+name: Bug report
+about: Skill misbehaves, scripts crash, generated tests are wrong
+title: "[bug] "
+labels: bug, needs-triage
+---
+
+## What happened
+
+<!-- One paragraph. Include the command you ran and what the skill produced. -->
+
+## What you expected
+
+<!-- One paragraph. -->
+
+## Reproduction
+
+1. ...
+2. ...
+3. ...
+
+## Environment
+
+- OS: <!-- Windows / macOS / Linux + version -->
+- Node version: `node --version`
+- Python version: `python --version`
+- Claude Code version: <!-- from `claude --version` -->
+- Skill version: <!-- from CHANGELOG -->
+- Target app stack: <!-- Next.js, FastAPI, Supabase, etc. -->
+
+## Logs / artifacts
+
+<details>
+<summary>Console output</summary>
+
+```
+<!-- paste relevant output -->
+```
+
+</details>
+
+<!-- If a `reports/<run-id>/` directory exists, attach `bugs.json` and `report.md`. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+name: Feature request
+about: Suggest an improvement
+title: "[feature] "
+labels: enhancement, needs-triage
+---
+
+## Problem
+
+<!-- What can't you do today? Be concrete — point at a real workflow that hits friction. -->
+
+## Proposed solution
+
+<!-- Sketch of how the skill should behave. If it's a new script, describe its CLI. -->
+
+## Alternatives considered
+
+<!-- What did you try / think about? Why didn't it work? -->
+
+## Out of scope
+
+<!-- What this feature is explicitly NOT trying to solve. Helps reviewers calibrate. -->
+
+## Stack / context
+
+<!-- Your app's stack and what kind of testing you're doing. Helps prioritise. -->

.github/ISSUE_TEMPLATE/os-compatibility-report.md

@@ -0,0 +1,47 @@
+---
+name: OS compatibility report
+about: Tested on a non-Windows OS — share the results (good or bad)
+title: "[compat] <OS> + <shell>"
+labels: compatibility, beta-feedback
+---
+
+We're actively looking for cross-platform feedback during the `0.1.x` beta. Even "everything works" reports help — they let us mark an OS as smoke-tested.
+
+## Environment
+
+- OS: <!-- Ubuntu 22.04, macOS 14.x, Fedora 40, ... -->
+- Architecture: <!-- x86_64 / arm64 -->
+- Shell: <!-- bash 5.2, zsh, fish, ... -->
+- Node version:
+- Python version:
+- Claude Code version:
+
+## Install path
+
+- Method: `bash install.sh` / `bash install.sh --symlink` / cloned manually
+- Result:
+  - [ ] `install.sh` ran cleanly
+  - [ ] `claude mcp list` shows `playwright` and `chrome-devtools`
+  - [ ] Skill appears in Claude Code's available skills list after restart
+
+## First run
+
+- Target app: <!-- public site / authed app / Supabase / NextAuth / FastAPI / ... -->
+- Bootstrap result:
+  - [ ] `npm i -D @playwright/test @axe-core/playwright dotenv` succeeded
+  - [ ] `npx playwright install chromium` succeeded
+  - [ ] `auth.setup.ts` ran without manual edits
+  - [ ] First spec passed
+  - [ ] `report.md` and `bugs.json` were generated
+
+## Friction points
+
+<!-- What did you have to fix manually? Quote shell commands or error messages. -->
+
+## Time to first green spec
+
+<!-- From `git clone` to first passing assertion. -->
+
+## Anything we should add to the docs?
+
+<!-- Edge cases that surprised you. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,33 @@
+## What this PR does
+
+<!-- One paragraph. -->
+
+## Why
+
+<!-- Link to issue or describe the user-facing problem this fixes. -->
+
+## Type
+
+- [ ] Bug fix
+- [ ] New feature / template / reference doc
+- [ ] Breaking change
+- [ ] Documentation only
+- [ ] Test / CI / tooling
+
+## Checklist
+
+- [ ] CHANGELOG.md updated under `[Unreleased]`
+- [ ] Touched scripts have `--help` and run on the smoke-test path
+- [ ] No personal/internal data in code, comments, or examples
+- [ ] Image-budget protection rules untouched (or documented violation justified)
+- [ ] If touching templates: placeholder list updated at file top
+
+## Tested on
+
+- OS:
+- Target app stack:
+- What you ran:
+
+## Risk
+
+<!-- Worst case if this PR is wrong. -->

.gitignore

@@ -0,0 +1,35 @@
+# Skill state
+.isolation-verified
+fixtures/iso-test/
+
+# Test artefacts (the skill writes these into target projects, not into the skill repo,
+# but contributors may have them lying around when they hand-test)
+node_modules/
+test-results/
+playwright-report/
+playwright/.auth/
+reports/
+**/*.spec.ts.snap
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db
+
+# Local env
+.env
+.env.local
+.env.test
+*.env.local
+
+# Build output (when we publish to npm)
+dist/
+*.tsbuildinfo

CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project will be documented here. Format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned for `0.2.0`
+- Supabase Auth pattern (`auth.setup.ts.tmpl` branch on `SUPABASE_URL`)
+- Onboarding-overlay state-seeding hook in auth setup template
+- Severity annotation: `// @severity: S0` parsing in spec files
+- Spec generation contract: console listeners + axe scan + issues collector required
+- `--bugs/--diff/--out` accepted as aliases on `generate_report.py`
+- Anchored regex in auth template
+- Pydantic / Next.js 15 patterns in `console-noise-patterns.md`
+
+## [0.1.0-beta] - 2026-04-29
+
+Initial public beta. Validated end-to-end on a real production app
+(static Next.js portfolio + a SaaS chat app via dogfooding).
+
+### Added
+- `SKILL.md` — Claude Code skill workflow (181 lines)
+- `README.md` — user-facing documentation
+- `install.sh` — copy/symlink installer with MCP preflight check
+- 9 black-box scripts:
+  - `detect_state.py` — project state probe (JSON / human modes)
+  - `with_server.py` — dev-server lifecycle (frontend + backend)
+  - `_image_isolation_check.py` — image-budget contract self-test
+  - `run_suite.py` — wraps `npx playwright test`, normalizes output, ANSI-strip,
+    extracts individual issues from `issues[]` collector pattern
+  - `fingerprint_bugs.py` — composite SHA-256 fingerprints, severity heuristics
+    (a11y impact-aware), Linear/GitHub/Jira tracker mappings, run-diff
+  - `triage_console.py` — default ignore-list (GTM, Stripe, Sentry, dev-mode
+    React, source-map 404s); bug-pattern classifier (hydration, CORS, CSP, 5xx)
+  - `visual_diff.py` — locates `toHaveScreenshot()` failures, prepares
+    vision-classification tasks
+  - `vision_classify.py` — validates verdict format from Task subagent
+  - `generate_report.py` — emits `report.md` + `index.html` + diff section
+- 7 reference docs: Playwright patterns, auth strategies, a11y patterns,
+  responsive checklist, console noise patterns, stack-specific (Next.js,
+  FastAPI, Telegram WebApp, WS/SSE, TTS), reporting (JSON schema + tracker
+  mappings)
+- 6 templates: `playwright.config.ts.tmpl` (with auth), `playwright.config.public.ts.tmpl`
+  (no auth), `auth.setup.ts.tmpl` (API-first, UI fallback), `fixture.ts.tmpl`,
+  `pom.ts.tmpl`, `spec.ts.tmpl` (issues[] collector pattern)
+
+### Image-budget protection
+- All browser work is delegated to a Task subagent (not a frontmatter
+  `context: fork` directive — that field is not honoured by all Claude Code
+  builds yet). Parent chat never receives inline images.
+
+### Known limitations
+- Playwright MCP must be installed separately (`claude mcp add playwright`).
+- Documentation drift: `generate_report.py` argument signature does not match
+  `SKILL.md` step 10 wording; will be reconciled in `0.2.0`.
+- Severity is structurally inferred (no LLM pass); P0 product regressions can
+  be misclassified as S2 unless the spec is annotated; `0.2.0` adds annotation
+  parsing.
+- Onboarding overlays in target apps will fail every spec until the user adds
+  state-seeding to `auth.setup.ts`; `0.2.0` adds an explicit hook block.
+- macOS / Linux installers untested in CI; help wanted (see
+  `os-compatibility-report` issue template).
+
+[Unreleased]: https://github.com/CreatmanCEO/webtest-orch/compare/v0.1.0-beta...HEAD
+[0.1.0-beta]: https://github.com/CreatmanCEO/webtest-orch/releases/tag/v0.1.0-beta

CODE_OF_CONDUCT.md

@@ -0,0 +1,33 @@
+# Code of Conduct
+
+## Our pledge
+
+In the interest of fostering an open and welcoming environment, we pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and unwelcome sexual attention
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Project maintainers are responsible for clarifying acceptable behavior and may take corrective action in response to any instances of unacceptable behavior, including warnings, temporary or permanent bans from the project's spaces.
+
+Reports go through GitHub's [report-abuse flow](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam) or via private email to the repository owner listed on the GitHub profile.
+
+## Attribution
+
+Adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to webtest-orch
+
+Thanks for considering a contribution. This document is short on purpose — read it once, then move fast.
+
+## Quick start
+
+1. Fork the repo, clone your fork.
+2. Install dependencies: Python 3.10+, Node.js 18+, Claude Code CLI.
+3. Install the skill locally for testing:
+   ```bash
+   bash install.sh --symlink   # symlinks live source into ~/.claude/skills/
+   ```
+4. Make changes. Re-run the skill in any project to test.
+
+## What we want
+
+| Welcome | Less welcome |
+|---|---|
+| Bug reports with reproduction steps | "doesn't work for me" without context |
+| New stack-specific patterns (Supabase, NextAuth, Clerk, etc.) | Speculative refactors of working code |
+| OS compatibility reports (Linux/macOS/Windows variants) | Style-only changes without functional reason |
+| New `console-noise-patterns.md` patterns from your apps | Re-litigating architectural decisions |
+| Test cases for `scripts/*.py` | New dependencies without strong justification |
+
+## Pull request workflow
+
+1. **One PR = one concern.** Don't bundle a bug fix with a refactor.
+2. **Update CHANGELOG.md** under `[Unreleased]`. The first line of your CHANGELOG entry is your PR description.
+3. **Add tests if you touched a Python script.** Smoke-tests live in `tests/python/` (coming in `0.2.0`); for now, hand-verify and document what you ran.
+4. **Don't add LLM calls inside scripts.** Skill scripts MUST stay deterministic. LLM work happens via Task subagents dispatched by the orchestrator, not inside `*.py`.
+5. **Image-budget protection is non-negotiable.** Any change that lets screenshots leak into the parent chat context will be reverted. Read `SKILL.md` § "Image budget protection" first.
+6. **Sign-off.** Add a `Co-authored-by:` trailer if multiple humans worked on the PR.
+
+## Naming and structure
+
+- New script: `scripts/<verb>_<noun>.py`. Must accept `--help` and return useful info.
+- New reference doc: `reference/<topic>.md`. Add a one-line entry in `SKILL.md` § References.
+- New template: `templates/<file>.<ext>.tmpl`. Document its placeholders at the top with `// PLACEHOLDERS: __NAME1__ __NAME2__`.
+
+## Review SLA
+
+- **Bug reports:** triaged within 7 days.
+- **PRs:** first review within 14 days. We're a small project; please be patient.
+
+## Code of Conduct
+
+By participating, you agree to abide by [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
+
+## Releasing (maintainers only)
+
+1. Bump version in `package.json` (when published).
+2. Move `[Unreleased]` items into a new `[X.Y.Z] - YYYY-MM-DD` section in `CHANGELOG.md`.
+3. `git tag vX.Y.Z && git push --tags`.
+4. GitHub Actions creates the release.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 webtest-orch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.