Instructions for an AI coding agent (and a useful checklist for a human). This
file is the same in every deck repository; anything specific to this deck -
its architecture, its design decisions, the traps it has already hit - goes in
CLAUDE.md (or your tool's equivalent) beside it, not here.
A deck: a library for the Jennifer language, consumed by vendoring its
src/ subtree into another project (jvc add). There is nothing to compile.
The manifest (deck.toml, deck.yaml, deck.yml or deck.json - whichever
exists) is the source of truth for the name, version, licence and interpreter
floor. Read it first.
| Path | What it is |
|---|---|
src/<slug>.j |
the entry module - the one consumers import |
src/*_test.j |
white-box test overlays, one beside every module |
src/topics/ |
only in a topics deck: files included by the entry module |
examples/ |
runnable programs; CI runs or parses every one |
docs/ |
the book; SUMMARY.md is the outline, cheatsheet.md the API surface |
tools/ |
the CI helpers; most are shared byte-identical between decks |
.github/ |
the workflows; shared byte-identical between decks |
- Check
JENNIFER.mdis current. Runjennifer versionand compare it to the<!-- jennifer-md-synced-for: ... -->marker on the file's last line. If they differ, follow the sync steps at the top ofJENNIFER.md. A stale copy is the most common reason generated code is rejected. - Read
JENNIFER.md, at least "The 10 rules that trip people up". Jennifer looks like other languages and is not:$sigils, no compound assignment,#comments, value semantics, no underscores in identifiers. - Read
CLAUDE.mdif there is one, for this deck's own conventions. - Look at the code you are changing and the overlay that tests it. Match their naming, comment density and docblock style.
- Understand the request. If it is ambiguous in a way the code cannot answer, ask before writing.
- Change the code in the smallest coherent step.
- Test it. Every behaviour change gets a test in the co-located overlay. A bug fix starts with a test that fails without the fix.
- Document it. A new or changed export is updated in
docs/cheatsheet.md, in the docblock, and in any guide or example that shows it. - Format:
jennifer fmt -w <files>. - Run the gate (below) and fix what it reports. Do not stop at "the tests pass": CI also fails on formatting, lint warnings, headers, overlays and undocumented exports.
- Report what you changed, which checks you ran, and their result. If a check failed or you skipped one, say so plainly.
tools/check-all.shIt runs every check .github/workflows/test.yml runs, in the same order, keeps
going after a failure, and ends with the list of what failed. A deck with
[decks] dependencies needs tools/vendor-deps.sh once first. Single checks,
when you are iterating on one thing:
jennifer test src/<module>_test.j # one suite (there is no finer filter)
jennifer fmt -l <files> # exits 1 if anything is unformatted
jennifer lint <files> # exits 1 on a warning
tools/check-headers.sh # SPDX pair + range match the manifest
tools/check-overlays.sh # every module has a _test.j, and back
tools/check-src.sh # src/ holds only .j files
tools/check-coverage.sh # every export is called from a test
tools/check-docs.sh # docs match the code, code blocks parse
tools/check-identity.sh # no template placeholder left
tools/check-examples.sh # every example still works-
Every
.jfile opens with three header lines, matching the manifest:# SPDX-License-Identifier: <package.license> # SPDX-FileCopyrightText: Copyright (C) <year> <holder> # pragma-jennifer-version: <engines.jennifer>The licence and range are stated twice on purpose; change both or neither. The range is
>=X.Y.Z, or>=X.Y.Z <A.B.Cwith an exclusive upper bound above the floor; the pragma must repeat it exactly. -
Every module in
src/(orsrc/topics/) has a co-located<module>_test.j. jvc will not publish without it. Only generated data files may opt out, with a# ci-no-overlayheader line or an entry insrc/.no-overlay. -
Every export has a signature in the cheatsheet (
docs/cheatsheet.md) with its real parameter names, every constant its real value, every struct its fields; every docblock's@param/@fieldmatch the declaration, written@param name {type} what it is- the order Jennifer'sdocblockmodule reads. The format is described at the top of the template's cheatsheet. -
Every exported function is called from an overlay.
-
Calls in the docs are checked. Snippets import the deck under its own name (
import "@scope/<slug>/" as <slug>;), and every<slug>.name(...)they show must exist and take that many arguments. -
Every
```jenniferblock in the docs parses.tools/check-docs.shparses each one without running it, so a fragment may use names it does not define, and...may stand for code left out, but a syntax error (a lost$,else ifforelseif, a{interpolating in a"..."string) fails the gate at the block's opening fence. Fence output and shell sessions astextorsh. A block that must not parse gets a<!-- no-check -->line directly before its fence, with no blank line between. -
Known gaps are a backlog, not a licence.
docs/.cheatsheet-todoandtools/.coverage-todolist what an older deck has not documented or tested yet. Remove a line when you fix it; never add one to make a check pass. -
Every chapter in
docs/SUMMARY.mdhas a file behind it, or the docs build fails. -
src/holds only Jennifer source. It is exactly what consumers vendor.
X_test.jis a white-box overlay ofX.j: it sees the internals, calls them unqualified, and inherits the module's imports. Re-importing one of them is an alias collision.lintfails on a warning, not on info. A# lint-disable: IDdirective only works as a trailing comment on the offending line.jennifer fmtre-joins hand-wrapped lines. Shorten a long line instead of wrapping it.{in a"..."string starts an interpolation; write\{, or use a raw'...'string.- In CI
jenniferruns in a container that mounts only the checkout. Test fixtures go inside the repository, and paths passed to programs are relative.
- Do not edit the shared files - every
sharedentry intools/shared-files, which is the workflows,.github/actions/*, this file, and everything intools/exceptcheck-examples.shandcheck-extra.sh- to fix something local to this deck. They are synced from the template repository and must stay identical across decks;tools/check-shared.shfails CI when one differs fromtools/shared.lock. A deck-specific check belongs intools/check-extra.sh(or a workflow of its own); examples that need inputs or a network belong intools/check-examples.sh, which is the deck's to change. If a shared file really is wrong, say so and propose the change for the template instead. - Do not edit
LICENSE, and editJENNIFER.mdonly through its sync procedure. - Do not add a dependency (
[decks]) or a capability (net,exec,sql, ...) without asking. A capability needs a comment in the manifest saying why. - Do not change the interpreter range (
engines.jennifer) without asking: it decides which interpreter CI tests on and which consumers can use the deck. - Never commit build output:
site/,dist/,vendor/, fixtures. - Ask before anything that leaves the machine or is hard to undo: pushing, tagging, creating a release, publishing, rewriting history.
The version lives in the manifest. A release is cut by pushing a tag that
matches it, plain 0.2.0 with no v prefix; release.yml refuses a tag
that disagrees. So the order is: bump the manifest, commit, then tag - and the
tag is the maintainer's call, not the agent's.
When a new interpreter (say 0.26.0) breaks this deck, it takes two releases:
- A capped patch release from the last tag. Branch from the deck's last
tag (say
0.3.1), change onlyengines.jenniferand every source pragma to>=0.25.0 <0.26.0, bump to0.3.2, and tag it. Release it before or with the new interpreter. - A minor release from main with
>=0.26.0and the deck's fixes for the new interpreter (0.4.0), after the interpreter is tagged.
Published releases are immutable, so 0.3.1 keeps claiming to run on 0.26.
jvc installs the newest deck version whose engines.jennifer admits the local
interpreter: on 0.25 that is now 0.3.2, which keeps those users working, and
on 0.26 it is 0.4.0. A 0.3.2 still vendored after an interpreter upgrade
fails at load with a clear version error instead of deep inside a call.
Development builds (-dev) count as newer than any release: they pass every
floor and fail every upper bound.