claude-dev-env 2.5.0 → 2.7.0

package/skills/condensing-instructions/SKILL.md

@@ -1,81 +1,72 @@
 ---
 name: condensing-instructions
 description: >-
-  Rewrite existing instruction documents or turn first drafts and requirements
-  into compact, high-information operational instructions without changing or
-  inventing their contract. Use for prompts, skills, policies, runbooks,
-  agent-facing documents, reference instructions, token reduction,
-  deduplication, restructuring, or concise instruction authoring.
+  Refine an instruction document for Claude 5 generation models: cut rules the
+  model's judgment already covers, move detail behind progressive disclosure,
+  and route each remaining piece to the system prompt, CLAUDE.md, a skill, or a
+  reference. Use for system prompts, CLAUDE.md files, skills, tool
+  descriptions, agent instructions, context engineering, prompt slimming, and
+  token reduction.
 ---
 
 # Condensing Instructions
 
-Rewrite an existing instruction document or turn a first draft, notes, or requirements into compact operational instructions. Preserve behavior; reduce length only after the contract is complete and unambiguous.
+Cut an instruction document to what a Claude 5 generation model needs, and move the rest to the surface that loads it on demand. Over 80% of Claude Code's system prompt came out for Claude Opus 5 and Claude Fable 5 with no measurable drop in performance, so treat a long instruction document as a place with room to cut.
 
-## Preserve the full contract
+## Clear the conflicts first
 
-Treat every execution-relevant detail as binding: required, prohibited, and permitted behavior; safety and authority boundaries; actors, objects, data or resource kinds, and scope; force, negation, and quantifiers; triggers, defaults, conditions, exceptions, thresholds, and precedence; dependencies, prerequisites, order, timing, duration, persistence, and state; failure and recovery behavior; exact strings, names, paths, URLs, identifiers, commands, flags, numbers, placeholders, schemas, and error text; and input, output, formatting, validation, acceptance, and completion requirements.
+Read the system prompt, the CLAUDE.md, and the skills as one body of text and find the lines that pull against each other — "leave documentation as appropriate" sitting beside "DO NOT add comments". A conflict makes the model deliberate at length before it acts. Resolve each pair into one statement, or delete both when neither changes what the model does.
 
-Keep rationale or examples only when they define a decision, boundary, exception, exact value, or required behavior. Preserve required frontmatter, tags, wrappers, templates, schemas, and other machine-read structure.
+## Trade rules for judgment
 
-When rewriting, change wording and structure, not behavior. When authoring, supply organization, wording, and conventional editorial choices, but do not invent material obligations, permissions, exceptions, or defaults. Ask one concise blocking question when missing, contradictory, or ambiguous information would materially change behavior, safety, authority, scope, precedence, failure handling, or output. Otherwise proceed.
+Delete a rule written to block a worst case, such as file deletion. Claude 5 generation models read the surrounding context and decide well without it, and a rigid rule blocks the user who has a real reason to want the behavior it forbids.
 
-If no instruction material or requirements are provided, respond exactly: `Provide the instructions or draft requirements.`
+State the outcome and the signal the model should read:
 
-## Build a requirement ledger first
+- Cut: "Default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max. Don't create planning, decision, or analysis documents unless the user asks for them."
+- Keep: "Write code that reads like the surrounding code: match its comment density, naming, and idiom."
 
-Before deleting, merging, or drafting text, record each atomic commitment internally. Capture its force, actor, trigger, action, object or type, required outcome, scope, timing or persistence, dependencies, defaults, exceptions, precedence, failure behavior, and exact literals when applicable.
+## Design the interface in place of examples
 
-For an existing document, inventory every behaviorally meaningful statement. Distinguish true duplicates from similar rules that apply to different actors, stages, conditions, or scopes. For a first draft, translate each stated goal into observable behavior or an acceptance condition; mark material gaps instead of silently choosing an answer. Do not promote a preference to a hard rule or average conflicting rules.
+Examples constrain exploration. Carry usage in the tool's own shape: expressive names, expressive parameters, and types that signal intent. A status parameter enumerated as `pending`, `in_progress`, `completed` shows correct use with no example attached.
 
-Do not expose the ledger unless requested.
+## Load detail at the point of use
 
-## Group rules by the decisions they control
+Move detail out of always-on text and into a surface the model reaches for:
 
-- Group requirements by function or decision point, not by draft order.
-- Default to this sequence when it fits: purpose and scope; inputs and prerequisites; operating defaults; procedures and branches; constraints and safety; outputs and failures; verification. Override it when dependencies require another sequence.
-- Place a safety rule or other constraint before the first action it governs.
-- Within a group, put prerequisites before actions, general rules before narrow exceptions, and production requirements before their checks.
-- Put each exception beside the rule it modifies. State precedence when rules overlap.
-- Give each rule one authoritative location. State a shared actor, condition, default, or scope once at the narrowest level that covers every affected rule.
-- Let a heading carry scope only when every instruction beneath it clearly inherits that scope. Use the fewest headings that preserve navigation.
+- A skill the model calls when the task calls for it. Code review and verification detail belongs here.
+- A linked file the model opens on demand.
+- A tool with deferred loading, where the model searches for the definition before it uses the tool.
 
-## Write direct, dense rules
+Keep the always-on context lean and let the model pull the rest.
 
-- Use active, imperative language and concrete verbs. Put a condition before its action and an exception immediately after its default.
-- Preserve force and quantifiers. Keep `must`, `never`, `only`, `should`, `may`, `all`, `any`, and exact counts distinct.
-- Combine statements only when their actor, force, scope, trigger, timing, persistence, and exceptions align.
-- Replace true repetition with one rule and a compact list of affected cases. Keep separate statements when repetition protects distinct stages, scopes, or failure modes.
-- Use one sentence per decision. Join clauses only when they form one testable rule.
-- Use paragraphs for cohesive rules and lists for parallel obligations, mappings, or branches. Avoid decorative headings and structural ceremony.
-- Remove non-operative background, history, rationale, transition text, conversational framing, restatement, setup narration, and examples. Remove inventories or folder maps that merely describe the document.
-- Use one term for each concept. Define unfamiliar terms at first use. Do not compress complete sentences into fragments, stacked jargon, or vague shorthand.
-- Preserve operational literals character for character, including spelling, case, punctuation, quoting, and placeholders. Preserve whether a list is exhaustive or illustrative; never replace an exact enumeration with `etc.` or a broader category.
+## Say each thing once
 
-## Imply only what cannot change behavior
+Put tool usage guidance in the tool description alone. Delete the copy that repeats it in the system prompt.
 
-Rely on ordinary language competence and document conventions only when every reasonable reader would take the same action. State a detail when omitting it could change permission, safety, actor, object or type, scope, force, trigger, sequence, timing, persistence, precedence, failure behavior, exact output, or acceptance.
+## Let memory carry session facts
 
-Match detail to fragility. Specify exact steps for brittle, high-risk, or order-dependent work. For flexible work, state the required outcome and constraints, then leave the method open.
+Claude's automatic memory captures relevant context and carries it across sessions. Delete hand-written memory notes from CLAUDE.md when memory already holds them.
 
-Never use implication to carry a prohibition, exception, dependency, safety boundary, or exact literal. Do not retain obvious advice that constrains nothing, and do not omit a non-obvious rule because it seems intuitive.
+## Point at rich references
 
-## Pass the quality gate
+Include files as references with @mentions. Prefer a reference the model can read with no ambiguity, in this order:
 
-Run these checks silently:
+1. Code from this or another codebase — the highest fidelity specification available.
+2. A test suite that pins the behavior.
+3. An HTML artifact or a mockup.
+4. A rubric, which lets a verification agent score work against a quality standard.
+5. Prose description or a screenshot.
 
-1. **Coverage:** Map every ledger item to a clause in the finished document.
-2. **Support:** Map every material clause back to a stated or confirmed requirement; remove invented behavior.
-3. **Fidelity:** Compare force, negation, quantifiers, actor, object or type, scope, conditions, exceptions, dependencies, order, timing, persistence, failure behavior, outputs, and protected literals. Nothing may be weakened, broadened, narrowed, contradicted, or altered character for character where exactness matters.
-4. **Boundary behavior:** Test the normal case, each branch and exception, prohibited cases, missing dependencies, failures, and acceptance checks when present. Each case must yield the intended action.
-5. **Clarity:** Resolve ambiguous references, hidden precedence, scattered exceptions, inconsistent terms, and unclear qualifier scope.
-6. **Density:** Delete any sentence that changes no behavior, safety boundary, interpretation, or validation result. Merge remaining text only when the boundary stays equally clear.
-7. **Independent use:** Reconstruct the ledger from only the finished document. It must stand alone without background or unstated context.
+## Route what remains
 
-Do not finish until every check passes. If multiple versions pass, prefer fewer words, fewer sections, and lower lookup cost. Shorter text never compensates for lost behavior or precision.
+| Surface | What belongs there |
+|---|---|
+| System prompt | The product Claude works within and the role it plays. For a custom agent, spend real effort here. |
+| CLAUDE.md | A short line on what the repository is, then the gotchas found inside the codebase. Drop anything the model can read off the file structure. Link to skills for the detail. |
+| Skills | Opinions, knowledge, and practices particular to your team or product, written as a guide the model consults. Split a long skill into several files. Constrain only where it matters. |
+| References | Specs, mockups, and codebases pulled in by @mention. |
 
-## Deliver the requested artifact
+## Deliver
 
-Preserve the requested format and required syntactic envelope. If no format is specified, use the leanest clear Markdown structure.
-
-For text supplied in the conversation, output only the finished instruction document. For file tasks, write only the requested paths: edit an existing file in place, and create a new file only when requested. Report changed paths with a concise behavior summary. Do not include the ledger or process narration unless requested.
+Rewrite the document in place and report what moved to which surface. Offer `claude doctor` as a follow-up pass — it rightsizes skills and CLAUDE.md files against these same rules.

package/skills/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