claude-dev-env 1.87.0 → 1.88.0

package/CLAUDE.md

@@ -21,6 +21,10 @@ Every Markdown file I write or edit describes the system's **current** state onl
 Full banned-pattern set + enforcement: `~/.claude/rules/no-historical-clutter.md` (hook `state-description-blocker`) and `~/.claude/rules/self-contained-docs.md`.
 
 ## GOTCHAS
+ALWAYS base new worktrees off of UPSTREAM origin main. Assume local is out of date.
+
+ALWAYS start each session with a /loop 15m populate or update the task list based on remaining todos.
+
 When making code changes, make sure you are working in the proper worktree path for the task at hand.
 
 ## Choosing Edit vs Write

package/agents/CLAUDE.md

@@ -16,7 +16,7 @@ Agent definition files installed into `~/.claude/agents/` by `bin/install.mjs`.
 | `docs-agent.md` | Docs Agent | Documentation authoring and maintenance |
 | `git-commit-crafter.md` | Git Commit Crafter | Stages changes, writes conventional commit messages, creates commits |
 | `plan-packet-validator.md` | Plan Packet Validator | Fresh-context validator for workflow-generated plan packets under `docs/plans/` |
-| `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes; required by the `pr_description_enforcer` hook |
+| `pr-description-writer.md` | PR Description Writer | Authors PR descriptions in Anthropic-style shapes that pass the `pr_description_enforcer` hook's body audit |
 
 ## Format
 

package/agents/pr-description-writer.md

@@ -1,6 +1,6 @@
 ---
 name: pr-description-writer
-description: "MANDATORY agent for PR descriptions and PR comments. Enforced by the `pr_description_enforcer` PreToolUse hook on `gh pr create`, `gh pr edit`, and `gh pr comment`. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`."
+description: "Optional agent for PR descriptions and PR comments. Authors bodies in one of three Anthropic-derived shapes (Trivial / Standard / Heavy) so PRs match merged-PR style in `anthropics/claude-code`, `anthropics/claude-code-action`, and `anthropics/claude-code-sdk-python`, and pass the `pr_description_enforcer` PreToolUse hook's body audit on `gh pr create`, `gh pr edit`, and `gh pr comment`."
 tools: Read,Grep,Glob,Bash
 model: haiku
 ---

package/bin/install.mjs

@@ -147,6 +147,7 @@ const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
         skills: [
+            'advisor', 'advisor-refresh',
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
             'recall', 'remember', 'task-build', 'verified-build'

package/hooks/blocking/CLAUDE.md

@@ -81,7 +81,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
-| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit` without a PR-description-writer-authored body |
+| `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit`/`comment` bodies that fail the Anthropic claude-code style audit |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |

package/hooks/blocking/pr_description_enforcer.py

@@ -178,7 +178,7 @@ def main() -> None:
         pr_guide_reference = f" @{PR_GUIDE_PATH}" if os.path.exists(PR_GUIDE_PATH) else ""
         denial_reason = (
             f"BLOCKED: [PR_DESCRIPTION] {violation_list}. "
-            f"Use the pr-description-writer agent to author the body in Anthropic claude-code style. "
+            f"Rewrite the body yourself in Anthropic claude-code style. "
             f"Guide:{pr_guide_reference}"
         )
         denial_payload = {

package/hooks/blocking/pr_description_readability.py

@@ -76,8 +76,10 @@ def _read_strike_count() -> int:
 def _increment_strike_count() -> int:
     payload = _read_json_or_default(READABILITY_STATE_FILE, {"strikes": 0})
     raw_count = payload.get("strikes", 0)
-    is_valid_integer = isinstance(raw_count, int) and not isinstance(raw_count, bool)
-    starting_count = max(raw_count, 0) if is_valid_integer else 0
+    if isinstance(raw_count, int) and not isinstance(raw_count, bool):
+        starting_count = max(raw_count, 0)
+    else:
+        starting_count = 0
     new_count = starting_count + 1
     _atomic_write_json(READABILITY_STATE_FILE, {"strikes": new_count})
     return new_count
@@ -87,31 +89,27 @@ def _reset_strike_count() -> None:
     _atomic_write_json(READABILITY_STATE_FILE, {"strikes": 0})
 
 
+def _resolve_integer_field(
+    all_payload_fields: dict[str, object], field_name: str, default_value: int
+) -> int:
+    raw_value = all_payload_fields.get(field_name, default_value)
+    if isinstance(raw_value, int) and not isinstance(raw_value, bool):
+        return raw_value
+    return default_value
+
+
 def _load_readability_thresholds() -> ReadabilityThresholds:
     payload = _read_json_or_default(READABILITY_THRESHOLD_OVERRIDE_FILE, {})
-    flesch_min_value = payload.get("flesch_min", DEFAULT_READABILITY_THRESHOLDS.flesch_min)
-    max_sentence_value = payload.get(
-        "max_sentence_words", DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
-    )
-    avg_sentence_value = payload.get(
-        "avg_sentence_words", DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
-    )
-    flesch_is_int = isinstance(flesch_min_value, int) and not isinstance(flesch_min_value, bool)
-    max_is_int = isinstance(max_sentence_value, int) and not isinstance(max_sentence_value, bool)
-    avg_is_int = isinstance(avg_sentence_value, int) and not isinstance(avg_sentence_value, bool)
-    resolved_flesch = (
-        flesch_min_value if flesch_is_int else DEFAULT_READABILITY_THRESHOLDS.flesch_min
-    )
-    resolved_max = (
-        max_sentence_value if max_is_int else DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
-    )
-    resolved_avg = (
-        avg_sentence_value if avg_is_int else DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
-    )
     return ReadabilityThresholds(
-        flesch_min=resolved_flesch,
-        max_sentence_words=resolved_max,
-        avg_sentence_words=resolved_avg,
+        flesch_min=_resolve_integer_field(
+            payload, "flesch_min", DEFAULT_READABILITY_THRESHOLDS.flesch_min
+        ),
+        max_sentence_words=_resolve_integer_field(
+            payload, "max_sentence_words", DEFAULT_READABILITY_THRESHOLDS.max_sentence_words
+        ),
+        avg_sentence_words=_resolve_integer_field(
+            payload, "avg_sentence_words", DEFAULT_READABILITY_THRESHOLDS.avg_sentence_words
+        ),
     )
 
 

package/package.json

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

package/skills/CLAUDE.md

@@ -26,6 +26,8 @@ Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/
 - `implement` — structured implementation from an existing plan packet
 - `bdd-protocol` — BDD depth: Example Mapping, scenario quality, outside-in layout
 - `verified-build` — build + test loop that gates on a verifier verdict
+- `advisor` — turns the session into the advisor-orchestrator: it spawns executor subagents to do the code edits and test runs, and answers a blocked executor with a plan, correction, or stop
+- `advisor-refresh` — sub-skill fired by the `/advisor` loop to re-assert the executor-advisor discipline mid-run
 
 **PR review and convergence**
 - `autoconverge` — autonomous single-run workflow that drives a PR to ready

package/skills/advisor/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: advisor
+description: >-
+  Turns the session into the advisor-orchestrator — the user's sole interface,
+  which spawns and resumes executor subagents (clean-coder and the like) to do
+  all the code editing and every build or test run. When an executor hits a
+  blocker it consults the advisor, which replies with one of three brief
+  signals — a plan, a correction, or a stop. The advisor orchestrates and
+  advises but never edits code or runs tests itself. Caps consultations per
+  task (default 5), reuses warm agents before spawning new ones, and
+  re-asserts the discipline every 20 minutes through the /advisor-refresh
+  loop. Adapts Anthropic's advisor strategy to Claude Code. Triggers:
+  '/advisor', 'advisor strategy', 'run with an advisor', 'executor-advisor
+  mode'.
+---
+
+# Advisor Strategy
+
+## Principle
+
+A cost-effective executor runs the primary work — it calls tools, reads
+results, and iterates — while a stronger model advises only at the hard
+decisions. Source: Anthropic's advisor strategy,
+https://claude.com/blog/the-advisor-strategy.
+
+Under this skill the session is the advisor-orchestrator. In Claude Code the
+user always talks to the session and never to a subagent, so the session is
+the user's sole interface: all user-facing communication flows through it. It
+spawns and resumes executor subagents — `clean-coder` and the like — and those
+executors do every bit of the execution: the code edits, the build runs, the
+test runs. The advisor drives the plan and answers the executors when they get
+stuck.
+
+This is the advisor-lite shape: the blog's pure pairing keeps the advisor
+tool-less and hidden from the user, but Claude Code routes every user message
+through the session, so the advisor here stays the user's interface while
+keeping execution out of its own hands. Consultations are capped (default 5
+per task) — the same guard the API's `max_uses` gives a tool.
+
+## Gotchas
+
+- **Double invocation duplicates the reminder loop.** A second `/advisor` in
+  the same session schedules a second refresh loop. Check whether the loop is
+  already running before you schedule one (see the invocation guard in
+  Process step 1).
+- **The advisor never executes.** The moment it edits a file or runs the tests
+  itself, the pairing breaks and the executor's warm context is wasted. Hand
+  every code edit and every build or test run to an executor; keep the
+  advisor's own tool use to orchestration and light verification reads.
+- **Resuming an unnamed background agent needs its agentId.** A background
+  spawn returns an `agentId` (format `a...-...`); keep it so `SendMessage` can
+  reach that agent later. A named agent is reachable by name.
+- **Consultations past the cap signal a scoping problem.** When five
+  consultations do not clear the blocker, the task needs re-scoping or a
+  hand-off to the user — not a sixth round of advice.
+
+
+## Process
+
+1. **Invocation guard (once per session).** Before scheduling anything, check
+   whether the refresh loop is already running this session. If it is, skip
+   straight to orchestration — do not schedule a second loop.
+
+2. **Register the discipline reminder.** By default, schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/advisor-refresh`, where
+   each refresh re-schedules the next one — a 1200-second wakeup costs one
+   prompt-cache miss per firing and nothing more (see Gotchas). The loop
+   mechanism (`/loop 20m /advisor-refresh`) is the escape hatch when
+   `ScheduleWakeup` is not available. Either way the reminder is the
+   enforcement surface: each firing re-asserts the discipline while the run is
+   in flight.
+
+3. **Orchestrate the task.** Hold the plan and the user conversation. Spawn or
+   resume executor subagents (for example `clean-coder`) to do every code edit
+   and every build or test run, and keep driving while they work. Your own
+   tool use stays orchestration and light verification reads. Keep your task list updated religiously.
+
+4. **Executors consult at a hard decision.** Each executor's spawn prompt tells
+   it to stop and message you — with the task, what it tried, and the exact
+   blocker (plus any short code excerpt that helps) — when one of these holds:
+   - It has tried the same problem twice or more and it still fails.
+   - A decision changes the deliverable's scope or a contract that is hard to
+     reverse.
+   - Two constraints conflict and it cannot satisfy both.
+   - It is unsure whether to stop or keep going.
+
+5. **Answer with one signal.** On a consultation, reply with exactly one
+   signal, brief (about 400 to 700 tokens):
+   - **PLAN** — a different approach, as concrete ordered steps the executor
+     can run. When a warm agent fits the plan, name which one to resume.
+   - **CORRECTION** — the executor's approach is right, one thing is wrong;
+     name the wrong step and the fix.
+   - **STOP** — no path satisfies the task as assigned; say why so it can be
+     reported upward.
+   The executor resumes the moment your reply lands.
+
+   A worked consultation:
+
+   ```
+   Executor → advisor
+   Task: add a retry to the upload client.
+   Tried: wrapped upload() in a three-attempt loop; the second attempt
+   double-posts.
+   Blocker: the server takes no idempotency key, so a retry after a timeout
+   creates a duplicate record.
+
+   Advisor → executor
+   CORRECTION — the retry loop is right; the missing piece is a stable request
+   id. Generate one client-side on the first attempt and send the same id on
+   every retry, so the server treats the retries as one request.
+   ```
+
+   For a decision the advisor itself cannot settle, it may spawn the tool-less
+   `code-advisor` agent for a second opinion — an optional escalation, not a
+   required step.
+
+## Agent reuse (non-negotiable)
+
+- **Resume before you spawn, always.** A warm agent carries its context and
+  cached tokens; a fresh spawn starts cold and pays to rebuild both.
+  `SendMessage` with an agent's name or `agentId` resumes a running or a
+  completed agent with its context intact — verified live in this environment.
+  Prefer that path every time an existing agent holds relevant context.
+- **Spawn a fresh agent only when** no existing agent holds relevant context,
+  or a genuine task switch needs a clean context.
+- **Name the agent to resume.** When you answer with a PLAN and a warm agent
+  fits, say which agent to resume and where.
+
+## Constraints
+
+- One `/advisor` per session; the invocation guard blocks a second reminder
+  loop.
+- The advisor orchestrates and advises but never edits code or runs a build or
+  test itself — executors do that.
+- Consultations are capped at five per task by default. At the cap, re-scope
+  or hand off; do not keep answering.
+- Reuse a warm agent over a cold spawn whenever one holds relevant context.

package/skills/advisor-refresh/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: advisor-refresh
+description: >-
+  Fired by the /advisor loop reminder about every 20 minutes to re-assert the
+  advisor discipline mid-run. A compressed restatement of /advisor: orchestrate
+  rather than execute, answer a blocked executor with a plan, correction, or
+  stop, and reuse warm agents before spawning new ones. Triggers:
+  '/advisor-refresh'.
+---
+
+# Advisor Refresh
+
+1. **You are the advisor.** Orchestrate and hold the user conversation; spawn
+   executor subagents to do all the work — every code edit and build or test
+   run.
+2. **An executor blocked twice on the same thing?** Answer it with one signal
+   — a plan, a correction, or a stop — brief. Never take over the edit or the
+   tests yourself.
+3. **Resume before you spawn.** `SendMessage` an existing agent by name or
+   `agentId` to reuse its warm context; prefer that over a cold spawn.
+4. **Fresh spawn only for a genuine task switch.** No tool compacts or clears a
+   subagent's context, so a clean context comes from a fresh spawn — never tell
+   an agent to compact.
+5. **Re-schedule the next refresh** (about 1200 seconds out) when the loop
+   mechanism needs each firing to queue the following one.

package/skills/bugteam/CONSTRAINTS.md

@@ -12,7 +12,7 @@
 - **Clean-room audits, every loop.** Each bugfind subagent's spawn prompt contains only the PR scope, audit rubric, and the current loop number. Prior loop history stays in the lead.
 - **Targeted fixes.** Each fix subagent sees ONLY the most recent audit's findings. Prior loops are invisible to the fix subagent.
 - **Fix subagent receives the latest audit as its input contract.** Each loop's fix run operates on the current audit's output and only that.
-- **Lead owns the final PR description rewrite only** (Step 4.5), via the `pr-description-writer` agent.
+- **Lead owns the final PR description rewrite only** (Step 4.5), composed directly against `docs/PR_DESCRIPTION_GUIDE.md`.
 
 ## Why this design
 

package/skills/bugteam/SKILL.md

@@ -98,7 +98,7 @@ end-to-end mental model before starting Step 0.
 | FIX action and verify-push semantics | [reference/audit-and-teammates.md](reference/audit-and-teammates.md) |
 | Posting the end-of-pass audit review (APPROVE on CLEAN, REQUEST_CHANGES with inline anchored comments on DIRTY) | [§ Audit posting](#audit-posting), which applies [../post-audit-findings/SKILL.md](../post-audit-findings/SKILL.md) |
 | Posting per-finding fix replies via GitHub MCP `add_reply_to_pull_request_comment` (rendered with the unified template at [`_shared/pr-loop/audit-reply-template.md`](../../_shared/pr-loop/audit-reply-template.md)) | [reference/github-pr-reviews.md](reference/github-pr-reviews.md) |
-| Teardown, PR description rewrite via `pr-description-writer`, permission revoke, final report | [../pr-loop-lifecycle/reference/teardown-publish-permissions.md](../pr-loop-lifecycle/reference/teardown-publish-permissions.md) |
+| Teardown, PR description rewrite composed by the lead, permission revoke, final report | [../pr-loop-lifecycle/reference/teardown-publish-permissions.md](../pr-loop-lifecycle/reference/teardown-publish-permissions.md) |
 | Spawn-prompt XML, A–P category bindings, outcome XML schemas | [PROMPTS.md](PROMPTS.md) |
 | Per-category audit content (sub-buckets, decision criteria, ready-to-send Variant C templates) | `$HOME/.claude/audit-rubrics/{category_rubrics,prompts}/` |
 | Invariants and design rationale | [CONSTRAINTS.md](CONSTRAINTS.md), [reference/design-rationale.md](reference/design-rationale.md) |

package/skills/pr-loop-lifecycle/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   auto-mode AskUserQuestion escalation when the classifier blocks it),
   worktree preflight and cwd routing, then the ordered close — conditional
   TeamDelete for team callers, worktree teardown, working-tree clean, PR
-  description rewrite via pr-description-writer, the always-run permission
+  description rewrite composed by the lead, the always-run permission
   revoke, and the caller-parameterized final report. Invoked by PR-loop
   orchestrators (bugteam, pr-converge, autoconverge, qbug) at run start and
   run end, including error exits; not for general git cleanup or permission
@@ -48,7 +48,7 @@ Run these in order from the lead session on EVERY exit — converged, cap reache
    ```
    Tolerates already-removed worktrees and missing directories; removal is Windows-safe per `~/.claude/rules/windows-filesystem-safe.md`.
 3. **Clean the working tree.** Return to the session worktree, remove run-scoped scratch files, and leave `git status` clean of run artifacts.
-4. **Rewrite the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, brief the `pr-description-writer` agent, publish via `update_pull_request`, remove the scratch files. On failure, report it and continue — the revoke still runs.
+4. **Rewrite the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, compose the new body directly against `docs/PR_DESCRIPTION_GUIDE.md`, publish via `update_pull_request`, remove the scratch files. On failure, report it and continue — the revoke still runs.
 5. **Revoke project permissions (always):**
    `python "$HOME/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py"`
    Non-negotiable, including on error exits: leaving the grant in place lets future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even when earlier close steps partially failed; log cleanup errors separately.

package/skills/pr-loop-lifecycle/reference/teardown-publish-permissions.md

@@ -35,26 +35,13 @@ When the run exits (any reason), run these steps in order from **this** session
 
 After teardown and before permission revoke, the lead rewrites the PR body to the PR's **final cumulative state** — what the change delivers, not the loop's process. This is the **only** PR-write the lead performs (audit and fix comments stay with the agents that produced them).
 
-The lead delegates body text to the `pr-description-writer` agent so the global mandatory-pr-description-writer hook accepts the `gh pr edit` that follows. The lead does **not** compose the body inline.
-
-`pr-description-writer` comes from the global git-workflow rule in `claude-code-config`. Invoke with `Agent`:
-
-```
-Agent(
-  subagent_type="pr-description-writer",
-  mode="bypassPermissions",
-  description="Rewrite PR <number> body from cumulative diff",
-  prompt="<brief from steps below>"
-)
-```
-
-If that subagent is missing, fall back to `general-purpose` with the same brief — the hook treats agent-authored bodies the same. If neither exists, log a warning and skip this step.
+The lead composes the body text directly against `docs/PR_DESCRIPTION_GUIDE.md` — no agent spawn — so the body passes the `pr_description_enforcer` hook's style audit on the `gh pr edit` that follows.
 
 **Steps:**
 
 1. Capture cumulative diff: `pull_request_read(method="get_diff", pullNumber=N, owner=O, repo=R)` → write the response text to `.<caller>-final.diff` using the `Write` tool.
 2. Capture original body: `pull_request_read(method="get", pullNumber=N, owner=O, repo=R)` → extract `.body` from the response, write it to `.<caller>-original-body.md` using the `Write` tool.
-3. Agent brief:
+3. Compose the new body from those inputs:
    - **Inputs:** diff path, original body path, head branch, base branch.
    - **Constraint:** describe what the PR delivers from the cumulative diff — behavior, user-visible effect, merge rationale. Process metadata (loops, fix counts, findings) stays in review comments.
    - **Preservation rule:** if the original body has manually curated sections (linked issues, screenshots, test plan, "Risk Assessment", etc.), preserve them verbatim and only rewrite narrative around them.
@@ -63,7 +50,7 @@ If that subagent is missing, fall back to `general-purpose` with the same brief
 5. Publish the new body: `update_pull_request(pullNumber=N, owner=O, repo=R, body=<contents of .<caller>-final-body.md>)`.
 6. Remove `.<caller>-final.diff`, `.<caller>-original-body.md`, `.<caller>-final-body.md`.
 
-If this step fails (agent error, hook block, network), report in the final report and continue to the revoke. The original PR body remains; commits and comments are unaffected.
+If this step fails (hook block, network), report in the final report and continue to the revoke. The original PR body remains; commits and comments are unaffected.
 
 ## Revoke project permissions (mandatory, always)
 

package/skills/qbug/SKILL.md

@@ -326,7 +326,7 @@ comment body via `INLINE_COMMENT_BODY_TEMPLATE`):
 
 ## Step 3: PR description refresh (lead)
 
-Delegate body composition to the `pr-description-writer` agent (the mandatory-pr-description hook requires it). Feed the agent the final PR diff and the original body. Apply via `update_pull_request(pullNumber=<number>, owner=<owner>, repo=<repo>, body=<new_body>)`.
+Compose the body directly against `docs/PR_DESCRIPTION_GUIDE.md` — no agent spawn — from the final PR diff and the original body. Apply via `update_pull_request(pullNumber=<number>, owner=<owner>, repo=<repo>, body=<new_body>)`.
 
 On error exit paths: best-effort; log the failure in the final report and continue.