Back to search
stack
SkillGitHub
ts ╭───STACK───╮ dev └─ 101 └─ 102 └─ 103 ╰───────────╯
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/kitlangton--stack)HTML
<a href="/listings/kitlangton--stack"><img src="/api/listings/kitlangton--stack/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install -g @kitlangton/stack
Install the agent skill too:
npx skills add kitlangton/stack --skill stack
Install and authenticate the matching host CLI:
gh auth login # GitHub glab auth login # GitLab
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 180 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # stack
- ```ts
- ╭───STACK───╮
- dev
- └─ #101
- └─ #102
- └─ #103
- ╰───────────╯
- ```
- Squash-safe stacked PR/MR repair for coding agents working in GitHub or GitLab
- repos that squash-merge and delete branches.
- `stack` is agent-first. Humans can run it directly, but the happy path is: let
- the agent do normal code work with plain `git`, then use `stack` for stack
- inspection, repair, merge, and undo workflows.
- ## Install
- ```bash
- npm install -g @kitlangton/stack
- ```
- Install the agent skill too:
- ```bash
- npx skills add kitlangton/stack --skill stack
- ```
- Install and authenticate the matching host CLI:
- ```bash
- gh auth login # GitHub
- glab auth login # GitLab
- ```
- ## Agent Happy Path
- 1. Create stacked changes using normal git branches.
- 2. Open the root PR/MR against trunk, for example `main` or `dev`.
- 3. Open each child PR/MR against its parent branch.
- 4. Preview the stack:
- ```bash
- stack sync
- ```
- 5. Apply the safe maintenance workflow:
- ```bash
- stack sync --apply
- ```
- 6. Merge from the root when ready:
- ```bash
- stack merge
- stack merge --apply
- ```
- Use `stack merge --auto` when the code host should wait for merge requirements,
- then repair descendants automatically after the root lands.
- ## What It Does
- `stack sync --apply` is the common maintenance workflow:
- - Infers stack links from PR/MR target branches.
- - Records stack intent in `.git/stack/state.json`.
- - Publishes ahead parent branches before repairing their descendants.
- - Repairs descendants after parent branches move or land.
- - Retargets PRs/MRs when needed.
- - Refreshes stack blocks in descriptions.
- - Saves `.git/stack/undo.json` before mutations.
- For a parent that needs no local repair, sync checks its actual push destinations
- and only publishes fast-forward changes, with explicit leases. Diverged or unknown
- remote tips require fetching and reconciling first. Undo restores each destination's
- previous tip without discarding commits that were already on the local parent;
- it refuses to overwrite a remote tip changed since sync.
- GitHub stack blocks use compact `#101` references. GitLab blocks use `!101`
- references plus titles because bare GitLab MR links only show titles on hover.
- Recognized transient code-host read failures are retried up to twice, with
- jittered backoff around one and two seconds. Writes are not automatically retried:
- a timed-out create, merge, or update may already have succeeded. GitLab reuses
- known titles and preserves historical stack entries if optional title lookup fails.
- If a repair fails, run:
- ```bash
- stack history
- stack undo
- stack undo --apply
- ```
- ## GitHub And GitLab
- Provider selection is automatic for public hosts:
- - `github.com` uses `gh`.
- - `gitlab.com` uses `glab`.
- For enterprise hosts, configure the repo once:
- ```bash
- git config stack.codeHost github # or: gitlab
- ```
- Use `STACK_CODE_HOST=github|gitlab` for a one-off override.
- ## Trunk Branches
- By default, `stack` treats `dev`, `main`, and `master` as trunk branches. Repos
- that use another trunk, such as `develop`, can configure the trunk list:
- ```bash
- git config stack.trunks dev,develop,main,master
- ```
- ## Stack Block Heading
- Each stack block has a heading that links back to this project. To render a
- plain `### Stack` heading without the attribution link — for example in
- enterprise repos where external links trip compliance checks — set:
- ```bash
- git config stack.blockLink false
- ```
- The linked heading stays on by default. This is repo-local; use
- `git config --global stack.blockLink false` to apply it everywhere.
- ## Example Output
- ```text
- Sync preview
- ● main
- └─ ● stack-a #101
- └─ ● stack-b #102
- Would update PRs: #101, #102
- Apply:
- stack sync
- ```
- ```text
- → retarget #102 (stack-b) to main before merge
- → merge #101 (stack-a)
- → rebase stack-b onto main
- → push stack-b
- → update #102 stack block
- ```
- ## CLI Reference
- ```bash
- stack status # inspect the relevant local stack
- stack skill # print the stack skill (agent instruction set)
- stack sync # preview inference, repairs, and description updates
- stack sync --apply # apply the previewed maintenance workflow
- stack sync <branch> # preview only the stack containing branch
- stack sync --apply <branch>
- # apply only the stack containing branch
- stack sync --apply --keep-going
- # process independent stacks and report failures
- stack doctor # inspect repo, host, metadata, and journal health
- stack merge # dry-run the next root merge
- stack merge --apply # merge root and repair descendants
- stack merge --auto # wait for host requirements, then merge and repair
- stack merge --auto --through <branch-or-change>
- # auto-merge roots through a bounded target
- stack history # show the last saved mutation journal
- stack undo # preview undo
- stack undo --apply # restore branch tips, request targets, and metadata
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.