/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, merge order, cleanup, and optional GitHub-native stack support.'
metadata:
  version: 0.3.0
  category: development
  tags: [git, pull-requests, stacked-prs, github-native, workflow]
  difficulty: advanced
  phase: ship

Stacked PRs

Build, publish, synchronize, validate, merge, and clean up stacked pull requests without corrupting branch topology.

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.

Reference Files

| File | Contents | Load When | | --- | --- | --- | | `references/stack-model.md` | Stack inference, explicit ordering, and `.stack-prs.yaml` rules | Inspecting, publishing, validating, or cleaning a stack | | `references/provider-adapters.md` | Provider adapter contract and GitHub `gh` commands | Creating, retargeting, checking, merging, or deleting PRs | | `references/sync-algorithm.md` | Rebase and force-with-lease synchronization workflow | Syncing a stack after a parent or base moves | | `references/merge-discipline.md` | Bottom-up merge and branch cleanup rules | Merging or closing out a stack | | `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 merging any stack | | `references/github-native.md` | Eligibility, `gh stack` operations, preview limits, and manual fallback | 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 release 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, validation, or merge sequencing | `pr-review` for reviewing one PR diff | | A stack must be cleaned after merge | General Git commands for unrelated branch cleanup |

Core Rules

• Run `git rev-parse --show-toplevel` before any workflow.
• Run `git status --porcelain` before rebases, pushes, PR creation, PR retargeting, merge, or cleanup.
• 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`; use `git push --force-with-lease origin <branch>`.
• Merge from root to leaf. Never merge a child before its parent.
• Do not delete unmerged stack branches without explicit user instruction.
• 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 merge.
• Probe every open stack PR for native-stack membership during Inspect (`references/stack-model.md` § Native Stack Detection) before merge planning; a detected native stack makes the manual merge path in §5 unavailable, not merely discouraged.
• Detect the provider's squash message policy (`squash_merge_commit_message`) before merging with `--squash`. Fold trailers into the squash body only when the policy is `PR_BODY` or `BLANK`; under `COMMIT_MESSAGES` (GitHub's default) trailers already survive automatically.

GitHub-native stack mode

GitHub-native stacks are public preview and 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 merge planning, whether or not `github-native` mode was requested.

Creating native state (opt-in)

Converting a manual stack to native with `gh stack link` is a mutation with public-preview risk. Use it only after this eligibility probe passes:

1. GitHub CLI plus `gh stack --help` succeeds; install `github/gh-stack` when absent. 2. Native stack support is enabled for the repository; native exit code 9 falls back to manual mode. 3. Every proposed head/base branch and pull request belongs to the same GitHub repository; reject forks and cross-repository stacks. 4. Existing PR bases, local branch order, and `Stack-Id`/`Stack-Position` provenance agree. Stop on disagreement. 5. The user explicitly requests native mode or accepts its public-preview risk.

Operating on an already-native stack (mandatory)

Once Inspect finds a PR already native, native mode is not a choice for any operation that mutates that PR: the provider refuses a plain synchronous merge mutation (`gh pr merge`, and the underlying `mergePullRequest`/`PUT .../pulls/{n}/merge`) for a stack member with "must be merged using the asynchronous merge REST API." There is no manual Armory merge path for an already-native stack; do not present one as an alternative. Conditions 1-4 above still apply as safety checks; condition 5's use