agentleFS
robotostudiorobotostudio/turbo-start-web-agent/.claude/skills/sync-changes/SKILL.md

sync-changes

Skill4 starsChanged 47 days agoMITView on GitHub

Use at the start of any editing session in this repo, and before delivering any change — pull the latest state before editing, never commit directly to main, and land work as a branch and a pull request. Use whenever asked to make, save, ship, or publish a change, or when starting a new task here.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 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.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If you are stale, rebase onto the live branch or start a fresh branch from it.

    line 54
  2. Very specific:

    Never work directly on main: Create or switch to a branch first, e.g.

    line 56
  3. Very specific:

    This section is about gh in a shell — route 3 above: If you are opening the pull request through a platform control or an MCP tool, type …

    line 129
  4. Very specific:

    Never pass a multi-line body as a --body "…" argument: Write it to a file and use --body-file:

    line 134
  5. Distinctive:

    The body must describe the change that was requested: Not the setup you did along the way, not a side effect you swept up.

    line 165

≈ “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.

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

Sync and deliver changes

This is a template: main is not guaranteed to be any given adopter's production branch — that's a per-project decision, not something this repo declares. On many projects it will be (this repo's own README documents VERCEL_ENV disambiguating a production deploy from a preview one, which only matters if main is what ships to production), but treat that as unconfirmed until you know otherwise. Before your first commit in a session, confirm which branch this project actually deploys from — ask the operator, or check the hosting provider's project settings (e.g. Vercel's Production Branch) — and treat that branch, not necessarily main, as the one nothing gets pushed to directly. If you cannot confirm it, assume the worst case (that the branch you're on ships live) rather than the permissive one. Committing directly to the live branch publishes to whoever is looking at the live site, with nobody having reviewed it first. This repo's own CI (.github/workflows/ci.yml) runs pnpm run checks on every pull request — the same command you run locally, covering harness:check, content:check, catalog:check, gallery:check, lint, test, typecheck, and build. That gate only fires on a PR, so a direct push to any branch that skips the PR step skips it entirely. Run pnpm run checks before you deliver: CI runs the identical script, so a failure there is one you could have seen first.

The workflow

  1. Pull before editing, and say what base you are on. git fetch, then check that your branch point actually matches the live branch:

    git fetch origin
    git log --oneline -1 origin/main
    git merge-base --is-ancestor origin/main HEAD && echo "up to date" || echo "STALE"

    State the result before your first edit — "starting from abc1234, which is current origin/main". One line, and it makes a whole class of failure visible immediately instead of at merge time.

    This matters most in a resumed session. Continuing yesterday's chat reuses yesterday's container: the clone is as old as the session, and the conversation still contains work you believe is unlanded but which was merged hours ago. You then commit on top of a base that no longer exists and re-apply changes already on the live branch. That happened here on 2026-08-21 — a branch whose merge base was 17 commits behind produced a pull request that conflicted by re-adding an FAQ entry already merged. git status looked perfectly healthy throughout, because it was reading a stale cache.

    If you are stale, rebase onto the live branch or start a fresh branch from it. Do not build on the old base and leave the conflict for a human.

  2. Never work directly on main. Create or switch to a branch first, e.g. git checkout -b <descriptive-name> (this repo's own current branch, feat/block-system, is an example of the naming style — short, hyphenated, prefixed by kind of change).
  3. Commit your change with a message describing why, not just what changed. Being asked to make a change is authorization to commit it — a commit on a branch is not the live site, and nothing is published by it existing. Do not stop and ask permission to commit work you were just asked to do.
  4. Deliver it by whatever channel this platform actually has (see below), then let CI run and let a human merge. This is the review step that makes "an agent may edit this site" safe to say at all. Never merge your own pull request.

Delivery: name your channel before you run anything

Getting the branch up and opening the pull request are two separate steps, and the route for each differs by platform. Work out which route you have before typing a command, and say which one you used.

Getting the branch up:

  1. git push, where the shell has a working origin.
  2. The platform's own git integration, where the shell has no origin. Codex cloud containers have none by design — the task's diff is what gets delivered, not a pushed branch.

Opening the pull request:

  1. The platform's own Create PR control, wherever one exists — this outranks the shell. v0, Claude Code cloud, and Codex all show one. Where there is a control, use it and do not reach for gh at all.
  2. A GitHub MCP tool, if one is connected to the session.
  3. gh pr create, only once you have confirmed that gh exists and is authenticated here.
  4. Ask the operator, and tell them the branch name and what is on it.

Looking before you run costs one turn. On 2026-08-26 an agent on v0 pushed its branch successfully, then ran gh pr create, and reported that it "couldn't create the PR because GitHub CLI authentication isn't configured in this environment" — while v0's own Create PR button sat in the toolbar directly above that message. The branch was already on the remote. Nothing was broken except the choice of route.

Two failures look alarming and are not:

  • No gh binary, or a gh that is not authenticated. Several platforms ship none, and some ship one with no credentials. Neither is a permissions problem and neither blocks delivery — use the platform's own control.
  • fatal: 'origin' does not appear to be a git repository. Codex cloud containers have no git remote at all, by design: the task's diff is what gets delivered, through the platform, not through a push. Seeing this does not mean the repository connection is broken, and it is not worth retrying — use the platform's own control.

A 403 on push is different from both: that one is a credentials problem, and it means the session has read access only. Say so plainly rather than retrying.

Pausing before the pull request

Where you control when the PR opens, pause first: say the change is committed, say what is in it, and ask. A PR is outward-facing — it creates a review artifact, notifies people, and starts CI.

Where the platform's own instructions tell you to create the PR immediately, follow the platform. Its system and developer instructions outrank this file, and there is no safety cost to losing the pause: the PR is not the gate. Nothing reaches the live branch without a human merging it, and on a protected branch GitHub itself refuses anything that skips that path.

Writing the pull request body

This section is about gh in a shell — route 3 above. If you are opening the pull request through a platform control or an MCP tool, type the body into that and skip to the trailers section: there is no shell in the path, so no escaping rule to get wrong.

Never pass a multi-line body as a --body "…" argument. Write it to a file and use --body-file:

cat > /tmp/pr-body.md <<'EOF'
## The change

What changed, and why.
EOF
gh pr create --title "…" --body-file /tmp/pr-body.md

This is a mechanical rule, not advice about being careful, because the failure it prevents is invisible until after the fact. A shell does not expand \n inside double quotes — it passes a backslash and the letter n. GitHub stores them, Markdown has no meaning for them, and the entire description renders as one run-on line with the escapes showing. It happened here on 2026-08-20 (AGENTS.md §6), and the broken command sat visible in an approval prompt without anyone spotting it, because nothing about it looks wrong unless you know the quoting rule.

--body-file has no shell escaping at all, so the defect cannot occur. If your platform has a PR tool or UI control instead of a shell, use that and this does not apply.

CI enforces it: the pr-hygiene workflow fails a pull request whose body carries literal \n escapes, and re-runs when the body is edited, so fixing it turns the check green without a new commit.

Two things the check cannot judge, which are yours:

  • The body must describe the change that was requested. Not the setup you did along the way, not a side effect you swept up. An agent once titled a pull request after a generated file the dev server had rewritten, never mentioning the change the client asked for. Every automated check passed.
  • Say what you actually verified. "Ran the checks" when you ran three of eight is worse than saying nothing.

Commit trailers

Land agent-made commits with these two trailers, and no others:

Requested-by: client
Agent: Claude Code

Each trailer goes on its own line, and the same shell rule that mangles a pull request body mangles a commit message: -m "Requested-by: client\nAgent: v0" puts a literal backslash and n between them, git reads one trailer whose value happens to contain two odd characters, and Agent: stops existing. That shipped on PR #47 on 2026-08-27. Use a second -m, a heredoc, or --file. CI fails it now (pr-hygiene), but the fix afterwards is an amend and a force-push, so it is much cheaper to get right the first time.

Requested-by: is whoever asked for the change — client when a client asked through an agent, or a name when you know it. Agent: is the platform you are running on: Claude Code, Codex, v0. Both are plain git trailers, so git log --grep='^Requested-by: client' answers "what did the client change this month" and git log --grep='^Agent: Codex' answers "what came through Codex" — which is the provenance a developer actually wants when a surprising line turns up in a content file.

Do not add vendor attribution trailers. Several platforms append Co-Authored-By: <model name> and a session URL by default. Strip them. They credit the model vendor rather than recording who wanted the change, they put a permanent AI-authorship marker in the history of what may be a public client repo, and the session link is useless to anyone but the account that created it.

Get this right at commit time. A trailer is part of the commit message, so correcting it means git commit --amend and a force-push — a bigger operation than getting it right once, and one that not every path can carry. A hosted platform's shell frequently has no git credentials at all, so an amend typed into a terminal never leaves the container: on 2026-08-21 an agent read the failing check, diagnosed it correctly, amended the commit, and could not deliver the fix, and the pull request had to be closed and the work redone. The platform's own integration may well be able to rewrite the branch even where its shell cannot — v0 does — so treat a failed force-push as a fact about the path you took, not about the platform.

So: check the message before you commit. If your platform adds a trailer automatically, remove it in the same step rather than planning to fix it afterwards. And if you find yourself unable to force-push a correction from the shell, do not retry it there — try the platform's own delivery path, and if that is not available say so plainly, quote the corrected message, and ask the operator to push it.

Platform caveat — verify the push actually landed

On some hosted agent platforms the shell has no git credentials configured at all, and the platform's own git panel (not the shell) is the only channel that actually talks to the remote. In that situation, git status, git log, or a cached origin/main can all look completely healthy locally — they're reading a local cache — while being hours stale, because the shell was never able to fetch or push in the first place. An agent that assumes shell git works will commit locally, report success, and silently lose the work: it never left the sandbox. Before calling a change "shipped," confirm it through a channel that actually reflects the remote — the platform's own PR/branch UI, or gh pr view/git ls-remote succeeding — not just a clean local git status.

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.