Skip to content

chore: add a steward skill that keeps ready agent PRs mergeable (#101) - #102

Draft
V3RON wants to merge 7 commits into
mainfrom
issue-101-add-a-steward-skill-that-keeps-ready-age
Draft

V3RON wants to merge 7 commits into
mainfrom
issue-101-add-a-steward-skill-that-keeps-ready-age

Conversation

@V3RON

@V3RON V3RON commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Closes #101

What changed

Adds .claude/skills/steward-pr, a skill that sweeps open, non-draft PRs carrying the work-issue ### Status ledger and keeps each one mergeable, green and answered until a human merges it: update-branch when behind, merge origin/main when conflicting, delegate failing checks and human review comments to implement-issue, one review-pr round on each fix, a reply on every thread, a Steward: entry in the ledger. To tell agent activity from human activity regardless of the GitHub login, every comment, review, PR body and issue comment an agent posts now ends with -- agent: <skill-name>; AGENTS.md states the rule and each posting skill appends it.

Repo tooling only: no TypeScript, no package tests. Each criterion is checked by a dry run of the skill's commands against this repo or by reading the files.

Acceptance criteria

# Criterion Test Tier
1 AGENTS.md names the trailer under Writing; every posting skill appends it; a review-pr dry run ends its summary and every inline comment with -- agent: review-pr grep -c -- '-- agent:' AGENTS.md .claude/skills/{review-pr,work-issue,implement-issue,design-feature,triage-issue,file-issue,cut-release,review-memory}/SKILL.md is non-zero for every file; a review-pr subagent run with "do not post" on this branch prints the trailer on its summary and every inline comment file check + dry run
2 .claude/skills/steward-pr/SKILL.md exists and the AGENTS.md Skills table routes to it test -f .claude/skills/steward-pr/SKILL.md && grep -n steward-pr AGENTS.md file check
3 No argument: sweeps gh pr list --state open, selects non-draft PRs with ### Status (and Ready: yes, see Out of scope); a PR number: that PR alone, "skipped: " when it does not qualify run the skill's selection command from step 1 on this repo (selects nothing); run it with this PR's number (draft: "skipped: draft") dry run
4 BEHIND: gh pr update-branch; DIRTY: merge origin/main, resolve, push; nothing rewrites history file check: step 3 names both commands; grep -n 'rebase|force' .claude/skills/steward-pr/SKILL.md shows only prohibitions file check
5 Failing checks: delegate to implement-issue with the failing job's log excerpt; green or blocked after two rounds file check: step 4 and the loop limit in step 7 file check
6 Human review comment (no trailer): a commit addressing it, one review-pr round, a reply on the thread with -- agent: steward-pr, thread left unresolved; a second sweep posts nothing file check: step 5 (classification by trailer, reply command, no resolve) file check
7 Ledger gains Steward: <date> <what>; fixed report block per PR file check: step 6 and the Report section file check
8 .claude/settings.json allowlists the skill's commands and nothing broader git diff main -- .claude/settings.json: allow gh pr update-branch *, gh api repos/{owner}/{repo}/pulls/*, gh api repos/{owner}/{repo}/issues/*, git merge origin/*; deny gh api merge, ref and release paths file check
9 A sweep where every qualifying PR is clean, green and answered posts and pushes nothing dry run of the sweep on this repo: no qualifying PR, nothing posted dry run

E2E evidence

not applicable

Checklist

  • CHANGELOG.md has an entry under Unreleased (writing-changelog skill), or the change is not user-visible (repo tooling; not user-visible)
  • User-facing docs updated for every surface the change touches (writing-user-docs skill), or the change is not user-visible (not user-visible)
  • No new import past a module's index.ts; no new direct node:* I/O outside an adapter
  • Simplification checklist from the architecture skill applied, exceptions explained above
  • docs/ARCHITECTURE.md updated if a surface it describes changed (it describes no skill)

Out of scope

  • Selection requires Ready: yes on top of the ### Status heading the issue names: the PR template ships that heading with Ready: no, so the heading alone selects every human PR opened from the template, which the issue says the steward must never touch (found by the review-pr dry run). Ready: yes is written only by work-issue step 5 or by a human handing a PR over.
  • .claude/settings.json allows gh api under this repo's pulls/ and issues/ paths only; the same prefixes cover the REST reads and the one REST write the steward needs (a reply under a review thread, which no gh pr subcommand can post). Deny entries for the merge, git/refs and releases paths keep rule 8 covered; whether a * in the middle of a deny pattern matches is unverified against a live permission prompt. Patterns match command text as written, so the skill writes every gh api flag after the path and leaves origin/$branch unquoted.
  • Criteria 4 to 7 need a qualifying PR that is behind, conflicting, red or commented on; none exists in this repo today, so they are covered by reading the skill's steps. The first real sweep on such a PR is the live check.
  • e2e-device is not in the issue's list of posting skills; it edits the PR body, so it got a one-line note to keep the trailer last.
  • The trailer goes in a PR body after the ### Status section; Claude Code cloud sessions append their own footer after it, so the steward classifies by "a line matches -- agent: ", not by "the last line".

Status

Implement: done (9/9 checked) Review: dry run, request-changes, 3 findings addressed in the next commit E2E: not applicable Ready: no

-- agent: implement-issue

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a steward skill that keeps ready agent PRs mergeable

1 participant