stack-create

Stack Create

Initialize a stacked branch set from a multi-step plan. Each logical slice of the plan becomes one branch targeting the previous slice's branch as its base.

When To Use

Use stack-create when a plan produces 2 or more ordered changes where each change depends on the previous one completing (and merging) before it can land. For independent changes, use parallel worktrees instead (see egregore).

When NOT To Use

• A single independent change, which should branch normally instead
• The stack exists and needs publishing (use sanctum:stack-push)

Prerequisites

• Git 2.38+ (git version | awk '{print $3}' to check)
• gh CLI authenticated
• A written plan with ordered slices (from do-issue or attune:blueprint)
• Clean working tree on the base branch (git status)

Required Progress Tracking

Create TodoWrite items before starting:

1. stack-create:git-version-checked
2. stack-create:slices-identified
3. stack-create:branches-created
4. stack-create:stack-verified

Step 1: Verify Git Version (git-version-checked)

git version

Confirm the output is 2.38.0 or higher. If not, the --update-refs flag is unavailable. Warn the user and fall back to manual branch tracking.

Check for optional jj accelerator:

if command -v jj &>/dev/null && jj root &>/dev/null 2>&1; then
  echo "jj available"
else
  echo "using git --update-refs"
fi

Step 2: Identify Slices (slices-identified)

Read the plan and extract ordered slices. Each slice must satisfy:

• A single logical concern (one PR worth of change)
• A clear dependency on the slice before it (if any)
• A short name suitable for a branch suffix

Example slices for a plan with three parts:

Slice 1: add-schema     -- database schema changes
Slice 2: add-api        -- API layer (depends on schema)
Slice 3: add-ui         -- frontend (depends on API)

Record the slice list before creating branches.

Step 3: Create Branches (branches-created)

Starting from the base branch (usually master or main):

BASE=master
STACK=stack/my-feature

# Slice 1 branches from master
git checkout -b ${STACK}/add-schema ${BASE}

# Slice 2 branches from slice 1
git checkout -b ${STACK}/add-api ${STACK}/add-schema

# Slice 3 branches from slice 2
git checkout -b ${STACK}/add-ui ${STACK}/add-api

Convention: stack/<feature-name>/<slice-name>

Return to the first slice branch to begin work:

git checkout ${STACK}/add-schema

jj Accelerator (if available)

# jj creates an empty commit on each branch automatically
# Use jj new to move to a new change
jj new -m "stack: add-schema" --no-edit

Step 4: Verify Stack (stack-verified)

Confirm the branch topology is correct:

git log --oneline --graph \
  ${BASE}..${STACK}/add-ui

Each slice branch should appear as a linear chain above the base.

If jj is available:

jj log --revisions \
  "ancestors(${STACK}/add-ui, 10) & !ancestors(${BASE})"

Notes

• Never push branches until at least one commit exists on each slice (empty branches produce confusing PRs)
• The slice name in the branch becomes the PR title prefix by convention; keep it short and descriptive
• After creating the stack, proceed to stack-push to open PRs, or work slice-by-slice and push when ready
• If the plan changes, add or remove branches manually and re-verify the topology in Step 4

Exit Criteria

• All 4 TodoWrite items (stack-create:git-version-checked through stack-create:stack-verified) are created before branch creation starts and marked complete in order
• Git version confirmed ≥ 2.38.0; if not, fallback to manual branch tracking is documented and the user is warned
• All slice branches created with the naming convention stack/<feature-name>/<slice-name>
• git log --oneline --graph <base>..<tip> shows a linear chain with each slice branch appearing in dependency order
• Working tree returned to the first slice branch after topology is verified