cantrips AGENTS.md

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 repository is the plugin: the manifests, the skills tree, 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 test suite, no lint step. Nothing needs installing to work on it, and nothing gates an edit: there is no command to run before or after one. 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, and 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.

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.
• .claude-plugin/plugin.json + .codex-plugin/plugin.json: the dual manifests; shared fields must stay identical.
• .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 why, 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.