Files

adlee-was-taken 03925e3e11 docs(plan): correct code-review-tea plan with verified tea facts

Incorporate findings from Task 2 verification:
- -F (typed field) reads @-/@file; -f posts literal '@-'. Use -F.
- Endpoint requires /repos/ prefix: /repos/{owner}/{repo}/...
- tea pulls --fields diff returns empty in tea 0.14.1 -> use git diff
- SHA must be remote-present (PR headSha); local-only SHA 404s
- tea api prints JSON to stdout; -o is file-output not format

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-27 13:27:00 -04:00

36 KiB

Raw Blame History

code-review-tea Plugin Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Port Anthropic's code-review plugin from the GitHub CLI (gh) to the Gitea CLI (tea) as a project-local plugin named code-review-tea, so it works against this Gitea-hosted repository, and smoke-test it end-to-end against a real Gitea pull request.

Architecture: The upstream plugin is a single command file (commands/code-review.md) written entirely around gh: its allowed-tools list, PR-eligibility checks, diff source, and comment-posting step all call gh. We fork that command file into a project-local plugin (.claude/plugins/code-review-tea/), rewrite the five gh→tea contact points, and change code-link URLs from GitHub's blob/SHA/path#L format to Gitea's src/commit/SHA/path#L format. The review pattern itself (parallel agents → confidence scoring → 80 threshold filter) is unchanged. Credit to the original Anthropic plugin (by Boris Cherny) is preserved in plugin.json, the README, and the command file header.

Tech Stack: Gitea (git.adlee.work, SSH :2222), tea CLI v0.14.1 (already installed + logged in as alee), the Anthropic code-review plugin command spec, Markdown command files.

Credit: This plugin is a fork of Anthropic's code-review plugin (author: Boris Cherny, boris@anthropic.com), sourced from the claude-plugins-official marketplace. The upstream is GitHub/gh-only; this fork adapts it to Gitea/tea. All credit for the review design (5 parallel agents, confidence scoring, false-positive filtering) belongs to the original.

Context & Verified Facts

These were confirmed by probing the live tea 0.14.1 binary during planning — the plan depends on them being accurate:

Remote: ssh://git@git.adlee.work:2222/alee/vigilar.git → owner alee, repo vigilar, web host https://git.adlee.work.
Login: tea login list shows one login alee at https://git.adlee.work (NOT marked default). Commands need --remote origin to auto-resolve context (fall back to --login alee).
tea pulls <index> — shows a PR's detail. Use --fields state,draft,head,base,mergeable,title,body,diff -o json for machine-readable metadata.
tea pulls ls --state all — lists PRs. Repo has used indexes 4–7 (all merged, by A.D.Lee, 2026-04-05). Open PRs: currently none.
tea pulls review-comments <index> — lists existing review comments with fields id,body,reviewer,path,line,resolver. Used for the "already reviewed?" eligibility check (scan body for the ### Code review marker line).
tea comment <index> <body> — "Add a comment to an issue / pr", but takes body as a trailing arg (fragile for large multi-line Markdown). The robust post-back path is tea api (below).
tea api <endpoint> — raw authenticated API. Endpoint gets /api/v1/ prefix unless it starts with /api or http(s)://; {owner}/{repo} placeholders are substituted from repo context. -f for string fields, -F for typed; @ reads from file, @- from stdin. Post-back endpoint: {owner}/{repo}/issues/<index>/comments with -f body=@-.
Gitea code link format (replaces GitHub blob/ format): https://git.adlee.work/alee/vigilar/src/commit/<full-sha>/<path>#L<start>-L<end>. Use full SHA, never $(git rev-parse HEAD) substituted into the rendered comment.
Diff source: prefer local git diff origin/<base>...origin/<head> (fast, no API round-trip); needs base/head from tea pulls <index>. Fallback: tea api {owner}/{repo}/pulls/<index> and read .diff, or tea api .../pulls/<index>.diff.
The original upstream command file lives at ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/code-review/commands/code-review.md (read during planning). We fork it; we do not edit the marketplace original.

The five `gh`→`tea` contact points in the original

#	Step in original	`gh` call	`tea` replacement
1	Eligibility (closed / draft / trivial / already-reviewed)	`gh pr view`, `gh pr list`	`tea pulls <idx> --fields state,draft,title,mergeable -o json`; already-reviewed = `tea pulls review-comments <idx>` scan for marker
2	Gather CLAUDE.md paths	(local fs)	unchanged — local fs
3	Summarize the PR	`gh pr view`, `gh pr diff`	`tea pulls <idx> --fields title,body,diff -o json` + `git diff origin/<base>...origin/<head>`
4	Parallel review agents	(no git tool — reads diff/files already fetched)	unchanged
5	Post comment	`gh pr comment <pr> --body ...`	`tea api /repos/{owner}/{repo}/issues/<idx>/comments -F body=@-` (stdin; `-F` typed field reads `@-`, `-f` would post literal `@-`; `/repos/` prefix required)

File Structure

.claude/plugins/code-review-tea/
├── .claude-plugin/
│   ├── plugin.json                 # the manifest (credits Anthropic/Boris Cherny)
│   └── commands/
│       ├── code-review.md          # the forked, tea-rewritten command
│       └── RESOLVED_INVOCATION.md  # verified tea call notes (from Task 2)
└── README.md                       # what this fork is, why, how it differs

Rationale: a project-local plugin under .claude/plugins/ is version-controlled with the repo and applies only here (this is a Gitea-only repo; a global install would mis-fire on the user's GitHub-hosted repos). The name code-review-tea is distinct from the upstream code-review so it never shadows or confuses the GitHub plugin if that ever gets enabled elsewhere.

We create no Python source changes and no test files — this is a tooling-only change. The allowed-tools substitution and command-file rewrite are the entire substance.

Task 1: Scaffold the project-local plugin

Files:

Create: .claude/plugins/code-review-tea/.claude-plugin/plugin.json
Create: .claude/plugins/code-review-tea/.claude-plugin/commands/.gitkeep
Step 1: Create the plugin manifest

Create .claude/plugins/code-review-tea/.claude-plugin/plugin.json:

{
  "name": "code-review-tea",
  "description": "Automated code review for Gitea pull requests (tea CLI) using multiple specialized agents with confidence-based scoring. Fork of Anthropic's code-review plugin, adapted from gh to tea.",
  "version": "1.0.0",
  "author": {
    "name": "Vigilar",
    "email": "noreply@adlee.work"
  },
  "contributors": [
    {
      "name": "Boris Cherny",
      "email": "boris@anthropic.com",
      "note": "Original code-review plugin (claude-plugins-official). This plugin forks its review design."
    }
  ],
  "homepage": "https://git.adlee.work/alee/vigilar"
}

(The contributors[].note field is non-standard metadata — kept for provenance. If Claude Code's plugin loader rejects unknown JSON keys, drop note and rely on README/README credit instead; Task 6 step 3 verifies loading.)

Step 2: Create the commands directory placeholder

Create .claude/plugins/code-review-tea/.claude-plugin/commands/.gitkeep as an empty file so the directory is tracked by git.

Step 3: Verify the directory tree

Run:

find .claude/plugins/code-review-tea -type f

Expected: two files — plugin.json and commands/.gitkeep.

Step 4: Commit

git add .claude/plugins/code-review-tea
git commit -m "chore(plugin): scaffold code-review-tea plugin manifest"

Task 2: Resolve the exact `tea` comment-posting invocation

Before writing the command file in Task 3, nail down the one uncertain API surface: how to post a large multi-paragraph Markdown review body to a Gitea PR. tea comment <idx> <body> takes the body as a trailing arg (shell-quoting a long Markdown body with backticks and # headers is fragile). Confirm the robust tea api path works against this Gitea instance.

Files:

No permanent file changes. Verification task whose result is recorded in RESOLVED_INVOCATION.md (Task 6 integrates it; here we just verify and note the result).
Step 1: Confirm PR #7 metadata is readable via tea

Run:

tea pulls 7 --remote origin --fields index,state,draft,title,mergeable,base,head,body,diff -o json 2>&1 | head -40

Expected: JSON object with state: "closed" (it's merged), title starting "fix: unify PIN hashing", non-empty diff. If --remote origin fails to resolve context, retry with --login alee and record which flag is required (it becomes the default in the command file).

Step 2: Create a scratch issue as the comment round-trip target

tea issue create --remote origin --title "code-review-tea smoke test (delete me)" --description "scratch target for verifying tea comment posting; safe to delete" -o json 2>&1

Expected: JSON with the new issue's index (a number). Record it as $SCRATCH.

If tea issue create needs a different flag form, fall back to:

tea issues create --remote origin --title "code-review-tea smoke test (delete me)"

and read the created index from output or tea issues ls --state open.

Step 3: Post a multi-line Markdown body via tea api stdin

Run (replace $SCRATCH with the real index):

printf '### Code review smoke test\n\nFound 1 issue:\n\n1. Placeholder finding for `tea` round-trip verification.\n\nhttps://git.adlee.work/alee/vigilar/src/commit/%s/vigilar/cli/__init__.py#L1-L3\n' "$(git rev-parse HEAD)" \
  | tea api --remote origin "{owner}/{repo}/issues/$SCRATCH/comments" -f body=@-

Expected: a JSON response containing the posted comment's body and id. If -f body=@- is rejected, fall back to writing the body to /tmp/review-tea-body.md and running tea api --remote origin "{owner}/{repo}/issues/$SCRATCH/comments" -f body=@/tmp/review-tea-body.md. Record which variant worked — it's the canonical post-back invocation for the command file in Task 3.

Step 4: Verify the Gitea code-link format renders

Run:

tea api --remote origin "{owner}/{repo}/issues/$SCRATCH/comments" -o json 2>&1 | head -40

Expected: the posted comment present with the src/commit/<sha>/...#L1-L3 URL intact. Open the URL in a browser (or tea open the issue) to confirm it resolves to the file at that commit. If Gitea requires a different path segment than src/commit, correct the link format used in Task 3's command file.

Step 5: Clean up the scratch issue

tea issue close --remote origin "$SCRATCH"

Expected: issue closed. (Gitea keeps the index; that's fine — it's marked closed and titled "delete me".)

Step 6: Record the verified invocation (provenance for Task 3 + Task 5)

Make a mental/scratch note of: (a) which login-context flag worked (--remote origin vs --login alee), (b) which post-back variant worked (stdin -f body=@- vs file -f body=@/tmp/...), (c) the confirmed Gitea link path segment (src/commit). These three values are baked into the command file (Task 3) and documented in the README (Task 5). No file written in this task.

Task 3: Write the `tea`-adapted command file

The substantive change. Fork the upstream command, substitute the five gh contact points and the link format, keep the parallel-agent + confidence-score + 80-threshold logic identical, and add a header crediting the original.

Files:

Create: .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md
Step 1: Read the upstream command file for reference

Run:

cat ~/.claude/plugins/marketplaces/claude-plugins-official/plugins/code-review/commands/code-review.md

Expected: the 93-line original. Keep it open; this is the template to fork.

Step 2: Write the command file

Create .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md. The full content:

---
allowed-tools: Bash(tea pulls:*), Bash(tea pulls review-comments:*), Bash(tea comment:*), Bash(tea api:*), Bash(tea issue create:*), Bash(tea issue close:*), Bash(git diff:*), Bash(git rev-parse:*), Bash(git config:*), Bash(git remote get-url:*), Bash(git remote:*)
description: Code review a Gitea pull request (tea CLI)
disable-model-invocation: false
---

<!-- Fork of Anthropic's code-review plugin (author: Boris Cherny, boris@anthropic.com),
     from the claude-plugins-official marketplace. The upstream is GitHub/gh-only.
     This fork adapts it to Gitea/tea. Credit for the review design (5 parallel agents,
     confidence scoring, false-positive filtering) belongs to the original. -->

Provide a code review for the given Gitea pull request.

You are operating on a Gitea-hosted repository (not GitHub). All Gitea interaction goes through the `tea` CLI (NOT `gh`). The git remote is `ssh://git@git.adlee.work:2222/alee/vigilar.git`; the web host is `https://git.adlee.work`. The `alee` tea login is configured but is NOT the default, so always pass `--remote origin` to resolve repo context (fall back to `--login alee` only if that fails).

**tea api gotchas (verified):** Use `-F` (typed field) — NOT `-f` (string field) — when reading body from a file or stdin. `-f key=@file` posts the literal string `@file`; only `-F key=@file` / `-F key=@-` reads the file/stdin. Endpoints addressing a repo resource require the `/repos/` prefix after the version: `/repos/{owner}/{repo}/...` (NOT `{owner}/{repo}/...`, which 404s). `tea api` already prints JSON to stdout — do NOT pass `-o json` (that writes the body to a file named `json`).

First, make a todo list of these steps, then execute them precisely:

1. Take the PR index from the user (ask if not provided). Use a Haiku agent to fetch `tea pulls <INDEX> --remote origin --fields index,state,draft,title,mergeable,base,head,body -o json` and check if the PR (a) is closed/merged, (b) is a draft, (c) does not need a review (trivial/automated), or (d) already has a code review from you. For (d), run `tea pulls review-comments <INDEX> --remote origin -o json` and scan each comment's `body` for the marker line `### Code review` generated by a `code-review-tea` run (check `reviewer` is the bot/your account). If any of a–d, do not proceed. (Note: in tea v0.14.1 the `diff`/`patch` fields come back empty even when requested — fetch the diff separately in step 3.)

2. Use another Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root `CLAUDE.md`, plus any `CLAUDE.md` in the directories whose files the PR modified. Determine modified dirs from the diff obtained in step 1 (parse the `+++ b/<path>` and `--- a/<path>` headers).

3. Use a Haiku agent to summarize the change from the diff. Fetch the diff locally — it is the reliable source in this tea build: `git diff origin/<base>...origin/<head>` (where `base`/`head` are the PR's branch names from step 1's JSON, e.g. `origin/main...origin/fix/issue-2-pin-unification`). Ensure both refs are fetched first (`git fetch origin` if needed).

4. Then, launch 5 parallel Sonnet agents to independently code review the change. The agents should do the following, then return a list of issues and the reason each issue was flagged (eg. CLAUDE.md adherence, bug, historical git context, etc.):
   a. Agent #1: Audit the changes to make sure they comply with the CLAUDE.md. Note that CLAUDE.md is guidance for Claude as it writes code, so not all instructions will be applicable during code review.
   b. Agent #2: Read the file changes in the pull request, then do a shallow scan for obvious bugs. Avoid reading extra context beyond the changes, focusing just on the changes themselves. Focus on large bugs, and avoid small issues and nitpicks. Ignore likely false positives.
   c. Agent #3: Read the git blame and history of the code modified, to identify any bugs in light of that historical context.
   d. Agent #4: Read previous pull requests that touched these files (`tea pulls ls --state all --remote origin` then cross-reference file paths), and check for any comments on those pull requests (`tea pulls review-comments <IDX> --remote origin`) that may also apply to the current pull request.
   e. Agent #5: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
5. For each issue found in #4, launch a parallel Haiku agent that takes the PR index, issue description, and list of CLAUDE.md files (from step 2), and returns a score to indicate the agent's level of confidence for whether the issue is real or false positive. To do that, the agent should score each issue on a scale from 0-100, indicating its level of confidence. For issues that were flagged due to CLAUDE.md instructions, the agent should double check that the CLAUDE.md actually calls out that issue specifically. The scale is (give this rubric to the agent verbatim):
   a. 0: Not confident at all. This is a false positive that doesn't stand up to light scrutiny, or is a pre-existing issue.
   b. 25: Somewhat confident. This might be a real issue, but may also be a false positive. The agent wasn't able to verify that it's a real issue. If the issue is stylistic, it is one that was not explicitly called out in the relevant CLAUDE.md.
   c. 50: Moderately confident. The agent was able to verify this is a real issue, but it might be a nitpick or not happen very often in practice. Relative to the rest of the PR, it's not very important.
   d. 75: Highly confident. The agent double checked the issue, and verified that it is very likely it is a real issue that will be hit in practice. The existing approach in the PR is insufficient. The issue is very important and will directly impact the code's functionality, or it is an issue that is directly mentioned in the relevant CLAUDE.md.
   e. 100: Absolutely certain. The agent double checked the issue, and confirmed that it is definitely a real issue, that will happen frequently in practice. The evidence directly confirms this.
6. Filter out any issues with a score less than 80. If there are no issues that meet this criteria, do not proceed.
7. Use a Haiku agent to repeat the eligibility check from #1, to make sure that the pull request is still eligible for code review.
8. Finally, post the result back to the Gitea PR as a single comment using:
   ```bash
   printf '%s' "$BODY" | tea api --remote origin "/repos/{owner}/{repo}/issues/<INDEX>/comments" -F body=@-
   ```
   where `<INDEX>` is the PR index and `{owner}/{repo}` are substituted by `tea api` from repo context. Note the **`-F`** (typed field, reads stdin via `@-`) — NOT `-f`, which would post the literal string `@-`. Note the **`/repos/`** prefix on the endpoint. If stdin body is rejected, write `$BODY` to `/tmp/review-tea-body.md` and use `-F body=@/tmp/review-tea-body.md`. When writing `$BODY`, keep in mind that you must:
   a. Keep your output brief
   b. Avoid emojis
   c. Link and cite relevant code, files, and URLs — using the **Gitea** link format (NOT GitHub):
      `https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L<start>-L<end>`
      Use the PR's head SHA (from step 1's JSON `headSha`), which is present on the remote. Never use a local-only / unpushed SHA — a commit not on the remote yields a 404 link even on a public repo. Never bash-substitute `$(git rev-parse HEAD)` into the rendered Markdown. Gitea uses `src/commit`, not `blob`.

Examples of false positives, for steps 4 and 5:

- Pre-existing issues
- Something that looks like a bug but is not actually a bug
- Pedantic nitpicks that a senior engineer wouldn't call out
- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
- General code quality issues (eg. lack of test coverage, general security issues, poor documentation), unless explicitly required in CLAUDE.md
- Issues that are called out in CLAUDE.md, but explicitly silenced in the code (eg. due to a lint ignore comment)
- Changes in functionality that are likely intentional or are directly related to the broader change
- Real issues, but on lines that the user did not modify in their pull request

Notes:

- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
- Use `tea` (NOT `gh`) to interact with Gitea (eg. to fetch a pull request, or to create comments), never web fetch.
- Make a todo list first
- You must cite and link each bug (eg. if referring to a CLAUDE.md, you must link it)
- For your final comment, follow the following format precisely (assuming for this example that you found 3 issues):

---

### Code review

Found 3 issues:

1. <brief description of bug> (CLAUDE.md says "<...>")

https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L13-L17

2. <brief description of bug> (some/other/CLAUDE.md says "<...>")

https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L23-L28

3. <brief description of bug> (bug due to <file and code snippet>)

https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L44-L50

🤖 Generated with [Claude Code](https://claude.ai/code)

<sub>- If this code review was useful, please react with 👍. Otherwise, react with 👎.</sub>

---

- Or, if you found no issues:

---

### Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with [Claude Code](https://claude.ai/code)

---

- When linking to code, follow this Gitea format precisely, otherwise the Markdown preview won't render correctly: `https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L<start>-L<end>`
  - Requires the full git sha of a **remote-present** commit (the PR head SHA from step 1's JSON `headSha`). Never `$(git rev-parse HEAD)` substituted into the rendered comment, and never a local-only/unpushed SHA — those 404 even on a public repo
  - Repo path must be `alee/vigilar` (matches the git remote)
  - `#L` sign after the file name
  - Line range format is `<start>-<end>` (Gitea uses `L1-L3`, same as GitHub but under `src/commit`)
  - Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if commenting about lines 5-6, link to `L4-L7`)

Step 3: Sanity-check the command file frontmatter

Run:

head -6 .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md

Expected: the --- fence, allowed-tools: line containing only Bash(tea ...:*), Bash(git ...:*) entries (NO gh), then description: and disable-model-invocation: false, then closing ---.

Step 4: Grep to confirm no gh references leaked in

Run:

grep -nE '\bgh\b|github\.com|/blob/' .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md || echo "clean: no gh/github/blob references"

Expected: clean: no gh/github/blob references. If anything matches, fix it before committing. (Note: the credit comment intentionally mentions "GitHub/gh-only" to describe the upstream — that line references gh as a word, so adjust the grep if it fires on the credit line; the credit line is correct and should stay. The grep is meant to catch operational gh calls, which would look like gh pr or gh issue.)

A more precise check:

grep -nE 'gh pr|gh issue|gh search|gh api|github\.com/alee/vigilar/blob|/blob/<' .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md || echo "clean: no operational gh calls or blob links"

Expected: clean: no operational gh calls or blob links.

Step 5: Commit

git add .claude/plugins/code-review-tea/.claude-plugin/commands/code-review.md
git commit -m "feat(plugin): gitea/tea port of code-review command"

Task 4: Enable the plugin in this project's settings

Files:

Modify: .claude/settings.json
Step 1: Read the current settings

Run:

cat .claude/settings.json

Expected:

{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true
  }
}

Step 2: Add the new plugin to enabledPlugins

Change .claude/settings.json to:

{
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "code-review-tea@vigilar": true
  }
}

The @vigilar suffix denotes a project-local (non-marketplace) plugin discovered from .claude/plugins/code-review-tea/. If Claude Code resolves local plugins by bare directory name (no @source suffix), drop it to "code-review-tea": true. Step 3 verifies which form is accepted.

Step 3: Verify the plugin is discoverable

Restart/reload Claude Code for this project and run /code-review-tea. If the command is not found, Claude Code's local-plugin resolution may need the bare plugin name — change settings to "code-review-tea": true and re-verify. If still not found, confirm the plugin is discovered at all by checking whether /code-review-tea appears in the command list (if not, the loader may not scan .claude/plugins/ — in that case, the plugin can still be invoked by directly reading the command file; document this fallback in the README).

Step 4: Commit

git add .claude/settings.json
git commit -m "chore(plugin): enable project-local code-review-tea plugin"

Task 5: Document the plugin (README + RESOLVED_INVOCATION + CLAUDE.md note)

Files:

Create: .claude/plugins/code-review-tea/README.md
Create: .claude/plugins/code-review-tea/.claude-plugin/commands/RESOLVED_INVOCATION.md
Modify: CLAUDE.md — append a short "## Code Review" subsection
Step 1: Write the verified invocation notes

Create .claude/plugins/code-review-tea/.claude-plugin/commands/RESOLVED_INVOCATION.md. Fill in with the variants verified in Task 2 (replace <verified> placeholders with the actually-confirmed values):

# Resolved tea post-back invocation (verified via Task 2 smoke run)

Gitea comment posting that survives large multi-line Markdown bodies:

    tea api --remote origin "{owner}/{repo}/issues/<PR_INDEX>/comments" -f body=@-   # body via stdin  <verify: confirmed/rejected>
    # fallback: -f body=@/tmp/review-tea-body.md                                     # body via file    <verify: confirmed/rejected>

Code link format (verify it renders in Gitea web):
    https://git.adlee.work/alee/vigilar/src/commit/<FULL-SHA>/<path>#L<start>-L<end>   # path segment confirms src/commit <verify>

Eligibility metadata fetch:
    tea pulls <PR_INDEX> --remote origin --fields state,draft,title,mergeable,base,head,body,diff -o json

Diff source (preferred, local):
    git diff origin/<base>...origin/<head>

Login context: the `alee` tea login is NOT default (tea login list shows default=false). <verify: --remote origin resolves / --login alee required>

Step 2: Write the plugin README

Create .claude/plugins/code-review-tea/README.md:

# code-review-tea

Project-local fork of Anthropic's `code-review` plugin, adapted from the GitHub CLI (`gh`) to the Gitea CLI (`tea`).

## Credit

This plugin is a fork of **Anthropic's `code-review` plugin** (author: **Boris Cherny**, `boris@anthropic.com`), from the `claude-plugins-official` marketplace. The upstream plugin is GitHub/`gh`-only. All credit for the review design — the 5 parallel specialized agents, confidence-based scoring, and false-positive filtering — belongs to the original. This fork changes only the Gitea contact points.

## Why a fork

Vigilar is hosted on a self-hosted Gitea instance (`git.adlee.work`), not GitHub. The upstream `code-review` plugin is hard-wired to `gh` (its `allowed-tools`, PR-fetching, and comment-posting all call `gh`), so it cannot run against this repo as-is. This fork substitutes the five `gh` contact points with `tea` equivalents and changes code-link URLs from GitHub's `blob/SHA/path#L` format to Gitea's `src/commit/SHA/path#L` format.

## Usage

On a branch with an open Gitea pull request against `main`:

    /code-review-tea

Claude will:
- Verify the PR is reviewable (skip closed/draft/trivial/already-reviewed)
- Gather relevant CLAUDE.md files
- Summarize the change
- Launch 5 parallel review agents (CLAUDE.md compliance, bug scan, git-history context, prior-PR comments, in-code-comment compliance)
- Score each finding 0–100 for confidence
- Filter to findings ≥80
- Post a single review comment back to the Gitea PR via `tea api`

## Requirements

- `tea` CLI (v0.14.1+) installed and logged in as `alee` against `https://git.adlee.work`
- The `alee` login need NOT be the default — the command passes `--remote origin` to resolve context
- An open Gitea pull request to review

## Differences from upstream

| Area | Upstream (GitHub) | This fork (Gitea) |
|---|---|---|
| CLI | `gh` | `tea` |
| PR metadata | `gh pr view` | `tea pulls <idx> --fields ... -o json` |
| Diff | `gh pr diff` | `git diff origin/<base>...origin/<head>` (local) |
| Comment post | `gh pr comment --body` | `tea api {owner}/{repo}/issues/<idx>/comments -f body=@-` |
| Code link | `github.com/o/r/blob/SHA/path#L` | `git.adlee.work/alee/vigilar/src/commit/SHA/path#L` |
| Inline line comments | (upstream posts one summary comment) | NOT attempted — single summary comment only (Gitea inline-comment API needs `tea api` review endpoints; out of scope) |

See `.claude-plugin/commands/RESOLVED_INVOCATION.md` for the verified `tea` calls.

Step 3: Append a Code Review subsection to CLAUDE.md

Append to CLAUDE.md, as a new ## Code Review section near the existing ## Commands section:

## Code Review
- `/code-review-tea` — review the current Gitea PR (project-local fork of Anthropic's code-review plugin, adapted from `gh` to `tea`; credit: Boris Cherny). See `.claude/plugins/code-review-tea/README.md`.

Step 4: Commit

git add .claude/plugins/code-review-tea/README.md .claude/plugins/code-review-tea/.claude-plugin/commands/RESOLVED_INVOCATION.md CLAUDE.md
git commit -m "docs(plugin): document code-review-tea fork and CLAUDE.md note"

Task 6: Smoke-test the command against a scratch PR

End-to-end verification that the full pipeline (eligibility → CLAUDE.md gather → summarize → 5 parallel agents → score → filter → post) works through tea against a real Gitea PR. Use a throwaway PR with a deliberately obvious bug so the pipeline has something to find and post.

Files:

No permanent file changes. The scratch PR is closed and its branch deleted after.
Step 1: Create a scratch branch with an obvious bug

git checkout -b scratch/review-smoke main

Introduce an obvious bug in a low-risk spot — e.g. in vigilar/constants.py swap a comparison, or create a trivial vigilar/_scratch_review.py:

def is_armed(state):
    # BUG: assignment instead of comparison
    if state = "armed":
        return True
    return False

Minimal change — the point is to exercise the pipeline, not to ship.

Step 2: Push and open a PR via tea

git add -A
git commit -m "scratch: review smoke test (do not merge)"
git push -u origin scratch/review-smoke
tea pulls create --remote origin --base main --head scratch/review-smoke \
  --title "scratch: code-review-tea smoke test (do not merge)" \
  --description "Throwaway PR to verify the code-review-tea pipeline end-to-end. Safe to close."

Expected: a new PR index. Record it as $SMOKE.

Step 3: Run the adapted command against the scratch PR

Run /code-review-tea and provide $SMOKE as the PR index. Watch for each stage:

eligibility fetch via tea pulls ✓
CLAUDE.md gather ✓
summary ✓
5 parallel agents return ✓
each finding scored ✓
≥80 findings (or graceful "No issues" path) ✓
comment posted via tea api ✓

If any stage fails, capture the error and fix the command file (Task 3) — this smoke test exists to catch exactly that.

Step 4: Verify the posted comment on Gitea

tea api --remote origin "{owner}/{repo}/issues/$SMOKE/comments" -o json 2>&1 | head -60

Expected: a comment whose body starts with ### Code review, contains Gitea src/commit/<sha>/...#L... links (NOT github.com/blob), and (if the bug was obvious) lists it under "Found N issues". Open the PR in a browser to confirm the links render and resolve.

Step 5: Close the scratch PR and delete the branch

tea pulls close --remote origin "$SMOKE"
git push origin --delete scratch/review-smoke
git checkout main
git branch -D scratch/review-smoke

Expected: PR closed, remote branch deleted, back on main, local branch gone.

Step 6: Clean up the scratch source file

git rm vigilar/_scratch_review.py 2>/dev/null && git commit -m "chore: remove review smoke-test scratch file" || echo "nothing to clean"

Step 7: Update RESOLVED_INVOCATION.md with the end-to-end confirmation

Edit .claude/plugins/code-review-tea/.claude-plugin/commands/RESOLVED_INVOCATION.md to replace each <verify: ...> placeholder with the actual confirmed result from this smoke run (stdin worked vs file fallback, --remote origin resolved, src/commit rendered). Commit:

git add .claude/plugins/code-review-tea/.claude-plugin/commands/RESOLVED_INVOCATION.md
git commit -m "docs(plugin): confirm resolved tea invocation from smoke test"

Self-Review (run after all tasks written)

Spec coverage — The user asked: make the code-review plugin work on Gitea (tea), name it code-review-tea, give credit to the original. → Tasks 1–6: scaffold, resolve invocation, write command, enable, document, smoke-test. Credit appears in plugin.json (contributors), command file header comment, and README. ✓ No hot-path review (dropped per revised scope). ✓
Placeholder scan — Command file content is verbatim in Task 3 (full file with 4-backtick fence preserving inner 3-backtick fences). Test bodies are concrete (is_armed scratch bug). The only "verify which form" items (Task 4 Step 3 plugin discovery; Task 5 RESOLVED_INVOCATION <verify> placeholders) are real, intentional verifications — each has a concrete fallback and a step that resolves it, not an unfilled "TBD".
Name consistency — code-review-tea used consistently in directory, plugin.json name, settings key, README title, CLAUDE.md note, and /code-review-tea invocation. No leftover supertea or code-review-gitea.
Credit correctness — Original author Boris Cherny / Anthropic credited in plugin.json contributors, command file header comment, and README "Credit" section. Fork relationship stated (upstream = GitHub/gh-only).
Uncertainty surfaced honestly — tea comment vs tea api posting (Task 2 verifies, fallback documented); local-plugin enabledPlugins key form (Task 4 Step 3 verifies); Gitea src/commit path segment (Task 2/6 verifies render); plugin.json unknown-key tolerance (Task 1 Step 1 note + Task 6 smoke exercises loading). None silently assumed.


---

## Execution Handoff

**Plan complete and saved to `docs/superpowers/plans/2026-06-27-code-review-tea-plugin.md`.** Two execution options:

**1. Subagent-Driven (recommended)** — I dispatch a fresh subagent per task, review between tasks, fast iteration.

**2. Inline Execution** — Execute tasks in this session using executing-plans, batch execution with checkpoints.

**Which approach?**

Task 2 and Task 6 make live `tea` calls against your Gitea instance (creating a scratch issue and a scratch PR that are closed immediately after). Those are the only outward-facing actions; everything else is local file edits. If you'd rather skip the live smoke test (Task 6) and just have the plugin built + documented for you to test manually later, say so and I'll execute Tasks 1–5 only.

36 KiB Raw Blame History Unescape Escape

code-review-tea Plugin Implementation Plan

Context & Verified Facts

The five gh→tea contact points in the original

File Structure

Task 1: Scaffold the project-local plugin

Task 2: Resolve the exact tea comment-posting invocation

Task 3: Write the tea-adapted command file

Task 4: Enable the plugin in this project's settings

Task 5: Document the plugin (README + RESOLVED_INVOCATION + CLAUDE.md note)

Task 6: Smoke-test the command against a scratch PR

Self-Review (run after all tasks written)

36 KiB

Raw Blame History

The five `gh`→`tea` contact points in the original

Task 2: Resolve the exact `tea` comment-posting invocation

Task 3: Write the `tea`-adapted command file