agentleFS
skyfox675skyfox675/agents-skills/.claude/skills/fast-forwarding-branches/SKILL.md

fast-forwarding-branches

Skill11 starsChanged 7 days agoMITView on GitHub

Keep the primary checkout's integration branch current with a safe, interval-driven `git pull --ff-only` — and alert, never improvise, when the fast-forward is refused. Because agents work in worktrees cut from the primary, a stale primary silently hands every new worktree a stale base (stale hooks, stale scripts, stale skills). A refused fast-forward ("Your local changes to the following files would be overwritten", "Not possible to fast-forward") means someone left work in the primary or the branch diverged — that is an anomaly to report, never to stash, reset, rebase, or merge away. Use whenever running the branch-ff lane, keeping a local checkout in sync on a loop, or deciding what to do when a pull is blocked by local changes or divergence.

The file

We split this skill 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:

    Never substitute a bare git pull (it can merge), pull --rebase, reset, checkout -f, or clean.

    line 43

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

Fast-forwarding the primary checkout

One job: keep the primary checkout's integration branch at the remote tip, safely, on a loop. Fast-forward when it is clean; report loudly and change nothing when it is not.

Why this lane exists (it explains every rule below)

Agents work in worktrees cut from the primary checkout. Everything a fresh worktree inherits — git hooks, repo scripts, CI config, the skills and agents themselves — comes from the primary's branch. So a primary that has drifted a week behind hands every newly-created worktree a stale base, and the staleness is invisible until something breaks oddly. One cheap pull --ff-only per tick keeps the base honest.

The second half matters just as much. Because agents are supposed to be in worktrees, the primary checkout should normally be clean. If a fast-forward is refused because local changes would be overwritten, that is not a routine condition to work around — it means uncommitted work is sitting in the primary. Clobbering it would destroy someone's work. So the refusal is the product of this lane: surface it, and stop.

Project bindings

Project-agnostic; the adopting project defines these in its own CLAUDE.md.

PlaceholderMeaning
<integration-branch>The branch the primary checkout is expected to sit on (e.g. main)
<remote>The remote to pull from (almost always origin)

The tick — run exactly this

Safe by construction: --ff-only never rewrites, merges, or clobbers anything — it refuses instead. The branch guard leaves a primary that is on some other branch completely alone. Run this from anywhere inside the repo (the primary checkout or any worktree — it resolves the primary itself):

PRIMARY="$(dirname "$(git rev-parse --path-format=absolute --git-common-dir)")"
BRANCH="$(git -C "$PRIMARY" rev-parse --abbrev-ref HEAD)"

if [ "$BRANCH" != "<integration-branch>" ]; then
  echo "ff tick: skipped — primary is on '$BRANCH', not <integration-branch>"
else
  BEFORE="$(git -C "$PRIMARY" rev-parse --short HEAD)"
  git -C "$PRIMARY" pull --ff-only <remote> <integration-branch> 2>&1 | tail -8
  AFTER="$(git -C "$PRIMARY" rev-parse --short HEAD)"
  echo "ff tick: $BEFORE -> $AFTER"
fi

Never substitute a bare git pull (it can merge), pull --rebase, reset, checkout -f, or clean. The only mutation this lane is ever allowed to make is a fast-forward that git itself judged safe.

Decision table — match the output, do exactly the action, nothing else

Output containsMeaningAction
Already up to date.Primary is already at the tip. Healthy no-op.Report ff tick: up to date (<sha>). Done.
Fast-forward / Updating <old>..<new>A real fast-forward landed.Report ff tick: fast-forwarded <old>..<new>. Done.
skipped — primary is on '<branch>'Primary is parked on another branch.Report the skip. Done — this is not an error, and you never switch branches to "fix" it.
Your local changes to the following files would be overwritten by merge:Uncommitted work is sitting in the primary.ALERT. Report the blocked tick plus the verbatim file list. Change nothing — no stash, no checkout, no reset. Done.
cannot pull with rebase / You have unstaged changesSame class: a dirty primary.ALERT exactly as above. Change nothing.
fatal: Not possible to fast-forward, aborting.The local branch has commits the remote does not — it has diverged.ALERT. Report that the primary has diverged and name the commit count (git -C "$PRIMARY" log --oneline <remote>/<integration-branch>..HEAD). Never rebase or merge to reconcile it. Done.
Could not resolve host / unable to access / Connection refusedTransient network.Report ff tick: network unreachable — retry next tick. Done. No action.
There is no tracking information / no such refBranch has no upstream, or the remote branch is gone.ALERT with the exact message. Change nothing. Done.
Anything elseUnknown state.STOP. Do not improvise. Report the command output verbatim and hand off to the operator.

Hard rules

  • Never resolve a block yourself. No git stash, reset, checkout -f, clean, rebase, merge, or push --force — ever, under any output. The uncommitted work in the primary belongs to a human; destroying it is far worse than a stale branch. Alert and stop.
  • Never touch worktrees. Agents are actively working in them. This lane's blast radius is exactly one directory: the primary checkout, and only when it is on <integration-branch>.
  • Never switch branches. A primary parked on another branch is a skip, not a problem to fix.
  • Never improvise a git command that is not in the tick block or the decision table. If the output matches no row, stop and report it verbatim.
  • Ticks are idempotent. An already-current primary is a no-op costing under a second, so never skip a tick because "it probably already ran" — the check is the point.

Scheduling

A loop lane: the operator starts it with /loop <interval> start and each firing is one tick. Cadence is the operator's dial; nothing about the behaviour changes with the interval. A few minutes to an hour all work — the tick is cheap, and the cost of a stale primary grows with how often new worktrees are cut.

Token discipline (caveman)

Load the caveman skill. One line per tick, nothing more:

  • ff tick: up to date (<sha>)
  • ff tick: fast-forwarded <old>..<new>
  • ff tick: skipped — primary on '<branch>'
  • ff tick: network unreachable — retry next tick
  • ff tick: BLOCKED — <one-line reason> followed by the verbatim git output (the only case where more than one line is correct).

Caveman compresses prose only — git commands, branch names, SHAs, and the blocked-file list stay byte-exact. Never paraphrase the git output on a block; the operator needs the literal file list.

Stop conditions

Primary up to date, fast-forwarded, or legitimately skipped → report the one-liner and end the tick. The loop re-fires on its interval. A BLOCKED tick does not stop the loop — keep reporting it each tick until the operator clears the primary, because a repeating alert is the signal that the work is still stranded there.

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.