claude-dev-env 2.0.1 → 2.1.0

package/skills/fresh-branch/SKILL.md

@@ -1,71 +1,122 @@
 ---
 name: fresh-branch
-description: Creates a fresh branch for the current repo based on origin main. Always fetches actual origin main rather than relying on local main. Suggests possible branch names via AskUserQuestion when context is available, or prompts the user to provide a name directly. Triggers on "fresh branch", "new branch from main", "/fresh-branch", "start fresh".
+description: >-
+  Fresh git branch from origin/main in an isolated temp worktree (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
 
-## Overview
-
-Creates a new branch from `origin/main` (always fresh-fetched, never stale local main). Designed as a shared primitive: other skills (e.g. gotcha) invoke `/fresh-branch` to create a clean branch for their own PR workflows.
+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.
 
 **Announce at start:** "Creating a fresh branch from origin/main."
 
-## Instructions
+## When this applies
+
+- User or caller wants a **new** branch based on current `origin/main`.
+- Caller needs the branch path/name as a return value for a later PR step.
+
+**Does not apply (refuse with the quoted line):**
 
-### Phase 1 — Fetch origin main
+- Switch to an existing branch → `Use git switch / checkout for an existing branch; /fresh-branch only creates new ones.`
+- Push or open a PR → `This skill only creates the branch worktree; push and PR are separate.`
 
-Always fetch `origin/main` directly. Do not rely on the local `main` branch, which may be stale.
+## Checklist
 
 ```
-git fetch origin main
+- [ ] Phase 1 — confirm repo context (cwd or --repo)
+- [ ] Phase 2 — resolve branch name (AskUserQuestion when needed)
+- [ ] Phase 3 — execute the create script; parse JSON
+- [ ] Phase 4 — report branch, worktree_path, base_commit; return to caller
 ```
 
-Confirm the fetch succeeded. If it fails (no network, no remote), report the error and stop.
+## Phase 1 — Repo context
 
-### Phase 2 — Determine branch name
+Work against the repository the user has open (or the path the caller names). The script resolves the git toplevel from `--repo` (default `.`). Do not invent a different clone.
 
-Branch names follow the repo's convention: lowercase, hyphen-separated, descriptive prefix.
+## Phase 2 — Branch name (high freedom)
 
-**When context is available (the caller or prior conversation provides a topic):**
+Branch names: lowercase, hyphen-separated, optional `prefix/description`.
 
-Suggest 2–4 branch names via `AskUserQuestion`. The suggestions should be short, descriptive, and follow the `prefix/description` or `description` convention visible in recent `git log` output.
-
-Poll recent branch naming patterns to inform suggestions:
+**When a topic is available:** suggest 2–4 names via `AskUserQuestion`. Poll recent remote names for local convention:
 
 ```
-git branch -r --sort=-committerdate | head -20
+git branch -r --sort=-committerdate
 ```
 
-**When no context is available:**
+(Take a short head of that list in the shell you use; do not require Unix `head`.)
+
+**When no topic:** ask for a name via `AskUserQuestion` (`multiSelect: false`, free-text option).
 
-Ask the user to provide a branch name directly via `AskUserQuestion` with `multiSelect: false` and a free-text option.
+## Phase 3 — Create branch (execute the script)
 
-### Phase 3 — Create the branch
+**Execute** the bundled CLI (do not reimplement with ad-hoc `git checkout -b`):
 
 ```
-git checkout -b <branch-name> origin/main
+python "${CLAUDE_SKILL_DIR}/scripts/create_fresh_branch.py" --branch-name "<name>"
 ```
 
-The `-b` flag creates the branch and checks it out. Basing on `origin/main` (not local `main`) guarantees the branch starts from the true latest state.
+Optional flags:
 
-Confirm success:
+| Flag | Role |
+|------|------|
+| `--repo <path>` | Source repo (default: current directory) |
+| `--agent <slug>` | Temp segment: `claude`, `grok`, `cursor`, `codex`, … |
+| `--base <ref>` | Base ref (default: `origin/main`) |
 
-```
-git rev-parse --abbrev-ref HEAD
-git log --oneline -1
-```
+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>`
+- If the path exists, the script suffixes `-2`, `-3`, …
 
-### Phase 4 — Report
+On exit 0, stdout is one JSON object:
 
-State the new branch name and its base commit. If invoked as a subroutine by another skill, return the branch name so the caller can proceed (e.g., creating a PR from it).
+| Field | Meaning |
+|-------|---------|
+| `branch` | Created branch name |
+| `worktree_path` | Absolute path of the new worktree |
+| `base_ref` | Base ref used |
+| `base_commit` | SHA at that ref after fetch |
+| `agent` | Host slug used in the path |
+| `repo_root` | Source repository root |
 
-## What this skill does NOT do
+On non-zero exit, stdout is `{"error": "..."}`. Report the error and stop. Do not fall back to `git checkout -b` in the caller tree.
 
-- Does not push the branch. The caller decides when and whether to push.
-- Does not create a PR. Use `gh pr create` separately.
-- Does not switch an existing branch. It always creates a new one.
+## Phase 4 — Report
+
+State `branch`, `worktree_path`, and `base_commit`. When invoked as a subroutine, return those fields so the caller can continue (for example open a PR from that worktree).
+
+Further edits for the new branch belong in `worktree_path`, not in the caller's original cwd.
+
+## Constraints
+
+- Never `git checkout -b` (or equivalent) in the caller's working tree.
+- Always fetch the base ref through the script (default `origin/main`).
+- Do not push. Do not open a PR.
+- Do not switch an existing branch; only create.
 
 ## Gotchas
 
-See the gotcha reference at the bottom of this file. When a new gotcha is discovered during use, invoke `/gotcha` to add it here.
+- **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.
+- **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.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `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/test_create_fresh_branch.py` | Real-repo tests for agent/path/CLI behavior |
+| `scripts/fresh_branch_scripts_constants/` | Named constants for the CLI |
+
+## Folder map
+
+- `scripts/` — executable CLI, tests, constants package
+- `scripts/fresh_branch_scripts_constants/` — importable `UPPER_SNAKE` values

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

@@ -0,0 +1,445 @@
+#!/usr/bin/env python3
+"""Create a fresh branch in an isolated git worktree under the agent scratch root.
+
+::
+
+    python create_fresh_branch.py --branch-name fix/example
+    {"branch": "fix/example", "worktree_path": "...", "base_ref": "origin/main",
+     "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`` into ``Temp/<agent>/<branch>`` (Windows) or
+``gettempdir()/<agent>/<branch>`` elsewhere. Exit 0 prints success JSON; any
+failure prints ``{"error": ...}`` and exits non-zero.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from fresh_branch_scripts_constants.fresh_branch_cli_constants import (
+    AGENT_SLUG_PATTERN,
+    ALL_AGENT_DETECTION_MARKERS,
+    ALL_WINDOWS_USER_SCRATCH_PARTS,
+    DEFAULT_AGENT_SLUG,
+    DEFAULT_BASE_REF,
+    ERROR_AGENT_SLUG_INVALID,
+    ERROR_BASE_COMMIT_LOOKUP,
+    ERROR_BASE_REF_MISSING,
+    ERROR_BRANCH_NAME_REQUIRED,
+    ERROR_BRANCH_NAME_UNSAFE,
+    ERROR_CLI_ARGUMENTS,
+    ERROR_FETCH_FAILED,
+    ERROR_REPO_NOT_GIT,
+    ERROR_UNIQUE_PATH_EXHAUSTED,
+    ERROR_WORKTREE_FAILED,
+    ERROR_WORKTREE_PATH_OUTSIDE_ROOT,
+    EXIT_CODE_FAILURE,
+    EXIT_CODE_SUCCESS,
+    FRESH_BRANCH_AGENT_ENV_VAR,
+    GIT_BRANCH_FLAG,
+    GIT_BRANCH_FORMAT_FLAG,
+    GIT_CHECK_REF_FORMAT,
+    GIT_COMMAND,
+    GIT_FETCH,
+    GIT_QUIET_FLAG,
+    GIT_REFS_REMOTES_PREFIX,
+    GIT_REMOTE_NAME_ORIGIN,
+    GIT_REMOTE_PREFIX,
+    GIT_REV_PARSE,
+    GIT_SHOW_REF,
+    GIT_SHOW_TOPLEVEL,
+    GIT_VERIFY_FLAG,
+    GIT_WORKTREE,
+    GIT_WORKTREE_ADD,
+    MAXIMUM_UNIQUE_PATH_ATTEMPTS,
+    PATH_SEGMENT_CURRENT,
+    PATH_SEGMENT_PARENT,
+    PAYLOAD_KEY_AGENT,
+    PAYLOAD_KEY_BASE_COMMIT,
+    PAYLOAD_KEY_BASE_REF,
+    PAYLOAD_KEY_BRANCH,
+    PAYLOAD_KEY_ERROR,
+    PAYLOAD_KEY_REPO_ROOT,
+    PAYLOAD_KEY_WORKTREE_PATH,
+    UNIQUE_PATH_SUFFIX_START,
+    USERPROFILE_ENV_VAR,
+    WINDOWS_PLATFORM_PREFIX,
+)
+
+
+def resolve_agent_slug(maybe_flag_agent: str | None) -> str:
+    """Return the short host label for the worktree path segment.
+
+    ::
+
+        resolve_agent_slug("Grok")  # ok: "grok" (flag wins)
+        # FRESH_BRANCH_AGENT=codex, no flag -> "codex"
+        # CURSOR_TRACE_ID set, no flag/env  -> "cursor"
+        # no flag, env, or markers          -> "claude"
+
+    Order: ``--agent`` flag, then ``FRESH_BRANCH_AGENT``, then the first set
+    marker in ``ALL_AGENT_DETECTION_MARKERS``, else ``DEFAULT_AGENT_SLUG``.
+
+    Args:
+        maybe_flag_agent: Explicit ``--agent`` value, or None.
+
+    Returns:
+        Lowercase agent slug safe for a single path segment.
+
+    Raises:
+        ValueError: When the resolved slug fails the path-safety pattern.
+    """
+    if maybe_flag_agent is not None and maybe_flag_agent.strip():
+        return _normalize_agent_slug(maybe_flag_agent)
+    explicit_agent = os.environ.get(FRESH_BRANCH_AGENT_ENV_VAR)
+    if explicit_agent is not None and explicit_agent.strip():
+        return _normalize_agent_slug(explicit_agent)
+    for each_env_name, each_agent_slug in ALL_AGENT_DETECTION_MARKERS:
+        maybe_marker = os.environ.get(each_env_name)
+        if maybe_marker is not None and str(maybe_marker).strip():
+            return each_agent_slug
+    return DEFAULT_AGENT_SLUG
+
+
+def resolve_agent_worktree_root(agent_slug: str) -> Path:
+    """Return ``Temp/<agent>`` on Windows USERPROFILE, else gettempdir root.
+
+    ::
+
+        # win32 + USERPROFILE=C:/Users/x -> C:/Users/x/AppData/Local/Temp/grok
+        resolve_agent_worktree_root("grok")
+
+    Args:
+        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
+
+
+def resolve_unique_worktree_path(preferred_path: Path) -> Path:
+    """Return preferred_path, or preferred_path-N when the path already exists.
+
+    ::
+
+        resolve_unique_worktree_path(Path("/tmp/claude/fix"))  # free path
+        # when /tmp/claude/fix exists -> /tmp/claude/fix-2
+
+    Args:
+        preferred_path: First-choice worktree directory.
+
+    Returns:
+        A path that does not exist yet.
+
+    Raises:
+        RuntimeError: When no free suffix remains within the attempt budget.
+    """
+    if not preferred_path.exists():
+        return preferred_path
+    for each_suffix in range(
+        UNIQUE_PATH_SUFFIX_START,
+        UNIQUE_PATH_SUFFIX_START + MAXIMUM_UNIQUE_PATH_ATTEMPTS,
+    ):
+        candidate_path = preferred_path.parent / f"{preferred_path.name}-{each_suffix}"
+        if not candidate_path.exists():
+            return candidate_path
+    raise RuntimeError(ERROR_UNIQUE_PATH_EXHAUSTED % preferred_path)
+
+
+def normalize_base_ref(base_ref: str) -> str:
+    """Return a remote-tracking ref for bare branch names.
+
+    ::
+
+        normalize_base_ref("main")         # ok: "origin/main"
+        normalize_base_ref("origin/main")  # ok: "origin/main"
+        normalize_base_ref("upstream/dev") # ok: "upstream/dev"
+
+    Bare names expand to ``origin/<name>`` so worktree start-points use the
+    remote-tracking tip that ``git fetch`` updates, not a stale local branch.
+
+    Args:
+        base_ref: User-supplied base ref or bare branch name.
+
+    Returns:
+        Normalized ref used for fetch, commit lookup, and worktree add.
+    """
+    cleaned_base_ref = base_ref.strip()
+    if not cleaned_base_ref:
+        return DEFAULT_BASE_REF
+    if "/" not in cleaned_base_ref:
+        return f"{GIT_REMOTE_PREFIX}{cleaned_base_ref}"
+    return cleaned_base_ref
+
+
+def create_fresh_branch(
+    branch_name: str,
+    repo_path: Path,
+    agent_slug: str,
+    base_ref: str,
+) -> dict[str, str]:
+    """Fetch base_ref and create an isolated worktree branch.
+
+    ::
+
+        create_fresh_branch("fix/x", Path("."), "grok", "origin/main")
+        # ok: worktree at Temp/grok/fix/x; source checkout stays on its branch
+
+    Args:
+        branch_name: New branch to create.
+        repo_path: Path inside the source repository.
+        agent_slug: Host label for the scratch root segment.
+        base_ref: Base ref (default ``origin/main``).
+
+    Returns:
+        Success payload mapping.
+
+    Raises:
+        ValueError: When branch_name is empty or path-unsafe, or agent_slug
+            fails the path-safety pattern.
+        RuntimeError: On git or path failures.
+    """
+    cleaned_branch = branch_name.strip()
+    if not cleaned_branch:
+        raise ValueError(ERROR_BRANCH_NAME_REQUIRED)
+    _validate_branch_name_for_worktree_path(cleaned_branch)
+    normalized_agent_slug = _normalize_agent_slug(agent_slug)
+    resolved_base_ref = normalize_base_ref(base_ref)
+    repo_root = _resolve_repo_root(repo_path)
+    _fetch_base_ref(repo_root, resolved_base_ref)
+    base_commit = _resolve_base_commit(repo_root, resolved_base_ref)
+    agent_worktree_root = resolve_agent_worktree_root(normalized_agent_slug)
+    preferred_path = agent_worktree_root / cleaned_branch
+    _assert_path_is_under_agent_root(
+        candidate_path=preferred_path,
+        agent_worktree_root=agent_worktree_root,
+    )
+    worktree_path = resolve_unique_worktree_path(preferred_path)
+    _assert_path_is_under_agent_root(
+        candidate_path=worktree_path,
+        agent_worktree_root=agent_worktree_root,
+    )
+    _create_worktree_branch(
+        repo_root,
+        branch_name=cleaned_branch,
+        worktree_path=worktree_path,
+        base_ref=resolved_base_ref,
+    )
+    return {
+        PAYLOAD_KEY_BRANCH: cleaned_branch,
+        PAYLOAD_KEY_WORKTREE_PATH: str(worktree_path.resolve()),
+        PAYLOAD_KEY_BASE_REF: resolved_base_ref,
+        PAYLOAD_KEY_BASE_COMMIT: base_commit,
+        PAYLOAD_KEY_AGENT: normalized_agent_slug,
+        PAYLOAD_KEY_REPO_ROOT: str(repo_root),
+    }
+
+
+def main() -> int:
+    """CLI entry: create worktree branch and print JSON to stdout.
+
+    Returns:
+        Process exit code (0 success, 1 failure).
+    """
+    try:
+        parsed_arguments = _parse_arguments()
+        agent_slug = resolve_agent_slug(parsed_arguments.agent)
+        success_payload = create_fresh_branch(
+            branch_name=parsed_arguments.branch_name,
+            repo_path=Path(parsed_arguments.repo).resolve(),
+            agent_slug=agent_slug,
+            base_ref=parsed_arguments.base,
+        )
+        print(json.dumps(success_payload))
+        return EXIT_CODE_SUCCESS
+    except (ValueError, RuntimeError, OSError) as error:
+        print(json.dumps({PAYLOAD_KEY_ERROR: str(error)}))
+        return EXIT_CODE_FAILURE
+
+
+def _normalize_agent_slug(raw_agent: str) -> str:
+    agent_slug = raw_agent.strip().lower()
+    if re.fullmatch(AGENT_SLUG_PATTERN, agent_slug) is None:
+        raise ValueError(ERROR_AGENT_SLUG_INVALID)
+    return agent_slug
+
+
+def _validate_branch_name_for_worktree_path(branch_name: str) -> None:
+    branch_as_path = Path(branch_name)
+    if branch_as_path.is_absolute():
+        raise ValueError(ERROR_BRANCH_NAME_UNSAFE)
+    for each_segment in branch_as_path.parts:
+        if each_segment in (PATH_SEGMENT_CURRENT, PATH_SEGMENT_PARENT):
+            raise ValueError(ERROR_BRANCH_NAME_UNSAFE)
+    _assert_git_accepts_branch_name(branch_name)
+
+
+def _assert_git_accepts_branch_name(branch_name: str) -> None:
+    completed = _run_git(
+        [GIT_CHECK_REF_FORMAT, GIT_BRANCH_FORMAT_FLAG, branch_name],
+        working_directory=Path.cwd(),
+    )
+    if completed.returncode != 0:
+        raise ValueError(ERROR_BRANCH_NAME_UNSAFE)
+
+
+def _assert_path_is_under_agent_root(
+    candidate_path: Path,
+    agent_worktree_root: Path,
+) -> None:
+    resolved_candidate = candidate_path.resolve()
+    resolved_root = agent_worktree_root.resolve()
+    if resolved_candidate == resolved_root:
+        return
+    try:
+        resolved_candidate.relative_to(resolved_root)
+    except ValueError as error:
+        raise ValueError(
+            ERROR_WORKTREE_PATH_OUTSIDE_ROOT % candidate_path,
+        ) from error
+
+
+def _resolve_repo_root(repo_path: Path) -> Path:
+    completed = _run_git(
+        [GIT_REV_PARSE, GIT_SHOW_TOPLEVEL],
+        working_directory=repo_path,
+    )
+    if completed.returncode != 0:
+        raise RuntimeError(ERROR_REPO_NOT_GIT % repo_path)
+    return Path(completed.stdout.strip())
+
+
+def _fetch_base_ref(repo_root: Path, base_ref: str) -> None:
+    remote_name, remote_branch = _split_remote_ref(base_ref)
+    completed = _run_git(
+        [GIT_FETCH, remote_name, remote_branch],
+        working_directory=repo_root,
+    )
+    if completed.returncode != 0:
+        stderr_text = completed.stderr.strip() or completed.stdout.strip()
+        raise RuntimeError(ERROR_FETCH_FAILED % (base_ref, stderr_text))
+    if not _is_ref_present(repo_root, base_ref):
+        raise RuntimeError(ERROR_BASE_REF_MISSING % base_ref)
+
+
+def _resolve_base_commit(repo_root: Path, base_ref: str) -> str:
+    completed = _run_git(
+        [GIT_REV_PARSE, base_ref],
+        working_directory=repo_root,
+    )
+    if completed.returncode != 0:
+        stderr_text = completed.stderr.strip() or completed.stdout.strip()
+        raise RuntimeError(ERROR_BASE_COMMIT_LOOKUP % (base_ref, stderr_text))
+    return completed.stdout.strip()
+
+
+def _create_worktree_branch(
+    repo_root: Path,
+    branch_name: str,
+    worktree_path: Path,
+    base_ref: str,
+) -> None:
+    worktree_path.parent.mkdir(parents=True, exist_ok=True)
+    completed = _run_git(
+        [
+            GIT_WORKTREE,
+            GIT_WORKTREE_ADD,
+            GIT_BRANCH_FLAG,
+            branch_name,
+            str(worktree_path),
+            base_ref,
+        ],
+        working_directory=repo_root,
+    )
+    if completed.returncode != 0:
+        stderr_text = completed.stderr.strip() or completed.stdout.strip()
+        raise RuntimeError(ERROR_WORKTREE_FAILED % stderr_text)
+
+
+def _parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Create a fresh branch in an isolated git worktree.",
+    )
+    parser.add_argument(
+        "--branch-name",
+        required=True,
+        help="Name of the new branch to create.",
+    )
+    parser.add_argument(
+        "--repo",
+        default=".",
+        help="Path inside the source repository (default: current directory).",
+    )
+    parser.add_argument(
+        "--agent",
+        default=None,
+        help="Host label for Temp/<agent>/ (default: detect from environment).",
+    )
+    parser.add_argument(
+        "--base",
+        default=DEFAULT_BASE_REF,
+        help=f"Base ref to fetch and branch from (default: {DEFAULT_BASE_REF}).",
+    )
+    try:
+        return parser.parse_args()
+    except SystemExit as exit_error:
+        if exit_error.code in (EXIT_CODE_SUCCESS, None):
+            raise
+        raise ValueError(ERROR_CLI_ARGUMENTS) from exit_error
+
+
+def _split_remote_ref(base_ref: str) -> tuple[str, str]:
+    if base_ref.startswith(GIT_REMOTE_PREFIX):
+        return GIT_REMOTE_NAME_ORIGIN, base_ref[len(GIT_REMOTE_PREFIX) :]
+    if "/" in base_ref:
+        remote_name, remote_branch = base_ref.split("/", 1)
+        return remote_name, remote_branch
+    return GIT_REMOTE_NAME_ORIGIN, base_ref
+
+
+def _is_ref_present(repo_root: Path, base_ref: str) -> bool:
+    remote_ref = f"{GIT_REFS_REMOTES_PREFIX}{base_ref}"
+    completed = _run_git(
+        [GIT_SHOW_REF, GIT_VERIFY_FLAG, GIT_QUIET_FLAG, remote_ref],
+        working_directory=repo_root,
+    )
+    if completed.returncode == 0:
+        return True
+    completed = _run_git(
+        [GIT_REV_PARSE, GIT_VERIFY_FLAG, GIT_QUIET_FLAG, base_ref],
+        working_directory=repo_root,
+    )
+    return completed.returncode == 0
+
+
+def _run_git(
+    all_git_arguments: list[str],
+    working_directory: Path,
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        [GIT_COMMAND, *all_git_arguments],
+        cwd=str(working_directory),
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1 @@
+"""Named constants for the fresh-branch skill scripts."""

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

@@ -0,0 +1,74 @@
+"""Constants for the fresh-branch worktree creator.
+
+Groups: default refs, agent detection, path layout, JSON payload keys,
+exit codes, and unique-path suffix limits.
+"""
+
+from __future__ import annotations
+
+DEFAULT_BASE_REF = "origin/main"
+DEFAULT_AGENT_SLUG = "claude"
+FRESH_BRANCH_AGENT_ENV_VAR = "FRESH_BRANCH_AGENT"
+
+ALL_AGENT_DETECTION_MARKERS: tuple[tuple[str, str], ...] = (
+    ("CURSOR_AGENT", "cursor"),
+    ("CURSOR_TRACE_ID", "cursor"),
+    ("CODEX_HOME", "codex"),
+    ("CODEX_CI", "codex"),
+    ("GROK_AGENT", "grok"),
+    ("CLAUDECODE", "claude"),
+    ("CLAUDE_CODE_ENTRYPOINT", "claude"),
+)
+
+PATH_SEGMENT_CURRENT = "."
+PATH_SEGMENT_PARENT = ".."
+
+WINDOWS_PLATFORM_PREFIX = "win"
+ALL_WINDOWS_USER_SCRATCH_PARTS = ("AppData", "Local", "Temp")
+USERPROFILE_ENV_VAR = "USERPROFILE"
+
+MAXIMUM_UNIQUE_PATH_ATTEMPTS = 100
+UNIQUE_PATH_SUFFIX_START = 2
+
+PAYLOAD_KEY_BRANCH = "branch"
+PAYLOAD_KEY_WORKTREE_PATH = "worktree_path"
+PAYLOAD_KEY_BASE_REF = "base_ref"
+PAYLOAD_KEY_BASE_COMMIT = "base_commit"
+PAYLOAD_KEY_AGENT = "agent"
+PAYLOAD_KEY_REPO_ROOT = "repo_root"
+PAYLOAD_KEY_ERROR = "error"
+
+EXIT_CODE_SUCCESS = 0
+EXIT_CODE_FAILURE = 1
+
+GIT_COMMAND = "git"
+GIT_FETCH = "fetch"
+GIT_REV_PARSE = "rev-parse"
+GIT_SHOW_REF = "show-ref"
+GIT_WORKTREE = "worktree"
+GIT_WORKTREE_ADD = "add"
+GIT_BRANCH_FLAG = "-b"
+GIT_VERIFY_FLAG = "--verify"
+GIT_QUIET_FLAG = "--quiet"
+GIT_SHOW_TOPLEVEL = "--show-toplevel"
+GIT_CHECK_REF_FORMAT = "check-ref-format"
+GIT_BRANCH_FORMAT_FLAG = "--branch"
+GIT_REMOTE_PREFIX = "origin/"
+GIT_REFS_REMOTES_PREFIX = "refs/remotes/"
+GIT_REMOTE_NAME_ORIGIN = "origin"
+
+ERROR_BRANCH_NAME_REQUIRED = "branch name is required"
+ERROR_BRANCH_NAME_UNSAFE = (
+    "branch name must be a relative path without '.' or '..' segments"
+)
+ERROR_WORKTREE_PATH_OUTSIDE_ROOT = "worktree path escapes agent root: %s"
+ERROR_CLI_ARGUMENTS = "invalid or missing command-line arguments"
+ERROR_AGENT_SLUG_INVALID = "agent slug must be lowercase letters, digits, or hyphens"
+ERROR_REPO_NOT_GIT = "path is not inside a git repository: %s"
+ERROR_BASE_REF_MISSING = "base ref not found after fetch: %s"
+ERROR_FETCH_FAILED = "git fetch failed for %s: %s"
+ERROR_WORKTREE_FAILED = "git worktree add failed: %s"
+ERROR_UNIQUE_PATH_EXHAUSTED = "could not allocate a unique worktree path under %s"
+ERROR_BASE_COMMIT_LOOKUP = "could not resolve base commit for %s: %s"
+
+AGENT_SLUG_PATTERN = r"^[a-z0-9]+(?:-[a-z0-9]+)*$"