@a2f0/agent-tool 0.1.17 → 0.1.18

package/README.md

@@ -1,440 +1,70 @@
 # agent-tool
 
-A CLI for independent agent code reviews, guarded GitHub PR operations, package
-version management, and portable skills for Claude Code, Codex, and OpenCode.
-
-- **Review** a committed branch with a different agent than the one that wrote
-  it, using a pinned, read-only snapshot.
-- **Ship** pull requests: open them, check CI, and squash-merge only the exact
-  reviewed commit.
-- **Version** packages: bump changed packages against an exact base and keep
-  `bun.lock` in sync.
-- **Share skills**: install the same workflow instructions where each harness
-  discovers them, and check them in CI.
-- **Render brand images**: build app icons, splash screens, favicons, and store
-  graphics from the SVGs in `assets/brand/`, with every size and destination
-  declared in `agent-tool.json`.
-- **Compact output**: run noisy commands with full private logs and bounded
-  diagnostics, keeping routine output out of an agent's context.
+Shared Git, GitHub, review, validation, and release workflows for repositories
+coordinated by Claude Code, Codex, and OpenCode. Repository policy stays in
+`agent-tool.json`; portable skills coordinate independently reviewed changes.
 
 ## Install
 
-### From npm
-
 ```sh
 bun add --dev --exact @a2f0/agent-tool
-# or
+# npm projects also need Bun on PATH to run the executable:
 npm install --save-dev --save-exact @a2f0/agent-tool
 ```
 
-The package ships the TypeScript source and embedded skills, with no install
-scripts or build step. Bun runs the executable, so Bun must be on `PATH`
-wherever it runs, including npm projects and CI; without it, the shell reports
-`env: bun: No such file or directory`.
-
-Add a script such as `"agent-tool": "agent-tool"` and run
-`bun run agent-tool --help`. For a command with an empty positional argument,
-invoke `node_modules/.bin/agent-tool` directly, for example
-`node_modules/.bin/agent-tool pr merge '' "$REVIEWED_SHA" "$REVIEW_BASE_REF"`.
-
-To use an unreleased commit, pin its full SHA from GitHub:
-
-```json
-{
-  "devDependencies": {
-    "@a2f0/agent-tool": "github:a2f0/agent-tool#<full-commit-sha>"
-  }
-}
-```
-
-npm records a GitHub dependency in `package-lock.json` as a `git+ssh` URL, but
-`npm ci` installs this public repository without SSH credentials.
-
-### Standalone executable
-
-Bun compiles the CLI and its skills into one executable that needs no Node, Bun,
-or npm dependencies at runtime:
+The npm package ships source and embedded skills with no install script. It needs
+Bun 1.3.11 or newer; version preparation needs Bun 1.4 or newer. Git is required,
+and GitHub operations require an authenticated `gh` supporting `pr checks --json`.
+Independent reviews require an authenticated Claude Code, Codex, or OpenCode CLI.
+A compiled standalone executable needs no Bun or Node at runtime.
 
 ```sh
-bun install --frozen-lockfile
-bun run build
-./dist/agent-tool --help
+bun run agent-tool init
+bun run agent-tool skills install --apply
+bun run agent-tool doctor
 ```
 
-The executable works when copied anywhere. See [Releases](#releases) for
-platform archives, a Homebrew formula, and Debian packages.
-
-### Requirements
+Add `"agent-tool": "agent-tool"` to package scripts, or invoke
+`node_modules/.bin/agent-tool` directly. Use the direct executable for an empty
+positional argument. Global `--repo <directory>` and `--config <file>` select a
+checkout and explicit policy file. Restart the agent harness after installing
+skills if its discovery cache needs refreshing.
 
-- Git.
-- An authenticated GitHub CLI (`gh`) for `pr` commands. `pr merge` needs a
-  `gh` whose `pr checks` supports `--json`; gh 2.45, still shipped by some
-  distributions, fails with `unknown flag: --json`.
-- An authenticated CLI for each agent you review with: `claude`, `codex`, or
-  `opencode`.
-- Bun 1.3.11 or newer to run the npm package.
-- 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 the flags the tool needs
-from each CLI, such as `gh pr checks --json` for merging, without calling a model.
-
-## Quick start
-
-These examples call `agent-tool` from `PATH`. With the npm package, use
-`bun run agent-tool` or `node_modules/.bin/agent-tool` instead.
-
-```sh
-# Review the current branch with an independent agent:
-agent-tool review codex
-# Review another checkout against a local base, without GitHub:
-agent-tool --repo ../some-project review opencode high --base main
-
-# Create project policy, then preview and install the shared skills:
-agent-tool init
-agent-tool skills install
-agent-tool skills install --apply
-```
-
-## Commands
-
-| Command | Behavior |
-| --- | --- |
-| `run [--label text] [--max-bytes N] [--tail-lines N] -- <command> [args...]` | Run with full local logs and compact results; preserve exit status |
-| `logs <file> [--max-bytes N] [--tail-lines N]` | Inspect a bounded, terminal-safe tail of a local file |
-| `review claude\|codex\|opencode [effort] [--base ref]` | Review committed HEAD using a pinned raw-file snapshot |
-| `pr open [title]` | Open a same-repository PR; body from stdin; branch already pushed |
-| `pr merge <subject-or-empty> <head-oid> <base-branch>` | Check CI and synchronously squash the reviewed HEAD |
-| `versions plan\|bump\|check <base-oid>` | Plan, rewrite, or check package versions against an exact base |
-| `versions prepare <base-oid>` | Bump, refresh `bun.lock`, validate, and commit versions; print a JSON receipt |
-| `versions resolve-conflicts` | Resolve only version-field conflicts in configured manifests |
-| `dependencies check-terraform-plan <json-file>` | Read-only screening for destructive or incomplete Terraform JSON plans |
-| `skills list` | List embedded portable skills |
-| `skills install [--harness all\|claude\|codex\|opencode] [--apply]` | Preview by default; install or update managed skills |
-| `skills check [--harness all\|claude\|codex\|opencode]` | Read-only CI check for current managed skills |
-| `images list [target...]` | List the files each image target writes, without rendering |
-| `images build [target...] [--out dir]` | Render image targets from `assets/brand/*.svg`; `--out` redirects one target |
-| `init` / `config show` | Create or inspect data-only project policy |
-| `doctor` | Inspect local versions and required CLI flags without running a model |
-
-Global options are `--repo <directory>` and `--config <file>`. Effort accepts
-`low`, `medium`, `high`, `xhigh`, and `max`; the default is `xhigh` for Claude
-and `high` for Codex and OpenCode. Legacy camelCase action names, listed in
-`--help`, remain available. Legacy `squashMerge` also accepts a manual form
-without a reviewed HEAD; prefer `pr merge`.
-
-A successful review exit means a complete review was returned, ending in a
-`VERDICT:` line. BLOCKER or MAJOR findings still require action. The review
-command does not repair, push, or merge; the shipping skills coordinate that
-work.
-
-### Compact command output
+## Normal usage
 
 ```sh
+agent-tool branch create chore/maintenance --base main --remote origin
+agent-tool repo context
 agent-tool run --label tests -- bun test
-agent-tool run --label build -- npm run build
-agent-tool run --label checks -- sh -c 'npm run lint && npm test'
-agent-tool logs /path/from/receipt/output.log --max-bytes 8192 --tail-lines 80
-```
-
-`run` executes the argv after `--` directly, without a shell, in the current
-directory (or `--repo`), with inherited environment and stdin. Use an explicit
-shell only when the command needs shell syntax. The child receives regular files
-for stdout and stderr, so interactive/TTY programs should run directly. This
-works outside Git and does not depend on project policy or a package manager.
-Use it for finite commands; long-running servers need their own lifecycle.
-
-Both streams go directly to one private log: even gigabytes of output do not
-accumulate in the runner's memory. On completion, stdout contains one JSON
-receipt with `status`, `exitCode`, `signal`, `durationMs`, `outputBytes`, and
-`log` (plus an optional label of at most 120 characters). Command arguments and
-environment are not copied to the receipt. A success emits no log content;
-failure adds a terminal-control-stripped tail on stderr. The default tail is at
-most 4096 bytes and 40 lines, with explicit limits up to 65536 bytes and 1000
-lines. Limits bound the excerpt after decoding too, including one huge line or
-invalid UTF-8; receipt metadata is additional. A command's numeric status is
-preserved, missing executables return 127, and other launch failures return 126.
-On macOS/Linux, SIGINT, SIGTERM, and SIGHUP are forwarded to the child process
-group, with SIGKILL escalation after five seconds; the runner then terminates by
-the original signal. Children that create a separate session escape that group;
-SIGKILL of the runner cannot be intercepted. The command is not a sandbox.
-
-Logs live in unique `agent-tool-run-*` directories under the system temporary
-directory, with mode 0700 directories and 0600 files. They are retained until you
-remove the specific directory reported by the receipt or the OS cleans temporary
-files. Remove task logs after investigation; long or repeated commands can use
-substantial disk space. There is no automatic age sweep or disk quota. Logs are
-complete, raw, and may contain secrets; terminal cleanup is not secret redaction.
-`logs` reads any explicitly supplied regular local file, including symlink targets;
-it does not authenticate a file as an agent-tool artifact.
-
-Use bounded log inspection or scoped searches for a failure, required warnings,
-coverage, timing assertions, or build artifacts; do not reread successful suite
-logs wholesale. Success means the command exited zero, not that its logs contain
-no warnings. Keep structured output and decisions visible: run `review`,
-`versions prepare`, audit reports, and infrastructure plan guards directly.
-Review commands retain full reviewer stderr in separate private
-`agent-tool-review-log-*` directories and show bounded stderr on failure, while
-always displaying the final findings and verdict. Empty reviewer logs are removed.
-The bundled shipping, review, and dependency skills use this distinction.
-
-## Configuration
-
-`agent-tool init` creates `agent-tool.json` and never overwrites an existing
-file. Missing settings use defaults; misspelled keys, invalid types, and unknown
-schema versions fail before any work begins. `--config <file>` or
-`AGENT_TOOL_CONFIG` selects an explicit policy file, for example to review a
-feature checkout with policy from a trusted source.
-
-```json
-{
-  "schemaVersion": 1,
-  "subject": { "conventional": true, "maxLength": 50 },
-  "merge": {
-    "requiredChecks": [{ "name": "CI gate", "workflow": "CI" }],
-    "requireStrictBaseFreshness": true
-  },
-  "review": {
-    "claudeModel": null,
-    "codexModel": null,
-    "opencodeModel": "deepseek/deepseek-v4-pro",
-    "opencodeVariants": { "xhigh": "max" },
-    "timeoutMs": 600000
-  },
-  "versions": {
-    "packages": ["packages/api", "packages/client"],
-    "bundles": ["packages/client"],
-    "lockfile": "bun.lock",
-    "validate": [["bun", "run", "lint", "--", "--staged"]],
-    "commitMessage": "chore: bump package versions"
-  },
-  "pr": { "rejectClaudeBranding": true }
-}
-```
-
-The policy is data only: no commitlint binary or JavaScript config runs.
-
-- **`subject`**: commit and PR titles default to conventional commits with a
-  72-character limit.
-- **`merge`**: by default a PR must report at least one check, and every check
-  must succeed or be skipped. Named required checks must succeed; configure
-  them before shipping.
-- **`review`**: Claude and Codex use their CLI defaults unless a model is set.
-  Set `opencodeModel` to a model your account supports. `opencodeVariants`
-  replaces the default effort-to-variant map (`xhigh` to `max`); an effort
-  level missing from the map is passed to OpenCode unchanged.
-
-### Versions
-
-Version helpers use the configured package directories, or discover committed
-`package.json` workspaces when `versions.packages` is null. `.` names the
-repository's root package, which then counts as changed when any file changes,
-including files in other configured packages. A changed package moves one patch
-past the base; a deliberate major or minor bump is kept. `plan`, `bump`, and
-`check` neither regenerate lockfiles nor commit.
-
-`versions.bundles` names versioned packages whose published artifact includes
-the workspace packages they depend on. Such a package also counts as changed
-when any workspace package it reaches through `workspace:` ranges in
-`dependencies` changes, directly or transitively; an alias range such as
-`workspace:crypto@*` names its target. `devDependencies` and
-`peerDependencies` do not count. A bundled package whose only change is its
-version does not move the bundle.
-
-`versions prepare` runs the whole sequence before a review snapshot:
-
-1. It requires a clean worktree on an attached branch with the exact base
-   already merged.
-2. It rewrites versions and, when `versions.lockfile` is `"bun.lock"` (the
-   default), runs `bun install --lockfile-only --ignore-scripts`. It then
-   verifies that `bun.lock` records every workspace version, because Bun before
-   1.4 exits successfully without refreshing them. Set `versions.lockfile` to
-   null for projects without a Bun lockfile.
-3. Each `versions.validate` command runs without a shell against the staged
-   result. Commands resolve on `PATH` outside the repository.
-4. It commits with `versions.commitMessage`, running the project's commit hooks,
-   and requires the commit to reproduce the prepared tree.
-
-On success it prints a JSON receipt with `baseOid`, `startHead`, `headOid`,
-`committed`, `lockfileChanged`, and the rewritten `versions`. A failure before
-the commit restores the manifests, lockfile, and index, unless HEAD or other
-paths changed, in which case it leaves that state for inspection. Repeating
-against the same base creates no commit.
-
-### Images
-
-`images` declares named targets of brand images rendered from SVG sources in
-`assets/brand/`. Each output names its file, pixel size or variants (such as
-Android densities or `@2x`/`@3x`), and the layers composed into it:
-
-```json
-{
-  "schemaVersion": 1,
-  "images": {
-    "targets": {
-      "ios": {
-        "dir": "ios/App/Assets.xcassets",
-        "outputs": [
-          {
-            "path": "AppIcon.appiconset/AppIcon.png",
-            "size": 1024,
-            "opaque": true,
-            "layers": [{ "source": "background", "fit": "cover" }, { "source": "logo", "scale": 0.7 }]
-          }
-        ]
-      }
-    }
-  }
-}
+agent-tool review claude
+agent-tool branch push <reviewed-head> --remote origin
+agent-tool pr open 'chore: maintain repository' < /tmp/pr-body.txt
+agent-tool pr checks --wait --head <reviewed-head>
+agent-tool pr preflight <reviewed-head> <base-branch> <reviewed-base>
+agent-tool pr merge 'chore: maintain repository' <reviewed-head> <base-branch>
 ```
 
-`agent-tool images build ios` writes PNG, ICO, SVG, and Android color resource
-outputs with a bundled WebAssembly renderer, so builds need no ImageMagick or
-librsvg and render identically on every machine. See the
-[image reference](docs/images.md) for every setting.
-
-## Portable skills
-
-Canonical skills live in `skills/`. The build embeds them, and the installer
-writes the same bytes where each harness discovers them:
-
-| Target | Project discovery directory |
-| --- | --- |
-| Claude Code | `.claude/skills` |
-| Codex | `.agents/skills` |
-| OpenCode alone | `.opencode/skills` |
-| All three | `.agents/skills` and `.claude/skills`; OpenCode discovers both |
-
-Discovery paths follow the [Codex](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills),
-[Claude Code](https://code.claude.com/docs/en/skills), and
-[OpenCode](https://opencode.ai/docs/skills/) documentation. Restart the harness
-if new skills do not appear. OpenCode may list identical skills from both
-paths.
-
-The bundle provides `cross-agent-review`, `open-pr`, `squash-merge`, `ship-pr`,
-`reset`, and `update-dependencies`. They make no package-manager or project-layout
-assumptions:
-
-- Keep validation commands, review-bot rules, and deployment checks in the
-  project's `AGENTS.md`.
-- Keep title and required-check policy in `agent-tool.json`.
-
-The installer is project-scoped and does not touch global harness settings, MCP
-configuration, or authentication. It records ownership in
-`.agent-tool-skills.json`, previews changes unless `--apply` is given, and
-refuses to overwrite unmanaged files, locally edited skills, or symlinks; there
-is no force mode. After updating the dependency, run
-`agent-tool skills install --apply` and commit the skills with
-`.agent-tool-skills.json`. Run `agent-tool skills check` in hooks and CI; it
-fails for missing, outdated, unmanaged, or edited skills without writing
-anything. Use the same `--harness` for install and check.
-
-### Dependency upgrades
-
-Invoke `update-dependencies` to upgrade repository-owned dependencies, runtimes,
-and tool pins with compatibility checks and safe infrastructure previews.
-See the [dependency upgrade guide](docs/dependency-upgrades.md) for advisory
-checks, preview limits, the Terraform plan guard, and maintaining upgrade records.
-
-## Review guarantees and limits
-
-Reviews run against exact base and head snapshots. Review policy comes from the
-base commit. Files are materialized from raw Git blobs with collision and path
-validation, and diffs are text-only without external drivers. Snapshots are
-cleaned up, output must end in a verdict, and an incomplete but successful run
-is retried once. Helper Git operations disable hooks and replace objects.
-Reviewer executables must resolve outside the project, reviews time out, and a
-review is rejected if HEAD moves before it returns.
-
-Each harness runs with its own read-only protections:
-
-- **Claude**: safe mode and read-only tools.
-- **Codex**: an ephemeral session, snapshot-scoped filesystem permissions, no
-  inherited environment for model commands, hosted web search disabled, and
-  final-message capture.
-- **OpenCode**: a neutral directory, pure mode, and inline permissions that
-  deny every tool except specific read-only ones.
-
-Unknown or unsupported CLI flags fail the run instead of silently dropping a
-protection. These are harness-level protections, not uniform OS isolation:
-Claude and OpenCode rely on their own permission implementations, and every
-reviewer runs with local authentication in the host environment. A verdict
-shows that a review completed, not that its findings are correct.
-
-`pr merge` binds the squash to the reviewed HEAD through GitHub's atomic
-expected-HEAD check. GitHub has no equivalent expected-base check, so the skills
-recheck the base, and repository protection must enforce stricter freshness.
-With `merge.requireStrictBaseFreshness`, `pr merge` refuses unless an active
-repository ruleset that the authenticated actor cannot bypass requires strict
-status checks on the base. Classic branch protection is not inspected. Reviews
-can resolve fork PR bases; `pr open` supports same-repository branches.
-
-## Development
-
-Development and build/release workflows use the Bun version pinned in
-`.mise.toml` and TypeScript 7.0.2. [mise](https://mise.jdx.dev/) installs the
-same Bun version locally and in CI.
-The compiler is used through `tsc`; this repository does not depend on its removed
-JavaScript compiler API. Runtime consumers still support Bun 1.3.11 or newer;
-CI also runs the installed-package smoke and plan-guard tests on that minimum.
-
-```sh
-mise install
-bun install --frozen-lockfile
-bun run typecheck
-bun test
-bun scripts/smoke-package.ts
-bun run build
-bun scripts/smoke.ts dist/agent-tool
-```
-
-`bun run build` regenerates `src/skills/bundled.ts` from `skills/*/SKILL.md`;
-commit it with skill changes. The package smoke test installs the packed npm
-tarball into a temporary project. The compiled smoke test drives all three
-review adapters through local stubs with Bun and Node absent from `PATH`, and
-makes no model calls. CI runs these checks on Linux and macOS and builds a
-Debian package on Linux.
-
-## Releases
-
-### npm
-
-`ship-pr` bumps the root `package.json` patch version on each merge, and the
-[publish workflow](.github/workflows/npm-publish.yml) publishes each version
-newer than npm's `latest` using
-[trusted publishing](https://docs.npmjs.com/trusted-publishers), with
-provenance and no stored npm token. The publish job runs in the `npm`
-environment, which only `main` can deploy to; npm's trusted publisher names
-that environment and `npm-publish.yml`. Runs never overlap, and when merges land
-together only the newest pending run starts, so intermediate versions may never
-reach npm. npm adds a trusted publisher only to an existing package, so the
-first version was published by hand; the workflow fails with that instruction
-when the package is missing from npm.
-
-### Standalone archives and packages
-
-```sh
-# macOS and Linux ARM64/x64 archives, and a Homebrew formula with SHA-256 values:
-bun scripts/release.ts a2f0/agent-tool
-
-# A Debian package (Linux with dpkg-deb); substitute the release version:
-scripts/package-deb.sh dist/agent-tool-<version>-linux-x64/bin/agent-tool amd64
-sudo apt install ./dist/agent-tool_<version>_amd64.deb
-```
-
-These scripts only create local artifacts. The manually triggered
-`Release artifacts` workflow runs them and uploads the archives, the formula,
-and amd64 and arm64 Debian packages as workflow artifacts. To offer
-`brew install <owner>/<tap>/agent-tool`, host the archives at the formula's
-URLs and publish `agent-tool.rb` in a tap. `apt install agent-tool` by name also
-requires a signed APT repository. Neither a tap nor an APT repository exists
-yet.
-
-## Further reading
-
-- [Design](docs/design.md): component boundaries and implementation choices.
-- [Images](docs/images.md): brand image sources, targets, and output settings.
-- [Validation record](docs/validation.md): observed test results and their
-  limits.
-- [Extraction record](docs/extraction.md): the projects this tool was extracted
-  from.
+Use the `ship-pr` skill for the full validation, versioning, independent review,
+feedback, merge, cleanup, and deployment workflow. A successful review process
+means a complete review was returned; read its final verdict and address blocking
+findings before shipping. Pushing and merging remain explicit authorized actions.
+
+## Documentation
+
+- [Shared workflows](docs/workflows.md): branches, commit trust, copied hooks,
+  PR checks/threads, cleanup, CI aggregate gates, release verification, durable
+  validation receipts, and toolchain/protection diagnostics.
+- [CLI reference](docs/reference.md): existing review, version, skill installation,
+  command capture, configuration, and distribution contracts.
+- [Development](docs/development.md): setup, source layout, validation, and release
+  procedures for this package.
+- [Images](docs/images.md): declarative brand sources and generated outputs.
+- [Dependency maintenance](docs/dependency-upgrades.md): active compatibility
+  constraints and the dependency-update workflow.
+- [Design](docs/design.md) and [extraction history](docs/extraction.md): component
+  boundaries, origins, and explicit implementation limits.
+
+The tool does not execute repository JavaScript as policy, bypass Git hooks for
+shipping mutations, discard local edits, or silently weaken required CI checks.
+Project builds, tests, deployment previews, health checks, and specialized checks
+remain repository commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2f0/agent-tool",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "packageManager": "bun@1.4.3",
   "type": "module",
   "description": "Portable cross-agent review, PR workflows, and shared skills",
@@ -28,7 +28,7 @@
     "start": "bun src/index.ts",
     "test": "bun test src scripts",
     "typecheck": "tsc --noEmit",
-    "generate": "bun scripts/bundle-skills.ts",
+    "generate": "bun scripts/build/bundle-skills.ts",
     "build": "bun run generate && bun build --compile --minify src/index.ts --outfile dist/agent-tool"
   },
   "devDependencies": {

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

@@ -30,7 +30,8 @@ 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
+Use `agent-tool repo context --fetch` to resolve and fetch the PR's own base,
+then 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
 returned; it does not mean the findings are non-blocking. Read the final
 `VERDICT: BLOCKER|MAJOR|MINOR|SUGGESTION|CLEAN` and the findings. A reviewer

package/skills/open-pr/SKILL.md

@@ -6,16 +6,15 @@ description: Open a GitHub pull request for the current feature branch with a va
 # Open PR
 
 Use the installed `agent-tool`. Follow repository policy for validation, commits,
-and branch naming. Resolve the repository and default branch with Git and `gh`;
+and branch naming. Resolve the repository and default branch with `agent-tool repo context`;
 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, 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.
+Ensure the intended commit is on a feature branch and use
+`agent-tool branch push <reviewed-head> --remote <remote>` through normal hooks.
+It names the destination explicitly and verifies local/remote HEAD afterward;
+a changed result needs another review. Respect existing push authorization.
+If the user only requested a draft description, prepare it without publishing.
 
 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/reset/SKILL.md

@@ -9,17 +9,27 @@ This is checkout cleanup, not a destructive Git reset. Read repository guidance
 for setup and hooks. Determine the default branch through the repository's
 remote metadata rather than assuming main.
 
-Check worktree and index first. Preserve user edits; if they prevent switching,
-report the condition instead of discarding or automatically stashing them. For
-post-merge cleanup, confirm the PR is MERGED before removing a feature branch.
+For post-merge cleanup, preview with
+`agent-tool repo cleanup <PR-number> <shipped-head>`, then run it with `--apply`
+within the authorized cleanup scope. It requires a confirmed MERGED PR, preserves
+local edits, checks exact local/remote feature commits, verifies the merge is on
+the default branch, and fast-forwards that branch. Pass `--keep-branch` when the
+user asked to preserve feature refs. Read the receipt's completed steps if a
+later operation fails; do not claim full cleanup from a partial result.
 
-Fetch the default branch, switch to it, and update by fast-forward only. A
-diverged default branch requires inspection rather than forced replacement.
-Delete a merged feature branch only within the requested cleanup scope and
-after verifying its exact commit is the shipped commit; squash merging does not
-make Git ancestry-based branch deletion proof of shipping. Honor keep-branch.
+Remote branch deletion uses GitHub REST after checking the live ref to avoid
+pre-push hooks. The API has no atomic expected-OID delete guard; the check and
+deletion retain a small concurrent-update window. Fork PRs require manual remote
+handling and are refused by the shared cleanup command.
 
-Run only the hook installer or dependency setup documented by this repository
-when the updated checkout requires it. Do not assume a package manager or copy
-setup commands from another project. Report final branch, commit, and any
-unfinished cleanup.
+For an explicit checkout cleanup without a merged PR, preserve all feature refs:
+check worktree/index, resolve the default branch with `repo context`, fetch it,
+switch, and update by fast-forward only. Never discard or automatically stash
+edits, force a diverged default branch, or infer shipping from Git ancestry after
+a squash merge.
+
+Run the repository's documented dependency/hook setup if required. When copied
+hooks are configured, use `agent-tool hooks check` and `hooks install --apply`;
+inspect unmanaged hooks before an explicit `--adopt`, which backs them up.
+Do not assume a package manager. Report final branch, commit, and unfinished
+cleanup or setup.