agentleFS
s-frantzs-frantz/sleek-geospatial-skills/CLAUDE.md

sleek-geospatial-skills

CLAUDE.md0 starsChanged 2 months agoMITView on GitHub

This is a conventions repo. The app exists so the conventions have something to be true about, which means a change that makes the app better while making a convention less clear is a bad trade. .claude/skills/ holds the skills. Before changing anything, read the one that covers it. Names carry their category: app- procedures act on an app, repo- procedures act on this repo, ui- and map- conventions are consulted while building. Procedures run in a rough order (app-start,…

The file

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

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Measure, do not eyeball: Never put a number in SIZE_FACTOR or NUDGE that did not come out of npm run icons.

    line 63

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
CLAUDE.md

Working in this repo

This is a conventions repo. The app exists so the conventions have something to be true about, which means a change that makes the app better while making a convention less clear is a bad trade.

Read the skill first

.claude/skills/ holds the skills. Before changing anything, read the one that covers it.

Names carry their category: app- procedures act on an app, repo- procedures act on this repo, ui- and map- conventions are consulted while building. Procedures run in a rough order (app-start, then app-verify forever, then app-upgrade paired with app-contribute); conventions have no order, only a subject. See README.md for the map.

touchingread
index.html, app/vendor/ui-boot
colours, css/tokens.css, themeui-theme
map controls, control-stack.jsmap-controls
icons.js, any glyph artui-icons
panel.js, css/furniture.cssui-furniture
any collapse, hide or minimiseui-stow
modals, dialogs, the Escape keyui-window
popups, tooltips, anything anchoredmap-popups
fitBounds, easeTo, zoom-tomap-camera
tests, or claiming something worksapp-verify
furniture.js, data-sgs-furniture, the camera/popup contractmap-camera
sgs.json, sgs:status, syncing an app against this repoapp-upgrade
creating a new app, sgs:init, the capability interviewapp-start
adopting into an app that already exists, --eject, --manifest-onlyapp-adopt
sgs:drift, sending a fix back, ejecting a componentapp-contribute
adding a component id, a capability, a skill, or anything at allrepo-maintain

Framework terms (clone, app, manifest, watermark, drift, ejected, tier, capability) are defined once, in VOCABULARY.md — link there, never redefine.

Most skills also travel into apps: a component owns the SKILL.md that describes it, listed among its files in sgs-components.json, so sgs:init copies it exactly when it copies the code. Writing or moving a skill means editing that file too. The skills for deciding how an app begins (app-start, app-adopt) and the laws for this repo (repo-maintain) belong to no component and stay here.

Editing sgs-components.json or sgs-capabilities.json

Adding a file to an existing component's list is a normal change, and that includes a .claude/skills/<name>/SKILL.md: a skill is one of the component's files. Minting, renaming or splitting a component id is bigger than it looks: every existing app's sgs.json still names the old id, and sgs:status/sgs:drift report it as unknown until the manifest is updated — so the CHANGELOG entry must say what manifests should do. The repo-maintain skill carries the tests an addition must pass; read it before growing either file.

Working with the maintainer

Build locally; open a pull request only when asked. Make changes on a local branch, verify them, and show them running on a localhost port. Then say what changed and ask what goes into a PR. Do not open one PR per change, and do not push each change as it lands. "One idea per PR" in CONTRIBUTING.md is about what a PR contains once it is opened, not a reason to open one per idea: nine small PRs for one session's work had to be folded back into one release.

House rules

Measure, do not eyeball. Never put a number in SIZE_FACTOR or NUDGE that did not come out of npm run icons. A guess reads exactly like a result, which makes it worse than leaving the entry out.

Say what you ran. "13 passed" is a result. "Looks right" is not. If you skipped a rung, say which and why.

Comments explain WHY. The what is in the code. Most doc comments here record a decision and the alternative it beat, and several record a bug that has actually happened. That is the repo's main content, so do not compress it away.

Avoid em-dashes in code, comments, docs and UI copy. Commas, colons and full stops.

Stated as a practice rather than an absolute, because the absolute was not true: the rule read "no em-dashes" while the corpus carried hundreds, so a contributor reading this file and a contributor reading any other one got different instructions. The rule now says what is actually enforced. Do not open a pull request that sweeps them out of files you were not otherwise touching: it would collide with everything in flight and show up as drift in every downstream app at once, for a change with no behaviour in it. Remove them from lines you are editing anyway, and the count goes down without anyone running a campaign.

No decorative accent stripes. A coloured bar down the left of a callout, along the top of a card, or beside a heading is the most reliable visual tell of generated UI. It is decoration standing in for hierarchy, and it is almost always a second copy of something the reader can already see: the popup's accent stripe repeated what its swatch said, and the aside's left border repeated what its tinted background said. Earn the distinction with the border, the background, the type and the spacing you already have. Colour is for things that carry information, which here means the layer swatches and the focus ring.

The broader rule this is one instance of: an element that repeats information already present next to it is decoration, not design. Before adding an accent, name the fact it carries and check nothing adjacent carries it already.

Keep decisions pure. A function that reads the document can only be tested by building a document. If a decision can take its inputs as arguments, it should, and the DOM-reading wrapper goes next to it. popup-placement.js is the pattern.

One owner per shared thing. Escape has one owner. Panel geometry has one applier. Glyph sizing has one table. When two features want the same resource, the answer is a stack or a registry owned once, not a cleverer guard in each of them.

No golden screenshots. See app-verify.

Before you say it works

npm run verify

Types, unit, geometry, ink. All four, and quote what came back.

Scope

Kept deliberately small, and deliberately not here: a real layer model, a group tree, drag reordering, a config schema, symbology, a basemap switcher, a minimap. Each is a reasonable addition; none is required to demonstrate a convention, and every one of them makes the repo harder to read as a set of examples. Add one only when it teaches something the existing skills do not.

Download now (ZIP)

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.