/stacked-prs

name: stacked-prs
description: 'Manages dependent branch stacks and stacked pull requests using safe Git topology rules. Triggers on: "create stacked PRs", "publish this stack", "sync my PR stack", "rebase this stack", "merge the stack", "retarget child PRs", "split this branch into stacked PRs", "validate this stack", "cleanup stacked branches", or "GitHub native stack". Use when local branches or one source branch need a dependency-ordered PR stack with correct parent bases, validation, synchronization and optional GitHub-native stack support, or when an existing stack needs its topology, provenance and native membership resolved before its landing and cleanup are delegated to the ship-workflow lifecycle.'
metadata:
  version: 0.6.0
  category: development
  tags: [git, pull-requests, stacked-prs, github-native, workflow]
  difficulty: advanced
  phase: ship

Stacked PRs

Build, publish, synchronize and validate stacked pull requests without corrupting branch topology, and decide the topology, provenance and native membership that landing an existing stack depends on.

The package identity is provider-neutral. Git is the source of truth for branch ancestry; provider PR metadata is the source of truth for review bases. GitHub through `gh` is the first documented provider adapter.

Landing, post-landing promotion and retargeting, and cleanup of an existing manual or GitHub-native stack have one executable owner: the `ship-workflow` skill's stack graph run. This skill authors its explicit stack decision packet and delegates to it once (§5); it has no hand-run landing or cleanup procedure of its own.

Reference Files

| File | Contents | Load When | | --- | --- | --- | | `references/stack-model.md` | Stack inference, explicit ordering, native detection and the explicit stack decision packet | Inspecting, publishing, validating, or delegating a stack | | `references/provider-adapters.md` | Provider adapter contract and GitHub `gh` commands for listing, creating, retargeting and checking PRs | Creating, retargeting or checking PRs | | `references/sync-algorithm.md` | Slice proof, expected-old leases and the standalone restack procedure | Syncing a stack after a parent or base moves | | `references/merge-discipline.md` | Parent-first landing rules, landing proofs, retention and endpoints the delegated run enforces | Deciding what to select and what an outcome means | | `references/metadata-format.md` | Optional metadata schema and validation rules | `.stack-prs.yaml` exists or inference is ambiguous | | `references/provenance.md` | Commit-trailer stack identity, stamping, verification, merge-mode coupling | Creating, splitting, syncing, or choosing a merge method | | `references/github-native.md` | Native detection, linking eligibility, native sync and the native prefix policy | A GitHub-native stack is requested or detected |

When To Use

| Use this skill | Use another package | | --- | --- | | Multiple dependent branches need PRs against parent branches | `ship-workflow` for one independent PR | | A feature branch must be split into reviewable dependent branches | `task-decomposer` for planning tasks before code exists | | An existing stack needs rebasing, retargeting to correct parents, validation, or a landing scope decision | `pr-review` for reviewing one PR diff | | An existing stack must be landed or cleaned after landing (delegated in §5) | General Git commands for unrelated branch cleanup |

Core Rules

• Prefer one cohesive PR unless real dependencies, review boundaries or safe incremental integration justify a stack. Keep the dependency chain shallow; a template or depth ceiling is not a target PR count. Honor an explicitly requested stack without silently widening its scope.

• Run `git rev-parse --show-toplevel` before any workflow.
• Run `git status --porcelain` before rebases, pushes, PR creation and PR retargeting.
• Stop on a dirty worktree unless the user explicitly scopes the operation to inspection only.
• Prefer existing PR `baseRefName` values over inferred ancestry.
• Resolve `<base>` from the root PR's `baseRefName` (`gh pr view <root-pr> --json baseRefName --jq .baseRefName`), not from `origin/HEAD`; a stack's trunk need not be the repository's default branch.
• Use explicit branch order or `.stack-prs.yaml` when parent inference is ambiguous.
• Never use plain `git push --force` or a bare `--force-with-lease`; push rewritten heads with `--force-with-lease=refs/heads/<branch>:<expected-old-oid>`.
• Never delete stack branches by hand; proof-based cleanup belongs to the delegated run (§5).
• Stamp `Stack-Id` and `Stack-Position` trailers on every commit the skill creates or splits; copy the ID from `.stack-prs.yaml` or mint it once when absent.
• Verify trailers are present and consistent before delegating a landing of a stack the skill created.
• Probe every open stack PR for native-stack membership during Inspect (`references/stack-model.md` § Native Stack Detection) before any landing decision.
• Detect the provider's squash message policy (`squash_merge_commit_message`) before choosing `squash` as a node's merge method (`references/provenance.md` § Merge Mode Coupling).

GitHub-native stack mode

GitHub-native stacks are same-repository-only. They enhance manual Armory stacks; they do not replace provenance trailers, `.stack-prs.yaml`, or the provider-neutral workflow.

Native-stack membership is a provider-side property of a pull request, not a mode this skill chooses. Detect it for every stack PR during Inspect, before any landing decision, whether or not `github-native` mode was requested: read `.stack` from `GET repos/{owner}/{repo}/pulls/<number>` and the complete ordered membership from `GET repos/{owner}/{repo}/stacks/<stack-number>` (`references/github-native.md` § Detecting an already-native stack).

Creating native state (opt-in)

Converting a manual stack to native with `gh stack link` is a provider mutation. Use it only after