AGENTS.md

Project overview

cantrips is a multi-harness (Claude Code + Codex) plugin of curated agent skills: the core engineering loop (/grilling → /spec → /tickets → /implement + /tdd → /simplify → /review-gate → /commit → /compound) plus its supporting skills. A feature's spec and tickets are disposable working material under a gitignored .scratch/, deleted once the feature closes (docs/agents/cantrips-loop.md); what survives is the skills, git history, the decision records in docs/adr/, and the deferred ideas in IDEAS.md.

The plugin also ships a Claude Code mod, the loop panel under mod/: a pane beside the chat that shows the loop's stage, the feature's spec and ticket board, and a band chip that opens it. The repository is the plugin: the manifests, the skills tree, the mod, and the catalog files that publish it all sit at the root, and an install copies the whole checkout. Everything else here (docs/, this file) therefore rides along into an install; keep it small and keep nothing secret in it.

There is no build

This repository is content, not code: no dependencies, no package manager, no build, no lint step, and no tests but those of the scripts skills ship, such as skills/review-gate/scripts/findings.test.ts over the script /review-gate reports through, and those of the mod. mise run test runs every such file and the mod's pure core under node --test, with node 22.18 or later on PATH and nothing else installed, then the mod's mounted scenarios. Nothing needs installing to work on it, and nothing gates an edit: the tests are there to run when you touch a script or the mod, never a step an edit must pass. The one mechanical convention is .editorconfig (LF, UTF-8, two-space indent, trailing newline, 100-column guide). What tooling exists is convenience: mise.toml wraps the scripts in scripts/, mise run dev:sync-install mirroring the working tree over the local installs (Claude Code and Codex CLI) so unreleased edits are usable from other projects, mise run dev:fork-diff reporting how far a fork has drifted from its upstream without ever asserting — it defines no expected state and exits zero whatever it finds — mise run dev:mod-preview starting the mod's preview session, and mise run dev:mod-shot rendering that session's pane to an image (uv fetches its Python libraries on the first run).

Consequently the invariants below are honored by hand. Nothing fails when one drifts, so check them yourself whenever you touch the files they cover.

Repository structure

• skills/<skill>/SKILL.md: the one shared skills tree; both harnesses auto-discover it.
• agents/<role>.md: the plugin agent definitions, one per role a skill dispatches, which Claude Code loads as cantrips:<role> (a subfolder joins the name with a colon); a definition is distributable like a skill, and a role's brief lives in its body and nowhere else. A definition's description says who summons the role, the user through the skill that dispatches it or by name, or the skill alone where the role takes only the message it composes, since no frontmatter field keeps a plugin agent out of automatic delegation and a description that reads as an open offer gets it dispatched unasked. A skill's own agents/openai.yaml is unrelated: that is the skill's Codex sidecar, and defines no agent.
• mod/: the loop panel mod, its pure core tested from tests/mod/; mod/CLAUDE.md holds its layout, reach boundary, style, tests and preview session, so read it before editing either folder or running mise run dev:mod-preview.
• .claude-plugin/plugin.json + .codex-plugin/plugin.json: the dual manifests; shared fields must stay identical, and the hooks and types fields are Claude-only.
• .claude-plugin/marketplace.json + .agents/plugins/marketplace.json: the catalog files that publish this repo as an installable plugin (Claude Code takes a string source, Codex CLI the object form; both point at ./).
• FORKS.md: the fork divergence ledger — every upstream skill listed, forks with how they deliberately differ and a reason that stays true of the fork as it stands, the rest marked not ported; /sync-upstream and human readers both consult it.
• docs/agents/cantrips-loop.md: the per-repo loop config — what the six storage verbs translate to here, and which knowledge stores are enabled (docs/adr/ on, docs/solutions/ off). Storage-touching skills read it instead of skills/setup-cantrips-loop/defaults.md; /setup-cantrips-loop rewrites it.
• .scratch/<feature>/: the spec and tickets of a feature in flight, gitignored and disposable — deleted when the feature closes, which is the human's act. .scratch/sync/ is not feature material but dev:fork-diff's cache of upstream files, outliving any one feature and safe to delete wholesale.
• docs/adr/: durable decision records with supersession chains, written only through /compound's user gate and read back by /spec.
• docs/research/: primary-source research notes, written by /research.
• scripts/: repository tooling — the bodies mise.toml's tasks wrap, kept in files so a task definition reads as what it runs. Root scripts/ maintains this repository, unlike the scripts/ directories inside skill folders, which are shipped assets an installed skill invokes; no skill in the plugin's tree may reference anything here. mise.toml runs these directly, so stage anything added here with git add --chmod=+x — a plain add records mode 100644 and the task then fails on a fresh Unix checkout.

How to add or revise a skill

1. Write against the /writing-for-agents standard (skills/writing-for-agents/SKILL.md): predictability, leading words, checkable completion criteria, progressive disclosure, positive phrasing, no no-ops, prune sediment. Forks prune rather than pad: a fork carries no restatement upstream lacks. Running longer than upstream is not a violation of that: a fork may add rules upstream has no counterpart for. A skill is guidance for an adaptive agent, not a program: state the intent and the guardrails the agent cannot infer — when to stop, when to ask, what done proves — and leave enumerable edge cases to its judgement. A skill's argument is the user speaking: read it as you read any request, and match a word as a flag only where the argument-hint declares it one, as /review-gate's --fix. A rule set that grows a clause per reviewed case is the symptom; hold such a file to a line budget and cut before adding.
2. Frontmatter: name, description (trigger-rich for model-invoked skills; one human-facing line + disable-model-invocation: true for user-invoked ones), argument-hint where an argument is meaningful, version (per-skill semver; bumped per the versioning section below), and for forks source recording upstream provenance, e.g. source: mattpocock/skills@1.2.3 (to-spec). version and source are unofficial keys the loaders ignore. Changing a fork's body beyond its upstream text is a divergence: record it in FORKS.md in the same edit, so /sync-upstream preserves it instead of merging upstream's wording back. README.md describes each skill's behaviour in prose; where an edit changes what one of its sentences claims, edit README in the same change. A passage carried byte-identical stays that way even where a quality pass finds a real improvement in it: skip the finding and name the reason, since the edit trades a permanent sync divergence for a redundancy upstream chose. Where a divergence already sits in carried text and house formatting is all it buys — a reflow, a restructure, a reordering, a gloss — restore upstream's bytes on sight, and delete the bullet that recorded it in the same edit; a /sync-upstream run instead surfaces both — restore and bullet deletion — as one audit finding, deferred to the spec its close names. Where the edit pruned a genuine no-op instead, keep it, and record it in FORKS.md like any other divergence. Where a fork keeps a pruned passage's substance inline, check the inline copy against the whole passage it replaces, since a clause dropped there reads as the passage to every later record. Where a fork needs a name for something upstream already names, take upstream's name. Every skill carries an agents/openai.yaml sidecar (interface.display_name, interface.short_description, policy.allow_implicit_invocation): false for user-invoked skills — Codex CLI ignores disable-model-invocation, so the sidecar is what stops auto-firing there — and true for model-invoked ones, stating the intent explicitly rather than leaning on Codex defaults. The sidecar's allow_implicit_invocation is always the logical inverse of the SKILL.md disable-model-invocation; a skill shipped without a sidecar auto-fires in Codex whatever its frontmatter says.
3. Pipeline skills end with a flow pointer naming the next step(s) of the loop and marking a user-invoked target (user-invoked); keep those pointers consistent when renaming or inserting skills. Author each closing from flow-pointers.md: every closing carries its format clause and its deputy step word for word, a closing whose first rendered step naming a skill can be /review-gate carries its compact hint the same way, and a gate that puts a decision to the user carries its routing clause the same way, the copies staying identical across skills as rule 5 asks for its own clause. The format rides in the closing because an agent closing a skill skips a read whose target holds only presentation. An agent cannot observe its own context level, so the compact hint conditions on the rendered step alone and is addressed to the user, who can.
4. A sibling reference file that declares what it extends or replaces must cover every path the parent skill can take — the inline pass included, since it reaches none of the sections a main-path declaration names. A declaration that names only the main path leaves the other paths running the parent's own rules, which is how a mode degrades silently at one level while reading correct at the others. The inverse costs as much: a brief written for a dispatched carrier holds lines addressed to one, so a fallback that runs the pass inline names what travels rather than reusing the whole prompt. A lens finder's definition says "You edit nothing" — right for a finder, and in the parent context it forbids the fixes /simplify's next step tells that same context to apply.
5. Every step that dispatches a general-purpose sub-agent asks for a background dispatch and carries the parenthetical "(Claude Code: do not use run_in_background: false)". A blocking dispatch freezes the session for as long as the agent runs, which degrades the user experience and is invisible from inside the skill. A step that tiers a general-purpose dispatch carries the "Model selection" paragraph /spec holds for its rereader, changing only the noun for the dispatch it tiers, and the tier where that dispatch wants another — a top tier reads "the platform's most capable model" and drops the sentence naming a Claude Code class, since the top class is renamed faster than a skill is revised. A step that dispatches a definition from agents/ names it by its scoped name, passes no model of its own — a per-dispatch model outranks the frontmatter pin — and carries the fallback clause, changing only the link: "Where the harness loads no plugin agent definitions, read <role>.md, skip its frontmatter, paste its body into a general-purpose dispatch run in the background, and apply the model its frontmatter names where the dispatch primitive exposes a selector." The parenthetical and the model paragraph stay off such a step, since the definition pins both; a definition's frontmatter may name a model alias, while a body, like a skill's, still names no class. These three are the only harness-specific settings a skill body may name, and each clause stays identical across skills so a reader meets one clause, not five.
6. Distributability rule: the plugin must be installable by anybody — no user-specific paths, names, or personal conventions inside skill bodies. Personalization belongs in the user's own global CLAUDE.md.
7. Cross-skill references use this repo's names (/spec, /commit, /compound…), never upstream names. In docs and prose, skill names always carry the / prefix, whatever the invocation mode.
8. Markdown intended for agents (SKILL.md files and their references, AGENTS.md, specs) goes one sentence per line, and is exempt from the 100-column guide. Text carried from an upstream is the exception rule 2 already covers: its line breaks stay upstream's, however long its lines run, since reflowing re-creates the whole paragraph as a diff at every sync. Human-facing docs (README.md, WHY.md, NOTICE.md, IDEAS.md) wrap at ~100 columns instead.
9. A gate branches on what the agent can observe in what it holds, never on how that material was produced. "Working from a spec that folded in the standing decisions" is observable; "arriving from /implement" and "working from a spec" are provenance, and an agent that got there another way matches neither branch and invents the behavior. Where a gate has a second branch, both branch on the one test, so the pair partitions every route into the skill.
10. Two settled sentences point at the loop config, and a skill takes the one its own use calls for: the verb form where it speaks a storage verb, the store form where it only gates a knowledge-store read. The store form states the fallback outright — the store is off — where the verb form sends the reader to defaults.md for it, so a skill that speaks no verb and takes the verb form buys a load it cannot act on. Copy the wording from a skill that already carries the form — /spec for the verb form; /diagnosing-bugs for the store form, swapping only which store or stores it names as off — as rule 5 asks for its own clause.
11. Prove a skill edit by probing what it makes an agent produce: pose a hypothetical finished-work scenario to a fresh agent holding only the revised skill and how it was invoked, ask for its next response, and grade that against a pass line written beforehand, from a scenario that leaves the behaviour under test for the skill to decide. Run each scenario against the unedited skill too: a pass line it already meets proves nothing about the edit. Keep the probe oblivious: its prompt poses the scenario and asks for the response, with as few cues as simulating it takes — never that it is a test, what changed, or what gets graded — since an agent that knows it is examined deliberates harder than a real run and passes where a real run fails. The probe is oblivious to this project too, so run it through the claude CLI rather than as a sub-agent, on Opus at medium effort unless the user names another: claude -p from a temp directory outside this repo holding a copy of the skill, with --setting-sources project to keep the installed plugin and the user's instructions out (--bare would too, but reads no OAuth login), the skill's body inlined in the prompt the way a harness loads it, and whatever the scenario says already happened made true beforehand — --session-id pins the session a skill script keys its state on, and --resume on it probes a behaviour that spans replies, turn by turn; the prompt opens on the scenario, never on the skill's slash command, which print mode runs. A probe registers none of the skill's frontmatter hooks, since the body is inlined rather than loaded, so what a hook does is proven by the script's tests. An agent definition is proven on the mirrored install instead — mise run dev:sync-install, then a scratch session on the harness, its transcript dissected the same way — since a probe inlines a body and loads no plugin agent. Dissect the transcript (--output-format stream-json --verbose) as well as the answer: every call, read, resent input and token spent is behaviour the skill caused, and a skill that reaches the right answer the long way still fails. A gate run over skill prose reviews wording, and wording always yields another finding.

Dual-manifest and catalog sync

The plugin has two plugin.json manifests (Claude Code + Codex CLI; the Codex schema is a superset of the shared fields, while hooks and types are Claude-only, so the Codex manifest carries neither) and two catalog files, because neither harness reads the other's. Shared metadata is duplicated by necessity, and keeping the copies honest is a manual duty:

• the shared plugin.json fields (name, version, description, author, homepage, repository, license, keywords) stay identical between the two manifests;
• both catalog files publish exactly one plugin, named after the manifests, sourced at ./, and described in the manifests' own words;
• every skill directory carries its agents/openai.yaml sidecar.

When editing plugin metadata, edit BOTH manifests, and both catalog files for the description.

Versioning and releases

release-please (.github/workflows/release-please.yml, release-please-config.json, .release-please-manifest.json) maintains a rolling release PR from Conventional Commits; merging it bumps the version, updates CHANGELOG.md, tags vX.Y.Z, and creates a GitHub Release. There is one release unit, and no version file to maintain: .release-please-manifest.json is the version of record, mirrored via extra-files into both plugin.json manifests. The simple release type would also write a version.txt, but it only updates that file when it already exists, so leaving it absent costs one skipped-file warning in the workflow log and nothing else.

• Commit messages follow Conventional Commits. feat/fix trigger releases; chore/refactor/docs do not. Anything user-facing (skills, manifests) must be feat or fix.
• Plain semver: a breaking change bumps major, feat bumps minor, fix bumps patch.
• Per-skill version frontmatter is bumped by hand when a skill changes; the plugin version is release-please's job. One bump per skill per release, sized to the largest change in it — successive edits to one unreleased change are one change, not three. Never hand-edit the plugin.json versions or the release manifest.

Boundaries

These govern your own conduct here, not what a skill may instruct its own users to do.

Never:

• Create a git branch, stage files, or commit work yourself unless the user expressly told you so.
• Commit secrets, tokens, .env files, dumps, or credentials.
• Put user-specific paths or personal conventions inside the plugin (see distributability above).
• Reintroduce a build step, a dependency, or a check script without asking; their absence is deliberate.

Ask first before:

• Renaming a skill (it touches the flow pointers, the README roster, and any spec naming it).

Preferred agent behavior

• Start by inspecting existing patterns: read a neighboring skill before writing a new one.
• Before editing a file, check IDEAS.md's Adopt when triggers for one naming it, and propose each entry that fires as a related change, for the user to include or leave.
• CLAUDE.md here is a committed relative symlink to AGENTS.md; edit AGENTS.md, never the symlink.
• Propose updates to this file when you notice a pattern or introduce changes that deserve to be documented for future sessions.