graphite_skill

Overview

This skill explains how to navigate and restack Git branch stacks using Graphite (gt). It focuses on safe, non-interactive workflows for moving between branches, maintaining local stack integrity, and syncing with remotes while avoiding forbidden commands. Follow the guidance to keep Graphite's internal metadata consistent and to recover from common mistakes.

How this skill works

The skill covers gt navigation commands (up, down, prev, next, top, bottom, ls) and stack maintenance commands (restack, get, sync). It recommends using gt-based commit and branch operations (create, modify, move, split) so Graphite can track changes and automatically restack descendants. For operations that require human input or hit conflicts, the agent stops and prompts the user to resolve them manually.

When to use it

• Moving between branches in a stacked workflow (use gt up/down/prev/next/top/bottom).
• Rebasing local branches to ensure parent commits are present (gt restack).
• Syncing branches or the entire stack from remote (gt get or gt sync).
• Creating or amending commits while preserving Graphite metadata (gt create, gt modify).
• When avoiding interactive selectors: prefer explicit flags like --onto for gt move.

Best practices

• Never run gt ss, gt submit, or gt squash — these are explicitly prohibited.
• Prefer gt commands over native git commands to preserve Graphite metadata and trigger automatic restacking.
• Provide explicit branch names and flags to avoid interactive prompts; stop and ask the user if interaction is required.
• If a restack/move hits conflicts, resolve files, stage with gt add -A, then run gt continue (do not use git rebase --continue).
• After completing restack operations, run tests to verify the merged state is stable.

Example use cases

• Create a feature stacked on the current branch: gt create my-feature (use /gt-create workflow).
• Move the current branch onto a new base non-interactively: gt move --onto target-branch.
• Recover from a misplaced commit by creating a new branch with gt create, resetting, and restacking.
• Refresh local stack after remote changes: gt get <branch> or gt sync for all branches.
• Fix a conflict during restack: resolve files, gt add -A, then gt continue to resume.