synapseradio/stax

Stax Context Engineering Runbook

Stax replaces most git branch, rebase, push, and PR commands with stack-aware equivalents. Consult the routing table below before running any git command. If stax can handle it, use stax.

Stax First — Default Routing

Before running any git command, check this table. If stax has an equivalent, use it.

| Instead of (git / gh) | Use (stax) | Notes | |------------------------|------------|-------| | git checkout -b <name> | stax create <name> | Creates branch + tracks parent | | git branch -d <name> | stax branch delete | Removes branch + metadata | | git branch -m <name> | stax rename <name> | Renames + updates metadata | | git checkout <branch> | stax checkout <branch> | Stack-aware checkout | | git checkout - | stax prev | Previous branch | | git checkout main | stax trunk | Switch to trunk | | git add . && git commit --amend | stax modify | Stage all + amend | | git add . && git commit --amend -m "msg" | stax modify -m "msg" | Stage all + amend with message | | git rebase <parent> | stax restack | Rebase onto tracked parent | | git rebase --continue | stax continue | After resolving conflicts | | git rebase --abort | stax abort | Abort rebase | | git push -u origin <branch> | stax submit --no-pr --yes --no-prompt | Push without PR | | git push && gh pr create | stax submit --yes --no-prompt | Push + create/update PR | | gh pr merge | stax merge --yes | Merge from bottom of stack up | | gh pr view --web | stax pr | Open PR in browser | | gh pr checks | stax ci | CI status for stack | | gh pr view --comments | stax comments | PR comments | | git fetch && git pull (trunk) | stax sync | Pull trunk + delete merged | | git fetch && git rebase origin/main | stax sync --restack | Sync + restack all | | git log --oneline --graph | stax log | Stack-aware commit graph | | git diff <parent>..HEAD | stax diff | Diff per branch vs parent | | git branch (list) | stax status | Stack tree view | | git push --force-with-lease | stax submit --yes --no-prompt | Stax handles force-push | | git rebase <parent> && git push | stax cascade | Restack + submit in one |

Full mapping with edge cases: references/stax-first.md

Git Fallback — No Stax Equivalent

These operations have NO stax equivalent. Use git directly.

| Operation | Command | Why | |-----------|---------|-----| | Selective staging | git add <file> | stax modify stages ALL changes | | New commit (not amend) | git commit -m "msg" | stax modify only amends; stax create makes a new branch | | Stash | git stash / git stash pop | No equivalent | | Blame | git blame <file> | No equivalent | | Cherry-pick | git cherry-pick <sha> | No equivalent | | Tags | git tag | No equivalent | | File-level log | git log -- <file> | No equivalent | | File-level diff | git diff -- <file> | stax diff is whole-branch | | Clone | git clone | No equivalent | | Remote management | git remote | No equivalent | | Git config | git config | Use stax config for stax settings only |

Context Loading

Load references only when needed:

| Situation | Load | Skip | |-----------|------|------| | Need exact flags for a command | references/commands.md | workflows, concepts | | Multi-step workflow (submit stack, merge, recover) | references/workflows.md | commands, concepts | | Understanding stack model or risk levels | references/concepts.md | commands, workflows | | Deciding git vs stax for an operation | references/stax-first.md | commands, workflows | | Simple create/modify/submit | Nothing extra — SKILL.md is sufficient | all references |

Quick Reference

Visualization

| Command | What it shows | Key flags | |---------|--------------|-----------| | stax status | Simple tree view | --json, --current, --compact | | stax ll | Tree + PR URLs + details | --json, --current | | stax log | Tree + commits + PR info | --json, --current | | stax diff | Diff per branch vs parent | --all | | stax ci | CI status for stack | --json, --watch, --stack |

Creating & Committing

| Command | What it does | Key flags | |---------|-------------|-----------| | stax create <name> | New branch on current | -m "msg", --from <branch>, -a | | stax modify | Stage all + amend commit | -m "new message" | | stax branch squash | Squash all commits on branch | — | | stax branch fold | Fold branch into parent | — |

Navigation

| Command | Destination | |---------|-------------| | stax checkout <branch> | Named branch | | stax up [N] | N children up (default 1) | | stax down [N] | N parents down (default 1) | | stax top | Tip/leaf of stack | | stax bottom | First branch above trunk | | stax trunk | Trunk branch | | stax prev | Previous branch (like git checkout -) |

Sync & Restack

| Command | What it does | Key flags | |---------|-------------|-----------| | stax sync | Pull trunk, delete merged | --restack, --prune, --force | | stax restack | Rebase current onto parent | --all, --yes, --dry-run | | stax cascade | Restack all + submit | --no-submit, --no-pr |

Submitting

| Command | Scope | Key flags | |---------|-------|-----------| | stax submit | Current + ancestors | --yes --no-prompt, --draft, --no-pr | | stax branch submit | Current branch only | Same as submit | | stax upstack submit | Current + descendants | — | | stax downstack submit | Ancestors + current | — |

Merging

| Command | What it does | Key flags | |---------|-------------|-----------| | stax merge | Merge PRs bottom-up to current | --yes, --method, --when-ready, --dry-run |

Agent-Specific Patterns

Non-Interactive Flags

Always use these when running stax commands in agent/automated context:

| Flag | Commands that support it | Purpose | |------|-------------------------|---------| | --yes | submit, merge, restack, detach, reorder, fix, undo, redo | Auto-approve prompts | | --no-prompt | submit | Disable interactive prompts entirely | | --quiet | status, ll, log, submit, modify, sync, restack, undo, redo | Suppress extra output | | --json | status, ll, log, ci, standup, changelog | Machine-readable output |

Standard agent invocation pattern: stax <command> --yes --no-prompt --quiet

JSON Output for Parsing

Use --json when you need to parse command output:

stax status --json          # stack structure as JSON
stax ci --json              # CI check results as JSON
stax ll --json              # branches + PR URLs as JSON

Interactive-Only Commands (NEVER use in agent mode)

| Command | Why | Alternative | |---------|-----|-------------| | stax split | Opens interactive editor | Advise user to run manually | | stax reorder | Opens interactive reorder UI | Use stax branch reparent for targeted moves | | stax rename (no args) | Prompts for name | Always pass name: stax rename <name> | | stax checkout (no args) | Interactive picker | Always pass branch: stax checkout <branch> |

Common Compositions

New feature stack → submit → merge:

stax sync && stax create feature-a -m "Add feature A" && stax modify && stax submit --yes --no-prompt

Respond to PR feedback:

stax checkout <branch> && stax modify -m "Address review feedback" && stax cascade

Full sync + restack + submit:

stax sync --restack && stax submit --yes --no-prompt

Check stack health before submitting:

stax validate && stax doctor && stax submit --yes --no-prompt

More workflows: references/workflows.md

NEVER

• NEVER git checkout -b — use stax create
• NEVER git push / git push --force-with-lease — use stax submit
• NEVER git rebase <branch> — use stax restack
• NEVER stax modify for selective staging — it stages ALL changes. Use git add <files> && git commit --amend for selective amend, or git add <files> && git commit for a new commit.
• NEVER stax split in agent mode — it requires interactive input
• NEVER stax reorder in agent mode — it requires interactive input
• NEVER stax checkout without a branch argument — it opens an interactive picker
• NEVER stax rename without a name argument — it prompts interactively
• NEVER run stax submit without --yes --no-prompt in agent mode — it may prompt
• NEVER git merge to merge stacked PRs — use stax merge which handles the bottom-up order

Rules

1. Sync before starting new work. Run stax sync before stax create to ensure you're building on the latest trunk.
2. Use --yes --no-prompt for all agent operations. Any stax command that might prompt must include these flags.
3. Check stax status before navigation. Understand the stack structure before using up/down/checkout.
4. Prefer stax cascade over manual restack+submit. It handles the full restack-from-bottom then submit flow.
5. Use stax resolve for AI conflict resolution. When restack hits conflicts, try stax resolve before manual resolution.
6. One branch = one logical change. Each stacked branch should be a single reviewable unit.
7. Use stax modify not git commit --amend. Stax modify handles staging and metadata updates.
8. Use stax merge --when-ready for unattended merges. It polls CI and waits for approval.
9. Check CI before merging. Run stax ci --stack to verify all checks pass.
10. Use stax undo for recovery. If a stax operation goes wrong, stax undo --yes reverts it.

Exit Check

After using stax, verify:

• [ ] No raw git checkout -b, git push, git rebase was used where stax has an equivalent
• [ ] All agent-mode commands include --yes --no-prompt where supported
• [ ] No interactive commands (split, reorder, argument-less checkout/rename) were used
• [ ] stax sync was run before creating new branches
• [ ] stax status was consulted to understand stack structure before navigation