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

merge-down

Skill9 starsChanged 3 months agoMITView on GitHub

Use when the user is inside a parallel stream (worktree branch) and wants to bring that branch up to date with the LATEST of its parent branch — typically after one or more sibling streams have merged their work up into the parent (via /merge-up). Pulls the parent's accumulated commits down into the current branch with a true merge. Inverse of /merge-up; the parent is recorded by /parallel-work in git config (branch.<name>.exosuitParent). Read-only on the parent — safe to run while the parent worktree is busy.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 4 are distinctive, and 6 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.

  • 6

    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 40
  2. Very specific:

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

    line 45
  3. Distinctive:

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

    line 47
  4. Very specific:

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

    line 48
  5. Distinctive:

    If dirty, STOP: merging the parent in could collide with uncommitted work.

    line 55
  6. Very specific:

    Only needed if parent commits were pushed from elsewhere (local /merge-ups already updated the shared parent ref).

    line 62
  7. Very specific:

    If origin/$P is ahead of local $P (right-count > 0), the canonical latest is on the remote.

    line 71
  8. Very specific:

    Fast-forward: when the current branch has no commits of its own ahead of $P.

    line 84
  9. Distinctive:

    Do not leave the worktree half-merged without telling the user which state it's in.

    line 91
  10. Distinctive:

    Read-only on the parent: this skill never moves the parent's branch tip and never touches the parent worktree's working files — only the …

    line 112

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

Bring the current stream's branch up to date with the parent it was created from. Use it after a round of /merge-ups have landed sibling streams' work on the parent: each sibling still only has its OWN commits, so run this in each stream to integrate everyone else's merged work.

This is the complement of /merge-up:

  • /merge-up — merge THIS branch into the parent (publish your work upward).
  • /merge-down — merge the parent into this branch (pull everyone's work downward).

Because all worktrees of a repository share one object store and one set of branch refs, the parent ref already reflects every local /merge-up — no network fetch is needed for local merges. A fetch is only relevant if merges were pushed from another machine (Step 3 handles that optionally). This skill never writes to the parent's working tree, so it is safe to run even while the parent worktree is in use.

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: 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 (current worktree only)

git status --porcelain            # current worktree — must be empty
  • If dirty, STOP: merging the parent in could collide with uncommitted work. Tell the user to commit or git stash first, then re-run.
  • Unlike /merge-up, the parent worktree does not need to be clean — this skill only reads the parent branch ref; it never commits into the parent's working tree.

Step 3 — Optionally refresh the parent from origin

Only needed if parent commits were pushed from elsewhere (local /merge-ups already updated the shared parent ref). Best-effort; skip silently if there is no remote.

git fetch origin "$P" 2>/dev/null || true
# Is origin/P ahead of local P?
git rev-list --left-right --count "$P...origin/$P" 2>/dev/null || true
  • If origin/$P is ahead of local $P (right-count > 0), the canonical latest is on the remote. Note: local $P is usually checked out in the primary worktree, so it cannot be fast-forwarded from here. In that case ASK the user whether to merge origin/$P instead of local $P in Step 4 (substitute the ref). For the common all-local workflow, local $P already holds every merged sibling — proceed with it.

Step 4 — Merge the parent into the current branch (true merge)

git merge "$P"          # or origin/$P if Step 3 selected it
  • "Already up to date." → the current branch already contains everything on the parent. Report and SKIP to Step 5.
  • Fast-forward when the current branch has no commits of its own ahead of $P.
  • On conflict (the parent's merged work overlaps this branch's work): do NOT auto-abort — the user usually wants to integrate. STOP and:
    • Show the conflicting files: git diff --name-only --diff-filter=U.
    • Offer two paths: (a) help resolve the conflicts now, then git add <files> && git commit to complete the merge; or (b) back out with git merge --abort to return to the pre-merge state.
    • Do not leave the worktree half-merged without telling the user which state it's in.
  • On success, show git log --oneline -5.

Step 5 — Report

echo "$B now contains $P:"; git log --oneline -5
git status --short
git rev-list --left-right --count "$P...$B"   # left = parent-only (should be 0), right = this branch ahead

Summarize: the current branch is now up to date with $P (it contains every sibling's merged work), and is ready for continued work or a later /merge-up (whose Step 5 sync stays a clean fast-forward).

Notes

  • True merge by design, matching /merge-up, so history is preserved and a later /merge-up of this branch fast-forwards cleanly.
  • Typical cadence: run all the /merge-ups for the round first, then run /merge-down in each still-active stream to redistribute the integrated parent to every branch.
  • Read-only on the parent: this skill never moves the parent's branch tip and never touches the parent worktree's working files — only the current branch advances.

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.