{"id":50489448,"url":"https://github.com/junit/pre-commit-review","last_synced_at":"2026-06-02T01:30:30.282Z","repository":{"id":358018093,"uuid":"1238522672","full_name":"junit/pre-commit-review","owner":"junit","description":"Reusable skill package for structured pre-commit Git diff review in Codex- and Claude-style agent workflows.","archived":false,"fork":false,"pushed_at":"2026-05-15T09:08:25.000Z","size":74,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T10:12:41.955Z","etag":null,"topics":["ai-agents","automation","claude","code-review","codex","developer-tools","git-diff","github-workflow","pre-commit","prompt-engineering","skill-package","uality-gate"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/junit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T07:38:53.000Z","updated_at":"2026-05-15T09:08:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/junit/pre-commit-review","commit_stats":null,"previous_names":["junit/pre-commit-review"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/junit/pre-commit-review","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junit%2Fpre-commit-review","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junit%2Fpre-commit-review/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junit%2Fpre-commit-review/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junit%2Fpre-commit-review/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/junit","download_url":"https://codeload.github.com/junit/pre-commit-review/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/junit%2Fpre-commit-review/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33802170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude","code-review","codex","developer-tools","git-diff","github-workflow","pre-commit","prompt-engineering","skill-package","uality-gate"],"created_at":"2026-06-02T01:30:27.854Z","updated_at":"2026-06-02T01:30:30.272Z","avatar_url":"https://github.com/junit.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pre-commit-review\n\n[English](./README.md) | [简体中文](./README.zh-CN.md)\n\n`pre-commit-review` is a reusable skill package for reviewing Git diffs before committing, pushing, or opening a pull request.\n\nIt is designed for agent workflows such as Codex- or Claude-style skill systems, where you want a structured, repeatable pre-commit quality gate instead of an ad hoc diff summary.\n\n## Available Languages\n\n- English: `README.md`\n- Simplified Chinese: `README.zh-CN.md`\n\nTranslations should stay functionally aligned. If you update one version, update the others in the same change when possible.\n\n## What It Does\n\n- Reviews the most relevant diff source in priority order:\n  - user-provided diff\n  - staged changes\n  - unstaged changes\n  - branch vs. base branch\n- Produces a consistent review format focused on:\n  - what changed\n  - code quality issues\n  - intent\n  - logic shifts\n  - blast radius\n  - regression risk\n- Returns a clear verdict:\n  - `SAFE_TO_COMMIT`\n  - `SAFE_TO_COMMIT_WITH_NOTES`\n  - `DO_NOT_COMMIT`\n- Uses a read-only helper script to collect local Git context without mutating the repository\n\n## Why This Repository Exists\n\nThis repository is not an application or framework. It is a small, portable skill package that can be:\n\n- published as a standalone open source repository\n- copied into an existing skills collection\n- adapted for local agent tooling that needs pre-commit review behavior\n\n## Repository Structure\n\n```text\n.\n├── install.sh\n├── SKILL.md\n├── agents/\n│   └── openai.yaml\n├── references/\n│   ├── coverage-led-review.md\n│   ├── output-examples.md\n│   └── visual-output.md\n├── scripts/\n│   └── collect_diff_context.sh\n└── tests/\n    ├── collect_diff_context_test.sh\n    ├── eval_contract_test.sh\n    ├── full_review_workflow_test.sh\n    ├── install_agent_matrix_test.sh\n    ├── output_eval_claude_case.sh\n    ├── output_eval_claude_runner.sh\n    ├── output_eval_codex_case.sh\n    ├── output_eval_codex_runner.sh\n    ├── output_eval_host_wrappers_test.sh\n    ├── output_eval_runner.sh\n    ├── output_eval_runner_test.sh\n    ├── output-eval.json\n    ├── skill_contract_test.sh\n    ├── trigger-eval.json\n    └── install_smoke_test.sh\n```\n\n### `SKILL.md`\n\nDefines the skill itself:\n\n- when it should be triggered\n- how the diff source is resolved\n- how large diffs are handled\n- what review dimensions must be covered\n- the required output template and verdict rules\n\n### `scripts/collect_diff_context.sh`\n\nA read-only helper script that gathers local repository context for the review workflow. It:\n\n- detects whether the current directory is a Git repository\n- prefers staged changes when present\n- falls back to unstaged changes or branch-vs-base comparison\n- reports diff stats, file lists, and status\n- identifies truncation, path/content high-risk candidates, generated-like files, lock files, and top-churn files\n- emits a Review Manifest and Review Groups for coverage-led commit-readiness workflows\n- records rename, delete, binary, mode-only, and submodule pointer changes as manifest units\n- emits Review Plan JSON for reducer-friendly automation without Markdown table parsing\n- emits Split Suggestions for review groups that exceed the hard budget\n- emits Split Unit Diff Preview blocks for hunk-level review\n- emits a Coverage Ledger Template with pending review units\n- emits Group Review Result templates for reducer-ready group findings\n- emits a Reducer State Snapshot Template for long multi-step reviews\n- emits a Coverage Validation Checklist for reducer preflight\n- emits a Full Review Execution Plan with ordered split/review steps\n- emits Group Review Work Packets for serial or delegated group review\n- emits a Reducer Finalization Template for final synthesis gates\n- emits a best-effort Dependency Summary for cross-file reduction\n- emits bounded Semantic Context Queries from project-provided read-only grep patterns\n- emits a suggested review queue for large or truncated diffs\n- truncates oversized diffs safely when needed\n\nIt does not fetch, stage, reset, install, or modify files.\n\nThe default diff output budget is 200KB. Override it with `PRE_COMMIT_REVIEW_MAX_DIFF_BYTES`; use a lower value when the surrounding conversation is already large, and use `0` only when printing the full diff is safe.\n\nReview group budgets default to 120KB target and 160KB hard limit. Override them with `PRE_COMMIT_REVIEW_GROUP_TARGET_BYTES` and `PRE_COMMIT_REVIEW_GROUP_HARD_BYTES`; groups over the hard limit are marked `split-required`.\n\nUse `scripts/collect_diff_context.sh --source \u003cstaged|unstaged|branch\u003e --group \u003cgroup_id\u003e` to retrieve one in-budget review group's diff after a global diff is truncated. Use `--path \u003cpath\u003e` for file-level follow-up when a group needs narrower context or has been split. Helper-emitted `context_command` values include `--source` so follow-up retrieval stays pinned to the original diff source; `split-required` groups must be reviewed through split suggestions instead of as one group.\n\nProject-specific risk hints can live in `.pre-commit-review/risk-paths` and `.pre-commit-review/risk-content`. Each non-empty, non-comment line is an extended regular expression; matches promote files into high-risk ordering but do not change coverage requirements.\n\nProject-specific semantic context hints can live in `.pre-commit-review/context-queries`. Each non-empty, non-comment line is an extended regular expression executed only through bounded read-only `git grep`; these matches can guide dependency or caller checks but never satisfy review coverage.\n\nReview-planning tables and `Dependency Summary` use TSV because paths, commands, and dependency details may contain commas.\n\nReducer and subagent automation should prefer `Review Plan JSON`, `Reducer State Snapshot Template`, and JSONL sections when present; TSV tables are primarily for human scanning.\n\n### `references/`\n\nContains optional guidance loaded only when needed, including the detailed coverage-led review workflow, localized output examples, and visual report formatting.\n\n### `agents/openai.yaml`\n\nProvides lightweight agent metadata for environments that expose skills through an agent registry.\n\n### `install.sh`\n\nInstalls this skill package into host-specific skills directories for supported AI coding agents.\n\n### Output Benchmark Harness\n\n`tests/output_eval_runner.sh` prepares real local fixtures for every scenario in `tests/output-eval.json`, can optionally invoke an external model runner, and grades saved responses against expected verdicts and required phrases.\n\n`tests/output_eval_runner_test.sh` is the deterministic self-test for that harness. It prepares fixtures, synthesizes mock responses, and verifies the grading logic without calling a real model.\n\n`tests/output_eval_codex_runner.sh` and `tests/output_eval_claude_runner.sh` are host-specific thin wrappers. They link this checkout into the fixture's project-local skill directory (`.agents/skills` for Codex, `.claude/skills` for Claude Code) and then delegate to `tests/output_eval_runner.sh` with host-appropriate non-interactive commands.\n\n`tests/output_eval_host_wrappers_test.sh` verifies those wrappers with mock Codex and Claude binaries so the host command templates can regress safely without spending model calls.\n\n### `tests/install_smoke_test.sh`\n\nRuns a small end-to-end installer smoke test against temporary directories.\n\n## Quick Install\n\nFrom a clone of this repository, install globally for any supported agent:\n\n```bash\n./install.sh --agent codex\n./install.sh --agent claude-code\n./install.sh --agent gemini-cli\n./install.sh --agent kiro-cli\n```\n\nList every supported agent id and its project/global paths:\n\n```bash\n./install.sh --list-agents\n```\n\nDefaults:\n\n- Global installs use the agent-specific global path shown by `--list-agents`\n- Project installs use the agent-specific project path shown by `--list-agents`\n- `--dir PATH` overrides both defaults\n- `AGENT_SKILLS_DIR` overrides the global default for all agents\n- Dedicated overrides are also supported for existing integrations: `CODEX_SKILLS_DIR`, `CLAUDE_SKILLS_DIR`, `GEMINI_SKILLS_DIR`, `KIRO_SKILLS_DIR`, and `CODEX_HOME`\n- Backward-compatible aliases are supported: `claude`, `gemini`, and `kiro`\n\nUseful flags:\n\n- `--copy` copies the skill into the target directory and is the default mode\n- `--link` creates a symlink to this repository, which is useful for local development\n- `--project` installs into the agent's project-local skills directory\n- `--dir PATH` overrides the target skills directory\n- `--force` replaces an existing non-managed target\n- `--dry-run` prints what would happen without changing anything\n\nExamples:\n\n```bash\n./install.sh --agent cursor --project\n./install.sh --agent windsurf --link --project\n./install.sh --agent github-copilot --dry-run\n./install.sh kiro --dir .kiro/skills\n```\n\n## How It Works\n\nThe skill resolves review input in this order:\n\n1. A diff explicitly provided by the user\n2. Staged changes in the current repository\n3. Unstaged changes if nothing is staged\n4. Current branch compared with a detected base branch\n5. If no diff is available, the skill asks for staged changes or a provided diff\n\nWhen local repository access is available, the workflow prefers using `scripts/collect_diff_context.sh` as the source of truth for:\n\n- diff source\n- review boundaries\n- changed file counts\n- staged vs. unstaged notes\n- untracked file warnings\n\n## Other Integration Modes\n\n### Use as a standalone repository\n\nClone or copy this repository into the place where your agent runtime expects custom skills.\n\nExample layout:\n\n```text\nyour-skills/\n└── pre-commit-review/\n    ├── SKILL.md\n    ├── agents/\n    ├── references/\n    └── scripts/\n```\n\nThen register or expose the skill according to your agent platform's skill-loading mechanism.\n\n### Merge into an existing skills collection\n\nIf you already maintain a larger skills repository, copy this directory in as one skill package and preserve the relative paths:\n\n- `SKILL.md`\n- `scripts/collect_diff_context.sh`\n- `references/`\n- `agents/openai.yaml`\n\nThe helper script is referenced by the skill instructions, so the directory structure should remain intact unless you also update those references.\n\n## Review Output\n\nThe expected output is an action-first, fast-scanning pre-commit review with:\n\n- a verdict plus a one-line conclusion\n- diff source\n- review scope\n- change scale\n- priority findings with concrete fixes\n- the minimum risk and test guidance needed to make a commit decision\n\nThe default review should answer three questions first:\n\n- can this be committed now\n- what must be fixed before commit\n- what should be tested next\n\nOnly include deeper intent analysis, before/after logic detail, or extra supporting notes when they materially improve the review.\n\nFinal verdicts mean:\n\n- `SAFE_TO_COMMIT`: reviewed scope looks safe to commit now\n- `SAFE_TO_COMMIT_WITH_NOTES`: safe to commit now, but follow-up notes or review limits exist\n- `DO_NOT_COMMIT`: blocking issue found; do not commit as-is\n\n## Safety Characteristics\n\nThis package is intentionally conservative:\n\n- it avoids pretending to see local changes when no repository is available\n- it distinguishes staged and unstaged review scope\n- it warns about untracked files not present in `git diff`\n- it treats large or truncated diffs as a reason to split work and retrieve smaller context, not as permission to skip material units\n- it reserves partial triage for advisory fallback and blocks commit-readiness when high-risk units are unreviewed\n- it supports coverage-led commit-readiness by requiring every manifest unit to be accounted for before claiming full scope\n- it keeps long-review reducer state compact and explicit instead of relying on implicit conversation memory\n- it treats semantic context queries as bounded read-only hints, not arbitrary shell commands or coverage substitutes\n\n## Limitations\n\n- This repository does not include the runtime that loads or executes the skill.\n- The included installer covers common Codex, Claude Code, and Gemini CLI locations, but some local setups may still require `--dir` overrides.\n- The helper script expects a working `git` executable in the environment.\n- The current repository itself may be used outside Git, but local diff collection only works inside a Git repository.\n\n## Contributing\n\nContributions are best focused on:\n\n- improving review heuristics\n- tightening safety boundaries\n- refining the output template\n- making diff collection more robust across repository states\n\nIf you change script paths or repository layout, update `SKILL.md` accordingly.\nIf you update user-facing documentation, keep localized README files synchronized.\n\n## License\n\nThis project is licensed under the Apache License 2.0. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunit%2Fpre-commit-review","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjunit%2Fpre-commit-review","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjunit%2Fpre-commit-review/lists"}