Add DeepWork Reviews — automated code review system

.claude/agents/requirements_reviewer.md

@@ -15,7 +15,7 @@ maxTurns: 30
 
 # Requirements Reviewer Agent
 
-You review the unsupervised-cli project to verify that its three-way traceability chain is maintained:
+You review the project to verify that its three-way traceability chain is maintained:
 
 **Functionality → Requirements → Tests**
 
@@ -52,10 +52,13 @@ For every piece of new or changed end-user functionality in the diff:
 
 ### 2. Test Coverage of Requirements
 
+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.
+
 For every requirement (new or existing):
 - Verify there is at least one test that references the requirement ID
 - Check that the test actually validates the behavior described in the requirement
 - Flag any requirements that have no corresponding test
+- Do NOT flag tests that lack a requirement reference — only flag requirements that lack tests
 
 ### 3. Test Stability
 
@@ -66,9 +69,12 @@ For any modified test files:
 
 ### 4. Traceability Completeness
 
-- Every test class or test function that validates a requirement must have the traceability comment
+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.
+
+- Every test that validates a requirement must have the traceability comment
 - The comment must reference the correct requirement ID
 - The comment must include the "MUST NOT MODIFY ... UNLESS THE REQUIREMENT CHANGES" warning
+- Do NOT flag tests that lack a requirement reference — only flag requirements whose tests are missing the traceability comment
 
 ## Output Format
 

.deepreview

@@ -0,0 +1,57 @@
+python_code_review:
+  description: "Check Python files for code quality, style, and best practices."
+  match:
+    include:
+      - "**/*.py"
+  review:
+    strategy: individual
+    instructions:
+      file: .deepwork/review/python_code_review.md
+
+python_lint:
+  description: "Run ruff (lint + format) and mypy on changed Python files."
+  match:
+    include:
+      - "**/*.py"
+  review:
+    strategy: matches_together
+    instructions:
+      file: .deepwork/review/python_lint.md
+
+requirements_traceability:
+  description: "Verify requirements traceability between specs, code, and tests."
+  match:
+    include:
+      - "**/*"
+  review:
+    strategy: all_changed_files
+    agent:
+      claude: requirements-reviewer
+    instructions: |
+      Review the changed files for requirements traceability.
+
+      This project keeps formal requirements in `specs/` using the naming pattern
+      `REQ-NNN-<topic>.md` with individually numbered requirements (e.g. REQ-001.1).
+      Tests live in `tests/` and reference requirement IDs via docstrings and
+      traceability comments.
+
+      For this review:
+      1. Check that any new or changed end-user functionality has a corresponding
+         requirement in `specs/`.
+      2. Check that every requirement touched by this change has at least one
+         automated test referencing it in `tests/`.
+      3. Flag any test modifications where the underlying requirement did not
+         also change.
+      4. Verify traceability comments are present, correctly reference
+         requirement IDs, and use the standard two-line format:
+         ```
+         # THIS TEST VALIDATES A HARD REQUIREMENT (REQ-xxx.x.x).
+         # YOU MUST NOT MODIFY THIS TEST UNLESS THE REQUIREMENT CHANGES
+         ```
+         Both lines are required. They must appear inside the method body
+         (after `def`, before the docstring). If tests have REQ references
+         only in docstrings but are missing the formal comment block, flag
+         them. If the second line is missing, flag that too.
+
+      Produce a structured review with Coverage Gaps, Test Stability Violations,
+      Traceability Issues, and a Summary with PASS/FAIL verdicts.

.deepwork/review/python_code_review.md

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

.deepwork/review/python_lint.md

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

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

@@ -45,6 +45,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
+          enable-cache: true
 
       - name: Set up Python
         if: github.event_name != 'pull_request'
@@ -163,6 +164,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
+          enable-cache: true
 
       - name: Set up Python
         if: steps.check-key.outputs.has_key == 'true'

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

@@ -27,22 +27,13 @@ jobs:
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
+          enable-cache: true
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
 
-      - name: Cache UV dependencies
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache/uv
-            .venv
-          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-
-
       - name: Install dependencies
         run: uv sync --extra dev
 

.github/workflows/prepare-release.yml

@@ -115,6 +115,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
+          enable-cache: true
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/release.yml

@@ -18,6 +18,7 @@ jobs:
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
+          enable-cache: true
 
       - name: Set up Python
         uses: actions/setup-python@v5

.github/workflows/validate.yml

@@ -12,25 +12,54 @@ permissions:
   contents: read
 
 jobs:
-  tests:
+  lint:
+    name: Lint
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Nix
-        uses: cachix/install-nix-action@v31
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
 
-      - name: Setup Nix development environment
-        uses: nicknovitski/nix-develop@v1
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
 
-      - name: Install Python dependencies
+      - name: Install dependencies
         run: uv sync --extra dev
 
-      - name: Check formatting (ruff)
-        run: |
-          ruff format --check src/ tests/
-          ruff check src/ tests/
+      - name: Check formatting
+        run: uv run ruff format --check src/ tests/
+
+      - name: Check linting
+        run: uv run ruff check src/ tests/
+
+      - name: Run type checking
+        run: uv run mypy src/
+
+  test:
+    name: Tests (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+          enable-cache: true
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: uv sync --extra dev
 
       - name: Run tests
-        run: pytest tests/ -v
+        run: uv run pytest tests/ -v

README.md

@@ -128,6 +128,8 @@ Claude will follow the workflow step by step.
 
 **4. All work happens on Git branches** — Every change can be version-controlled and tracked. You can roll-back to prior versions of the skill or keep skills in-sync and up-to-date across your team.
 
+**5. Automated change review** — Define `.deepreview` config files to set up review rules (patterns, strategies, instructions). Run `deepwork review --instructions-for claude` to generate parallel review tasks for your changed files. Works wonderfully for code reviews, but can review non-code files as well.
+
 ---
 
 ## Supported Platforms