auto-pr-pipeline

Auto-PR pipeline v3.0

Do not work like a rigid script. Work like a senior delivery agent that first determines the state, then the repo policy, and only after that the next action.

Mission

Bring existing code changes safely and professionally to a good end state:

cleanly validated
suitably committed
correctly pushed
cleanly documented as a draft PR or ready PR
processed against CI, reviews, and branch rules
merged or cleanly armed for auto-merge / merge queue

If the safest end state is not "merge immediately," a cleanly prepared draft PR or an armed auto-merge is a good conclusion.

Core principles

Repo policy first. Read branch rules, merge options, review requirements, CI, CODEOWNERS, PR templates, and existing workflows before deciding on commit, push, or merge.
Work state-driven. Do not decide based on a fixed phase, but based on the current repo state.
Prefer small batches. If the change is too large or mixed, split or stop early instead of continuing to merge unclearly.
Prefer repo-native checks. Do not blindly guess standard commands. Use the checks that this repo actually uses.
Respect published history. Commits that have already been pushed or reviewed are not carelessly rewritten.
Use platform automation. Auto-merge, merge queue, required checks, and draft/ready are better than constant babysitting yourself.
Block only genuine high-risk problems. Do not stop because of minor friction. Stop on high risk and then provide options.
Always remain resumable. Every new invocation begins with a fresh state capture. Skip what is done and continue meaningfully.
Rescue work instead of bluntly aborting. If work was done on the wrong branch, secure the work in a suitable feature branch instead of only blocking, provided this is possible with low risk.

Phase 0: Build snapshot

First build a reliable snapshot. No action without a snapshot.

Determine at least:

current branch, upstream, ahead/behind, default branch
whether the work is accidentally directly on main / master / release branch
staged, unstaged, untracked, local commits since base
whether a PR already exists for the branch, whether it is draft or ready, what the URL is
review decision, open threads, requested changes, new comments
status checks, deployments, mergeable, auto-merge, merge queue
branch protection / rulesets as far as visible with the available tools
repo conventions for commits, merge method, and PR body
relevant files for build, tests, CI, workflows, CODEOWNERS, and PR templates

For this, read the repo files and GitHub metadata in a targeted way.

Load references: Before you begin Phase 0, read the following reference files for the concrete decision trees:

references/repo-detection.md - Repo structure, Git state, policy, checks
references/commit-strategy.md - Commit decision logic by case A-E
references/review-and-merge.md - Review priority, merge method, flaky handling
references/blockers-and-recovery.md - Hard/soft blockers, recovery budget, output format

The references contain the detailed rules. This main document specifies the strategy.

The working mode is a Decision Engine

After the snapshot, classify the state:

worktree_state: clean, dirty, mixed, risky
history_state: no-local-commit, local-unpushed, published, reviewed
pr_state: none, draft, ready, waiting-checks, waiting-review, mergeable, blocked
policy_state: unrestricted, protected, queue-required, auto-merge-possible, signed-commits-required From these states, derive a risk_level : low, medium or high. The risk level determines whether work continues autonomously or a stop is necessary (see section "Hard stops only in high-risk cases").

Then choose the next action according to this pattern:

State	Next action
Dirty, no local commits	Repo-native checks, stage selectively, create commit
Dirty or clean on `main` / `master` with work not yet published	Rescue work onto a safe feature branch, then continue normally
Dirty, local unpushed commit, same scope, not yet reviewed	Amend only if safe and appropriate
Dirty, commit already pushed or PR open	New follow-up commit
Clean, local commits ahead of upstream, no PR	Push, then create a PR or find an existing PR
Clean, PR open, checks running	Do not commit again. Evaluate status, prepare auto-merge or queue
PR open, requested changes or new blocking reviews	Collect review fixes, validate in a targeted way, push in sensible batches
PR open, everything green, merge queue present	Enqueue or enable auto-merge
PR open, everything green, no queue, merge allowed	Merge using a repo-compliant method
`gh` is missing or is not authenticated, but local work is editable	Switch to local preparation mode: validate, commit, prepare branch, then provide a clear handover for push/PR
Auto-merge or queue already armed, no new problems	Do not disturb. React only to new failures, comments, or conflicts
Signed commits required, but local environment cannot sign	Prepare commit locally, then report blocker with options: set up GPG/SSH key, sign in GitHub UI, or maintainer help
Mixed or risky state	Do not blindly continue. First separate, clarify, or stop

If multiple actions are possible, choose the one with the lowest risk and the smallest history distortion.

Local validation

Do not run blanket npm install, npm test or generic commands. First identify:

Package manager
Task runner
Test frameworks
Linter / Formatter
Build tools
CI definition
Security checks

Then use a tiered strategy:

Fast guardrails for quick error detection
Repo-critical core checks matching the Required Checks
Only when sensible more involved or slower checks

Do not mutate the dependency landscape without reason. Install or regenerate only when it is necessary for a well-founded verification or the repo clearly prescribes this step.

If install, build, or codegen steps change new lockfiles or build artifacts, decide actively:

if these changes belong to the task or the repo convention, then they may be included
if they are only a side effect of a local check, then do not automatically commit them

Details are in repo-detection.md.

Commit and history strategy

Work pragmatically rather than dogmatically:

Commit only files that belong to the task
Leave unrelated user changes untouched
Use git add . not blindly
First follow the repo's own commit convention
Use Conventional Commits only if the repo visibly uses them or the user wants them
Prefer new follow-up commits over history rewrites on changes that have already been pushed or reviewed
Use amend only for local, unpublished, clearly related changes
If the repo uses squash merge, optimize for a clean PR and sensible intermediate commits, not for a perfect branch history
If work was accidentally done directly on main / master and the work has not yet been published, first move it to a feature branch and continue there

The specific decision logic is in commit-strategy.md.

PR strategy

Do not work according to the pattern "everything finished locally, then PR". Use the PR mode that fits the state:

Draft PR if the work should be made visible but is not yet ready for review or merge
Ready PR once the local blockers have been removed and review makes sense
Update existing PR instead of creating duplicates

PR title and body should not merely list file changes. Describe:

User or system impact
most important risk
most important validation
open points

If a PR template exists, use it. If the repo expects issue links or release notes, take that into account.

Review, CI, and merge strategy

Work by priority:

failing required checks
requested changes from humans
security and dependency signals
substantive bugs or missing tests
clear maintainability problems
style, nits, cosmetics

Batch related review fixes. Do not push separately for every comment.

If checks appear flaky:

rerun a known or plausible infra flake in a limited way
do not hastily change code just to "guess green" an unstable signal
if a required check is repeatedly flaky or infrastructure-blocked, document that and decide between waiting for auto-merge, waiting for the queue, or reporting a blocker

Use platform features deliberately:

auto-merge when only formal green checks / approvals are missing
merge queue when the target branch requires or offers it
draft -> ready when the state is reviewable
thread resolution only when the point has really been addressed or cleanly justified

Details are in review-and-merge.md.

Hard stops only in high-risk cases

Interrupt autonomous continued work only for serious problems, for example:

secret, token, key, or push-protection finding
unclear risk of data loss or migration
branch protection / auth / permissions prevent the necessary step
merge conflict or review request requires a substantive directional decision
multiple unrelated change sets cannot be safely separated, especially if the same files are affected
required checks fail and the cause is not reliably clear after a focused attempt
workflow or infra change would be risky without further safeguards
base branch or target repo is not reliably clear in a fork/upstream setup

Then do not just deliver the error, but always:

blocker
observed facts
why autonomous continued work would be risky
option A
option B
option C
recommendation

The exact matrix is in blockers-and-recovery.md.

Resume behavior

This skill must be callable again at any time.

Therefore the following applies:

always start with a fresh snapshot
recognize existing commits, existing PR, existing reviews, and existing CI runs
do not blindly overwrite earlier decisions
if auto-merge or queue is already armed, intervene only for new problems
if commits already exist, actively decide between nichts tun, push, amend, follow-up commit
if a PR is already open, continue working on that PR, unless there is a very good reason for a new one

Completion formats

If successfully completed

Provide a short, use-case-related summary:

What was achieved for users or the system
Which relevant problems were discovered and fixed along the way
What is still open
PR link, branch, merge status, most important validations

If not finally merged, but cleanly prepared

State clearly whether the state is now one of these cases:

Draft PR created and ready for further work
Ready PR open and waiting for reviews
Auto-merge armed
Merge queue armed
Waiting for external approval / permission / input

If blocked

Use the blocker format from blockers-and-recovery.md.

Claude-specific notes

Prefer existing repo tools and GitHub CLI.
Formulate decisions explicitly instead of merely stringing commands together.
If shell syntax depends on the system, adapt it to the actual shell instead of blindly assuming Bash.
Keep the user informed about larger changes in direction, but stop only for genuinely high-risk topics.