feat(review): default to minimal 'reviewer' subagent on Sonnet (#364)

* feat(review): default to minimal 'reviewer' subagent on Sonnet

Ship a new 'reviewer' subagent in the DeepWork Claude plugin pinned to
Sonnet with minimal instructions, and default review dispatch to it.
Opus→Sonnet across parallel review fan-out is the dominant cost lever.
Per-rule agent overrides still take precedence.

The reviewer's tools list includes dual-wildcard MCP prefixes
(mcp__plugin_deepwork_deepwork__* and mcp__deepwork-dev__*) so the same
agent file resolves mark_review_as_passed in both production (plugin
install only) and development (dev MCP server, with or without plugin)
contexts. Spec REVIEW-REQ-006.3.c and test_formatter.py are updated in
lockstep; stale REVIEW-REQ-006.3.3b/c cross-references corrected.

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

* fix: address review findings — ID numbering, docs, and PLUG-REQ-001.14

- Fix test_formatter.py traceability comment IDs: restore the .3.3
  hierarchy level (REVIEW-REQ-006.3.3c, .3.3b) instead of the
  incorrectly shortened .3.c, .3.b format.
- Update README_REVIEWS.md example output to match current formatter
  format (name/description/subagent_type/prompt fields, reviewer default).
- Add agents/ directory to CLAUDE.md and doc/architecture.md project
  structure trees.
- Add PLUG-REQ-001.14 (Default Reviewer Subagent) formalizing the
  reviewer agent's existence, model, tools, and behavioral constraints.

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

README_REVIEWS.md

@@ -305,18 +305,21 @@ This:
 ### What the output looks like
 
 ```
-Invoke the following list of Tasks in parallel:
+Invoke the following list of Tasks in parallel.
 
-Name: "python_review review of src/app.py"
-	Agent: Default
+name: "python_review review of src/app.py"
+	description: Review python_review
+	subagent_type: reviewer
 	prompt: "@.deepwork/tmp/review_instructions/7142141.md"
 
-Name: "python_review review of src/lib.py"
-	Agent: Default
+name: "python_review review of src/lib.py"
+	description: Review python_review
+	subagent_type: reviewer
 	prompt: "@.deepwork/tmp/review_instructions/6316224.md"
 
-Name: "db_migration_safety review of 2 files"
-	Agent: db-expert
+name: "db_migration_safety review of 2 files"
+	description: Review db_migration_safety
+	subagent_type: db-expert
 	prompt: "@.deepwork/tmp/review_instructions/3847291.md"
 ```
 
@@ -529,3 +532,9 @@ Patterns follow standard glob syntax, evaluated relative to the `.deepreview` fi
 | `config/*` | `config/settings.yaml` | `config/deep/nested.yaml` |
 | `**/Dockerfile` | `Dockerfile`, `services/api/Dockerfile` | `Dockerfile.dev` |
 | `CHANGELOG.md` | `CHANGELOG.md` | `docs/CHANGELOG.md` |
+
+## Contributor setup
+
+By default, `/review` dispatches each review task to the `reviewer` subagent shipped with the DeepWork Claude plugin (`plugins/claude/agents/reviewer.md`). If you are developing against this repo with only the dev MCP server (`uv run deepwork serve`) and no plugin installed, Claude Code cannot resolve `subagent_type: reviewer` and review dispatch will fail.
+
+To run reviews as a contributor, install the plugin alongside the dev server: `claude plugin marketplace add Unsupervisedcom/deepwork && claude plugin install deepwork@deepwork-plugins`. The plugin ships the reviewer agent file, and either MCP server prefix (`mcp__deepwork-dev__*` or `mcp__plugin_deepwork_deepwork__*`) will resolve the reviewer's tools.

doc/architecture.md

@@ -105,6 +105,8 @@ deepwork/                       # DeepWork tool repository
 │   ├── claude/                 # Claude Code plugin
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── README_REVIEWS.md   # Review system documentation
+│   │   ├── agents/              # Subagent definitions (e.g., reviewer.md)
+│   │   │   └── reviewer.md     # Default review subagent (Sonnet, minimal instructions)
 │   │   ├── example_reviews/    # Example review instruction files
 │   │   │   ├── prompt_best_practices.md
 │   │   │   └── suggest_new_reviews.md

plugins/claude/agents/reviewer.md

@@ -0,0 +1,29 @@
+---
+name: reviewer
+description: Minimal review subagent for DeepWork review tasks. Reads a supplied instruction file, performs the review against the criteria in that file, and reports results via the DeepWork MCP mark_review_as_passed tool. Use when dispatching parallel review tasks from .deepreview rules or workflow quality gates.
+model: sonnet
+color: cyan
+tools:
+  - Read
+  - Grep
+  - Glob
+  - Bash
+  - "mcp__plugin_deepwork_deepwork__*"
+  - "mcp__deepwork-dev__*"
+---
+
+You are a DeepWork review agent. Your only job is to execute one review task and report the result.
+
+**Process**
+
+1. Read the instruction file referenced in the user prompt (e.g. `@.deepwork/tmp/review_instructions/<id>.md`). The file contains the review criteria, the file(s) to review, and the expected verdict format.
+2. Perform the review exactly against the criteria in that file. Use `Read`, `Grep`, `Glob`, and `Bash` to examine only the files the instructions direct you to examine.
+3. When finished, call `mark_review_as_passed` with the structured verdict the instructions specify. Use whichever DeepWork MCP prefix is available in your environment (`mcp__plugin_deepwork_deepwork__mark_review_as_passed` in production; `mcp__deepwork-dev__mark_review_as_passed` in development).
+4. If the instructions ask you to call additional DeepWork MCP tools (e.g. `get_configured_reviews`, `get_named_schemas`), use whichever prefix is available in your environment.
+
+**Constraints**
+
+- Do not edit files. You are a read-only reviewer.
+- Do not explore beyond what the instructions direct. No scope creep.
+- Do not add commentary outside the structured verdict the instructions request.
+- If the instructions are ambiguous, apply them as literally as possible and note the ambiguity in the verdict rather than asking for clarification.

specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md

@@ -98,3 +98,12 @@ The Claude Code plugin is the primary distribution mechanism for DeepWork on the
 2. The skill MUST document how DeepWork Reviews work, including `.deepreview` config format, review strategies (`individual`, `matches_together`, `all_changed_files`), and how changed files are detected.
 3. The skill MUST explain how DeepSchemas automatically generate synthetic review rules.
 4. The skill MUST describe workflow quality gates and how `finished_step` triggers reviews on step outputs.
+
+### PLUG-REQ-001.14: Default Reviewer Subagent
+
+1. The plugin MUST ship a default reviewer subagent at `plugins/claude/agents/reviewer.md`.
+2. The agent's `model` frontmatter field MUST be set to `sonnet` to reduce per-review cost relative to the parent session's model.
+3. The agent's `tools` frontmatter field MUST include at minimum `Read`, `Grep`, `Glob`, and `Bash`, plus DeepWork MCP tools needed for review completion (`mark_review_as_passed`) in both the production (`mcp__plugin_deepwork_deepwork__*`) and development (`mcp__deepwork-dev__*`) MCP server prefixes.
+4. The agent body MUST instruct the subagent to read the instruction file from the user prompt, perform the review against the criteria in that file, and call `mark_review_as_passed` to report results.
+5. The agent body MUST instruct the subagent not to edit files and not to explore beyond what the review instructions direct.
+6. When the review formatter renders tasks with no per-rule agent persona specified (`agent_name` is `None`), it MUST default to `"reviewer"` as the `subagent_type` (see REVIEW-REQ-006.3.3c).

specs/deepwork/review/REVIEW-REQ-006-cli-review-command.md

@@ -32,7 +32,7 @@ The `deepwork review` CLI command orchestrates the full DeepWork Reviews pipelin
 3. For each review task, the output MUST include fields matching the Claude Code `Task` tool parameters:
    a. A `name` field formatted as `"{scope_prefix}{rule_name} review of {file_or_scope}"` — for `individual` strategy, `{file_or_scope}` is the single filename; for grouped strategies, it is a summary (e.g., `"3 files"`). When the rule comes from a `.deepreview` in a subdirectory, `{scope_prefix}` MUST be `"{parent_dir_name}/"` (e.g., `"my_job/"`); for root-level `.deepreview` files, `{scope_prefix}` MUST be empty.
    b. A `description` field with a short (3-5 word) summary for the task (e.g., `"Review {rule_name}"`). When the rule comes from a `.deepreview` in a subdirectory, the description MUST include the scope (e.g., `"Review my_job/{rule_name}"`).
-   c. A `subagent_type` field set to the agent persona name (from the rule's `agent.claude` value) or `"general-purpose"` if no persona is specified.
+   c. A `subagent_type` field set to the agent persona name (from the rule's `agent.claude` value) or `"reviewer"` if no persona is specified. `"reviewer"` refers to the default reviewer subagent shipped by the DeepWork Claude plugin (`plugins/claude/agents/reviewer.md`).
    d. A `prompt` field referencing the instruction file path relative to the project root, prefixed with `@` (e.g., `@.deepwork/tmp/review_instructions/7142141.md`).
 4. The instruction file paths MUST be relative to the project root.
 5. When running inside a git worktree, the formatter MUST resolve `@file` paths relative to the main working tree root (not the worktree root), because Claude Code expands `@file` references relative to the main repo root. The main repo root MUST be detected via `git rev-parse --path-format=absolute --git-common-dir`. If git is unavailable or the directory is not a worktree, the formatter MUST fall back to using the project root.

src/deepwork/review/formatter.py

@@ -106,7 +106,7 @@ def format_for_claude(
 
         name = _task_name(task)
         description = _task_description(task)
-        subagent_type = task.agent_name or "general-purpose"
+        subagent_type = task.agent_name or "reviewer"
 
         lines.append(f'name: "{name}"')
         lines.append(f"\tdescription: {description}")

tests/unit/review/test_formatter.py

@@ -70,23 +70,23 @@ def test_inline_content_task_name_says_inline_content(self, tmp_path: Path) -> N
         assert 'name: "string_rule review of inline content"' in result
         assert "0 files" not in result
 
-    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3b).
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3c).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     def test_default_subagent_type_when_no_agent(self, tmp_path: Path) -> None:
         task = _make_task(agent_name=None)
         file_path = tmp_path / "instructions.md"
         result = format_for_claude([(task, file_path)], tmp_path)
-        assert "subagent_type: general-purpose" in result
+        assert "subagent_type: reviewer" in result
 
-    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3b).
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3c).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     def test_custom_subagent_type(self, tmp_path: Path) -> None:
         task = _make_task(agent_name="security-expert")
         file_path = tmp_path / "instructions.md"
         result = format_for_claude([(task, file_path)], tmp_path)
         assert "subagent_type: security-expert" in result
 
-    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3c).
+    # THIS TEST VALIDATES A HARD REQUIREMENT (REVIEW-REQ-006.3.3b).
     # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
     def test_description_field_present(self, tmp_path: Path) -> None:
         task = _make_task(rule_name="py_review")