claude-dev-env 2.4.0 → 2.7.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

@@ -1,6 +1,6 @@
 # fresh-branch
 
-Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under `Temp/<agent>/<branch-name>`. Does not push, open a PR, or run `checkout -b` in the caller tree.
+Creates a new branch from fresh-fetched `origin/main` inside an isolated worktree under `<repo-root>/.claude/worktrees/<agent>/<branch-name>`. Does not push, open a PR, or run `checkout -b` in the caller tree.
 
 ## Key files
 

package/skills/fresh-branch/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: fresh-branch
 description: >-
-  Fresh git branch from origin/main in an isolated temp worktree (never checkout -b in the caller tree).
+  Fresh git branch from origin/main in an isolated worktree under the repo's .claude/worktrees/ (never checkout -b in the caller tree).
   Triggers: fresh branch, new branch from main, /fresh-branch, start fresh, clean branch off main,
   worktree branch, branch in temp.
 ---
 
 # fresh-branch
 
-Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under the agent temp root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
+Creates a new branch from a fresh-fetched `origin/main` inside an isolated git worktree under the repository's `.claude/worktrees/<agent>/` root. Shared primitive: other skills invoke `/fresh-branch` when they need a clean branch without touching the caller's dirty tree.
 
 **Announce at start:** "Creating a fresh branch from origin/main."
 
@@ -62,15 +62,14 @@ Optional flags:
 | Flag | Role |
 |------|------|
 | `--repo <path>` | Source repo (default: current directory) |
-| `--agent <slug>` | Temp segment: `claude`, `grok`, `cursor`, `codex`, … |
+| `--agent <slug>` | Worktree-root segment: `claude`, `grok`, `cursor`, `codex`, … |
 | `--base <ref>` | Base ref (default: `origin/main`) |
 
 Agent resolution inside the script: `--agent` → `FRESH_BRANCH_AGENT` env → host markers → `claude`.
 
 Worktree path:
 
-- Windows: `${USERPROFILE}/AppData/Local/Temp/<agent>/<branch-name>`
-- Else: `${tmpdir}/<agent>/<branch-name>`
+- `<repo-root>/.claude/worktrees/<agent>/<branch-name>`, on every platform
 - If the path exists, the script suffixes `-2`, `-3`, …
 
 On exit 0, stdout is one JSON object:
@@ -101,7 +100,7 @@ Further edits for the new branch belong in `worktree_path`, not in the caller's
 
 ## Gotchas
 
-- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `Temp/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
+- **Dirty caller cwd blocks `checkout -b` and pollutes the tree.** Phase 3 always uses `git worktree add -b` into `<repo-root>/.claude/worktrees/<agent>/…`. If you reconstruct Phase 3 by hand with `checkout -b` in the session cwd, local modifications block the checkout and leave the user on a half-switched branch.
 - **Caller HEAD must stay put.** After success, the original repo's checked-out branch and dirty files are unchanged; only the new worktree has the new branch.
 - **Branch name collision.** If the branch already exists, the script exits non-zero with `{"error":...}`. Pick a new name; do not delete remote branches unless the user asks.
 - **Path already occupied.** A leftover folder at the preferred worktree path gets a numeric suffix (`-2`, …); report the path from JSON, not the path you assumed.

package/skills/fresh-branch/scripts/create_fresh_branch.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create a fresh branch in an isolated git worktree under the agent scratch root.
+"""Create a fresh branch in an isolated git worktree under the repository.
 
 ::
 
@@ -8,9 +8,9 @@
      "base_commit": "abc...", "agent": "claude", "repo_root": "..."}
 
 Never runs ``git checkout -b`` in the caller's working tree. Fetches the base
-ref, then ``git worktree add -b --no-track`` into ``Temp/<agent>/<branch>``
-(Windows) or ``gettempdir()/<agent>/<branch>`` elsewhere. Exit 0 prints success
-JSON; any failure prints ``{"error": ...}`` and exits non-zero.
+ref, then ``git worktree add -b --no-track`` into
+``<repo-root>/.claude/worktrees/<agent>/<branch>``. Exit 0 prints success JSON;
+any failure prints ``{"error": ...}`` and exits non-zero.
 """
 
 from __future__ import annotations
@@ -20,7 +20,6 @@ import json
 import os
 import re
 import sys
-import tempfile
 from pathlib import Path
 
 from fresh_branch_git_commands import (
@@ -33,7 +32,7 @@ from fresh_branch_git_commands import (
 from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     AGENT_SLUG_PATTERN,
     ALL_AGENT_DETECTION_MARKERS,
-    ALL_WINDOWS_USER_SCRATCH_PARTS,
+    ALL_REPOSITORY_WORKTREE_ROOT_PARTS,
     DEFAULT_AGENT_SLUG,
     DEFAULT_BASE_REF,
     ERROR_AGENT_SLUG_INVALID,
@@ -57,8 +56,6 @@ from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
     PAYLOAD_KEY_REPO_ROOT,
     PAYLOAD_KEY_WORKTREE_PATH,
     UNIQUE_PATH_SUFFIX_START,
-    USERPROFILE_ENV_VAR,
-    WINDOWS_PLATFORM_PREFIX,
 )
 
 
@@ -94,28 +91,26 @@ def _detect_agent_slug_from_environment() -> str:
     return DEFAULT_AGENT_SLUG
 
 
-def resolve_agent_worktree_root(agent_slug: str) -> Path:
-    """Return ``Temp/<agent>`` on Windows USERPROFILE, else gettempdir root.
+def resolve_agent_worktree_root(repo_root: Path, agent_slug: str) -> Path:
+    """Return the repository's per-agent worktree root.
 
     ::
 
-        # win32 + USERPROFILE=C:/Users/x -> C:/Users/x/AppData/Local/Temp/grok
-        resolve_agent_worktree_root("grok")
+        # repo_root=/srv/app, agent_slug=grok
+        resolve_agent_worktree_root(Path("/srv/app"), "grok")
+        # -> /srv/app/.claude/worktrees/grok
+
+    Every worktree sits under the repository it branches from, so a worktree
+    travels with its repository and each agent keeps its own subdirectory.
 
     Args:
+        repo_root: Absolute path of the repository the branch comes from.
         agent_slug: Short host label (one path segment).
 
     Returns:
         Directory that should hold per-branch worktree folders.
     """
-    if sys.platform.startswith(WINDOWS_PLATFORM_PREFIX):
-        user_profile = os.environ.get(USERPROFILE_ENV_VAR)
-        if user_profile:
-            return Path(user_profile).joinpath(
-                *ALL_WINDOWS_USER_SCRATCH_PARTS,
-                agent_slug,
-            )
-    return Path(tempfile.gettempdir()) / agent_slug
+    return repo_root.joinpath(*ALL_REPOSITORY_WORKTREE_ROOT_PARTS, agent_slug)
 
 
 def resolve_unique_worktree_path(preferred_path: Path) -> Path:
@@ -181,13 +176,33 @@ def create_fresh_branch(
     ::
 
         create_fresh_branch("fix/x", Path("."), "grok", "origin/main")
+
+    The caller's working tree is never checked out. The worktree lands under
+    the repository's ``.claude/worktrees/<agent>/<branch>``, suffixed ``-2``,
+    ``-3``, … when that path is already taken.
+
+    Args:
+        branch_name: Branch to create; must be a safe relative path.
+        repo_path: Any path inside the repository the branch comes from.
+        agent_slug: Short host label naming the worktree-root subdirectory.
+        base_ref: Ref the branch starts from, such as ``origin/main``.
+
+    Returns:
+        The success payload: branch, worktree_path, base_ref, base_commit,
+        agent, and repo_root.
+
+    Raises:
+        ValueError: When the branch name or the agent slug is unsafe.
+        RuntimeError: When git refuses the fetch or the worktree add.
     """
     cleaned_branch = _require_safe_branch_name(branch_name)
     normalized_agent_slug = _normalize_agent_slug(agent_slug)
     resolved_base_ref, repo_root, base_commit = _resolve_branch_base(
         repo_path, base_ref,
     )
-    worktree_path = _allocate_worktree_path(cleaned_branch, normalized_agent_slug)
+    worktree_path = _allocate_worktree_path(
+        cleaned_branch, normalized_agent_slug, repo_root,
+    )
     create_worktree_branch(
         repo_root,
         branch_name=cleaned_branch,
@@ -241,8 +256,11 @@ def _require_safe_branch_name(branch_name: str) -> str:
     return cleaned_branch
 
 
-def _allocate_worktree_path(branch_name: str, agent_slug: str) -> Path:
-    agent_worktree_root = resolve_agent_worktree_root(agent_slug)
+def _allocate_worktree_path(
+    branch_name: str, agent_slug: str, repo_root: Path,
+) -> Path:
+    agent_worktree_root = resolve_agent_worktree_root(repo_root, agent_slug)
+    agent_worktree_root.mkdir(parents=True, exist_ok=True)
     preferred_path = agent_worktree_root / branch_name
     _assert_path_is_under_agent_root(
         candidate_path=preferred_path,
@@ -324,7 +342,7 @@ def _parse_arguments() -> argparse.Namespace:
     parser.add_argument(
         "--agent",
         default=None,
-        help="Host label for Temp/<agent>/ (default: detect from environment).",
+        help="Host label for .claude/worktrees/<agent>/ (default: detect from environment).",
     )
     parser.add_argument(
         "--base",

package/skills/fresh-branch/scripts/fresh_branch_scripts_constants/fresh_branch_cli_constants.py

@@ -23,9 +23,7 @@ ALL_AGENT_DETECTION_MARKERS: tuple[tuple[str, str], ...] = (
 PATH_SEGMENT_CURRENT = "."
 PATH_SEGMENT_PARENT = ".."
 
-WINDOWS_PLATFORM_PREFIX = "win"
-ALL_WINDOWS_USER_SCRATCH_PARTS = ("AppData", "Local", "Temp")
-USERPROFILE_ENV_VAR = "USERPROFILE"
+ALL_REPOSITORY_WORKTREE_ROOT_PARTS = (".claude", "worktrees")
 
 MAXIMUM_UNIQUE_PATH_ATTEMPTS = 100
 UNIQUE_PATH_SUFFIX_START = 2