Agent-Skills.md

Agent Skills: Use Graphite - Stacked PRs

Manage stacked PRs with Graphite CLI (gt) instead of git push/gh pr create. Auto-detects Graphite repos and blocks conflicting commands with helpful alternatives. Use when: (1) About to run git push or gh pr create in a Graphite repo, (2) Creating a new branch for a feature, (3) Submitting code for review, (4) Large changes that should be split into reviewable chunks, (5) Hook blocks your git command and suggests gt equivalent. NOT for: repos not initialized with Graphite, git add/commit/status/log. Triggers: git push blocked, gh pr create blocked, create branch, submit PR, stacked PRs, split large PR, gt create, gt submit, graphite workflow.

UncategorizedID: LukasStrickler/ai-dev-atelier/use-graphite

Repository

LukasStrickler/ai-dev-atelier
LukasStricklerLicense: NOASSERTION

Skill Files

Browse the full folder contents for use-graphite.

Download Skill

Loading file tree…

skills/use-graphite/SKILL.md

Skill Metadata

Name
use-graphite
Description
"Manage stacked PRs with Graphite CLI (gt) instead of git push/gh pr create. Auto-detects Graphite repos and blocks conflicting commands with helpful alternatives. Use when: (1) About to run git push or gh pr create in a Graphite repo, (2) Creating a new branch for a feature, (3) Submitting code for review, (4) Large changes that should be split into reviewable chunks, (5) Hook blocks your git command and suggests gt equivalent. NOT for: repos not initialized with Graphite, git add/commit/status/log. Triggers: git push blocked, gh pr create blocked, create branch, submit PR, stacked PRs, split large PR, gt create, gt submit, graphite workflow."

Use Graphite - Stacked PRs

Graphite enables stacked PRs - chains of dependent PRs that build on each other. Essential for large changes that would be overwhelming as single PRs.

Assess Current State First

Always run these commands to understand where you are:

bash skills/use-graphite/scripts/graphite-detect.sh   # Is Graphite active?
gt log short                                           # Current stack structure
git status                                             # Uncommitted changes?

Interpret the output:

| gt log short shows | You are | Next action | |---------------------|---------|-------------| | main only (no branches) | Not in a stack | gt create <branch> to start | | Branch with ← marker | On that branch in stack | Continue work, then gt submit | | Multiple branches in tree | Mid-stack | Check which branch, continue or gt checkout | | (merged) on parent | Parent merged | gt sync to update | | (changes requested) | Review feedback pending | Address feedback, commit, gt submit |

If you have uncommitted changes:

  1. Commit them first: git add . && git commit -m "..."
  2. Then submit: gt submit or gt submit --stack

If unsure which branch you're on: git branch --show-current

Quick Start

First, check if Graphite is active:

bash skills/use-graphite/scripts/graphite-detect.sh
  • enabled: true → Use gt commands for branch/PR operations
  • enabled: false → Use standard git/gh, this skill does not apply

Core Workflow

Single PR

# 1. Develop and test FIRST (on current branch or main)
# make changes
# verify locally (run your project's test/lint/build commands)

# 2. THEN create branch and commit verified code
gt create my-feature
git add . && git commit -m "feat: add feature"
gt submit                       # CI should pass (you verified locally)

Stacked PRs (Large Changes)

# Step 1: Develop and verify schema changes
# make schema changes, verify locally FIRST
gt create step-1-schema
git add . && git commit -m "feat(db): add schema"

# Step 2: Develop and verify API changes (on top of step-1)
# make API changes, verify locally FIRST
gt create step-2-api
git add . && git commit -m "feat(api): add endpoints"

# Step 3: Develop and verify UI changes (on top of step-2)
# make UI changes, verify locally FIRST
gt create step-3-ui
git add . && git commit -m "feat(ui): add panel"

# Submit entire stack (all layers verified)
gt submit --stack

Key pattern: Each layer follows develop → test → verify → gt create → commit. Only submit when ALL layers are verified locally.

CRITICAL: CI Must Pass

Verify BEFORE creating branches and committing.

Check your project for verification commands (look for package.json scripts, Makefile targets, Cargo.toml, pyproject.toml, CI config, or README). Run tests, type checks, linting, and build locally before submitting.

WRONG workflow (commit-and-pray):
1. gt create feature
2. Make changes
3. Commit and gt submit → CI fails
4. Fix → gt submit → CI fails again
5. Repeat 5 times...
Result: 5 failed CI runs, broken commit history

CORRECT workflow (verify-then-commit):
1. Make changes
2. Run tests/lint/build LOCALLY
3. Fix issues until green
4. gt create feature
5. Commit verified code
6. gt submit → CI passes
Result: 1 clean submission

Rule: If local tests fail, you're not ready to commit. Fix first, verify, then create branch and commit.

When to Stack

| Scenario | Recommendation | |----------|----------------| | Bug fix (< 100 lines) | Single PR | | Feature (200-500 lines) | 2-3 stacked PRs | | Large feature (500+ lines) | Always stack | | Refactor + feature | Stack: refactor first | | DB migration + code | Stack: migration first |

DO: Best Practices

| Practice | Why | |----------|-----| | Test before submit | CI failures waste everyone's time | | 1 logical change per PR | Easy to review, easy to revert | | Stack by dependency | schema → API → UI, not random splits | | Keep stacks shallow (3-5 PRs) | Deep stacks are hard to manage | | Sync daily (gt sync) | Avoid painful merge conflicts | | Use gt modify -c | Not git commit --amend in tracked branches |

DON'T: Common Mistakes

| Mistake | Problem | Fix | |---------|---------|-----| | Submit without testing | CI fails, blocks review | Always run tests locally first | | Split randomly | PRs don't make sense alone | Split by logical dependency | | 10-PR stacks | Unmergeable, conflicts pile up | Max 3-5 PRs, start new stack | | Never sync | Conflicts grow over time | gt sync daily | | Use git rebase | Breaks Graphite tracking | Use gt restack instead | | Use git push | Bypasses stack management | Use gt submit | | Tiny PRs for simple features | Overhead without benefit | Single PR for <100 lines |

Command Translation

| Instead of (blocked) | Use (Graphite) | |---------------------|----------------| | git checkout -b feature | gt create feature | | git push | gt submit | | gh pr create | gt submit | | git rebase main | gt restack | | git commit --amend | gt modify -c |

What Graphite Does NOT Replace

Keep using these normally:

  • git add, git commit - staging and committing
  • git status, git log, git diff - inspection
  • git stash, git checkout <branch> - switching, stashing

Updating a Stack

After review feedback on an earlier PR:

gt checkout step-1-schema
# make changes, TEST LOCALLY
git add . && git commit -m "fix: address review feedback"
gt restack                      # Update dependent branches
gt submit --stack               # Push entire stack

Resuming Work (After Context Loss)

If you're continuing work and unsure of the state:

# 1. Check current state
gt log short                    # See full stack structure
git status                      # Any uncommitted changes?
git log --oneline -3            # Recent commits

# 2. Common scenarios:

| Situation | What to do | |-----------|------------| | Stack exists, on correct branch | Continue work, commit, gt submit | | Stack exists, wrong branch | gt checkout <branch-name> | | Changes not pushed | gt submit (single) or gt submit --stack (all) | | Need to add to existing stack | gt create <new-branch> (adds on top of current) | | Stack has merge conflicts | gt sync then resolve conflicts | | PRs exist but out of date | gt sync && gt restack && gt submit --stack |

CRITICAL: After Submit - Validate PR Description

gt submit creates PRs in draft mode with empty descriptions. You MUST fill them.

After every gt submit, immediately run:

# Get the PR number from gt submit output, then:
gh pr view <PR_NUMBER> --json body --jq '.body'

If the body is empty or just contains template placeholders:

gh pr edit <PR_NUMBER> --title "feat: meaningful title" --body-file /path/to/pr-body.md

What a complete PR description needs:

  • Summary of what the PR does (2-3 sentences)
  • Type of change (bug fix, feature, refactor, etc.)
  • How it was tested
  • Files changed overview (for larger PRs)

Never leave PRs with:

  • Fixes # (issue) placeholder unfilled
  • Empty checkboxes with no selections
  • Template comments like <!-- What does this PR do? -->
  • Just ## Summary headers with no content

Workflow reminder:

gt submit                           # Creates draft PR
gh pr view <N> --json body --jq '.body'  # Check if body is populated
# If empty/template:
gh pr edit <N> --title "..." --body "..."  # Fill it properly

Emergency Fallback

If gt commands fail (auth expired, service down), save your work:

git add .
git commit -m "wip: saving progress"
git push origin HEAD  # BYPASS_GRAPHITE: gt service unavailable

The # BYPASS_GRAPHITE: <reason> comment is required to bypass the hook.

Troubleshooting

| Issue | Solution | |-------|----------| | gt: command not found | npm install -g @withgraphite/graphite-cli | | Not authenticated | gt auth login | | Branch not tracked | gt track then gt submit | | Stack out of sync | gt restack then gt submit --stack | | Merge conflict during sync | Resolve conflicts, git add, git rebase --continue, then gt sync | | Need to set up new repo | gt auth login && gt repo init --trunk main |

Splitting a Large Commit

If you realize a commit should have been stacked:

git reset HEAD~1 --soft          # Undo commit, keep changes staged
gt create step-1-types
git add src/types/* && git commit -m "feat: add types"
gt create step-2-impl
git add src/api/* && git commit -m "feat: implement"
gt submit --stack

View Stack Status

gt log short

  main
  └── feat-schema (#234, approved)
      └── feat-api (#235, changes requested)
          └── feat-ui (#236, pending review)

Scripts

| Script | Purpose | |--------|---------| | graphite-detect.sh | Check if Graphite is active | | graphite-block-hook.sh | PreToolUse hook (blocks conflicting commands) |

References

  • references/graphite-workflow.md - Extended stacking examples, team patterns, CI integration

Integration

| When | Related Skill | Action | |------|---------------|--------| | Before submit | code-quality | Run checks, ensure CI will pass | | After changes | git-commit | Commit with proper message | | Before PR | code-review | Review your changes |

Output

Branches and PRs managed via Graphite CLI. View stack: gt log short.