# Georgeguimaraes Claude Code Graphite Graphite > Graphite Stacked PRs Workflow - Skill: `tomevault-io/georgeguimaraes-claude-code-graphite-graphite` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/georgeguimaraes-claude-code-graphite-graphite` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/georgeguimaraes-claude-code-graphite-graphite/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/georgeguimaraes-claude-code-graphite-graphite --- # Graphite Stacked PRs Workflow **IMPORTANT:** This workflow applies ONLY to repositories with `.git/.graphite_repo_config`. For repositories without this file, use standard git commands (`git commit`, `git push`, etc.). ## Detection Check for `.git/.graphite_repo_config` to determine if a repo uses Graphite: - **File exists:** Use `gt` commands (this skill applies) - **File does not exist:** Use standard `git` commands (this skill does NOT apply) When Graphite is detected, use `gt` commands instead of `git` for all commit and branch operations. ## MCP Server A Graphite MCP server may be available (check with `/mcp`). If the `graphite` MCP is connected, it provides tools to work with stacked PRs. ## Planning Stacks (CRITICAL) **Before writing any code, present the stack structure and ask for confirmation.** When building a feature as a stack: 1. **Plan first** - break the work into logical, sequential PRs 2. **Use TodoWrite** - each todo item maps to one PR/`gt create` 3. **Present the structure** - show the user the planned stack: ``` PR Stack for [Feature]: 1. PR 1: [description] - [what it does] 2. PR 2: [description] - [what it does] 3. PR 3: [description] - [what it does] ``` 4. **Ask for confirmation** - "Does this structure look good to proceed?" 5. **Only then start coding** **IMPORTANT:** Each PR must be atomic and pass CI independently. Verify this before committing. ## Command Mapping Use these `gt` commands instead of their git equivalents: | Instead of | Use | Purpose | |------------|-----|---------| | `git commit` | `gt create -am "msg"` | Create new branch/PR with changes | | `git commit --amend` | `gt modify -a` | Amend current PR | | `git push` | `gt submit --no-interactive` | Submit current + all downstack branches | | `git pull` | `gt sync` | Pull trunk, restack, clean merged | | `git checkout` | `gt checkout ` | Switch branches | | `git rebase` | `gt restack` | Rebase stack (usually via `gt sync`) | ## When to Create vs Amend **Use `gt create -am "message"`** when: - Starting new work (new feature, new fix) - The change is logically separate from current PR - Building the next piece in a stack **Use `gt modify -a`** when: - Addressing PR review feedback - Fixing something in the current PR - Adding forgotten changes to current work ## Commit and PR Style ### Commit Messages Use conventional commits with casual, concise descriptions: - Start with type: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `perf:`, `test:` - Capitalize after the prefix - Keep it brief and human - No LLM fluff, no em dashes ### PR Body Descriptions Write PR bodies that explain: 1. **What** changed 2. **Why** it changed 3. **The benefit** or purpose Keep descriptions casual, concise, and human-like. Avoid corporate speak or overly formal language. Don't wrap long lines with line breaks (unlike git commits). Line breaks are fine for separating paragraphs. ### After Submitting When returning the PR URL to the user, use the **Graphite PR URL** (e.g., `https://app.graphite.dev/github/pr/...`), not the GitHub PR URL. ## Stack Philosophy Each PR in a stack must be: - **Atomic** - passes CI independently, no broken intermediate states - **Small** - ideally under 250 lines changed - **Focused** - one logical change per branch - **Reviewable** - makes sense on its own (even if it depends on others) Break large features into functional components: - Database changes first - Backend logic next - Frontend last Or use iterative stacking: - Basic implementation - Error handling - Tests - Polish ## Navigation Move through the stack: ```bash gt log # View full stack with PR status gt ls # Abbreviated stack view gt up # Move up one branch (toward tip) gt down # Move down one branch (toward trunk) gt top # Jump to top of stack gt bottom # Jump to bottom of stack gt checkout X # Switch to specific branch ``` ## Sync Workflow Run `gt sync` regularly (at least daily) to: 1. Pull latest trunk changes 2. Restack all branches 3. Clean up merged branches When `gt sync` encounters conflicts, it pauses for resolution. See conflict resolution below. ## Submitting Work Push changes with: ```bash gt submit --no-interactive # Submit current + all downstack branches (recommended) gt submit --stack # Submit current + all descendant branches gt ss # Shorthand for --stack ``` Use `--no-interactive` to avoid prompts during submission. ## Conflict Resolution When `gt sync` or `gt restack` hits conflicts: 1. **Understand what conflicted** - check which branch and what files 2. **Check what each branch does** - use `gt log` and review the changes 3. **Auto-resolve obvious conflicts:** - Import order changes - Whitespace differences - Non-overlapping additions 4. **Ask about ambiguous conflicts:** - Same code modified differently - Deleted vs modified conflicts - Semantic conflicts (logic changes) After resolving: ```bash gt continue -a # Stage all and continue restack ``` If stuck: ```bash gt abort # Abandon restack, return to previous state ``` For detailed conflict resolution patterns, see `references/conflict-resolution.md`. ## Reorganizing Stacks Adjust stack structure when needed: ```bash gt move --onto # Move current branch to new parent gt fold # Merge branch into its parent gt split # Break branch into multiple gt squash # Combine commits in branch to one gt reorder # Interactively reorder branches ``` ## Collaboration Work with others' stacks: ```bash gt get # Fetch someone's stack locally gt track # Start tracking existing git branch ``` ## Quick Reference See `references/cheatsheet.md` for a complete command reference. ## Common Workflows ### Building a Feature as a Stack 1. Plan the stack structure first (use TodoWrite) 2. Present to user and get confirmation 3. Implement each PR sequentially: ```bash gt sync # Get latest gt create -am "feat: Add avatar upload API" # ... verify it passes CI ... gt create -am "feat: Add avatar display component" # ... verify it passes CI ... gt create -am "feat: Add avatar to user profile" gt submit --no-interactive # Submit entire stack ``` ### Addressing Review Feedback ```bash gt checkout # ... make fixes ... gt modify -a # Amend changes gt submit --no-interactive # Push updates (auto-restacks dependents) ``` ### Daily Sync Routine ```bash gt sync # Pull, restack, clean # Resolve any conflicts if prompted gt continue -a # After resolving ``` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/georgeguimaraes) — claim your Tome and manage your conversions.