I'll flag two ambiguities before proceeding, then state my assumptions: **Ambiguity 1 — Claude Code plugin schema**: As of my knowledge cutoff (August 2025), Claude Code does not have a publicly documented "plugin.json" manifest format with the 10 component types listed. I'm designing this as a *forward-compatible specification* based on Claude Code's documented features (slash commands via CLAUDE.md, hooks via hooks config, MCP servers via mcp config). I'll flag where I'm extrapolating a plausible schema versus what's documented. **Ambiguity 2 — GitHub MCP endpoint**: No official Anthropic-maintained GitHub PR review MCP server URL is publicly documented. I'll use a placeholder URL and flag it. **Assumption**: Per-repo install targets `<project-root>/.claude/` as the primary config location, consistent with Claude Code's documented project-scoped config behavior. --- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DELIVERABLE 1 — PLUGIN MANIFEST (plugin.json) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ { "name": "claude-code-review", "version": "1.0.0", "description": "Automated, opinionated code review baked into Claude Code. Adds /review command, post-edit hooks, diff-style output, and GitHub PR integration.", "license": "MIT", "min_claude_code_version": "1.0.0", "author": "", "repository": "", ── 1. COMMANDS ──────────────────────────────────────── "commands": [ { "name": "review", "description": "Trigger a full code review of staged changes, a specific file, or a PR. Usage: /review [file|--pr <number>|--staged]", "agent": "code-review-agent", "args": [ { "name": "target", "type": "string", "required": false, "description": "File path, --pr <number>, or --staged. Defaults to current file in context." } ], "output_style": "diff-review" }, { "name": "review-config", "description": "Display or update active review preferences for this repo.", "agent": null, "args": [], "output_style": "plain" } ], What it does: Registers /review as an invocable slash command that routes to the code-review-agent, and /review-config for runtime preference inspection. ── 2. AGENTS ────────────────────────────────────────── "agents": [ { "name": "code-review-agent", "role": "Senior code reviewer. Analyze diffs, flag bugs, security issues, style violations, and test gaps. Never suggest changes outside the provided diff scope.", "trigger": "command:review", "model": "claude-sonnet-4-20250514", "skills": ["diff-parser", "severity-classifier", "pr-comment-formatter"], "output_style": "diff-review", "context_window_strategy": "diff-focused", "system_prompt_file": "agents/review_system_prompt.md", "max_turns": 8 } ], What it does: Declares the code-review-agent subagent with its role, skill dependencies, output style binding, and a file-referenced system prompt so the agent's persona is version-controlled. ── 3. SKILLS ────────────────────────────────────────── "skills": [ { "name": "diff-parser", "description": "Parses unified diff output into structured hunk objects the agent can reason over.", "file": "skills/diff_parser.md" }, { "name": "severity-classifier", "description": "Classifies review findings into CRITICAL / WARNING / SUGGESTION / NITS tiers with defined criteria.", "file": "skills/severity_classifier.md" }, { "name": "pr-comment-formatter", "description": "Formats agent findings as GitHub PR inline review comments, including file path, line reference, and severity badge.", "file": "skills/pr_comment_formatter.md" } ], What it does: Declares three composable skill documents the agent loads at runtime — diff parsing, finding classification, and output formatting — each as a versioned markdown file. ── 4. HOOKS ─────────────────────────────────────────── "hooks": [ { "event": "PostToolUse", "tool_name_filter": ["Write", "Edit", "MultiEdit"], "handler": "hooks/post_edit_lint.sh", "run_as": "shell", "blocking": false, "description": "After any file write or edit, run a lightweight static check and surface findings as Claude notifications.", "disclose_network": false }, { "event": "PreToolUse", "tool_name_filter": ["Write", "Edit"], "handler": "hooks/pre_edit_guard.sh", "run_as": "shell", "blocking": true, "description": "Before any file write, check if the target file is in a protected path list defined in user_config.", "disclose_network": false }, { "event": "Stop", "handler": "hooks/session_summary.sh", "run_as": "shell", "blocking": false, "description": "At session end, write a structured review summary to .claude/logs/session_review.json.", "disclose_network": false } ], What it does: Registers three hooks — a non-blocking post-edit linter, a blocking pre-edit guard for protected paths, and a stop hook that persists a session review log; all shell-based with no undisclosed network calls. ── 5. MCP_SERVERS ───────────────────────────────────── "mcp_servers": [ { "name": "github-pr-review", "type": "url", "url": "https://YOUR_MCP_HOST/github-pr-review/sse", "description": "MCP server exposing GitHub PR review tools: list_pr_files, post_review_comment, submit_review.", "auth": { "type": "env", "token_env_var": "GITHUB_TOKEN" }, "required": false, "fallback_behavior": "Skip PR posting; output review to stdout only." } ], ⚠ FLAG: No official Anthropic-maintained GitHub PR MCP server URL exists as of August 2025. Replace the url value with your actual MCP server endpoint. The auth block assumes a GitHub personal access token or fine-grained token stored in the environment — never hardcoded. What it does: Declares the GitHub PR review MCP server connection so the code-review-agent can post inline comments directly to pull requests via MCP tool calls. ── 6. LSP_SERVERS ───────────────────────────────────── NOT INCLUDED — This plugin performs semantic review via LLM agent, not syntax-level language analysis. No LSP integration is warranted. Adding a language-specific LSP would narrow the plugin's language-agnostic scope without adding review value. ── 7. OUTPUT_STYLES ─────────────────────────────────── "output_styles": [ { "name": "diff-review", "description": "Renders review findings as annotated unified diff blocks with severity badges, file anchors, and a summary table.", "format": "markdown", "template_file": "styles/diff_review_template.md", "rules": { "finding_prefix": "[{severity}] {file}:{line}", "severity_badges": { "CRITICAL": "🔴", "WARNING": "🟡", "SUGGESTION": "🔵", "NITS": "⚪" }, "include_summary_table": true, "diff_context_lines": 3, "max_findings_per_file": 20 } }, { "name": "plain", "description": "Unformatted prose output for config commands and informational responses.", "format": "plaintext", "template_file": null, "rules": {} } ], What it does: Defines diff-review as the canonical review output format — annotated diffs with severity-coded badges and a summary table — and plain for utility commands. ── 8. CHANNELS ──────────────────────────────────────── "channels": [ { "name": "review-findings", "description": "Primary output channel for review findings. Routes to terminal UI and optionally to a findings log file.", "destinations": ["terminal", "file:.claude/logs/findings.jsonl"], "format": "diff-review", "enabled_by_default": true }, { "name": "hook-alerts", "description": "Channel for post-edit hook notifications — surfaces as inline Claude warnings during the session.", "destinations": ["terminal"], "format": "plain", "enabled_by_default": true } ], What it does: Routes review agent output to both terminal and a persistent JSONL log, and hook alerts to terminal only, keeping findings queryable after the session ends. ── 9. SETTINGS ──────────────────────────────────────── "settings": { "description": "Project-scoped Claude Code settings applied when this plugin is active.", "values": { "haiku_for_simple_tasks": false, "auto_compact_threshold_tokens": 80000, "verbose_tool_output": false, "max_concurrent_subagents": 1 } }, What it does: Disables Haiku routing for review tasks (review quality degrades on smaller models), caps context before compaction, and limits to one concurrent subagent to prevent interleaved review output. ── 10. USER_CONFIG ──────────────────────────────────── "user_config": { "description": "Per-user overridable preferences. Users set these in .claude/user.json or via /review-config.", "schema": { "protected_paths": { "type": "array", "items": "string", "default": ["migrations/", "db/schema", ".env*"], "description": "Glob patterns for files the pre-edit guard hook will block edits to without explicit confirmation." }, "auto_review_on_edit": { "type": "boolean", "default": false, "description": "If true, the post-edit hook triggers a mini-review automatically on every file save, not just on /review invocation." }, "review_verbosity": { "type": "string", "enum": ["concise", "standard", "verbose"], "default": "standard", "description": "Controls depth of finding explanations. concise = one-liners only; verbose = includes remediation code snippets." }, "github_pr_auto_post": { "type": "boolean", "default": false, "description": "If true and inside a PR context, automatically post findings to GitHub via the MCP server after /review completes." }, "nits_threshold": { "type": "integer", "minimum": 0, "maximum": 50, "default": 10, "description": "Maximum number of NITS-level findings to surface. Excess nits are suppressed to reduce noise." } } } } What it does: Exposes five user-tunable preferences — protected path guards, auto-review toggle, output verbosity, GitHub auto-post, and nits suppression ceiling — each with a safe default. --- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DELIVERABLE 2 — INSTALL SCRIPT (install.sh) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ #!/bin/sh # install.sh — claude-code-review plugin installer # POSIX-compatible. Tested: bash 3.2+, dash, zsh in sh mode. # Usage: sh install.sh [--symlink] [--dry-run] set -e PLUGIN_NAME="claude-code-review" SYMLINK=0 DRY_RUN=0 for arg in "$@"; do case "$arg" in --symlink) SYMLINK=1 ;; --dry-run) DRY_RUN=1 ;; --help) echo "Usage: sh install.sh [--symlink] [--dry-run]" echo " --symlink Symlink files instead of copying (useful for plugin development)" echo " --dry-run Print actions without executing them" exit 0 ;; *) echo "Unknown option: $arg" >&2 exit 1 ;; esac done # ── Locate source directory ────────────────────────────── SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" # ── Resolve .claude/ target directory (priority order) ─── if [ -n "$CLAUDE_CONFIG_DIR" ]; then CLAUDE_DIR="$CLAUDE_CONFIG_DIR" echo "[info] Using CLAUDE_CONFIG_DIR: $CLAUDE_DIR" elif [ -d "$HOME/.claude" ]; then CLAUDE_DIR="$HOME/.claude" echo "[info] Using HOME/.claude: $CLAUDE_DIR" elif git rev-parse --show-toplevel > /dev/null 2>&1; then GIT_ROOT="$(git rev-parse --show-toplevel)" CLAUDE_DIR="$GIT_ROOT/.claude" echo "[info] Using git repo root: $CLAUDE_DIR" else echo "[error] Cannot locate a .claude/ directory." >&2 echo "[error] Set CLAUDE_CONFIG_DIR, ensure $HOME/.claude exists," >&2 echo "[error] or run this script from inside a git repository." >&2 exit 1 fi # ── Create .claude/ and subdirectories ─────────────────── for dir in \ "$CLAUDE_DIR" \ "$CLAUDE_DIR/agents" \ "$CLAUDE_DIR/skills" \ "$CLAUDE_DIR/hooks" \ "$CLAUDE_DIR/styles" \ "$CLAUDE_DIR/logs" \ "$CLAUDE_DIR/plugins/$PLUGIN_NAME" do if [ ! -d "$dir" ]; then if [ "$DRY_RUN" -eq 1 ]; then echo "[dry-run] mkdir -p $dir" else mkdir -p "$dir" echo "[created] directory: $dir" fi fi done # ── Helper: install one file ────────────────────────────── install_file() { src="$1" dest="$2" label="$3" if [ ! -f "$src" ]; then echo "[warn] Source not found, skipping: $src" return 0 fi if [ "$DRY_RUN" -eq 1 ]; then if [ "$SYMLINK" -eq 1 ]; then echo "[dry-run] ln -sf $src -> $dest" else echo "[dry-run] cp $src -> $dest" fi return 0 fi if [ "$SYMLINK" -eq 1 ]; then ln -sf "$src" "$dest" echo "[symlinked] $label: $dest" else cp "$src" "$dest" echo "[installed] $label: $dest" fi } # ── Install manifest ────────────────────────────────────── install_file \ "$SCRIPT_DIR/plugin.json" \ "$CLAUDE_DIR/plugins/$PLUGIN_NAME/plugin.json" \ "manifest (plugin.json)" # ── Install agent system prompt ─────────────────────────── install_file \ "$SCRIPT_DIR/agents/review_system_prompt.md" \ "$CLAUDE_DIR/agents/review_system_prompt.md" \ "agent prompt (review_system_prompt.md)" # ── Install skills ──────────────────────────────────────── for skill in diff_parser.md severity_classifier.md pr_comment_formatter.md; do install_file \ "$SCRIPT_DIR/skills/$skill" \ "$CLAUDE_DIR/skills/$skill" \ "skill ($skill)" done # ── Install hooks ───────────────────────────────────────── for hook in post_edit_lint.sh pre_edit_guard.sh session_summary.sh; do src="$SCRIPT_DIR/hooks/$hook" dest="$CLAUDE_DIR/hooks/$hook" install_file "$src" "$dest" "hook ($hook)" if [ "$DRY_RUN" -eq 0 ] && [ -f "$dest" ]; then chmod +x "$dest" echo "[chmod+x] $dest" fi done # ── Install output style template ───────────────────────── install_file \ "$SCRIPT_DIR/styles/diff_review_template.md" \ "$CLAUDE_DIR/styles/diff_review_template.md" \ "output style template (diff_review_template.md)" # ── Install default user config (do not overwrite existing) ── USER_CONFIG_DEST="$CLAUDE_DIR/user.json" if [ -f "$USER_CONFIG_DEST" ]; then echo "[skipped] user.json already exists — not overwriting user preferences." else install_file \ "$SCRIPT_DIR/user.json.default" \ "$USER_CONFIG_DEST" \ "user config (user.json)" fi # ── Append CLAUDE.md slash command registration ─────────── CLAUDE_MD="$CLAUDE_DIR/CLAUDE.md" REVIEW_MARKER="<!-- claude-code-review:commands -->" if [ -f "$CLAUDE_MD" ] && grep -q "$REVIEW_MARKER" "$CLAUDE_MD" 2>/dev/null; then echo "[skipped] CLAUDE.md already contains /review registration." else if [ "$DRY_RUN" -eq 1 ]; then echo "[dry-run] Append /review registration block to $CLAUDE_MD" else cat >> "$CLAUDE_MD" << 'CLAUDEMD_BLOCK' <!-- claude-code-review:commands --> ## Slash Commands (claude-code-review plugin) - /review [file|--pr <number>|--staged] Trigger the code-review-agent on the specified target. Outputs diff-formatted findings with severity badges. - /review-config Display or update active review preferences for this session. CLAUDEMD_BLOCK echo "[updated] CLAUDE.md: appended /review command registration." fi fi # ── Remind about required environment variable ──────────── echo "" echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo " $PLUGIN_NAME install complete." echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━" echo "" echo " Next steps:" echo " 1. Set GITHUB_TOKEN in your environment if you want" echo " GitHub PR posting via the MCP server." echo " 2. Update the mcp_servers[0].url in plugin.json" echo " with your actual GitHub MCP server endpoint." echo " 3. Run /review-config inside Claude Code to verify" echo " your preferences." echo "" --- ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ DELIVERABLE 3 — MARKETPLACE SUBMISSION CHECKLIST ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1. Manifest completeness All 10 component type fields are present or explicitly declared absent with a reason. Validate against the plugin schema using the marketplace validator before submission. 2. Schema validity plugin.json passes JSON schema linting (e.g. ajv-cli) against the published Claude Code plugin schema. No additional or misspelled top-level keys. 3. Version field and changelog "version" follows semver (MAJOR.MINOR.PATCH). A CHANGELOG.md exists at the repo root with an entry for every published version. 4. License field "license" is present in plugin.json and a LICENSE file exists at the repo root with the full license text. 5. Install script portability install.sh runs without errors on macOS (bash + zsh), Ubuntu (dash + bash), and WSL2 (bash). No bashisms in POSIX sh sections; test with shellcheck --shell=sh. 6. No hardcoded secrets A grep scan of the entire repo for tokens, passwords, and API keys finds nothing. Secrets are referenced only via environment variable names documented in README. 7. Network call disclosure Every hook or script that makes a network call explicitly declares disclose_network: true in the manifest and documents the destination and purpose in README. 8. Component naming conventions All command names are lowercase kebab-case, agent names are lowercase hyphenated, skill filenames are snake_case .md files, and hook filenames are snake_case .sh files. 9. Dependency declarations Any external binaries required by hooks (e.g. jq, git, gh) are listed under a "dependencies" key in plugin.json and verified for existence by install.sh with a clear error if missing. 10. README requirements README.md covers: what the plugin does, prerequisites, install steps, all slash commands with arguments, all user_config fields with defaults, and how to set GITHUB_TOKEN. 11. Test coverage — commands An automated test or recorded session exists for /review --staged, /review <file>, /review --pr <number>, and /review-config, each asserting the expected output_style and agent invocation. 12. Test coverage — agents and hooks The code-review-agent is tested against at minimum one CRITICAL, one WARNING, and one NITS finding fixture. Each hook is tested with a mock tool invocation that exercises its guard or logging logic. 13. Compatibility declaration "min_claude_code_version" is set to the lowest version on which all hooks, commands, and MCP server config syntax used in this plugin are supported. Verified against release notes. 14. MCP server endpoint documentation The mcp_servers[0].url placeholder is clearly marked in both plugin.json and README as a value the installer must replace. The marketplace listing does not publish a live credential endpoint. 15. Protected-path defaults are safe The default protected_paths list does not include paths that would silently block normal development workflows. Defaults are reviewed by a second engineer and documented with rationale in README.