Development

How the repository is laid out, how to test a change, and how a release is made. The rules for agents working in the repository are in AGENTS.md; session notes, the handoff and the research are under ai-docs.

Layout

Path	What
skills/polywright/scripts/pw.py	The command-line tool: standard-library Python 3.9 or newer, one JSON object per command
skills/polywright/scripts/pw_bpy.py	Its Blender half, run inside Blender (or a Python with the bpy module); never run by hand
skills/polywright/references/targets.json	The budgets pw.py check reads, each with its source
skills/*/	The seven skills and their companion files (The skills)
tests/	check_skills.py, test_pw.py, test_recipes.py and fixtures
scripts/budget.py	The size budget
ai-docs/	Handoff, log, decisions, research notes, and the wiki's verification program and output

Testing a change

From the repository root:

python tests/check_skills.py
python tests/test_pw.py
python tests/test_recipes.py
python scripts/budget.py

• check_skills.py: frontmatter, the 1,024-character description limit, the companion files, the manifests, relative links, and guards against home-folder paths, the owner's own paths and AI attribution. It also fails when pw.py's VERSION differs from .claude-plugin/plugin.json (since 0.1.2).
• test_pw.py: geometry, file formats, the manifest, an offline place, the ComfyUI workflow converter, and Blender-backed inspect, render, convert, printable, union and the bpy runner. The Blender tests skip when no Blender is found.
• test_recipes.py: runs every # recipe: block in skills/polywright-blender/references/bpy-recipes.md in Blender and requires its [pw] ok line.
• budget.py: what every session loads (the seven descriptions) and the installed size, against green, yellow and red limits. Red fails CI.

Point the tests at a Blender with POLYWRIGHT_BLENDER=<path to blender>, or at a Python 3.13 with the bpy wheel with POLYWRIGHT_BPY_PYTHON=<python>.

CI

.github/workflows/tests.yml runs on every push to main and every pull request:

Job	Runs
structure	Linux, macOS and Windows, Python 3.9 and 3.14: check_skills.py and test_pw.py (Blender parts skip)
blender	Linux, Python 3.13 with bpy 5.2.2 from PyPI and Mesa's software EGL: test_pw.py with Blender and every recipe
budget	budget.py

The Mesa packages are there because GitHub's Linux runners have no GPU: without them Blender stops rendering with "Couldn't open libEGL.so.1".

Testing the skills themselves

Each skill's evals/evals.json holds trigger cases, decoys, an action case and an outcome case. They were run headless, one fresh Claude Code session per case (claude -p "<prompt>" --output-format stream-json --verbose), with the plugin installed, and graded on the trace: a call to the skill for a trigger, none for a decoy, the named pw.py command for an action case. Action cases run in a throwaway clone so nothing writes into the working repository. On Windows, start claude from Python through its full path (shutil.which("claude")): the bare name fails to launch the .cmd shim and every case looks like a miss.

Releasing

1. Bump version in .claude-plugin/plugin.json and VERSION in pw.py together, and add the section to CHANGELOG.md.
2. Merge to main through a pull request with CI green.
3. Push a tag vX.Y.Z. .github/workflows/release.yml checks the tag against plugin.json, runs the structure checks and the budget, zips skills/ with the README, LICENSE and SECURITY.md, and publishes the GitHub release with that zip.
4. Update this wiki: rerun ai-docs/notes/2026-10-11-wiki-verify.py <version> and compare its output with the saved one; the procedure is in the wiki note in ai-docs/notes.