claude-dev-env 8.22.0 → 8.23.0

package/.agents/skills/eli5/SKILL.md

@@ -90,11 +90,15 @@ Process steps in order.
    artifact, preserve an explicit user path, or create a clear self-contained
    browser-ready HTML artifact when no path exists. Keep the chosen path for the
    rest of the active task or conversation.
-2. **Borderline — add the current explanation to that artifact.** Read and apply
+2. **Deterministic — list the cases the user named.** When the request lists
+   cases, count each variant as its own case and keep the user's numbering,
+   such as 3a and 3b for a case that holds a draft and a ready variant. Give
+   each case its own card and its own visual.
+3. **Borderline — add the current explanation to that artifact.** Read and apply
    `~/.claude/rules/asd-ste100-language.md` to every sentence. Frame the topic
    for a beginner, use a large useful visual, keep the text minimal, and update
    the same artifact in place.
-3. **Deterministic — run the digest check on a summary of many changes.** A
+4. **Deterministic — run the digest check on a summary of many changes.** A
    summary of a set of changes, such as the pull requests merged in a day, is a
    digest. Give each change one card marked `data-digest-card="<id>"` that holds
    its picture and its one-line change. Pass every source id to the check:
@@ -106,7 +110,7 @@ Process steps in order.
    The check reports each source id with no card, each card over 25 words, each
    card without a picture, and more than 40 words outside the cards. Fix every
    finding and run it again until it prints `CLEAN`.
-4. **Judgment — share the updated artifact with the user.**
+5. **Judgment — share the updated artifact with the user.**
 
 ### Examples
 

package/.agents/skills/eli5/reference/task-seeds.md

@@ -5,8 +5,9 @@ the start of the ELI5 process.
 
 1. Resolve the active HTML artifact path and preserve the stable path.
 2. Create the artifact when no active path exists and keep it self-contained.
-3. Apply the ASD-STE100 rule to page and response sentences.
-4. Add the concise beginner explanation and useful large visual in place.
-5. Run `digest_check.py` on a digest with every source id until it prints
+3. List each case the user named, with each variant as its own case.
+4. Apply the ASD-STE100 rule to page and response sentences.
+5. Add the concise beginner explanation and useful large visual in place.
+6. Run `digest_check.py` on a digest with every source id until it prints
    `CLEAN`.
-6. Share the updated artifact with the user.
+7. Share the updated artifact with the user.

package/hooks/hooks.json

@@ -129,6 +129,11 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/working_style_prompt.py",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/advisor_rules_prompt.py",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/orchestrator_auto_starter.py",

package/hooks/hooks_constants/advisor_rules_prompt_constants.py

@@ -0,0 +1,43 @@
+"""Advisor consult guidance for the SessionStart advisor_rules_prompt hook.
+
+Each sentence in ``ALL_ADVISOR_RULE_SENTENCES`` is copied word for word from
+``docs/references/advisor-tool.md``, which stays the one source. A
+synchronization test fails when a sentence drifts from that document.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ADVISOR_DISABLE_ENV_VAR",
+    "ADVISOR_MODEL_SETTINGS_KEY",
+    "ADVISOR_RULES_HEADER",
+    "ADVISOR_RULES_PROMPT",
+    "ALL_ADVISOR_RULE_SENTENCES",
+    "ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES",
+    "CLAUDE_CONFIG_DIR_ENV_VAR",
+    "DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME",
+    "USER_SETTINGS_FILE_NAME",
+]
+
+ADVISOR_MODEL_SETTINGS_KEY = "advisorModel"
+ADVISOR_DISABLE_ENV_VAR = "CLAUDE_CODE_DISABLE_ADVISOR_TOOL"
+ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES = frozenset({"1", "true", "yes", "on"})
+CLAUDE_CONFIG_DIR_ENV_VAR = "CLAUDE_CONFIG_DIR"
+DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME = ".claude"
+USER_SETTINGS_FILE_NAME = "settings.json"
+
+ADVISOR_RULES_HEADER = (
+    "ADVISOR, when `advisor` is in your tool list. Use your own judgment on when a"
+    " consult helps. Starting points from ~/.claude/docs/references/advisor-tool.md:"
+)
+
+ALL_ADVISOR_RULE_SENTENCES = (
+    "Call for design, architecture, and risk questions where you will not touch a file.",
+    "On tasks longer than a few steps, aim for an early approach consult and a completion review.",
+    "This cadence guides planning and leaves the task free to follow its evidence.",
+    "Short reactive tasks may use the single consult that best fits the live decision.",
+    "Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.",
+    "Give the advice serious weight.",
+)
+
+ADVISOR_RULES_PROMPT = " ".join((ADVISOR_RULES_HEADER, *ALL_ADVISOR_RULE_SENTENCES))

package/hooks/session/advisor_rules_prompt.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""SessionStart hook: inject open advisor consult guidance when the advisor is on.
+
+The built-in advisor tool brings its own guidance on when to call it. This hook
+adds the team-advisor starting points, such as a consult on a design question,
+and leaves each call to the session's judgment. It emits them only when the user settings carry an
+``advisorModel`` value and ``CLAUDE_CODE_DISABLE_ADVISOR_TOOL`` is not set, so a
+session without the advisor is never told to call it.
+The hook writes nothing and runs no tools itself.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.advisor_rules_prompt_constants import (
+    ADVISOR_DISABLE_ENV_VAR,
+    ADVISOR_MODEL_SETTINGS_KEY,
+    ADVISOR_RULES_PROMPT,
+    ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME,
+    USER_SETTINGS_FILE_NAME,
+)
+
+
+def user_settings_path() -> Path:
+    """Return the user settings file under the active Claude config directory."""
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
+    if configured_directory:
+        return Path(configured_directory) / USER_SETTINGS_FILE_NAME
+    return Path.home() / DEFAULT_CLAUDE_CONFIG_DIRECTORY_NAME / USER_SETTINGS_FILE_NAME
+
+
+def is_advisor_disabled_by_environment() -> bool:
+    """Return True when the environment turns the advisor tool off."""
+    raw_value = os.environ.get(ADVISOR_DISABLE_ENV_VAR, "").strip().lower()
+    return raw_value in ALL_ADVISOR_DISABLE_ENV_TRUE_VALUES
+
+
+def is_advisor_configured(settings_path: Path) -> bool:
+    """Return True when the settings file names a non-empty advisor model."""
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return False
+    if not isinstance(settings, dict):
+        return False
+    advisor_model = settings.get(ADVISOR_MODEL_SETTINGS_KEY)
+    return isinstance(advisor_model, str) and advisor_model.strip() != ""
+
+
+def main() -> None:
+    """Emit the advisor guidance as SessionStart additionalContext when the advisor is on."""
+    if is_advisor_disabled_by_environment():
+        return
+    if not is_advisor_configured(user_settings_path()):
+        return
+    session_start_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": ADVISOR_RULES_PROMPT,
+        }
+    }
+    sys.stdout.write(json.dumps(session_start_output) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_advisor_rules_prompt.py

@@ -0,0 +1,86 @@
+"""Tests for advisor_rules_prompt: SessionStart hook that injects advisor consult rules."""
+
+import json
+import sys
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+_HOOKS_ROOT = _SESSION_DIR.parent
+_ADVISOR_TOOL_DOC = _HOOKS_ROOT.parent / "docs" / "references" / "advisor-tool.md"
+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 advisor_rules_prompt as starter
+
+from hooks_constants.advisor_rules_prompt_constants import (
+    ADVISOR_DISABLE_ENV_VAR,
+    ADVISOR_RULES_PROMPT,
+    ALL_ADVISOR_RULE_SENTENCES,
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+)
+
+
+def _run_main() -> str:
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        starter.main()
+    return captured_stdout.getvalue()
+
+
+@pytest.fixture
+def config_directory(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+    monkeypatch.setenv(CLAUDE_CONFIG_DIR_ENV_VAR, str(tmp_path))
+    monkeypatch.delenv(ADVISOR_DISABLE_ENV_VAR, raising=False)
+    return tmp_path
+
+
+def _write_settings(config_directory: Path, settings: object) -> None:
+    (config_directory / "settings.json").write_text(json.dumps(settings), encoding="utf-8")
+
+
+class TestAdvisorRulesPrompt:
+    def test_should_emit_rules_when_advisor_model_is_set(self, config_directory: Path) -> None:
+        _write_settings(config_directory, {"advisorModel": "fable"})
+        hook_output = json.loads(_run_main())["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "SessionStart"
+        assert hook_output["additionalContext"] == ADVISOR_RULES_PROMPT
+
+    def test_should_emit_nothing_when_advisor_model_is_missing(
+        self, config_directory: Path
+    ) -> None:
+        _write_settings(config_directory, {"permissions": {}})
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_advisor_model_is_blank(self, config_directory: Path) -> None:
+        _write_settings(config_directory, {"advisorModel": "  "})
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_settings_file_is_absent(self, config_directory: Path) -> None:
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_settings_file_is_not_json(
+        self, config_directory: Path
+    ) -> None:
+        (config_directory / "settings.json").write_text("{not json", encoding="utf-8")
+        assert _run_main() == ""
+
+    def test_should_emit_nothing_when_environment_disables_the_advisor(
+        self, config_directory: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        _write_settings(config_directory, {"advisorModel": "fable"})
+        monkeypatch.setenv(ADVISOR_DISABLE_ENV_VAR, "1")
+        assert _run_main() == ""
+
+
+class TestAdvisorRulesMatchTheDoc:
+    @pytest.mark.parametrize("each_rule_sentence", ALL_ADVISOR_RULE_SENTENCES)
+    def test_should_quote_each_sentence_from_advisor_tool_doc(
+        self, each_rule_sentence: str
+    ) -> None:
+        doc_text = " ".join(_ADVISOR_TOOL_DOC.read_text(encoding="utf-8").split())
+        assert each_rule_sentence in doc_text

package/package.json

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