Add DeepWork Review GitHub Action

.github/workflows/example.yml

@@ -0,0 +1,38 @@
+name: DeepWork Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+# Prevent concurrent runs on the same PR
+concurrency:
+  group: deepwork-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  deepwork-review:
+    runs-on: ubuntu-latest
+    # Required permissions
+    permissions:
+      contents: write        # push auto-fix commits to the PR branch
+      pull-requests: write   # post inline PR review comments
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          # Fetch full history so DeepWork can diff against the base branch
+          fetch-depth: 0
+          # Use the merge ref so we operate on the PR's head commit
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run DeepWork Review
+        uses: Unsupervisedcom/deepwork-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # Optional overrides:
+          # model: claude-sonnet-4-5
+          # max_turns: '50'
+          # commit_message: 'chore: apply DeepWork review suggestions [skip ci]'

.gitignore

@@ -0,0 +1 @@
+scripts/__pycache__/

README.md

@@ -1,2 +1,89 @@
 # deepwork-action
-DeepWork GitHub Action
+
+A prebuilt GitHub Action that runs [Claude Code](https://docs.anthropic.com/en/docs/claude-code) on a Pull Request with the [DeepWork](https://github.com/Unsupervisedcom/deepwork) plugin installed, triggers the `/review` skill, auto-commits all review-driven improvements back to the PR branch, and posts inline PR review comments explaining each change.
+
+## How It Works
+
+1. **DeepWork review** — Claude Code runs the `/review` skill, which reads your `.deepreview` config files to discover review rules, diffs the PR branch, and dispatches parallel review agents scoped to exactly the right files.
+2. **Apply changes** — Claude applies every suggested improvement (bugs, style, performance, security, docs, refactoring) without asking for confirmation.
+3. **Auto-commit** — All file changes are committed back to the PR branch under the `deepwork-action[bot]` identity.
+4. **Inline PR comments** — A GitHub PR review is posted with one inline comment per changed file, describing what was changed and why, so your team can review each improvement.
+
+## Prerequisites
+
+1. **Anthropic API key** — add it as a repository secret named `ANTHROPIC_API_KEY`.
+2. **`.deepreview` configuration** — place one or more `.deepreview` files in your repository defining your review rules. See the [DeepWork Reviews documentation](https://github.com/Unsupervisedcom/deepwork/blob/main/README_REVIEWS.md) for details.
+
+## Usage
+
+Create a workflow file such as `.github/workflows/deepwork-review.yml`:
+
+```yaml
+name: DeepWork Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+concurrency:
+  group: deepwork-review-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  deepwork-review:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write       # push auto-fix commits to the PR branch
+      pull-requests: write  # post inline PR review comments
+
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.ref }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Run DeepWork Review
+        uses: Unsupervisedcom/deepwork-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `anthropic_api_key` | ✅ | — | Anthropic API key for Claude Code |
+| `github_token` | ✅ | — | GitHub token with `contents: write` and `pull-requests: write` |
+| `model` | ❌ | `claude-sonnet-4-5` | Claude model to use |
+| `max_turns` | ❌ | `50` | Maximum agentic turns for Claude Code |
+| `commit_message` | ❌ | `chore: apply DeepWork review suggestions [skip ci]` | Commit message for auto-committed changes |
+
+## What Gets Changed
+
+The action applies **all** suggestions from your `.deepreview` rules, including:
+
+- Bug fixes and null-safety checks
+- Style and formatting improvements
+- Performance optimisations
+- Security hardening
+- Documentation updates
+- Refactoring suggestions
+
+If no `.deepreview` rules are configured in the repository, the action exits cleanly without making any changes or commits.
+
+## Review Comments
+
+After pushing the auto-fix commit, the action posts a GitHub PR review with inline comments on each changed file. The comments appear in the **Files Changed** tab and describe what was changed and why, so your team can accept, request modifications, or revert individual changes as needed.
+
+## Security
+
+- The action runs Claude with `--dangerously-skip-permissions` in a sandboxed GitHub Actions runner. It has no access to secrets beyond what you explicitly provide.
+- Auto-fix commits are signed with the `deepwork-action[bot]` identity.
+- The `[skip ci]` suffix on the default commit message prevents the action from triggering itself recursively.
+
+## License
+
+See [LICENSE](LICENSE).

action.yml

@@ -0,0 +1,167 @@
+name: 'DeepWork Review Action'
+description: 'Run DeepWork reviews via Claude Code on a PR, auto-commit improvements, and add inline PR review comments'
+author: 'Unsupervisedcom'
+
+branding:
+  icon: 'check-circle'
+  color: 'blue'
+
+inputs:
+  anthropic_api_key:
+    description: 'Anthropic API key for Claude Code'
+    required: true
+  github_token:
+    description: 'GitHub token with write access to commit changes and post review comments'
+    required: true
+  model:
+    description: 'Claude model to use (e.g. claude-sonnet-4-5, claude-opus-4-5)'
+    required: false
+    default: 'claude-sonnet-4-5'
+  max_turns:
+    description: 'Maximum number of agentic turns for Claude Code'
+    required: false
+    default: '50'
+  commit_message:
+    description: 'Commit message for auto-committed review changes'
+    required: false
+    default: 'chore: apply DeepWork review suggestions [skip ci]'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install Claude Code CLI
+      shell: bash
+      run: |
+        # Install the latest Claude Code CLI.
+        # Minimum safe version is 2.1.53 (fixes all known CVEs as of this action's release).
+        npm install -g @anthropic-ai/claude-code
+        # Verify the installed version meets the minimum requirement.
+        INSTALLED=$(claude --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+        MAJOR=$(echo "$INSTALLED" | cut -d. -f1)
+        MINOR=$(echo "$INSTALLED" | cut -d. -f2)
+        PATCH=$(echo "$INSTALLED" | cut -d. -f3)
+        if [ "$MAJOR" -lt 2 ] || \
+           ([ "$MAJOR" -eq 2 ] && [ "$MINOR" -lt 1 ]) || \
+           ([ "$MAJOR" -eq 2 ] && [ "$MINOR" -eq 1 ] && [ "$PATCH" -lt 53 ]); then
+          echo "ERROR: claude-code $INSTALLED is below the minimum safe version 2.1.53" >&2
+          exit 1
+        fi
+        echo "claude-code $INSTALLED meets minimum version requirement."
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+      with:
+        version: 'latest'
+
+    - name: Clone deepwork Claude plugin
+      shell: bash
+      run: |
+        PLUGIN_DIR="/tmp/deepwork-plugin"
+        git clone --depth 1 --filter=blob:none --sparse \
+          https://github.com/Unsupervisedcom/deepwork.git \
+          "$PLUGIN_DIR"
+        cd "$PLUGIN_DIR"
+        git sparse-checkout set plugins/claude
+        echo "Plugin ready at $PLUGIN_DIR/plugins/claude"
+
+    - name: Fetch base branch for git diff
+      shell: bash
+      run: |
+        BASE_REF="${{ github.event.pull_request.base.ref }}"
+        if [ -n "$BASE_REF" ]; then
+          git fetch origin "$BASE_REF" --depth=1 || \
+            echo "Warning: could not fetch base branch '$BASE_REF'; diff detection may be incomplete"
+        fi
+
+    - name: Prepare MCP config
+      shell: bash
+      run: |
+        # Merge deepwork's MCP server into the project's .mcp.json (if any), or create one.
+        # We always restore the original file afterwards (see "Restore MCP config" step).
+
+        if [ -f .mcp.json ]; then
+          cp .mcp.json /tmp/deepwork-original-mcp.json
+        else
+          touch /tmp/deepwork-no-original-mcp  # flag: no original file existed
+        fi
+
+        python3 "${{ github.action_path }}/scripts/merge-mcp-config.py" .mcp.json
+
+    - name: Run DeepWork review with Claude Code
+      shell: bash
+      env:
+        ANTHROPIC_API_KEY: ${{ inputs.anthropic_api_key }}
+        GH_TOKEN: ${{ inputs.github_token }}
+      run: |
+        PLUGIN_DIR="/tmp/deepwork-plugin/plugins/claude"
+        PROMPT_FILE="${{ github.action_path }}/prompts/review.txt"
+
+        # Clean up any leftover changes file from a previous run.
+        rm -f /tmp/deepwork_changes.json
+
+        # Run Claude Code with the deepwork plugin and the review prompt.
+        #
+        # --plugin-dir                loads DeepWork skills, hooks, and MCP config
+        # --print                     non-interactive / CI mode
+        # --dangerously-skip-permissions  suppress all permission prompts
+        claude \
+          --print \
+          --dangerously-skip-permissions \
+          --model "${{ inputs.model }}" \
+          --max-turns "${{ inputs.max_turns }}" \
+          --plugin-dir "$PLUGIN_DIR" \
+          < "$PROMPT_FILE" || true
+
+    - name: Restore MCP config
+      if: always()
+      shell: bash
+      run: |
+        if [ -f /tmp/deepwork-original-mcp.json ]; then
+          cp /tmp/deepwork-original-mcp.json .mcp.json
+        elif [ -f /tmp/deepwork-no-original-mcp ]; then
+          rm -f .mcp.json
+        fi
+
+    - name: Commit and push changes
+      id: commit
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+      run: |
+        git config user.name "deepwork-action[bot]"
+        git config user.email "deepwork-action[bot]@users.noreply.github.com"
+
+        # Check for any modified, added, or deleted tracked files
+        if git diff --quiet && git diff --cached --quiet \
+            && [ -z "$(git ls-files --others --exclude-standard)" ]; then
+          echo "No changes to commit."
+          echo "changes_made=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        echo "changes_made=true" >> "$GITHUB_OUTPUT"
+
+        git add -A
+        git commit -m "${{ inputs.commit_message }}"
+
+        # Authenticate push via the provided token.
+        REPO="${{ github.repository }}"
+        git remote set-url origin \
+          "https://x-access-token:${GITHUB_TOKEN}@github.com/${REPO}.git"
+        git push
+
+    - name: Post inline PR review comments
+      if: steps.commit.outputs.changes_made == 'true' && github.event.pull_request.number != ''
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.github_token }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+        GITHUB_REPOSITORY: ${{ github.repository }}
+        GITHUB_BASE_REF: ${{ github.event.pull_request.base.ref }}
+      run: |
+        python3 "${{ github.action_path }}/scripts/post-review-comments.py"

prompts/review.txt

@@ -0,0 +1,38 @@
+/review
+
+You are running in a fully automated CI environment on a GitHub Pull Request.
+There is NO human watching this session. Follow these critical rules at all times:
+
+## Automation Rules (MANDATORY)
+
+1. **NEVER use AskUserQuestion** — you are in CI mode; make every decision autonomously.
+2. **Make ALL changes** suggested by the review findings — not just "obviously good" ones.
+   Apply every finding: bugs, style, performance, security, documentation, and refactoring.
+   When a finding offers multiple approaches, choose the best one yourself.
+3. **Iterate** — after making changes, re-run the review until it comes back clean.
+4. **If no `.deepreview` rules are configured** — output the message "No review rules configured."
+   and stop. Do not attempt to configure rules; that is the repository owner's responsibility.
+
+## Change Tracking (REQUIRED)
+
+For every file you modify, append an entry to `/tmp/deepwork_changes.json`.
+Create the file with `{"changes": []}` if it does not yet exist.
+
+Each entry must follow this exact JSON structure:
+
+```json
+{
+  "file": "relative/path/to/changed/file",
+  "line": <line_number_where_main_change_was_made>,
+  "description": "One-sentence description of what was changed",
+  "reason": "The review finding that prompted this change"
+}
+```
+
+Write the final file when all changes are complete and the review passes.
+
+## Important
+
+- You have full permission to edit, create, and delete files in this repository.
+- Do NOT commit changes yourself — the CI workflow handles git commit and push.
+- Do NOT push changes yourself — the CI workflow handles git commit and push.

scripts/merge-mcp-config.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python3
+"""
+Merge the deepwork MCP server entry into an existing .mcp.json file.
+
+Usage: python3 merge-mcp-config.py <path-to-mcp.json>
+
+Reads the JSON file, adds/replaces the 'deepwork' entry under 'mcpServers',
+and writes the result back to the same file.
+"""
+import json
+import sys
+from pathlib import Path
+
+mcp_path = Path(sys.argv[1]) if len(sys.argv) > 1 else Path(".mcp.json")
+
+existing: dict = {}
+if mcp_path.exists():
+    try:
+        existing = json.loads(mcp_path.read_text())
+    except json.JSONDecodeError:
+        existing = {}
+
+existing.setdefault("mcpServers", {})["deepwork"] = {
+    "command": "uvx",
+    "args": ["deepwork", "serve", "--platform", "claude"],
+}
+
+mcp_path.write_text(json.dumps(existing, indent=2) + "\n")
+print(f"Written {mcp_path}")