|
| 1 | +--- |
| 2 | +name: sync-branch-to-develop |
| 3 | +description: Use when finishing work on a feature branch and wanting to promote it to develop (or another integration branch) while staying on the original branch. Handles commit, push, merge, push develop, and return. |
| 4 | +--- |
| 5 | + |
| 6 | +# Sync branch to develop |
| 7 | + |
| 8 | +## Overview |
| 9 | + |
| 10 | +Promote the current branch to the `develop` integration branch and return, so the user keeps working where they were. The sequence: commit any pending work, push the current branch, fast-forward-update develop, merge the branch into develop, push develop, check out the original branch. |
| 11 | + |
| 12 | +Users end where they started. Never leave them on `develop`. |
| 13 | + |
| 14 | +## When to use |
| 15 | + |
| 16 | +- User says: "sync to develop", "push and merge to develop", "promote this branch to staging", "land this on develop", or equivalent. |
| 17 | +- A feature branch is ready to land on the integration branch while work continues. |
| 18 | + |
| 19 | +## When NOT to use |
| 20 | + |
| 21 | +- Current branch IS `develop`, `main`, or another protected trunk → refuse, explain why. |
| 22 | +- Target is not `develop` → confirm the target branch name with the user before proceeding. |
| 23 | +- User wants to merge via PR, not directly → skip this skill and open a PR instead. |
| 24 | + |
| 25 | +## Workflow |
| 26 | + |
| 27 | +**Before step 1:** capture the starting branch with `git rev-parse --abbrev-ref HEAD`. You return here at the end no matter what — including on failure. |
| 28 | + |
| 29 | +### 1. Commit pending work (skip if clean) |
| 30 | + |
| 31 | +- Run `git status --porcelain`. Empty → skip this step. |
| 32 | +- Read all pending changes: `git status` + `git diff` (staged + unstaged). |
| 33 | +- Look at recent commit history to match the repo's style: `git log --oneline -10`. |
| 34 | +- Draft the commit message following the rules in "Writing the commit message" below. |
| 35 | +- Show the user the diff summary **and** the drafted message. Commit only after they approve (or implicitly approve by telling you to proceed). |
| 36 | +- Stage specific files by name. Never `git add -A` or `git add .` (risks staging secrets, unrelated files). |
| 37 | +- Refuse to stage files that likely contain secrets (`.env`, `credentials.json`, private keys). Warn and skip. |
| 38 | +- Use a HEREDOC to pass the commit message so multi-line formatting is preserved (see example below). |
| 39 | +- If a pre-commit hook fails: surface the error, fix the underlying issue, re-stage, and create a **new** commit. Never `--amend` (the failed commit didn't happen), never `--no-verify`. |
| 40 | + |
| 41 | +#### Writing the commit message |
| 42 | + |
| 43 | +Match the repo's existing style (check `git log --oneline -10` first). General rules: |
| 44 | + |
| 45 | +- **Subject line:** one line, imperative mood, ≤70 characters, no trailing period. Match the pattern of recent commits. |
| 46 | +- **Body (optional, only if helpful):** 1–2 sentences explaining *why* the change was made, not what it does. Wrap at ~72 chars. |
| 47 | +- **Verb choice reflects nature:** "Add" for wholly new features, "Update" for enhancements, "Fix" for bugs, "Refactor" for internal restructuring, "Remove" for deletions, "Docs" for documentation-only changes. |
| 48 | +- **No filler:** don't reference the task/PR number unless the repo convention does it; don't narrate ("this commit…"); don't list every file. |
| 49 | +- **No Co-Authored-By trailer** — the commit content may not have been authored by Claude; only add it if the user explicitly asks. |
| 50 | + |
| 51 | +Commit via HEREDOC (preserves formatting): |
| 52 | + |
| 53 | +```bash |
| 54 | +git commit -m "$(cat <<'EOF' |
| 55 | +Subject line here |
| 56 | +
|
| 57 | +Optional short body explaining why. |
| 58 | +EOF |
| 59 | +)" |
| 60 | +``` |
| 61 | + |
| 62 | +### 2. Push the current branch |
| 63 | + |
| 64 | +- First push: `git push -u origin <branch>` |
| 65 | +- Otherwise: `git push` |
| 66 | +- If push is rejected (non-fast-forward, protected branch, etc.) — stop and report. Never force-push without an explicit ask. |
| 67 | + |
| 68 | +### 3. Update develop locally |
| 69 | + |
| 70 | +- `git fetch origin` |
| 71 | +- `git checkout develop` |
| 72 | +- `git pull --ff-only origin develop` |
| 73 | +- If the fast-forward fails (local develop has diverged), stop and ask the user how to proceed. Do not `reset --hard` or force-pull. |
| 74 | + |
| 75 | +### 4. Merge the branch into develop |
| 76 | + |
| 77 | +- `git merge --no-ff <branch>` — `--no-ff` keeps the feature branch identifiable in history. Only omit if the user prefers fast-forward merges. |
| 78 | +- On conflict: stop, list conflicted files, ask the user. Never use `-X ours/theirs`, `--strategy=ours`, or force-resolve silently. |
| 79 | + |
| 80 | +### 5. Push develop |
| 81 | + |
| 82 | +- `git push origin develop` |
| 83 | +- On rejection (protected branch, diverged remote), stop and report. Never force-push develop. |
| 84 | + |
| 85 | +### 6. Return to the original branch |
| 86 | + |
| 87 | +- `git checkout <original-branch>` |
| 88 | +- Run `git status` to confirm state. Report to user: what landed on develop, which commit SHA, remote status. |
| 89 | + |
| 90 | +## Quick reference |
| 91 | + |
| 92 | +| Step | Command | Skip when | |
| 93 | +|------|---------|-----------| |
| 94 | +| Commit | `git add <files> && git commit -m "msg"` | Working tree clean | |
| 95 | +| Push branch | `git push [-u origin <branch>]` | Never | |
| 96 | +| Fetch | `git fetch origin` | Never | |
| 97 | +| Update develop | `git checkout develop && git pull --ff-only origin develop` | Never | |
| 98 | +| Merge | `git merge --no-ff <branch>` | Never | |
| 99 | +| Push develop | `git push origin develop` | Never | |
| 100 | +| Return | `git checkout <original-branch>` | Never | |
| 101 | + |
| 102 | +## Common mistakes |
| 103 | + |
| 104 | +- **Committing without review.** Always show the diff summary and the drafted message first, then wait for approval. |
| 105 | +- **`git add -A` / `git add .`** — stage specific files by name. |
| 106 | +- **Vague commit messages** ("updates", "fixes things") — check `git log` for the repo's voice and write a message that says *what* changed at a conceptual level and *why*. |
| 107 | +- **Adding a Co-Authored-By trailer by default** — the commit contents may not have been written by Claude. Omit unless the user asks for it. |
| 108 | +- **Bypassing hook failures with `--no-verify`** — fix the underlying issue instead. |
| 109 | +- **`git commit --amend` after a hook failure** — the failed commit didn't happen; amend would modify the previous real commit. Create a new commit instead. |
| 110 | +- **`git reset --hard` or force-pull on develop divergence** — stop and ask. |
| 111 | +- **Silent conflict resolution** — surface conflicts, don't auto-pick sides. |
| 112 | +- **Force-pushing develop or origin branch** — never, without explicit user instruction. |
| 113 | +- **Forgetting to return** — the final `checkout <original-branch>` is mandatory. |
| 114 | +- **Running on main** — refuse. `main → develop` is not this workflow. |
| 115 | + |
| 116 | +## Red flags — STOP and ask |
| 117 | + |
| 118 | +- User rejects the drafted commit message → re-draft or ask for theirs; do not commit |
| 119 | +- Pre-commit / pre-push hook failure |
| 120 | +- `git pull --ff-only origin develop` fails (diverged) |
| 121 | +- Merge conflict |
| 122 | +- Push rejected (any branch) |
| 123 | +- Current branch is `develop`, `main`, or another trunk |
| 124 | +- Staged diff includes a file that looks like it holds secrets (`.env*`, `*.pem`, `credentials*`) |
| 125 | + |
| 126 | +On any red flag: stop the workflow, report state, checkout back to the starting branch if you left it, ask the user. |
0 commit comments