stax: Rust CLI for stacked Git branches and PRs. Branch metadata lives in git refs (refs/branch-metadata/<branch>, trunk in refs/stax/trunk), compatible with freephite. Everything else is discoverable from src/; this file only covers what isn't.
For this Nick-Motion/stax fork, land verified changes on local main and push to nick/main. Do not create pull requests. Keep origin as the upstream source. Preserve existing histories with normal merges or fast-forwards; never force-push main.
Keep the harness's planning, independent review, and verification gates. Its release manager must commit the verified result, fast-forward local main to it, and push only nick/main. This policy overrides the automatic draft-PR and no-main-delivery instructions in the harness and agent definitions below.
Goal: Accelerate stax feature development and bug fixing via a git-native worktree → plan → implement → review → verify → (optional) benchmark → commit → draft-PR pipeline with a bounded repair loop.
Trigger: For any code change to the stax CLI (new commands, flags, bugfixes, refactors, behavior changes), run the /stax-dev prompt. It orchestrates the project-local stax-planner, stax-implementer, stax-reviewer, stax-verifier, stax-benchmarker, and stax-release-manager definitions under .claude/agents/. The former .pi/agents/ definitions were intentionally moved to personal dotfiles and are not the project harness. Direct usage/architecture questions don't need the pipeline. Each task runs in its own worktree on a stacked branch; commit + current-branch-only draft PR submission (stax branch submit --draft --ai --yes) is automatic when the applicable gate is green; merging to main is never automatic and promoting a draft to ready-for-review is HITL-gated.
Change History:
| Date | Change | Target | Reason |
|---|---|---|---|
| 2026-07-25 | Initial harness build (5 agents, 5 skills, /stax-dev orchestrator) |
All | New harness |
| 2026-07-25 | Git-native evolution: added benchmarker (optional perf gate) + stax-benchmark skill; worktree-per-task + stacked branch; auto commit-on-green + auto draft PR; hard "never merge to main" rule |
benchmarker.md, stax-benchmark/, release-manager.md, codex.md, stax-release/, stax-dev.md | Adopt git-native workflow constraints; keep verifier as mandatory correctness gate |
| 2026-07-28 | Added fallbackModels: claude-bridge/claude-sonnet-4-6 to the four cursor/composer-2.5 agents so a provider outage (quota/auth/timeout) auto-routes instead of stalling the run; codex also falls back to openai-codex/gpt-5.6-terra. Extended benchmarker skip rule to cover pure delegation/deletion diffs with no new local hot-path work |
codex.md, verifier.md, benchmarker.md, release-manager.md | Cursor was down + OpenAI-Codex usage-limited mid-run (stax-dev-03), forcing manual model overrides; benchmarker also burned time trying to bench a no-local-compute change |
| 2026-08-26 | Split verification into a fast scoped draft gate and a full CI/ready-for-review gate | AGENTS.md, verifier.md, stax-verify/, stax-dev.md | Avoid repeating the process-heavy full integration suite in every isolated worktree while retaining full validation before review or merge |
| 2026-08-27 | Reconciled the project-local harness with its documented git-native pipeline: added independent review, optional benchmark, bounded repair artifacts, and release ownership with current-branch-only draft submission | .claude/agents/, .claude/skills/stax-dev/, skills.md, AGENTS.md |
Restore the missing commit/draft-PR path and keep full-stack submit, undraft, and merge outside automation |
cargo nextest run <filter> # scoped tests; a module prefix works, e.g. status_tests::
make lint-fast # fmt check + clippy; run while iterating
make lint # full lint gate
make test # full suite; see rules below- Never run the full suite with
cargo test(process-heavy, exhausts file handles). Usemake test. - Use
make lint-fastand focused nextest runs for the scoped draft gate; usemake lintandmake testfor the full gate or high-risk changes. - On macOS
make testneeds Docker. If the daemon is down, ask the user to start it instead of falling back tomake test-native. - Use the Make lint targets, not ad hoc
cargo clippy, so flags match CI. - State in the PR description whether evidence is a scoped run, a full local run, or CI.
- Draft PR gate (default): run
cargo check,make lint-fast,git diff --check, and focusedcargo nextest run <pattern>coverage for the changed behavior. Reviewer and verifier must pass, but localmake lintandmake testare not required merely to commit and open a draft PR. - Full gate: CI must run
make lintandmake testbefore a draft is promoted to ready-for-review or merged. If CI is unavailable, run both commands locally on the exact PR head. - High-risk exception: run the full local gate before opening the draft when the change touches shared/core execution (
engine/,git/repo.rs,ops/), build or test infrastructure, broad cross-cutting behavior, or security-critical behavior. The verifier may widen scope when concrete risk warrants it, and must explain why. - PR descriptions and verification artifacts must say whether evidence came from the scoped draft gate, the full local gate, or CI.
- AI agents: when full-suite validation is required, always run
make test. On macOS this routes through Docker, which is the only sane way to run the entire integration suite —cargo testnatively will be slow, flaky, and may exhaust file handles. Do not run a full suite for every localized draft by default; follow the verification tiers above. - Start Docker before running
make test. On macOS the Docker daemon is not always running; ifmake testfails because the Docker API is unavailable, ask the user to launch Docker Desktop instead of falling back tomake test-native. - Do not run the full suite via
cargo testin this repo. - For full-suite validation, always use
make test. - On macOS,
make testintentionally routes to the Docker fast path. - Use native paths only when explicitly needed:
make test-native(guarded nextest path; validates the file-descriptor limit)make test-local-ramdiskmake test-local-fast
- Targeted runs via
cargo nextest run <pattern>are required for the scoped draft gate and encouraged for tight feedback loops. Switch tomake testwhen the full gate or high-risk exception applies. - Full test runs (
make test, including native Linux fallback, plusmake test-docker/make test-container) use thetest-containerCargo profile (no debuginfo) and shared env (STAX_DISABLE_UPDATE_CHECK,RUST_MIN_STACK, capped/sanitizedNEXTEST_TEST_THREADS). Container runs also use the pre-bakedstax-testimage (make test-image) and mold linker. CI uses the sametest-containerprofile and mold onubuntu-latest. For tight iteration, prefercargo nextest run --lib --binsor a module filter. - All integration tests compile into a single binary (
tests/all_tests.rs, withautotests = falseinCargo.toml) so cargo links one test binary instead of ~50 — this is what keeps test builds fast. Because of this, there is only one[[test]]target namedall_tests:cargo test --test status_testsno longer works. To scope a run, filter by module path, e.g.cargo nextest run status_tests::. When adding a newtests/*_tests.rsfile, register it with a#[path = "..."] mod ...;entry intests/all_tests.rs.
- This suite is process/filesystem heavy (
git+staxsubprocesses), and Linux Docker is dramatically faster and more stable than native macOS for full runs. - Native macOS performance remains sensitive to endpoint-security tooling; do not assume a warm native timing will match Docker.
- During implementation, use
make lint-fastfor formatting plus Clippy on library and binary targets. - Before opening a draft PR,
make lint-fastis sufficient when the scoped draft gate applies. Runmake lintfor the full gate or high-risk exception. - Use these Make targets instead of ad hoc
cargo clippycommands so local and CI lint flags stay aligned.
src/application/is presentation-neutral: noprintln!, stdin/stdout,commands/,tui/, or UI crates (dialoguer,ratatui,console).make lintenforces it. Put UI incommands/ortui/.- Commands that must work outside a repo (
setup,auth,config,doctor,web) are dispatched beforeensure_initialized()insrc/cli/mod.rs. Add new repo-less commands there, or they triggerinit. - Rebasing descendants (
restack,merge,sync --restack) must preserveparent_branch_revisionand usegit rebase --onto <new> <old>. A plaingit rebase <trunk>replays squash-merged history. - When merging stacks, rebase and retarget children before deleting the base branch, or GitHub auto-closes their PRs.
- Walk the branch graph iteratively with cycle detection. Metadata can be corrupted, so never recurse over it.
- Stack colors come from
src/commands/stack_palette.rs; don't add per-command palettes. - Send progress and prompts to stderr so
--jsonand piped stdout stay clean. - A new config option needs an entry in
src/config/default_config.toml.
learnings.md has more lessons on TUI/picker rendering, shell integration, worktree removal, and CI timing. Read the relevant part before touching those areas.
- Cover the happy path, the error path, and edge cases. Prefer integration tests that run the real
staxbinary in a temp repo; a new command or flag needs at least one. - All integration tests compile into ONE binary,
tests/all_tests.rs. Register a newtests/<name>_tests.rsthere with#[path = "<name>_tests.rs"] mod <name>_tests;and import helpers withuse crate::common;.cargo test --test <name>won't work; filter by module path. - Tests must be hermetic: no GitHub tokens, no user
STAX_*env, nullGIT_CONFIG_GLOBAL/GIT_CONFIG_SYSTEM. Never callenv::set_var/remove_var; configure the child command (lint enforces this).
When a change touches user-visible behaviour — new commands, changed flags, renamed concepts, removed features, or updated defaults — the following must also be updated in the same PR:
README.md— if the change affects the quick-start, core commands table, key capabilities, or any section a first-time user would read.docs/— the relevant page(s) underdocs/commands/,docs/workflows/,docs/configuration/, etc.; keep one canonical page per command.skills.md— the command map, high-value flags, workflow examples, best practices, or tips that reference the changed behaviour. This file is consumed by AI coding agents, so stale entries actively cause failures.
If none of these files need updating, leave a one-line note in the PR description explaining why. Check flags against stax --help.