claude-dev-env 2.5.0 → 2.7.1

package/skills/autoconverge/workflow/converge.fix-recovery.test.mjs

@@ -258,6 +258,7 @@ const verifyObjectionModule = new Function(
   `${functionSource('parseLastVerdictFence')}\n` +
     `${constantLine('VERIFY_OBJECTION_FALLBACK')}\n` +
     `${functionSource('renderVerifyObjectionLine')}\n` +
+    `${functionSource('extractPreFenceProse')}\n` +
     `${functionSource('extractVerifyObjection')}\n` +
     'return { extractVerifyObjection, VERIFY_OBJECTION_FALLBACK };',
 )();
@@ -338,6 +339,78 @@ test('extractVerifyObjection falls back when no finding yields usable text', ()
   assert.equal(extractVerifyObjection(transcript), VERIFY_OBJECTION_FALLBACK);
 });
 
+test('the prose reader anchors on the last CLOSED fence, not a stray unterminated marker', () => {
+  const transcript =
+    'check X never showed red\n\n' +
+    '```verdict\n{"all_pass": false, "findings": []}\n```\n\n' +
+    'and here I started to restate it\n\n' +
+    '```verdict';
+  const objection = extractVerifyObjection(transcript);
+  assert.equal(objection, 'check X never showed red');
+  assert.doesNotMatch(objection, /all_pass/, 'expected the verdict body never to be read back as prose');
+});
+
+test('the prose reader skips a scaffolding-only paragraph above the fence', () => {
+  const transcript =
+    'check X never showed red\n\n' + '## Verdict\n\n' + '```verdict\n{"all_pass": false, "findings": []}\n```';
+  assert.equal(extractVerifyObjection(transcript), 'check X never showed red');
+});
+
+const verifyRecoveryPromptModule = new Function(
+  `${constantLine('VERIFY_OBJECTION_FALLBACK')}\n` +
+    'const prCoordinates = "owner/repo#1";\n' +
+    'const PRE_COMMIT_GATE_STEP = "";\n' +
+    'const EDIT_SCHEMA = {};\n' +
+    'const TIERS = { sonnetMedium: {} };\n' +
+    'const convergeAgent = (spawnPrompt) => spawnPrompt;\n' +
+    `${functionSource('runCodeEditorTask')}\n` +
+    'return { runCodeEditorTask };',
+)();
+
+const { runCodeEditorTask: buildCodeEditorPrompt } = verifyRecoveryPromptModule;
+
+function buildVerifyRecoveryPrompt(verifyTranscript) {
+  return buildCodeEditorPrompt('verify-recover', {
+    objection: extractVerifyObjection(verifyTranscript),
+    head: 'deadbeefcafe',
+    sourceLabel: 'round-1 lens findings',
+    attempt: 1,
+  });
+}
+
+const INCOMPLETE_CHECK_SENTENCE =
+  'This verdict is incomplete: the deliberate break for check_docstring_runon_sentence never showed red, so that gate is unproven rather than failed.';
+
+test('an incomplete verdict carries its named check into the fixer prompt instead of the fallback', () => {
+  const transcript =
+    'I ran the named gates and read the diff against the task text.\n\n' +
+    `${INCOMPLETE_CHECK_SENTENCE}\n\n` +
+    '```verdict\n{"all_pass": false, "findings": [], "manifest_sha256": "0f1e2d"}\n```';
+  const fixerPrompt = buildVerifyRecoveryPrompt(transcript);
+  assert.match(fixerPrompt, /VERIFY-RECOVERY fixer/, 'expected the verify-recovery fixer prompt');
+  assert.ok(
+    fixerPrompt.includes(INCOMPLETE_CHECK_SENTENCE),
+    `expected the fixer prompt to carry the incomplete-check sentence, got:\n${fixerPrompt.slice(0, 600)}`,
+  );
+  assert.doesNotMatch(
+    fixerPrompt,
+    /without a parseable verdict/,
+    'expected the incomplete verdict never to reach the fixer as VERIFY_OBJECTION_FALLBACK',
+  );
+});
+
+test('a genuine code defect still reaches the fixer prompt from findings, unchanged by pre-fence prose', () => {
+  const transcript =
+    `${INCOMPLETE_CHECK_SENTENCE}\n\n` +
+    '```verdict\n{"all_pass": false, "findings": [{"check": "Finding 1", "detail": "boundary still over-blocks"}]}\n```';
+  const fixerPrompt = buildVerifyRecoveryPrompt(transcript);
+  assert.match(fixerPrompt, /1\. Finding 1 — boundary still over-blocks/);
+  assert.ok(
+    !fixerPrompt.includes(INCOMPLETE_CHECK_SENTENCE),
+    'expected findings to keep owning a verdict that names a code defect',
+  );
+});
+
 test('the verify-recover task in runCodeEditorTask is a clean-coder edit step bound to the verifier objection and leaves changes uncommitted', () => {
   const recoverBody = functionSource('runCodeEditorTask');
   assert.match(recoverBody, /agentType:\s*'clean-coder'/, 'expected the fixer to use clean-coder');

package/skills/autoconverge/workflow/converge.mjs

@@ -68,13 +68,15 @@ const HEADLESS_EDIT_PREAMBLE =
   '- When your run was given a result schema, your final action is always the StructuredOutput call. If the poll budget is spent before the awaited signal arrives, call StructuredOutput with the whole time-out result the step documents — for the Copilot gate, the full down result {sha, clean:false, down:true, findings:[]}, never a bare down flag — rather than ending the turn without a result.\n\n'
 
 const HEADLESS_READONLY_DESTRUCTIVE_POINTER =
-  '- Never run a destructive command (rm -rf, git reset --hard, dd, mkfs, chmod -R, a fork bomb) and never place its literal text in a Bash command: this step reads only and edits nothing, so it needs no destructive command. If a step seems to require one, report it as a blocker rather than running it.\n'
+  '- Never run a destructive command (rm -rf, git reset --hard, dd, mkfs, chmod -R, a fork bomb) and never place its literal text in a Bash command: this step makes no edit to the tree it reads, so it needs no destructive command. If a step seems to require one, report it as a blocker rather than running it.\n'
 
 /**
  * The read-only preamble a review, verify, or utility agent receives: the full
- * edit preamble with the rm-shape-rules bullet dropped, since an agent that edits
- * nothing never runs rm and the shape rules add no value to its prompt. The
- * one-line destructive pointer keeps the escape-hatch guidance in view. The
+ * edit preamble with the rm-shape-rules bullet dropped, since an agent that makes
+ * no edit in the tree it reads never runs rm against that tree, and the one file
+ * it may touch off that tree — a deliberate break at a break site outside it —
+ * is an edit rather than a delete, so the shape rules add no value to its
+ * prompt. The one-line destructive pointer keeps the escape-hatch guidance in view. The
  * derivation reads the single rm-shape bullet out of the edit preamble and swaps
  * the pointer in, so the two preambles share every other clause from one source.
  */
@@ -381,7 +383,7 @@ function runCodeEditorTask(task, context) {
       `You are the COMMIT step opening the environment-hardening PR (${context.sourceLabel}) for the change staged in ${context.hardeningRepoPath} on branch ${context.hardeningBranch}. The edit step left the hooks/rules edits in the working tree and the verify step passed, so a verifier verdict already binds to this exact working tree. Do NOT touch the PR's own branch.\n\n` +
         `Rules:\n` +
         `- Make NO further file edits of any kind. Any edit changes the surface and invalidates the verdict that unlocks the commit gate, so the push would be blocked. Only commit and push what is already there.\n` +
-        `- In ${context.hardeningRepoPath}: make ONE commit of the staged hooks/rules change on branch ${context.hardeningBranch}, push it, then open a DRAFT PR. The PR body references the follow-up issue ${context.issueUrl || '(none)'} and states the PR hardens the environment so the deferred violation classes are blocked at Write/Edit time. Honor the gh-body-file rule: write a BOM-free temp file and pass --body-file.\n` +
+        `- In ${context.hardeningRepoPath}: make ONE commit of the staged hooks/rules change on branch ${context.hardeningBranch}, push it, then open a DRAFT PR. The PR body references the follow-up issue ${context.issueUrl || '(none)'} and states the PR hardens the environment so the deferred violation classes are blocked at Write/Edit time. Honor the gh-cli-conventions rule: write a BOM-free temp file and pass --body-file.\n` +
         `- Title the PR as a Conventional Commit — a type prefix (feat, fix, chore, docs, refactor, perf, ci, style, test, build, revert), an optional scope in parentheses, then a colon and a short summary, e.g. "feat(hooks): block the deferred violation class". The target repo's CI validates the PR title as a semantic commit and rejects a non-conforming title.\n\n` +
         `Return the full https URL of the DRAFT hardening PR in hardeningPrUrl (empty string when no PR was opened) and a one-line summary.`,
       { label, phase: 'Converge', schema: HARDENING_COMMIT_SCHEMA, agentType: 'clean-coder', ...TIERS.sonnetMedium },
@@ -430,7 +432,7 @@ function runVerifierTask(task, context) {
   if (task === 'fix-verify') {
     const findingsBlock = renderFindingsBlock(context.findings)
     return convergeReadOnlyAgent(
-      `You are the VERIFY step for ${context.findings.length} finding(s) (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.head}. The edit step left fixes in the working tree, uncommitted. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+      `You are the VERIFY step for ${context.findings.length} finding(s) (${context.sourceLabel}) on ${prCoordinates}, HEAD ${context.head}. The edit step left fixes in the working tree, uncommitted. Make NO edit to the tree under verification — verification only; any edit inside that tree invalidates the verdict you are about to emit.\n\n` +
         `Findings the working-tree fixes must address:\n${findingsBlock}\n\n` +
         `Steps:\n` +
         `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
@@ -444,7 +446,7 @@ function runVerifierTask(task, context) {
       ? context.failures.map((each, position) => `${position + 1}. ${each}`).join('\n')
       : 'none reported'
     return convergeReadOnlyAgent(
-      `You are the VERIFY step for the convergence repair on ${prCoordinates}, HEAD ${context.head}. The edit step left its repair in the working tree (a bot-thread fix uncommitted, and/or a rebase onto origin/main), unpushed. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+      `You are the VERIFY step for the convergence repair on ${prCoordinates}, HEAD ${context.head}. The edit step left its repair in the working tree (a bot-thread fix uncommitted, and/or a rebase onto origin/main), unpushed. Make NO edit to the tree under verification — verification only; any edit inside that tree invalidates the verdict you are about to emit.\n\n` +
         `Concerns the working-tree repair must resolve (the gates the convergence check flagged):\n${failureBlock}\n\n` +
         `Steps:\n` +
         `1. Resolve the worktree repo root for running tests: REPO=$(git rev-parse --show-toplevel).\n` +
@@ -454,7 +456,7 @@ function runVerifierTask(task, context) {
     )
   }
   return convergeReadOnlyAgent(
-    `You are the VERIFY step for an environment-hardening change (${context.sourceLabel}) staged in the working tree of ${context.hardeningRepoPath}. The edit step left the hooks/rules edits uncommitted there. Do NO edits of any kind — verification only; any edit invalidates the verdict you are about to emit.\n\n` +
+    `You are the VERIFY step for an environment-hardening change (${context.sourceLabel}) staged in the working tree of ${context.hardeningRepoPath}. The edit step left the hooks/rules edits uncommitted there. Make NO edit to the tree under verification — verification only; any edit inside that tree invalidates the verdict you are about to emit.\n\n` +
       `Concern the working-tree change must resolve: the edited hooks/rules block the code-standard violation classes from the deferred round at Write/Edit time, and a hook change carries a passing test per CODE_RULES.\n\n` +
       `Steps:\n` +
       `1. cd into ${context.hardeningRepoPath}, then resolve its repo root: REPO=$(git rev-parse --show-toplevel).\n` +
@@ -468,7 +470,7 @@ function runVerifierTask(task, context) {
       "      ```verdict\n" +
       `      {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
       "      ```\n" +
-      `      When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`,
+      `      Set all_pass to false when verification fails, and list every code defect you found in findings. When the verdict is incomplete because a check it rests on never showed red, set all_pass to false and name that check in prose directly above the fence rather than in findings. Always include the manifest_sha256. The verdict fence must be the last thing in your message.`,
     { label, phase: 'Converge', agentType: 'code-verifier', ...TIERS.sonnetMedium },
   )
 }
@@ -871,7 +873,7 @@ function buildVerdictFenceSteps(prOwner, prRepo, prNumber) {
     "   ```verdict\n" +
     `   {"all_pass": true, "findings": [], "manifest_sha256": "<that hash>"}\n` +
     "   ```\n" +
-    `   When verification fails, set all_pass to false and list the unresolved concerns in findings; still include the manifest_sha256. The verdict fence must be the last thing in your message.`
+    `   Set all_pass to false when verification fails, and list every code defect you found in findings. When the verdict is incomplete because a check it rests on never showed red, set all_pass to false and name that check in prose directly above the fence rather than in findings. Always include the manifest_sha256. The verdict fence must be the last thing in your message.`
   )
 }
 
@@ -1343,14 +1345,61 @@ function renderVerifyObjectionLine(eachFinding) {
   return stringifiedFinding === '{}' ? null : stringifiedFinding
 }
 
+/**
+ * Read the prose paragraph the verifier wrote directly above its last verdict
+ * fence. A verdict that is incomplete — a check it rests on never showed red —
+ * is not a code defect, so the fence contract puts that reason here rather than
+ * in findings; this reader is how the reason survives into the re-fix step.
+ *
+ * Anchors on the same fence parseLastVerdictFence reads — the last CLOSED
+ * verdict fence, not the last bare marker — so a stray unterminated marker after
+ * the real fence can never make this read the verdict body itself as prose. A
+ * candidate paragraph carrying only markdown scaffolding (a heading, a fence
+ * delimiter) is skipped, since handing the fixer a heading is worse than the
+ * generic fallback the caller keeps.
+ *
+ * ::
+ *
+ *   'ran the gates\n\ncheck X never showed red\n\n```verdict\n{}\n```'
+ *     -> 'check X never showed red'
+ *   '```verdict\n{}\n```'  -> null
+ *
+ * @param {string|null|undefined} verifyTranscript the verifier transcript text
+ * @returns {string|null} the last prose paragraph above the final fence, or null when there is none
+ */
+function extractPreFenceProse(verifyTranscript) {
+  if (typeof verifyTranscript !== 'string') return null
+  const fenceMarker = '```verdict'
+  let lastFenceStart = verifyTranscript.lastIndexOf(fenceMarker)
+  while (lastFenceStart !== -1 && !verifyTranscript.slice(lastFenceStart + fenceMarker.length).includes('```')) {
+    lastFenceStart = verifyTranscript.lastIndexOf(fenceMarker, lastFenceStart - 1)
+  }
+  if (lastFenceStart === -1) return null
+  const proseParagraphs = verifyTranscript
+    .slice(0, lastFenceStart)
+    .split(/\n\s*\n/)
+    .map((eachParagraph) => eachParagraph.trim())
+    .filter((eachParagraph) =>
+      eachParagraph
+        .split('\n')
+        .some((eachLine) => {
+          const trimmedLine = eachLine.trim()
+          return trimmedLine.length > 0 && !trimmedLine.startsWith('#') && !trimmedLine.startsWith('```') && /[A-Za-z]/.test(trimmedLine)
+        }),
+    )
+  return proseParagraphs.length === 0 ? null : proseParagraphs[proseParagraphs.length - 1]
+}
+
 /**
  * Pull the verifier's stated objections out of a failed verify transcript so the
  * re-fix step knows what the verdict rejected. Reads the last fenced verdict JSON
  * (the same block verdictPassed reads) and renders each finding through
- * renderVerifyObjectionLine into a numbered list. A missing fence, a parse
- * failure, an empty findings list, or a findings list where no entry yields
- * usable text falls back to a generic re-read instruction, so the re-fix step
- * always receives actionable text.
+ * renderVerifyObjectionLine into a numbered list. When findings yields no usable
+ * line the verdict is an incomplete one rather than a code-defect one, so the
+ * prose paragraph above the fence — where the fence contract puts the unshown-red
+ * check — carries the objection instead. A missing fence, a parse failure, or an
+ * empty findings list with no prose above the fence falls back to a generic
+ * re-read instruction, so the re-fix step always receives actionable text.
  * @param {string|null|undefined} verifyTranscript the failed verifier transcript text
  * @returns {string} a human-readable block of the verifier's objections
  */
@@ -1361,7 +1410,7 @@ function extractVerifyObjection(verifyTranscript) {
   const renderedObjections = allObjections
     .map((eachFinding) => renderVerifyObjectionLine(eachFinding))
     .filter((eachLine) => eachLine !== null)
-  if (renderedObjections.length === 0) return VERIFY_OBJECTION_FALLBACK
+  if (renderedObjections.length === 0) return extractPreFenceProse(verifyTranscript) || VERIFY_OBJECTION_FALLBACK
   return renderedObjections.map((eachLine, position) => `${position + 1}. ${eachLine}`).join('\n')
 }
 

package/skills/bugteam/reference/copilot-gap-analysis.md

@@ -510,4 +510,4 @@ Expected output after the patch lands: a list containing `Line 91: Collection co
 - Inventory data sources: live `gh api repos/example-org/example-repo/pulls/{101,102}/comments` filtered to `Copilot`; verbatim bodies preserved in the inventory table above.
 - Original-commit content used to confirm violations: PR #101 head `29117309cf4ec1e83883160d8c819e0843f9c3ac`; PR #102 review-time commit `e4abf52c3a6c724b4e64bfed0d979cd60a2c8bf0`; PR #102 merged head `c9c935a96cc59d39d623dc7eddda3d341007607c`.
 - CODE_RULES.md sections invoked by the patch plan: §⚡ Magic values; §5 Extended naming rules (collections `all_orders`, `all_users`); §6.5 File length guidance; §7 Right-Sized Engineering; §10 No redundant data fetches (used as analogue for wrapper plumb-through).
-- Constraints honored: `gh-body-file` (no `gh ... --body` calls in the new code paths), `no-shell-substitution` (no `$(...)` in the verification commands above; multi-step shell flows are written as separate Bash invocations or `&&`-chained literal strings).
+- Constraints honored: `gh-cli-conventions` (no `gh ... --body` calls in the new code paths), `shell-invocation` (no `$(...)` in the verification commands above; multi-step shell flows are written as separate Bash invocations or `&&`-chained literal strings).

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