melech-pr-gardener

Files (2)

• SKILL.md
• ROUTINE.md · references/

SKILL.md (first lines)

# PR Gardener

## What This Is

A **single-pass playbook**, not a loop or a long-lived agent. A scheduled runtime
(Claude Routine, Cursor Automation, Codex Automation, Antigravity Scheduled
Task, or cron) invokes you once: make one picked PR a little more merge-ready,
log it, and **return**. The scheduler is the loop; you're one tick.

Any memory the host hands you is a **hint, never authority**. Reconstruct truth
from the PR — base, threads, checks — and your own trail from its **ledger**
(below). The PR is the database; if they disagree, the PR wins.

No scheduler driving you yet — the user invoked this by hand? Run the pass
anyway, then offer to install the loop for the current repo using
`references/ROUTINE.md`.

## Stay In Scope

You watch and fix three fronts, all cleared by the **commits** you push — nothing
else:

- **Base drift** — branch fell behind or conflicts with its base.
- **Review comments** — unresolved CR threads (Bugbot, CodeRabbit, humans).
- **CI checks** — red GitHub checks caused by this diff.

Fix them with the repo's own **local tooling** — lint, typecheck, unit tests,
build (the `package.json` scripts) — to reason about and verify changes. Off-limits
is anything needing a live **environment**: E2E suites, provisioning infra,
spinning up services. A blocker only a live environment can diagnose is out of
scope — surface it, don't chase it. Step 3 handles each front in order, fixing it
when clear and handing it back when it needs your call.

**Never** merge, enable auto-merge, or mark a draft ready. You report readiness;
PR-state changes belong to the user.
Never open a new gardener PR: push only to the picked PR's existing head branch.

## Required Run Input And Auth

Require `GARDENER_AUTHOR`, as an environment variable or explicit run input,
with the GitHub login whose PRs this run should tend. Export an explicit input
before shell calls. It selects an author; it does **not** select or impersonate
the API identity.
The system `gh` authentication performs every read, push, reply, resolution, and
ledger update. Those writes remain attributed to the authenticated app or user
and every visible comment keeps the `🪴 ` prefix.

If `GARDENER_AUTHOR` is absent, inspect `gh auth status` only. A clearly
human-authenticated local development session may use `@me` for that pass. If
the token belongs to an app/bot, or the identity is unclear, report
"misconfigured / nothing to tend" and stop. Never silently fall through to
`@me`, and don't depend on `gh api user`: integrations may be forbidden from
calling `/user`.

## Workflow

Follow these steps in order, once, then stop.

### 1. Discover candidates

In the current repo, list the selected human's **authored, non-draft, open** PRs:

```bash
gh pr list --author "$GARDENER_AUTHOR" --state open
```

Drop drafts and any already merge-ready (mergeable, CI green, no unresolved
threads). What's left is the candidate set — if empty, report "nothing to tend"
and stop.

### 2. Pick one (fair round-robin)

Read each candidate's **ledger** (below) for its most recent run timestamp (top
entry). Pick the **least recently tended** — oldest top entry; no ledger sorts
first; ties break by oldest `updatedAt`. Apply mechanically — don't re-rank by
importance. Fair rotation, no starvation.

### 3. Reconcile the picked PR

Refresh live state first (`gh pr view`, `gh pr checks`) — never act on stale
data. Then work the three fronts in **strict priority order**, stopping at the
first that needs the user.

Triage (a dismissal, a reply, an infra-only failure) is pure `gh` API — no
checkout. **Only for an actual code change, or code investigation needed to
answer**, use a throwaway **git worktree**, never the main checkout (you don't own
its state — a cloud checkout, or the user's laptop mid-edit). One per run, never
reused:

```bash
main_repo="$(git rev-parse --show-toplevel)"
git -C "$main_repo" fetch origin <pr-head-branch>
git -C "$main_repo" worktree add /tmp/gardener-<pr> \
  -b <pr-head-branch> origin/<pr-head-branch>
# edit, commit, push — all inside /tmp/gardener-<pr>
git -C /tmp/gardener-<pr> push
cd "$main_repo"
git -C "$main_repo" worktree remove /tmp/gardener-<pr> --force
git -C "$main_repo" worktree prune
```

- **Never** `checkout`, `switch`, `stash`, reset, or clean the main checkout to
  "make room" — it clobbers whatever's open there.
- Never add a worktree directly from `origin/<branch>` without `-b`; that leaves
  detached HEAD. If the local branch already exists or is checked out, create a
  unique local worktree branch and push `HEAD:<pr-head-branch>` without force.
- Fork PR: fetch the head ref first
  (`git -C "$main_repo" fetch origin pull/<n>/head:gardener-<pr>`), add the
  worktree from that local branch.
- Can't create one (no access, detached env)? Stop and report — never fall back
  to the main checkout.
- On every cleanup path, first `cd "$main_repo"` (or `/` if the main checkout is
  unavailable), then remove and prune through `git -C "$main_repo"`. Removing a
  worktree while the shell is inside it leaves the shell with a dead working
  directory.
- A fresh worktree may not have `node_modules` or other installed dependencies.
  Do not perform a full monorepo install by default. If the required local runner
  is absent, skip that local check, record the exact limitation, and let CI
  verify a narrow low-risk push. If the change is unsafe without local

From AdirD/agent-shell-hamelech, MIT.

More from AdirD/agent-shell-hamelech