Skip to content

Commit f8d6442

Browse files
nhortonclaude
nhorton
and
claude
authored
Add DeepWork Reviews — automated code review system (#229)
* Add DeepWork Reviews — automated code review via .deepreview config files Implements a complete review system that lets users define `.deepreview` YAML config files throughout their project tree. When `deepwork review` runs, it discovers these configs, diffs the branch, matches changed files against rules, and generates parallel review task instructions for Claude Code. Key features: - Three review strategies: individual, matches_together, all_changed_files - Hierarchical config placement (like .gitignore) - Inline or file-referenced review instructions - Agent personas per platform - Policy traceability (each review links back to its source rule) - Explicit file list via --files or stdin pipe (skips git diff) - Two new plugin skills: `review` (run reviews) and `configure_reviews` Includes 7 REQ spec files, full implementation in src/deepwork/review/, CLI command, 122 unit tests, and README_REVIEWS.md usage documentation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Align review output with Task tool params and add python code review rule - Rename formatter output fields to match Claude Code Task tool parameters (Name→name, Agent→subagent_type, add description field) - Default subagent_type to "general-purpose" instead of "Default" - Add python_code_review rule referencing doc/code_review_standards.md - Update REQ-006, SKILL.md, and tests to match new format Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Improve requirements traceability, review skills, and test coverage - Add .deepreview config with requirements_traceability rule using requirements-reviewer agent - Move deepreview schema to src/deepwork/schemas/ to match REQ-001.7.1 - Fix REQ-004.9.1 function signature to match implementation - Add 13 tests for REQ-003 sub-requirements (changed file detection) - Add test for REQ-006.5.3 (write error exits with code 1) - Add full traceability comment blocks to ~90 tests - Update module docstrings with "validates REQ-NNN" in all review test files - Update requirements-reviewer agent: clarify directionality, make project-agnostic - Update review skill: per-finding questions with multiple fix approach options - Update configure_reviews skill: offer to run /review after configuration - Add review MCP tool and related server/doc changes Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * cleanup docs * Add .mcp.json cleanup to repair workflow errata step The repair workflow's errata step now removes legacy `deepwork serve` entries from the repo's .mcp.json file, since this is handled by the plugin system. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add repair hint to get_workflows job parse errors When a job fails to parse, the error message now suggests running `/deepwork:repair` so the agent knows how to resolve the issue. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add required description field to .deepreview rule schema Add a `description` field (string, max 256 chars) as a required property on each review rule. Update the JSON schema, config parser, dataclass, all .deepreview files, README_REVIEWS.md examples, and test fixtures. Also fix integration test skip condition for nested Claude sessions and simplify CLAUDE.md dev environment instructions to use uv directly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * rename tool * Add get_configured_reviews MCP tool and python_lint review rule Introduces a new `get_configured_reviews` tool that lists configured .deepreview rules with optional file-based filtering. Also adds a python_lint review rule, post-commit reminder hook, and updates specs and docs to reflect the description field requirement and new tool. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Update post-commit hook to more strongly offer review skill Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Apply review findings: fix egg-info bug, promote APIs, surface errors, add traceability - Fix *.egg-info glob pattern bug in discovery._SKIP_DIRS (set membership doesn't support globs; now uses endswith check) - Promote _match_rule and _format_source_location to public API in matcher.py - Surface discovery errors in mcp.py instead of silently discarding them - Remove duplicate tests in test_mcp.py that didn't test platform behavior - Add formal two-line traceability comments to all REQ-007/REQ-008 tests - Update review infrastructure: python_lint instructions, review skill, requirements_traceability rule, and post-commit hook wording - Apply ruff format and mypy type annotations across test files Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix import sorting and line formatting from ruff Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Replace nix with uv in CI and split validate into separate jobs Removes nix dependency from the validate workflow, using uv + setup-python directly (matching other workflows). Splits the single job into three parallel jobs (lint, typecheck, tests) so each shows as a separate check line on PRs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Move claude wrapper into nix flake, remove shell script The nix dev shell now wraps the claude binary with --plugin-dir flags automatically, using the real binary's store path to avoid circular PATH lookup. The standalone ./claude script is no longer needed. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * readme cleanup * Combine ruff and mypy into single Lint job and enable uv caching Merges the separate lint and typecheck CI jobs into one. Adds enable-cache: true to all setup-uv steps across all workflows and removes the redundant manual cache step in copilot-setup-steps. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 1457367 commit f8d6442

58 files changed

Lines changed: 4898 additions & 67 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/agents/requirements_reviewer.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ maxTurns: 30
1515

1616
# Requirements Reviewer Agent
1717

18-
You review the unsupervised-cli project to verify that its three-way traceability chain is maintained:
18+
You review the project to verify that its three-way traceability chain is maintained:
1919

2020
**Functionality → Requirements → Tests**
2121

@@ -52,10 +52,13 @@ For every piece of new or changed end-user functionality in the diff:
5252

5353
### 2. Test Coverage of Requirements
5454

55+
The direction of this check is FROM requirements TO tests. Every requirement must have a test, but not every test needs to reference a requirement — some tests are utility/edge-case tests that don't map to a specific requirement, and that's fine.
56+
5557
For every requirement (new or existing):
5658
- Verify there is at least one test that references the requirement ID
5759
- Check that the test actually validates the behavior described in the requirement
5860
- Flag any requirements that have no corresponding test
61+
- Do NOT flag tests that lack a requirement reference — only flag requirements that lack tests
5962

6063
### 3. Test Stability
6164

@@ -66,9 +69,12 @@ For any modified test files:
6669

6770
### 4. Traceability Completeness
6871

69-
- Every test class or test function that validates a requirement must have the traceability comment
72+
Only tests that DO validate a specific requirement need the traceability comment. Tests that are utility/edge-case tests without a requirement mapping do not need one — do not flag them.
73+
74+
- Every test that validates a requirement must have the traceability comment
7075
- The comment must reference the correct requirement ID
7176
- The comment must include the "MUST NOT MODIFY ... UNLESS THE REQUIREMENT CHANGES" warning
77+
- Do NOT flag tests that lack a requirement reference — only flag requirements whose tests are missing the traceability comment
7278

7379
## Output Format
7480

‎.deepreview‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
python_code_review:
2+
description: "Check Python files for code quality, style, and best practices."
3+
match:
4+
include:
5+
- "**/*.py"
6+
review:
7+
strategy: individual
8+
instructions:
9+
file: .deepwork/review/python_code_review.md
10+
11+
python_lint:
12+
description: "Run ruff (lint + format) and mypy on changed Python files."
13+
match:
14+
include:
15+
- "**/*.py"
16+
review:
17+
strategy: matches_together
18+
instructions:
19+
file: .deepwork/review/python_lint.md
20+
21+
requirements_traceability:
22+
description: "Verify requirements traceability between specs, code, and tests."
23+
match:
24+
include:
25+
- "**/*"
26+
review:
27+
strategy: all_changed_files
28+
agent:
29+
claude: requirements-reviewer
30+
instructions: |
31+
Review the changed files for requirements traceability.
32+
33+
This project keeps formal requirements in `specs/` using the naming pattern
34+
`REQ-NNN-<topic>.md` with individually numbered requirements (e.g. REQ-001.1).
35+
Tests live in `tests/` and reference requirement IDs via docstrings and
36+
traceability comments.
37+
38+
For this review:
39+
1. Check that any new or changed end-user functionality has a corresponding
40+
requirement in `specs/`.
41+
2. Check that every requirement touched by this change has at least one
42+
automated test referencing it in `tests/`.
43+
3. Flag any test modifications where the underlying requirement did not
44+
also change.
45+
4. Verify traceability comments are present, correctly reference
46+
requirement IDs, and use the standard two-line format:
47+
```
48+
# THIS TEST VALIDATES A HARD REQUIREMENT (REQ-xxx.x.x).
49+
# YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
50+
```
51+
Both lines are required. They must appear inside the method body
52+
(after `def`, before the docstring). If tests have REQ references
53+
only in docstrings but are missing the formal comment block, flag
54+
them. If the second line is missing, flag that too.
55+
56+
Produce a structured review with Coverage Gaps, Test Stability Violations,
57+
Traceability Issues, and a Summary with PASS/FAIL verdicts.

‎.deepwork/review/python_code_review.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Review this Python file according to the project's code review standards defined in @doc/code_review_standards.md.
2+
3+
Apply all review categories (General Issues, DRY, Naming Clarity, Test Coverage, Test Quality) and use the severity levels defined in that document.
4+
5+
For each issue found, report:
6+
1. File and line number
7+
2. Severity level (Critical / High / Medium / Low)
8+
3. Category
9+
4. Description of the issue
10+
5. Suggested fix

‎.deepwork/review/python_lint.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
Run ruff and mypy on the changed Python files listed below. Fix what you can automatically, then report only issues that remain unresolved.
2+
3+
## Steps
4+
5+
1. Run `uv run ruff check --fix` on each file listed under "Files to Review".
6+
2. Run `uv run ruff format` on each file listed under "Files to Review".
7+
3. Run `uv run mypy` on each file listed under "Files to Review".
8+
4. Fix any remaining issues you can resolve (e.g., adding type annotations, renaming ambiguous variables).
9+
5. Re-run all three checks to confirm your fixes are clean.
10+
11+
## Output Format
12+
13+
Only report issues that remain **after** your fixes. Do not report issues you already resolved.
14+
15+
- PASS: All checks pass (no remaining issues).
16+
- FAIL: Unfixable lint errors or type errors remain. List each with file, line, and details.

‎.github/workflows/claude-code-test.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ jobs:
4545
uses: astral-sh/setup-uv@v4
4646
with:
4747
version: "latest"
48+
enable-cache: true
4849

4950
- name: Set up Python
5051
if: github.event_name != 'pull_request'
@@ -163,6 +164,7 @@ jobs:
163164
uses: astral-sh/setup-uv@v4
164165
with:
165166
version: "latest"
167+
enable-cache: true
166168

167169
- name: Set up Python
168170
if: steps.check-key.outputs.has_key == 'true'

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 1 addition & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,22 +27,13 @@ jobs:
2727
uses: astral-sh/setup-uv@v4
2828
with:
2929
version: "latest"
30+
enable-cache: true
3031

3132
- name: Set up Python
3233
uses: actions/setup-python@v5
3334
with:
3435
python-version: "3.11"
3536

36-
- name: Cache UV dependencies
37-
uses: actions/cache@v4
38-
with:
39-
path: |
40-
~/.cache/uv
41-
.venv
42-
key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
43-
restore-keys: |
44-
${{ runner.os }}-uv-
45-
4637
- name: Install dependencies
4738
run: uv sync --extra dev
4839

‎.github/workflows/prepare-release.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ jobs:
115115
uses: astral-sh/setup-uv@v4
116116
with:
117117
version: "latest"
118+
enable-cache: true
118119

119120
- name: Set up Python
120121
uses: actions/setup-python@v5

‎.github/workflows/release.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ jobs:
1818
uses: astral-sh/setup-uv@v4
1919
with:
2020
version: "latest"
21+
enable-cache: true
2122

2223
- name: Set up Python
2324
uses: actions/setup-python@v5

‎.github/workflows/validate.yml‎

Lines changed: 41 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -12,25 +12,54 @@ permissions:
1212
contents: read
1313

1414
jobs:
15-
tests:
15+
lint:
16+
name: Lint
1617
runs-on: ubuntu-latest
17-
1818
steps:
1919
- uses: actions/checkout@v4
2020

21-
- name: Install Nix
22-
uses: cachix/install-nix-action@v31
21+
- name: Install uv
22+
uses: astral-sh/setup-uv@v4
23+
with:
24+
version: "latest"
25+
enable-cache: true
2326

24-
- name: Setup Nix development environment
25-
uses: nicknovitski/nix-develop@v1
27+
- name: Set up Python
28+
uses: actions/setup-python@v5
29+
with:
30+
python-version: "3.11"
2631

27-
- name: Install Python dependencies
32+
- name: Install dependencies
2833
run: uv sync --extra dev
2934

30-
- name: Check formatting (ruff)
31-
run: |
32-
ruff format --check src/ tests/
33-
ruff check src/ tests/
35+
- name: Check formatting
36+
run: uv run ruff format --check src/ tests/
37+
38+
- name: Check linting
39+
run: uv run ruff check src/ tests/
40+
41+
- name: Run type checking
42+
run: uv run mypy src/
43+
44+
test:
45+
name: Tests (pytest)
46+
runs-on: ubuntu-latest
47+
steps:
48+
- uses: actions/checkout@v4
49+
50+
- name: Install uv
51+
uses: astral-sh/setup-uv@v4
52+
with:
53+
version: "latest"
54+
enable-cache: true
55+
56+
- name: Set up Python
57+
uses: actions/setup-python@v5
58+
with:
59+
python-version: "3.11"
60+
61+
- name: Install dependencies
62+
run: uv sync --extra dev
3463

3564
- name: Run tests
36-
run: pytest tests/ -v
65+
run: uv run pytest tests/ -v

‎.mcp.json‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

0 commit comments

Comments
 (0)