Skip to content
Back to search

stack

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kitlangton--stack/badge.svg)](/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)

  1. # stack
  2. ```ts
  3. ╭───STACK───╮
  4. dev
  5. └─ #101
  6. └─ #102
  7. └─ #103
  8. ╰───────────╯
  9. ```
  10. Squash-safe stacked PR/MR repair for coding agents working in GitHub or GitLab
  11. repos that squash-merge and delete branches.
  12. `stack` is agent-first. Humans can run it directly, but the happy path is: let
  13. the agent do normal code work with plain `git`, then use `stack` for stack
  14. inspection, repair, merge, and undo workflows.
  15. ## Install
  16. ```bash
  17. npm install -g @kitlangton/stack
  18. ```
  19. Install the agent skill too:
  20. ```bash
  21. npx skills add kitlangton/stack --skill stack
  22. ```
  23. Install and authenticate the matching host CLI:
  24. ```bash
  25. gh auth login # GitHub
  26. glab auth login # GitLab
  27. ```
  28. ## Agent Happy Path
  29. 1. Create stacked changes using normal git branches.
  30. 2. Open the root PR/MR against trunk, for example `main` or `dev`.
  31. 3. Open each child PR/MR against its parent branch.
  32. 4. Preview the stack:
  33. ```bash
  34. stack sync
  35. ```
  36. 5. Apply the safe maintenance workflow:
  37. ```bash
  38. stack sync --apply
  39. ```
  40. 6. Merge from the root when ready:
  41. ```bash
  42. stack merge
  43. stack merge --apply
  44. ```
  45. Use `stack merge --auto` when the code host should wait for merge requirements,
  46. then repair descendants automatically after the root lands.
  47. ## What It Does
  48. `stack sync --apply` is the common maintenance workflow:
  49. - Infers stack links from PR/MR target branches.
  50. - Records stack intent in `.git/stack/state.json`.
  51. - Publishes ahead parent branches before repairing their descendants.
  52. - Repairs descendants after parent branches move or land.
  53. - Retargets PRs/MRs when needed.
  54. - Refreshes stack blocks in descriptions.
  55. - Saves `.git/stack/undo.json` before mutations.
  56. For a parent that needs no local repair, sync checks its actual push destinations
  57. and only publishes fast-forward changes, with explicit leases. Diverged or unknown
  58. remote tips require fetching and reconciling first. Undo restores each destination's
  59. previous tip without discarding commits that were already on the local parent;
  60. it refuses to overwrite a remote tip changed since sync.
  61. GitHub stack blocks use compact `#101` references. GitLab blocks use `!101`
  62. references plus titles because bare GitLab MR links only show titles on hover.
  63. Recognized transient code-host read failures are retried up to twice, with
  64. jittered backoff around one and two seconds. Writes are not automatically retried:
  65. a timed-out create, merge, or update may already have succeeded. GitLab reuses
  66. known titles and preserves historical stack entries if optional title lookup fails.
  67. If a repair fails, run:
  68. ```bash
  69. stack history
  70. stack undo
  71. stack undo --apply
  72. ```
  73. ## GitHub And GitLab
  74. Provider selection is automatic for public hosts:
  75. - `github.com` uses `gh`.
  76. - `gitlab.com` uses `glab`.
  77. For enterprise hosts, configure the repo once:
  78. ```bash
  79. git config stack.codeHost github # or: gitlab
  80. ```
  81. Use `STACK_CODE_HOST=github|gitlab` for a one-off override.
  82. ## Trunk Branches
  83. By default, `stack` treats `dev`, `main`, and `master` as trunk branches. Repos
  84. that use another trunk, such as `develop`, can configure the trunk list:
  85. ```bash
  86. git config stack.trunks dev,develop,main,master
  87. ```
  88. ## Stack Block Heading
  89. Each stack block has a heading that links back to this project. To render a
  90. plain `### Stack` heading without the attribution link — for example in
  91. enterprise repos where external links trip compliance checks — set:
  92. ```bash
  93. git config stack.blockLink false
  94. ```
  95. The linked heading stays on by default. This is repo-local; use
  96. `git config --global stack.blockLink false` to apply it everywhere.
  97. ## Example Output
  98. ```text
  99. Sync preview
  100. ● main
  101. └─ ● stack-a #101
  102. └─ ● stack-b #102
  103. Would update PRs: #101, #102
  104. Apply:
  105. stack sync
  106. ```
  107. ```text
  108. → retarget #102 (stack-b) to main before merge
  109. → merge #101 (stack-a)
  110. → rebase stack-b onto main
  111. → push stack-b
  112. → update #102 stack block
  113. ```
  114. ## CLI Reference
  115. ```bash
  116. stack status # inspect the relevant local stack
  117. stack skill # print the stack skill (agent instruction set)
  118. stack sync # preview inference, repairs, and description updates
  119. stack sync --apply # apply the previewed maintenance workflow
  120. stack sync <branch> # preview only the stack containing branch
  121. stack sync --apply <branch>
  122. # apply only the stack containing branch
  123. stack sync --apply --keep-going
  124. # process independent stacks and report failures
  125. stack doctor # inspect repo, host, metadata, and journal health
  126. stack merge # dry-run the next root merge
  127. stack merge --apply # merge root and repair descendants
  128. stack merge --auto # wait for host requirements, then merge and repair
  129. stack merge --auto --through <branch-or-change>
  130. # auto-merge roots through a bounded target
  131. stack history # show the last saved mutation journal
  132. stack undo # preview undo
  133. stack undo --apply # restore branch tips, request targets, and metadata
  134. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.