What is a stacked branch?

A stacked branch is a new branch based on an existing PR branch (not main) so you can work on changes dependent on that PR.

How do I specify the parent branch?

You can provide an explicit parent in the command or, if on a feature branch, the skill can offer to use it as the parent.

What happens after the parent PR is merged?

Use /rebase-merged-parent to rebase the stacked branch onto main and update its history accordingly.

stack-branch

npx machina-cli add skill flurdy/agent-skills/stack-branch --openclaw

Files (1)

SKILL.md

2.4 KB

Create Stacked Branch

Create a new branch based on an existing PR branch (not main) for dependent work.

Usage

/stack-branch AB-456
/stack-branch AB-456 feature/parent-branch    # Explicit parent

Instructions

1. Get the Jira Ticket

The first argument is the Jira ticket number for the new work.

Use the /jira-ticket skill or the Jira MCP tools directly to get ticket details:

mcp__jira__jira_get with:
  path: /rest/api/3/issue/{ticketNumber}
  jq: "{key: key, summary: fields.summary, issuetype: fields.issuetype.name}"

2. Identify Parent Branch

If parent branch not specified:

# Check if currently on a feature branch
git branch --show-current

If on a feature branch (not main), offer to use it as the parent. Otherwise, ask the user which branch to stack on.

3. Ensure Parent is Up to Date

# Fetch the parent branch
git fetch origin {parent-branch}

# Check out and update local copy
git checkout {parent-branch}
git pull origin {parent-branch}

4. Create Branch Name

Map the Jira issue type to conventional commit prefix:

Issue Type	Prefix
Story	`feat`
Task	`feat`
Bug	`fix`
Improvement	`feat`
Spike	`chore`
Sub-task	inherit from parent

Create branch name:

{prefix}/{TICKET}-{summary-in-kebab-case}

Example: feat/AB-456-add-caching-layer

5. Create the Branch

git checkout -b {new-branch-name}

6. Push and Set Upstream

git push -u origin {new-branch-name}

7. Inform User

Tell the user:

Created branch {new-branch-name} based on {parent-branch}
When creating a PR, target {parent-branch} not main
When {parent-branch} is merged, use /rebase-merged-parent to rebase onto main

8. Optional: Create Draft PR

Ask if the user wants to create a draft PR now:

Check for a repo-specific PR template at .github/pull-request-template.md or .github/pull_request_template.md. If found, use that format. If not, ask user for confirmation on generating the body ourselves.

Create the PR targeting parent branch

gh pr create --draft --base {parent-branch} --title "{type}({scope}): {description}" --body "$(cat <<'EOF'
{body}
EOF
)"

Source

git clone https://github.com/flurdy/agent-skills/blob/main/skills/stack-branch/SKILL.mdView on GitHub

Overview

Stack-branch creates a new git branch based on an existing PR branch (not main) to support dependent work. It ties your work to the parent PR, keeps change history aligned, and can leverage Jira ticket data to name the branch and structure the workflow. You can also optionally create a draft PR targeting the parent branch.

How This Skill Works

The skill retrieves the Jira ticket details, determines or confirms the parent branch, updates the parent if needed, and then creates a new branch name by mapping the Jira issue type to a conventional prefix. It then checks out the new branch, pushes it to origin, and can initiate a draft PR targeting the parent branch.

When to Use It

You need to start work that depends on an existing PR that hasn't been merged yet.
You want to explicitly stack on a parent branch rather than the main branch.
Your Jira ticket describes work that should sit under a parent PR and be developed in a separate branch.
You must ensure the parent branch is up to date before creating the new stacked branch.
You want to optionally draft a PR that targets the parent branch for review alongside the parent PR.

Quick Start

Step 1: Get the Jira ticket details using /jira-ticket to fetch key, summary, and type.
Step 2: Identify or specify the parent branch, fetch and update it if needed, then decide on the new branch name based on the Jira type.
Step 3: Create and push the new branch, and optionally start a draft PR targeting the parent branch.

Best Practices

Always fetch and update the parent branch before creating the new branch.
If possible, specify the parent explicitly to avoid mis-stacking on the wrong branch.
Map Jira issue types to prefixes correctly: Story/Task/Improvement -> feat, Bug -> fix, Spike -> chore, Sub-task inherits from parent.
Name branches in kebab-case and include the Jira ticket for traceability.
If the parent PR is merged, use rebase-merged-parent to rebase onto main and refresh the stack.

Example Use Cases

feat/AB-456-add-caching-layer
fix/AB-789-auth-bug
feat/AB-1011-improve-logging
chore/AB-1213-initial-spike-cleanup
inherit/AB-1314-subtask-derived-from-parent

Frequently Asked Questions

Add this skill to your agents