# Ghstack Workflow

> A Claude skill from shikanime-labs/skills.

- **Type:** Skill
- **Install:** `agentstack add skill-shikanime-labs-skills-ghstack-workflow`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [shikanime-labs](https://agentstack.voostack.com/s/shikanime-labs)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [shikanime-labs](https://github.com/shikanime-labs)
- **Source:** https://github.com/shikanime-labs/skills/tree/main/skills/github/ghstack-workflow

## Install

```sh
agentstack add skill-shikanime-labs-skills-ghstack-workflow
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ghstack + jj: Stacked PR Workflow

Manage stacked pull requests using `ghstack` (or `gh stack`) with Jujutsu (`jj`)
as the local VCS. Each commit becomes exactly one PR.

## Core Concept

```text
1 commit  ==  1 PR
N commits ==  N PRs  (called a "stack")
```

Each PR's base is the commit below it. Reviewers see only that layer's diff. The
bottom PR targets `main` (or trunk).

```text
commit-3  -> PR #3 (base: commit-2)   PR #2 (base: commit-1)
commit-1  -> PR #1 (base: main)      //base`, `gh///head`, `gh///orig`.

## Workflow: Update a PR in the Stack

```bash
# 1. Edit files as needed
# 2. Squash changes into the TARGET commit (NOT a new commit)
jj squash -r 
# 3. Resubmit the entire stack
ghstack
```

**Critical:** Use `jj squash` (not `jj commit`) to amend an existing commit.
This preserves the 1-commit-1-PR mapping.

### Targeting a specific commit

```bash
# Squash working copy into a specific revision
jj squash -r 

# Or squash a specific revision into another
jj squash  -d 
```

## Workflow: Land (Merge) a Stack

```bash
# Land a specific PR (cascading rebase + merge)
ghstack land 
# OR: ghstack land #
# OR: gh stack merge 
```

**Never** use `gh pr merge` or the GitHub UI merge button on a ghstack PR. This
breaks the stack's base branch tracking and produces `[ghstack-poisoned]`
commits.

## Workflow: Rebase a Stack onto Updated Main

```bash
# Fetch latest main, then rebase the entire stack
jj rebase -d main
# Then resubmit
ghstack
```

**Never** `git merge` into a ghstack branch — ghstack will error because each
commit must remain a separate PR.

## Workflow: Checkout an Existing Stack

```bash
# By PR number
ghstack checkout 
# OR: gh stack checkout 
```

## Workflow: Sync PR Descriptions

```bash
# Sync GitHub PR descriptions back to local commit messages
ghstack sync
```

## Branch Structure (Internal)

For each commit N in a stack, ghstack creates three branches:

| Branch           | Purpose                                                   |
| ---------------- | --------------------------------------------------------- |
| `gh/user/N/base` | Base branch (like `main`). Never force-pushed.            |
| `gh/user/N/head` | The actual change. PR targets `base`. Never force-pushed. |
| `gh/user/N/orig` | Exact local commit. Not visible on GitHub.                |

## Pitfalls

1. **Never `gh pr merge` on a ghstack PR.** Always use `ghstack land`. The UI
   merge button breaks base branch tracking.

2. **Never force-push ghstack branches manually.** ghstack manages branch
   pointers. Manual force-poisoning corrupts the stack.

3. **Never `git merge` into a ghstack branch.** Use `jj rebase` instead. Merge
   commits break the 1-commit-1-PR invariant.

4. **Use `jj squash` not `jj commit` for updates.** A new commit means a new PR.
   Squashing preserves the existing PR.

5. **Rebase before resubmit.** If `main` has moved, rebase your stack first:
   `jj rebase -d main` then `ghstack`.

6. **Stack order matters.** Commits are stacked in topological order (oldest =
   bottom). Reorder with `jj rebase -r  -d ` before submitting.

7. **`ghstack` vs `gh stack`:** `ghstack` (ezyang) is the Python CLI with
   `~/.ghstackrc`. `gh stack` (GitHub official) is a Go-based `gh` extension
   with `.git/gh-stack` metadata. They are NOT compatible — pick one per repo.

8. **Splitting a stack into separate PRs.** When asked to split changes into
   individual PRs (1 commit == 1 PR), use `ghstack submit` for each commit. If
   `ghstack submit` fails mid-stack (e.g., timeout, duplicate commit error),
   push remaining commits as separate branches and create PRs manually:

   ```bash
   # Push each commit to its own branch
   git push origin :refs/heads/fix/
   # Create PRs manually, basing each on the previous PR's head branch
   gh pr create --title "..." --head fix/ --base 
   ```

   This preserves the stack relationship without relying on ghstack's internal
   tracking.

## Quick Reference

| Task              | Command                                 |
| ----------------- | --------------------------------------- |
| Create stack      | `jj commit -m "..."` x N → `ghstack`    |
| Update PR         | edit → `jj squash -r ` → `ghstack` |
| Land PR           | `ghstack land `                    |
| Rebase stack      | `jj rebase -d main` → `ghstack`         |
| Checkout PR       | `ghstack checkout `                  |
| Sync descriptions | `ghstack sync`                          |
| View stack        | `jj log -r main..@`                     |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [shikanime-labs](https://github.com/shikanime-labs)
- **Source:** [shikanime-labs/skills](https://github.com/shikanime-labs/skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-shikanime-labs-skills-ghstack-workflow
- Seller: https://agentstack.voostack.com/s/shikanime-labs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.