graphite-stacks

Original：🇺🇸 English

Translated

This skill should be used when the user asks to "create a stack", "submit stacked PRs", "gt submit", "gt create", "reorganize branches", "fix stack corruption", or mentions Graphite, stacked PRs, gt commands, or trunk-based development workflows.

2installs

Sourceoutfitter-dev/agents

Added on2026-02-07

NPX Install

npx skill4agent add outfitter-dev/agents graphite-stacks

SKILL.md Content

View Translation Comparison →

Graphite Stacks

Trunk-based development with stacked PRs using Graphite CLI.

<when_to_use>

Creating or managing branch stacks
Submitting stacked PRs
Reorganizing branch relationships
Addressing PR feedback across a stack
Recovering from stack corruption
Any
```
gt
```
command usage

</when_to_use>

Core Principle

Use
gt
commands exclusively. Mixing

git

and

gt

causes sync issues and divergent stacks. The only exception:

git add

for staging (or use

-a

flags).

This, Not That

Task	This	Not That
Create branch	`gt create 'name' -am "msg"`	`git checkout -b name`
Commit changes	`gt modify -acm "msg"`	`git commit -m "msg"`
Push to remote	`gt submit`	`git push`
Rebase stack	`gt restack`	`git rebase`
View stack	`gt status` or `gt ls`	`git log --graph`
Switch branches	`gt checkout`	`git checkout`
Amend commit	`gt modify -a`	`git commit --amend`
Multi-PR feedback	`gt top && gt absorb -a`	Cherry-pick commits manually

Stack Lifecycle

Create stack → Implement features → Submit PRs → Address feedback → Merge
     │              │                  │               │            │
     ▼              ▼                  ▼               ▼            ▼
 gt create     gt modify -acm     gt submit      gt absorb     gt sync

Creating Stacks

bash

# New branch with staged changes
gt create 'feature/step-1' -am "feat: first step"

# Continue stacking
gt create 'feature/step-2' -am "feat: second step"
gt create 'feature/step-3' -am "feat: third step"

# Insert branch between current and child
gt create 'feature/step-1.5' --insert -am "feat: inserted step"

Navigation

Command	Action
`gt up`	Move up the stack (toward children)
`gt down`	Move down the stack (toward parent)
`gt top`	Jump to stack top
`gt bottom`	Jump to stack bottom
`gt checkout`	Interactive branch picker

Modifying Branches

bash

# Amend current branch (stages all)
gt modify -a

# New commit within same branch
gt modify -acm "fix: address review feedback"

# Commit to a different branch in the stack
git add path/to/file.ts
gt modify --into target-branch -m "feat: add file"

<rules>

ALWAYS:

Use
```
gt create
```
for new branches
Use
```
gt modify
```
for commits
Use
```
gt submit
```
to push
Use
```
gt restack
```
after parent changes
Check
```
gt status
```
when uncertain

NEVER:

Mix
```
git commit/push/rebase
```
with
```
gt
```
workflows
Force push without understanding stack state
Use
```
git rebase -i
```
(breaks Graphite metadata)

</rules>

Addressing Review Feedback

Single PR: Navigate to branch, modify directly

bash

gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit

Multiple PRs in stack: Use absorb from top

bash

gt top
git add .
gt absorb -a
gt submit --stack

Graphite routes changes to correct branches based on file history.

Reorganizing Stacks

bash

# Move branch to different parent
gt move --onto new-parent

# Move specific branch
gt move --source branch-name --onto target

# After reorganization
gt restack

Submitting

bash

# Current branch + downstack
gt submit

# Entire stack
gt submit --stack

# Non-interactive (automation)
gt submit --no-interactive

Stack Visualization

bash

# JSON with parent relationships (preferred for scripts)
gt status

# Visual tree
gt ls

# Recent history
gt log

Sync and Maintenance

bash

# Pull trunk, rebase stacks, clean merged
gt sync

# Rebase branches onto updated parents
gt restack

# Undo last gt operation
gt undo

When Things Go Wrong

Stack corruption symptoms:

Branches appear as siblings instead of parent-child
PRs contain wrong files
```
gt status
```
shows unexpected structure

See recovery.md for step-by-step recovery procedures.

commands.md - Quick command reference
recovery.md - Stack corruption recovery

</references>

graphite-stacks

NPX Install

Tags

SKILL.md Content

Graphite Stacks

Core Principle

This, Not That

Stack Lifecycle

Creating Stacks

Navigation

Modifying Branches

Addressing Review Feedback

Reorganizing Stacks

Submitting

Stack Visualization

Sync and Maintenance

When Things Go Wrong