(magpie) 01/01: docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs

[po...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch feat/suggest-gh-stack
in repository https://gitbox.apache.org/repos/asf/magpie.git

commit db4125a4b2e43617b040c4593c55e2a6e610212c
Author: Jarek Potiuk <po...@apache.org>
AuthorDate: Sun Sep 27 16:52:10 2026 +0200

    docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs
    
    GitHub's stacked PRs (the github/gh-stack extension) show a chain of
    dependent PRs as one stack. The agent conventions now say to check for
    the extension when a change is split into dependent PRs, suggest the
    user install it themselves (the secure setup denies extension installs
    from the agent), create each PR from its approved body with
    `gh pr create --base <previous branch> --web`, and join them with
    `gh stack link`. `gh stack submit --auto`, and letting `link` create PRs
    for bare branches, are ruled out because both post titles and bodies
    nobody approved.
    
    The same guidance goes into the AGENTS.md block setup writes for
    adopters (as a paragraph, so the setup skill's surface hash is
    unchanged), the fix-workflow template, and the prerequisites.
    
    Generated-by: Claude Opus 5
---
 AGENTS.md                                      | 10 ++++++++++
 docs/quick-start/prerequisites.md              |  1 +
 plugins/magpie-setup/skills/setup/install.md   | 10 ++++++++++
 plugins/magpie-setup/templates/fix-workflow.md |  8 ++++++++
 4 files changed, 29 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c67a23d0..da7574a9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -538,6 +538,16 @@ to a home-dir path and update the tool to read from there.
 - **Always open PRs with `gh pr create --web`** so the human reviewer can check the title,
   body, and the generative-AI disclosure in the browser before submission. Pre-fill `--title`
   and `--body-file` (including the Gen-AI disclosure block) so they only need to review, not edit.
+- **Stack a series of dependent PRs with GitHub's stacked PRs.**
+  When one change is split into several PRs that each build on the previous one,
+  check for the [`github/gh-stack`](https://gh.io/stacks) extension with a plain `gh extension list`.
+  If it is missing, suggest the user install it themselves with `! gh extension install github/gh-stack` —
+  the secure setup denies extension installs from the agent, and installing one is the user's call.
+  Create each PR from its approved body file with `gh pr create --base <previous branch> --web`,
+  then join them bottom to top with `gh stack link <bottom-PR> … <top-PR>`.
+  Never use `gh stack submit --auto`, or let `gh stack link` create a PR for a bare branch:
+  both post auto-generated titles and bodies nobody approved.
+  If the repository does not have stacks enabled, the base-chained PRs still work; say so and carry on.
 - **Pass long or multi-line message bodies to `gh` (and similar CLIs) through a file,
   never inline.**
   Write the text to a file in the session scratch directory or `$TMPDIR` first,
diff --git a/docs/quick-start/prerequisites.md b/docs/quick-start/prerequisites.md
index b5e685dd..729acff3 100644
--- a/docs/quick-start/prerequisites.md
+++ b/docs/quick-start/prerequisites.md
@@ -215,6 +215,7 @@ JIRA), `contract:change-request` (GitHub PRs, JIRA patches, or dev@
   needs a fork of `<upstream>` on your GitHub account (it pushes a branch
   there, then opens the PR via `gh pr create --web`). Claude Code also
   ships a GitHub MCP; `gh` covers the rest and is what OpenCode uses.
+- **Optional: [`github/gh-stack`](https://gh.io/stacks).** When a change goes up as a series of dependent PRs, the agent suggests this `gh` extension and links the PRs into a native GitHub stack with `gh stack link`. Install it yourself with `gh extension install github/gh-stack`; the secure setup does not let the agent install extensions.
 - **JIRA / SVN-first projects.** No `gh` is required. The tracker is JIRA,
   review + merge run through `jira-patch` or `dev@` `[PATCH]` mail, and
   commits land via SVN — declare those backends in
diff --git a/plugins/magpie-setup/skills/setup/install.md b/plugins/magpie-setup/skills/setup/install.md
index 74b73fc2..8d2dca9f 100644
--- a/plugins/magpie-setup/skills/setup/install.md
+++ b/plugins/magpie-setup/skills/setup/install.md
@@ -1768,6 +1768,16 @@ framework before they hit a "skill not found" error:
    — never edit the snapshot directly. Framework changes go
    via PR to
    [`apache/magpie`](https://github.com/apache/magpie).
+
+   **Series of dependent PRs.** When a change is split into
+   PRs that build on each other, stack them with GitHub's
+   stacked PRs: if `gh extension list` does not show
+   [`github/gh-stack`](https://gh.io/stacks), suggest the
+   contributor run `gh extension install github/gh-stack`
+   themselves; open each PR from its approved body against
+   the previous PR's branch, in the browser, then
+   `gh stack link <bottom-PR> … <top-PR>`. Never let
+   `gh stack` generate titles or bodies.
    ```
 
    **If the adopter installed the `pr-management-*` family**
diff --git a/plugins/magpie-setup/templates/fix-workflow.md b/plugins/magpie-setup/templates/fix-workflow.md
index 0b7557e3..8a49c338 100644
--- a/plugins/magpie-setup/templates/fix-workflow.md
+++ b/plugins/magpie-setup/templates/fix-workflow.md
@@ -96,6 +96,14 @@ before submission. Pre-fill `--title` and `--body` (including the
 Gen-AI disclosure block) so the reviewer only needs to review, not
 edit.
 
+When a fix is split into several dependent PRs, stack them with
+GitHub's stacked PRs: suggest the contributor install the
+[`github/gh-stack`](https://gh.io/stacks) extension
+(`gh extension install github/gh-stack`) if `gh extension list`
+does not show it, open each PR with `gh pr create --base <previous
+branch> --web`, then run `gh stack link <bottom-PR> … <top-PR>`.
+Never let `gh stack` generate PR titles or bodies.
+
 ## Private-PR fallback
 
 The exceptional private-PR path (target branch `main` of the