mason: Instructions file for Codex

mason

agent kit for chisel / rocks work. a cross-agent skill bundle, portable across claude code, pi, opencode, copilot, and codex.

each capability area is its own skill under mason/skills/. today there are two: mason (the /mason entry point -- routes a request to the right skill, or prints usage) and the substance:

chisel-releases

working on canonical/chisel-releases. command-per-file; commands:

• write-slice -- authors + tests + commits chisel slice definition files (SDFs). does not open PRs.
• review-slice -- read-only review of SDFs against chisel conventions, CI checks, and forward-port rules.

@./mason/skills/chisel-releases/SKILL.md

lives under ./mason/skills/chisel-releases/: commands/, helpers under scripts/, command index schemas/commands.manifest.yaml, and -- once installed -- shared reference shared/CHISEL.md. paths inside command files are relative to the skill's own directory (or, for repo paths like slices/, to the chisel-releases checkout being worked on).

shared/CHISEL.md is not committed -- the source of truth is ./mason/_shared/CHISEL.md, and cli.js materialises it as <skill>/shared/ when installing each skill. in this repo, read/edit mason/_shared/CHISEL.md directly; a mason/skills/*/shared/ dir here is gitignored install fallout, not source.

the deterministic scripts are the backbone, so the commands don't rely on the agent remembering conventions or hand-rolling boilerplate:

• inspect / author: orientation (where am i, which release/format, which tools are available), deb-list.py (files + deps inside a .deb; --sdf groups them into a draft SDF -- bins/libs/config/headers/var/copyright, clutter dropped, multiarch dirs globbed, copyright wired (incl. shared-copyright doc-dir symlinks), sorted, ambiguous files left as unplaced comments -- as a deterministic starting point the author refines), try-cut (chisel cut into a temp root), scaffold-test.py (emit a spread task.yaml skeleton -- one fresh rootfs per binary-bearing slice, a chroot line per declared binary, so the author fills real functional checks not boilerplate).
• check: check-slice.py (static conventions: sorting, naming, absolute paths, copyright presence, clutter exclusion, arch names, version-gated fields, hint length/style), check-test.py (binary test coverage: warns on no test or a test exercising none of the binaries, else an info summary of untested binaries), check-diff.py (append-only regressions -- removed SDF / slice / path -- the removed-slices CI gate; file-pair or --base <ref> via git).
• assemble: review-diff.py --base <ref> finds the changed SDFs in a diff, runs the three checkers, prints findings by severity with a verdict, exits non-zero on any block. this is the CI-callable PR-review bot; it needs no agent.