Stats
Actions
Tags
From feature-branch-pr
Creates fix/feature branches from upstream/main for beads/gastown forks: selects bead via bd, implements changes, submits upstream PR, cherry-picks to fork.
How this skill is triggered — by the user, by Claude, or both
Slash command
/feature-branch-pr:feature-branch-prThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
End-to-end workflow for creating a fix/feature branch, implementing changes, submitting a PR to upstream, and cherry-picking onto your fork's main.
End-to-end workflow for creating a fix/feature branch, implementing changes, submitting a PR to upstream, and cherry-picking onto your fork's main.
upstream/mainIf resuming mid-skill from a handoff, ALWAYS re-read this skill file before continuing. The handoff mail provides context, but THIS FILE defines the steps.
$ARGUMENTS — optional bead ID (e.g. bd-abc or gt-xyz)
# Detect fork from origin remote
git remote get-url origin
# Parse FORK_OWNER and REPO_NAME
# Detect upstream
git remote get-url upstream
# Parse UPSTREAM_OWNER and UPSTREAM_REPO (e.g. steveyegge/beads)
# Detect project type from upstream URL
# "beads" in URL → Go project, binary = bd, cmd = cmd/bd
# "gastown" in URL → Go project, binary = gt, cmd = cmd/gt
# Working directory
pwd
# Parse CREW_NAME from path: */crew/<CREW_NAME>
Present to user for confirmation:
Detected environment:
- Fork:
FORK_OWNER/REPO_NAME(origin) forked fromUPSTREAM_OWNER/UPSTREAM_REPO(upstream)- Project: beads/gastown
- Crew: CREW_NAME
- Binary: bd/gt
Please confirm or correct.
If bead ID provided in $ARGUMENTS:
bd show <BEAD_ID>
Read the bead to understand the issue/feature. Extract: title, description, any linked GitHub issues.
If NO bead ID provided:
bd ready -n 20
Present the ready issues and ask:
Which issue would you like to work on? Pick from the list or provide a bead ID.
After selection, read the full bead with bd show.
Based on the bead type and title, propose a branch name:
fix/<short-kebab-description>feat/<short-kebab-description>chore/<short-kebab-description>Ask user to confirm or adjust the branch name.
Search for an existing upstream GitHub issue:
# If bead mentions a GH issue number
gh issue view <NUMBER> --repo UPSTREAM_OWNER/UPSTREAM_REPO --json title,state,body 2>/dev/null
# Otherwise search by keywords from bead title
gh search issues "<keywords>" --repo UPSTREAM_OWNER/UPSTREAM_REPO --json number,title,state 2>/dev/null | head -5
If found, note the issue number for the PR body (Closes #NNN).
git fetch upstream
git checkout -b <BRANCH_NAME> upstream/main
bd update <BEAD_ID> -s in_progress
Read the relevant source files. Understand the current behavior. Plan the fix/feature.
Use EnterPlanMode if the change is non-trivial. For simple fixes, proceed directly.
Make changes, then verify:
# Quick build (fast iteration)
go build -o ./<BINARY> ./cmd/<BINARY>
# Run targeted tests
go test ./path/to/package/ -run "TestRelevantPattern" -v -count=1
# Manual verification if applicable
./<BINARY> <command-to-test>
Iterate until the fix/feature works correctly.
Before asking user to confirm:
# Full test suite
go test ./...
# Format check
gofmt -l .
# Static analysis
go vet ./...
# Full build with version info
make build
Report any failures. Fix before proceeding.
Present a summary of changes:
git diff --stat
Show what changed and why. Ask:
The fix/feature is implemented and tests pass. Please verify the behavior is correct. Would you like to proceed with creating the PR?
Wait for explicit user approval before proceeding.
Stage and commit with a conventional commit message:
git add <specific-files>
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>
<body explaining what changed and why>
<optional: Closes #NNN or (BEAD_ID)>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
EOF
)"
Commit message conventions:
fix, feat, docs, chore, refactorCloses #123 or (bd-xxx)git push -u origin <BRANCH_NAME>
gh pr create --repo UPSTREAM_OWNER/UPSTREAM_REPO \
--head FORK_OWNER:<BRANCH_NAME> \
--title "<type>(<scope>): <description>" \
--body "$(cat <<'EOF'
## Summary
<2-3 bullet points explaining the change>
## Problem
<What was wrong / what was missing>
## Solution
<What this PR does to fix/add it>
## Before / After
<If applicable, show behavior change>
## Testing
- <How the change was tested>
- <Relevant test commands>
<optional: Closes #NNN>
EOF
)"
PR body guidelines:
Show the user the PR URL so they can review it on GitHub.
If the branch has multiple commits, squash to one:
# Soft-reset to branch point and re-commit
git reset --soft upstream/main
git commit -m "<type>(<scope>): <squashed description>
Co-Authored-By: Claude Opus 4.6 <[email protected]>"
Note the squashed commit hash.
git checkout main
git cherry-pick <BRANCH_NAME>
If cherry-pick conflicts (rare for fresh work):
# Resolve conflicts
git add <resolved-files>
git cherry-pick --continue
git push origin main
make install
Verify:
<BINARY> version 2>/dev/null || <BINARY> --version 2>/dev/null
git rev-parse --short HEAD
Confirm the version hash matches HEAD.
Discover and update rig directories:
# Find rig directories for this project
GT_HOME="${GT_HOME:-$HOME/gt}"
ls -d "$GT_HOME"/*/mayor/rig "$GT_HOME"/*/refinery/rig 2>/dev/null
# Filter to those tracking the same fork
For each rig directory:
cd <RIG_DIR>
git status --porcelain
# If dirty: git stash
git fetch origin && git pull --rebase origin main
# If stashed: git stash pop
bd doctor --fix
# or gt doctor --fix (depending on project)
Report any issues.
bd close <BEAD_ID> -r "Fixed in PR #<PR_NUMBER>: <PR_URL>"
git checkout main
Present final summary:
================================================================
FEATURE BRANCH PR COMPLETE
================================================================
Branch: <BRANCH_NAME>
PR: <PR_URL>
Bead: <BEAD_ID> (closed)
Cherry-picked to main: <COMMIT_HASH>
Binary installed: <BINARY> @ <VERSION>
Rig clones updated: <list>
Doctor: <pass/issues>
================================================================
| Issue | Solution |
|---|---|
| Tests fail on feature branch | Fix before proceeding. Don't submit broken PRs. |
| Cherry-pick conflicts with main | Main has other cherry-picks. Resolve on main, or rebuild main from upstream + cherry-picks. |
| PR branch has upstream's cherry-pick too | You branched from origin/main not upstream/main. Start over from upstream/main. |
gh pr create fails with "head not found" | Push the branch first (git push -u origin <branch>). |
| Multiple commits on feature branch | Squash before cherry-picking to main (step 4.1). |
| Build fails after cherry-pick to main | Cross-branch collision with another cherry-pick. Fix on feature branch, re-squash, rebuild main. |
Never:
origin/main (use upstream/main for clean PRs)main branchAlways:
npx claudepluginhub xexr/marketplace --plugin feature-branch-prSyncs beads forks with upstream steveyegge/beads repo, updates bd binary, and cleans merged PR branches in crew clone directories. Triggers on sync upstream or branch cleanup phrases.
Automates PR creation with upstream tracking and validates branch setup. Prevents common git errors using GitHub CLI best practices.
Guides Git branch management and GitHub PR workflows using main-branch development, modern git switch/restore commands, and MCP tools for creating, listing, and updating PRs.