@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