@a2f0/agent-tool 0.1.3 → 0.1.5

package/README.md

@@ -71,8 +71,8 @@ platform archives, a Homebrew formula, and Debian packages.
 - Bun 1.4 or newer on `PATH` for `versions prepare`, with either install,
   because it refreshes workspace versions in `bun.lock`.
 
-Run `agent-tool doctor` to report installed versions and supported review flags
-without calling a model.
+Run `agent-tool doctor` to report installed versions and the flags the tool needs
+from each CLI, such as `gh pr checks --json` for merging, without calling a model.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
   "license": "UNLICENSED",

package/skills/cross-agent-review/SKILL.md

@@ -18,8 +18,10 @@ Review committed changes with `agent-tool review claude`, `agent-tool review cod
 or `agent-tool review opencode`. Optional effort is `low`, `medium`, `high`,
 `xhigh`, or `max`. For a local or non-GitHub repository, add `--base <commit-or-ref>`.
 For a coordinated GitHub review, pin the fetched base using
-`AGENT_TOOL_REVIEW_BASE_REF` and `AGENT_TOOL_REVIEW_BASE_OID`; fetch from the
-repository that owns the PR, which can differ from the checkout's origin.
+`AGENT_TOOL_REVIEW_BASE_REF`, the base branch name such as `main` (not a
+remote-tracking ref like `origin/main`), and `AGENT_TOOL_REVIEW_BASE_OID`, its
+fetched commit. Fetch from the repository that owns the PR, which can differ
+from the checkout's origin.
 
 Record the exact base and HEAD before reviewing. The tool reviews raw committed
 files and excludes worktree edits. A zero exit means a complete review was

package/skills/open-pr/SKILL.md

@@ -11,9 +11,11 @@ do not assume the branch is named main. Preserve unrelated work and finish
 requested changes and appropriate checks before publishing them.
 
 Ensure the intended commit is on a feature branch and push it through the
-repository's normal push workflow. Respect existing push authorization; do not
-bypass hooks. If the user only requested a draft description, prepare that text
-without publishing a PR.
+repository's normal push workflow, naming the PR repository's remote and branch
+explicitly, as in `git push -u origin HEAD`; a bare push follows whatever
+upstream the branch tracks, which may be a local branch. Respect existing push
+authorization; do not bypass hooks. If the user only requested a draft
+description, prepare that text without publishing a PR.
 
 Write a title that satisfies the data-only `agent-tool.json` subject policy.
 Describe the concrete resulting behavior and relevant validation. Put multiline

package/skills/ship-pr/SKILL.md

@@ -11,8 +11,11 @@ concerns. Shipping authorizes this workflow within the user's stated scope.
 Preserve unrelated edits and honor requested stopping points such as open-PR
 only, report-only review, or keeping the feature branch.
 
-1. Finish the requested change on a feature branch. Validate it with appropriate
-   project checks and commit only the intended files.
+1. Finish the requested change on a feature branch. Create it with
+   `git switch --no-track -c <branch>`; settings such as
+   `branch.autosetupmerge=always` otherwise make it track a local branch.
+   Validate it with appropriate project checks and commit only the intended
+   files.
 2. Determine the current PR's base repository and branch, or the repository's
    default branch when no PR exists. Fetch and pin its exact base. Integrate it
    using the repository's normal workflow, resolving conflicts without losing

package/src/doctor.ts

@@ -3,7 +3,7 @@ import { loadConfig } from "./config";
 
 const specifications = [
   { name: "git", help: [] as string[], flags: [] as string[] },
-  { name: "gh", help: [] as string[], flags: [] as string[] },
+  { name: "gh", help: ["pr", "checks", "--help"], flags: ["--json"] },
   { name: "claude", help: ["--help"], flags: ["--safe-mode", "--permission-mode", "--effort"] },
   { name: "codex", help: ["exec", "--help"], flags: ["--ignore-user-config", "--ignore-rules", "--strict-config", "--ephemeral", "--output-last-message"] },
   { name: "opencode", help: ["run", "--help"], flags: ["--pure", "--variant", "--agent"] },

package/src/git/prContext.ts

@@ -370,8 +370,13 @@ export function assertPinnedReviewBaseRef(
 ): void {
   const expected = pinnedBaseRefName?.trim() ?? "";
   if (expected.length > 0 && expected !== actualBaseRefName) {
+    // A remote-tracking or full ref such as origin/main is a common mistake for
+    // the branch name; say so instead of reporting a retargeted PR.
+    const hint = expected.endsWith(`/${actualBaseRefName}`)
+      ? ` AGENT_TOOL_REVIEW_BASE_REF takes the base branch name; use '${actualBaseRefName}', not '${expected}'.`
+      : "";
     throw new Error(
-      `Review base changed from pinned branch '${expected}' to '${actualBaseRefName}'.`,
+      `Review base changed from pinned branch '${expected}' to '${actualBaseRefName}'.${hint}`,
     );
   }
 }

package/src/skills/bundled.ts

@@ -1,8 +1,8 @@
 // Generated by scripts/bundle-skills.ts; edit skills/*/SKILL.md.
 export const BUNDLED_SKILLS: Readonly<Record<string, string>> = {
-  "cross-agent-review": "---\nname: cross-agent-review\ndescription: Review committed branch changes with an independent Claude Code, Codex, or OpenCode reviewer, and repair actionable findings when requested.\n---\n\n# Cross-Agent Review\n\nUse the installed `agent-tool` executable. Read the repository's development and\nreview policy and `agent-tool.json` when present. Keep project validation commands\nand release rules in the repository; do not assume Bun, a workspace layout, or\nparticular CI job names.\n\nSelect a reviewer different from the coordinating agent when possible. Honor a\nrequested reviewer or effort; otherwise use an available independent reviewer.\nRun `agent-tool doctor` if CLI compatibility is uncertain.\n\nReview committed changes with `agent-tool review claude`, `agent-tool review codex`,\nor `agent-tool review opencode`. Optional effort is `low`, `medium`, `high`,\n`xhigh`, or `max`. For a local or non-GitHub repository, add `--base <commit-or-ref>`.\nFor a coordinated GitHub review, pin the fetched base using\n`AGENT_TOOL_REVIEW_BASE_REF` and `AGENT_TOOL_REVIEW_BASE_OID`; fetch from the\nrepository that owns the PR, which can differ from the checkout's origin.\n\nRecord the exact base and HEAD before reviewing. The tool reviews raw committed\nfiles and excludes worktree edits. A zero exit means a complete review was\nreturned; it does not mean the findings are non-blocking. Read the final\n`VERDICT: BLOCKER|MAJOR|MINOR|SUGGESTION|CLEAN` and the findings. A reviewer\nthat labels findings `[P0]` through `[P3]` uses the same scale: `[P0]` and\n`[P1]` are BLOCKER and MAJOR, `[P2]` and `[P3]` are MINOR and SUGGESTION.\n\nIf a CLI is unavailable, out of credits, or returns an unusable review, try another\navailable reviewer and disclose the fallback. Do not silently convert a failed\nreview into CLEAN or call an in-session review independent.\n\nFor report-only requests, report findings without changing files or history.\nWhen repairs are authorized, address actionable BLOCKER and MAJOR findings,\nvalidate with the repository's relevant checks, commit the repairs, and review\nthe new HEAD. Continue while meaningful progress is possible; report an impasse\nwhen progress requires a material user decision. A repaired commit is unreviewed\nuntil the next review completes. Preserve unrelated work.\n\nBefore reporting success, confirm HEAD still matches the reviewed commit and\nthat an existing PR points to that same commit. If the base moved, refresh it and\nreview again before shipping. Report reviewer, exact base and head IDs, verdict,\nremaining findings, validation, and any repairs performed. This skill does not\nauthorize pushing, opening a PR, or merging unless the user requested that work.\n",
-  "open-pr": "---\nname: open-pr\ndescription: Open a GitHub pull request for the current feature branch with a validated title and a reviewable description.\n---\n\n# Open PR\n\nUse the installed `agent-tool`. Follow repository policy for validation, commits,\nand branch naming. Resolve the repository and default branch with Git and `gh`;\ndo not assume the branch is named main. Preserve unrelated work and finish\nrequested changes and appropriate checks before publishing them.\n\nEnsure the intended commit is on a feature branch and push it through the\nrepository's normal push workflow. Respect existing push authorization; do not\nbypass hooks. If the user only requested a draft description, prepare that text\nwithout publishing a PR.\n\nWrite a title that satisfies the data-only `agent-tool.json` subject policy.\nDescribe the concrete resulting behavior and relevant validation. Put multiline\nbody text in a temporary file, then run:\n\n```sh\nagent-tool pr open 'feat: describe the change' < /path/to/pr-body.txt\n```\n\nOmitting the title uses the latest commit subject. The tool refuses duplicate\nopen PRs and requires the branch to be pushed at its local HEAD. It does not\npush for you. Resolve a fork's head/base identities explicitly if the repository\nuses fork PRs; the initial open helper supports same-repository branches.\n\nReport the created PR link and any remaining validation or review work.\n",
+  "cross-agent-review": "---\nname: cross-agent-review\ndescription: Review committed branch changes with an independent Claude Code, Codex, or OpenCode reviewer, and repair actionable findings when requested.\n---\n\n# Cross-Agent Review\n\nUse the installed `agent-tool` executable. Read the repository's development and\nreview policy and `agent-tool.json` when present. Keep project validation commands\nand release rules in the repository; do not assume Bun, a workspace layout, or\nparticular CI job names.\n\nSelect a reviewer different from the coordinating agent when possible. Honor a\nrequested reviewer or effort; otherwise use an available independent reviewer.\nRun `agent-tool doctor` if CLI compatibility is uncertain.\n\nReview committed changes with `agent-tool review claude`, `agent-tool review codex`,\nor `agent-tool review opencode`. Optional effort is `low`, `medium`, `high`,\n`xhigh`, or `max`. For a local or non-GitHub repository, add `--base <commit-or-ref>`.\nFor a coordinated GitHub review, pin the fetched base using\n`AGENT_TOOL_REVIEW_BASE_REF`, the base branch name such as `main` (not a\nremote-tracking ref like `origin/main`), and `AGENT_TOOL_REVIEW_BASE_OID`, its\nfetched commit. Fetch from the repository that owns the PR, which can differ\nfrom the checkout's origin.\n\nRecord the exact base and HEAD before reviewing. The tool reviews raw committed\nfiles and excludes worktree edits. A zero exit means a complete review was\nreturned; it does not mean the findings are non-blocking. Read the final\n`VERDICT: BLOCKER|MAJOR|MINOR|SUGGESTION|CLEAN` and the findings. A reviewer\nthat labels findings `[P0]` through `[P3]` uses the same scale: `[P0]` and\n`[P1]` are BLOCKER and MAJOR, `[P2]` and `[P3]` are MINOR and SUGGESTION.\n\nIf a CLI is unavailable, out of credits, or returns an unusable review, try another\navailable reviewer and disclose the fallback. Do not silently convert a failed\nreview into CLEAN or call an in-session review independent.\n\nFor report-only requests, report findings without changing files or history.\nWhen repairs are authorized, address actionable BLOCKER and MAJOR findings,\nvalidate with the repository's relevant checks, commit the repairs, and review\nthe new HEAD. Continue while meaningful progress is possible; report an impasse\nwhen progress requires a material user decision. A repaired commit is unreviewed\nuntil the next review completes. Preserve unrelated work.\n\nBefore reporting success, confirm HEAD still matches the reviewed commit and\nthat an existing PR points to that same commit. If the base moved, refresh it and\nreview again before shipping. Report reviewer, exact base and head IDs, verdict,\nremaining findings, validation, and any repairs performed. This skill does not\nauthorize pushing, opening a PR, or merging unless the user requested that work.\n",
+  "open-pr": "---\nname: open-pr\ndescription: Open a GitHub pull request for the current feature branch with a validated title and a reviewable description.\n---\n\n# Open PR\n\nUse the installed `agent-tool`. Follow repository policy for validation, commits,\nand branch naming. Resolve the repository and default branch with Git and `gh`;\ndo not assume the branch is named main. Preserve unrelated work and finish\nrequested changes and appropriate checks before publishing them.\n\nEnsure the intended commit is on a feature branch and push it through the\nrepository's normal push workflow, naming the PR repository's remote and branch\nexplicitly, as in `git push -u origin HEAD`; a bare push follows whatever\nupstream the branch tracks, which may be a local branch. Respect existing push\nauthorization; do not bypass hooks. If the user only requested a draft\ndescription, prepare that text without publishing a PR.\n\nWrite a title that satisfies the data-only `agent-tool.json` subject policy.\nDescribe the concrete resulting behavior and relevant validation. Put multiline\nbody text in a temporary file, then run:\n\n```sh\nagent-tool pr open 'feat: describe the change' < /path/to/pr-body.txt\n```\n\nOmitting the title uses the latest commit subject. The tool refuses duplicate\nopen PRs and requires the branch to be pushed at its local HEAD. It does not\npush for you. Resolve a fork's head/base identities explicitly if the repository\nuses fork PRs; the initial open helper supports same-repository branches.\n\nReport the created PR link and any remaining validation or review work.\n",
   "reset": "---\nname: reset\ndescription: Return a clean checkout to its updated default branch after confirmed shipping or an explicit checkout cleanup request.\n---\n\n# Reset\n\nThis is checkout cleanup, not a destructive Git reset. Read repository guidance\nfor setup and hooks. Determine the default branch through the repository's\nremote metadata rather than assuming main.\n\nCheck worktree and index first. Preserve user edits; if they prevent switching,\nreport the condition instead of discarding or automatically stashing them. For\npost-merge cleanup, confirm the PR is MERGED before removing a feature branch.\n\nFetch the default branch, switch to it, and update by fast-forward only. A\ndiverged default branch requires inspection rather than forced replacement.\nDelete a merged feature branch only within the requested cleanup scope and\nafter verifying its exact commit is the shipped commit; squash merging does not\nmake Git ancestry-based branch deletion proof of shipping. Honor keep-branch.\n\nRun only the hook installer or dependency setup documented by this repository\nwhen the updated checkout requires it. Do not assume a package manager or copy\nsetup commands from another project. Report final branch, commit, and any\nunfinished cleanup.\n",
-  "ship-pr": "---\nname: ship-pr\ndescription: Complete an authorized commit, independent review, repair, PR, CI, and squash-merge workflow for a GitHub repository.\n---\n\n# Ship PR\n\nUse the installed `agent-tool`. Read repository guidance and policy first;\nvalidation, versioning, package management, and hook installation remain project\nconcerns. Shipping authorizes this workflow within the user's stated scope.\nPreserve unrelated edits and honor requested stopping points such as open-PR\nonly, report-only review, or keeping the feature branch.\n\n1. Finish the requested change on a feature branch. Validate it with appropriate\n   project checks and commit only the intended files.\n2. Determine the current PR's base repository and branch, or the repository's\n   default branch when no PR exists. Fetch and pin its exact base. Integrate it\n   using the repository's normal workflow, resolving conflicts without losing\n   user work. If project policy versions packages, prepare versions against the\n   pinned base after every integration or repair and before each review, using\n   the project's commands or `agent-tool versions prepare <base-oid>`, which\n   commits bumped manifests and the refreshed lockfile.\n   `agent-tool versions resolve-conflicts` resolves conflicts confined to\n   version fields. Review the resulting committed HEAD with an independent\n   reviewer using the bundled cross-agent-review skill. Repair blocking findings\n   and review every changed HEAD again. Review failure blocks shipping.\n3. Push the reviewed HEAD through normal hooks, then verify the pushed SHA still\n   equals the reviewed SHA. If a hook changed content or HEAD, review that result.\n   Open the PR using the open-pr skill, or update the existing PR as needed.\n4. Allow any configured review bots time to respond, then fetch unresolved PR\n   review threads. Follow repository policy for feedback: fix valid findings,\n   reply in the original threads, and resolve only fully addressed comments.\n   Validate, commit, push, and independently review every feedback or CI repair.\n   Wait for CI, recheck the live base, PR base branch, and local and remote heads.\n   A changed base requires integration, validation, and another review. When\n   versions are managed, `agent-tool versions check <base-oid>` must pass for the\n   live base. Use the squash-merge skill to merge the exact reviewed HEAD.\n5. After confirmed MERGED, honor keep-branch; otherwise use the reset skill to\n   return to the updated default branch and apply any documented project setup.\n6. When the project deploys the merged branch, verify the deployment for the\n   merge commit and run its documented live checks. Report deployment failures\n   separately from a successful merge; follow project policy for repairs.\n\nNever infer a clean review from process success alone or carry a review across\ncontent changes. Do not weaken configured CI policy to get a merge through.\nIf a step fails, preserve useful intermediate work and report the concrete\nremaining issue. Report PR link, merged commit, review verdict, validation, and\nfinal checkout state.\n",
+  "ship-pr": "---\nname: ship-pr\ndescription: Complete an authorized commit, independent review, repair, PR, CI, and squash-merge workflow for a GitHub repository.\n---\n\n# Ship PR\n\nUse the installed `agent-tool`. Read repository guidance and policy first;\nvalidation, versioning, package management, and hook installation remain project\nconcerns. Shipping authorizes this workflow within the user's stated scope.\nPreserve unrelated edits and honor requested stopping points such as open-PR\nonly, report-only review, or keeping the feature branch.\n\n1. Finish the requested change on a feature branch. Create it with\n   `git switch --no-track -c <branch>`; settings such as\n   `branch.autosetupmerge=always` otherwise make it track a local branch.\n   Validate it with appropriate project checks and commit only the intended\n   files.\n2. Determine the current PR's base repository and branch, or the repository's\n   default branch when no PR exists. Fetch and pin its exact base. Integrate it\n   using the repository's normal workflow, resolving conflicts without losing\n   user work. If project policy versions packages, prepare versions against the\n   pinned base after every integration or repair and before each review, using\n   the project's commands or `agent-tool versions prepare <base-oid>`, which\n   commits bumped manifests and the refreshed lockfile.\n   `agent-tool versions resolve-conflicts` resolves conflicts confined to\n   version fields. Review the resulting committed HEAD with an independent\n   reviewer using the bundled cross-agent-review skill. Repair blocking findings\n   and review every changed HEAD again. Review failure blocks shipping.\n3. Push the reviewed HEAD through normal hooks, then verify the pushed SHA still\n   equals the reviewed SHA. If a hook changed content or HEAD, review that result.\n   Open the PR using the open-pr skill, or update the existing PR as needed.\n4. Allow any configured review bots time to respond, then fetch unresolved PR\n   review threads. Follow repository policy for feedback: fix valid findings,\n   reply in the original threads, and resolve only fully addressed comments.\n   Validate, commit, push, and independently review every feedback or CI repair.\n   Wait for CI, recheck the live base, PR base branch, and local and remote heads.\n   A changed base requires integration, validation, and another review. When\n   versions are managed, `agent-tool versions check <base-oid>` must pass for the\n   live base. Use the squash-merge skill to merge the exact reviewed HEAD.\n5. After confirmed MERGED, honor keep-branch; otherwise use the reset skill to\n   return to the updated default branch and apply any documented project setup.\n6. When the project deploys the merged branch, verify the deployment for the\n   merge commit and run its documented live checks. Report deployment failures\n   separately from a successful merge; follow project policy for repairs.\n\nNever infer a clean review from process success alone or carry a review across\ncontent changes. Do not weaken configured CI policy to get a merge through.\nIf a step fails, preserve useful intermediate work and report the concrete\nremaining issue. Report PR link, merged commit, review verdict, validation, and\nfinal checkout state.\n",
   "squash-merge": "---\nname: squash-merge\ndescription: Squash-merge a reviewed GitHub pull request while binding the mutation to the reviewed commit and checking CI.\n---\n\n# Squash Merge\n\nUse the installed `agent-tool` and repository merge policy. Merge only within\nthe user's authorized scope. Have the exact reviewed HEAD, base commit, and base\nbranch available, and read the verdict and unresolved findings. BLOCKER or MAJOR\nfindings require repair and a new review before merging.\nFollow the repository's review-bot policy and require all actionable blocking\nreview feedback to be addressed before merging.\n\nWait for required checks using `gh pr checks --watch --fail-fast`. Refresh the\nPR and live base from the repository that owns the PR. Confirm local HEAD and PR\nHEAD both equal the reviewed commit, the base branch is unchanged, the live base\nstill equals the reviewed base, and that base is an ancestor of reviewed HEAD.\nIf any identity changed, refresh, validate, and review again.\n\nUse a title that satisfies `agent-tool.json` and pass both reviewed HEAD and\nbase branch:\n\n```sh\nagent-tool pr merge 'feat: describe the change' <reviewed-head-oid> <base-branch>\n```\n\nThe helper enforces HEAD atomically through GitHub's `expectedHeadOid`, checks\nCI, rejects queued or automatic merges, and creates a subject-only squash with\nthe PR reference. GitHub has no atomic expected-base argument in this mutation;\nrepository branch protection must enforce any required base freshness. With\n`merge.requireStrictBaseFreshness`, the helper refuses to merge unless an\nactive strict status ruleset that the actor cannot bypass protects the base. Do\nnot retarget the PR concurrently with merging.\n\nConfirm GitHub reports MERGED before any cleanup. A failed or uncertain mutation\nis not evidence of a merge. Preserve the branch on failure. After a confirmed\nmerge, perform checkout cleanup only when requested or as part of an authorized\nshipping workflow. Report the PR and merge result.\n"
 };