claude-dev-env 8.8.0 → 8.9.0

package/.agents/skills/privacy-hygiene/SKILL.md

@@ -32,6 +32,7 @@ Surfaces:
 1. **Write / Edit / MultiEdit** — payload text about to land on disk (via PreToolUse dispatcher)
 2. **Durable posts** — `gh pr/issue create|comment|edit|review` bodies and GitHub MCP body/comment fields (Bash and PowerShell)
 3. **git commit** — staged blob text (non-exempt paths) on Bash and PowerShell, including `git.exe` and flag forms (`--no-verify`, `-c`, `-C`). Commit message bodies (`-m` / `-F`) are out of scope for the automated gate
+4. **CI** — the `committed-tree` job in `.github/workflows/ci-tests.yml` runs [gitleaks](https://github.com/gitleaks/gitleaks) over every commit the pull request adds, test files included. The repository-root `.gitleaks.toml` adds three rules to the gitleaks defaults: a user folder path that names a person, an RFC 1918 address, and an email other than a noreply or example address. To clear a fixture that must stay, add its gitleaks fingerprint to `.gitleaksignore`
 
 ## Sweep procedure
 

package/.agents/skills/pull-request/scripts/pull_request.py

@@ -100,6 +100,7 @@ def _linter_arguments(
         all_arguments.extend(["--body-file", str(arguments.body_file)])
     if getattr(arguments, "head", None) is not None:
         all_arguments.extend(["--head-branch", arguments.head])
+    all_arguments.extend(["--repository", arguments.repo])
     return all_arguments
 
 

package/.agents/skills/pull-request/scripts/test_pull_request.py

@@ -198,6 +198,8 @@ def test_actions_run_exact_linter_then_gh_arguments(
         "--body-file",
         BODY_FILENAME,
         *head_arguments,
+        "--repository",
+        all_cli_arguments[all_cli_arguments.index("--repo") + 1],
     ]
     assert exit_code == 0
     assert _calls(command_runner) == [expected_linter, expected_gh]

package/docs/second-claude-account.md

@@ -46,5 +46,12 @@ An unreadable main meter never picks main.
 
 ```
 python packages/claude-dev-env/scripts/claude_account_choice.py
-{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "..."}
+{"account": "second", "config_dir": "C:\\Users\\me\\.claude-profiles\\ev", "reason": "...",
+ "meters": {"main": {"session_used_percent": 12.0, "session_resets_at": "...",
+                     "weekly_used_percent": 34.0, "weekly_resets_at": "..."},
+            "second": null}}
 ```
+
+The `meters` object carries each account's used percent and reset time for the
+5-hour window and the week. An account whose meter could not be read shows `null`.
+A usage report reads both accounts from this one call.

package/hooks/hooks.json

@@ -2,6 +2,16 @@
   "description": "Code standards enforcement, safety guards, and development workflow hooks",
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "multi_agent_v1__spawn_agent",
         "hooks": [
@@ -51,6 +61,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/style_reminder_prompt.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
           }
         ]
       }
@@ -95,6 +110,16 @@
             "timeout": 10
           }
         ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/skill_loaded_reminder.py",
+            "timeout": 10
+          }
+        ]
       }
     ],
     "SessionEnd": [

package/hooks/hooks_constants/skill_loaded_reminder_constants.py

@@ -0,0 +1,58 @@
+"""Texts and names for the skill_loaded_reminder hook."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_SELF_LOADING_SUBAGENT_TYPES",
+    "ALL_SUBAGENT_TOOL_NAMES",
+    "ASSISTANT_ENTRY_TYPE",
+    "COMPACT_BOUNDARY_SUBTYPE",
+    "COMPACTION_REMINDER",
+    "COMPACTION_SOURCE",
+    "NOT_LOADED_REMINDER",
+    "POTETO_MODE_SKILL_NAME",
+    "PRE_TOOL_USE_EVENT_NAME",
+    "PROMPT_SEPARATOR",
+    "SESSION_START_EVENT_NAME",
+    "SKILL_TOOL_NAME",
+    "SLASH_COMMAND_MARKER",
+    "SUBAGENT_PROMPT_PREFIX",
+    "TOOL_USE_BLOCK_TYPE",
+    "USER_ENTRY_TYPE",
+    "USER_PROMPT_SUBMIT_EVENT_NAME",
+]
+
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+SESSION_START_EVENT_NAME = "SessionStart"
+USER_PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
+COMPACTION_SOURCE = "compact"
+
+ALL_SUBAGENT_TOOL_NAMES = frozenset({"Agent", "Task"})
+ALL_SELF_LOADING_SUBAGENT_TYPES = frozenset({"pstack:poteto-agent", "poteto-agent"})
+
+POTETO_MODE_SKILL_NAME = "pstack:poteto-mode"
+SKILL_TOOL_NAME = "Skill"
+SLASH_COMMAND_MARKER = "<command-name>/pstack:poteto-mode</command-name>"
+PROMPT_SEPARATOR = "\n\n"
+
+ASSISTANT_ENTRY_TYPE = "assistant"
+USER_ENTRY_TYPE = "user"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+COMPACT_BOUNDARY_SUBTYPE = "compact_boundary"
+
+SUBAGENT_PROMPT_PREFIX = (
+    "Before any other work, invoke the pstack:poteto-mode skill with the Skill tool. "
+    "Every prompt you write for a subagent opens with the same instruction."
+)
+
+NOT_LOADED_REMINDER = (
+    "The pstack:poteto-mode skill is not loaded in this context. "
+    "Your next tool call is the Skill tool with skill pstack:poteto-mode, before any other "
+    "tool call."
+)
+
+COMPACTION_REMINDER = (
+    "The context was just compacted and the pstack:poteto-mode skill rules were dropped. "
+    "Your next tool call is the Skill tool with skill pstack:poteto-mode, before any other "
+    "tool call. Then re-read the request that started this session and continue."
+)

package/hooks/session/skill_loaded_reminder.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""PreToolUse, SessionStart and UserPromptSubmit hook. Keeps poteto-mode loaded in every context.
+
+::
+
+    Agent tool call, prompt lacks the skill      -> prompt opens with "invoke pstack:poteto-mode"
+    context compacted mid-run                    -> "invoke pstack:poteto-mode again"
+    user turn, skill not loaded since compacting -> "invoke pstack:poteto-mode now"
+    user turn, skill already loaded              -> nothing
+
+A session that loaded the skill hears nothing more until a compaction drops it.
+The hook prints its output and stops.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.skill_loaded_reminder_constants import (
+    ALL_SELF_LOADING_SUBAGENT_TYPES,
+    ALL_SUBAGENT_TOOL_NAMES,
+    ASSISTANT_ENTRY_TYPE,
+    COMPACT_BOUNDARY_SUBTYPE,
+    COMPACTION_REMINDER,
+    COMPACTION_SOURCE,
+    NOT_LOADED_REMINDER,
+    POTETO_MODE_SKILL_NAME,
+    PRE_TOOL_USE_EVENT_NAME,
+    PROMPT_SEPARATOR,
+    SESSION_START_EVENT_NAME,
+    SKILL_TOOL_NAME,
+    SLASH_COMMAND_MARKER,
+    SUBAGENT_PROMPT_PREFIX,
+    TOOL_USE_BLOCK_TYPE,
+    USER_ENTRY_TYPE,
+    USER_PROMPT_SUBMIT_EVENT_NAME,
+)
+from hooks_constants.pre_tool_use_allow_output import write_pre_tool_use_allow_to_stdout
+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
+
+
+def subagent_input_with_poteto_mode(
+    all_tool_input_fields: dict[str, object],
+) -> dict[str, object] | None:
+    """Return the Agent tool input with the poteto-mode instruction first, or None to leave it.
+
+    ::
+
+        {"prompt": "Reply leaf."}                          -> {"prompt": "Before any ...\\n\\nReply leaf."}
+        {"prompt": "Invoke pstack:poteto-mode, then ..."}  -> None
+        {"subagent_type": "pstack:poteto-agent", ...}      -> None, that agent loads the skill itself
+
+    Args:
+        all_tool_input_fields: The Agent tool input the session is about to send.
+    """
+    prompt = all_tool_input_fields.get("prompt")
+    if not isinstance(prompt, str) or POTETO_MODE_SKILL_NAME in prompt:
+        return None
+    if all_tool_input_fields.get("subagent_type") in ALL_SELF_LOADING_SUBAGENT_TYPES:
+        return None
+    return {**all_tool_input_fields, "prompt": SUBAGENT_PROMPT_PREFIX + PROMPT_SEPARATOR + prompt}
+
+
+def _invokes_poteto_mode(all_entry_fields: dict[str, object]) -> bool:
+    message = all_entry_fields.get("message")
+    if not isinstance(message, dict):
+        return False
+    content_blocks = message.get("content")
+    if all_entry_fields.get("type") == USER_ENTRY_TYPE and isinstance(content_blocks, str):
+        return SLASH_COMMAND_MARKER in content_blocks
+    if all_entry_fields.get("type") != ASSISTANT_ENTRY_TYPE or not isinstance(content_blocks, list):
+        return False
+    return any(
+        isinstance(each_block, dict)
+        and each_block.get("type") == TOOL_USE_BLOCK_TYPE
+        and each_block.get("name") == SKILL_TOOL_NAME
+        and isinstance(each_block.get("input"), dict)
+        and each_block["input"].get("skill") == POTETO_MODE_SKILL_NAME
+        for each_block in content_blocks
+    )
+
+
+def _marker_entry(transcript_line: str) -> dict[str, object] | None:
+    if (
+        COMPACT_BOUNDARY_SUBTYPE not in transcript_line
+        and POTETO_MODE_SKILL_NAME not in transcript_line
+    ):
+        return None
+    try:
+        parsed_entry = json.loads(transcript_line)
+    except json.JSONDecodeError:
+        return None
+    return parsed_entry if isinstance(parsed_entry, dict) else None
+
+
+def _is_loaded_after(all_entry_fields: dict[str, object], was_loaded: bool) -> bool:
+    if all_entry_fields.get("subtype") == COMPACT_BOUNDARY_SUBTYPE:
+        return False
+    return was_loaded or _invokes_poteto_mode(all_entry_fields)
+
+
+def is_poteto_mode_loaded(all_transcript_lines: Iterable[str]) -> bool:
+    """Return True when the transcript invoked the skill after its last compaction.
+
+    ::
+
+        Skill(pstack:poteto-mode) ... Read ... Edit               -> True
+        /pstack:poteto-mode typed as a command ... Read           -> True
+        Skill(pstack:poteto-mode) ... compact_boundary ... Read   -> False
+        Read ... Edit                                             -> False
+
+    Only lines naming the skill or a compaction are parsed, so a long transcript
+    reads fast.
+
+    Args:
+        all_transcript_lines: The session transcript, one JSON entry per line.
+    """
+    is_loaded = False
+    for each_line in all_transcript_lines:
+        all_entry_fields = _marker_entry(each_line)
+        if all_entry_fields is not None:
+            is_loaded = _is_loaded_after(all_entry_fields, is_loaded)
+    return is_loaded
+
+
+def _is_loaded_in_transcript(transcript_path: object) -> bool:
+    if not isinstance(transcript_path, str):
+        return False
+    try:
+        with open(
+            transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY
+        ) as transcript:
+            return is_poteto_mode_loaded(transcript)
+    except OSError:
+        return False
+
+
+def reminder_for(all_hook_fields: dict[str, object]) -> str | None:
+    """Return the reminder a session event carries, or None when the skill is in view.
+
+    ::
+
+        SessionStart, source compact                     -> COMPACTION_REMINDER
+        UserPromptSubmit, transcript lacks the skill     -> NOT_LOADED_REMINDER
+        UserPromptSubmit, transcript loaded the skill    -> None
+
+    Args:
+        all_hook_fields: The parsed hook input.
+    """
+    event_name = all_hook_fields.get("hook_event_name")
+    if event_name == SESSION_START_EVENT_NAME:
+        return COMPACTION_REMINDER if all_hook_fields.get("source") == COMPACTION_SOURCE else None
+    if event_name != USER_PROMPT_SUBMIT_EVENT_NAME:
+        return None
+    if _is_loaded_in_transcript(all_hook_fields.get("transcript_path")):
+        return None
+    return NOT_LOADED_REMINDER
+
+
+def _is_subagent_spawn(all_hook_fields: dict[str, object]) -> bool:
+    return (
+        all_hook_fields.get("hook_event_name") == PRE_TOOL_USE_EVENT_NAME
+        and all_hook_fields.get("tool_name") in ALL_SUBAGENT_TOOL_NAMES
+        and isinstance(all_hook_fields.get("tool_input"), dict)
+    )
+
+
+def main() -> None:
+    """Rewrite a subagent prompt, or print the reminder its event needs, or stay quiet."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return
+    if _is_subagent_spawn(hook_payload):
+        rewritten_input = subagent_input_with_poteto_mode(hook_payload["tool_input"])
+        if rewritten_input is not None:
+            write_pre_tool_use_allow_to_stdout(rewritten_input)
+        return
+    reminder = reminder_for(hook_payload)
+    if reminder is None:
+        return
+    reminder_output = {
+        "hookSpecificOutput": {
+            "hookEventName": hook_payload["hook_event_name"],
+            "additionalContext": reminder,
+        }
+    }
+    sys.stdout.write(json.dumps(reminder_output) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_skill_loaded_reminder.py

@@ -0,0 +1,206 @@
+"""Tests for skill_loaded_reminder. Checks every fresh context gets poteto-mode, and loaded ones hear nothing."""
+
+import json
+import sys
+from io import BytesIO, StringIO, TextIOWrapper
+from pathlib import Path
+from unittest.mock import patch
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+import skill_loaded_reminder as reminder
+from hooks_constants.skill_loaded_reminder_constants import (
+    COMPACTION_REMINDER,
+    NOT_LOADED_REMINDER,
+)
+
+SKILL_CALL_LINE = json.dumps(
+    {
+        "type": "assistant",
+        "message": {
+            "role": "assistant",
+            "content": [
+                {
+                    "type": "tool_use",
+                    "name": "Skill",
+                    "input": {"skill": "pstack:poteto-mode"},
+                }
+            ],
+        },
+    }
+)
+TYPED_COMMAND_LINE = json.dumps(
+    {
+        "type": "user",
+        "message": {
+            "role": "user",
+            "content": "<command-name>/pstack:poteto-mode</command-name>",
+        },
+    }
+)
+COMPACT_BOUNDARY_LINE = json.dumps({"type": "system", "subtype": "compact_boundary"})
+READ_CALL_LINE = json.dumps(
+    {
+        "type": "assistant",
+        "message": {
+            "content": [{"type": "tool_use", "name": "Read", "input": {"file_path": "a.py"}}]
+        },
+    }
+)
+TOOL_RESULT_QUOTING_THE_SKILL_LINE = json.dumps(
+    {
+        "type": "user",
+        "message": {
+            "content": [
+                {
+                    "type": "tool_result",
+                    "content": 'SKILL = "pstack:poteto-mode" and <command-name>/pstack:poteto-mode</command-name>',
+                }
+            ]
+        },
+    }
+)
+
+
+def _run_main(hook_payload: object) -> str:
+    """Return the text main() prints for the given hook payload."""
+    stdin_text = hook_payload if isinstance(hook_payload, str) else json.dumps(hook_payload)
+    captured_stdout = StringIO()
+    fake_stdin = TextIOWrapper(BytesIO(stdin_text.encode("utf-8")), encoding="utf-8")
+    with patch("sys.stdin", fake_stdin), patch("sys.stdout", captured_stdout):
+        reminder.main()
+    return captured_stdout.getvalue()
+
+
+def _agent_call(tool_input: dict[str, object], tool_name: str = "Agent") -> dict[str, object]:
+    return {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": tool_input}
+
+
+def _user_turn(transcript_path: Path) -> dict[str, object]:
+    return {"hook_event_name": "UserPromptSubmit", "transcript_path": str(transcript_path)}
+
+
+def _write_transcript(tmp_path: Path, all_lines: list[str]) -> Path:
+    transcript_path = tmp_path / "session.jsonl"
+    transcript_path.write_text("\n".join(all_lines) + "\n", encoding="utf-8")
+    return transcript_path
+
+
+class TestSubagentSpawn:
+    def test_a_plain_subagent_prompt_opens_with_the_poteto_mode_invocation(self) -> None:
+        emitted = json.loads(
+            _run_main(
+                _agent_call(
+                    {
+                        "description": "Find callers",
+                        "subagent_type": "Explore",
+                        "prompt": "List every caller of main.",
+                    }
+                )
+            )
+        )
+        hook_output = emitted["hookSpecificOutput"]
+        rewritten_input = hook_output["updatedInput"]
+        assert hook_output["permissionDecision"] == "allow"
+        assert rewritten_input["prompt"].startswith(
+            "Before any other work, invoke the pstack:poteto-mode skill with the Skill tool."
+        )
+        assert rewritten_input["prompt"].endswith("\n\nList every caller of main.")
+        assert rewritten_input["subagent_type"] == "Explore"
+        assert rewritten_input["description"] == "Find callers"
+
+    def test_the_legacy_task_tool_name_is_rewritten_too(self) -> None:
+        emitted = json.loads(_run_main(_agent_call({"prompt": "Go."}, tool_name="Task")))
+        assert "pstack:poteto-mode" in emitted["hookSpecificOutput"]["updatedInput"]["prompt"]
+
+    def test_a_prompt_that_already_names_the_skill_is_left_alone(self) -> None:
+        assert _run_main(_agent_call({"prompt": "Invoke pstack:poteto-mode first. Then go."})) == ""
+
+    def test_a_poteto_agent_is_left_alone_because_it_loads_the_skill_itself(self) -> None:
+        assert (
+            _run_main(_agent_call({"subagent_type": "pstack:poteto-agent", "prompt": "Go."})) == ""
+        )
+
+    def test_another_tool_is_left_alone(self) -> None:
+        assert _run_main(_agent_call({"prompt": "Go."}, tool_name="Bash")) == ""
+
+
+class TestSubagentInputWithPotetoMode:
+    def test_every_other_input_field_is_kept(self) -> None:
+        rewritten_input = reminder.subagent_input_with_poteto_mode(
+            {"prompt": "Go.", "model": "sonnet", "run_in_background": True}
+        )
+        assert rewritten_input is not None
+        assert rewritten_input["model"] == "sonnet"
+        assert rewritten_input["run_in_background"] is True
+
+    def test_an_input_with_no_prompt_is_left_alone(self) -> None:
+        assert reminder.subagent_input_with_poteto_mode({"description": "Go"}) is None
+
+
+class TestIsPotetoModeLoaded:
+    def test_a_skill_call_loads_it(self) -> None:
+        assert reminder.is_poteto_mode_loaded([READ_CALL_LINE, SKILL_CALL_LINE, READ_CALL_LINE])
+
+    def test_a_typed_slash_command_loads_it(self) -> None:
+        assert reminder.is_poteto_mode_loaded([TYPED_COMMAND_LINE, READ_CALL_LINE])
+
+    def test_a_compaction_after_the_skill_call_drops_it(self) -> None:
+        assert not reminder.is_poteto_mode_loaded(
+            [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, READ_CALL_LINE]
+        )
+
+    def test_a_skill_call_after_the_compaction_loads_it_again(self) -> None:
+        assert reminder.is_poteto_mode_loaded(
+            [SKILL_CALL_LINE, COMPACT_BOUNDARY_LINE, SKILL_CALL_LINE]
+        )
+
+    def test_a_plain_user_prompt_does_not_load_it(self) -> None:
+        plain_prompt_line = json.dumps(
+            {"type": "user", "message": {"content": "Read pstack:poteto-mode docs."}}
+        )
+        assert not reminder.is_poteto_mode_loaded([plain_prompt_line])
+
+    def test_a_tool_result_that_quotes_the_skill_name_does_not_load_it(self) -> None:
+        assert not reminder.is_poteto_mode_loaded([TOOL_RESULT_QUOTING_THE_SKILL_LINE])
+
+
+class TestReminderFor:
+    def test_a_user_turn_in_a_session_that_never_loaded_the_skill_gets_the_reminder(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(tmp_path, [READ_CALL_LINE])
+        emitted = json.loads(_run_main(_user_turn(transcript_path)))
+        hook_output = emitted["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "UserPromptSubmit"
+        assert hook_output["additionalContext"] == NOT_LOADED_REMINDER
+        assert "pstack:poteto-mode" in NOT_LOADED_REMINDER
+
+    def test_a_user_turn_in_a_session_that_loaded_the_skill_prints_nothing(
+        self, tmp_path: Path
+    ) -> None:
+        transcript_path = _write_transcript(tmp_path, [SKILL_CALL_LINE, READ_CALL_LINE])
+        assert _run_main(_user_turn(transcript_path)) == ""
+
+    def test_a_user_turn_with_no_transcript_yet_gets_the_reminder(self, tmp_path: Path) -> None:
+        assert (
+            reminder.reminder_for(_user_turn(tmp_path / "not-written-yet.jsonl"))
+            == NOT_LOADED_REMINDER
+        )
+
+    def test_session_start_after_compaction_tells_the_session_to_invoke_it_again(self) -> None:
+        emitted = json.loads(_run_main({"hook_event_name": "SessionStart", "source": "compact"}))
+        hook_output = emitted["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "SessionStart"
+        assert hook_output["additionalContext"] == COMPACTION_REMINDER
+        assert "pstack:poteto-mode" in COMPACTION_REMINDER
+
+    def test_a_resumed_session_keeps_its_context_and_prints_nothing(self) -> None:
+        assert _run_main({"hook_event_name": "SessionStart", "source": "resume"}) == ""
+
+    def test_a_payload_that_is_not_json_prints_nothing(self) -> None:
+        assert _run_main("not json") == ""

package/package.json

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

package/rules/durable-post-artifacts.md

@@ -3,7 +3,8 @@
 ## When this applies
 
 Use this rule for a GitHub issue, pull request, comment, or review created
-through `gh` or a GitHub MCP post tool.
+through `gh` or a GitHub MCP post tool. The image section also covers a PNG a
+commit adds and a file a release upload sends.
 
 ## Rule
 
@@ -26,6 +27,24 @@ Handle text and binary content differently:
   under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints a permanent download
   URL. Put that URL in the post.
 
+## Optimize every image before it reaches GitHub
+
+The helper shrinks a PNG with [oxipng](https://github.com/oxipng/oxipng) before
+it uploads, and prints the size before and after. Oxipng is lossless.
+`--strip none` keeps every chunk, and `--nb --nc` keep the bit depth and the
+color type, so a reader that checks the image mode sees the same file shape.
+
+Any other route to GitHub runs the same pass first: a PNG a commit adds, and a
+file sent with `gh release upload`.
+
+```
+oxipng --opt 4 --strip none --nb --nc <file> [<file> ...]
+```
+
+The `Binary optimization` check fails a pull request whose changed PNG files
+still shrink under that pass. A fixture whose exact bytes a test pins takes
+`binary-optimizer=keep` in `.gitattributes`, and the check skips it.
+
 ## Volatile paths that must not appear in a post body
 
 - A job scratch directory: `.claude-profile-a/jobs/`
@@ -46,5 +65,11 @@ server write. Pass the matching action and body file. Use `pr-create`,
 `pr-edit`, `pr-comment`, `pr-review`, `issue-create`, `issue-edit`,
 `issue-comment`, or `github-mcp-post`.
 
+Pass `--repository <owner>/<name>` for the repository the post targets. A
+post may name a private organization only inside a repository that
+organization owns. The linter holds the names as digests, so it reports the
+line that names one without printing the name. Describe the organization in
+general terms and drop the link.
+
 The linter reads the body file and reports a volatile local path without
 printing the body. Fix the body and rerun the linter before posting.

package/rules/prefer-existing-tools.md

@@ -0,0 +1,35 @@
+# Prefer Existing Tools
+
+**When this applies:** Before you build a tool, check, scanner, script, or library of your own.
+
+## Rule
+
+Search in this order, and stop at the first fit:
+
+1. **Internal code.** Search the repository and its shared packages for a tool that already does the job. Reuse or extend it.
+2. **An established open-source option.** Search for a plugin, package, or tool that already does the job.
+3. **Your own code.** Build it only when steps 1 and 2 find nothing that fits.
+
+Use an open-source option only when it meets all four conditions:
+
+- It is secure: it has an active security process and no open critical advisory.
+- It is well known in its field.
+- It is widely used: many stars, downloads, or dependents.
+- It is maintained: it had a release or commit in the last year.
+
+Add only what the option lacks. Put custom rules in its own configuration format. Do not wrap it in a new layer of your own code.
+
+## Report the choice
+
+Tell the user which tool you chose before the work is marked ready. Give its name, link, license, and one number that shows how widely it is used. When you build your own code, name what you searched and why each candidate did not fit.
+
+## Why
+
+Code of your own is code you maintain alone. A trusted tool carries fixes and new patterns from its community, and its users find its defects first.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`explore-thoroughly.md`](explore-thoroughly.md) | Read what exists before you propose a change |
+| [`verify-before-asking.md`](verify-before-asking.md) | Answer a question with a tool before you ask it |

package/rules/review-closure-is-a-check.md

@@ -33,7 +33,7 @@ The driving account is the one that opened the pull request. Where the agent com
 
 `.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, and on a review comment. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.
 
-`Echo-Visuals-Inc/python-automation` runs the same command from its own workflow, against the revision of this package that its workflow pins.
+A private repository that installs this package runs the same command from its own workflow, against the revision of this package that its workflow pins.
 
 ## Sibling rules