claude-dev-env 8.63.0 → 8.65.0

package/.agents/skills/mod-playbooks/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: mod-playbooks
+description: >-
+  Map of playbooks for driving a Claude Code mod (plugin) and seeing its screen: press keys, open menus and drawers, hover a reply to show its action row, click a dropdown, type in a field, fire a toast or a question card, and capture each screen as text and PNG. Use when an agent must test a mod, check a fix by looking at it, or show a mod to the operator on their own desktop.
+---
+
+# Mod playbooks
+
+## Principle
+
+An agent proves a mod works by driving it and reading the screen. It needs no person for that. A
+cloud session runs Claude Code in a pseudo-terminal, plays the steps, and reads each capture. The
+operator's desktop comes last, when a person wants to look.
+
+## Pick the route
+
+| Goal | Route | Reference |
+| --- | --- | --- |
+| Test a mod, or check a fix, with no person | Drive it in a pseudo-terminal and read the captures | [cloud-drive.md](references/cloud-drive.md) |
+| Let the operator watch the mod on their own screen | Open a desktop window from a Remote Control session | [desktop-window.md](references/desktop-window.md) |
+| Prove what the operator's window shows | Capture that window to a PNG | [desktop-capture.md](references/desktop-capture.md) |
+
+When the mod's repository ships a driver and playbooks, use them first. Look for a `drive.mjs` beside
+a `playbooks/` folder and a playbook guide in its docs. Read the guide, run the matching playbook, and
+add a playbook for any new screen you test.
+
+## Playbook map
+
+Each row is one thing an agent does to a mod, and the input that does it. The bytes are in
+[cloud-drive.md](references/cloud-drive.md).
+
+| Do this | Input | Check on screen |
+| --- | --- | --- |
+| Send a prompt | Type the text, then Enter | The scripted reply |
+| Open a slash-command menu or pane | Type the command, then Enter | The pane's title |
+| Open a pane from a footer pill | Click the pill's label | The pane's title |
+| Move between buttons in a pane | Tab forward, Shift+Tab back, Enter to press | The focused button |
+| Toggle a control | Click its label | The control's new state |
+| Close a pane | Escape | The prompt again |
+| Show a reply's action row | Hover the reply text; the row draws only under the pointer | The action labels |
+| Pick from a dropdown | Click the action, click the choice, click the confirm button | The confirm line |
+| Type in a text field | Click the field label, type, then Enter | The saved text |
+| Fire a toast | Script a tool turn the mod watches, and allow that tool | The toast's words, top right |
+| Raise a question card | Script a question tool turn, then click an option | The answered line |
+
+## Self-resolve loop
+
+1. Change the mod.
+2. Run the playbook for the screen you changed.
+3. Read the `.txt` capture for words, and open the `.png` for color and layout.
+4. On a failed step, read `failure.png`, fix the cause, and run again.
+5. Keep the passing captures as the proof, then show the operator if they asked to see it.
+
+## Limits
+
+- The cloud route proves the mod's screens. It runs a mock model, so it proves nothing about model output.
+- Drive input with the mod repository's driver, in the cloud or on the operator's PC. The desktop window is for looking only.
+- A screen that needs the operator's account, files or network stays on the desktop route.

package/.agents/skills/mod-playbooks/references/cloud-drive.md

@@ -0,0 +1,47 @@
+# Drive a mod in a pseudo-terminal
+
+A cloud session can run Claude Code with a mod loaded, press keys, click, hover, and capture the screen,
+with no PC and no person. Use the mod repository's own driver when it ships one. Build on the same parts
+when it does not.
+
+## The parts
+
+| Part | Job |
+| --- | --- |
+| `node-pty` | Runs `claude --plugin-dir <mod>` in a pseudo-terminal. |
+| `@xterm/headless` | Mirrors the output into a cell buffer, so the screen reads as text with colors. |
+| A local mock of the Messages API | Scripts each model turn, so the model calls the tool that fires the mod. Point `ANTHROPIC_BASE_URL` at it. |
+| A throwaway home and config folder | Seeds onboarding, API key approval and folder trust, so the first screen is the prompt. |
+| A renderer | Paints the cells to HTML and screenshots it with Playwright Chromium, so the capture is a PNG. |
+
+## Input bytes
+
+| Action | Bytes written to the terminal |
+| --- | --- |
+| Enter | `\r` |
+| Tab, Shift+Tab | `\t`, `\x1b[Z` |
+| Escape | `\x1b` |
+| Arrow up, down, right, left | `\x1b[A`, `\x1b[B`, `\x1b[C`, `\x1b[D` |
+| Clear the prompt line | `\x15` |
+| Left click at column `c`, row `r` (1-based) | `\x1b[<0;c;rM` then `\x1b[<0;c;rm` |
+| Hover at column `c`, row `r` | `\x1b[<35;c;rM` |
+
+Find `c` and `r` by searching the cell buffer for the text to point at. Search from the bottom row up,
+so a click lands on the newest copy of a label. Skip zero-width cells when you join a row, or wide
+characters shift every column after them.
+
+## The loop
+
+1. Write the steps: the scripted turns, then each key, click or hover, the text to wait for, and a capture.
+2. Run them. Wait for each step's text, then for the screen to stop changing, before the next step.
+3. Read the text capture for words, and open the PNG for color and layout.
+4. Fix the mod, run again, and keep the passing captures as the proof.
+
+## Gotchas
+
+- A tool the scripted turn calls needs `--allowedTools <tool>`, or a permission prompt stops the run.
+- Check the request body for your tool id, so the second request ends the turn with text.
+- A mod can refuse to draw a pane below a minimum width. Run at 180 columns unless the steps need less.
+- A toast draws in the top-right corner, over the header rows.
+- A PNG renderer can paint a wide emoji over the next cell. The text capture holds the characters as drawn.
+- A step that runs a script from the project folder fails in the sandbox, because that folder is empty.

package/.agents/skills/mod-playbooks/references/desktop-capture.md

@@ -0,0 +1,41 @@
+# Capture a desktop window
+
+Run this on the operator's PC after the mod fires. It asks the window to paint itself into a bitmap
+with `PrintWindow`, so another window on top does not spoil the image. Open the demo with
+`wt.exe -w new` and `--suppressApplicationTitle`, so its window keeps the demo title and the block
+below can find it by that title.
+
+```powershell
+Add-Type -AssemblyName System.Drawing
+Add-Type @"
+using System; using System.Runtime.InteropServices;
+public struct RECT { public int Left, Top, Right, Bottom; }
+public static class W {
+  [DllImport("user32.dll")] public static extern bool SetProcessDPIAware();
+  [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] public static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint flags);
+}
+"@
+[W]::SetProcessDPIAware() | Out-Null
+$window = Get-Process WindowsTerminal | Where-Object MainWindowTitle -like '*Mod demo*' | Select-Object -First 1
+$rect = New-Object RECT
+[W]::GetWindowRect($window.MainWindowHandle, [ref]$rect) | Out-Null
+$bitmap = New-Object System.Drawing.Bitmap ($rect.Right - $rect.Left), ($rect.Bottom - $rect.Top)
+$graphics = [System.Drawing.Graphics]::FromImage($bitmap)
+$hdc = $graphics.GetHdc()
+[W]::PrintWindow($window.MainWindowHandle, $hdc, 2) | Out-Null
+$graphics.ReleaseHdc($hdc)
+$bitmap.Save((Join-Path $env:TEMP 'mod-demo.png'))
+```
+
+Report the path and size, and say whether the image shows color and the mod's output. The PNG stays on
+the PC; a cloud session that needs to see it stages the file through the device folder tools, or has
+the PC session post it. A toast fades, so capture while it shows, or capture twice.
+
+## What went wrong before
+
+| Capture | Result |
+| --- | --- |
+| `CopyFromScreen` on the window rectangle, demo opened with `new-tab` | 1752 x 936 in color, but it showed the active tab and missed the toast. |
+| `CopyFromScreen` without `SetProcessDPIAware` | The image held the wrong region, with other windows in it. |
+| `SetProcessDPIAware`, then `PrintWindow` with flag 2 (`PW_RENDERFULLCONTENT`) | 2520 x 936 in full color, as reported by the PC session. |

package/.agents/skills/mod-playbooks/references/desktop-window.md

@@ -0,0 +1,79 @@
+# Open a mod on the operator's desktop
+
+A toast, pane or status line shows only in the Claude Code window that loads the mod. A Remote Control
+session has no window the operator can see. So the session opens a new desktop window that loads the
+mod, and the operator only looks at it.
+
+## Gotchas
+
+- A mod loaded inside the Remote Control session fires its toast there. The operator sees nothing.
+- `/plugin install` plus hot reload asks the operator to click "Enable for this session". `--plugin-dir` on a new window skips that prompt.
+- A child window inherits `NO_COLOR=1` and `CLAUDE_CODE_CHILD_SESSION=1` from the Remote Control process. The window then runs black and white. Remove both variables in the child before `claude` starts.
+- `Start-Process pwsh` opens the old console host. Launch through `wt.exe` to get Windows Terminal.
+- `wt.exe new-tab` lands in an existing Windows Terminal window. A screen capture then shows whichever tab is active. Use `wt.exe -w new` for a window of its own.
+- `wt.exe` is an app execution alias. Call it by its full path under `%LOCALAPPDATA%\Microsoft\WindowsApps`.
+- When the operator already has the same plugin installed, both copies load. A `--settings` file with `{"enabledPlugins":{"<plugin>@<marketplace>":false}}` turned off the installed copy for that one session.
+- A shell or program can rename the tab, and the window title follows it. Pass `--suppressApplicationTitle` so the capture can find the window by its demo title.
+
+## The auto mode safety check
+
+The Remote Control session runs in auto mode, and its classifier reads the operator's message that
+started the session. Two launches with the same commands went two ways:
+
+| Seed message | Result |
+| --- | --- |
+| The operator asked to see the mod run: "can i see it in action? build the mod and show me" | The window opened. |
+| The operator described a design change and asked for no run | The first step, writing the launcher script, was refused: `Permission for this action was denied by the Claude Code auto mode classifier. Reason: [Auto-Mode Bypass].` |
+
+The likely rule, inferred from these two cases: start the session on the operator's own message that asks
+to see or run the mod, and quote that ask in the instructions. When no such message exists, ask the
+operator in one line whether to open the window, and start the session on the answer. A refused
+step is final for that session; report the refusal text and stop.
+
+## Steps
+
+1. Start a Remote Control session, on the operator's message that asks to see the mod, in a folder on
+   the operator's PC that is already approved.
+2. Clone the mod's branch to a fresh temporary folder:
+
+   ```powershell
+   $dir = Join-Path $env:TEMP ('mod-demo-' + (Get-Date -Format 'HHmmss'))
+   git clone -q --depth 1 -b <branch> <repo-url> $dir
+   ```
+
+3. Write a launcher script that clears the inherited variables and starts Claude Code with the mod:
+
+   ```powershell
+   $script = Join-Path $env:TEMP 'mod-demo.ps1'
+   @"
+   Remove-Item env:NO_COLOR, env:CLAUDE_CODE_CHILD_SESSION -ErrorAction SilentlyContinue
+   Set-Location `$env:USERPROFILE
+   claude --plugin-dir '$dir\plugins\<mod>' '<one harmless prompt that fires the mod>'
+   "@ | Set-Content -Encoding utf8 $script
+   ```
+
+4. Open it in its own Windows Terminal window with PowerShell 7:
+
+   ```powershell
+   $wt = Join-Path $env:LOCALAPPDATA 'Microsoft\WindowsApps\wt.exe'
+   Start-Process $wt -ArgumentList "-w new new-tab --title `"Mod demo`" --suppressApplicationTitle pwsh -NoExit -File `"$script`""
+   ```
+
+5. Capture the window with [desktop-capture.md](desktop-capture.md) and check the PNG yourself.
+6. Tell the operator the window is open and what to look at. Hand over a pasteable command only when
+   the launch failed, and say why it failed.
+
+## Input on the operator's PC
+
+To click, hover or type into a mod on the operator's PC, run the mod repository's driver there from the
+Remote Control session, for example `node tools/visual-test/drive.mjs <playbook> <capture-folder>`.
+The driver owns its pseudo-terminal, so no input goes to a desktop window, and the auto mode check has
+nothing to refuse. One PC run of the drawer playbook passed with no refusal, where a session that sent
+operating-system keystrokes to a demo window was refused. Post the driver's PNG captures.
+Never send operating-system keystrokes or clicks to the demo window.
+
+## Verification
+
+- The operator sees the window without any click.
+- The window shows color and runs in Windows Terminal with PowerShell 7.
+- The mod loads with no failure line, and its toast or pane appears.

package/.agents/skills/search-before-acting/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: search-before-acting
+description: >-
+  Search for what already does an ask before logging, planning, delegating,
+  or building it, then report what exists in four points and wait for the
+  user. Use when a user asks for new or changed behavior, a tool, a check,
+  a workflow, a report, a tracker entry, or a plan, and before writing a
+  brief for a worker.
+---
+
+# Search before acting
+
+The user should hear about work that already does their ask before anyone duplicates it. Search first, report what you find, and let the user decide what to add.
+
+## Steps
+
+1. Restate the ask as the outcome the user wants, in their words.
+2. Search every place in [`references/search-places.md`](references/search-places.md) that this session can reach. Note each place you could not reach.
+3. Sort each hit as full, partial, or related. A hit is full when it already produces the outcome from step 1.
+4. When any hit is full or partial, stop. Send the four-point report from [`references/report-shape.md`](references/report-shape.md) and wait for the user. When a hit is full, tell the user they already have it.
+5. When nothing is found, say where you looked in one line, then continue with the playbook below.
+
+## Playbooks
+
+Open the playbook that matches the next move.
+
+| Next move | Playbook |
+|---|---|
+| Build or change code, a hook, a skill, a rule, a workflow, or config | [`playbooks/build.md`](playbooks/build.md) |
+| Log the ask in a tracker, or write a plan for it | [`playbooks/plan-or-log.md`](playbooks/plan-or-log.md) |
+| Hand the ask to a worker, a thread, or another session | [`playbooks/delegate.md`](playbooks/delegate.md) |
+
+## Layout
+
+| File | What it holds |
+|---|---|
+| `SKILL.md` | The steps and the playbook index |
+| `references/search-places.md` | Where to search, with the query to run in each place |
+| `references/report-shape.md` | The four-point report and the "you already have it" answer |
+| `playbooks/build.md` | The search and report before a build, and the pull request section |
+| `playbooks/plan-or-log.md` | The search and report before a tracker entry or plan |
+| `playbooks/delegate.md` | The search before a brief, and what the brief carries |

package/.agents/skills/search-before-acting/playbooks/build.md

@@ -0,0 +1,18 @@
+# Build
+
+Use this playbook before you build or change code, a hook, a skill, a rule, a workflow, or config for an ask.
+
+1. Run the skill steps. Search the places in [`../references/search-places.md`](../references/search-places.md), with production config and launcher options first when the ask names a running system.
+2. When a hit is full or partial, send the [report](../references/report-shape.md) and wait for the user's answer.
+3. When the user says go, build only the missing part from point 3 of the report. Extend the existing piece where it lives. Start a new piece only when the existing one cannot hold the addition, and say why in the pull request.
+4. When nothing exists, follow `prefer-existing-tools.md` to check open-source options, then build.
+5. Add an "Existing work" section to the pull request body. List each hit with its link or `file:line` and what the pull request adds on top of it. When nothing was found, say so and name the places searched. The pull request gate denies a body without this section.
+
+Example section:
+
+```markdown
+## Existing work
+
+- `scripts/run_batch.py:40` already runs jobs in parallel with `--workers`. This pull request adds a per-job timeout on top of it.
+- Searched open and merged pull requests for "timeout" and "workers"; none add a timeout.
+```

package/.agents/skills/search-before-acting/playbooks/delegate.md

@@ -0,0 +1,9 @@
+# Delegate
+
+Use this playbook before you hand an ask to a worker, a thread, or another session.
+
+1. Run the skill steps yourself before you write the brief. The worker starts from your search.
+2. When a hit is full or partial, send the user the [report](../references/report-shape.md) and wait. Delegate only after the user says go.
+3. Put the search result in the brief. Name each existing piece with its link or `file:line`, what it covers, and the missing part the worker builds.
+4. When nothing exists, put the places searched in the brief, so the worker skips them and searches what you could not reach.
+5. Ask the worker to report any existing piece it finds that the brief missed, and to stop on it before it builds.

package/.agents/skills/search-before-acting/playbooks/plan-or-log.md

@@ -0,0 +1,9 @@
+# Plan or log
+
+Use this playbook before you add an ask to a tracker, open an issue or card for it, or write a plan for it.
+
+1. Run the skill steps. Search open and closed tracker entries for the ask first, then the rest of [`../references/search-places.md`](../references/search-places.md).
+2. When a tracker entry already names the ask, update that entry and link it. Skip the new entry.
+3. When code, config, or a merged pull request already does the ask in full or in part, send the [report](../references/report-shape.md) and wait for the user before you log or plan.
+4. When the user says go, log or plan only the missing part. Link each existing piece in the entry or plan, so the reader starts from what is live.
+5. When nothing exists, write the entry or plan with one line that names the places searched.

package/.agents/skills/search-before-acting/references/report-shape.md

@@ -0,0 +1,14 @@
+# Report shape
+
+Send this report when the search finds something that does the ask in full or in part. Send it before any log entry, plan, brief, or edit, and wait for the user.
+
+1. **What exists and where.** Each hit with a link or `file:line`, and whether it is live.
+2. **What it covers of the ask.** The parts of the outcome it already produces.
+3. **What is missing.** The parts of the outcome nothing produces yet.
+4. **What the addition would add.** What the new work gives on top of what exists, and the smallest change that closes the gap.
+
+When nothing is missing, the report is one line: the user already has it, with the link and how to use it.
+
+When a place in [`search-places.md`](search-places.md) was out of reach, add one line naming it and the check that would reach it.
+
+Keep the report as short as the user's channel asks for. When the channel limits length, put the four points in a linked file and send a short message that says what exists, what is missing, and what the user decides.

package/.agents/skills/search-before-acting/references/search-places.md

@@ -0,0 +1,26 @@
+# Search places
+
+Search each place this session can reach. Start from the outcome words in the ask and from the names of the systems it touches. Try two or three phrasings, since an existing feature often uses different words than the ask, such as "workers" for "parallel" or "queue" for "batch".
+
+| Place | What to run |
+|---|---|
+| Repository code | `rg -i "<outcome words>"` across each repository the work touches, and a search for the system's entry points and their flags, such as `--help` output and argument parsers |
+| Open pull requests | `gh pr list --state open --search "<words>"`, or the GitHub search tool with `is:pr is:open` |
+| Merged pull requests | `gh pr list --state merged --search "<words>"`, and `git log --oneline -i --grep "<words>"` on the default branch |
+| Hooks | the hook registry, such as `hooks.json` or `settings.json`, and the hook directories, for a gate or reminder that already does the step |
+| Rules and instructions | `rules/`, `AGENTS.md`, `CLAUDE.md`, project instructions, and memory notes |
+| Skills and commands | the installed skills list, `skills/`, `.agents/skills/`, and `commands/` |
+| Workflows and schedules | `.github/workflows/`, scheduled routines, cron entries, and task schedulers |
+| Trackers | open and closed issues, project boards, and task cards that name the ask |
+| Production config | config files, environment settings, feature flags, and launcher options that the running system reads, including values that turn on a mode the ask describes |
+| Run logs and dashboards | recent run output that shows the behavior already happening |
+
+## What to record for each hit
+
+- The place and a link or `file:line`.
+- One sentence on what it does now.
+- Whether it is live: merged and running, merged and unused, or still open.
+
+## When a place is out of reach
+
+Name the place and the check that would reach it, such as "the production config on the build machine, read through a remote session". The report states the gap. The user may know the answer at once.

package/bin/ever-shipped-skills.mjs

@@ -95,9 +95,11 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'reviewer-gates',
     'reviews',
     'run-claude-dev-env',
+    'search-before-acting',
     'second-account-workers',
     'session-continuity',
     'session-log',
+    'mod-playbooks',
     'session-tidy',
     'pr-shared-extraction',
     'show',

package/bin/ever-shipped-skills.test.mjs

@@ -45,6 +45,10 @@ test('EVER_SHIPPED_SKILL_NAMES includes the correction skill', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('correction'), true);
 });
 
+test('EVER_SHIPPED_SKILL_NAMES includes the search before acting skill', () => {
+    assert.equal(EVER_SHIPPED_SKILL_NAMES.has('search-before-acting'), true);
+});
+
 test('EVER_SHIPPED_SKILL_NAMES includes the windows scheduled task skill', () => {
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('windows-scheduled-task'), true);
 });

package/docs/rule-guides/explore-thoroughly.md

@@ -6,6 +6,16 @@ Source: [Anthropic - Overthinking and Excessive Thoroughness](https://platform.c
 
 Note: This deliberately chooses exploration depth over the "commit and execute quickly" pattern from the same source. Thorough upfront exploration is preferred for the intended workflow.
 
+## Search for existing work first
+
+Before you log, plan, delegate, or build an ask, search for what already does it in full or in part. An ask is any request for new or changed behavior, a tool, a check, a workflow, a report, a tracker entry, or a plan. The `search-before-acting` skill holds the search places, the four-point report, and a playbook for each next move.
+
+When the search finds something, stop before you act and report what exists and where, what it covers of the ask, what is missing, and what the addition would add. When it covers the whole ask, tell the user they already have it. When the search finds nothing, say where you looked and continue.
+
+[`prefer-existing-tools.md`](../../rules/prefer-existing-tools.md) and [`build-needs-a-user.md`](../../rules/build-needs-a-user.md) load only when a session touches a script, hook, or manifest path. This rule loads in every session, so the search comes before the plan is set.
+
+The pull request gate reads the body of each new pull request for an "Existing work" heading. Under it, list what the search found with a link or `file:line` and what the pull request adds on top of it, or state that nothing was found and name the places searched.
+
 ## Before committing to an approach
 
 - Read the relevant files. Understand what exists before proposing what to change.

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -53,7 +53,7 @@ from hooks_constants.hook_specific_output_keys import (
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
 from blocking.followup_pr_dedupe import duplicate_followup_reason
-from blocking.pull_request_proof import missing_proof_reason
+from blocking.pull_request_proof import missing_existing_work_reason, missing_proof_reason
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -199,7 +199,7 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for an unloaded skill, a new pull request with no proof, or a second follow-up.
+    """Return a deny for an unloaded skill, a new pull request with no proof or existing-work section, or a second follow-up.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -211,6 +211,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     proof_reason = missing_proof_reason(all_payload_fields)
     if proof_reason is not None:
         return _deny(proof_reason)
+    search_reason = missing_existing_work_reason(all_payload_fields)
+    if search_reason is not None:
+        return _deny(search_reason)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)
 

package/hooks/blocking/pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Deny a new pull request whose body carries no 'Proof in practice' section."""
+"""Deny a new pull request whose body lacks a 'Proof in practice' or an 'Existing work' section."""
 
 from __future__ import annotations
 
@@ -18,8 +18,10 @@ from hooks_constants.pull_request_proof_constants import (
     ALL_PYTHON_PROGRAM_NAMES,
     COMMAND_MARKER,
     CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    EXISTING_WORK_HEADING_PATTERN,
     LINE_SEPARATOR,
     MISSING_BODY_REASON,
+    MISSING_EXISTING_WORK_REASON,
     MISSING_PROOF_REASON,
     NEXT_HEADING_PATTERN,
     PROOF_HEADING_PATTERN,
@@ -48,6 +50,16 @@ def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
     return all_lines
 
 
+def _section_text(body: str, heading_pattern: str) -> str | None:
+    all_lines = body.splitlines()
+    for each_index, each_line in enumerate(all_lines):
+        heading_level = _heading_level(each_line, heading_pattern)
+        if heading_level is not None:
+            all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
+            return LINE_SEPARATOR.join(all_section_lines).strip()
+    return None
+
+
 def proof_section(body: str) -> str | None:
     """Return the text under the body's 'Proof in practice' heading, or None.
 
@@ -58,13 +70,20 @@ def proof_section(body: str) -> str | None:
 
     The section runs to the next heading of the same or a higher level.
     """
-    all_lines = body.splitlines()
-    for each_index, each_line in enumerate(all_lines):
-        heading_level = _heading_level(each_line, PROOF_HEADING_PATTERN)
-        if heading_level is not None:
-            all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
-            return LINE_SEPARATOR.join(all_section_lines).strip()
-    return None
+    return _section_text(body, PROOF_HEADING_PATTERN)
+
+
+def section_under_existing_work(body: str) -> str | None:
+    """Return the text under the body's 'Existing work' heading, or None.
+
+    ::
+
+        "## Existing work\\n`a.py:4` runs it\\n## Notes" -> "`a.py:4` runs it"
+        "## Summary\\nno existing work heading"         -> None
+
+    The section runs to the next heading of the same or a higher level.
+    """
+    return _section_text(body, EXISTING_WORK_HEADING_PATTERN)
 
 
 def _script_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
@@ -139,3 +158,26 @@ def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None
         if not section or COMMAND_MARKER not in section:
             return MISSING_PROOF_REASON
     return None
+
+
+def missing_existing_work_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a new pull request's body has no existing-work section, else None.
+
+    ::
+
+        mcp__github__create_pull_request, body has the section -> None
+        mcp__github__create_pull_request, body without it      -> MISSING_EXISTING_WORK_REASON
+        gh pr create --fill                                     -> None
+        gh pr edit, git push, any other tool                    -> None
+
+    The section is an 'Existing work' heading with text under it. A create
+    command whose body this gate cannot read passes here, because
+    missing_proof_reason denies it first.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_body in _create_bodies(all_payload_fields):
+        if each_body is not None and not section_under_existing_work(each_body):
+            return MISSING_EXISTING_WORK_REASON
+    return None

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -15,7 +15,10 @@ from blocking import pr_lifecycle_skill_gate as gate
 from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
 from hooks_constants.pull_request_proof_constants import MISSING_PROOF_REASON
 
-PROVEN_FOLLOWUP_BODY = "Follow-up to #1731\n\n## Proof in practice\nRan `python probe.py`.\n"
+PROVEN_FOLLOWUP_BODY = (
+    "Follow-up to #1731\n\n## Existing work\nNothing found in open or merged pull requests.\n\n"
+    "## Proof in practice\nRan `python probe.py`.\n"
+)
 
 
 def _transcript(tmp_path: Path, skill_name: str | None = None, compact: bool = False) -> Path:

package/hooks/blocking/test_pull_request_proof.py

@@ -1,4 +1,4 @@
-"""Behavior tests for the proof-in-practice check on a new pull request."""
+"""Behavior tests for the proof-in-practice and existing-work checks on a new pull request."""
 
 import sys
 from pathlib import Path
@@ -8,10 +8,19 @@ if str(HOOKS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIRECTORY))
 
 from blocking import pull_request_proof as gate
-from hooks_constants.pull_request_proof_constants import MISSING_BODY_REASON, MISSING_PROOF_REASON
+from hooks_constants.pull_request_proof_constants import (
+    MISSING_BODY_REASON,
+    MISSING_EXISTING_WORK_REASON,
+    MISSING_PROOF_REASON,
+)
 
 PROVEN_BODY = "## Summary\nAdds a gate.\n\n## Proof in practice\nRan `python run.py`.\n> denied\n"
 UNPROVEN_BODY = "## Summary\nAdds a gate.\n\n## Verification\nUnit tests pass.\n"
+SEARCHED_BODY = (
+    "## Summary\nAdds a gate.\n\n## Existing work\n`gate.py:12` runs the check; this adds a flag.\n\n"
+    "## Proof in practice\nRan `python run.py`.\n"
+)
+EMPTY_EXISTING_WORK_BODY = "## Existing work\n\n## Proof in practice\nRan `python run.py`.\n"
 
 
 def _shell(command: str, working_directory: Path | None = None) -> dict[str, object]:
@@ -90,3 +99,37 @@ def test_other_pull_request_commands_should_pass() -> None:
 def test_other_tools_should_pass() -> None:
     payload = {"tool_name": "mcp__github__update_pull_request", "tool_input": {"body": "x"}}
     assert gate.missing_proof_reason(payload) is None
+
+
+def test_existing_work_section_should_stop_at_a_heading_of_the_same_level() -> None:
+    assert gate.section_under_existing_work(SEARCHED_BODY) == "`gate.py:12` runs the check; this adds a flag."
+
+
+def test_mcp_create_without_existing_work_should_be_denied() -> None:
+    assert gate.missing_existing_work_reason(_mcp_create(PROVEN_BODY)) == MISSING_EXISTING_WORK_REASON
+
+
+def test_mcp_create_with_an_empty_existing_work_section_should_be_denied() -> None:
+    payload = _mcp_create(EMPTY_EXISTING_WORK_BODY)
+    assert gate.missing_existing_work_reason(payload) == MISSING_EXISTING_WORK_REASON
+
+
+def test_mcp_create_with_existing_work_should_pass() -> None:
+    assert gate.missing_existing_work_reason(_mcp_create(SEARCHED_BODY)) is None
+
+
+def test_gh_create_body_file_without_existing_work_should_be_denied(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(PROVEN_BODY, encoding="utf-8")
+    payload = _shell("gh pr create --draft --body-file body.md", tmp_path)
+    assert gate.missing_existing_work_reason(payload) == MISSING_EXISTING_WORK_REASON
+
+
+def test_unreadable_body_should_leave_the_deny_to_the_proof_check() -> None:
+    payload = _shell("gh pr create --fill")
+    assert gate.missing_existing_work_reason(payload) is None
+    assert gate.missing_proof_reason(payload) == MISSING_BODY_REASON
+
+
+def test_other_pull_request_commands_should_pass_the_existing_work_check() -> None:
+    for each_command in ("gh pr edit 3 --body x", "git push -u origin b", "gh pr view"):
+        assert gate.missing_existing_work_reason(_shell(each_command)) is None

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -25,3 +25,17 @@ MISSING_PROOF_REASON = (
     " prove the change, leave the pull request unopened and tell the user what you could"
     " not run. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
+EXISTING_WORK_HEADING_PATTERN = r"^(#{1,6})[ \t]+existing work[ \t]*#*[ \t]*$"
+EXISTING_WORK_GUIDE_PATH = "~/.claude/docs/rule-guides/explore-thoroughly.md"
+MISSING_EXISTING_WORK_REASON = (
+    "This pull request body has no 'Existing work' section. Before you open a pull"
+    " request, search for what already does the change in full or in part: repository"
+    " code, open and merged pull requests, hooks, rules, skills, workflows, trackers and"
+    " production config. Add an 'Existing work' heading to the body. Under it, list each"
+    " piece you found with its link or file:line and what this pull request adds on top"
+    " of it, or state that nothing was found and name the places you searched. When the"
+    " search finds a piece that already does the change, stop and report it to the user"
+    " before you open the pull request. Run the search-before-acting skill and read "
+    + EXISTING_WORK_GUIDE_PATH
+    + " for the full rule."
+)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.63.0",
+    "version": "8.65.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/explore-thoroughly.md

@@ -1,9 +1,9 @@
 # Explore thoroughly
 
-**When:** Choosing an implementation approach or recommending an architectural direction.
+**When:** Before you log, plan, delegate, or build an ask, or choose an approach.
 
-Read relevant files, map local patterns, and identify constraints before committing to an approach. Scale exploration to risk: inspect nearby files for a small change, broader examples for a new feature, and the full landscape for an architectural decision. Once the files, constraints, and success condition are known, act without repeating settled research.
+Search for what already does the ask, in full or in part. When something exists, stop and report it to the user in four points; run the `search-before-acting` skill. Then read files, patterns, and constraints, scaled to risk. Once the files, constraints, and success condition are known, act without repeating settled research.
 
-**Enforcement:** none, the agent applies it.
+**Enforcement:** the pull request gate denies a body with no "Existing work" section.
 
-**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it when setting exploration depth.
+**Full text:** [`docs/rule-guides/explore-thoroughly.md`](../docs/rule-guides/explore-thoroughly.md). Read it for search scope and depth.