Development

How the repository is laid out, how it is checked, and how a release will be made. The rules for anyone (person or agent) changing it are in AGENTS.md.

Layout

Path	Holds
skills/artwright/	the hub skill, scripts/aw.py and the knowledge files in references/ (movements, theory, traditions, evidence, craft, ceramics, market, law, the CLI list)
skills/artwright-judge/	the judge skill; references/ holds the rubric, the verdict contract, vocabulary, the "AI look" and model profiles
skills/artwright-pixel/	the pixel skill; references/ holds pixel-art rules and sprites and tiles
skills/artwright-curate/	the curator skill; references/store.md gives the store layout and record formats
tests/	test_aw.py (offline tests for aw.py) and check_skills.py (structure and safety checks)
scripts/	budget.py (size budget) and eval-wsl.sh (runs the eval cases under WSL2, Linux or macOS)
evals/	evals.json and the eval cases; fixtures/make_fixtures.py draws the test images
.claude-plugin/	plugin.json (the manifest, version 0.1.0) and marketplace.json
ai-docs/	session notes, decisions, research and the handoff for the next session
root	the shared evergreen record: evergreen.json, RESEARCH, CHANGELOG, LEARNINGS, TESTS, MAINTENANCE

Checks

From the repository root:

python tests/check_skills.py
python tests/test_aw.py
python scripts/budget.py

On a fresh clone of main at 997f5b9 (Windows, Python 3.14, Pillow 12.3.0) these printed, in part:

Ran 34 tests in 0.613s

OK (skipped=1)
check_skills: 0 problem(s)
knowledge files                154 KB         green
vocabulary.md                  37942 bytes    green
descriptions (every session)   ~594 tokens    green

The skipped test checks the museum fixtures: Cleveland Museum of Art open-access images fetched by accession number and compared against pinned SHA-256 values. It runs with AW_NET=1 python tests/test_aw.py, and was not run for this wiki.

check_skills.py checks the skills' structure, links, knowledge verified flags, LF line endings, and that no key or machine path is committed. budget.py keeps the knowledge files, vocabulary.md (red above 40 KB) and the always-loaded descriptions within budget.

Rules for aw.py

From AGENTS.md: standard-library Python 3.9 or later with Pillow optional, exactly one JSON object per command, failing soft with ok: false and error, on Windows, macOS and Linux. Never numpy, scipy, OpenCV, scikit-image or imagehash. Every new command or option gets an offline test with its fixture drawn in code, and the file stays under 100 KB. No images are committed except the README banner.

CI

.github/workflows/tests.yml runs on pushes to main and on pull requests: Linux, macOS and Windows, with Python 3.9 and 3.14 (the Linux 3.9 job on ubuntu-24.04). Each job runs check_skills.py, test_aw.py without Pillow, test_aw.py again with Pillow on 3.14, and budget.py.

Evals

The skills are tested with claude plugin eval: trigger prompts and decoys (does the right skill fire, and does it stay quiet on a neighbour's request), action cases proven by evidence outside the transcript, and outcome and guard cases graded by a judge. scripts/eval-wsl.sh runs them, because native Windows has no sandbox for cases that grant Bash. Results go to evals/results/ and evals/cases/results/, both ignored by git. The runs so far are in TESTS.md.

Releases

None yet. .github/workflows/release.yml runs when a v* tag is pushed: it fails unless the tag matches the version in .claude-plugin/plugin.json, runs check_skills.py and budget.py, zips skills/ with the README, LICENSE and SECURITY.md as artwright-<version>.zip, and publishes a GitHub release with generated notes. Tags are made by the maintainer. When a packaged file changes, the manifest version and the CHANGELOG's release notes move with it, and a breaking change to the verdict contract bumps the minor version.

The examples on this wiki

Each output on these pages was printed by a script that draws its test images in code, copies aw.py from a fresh clone of main into a scratch folder, and runs every page's command and Python block there; the output was pasted, not typed. It ran three times on 2026-10-22: Linux with Python 3.14.4 and Pillow 13.0.0 (the pages show this run), Linux with Pillow hidden, and Windows with Python 3.9.25, no Pillow and ffmpeg. Home folders are shown as /home/you and times as <time>.