claude-dev-env 2.4.0 → 2.7.0

package/skills/condensing-instructions/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: condensing-instructions
+description: >-
+  Refine an instruction document for Claude 5 generation models: cut rules the
+  model's judgment already covers, move detail behind progressive disclosure,
+  and route each remaining piece to the system prompt, CLAUDE.md, a skill, or a
+  reference. Use for system prompts, CLAUDE.md files, skills, tool
+  descriptions, agent instructions, context engineering, prompt slimming, and
+  token reduction.
+---
+
+# Condensing Instructions
+
+Cut an instruction document to what a Claude 5 generation model needs, and move the rest to the surface that loads it on demand. Over 80% of Claude Code's system prompt came out for Claude Opus 5 and Claude Fable 5 with no measurable drop in performance, so treat a long instruction document as a place with room to cut.
+
+## Clear the conflicts first
+
+Read the system prompt, the CLAUDE.md, and the skills as one body of text and find the lines that pull against each other — "leave documentation as appropriate" sitting beside "DO NOT add comments". A conflict makes the model deliberate at length before it acts. Resolve each pair into one statement, or delete both when neither changes what the model does.
+
+## Trade rules for judgment
+
+Delete a rule written to block a worst case, such as file deletion. Claude 5 generation models read the surrounding context and decide well without it, and a rigid rule blocks the user who has a real reason to want the behavior it forbids.
+
+State the outcome and the signal the model should read:
+
+- Cut: "Default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them."
+- Keep: "Write code that reads like the surrounding code: match its comment density, naming, and idiom."
+
+## Design the interface in place of examples
+
+Examples constrain exploration. Carry usage in the tool's own shape: expressive names, expressive parameters, and types that signal intent. A status parameter enumerated as `pending`, `in_progress`, `completed` shows correct use with no example attached.
+
+## Load detail at the point of use
+
+Move detail out of always-on text and into a surface the model reaches for:
+
+- A skill the model calls when the task calls for it. Code review and verification detail belongs here.
+- A linked file the model opens on demand.
+- A tool with deferred loading, where the model searches for the definition before it uses the tool.
+
+Keep the always-on context lean and let the model pull the rest.
+
+## Say each thing once
+
+Put tool usage guidance in the tool description alone. Delete the copy that repeats it in the system prompt.
+
+## Let memory carry session facts
+
+Claude's automatic memory captures relevant context and carries it across sessions. Delete hand-written memory notes from CLAUDE.md when memory already holds them.
+
+## Point at rich references
+
+Include files as references with @mentions. Prefer a reference the model can read with no ambiguity, in this order:
+
+1. Code from this or another codebase — the highest fidelity specification available.
+2. A test suite that pins the behavior.
+3. An HTML artifact or a mockup.
+4. A rubric, which lets a verification agent score work against a quality standard.
+5. Prose description or a screenshot.
+
+## Route what remains
+
+| Surface | What belongs there |
+|---|---|
+| System prompt | The product Claude works within and the role it plays. For a custom agent, spend real effort here. |
+| CLAUDE.md | A short line on what the repository is, then the gotchas found inside the codebase. Drop anything the model can read off the file structure. Link to skills for the detail. |
+| Skills | Opinions, knowledge, and practices particular to your team or product, written as a guide the model consults. Split a long skill into several files. Constrain only where it matters. |
+| References | Specs, mockups, and codebases pulled in by @mention. |
+
+## Deliver
+
+Rewrite the document in place and report what moved to which surface. Offer `claude doctor` as a follow-up pass — it rightsizes skills and CLAUDE.md files against these same rules.

package/skills/copilot-review/SKILL.md

@@ -1,119 +1,119 @@
----
-name: copilot-review
-description: >-
-  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
-  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
-  review, and exits on convergence. Triggers: '/copilot-review', 'watch
-  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
----
-
-# Copilot Review
-
-Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
-
-## Transport check (before any GitHub step)
-
-Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
-
-## When this skill applies
-
-The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
-
-## The Process
-
-### Step 0: Opt-out check
-
-Before any other work, run:
-
-```bash
-python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
-```
-
-Exit 0 — Copilot reviews are disabled: respond with the literal line
-`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
-spawn the subagent, do not call the Copilot reviewer API, do not run any
-other step of this skill. Exit 1 — continue. Gate semantics live in the
-`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
-
-### Step 1: Gather PR context
-
-From the current repo:
-
-```bash
-# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
-```
-
-Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
-
-### Step 2: Spawn the background subagent
-
-Invoke the `Agent` tool with:
-
-- `subagent_type: "general-purpose"`
-- `run_in_background: true`
-- `description: "Copilot review loop for PR #<N>"`
-- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
-
-Record the returned agent ID. Report to the user in one or two lines:
-
-- The subagent is running in the background.
-- It self-terminates on convergence.
-- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
-- The main session stays free; completion arrives as a notification.
-
-Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
-
-### Step 3: Subagent prompt template
-
-Pass the prompt in
-[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
-word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
-[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
-rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
-and the 20-tick safety cap.
-
-### Step 4: Report back to the user
-
-After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
-
-## Stopping the subagent
-
-- Convergence → subagent stops itself.
-- Blocker → subagent reports and stops.
-- User says stop → `TaskStop <agent_id>`.
-- User asks what loops are running → `TaskList`.
-
-## Ground rules (for the subagent)
-
-- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
-- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
-- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
-- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
-- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
-
-## Examples
-
-<example>
-User: `/copilot-review`
-Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
-</example>
-
-<example>
-User: "babysit copilot on this PR until it's clean"
-Claude: [same as above]
-</example>
-
-<example>
-Subagent tick fires, latest Copilot review is against an older commit.
-Subagent: [re-requests review, schedules next wakeup, returns]
-</example>
-
-<example>
-Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
-Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
-</example>
-
-<example>
-Subagent tick fires, latest review is clean against HEAD.
-Subagent: [reports convergence to parent, terminates — no further wakeups]
-</example>
+---
+name: copilot-review
+description: >-
+  Spawns a background subagent that babysits the GitHub Copilot reviewer on the
+  current PR: each tick it fixes unaddressed findings against HEAD, re-requests
+  review, and exits on convergence. Triggers: '/copilot-review', 'watch
+  copilot', 'babysit copilot review', 'keep re-requesting copilot'.
+---
+
+# Copilot Review
+
+Delegates Copilot babysitting to a background subagent so the main session stays free. The subagent loops internally and closes itself on convergence.
+
+## Transport check (before any GitHub step)
+
+Run `command -v gh`; when it succeeds, run `gh auth status`; once the PR scope is resolved, run `gh api repos/<owner>/<repo> --jq .permissions.push` and take `true` as the pass. When any check fails, run the `pr-loop-cloud-transport` skill first, route every `gh` operation in this skill through its substitution matrix, and carry the same routing into the subagent prompt so the spawned watcher inherits it.
+
+## When this skill applies
+
+The user is on a PR branch, wants Copilot (the GitHub Copilot reviewer bot) to keep re-reviewing after each push, and wants findings auto-addressed between ticks — but does not want the main conversation consumed by polling.
+
+## The Process
+
+### Step 0: Opt-out check
+
+Before any other work, run:
+
+```bash
+python "$HOME/.claude/_shared/pr-loop/scripts/reviews_disabled.py" --reviewer copilot
+```
+
+Exit 0 — Copilot reviews are disabled: respond with the literal line
+`/copilot-review is disabled via CLAUDE_REVIEWS_DISABLED.` and stop — do not
+spawn the subagent, do not call the Copilot reviewer API, do not run any
+other step of this skill. Exit 1 — continue. Gate semantics live in the
+`reviewer-gates` skill ([../reviewer-gates/SKILL.md](../reviewer-gates/SKILL.md)).
+
+### Step 1: Gather PR context
+
+From the current repo:
+
+```bash
+# MCP: pull_request_read(method="get") returns {number, url, head.sha, base.ref, head.ref, isDraft}
+```
+
+Capture `number`, `head.sha`, owner/repo (from `url`), and branch name. Pass these to the subagent so it does not rediscover them.
+
+### Step 2: Spawn the background subagent
+
+Invoke the `Agent` tool with:
+
+- `subagent_type: "general-purpose"`
+- `run_in_background: true`
+- `description: "Copilot review loop for PR #<N>"`
+- `prompt`: the full instructions in **Step 3 (Subagent prompt template)**, with placeholders filled in from Step 1.
+
+Record the returned agent ID. Report to the user in one or two lines:
+
+- The subagent is running in the background.
+- It self-terminates on convergence.
+- To stop it early, the user says "stop the copilot loop" and you call `TaskStop <agent_id>`.
+- The main session stays free; completion arrives as a notification.
+
+Let the subagent own the cadence. The skill's job in the main session ends once the subagent is spawned and reported.
+
+### Step 3: Subagent prompt template
+
+Pass the prompt in
+[`templates/subagent-prompt.md`](templates/subagent-prompt.md) to the subagent
+word for word, filling in the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) from Step 1. It carries the per-tick work, the escalation
+rule (three consecutive no-review ticks), the fix protocol, the stop conditions,
+and the 20-tick safety cap.
+
+### Step 4: Report back to the user
+
+After spawning, tell the user in one or two lines: subagent ID, PR URL, that it will notify on convergence or blocker. Nothing else.
+
+## Stopping the subagent
+
+- Convergence → subagent stops itself.
+- Blocker → subagent reports and stops.
+- User says stop → `TaskStop <agent_id>`.
+- User asks what loops are running → `TaskList`.
+
+## Ground rules (for the subagent)
+
+- **Append commits.** Each tick adds one new commit on the existing branch with `git commit` and `git push origin [BRANCH]`.
+- **Honor pre-push and pre-commit hooks.** When a hook rejects the change, read its output, fix the underlying issue (the failing test, the missing constant, the broken import), and retry. Solve, do not punt.
+- **Respect the PR's current state.** Whatever draft-vs-ready state the PR has when the loop starts is the state the subagent preserves. The user decides when to flip it.
+- **One fix commit per tick.** Batch all of the current tick's findings into a single commit; the next tick handles the next review round.
+- **Use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix for the reviewer ID.** That exact spelling is load-bearing — it is the only form the API accepts.
+
+## Examples
+
+<example>
+User: `/copilot-review`
+Claude: [reads PR context, spawns background subagent with the Step 3 template, reports "subagent X watching PR #123; will notify on convergence"]
+</example>
+
+<example>
+User: "babysit copilot on this PR until it's clean"
+Claude: [same as above]
+</example>
+
+<example>
+Subagent tick fires, latest Copilot review is against an older commit.
+Subagent: [re-requests review, schedules next wakeup, returns]
+</example>
+
+<example>
+Subagent tick fires, Copilot has 2 unaddressed inline findings on HEAD.
+Subagent: [TDD-fixes both, one commit, pushes, replies inline on both threads, resolves both threads, re-requests review, schedules next wakeup]
+</example>
+
+<example>
+Subagent tick fires, latest review is clean against HEAD.
+Subagent: [reports convergence to parent, terminates — no further wakeups]
+</example>

package/skills/e-code-review/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: e-code-review
+description: >-
+  Max-recall code review at a selectable effort level (low, medium, xhigh), with
+  optional auto-fix and an auto-execute loop for any level. Triggers:
+  /e-code-review, /e-code-review low, /e-code-review medium, /e-code-review
+  xhigh, /e-code-review <level> --fix, /e-code-review <level> loop.
+---
+
+# e-code-review
+
+**Pick a level, run that review, optionally fix and loop.** Each level has its own procedure file. Fix application lives in `reference/fix.md`; repeat-until-clean lives in `reference/loop.md`.
+
+## Gotchas
+
+- **`low` stays single-pass.** Do not spawn subagents. One diff read, one findings pass.
+- **`medium` favors precision, `xhigh` favors recall.** At `medium` (8 angles) surface only findings a maintainer would act on. At `xhigh` (10 angles plus a gap sweep) a single non-REFUTED vote carries the finding; do not drop on uncertainty.
+- **`--fix` applies findings once.** Load `reference/fix.md` and follow it — it owns the fix agent, the commit gate, skip logging, and outcome reporting.
+- **`loop` never asks.** After findings, fix nits or stop on bugs. Load `reference/loop.md` and follow it.
+- **`--fix` and `loop` combine.** With both, each loop round runs the level file, then `reference/fix.md`, then re-reviews.
+
+## When this skill applies
+
+Triggers: `/e-code-review <level> [--fix] [loop]`. `<level>` is `low`, `medium`, or `xhigh`. `--fix` and `loop` are each optional and may be used together.
+
+**Refusal — first match wins:**
+
+- **No level, or an unknown level.** Respond exactly: `Which effort level — low, medium, or xhigh?`
+
+## The process
+
+1. Read `<level>` and the optional `--fix` and `loop` flags. Apply the refusal first.
+2. Load `reference/low.md`, `reference/medium.md`, or `reference/xhigh.md`. Run that file as one review cycle, ending in its structured findings report.
+3. If `--fix` is set, load `reference/fix.md` and apply it to that cycle's findings.
+4. If `loop` is set, load `reference/loop.md` and follow it. Each round re-runs the same level file from step 2, plus step 3 when `--fix` is set.
+5. Without `--fix` or `loop`, return the cycle findings and stop.
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Route by level; dispatch `--fix` and `loop` |
+| `reference/low.md` | low review procedure — 1 diff pass, no verify |
+| `reference/medium.md` | medium review procedure — 8 angles, 1-vote verify |
+| `reference/xhigh.md` | xhigh review procedure — 10 angles, 1-vote verify, gap sweep |
+| `reference/fix.md` | Fix application, commit gate, skip logging, outcome reporting |
+| `reference/loop.md` | Repeat review/fix rounds until clean |
+
+## Folder map
+
+- `SKILL.md` — route and dispatch.
+- `reference/` — one procedure per level, plus `fix.md` and `loop.md`.

package/skills/e-code-review/reference/fix.md

@@ -0,0 +1,54 @@
+# Fix Behavior (--fix)
+
+When `--fix` is passed, apply the reviewed findings to the working tree.
+
+## Resume the finding agent
+
+For each finding, resume the same Agent-tool agent instance that originally
+surfaced it. That agent applies all relevant fixes, which you provide guidance
+on in your resume prompt.
+
+At `low` — and any time the Agent tool is unavailable — no finder agent exists
+to resume. Apply the fixes yourself, sequentially, in this context, holding to
+every rule below.
+
+## Commit gate
+
+Before returning, the resumed agent attempts a commit on its own change:
+
+1. Run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo
+   root> <changed/added files>` against every file it changed or added.
+2. If the gate reports violations, fix them and re-run the exact same command.
+3. Repeat until the gate returns clean.
+4. Only after a clean gate result does the agent return control and report
+   its outcome.
+
+## Skip candidates
+
+Skip a finding when fixing it would change intended behavior, require changes
+well outside the reviewed diff, or the finding itself is judged a false
+positive.
+
+Every logged skip surfaces exactly once, batched together, in a single 
+consolidated list presented to the user at the very end of the fix pass 
+— after every other finding has been fixed, marked not-needed, or skipped, 
+and never before.
+
+## Reporting outcomes
+
+After fixes land, report the same findings list again through the structured
+findings-report call — the mechanism that renders this review's results as a
+typed list in the host UI — with each finding now carrying an `outcome`:
+`fixed`, `no_change_needed` (the finding was wrong or already handled), or
+`skipped` (real but not applied). Do not repeat the findings as text in the
+response body; the structured call is the record the host UI reads, and the
+batched skip list from above goes in the prose that follows it.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in the session — the user asks for
+the fix, or later work fixes it incidentally — call the structured
+findings-report call again with the same findings, each carrying an
+`outcome` (`fixed`, `no_change_needed`, or `skipped`). Do not repeat the
+findings as text. Make that call immediately after the fixes land, before any
+prose summary.

package/skills/e-code-review/reference/loop.md

@@ -0,0 +1,43 @@
+# Loop until clean
+
+## Act
+
+`loop` on the hub command authorizes the full cycle. After the effort level procedure returns findings, take the matching branch below immediately.
+
+Do not ask whether to fix, which nits to keep, whether to commit or push, or whether to re-review. Do not open a plan fork. Do not end the turn on a recommendation.
+
+Report progress while you work. Stop for the user only on a terminal outcome below.
+
+## Where fixes come from
+
+When `--fix` is also set, each round's fix pass runs `reference\fix.md`
+(relative to this skill's folder) — it owns which agent applies each fix, the
+commit gate, skip logging, and outcome reporting. Apply the branch rules below
+on top of it: they decide whether a round fixes, commits, pushes, and
+re-reviews.
+
+## Scope stays narrow
+
+Auto-fix only verified findings on the review target. Leave deferred PR-body follow-ups and unrelated refactors alone.
+
+## How to class each finding
+
+Use the finding's verified `severity` when the level emits one.
+
+A finding is a `nit` only when that severity is `nit`. Runtime-correctness, security, data-loss, compatibility, and every other non-nit finding is a `bug`.
+
+If the level emits no severity (for example untagged `low` lines), consult your advisor to determine classification.
+
+## Required checks
+
+"Run required checks" means: run `~/.claude/_shared/pr-loop/scripts/code_rules_gate.py --repo-root <repo root> <changed/added files>` against every file changed or added in the round. On any violation, fix it and re-run the exact same command again — repeat until it reports clean.
+
+## Terminal outcomes
+
+Repeat the same-level review/fix cycle until one of these holds:
+
+- **Clean.** Findings are `[]` or `(none)`. Post the proof-of-work PR comment when the target is a PR. Run `gh pr ready` for a draft PR; otherwise state ready.
+- **Nits only.** Every surviving finding is severity `nit`. Fix all of them on the review target. Run required checks. Commit once per loop round. Push. Consider this clean — post the proof-of-work PR comment and mark ready as in the Clean branch above.
+- **Any bug.** Validate each bug-severity finding with an advisor before touching code — confirm it's real and confirm the intended fix. Then fix all validated findings (bugs and nits) on the review target. Run required checks. Commit once per loop round. Push. Run the same effort level on the new head. Repeat until clean, then mark ready as above.
+
+Do not drop findings to force ready. Without `loop`, run one review at the selected level, fix, and return every validated finding.

package/skills/e-code-review/reference/low.md

@@ -0,0 +1,57 @@
+`low effort → 1 diff pass → no verify → ≥min(files,4) findings`
+
+## Turn 1 — read
+
+One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
+to cover both committed and uncommitted changes, or `git diff main...HEAD` /
+the target passed as an argument). Skip test/fixture
+hunks (`test/`, `spec/`, `__tests__/`, `*_test.*`, `*.test.*`,
+`fixtures/`, `testdata/`) — test-file changes are not reviewed at this level.
+No subagents, no full-file reads.
+
+## Turn 2 — findings
+
+Flag runtime-correctness bugs visible from the hunk alone: inverted/wrong
+condition, off-by-one, null/undefined deref where adjacent lines show the value
+can be absent, removed guard, falsy-zero check, missing `await`,
+wrong-variable copy-paste, error swallowed in a catch that should propagate.
+Also flag — still from the hunk alone — new code that duplicates an existing
+helper visible in the diff context, and dead code the diff leaves behind.
+
+Do **not** flag style, naming, perf, missing tests, or anything outside the
+hunk.
+
+Target **min(files_changed, 4) findings**, most-severe first, reported in one
+call to the structured findings-report call — the mechanism that renders
+findings as a typed list in the host UI — with `{level, findings}`; each
+entry has `file`, `line`, `summary`, `short_summary` (≤60 characters), and
+`failure_scenario`. If you have fewer, do one more pass focused on the largest
+changed file and on any **removed** code blocks. Make that call with an empty
+findings array only if the diff is trivially correct after that pass. Do not
+also print the findings as text.
+
+## Applying fixes (--fix)
+
+The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
+skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
+it governs which agent applies each fix, how a fix gets committed, how a skip
+is logged, and how outcomes get reported. Do not repeat the findings as text;
+follow that document's reporting rules once fixes land.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in this session — the user asks you
+to fix it, or later work fixes it incidentally — follow `reference\fix.md`'s
+reporting rules again: report the same findings through the structured
+findings-report call, each carrying an `outcome`. Do not repeat the findings
+as text. Make that call immediately after the fixes land, before any prose
+summary; the host UI's per-finding status updates only from that call.
+
+## Looping (`loop`)
+
+The `loop` arg was passed. Follow `reference\loop.md` (relative to this
+skill's folder) for how to re-run Turn 1 (read), Turn 2 (findings), and (if
+`--fix` is also present) `reference\fix.md`'s fix pass, repeatedly —
+including its exit condition, iteration cap, and re-invocation rules. Do not
+treat a single pass through this document as complete while `loop` is active;
+hand control to that document instead of stopping at Turn 2.