Metadata-Version: 2.3
Name: takopi-review
Version: 0.1.9
Summary: Review orchestration plugin for Takopi.
Keywords: takopi,review,plugin,code-review
Author: takopi contributors
License: MIT License
         
         Copyright (c) takopi contributors
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Dist: takopi>=0.22,<0.23
Requires-Python: >=3.14
Project-URL: Homepage, https://takopi.dev
Description-Content-Type: text/markdown

# 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

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

or install into the same environment as Takopi:

```sh
pip install -U takopi-review
```

enable it:

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

## commands

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

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

Review the current workspace diff:

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

Review a pull request, including one from another repo:

```text
/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:

```text
/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](/Users/richardliang/.codex/skills/vercel-react-best-practices/SKILL.md).

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

```toml
[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:

```md
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:

```text
.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:

```json
{
  "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:

```sh
uv sync --frozen --group dev
```

Run the same checks as CI:

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

Build the package locally:

```sh
uv build
```
