ReddRadar
Agent skill
graphite-stacks
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.
Install this agent skill to your Project
npx add-skill https://github.com/outfitter-dev/agents/tree/main/plugins/gt/skills/stacks
Metadata
Additional technical details for this skill
- author
- outfitter
- version
- 1.0.0
- category
- version-control
SKILL.md
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
gtcommand 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
# 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
# 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"
ALWAYS:
- Use
gt createfor new branches - Use
gt modifyfor commits - Use
gt submitto push - Use
gt restackafter parent changes - Check
gt statuswhen uncertain
NEVER:
- Mix
git commit/push/rebasewithgtworkflows - Force push without understanding stack state
- Use
git rebase -i(breaks Graphite metadata)
Addressing Review Feedback
Single PR: Navigate to branch, modify directly
gt checkout target-branch
gt modify -acm "fix: address review comment"
gt submit
Multiple PRs in stack: Use absorb from top
gt top
git add .
gt absorb -a
gt submit --stack
Graphite routes changes to correct branches based on file history.
Reorganizing Stacks
# 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
# Current branch + downstack
gt submit
# Entire stack
gt submit --stack
# Non-interactive (automation)
gt submit --no-interactive
Stack Visualization
# JSON with parent relationships (preferred for scripts)
gt status
# Visual tree
gt ls
# Recent history
gt log
Sync and Maintenance
# 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 statusshows unexpected structure
See recovery.md for step-by-step recovery procedures.
- commands.md - Quick command reference
- recovery.md - Stack corruption recovery
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
outfitter-dev/agents
stack-feedback
Creates GitHub issues for problems discovered while using @outfitter/* packages. Use when finding bugs, missing features, unclear documentation, or improvement opportunities.
outfitter-dev/agents
stack-architecture
Design stack-based systems using @outfitter/* packages. Use when planning new projects, choosing packages, designing handler architecture, or when "architecture", "design", "structure", "plan handlers", or "error taxonomy" are mentioned.
outfitter-dev/agents
stack-templates
Templates for creating handlers, CLI commands, MCP tools, and daemon services following Outfitter Stack conventions. Use when scaffolding new components, creating handlers, adding commands, or when "create handler", "new command", "add tool", "scaffold", "template", or "daemon service" are mentioned.
outfitter-dev/agents
stack-audit
Scan codebase for Outfitter Stack adoption candidates. Identifies throw statements, console usage, hardcoded paths, and custom errors. Use when assessing adoption scope or checking readiness.
outfitter-dev/agents
stack-review
Audits code for Outfitter Stack compliance including Result types, error handling, logging patterns, and path safety. Use for pre-commit reviews, code quality checks, migration validation, or when "audit", "check compliance", "review stack", or "stack patterns" are mentioned.
outfitter-dev/agents
stack-patterns
Reference for Outfitter Stack patterns including Result types, Handler contract, Error taxonomy, and @outfitter/* package conventions. Use when learning the stack, looking up patterns, understanding packages, or when "Result", "Handler", "error taxonomy", "OutfitterError", "CLI output", "pagination", "MCP server", "MCP tool", "structured logging", "redaction", "test handler", "daemon", "IPC", or "@outfitter/*" are mentioned.
Didn't find tool you were looking for?