diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index fc1624d9a..e9327c2d7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1355,6 +1355,20 @@ "server" ] }, + { + "name": "session-code-review", + "description": "Backpressure code review that validates changes against REVIEW.md before commits and session completion.", + "source": "./plugins/validation/session-code-review", + "category": "Validation", + "keywords": [ + "code-review", + "review", + "backpressure", + "quality", + "validation", + "review.md" + ] + }, { "name": "shellcheck", "description": "Validation and quality enforcement for Bash and shell scripts using ShellCheck with portability and error handling skills.", diff --git a/plugins/validation/session-code-review/.claude-plugin/plugin.json b/plugins/validation/session-code-review/.claude-plugin/plugin.json new file mode 100644 index 000000000..bd3cb7bb3 --- /dev/null +++ b/plugins/validation/session-code-review/.claude-plugin/plugin.json @@ -0,0 +1,19 @@ +{ + "name": "session-code-review", + "version": "1.0.0", + "description": "Backpressure code review that validates changes against REVIEW.md before commits and session completion.", + "author": { + "name": "The Bushido Collective", + "url": "https://thebushido.co" + }, + "homepage": "https://github.com/thebushidocollective/han", + "repository": "https://github.com/thebushidocollective/han", + "license": "Apache-2.0", + "keywords": [ + "code-review", + "review", + "backpressure", + "quality", + "validation" + ] +} diff --git a/plugins/validation/session-code-review/README.md b/plugins/validation/session-code-review/README.md new file mode 100644 index 000000000..742afb0db --- /dev/null +++ b/plugins/validation/session-code-review/README.md @@ -0,0 +1,68 @@ +# Session Code Review + +Backpressure code review plugin that validates changes against `REVIEW.md` before commits and session completion. + +## How It Works + +This plugin uses Claude Code's [agent-based hooks](https://code.claude.com/docs/en/hooks#agent-based-hooks) to provide automatic code review at two critical points: + +### Stop Hook — Session Review + +When Claude finishes responding, an agent reviewer examines all uncommitted and staged changes against your `REVIEW.md` and `CLAUDE.md` guidelines. If issues are found, Claude continues working to fix them instead of stopping. + +### PreToolUse Hook — Commit/Push Gate + +Before any `git commit` or `git push` command executes, an agent reviewer checks the staged or branch changes. If issues are found, the commit/push is blocked and Claude is told what to fix. + +## REVIEW.md + +Create a `REVIEW.md` file at your repository root to define review rules. The plugin auto-discovers this file — no configuration needed. + +Example `REVIEW.md`: + +```markdown +# Review Guidelines + +## Required + +- All API routes must validate authentication tokens +- Database queries must use parameterized statements +- Error responses must not leak internal implementation details +- All new public functions must have JSDoc comments + +## Do Not Flag + +- Formatting issues (handled by Biome) +- Test file naming conventions +- Import ordering +``` + +The plugin also respects `CLAUDE.md` files for project-specific conventions. + +## Installation + +```bash +claude plugin install session-code-review@han +``` + +Recommended scope: **project** (since review rules are project-specific): + +```bash +han plugin install session-code-review --scope project +``` + +## On-Demand Review + +Use the `/code-review` skill to manually trigger a review of your current branch: + +``` +/code-review +/code-review --branch develop +``` + +## Design Philosophy + +- **High signal only** — Only flags issues with high confidence. False positives erode trust. +- **REVIEW.md driven** — Your team's rules, not generic suggestions. +- **Backpressure, not gatekeeping** — Issues are fixed in-session, not posted as comments to review later. +- **Complements Anthropic's Code Review** — Anthropic's review runs on PRs in CI. This plugin catches issues earlier, before code is even committed. diff --git a/plugins/validation/session-code-review/han-plugin.yml b/plugins/validation/session-code-review/han-plugin.yml new file mode 100644 index 000000000..2f6850f2c --- /dev/null +++ b/plugins/validation/session-code-review/han-plugin.yml @@ -0,0 +1,2 @@ +dependencies: + - bushido diff --git a/plugins/validation/session-code-review/hooks/hooks.json b/plugins/validation/session-code-review/hooks/hooks.json new file mode 100644 index 000000000..71f323340 --- /dev/null +++ b/plugins/validation/session-code-review/hooks/hooks.json @@ -0,0 +1,30 @@ +{ + "description": "Backpressure code review — reviews session changes against REVIEW.md before allowing completion or commits", + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "agent", + "prompt": "Run /code-review to review all uncommitted and staged changes against the project's REVIEW.md and CLAUDE.md guidelines.\n\nIf there are no changes (empty diff), return {\"ok\": true}.\n\nAfter the review completes:\n- If no issues found: return {\"ok\": true}\n- If issues found: return {\"ok\": false, \"reason\": \"\"}\n\nOnly flag issues you are CERTAIN about. False positives waste time. When in doubt, allow.\n\nHook context: $ARGUMENTS", + "timeout": 300, + "statusMessage": "Reviewing session changes..." + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "agent", + "prompt": "Check the bash command in the hook context below. If it is NOT a `git commit` or `git push` command, immediately return {\"ok\": true}.\n\nIf it IS a git commit or git push, run /code-review to review the changes being committed or pushed.\n\nAfter the review completes:\n- If no issues found: return {\"ok\": true}\n- If issues found: return {\"ok\": false, \"reason\": \"\"}\n\nOnly flag issues you are CERTAIN about. When in doubt, allow the commit.\n\nHook context: $ARGUMENTS", + "timeout": 300, + "statusMessage": "Reviewing changes before commit..." + } + ] + } + ] + } +} diff --git a/plugins/validation/session-code-review/skills/code-review/SKILL.md b/plugins/validation/session-code-review/skills/code-review/SKILL.md new file mode 100644 index 000000000..1141a585d --- /dev/null +++ b/plugins/validation/session-code-review/skills/code-review/SKILL.md @@ -0,0 +1,116 @@ +--- +description: Review current branch changes against REVIEW.md guidelines +--- + +# Code Review + +## Name + +session-code-review:code-review - Review session changes against REVIEW.md and CLAUDE.md guidelines + +## Synopsis + +``` +/code-review [--branch ] +``` + +## Description + +Performs a thorough code review of all changes on the current branch compared to the base branch (defaults to `main` or `master`). Reviews against `REVIEW.md` and `CLAUDE.md` guidelines in the repository. + +This is a local-only review — no PR or GitHub integration required. It examines your uncommitted changes, staged changes, and all commits on the current branch. + +## Implementation + +Follow these steps exactly: + +### 1. Determine the base branch + +If `--branch` was provided, use that. Otherwise, detect the default branch: + +```bash +git remote show origin | grep 'HEAD branch' | sed 's/.*: //' +``` + +### 2. Gather review guidelines + +Read the following files if they exist: +- `REVIEW.md` at the repo root +- `CLAUDE.md` at the repo root +- Any `CLAUDE.md` files in directories containing changed files + +These define the review criteria. If no `REVIEW.md` or `CLAUDE.md` exists, use general best practices (security, correctness, logic errors). + +### 3. Get the full diff + +```bash +# Uncommitted changes +git diff + +# Staged changes +git diff --cached + +# All commits on this branch vs base +git diff ...HEAD +``` + +### 4. Review the changes + +For each changed file, check against the guidelines from step 2. Focus on: + +- **REVIEW.md violations**: Explicit rules the team has defined +- **CLAUDE.md violations**: Project conventions and requirements +- **Bugs**: Logic errors, off-by-one errors, null pointer issues +- **Security**: Injection, auth bypass, exposed secrets, OWASP top 10 +- **Correctness**: Code that will produce wrong results + +Do NOT flag: +- Style preferences (unless in REVIEW.md) +- Issues a linter catches +- Subjective improvements +- Pre-existing issues not in the diff + +### 5. Report findings + +For each issue found, report: +- **File and line number** (link format: `file_path:line_number`) +- **Severity**: critical / warning +- **Description**: What's wrong and why +- **Suggestion**: How to fix it + +If no issues are found, report: "No issues found. Changes comply with REVIEW.md and CLAUDE.md guidelines." + +### 6. Offer to fix + +If issues were found, ask the user if they'd like you to fix them. + +## Example Interaction + +``` +User: /code-review + +Claude: Reviewing changes on branch `feature/auth-flow` against `main`... + +Found REVIEW.md with 3 rules: +1. All API routes must validate auth tokens +2. Database queries must use parameterized statements +3. Error responses must not leak internal details + +Reviewing 4 changed files... + +## Code Review Results + +### 1. Missing auth validation (critical) +`src/routes/users.ts:45` — New GET `/users/:id` endpoint does not validate the auth token. REVIEW.md rule: "All API routes must validate auth tokens." + +**Fix**: Add `validateToken(req)` middleware before the handler. + +### 2. SQL injection risk (critical) +`src/db/queries.ts:23` — String interpolation in SQL query: `` `SELECT * FROM users WHERE id = ${id}` ``. REVIEW.md rule: "Database queries must use parameterized statements." + +**Fix**: Use `db.query('SELECT * FROM users WHERE id = ?', [id])`. + +--- + +Found 2 issues (2 critical). Would you like me to fix them? +```