claude-dev-env 2.22.0 → 2.23.0

package/.agents/skills/source-command-sr-loop/SKILL.md

@@ -13,6 +13,13 @@ Run the converging cleanup loop on the target the user names (a PR URL,
 a branch, or blank for the current branch's diff). Each phase invokes an
 existing skill and repeats it until a pass returns zero new findings.
 
+### Stack context
+
+Before any fixes, load and review the full PR stack, from its base through the
+target PR. Read every PR and diff in the stack. Use that full context to judge
+each proposed simplify or code-review fix. Apply a fix only when it fits the
+stack's design, intent, and changes.
+
 ### Phase A — loop simplify
 
 1. Invoke the `simplify` skill (or its local equivalent, e.g. `e-simplify`)
@@ -44,6 +51,9 @@ existing skill and repeats it until a pass returns zero new findings.
 
 ### Finish
 
+When both phases are clean, or only fixed nits remain, mark the target PR ready
+with `gh pr ready`. Confirm that it is no longer a draft.
+
 Report: passes run per phase, commits pushed with hashes, fixes applied, and
 the standing skip list with reasons.
 

package/.agents/skills/team-advisor/SKILL.md

@@ -30,6 +30,8 @@ One warm advisor at the strongest tier this session can reach. This session is t
 5. Skip the multi-consumer "who you are" opener — sole consumer.
 6. When the bind or reply path fails, fail closed and report to the user. On a third-party host, only the bound Claude advisor issues ENDORSE / CORRECTION / PLAN / STOP.
 
+**GOTCHA (Cursor / ThirdParty + Sol):** when the walk reaches Sol or the user asks for Sol, first tool call is `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --enable-sol --cwd <repo-root>` with the charter on stdin — not Agent/Task, not a probe-path search. Details: [`third-party-bind.md`](../../_shared/advisor/reference/third-party-bind.md) GOTCHA and [`sol-rung.md`](../../_shared/advisor/reference/sol-rung.md).
+
 Full walk, charter, consult packet, Sol routing, and drift re-bind live in the protocol read map and its authoritative `reference/` leaves.
 
 ## Consult

package/AGENTS.md

@@ -1,3 +1,5 @@
+less words. small words. few words. always. forever.
+
 Avoid all redundant text for all output. IE: instead of "the review found 2 real issues", simply state "the review found 2 issues".
 
 ## User-facing language hierarchy

package/_shared/advisor/advisor-protocol.md

@@ -76,6 +76,7 @@ Assemble and paste each executor's Advisor block per the **Advisor block** secti
 On a third-party (non-Claude, non-Codex) harness, the shared CLI Claude-chain is the one path to a Claude advisor: bind Fable through it, per [`reference/third-party-bind.md`](reference/third-party-bind.md).
 The bound Claude session is the advisor; this third-party session stays the executor.
 Walk `candidate_tiers = ["Fable"]`. When Fable is out of usage, the sol rung binds after Fable (`candidate_tiers = ["Fable", "Sol"]`).
+**Cursor Sol first shot:** when the walk reaches Sol (or the user asks for Sol), bind through `codex_sol_advisor.py --bind --enable-sol` on the first tool call (see the GOTCHA in [`reference/third-party-bind.md`](reference/third-party-bind.md)) — not the Agent tool, and not a probe-path hunt.
 **Fail closed:** when every candidate fails, set `selected_tier = null` and a `fallback_reason`, report that the advisor is unreachable, and **stop** — ENDORSE / CORRECTION / PLAN / STOP come only from a bound advisor.
 Executors report to the orchestrating session; that session consults the bound advisor and relays the four-signal reply.
 

package/_shared/advisor/reference/sol-rung.md

@@ -24,9 +24,9 @@ Flag on: run the Codex preflight first —
 python ~/.claude/_shared/pr-loop/scripts/codex_usage_probe.py
 ```
 
-Repo home: `packages/claude-dev-env/_shared/pr-loop/scripts/`.
+**GOTCHA — probe path:** that installed path is the only one. `codex_sol_advisor.resolve_usage_probe_path` builds `~/.claude/_shared/pr-loop/scripts/codex_usage_probe.py` and stops. Do not hunt `skills/codex-review/`, Codex worktrees under `C:\dev\.codex\worktrees\`, or other copies. Repo home: `packages/claude-dev-env/_shared/pr-loop/scripts/`.
 
-The shared entry point is `~/.claude/_shared/advisor/scripts/codex_sol_advisor.py`; it calls the installed probe and owns Sol bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
+The shared entry point is `~/.claude/_shared/advisor/scripts/codex_sol_advisor.py`; it calls the installed probe and owns Sol bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_sol_advisor.py --bind --enable-sol --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
 
 The gate passes only when the probe exits 0, `percent_left` is finite numeric data, and `percent_left` is strictly greater than `WEEKLY_USAGE_GATE_THRESHOLD_PERCENT` from the existing probe. The exact-threshold case fails closed when Fable did not bind.
 

package/_shared/advisor/reference/third-party-bind.md

@@ -3,6 +3,18 @@
 Detail behind the **Host profiles → Third-party host** section of [`advisor-protocol.md`](../advisor-protocol.md).
 Open this when binding or re-binding the advisor from a third-party (non-Claude, non-Codex) harness.
 
+## GOTCHA — Cursor Sol first shot
+
+Cursor is a third-party host. When the walk reaches Sol (`ADVISOR_SOL=1` / `--enable-sol` after Fable is out of usage, or the user asks for Sol), bind Sol on the **first** tool call through the headless Codex helper. Do not use the Agent or Task tool, do not spawn Grok as a substitute, and do not search the filesystem for `codex_usage_probe.py`.
+
+```
+python "$HOME/.claude/_shared/advisor/scripts/codex_sol_advisor.py" --bind --enable-sol --cwd <repo-root>
+```
+
+Pipe the standing-reviewer charter on stdin. Persist `session_id` from the JSON reply. Later consults: `--resume <session_id>` with the delta on stdin. Capture helper / `codex` stdout as UTF-8 on Windows (`encoding="utf-8"`, `errors="replace"`). Probe path and preflight: [`sol-rung.md`](sol-rung.md).
+
+When the Sol flag is off, follow the Claude-chain steps below.
+
 ## Bind steps
 
 1. Name the session identity first (protocol **Host profiles**). This path is for a ThirdParty profile.

package/_shared/advisor/scripts/codex_sol_advisor.py

@@ -34,6 +34,10 @@ from advisor_scripts_constants.sol_advisor_constants import (  # noqa: E402
     CODEX_REASONING_CONFIG_TEMPLATE,
     CODEX_RESUME_SUBCOMMAND,
     CODEX_SANDBOX_FLAG,
+    USAGE_PROBE_FILENAME,
+    USAGE_PROBE_PACKAGE_DIRECTORY_NAME,
+    USAGE_PROBE_SCRIPTS_DIRECTORY_NAME,
+    USAGE_PROBE_SHARED_DIRECTORY_NAME,
     SOL_BIND_FAILURE_REASON,
     SOL_CODEX_TIMEOUT_REASON,
     SOL_CODEX_TIMEOUT_SECONDS,
@@ -201,6 +205,14 @@ def resolve_advisor_effort(
 def resolve_usage_probe_path(home_directory: Path) -> Path:
     """Return the installed Codex weekly usage probe path.
 
+    ::
+
+        resolve_usage_probe_path(Path.home())
+            -> ~/.claude/_shared/pr-loop/scripts/codex_usage_probe.py
+
+    This is the only probe path the Sol helper uses. Do not search worktrees
+    or archived ``skills/codex-review`` trees for a second copy.
+
     Args:
         home_directory: Home directory used to construct the path.
 
@@ -210,10 +222,10 @@ def resolve_usage_probe_path(home_directory: Path) -> Path:
     return (
         home_directory
         / CLAUDE_CONFIG_DIRECTORY_NAME
-        / "skills"
-        / "codex-review"
-        / "scripts"
-        / "codex_usage_probe.py"
+        / USAGE_PROBE_SHARED_DIRECTORY_NAME
+        / USAGE_PROBE_PACKAGE_DIRECTORY_NAME
+        / USAGE_PROBE_SCRIPTS_DIRECTORY_NAME
+        / USAGE_PROBE_FILENAME
     )
 
 

package/_shared/advisor/scripts/config/advisor_scripts_constants/sol_advisor_constants.py

@@ -14,6 +14,10 @@ CODEX_EXEC_SUBCOMMAND: str = "exec"
 CODEX_RESUME_SUBCOMMAND: str = "resume"
 CODEX_SANDBOX_FLAG: str = "--sandbox"
 CLAUDE_CONFIG_DIRECTORY_NAME: str = ".claude"
+USAGE_PROBE_SHARED_DIRECTORY_NAME: str = "_shared"
+USAGE_PROBE_PACKAGE_DIRECTORY_NAME: str = "pr-loop"
+USAGE_PROBE_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+USAGE_PROBE_FILENAME: str = "codex_usage_probe.py"
 SOL_SESSION_ID_METAVAR: str = "SESSION_ID"
 SOL_CODEX_TIMEOUT_SECONDS: float = 120.0
 SOL_USAGE_PROBE_TIMEOUT_SECONDS: float = 30.0

package/_shared/advisor/scripts/tests/test_codex_sol_advisor.py

@@ -31,9 +31,8 @@ def _load_sol_module() -> ModuleType:
 sol_advisor = _load_sol_module()
 SCRIPTS_ROOT = Path(__file__).parent.parent
 USAGE_PROBE_PATH = (
-    SCRIPTS_ROOT.parents[2]
-    / "skills"
-    / "codex-review"
+    SCRIPTS_ROOT.parents[1]
+    / "pr-loop"
     / "scripts"
     / "codex_usage_probe.py"
 )
@@ -134,8 +133,8 @@ def test_resolve_usage_probe_path_uses_supplied_home_directory(tmp_path: Path) -
     assert probe_path == (
         tmp_path
         / ".claude"
-        / "skills"
-        / "codex-review"
+        / "_shared"
+        / "pr-loop"
         / "scripts"
         / "codex_usage_probe.py"
     )

package/commands/sr-loop.md

@@ -10,6 +10,13 @@ tool and repeats it until a pass returns zero new findings.
 Use `rules/asd-ste100-language.md` for user-facing wording. Keep the loop's
 cleanup, verification, commit, push, and finish-report fields.
 
+## Stack context
+
+Before any fixes, load and review the full PR stack, from its base through the
+target PR. Read every PR and diff in the stack. Use that full context to judge
+each proposed simplify or code-review fix. Apply a fix only when it fits the
+stack's design, intent, and changes.
+
 ## Phase A — loop /simplify
 
 1. Invoke the `simplify` skill on the target (the same review the user gets
@@ -41,6 +48,9 @@ cleanup, verification, commit, push, and finish-report fields.
 
 ## Finish
 
+When both phases are clean, or only fixed nits remain, mark the target PR ready
+with `gh pr ready`. Confirm that it is no longer a draft.
+
 Report: passes run per phase, commits pushed with hashes, fixes applied, and
 the standing skip list with reasons.
 

package/docs/codex-compatibility.md

@@ -22,6 +22,34 @@ A missing or unreadable source root is an error, and the run changes nothing. An
 
 Run `codex-compat bridge --surface <name> --payload '<json-object>'`. The bridge exposes the Python translation logic directly. `TaskCreate` and `TaskUpdate` map to `update_plan`; spawn, message, wait, and stop map to multi-agent surfaces. `ScheduleWakeup` is explicitly unsupported and requires manual review.
 
+## Per-message context injection (manual wiring)
+
+Codex reads the same `hookSpecificOutput.additionalContext` shape as Claude,
+on its own `UserPromptSubmit` event. `hooks/session/style_reminder_prompt.py`
+works for both, as is.
+
+The install already points `$CODEX_HOME/hooks` at the shared hooks folder.
+Once installed, the script sits at
+`$CODEX_HOME/hooks/session/style_reminder_prompt.py`.
+
+Add this by hand to `$CODEX_HOME/hooks.json` (merge it into an existing file):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "command": "python3 $CODEX_HOME/hooks/session/style_reminder_prompt.py"
+      }
+    ]
+  }
+}
+```
+
+Limits:
+
+- The installer skips Codex `hooks.json` for now. Wire it by hand.
+
 ## Roots and safety
 
 Both roots are caller-supplied. The tool never writes to `.agents` or `CODEX_HOME` automatically; pass those locations explicitly when desired. No personal paths or secrets are embedded in the package.

package/hooks/hooks.json

@@ -123,6 +123,18 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/style_reminder_prompt.py",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "",

package/hooks/hooks_constants/AGENTS.md

@@ -81,6 +81,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
 | `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
 | `stop_dispatcher_constants.py` | Ordered hosted-hook roster and Stop block payload field names for the Stop-chain dispatcher |
+| `style_reminder_prompt_constants.py` | The style reminder text ("small words. few words. always. forever.") for the style_reminder_prompt hook |
 | `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
 | `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
 | `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |

package/hooks/hooks_constants/style_reminder_prompt_constants.py

@@ -0,0 +1,9 @@
+"""The style reminder text for the style_reminder_prompt hook."""
+
+from __future__ import annotations
+
+__all__ = [
+    "STYLE_REMINDER_PROMPT",
+]
+
+STYLE_REMINDER_PROMPT = "small words. few words. always. forever."

package/hooks/session/AGENTS.md

@@ -1,6 +1,6 @@
 # hooks/session
 
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown.
+SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown. Also holds the UserPromptSubmit hook. It adds a style reminder to each message.
 
 The working-style projection uses `~/.claude/rules/asd-ste100-language.md` for
 user-facing word choice, sentence style, tone, punctuation, and prose form.
@@ -21,6 +21,8 @@ user-facing word choice, sentence style, tone, punctuation, and prose form.
 | `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
 | `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
 | `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, canonical language policy, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
+| `style_reminder_prompt.py` | UserPromptSubmit | Adds the style reminder ("small words. few words. always. forever.") to every message, as `hookSpecificOutput.additionalContext`. Codex reads the same shape, so a manually wired Codex `hooks.json` can reuse this script too (see `docs/codex-compatibility.md`). Prints text and stops. |
+| `test_style_reminder_prompt.py` | — | Tests for `style_reminder_prompt.py` |
 | `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
 | `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
 | `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |

package/hooks/session/style_reminder_prompt.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook. Adds the style reminder to every message.
+
+::
+
+    user sends a message
+             |
+             v
+    UserPromptSubmit fires -> additionalContext: "small words. few words. always. forever."
+             |
+             v
+    the model sees the reminder this turn, and each turn after
+
+Claude Code and Codex CLI both read the same ``additionalContext`` shape on
+their ``UserPromptSubmit`` event. One script serves both. The hook prints
+text and stops.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.style_reminder_prompt_constants import STYLE_REMINDER_PROMPT
+
+
+def main() -> None:
+    """Print the style reminder as UserPromptSubmit additionalContext."""
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": STYLE_REMINDER_PROMPT,
+        }
+    }
+    sys.stdout.write(json.dumps(payload) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_style_reminder_prompt.py

@@ -0,0 +1,32 @@
+"""Tests for style_reminder_prompt. Checks the hook adds the style reminder."""
+
+import json
+import sys
+from io import StringIO
+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 style_reminder_prompt as reminder
+from hooks_constants.style_reminder_prompt_constants import STYLE_REMINDER_PROMPT
+
+
+def _run_main() -> str:
+    """Return the text main() prints."""
+    captured_stdout = StringIO()
+    with patch("sys.stdout", captured_stdout):
+        reminder.main()
+    return captured_stdout.getvalue()
+
+
+class TestStyleReminderPrompt:
+    def test_main_emits_user_prompt_submit_hook_specific_output(self) -> None:
+        emitted = json.loads(_run_main())
+        hook_output = emitted["hookSpecificOutput"]
+        assert hook_output["hookEventName"] == "UserPromptSubmit"
+        assert hook_output["additionalContext"] == STYLE_REMINDER_PROMPT

package/package.json

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

package/rules/AGENTS.md

@@ -29,6 +29,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
 | `falsify-before-green.md` | A check's green counts as evidence only after that same check ran red on a named break, with a passing control beside it |
 | `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
+| `few-words.md` | The style reminder. Syncs to Cursor as an always-on `.mdc` rule. |
 | `filesystem-search.md` | Every filesystem search names a scope; `es.exe`, `Glob`, `Grep`, and `Read` are equally sanctioned, and the `unscoped_search_blocker` denies a walk from a root |
 | `gh-cli-conventions.md` | `--body-file` for every `gh` body; `--paginate --slurp` piped to external `jq` for every paginated list read |
 | `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images; carries the review-response protocol and a See-also block for its seven siblings |

package/rules/few-words.md

@@ -0,0 +1,3 @@
+# Few Words
+
+small words. few words. always. forever.