app-contribute
Skill0 starsChanged 2 months agoMITView on GitHub
Turn an app's local changes into upstream contributions - run sgs:drift for the candidate list, triage which changes are lessons versus app-being-an-app, and ship the keepers as clean-room issues or PRs. Use when asked "should any of this go back?", after fixing a bug in a copied component, or periodically alongside app-upgrade.
- Commits and pushes
In this repository15 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- app-adoptSkill
- app-startSkill
- app-upgradeSkill
- app-verifySkill
- map-cameraSkill
- map-controlsSkill
- map-popupsSkill
- repo-maintainSkill
- ui-bootSkill
- ui-furnitureSkill
- ui-iconsSkill
- ui-stowSkill
- ui-themeSkill
- ui-windowSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Run both when doing either.
- Distinctive: line 23
Every watermarked component whose files differ from what the watermark shipped, file by file.
- Very specific: line 84
After it merges and releases: run the app-upgrade flow on your own app to adopt the released version of your own fix, and move the …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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.
Files
Contributing upstream
Two mirrored questions keep an app and this repo honest, and each has its own skill:
- "Did upstream move past me?" →
sgs:status, theapp-upgradeskill. - "Did I move past my watermark?" →
sgs:drift, this skill.
Run both when doing either; they are cheap and their outputs feed each other (a file both drifted AND behind is exactly where a lesson was learned twice independently — the strongest possible contribution signal).
1. Get the candidate list
npm run sgs:drift # from the app; it takes a path tooEvery watermarked component whose files differ from what the watermark shipped, file by file. Drift is information, not error — a clean report just means nothing to consider, and exit 0 means the question was actually answered (a watermark the clone cannot resolve exits 1 and says so instead of reading as clean).
Drift needs a CLONE to read watermarks out of, and finds one itself: $SGS_CLONE, or a
directory named .sgs or sleek-geospatial-skills in the app or any ancestor. If there is
none, clone one anywhere convenient. You will need it for step 3 regardless: a contribution
is a branch in the clone. To see one diff:
git -C <clone> show v0.1.0:app/js/ui/tooltip.js > /tmp/upstream.js
diff /tmp/upstream.js path/to/app/app/js/ui/tooltip.js2. Triage each drifted file — the judgment step
The tier decides the prior; the diff decides the answer:
| where the drift is | prior |
framework (furniture.js, visible-area.js, popup-placement.js) | almost always interesting. These are contracts every app relies on; a change here is a bug found or a case the contract missed |
| components | often interesting. Ask: does this fix something ANY app using the component would hit, or does it bend the component to this app's taste? The first goes up; the second is a candidate for ejecting instead |
| tokens | usually app theming — an alias block should have carried it. Aliasing that goes wrong IS worth an issue |
app-shell / furniture (main.js, panel, table, popups) | usually the app being an app. Escalate only when the change is a transplantable LESSON (an ordering bug in boot, a posture case the panel mishandles), not a feature |
Walk them one at a time with the user; do not propose a bundle. Three honest outcomes per
file, and all three are wins. Each one gets a line in sgs-decisions.md — the triage is the
expensive part and it is worth exactly once:
- Contribute — a lesson with a reproduction. Continue below.
- Keep, and eject — deliberate permanent divergence. Set
"<id>": "ejected@<tag>"insgs.jsonso drift and status stop nagging and start informing. - Keep, no action — drift that is simply the app's own content. Leave the watermark alone; drift will keep listing it, which is correct: it IS drifted.
3. Ship the keepers, clean-room
The protocol is the clone's CONTRIBUTING.md, and it is the only path: reproduce against this repo's demo, never diff the app's code into the PR. Nothing in the contribution may say where the lesson was actually learned — no app names, no client names, no "in our project". This is what lets any application, however private, contribute identically.
As an issue (lower bar — can't spare the time, or unsure of the fix): describe the problem in the demo's own terms, with steps that reproduce it on a fresh clone.
As a PR (the full contribution), on a branch in the clone — the one time the clone is deliberately written to:
git -C <clone> switch -c fix-tooltip-clamp # BEFORE editing: a commit on no branch
# is silently lost on the next pull- A failing test in
tests/unit/ortests/e2e/, using only the demo and its data. - The fix, restated against the demo's code (not pasted from the app — re-derive it).
- The relevant
SKILL.mdupdated, if a convention changed and not just a bug. package.jsonversion bumped (required check; see CONTRIBUTING.md), CHANGELOG entry,Breaking:line naming component ids if the contract moved.npm run verifygreen in the clone, thengh pr create.
After it merges and releases: run the app-upgrade flow on your own app to adopt the
released version of your own fix, and move the watermark. Your app then holds the fix at a
tag rather than as drift — which is the whole loop closing.
Checklist
sgs:driftANDsgs:statusboth run; both outputs in front of you.- Every drifted file got one of the three outcomes, decided with the user, one at a time.
- Ejections recorded in
sgs.json, not just decided verbally. - Every triage outcome appended to
sgs-decisions.mdwith its reason and the version it was decided at, so the next drift report over the same file is read rather than re-triaged. Keep provenance OUT of the contribution itself; the log is the app's, and the app's alone. - Contributions carry zero provenance — reread the diff and the test for app names.
- PR branch created in the clone BEFORE editing; clone back to clean + pulled after.
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
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.

