| name | stack-create |
| description | Use when the user says "create a stacked branch", "start a new branch on top of the current one", or "add a layer to the stack" — creates a new git branch whose parent is the currently checked-out branch and registers it in the stack graph so subsequent stack-submit and stack-restack know the lineage. |
| when_to_use | Reach for this when starting work that should sit on top of the current branch rather than on main/master. The branch is created locally; no push or PR happens here. Do NOT use to open or refresh pull requests — stack-create only makes the branch and records the lineage; use /stack-submit to open or refresh PRs. |
| disable-model-invocation | true |
| allowed-tools | ["Bash(git *)"] |
| argument-hint | <new-branch-name> |
| scheduling | user wants a new branch stacked on the current branch, with lineage recorded in the stack graph |
| structural | ["Resolve the current branch name via git symbolic-ref","Create the new branch with git checkout -b","Record the relationship in the stack graph via stack-graph.sh set"] |
| logical | the new branch exists locally, HEAD points at it, and stack-graph.json contains an entry mapping new-branch → {parent, parent_sha_at_stack_time, pr_number:null} |
/stack-create — Create a Stacked Branch
Create a new branch on top of the currently checked-out branch, then register the parent/child relationship in the stack graph. The PR number is left null until /stack-submit fills it.
Execution Checklist
Example Pairs
Pair 1 — branch created on a feature branch
Input:
Current branch: feat-auth
Command: /stack-create feat-auth-tests
Output (stack-graph.json entry for feat-auth-tests):
{
"parent": "feat-auth",
"parent_sha_at_stack_time": "a3f8c21d9e04b657c12890f1234567890abcdef0",
"pr_number": null
}
Pair 2 — branch stacked on main
Input:
Current branch: main
Command: /stack-create feat-login
Output (stack-graph.json entry for feat-login):
{
"parent": "main",
"parent_sha_at_stack_time": "b7d01f4e2a39c8556d78901e2345678901bcdef1",
"pr_number": null
}
What the Recorded SHA Means
parent_sha_at_stack_time is the SHA of the parent branch tip at the moment the stack relationship was created. /stack-reparent uses this value as the <old-base> argument to git rebase --onto when the parent branch was squash-merged and its commits now appear duplicated on the child. Without this recorded SHA, the squash-merge recovery case cannot be handled deterministically.
Known Failure Modes
- Detached HEAD at invocation.
git symbolic-ref --short HEAD exits non-zero when HEAD is detached. Stop immediately and tell the user to check out a named branch first — there is no parent to record.
- Branch name already exists.
git checkout -b fails if the branch name is already in the repo. The stack graph is not modified in this case; no cleanup is needed.
