claude-dev-env 8.64.0 → 8.65.1

package/.agents/skills/grok-spawn/SKILL.md

@@ -108,54 +108,10 @@ Flag sets and profile meaning:
 
 ### 3. Write the batch JSON spec
 
-Shape:
-
-```json
-{
-  "role": "bugteam",
-  "should_ping": false,
-  "workers": [
-    {
-      "role_name": "investigate-hooks",
-      "prompt_parts": [
-        "/abs/path/to/readonly-brief.md",
-        "/abs/path/to/task-body.md",
-        "/abs/path/to/report-contract.md"
-      ],
-      "cwd": "/abs/path/to/worktree",
-      "tool_profile": "readonly",
-      "timeout_seconds": 600,
-      "is_repo_only": true,
-      "agent_name": "poteto-agent"
-    }
-  ]
-}
-```
-
-| Field | Meaning |
-|---|---|
-| `role` | Preflight role configuration to check (default `bugteam`) |
-| `should_ping` | When true, preflight runs the opt-in live ping |
-| `workers` | Non-empty list of worker objects |
-| `role_name` | Label on the summary report for this worker |
-| `prompt_parts` | Ordered absolute paths to part files |
-| `cwd` | Working directory for that worker |
-| `tool_profile` | `readonly` or `build` |
-| `timeout_seconds` | Per-worker timeout (default 600, ceiling 5400). A spec asking for more is refused |
-| `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
-| `agent_name` | Use `poteto-agent`; prompts carry the worker role. |
-
-Workers run with no turn cap. The timeout is the only bound on a worker's
-length, and a worker that hits it is killed with its whole process tree and
-reported as `timeout`.
-
-A worker entry accepts these fields and no others. Any other key fails the
-load with an error naming the stray key and listing the accepted set, so a
-misspelled field shows up at startup rather than passing for a setting that
-took effect.
-
-Put the spec file under the run state directory (or any path you pass to
-`--spec`).
+Write the spec from the shape and field table in
+[`reference/batch-spec.md`](reference/batch-spec.md). A worker entry accepts
+only the listed fields. Put the spec file under the run state directory (or any
+path you pass to `--spec`).
 
 ### 4. Launch the batch
 
@@ -222,14 +178,9 @@ Build workers stop at stage-ready edits and a written report. They do not run
 | File | Purpose |
 |---|---|
 | `SKILL.md` | Trigger, gotchas, process, batch shape, composition |
-| `CLAUDE.md` | Package map for this skill folder |
 | `reference/worker-briefs.md` | Readonly brief, build brief, report contract templates |
 | `reference/flag-profiles.md` | Readonly vs build flags, shared flags, socket and stagger rules |
-
-## Folder map
-
-- `SKILL.md` — hub and process.
-- `reference/` — brief templates and flag profiles.
+| `reference/batch-spec.md` | Batch JSON spec shape and worker fields |
 
 ## Worker advisors
 

package/.agents/skills/grok-spawn/reference/batch-spec.md

@@ -0,0 +1,49 @@
+# Batch JSON spec
+
+Shape:
+
+```json
+{
+  "role": "bugteam",
+  "should_ping": false,
+  "workers": [
+    {
+      "role_name": "investigate-hooks",
+      "prompt_parts": [
+        "/abs/path/to/readonly-brief.md",
+        "/abs/path/to/task-body.md",
+        "/abs/path/to/report-contract.md"
+      ],
+      "cwd": "/abs/path/to/worktree",
+      "tool_profile": "readonly",
+      "timeout_seconds": 600,
+      "is_repo_only": true,
+      "agent_name": "poteto-agent"
+    }
+  ]
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `role` | Preflight role configuration to check (default `bugteam`) |
+| `should_ping` | When true, preflight runs the opt-in live ping |
+| `workers` | Non-empty list of worker objects |
+| `role_name` | Label on the summary report for this worker |
+| `prompt_parts` | Ordered absolute paths to part files |
+| `cwd` | Working directory for that worker |
+| `tool_profile` | `readonly` or `build` |
+| `timeout_seconds` | Per-worker timeout (default 600, ceiling 5400). A spec asking for more is refused |
+| `is_repo_only` | Readonly only: when true, also pass `--disable-web-search` |
+| `agent_name` | Use `poteto-agent`; prompts carry the worker role. |
+
+Workers run with no turn cap. The timeout is the only bound on a worker's
+length, and a worker that hits it is killed with its whole process tree and
+reported as `timeout`.
+
+A worker entry accepts these fields and no others. Any other key fails the
+load with an error naming the stray key and listing the accepted set, so a
+misspelled field fails at startup.
+
+Put the spec file under the run state directory (or any path you pass to
+`--spec`).

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/orchestrator/test_orchestrator_skill_contract.py

@@ -7,11 +7,9 @@ _SKILL_DIR = Path(__file__).resolve().parent
 _REFRESH_PATH = _SKILL_DIR.parent / "orchestrator-refresh" / "SKILL.md"
 _ORCHESTRATOR_PATHS = (
     _SKILL_DIR / "SKILL.md",
-    _SKILL_DIR / "AGENTS.md",
     _SKILL_DIR / "reference" / "consult-the-orchestrator.md",
     _SKILL_DIR / "reference" / "executor-consult-block.md",
     _SKILL_DIR / "reference" / "host-detect.md",
-    _SKILL_DIR / "reference" / "AGENTS.md",
     _REFRESH_PATH,
 )
 _FOREIGN_MARKERS = (

package/.agents/skills/pull-request/SKILL.md

@@ -8,21 +8,6 @@ description: >-
 
 # Pull request
 
-## Contents
-
-- [Principle](#principle)
-- [When this applies](#when-this-applies)
-- [Constraints](#constraints)
-- [Dependencies](#dependencies)
-- [Sub-skills](#sub-skills)
-- [Task seeding](#task-seeding)
-- [Process](#process)
-- [Exit handling](#exit-handling)
-- [Examples](#examples)
-- [Gotchas](#gotchas)
-- [File index](#file-index)
-- [Folder map](#folder-map)
-
 ## Principle
 
 Publish one GitHub pull request action from validated local files and a
@@ -151,12 +136,8 @@ failure. Never print the value.
 
 ### 6. Recover a selected legacy record
 
-Run `.agents/skills/pull-request/scripts/recover_legacy_author.py
-<exact-state-file> --confirm-inactive` only when the user selects one legacy
-state file. The command checks the record's age, secure file metadata, and
-contents. The confirmation flag records that the caller verified inactivity.
-Leave every other record untouched. Delete the selected record only after a
-successful restore. Mark this step `N/A` when no legacy state file is selected.
+Follow `reference/legacy-author-recovery.md` only when the user selects one
+legacy state file. Mark this step `N/A` otherwise.
 
 ### 7. Run the action
 
@@ -185,24 +166,12 @@ only after remote readback proves the requested state.
 
 ## Examples
 
-Create example: the writer produces `pr-body.md`. The linter exits `0` for
-`pr-create`. `pull_request.py create` publishes one ready pull request. The
-readback matches the title, body, head SHA, and draft state.
-
-Rejected comment example: the comment body names a worktree file. The linter
-returns a non-zero exit. No account lookup or GitHub request runs. Replace the
-path with inline text or a permanent artifact URL, then rerun.
-
-Recovery example: one old record remains after an interrupted legacy account
-swap. The user selects that exact file and confirms its session is inactive.
-The recovery command restores the named account and deletes only that record.
+Read `reference/examples.md` for a create, a rejected comment, and a recovery.
 
 ## Gotchas
 
 - Relative body-file paths depend on the caller directory. Use an absolute path
   when another process or worktree starts the command.
-- A record older than 30 minutes can still belong to a live session. Require
-  `--confirm-inactive` before recovery.
 - Normal pull request actions never call `gh auth switch`. If that command
   appears outside explicit recovery, stop.
 - `gh auth switch`, `login`, and `logout` change the account for every session
@@ -217,6 +186,8 @@ The recovery command restores the named account and deletes only that record.
 |---|---|
 | `SKILL.md` | Hub for pull request publication, validation, author selection, recovery, and readback |
 | `reference/publication-tasks.md` | Ordered tasks for every publication gate |
+| `reference/legacy-author-recovery.md` | Recovery of one selected legacy author record |
+| `reference/examples.md` | Worked create, rejected comment, and recovery examples |
 | `scripts/pull_request.py` | Command for author selection and create, edit, comment, and review actions |
 | `scripts/github_pr_command_constants/` | Constants for pull request actions, recovery, exit codes, and generic messages |
 | `scripts/test_pull_request.py` | Tests for `pull_request.py` |
@@ -226,18 +197,3 @@ The recovery command restores the named account and deletes only that record.
 | `<managed-root>/scripts/durable_post_lint.py` | Shared action-aware title, body, and path validator |
 | `scripts/gh_artifact_upload.py` | Helper for permanent GitHub binary evidence URLs |
 | `scripts/tests/test_gh_artifact_upload.py` | Tests for binary evidence upload |
-
-## Folder map
-
-```text
-pull-request/
-├── SKILL.md
-├── reference/
-│   └── publication-tasks.md
-└── scripts/
-    ├── pull_request.py
-    ├── github_pr_command_constants/
-    ├── recover_legacy_author.py
-    ├── test_pull_request.py
-    └── test_recover_legacy_author.py
-```

package/.agents/skills/pull-request/reference/examples.md

@@ -0,0 +1,13 @@
+# Pull request examples
+
+Create example: the writer produces `pr-body.md`. The linter exits `0` for
+`pr-create`. `pull_request.py create` publishes one ready pull request. The
+readback matches the title, body, head SHA, and draft state.
+
+Rejected comment example: the comment body names a worktree file. The linter
+returns a non-zero exit. No account lookup or GitHub request runs. Replace the
+path with inline text or a permanent artifact URL, then rerun.
+
+Recovery example: one old record remains after an interrupted legacy account
+swap. The user selects that exact file and confirms its session is inactive.
+The recovery command restores the named account and deletes only that record.

package/.agents/skills/pull-request/reference/legacy-author-recovery.md

@@ -0,0 +1,11 @@
+# Recover a selected legacy author record
+
+Run `.agents/skills/pull-request/scripts/recover_legacy_author.py
+<exact-state-file> --confirm-inactive` only when the user selects one legacy
+state file. The command checks the record's age, secure file metadata, and
+contents. The confirmation flag records that the caller verified inactivity.
+Leave every other record untouched. Delete the selected record only after a
+successful restore.
+
+A record older than 30 minutes can still belong to a live session. Require
+`--confirm-inactive` before recovery.

package/bin/ever-shipped-skills.mjs

@@ -99,6 +99,7 @@ export const EVER_SHIPPED_SKILL_NAMES = new Set([
     'second-account-workers',
     'session-continuity',
     'session-log',
+    'mod-playbooks',
     'session-tidy',
     'pr-shared-extraction',
     'show',

package/bin/install.settings-defaults.test.mjs

@@ -32,7 +32,7 @@ const PACKAGE_SETTINGS_PATH = join(PACKAGE_ROOT, 'settings.json');
 const INSTALL_ENTRY = join(PACKAGE_ROOT, 'bin', 'install.mjs');
 
 const EXPECTED_DENY_ENTRIES = [];
-const EXPECTED_ALLOW_ENTRIES = ['WebFetch(domain:docs.github.com)'];
+const EXPECTED_ALLOW_ENTRIES = ['WebFetch(domain:docs.github.com)', 'Read(~/.claude/docs/**)'];
 const PROFILE_ALLOW_ENTRIES = DECLARED_PROFILE_SETTINGS
     .find((eachEntry) => eachEntry.keyPath.join('.') === 'permissions.allow').items;
 const SAMPLE_MANAGED_DENY_ENTRIES = ['Edit($HOME/.claude/managed-test/**)'];

package/docs/references/working-style.md

@@ -0,0 +1,40 @@
+# Working style
+
+The SessionStart hook `hooks/session/working_style_prompt.py` points every session here. Read this file once, before your first reply.
+
+## Records
+
+- Document each task in a location that remains easy to find later.
+- Keep a running scratch text ledger as you work.
+
+## Presentation
+
+- Use ELI5 for beginner framing, large visuals, minimal text, one stable self-contained HTML artifact, update-in-place continuity, and sharing when a user-facing response needs that presentation.
+- Apply `~/.claude/rules/asd-ste100-language.md` for user-facing word choice, sentence style, tone, punctuation, and prose form.
+- Keep responses focused, brief, and concise. Keep disclaimers and caveats short while giving the main answer most of the response.
+- Give a high-level explanation by default and provide depth when the request calls for it.
+- Match written-document length to the task. Cover the substance and keep every section, summary, and phrase useful.
+- Use current, immediately relevant context. Use full terms and specific names for repository work. Keep all text concise, clear, direct, and useful.
+
+## Replies
+
+- On a typed request, state your next action in one sentence before the first tool call.
+- Finish with the outcome in the first sentence.
+- Send the user only what they must act on or need to know.
+- When a background event, such as a task notification, an agent message, or a scheduled wake, starts a turn and nothing in it needs the user, end the turn with no text.
+- A report that a fix is done carries three lines: the fix acknowledged, what changed, and the proof that it works. Put the rest of the detail in the pull request or a linked file.
+
+## Scope
+
+- Deliver the requested work at its intended scope. Make routine judgment calls yourself.
+- Ask for direction when different interpretations would produce materially different work.
+- When a request seems mistaken or a better approach exists, state the concern briefly and continue with the requested task.
+- A request to remove something is complete once it is gone. Put nothing in its place, and pass a replacement idea to the requester as a question.
+- Finish the complete task and keep actions within the requested scope.
+
+## Questions
+
+- When a request has multiple reasonable interpretations, state your understanding and the assumptions that shape the work.
+- Ask one focused clarification question when the ambiguity changes the outcome, scope, audience, format, or risk.
+- Use a clearly stated low-risk assumption when the intended result remains stable.
+- Pause for the user's choice before making a high-impact decision.

package/hooks/hooks_constants/working_style_prompt_constants.py

@@ -3,43 +3,14 @@
 from __future__ import annotations
 
 __all__ = [
+    "WORKING_STYLE_GUIDE_RELATIVE_PATH",
     "WORKING_STYLE_PROMPT",
 ]
 
+WORKING_STYLE_GUIDE_RELATIVE_PATH = "docs/references/working-style.md"
+
 WORKING_STYLE_PROMPT = (
-    "Document each task in a location that remains easy to find later. Keep a "
-    "running scratch text ledger as you work. Use ELI5 for beginner framing, large "
-    "visuals, minimal text, one stable self-contained HTML artifact, update-in-place "
-    "continuity, and sharing when a user-facing response needs that presentation. "
-    "Keep responses focused, brief, and concise. Apply ~/.claude/rules/asd-ste100-language.md for "
-    "user-facing word choice, sentence style, tone, punctuation, and prose form. "
-    "Keep disclaimers and caveats short while giving "
-    "the main answer most of the response. Give a high-level explanation by default "
-    "and provide depth when the request calls for it. "
-    "On a typed request, state your next action in one sentence before the first "
-    "tool call. "
-    "Finish with the outcome in the first sentence. "
-    "Send the user only what they must act on or need to know. When a background "
-    "event, such as a task notification, an agent message, or a scheduled wake, "
-    "starts a turn and nothing in it needs the user, end the turn with no text. A "
-    "report that a fix is done carries three lines: the fix acknowledged, what "
-    "changed, and the proof that it works. Put the rest of the detail in the pull "
-    "request or a linked file. "
-    "Match written-document length to the task. Cover the substance and keep every "
-    "section, summary, and phrase useful. "
-    "Deliver the requested work at its intended scope. Make routine judgment calls "
-    "yourself. Ask for direction when different interpretations would produce "
-    "materially different work. When a request seems mistaken or a better approach "
-    "exists, state the concern briefly and continue with the requested task. "
-    "A request to remove something is complete once it is gone. Put nothing in its "
-    "place, and pass a replacement idea to the requester as a question. Finish "
-    "the complete task and keep actions within the requested scope. "
-    "When a request has multiple reasonable interpretations, state your understanding "
-    "and the assumptions that shape the work. Ask one focused clarification question "
-    "when the ambiguity changes the outcome, scope, audience, format, or risk. Use a "
-    "clearly stated low-risk assumption when the intended result remains stable. "
-    "Pause for the user's choice before making a high-impact decision. "
-    "Use current, immediately relevant context. "
-    "Use full terms and specific names for repository work. Keep all "
-    "text concise, clear, direct, and useful."
+    f"Read ~/.claude/{WORKING_STYLE_GUIDE_RELATIVE_PATH} before your first reply. "
+    "It sets how you keep task records, present answers, reply, hold scope, and "
+    "ask questions."
 )