claude-dev-env 8.63.0 → 8.64.0

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,6 +95,7 @@ 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',

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.64.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.