diff --git a/README_REVIEWS.md b/README_REVIEWS.md index 359fd1b1..03e2abcc 100644 --- a/README_REVIEWS.md +++ b/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. diff --git a/doc/architecture.md b/doc/architecture.md index 33eaadaf..75285e13 100644 --- a/doc/architecture.md +++ b/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 diff --git a/plugins/claude/agents/reviewer.md b/plugins/claude/agents/reviewer.md new file mode 100644 index 00000000..90e77fe4 --- /dev/null +++ b/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/.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. diff --git a/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md b/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md index 93ffc87e..8a045800 100644 --- a/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md +++ b/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). diff --git a/specs/deepwork/review/REVIEW-REQ-006-cli-review-command.md b/specs/deepwork/review/REVIEW-REQ-006-cli-review-command.md index 585dc613..721b9a57 100644 --- a/specs/deepwork/review/REVIEW-REQ-006-cli-review-command.md +++ b/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. diff --git a/src/deepwork/review/formatter.py b/src/deepwork/review/formatter.py index ce38a774..a7636734 100644 --- a/src/deepwork/review/formatter.py +++ b/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}") diff --git a/tests/unit/review/test_formatter.py b/tests/unit/review/test_formatter.py index 3d7232d9..0946237a 100644 --- a/tests/unit/review/test_formatter.py +++ b/tests/unit/review/test_formatter.py @@ -70,15 +70,15 @@ 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") @@ -86,7 +86,7 @@ def test_custom_subagent_type(self, tmp_path: Path) -> None: 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")