@a2f0/agent-tool 0.1.1

package/README.md

@@ -0,0 +1,288 @@
+# agent-tool
+
+A standalone CLI for independent agent reviews, GitHub PR operations, package
+version helpers, and portable skills for Claude Code, Codex, and OpenCode.
+Extracted from the agent tooling in the projects under `~/github`.
+
+The first implementation retains TypeScript and the existing regression suite.
+Bun compiles the code and skill text into one executable, so installed users do
+not need Node, Bun, TypeScript, or repository-local npm dependencies. The current
+macOS ARM64 executable is approximately 58 MiB because it includes its runtime.
+Rust remains a reasonable later implementation choice; it is not required for
+Brew or Debian packaging. See [the design](docs/design.md) and
+[extraction record](docs/extraction.md).
+
+## Try it
+
+Development and CI use Bun 1.4.2. The source CLI runs on Bun 1.3.11 or newer,
+but `versions prepare` needs Bun 1.4 or newer on PATH to refresh workspace
+versions in `bun.lock`. Runtime requires Git; GitHub commands also require
+authenticated `gh`. Review requires an authenticated CLI for the chosen agent.
+
+```sh
+bun install --frozen-lockfile
+bun run build
+./dist/agent-tool --help
+./dist/agent-tool doctor
+
+# Point the installed tool at an existing project:
+./dist/agent-tool --repo ../some-project review codex
+# Review against an explicit local base without GitHub:
+./dist/agent-tool --repo ../some-project review opencode high --base main
+
+# Preview shared skills, then install them when ready:
+./dist/agent-tool --repo ../some-project skills install
+./dist/agent-tool --repo ../some-project skills install --apply
+```
+
+The same binary works when copied outside this repository. No sibling project
+has to retain `packages/agent-tool` once its callers are migrated.
+
+### Use as a package dependency
+
+Projects can install the source CLI from npm as `@a2f0/agent-tool`:
+
+```sh
+bun add --dev --exact @a2f0/agent-tool
+# or
+npm install --save-dev --save-exact @a2f0/agent-tool
+```
+
+Run `bun run agent-tool --help` after adding a script such as
+`"agent-tool": "agent-tool"`. The package exposes
+`node_modules/.bin/agent-tool`; invoke it directly for commands containing an
+empty positional argument, such as
+`node_modules/.bin/agent-tool pr merge '' "$REVIEWED_SHA" "$REVIEW_BASE_REF"`.
+The source package includes the CLI and embedded skills and needs no dependency
+install scripts or compile step. The executable is TypeScript run by Bun, 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`. The standalone binary
+described above remains available for use without Bun.
+
+To use an unreleased commit, pin a full commit SHA from GitHub instead:
+
+```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.
+
+## Commands
+
+| Command | Behavior |
+| --- | --- |
+| `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 |
+| `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 |
+| `init` / `config show` | Create or inspect data-only project policy |
+| `doctor` | Inspect local versions and required CLI flags without running a model |
+
+Effort accepts `low`, `medium`, `high`, `xhigh`, and `max`. Defaults are `xhigh`
+for Claude and `high` for Codex and OpenCode. Older camelCase action names remain
+available; run `--help` for the compatibility list. The modern merge command
+requires reviewed HEAD and base branch; legacy `squashMerge` also retains its
+manual, unguarded form.
+
+A successful review exit means a complete review was returned, including a
+`VERDICT:` line. BLOCKER or MAJOR findings still require action. The review CLI
+does not repair, push, or merge; the coordinating skills orchestrate that work.
+
+## Project configuration
+
+Run `agent-tool init` in a project to create `agent-tool.json`. Existing policy
+files are never overwritten. Missing settings use defaults; misspelled keys,
+invalid types, and unknown schema versions fail before work begins. Global
+`--config <file>` or `AGENT_TOOL_CONFIG` selects an explicit policy file, useful
+when reviewing a feature checkout with policy supplied 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"],
+    "lockfile": "bun.lock",
+    "validate": [["bun", "run", "lint", "--", "--staged"]],
+    "commitMessage": "chore: bump package versions"
+  },
+  "pr": { "rejectClaudeBranding": true }
+}
+```
+
+The default title policy uses conventional commits and a 72-character limit.
+No commitlint binary or JavaScript config is executed. Required CI names are
+project settings; default policy requires reported checks, rejects unsuccessful
+checks, and allows intentionally skipped optional jobs. A named required check
+must succeed. Configure explicit required names for shipping.
+
+The OpenCode model default preserves the source projects' fallback provider; set
+it to a model your account supports. `opencodeVariants` overrides mappings for
+the supplied levels, with unspecified entries passed through unchanged. Claude
+and Codex use their CLI defaults unless a model is configured.
+
+Version helpers discover committed `package.json` workspaces when
+`versions.packages` is null, or use the configured relative package directories;
+`.` names the repository's root package, which then changes with any file,
+including files in other configured packages.
+They preserve deliberate major/minor releases and bump changed packages one
+patch past the base. `plan`, `bump`, and `check` do not regenerate lockfiles or
+commit changes.
+
+`versions prepare` owns the whole sequence before a review snapshot. It needs a
+clean worktree on an attached branch with the exact base already merged. 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. Each `versions.validate` command runs
+without a shell against the staged result; commands resolve on PATH outside
+the repository. The commit uses `versions.commitMessage` and runs the project's
+commit hooks, and must reproduce the prepared tree. Set `versions.lockfile` to
+null for projects without a Bun lockfile. 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; otherwise it preserves
+that state for inspection. Repeating against the same base creates no commit.
+
+## Portable skills
+
+Canonical instructions live once in `skills/`. The build embeds them, and the
+installer places 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 official [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 see identical names through both
+compatibility paths; the installed instructions are identical.
+
+The bundle provides `cross-agent-review`, `open-pr`, `squash-merge`, `ship-pr`, and
+`reset`. The installer tracks ownership with `.agent-tool-skills.json`, previews
+changes without writing, and rejects unmanaged or locally edited files and
+symlink destinations. Preserve existing project-specific skills before
+migration rather than overwriting them. Project validation and setup commands
+stay in repository guidance; the shared skills make no package-manager or
+application-layout assumptions. The installer is project-scoped; it does not
+modify global harness settings, MCP configuration, or authentication.
+
+To normalize consumers, install the bundled skills and keep project validation,
+review-bot rules, and deployment checks in `AGENTS.md`. Put title and required CI
+settings in `agent-tool.json` instead of copying the shipping workflow. After a
+dependency update, run `agent-tool skills install --apply` and commit the updated
+skills with `.agent-tool-skills.json`. Run `agent-tool skills check` in hooks and
+CI: it fails for missing, outdated, unmanaged, or locally edited skills without
+writing anything. Use the same `--harness` when installing and checking a single
+harness. Existing unmanaged skills must be preserved or deliberately migrated
+before installation; there is no force-overwrite mode.
+
+## Review guarantees and limits
+
+The extraction retains exact base/head snapshots, base-commit review policy,
+raw Git blob materialization, collision/path validation, text diffs without
+external drivers, snapshot cleanup, verdict gating, and one retry for incomplete
+successful output. Git hooks and replace objects are disabled for helper Git
+operations. Reviewer executables must resolve outside the project, and reviews
+have configurable timeouts. Modern review rejects HEAD drift before returning.
+
+Claude uses safe mode and read-only tools. Codex uses an ephemeral session,
+snapshot-scoped filesystem permissions, no model-command environment
+inheritance, disabled hosted web search, and final-message capture. OpenCode uses
+a neutral directory, pure mode, inline permissions denying every tool by default,
+and specific read-only allowances. Unknown/unsupported CLI flags fail the run;
+there is no fallback that silently removes those protections.
+
+These are different harness protections, not a uniform OS isolation guarantee.
+Claude and OpenCode rely on their tool permission implementations. The launcher
+still uses local authentication and a host environment; the stronger
+credential-stripped macOS preflight from `stealth` has not been ported. A verdict
+is a completion marker, not proof that a model's findings are correct.
+
+GitHub atomically enforces expected HEAD during merging, but this mutation has
+no atomic expected-base precondition. Skills recheck base freshness; repository
+protection must enforce stricter concurrent-update requirements. With
+`merge.requireStrictBaseFreshness`, `pr merge` refuses unless the base's
+effective rules include an active repository ruleset requiring strict status
+checks that the authenticated actor can never bypass. GitHub then rejects a
+head that no longer contains the latest base. Classic branch protection is not
+inspected. Fork reviews
+can resolve upstream PR bases; the PR-opening helper initially supports
+same-repository branches.
+
+## Packages and verification
+
+```sh
+bun run typecheck
+bun test
+bun scripts/smoke-package.ts
+bun run build
+bun scripts/smoke.ts dist/agent-tool
+
+# Build macOS/Linux ARM64/x64 archives and a formula with real SHA-256 values:
+bun scripts/release.ts a2f0/agent-tool
+
+# On Linux with dpkg-deb; substitute your release version:
+scripts/package-deb.sh dist/agent-tool-0.1.0-linux-x64/bin/agent-tool amd64
+# Install a produced Debian package:
+sudo apt install ./dist/agent-tool_0.1.0_amd64.deb
+```
+
+Release scripts create local artifacts; they do not publish anything. Put the
+archives at the generated release URLs and the generated `agent-tool.rb` in a
+Homebrew tap to support `brew install <owner>/<tap>/agent-tool`. A downloadable
+`.deb` supports `apt install ./file.deb`; `apt install agent-tool` by name also
+requires hosting a signed APT repository and configuring that source. Neither a
+tap nor an APT repository is live yet. The GitHub release workflow builds and
+uploads CI artifacts only.
+
+### npm releases
+
+ship-pr bumps the root `package.json` patch version on every merge, and the
+[publish workflow](.github/workflows/npm-publish.yml) publishes each version
+newer than npm's `latest` with
+[trusted publishing](https://docs.npmjs.com/trusted-publishers) and provenance.
+No npm token is stored. The job runs in the `npm` environment, which only
+`main` can deploy to, and npm's trusted publisher names that environment and
+`npm-publish.yml`. A deliberate major or minor bump in a PR is kept. Runs never
+overlap, and when merges land together only the newest pending run starts, so
+intermediate versions can be skipped on npm.
+
+npm adds a trusted publisher only to a package that already exists, so the
+first version was published by hand with `npm publish --ignore-scripts`. Until
+a package exists, the workflow fails with that instruction rather than
+attempting a publish npm would reject.
+
+Standalone builds use [Bun's executable support](https://bun.sh/docs/bundler/executables).
+The compiled smoke test invokes all three adapters through local stubs with Bun
+and Node absent from PATH; it makes no paid model calls. CI checks source tests,
+type checking, compiled smoke tests, and Debian packaging on Linux, plus source
+and compiled checks on macOS.
+
+See [the validation record](docs/validation.md) for observed results and the
+limits of the local tests.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@a2f0/agent-tool",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Portable cross-agent review, PR workflows, and shared skills",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/a2f0/agent-tool.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "agent-tool": "src/index.ts"
+  },
+  "files": [
+    "src",
+    "skills",
+    "!src/**/*.test.ts",
+    "!src/**/*.testUtils.ts"
+  ],
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "scripts": {
+    "start": "bun src/index.ts",
+    "test": "bun test src scripts",
+    "typecheck": "tsc --noEmit",
+    "generate": "bun scripts/bundle-skills.ts",
+    "build": "bun run generate && bun build --compile --minify src/index.ts --outfile dist/agent-tool"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.11",
+    "typescript": "5.9.3"
+  }
+}

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

@@ -0,0 +1,46 @@
+---
+name: cross-agent-review
+description: Review committed branch changes with an independent Claude Code, Codex, or OpenCode reviewer, and repair actionable findings when requested.
+---
+
+# Cross-Agent Review
+
+Use the installed `agent-tool` executable. Read the repository's development and
+review policy and `agent-tool.json` when present. Keep project validation commands
+and release rules in the repository; do not assume Bun, a workspace layout, or
+particular CI job names.
+
+Select a reviewer different from the coordinating agent when possible. Honor a
+requested reviewer or effort; otherwise use an available independent reviewer.
+Run `agent-tool doctor` if CLI compatibility is uncertain.
+
+Review committed changes with `agent-tool review claude`, `agent-tool review codex`,
+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.
+
+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
+that labels findings `[P0]` through `[P3]` uses the same scale: `[P0]` and
+`[P1]` are BLOCKER and MAJOR, `[P2]` and `[P3]` are MINOR and SUGGESTION.
+
+If a CLI is unavailable, out of credits, or returns an unusable review, try another
+available reviewer and disclose the fallback. Do not silently convert a failed
+review into CLEAN or call an in-session review independent.
+
+For report-only requests, report findings without changing files or history.
+When repairs are authorized, address actionable BLOCKER and MAJOR findings,
+validate with the repository's relevant checks, commit the repairs, and review
+the new HEAD. Continue while meaningful progress is possible; report an impasse
+when progress requires a material user decision. A repaired commit is unreviewed
+until the next review completes. Preserve unrelated work.
+
+Before reporting success, confirm HEAD still matches the reviewed commit and
+that an existing PR points to that same commit. If the base moved, refresh it and
+review again before shipping. Report reviewer, exact base and head IDs, verdict,
+remaining findings, validation, and any repairs performed. This skill does not
+authorize pushing, opening a PR, or merging unless the user requested that work.

package/skills/open-pr/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: open-pr
+description: Open a GitHub pull request for the current feature branch with a validated title and a reviewable description.
+---
+
+# 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`;
+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.
+
+Write a title that satisfies the data-only `agent-tool.json` subject policy.
+Describe the concrete resulting behavior and relevant validation. Put multiline
+body text in a temporary file, then run:
+
+```sh
+agent-tool pr open 'feat: describe the change' < /path/to/pr-body.txt
+```
+
+Omitting the title uses the latest commit subject. The tool refuses duplicate
+open PRs and requires the branch to be pushed at its local HEAD. It does not
+push for you. Resolve a fork's head/base identities explicitly if the repository
+uses fork PRs; the initial open helper supports same-repository branches.
+
+Report the created PR link and any remaining validation or review work.

package/skills/reset/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: reset
+description: Return a clean checkout to its updated default branch after confirmed shipping or an explicit checkout cleanup request.
+---
+
+# Reset
+
+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.
+
+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.
+
+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.

package/skills/ship-pr/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ship-pr
+description: Complete an authorized commit, independent review, repair, PR, CI, and squash-merge workflow for a GitHub repository.
+---
+
+# Ship PR
+
+Use the installed `agent-tool`. Read repository guidance and policy first;
+validation, versioning, package management, and hook installation remain project
+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.
+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
+   user work. If project policy versions packages, prepare versions against the
+   pinned base after every integration or repair and before each review, using
+   the project's commands or `agent-tool versions prepare <base-oid>`, which
+   commits bumped manifests and the refreshed lockfile.
+   `agent-tool versions resolve-conflicts` resolves conflicts confined to
+   version fields. Review the resulting committed HEAD with an independent
+   reviewer using the bundled cross-agent-review skill. Repair blocking findings
+   and review every changed HEAD again. Review failure blocks shipping.
+3. Push the reviewed HEAD through normal hooks, then verify the pushed SHA still
+   equals the reviewed SHA. If a hook changed content or HEAD, review that result.
+   Open the PR using the open-pr skill, or update the existing PR as needed.
+4. Allow any configured review bots time to respond, then fetch unresolved PR
+   review threads. Follow repository policy for feedback: fix valid findings,
+   reply in the original threads, and resolve only fully addressed comments.
+   Validate, commit, push, and independently review every feedback or CI repair.
+   Wait for CI, recheck the live base, PR base branch, and local and remote heads.
+   A changed base requires integration, validation, and another review. When
+   versions are managed, `agent-tool versions check <base-oid>` must pass for the
+   live base. Use the squash-merge skill to merge the exact reviewed HEAD.
+5. After confirmed MERGED, honor keep-branch; otherwise use the reset skill to
+   return to the updated default branch and apply any documented project setup.
+6. When the project deploys the merged branch, verify the deployment for the
+   merge commit and run its documented live checks. Report deployment failures
+   separately from a successful merge; follow project policy for repairs.
+
+Never infer a clean review from process success alone or carry a review across
+content changes. Do not weaken configured CI policy to get a merge through.
+If a step fails, preserve useful intermediate work and report the concrete
+remaining issue. Report PR link, merged commit, review verdict, validation, and
+final checkout state.

package/skills/squash-merge/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: squash-merge
+description: Squash-merge a reviewed GitHub pull request while binding the mutation to the reviewed commit and checking CI.
+---
+
+# Squash Merge
+
+Use the installed `agent-tool` and repository merge policy. Merge only within
+the user's authorized scope. Have the exact reviewed HEAD, base commit, and base
+branch available, and read the verdict and unresolved findings. BLOCKER or MAJOR
+findings require repair and a new review before merging.
+Follow the repository's review-bot policy and require all actionable blocking
+review feedback to be addressed before merging.
+
+Wait for required checks using `gh pr checks --watch --fail-fast`. Refresh the
+PR and live base from the repository that owns the PR. Confirm local HEAD and PR
+HEAD both equal the reviewed commit, the base branch is unchanged, the live base
+still equals the reviewed base, and that base is an ancestor of reviewed HEAD.
+If any identity changed, refresh, validate, and review again.
+
+Use a title that satisfies `agent-tool.json` and pass both reviewed HEAD and
+base branch:
+
+```sh
+agent-tool pr merge 'feat: describe the change' <reviewed-head-oid> <base-branch>
+```
+
+The helper enforces HEAD atomically through GitHub's `expectedHeadOid`, checks
+CI, rejects queued or automatic merges, and creates a subject-only squash with
+the PR reference. GitHub has no atomic expected-base argument in this mutation;
+repository branch protection must enforce any required base freshness. With
+`merge.requireStrictBaseFreshness`, the helper refuses to merge unless an
+active strict status ruleset that the actor cannot bypass protects the base. Do
+not retarget the PR concurrently with merging.
+
+Confirm GitHub reports MERGED before any cleanup. A failed or uncertain mutation
+is not evidence of a merge. Preserve the branch on failure. After a confirmed
+merge, perform checkout cleanup only when requested or as part of an authorized
+shipping workflow. Report the PR and merge result.

package/src/cli.ts

@@ -0,0 +1,121 @@
+import { execFileSync } from "node:child_process";
+import { writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_CONFIG, loadConfig } from "./config";
+import { doctor } from "./doctor";
+import { review } from "./harnesses";
+import { runAgentToolAction } from "./runAgentToolAction";
+import { BUNDLED_SKILLS } from "./skills/bundled";
+import { checkSkills, installSkills } from "./skills/install";
+import { bumpVersions, checkVersions, planVersions } from "./version/bumpVersions";
+import { prepareVersions } from "./version/prepareVersions";
+import { resolveVersionConflicts } from "./version/resolveVersionConflicts";
+import { openPr } from "./pr/openPr";
+import { squashMerge } from "./pr/squashMerge";
+import metadata from "../package.json";
+
+export const HELP = `agent-tool ${metadata.version}
+
+Usage: agent-tool [--repo <directory>] [--config <file>] <command>
+
+  review <claude|codex|opencode> [effort] [--base <local-ref>]
+  pr open [title]                       Body from stdin; branch already pushed
+  pr merge <subject-or-empty> <head-oid> <base-branch>
+  versions <plan|bump|check|prepare> <base-oid>
+  versions resolve-conflicts
+  skills list
+  skills install [--harness <all|claude|codex|opencode>] [--apply]
+  skills check [--harness <all|claude|codex|opencode>]
+  init                                  Create agent-tool.json without overwriting
+  config show
+  doctor                                JSON versions and supported review flags
+  --help | --version
+
+Legacy actions remain available: solicitClaudeCodeReview, solicitCodexReview,
+solicitOpencodeReview, openPr, squashMerge, bumpVersions, checkVersions,
+resolveVersionConflicts. A successful review exit means a usable review was
+returned; inspect VERDICT before shipping. Skill install previews unless --apply.
+`;
+
+function output(value: unknown): void { writeSync(1, `${JSON.stringify(value, null, 2)}\n`); }
+function usage(condition: boolean, message: string): void { if (!condition) throw new Error(message); }
+function gitRoot(): string {
+  return execFileSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const args = [...argv];
+  while (args[0] === "--repo" || args[0] === "--config") {
+    const flag = args.shift()!;
+    const value = args.shift();
+    usage(!!value && !value.startsWith("--"), `${flag} requires a path.`);
+    if (flag === "--repo") process.chdir(value!);
+    else process.env.AGENT_TOOL_CONFIG = path.resolve(value!);
+  }
+  const command = args.shift();
+  if (!command || command === "--help" || command === "-h") {
+    usage(args.length === 0, "Unexpected arguments after --help.");
+    writeSync(1, HELP); return 0;
+  }
+  if (command === "--version") { usage(args.length === 0, "Unexpected version arguments."); writeSync(1, `${metadata.version}\n`); return 0; }
+  if (command === "init") {
+    usage(args.length === 0, "Usage: agent-tool init");
+    writeFileSync(path.join(process.cwd(), "agent-tool.json"), `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, { flag: "wx" });
+    writeSync(1, "Created agent-tool.json. Set project policy before shipping.\n"); return 0;
+  }
+  if (command === "config") { usage(args.length === 1 && args[0] === "show", "Usage: agent-tool config show"); output(loadConfig()); return 0; }
+  if (command === "doctor") {
+    usage(args.length === 0, "Usage: agent-tool doctor");
+    const result = doctor(process.cwd()); output(result);
+    return result.tools.find(item => item.name === "git")?.compatible && result.tools.some(item => ["claude", "codex", "opencode"].includes(item.name) && item.compatible) ? 0 : 1;
+  }
+  if (command === "skills") {
+    const action = args.shift();
+    if (action === "list") { usage(args.length === 0, "Usage: agent-tool skills list"); output(Object.keys(BUNDLED_SKILLS)); return 0; }
+    usage(action === "install" || action === "check", "Usage: agent-tool skills <list|install|check>");
+    let target = "all", apply = false;
+    while (args.length) {
+      const flag = args.shift();
+      if (flag === "--apply") { usage(action === "install", "skills check is read-only; --apply is not allowed."); usage(!apply, "Duplicate --apply."); apply = true; }
+      else if (flag === "--harness") { const value = args.shift(); usage(!!value, "--harness requires a name."); target = value!; }
+      else throw new Error(`Unknown skills ${action} argument '${flag}'.`);
+    }
+    if (action === "check") {
+      const changes = checkSkills(process.cwd(), target);
+      const ok = changes.every(change => change.status === "unchanged");
+      output({ ok, changes }); return ok ? 0 : 1;
+    }
+    output({ applied: apply, changes: installSkills(process.cwd(), target, apply) }); return 0;
+  }
+  const root = gitRoot();
+  process.chdir(root);
+  loadConfig(root); // Validate policy before running a reviewer or mutating GitHub.
+  if (command === "review") {
+    const name = args.shift(); usage(!!name, "Usage: agent-tool review <claude|codex|opencode> [effort] [--base ref]");
+    let effort: string | undefined, base: string | undefined;
+    while (args.length) {
+      const value = args.shift()!;
+      if (value === "--base") { usage(base === undefined && !!args[0] && !args[0].startsWith("--"), "--base requires one local ref."); base = args.shift(); }
+      else { usage(effort === undefined && !value.startsWith("-"), `Unexpected review argument '${value}'.`); effort = value; }
+    }
+    return review(root, name!, effort, base);
+  }
+  if (command === "pr") {
+    const action = args.shift();
+    if (action === "open") { usage(args.length <= 1, "Usage: agent-tool pr open [title]"); return openPr(root, args[0]); }
+    usage(action === "merge" && args.length === 3, "Usage: agent-tool pr merge <subject-or-empty> <reviewed-head-oid> <base-branch>");
+    usage(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(args[1]!), "Merge requires a full reviewed HEAD OID.");
+    return squashMerge(root, args[0], args[1], args[2]);
+  }
+  if (command === "versions") {
+    const action = args.shift();
+    if (action === "resolve-conflicts") { usage(args.length === 0, "resolve-conflicts takes no arguments."); return resolveVersionConflicts(root); }
+    usage(args.length === 1, "Usage: agent-tool versions <plan|bump|check|prepare> <base-oid>");
+    if (action === "plan") { output(planVersions(root, args[0])); return 0; }
+    if (action === "bump") return bumpVersions(root, args[0]);
+    if (action === "check") return checkVersions(root, args[0]);
+    if (action === "prepare") return prepareVersions(root, args[0]);
+    throw new Error(`Unknown version action '${action}'.`);
+  }
+  return runAgentToolAction(root, [command, ...args]);
+}