feat: add pre-commit review hook

.pre-commit-hooks.yaml

@@ -0,0 +1,9 @@
+- id: agentskit-review
+  name: AgentsKit Code Review
+  description: Run provider-neutral, adversarial code review over the repository diff.
+  entry: agentskit-review
+  language: node
+  pass_filenames: false
+  always_run: true
+  require_serial: true
+  stages: [manual]

README.md

@@ -66,6 +66,29 @@ The current command runs directly from GitHub. After the first npm release, the
 npx @agentskit/code-review --provider codex-cli
 ```
 
+## Run through pre-commit
+
+The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter.
+
+Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AgentsKit-io/code-review-cli
+    rev: main # pre-release; pin a release tag when one contains the hook
+    hooks:
+      - id: agentskit-review
+        args: [--provider, codex-cli, --no-fail, --max-files, "20"]
+```
+
+Then run it when a change is ready for review:
+
+```sh
+pre-commit run --hook-stage manual agentskit-review
+```
+
+The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository.
+
 ## Use the GitHub Action
 
 Add `.github/workflows/code-review.yml` to any repository:

docs/OPERATIONS.md

@@ -15,6 +15,14 @@ Credential precedence is `--api-key`, `LLM_API_KEY`, then `<PROVIDER>_API_KEY`.
 
 Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF.
 
+## pre-commit integration
+
+The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit.
+
+Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor.
+
+The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch.
+
 ## GitHub Action permissions
 
 The copy-ready workflow in [`examples/pull-request.yml`](../examples/pull-request.yml) requires:

llms-full.txt

@@ -84,6 +84,29 @@ The current command runs directly from GitHub. After the first npm release, the
 npx @agentskit/code-review --provider codex-cli
 ```
 
+## Run through pre-commit
+
+The repository publishes a [`pre-commit`](https://pre-commit.com/) hook for teams that already use that framework. It is manual by default because a full adversarial review is slower and more expensive than a formatter or linter.
+
+Add this to `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://github.com/AgentsKit-io/code-review-cli
+    rev: main # pre-release; pin a release tag when one contains the hook
+    hooks:
+      - id: agentskit-review
+        args: [--provider, codex-cli, --no-fail, --max-files, "20"]
+```
+
+Then run it when a change is ready for review:
+
+```sh
+pre-commit run --hook-stage manual agentskit-review
+```
+
+The hook reviews the repository diff against `origin/main`; it does not claim to review only staged files. Override `--base` when your integration branch differs. To run on every push, override the hook with `stages: [pre-push]` and install that hook type explicitly, but first choose cost, latency, provider, and blocking policies appropriate for the repository.
+
 ## Use the GitHub Action
 
 Add `.github/workflows/code-review.yml` to any repository:
@@ -301,6 +324,14 @@ Credential precedence is `--api-key`, `LLM_API_KEY`, then `<PROVIDER>_API_KEY`.
 
 Do not run hosted review on code whose policy forbids external processing. A local model reduces external disclosure but does not remove the need to secure the runner, logs, cache, and generated SARIF.
 
+## pre-commit integration
+
+The root `.pre-commit-hooks.yaml` exposes `agentskit-review` as a Node hook. It uses `pass_filenames: false` because the CLI reviews a Git diff, explicit paths, a pull request, or stdin rather than interpreting positional filenames. It is confined to the `manual` stage by default so cloning the hook does not silently add model calls to every commit.
+
+Consumer configuration must select a provider through `args`. Keep credentials in the provider login or environment; never place API keys in `.pre-commit-config.yaml`. Before overriding the hook to `stages: [pre-push]`, decide whether findings are advisory, set a file budget, and confirm that provider latency and data handling are appropriate for every contributor.
+
+The default diff base remains `origin/main`. A pre-commit invocation does not mean the input is limited to the Git staging area. Set `--base` explicitly when the repository uses another integration branch.
+
 ## GitHub Action permissions
 
 The copy-ready workflow in [`examples/pull-request.yml`](https://github.com/AgentsKit-io/code-review-cli/blob/main/examples/pull-request.yml) requires:

package.json

@@ -12,6 +12,7 @@
     "README.md",
     "LICENSE",
     "AGENTS.md",
+    ".pre-commit-hooks.yaml",
     "action.yml",
     "examples/pull-request.yml",
     "SECURITY.md",

readme-standard-v1.json

@@ -215,7 +215,7 @@
           "docs/OPERATIONS.md",
           "test/cli-smoke.test.mjs"
         ],
-        "sourceHash": "sha256:df64583bb8d08a538138986bfe3604ee9fb821c7271a08527fe758229f6116d8"
+        "sourceHash": "sha256:9b6b6c25a9ccdde85eb1f5eb39b484a8b4ca726a783584d4c8606a3342baaa5c"
       },
       "exceptions": []
     }

test/documentation.test.mjs

@@ -20,11 +20,31 @@ test('README communicates pipeline, maturity, contribution, and ecosystem role',
 
 test('operations guide covers every required security and release topic', () => {
   const operations = read('docs/OPERATIONS.md')
-  for (const marker of ['## Provider and credential choices', '## GitHub Action permissions', '## Advisory and blocking behavior', '## Cost and latency controls', '## SARIF', '## Failure scenarios', '## Releases and maturity', '## Contribution and security', 'pull_request_target', 'security-events: write']) {
+  for (const marker of ['## Provider and credential choices', '## pre-commit integration', '## GitHub Action permissions', '## Advisory and blocking behavior', '## Cost and latency controls', '## SARIF', '## Failure scenarios', '## Releases and maturity', '## Contribution and security', 'pull_request_target', 'security-events: write']) {
     assert.ok(operations.includes(marker), `operations guide missing ${marker}`)
   }
 })
 
+test('pre-commit hook is manual, provider-neutral, and reviews the repository diff', () => {
+  const hook = read('.pre-commit-hooks.yaml')
+  const readme = read('README.md')
+  for (const marker of [
+    'id: agentskit-review',
+    'entry: agentskit-review',
+    'language: node',
+    'pass_filenames: false',
+    'always_run: true',
+    'require_serial: true',
+    'stages: [manual]',
+  ]) {
+    assert.ok(hook.includes(marker), `pre-commit hook missing ${marker}`)
+  }
+  assert.match(readme, /pre-commit run --hook-stage manual agentskit-review/)
+  assert.match(readme, /does not claim to review only staged files/)
+  assert.match(readme, /args: \[--provider, codex-cli, --no-fail/)
+  assert.doesNotMatch(hook, /api[_-]?key/i)
+})
+
 test('the Action stays least-privilege, secret-safe, and advisory by default', () => {
   const action = read('action.yml')
   const workflow = read('examples/pull-request.yml')
@@ -100,6 +120,7 @@ test('published package keeps documentation generators and freshness enforcement
     '.doc-bridge/index.json',
     '.doc-bridge/capabilities.json',
     'action.yml',
+    '.pre-commit-hooks.yaml',
     'examples/pull-request.yml',
   ]) {
     assert.ok(manifest.files.includes(input), `published documentation input missing: ${input}`)