claude-dev-env 2.3.0 → 2.5.0

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

@@ -0,0 +1,153 @@
+`medium effort → 3+5 angles → 1-vote verify`
+
+You are reviewing for **precision** at medium effort: every finding you surface
+should be one a maintainer would act on.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
+
+Run **8 independent finder angles** via the Agent tool. Each surfaces
+candidate findings with `file`, `line`, a one-line `summary`, and a concrete
+`failure_scenario`. If the Agent tool is not available in your current tool
+set, do not error — perform each angle (and each verification) yourself,
+sequentially, in this context.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings.
+
+Pass every candidate with a nameable failure scenario through — finders that
+silently drop half-believed candidates bypass the verify step and are the
+dominant cause of misses.
+
+## Phase 2 — Verify (1-vote, 3-state)
+
+Dedup candidates that point at the same line/mechanism, keeping the one with
+the most concrete failure scenario. For each remaining candidate, run **one
+verifier** via the Agent tool: give it the diff, the relevant
+file(s), and the candidate, and have it return exactly one of:
+
+- **CONFIRMED** — can name the inputs/state that trigger it and the wrong
+  output or crash. Quote the line.
+- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+  config). State what would confirm it.
+- **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
+  Quote the line that proves it.
+
+Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
+
+## Output
+
+Report this review's results — `{level, findings}` — through the structured
+findings-report call: the mechanism that renders a review's results as a typed
+list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
+`summary`, `short_summary` — the claim compressed to ≤60 characters, no
+rationale or consequence clause — `failure_scenario`, and `category` — a short
+kebab-case slug for the angle that produced it (`correctness`,
+`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
+specific slug like `test-coverage` when one fits better) — plus `verdict` when
+a verify pass produced one. If nothing survives verification, make that call
+with an empty array. Do not also print the findings as text, and do not create
+or publish an artifact of the review — the structured call is the report.
+
+## 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 Phases 0–2, Output, 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 Output.

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

@@ -0,0 +1,182 @@
+`xhigh effort → 5+5 angles → 1-vote verify → sweep`
+
+You are reviewing for **recall** at extra-high effort: catch every real bug. At
+this level, catching real bugs matters more than avoiding false positives — a
+missed bug ships. Err on the side of surfacing.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (5 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
+
+Run **10 independent finder angles** via the Agent tool. Each surfaces
+candidate findings. Do NOT let one angle's conclusions suppress another's — if
+two angles flag the same line for different reasons, record both. If the Agent
+tool is not available in your current tool set, do not error — perform each
+angle (and each verification) yourself, sequentially, in this context.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Angle D — language-pitfall specialist
+
+Scan for the classic pitfalls of the diff's language/framework — for example:
+JS falsy-zero, `==` coercion, closure-captured loop var; Python mutable default
+args, late-binding closures; Go nil-map write, range-var capture; SQL injection;
+timezone/DST drift; float equality. Flag any instance the diff introduces.
+
+### Angle E — wrapper/proxy correctness
+
+When the PR adds or modifies a type that wraps another (cache, proxy, decorator,
+adapter): check that every method routes to the wrapped instance and not back
+through a registry/session/global — e.g. a caching provider holding a
+`delegate` field that resolves IDs via `session.get(...)` instead of
+`delegate.get(...)` will re-enter the cache or recurse. Also check that the
+wrapper forwards all the methods the callers actually use.
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings.
+
+## Phase 2 — Verify (1-vote, 3-state)
+
+Dedup candidates that point at the same line/mechanism, keeping the one with
+the most concrete failure scenario. For each remaining candidate, run **one
+verifier** via the Agent tool: give it the diff, the relevant
+file(s), and the candidate, and have it return exactly one of:
+
+- **CONFIRMED** — can name the inputs/state that trigger it and the wrong
+  output or crash. Quote the line.
+- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+  config). State what would confirm it.
+- **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
+  Quote the line that proves it.
+
+Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
+
+This is recall mode — a single non-REFUTED vote carries the finding. Do NOT
+drop on uncertainty.
+
+## Phase 3 — Sweep for gaps
+
+Run **one more finder** as a fresh reviewer who has the verified list. Re-read
+the diff and enclosing functions looking ONLY for defects not already listed.
+Do not re-derive or re-confirm anything already there — the job is gaps. Focus
+on what the first pass tends to miss: moved/extracted code that dropped a guard
+or anchor; second-tier footguns (dataclass default evaluated once, `hash()`
+non-determinism, lock-scope shrink, predicate methods with side effects);
+setup/teardown asymmetry in tests; config defaults flipped.
+
+Surface additional candidates, each naming a defect not already on the list.
+If nothing new, return an empty sweep — do not pad.
+
+## Output
+
+Report this review's results — `{level, findings}` — through the structured
+findings-report call: the mechanism that renders a review's results as a typed
+list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
+`summary`, `short_summary` — the claim compressed to ≤60 characters, no
+rationale or consequence clause — `failure_scenario`, and `category` — a short
+kebab-case slug for the angle that produced it (`correctness`,
+`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
+specific slug like `test-coverage` when one fits better) — plus `verdict` when
+a verify pass produced one. If nothing survives verification, make that call
+with an empty array. Do not also print the findings as text, and do not create
+or publish an artifact of the review — the structured call is the report.
+
+## 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 Phases 0–3, Output, 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 Output.

package/skills/e-simplify/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: e-simplify
+description: >-
+  Cleanup-only pass on the current diff — reuse, simplification, efficiency,
+  altitude — that fixes what it finds directly; no correctness-bug hunting.
+  Triggers: /e-simplify.
+---
+
+# e-simplify
+
+**Core principle:** Four parallel cleanup angles (reuse, simplification, efficiency, altitude) over the current diff, applied directly — not a bug hunt, and not a report.
+
+## Gotchas
+
+- This skill fixes code quality, not correctness. A request for bug-hunting belongs to `/e-code-review`, not here — see the refusal case below.
+- Applying a fix that changes intended behavior, or that reaches well outside the reviewed diff, is worse than leaving a flagged item unfixed — skip and note it instead of stretching the fix to cover it.
+
+## When this skill applies
+
+Triggers: `/e-simplify` on the current diff (or a PR/branch/path passed as an argument).
+
+**Refusal cases — first match wins:**
+
+- **Asked to find correctness bugs (crashes, wrong output, security issues) rather than cleanup.** Respond exactly: `That's a correctness review — use /e-code-review, not this skill.`
+
+## The process
+
+`/simplify → 4 cleanup agents in parallel → apply the fixes`
+
+You are improving the quality of the changed code, not hunting for bugs. Review
+it for reuse, simplification, efficiency, and altitude issues, then fix what you
+find. Do not look for correctness bugs — that is what `/code-review` is for.
+
+### Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+### Phase 1 — Review (4 cleanup agents in parallel)
+
+Launch **4 independent review agents** via the Agent tool, all in a
+single message so they run concurrently. Pass each agent the diff and one of
+the four angles below. Each returns its findings with `file`, `line`, a
+one-line `summary`, and the concrete cost (what is duplicated, wasted, or
+harder to maintain).
+
+#### Reuse
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+#### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+#### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+#### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Phase 2 — Apply the fixes
+
+Wait for all four agents to complete, dedup findings that point at the same
+line or mechanism, and fix each remaining one directly. Skip any finding whose
+fix would change intended behavior, require changes well outside the reviewed
+diff, or that you judge to be a false positive — note the skip rather than
+arguing with it. Finish with a brief summary of what was fixed and what was
+skipped (or confirm the code was already clean).
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This hub — the full cleanup procedure, refusal case |
+
+## Folder map
+
+- `SKILL.md` — hub: full procedure, refusal case.

package/skills/fresh-branch/CLAUDE.md

@@ -8,5 +8,7 @@ Creates a new branch from fresh-fetched `origin/main` inside an isolated worktre
 |---|---|
 | `SKILL.md` | Phases, checklist, execute-vs-read for the CLI, gotchas |
 | `scripts/create_fresh_branch.py` | Deterministic CLI: fetch base, `git worktree add -b`, JSON stdout |
+| `scripts/fresh_branch_git_commands.py` | Git command helpers: fetch, ref checks, `git worktree add -b --no-track` |
 | `scripts/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/test_fresh_branch_git_commands.py` | Behavioral tests for the git command helpers |
 | `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |

package/skills/fresh-branch/SKILL.md

@@ -113,7 +113,9 @@ Further edits for the new branch belong in `worktree_path`, not in the caller's
 | `SKILL.md` | This hub: phases, checklist, constraints, gotchas |
 | `CLAUDE.md` | Package map for agents browsing the skill folder |
 | `scripts/create_fresh_branch.py` | **Execute** — deterministic fetch + worktree branch CLI |
+| `scripts/fresh_branch_git_commands.py` | Git command helpers behind the CLI (fetch, ref checks, worktree add) |
 | `scripts/test_create_fresh_branch.py` | Real-repo tests for agent/path/CLI behavior |
+| `scripts/test_fresh_branch_git_commands.py` | Real-repo tests for the git command helpers |
 | `scripts/fresh_branch_scripts_constants/` | Named constants for the CLI |
 
 ## Folder map