trellis-sync
Skill5 starsChanged 11 days agoMITView on GitHub
Check this project against the template it was made from, show what changed upstream, and apply only what the user picks. Use when asked to "check for template updates", "sync with trellis", "is my template copy out of date", "pull in upstream template changes", "what changed in the template".
In this repository48 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/project.mdcCursor rule
- bug-reportSkill
- build-verification-skillSkill
- daily-briefSkill
- grill-designSkill
- launch-checkSkill
- learnSkill
- pin-guardrailSkill
- prd-to-issuesSkill
- review-dependency-updatesSkill
- security-auditSkill
- setupSkill
- tddSkill
- trellis-surveySkill
- trellis-syncSkill
- worktreeSkill
- write-a-prdSkill
- build-verification-skillSkill
- daily-briefSkill
- grill-designSkill
- launch-checkSkill
- learnSkill
- pin-guardrailSkill
- prd-to-issuesSkill
- review-dependency-updatesSkill
- security-auditSkill
- setupSkill
- trellis-surveySkill
- write-a-prdSkill
- bug-reportSkill
- build-verification-skillSkill
- daily-briefSkill
- grill-designSkill
- launch-checkSkill
- learnSkill
- pin-guardrailSkill
- prd-to-issuesSkill
- review-dependency-updatesSkill
- security-auditSkill
- setupSkill
- tddSkill
- trellis-surveySkill
- trellis-syncSkill
- worktreeSkill
- write-a-prdSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
If there is no .trellis/manifest, this copy predates the sync mechanism or was not made from the template.
- Very specific: line 79
If a file needs a matching change elsewhere - a skill and its retained adapter routers, a hook and its settings.json entry - take both or …
- Distinctive: line 99
If the user declined everything, nothing is written - not the manifest, not the version.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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
Sync a copy against the template it came from
A copy made from a GitHub template has no git relationship to the template, so there is no "git pull" for it. This procedure closes that gap: it reports what upstream changed, and applies only what the user chooses.
The rule that matters
You do not classify anything yourself. bin/trellis-sync.sh decides which
bucket each file is in. Read its output and act on that. If you eyeball the
files and form your own opinion, you will eventually tell someone a file is
safe to overwrite when they spent an afternoon editing it.
1. Run the check
bash bin/trellis-sync.sh --porcelainEach line is <bucket>\t<path>. Exit codes: 0 nothing to take, 1 there
is something, 2 could not tell.
Exit 2 is not "you are up to date." It means the check did not run - no manifest, an unreachable upstream, an empty response. Report what it said and stop. Never summarise a failed check as good news.
If there is no .trellis/manifest, this copy predates the sync mechanism or was
not made from the template. Say so. Do not offer to generate one from the
current tree: a manifest built from an already-modified copy records your edits
as if upstream had shipped them, and every future sync inherits that lie.
2. Read the buckets back to the user
| Bucket | Means | Default |
apply | Upstream changed it; this copy has not | Offer to take it |
added | Upstream has a new file this copy lacks | Offer to take it |
conflict | Changed upstream and here | Ask. Never auto-apply |
removed | Upstream deleted it; this copy still has it | Ask. Deleting is theirs to choose |
deleted | Deleted here; upstream still ships it | Mention once. Assume deliberate |
localonly | Changed here, unchanged upstream | Nothing to do. Do not list these individually |
Lead with apply and added, because those are the cheap wins. Summarise
localonly as a count. A report where everything looks urgent gets skimmed.
3. Apply what they pick
You do not fetch or write files yourself. One command does it:
bash bin/trellis-sync.sh --apply <path> [--apply <path> ...]It resolves the upstream to a single immutable commit, takes the bytes for each path from that same commit, checks each one against its hash in the upstream manifest, and only then moves it into place. A file that fails any of that is not written and the run exits 2.
The earlier version of this section told you to run
gh api "repos/<upstream>/contents/<path>" ... > "<path>" by hand. Do not go
back to it, and do not reach for it when the script is inconvenient. It was
wrong twice over. That URL is the default branch, while the buckets above
are computed from the release manifest, so the bytes written were not the bytes
that had been classified. And > truncates the destination before the fetch
runs, so a failed fetch left an empty file where the adopter's file had
been. That is measured, not theoretical: 42 bytes to 0.
Rules that still need you:
- Show the diff before applying, for every file, including
apply. "Safe to take" means nobody edited it here, not that they wanted the change. - Never apply a
conflictfile without the user having seen both versions. Taking an update is a whole-file write. There is no merge. - If a file needs a matching change elsewhere - a skill and its retained adapter routers,
a hook and its
settings.jsonentry - take both or neither. removedis not applied by this tool. Upstream deleting a file is not the same as you wanting it gone; delete it yourself if you agree.
4. Recording happens automatically. Do not "regenerate the manifest"
--apply rewrites only the manifest lines for the files it actually took.
Everything else is left exactly as it was, which is what makes a declined
update show up again next time instead of disappearing.
Never run bin/trellis-manifest.sh --write in a copy. It hashes every
tracked file, so it records your work as though the template had shipped it.
Measured on a fixture: a template file the adopter had edited and declined went
from localonly to apply - "SAFE TO TAKE" - on the very next run, and their
own src/app.ts appeared under "REMOVED UPSTREAM - decide whether to keep". The
command now refuses to run outside the template, but the reason matters more
than the guard: the manifest records what the TEMPLATE shipped, and the moment
it records anything else, every later sync inherits that.
If the user declined everything, nothing is written - not the manifest, not the version. Declining is not syncing, and recording it as one would hide those same updates next time.
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.

