branch-pr

branch-pr: Branch & Draft PR Creation

Set up a working branch and draft pull request for a GitHub issue.

Arguments

• $ACTION: The action to perform (create, push)
• $ISSUE_NUMBER: The GitHub issue number
• $FEATURE_SLUG: Kebab-case feature name (used in branch name and task directory)
• $ISSUE_TITLE: The issue title (used in PR title)
• $REPO: Repository in owner/repo format (optional, defaults to current repo)
• $REQ_ID: Requirement ID like REQ-001 (optional, for traceability in commit messages)
• $NANO_SPEC_PATH: Path to the nano-spec task directory to commit (optional)
• $STACK_ON_BRANCH: Head branch of a parent dev-loop PR to stack on top of (optional). When set, the new branch is cut from this ref and the draft PR's base is this branch instead of the repo default.
• $STACK_ON_PR: PR number of the parent (optional, used only for the body note). Pair with $STACK_ON_BRANCH.

Actions

create

Create a branch, push it, create a draft PR, and optionally commit nano-spec files.

Usage: branch-pr create

Steps:

1. Construct the branch name: dev-loop/<issue-number>-<feature-slug>.
2. Decide the base ref:
   • If $STACK_ON_BRANCH is set, fetch and use it as the base:

     git fetch origin $STACK_ON_BRANCH
     git checkout -b dev-loop/$ISSUE_NUMBER-$FEATURE_SLUG origin/$STACK_ON_BRANCH
     

   • Otherwise, branch from the current HEAD (assumed to be the default branch checked out fresh):

     git checkout -b dev-loop/$ISSUE_NUMBER-$FEATURE_SLUG
     

3. Push the branch:

   git push -u origin dev-loop/$ISSUE_NUMBER-$FEATURE_SLUG
   

   Add --repo $REPO to gh commands if $REPO is provided.
4. Create a draft PR linking to the issue. Add --base $STACK_ON_BRANCH when stacking, and include a Stacked on #<parent-pr> line in the body so reviewers see the relationship.
   • Unstacked:

     gh pr create --draft --title "$ISSUE_TITLE" --body "Closes #$ISSUE_NUMBER
     
     Automated implementation by dev-loop agent."
     

   • Stacked:

     gh pr create --draft --base "$STACK_ON_BRANCH" --title "$ISSUE_TITLE" --body "Closes #$ISSUE_NUMBER
     
     Stacked on #$STACK_ON_PR. GitHub will retarget this PR's base to the default branch when the parent merges.
     
     Automated implementation by dev-loop agent."
     

5. If $NANO_SPEC_PATH is provided, commit those files:

   git add $NANO_SPEC_PATH
   git commit -m "docs: add nano-spec plan for #$ISSUE_NUMBER [REQ-XXX]"
   

   Include [REQ-XXX] only if $REQ_ID is available.
6. Push the commit.
7. Return the PR number, URL, and base ref for use by subsequent steps.

Output Format (create)

Branch: dev-loop/<issue-number>-<feature-slug>
Base: <main | $STACK_ON_BRANCH>
PR: #<pr-number> (<pr-url>)
Commit: <sha> (nano-spec files, if committed)

---

push

Push the current branch to its remote tracking branch.

Usage: branch-pr push

Steps:

1. Push the current branch:

   git push
   

2. If no upstream is set, push with -u origin <current-branch>.

Output Format (push)

Pushed: <branch-name> -> origin/<branch-name>