amux-pr-workflow
Skill34 starsChanged 6 months agoMITView on GitHub
Use when creating, updating, reviewing, or merging a PR in this repo. Covers first-push rebases, review and simplification passes, benchmark baseline requirements, and post-merge `$postmortem` runs.
- Commits and pushes
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- amuxSkill
- demo-recordingSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
35 rules. About 0 are common, 16 are distinctive, and 19 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
19
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use this skill when the task involves git push, gh pr create, gh pr merge, PR review, benchmark PR prep, or "wrap this up" work near the …
- Very specific: line 13
Do not git pull a dirty local main.
- Distinctive: line 14
Do not use git worktree unless the user explicitly asks for it.
- Very specific: line 15
If git fetch origin main or git pull advances origin/main while a PR branch is open, refresh that branch onto origin/main before treating …
- Distinctive: line 16
If the PR drifts after opening and you rebase or resolve conflicts, rerun the review pass and simplification pass on the rebased diff …
- Very specific: line 20
Prefer gh pr create --body-file ...
- Very specific: line 21
After gh pr create, run scripts/watch-pr-ci.sh and wait for required checks on that PR.
- Very specific: line 26
If scripts/watch-pr-ci.sh reports failures, inspect the failed-check summary and failed-step logs, fix issues likely caused by your diff, …
- Distinctive: line 27
If CI looks flaky or unrelated to your diff, say so explicitly with evidence instead of blindly retrying or making speculative fixes.
- Distinctive: line 28
Do not present a PR as done until it has had both a review pass and a simplification pass.
- Very specific: line 29
If codex review or other external review tooling stalls, fall back to a manual diff review and say so explicitly.
- Very specific: line 30
If benchmarks changed, add a Baseline numbers section to the PR description with representative results and hardware.
- Distinctive: line 31
If a rebase triggers broad noisy local failures, verify with a targeted regression slice before making invasive code changes.
- Very specific: line 32
After merge, verify local state explicitly: confirm the checkout is on main, the worktree is clean, and HEAD matches origin/main.
- Distinctive: line 33
After merge, any follow-up fix goes on a fresh branch and PR.
- Very specific: line 34
After merge, explicitly run $postmortem.
- Very specific: line 35
Do not say $postmortem ran unless you have the logged ~/.local/share/postmortems/...
- Very specific: line 37
If $postmortem is skipped, say so explicitly and give the reason.
- Very specific: line 44
After gh pr create, run scripts/watch-pr-ci.sh.
- Distinctive: line 45
If CI fails, fix the issue, rerun the relevant local verification slice, and repeat the push/watch loop up to 3 times.
- Distinctive: line 46
Keep related follow-up fixes on that PR branch.
- Very specific: line 47
Run a review pass. Prefer codex review when available, but if it stalls, do a manual diff review and state that explicitly.
- Distinctive: line 48
Run a simplification pass focused on unnecessary complexity and cleanup opportunities.
- Distinctive: line 49
If the branch had to be rebased or conflict-resolved after the PR was open, rerun both passes on that rebased diff before pushing again.
- Distinctive: line 50
If the change affects layout math or resize behavior, compare against tmux before adding new layout state or diverging from tmux semantics.
- Distinctive: line 51
If the change touched benchmarks, add baseline numbers before calling the PR ready.
- Distinctive: line 52
If a rebase causes broad noisy local failures, run a targeted regression slice that represents the suspected regression before making …
- Distinctive: line 53
Before merging, re-check the live PR state and mergeability after the latest green checks.
- Very specific: line 54
After merge, verify local state with git branch --show-current, git status --short --branch, and git rev-parse HEAD origin/main.
- Distinctive: line 55
If you discover a follow-up fix after merge, create a fresh branch before editing.
- Very specific: line 56
After merge, explicitly run $postmortem to capture learnings, pain points, and follow-up actions.
- Very specific: line 58
If $postmortem ran, summarize the main learnings and follow-up actions in the user-facing closeout so the user gets the result directly, …
- Distinctive: line 75
Follow-up fixes kept off local main.
- Very specific: line 77
If $postmortem ran, the log path is reported.
- Very specific: line 78
If $postmortem ran, the key learnings and action items are also summarized in the final handoff.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
amux PR Workflow
Use this skill when the task involves git push, gh pr create, gh pr merge, PR review, benchmark PR prep, or "wrap this up" work near the end of a change.
Rules
- Rebase onto
origin/mainbefore the first push:git fetch origin main && git rebase origin/main. - Do not
git pulla dirty localmain. Ifmainhas local changes, start the next branch from freshorigin/maininstead of updating that checkout in place. - Do not use
git worktreeunless the user explicitly asks for it. - If
git fetch origin mainorgit pulladvancesorigin/mainwhile a PR branch is open, refresh that branch ontoorigin/mainbefore treating the PR as current again. - If the PR drifts after opening and you rebase or resolve conflicts, rerun the review pass and simplification pass on the rebased diff before calling the PR ready again.
- In non-interactive sessions, prefer
GIT_EDITOR=true git rebase --continueso rebase continuation does not stall invim. - This repo is squash-only on GitHub. Use
gh pr merge --squash; merge and rebase merges will fail. - GitHub auto-merge is disabled on this repo. Wait for green checks, then merge manually.
- Prefer
gh pr create --body-file ...for multiline PR descriptions, especially when they include backticks or code fences. - After
gh pr create, runscripts/watch-pr-ci.shand wait for required checks on that PR. - Once a PR exists, prefer
scripts/push-and-watch-ci.shover baregit pushso the CI watch step is automatic. - In an amux pane, prefer
scripts/gh-pr-create.sh ...over rawgh pr createso pane PR metadata syncs for every agent; latergit pushcalls re-sync via the repopre-pushhook installed bymake setup. - In
amux, if the change is ready for review, open the PR proactively instead of asking whether to make one. - Once a PR is open, keep related follow-up fixes on that PR branch. Do not leave a relevant fix only on a side branch or local branch after reporting PR status.
- If
scripts/watch-pr-ci.shreports failures, inspect the failed-check summary and failed-step logs, fix issues likely caused by your diff, rerun the relevant tests, and repeat up to 3 attempts before escalating. - If CI looks flaky or unrelated to your diff, say so explicitly with evidence instead of blindly retrying or making speculative fixes.
- Do not present a PR as done until it has had both a review pass and a simplification pass.
- If
codex reviewor other external review tooling stalls, fall back to a manual diff review and say so explicitly. - If benchmarks changed, add a
Baseline numberssection to the PR description with representative results and hardware. - If a rebase triggers broad noisy local failures, verify with a targeted regression slice before making invasive code changes.
- After merge, verify local state explicitly: confirm the checkout is on
main, the worktree is clean, andHEADmatchesorigin/main. - After merge, any follow-up fix goes on a fresh branch and PR. Do not make extra commits on local
main. - After merge, explicitly run
$postmortem. A short manual summary does not count. Turn action items into issues or doc updates. - Do not say
$postmortemran unless you have the logged~/.local/share/postmortems/...path. - In the final merge closeout, include the
$postmortemlog path, summarize the key learnings and concrete action items, and say whether they were implemented now or left as follow-up work. - If
$postmortemis skipped, say so explicitly and give the reason. Do not imply it was done.
Workflow
- Confirm the relevant tests ran and note any gaps.
- If this is the first push for the branch, rebase onto
origin/main. If the localmaincheckout is dirty, do not update it in place; create the next branch directly fromorigin/main. If the PR is already open and a fetch/pull advancedorigin/main, refresh the branch ontoorigin/mainbefore continuing. - Create or update the PR as soon as the branch is ready for review. In an amux pane, use
scripts/gh-pr-create.sh ...when opening the PR; otherwise usegh pr create --body-file ...when the body is multiline. If the PR is already open and you make a related fix, commit it on that PR branch, rerun the relevant verification slice, and push before reporting status. - After
gh pr create, runscripts/watch-pr-ci.sh. If you update an already-open PR, usescripts/push-and-watch-ci.shso the push blocks on required checks and prints failed-step logs on failure. - If CI fails, fix the issue, rerun the relevant local verification slice, and repeat the push/watch loop up to 3 times. If the failure looks flaky or unrelated to your diff, report that explicitly with evidence before handing off.
- Keep related follow-up fixes on that PR branch. Do not leave a relevant fix only on a side branch or local branch after reporting PR status.
- Run a review pass. Prefer
codex reviewwhen available, but if it stalls, do a manual diff review and state that explicitly. - Run a simplification pass focused on unnecessary complexity and cleanup opportunities.
- If the branch had to be rebased or conflict-resolved after the PR was open, rerun both passes on that rebased diff before pushing again.
- If the change affects layout math or resize behavior, compare against tmux before adding new layout state or diverging from tmux semantics.
- If the change touched benchmarks, add baseline numbers before calling the PR ready.
- If a rebase causes broad noisy local failures, run a targeted regression slice that represents the suspected regression before making invasive code changes.
- Before merging, re-check the live PR state and mergeability after the latest green checks. If
mainmoved, fetch and rebase again before merging. - After merge, verify local state with
git branch --show-current,git status --short --branch, andgit rev-parse HEAD origin/main. If needed, rungit checkout main && git pull --ff-only. - If you discover a follow-up fix after merge, create a fresh branch before editing.
- After merge, explicitly run
$postmortemto capture learnings, pain points, and follow-up actions. Do not substitute a brief ad hoc summary. - In the final merge closeout, state either the logged
$postmortempath or the explicit reason it was skipped. - If
$postmortemran, summarize the main learnings and follow-up actions in the user-facing closeout so the user gets the result directly, not only via the log file.
Output Checklist
- Tests run, or an explicit testing gap is called out.
- Rebase-before-first-push handled or explicitly not needed.
- Open PR branches refreshed after any fetch/pull that advanced
origin/main. - PR CI watched after
gh pr createand after subsequent PR updates. - CI failures either fixed on the same PR branch or called out explicitly as flaky/unrelated with evidence.
- Related follow-up fixes pushed to the already-open PR branch before PR status is reported complete.
- Review pass completed.
- Simplification pass completed.
- Review/simplification rerun after any post-open rebase or conflict resolution.
- Squash merge policy followed.
- Final mergeability check handled before merge.
- Benchmark baseline section added when relevant.
- Local post-merge state verified.
- Follow-up fixes kept off local
main. $postmortemexplicitly run after merge, or a clear skip reason is stated.- If
$postmortemran, the log path is reported. - If
$postmortemran, the key learnings and action items are also summarized in the final handoff.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

