agentleFS
Sign inStart free
cathrynlaverycathrynlavery/diagram-design/AGENTS.md

diagram-design

AGENTS.md61k starsChanged 31 days agoMITView on GitHub

Read CONTRIBUTING.md before changing anything. It has the gate suite and the rules for each kind of change. This file covers the parts of adding a diagram that agents keep missing. Follow "Adding a new diagram type" in CONTRIBUTING.md. The suite fails until these are done: Nothing checks these, so do them in the same PR: Run every command in gates.local_commands of .maintainer-policy.json before you push. The type count also appears in three places outside this repo: the GitHub About…

We split this AGENTS.md into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read CONTRIBUTING.md before changing anything.

    line 3
  2. Distinctive:

    Follow "Adding a new diagram type" in CONTRIBUTING.md.

    line 7
  3. Very specific:

    Plugin manifests: Keep description and keywords identical across .claude-plugin, .codex-plugin, .factory-plugin and .qoder-plugin.

    line 11
  4. Very specific:

    README thumbnail (new type): Run scripts/render-canonical-screenshots.py, add the cell with its full-size PNG link to the grid under "What …

    line 15
  5. Very specific:

    README file tree (new type): Add the new type-*.md to the tree under "Architecture", sorted by type name.

    line 17
  6. Very specific:

    Layout budget (new type): Add the type's row to the complexity budget table in skills/diagram-design/references/layout-budget.md.

    line 18
  7. Very specific:

    Run every command in gates.local_commands of .maintainer-policy.json before you push.

    line 20

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

Notes for coding agents

Read CONTRIBUTING.md before changing anything. It has the gate suite and the rules for each kind of change. This file covers the parts of adding a diagram that agents keep missing.

Adding a diagram type or variant

Follow "Adding a new diagram type" in CONTRIBUTING.md. The suite fails until these are done:

  • Gallery. Register every example in skills/diagram-design/assets/index.html. A new type gets the next number. Any other example of an existing type is a lettered variant: it goes directly after its parent with data-parent-type and a lettered eyebrow (28c). GitHub Pages publishes skills/diagram-design/assets/ when the PR merges, so the live gallery needs no separate step.
  • Type count (new type). Raise VISUAL_TYPE_COUNT in scripts/verify-docs-sync.py and scripts/verify-semantic-motion.py, and the hardcoded count in scripts/verify-screenshot-freshness.py and scripts/render-canonical-screenshots.py. Then fix every count the suite reports: the README, SKILL.md, CONTRIBUTING, onboarding.md and semantic-patterns.md, plus a new amendment in ADR 0002.
  • Plugin manifests. Keep description and keywords identical across .claude-plugin, .codex-plugin, .factory-plugin and .qoder-plugin. A type whose selection-table name differs from the word used in the descriptions needs a DESCRIPTION_ALIASES entry in verify-docs-sync.py. Leave version alone; main bumps it after merge (ADR 0009).

Nothing checks these, so do them in the same PR:

  • README thumbnail (new type). Run scripts/render-canonical-screenshots.py, add the cell with its full-size PNG link to the grid under "What it makes", then run scripts/build-readme-thumbs.py; it only builds thumbnails for PNGs the README already links. Update "01 to N" in the gallery sentence below the grid.
  • README named variants. Line, Scatter and Treemap have named variants (slopegraph, bubble, marimekko and others). A new one goes in the "Several types have named variants" line.
  • README file tree (new type). Add the new type-*.md to the tree under "Architecture", sorted by type name.
  • Layout budget (new type). Add the type's row to the complexity budget table in skills/diagram-design/references/layout-budget.md.

Run every command in gates.local_commands of .maintainer-policy.json before you push.

After a new type merges

The type count also appears in three places outside this repo: the GitHub About description, Cathryn's profile README (cathrynlavery/cathrynlavery) and diagramdesign.dev. No check covers them. If you are working for the maintainer, tell her the new count so she can update all three.

Download now (ZIP)

Trending

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Aug 30: 0 new projectsWeek of Sep 6: 0 new projectsWeek of Sep 13: 0 new projectsWeek of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projects
Aug 2026Sep 2026Oct 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Who's talking about cathrynlavery/diagram-design

The biggest 5 of 105 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 105

Talked about on GitHub, YouTube, Bluesky, the web and Hacker News (105 times).

On GitHub · 50

45 more on GitHub

On YouTube · 20

15 more on YouTube

On Bluesky · 19

14 more on Bluesky

On the web · 14

9 more on the web

On Hacker News · 2

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository2 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free