claude-dev-env 8.70.0 → 8.71.1

package/docs/rule-guides/question-presentation.md

@@ -0,0 +1,11 @@
+# Present questions clearly
+
+Full text behind [`rules/question-presentation.md`](../../rules/question-presentation.md).
+
+## Codex visual comparisons
+
+For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
+
+## Option cards
+
+When the user asks for option cards, build an Artifact page with the `html-plan:html-plan` skill and follow `~/.claude/docs/templates/html-plan/README.md`. Load the `artifact-capabilities` skill and declare the capability that saves the answer where you can read it. A tap selects a card, a second tap clears it, a picked card shows "Change it" with a notes field, and only Send delivers. After publishing, read the saved answer back before dependent work. If no capability can return the answer, use the native question tool with the same labels.

package/docs/templates/html-plan/README.md

@@ -0,0 +1,36 @@
+# html-plan page template
+
+Build a new artifact page from the html-plan skill. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
+
+## Get the skill
+
+The html-plan plugin is the upstream source, and it stays read-only. Keep every local change in this folder.
+
+1. When the plugin is installed, run `/html-plan` or load the `html-plan` skill.
+2. When it is not installed, clone the source read-only and read the skill from it:
+
+   ```
+   git clone --depth 1 https://github.com/anthropics/claude-plugins-community <scratch folder>
+   git -C <scratch folder> checkout f60f0454df3045f724c43c6346ec80bdcc3472b2
+   ```
+
+   Read `html-plan/skills/html-plan/SKILL.md`, then `references/blocks.md` and `examples/scheduled-send.html` beside it. Link `runtime/htmlplan.css` and `runtime/htmlplan.js` from the page, and run `runtime/pack.mjs` to inline them.
+3. To install the plugin, run `claude plugin install html-plan@claude-community`. The person who owns the environment approves this step.
+
+Codex reads the same `SKILL.md` from the clone in step 2.
+
+## House layer
+
+`house.css` loads after `htmlplan.css`. It:
+
+- sets the body text color and background from the theme tokens, so text keeps its contrast in dark mode,
+- maps the gray text tokens to the full text color,
+- sets accent and status colors that hold 7:1 contrast in light and dark,
+- raises small text to 16px,
+- removes opacity dimming on text.
+
+Paste it into a `<style>` block after the plugin stylesheet, or link it beside the page.
+
+## Check before publishing
+
+Render the page at 390px in light and dark. Every text node is 16px or larger and holds 7:1 contrast against its painted background. The page has no console errors and no horizontal scroll.

package/docs/templates/html-plan/house.css

@@ -0,0 +1,26 @@
+:root { color-scheme: light dark; --ink-2: var(--ink); --ink-3: var(--ink); --accent: #7a2e14; --green: #1c5426; --amber: #5f3f06; --red: #8f1d17; --on-accent: #ffffff; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --ink-2: var(--ink); --ink-3: var(--ink); --accent: #f6bba5; --green: #9fdcaa; --amber: #f2cc80; --red: #f7b3ab; --on-accent: #1f1e1d; } }
+:root[data-theme="dark"] { --ink-2: var(--ink); --ink-3: var(--ink); --accent: #f6bba5; --green: #9fdcaa; --amber: #f2cc80; --red: #f7b3ab; --on-accent: #1f1e1d; }
+body { background: var(--paper); color: var(--ink); font: 430 16px/1.6 var(--sans); }
+small, code, bdi, .mk-cap, .mk-label, .mk-bar, .fig-cap, .c-lang, .c-lines, .c-body td,
+.pl-num, .pl-chev, .pl-bdg, p.pl-claim, doc-claim > .pl-row > .pl-claim, .pl-body > p, .pl-body > ul, .pl-body > doc-note,
+doc-ask::before, doc-ask label small, doc-ask label .sug, doc-ask label > span,
+.nw-askrow .s, .nw-askrow .q small, .nw-btn, .nw-next, .nw-respond, .nw-cbtn, .fig-zoom, .tr-name, .tr-guide, .tr-note, .cl-note, .cl-loc, .mc-to, .mc-hint { font-size: 16px !important; }
+.nw-cbtn, .cl-loc, .fig-zoom, .mc-ev[disabled], .nw-btn[disabled], svg.nw .msg.mc-past path, svg.nw .msg.mc-past text { opacity: 1 !important; }
+.nw-next, .has-comment > .nw-cbtn, .nw-cbtn.on, .nw-askrow.todo .s, .nw-asks .ttl b.todo, .nw-pop.note .k { color: var(--on-accent) !important; }
+.mk-frame.terminal .mk-bar { color: #e6e3dc; }
+doc-note, doc-note > strong:first-child { font-size: 16px !important; }
+:root { --blue: #1d4a85; --purple: #4f2f96; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --blue: #b9d3f5; --purple: #d3c3f5; } }
+:root[data-theme="dark"] { --blue: #b9d3f5; --purple: #d3c3f5; }
+doc-note, doc-note > strong:first-child, .pill, .kicker, .dek, .meta, h4, th, table, figcaption, .caption, details > summary, pre,
+.nw-toc, .nw-toc a, .nw-toc a.h3, .nw-toc a.ask, .nw-toc .ttl, .nw-pop, .nw-pop .ref, .nw-pop textarea, .nw-sheet .hint, .nw-send-state,
+.nw-sheet .body pre, .nw-asks .ttl, .nw-asks .ttl b, .nw-askrow, .nw-askrow .k, .nw-toast, .nw-pin-list, .nw-err, .nw-bar .nw-respond .n,
+doc-claim[data-l="1"] > .pl-row > .pl-num, doc-claim[data-l="2"] > .pl-row > .pl-claim { font-size: 16px !important; }
+.has-comment > .nw-cbtn, .nw-cbtn.on, .nw-bar .nw-respond .n, .nw-bar .nw-next { background: var(--accent); }
+.nw-bar .nw-respond .n.ok { background: var(--green); color: var(--on-accent); }
+.nw-bar .nw-respond .n { color: var(--on-accent); }
+doc-changes, doc-changes b, .ch-tag, .ch-n, .q-head, .q-via, .q-from, .q-at, .q-body { font-size: 16px !important; }
+.cl-head, .cl-kind, .cl-title, .cl-counts, .cl-counts b, .cl-nm, .cl-rail, .cl-tg, .c-cap, .c-pin b, .mc-now, .mc-now b, .mc-now i, .mc-now span, .nw-pin-dot, svg.nw text, svg.nw .node text.sub, svg.nw .node text.more, svg.nw .edge text, svg.nw .group text { font-size: 16px !important; }
+.cl-tg, .tr-guide { color: var(--ink); }
+.nw-pin-dot { color: var(--on-accent); }

package/hooks/features/session-context.md

@@ -10,7 +10,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
 - `session/issue_tracker_session_starter.py` injects issue tracker guidance when enabled for a registered repository.
-- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
+- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires
@@ -32,7 +32,7 @@ Preconditions:
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
 - **Issue tracker start.** Input is SessionStart with its opt-in flag and a registered checkout. Run `python -m pytest packages/claude-dev-env/hooks/session/test_issue_tracker_session_starter.py -q`. The adjacent test observes issue tracker context.
-- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the template path in `additionalContext`, and silence on a publish call or another skill.
+- **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 
 ## Gotchas

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -9,6 +9,8 @@ __all__ = [
     "ARTIFACT_QUICKSTART_ACTION",
     "ARTIFACT_TEMPLATE_PATH",
     "ARTIFACT_TOOL_NAME",
+    "HTML_PLAN_TEMPLATE_README_PATH",
+    "POINTER_ALTERNATIVE_PREFIX",
     "POINTER_TEXT_PREFIX",
     "SKILL_NAME_INPUT_KEY",
     "SKILL_TOOL_NAME",
@@ -21,7 +23,11 @@ ARTIFACT_QUICKSTART_ACTION = "quickstart"
 SKILL_TOOL_NAME = "Skill"
 SKILL_NAME_INPUT_KEY = "skill"
 ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
-ARTIFACT_TEMPLATE_PATH = (
-    Path(__file__).resolve().parents[2] / "docs" / "templates" / "artifact-page" / "README.md"
+TEMPLATES_DIRECTORY = Path(__file__).resolve().parents[2] / "docs" / "templates"
+ARTIFACT_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "README.md"
+HTML_PLAN_TEMPLATE_README_PATH = TEMPLATES_DIRECTORY / "html-plan" / "README.md"
+POINTER_TEXT_PREFIX = "Build this artifact page from the html-plan skill, following "
+POINTER_ALTERNATIVE_PREFIX = (
+    ". When the request names the older artifact page template,"
+    " pick the one that fits the ask from "
 )
-POINTER_TEXT_PREFIX = "Pick the artifact page template that fits the ask from "

package/hooks/hooks_constants/test_artifact_template_pointer_constants.py

@@ -1,8 +1,16 @@
 """Behavioral tests for the artifact template pointer's path."""
 
-from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+from hooks_constants.artifact_template_pointer_constants import (
+    ARTIFACT_TEMPLATE_PATH,
+    HTML_PLAN_TEMPLATE_README_PATH,
+)
 
 
 def test_template_path_names_the_packaged_template_file() -> None:
     assert ARTIFACT_TEMPLATE_PATH.is_file()
     assert ARTIFACT_TEMPLATE_PATH.parent.joinpath("README.md").is_file()
+
+
+def test_html_plan_readme_path_names_the_packaged_readme_and_house_stylesheet() -> None:
+    assert HTML_PLAN_TEMPLATE_README_PATH.is_file()
+    assert HTML_PLAN_TEMPLATE_README_PATH.parent.joinpath("house.css").is_file()

package/hooks/session/artifact_template_pointer.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: point an agent about to build an artifact page at the template.
+"""PreToolUse hook: point an agent about to build an artifact page at html-plan.
 
 Registered on ``Artifact|Skill``. It adds one line of ``additionalContext``
-naming ``docs/templates/artifact-page/template.html`` when a session starts a
-new artifact page:
+naming ``docs/templates/html-plan/README.md`` as the default and
+``docs/templates/artifact-page/README.md`` as the alternative when a
+session starts a new artifact page:
 
 ::
 
@@ -31,6 +32,8 @@ from hooks_constants.artifact_template_pointer_constants import (
     ARTIFACT_QUICKSTART_ACTION,
     ARTIFACT_TEMPLATE_PATH,
     ARTIFACT_TOOL_NAME,
+    HTML_PLAN_TEMPLATE_README_PATH,
+    POINTER_ALTERNATIVE_PREFIX,
     POINTER_TEXT_PREFIX,
     SKILL_NAME_INPUT_KEY,
     SKILL_TOOL_NAME,
@@ -77,7 +80,10 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
-            ADDITIONAL_CONTEXT_KEY: f"{POINTER_TEXT_PREFIX}{ARTIFACT_TEMPLATE_PATH}.",
+            ADDITIONAL_CONTEXT_KEY: (
+                f"{POINTER_TEXT_PREFIX}{HTML_PLAN_TEMPLATE_README_PATH}"
+                f"{POINTER_ALTERNATIVE_PREFIX}{ARTIFACT_TEMPLATE_PATH}."
+            ),
         }
     }
 

package/hooks/session/test_artifact_template_pointer.py

@@ -10,7 +10,10 @@ for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
         sys.path.insert(0, each_sys_path_entry)
 
 import artifact_template_pointer
-from hooks_constants.artifact_template_pointer_constants import ARTIFACT_TEMPLATE_PATH
+from hooks_constants.artifact_template_pointer_constants import (
+    ARTIFACT_TEMPLATE_PATH,
+    HTML_PLAN_TEMPLATE_README_PATH,
+)
 
 HOOK_SCRIPT = Path(__file__).resolve().parent / "artifact_template_pointer.py"
 
@@ -34,7 +37,10 @@ def test_artifact_quickstart_gets_the_template_pointer() -> None:
     hook_output = json.loads(_run_hook(_payload("Artifact", {"action": "quickstart", "intent": "other"})))
     specific_output = hook_output["hookSpecificOutput"]
     assert specific_output["hookEventName"] == "PreToolUse"
-    assert str(ARTIFACT_TEMPLATE_PATH) in specific_output["additionalContext"]
+    pointer_text = specific_output["additionalContext"]
+    assert pointer_text.index(str(HTML_PLAN_TEMPLATE_README_PATH)) < pointer_text.index(
+        str(ARTIFACT_TEMPLATE_PATH)
+    )
     assert "permissionDecision" not in specific_output
 
 

package/package.json

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

package/rules/question-presentation.md

@@ -2,8 +2,10 @@
 
 Before asking, give a short formatted chat brief with context and each choice's effect. Add helpful visuals or artifacts.
 
-For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
-
 Ask one short, self-contained question with two or three choices. Give each a short label and one short sentence. Reuse labels in the brief, comparison, and picker.
 
 Find the native question tool and schema. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question in its title or question field and choices in string or object fields. If unusable, ask in chat.
+
+When the user asks for option cards, or for a Codex visual comparison, read the full text first.
+
+**Full text:** [`~/.claude/docs/rule-guides/question-presentation.md`](../docs/rule-guides/question-presentation.md).