atmos-new-pr-merge

name	atmos-new-pr-merge
description	Ship a finished feature or bugfix through a short-lived PR branch with archival history: create a branch from main (or another base), push commits, open a PR using the repo PR template, auto-merge into main, then checkout main and pull latest. Use whenever the user says "new pr merge", "开 PR 并合并", "创建 PR 然后合并到 main", "push 并合并", "leave a PR for the record", or runs /atmos-new-pr-merge. Prefer this over committing or pushing directly to main for routine feature work and bugfixes.
user-invokable	true
args	[{"name":"base","description":"Base branch to branch from and merge into (default main)","required":false},{"name":"branch","description":"Explicit feature branch name; if omitted, derive from the change","required":false},{"name":"title","description":"PR title; if omitted, derive from the commit subject / change summary","required":false},{"name":"merge","description":"Merge after creating the PR (default true). Set false to only open the PR","required":false},{"name":"delete_branch","description":"Delete the remote (and local tracking) branch after merge (default false). Set true only when the user explicitly wants the branch removed.","required":false},{"name":"dry_run","description":"Print the planned branch/PR/merge steps without mutating git or GitHub","required":false}]

Atmos new-PR-merge

Ship finished product feature work or bugfixes via a PR-first path so main stays clean and every product change leaves a PR archive.

When to use

• Small/medium feature or bugfix is done (or about to be committed)
• User wants: branch → PR (template) → merge → back on latest main
• User wants PR history even when they will self-merge immediately

When not to use

• Large multi-reviewer work that should stay open for review (merge=false only if they still want the PR opened)
• Release / deploy / version-tag flows → use the dedicated release/deploy skills
• Spec-only planning work with no code yet
• User only wants a local commit (no remote)
• Agent skill-only edits under .agents/skills/** (especially atmos-* skills) that only need to be published to remote — use the direct main path below instead of opening a PR

Defaults

Item	Default
Base / merge target	main (override with base)
Merge after PR	yes (merge=true)
Merge strategy	gh pr merge --merge (merge commit; keeps PR node in history)
Delete remote branch after merge	no (keep the feature branch; use delete_branch=true only if asked)
End state	local main (or base) checked out + git pull

Hard rules

1. Never git commit / git push on main for product work (apps/packages/crates/e2e/product docs). Product changes always go through a feature branch + PR.
2. Exception — agent skills only: If the diff is only under .agents/skills/** (and related skill ignore/index tweaks such as .gitignore skill rules), do not open a PR. Commit and git push origin main on main after a pull. User may also say “直接 main / 不用 PR”.
3. If currently on main with product uncommitted changes → create/switch to a feature branch before staging/committing.
4. If already on a feature branch with the right product commits → reuse it; do not invent a second branch unless asked.
5. For product PRs, always open with a body that follows .github/PULL_REQUEST_TEMPLATE.md sections (fill them in; do not leave the template comments empty of content).
6. After a successful product merge: git checkout <base> && git pull origin <base> and confirm clean, up-to-date status.
7. Report the PR URL (product path) or commit SHA (skill-direct path) and final tip of $BASE to the user.

Direct main path (skills only)

Use this when shipping only agent skill files (no product code):

git fetch origin main
git checkout main
git pull origin main
# stage only .agents/skills/** (and skill-related .gitignore if needed)
git add .agents/skills/<skill>/ ...
git commit -m "chore(skills): …"
git push origin main
git status
git log -1 --oneline

Do not create a feature branch or PR for skill-only publishes.

Branch naming

Use a professional type prefix that matches the change — never personal name prefixes (e.g. do not use aarynlu/…, username/…).

<type>/<optional-area>-<short-kebab-summary>

Prefix	Use when
fix/	Bugfix, incorrect behavior, regression
feat/	New user-facing capability
refactor/	Internal restructure without intended behavior change
chore/	Tooling, deps, non-product housekeeping
docs/	Documentation-only
perf/	Performance improvement
test/	Tests only

Examples:

• fix/web-mention-file-search
• feat/terminal-ai-input-scroll
• refactor/composer-popover-scroll-helper
• chore/agents-new-pr-merge-skill

Derive <type> from the actual diff and conventional commit type; keep the slug short and specific. If branch is provided by the user, use it as-is (after validating it is not main / the base and does not use a personal-name prefix unless they insisted).

Standard flow

0. Preconditions

git status
git rev-parse --abbrev-ref HEAD
git fetch origin

• Confirm repo is Atmos and gh is authenticated.
• If dry_run=true: print the full plan (branch name, commit plan, gh pr create title/body outline, merge command) and stop.
• If working tree has unrelated dirty files the user did not intend to ship → stop and ask.

1. Base branch

BASE="${base:-main}"
git fetch origin "$BASE"

If the work is not yet branched:

# clean base
git checkout "$BASE"
git pull origin "$BASE"

# new branch for the work
git checkout -b "<branch>"

If already on a non-base feature branch that contains the work → keep it (unless user passed a different branch).

2. Commit (only if needed)

If there are staged/uncommitted changes that belong to this ship:

1. Review git status + git diff
2. Stage only relevant files (not secrets, not unrelated dirt)
3. Commit with a conventional subject, complete sentences in the body:

fix(web): improve composer @ file search and popover keyboard scroll

Match @ mentions by file/folder name only, highlight keywords, and keep
3 peek rows when arrow-navigating @ and / popovers.

Do not invent extra files or drive-by refactors.

3. Push branch

git push -u origin HEAD

4. Create PR from template

Read and honor:

• .github/PULL_REQUEST_TEMPLATE.md

Fill every section with real content (checkboxes marked for what is true). Structure:

## Summary

<1–5 bullets: what changed and why>

## Related Issue

Closes #<n>   # or N/A

## Type of Change

- [x] Bug fix
- [ ] New feature
- [ ] Refactor
- [ ] Documentation
- [ ] Chore / tooling

## Validation

- [ ] `just lint`
- [ ] `just test`
- [ ] `just fmt`
- [x] <actual checks you ran, e.g. targeted bun test>

## Checklist

- [ ] I updated documentation if behavior changed
- [x] I added/updated tests where appropriate
- [x] I followed repository conventions and AGENTS.md guidance

Create:

gh pr create --base "$BASE" --head "<branch>" --title "<title>" --body "$(cat <<'EOF'
...filled template...
EOF
)"

Title: conventional and specific (same spirit as the commit subject). Prefer the title arg when provided.

5. Merge (default)

If merge is not false:

# Default: keep the feature branch after merge
gh pr merge <number-or-url> --merge

# Only when delete_branch=true / user explicitly asks to remove the branch:
# gh pr merge <number-or-url> --merge --delete-branch

Notes:

• Prefer --merge (merge commit) so the PR remains a clear archive node on main.
• Do not pass --delete-branch by default. Feature branches are part of the archive trail and are useful for follow-ups; delete only when delete_branch=true or the user explicitly asks.
• Use --squash only if the user explicitly asks.
• If merge is blocked (required checks, permissions), report the PR URL and the blocker; do not force unless the user explicitly requests a force path (usually there is none).

If merge=false: stop after PR creation and give the URL.

6. Return to latest base

git checkout "$BASE"
git pull origin "$BASE"
git status
git log -3 --oneline

Confirm:

• on $BASE
• clean working tree (or only pre-existing unrelated dirt the user already had)
• up to date with origin/$BASE

7. Report back

Always tell the user:

• branch name
• PR URL
• merged? (yes/no)
• merge commit / tip of $BASE
• local branch now checked out

Decision matrix

Situation	Action
Diff is only .agents/skills/** (skill publish)	commit + git push origin main — no PR
On main, dirty with a product fix	checkout -b feature branch → commit → push → PR → merge → back to main
On feature branch, uncommitted product work	commit on that branch → push → PR → merge → back to base
On feature branch, already committed, not pushed	push → PR → merge → back to base
PR already open for this branch	skip create; merge if requested; then pull base
User says “only open PR”	merge=false
User says “don’t touch remote yet”	stop after local branch + commit (or dry-run)
User says “delete the branch after merge”	delete_branch=true → add --delete-branch
User says “直接 main / 不用 PR” for a skill-only change	direct main path

Anti-patterns (never)

• git push origin main with product commits (apps/packages/crates/…)
• Opening a PR for a pure .agents/skills/** skill publish (wasteful; push main instead)
• amending / force-pushing shared history without explicit request
• empty PR bodies or “see commits” with no Summary
• opening a PR from main into main
• merging someone else’s open review PR without the user asking
• skipping git pull after merge (leaves the user on a stale local base)
• deleting the feature branch after merge unless the user asked (delete_branch=true)

Quick reference

# typical happy path (agent executes these with real names)
git fetch origin main
git checkout main && git pull origin main
git checkout -b fix/web-short-summary
# ... stage + commit ...
git push -u origin HEAD
gh pr create --base main --title "fix(web): …" --body "$(cat <<'EOF'
## Summary
…

## Related Issue
N/A

## Type of Change
- [x] Bug fix
…

## Validation
…

## Checklist
…
EOF
)"
gh pr merge <n> --merge
git checkout main && git pull origin main

Summary

This skill is the Atmos PR-archive ship path for day-to-day product features and bugfixes: branch off base, open a template-compliant PR, auto-merge by default (keep the feature branch), then return to latest base. Agent skill-only publishes skip the PR and go straight to main.