takopi-review

Config-driven multi-review orchestration plugin for Takopi.

takopi-review now has a hard-cutover architecture:

• package-owned request parser
• package-owned reviewer router
• repo-owned specialist reviewers from takopi.toml
• package-owned lead reviewer that dedupes and triages findings

The package no longer ships built-in specialist lanes such as security, React, or spec review. Repos define their own reviewer set, enable or disable reviewers in config, and keep reviewer execution prompts in Markdown files.

how it works

Each /review run goes through four stages:

1. parse the review target from the request text
2. build a deterministic change profile from the diff or snippet
3. route the change to the best enabled reviewers from config
4. run a final lead pass that validates, deduplicates, and ranks the reviewer findings

The router and lead prompts are package-owned and codex-only. Only the middle specialist reviewer prompts are repo-owned.

requirements

• python 3.14+
• takopi installed
• codex available in your Takopi setup
• gh installed if you want /review pr ...

install

uv tool install -U takopi --with takopi-review

or install into the same environment as Takopi:

pip install -U takopi-review

enable it:

[plugins]
enabled = ["takopi-review"]

commands

Review a freeform request, optionally by replying to a pasted snippet or message:

/review python auth middleware in this pasted snippet
/review typescript react component for accessibility --focus ui

Review the current workspace diff:

/review the working tree diff
/review the current diff --focus security --focus tests

Review a pull request, including one from another repo:

/review this pr 123
/review this pr 123 in this repo richardliang/takopi-review --focus performance
/review https://github.com/acme/repo/pull/123

Review a commit:

/review commit abc1234

config

Each target repo owns its own takopi.toml. This package repo no longer ships an active root config.

This repo keeps example review assets under examples/:

• security-best-practices
• typechecker
• correctness-simplicity
• tests
• boundary-regressions
• spec-reviewer
• code-review-excellence
• frontend-browser

For the React lane, point the reviewer directly at your installed Vercel React skill instead of copying a vendored react-vercel.md. In this workspace that skill lives at SKILL.md.

Example config for a repo that vendors the example prompts into .takopi/review/reviewers/:

[plugins.review]
timeout_s = 1200
max_parallel_reviews = 8
require_repo = true
post_github_comments = true
report_dir = ".takopi/review"

[[plugins.review.reviewers]]
id = "security-best-practices"
enabled = true
summary = "Review concrete authorization, trust-boundary, secret handling, signature validation, and data-exposure regressions across services, clients, contracts, and provider integrations."
prompt_file = ".takopi/review/reviewers/security-best-practices.md"

[[plugins.review.reviewers]]
id = "react-vercel"
enabled = true
summary = "Review React, Vite, and Next-style frontend changes for bundle shape, hydration, client-server boundaries, stale data flows, rendering regressions, and performance cliffs."
prompt_file = "/absolute/path/to/vercel-react-best-practices/SKILL.md"

[[plugins.review.reviewers]]
id = "frontend-browser"
enabled = true
summary = "Read README, start the relevant local app, and use Chrome MCP to click through the changed UI flow and catch grounded regressions."
requires_repo = true
prompt_file = ".takopi/review/reviewers/frontend-browser.md"

Rules:

• summary is the router contract
• prompt_file is the execution contract
• editing only a reviewer prompt changes execution behavior, not routing behavior
• editing summary changes how the router may select that reviewer
• requires_repo = true skips that reviewer when no local repo context exists

Prompt files resolve relative to takopi.toml when Takopi provides a config path, otherwise relative to the workspace root.

reviewer prompt files

The example prompt files in examples/review/reviewers/ follow a consistent skill-style structure:

• short frontmatter metadata
• Goal
• Working style
• reviewer-specific Checks
• optional repo-specific emphasis such as ZKP2P emphasis
• Do not report

That structure keeps the router metadata short in takopi.toml while making the execution prompt easy to update without changing the package.

Copy the prompts you want into your own repo and point prompt_file at them, or point prompt_file at any other Markdown file such as an installed skill SKILL.md.

Repos can also commit extra review context under .takopi/review/reference/*.md. Those files are bundled alongside AGENTS.md and README.md, so specialist reviewers can use repo-specific guidance without hardcoding it into the package. This repo's example reference file now lives under examples/review/reference/.

Example browser reviewer prompt:

Read `README.md` first to determine how to run the app locally for this repo.

Start the relevant local dev server for the changed feature.

Use Chrome MCP to open the local app and click through only the UI flows relevant to this review target.

Base your exploration on:
- the changed files
- the diff summary
- the PR or request description

Report only grounded regressions from the changed feature. Ignore generic polish comments.

outputs

Review artifacts are written under .takopi/review/ by default:

.takopi/review/
  latest.json
  <run-id>/
    bundle.json
    report.json
    report.md
    raw/
      <reviewer-id>.txt
      takopi-review-lead.txt

The report includes:

• router review kind and route summary
• selected reviewers
• skipped reviewers with reasons
• consolidated findings
• agreement matrix across selected reviewers
• recommended fix order
• testing gaps
• reviewer errors

finding schema

All reviewer output is normalized into this shape before consolidation:

{
  "reviewer": "security",
  "title": "Missing authorization check",
  "priority": 1,
  "confidence": 0.84,
  "file": "src/example.py",
  "start_line": 42,
  "end_line": 45,
  "summary": "Route allows any caller to trigger destructive actions.",
  "suggested_fix": "Check allowed_user_ids before dispatch.",
  "reviewed_code": "delete route still succeeds for unauthorized users.",
  "agent_prompt": "Update src/example.py so unauthorized users are rejected before dispatch and add regression coverage for the denied path."
}

development

Install the locked dev environment:

uv sync --frozen --group dev

Run the same checks as CI:

uv run --no-sync ruff check
uv run --no-sync pytest -q

Build the package locally:

uv build