claude-dev-env 1.88.0 → 1.89.0

package/CLAUDE.md

@@ -1,13 +1,19 @@
 # Claude Development Assistant
 
-The user is short on time and tokens. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
-
-The user is short on tokens; whenever a task can be achieved cleanly and effectively, optimize to save the user $$ and token usage.
+The user is short on time and appreciates brevity in replies. When you reply, always assume they'll only read your first few sentences and final sentences. Anything else is skimmed at best. Frame your replies accordingly.
 
 The user delegates execution to you and expects zero manual steps unless strictly necessary. Execute every command you can directly. Only instruct the user to do something manually when you are technically unable to do it yourself. When a task involves credentials or other sensitive input, display a minimal secure UI (e.g., a password dialog) to collect it rather than asking the user to paste it into chat or run the command themselves. When direction is ambiguous, use AskUserQuestion to clarify before acting.
 
-## Code Rules
-@~/.claude/docs/CODE_RULES.md
+You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.
+
+Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.
+
+Also call advisor:
+- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
+- When stuck — errors recurring, approach not converging, results that don't fit.
+- When considering a change of approach.
+
+On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.
 
 ALWAYS call the AskUserQuestion tool if you have a question for the user. Provide content-appropriate default options, with a flag for the recommended one.
 
@@ -21,12 +27,8 @@ 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
 
 `Edit` changes existing files; `Write` creates new ones. Default to `Edit` — reach for `Write` only for a genuinely new path. For a true full rewrite, delete the file first, then `Write`.
@@ -37,10 +39,6 @@ When I ask you to "show me", "open", "display", "let me see", or "pull up" a fil
 
 `Start-Process pwsh -WindowStyle Hidden -ArgumentList '-NoProfile','-File',"$HOME\.claude\scripts\Show-Asset.ps1",'<path 1>','<path 2>'`
 
-It sizes each image window to the image (scaled down to fit the screen) and opens non-image files in their default app; pass every path I name. Printing a path or attaching the file is not showing it — do that only when the file truly cannot be opened, and say why.
-
-The `send_user_file_open_locally_blocker` hook backs this up: it blocks a desk-side `SendUserFile` attach and sends you back to this command, while a phone push (`status: "proactive"`) stays allowed.
-
 ## Test Philosophy
 
 When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.
@@ -59,34 +57,15 @@ Reserve `Read`/`Grep`/`Glob` for files you will actually touch this turn. Compos
 
 Run every multi-step code task in two phases:
 
-1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the tool-less `code-advisor` agent — which returns a plan, a correction, or a stop signal — and resumes. Source: Anthropic's advisor strategy (https://claude.com/blog/the-advisor-strategy).
-2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context. It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
+1. **Coders** — one coder agent per scoped assignment writes the code. A coder that hits a decision it can't reasonably solve consults the advisor (see beginning of this file).
+2. **Verification** — when the coders finish, the main session spawns the `code-verifier` agent in a fresh context, but you must first verify that their work is based on upstream's origin main (aka: the commit live on github). It derives and runs the checks itself rather than trusting coder reports: the task's named gates, tests against baselines recorded before the coders ran, and a two-way diff-vs-assignment reading (every task item maps to a hunk, every hunk maps to a task item, nothing missing). A finding must cite a failing command or a named task item. Source: the fresh-context review step in Claude Code best practices (https://code.claude.com/docs/en/best-practices) — the agent doing the work isn't the one grading it.
 
 Repair agents run only on reported findings; the verifier re-checks after each repair. Work lands (commit, push, draft PR) only on a clean verdict — enforced by the `verified_commit_gate` hook, which blocks `git commit`/`git push` unless a hook-minted verdict covers the current branch diff. The one exemption is mechanical, not discretionary: a diff whose every changed file is non-code or has an unchanged Python AST once docstrings are stripped (docs, docstrings, comments).
 
-## Converge & Review Loop Discipline
-
-- **Worktree isolation:** Run every PR convergence and review loop in an isolated worktree, never a shared checkout that concurrent processes may advance. Verify isolation (the working directory path includes `.claude/worktrees/`) before the first tick or round.
-- **No hedging in findings:** Findings and PR reports state verified facts only — never `likely`, `probably`, `should`, `appears to`. Verify each claim against the code before stating it; the anti-hallucination Stop hook rejects hedged responses.
-- **Tight edit scope:** Edit exactly what the task names — no whole-file rewrites, no renaming public method parameters, no changes beyond the stated task. When the user asks for a "lasting" or "reusable" fix, prefer the durable systemic fix over a one-off edit. When the task touches a pipeline, generator, or other repeated process, fix the process itself, not its individual outputs — even when the request does not say so; for one-off targets, a scoped patch remains the default.
-- **GitHub MCP first:** The GitHub MCP (`mcp__plugin_github_github__*`) is the primary path for PR and review-thread inspection; raw `gh api` is the fallback, not the default — MCP calls work the same from any worktree.
-
-## Destructive-command literals in Bash
-
-Never put a destructive-command literal (`rm -rf`, `git reset --hard`, `dd`, `mkfs`) inside a Bash command string, even when the shell never runs it — a quoted `python -c` argument, a heredoc body, an echoed string, a commit or PR body. The `destructive_command_blocker` hook matches the raw text and asks for confirmation, which a background run cannot answer, so the call stalls. Run hook and deletion checks through the committed test suite (`python -m pytest <test_file>`), or a throwaway script under `$CLAUDE_JOB_DIR/tmp` run as `python <file>.py` — either way the command string carries no destructive text, so the hook stays silent. Group genuine cleanup deletions into one teardown step. See `~/.claude/rules/no-inline-destructive-literals.md`.
-
 ## Sub-agent Output Validation
 
 After any sub-agent returns a PR description, file list, or counts, verify each claim against the actual diff and repo state before using it. Flag and correct any invented paths, fabricated counts, or out-of-scope changes before they land in commits or PR bodies.
 
-## Git Sync Intent
-
-When asked to sync git ("get X onto origin main", "update main"), fast-forward local main to origin — do NOT commit untracked working-tree files unless explicitly told to.
-
-## Scheduled Task Cadence
-
-For scheduled/cron tasks, default to sub-hour intervals (30-minute); do not propose hourly cadences.
-
 ## Task Tracking
 
 Track every task with the task tool, always — for all sessions and all tasks. Capture each task with `TaskCreate` as it arrives, mark it `in_progress` with `TaskUpdate` when you start, and `completed` when it is done. Run `/task-build` to gather any open tasks and add them to the list in one pass.

package/agents/code-verifier.md

@@ -2,7 +2,8 @@
 name: code-verifier
 description: Post-hoc verification agent for the two-phase code workflow. Spawned by the main session after coder agents finish. Runs every check itself in a fresh context — named gates, tests against recorded baselines, two-way diff-vs-task reading — and ends with a fenced verdict block the verifier_verdict_minter hook turns into the commit-gate verdict. Read and execute only; it never edits files.
 tools: Read, Grep, Glob, Bash
-model: inherit
+model: sonnet
+effort: medium
 color: orange
 ---
 

package/bin/install.mjs

@@ -147,7 +147,6 @@ 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/package.json

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

package/skills/CLAUDE.md

@@ -26,8 +26,6 @@ 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

@@ -1,137 +0,0 @@
----
-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

@@ -1,25 +0,0 @@
----
-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.