/sync

name: sync
description: >
  Update the current feature branch with the latest changes from its
  base branch (rebase by default, merge when asked).
  TRIGGER when the user says "sync with main", "update my branch",
  "rebase on main", "catch up with main", "pull in main", "bring
  this branch up to date", "merge main into this branch",
  "/nyann:sync". Trigger on "resolve conflicts" only when the user
  specifically ties it to syncing — otherwise that's a manual resolve.
  Do NOT trigger on "pull" alone (that's a different operation for
  updating main itself). Do NOT trigger on main/master/develop — those
  are long-lived branches and sync-skill refuses them. Do NOT trigger
  on commit / push / PR — those are separate skills.

sync

Wraps `bin/sync.sh`. Rebases (or merges) the current feature branch onto its base, after a clean-tree + branch-safety check.

1. Pre-flight (the script does these; your job is to interpret them)

• **Not a git repo** (exit 2) → tell the user; stop.
• **Detached HEAD / main / master / develop** (exit 2) → refuse with

a clear message; suggest switching to a feature branch first (`/nyann:branch` creates one).

• **Dirty working tree** (status=`dirty` in JSON) → stop and tell the

user to commit or stash first. Don't silently stash on their behalf — `git stash` is a footgun when the rebase also conflicts.

2. Choose strategy

Default to `rebase`. Use `merge` when:

• The user explicitly says "merge" (not "rebase").
• The profile's branching strategy is `gitflow` and the target base

is `develop`/`main` (shared long-lived branches — some teams ban rebase on these).

• The branch has already been pushed to a shared remote and has open

PRs (rebasing rewrites history; merges don't).

If unclear, **you MUST call the `AskUserQuestion` tool** (not plain text):

{
  "questions": [
    {
      "question": "How should upstream changes be integrated?",
      "header": "Strategy",
      "multiSelect": false,
      "options": [
        { "label": "Rebase (Recommended)", "description": "Keeps history linear; replays your commits on top of base" },
        { "label": "Merge", "description": "Preserves original commits; adds a merge commit" }
      ]
    }
  ]
}

3. Resolve base

`bin/sync.sh` picks base via: `--base` > `@{upstream}` > `origin/HEAD` > `main`. Override only when the user explicitly names a different target ("sync against develop"). Normally trust the resolution.

4. Invoke

bin/sync.sh --target <cwd> [--strategy rebase|merge] [--base <branch>] [--dry-run]

`--dry-run` reports what would happen without mutating. Use it when the user is cautious or you want to show them the ahead/behind count first.

5. Interpret the output JSON

| status | meaning | what to tell the user | |---|---|---| | `up-to-date` | behind == 0 | "Already up to date with `<base>`." No action needed. | | `synced` | operation completed | "Synced via `<strategy>`. Now `<ahead>` ahead, 0 behind." | | `dirty` | working tree had uncommitted changes | "Working tree has uncommitted changes. Commit or stash first." | | `skipped` | base not found locally or on origin | "Couldn't find `<base>` locally or on origin. Check the branch name." | | `conflicts` | rebase/merge halted mid-operation | See §6 — this is the tricky case. |

6. When conflicts happen

The script stops and leaves the working tree in a rebase-in-progress or merge-in-progress state. Do NOT call sync again — the script doesn't know how to resume.

Read the `conflicts[]` array from the JSON. For each file, offer to help resolve it (read the file, show conflict markers, ask the user which side to keep). When the user is done:

• **For rebase**: `git add <resolved-files>` then `git rebase --continue`.
• **For merge**: `git add <resolved-files>` then

`git -c user.email=... -c user.name=... commit --no-edit` to finalize.

If the user wants to bail: `git rebase --abort` or `git merge --abort`. Either returns the working tree to its pre-sync state.

When to hand off

• "Now push and PR" → `pr` skill.
• "The conflicts are too messy, just abort" → run `git rebase --abort`

/ `git merge --abort` yourself and confirm.

• "Update main itself" → out of scope; tell the user `git checkout main

&& git pull` handles that.