stack-plan

name	stack-plan
description	Use when you need to plan commits, restructure a stack, or commit uncommitted work as organized atomic commits. Builds a stack from a description, uncommitted work, or existing commits INSTEAD of manual git rebase -i, git reset --soft, or ad-hoc git move sequences. Prevents: wrong commit ordering, forward references, git move -F panics, untested intermediates.
argument-hint	<plan | range | (none for working tree)>
disable-model-invocation	true
compatibility	Requires git-branchless

Plan and execute a commit stack. Determines mode automatically based on input:

• From a plan/description — user describes what needs to be built; skill produces the commit ordering and executes it
• From uncommitted work — working tree has changes; skill classifies and commits them as an atomic stack
• From existing commits — range like main..HEAD; skill restructures into a clean atomic stack

Pre-flight

1. Load references — read references/philosophy.md and references/git-branchless.md (relative to this skill's directory) before proceeding.

2. Check branchless init:

   if [ ! -d ".git/branchless" ]; then git branchless init; fi
   

3. Check for stale rebase state:

   ls .git/rebase-merge .git/rebase-apply 2>/dev/null
   

   If present, run git rebase --abort before proceeding.

Determine Mode

Examine $ARGUMENTS and repo state to select the mode:

• If $ARGUMENTS contains --root or requests a from-root restructure → Restructure mode (from-root)
• If $ARGUMENTS looks like a commit range (main..HEAD, hash1..hash2, branch name) → Restructure mode
• If $ARGUMENTS is a natural-language description of work to do → Plan mode
• If $ARGUMENTS is empty and the working tree has uncommitted changes → Working tree mode
• If $ARGUMENTS is empty and the working tree is clean → ask the user what they want to do

Plan Mode

The user describes work to be done. Build the stack from scratch.

1. Understand the task from $ARGUMENTS. If the description is vague, ask clarifying questions.

2. Design the commit stack following the ordering in references/philosophy.md:

   1. Refactoring / cleanup (separate from feature work, always first)
   2. Dependencies / build config changes
   3. Scaffolding / types / interfaces / schemas
   4. Core business logic
   5. Edge cases / error handling
   6. Tests

   For each commit, note:

   • One-sentence commit message (Conventional Commits format)
   • Which files will be created or modified
   • Estimated line count (target 50-200 per commit)
   • Dependencies on prior commits (no forward references)

3. Verify no forward references: each commit must only reference files, imports, and config that exist in it or earlier commits. Documentation goes WITH the feature it documents. Dependencies arrive in the commit that first uses them.

4. Present the plan to the user:

   Proposed stack (N commits):
   
   1. type(scope): description — files X, Y (~80 lines)
   2. type(scope): description — files A, B (~120 lines)
   3. type(scope): description — files C, D, E (~150 lines)
   ...
   

   Wait for user approval. Adjust if they have feedback.

5. Execute the plan — implement each commit in order:

   # Write the code for commit 1
   git add <files>
   git commit -m "type(scope): description"
   
   # Write the code for commit 2
   git add <files>
   git commit -m "type(scope): description"
   

   After each commit, verify the codebase is in a working state.

Working Tree Mode

Uncommitted changes exist. Classify and commit them as a stack.

1. Survey the changes:

   git status --short
   git diff --stat
   git diff
   

   Read the full diff. Count total lines changed.

2. Classify every change into logical groups following the ordering in references/philosophy.md. For each group, note:

   • Which files and hunks belong to it
   • A one-sentence commit message
   • Estimated line count (target 50-200 per commit)

   If a file has changes spanning multiple groups, it will need git add -p to split hunks across commits.

3. Present the plan to the user (same format as Plan mode step 4). Wait for user approval.

4. Commit each group in plan order:

   # For file-level grouping:
   git add <file1> <file2>
   git commit -m "type(scope): description"
   
   # For hunk-level splitting within a file:
   git add -p <file>
   git commit -m "type(scope): description"
   

   After each commit, verify nothing was missed or double-counted:

   git diff --stat   # remaining uncommitted changes
   

Restructure Mode

Existing commits need to be reorganized into a clean atomic stack.

1. Parse the range from $ARGUMENTS. Resolve to a <base> and <tip>:

   # For range syntax (base..tip):
   BASE=<resolved base>
   TIP=<resolved tip>
   
   # For a branch name, find the merge-base:
   BASE=$(git merge-base main <branch>)
   TIP=<branch>
   
   # For --root (entire history):
   BASE=<empty tree>
   TIP=HEAD
   

2. Understand the current state:

   git sl
   git log --oneline --reverse $BASE..$TIP   # or --root for from-root
   git log --reverse --stat --format="=== %h %s ===" $BASE..$TIP
   git diff --stat $BASE..$TIP
   
   # From-root (no base commit):
   git log --oneline --reverse --root
   git log --reverse --stat --format="=== %h %s ===" --root
   git diff --stat $(git hash-object -t tree /dev/null) HEAD
   

   Read the full diff and per-commit stats. Count total lines changed.

3. Classify every change into logical groups (same as Working Tree mode step 2).

4. Identify files with intermediate states: before planning the commit sequence, list every file that will have DIFFERENT content across multiple commits (e.g. README.md, CLAUDE.md, flake.nix growing incrementally). For each, note what content exists at each commit boundary. This prevents accidentally committing the final version too early and having to reset.

5. Present the plan (same format as Plan mode step 4). Wait for user approval.

6. Check for uncommitted work before flattening:

   git status --short
   

   If there are uncommitted changes, warn the user and ask whether to stash or commit them first.

7. Create a backup branch:

   git branch backup-before-restructure
   

   If a branch with this name already exists, delete it first or use a unique name (e.g., backup-restructure-$(date +%s)).

8. Save the tree hash for post-verification:

   FINAL_TREE=$(git rev-parse HEAD^{tree})
   

9. Flatten the range into the working tree:

   # Standard range (has a base commit):
   git reset --soft $BASE
   git restore --staged .
   
   # From-root (no base commit):
   git checkout --orphan restructure-wip
   git reset
   # Note: git-branchless hook will panic on orphan branches — this is
   # harmless. The checkout succeeds. Suppress noise with:
   #   2>&1 | grep -v "^branchless:"
   

   Verify the working tree matches the original diff:

   # Standard range (files are unstaged):
   git diff --stat   # should match step 2's total diff
   
   # From-root (all files are untracked after orphan+reset):
   git status --short | wc -l   # should match step 2's file count
   

10. Commit each group in plan order (same as Working Tree mode step 4). For files with intermediate states (identified in step 4), use the Write or Edit tool to set the correct content BEFORE staging for each commit. Do not rely on the final working tree content — it represents the end state, not intermediate states.

Post-execution

1. Move branch pointer (from-root only):

   # If on orphan branch, move main to the new history:
   git checkout -B main
   

2. Verify the result:

   git sl
   git log --oneline --reverse
   

   Show the user the new stack.

3. Confirm total diff is identical (Restructure mode only — $BASE is only defined in Restructure mode, not Working Tree mode):

   # Standard range:
   git diff $BASE..HEAD --stat   # should match the original
   
   # From-root (compare tree hashes):
   test "$(git rev-parse HEAD^{tree})" = "$FINAL_TREE" && echo "trees match"
   # Or compare against backup:
   git diff backup-before-restructure HEAD --stat
   

4. Clean up stale artifacts: check for self-referencing symlinks or other working tree debris:

   git status --short   # should be clean
   

   Remove any untracked artifacts that weren't in the original tree.

5. Run tests if a test command is identifiable:

   git test run -x '<test-command>' 'stack()'
   

   Report any commits that break the build.

Tips

• Don't lose changes. After flattening, double-check git diff --stat matches the original range diff. If anything is missing, stop and investigate.
• Prefer git add <files> over git add -p when the changeset groups by file without needing hunk splitting.
• Respect user-requested commit boundaries — not every restructure needs to flatten everything.
• From-root restructures flatten the entire history. Use git checkout --orphan + git reset (not git reset --soft which needs a parent commit). The branchless hook will panic — ignore it.
• Intermediate file states are the #1 source of rework. Files like README.md and CLAUDE.md that grow across many commits must be written with partial content at each step. Plan these states BEFORE flattening.
• For files with complex structure (nested sections, cross-references), a full rewrite at the appropriate commit is often cleaner than incremental Edit operations that can cause structural nesting errors.
• Sentinel commits (TODO.md, CHANGELOG.md) must stay at the tip of the stack. When adding new commits, check the tip first — if it's a sentinel, insert before it or move it back to tip afterward with git move -x <sentinel-hash> -d HEAD.
• Avoid scripted GIT_SEQUENCE_EDITOR reorders when files are built incrementally. Use git move -x <hash> -d <dest> for individual commit reorders — it's in-memory and avoids context-dependent conflicts.