sync

name	sync
description	Bring this machine level with the repo and push anything done here. Use at the start of a session, at the end of a session, and any time you are about to switch machines.
audience	team

Sync

Your team lives in one repo. Your laptop, your travel machine and every cloud run are copies of it. Sync is how they stay the same thing.

You should never type a git command. Ask for a sync, or let it run at the start and end of a session.

1. Come level before you start

git pull --rebase --autostash

--rebase keeps the history a straight line instead of a thicket of merge commits. --autostash sets aside anything half-finished, pulls, and puts it back.

If the pull reports a conflict, stop and say so in plain words — which file, and what the two versions each say. Do not resolve it silently. Conflicts should be close to impossible here (see below), so one appearing means something is worth a human look.

2. Push what happened here

git add -A
git status --short

Read the list before committing. Two things must be true:

• No .env, no keys, no tokens. They are gitignored, but check the list anyway. If a credential is staged, remove it, tell the user, and treat it as compromised.
• Nothing surprising. If files you did not touch are staged, find out why before pushing.

Then commit with a message that says what actually changed, and push:

git commit -m "<what changed, in a sentence>"
git push

If you were told not to commit, do not commit — and do not push. Leave everything uncommitted, say what is staged and waiting, and stop. This skill commits and pushes by design, which is exactly why an instruction not to has to win here.

If there is nothing to commit, say so and stop. An empty sync is a normal outcome.

3. Why conflicts are rare by design

Agents only ever write to inbox/<date>/<agent>-<timestamp>.md and runs/<month>/<id>.json. Every one of those filenames is unique to the run that made it, so two machines cannot write the same file. There is nothing to merge.

Files a human edits — shared/, CLAUDE.md, tiles.yml — are the only place a genuine conflict can occur, and only if you edit the same one on two machines without syncing between. Syncing at the start of a session is what prevents that.

4. What does not sync, and why

Not synced	Why
.env	Secrets never enter the repo. Cloud runs read theirs from the environment instead
node_modules/	Rebuilt, never carried
Anything in .gitignore	Same reason it is ignored

If a cloud run cannot see something, it is because that thing is not in the repo. That is the single most common cause of a scheduled workflow failing on its first run: the key that works on your laptop was never there to find.

5. Travelling

• On a phone — nothing to sync. The dashboard and your scheduled work run in the cloud against the repo directly.
• On a borrowed or second machine — clone the repo, work, sync at the end.
• Going offline — sync before you go. Work locally. Sync when you land.