@capybearista/opencode-adversarial-review 1.0.0 → 2.0.1

package/README.md

@@ -1,161 +1,167 @@
 # opencode-adversarial-review
 
-<p align="center">Challenge code with adversarial review</p>
+<p align="center">Unbiased challenges and reviews for your code</p>
 <p align="center">
-  <a href="https://www.npmjs.com/package/@capybearista/opencode-adversarial-review"><img alt="npm" src="https://img.shields.io/npm/v/@capybearista/opencode-adversarial-review?style=flat-square&color=8d60e6" /></a>
-  <a href="https://www.npmjs.com/package/@capybearista/opencode-adversarial-review"><img alt="npm" src="https://img.shields.io/npm/dm/@capybearista/opencode-adversarial-review?style=flat-square&color=6067e6" /></a>
-  <a href="https://opencode.ai"><img alt="opencode" src="https://img.shields.io/badge/OpenCode-Plugin-orange?style=flat-square&color=60a5e6
-  " /></a>
+  <a href="https://www.npmjs.com/package/@capybearista/opencode-adversarial-review"><img alt="npm version" src="https://img.shields.io/npm/v/@capybearista/opencode-adversarial-review?style=flat-square&color=8d60e6" /></a>
+  <a href="https://www.npmjs.com/package/@capybearista/opencode-adversarial-review"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@capybearista/opencode-adversarial-review?style=flat-square&color=6067e6" /></a>
+  <a href="https://opencode.ai"><img alt="opencode" src="https://img.shields.io/badge/OpenCode-Plugin-orange?style=flat-square&color=60a5e6" /></a>
   <a href="https://opensource.org/licenses/MPL-2.0"><img alt="license" src="https://img.shields.io/badge/License-MPL--2.0-blue.svg?style=flat-square&color=60dfe6" /></a>
 </p>
+
 ---
 
 ## Why?
 
-> Provides an adversarial code review agent that challenges implementation approach and design choices, not just finding bugs. Uses a clean-context subagent so the review is unbiased by conversation history.
+> Two code review agents with a clean-context subagent each, so reviews are unbiased by conversation history: an **adversarial reviewer** that challenges approach and design choices (modeled on the Codex CLI's review system), and a general **constructive reviewer** that checks correctness first and suggests improvements.
 
 ## Philosophy: Extending OpenCode
 
-OpenCode is designed to be highly extensible. This plugin hooks into the OpenCode lifecycle to provide additional functionality seamlessly into your workflows. This plugin is modeled after the Codex CLI's adversarial review system, focusing on "breaking confidence" rather than validating changes.
+OpenCode is designed to be highly extensible. This plugin adds adversarial and constructive review passes directly to your workflow.
 
 ### Architecture
 
 ```mermaid
 graph TB
-    subgraph Host [OpenCode Host]
-        User([User]) -->|/adversarial-review| Command[Command Template]
+    subgraph OpenCode [OpenCode]
+        User([User]) -->|"/adversarial-review / /constructive-review"| Command[Installed Command Templates]
+        Command -->|"$ARGUMENTS + five shell blocks"| Reviewer
     end
 
-    subgraph Injection [Context Injection]
-        direction LR
-        Command -->|!git status| S[Status]
-        Command -->|!git log| L[Commits]
-        Command -->|!git diff| D[Diff Summary]
-        Command -->|!cat| U[Untracked]
+    subgraph Plugin [Plugin]
+        Setup[setup] -->|registers| Reviewer{"adversarial-reviewer<br/>constructive-reviewer<br/>hidden subagents"}
+        Setup -->|"atomic install; stamped refresh"| Command
     end
 
-    subgraph Adversary [Adversarial Subagent]
-        direction TB
-        Reviewer{Adversarial Reviewer}
-        S & L & D & U --> Reviewer
-        
-        Reviewer -->|Self-Collect| Tools[Explorer Tools]
-        Tools -->|Source Code| Reviewer
+    subgraph Review [Review Session]
+        Reviewer -->|self-collected evidence| Tools[read / grep / glob / git / gh]
+        Tools --> Reviewer
+        Reviewer -->|"requested output: JSON / Markdown"| User
     end
 
-    Reviewer -->|Structured JSON| User
-
-    classDef host fill:#bbf,stroke:#333,stroke-width:2px;
-    classDef collection fill:#dfd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
+    classDef opencode fill:#bbf,stroke:#333,stroke-width:2px;
+    classDef plugin fill:#dfd,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
     classDef adversary fill:#f9f,stroke:#333,stroke-width:2px;
-    
-    class Host host;
-    class Collection collection;
-    class Adversary adversary;
+
+    class OpenCode opencode;
+    class Plugin plugin;
+    class Review adversary;
 ```
 
-The plugin uses a **stateless subagent architecture**. When the command is invoked, a deterministic shell script collects git metadata (diff stat, untracked files, recent commits) and injects it into a fresh subagent session. This ensures the review is unbiased by the primary agent's conversation history.
+One config drives two sandboxed subagents: agents register in memory and commands install to disk,
+
+- **Agents**: setup registers the hidden `adversarial-reviewer` and `constructive-reviewer` subagents; nothing is written to your agents directory.
+- **Commands**: setup installs `~/.config/opencode/commands/adversarial-review.md` and `~/.config/opencode/commands/constructive-review.md` into your OpenCode config directory.
+- **Prompts**: `src/prompt.ts` holds both system prompts; `src/prompts/adversarial-review.md` and `src/prompts/constructive-review.md` are their reference copies. All review doctrine — target selection, evidence rules, output contract — lives there, never in the command templates.
 
 ## Features
 
-- **Adversarial Persona**: A specialized subagent prompted to find reasons *not* to ship, prioritizing auth gaps, race conditions, and data loss.
-- **Dynamic Context Collection**: Automatically switches between full-inline diff (for 1-2 files) and high-level stat (for larger changes).
-- **Subagent Self-Collection**: The subagent uses whitelisted git and file tools to "pull" the specific file contents it needs based on the initial diff summary.
-- **Structured JSON Output**: Returns findings with severity, file locations, confidence scores, and concrete recommendations.
-- **Configurable Scope**: Support for `--base <ref>`, `--scope branch`, and `--scope working-tree`.
+- **Two reviewers**: adversarial (reasons *not* to ship) and constructive (correctness first, then suggestions).
+- **Reviewer-collected evidence**: changed files, untracked files, and branch diffs are inspected with read-only tools; only verified findings are reported.
+- **Auto-installed commands**: both slash commands are written on first setup; stamped files refresh on `/reload`, user-owned edits are preserved (see note below).
+- **Targets**: `--scope`, `--base`, bare commit SHA, or PR URL/number on both commands.
 
 ## Install
 
-Add the plugin to `opencode.json` or `opencode.jsonc`:
+### OpenCode V2
+
+Add it under the `"plugins"` key in `opencode.json(c)`:
+
 ```json
 {
-  "plugin": ["@capybearista/opencode-adversarial-review"]
+  "plugins": ["@capybearista/opencode-adversarial-review@latest"]
 }
 ```
 
-You can also install it through the CLI:
+Server entry only, so `cli.json` needs no entry.
 
-```bash
-opencode plugin -g @capybearista/opencode-adversarial-review    # global install
-opencode plugin @capybearista/opencode-adversarial-review    # project-local install
-```
+### OpenCode V1
 
-## Usage
+Add it under the `"plugin"` key in `opencode.json(c)`:
 
-Run a review on your current working tree changes:
-```bash
-/adversarial-review
+```json
+{
+  "plugin": ["@capybearista/opencode-adversarial-review@1.0.0"]
+}
 ```
 
-### Arguments
+Server entry only, so `tui.json(c)` needs no entry.
 
-| Argument | Values | Description |
-| :--- | :--- | :--- |
-| `--scope` | `auto`, `working-tree`, `branch` | The range of changes to review. Defaults to `auto`. |
-| `--base` | `<git-ref>` | The base reference (branch or commit) to compare against when using `branch` scope. |
+See the [V1 plugin guide](../../docs/v1-plugins.md) for details.
 
-- **`auto`**: Reviews using the broadest context the provided information supports.
-- **`working-tree`**: Reviews staged and unstaged changes against `HEAD`.
-- **`branch`**: Reviews all changes on the current branch since it diverged from the upstream or main branch.
-- **`focus ...`**: Any trailing text is treated as a focus area for the review.
+On setup, both command files install at `~/.config/opencode/commands/{adversarial-review.md,constructive-review.md}`. The directory **must already** exist; if a file cannot install, setup fails loudly and **neither** agent is registered.
 
-### Examples
+### Uninstall
 
-Force review of only working tree changes (ignoring branch history):
-```bash
-/adversarial-review --scope working-tree
-```
+Remove the plugin from `"plugin(s)"` from the respective config files they were added to. Then delete both installed command files—plugin removal does not delete them, and OpenCode would otherwise keep discovering commands with no agents behind them.
 
-Review all changes on the current branch (automatically finds the fork point):
-```bash
-/adversarial-review --scope branch
-```
+## Usage
 
-Review a specific branch against its fork point from `main`:
-```bash
-/adversarial-review --base main
-```
+Both commands accept `--scope auto|working-tree|branch`, `--base <ref>`, a bare commit SHA, or a PR URL/number. A PR URL always wins; otherwise the first bare token decides (all-decimal → PR, 7+ hex chars with a letter → commit); an explicit target beats the flags. `/adversarial-review` treats remaining text as a focus area; `/constructive-review` ignores trailing non-flag text (no focus support).
 
-Review with a specific focus area:
 ```bash
-/adversarial-review --base main focus on race conditions in the auth middleware
+/adversarial-review                  # working tree (or branch, if tree is clean)
+/adversarial-review --scope branch   # current branch since fork point
+/adversarial-review 4f2a9c1e         # a commit
+/adversarial-review 42               # PR #42 (bare number; hex SHAs stay commits)
+/constructive-review --scope working-tree  # constructive pass, working tree only
+/constructive-review --scope branch        # constructive pass, current branch since fork point
+/constructive-review 4f2a9c1e              # constructive pass, a commit
+/constructive-review 42                    # constructive pass, PR #42
 ```
 
+> [!NOTE]
+> The installed command files are managed via a `managed_version` stamp in their frontmatter. Keep the stamp and the file refreshes from the bundled template on `/reload`; remove it to take ownership — the file is then left untouched with a warning. Unknown or newer stamps are likewise preserved (downgrades never clobber). A failure partway can leave the first file as a harmless orphan; it is reconciled on the next `/reload`, and registration still waits for both files. Delete a file and `/reload` to force-reinstall; uninstall the plugin *and* delete both files to fully remove the commands.
+>
+> The same ownership rule cleans up an upgrade leftover: a pre-rename build installed the second command as `commands/review.md` with `agent: reviewer`, an agent this version no longer registers, so OpenCode discovers it as a broken `/review`. Setup removes that exact file only when it carries `agent: reviewer` plus a `managed_version` stamp this build knows; any other `review.md` is preserved, with a warning when it carries the old agent id. Setup never deletes a file on a failed refresh unless its `O_TRUNC` open already ran — an unreadable/unwritable managed file is left intact and setup fails loudly instead.
+
 ## Configuration
 
-| Property | Type | Description |
-| :--- | :--- | :--- |
-| `agent.adversarial-review.model` | `string` | The model to use for the subagent (defaults to `openai/gpt-5.4`). |
-| `agent.adversarial-review.temperature` | `number` | Sampling temperature (defaults to `0.1` for deterministic review). |
-| `command.adversarial-review.template` | `string` | The shell-injected template used to gather git context. |
+Nothing is pinned — model and temperature are both inherited. Resolution order for the model: frontmatter `model` (add manually to pin) → agent `model` in OpenCode config → invoking session's model, with its temperature. To pin a reviewer model, set it in `opencode.json`/`opencode.jsonc`:
 
-This plugin requires no manual configuration out of the box, but you can override the subagent model in your local `opencode.json`.
+```jsonc
+{
+  "agents": {
+    "adversarial-reviewer": { "model": "openrouter/openai/gpt-6-sol" },
+    "constructive-reviewer": { "model": "openrouter/openai/gpt-6-sol" }
+  }
+}
+```
 
 ## Permissions & Security
 
-This plugin is designed with a "least privilege" security model. The adversarial subagent is strictly sandboxed to prevent accidental or malicious modifications to your codebase:
+Both reviewers are sandboxed and unattended; the single accepted risk is pasted arguments (below). Details:
+
+**Pasted arguments become executable template content.** `$ARGUMENTS` is substituted before the snapshot blocks run, so argument text can execute as shell. Inspect arguments before invoking, and never pass untrusted or pasted Markdown containing backtick blocks.
 
-- **Edit**: Explicitly denied (`edit: deny`).
-- **Bash**: Restricted to a read-only whitelist of 12 Git patterns (e.g., `git diff`, `git log`, `git status`). All other shell commands are blocked.
-- **Read/Grep/Glob**: Allowed (read-only) to enable code inspection.
-- **Network**: Web fetch and search are disabled to ensure the review remains focused on the files at hand.
+One shared sandbox: `edit`/`write`/`patch`, `subagent`, `skill`, `webfetch`/`websearch`, `question` denied (zero ask — reviewers run unattended); shell limited to 13 read-only `git` patterns plus `gh pr view*`/`gh pr diff*` and the `gh auth status*` diagnostic (token-printing and all other `gh` denied); `read`/`grep`/`glob` allowed except `.env`/`.env.*` (`.env.example` allowed, as is `git show <rev>:<path>` of a `.env.example` blob). See `AGENTS.md` for the full rule inventory.
 
 ## Troubleshooting
 
-- **"No changes to review"**: Ensure you have staged or unstaged changes, or use `--base` to review a committed branch.
-- **Model timeouts**: Large diffs may require a model with a larger context window or more time. The subagent is whitelisted to `read` files if the diff stat is too long to include.
-- **Git errors**: Ensure you are running within a git repository. The command relies on `git` being available in your PATH.
+- **Setup failed installing a command file**: create (or fix permissions on) `<config>/commands/`, then `/reload`. A readable-but-unwritable managed file is left untouched, never deleted.
+- **"Leaving it untouched" warning**: the file is user-owned or carries an unknown/newer stamp — edit in place, or delete to reinstall.
+- **Broken `/review` after upgrading**: a pre-rename build's `commands/review.md` references the removed `reviewer` agent. Setup removes it when it carries a known stamp; an unstamped copy is preserved with a warning — delete that file manually.
+- **File replaced on `/reload`**: it kept a known stamp and was refreshed; remove the stamp to take ownership.
+- **"No changes to review"**: stage changes or pass `--base`.
+- **PR target fails**: needs authed `gh`; the reviewer reports that plainly (stderr verbatim on failure).
+- **Large diffs**: use a model with a bigger context window; reviewers also read files as they work.
+- **Not a git repo**: the template needs `git` on `PATH` inside a repository.
 
 ## Contributing
 
 This package lives in the `opencode-plugins` monorepo.
 
-- Run `bun run build`, `bun run typecheck`, `bun run lint`, and `bun test` before opening a PR.
-- Keep the plugin focused on the adversarial code review function.
+See the [contribution guidelines](../../CONTRIBUTING.md) before opening a pull request.
+
+- From the monorepo root, run `bun run build` before artifact checks, then `bun run typecheck`,
+  `bun run lint`, and the canonical `bun run test` Turbo pipeline. Do not use bare root `bun test`
+  as the workspace check.
+- For a focused run, `bun test` is supported from this package directory; its tests include the
+  real local-directory resolver regression.
+- `bun run check` writes Biome changes; use it only when formatting changes are intended.
 - Prefer small, direct changes.
 
 Please open an issue or check for existing ones before creating a pull request.
 
 ## License
 
-[MPL-2.0](LICENSE)
+[MPL-2.0](./LICENSE.txt)

package/commands/adversarial-review.md

@@ -0,0 +1,28 @@
+---
+description: "Adversarial code review: challenges the implementation. Args: [<sha|pr-url|pr-number>] [--base <ref>] [--scope auto|working-tree|branch] [focus ...]"
+agent: adversarial-reviewer
+subagent: true
+managed_version: 2
+metadata: Managed by @capybearista/opencode-adversarial-review. Keep the managed_version stamp to receive bundled-template updates on /reload or restart; remove it to take ownership and your version is then preserved with a warning; a stamp newer than the shipped template is also preserved.
+---
+
+# Adversarial review handoff
+
+You are the adversarial reviewer for this repository. Review the change and return the structured JSON verdict defined in your system prompt.
+
+Target selection, focus weighting, evidence rules, and the output contract live in your system prompt — follow them.
+
+Args and focus: $ARGUMENTS
+
+The blocks below are a point-in-time snapshot rendered by this template. They can be incomplete: commands can fail, output can be empty, and untracked file contents are not inlined. Verify everything with your own read-only tools before reporting.
+
+- Branch:
+  !`git branch --show-current 2>&1 || true`
+- Status:
+  !`git status --short --untracked-files=all 2>&1 || true`
+- Recent commits:
+  !`git log --oneline -3 2>&1 || true`
+- Working-tree diff against HEAD:
+  !`git diff HEAD 2>&1 || true`
+- Untracked files (paths only; read their contents with your tools):
+  !`git ls-files --others --exclude-standard 2>&1 || true`

package/commands/constructive-review.md

@@ -0,0 +1,30 @@
+---
+description: "Constructive code review: correctness and risk. Args: [<sha|pr-url|pr-number>] [--base <ref>] [--scope auto|working-tree|branch]"
+agent: constructive-reviewer
+subagent: true
+managed_version: 2
+metadata: Managed by @capybearista/opencode-adversarial-review. Keep the managed_version stamp to receive bundled-template updates on /reload or restart; remove it to take ownership and your version is then preserved with a warning; a stamp newer than the shipped template is also preserved.
+---
+
+# Review handoff
+
+You are the constructive reviewer for this repository. Review the change for correctness first, then for material maintainability risk, and return the Markdown report defined in your system prompt.
+
+Review only: do not modify the repository; report findings and suggestions for the author to apply.
+
+Target selection (scope flags and explicit targets; no focus text), evidence rules, and the output contract live in your system prompt — follow them.
+
+Args: $ARGUMENTS
+
+The blocks below are a point-in-time snapshot rendered by this template. They can be incomplete: commands can fail, output can be empty, and untracked file contents are not inlined. Verify everything with your own read-only tools before reporting.
+
+- Branch:
+  !`git branch --show-current 2>&1 || true`
+- Status:
+  !`git status --short --untracked-files=all 2>&1 || true`
+- Recent commits:
+  !`git log --oneline -3 2>&1 || true`
+- Working-tree diff against HEAD:
+  !`git diff HEAD 2>&1 || true`
+- Untracked files (paths only; read their contents with your tools):
+  !`git ls-files --others --exclude-standard 2>&1 || true`

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import type { Plugin } from "@opencode-ai/plugin";
-export declare const AdversarialReviewPlugin: Plugin;
-declare const _default: {
-    id: string;
-    server: Plugin;
-};
+import { Plugin } from "@opencode/plugin";
+export declare const CURRENT_TEMPLATE_VERSION = 2;
+export declare const KNOWN_TEMPLATE_VERSIONS: readonly number[];
+export declare function managedVersionOf(markdown: string): number | undefined;
+export declare function isManagedUpgrade(installedVersion: number, knownVersions: readonly number[], currentVersion: number): boolean;
+declare const _default: Plugin.Plugin;
 export default _default;