graphite-workflow
Use this skill when working with Graphite (gt) for stacked PRs, when the user mentions pull requests, Graphite, stacking, or gt commands. Ensures proper use of gt commands instead of raw git for stack-aware operations.
When & Why to Use This Skill
This Claude skill optimizes software development workflows by integrating Graphite (gt) for managing stacked pull requests. It ensures developers use stack-aware commands instead of standard git, automating the complex process of branch management, restacking, and multi-PR submissions to increase engineering velocity and code review efficiency.
Use Cases
- Managing complex feature developments by breaking them into a 'stack' of smaller, interdependent pull requests for faster and more granular code reviews.
- Updating an earlier PR in a stack and automatically restacking all subsequent descendant branches to maintain consistency without manual rebasing.
- Submitting an entire sequence of related pull requests to GitHub simultaneously using automated, non-interactive commands.
- Navigating through a hierarchy of branches using stack-aware navigation tools like 'gt up' and 'gt down' to maintain context within large projects.
- Synchronizing local stacks with the remote trunk while automatically cleaning up merged branches and rebasing active work.
| name | graphite-workflow |
|---|---|
| description | Use this skill when working with Graphite (gt) for stacked PRs, when the user mentions pull requests, Graphite, stacking, or gt commands. Ensures proper use of gt commands instead of raw git for stack-aware operations. |
Graphite Workflow Skill
This skill ensures correct usage of Graphite CLI (gt) for managing stacked PRs. When working in a Graphite-enabled workflow, always use gt commands instead of raw git commands for stack-aware operations.
When to Use
Apply this skill when:
- User mentions Graphite, pull requests, stacking, or
gt - Working on a feature that uses stacked PRs
- Managing branches in a stack
Critical Rule: gt vs git
| Instead of... | Use... | Why |
|---|---|---|
git commit |
gt create -a -m "message" |
Creates branch + commit + tracks in stack |
git commit --amend |
gt modify -a |
Amends AND auto-restacks descendants |
git push |
gt submit --no-interactive |
Pushes AND creates/updates PRs |
git checkout <branch> |
gt checkout <branch> |
Stack-aware checkout |
git pull / git rebase |
gt sync |
Syncs trunk AND rebases entire stack |
Core Commands Quick Reference
# Creating PRs in a stack
gt create -a -m "feat: description" # Stage all, create branch, commit
# Modifying existing PR
gt modify -a # Amend commit, auto-restack upstack
# Submitting to GitHub
gt submit --no-interactive # Current branch + downstack
gt submit --stack --no-interactive # Entire stack
# Navigation
gt up / gt down # Move within stack
gt top / gt bottom # Jump to ends of stack
gt checkout # Interactive picker
# Syncing
gt sync # Fetch trunk, rebase stack, cleanup merged
# Viewing
gt log # Visual stack graph
gt ls # Short list
The Stack Building Workflow
- Write code FIRST - Never create empty branches
- Stage changes -
git add . - Create branch -
gt create -a -m "message" - Repeat for each slice
- Submit stack -
gt submit --stack --no-interactive
When to Use Raw Git
These operations are fine with raw git:
git add- Staging filesgit status- Checking statusgit diff- Viewing changesgit log(for viewing history, not stack structure)
Handling Modifications
When changes are needed to an earlier PR in the stack:
gt checkout <branch-needing-changes>
# Make code changes
git add .
gt modify -a # Amend + auto-restack
gt submit --stack --no-interactive # Push updates
Conflict Resolution
# If conflict occurs during sync/restack:
# 1. Fix conflicts in editor
git add .
gt continue
# To abort:
gt abort