From f7f178414c2cda6988e328d8ec39698eb9aefcff Mon Sep 17 00:00:00 2001 From: Geoff Lamrock Date: Fri, 17 Apr 2026 17:25:05 +1000 Subject: [PATCH 1/3] Add stack-cli agent skill Adds a SKILL.md at .github/skills/stack-cli/ that enables agents to use the stack CLI for managing stacked branches and pull requests. The skill covers: - Prerequisites check with download prompt if stack is not installed - Creating a new stack (stack new) - Managing branches (branch new, add, remove, move) - Syncing a stack with remote (stack sync) - Updating branches locally (stack update) - Checking stack status and other common commands Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/stack-cli/SKILL.md | 177 ++++++++++++++++++++++++++++++ 1 file changed, 177 insertions(+) create mode 100644 .github/skills/stack-cli/SKILL.md diff --git a/.github/skills/stack-cli/SKILL.md b/.github/skills/stack-cli/SKILL.md new file mode 100644 index 00000000..0c7b312f --- /dev/null +++ b/.github/skills/stack-cli/SKILL.md @@ -0,0 +1,177 @@ +--- +name: stack-cli +description: "Use the stack CLI to manage stacked branches and pull requests. Use when: creating a new stack, adding or removing branches from a stack, moving branches within a stack, syncing a stack with the remote repository, checking stack status, or managing stacked pull requests." +argument-hint: What would you like to do with your stack? +--- + +# Stack CLI + +A tool for managing multiple Git branches and pull requests that build on top of each other (stacked branches/PRs). + +## Prerequisites Check + +Before running any stack commands, verify the CLI is available: + +```shell +stack --version +``` + +If the command fails or is not found, prompt the user: + +> The `stack` CLI is not installed or not in your PATH. +> Download the latest release for your OS from: https://github.com/geofflamrock/stack/releases +> Unarchive the binary and add it to your PATH, then try again. + +Also check that `git` is available (required) and optionally `gh` (for GitHub/PR features): + +```shell +git --version +gh --version +``` + +## When to Use + +- Creating a new stack of branches +- Adding a new branch to an existing stack +- Adding an existing branch to a stack +- Removing or moving a branch within a stack +- Syncing a stack with remote (fetch + pull + update + push) +- Checking the status of a stack +- Updating stack branches without pushing + +--- + +## Procedures + +### Create a New Stack + +```shell +stack new [--name ] [--source-branch ] [--branch ] +``` + +**Interactive flow** (no flags needed — stack will prompt): +1. Run `stack new` +2. Enter a unique name for the stack +3. Select a source branch (usually `main` or `master`) +4. Choose to: create a new branch, add an existing branch, or skip + +**Non-interactive example:** +```shell +stack new --name my-feature --source-branch main --branch feature/first-step +``` + +After creation, the stack is saved in `{user}/stack/config.json`. + +--- + +### Manage Branches in a Stack + +#### Create a new branch in a stack + +```shell +stack branch new [--stack ] [--branch ] [--parent ] +``` + +- Creates a new branch from the specified parent (or prompts) +- Pushes the branch to remote +- Switches to the new branch + +#### Add an existing local branch to a stack + +```shell +stack branch add [--stack ] [--branch ] [--parent ] +``` + +- Branch must already exist locally +- Prompts for which stack and parent branch if not specified + +#### Remove a branch from a stack + +```shell +stack branch remove [--stack ] [--branch ] [--move-children-to-parent | --remove-children] [-y] +``` + +- If the branch has children, you must choose to move them to the parent or remove them +- Use `-y` to skip the confirmation prompt + +#### Move a branch to a new position in a stack + +```shell +stack branch move [--stack ] [--branch ] [--parent ] [--move-children | --re-parent-children] +``` + +- After moving, run `stack sync` or `stack update` to synchronize git history + +--- + +### Sync a Stack + +`stack sync` is the most common way to keep a stack up to date. It runs fetch, pull, update, and push in sequence. + +```shell +stack sync [--stack ] [--rebase | --merge] [-y] [--no-push] [--check-pull-requests] +``` + +**Options:** +| Flag | Description | +|------|-------------| +| `--rebase` | Rebase each branch onto its parent | +| `--merge` | Merge each parent into child branch | +| `--no-push` | Skip pushing changes to remote | +| `-y` | Skip confirmation prompt | +| `--check-pull-requests` | Skip branches whose PR is already merged | + +**Default update strategy:** Checks `stack.update.strategy` in git config, or prompts if not set. + +**Configure a default strategy:** +```shell +git config stack.update.strategy rebase # or: merge +``` + +**Conflict handling:** If conflicts occur during sync, resolve them and continue. The command will surface any `ConflictException` and prompt for next steps. + +--- + +### Update Stack Branches (without push) + +```shell +stack update [--stack ] [--rebase | --merge] [--check-pull-requests] +``` + +Updates branches in order within the stack without fetching from or pushing to the remote. Useful when you only need to rebase/merge local branches. + +--- + +### Check Stack Status + +```shell +stack status [--stack ] [--all] [--check-pull-requests] +``` + +Shows a tree view of the stack including: +- Each branch and whether it exists locally/remotely +- Commits ahead/behind the parent branch +- PR status (if `--check-pull-requests` is used and `gh` CLI is available) + +--- + +### Other Useful Commands + +| Command | Description | +|---------|-------------| +| `stack list` | List all stacks for the current repository | +| `stack switch` | Switch to a branch in a stack | +| `stack cleanup` | Remove branches that are no longer needed (merged/squash-merged) | +| `stack rename` | Rename a stack | +| `stack delete` | Delete a stack (does not delete the git branches) | +| `stack pr create` | Create stacked pull requests via `gh` CLI | + +--- + +## Tips + +- All commands can be run from anywhere inside the git repository +- Use `--working-dir ` to target a specific repo from any directory +- Use `--verbose` to see the underlying git commands being run +- Use `--json` for structured output suitable for scripting +- Stack config is stored at `{user}/stack/config.json` — open with `stack config open` From ba14849e55020906dd9137048d582a1af4f54076 Mon Sep 17 00:00:00 2001 From: Geoff Lamrock Date: Fri, 17 Apr 2026 17:34:45 +1000 Subject: [PATCH 2/3] Move to common directory --- {.github/skills/stack-cli => skills/stack}/SKILL.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {.github/skills/stack-cli => skills/stack}/SKILL.md (100%) diff --git a/.github/skills/stack-cli/SKILL.md b/skills/stack/SKILL.md similarity index 100% rename from .github/skills/stack-cli/SKILL.md rename to skills/stack/SKILL.md From eeb0b333bc2505a686326a40b23139500fa87097 Mon Sep 17 00:00:00 2001 From: Geoff Lamrock Date: Fri, 17 Apr 2026 17:44:46 +1000 Subject: [PATCH 3/3] Update skill name --- skills/stack/SKILL.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/skills/stack/SKILL.md b/skills/stack/SKILL.md index 0c7b312f..78a734c8 100644 --- a/skills/stack/SKILL.md +++ b/skills/stack/SKILL.md @@ -1,5 +1,5 @@ --- -name: stack-cli +name: stack description: "Use the stack CLI to manage stacked branches and pull requests. Use when: creating a new stack, adding or removing branches from a stack, moving branches within a stack, syncing a stack with the remote repository, checking stack status, or managing stacked pull requests." argument-hint: What would you like to do with your stack? --- @@ -50,12 +50,14 @@ stack new [--name ] [--source-branch ] [--branch ] ``` **Interactive flow** (no flags needed — stack will prompt): + 1. Run `stack new` 2. Enter a unique name for the stack 3. Select a source branch (usually `main` or `master`) 4. Choose to: create a new branch, add an existing branch, or skip **Non-interactive example:** + ```shell stack new --name my-feature --source-branch main --branch feature/first-step ``` @@ -124,6 +126,7 @@ stack sync [--stack ] [--rebase | --merge] [-y] [--no-push] [--check-pull **Default update strategy:** Checks `stack.update.strategy` in git config, or prompts if not set. **Configure a default strategy:** + ```shell git config stack.update.strategy rebase # or: merge ``` @@ -149,6 +152,7 @@ stack status [--stack ] [--all] [--check-pull-requests] ``` Shows a tree view of the stack including: + - Each branch and whether it exists locally/remotely - Commits ahead/behind the parent branch - PR status (if `--check-pull-requests` is used and `gh` CLI is available) @@ -157,14 +161,14 @@ Shows a tree view of the stack including: ### Other Useful Commands -| Command | Description | -|---------|-------------| -| `stack list` | List all stacks for the current repository | -| `stack switch` | Switch to a branch in a stack | -| `stack cleanup` | Remove branches that are no longer needed (merged/squash-merged) | -| `stack rename` | Rename a stack | -| `stack delete` | Delete a stack (does not delete the git branches) | -| `stack pr create` | Create stacked pull requests via `gh` CLI | +| Command | Description | +| ----------------- | ---------------------------------------------------------------- | +| `stack list` | List all stacks for the current repository | +| `stack switch` | Switch to a branch in a stack | +| `stack cleanup` | Remove branches that are no longer needed (merged/squash-merged) | +| `stack rename` | Rename a stack | +| `stack delete` | Delete a stack (does not delete the git branches) | +| `stack pr create` | Create stacked pull requests via `gh` CLI | ---