Development and Release

How the repository is laid out, checked and released. The rules for any agent working in it are in AGENTS.md.

Layout

skills/minewright-*/       the five skills, each with its evergreen companions and evals
  minewright-checks/scripts/mw_check.py, mw_mct.py
  minewright-server/scripts/bds_run.py
tests/check_skills.py      structure, companions, eval shape, manifests, links, public-safety guards
tests/test_scripts.py      both scripts against a fixture add-on, a broken copy and a fake server
tests/fixtures/addon/      a minimal add-on (behavior pack, resource pack, one entity, a self-test)
scripts/budget.py          the size budget
examples/given-jar/        the example add-on (not installed with the skills)
.claude-plugin/            plugin.json and marketplace.json for Claude Code
plugin.json                the same manifest for other agent plugin hosts

Checks before a commit

From the repository root, as AGENTS.md asks:

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

On 2026-10-27 all three passed on Windows with Python 3.14.6: check_skills.py printed ok: 5 skills, companions, manifests, links and text guards, test_scripts.py ran 18 tests with none failing (the real-server test included, since BDS was cached), and budget.py reported GREEN on every line.

What check_skills.py guards

• Frontmatter, and the 1,024-character limit on a skill's description (the Agent Skills spec).
• Every companion file is present, and each eval suite has the right shape.
• The plugin manifests parse.
• Relative links in the markdown resolve, including the links into examples/.
• Public-safety guards: no absolute path into someone's home folder, and no AI attribution lines.

The size budget

scripts/budget.py sets green, yellow and red limits on what every session loads (the descriptions) and on the installed size. Red fails CI. Its report on 2026-10-27:

largest description characters (always loaded; spec limit 1,024)        946  green<=950   yellow<=1024  green  minewright-server
all descriptions tokens together (always loaded)                       1162  green<=1200  yellow<=1600  green  5 skills
largest SKILL.md tokens (loaded on every use)                          2468  green<=2500  yellow<=3500  green  minewright-project
largest reference or script tokens (loaded on demand)                  4925  green<=5000  yellow<=6500  green  minewright-checks/mw_check.py
installed skills folder KB                                              223  green<=256   yellow<=400   green
tracked repository KB outside examples/                                 510  green<=768   yellow<=2048  green
example add-ons KB (not installed with the skills)                     1026  green<=1536  yellow<=3072  green
budget: GREEN

Three lines sit close to yellow: the longest description (minewright-server, 946 of 950), the longest SKILL.md (minewright-project, 2,468 of 2,500 tokens) and the largest script (mw_check.py, 4,925 of 5,000 tokens). A change that crosses yellow says so.

CI

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

Job	Runs on	Does
structure	Linux, macOS and Windows, with Python 3.9 and 3.14	check_skills.py, then test_scripts.py (the real-server test skips: CI never downloads BDS)
example	Linux, Node 24, Python 3.14	in examples/given-jar: npm ci, type check, lint, unit tests, build, pack, a check that the .mcaddon exists, then mw_check.py on the result
budget	Linux, Python 3.14	scripts/budget.py

Editing a skill

• Read its evergreen.json first. If next_due has passed, say so and refresh after the task.
• Never change a version, command, path or API name from memory: cite the source in RESEARCH.md as an R- entry with the date checked, and log the change in CHANGELOG.md as a C- entry.
• Every edit to a SKILL.md gets a CHANGELOG entry with its reason. Re-run that skill's evals when the change alters what it triggers on, decides or does.
• Skills stay under 200 lines, with a description that says what the skill does and names the sibling that owns nearby requests.
• Stable APIs only in anything the repository ships or recommends by default.
• Both scripts stay standard-library Python 3.9+, print exactly one JSON object, fail soft, and work on Windows, macOS and Linux.
• This is a public repository: nothing names a person other than the author credit, a machine, an absolute path on someone's machine, or a credential. No AI attribution in commits, pull requests or files.

Releases

When a packaged file changes, bump .claude-plugin/plugin.json and plugin.json together and push a tag vX.Y.Z. .github/workflows/release.yml then:

1. fails if the tag does not match the version in .claude-plugin/plugin.json;
2. runs check_skills.py and budget.py;
3. zips skills/, the README, LICENSE and SECURITY.md into minewright-X.Y.Z.zip;
4. builds the example add-on (npm ci, type check, tests, pack) and attaches its .mcaddon;
5. publishes a GitHub release with generated notes.

On 2026-10-27 both manifests said 0.1.0 and no tag had been pushed yet, so no release exists.

This wiki

The pages live in the wiki's own repository (https://github.com/m4bwav/minewright.wiki.git, branch master). Every output on Checks and the BDS harness and the pack line on Project and packaging came from ai-docs/notes/2026-10-27-wiki-verify.py. That program copies skills/ and examples/given-jar/ out of a checkout, runs each command the pages show, masks what changes from run to run, and saves its output next to it as 2026-10-27-wiki-verify.out.txt. ai-docs/notes/2026-10-27-github-wiki.md says how to update the pages for the next version.