handoff-push

handoff-push

Park current working state and session context on a handoff/<topic> branch and push it. The receiving-end skill is handoff-pull.

Pre-flight

• You must be inside a git repo with a remote named origin. If not, stop and tell the user.
• If the working tree is clean AND the current branch is already handoff/<something>, the user probably meant to re-snapshot the existing handoff — keep the topic name and proceed.

Steps

1. Pick the topic name. Default rule: take the current branch, strip common prefixes (can/, fix/, feat/, refactor/, chore/, and any leading ticket prefix like pla-1188-). Propose the result to the user and let them override in one line. Example: can/pla-1188-domainpurchasesaga-createcloudflarezone-not-idempotent → pla-1188-cf-zone-idempotent.

2. Preserve uncommitted work on the CURRENT branch first. Do this before switching, so the user's checkpoint stays on their feature branch:

   if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
     git add -A
     git commit -m "wip: handoff snapshot"
   fi
   

3. Create or fast-forward the handoff branch from current HEAD:

   git checkout -B handoff/<topic>
   

4. Write .handoff/notes.md. Brief the reader like a colleague walking in cold. Sections (use this exact structure):

   # Handoff: <topic>
   
   **Parent branch:** <original feature branch name>
   **Last handoff:** <ISO timestamp>
   
   ## Current status
   
   <2–4 sentences. What's done, what's pending, what's broken. Reference file paths + line numbers where helpful.>
   
   ## Next steps
   
   1. <Concrete action — include the command if there is one>
   2. ...
   
   ## Related
   
   - PR: <URL or "none yet">
   - Linear: <ticket ID and URL>
   - Other handoff branches: <if this topic has siblings, list them>
   
   ## Key decisions this session
   
   - <Things a cold reader wouldn't learn from git log — tradeoffs, rejected alternatives, why-not-X>
   

   Write this based on the current conversation and git state. Specific file paths + exact commands beat vague summaries.

5. Commit and push:

   mkdir -p .handoff
   # (write notes.md)
   git add .handoff/notes.md
   git commit -m "handoff: <topic>"
   git push -u origin handoff/<topic>
   

6. Return to the original feature branch so the user can keep working if they change their mind:

   git checkout <original feature branch>
   

7. Print pickup instructions exactly:

   Handoff pushed: handoff/<topic>
   
   On the other machine:
     git fetch && git checkout handoff/<topic>
     claude
     # then ask Claude to pick it up via the `handoff-pull` skill
   

Invariants

• .handoff/ directory only exists on handoff/* branches. Never commit it to main or feature branches.
• Handoff branches are disposable scratch. They are never merged. When the topic is done, tell the user to clean up:

  git push origin --delete handoff/<topic>
  git branch -D handoff/<topic>
  

• Do not force-push a handoff branch unless the user explicitly says to.

Writing good notes.md

• Include absolute paths or repo-relative paths with line numbers: internal/services/domain/purchase.go:566.
• Include the exact command the next session should run next (e.g., go test ./internal/services/domain/...).
• Don't restate what git log already shows. Focus on non-obvious context: why a decision was made, what was ruled out, what the next human should NOT do.
• Link every PR, Linear ticket, and related handoff branch by URL.

What this skill does NOT do

• Does not touch env vars, auth tokens, kubeconfig, or memory directories. Those live outside git; manage separately.
• Does not open a pull request for the handoff branch.
• Does not rebase / squash / rewrite history on the feature branch.