jj-stack 0.1.3__tar.gz → 0.1.5__tar.gz

{jj_stack-0.1.3 → jj_stack-0.1.5}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -26,9 +26,9 @@ jobs:
         run: |
           TOKEI_VERSION="$(
             uv run --no-project --python 3.14 python -c \
-              'from tools.check_complexity import TOKEI_VERSION; print(TOKEI_VERSION)'
+              'from tools.check_complexity import TOKEI_VERSIONS; print(TOKEI_VERSIONS[-1])'
           )"
-          cargo install tokei --locked --version "$TOKEI_VERSION"
+          cargo install tokei --locked --version "^$TOKEI_VERSION"
 
       - name: Install project environment
         run: uv sync --locked
@@ -52,7 +52,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -79,18 +79,13 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
       - name: Install jj
         run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
 
-      - name: Run submit property smoke scenarios
+      - name: Run generated client and server sequences
         run: >-
-          tests/run_submit_property_scenarios.py 10 --random-seed -n auto
-          --stack-join-scenarios 5
-          --lifecycle-scenarios 10
-          --stack-move-scenarios 5
-          --retry-scenarios 5
-          --drift-scenarios 21
+          tests/run_submit_property_scenarios.py 5 --steps 20 --shards 8 --random-seed -n auto

{jj_stack-0.1.3 → jj_stack-0.1.5}/.github/workflows/codeql.yml

@@ -23,10 +23,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4.37.8
+        uses: github/codeql-action/init@v4.37.9
         with:
           languages: python
           build-mode: none
 
       - name: Analyze
-        uses: github/codeql-action/analyze@v4.37.8
+        uses: github/codeql-action/analyze@v4.37.9

{jj_stack-0.1.3 → jj_stack-0.1.5}/.github/workflows/release.yml

@@ -34,7 +34,7 @@ jobs:
           ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -94,7 +94,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 
@@ -127,7 +127,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
         with:
           python-version: "3.14"
 

{jj_stack-0.1.3 → jj_stack-0.1.5}/.gitignore

@@ -10,3 +10,5 @@ htmlcov/
 .uv-cache/
 .venv
 .venv/
+
+.hypothesis/

{jj_stack-0.1.3 → jj_stack-0.1.5}/AGENTS.md

@@ -1,15 +1,15 @@
-## Complexity control
+# Complexity control
 
 - A replacement is incomplete until it deletes the mechanism it supersedes in the same change.
-  Do not add a temporary parallel model with a promise to remove it in a later cleanup slice.
-- Define each jj-stack-owned durable policy fact once and store it one way. Shared observation or
-  storage code must not create a second path for deciding or changing it.
+  Do not keep a parallel model for a later cleanup.
+- Store each persistent fact in one form, with one owner. Shared observation and storage code
+  must not introduce competing policy decisions.
 - Batch independent read-only facts, but keep dependent mutations in order. Bind an irreversible
   external mutation to the identity and version observed while planning when the platform
   supports a conditional write or lease. Re-observe only when an earlier mutation invalidates a
   precondition or when an observed trigger or platform contract requires it.
-- Apply the cumulative complexity budgets after every code slice. Run `just complexity` locally
-  when the pinned `tokei` is installed; CI invokes the underlying checker. A budget increase is a
+- Check the cumulative complexity budgets after each code change. Run `just complexity` locally
+  when a supported `tokei` is installed; CI invokes the underlying checker. A budget increase is a
   design stop that requires explicit review, not routine maintenance of the budget file.
 - If the same subsystem needs a third consecutive hardening change, stop patching it and
   re-derive the design from the core invariants.
@@ -38,25 +38,26 @@
 
 # Documentation
 
-- User-facing docs live in `docs/`. See [docs/AGENTS.md](docs/AGENTS.md) for the vocabulary
-  rules and the public/internal split. Built-in `--help` text is held to the same standard as
-  the user docs: assume jj/git familiarity, avoid `jj-stack` internal design jargon.
+- User-facing docs live in `docs/`, except for contributor notes in `docs/internals/`. See
+  [docs/AGENTS.md](docs/AGENTS.md) for the vocabulary rules and the public/internal split.
+  Built-in `--help` text is held to the same standard as the user docs: assume jj/git familiarity,
+  avoid `jj-stack` internal design jargon.
 - The web version of the user docs normally lives in the sibling jj repository at
   `$(jj root)/../website`. When user-facing docs change here, run `just website`, inspect the
   corresponding website changes, and update them as needed. If the change here is committed,
   commit the corresponding website update in that repository as well; preserve unrelated work in
   either working copy.
 - Active internal docs use ordinary technical language too. Introduce a project-specific term
-  only when it names a real type, field, or enduring rule, define it at first use, and prefer
+  only when it names an existing type, field, or enduring rule, define it at first use, and prefer
   describing concrete inputs and effects.
-- `design.md` and `implementation-strategy.md` describe the current product and architecture, not
-  completed slices or abandoned mechanisms. Keep implementation history in `jj` commits.
-- Default to code and tests only. Update documentation only when a change intentionally adds or
-  changes a supported product rule or user workflow, or makes a specific existing statement
-  materially inaccurate. A bug and its fix are not by themselves a documentation trigger.
+- Internal design and strategy documents describe the current product and architecture. Keep
+  implementation history in `jj` commits.
+- For implementation work, update documentation when a change adds or alters a supported rule or
+  workflow, or makes an existing statement inaccurate. A bug fix alone does not require a docs
+  change. Documentation reviews and corrections can also address clarity, duplication, and gaps.
 - When documentation is required, update only the affected source: `design.md` for an enduring
-  product rule, user docs or `--help` for user guidance, and `implementation-strategy.md` for an
-  architecture, tooling, or test-layer strategy change.
+  product rule, user docs or `--help` for user guidance, and the relevant testing document for
+  test strategy.
 
 # Behaviour changes
 
@@ -67,8 +68,9 @@
   the other way around: evaluate a documented behavior on its merits before extending it, and
   prefer deleting case-specific rules that follow from the principles over adding new ones. Never
   add durable transaction or replay state; recovery is observational (see design.md).
-- Preserve the core invariants: the `jj` DAG determines stack topology, local cache is sparse,
-  GitHub pull requests are derived from the local `jj` stack, and ambiguous linkage fails closed.
+- Preserve the core invariants: the `jj` DAG determines stack topology, tracking stores only PR
+  links and submitted commits, GitHub PRs follow the local stack, and ambiguous linkage stops
+  mutation.
 
 # Testing
 

{jj_stack-0.1.3 → jj_stack-0.1.5}/CONTRIBUTING.md

@@ -13,7 +13,8 @@ discussion.
 
 ## Development setup
 
-You need `uv`, `jj` 0.45.1 or newer, and `just`. Then:
+You need `uv`, Git, `jj` 0.45.1 or newer, and `just`. The project requires Python 3.14 or newer;
+`uv` can provide the interpreter when it creates the locked development environment:
 
 ```console
 just setup
@@ -30,12 +31,31 @@ virtualenv path directly:
 just run view
 ```
 
-Run the standard Ruff, type-check, and test pass before you finish:
+Before finishing a code change, run the standard Ruff, type-check, and test pass. Docs-only edits
+under `docs/` do not require it:
 
 ```console
 just check
 ```
 
+Pyrefly is the default type checker, including a second pass targeting Windows. To select ty
+for the current platform instead, use `--type-checker` or its short form, `-t`:
+
+```console
+just check -t ty
+```
+
+Repeat the option to run several in the given order, for example `just check -t pyrefly -t ty`.
+The runner installs the selected checkers from the lockfile, checks `src`, `tests`, `tools`, and
+`check.py`, and runs the usual Ruff and pytest checks. It stops at the first failed check. ty is
+optional during development and can report issues that Pyrefly does not; its failures are
+reported normally. Plain `just check` and CI continue to use Pyrefly. Before a release, follow the
+[requirement for both type checkers to pass](docs/internals/releasing.md#qualify-the-candidate).
+
+mypy is deliberately not part of the toolchain. It fixes a variable's type at its first
+assignment and rejects a later assignment of another type, which Pyrefly and ty accept, so
+keeping it green required annotations whose only purpose was to satisfy mypy.
+
 Run focused tests while you iterate:
 
 ```console
@@ -43,10 +63,10 @@ just test tests/unit/test_jj_client.py
 ```
 
 CI also enforces the cumulative complexity budgets. Check them locally with `just complexity`
-when the pinned `tokei` is installed. Raising a budget is a design decision, not routine
+when a supported `tokei` is installed. Raising a budget is a design decision, not routine
 maintenance — say why in the pull request.
 
-If your change touches user-facing documentation, refresh the website snapshot with
+If your change touches user-facing guides or references, refresh the website snapshot with
 `just website` and include the resulting change in the sibling `website` repository.
 
 ## Conventions
@@ -62,8 +82,8 @@ The short version:
 - Explain *why* the change exists in the body, wrapped at 72 columns.
 - Add tests at the narrowest layer that covers a distinct risk; consolidate overlapping coverage
   rather than adding parallel cases.
-- Update documentation only when a change adds or alters a supported rule or workflow, or makes
-  an existing statement inaccurate.
+- For code changes, update docs when supported rules, workflows, or existing statements change.
+  Documentation corrections and editorial improvements are welcome independently.
 
 ## Submitting
 

{jj_stack-0.1.3 → jj_stack-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jj-stack
-Version: 0.1.3
+Version: 0.1.5
 Summary: Stacked GitHub pull requests for Jujutsu
 Project-URL: Homepage, https://www.serpentine.com/software/jj-stack/
 Project-URL: Documentation, https://www.serpentine.com/software/jj-stack/
@@ -29,64 +29,26 @@ Description-Content-Type: text/markdown
 # jj-stack: manage stacked GitHub PRs with jj
 
 `jj-stack` turns a linear series of local `jj` changes into a stack of GitHub pull requests.
-Rewrite, split, squash, or reorder the changes with `jj`, then let `jj-stack` update the
-matching PRs.
+Rewrite, split, squash, or reorder the changes with `jj`, then run `jj-stack submit` to update
+GitHub. Existing PRs follow their change IDs, keeping comments and review history together.
 
 ## Quick start
 
-### Requirements
+You need Python 3.14 or newer, `jj` 0.45.1 or newer, and a repo on github.com where you can push
+branches and open pull requests. `jj-stack` uses `GITHUB_TOKEN`, then `GH_TOKEN`, then your GitHub
+CLI login for authentication.
 
-- Python 3.14 or newer
-- `jj` 0.45.1 or newer
-- GitHub authentication
-
-### Install
-
-Install `jj-stack` from PyPI with `uv` in an isolated tool environment (recommended):
+Install with `uv`:
 
 ```bash
 uv tool install jj-stack
 ```
 
-`pipx` provides another isolated installation:
-
-```bash
-pipx install jj-stack
-```
-
-You can also use `pip` inside an activated virtual environment:
-
-```bash
-python -m pip install jj-stack
-```
-
-To upgrade an installation made with `uv`, rerun its command with `--force`. If the command is
-not on your shell `PATH`, run `uv tool update-shell`.
-
-### Invoke it as `jj stack`
-
-Add a command alias to your user configuration with `jj config edit --user`:
-
-```toml
-[aliases]
-stack = ["util", "exec", "--", "jj-stack"]
-```
-
-For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
-your shell startup file:
-
-```bash
-eval "$(jj-stack completion zsh --jj-alias stack)"
-```
-
-`bash` and `fish` work the same way. See
-[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
-setup options.
-
 ### Submit your first stack
 
-Start with a linear series of local `jj` changes on top of `trunk()`. In a new repo, check
-the setup and apply the safe local fixes:
+Start with a linear series of local `jj` changes on top of `trunk()`. Authenticate with
+`gh auth login`, or supply a token in `GITHUB_TOKEN` or `GH_TOKEN`. Check the repo setup and
+apply the safe local fixes:
 
 ```bash
 jj-stack doctor --fix
@@ -110,19 +72,26 @@ refresh. Use `jj-stack list` to see every tracked stack in the repo.
 ## Mental model
 
 Your local `jj` history determines which changes form a stack and their order. On GitHub, each
-change gets a stable PR branch and a PR; every PR targets the PR branch below it, except the
-bottom PR, which targets trunk by default:
+change gets a stable PR branch and a PR. The bottom PR targets trunk by default, and each PR
+above it targets the PR branch below:
 
 ```text
-jj-stack/add-ui-...         -> PR #3 (base: jj-stack/add-api-...)
-jj-stack/add-api-...        -> PR #2 (base: jj-stack/refactor-model-...)
-jj-stack/refactor-model-... -> PR #1 (base: main)
-main                        -> trunk
+Local changes:  trunk() <- A     <- B     <- C
+GitHub PRs:     main    <- PR #1 <- PR #2 <- PR #3
 ```
 
-The PR branches normally stay out of your local bookmark view. When you rewrite a change,
-`jj-stack` updates that change's existing PR branch and PR, along with the PR branches and PRs for
-dependent changes.
+Each PR's diff shows only the changes it adds on top of its base, so reviewers can consider
+one change at a time. `jj-stack` manages the PR branches for you, and they normally stay out
+of your local bookmark view.
+
+When you rewrite a change, its change ID still connects it to the same PR. Submitting again
+updates that PR and the PRs for any dependent changes, preserving their discussions.
+
+To select a stack, pass the change ID of its head (the top change). `jj-stack` follows the
+head's parents back to trunk to find the rest. If you don't name a head, it uses your working
+copy when it has both a description and changes, or its parent otherwise. After editing a
+lower change, pass the head's ID to `jj-stack submit` so the update includes the changes above
+your edit.
 
 ## Everyday workflow
 
@@ -130,9 +99,11 @@ dependent changes.
 2. Run `jj-stack submit`.
 3. Revise, add, remove, or reorder the changes locally as reviews come in.
 4. Run `jj-stack submit` again to refresh GitHub.
-5. Run `jj-stack merge` when the changes at the bottom are ready.
-6. After a queued or externally initiated merge finishes, run
-   `jj-stack sync <head-change-id>`.
+5. Run `jj-stack merge` when the PRs at the bottom are ready. Pass `--pull-request <pr>` to
+   stop at an earlier PR, and `--method` to choose a merge method your repo allows. The command
+   waits for GitHub, including its merge queue, then updates your local stack and remaining PRs.
+6. If you used `--no-wait`, interrupted the wait, or merged through GitHub, run
+   `jj-stack sync <head-change-id>` after GitHub finishes.
 
 `view`, `submit`, `merge`, and `sync` accept a change ID when you need to select a stack other
 than the one ending at the working copy.
@@ -140,19 +111,58 @@ than the one ending at the working copy.
 See the [user guide](https://www.serpentine.com/software/jj-stack/) for drafts, descriptions,
 merge queues, cleanup, and working with multiple stacks.
 
+## Optional setup
+
+### Invoke it as `jj stack`
+
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
+```
+
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
+
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
+
+### Other installation options
+
+`pipx` provides another isolated installation:
+
+```bash
+pipx install jj-stack
+```
+
+You can also use `pip` inside an activated virtual environment:
+
+```bash
+python -m pip install jj-stack
+```
+
+To upgrade an installation made with `uv`, run `uv tool upgrade jj-stack`. If the command is
+not on your shell `PATH`, run `uv tool update-shell`.
+
 ## Learn more
 
-- [Mental model](https://www.serpentine.com/software/jj-stack/mental-model/)
-- [Quick start](https://www.serpentine.com/software/jj-stack/quick-start/)
-- [Everyday workflows](https://www.serpentine.com/software/jj-stack/guides/submit-and-update/)
+- [How jj-stack works](https://www.serpentine.com/software/jj-stack/mental-model/)
+- [Submit and update](https://www.serpentine.com/software/jj-stack/guides/submit-and-update/)
+- [Merge and sync](https://www.serpentine.com/software/jj-stack/guides/merge-and-sync/)
+- [Multiple stacks](https://www.serpentine.com/software/jj-stack/guides/multiple-stacks/)
 - [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
 - [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
 - [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
-- [Tool comparison](https://www.serpentine.com/software/jj-stack/tool-comparison/)
-- [JSON output](https://www.serpentine.com/software/jj-stack/reference/json-output/)
-- [Automation and exit codes](https://www.serpentine.com/software/jj-stack/reference/automation/)
+- [Compare tools](https://www.serpentine.com/software/jj-stack/tool-comparison/)
+- [Automation](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
-The built-in help is the canonical flag reference:
+For all flags and aliases, use the built-in help:
 
 ```bash
 jj-stack --help
@@ -160,42 +170,18 @@ jj-stack <command> --help
 jj-stack help --all
 ```
 
-## Development
-
-Contributor workflows live in the [`justfile`](justfile). With `uv`, `jj`, and `just` installed,
-run `just` to list the setup, formatting, focused test, verification, documentation, and release
-recipes.
-
 ## Coding agent integration
 
-Install the bundled skill to teach coding agents to work with local `jj` stacks and refresh their
-GitHub PRs safely:
+Install the bundled skill to give coding agents instructions for working with `jj-stack`:
 
 ```bash
 gh skill install bos/jj-stack jj-stack
 ```
 
-See the [skill source](https://github.com/bos/jj-stack/blob/main/skills/jj-stack/SKILL.md). In
-my evaluations with Codex and Claude Code, agents with the `jj-stack` skill succeeded in 11/12
-scenarios versus 6/12 without it, with one critical error versus four, using 60% fewer failed
-command attempts and 18% fewer tool calls. Treat that as a small pilot rather than a published
-benchmark:
-[`evals/jj-stack-skill.md`](https://github.com/bos/jj-stack/blob/main/evals/jj-stack-skill.md)
-gives the evaluation design, but this repo does not include the traces behind those numbers.
-(The critical error was due to Claude Haiku understanding a rule and ignoring it. I haven't
-figured out how to get smaller Claude models to behave better, and I don't personally use them.)
-
-## Performance
-
-Although `jj-stack` is written in Python, this does not significantly affect its speed.
-The real determinants of its performance are the GitHub API and the `jj` command.
+The [skill source](skills/jj-stack/SKILL.md) and [evaluation notes](evals/jj-stack-skill.md) are
+included in this repo.
 
-The GitHub API is *slow*; a single roundtrip takes many hundreds of milliseconds. `jj-stack`
-reduces its impact with:
-
-- GraphQL batch requests where possible
-- concurrent use of the GitHub REST API
-- periodic audits that its queries are minimal in extent
+## Development
 
-In pursuit of good performance, `jj-stack` also batches calls to `jj` and minimizes the amount
-of work those calls must do.
+With `uv`, `jj`, and `just` installed, run `just` to list the development workflows. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup and validation instructions.

jj_stack-0.1.5/README.md

@@ -0,0 +1,159 @@
+# jj-stack: manage stacked GitHub PRs with jj
+
+`jj-stack` turns a linear series of local `jj` changes into a stack of GitHub pull requests.
+Rewrite, split, squash, or reorder the changes with `jj`, then run `jj-stack submit` to update
+GitHub. Existing PRs follow their change IDs, keeping comments and review history together.
+
+## Quick start
+
+You need Python 3.14 or newer, `jj` 0.45.1 or newer, and a repo on github.com where you can push
+branches and open pull requests. `jj-stack` uses `GITHUB_TOKEN`, then `GH_TOKEN`, then your GitHub
+CLI login for authentication.
+
+Install with `uv`:
+
+```bash
+uv tool install jj-stack
+```
+
+### Submit your first stack
+
+Start with a linear series of local `jj` changes on top of `trunk()`. Authenticate with
+`gh auth login`, or supply a token in `GITHUB_TOKEN` or `GH_TOKEN`. Check the repo setup and
+apply the safe local fixes:
+
+```bash
+jj-stack doctor --fix
+```
+
+Inspect the stack that ends at your working copy:
+
+```bash
+jj-stack
+```
+
+Create one GitHub PR per local change:
+
+```bash
+jj-stack submit
+```
+
+Revise the changes locally with `jj` and rerun `jj-stack submit` whenever the stack is ready to
+refresh. Use `jj-stack list` to see every tracked stack in the repo.
+
+## Mental model
+
+Your local `jj` history determines which changes form a stack and their order. On GitHub, each
+change gets a stable PR branch and a PR. The bottom PR targets trunk by default, and each PR
+above it targets the PR branch below:
+
+```text
+Local changes:  trunk() <- A     <- B     <- C
+GitHub PRs:     main    <- PR #1 <- PR #2 <- PR #3
+```
+
+Each PR's diff shows only the changes it adds on top of its base, so reviewers can consider
+one change at a time. `jj-stack` manages the PR branches for you, and they normally stay out
+of your local bookmark view.
+
+When you rewrite a change, its change ID still connects it to the same PR. Submitting again
+updates that PR and the PRs for any dependent changes, preserving their discussions.
+
+To select a stack, pass the change ID of its head (the top change). `jj-stack` follows the
+head's parents back to trunk to find the rest. If you don't name a head, it uses your working
+copy when it has both a description and changes, or its parent otherwise. After editing a
+lower change, pass the head's ID to `jj-stack submit` so the update includes the changes above
+your edit.
+
+## Everyday workflow
+
+1. Write code as a series of local `jj` changes.
+2. Run `jj-stack submit`.
+3. Revise, add, remove, or reorder the changes locally as reviews come in.
+4. Run `jj-stack submit` again to refresh GitHub.
+5. Run `jj-stack merge` when the PRs at the bottom are ready. Pass `--pull-request <pr>` to
+   stop at an earlier PR, and `--method` to choose a merge method your repo allows. The command
+   waits for GitHub, including its merge queue, then updates your local stack and remaining PRs.
+6. If you used `--no-wait`, interrupted the wait, or merged through GitHub, run
+   `jj-stack sync <head-change-id>` after GitHub finishes.
+
+`view`, `submit`, `merge`, and `sync` accept a change ID when you need to select a stack other
+than the one ending at the working copy.
+
+See the [user guide](https://www.serpentine.com/software/jj-stack/) for drafts, descriptions,
+merge queues, cleanup, and working with multiple stacks.
+
+## Optional setup
+
+### Invoke it as `jj stack`
+
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
+```
+
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
+
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
+
+### Other installation options
+
+`pipx` provides another isolated installation:
+
+```bash
+pipx install jj-stack
+```
+
+You can also use `pip` inside an activated virtual environment:
+
+```bash
+python -m pip install jj-stack
+```
+
+To upgrade an installation made with `uv`, run `uv tool upgrade jj-stack`. If the command is
+not on your shell `PATH`, run `uv tool update-shell`.
+
+## Learn more
+
+- [How jj-stack works](https://www.serpentine.com/software/jj-stack/mental-model/)
+- [Submit and update](https://www.serpentine.com/software/jj-stack/guides/submit-and-update/)
+- [Merge and sync](https://www.serpentine.com/software/jj-stack/guides/merge-and-sync/)
+- [Multiple stacks](https://www.serpentine.com/software/jj-stack/guides/multiple-stacks/)
+- [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
+- [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
+- [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
+- [Compare tools](https://www.serpentine.com/software/jj-stack/tool-comparison/)
+- [Automation](https://www.serpentine.com/software/jj-stack/reference/automation/)
+
+For all flags and aliases, use the built-in help:
+
+```bash
+jj-stack --help
+jj-stack <command> --help
+jj-stack help --all
+```
+
+## Coding agent integration
+
+Install the bundled skill to give coding agents instructions for working with `jj-stack`:
+
+```bash
+gh skill install bos/jj-stack jj-stack
+```
+
+The [skill source](skills/jj-stack/SKILL.md) and [evaluation notes](evals/jj-stack-skill.md) are
+included in this repo.
+
+## Development
+
+With `uv`, `jj`, and `just` installed, run `just` to list the development workflows. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for setup and validation instructions.