AGENTS.md

This repo is a Claude Code plugin that helps a team make its brand, design guidelines and mockups with their coding agent. It then hands the result to Crocotaste, the app that keeps every pull request on-system.

For contributors and coding agents working on the plugin itself, not for people who use it. People who use it read README.md; the long form of these rules is CONTRIBUTING.md.

Map

Commands

npm install          # install; also switches on the Git hooks
npm run check        # format:check, then the tests
npm run format       # Prettier
npm run validate     # claude plugin validate --strict
node scripts/crocotaste.mjs help   # check, tokens, sync, serve, fonts

npm test runs node --test checks/*.test.mjs scripts/test/*.test.mjs: the repo rules, then the command line tool. The evals (evals/README.md) call the model and cost money; CI never runs them.

Constraints

• Zero runtime dependencies. Prettier is the only devDependency. Node 20 or newer, ES modules, node --test.
• No SessionStart hook and no .mcp.json. The plugin is skills and one script.
• No prices and no dates about the Crocotaste offer anywhere in the plugin, and nothing about its internals.
• Never overwrite a user's file silently: tokens merges, skills ask before writing a file that exists, ## Decisions is kept verbatim.
• The plugin writes only its own files in a user's repo: BRAND.html, DESIGN.md, docs/design/, one block in CLAUDE.md or AGENTS.md, two lines in .gitattributes.
• No em dashes and no exclamation marks in prose: skills, templates, README, output copy.
• Nothing personal and nothing secret in the repo: no keys, no home-folder paths, no emails of people.
• Never credit an AI tool as an author, in commits, pull requests or files.

How to work

1. Branch from an up-to-date main (feat/..., fix/..., docs/..., chore/...).
2. Make the change, with its test first.
3. Run npm run check and read the result; run npm run validate when a manifest or skill changed.
4. Commit with a conventional message (feat(scripts): ..., fix(skills): ..., docs: ...) and no trailer.
5. Open a pull request against main with the template. Never push to main, never force-push, never --no-verify.
6. Docs are part of the change: fix the README, this file, CONTRIBUTING.md or a skill in the same pull request.

Writing a skill

• One folder, skills/<name>/, with a SKILL.md; the name is one plain word.
• Frontmatter keys: name, description, when_to_use, and argument-hint when it takes an argument.
• Under 500 lines. Detail goes into references/, files to copy into templates/.
• A test in checks/, and the folder added to checks/manifest.test.mjs.
• Plain words, one question at a time, neutral "we" when the plugin speaks of itself. End by naming the next skill.
• A skill calls the script as node "${CLAUDE_PLUGIN_ROOT}/scripts/crocotaste.mjs" <command>, never by a relative path: it runs from the user's repo, not this one.
• Inside a <style>, a block marker is wrapped in a CSS comment, /* <!-- tokens:start --> */, so the next rule stays valid CSS; the script reads both the bare and the wrapped shape.
• The examples are regenerated by running the skills and the script on them (tokens --write, sync), never edited by hand.

Claude Code

• Claude Code reads this file directly (Claude Code 2.1.277 or later); there is no CLAUDE.md here, because claude plugin validate --strict flags one at a plugin's root.
• No edit hook formats files here. Run npm run format before you commit.
• .claude/settings.json denies skipping the Git hooks (--no-verify, -n), changing core.hooksPath, editing .githooks/ and editing checks/guards.mjs. Every agent follows the same rule: the hooks and the guards are protected files, changed only by a person in a pull request of their own.