# Stack

> Use when work should land as a stacked bead→worktree→PR chain (gh-stack analogue) — `bro flow stack push` a bead onto a named stack, `bro flow stack list` the chain, `bro flow stack publish` registers the PRs as the host's stack, `bro flow stack sync` after a member merges, `bro flow stack merge` to land it, `bro flow loop --stack` to drive it. Thin wrapper over the bro CLI — mechanics live in the CLI.

- Skill: `theplenkov/stack` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add theplenkov/stack`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theplenkov/stack/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: theplenkov (https://skillmd.com/u/theplenkov)
- Updated: 2026-11-17
- Page: https://skillmd.com/skills/theplenkov/stack

---


# /stack (bro)

**All mechanics live in the `bro` CLI.** This skill is policy only.

A stack is an ordered chain of beads: member N's worktree branches off
member N-1's branch and its PR targets that branch, so dependent work
reviews while the parent is still in flight. The stack is a *view* over
`stack/<name>/<n>-<slug>` branches plus the `.git/bro/stack/` edges
`bro work enter` records — dead branches just drop out.

## Commands

| Command | What it does |
| ------- | ------------ |
| `bro flow stack push <bead> [--name <stack>]` | Sibling worktree `<repo>--<bead>` on branch `stack/<name>/<n>-<bead>`, based on the stack tip (first member bases on the default branch). `--name` is required from the main checkout; inside a `stack/<name>/…` member worktree the name is inferred. Re-pushing a bead that is already a member re-enters its worktree — no duplicate position. Claims the bead, like `work enter` |
| `bro flow stack list [<name>]` | The chain: position, bead, branch, recorded base, worktree state, PR state + declared base |
| `bro flow stack sync [<name>]` | Post-merge cascade: retarget open child PRs to the new base and rebase child branches — skipped where the platform already did it; a dirty or locked worktree is skipped and reported — its owner rebases on enter. A clean cascade also publishes the chain (below) |
| `bro flow stack publish [<name>]` | Register the chain's open member PRs as the host's server-side stack — `gh stack link` on GitHub. Idempotent: members already inside are kept, a re-run is a no-op. Needs ≥2 open member PRs; declines where the host detects chains itself (GitLab, plain git) |
| `bro flow stack merge [<name>] [--squash\|--merge\|--rebase] [--admin]` | Land the chain bottom→top through the connector's own mechanism after gating every mergeable member's act gate; post-merge sync runs automatically |
| `bro flow loop --stack <name>` | The autonomous runner chains every claimed bead onto the named stack and syncs after each landed merge |

## Connector dispatch

Stack ops are the connector's answer to "what does the platform already
do" — `bro flow stack` never hand-rolls a step the host owns:

- **GitHub** — a `.stack`-marked PR means the platform retargets
  dependents AND rebases their remote branches on merge: sync skips the
  API retarget and fast-follows the remote (local-only commits replay
  on top — never a force-push over the platform's rewrite). With the
  `gh stack` extension installed, `stack merge` is one atomic
  `gh stack merge <top-pr> --yes`; without it, per-layer merge-async.
  `stack publish` is the same extension's `gh stack link` — the
  write path that creates or grows the server-side stack object the
  `.stack` reads reflect.
- **GitLab** (19.1+) — the platform detects the chain from target
  branches and retargets the next MR on each merge; bro never calls the
  retarget API there. Merge is bottom-up `PUT …/merge` per layer —
  that IS the platform flow.
- **plain git** — no forge: `stack merge` lands each member into the
  trunk inside the primary worktree, sync is a local rebase cascade.

## Policy

- **Push beads, not branches.** `stack push` names the bead — the
  branch/worktree/PR machinery follows; a beadless slug still works but
  claims nothing.
- **Open member PRs against the member below** — the push hint is the
  connector's (`gh pr create --base`, `glab mr create
  --target-branch`); the bottom member targets the default branch. A
  forge-less repo prints no hint — there is nothing to open.
- **Publish is post-hoc, not part of push.** No PR exists at `stack
  push` time — registration can only run once ≥2 member PRs exist. Call
  `bro flow stack publish` after the second member's PR is open, or let a
  clean `stack sync` do it; `stack list` hints while open PRs are
  unregistered. Registration is what unlocks the platform cascade and
  `gh stack merge` — publish before depending on either.
- **Merge via `stack merge`, then it syncs itself.** The merge set is
  the contiguous prefix of live members with an OPEN PR — a PR-less
  member breaks the chain and merge stops below it. Every member's act
  gate must be green before the first merge call. A squash-merged
  member leaves the chain — its edge is retired and its branch is
  deleted once no worktree holds it.
- **Sync is safe to rerun** — in-sync members are no-ops, and
  platform-owned cascade steps are skipped rather than duplicated.
- **Never sync over someone's dirty worktree.** Skipped members keep
  their recorded base; the owner rebases when they re-enter.
- Stacks compose with `bro work enter --stack` — the same edge registry
  backs both (`stack.mode: "auto"` ad-hoc chains vs named `bro flow stack`
  chains).

