claude-dev-env 2.0.2 → 2.2.0

package/skills/copilot-review/templates/subagent-prompt.md

@@ -0,0 +1,49 @@
+# Copilot-review subagent prompt template
+
+The background watcher prompt for the `copilot-review` skill. The hub
+([`../SKILL.md`](../SKILL.md) Step 3) passes the fenced block below to the
+subagent word for word, with the bracketed values ([NUMBER], [OWNER], [REPO],
+[BRANCH], [HEAD_SHA]) filled in from Step 1.
+
+```text
+You are babysitting the GitHub Copilot reviewer on PR **#[NUMBER]** at **[OWNER]/[REPO]** (branch `[BRANCH]`, current HEAD `[HEAD_SHA]`). Your job: keep the loop running until Copilot returns a clean review against the current HEAD, then stop.
+
+**Per-tick work** (do this now, then on each wakeup):
+
+1. Resolve current HEAD: `pull_request_read(method="get", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")` and extract `.head.sha`.
+2. Fetch latest Copilot review via `pull_request_read(method="get_reviews", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]")`.
+   Capture `commit_id`, `state`, `submitted_at`, `id`.
+3. Decide the branch:
+   - **No review exists:** increment `no_review_count` (see escalation rule below), re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` != current HEAD:** increment `no_review_count`, re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` == current HEAD with unresolved inline findings:** reset `no_review_count` to 0, TDD-fix them, push, reply inline on each thread, resolve each addressed thread, re-request (step 4), schedule next wakeup, return.
+   - **Latest review's `commit_id` == current HEAD and clean:** report convergence to the parent with a one-sentence summary and terminate. The loop is done; skip the ScheduleWakeup call.
+
+   **Escalation rule:** `no_review_count` starts at 0, counts consecutive ticks where no Copilot review exists at the current HEAD, and resets to 0 on every push and every review sighted at HEAD. When it reaches 3, Copilot is not delivering reviews — report the stall to the parent with the count and the last request timestamp, then terminate without scheduling another wakeup.
+4. Re-request Copilot via `request_copilot_review(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER])`.
+   The reviewer ID **must** be `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix — empirically verified: `Copilot`, `copilot`, and `github-copilot` all return `requested_reviewers: []` with no error, silently no-op.
+5. Schedule the next wakeup with `ScheduleWakeup`:
+   - `delaySeconds: 360`
+   - `reason`: one short sentence on what you are waiting for.
+   - `prompt`: the literal sentinel `<<autonomous-loop-dynamic>>` so the next firing re-enters these instructions.
+
+**Fix protocol** (step 3, third branch):
+
+- Read `$HOME/.claude/skills/pr-fix-protocol/SKILL.md` and apply it — it carries the shared fix sequence, the reply-and-resolve unit, and the unresolved-thread sweep.
+- Read each referenced file:line.
+- Write a failing test first when the finding has behavior to test. For pure doc or comment nits that have no behavior, go straight to the fix.
+- Stage the fix and create one new commit on the existing branch: `git add <files> && git commit -m "fix(review): ..."`.
+- Push the new commit: `git push origin [BRANCH]`.
+- Reply inline via `add_reply_to_pull_request_comment(owner="[OWNER]", repo="[REPO]", pullNumber=[NUMBER], body="...", commentId=<comment_id>)`, referencing the new commit SHA; then resolve each addressed thread via `pull_request_review_write(method="resolve_thread", pullNumber=[NUMBER], owner="[OWNER]", repo="[REPO]", threadId="<PRRT id>")`, harvesting the `PRRT_…` id from `pull_request_read(method="get_review_comments", ...)`. Reply first, then resolve — atomic per thread, per the protocol.
+
+When a pre-push, pre-commit, or other hook rejects the change, solve it. Read the hook's error message, diagnose the root cause in the code or test, and fix that. Then rerun the commit or push. Hooks exist to catch real problems; treat each rejection as new evidence to act on.
+
+**Stop conditions:**
+
+- Convergence (clean review against HEAD): report one-sentence summary to parent and terminate.
+- Blocker you have exhausted fix attempts on (API auth failure persists, CI regression whose root cause falls outside this PR, a hook you have investigated and cannot resolve in one commit): report the specific blocker and its diagnosis to the parent, then terminate without scheduling another wakeup.
+- Parent sends `TaskStop`: terminate immediately.
+- `no_review_count` reaches 3 (escalation rule above): report the stall and terminate.
+
+**Safety cap:** after 20 ticks without convergence, stop and report. This is the total-tick runaway guard, distinct from the 3-consecutive-no-review escalation; that many rounds means something structural is wrong with the loop.
+```

package/skills/fresh-branch/CLAUDE.md

@@ -1,15 +1,12 @@
 # fresh-branch
 
-Creates a new branch from `origin/main` (always fresh-fetched). Triggered by `fresh branch`, `new branch from main`, `/fresh-branch`, or `start fresh`.
+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.
 
-## Purpose
-
-A shared primitive used by other skills and directly by the user. Fetches `origin/main`, suggests 2–4 branch names via `AskUserQuestion` when a topic is available (polling recent branch naming patterns from `git branch -r`), then creates and checks out the branch with `git checkout -b <name> origin/main`.
-
-Does not push the branch. Does not create a PR. Does not switch an existing branch. Callers that need the new branch name (for example, to open a PR) receive it as a return value.
-
-## Key file
+## Key files
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Four-phase instructions: fetch `origin/main`, pick branch name (suggest or prompt), create branch, report. Includes gotchas discovered during use. |
+| `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/test_create_fresh_branch.py` | Behavioral tests with temporary git repos |
+| `scripts/fresh_branch_scripts_constants/` | Constants package (`fresh_branch_cli_constants`) for the CLI |

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."""