agentleFS
joris887joris887/exosuit/.claude/skills/merge-up/SKILL.md

merge-up

Skill9 starsChanged 3 months agoMITView on GitHub

Use when the user is inside a parallel stream (worktree branch) and wants to merge that branch's committed work into the parent branch it was created from, then bring the stream back up to date with the parent. True merge (keeps individual commits); prompts before pushing the parent. Pairs with /parallel-work, which records the parent in git config (branch.<name>.exosuitParent), and with /merge-down (the inverse direction).

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 7

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If B is HEAD (detached), STOP — tell the user to check out a branch.

    line 28
  2. Very specific:

    If empty, fall back to stripping the last -<suffix> (e.g.

    line 33
  3. Distinctive:

    If still unresolved or ambiguous, ASK the user which branch is the parent.

    line 35
  4. Very specific:

    If P == B or P doesn't exist, STOP and report.

    line 36
  5. Distinctive:

    If the current worktree is dirty, STOP: the skill merges committed work only.

    line 43
  6. Very specific:

    If P is not checked out in any worktree, STOP and tell the user to check it out in a worktree first (the merge needs a working tree to run …

    line 50
  7. Very specific:

    Verify the parent worktree is clean: git -C "$PDIR" status --porcelain must be empty.

    line 52
  8. Distinctive:

    Run the merge in the parent's worktree:

    line 57
  9. Very specific:

    ASK the user (AskUserQuestion): "Push $P to origin now?" — Yes / No.

    line 70
  10. Very specific:

    If yes: git -C "$PDIR" push origin "$P" (never --force.

    line 71
  11. Distinctive:

    If no: leave it local.

    line 73

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

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

merge-up

Merge the current stream's branch into the parent it was created from, then fast-forward the current branch back up to the parent. Safe across worktrees: the parent is usually checked out in another worktree, so the merge runs there via git -C rather than checking the parent out here (git forbids that).

Step 1 — Identify branches

B="$(git rev-parse --abbrev-ref HEAD)"
echo "current branch: $B"
  • If B is HEAD (detached), STOP — tell the user to check out a branch.
  • Resolve the parent P:
    P="$(git config "branch.$B.exosuitParent" || true)"
    • If empty, fall back to stripping the last -<suffix> (e.g. sprint-3-a → sprint-3) and verify it exists with git show-ref --verify --quiet refs/heads/<cand>.
    • If still unresolved or ambiguous, ASK the user which branch is the parent.
  • If P == B or P doesn't exist, STOP and report.

Step 2 — Pre-flight cleanliness (both worktrees)

git status --porcelain            # current worktree — must be empty
  • If the current worktree is dirty, STOP: the skill merges committed work only. Tell the user to commit or stash first.
  • Locate the parent's worktree dir:
    git worktree list --porcelain
    Find the entry whose branch is refs/heads/$P; call its path PDIR.
    • If P is not checked out in any worktree, STOP and tell the user to check it out in a worktree first (the merge needs a working tree to run in).
  • Verify the parent worktree is clean: git -C "$PDIR" status --porcelain must be empty. If dirty, STOP and report which worktree/path needs attention.

Step 3 — Merge current branch into parent (true merge)

Run the merge in the parent's worktree:

git -C "$PDIR" merge "$B"
  • This keeps B's individual commits (fast-forwards when possible).
  • On "Already up to date." → nothing to merge; tell the user and SKIP to Step 5.
  • On conflict: run git -C "$PDIR" merge --abort, then STOP and report the conflicting files. Offer to help resolve, but do NOT leave the parent worktree in a half-merged state without telling the user.
  • On success, show git -C "$PDIR" log --oneline -3.

Step 4 — Offer to push the parent

ASK the user (AskUserQuestion): "Push $P to origin now?" — Yes / No.

  • If yes: git -C "$PDIR" push origin "$P" (never --force; if rejected, report and let the user decide — likely needs a pull/merge of origin first).
  • If no: leave it local.
  • Note: if P is the repository's default branch, do NOT push — the framework's git rules require all changes to the default branch to go through a PR (/sprint-end handles that). Skip this step and say so.

Step 5 — Sync current branch back up to parent

Back in the current worktree:

git merge "$P"          # fast-forward: B now contains everything on P
  • This should fast-forward cleanly (P already contains B's commits plus anything else that landed on P). If it somehow reports a conflict, STOP and report.

Step 6 — Report

Show the final state so the user can see both branches aligned:

echo "$B:"; git log --oneline -3
echo "$P:"; git -C "$PDIR" log --oneline -3
git status --short

Summarize: what merged into $P, whether it was pushed, and that $B is now up to date with $P and ready for continued work.

Notes

  • True merge by design so the stream branch stays alive and Step 5 is a clean fast-forward. Do not switch to squash/rebase without re-checking with the user.
  • The parent worktree's checked-out branch tip moves as a result of this skill — that's intended (it IS the merge). Anyone else working in that worktree should be clean before you run this.
  • Typical cadence with several streams: each stream runs /merge-up when a story completes, then every still-active stream runs /merge-down to pick up the integrated result.

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.