These notes are for coding agents changing Hallmark itself. If you were asked to build or design a page with Hallmark, follow skills/hallmark/SKILL.md instead. People should read CONTRIBUTING.md; this file sums up the same rules.
skills/hallmark/SKILL.mdis the skill's entry point. It loads files fromskills/hallmark/references/.skills/hallmark/references/gates.mdlists every gate and its tier.sloplint.mjskeeps a copy of the tiers in itsTIERSmap, andrefcheck.mjsfails when the two disagree.skills/hallmark/references/themes/holds one Markdown file per theme plus the generatedindex.json.skills/hallmark/scripts/holds the Node tools (sloplint.mjs,sloplint-render.mjs,theme.mjs,capture.mjs,picture.mjs,imagegen.mjs,install.mjs,install-hook.mjs,lint-hook.mjs,refcheck.mjs) and their*.test.mjsfiles.site/is the public website, deployed as it is.
Everything in skills/hallmark/ is copied to every user's machine and read by their agent.
There is no install or build step. These are the checks CI runs, and all of them must pass:
node skills/hallmark/scripts/refcheck.mjs
node skills/hallmark/scripts/theme.mjs validate skills/hallmark/references/themes/*.md
node skills/hallmark/scripts/theme.mjs index && git diff --exit-code -- skills/hallmark/references/themes/index.json
node --test skills/hallmark/scripts/*.test.mjs skills/hallmark/scripts/fixtures/*/*.test.mjsBrowser tests skip without Chrome and puppeteer-core, and they always skip on CI. CONTRIBUTING.md lists the four variables that turn them on; set them whenever you change capture.mjs, picture.mjs or sloplint-render.mjs.
- Reproduce the bug on
mainwith the real command before you change code, and keep the command and output for the pull request. - Add a test that fails on
mainand passes with the fix. Put script tests in the<script>.test.mjsfile beside the script (imagegen.mjskeeps its tests infixtures/imagegen/). For a static sloplint gate, add a page underskills/hallmark/scripts/fixtures/<name>/and its expected result to theexpectationslist inrefcheck.mjs. For a render gate, add a case tosloplint-render.test.mjs. - Make one change per pull request, with no unrelated refactors, renames or reformatting.
- Add no dependencies, and leave
package.jsonand lockfiles alone. - Leave
.github/workflows/verify.ymlalone. CI runs every*.test.mjsinskills/hallmark/scripts/and one folder belowfixtures/, so new tests there run on their own. - Write no em dashes or en dashes in any file, comment, commit message or pull request text.
- Keep notes, plans and reports out of the repository, and add files to
skills/hallmark/only when the change needs them there. - When you change sloplint, run
node skills/hallmark/scripts/sloplint.mjs site --jsononmainand on your branch and diff the two.mainalready has a few findings, so report only what changed and leave the rest alone. If--renderdoes more work, time it on twosite/made/folders on both branches. - A new gate needs one row in
gates.mdand a matching entry inTIERSinsloplint.mjs. Keep implementation notes out ofgates.md. - Add photos to
photos.jsonand the themes only from Wikimedia Commons. - Leave version numbers, the README and the roadmap alone unless the task is about them.
- Build paths with
node:pathso they work on Windows, and print forward slashes in anything meant for HTML.
Title the pull request with the area and what now works, for example fix(sloplint): lint a dot folder named on the command line.
gh pr create --body skips the template, so write the body with these headings:
## What was wrong
## How to reproduce it on main
## What changed
## Checks runEnd it with Fixes #<issue> when there is an issue.