takopi-review 0.1.7

Review orchestration plugin for Takopi.

takopi-review

multi-review orchestration plugin for takopi.

takopi-review runs multiple review agents over the same diff bundle, normalizes their findings into one schema, deduplicates overlap, and produces a single report you can act on. It keeps raw reviewer output for audit, but everything downstream uses the same provider-agnostic finding shape.

shipped now

phase 1 of the review pipeline is implemented here:

• natural-language /review <request> runs, including reply-to-snippet reviews
• repo-aware PR review requests such as /review this pr 123 in this repo owner/repo
• working-tree diff requests such as /review the working tree diff
• commit review requests such as /review commit abc1234
• normalized provider-agnostic findings
• consolidated markdown reports with audit artifacts
• lead reviewer validation, dedupe, and prioritization
• final review message inherits the lead reviewer session metadata when available

how it works

the plugin runs in four stages:

1. collect the review target, diff or source content, changed files when available, inferred language/test surface, and workspace instructions
2. run the repo-owned specialist reviewer roles in parallel against the same bundle
3. run a final lead reviewer that validates the specialist findings, merges overlap, ranks the final list, and emits the grounded output
4. persist the consolidated report and raw reviewer artifacts for audit

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

reviewer roles are now fixed in the repo/plugin and are no longer user-settable from the command line. the shipped pipeline runs these specialist lanes by default, on codex only:

• security-best-practices
• typechecker
• correctness-simplicity
• tests
• boundary-regressions

the typechecker lane stays enabled for every review because the intended repo set is typed by default.

when the changed files include a committed spec document such as a PRD, spec, requirements doc, design doc, or RFC in a text format, the pipeline also adds:

• spec-reviewer

when the bundle looks like React or Next.js code, the pipeline also adds:

• react-vercel

before the lead pass, the pipeline also runs one broad code-review-excellence-codex sweep lane.

after those pre-lead passes finish, a single final code-review-excellence lead reviewer runs on codex, validates whether the reviewer findings are actually grounded, merges duplicates, and ranks the final report. the lead lane is explicitly single-engine so the final emitted message has one canonical session to inherit.

the security-best-practices lane is backed by the repo-local skill corpus in src/takopi_review/review_skills.py and uses the bundled language- and framework-specific references when the bundle matches supported stacks.

the final lead lane is backed by the same repo-local skill corpus, so the adjudication stage uses explicit code-review principles rather than a bespoke repo-local reviewer persona.

the repo vendors one shared skill corpus for the shipped review lanes. the reviewer prompt loader does not depend on external skill installs for review prompt enrichment.

all /review commands go through the same parser. the plugin uses an LLM pre-pass to infer the review target, repo hint, and primary language signal from the text after /review and any replied content, then injects that signal into the reviewer prompts.

outputs

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

.takopi/review/
  latest.json
  <run-id>/
    bundle.json
    report.json
    report.md
    raw/
      security-best-practices-codex.txt
      typechecker-codex.txt
      correctness-simplicity-codex.txt
      tests-codex.txt
      boundary-regressions-codex.txt
      spec-reviewer-codex.txt
      react-vercel-codex.txt
      code-review-excellence-codex.txt
      code-review-excellence-lead-codex.txt

the markdown review report includes:

• a consolidated findings table
• a terse final summary from the lead reviewer
• an agreement matrix by specialist reviewer
• missing reviewers that were skipped for the bundle
• recommended fix order
• per-finding reviewed code, suggested fix, and agent prompt
• testing gaps
• reviewer execution errors, if any

finding schema

all reviewer output is normalized into this shape before consolidation:

{
  "reviewer": "security-best-practices-codex",
  "title": "Missing authorization check",
  "priority": 1,
  "confidence": 0.84,
  "file": "src/example.py",
  "start_line": 42,
  "end_line": 45,
  "summary": "Route allows any Slack user 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."
}

config

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

reports and raw reviewer outputs are stored under report_dir inside the repo. set require_repo = false to allow natural-language snippet reviews outside a git repo; repo-targeted PR reviews can already run without a local checkout when the command names the repo explicitly. when post_github_comments = true, PR reviews post the consolidated findings directly to the GitHub PR thread. the comment body is compacted and split across multiple PR comments when needed to stay under GitHub size limits, and the Slack reply is reduced to job done.

plugins.review.reviewers, plugins.review.default_fixer, plugins.review.auto_fix, and /review fix were removed in the hard cutover. reviewer selection now belongs to the repo-owned orchestration pipeline, not the caller.

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

release

ci runs on pushes to main and pull requests. publishing is wired through github actions on tags matching v*.

once PyPI trusted publishing is configured, a release is:

git tag v0.1.0
git push origin main --tags