ai-code-review

@tabilo/ai-code-review

Reusable, multi-language AI code-review workflow for VS Code Copilot, powered by Agent Skills. Run /ai-review in Copilot Chat to get a structured, evidence-based review of your branch/PR — with zero configuration beyond a one-time setup:

git diff context → pack routing → pack skills → impact analysis → tests → coverage gate → report

The whole workflow (rules, language packs, config, report template) is copied into your repo as .ai-code-review/, so you can tune it per project without touching the package.

---

✨ Features

• 6 Agent Skills installed to ~/.copilot/skills/: /ai-review, /ai-review-java, /ai-review-react, /ai-review-vue, /ai-review-angular, /ai-review-help
• 4 language packs: java (JaCoCo coverage gate) and react / vue / angular (Istanbul coverage gate)
• Per-repo payload .ai-code-review/ — the workflow, packs, config and report template live in the repo and can be customized freely
• Cross-platform git context — collects diffs with plain Node.js (no PowerShell dependency), works on Windows, macOS and Linux
• Mandatory impact analysis — uses GitNexus MCP, CodeGraph, or falls back to manual grep to answer "what breaks if this merges?"
• Test + coverage gate — runs your unit tests and enforces C0/C1 ≥ 80% on changed code (JaCoCo / Istanbul)
• Structured report — severity-classified findings, verdict by exit gate, Vietnamese or English output (en default, vi supported)
• Context integrity — a single out/context.md is the only diff source the agent reviews; every finding must quote a real file:line from it

---

📋 Table of Contents

• Requirements
• How it works
• Installation & Setup
• Usage
• CLI Reference
• Configuration
• The Review Workflow
• Report & Verdict
• Extending
• Troubleshooting
• Docs
• License

---

Requirements

Dependency	Version / Notes
Node.js	≥ 18 (≥ 16 for the package itself, 18+ recommended)
VS Code	latest, with the GitHub Copilot Chat extension (Agent Skills support)
git	on PATH (used for diff collection)
Language toolchain	mvn for Java, npm/node for frontend packs (needed for tests & coverage)

---

How it works

┌─ Agent Skills (installed once per machine) ────────────────┐
│  ~/.copilot/skills/ai-review/SKILL.md                     │  ← /ai-review slash command
│  ~/.copilot/skills/ai-review-java/SKILL.md                │  ← force java pack
│  ~/.copilot/skills/ai-review-react|vue|angular/SKILL.md   │  ← force frontend pack
│  ~/.copilot/skills/ai-review-help/SKILL.md                │  ← cheat sheet
└───────────────────────────────────────────────────────────┘
            │ reads / orchestrates
┌─ Repo payload (copied per repo by `setup`) ────────────────┐
│  .ai-code-review/                                           │
│    config/ai-review.yaml    reportLanguage, defaultTarget, activePacks
│    core/workflow.md         the mandatory 6-step workflow
│    core/synthesizer.md      merging findings + exit gate
│    core/impact-analysis.md  GitNexus / CodeGraph / grep strategy
│    core/report-template.md  report structure
│    core/pr-comment.md       PR comment structure
│    packs/<lang>/            pack.yaml + review skills
│    out/                     generated context.md + review-report.md
└───────────────────────────────────────────────────────────┘

The skills are installed once per machine and describe how to review. The payload is copied into every repo and describes what to review — routing rules, priorities, test/coverage commands, thresholds and the report template. This split lets you customize the review per repository while the package stays up-to-date centrally.

---

Installation & Setup

Run once per repository (a few seconds, no interactive prompts):

# at the repo root you want to review
npx @tabilo/ai-code-review setup

setup does the following:

1. Copies the payload → <repo>/.ai-code-review/ (core/, packs/, config/, out/.gitkeep). Skipped if it already exists (use --force to restore template files — your out/ reports are never deleted).
2. Creates .ai-code-review/out/ — generated reports live here.
3. Scans the repo and auto-activates the matching packs (java, react, vue, angular).
4. Writes .ai-code-review/config/ai-review.yaml if missing.
5. Adds .ai-code-review/ to the repo's .gitignore (idempotent — never duplicates the entry).
6. Installs the 6 skills into ~/.copilot/skills/ (idempotent: identical files are skipped, changed files are updated).

Then:

1. Reload the VS Code window (so Copilot picks up the new skills).
2. Open Copilot Chat and type:

/ai-review

💡 .ai-code-review/ is often gitignored (added automatically by setup). The agent always reads it with includeIgnoredFiles: true, so this is fine — but don't be surprised if the folder doesn't show in your source control view.

Verify the installation

npx @tabilo/ai-code-review doctor

doctor checks the payload, config/ai-review.yaml, out/, the 6 installed skills and the activated packs, then prints a summary line telling you exactly what to run if anything is missing. Exit code is 0 even when things are missing — read the output.

npx @tabilo/ai-code-review list

list shows the shipped packs, packs present in the payload, active packs, and the install state of every skill.

---

Usage

Quick start

/ai-review                              # auto-detect pack, diff vs develop

That's it — the agent collects the diff, routes files to the right review area, runs impact analysis + tests + coverage, and writes .ai-code-review/out/review-report.md.

Slash commands

Command	Effect
/ai-review	Auto-detect the pack from changed files
/ai-review-java	Force the java pack
/ai-review-react	Force the react pack
/ai-review-vue	Force the vue pack
/ai-review-angular	Force the angular pack
/ai-review-help	Show the cheat sheet in chat

Options (tokens)

Append space-separated key:value tokens after the command (each token is split on the first :):

Token	Values	Default	Meaning
target:<branch>	any branch	config defaultTarget → develop	base branch to diff against (resolves origin/<b> first, then local <b>)
source:<branch>	any branch	current branch / HEAD	branch (or revision) to review
scope:<mode>	branch | staged | working | commit:<a>..<b>	branch	what to review
report-lang:<code>	en | vi	config reportLanguage → en	report language
severity:<level>	critical | high | medium	built-in gate	override the exit-gate severity levels
pack:<name>	java | react | vue | angular	auto-detect	force a specific pack

Precedence: slash token > .ai-code-review/config/ai-review.yaml > built-in default.

Examples

# Basic — review current branch vs develop
/ai-review

# Review current branch vs main
/ai-review target:main

# Review only the staged changes
/ai-review scope:staged

# Review uncommitted working-tree changes
/ai-review scope:working

# Review a commit range
/ai-review scope:commit:abc123..def456

# Vietnamese report
/ai-review report-lang:vi

# Combine options
/ai-review target:main report-lang:vi

# Force the Java pack regardless of detected files
/ai-review-java target:develop

# Force a pack with a token (works from any skill)
/ai-review pack:react scope:staged

Review scopes

Scope	Reviews
branch	everything on the current branch since the merge-base with the target branch — the default for PR-style reviews
staged	only what is git add-ed in the index
working	only the uncommitted working-tree changes
commit:<a>..<b>	a specific commit range (both ends can be SHAs or branch names)

---

CLI Reference

All commands run through npx: npx @tabilo/ai-code-review <command> [options].

Command	Description	Options
setup	Copy the .ai-code-review/ payload into the repo, gitignore it, and install the Agent Skills	--dir <repo>, --force / -f
doctor	Verify payload, config, packs and skills are in place	--dir <repo>
list	Show shipped/installed/active packs and skill install state	--dir <repo>
add <pack>	Activate a pack (java | react | vue | angular)	--dir <repo>, --force / -f
context	Regenerate .ai-code-review/out/context.md (the diff source)	--dir <repo>, --target <b>, --source <b>, --scope <m>
open-report	Open the latest report in the default browser	--dir <repo>, --file <path>
help	Print the command summary + slash-command tokens	—

Command details

context — the cross-platform diff collector (pure Node.js, no PowerShell).

npx @tabilo/ai-code-review context
npx @tabilo/ai-code-review context --target main --source my-feature
npx @tabilo/ai-code-review context --scope staged

Output sections written to .ai-code-review/out/context.md:

• Git Information — branch, base, merge-base, changed files, added/removed lines, CodeGraph/GitNexus index presence
• Changed Files — list with per-file stats
• Diff Stat — numeric summary
• Full Diff — truncated at 4000 lines with a clear marker

You normally don't need to run this yourself — the agent regenerates it automatically at review time when missing or stale.

open-report — opens .ai-code-review/out/review-report.md (or --file) in the browser, using start (Windows), open (macOS) or xdg-open (Linux).

add — activate another pack later without re-running full setup:

npx @tabilo/ai-code-review add react

Copies the pack template if not already present, then appends it to activePacks in .ai-code-review/config/ai-review.yaml.

---

Configuration

There are three configuration layers, applied in this order:

slash-command tokens  >  .ai-code-review/config/ai-review.yaml  >  built-in defaults

1. Repo config — .ai-code-review/config/ai-review.yaml

reportLanguage: en        # en | vi — report output language
defaultTarget: develop    # base branch used when no target: token is given
activePacks:              # packs enabled for this repo (auto-detected at setup)
  - java

The file also embeds (read by the agent, not the CLI) the severity definitions (critical/high/medium/low), the exit gate and the large-diff threshold — all editable.

2. Pack config — .ai-code-review/packs/<pack>/pack.yaml

name: java              # pack id
language: java          # primary language
routing:                # glob → review area
  java: ["**/*.java", "**/src/main/java/**"]
  logic: ["**/*Service*.java", "**/service/**"]
  business: ["**/domain/**", "**/policy/**"]
  config: ["**/application*.yml", "**/pom.xml"]
  security: ["**/*Security*.java", "**/filter/**"]
priority: [business, security, logic, java, config]   # review order
test:
  command: "mvn -q test"     # run to verify tests
  framework: junit5
coverage:
  tool: jacoco               # jacoco (java) | istanbul (frontend)
  command: "mvn test jacoco:report"
  reportPath: target/site/jacoco/index.html
  c0: 80                     # line/statement threshold %
  c1: 80                     # branch threshold %
  scope: changedClasses      # what the gate applies to
skills:                      # skill files under packs/<pack>/skills/
  - java-review
  - logic-review
  - business-review
  - config-review
  - security-review
  - unit-test-generation

Globs are matched against the repo-relative path with forward slashes.

3. Built-in defaults

Setting	Default
Base branch	develop
Report language	en
Exit gate	>=1 critical OR >=2 high → Request changes
Coverage thresholds	C0/C1 ≥ 80% on changed code
Large-diff threshold	30 files / 1500 LOC

---

The Review Workflow

When you run /ai-review, the agent follows this exact 6-step workflow (defined in .ai-code-review/core/workflow.md, which you can edit):

1. Collect context — regenerates out/context.md (the single diff source) and cross-checks it against the GitKraken MCP diff when available.
2. Route changed files — each changed file is matched against the active pack's routing globs; a file matching several areas (e.g. a payment service) is reviewed for all of them, in the pack's declared priority order.
3. Review with pack skills — applies the pack's area skills (correctness, logic, business, config, security). Every finding carries a severity, an exact file:line, a suggestion, a solution and required tests.
4. Impact analysis (mandatory) — checks what else breaks: GitNexus MCP (mcp_gitnexus_impact, depth 1→3 on hot paths), CodeGraph (codegraph explore "<symbol>"), or manual grep as fallback.
5. Tests & coverage gate — generates missing unit tests per the pack's skill (JUnit 5 + Mockito / Vitest / Jest), runs the pack's test.command, then runs the coverage command and checks the changed classes against c0/c1.
6. Synthesize — merges findings (same root cause = one finding), applies the exit gate, and writes .ai-code-review/out/review-report.md (plus fills the PR-comment template).

Guardrails (always enforced)

• No hallucination — every finding must be traceable to a concrete line in context.md; the agent must say "not sure" instead of inventing.
• Report honestly — broken builds, missing dependencies and skipped coverage are reported in Limitations with real command output.
• .ai-code-review/ is read-only for the agent — reports go only in .ai-code-review/out/.

---

Report & Verdict

The report (.ai-code-review/out/review-report.md) follows the template in .ai-code-review/core/report-template.md and ends with a verdict computed by the exit gate:

Findings	Verdict
≥ 1 critical OR ≥ 2 high	🔴 Request changes
Only medium / low	🟡 Approve with comments
None	🟢 Approve

Severity definitions (editable in ai-review.yaml):

• critical — data loss, wrong money, security breach (SQLi, auth bypass, secret leak), or a bug that breaks the main feature. Must be fixed before merge.
• high — bug affecting the main flow or many users, clear regression, or an exploitable security risk.
• medium — edge-case bug, missing validation, code smell, or an interaction issue between two modules.
• low — style, naming, docs, missing tests, best practice not applied.

Report language

Set reportLanguage: vi in ai-review.yaml, or pass report-lang:vi per review, to get the report (and PR comment) in Vietnamese. Technical terms stay in English: file/class/method names, paths, CLI commands, severity labels, C0/C1, JaCoCo, GitNexus, CodeGraph.

---

Extending

The whole workflow lives in the repo payload, so it's customizable per repo:

• Add a new language pack — create .ai-code-review/packs/<name>/pack.yaml plus skills under packs/<name>/skills/*.md; optionally add a forcing slash command. See Extending.
• Tune the workflow — edit .ai-code-review/core/workflow.md, synthesizer.md, impact-analysis.md, report-template.md or config/ai-review.yaml. setup --force restores template files (never your out/ reports), so keep customizations in the payload after setup.
• Customize the skills — the installed ~/.copilot/skills/*/SKILL.md files are updated by setup only when the content differs from the package template; edit them directly for manual control.

---

Troubleshooting

Symptom	Fix
/ai-review says the payload is missing	Run npx @tabilo/ai-code-review setup at the repo root, reload VS Code, try again
Slash command not recognized	Confirm the skills exist: npx @tabilo/ai-code-review doctor, then reload VS Code
Wrong base branch used	Pass target:<branch> or change defaultTarget in .ai-code-review/config/ai-review.yaml
Report in the wrong language	Pass report-lang:vi (or en) or set reportLanguage in the config
Pack not reviewing my files	Run npx @tabilo/ai-code-review list to see active packs; add the missing one
.ai-code-review/ not visible in the editor	It's gitignored (added by setup) — that's expected; the agent reads it with includeIgnoredFiles: true
Coverage not running	Check pack.yaml → coverage.command matches your toolchain (mvn/npm on PATH)
Agent reports "file not found" inside .ai-code-review/	Ask it to re-read with includeIgnoredFiles: true (or report the issue)

---

Docs

• Package docs
• Commands
• Configuration
• Extending

License

MIT