mcpField
W
working-with-graphite

working-with-graphite

github.com/neekolasDevelopment138 installsUpdated 32w ago
Repository

About working-with-graphite

A skill that guides coding agents through code changes managed with Graphite, covering branches, commits, stack updates, and PR workflows. It emphasizes using `gt` commands to preserve stack metadata and restricting branch or PR actions without authorization.

Key features

  1. 01Graphite branch and stack conventions
  2. 02Commit and change-amendment workflow
  3. 03PR submission and approval rules
  4. 04Conflict resolution steps
  5. 05Updating a mid-stack branch

Use cases

  1. 01Planning work across stacked branches
  2. 02Editing an existing branch in a Graphite stack
  3. 03Updating and submitting PRs by the stated process
  4. 04Resolving conflicts during sync or restack

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/neekolas/claude-skills --skill working-with-graphite

After installing, type/working-with-graphitein Claude Code to confirm it loaded.

Details

From the project README

Working with Graphite

Core Principles

  1. Never commit to main All commits must be on a feature branch
  2. Do not create branches unless asked Do not create new branches unless explicitly requested to.
  3. Never use raw Git rebase -- always use gt commands to preserve stack metadata
  4. Always set Claude as the co-author when committing

Branch Strategy

  • When creating plans, include the expected branches for each unit of work
  • Pieces of work that span > 500 LOC should be broken into multiple branches and stacked onto one another
  • Stack branches in a logical order, with discrete features in each branch.
  • Each branch must be able to pass all lint, check, and test evaluations

Committing code

  • Manually stage changes to impacted files using git commands. Do not use the -a flag to automatically stage all changes.
  • For new features, create a commit using gt modify --commit -m "description of the change"
  • For modifications to an existing feature or bug fixes, amend the commit using gt modify

Submitting Changes

  • When the task is complete, always gt restack and ensure that any impacted upstack branches are still valid (lint checks pass)
  • Use gt submit --stack --update-only when tasks are complete
  • If the changes are material, read the existing PR description and incorporate the changes. Do not overwrite the existing description losing important context.
  • Present any changes to the PR description to the user for approval

Creating PR's

  • Only submit a new PR with the user's explicit consent.
  • Create the PR with gt submit --draft. Always submit new PR's as a draft.
  • After submitting the PR, create a detailed PR description and submit it using the gh tool
  • Ask the user for approval before submitting the PR description

Handling Conflicts

When conflicts occur during gt sync, gt restack, or gt modify:

  1. Resolve conflicts in affected files
  2. Stage resolved files: git add <files>
  3. Continue: gt continue or gt continue --all

Workflow: Updating a Mid-Stack Branch

  1. gt checkout <target-branch>
  2. Make edits
  3. gt modify -a (amends and restacks upstack)
  4. gt submit --stack --update-only --no-interactive (pushes all updated branches)

Common Gotchas

  • Never git rebase -i -- breaks Graphite metadata. Use gt move instead.
  • Never git branch -d -- use gt delete to preserve metadata.
  • Never git commit --amend -- use gt modify -a which also restacks.
  • gt rename breaks PR links -- avoid renaming branches with existing PRs.
  • Squash merges cause cascading conflicts -- gt sync + gt restack resolves this.

Comments

Markdown supported