@jeffober/thatch 0.1.26 → 0.1.28

package/src/prompts.ts

@@ -9,7 +9,7 @@ knowledge so future sessions can build on what you've already learned.
 Tools: thatch_memory_remember, thatch_memory_recall, thatch_memory_list,
        thatch_memory_show, thatch_memory_forget, thatch_store_list,
        thatch_find_duplicates, thatch_dedup_mark_checked,
-       thatch_extraction_done,
+       thatch_extraction_done, thatch_get_extraction_payload,
        thatch_prediction_query, thatch_prediction_update, thatch_prediction_list,
        thatch_prediction_delete
 
@@ -37,19 +37,20 @@ you're working in. Prior sessions may have already investigated it.
 Thatch ships skills for code review, project investigation, and memory
 workflows. The host auto-discovers them, but reach for them proactively:
 
-- \`thatch-code-review\` — full multi-agent code review (dispatches 7 specialists + synthesizer). Requires sub-agent support.
-- \`thatch-review-followup\` — alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
-- \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
-- \`thatch-project-primer\` — investigate a new project and write foundational memories.
-- \`thatch-session-reflection\` — record what you learned at end of session.
-- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
-- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`thatch_find_duplicates\`.
-- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
-- \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-code-review\` - full multi-agent code review (dispatches 7 specialists + synthesizer). Requires sub-agent support.
+- \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
+- \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
+- \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-project-primer\` - investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` - record what you learned at end of session.
+- \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` - resolve duplicate memory pairs from \`thatch_find_duplicates\`.
+- \`thatch-pr-description\` - draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
+- \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 
 ## When to Write
 
@@ -61,8 +62,8 @@ current state of the code).
 
 ## Before Responding
 
-Before composing a final response after substantial work this turn — multiple
-rounds of tool calls for investigation, debugging, or code-writing — check
+Before composing a final response after substantial work this turn - multiple
+rounds of tool calls for investigation, debugging, or code-writing - check
 whether you've discovered knowledge worth persisting. Use thatch_memory_recall
 to check for duplicates, then thatch_memory_remember for new findings. Then
 deliver your response.
@@ -70,7 +71,7 @@ deliver your response.
 ## Background Task Completions
 
 When a background task completes and its result is injected into the session,
-the completion is informational — it is not user input and not approval to
+the completion is informational - it is not user input and not approval to
 proceed with anything you were discussing. Do not narrate what the task did or
 summarize its output. If you were mid-conversation with the user, continue
 that thread. If the user's last message has been fully addressed, stop and
@@ -79,7 +80,7 @@ not greenlit.
 
 If a background task was cancelled after timing out, re-dispatch it once with
 the same prompt. If the re-dispatch also fails or times out, note the gap and
-move on. Do not retry more than once — repeated failures indicate an
+move on. Do not retry more than once - repeated failures indicate an
 intractable prompt, not a transient hang.
 
 ## User Decision Model
@@ -147,7 +148,7 @@ do not save it. Do not store:
 
 ## Archived Memories
 
-Memories can be marked \`archived\` — a flag for stable, long-term historical
+Memories can be marked \`archived\` - a flag for stable, long-term historical
 records that should not trigger hygiene nudges (stale, orphaned, duplicate).
 Archived memories are excluded from search/recall results by default; pass
 \`includeArchived: true\` to surface them for archaeological dives.
@@ -155,25 +156,25 @@ Archived memories are excluded from search/recall results by default; pass
 When a branch is merged or about to be deleted, consolidate its branch-scoped
 memories into a single archived memory scoped to that same branch (preserving
 provenance). Capture intent, design decisions, review back-and-forth, PR
-number, unexpected pivots — the kind of git-archaeology context that explains
+number, unexpected pivots - the kind of git-archaeology context that explains
 _why_ the code looks the way it does a year from now. Then memory_forget the
 originals. The archived record outlives the branch. Future sessions searching
 with \`includeArchived: true\` can pull it up when investigating ambiguous code.
 
-Updating an archived memory requires passing \`archived\` explicitly — omit it
+Updating an archived memory requires passing \`archived\` explicitly - omit it
 and the tool returns an error. Pass \`archived: true\` to keep it archived,
 \`archived: false\` to unarchive.
 
 ## Explicit Requests
 
-"Remember X" — save immediately.
-"Forget X" — thatch_memory_recall to find it, then thatch_memory_forget.`;
+"Remember X" - save immediately.
+"Forget X" - thatch_memory_recall to find it, then thatch_memory_forget.`;
 }
 
 export function compactionContext(repo: string): string {
   return `Thatch persistent memory is active with stores "${repo}" and "global".
 When summarizing, preserve context about what's been learned and decided
-this session — conventions, architectural decisions, and prior knowledge
+this session - conventions, architectural decisions, and prior knowledge
 retrieved from memory. This ensures continuity after compaction.`;
 }
 
@@ -199,7 +200,7 @@ When convenient this session (not before addressing the user's request), tend th
  * start. The repo store name is auto-detected at runtime by the MCP server, so
  * the instructions don't need it.
  *
- * Tool names use the bare form (memory_remember, memory_recall, etc.) — in
+ * Tool names use the bare form (memory_remember, memory_recall, etc.) - in
  * Claude Code they're prefixed as mcp__thatch__memory_remember, but the bare
  * names are what the agent searches for and what the instructions reference.
  */
@@ -213,6 +214,7 @@ Tools are prefixed in Claude Code: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
 \`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`,
+\`mcp__thatch__get_extraction_payload\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`. Bare names used below for readability.
 
@@ -240,19 +242,20 @@ you're working in. Prior sessions may have already investigated it.
 Thatch ships skills for code review, project investigation, and memory
 workflows. The host auto-discovers them, but reach for them proactively:
 
-- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
-- \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
-- \`thatch-review-followup\` — alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` — seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
-- \`thatch-project-primer\` — investigate a new project and write foundational memories.
-- \`thatch-session-reflection\` — record what you learned at end of session.
-- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
-- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
-- \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
+- \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` - seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-project-primer\` - investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` - record what you learned at end of session.
+- \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` - resolve duplicate memory pairs from \`find_duplicates\`.
+- \`thatch-pr-description\` - draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
+- \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 
 ## When to Write
 
@@ -264,8 +267,8 @@ current state of the code).
 
 ## Before Responding
 
-Before composing a final response after substantial work this turn — multiple
-rounds of tool calls for investigation, debugging, or code-writing — check
+Before composing a final response after substantial work this turn - multiple
+rounds of tool calls for investigation, debugging, or code-writing - check
 whether you've discovered knowledge worth persisting. Use memory_recall to
 check for duplicates, then memory_remember for new findings. Then deliver
 your response.
@@ -335,7 +338,7 @@ do not save it. Do not store:
 
 ## Archived Memories
 
-Memories can be marked \`archived\` — a flag for stable, long-term historical
+Memories can be marked \`archived\` - a flag for stable, long-term historical
 records that should not trigger hygiene nudges (stale, orphaned, duplicate).
 Archived memories are excluded from search/recall results by default; pass
 \`includeArchived: true\` to surface them for archaeological dives.
@@ -343,19 +346,19 @@ Archived memories are excluded from search/recall results by default; pass
 When a branch is merged or about to be deleted, consolidate its branch-scoped
 memories into a single archived memory scoped to that same branch (preserving
 provenance). Capture intent, design decisions, review back-and-forth, PR
-number, unexpected pivots — the kind of git-archaeology context that explains
+number, unexpected pivots - the kind of git-archaeology context that explains
 _why_ the code looks the way it does a year from now. Then memory_forget the
 originals. The archived record outlives the branch. Future sessions searching
 with \`includeArchived: true\` can pull it up when investigating ambiguous code.
 
-Updating an archived memory requires passing \`archived\` explicitly — omit it
+Updating an archived memory requires passing \`archived\` explicitly - omit it
 and the tool returns an error. Pass \`archived: true\` to keep it archived,
 \`archived: false\` to unarchive.
 
 ## Explicit Requests
 
-"Remember X" — save immediately.
-"Forget X" — \`memory_recall\` to find it, then \`memory_forget\`.`;
+"Remember X" - save immediately.
+"Forget X" - \`memory_recall\` to find it, then \`memory_forget\`.`;
 }
 
 /**
@@ -393,17 +396,22 @@ export function claudeWriteNudge(): string {
  * their respective tool name prefix. The missedCount parameter tracks
  * consecutive nudges delivered without any memory_remember call in between,
  * escalating the tone from polite to insistent to shouting.
+ *
+ * The sessionID replaces the inline payload: the nudge tells the model to
+ * dispatch a sub-agent that calls get_extraction_payload to fetch the queued
+ * interactions as a tool response. This keeps the full payload out of the
+ * main session's context window.
  */
 export function extractionNudge(
   count: number,
   missedCount: number,
   toolName: string,
-  payload: string,
+  sessionID: string,
 ): string {
   const plural = count === 1 ? "" : "s";
   // opencode's task tool has a `background` parameter (requires
   // OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true) that launches the sub-agent
-  // asynchronously — the call returns immediately and the session is notified
+  // asynchronously - the call returns immediately and the session is notified
   // on completion. Naming the parameter gives the model a direct hit on the tool
   // schema it sees. MCP hosts (Claude Code, Cursor) keep generic sub-agent
   // wording because their background mechanisms differ and are not exposed as a
@@ -413,47 +421,48 @@ export function extractionNudge(
     ? "Dispatch a task with background: true"
     : "Spawn a background sub-agent";
   const drainTool = isOpencode ? "thatch_extraction_done" : "mcp__thatch__extraction_done";
+  const fetchTool = isOpencode
+    ? "thatch_get_extraction_payload"
+    : "mcp__thatch__get_extraction_payload";
   const acknowledge = `After dispatching, call ${drainTool} to acknowledge.`;
+  const subAgentPrompt = `Call ${fetchTool} with session_id "${sessionID}" to retrieve the queued tool interactions, then run the thatch-fact-extractor skill to extract durable facts. Call ${drainTool} with session_id "${sessionID}" when finished, even if nothing was worth saving.`;
 
   if (missedCount >= 3) {
     return `[thatch] YOU ARE IGNORING EXTRACTION INSTRUCTIONS. ` +
       `${count} TOOL INTERACTION${plural.toUpperCase()} ARE QUEUED AND YOU HAVE NOT PROCESSED ANY OF THEM. ` +
       `THE USER INSTALLED THIS PLUGIN FOR A REASON. ` +
-      `${dispatch.toUpperCase()} NOW TO RUN THE thatch-fact-extractor SKILL. ` +
-      `${acknowledge.toUpperCase()} ` +
-      `USE ${toolName.toUpperCase()} TO SAVE DURABLE FACTS FROM THIS PAYLOAD:\n${payload}`;
+      `${dispatch.toUpperCase()} NOW WITH THIS PROMPT: "${subAgentPrompt.toUpperCase()}" ` +
+      `${acknowledge.toUpperCase()}`;
   }
   if (missedCount >= 2) {
     return `[thatch] YOU HAVE NOT PROCESSED YOUR PREVIOUS EXTRACTION PAYLOAD${plural.toUpperCase()}. ` +
       `${count} more tool interaction${plural} are now queued. ` +
-      `${dispatch} to run the thatch-fact-extractor skill on this payload. ` +
-      `${acknowledge} ` +
-      `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+      `${dispatch} with this prompt: "${subAgentPrompt}" ` +
+      `${acknowledge}`;
   }
   return `[thatch] ${dispatch} to run the thatch-fact-extractor skill ` +
     `on ${count} queued tool interaction${plural}. ` +
+    `Sub-agent prompt: "${subAgentPrompt}" ` +
     `${acknowledge} ` +
     `This is a system nudge, not user input. After dispatching and acknowledging, ` +
     `stop: do not advance pending work on this nudge's account. If you are ` +
-    `waiting for the user to respond, continue waiting. ` +
-    `Use ${toolName} to save durable facts from this payload:\n${payload}`;
+    `waiting for the user to respond, continue waiting.`;
 }
 
 /**
  * Prompt text sent directly to a child session the plugin created for
  * extraction. Unlike extractionNudge (which tells the model to dispatch a
  * sub-agent and call extraction_done), this prompt is already inside the
- * child — the model just runs the fact-extractor skill and saves facts.
- * The payload format is identical to the nudge path so the skill receives
- * the same contract either way.
+ * child - the model calls get_extraction_payload to fetch the queued
+ * interactions, runs the fact-extractor skill, and saves facts.
  */
-export function extractionDirectPrompt(count: number, payload: string): string {
+export function extractionDirectPrompt(count: number, sessionID: string): string {
   const plural = count === 1 ? "" : "s";
   return `Run the thatch-fact-extractor skill to extract durable facts from ` +
     `${count} queued tool interaction${plural}. ` +
+    `Call thatch_get_extraction_payload with session_id "${sessionID}" to retrieve the interactions. ` +
     `Use thatch_memory_remember to save any durable facts you find. ` +
-    `Call thatch_extraction_done when finished, even if nothing was worth saving.\n` +
-    `Payload:\n${payload}`;
+    `Call thatch_extraction_done with session_id "${sessionID}" when finished, even if nothing was worth saving.`;
 }
 
 /**
@@ -461,13 +470,13 @@ export function extractionDirectPrompt(count: number, payload: string): string {
  * Maintained for any external callers; bin/thatch should use extractionNudge
  * directly with a missedCount from extract-queue.ts.
  */
-export function claudeExtractionNudge(count: number, payload: string): string {
-  return extractionNudge(count, 0, "mcp__thatch__memory_remember", payload);
+export function claudeExtractionNudge(count: number, sessionID: string): string {
+  return extractionNudge(count, 0, "mcp__thatch__memory_remember", sessionID);
 }
 
 /**
  * Static instructions for Cursor's AGENTS.md. Same contract as
- * claudeInstructions() — the host loads this at every session start, and the
+ * claudeInstructions() - the host loads this at every session start, and the
  * repo store name is auto-detected at runtime by the MCP server. Tool names
  * use the same mcp__thatch__ prefix since Cursor discovers MCP tools via the
  * same protocol.
@@ -482,6 +491,7 @@ Tools are prefixed in Cursor: \`mcp__thatch__memory_remember\`,
 \`mcp__thatch__memory_show\`, \`mcp__thatch__memory_forget\`,
 \`mcp__thatch__store_list\`, \`mcp__thatch__find_duplicates\`,
 \`mcp__thatch__dedup_mark_checked\`, \`mcp__thatch__extraction_done\`,
+\`mcp__thatch__get_extraction_payload\`,
 \`mcp__thatch__prediction_query\`, \`mcp__thatch__prediction_update\`,
 \`mcp__thatch__prediction_list\`, \`mcp__thatch__prediction_delete\`. Bare names used below for readability.
 
@@ -509,19 +519,20 @@ you're working in. Prior sessions may have already investigated it.
 Thatch ships skills for code review, project investigation, and memory
 workflows. The host auto-discovers them, but reach for them proactively:
 
-- \`thatch-workflow-research\` — research code workflows affected by a change or planned change, before reviewing or planning.
-- \`thatch-change-walkthrough\` — produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-code-walkthrough\` — produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
-- \`thatch-review-context\` — gather project context (PRs, tickets, TODOs, deferred work) before a review.
-- \`thatch-review-followup\` — alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
-- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` — seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
-- \`thatch-project-primer\` — investigate a new project and write foundational memories.
-- \`thatch-session-reflection\` — record what you learned at end of session.
-- \`thatch-fact-extractor\` — extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
-- \`thatch-dedup-classifier\` — resolve duplicate memory pairs from \`find_duplicates\`.
-- \`pr-description\` — draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
-- \`ticket-description\` — draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
-- \`split-overlarge-pr\` — split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-code-archaeology\` - investigate an existing feature, debug an unfamiliar area, or begin a new ticket. Explores the code base from multiple angles (data model, state flow, git history, sibling features) before proposing changes. The research skill; pair with \`thatch-coding-workflow\`.
+- \`thatch-change-walkthrough\` - produces a teaching walkthrough of a diff with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + change overlay mirroring the same numbers) and calibrated prose rules. Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-code-walkthrough\` - produces a teaching walkthrough for a feature/workflow as it stands today with a specific format (SYNOPSIS + per-workflow orient/mechanism/numbered-stages + Key files) and calibrated prose rules. Also use proactively to draft high-level docs for new or undocumented features (suitable for pkg/README.md or docs/features/<name>.md). Load the skill for the format and prose rules, not just for the research method.
+- \`thatch-review-context\` - gather project context (PRs, tickets, TODOs, deferred work) before a review.
+- \`thatch-review-followup\` - alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review adequately addressed prior findings, offers to reply on resolved items, then optionally re-runs the full structured review.
+- \`thatch-review-pedantic\` / \`-acceptance\` / \`-state-flow\` / \`-no-slop\` / \`-breadcrumbs\` / \`-mark-and-sweep\` / \`-highlights\` - seven specialist review lenses. Run individually, then \`thatch-review-synthesizer\` to verify and aggregate.
+- \`thatch-project-primer\` - investigate a new project and write foundational memories.
+- \`thatch-session-reflection\` - record what you learned at end of session.
+- \`thatch-fact-extractor\` - extract durable facts from recent tool interactions (auto-triggered by the extraction pipeline).
+- \`thatch-dedup-classifier\` - resolve duplicate memory pairs from \`find_duplicates\`.
+- \`thatch-pr-description\` - draft a PR description with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, using bold and italic emphasis on the phrases that carry the meaning.
+- \`thatch-ticket-description\` - draft a ticket, issue, or work item (Linear or Jira) with clear sections and bold/italic emphasis for scanning.
+- \`thatch-split-overlarge-pr\` - split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main.
+- \`thatch-review-response\` - respond to code review on the user's own PR. Triage findings, fix bugs one by one, reply on each thread, then post a top-level summary comment.
 
 ## When to Write
 
@@ -533,8 +544,8 @@ current state of the code).
 
 ## Before Responding
 
-Before composing a final response after substantial work this turn — multiple
-rounds of tool calls for investigation, debugging, or code-writing — check
+Before composing a final response after substantial work this turn - multiple
+rounds of tool calls for investigation, debugging, or code-writing - check
 whether you've discovered knowledge worth persisting. Use memory_recall to
 check for duplicates, then memory_remember for new findings. Then deliver
 your response.
@@ -604,7 +615,7 @@ do not save it. Do not store:
 
 ## Archived Memories
 
-Memories can be marked \`archived\` — a flag for stable, long-term historical
+Memories can be marked \`archived\` - a flag for stable, long-term historical
 records that should not trigger hygiene nudges (stale, orphaned, duplicate).
 Archived memories are excluded from search/recall results by default; pass
 \`includeArchived: true\` to surface them for archaeological dives.
@@ -612,23 +623,23 @@ Archived memories are excluded from search/recall results by default; pass
 When a branch is merged or about to be deleted, consolidate its branch-scoped
 memories into a single archived memory scoped to that same branch (preserving
 provenance). Capture intent, design decisions, review back-and-forth, PR
-number, unexpected pivots — the kind of git-archaeology context that explains
+number, unexpected pivots - the kind of git-archaeology context that explains
 _why_ the code looks the way it does a year from now. Then memory_forget the
 originals. The archived record outlives the branch. Future sessions searching
 with \`includeArchived: true\` can pull it up when investigating ambiguous code.
 
-Updating an archived memory requires passing \`archived\` explicitly — omit it
+Updating an archived memory requires passing \`archived\` explicitly - omit it
 and the tool returns an error. Pass \`archived: true\` to keep it archived,
 \`archived: false\` to unarchive.
 
 ## Explicit Requests
 
-"Remember X" — save immediately.
-"Forget X" — \`memory_recall\` to find it, then \`memory_forget\`.`;
+"Remember X" - save immediately.
+"Forget X" - \`memory_recall\` to find it, then \`memory_forget\`.`;
 }
 
 // ---------------------------------------------------------------------------
-// Prompt-aware recall nudge — fires when the user's prompt semantically
+// Prompt-aware recall nudge - fires when the user's prompt semantically
 // matches existing memories. Injected via opencode's chat.message hook
 // (in-process, warm model) or via the sideband socket for Claude Code/Cursor
 // (flush-tools CLI subcommand).

package/src/setup.ts

@@ -22,7 +22,7 @@ interface SetupPaths {
 
 /**
  * Resolve the Claude config directory. `CLAUDE_CONFIG_DIR` overrides the
- * default `~/.claude` location — used by people running multiple accounts
+ * default `~/.claude` location - used by people running multiple accounts
  * side by side (per Claude Code env-vars docs). Settings, CLAUDE.md, and
  * skills are all stored under this path in global scope. Project-local
  * installs only use it for skills (which are always user-scoped); the
@@ -41,7 +41,7 @@ function resolvePaths(global: boolean, projectDir: string, homeDir: string): Set
       mcpConfigPath: null,
       // Per Claude Code settings docs, user-scope CLAUDE.md lives at
       // `~/.claude/CLAUDE.md` (or `$CLAUDE_CONFIG_DIR/CLAUDE.md` when the
-      // env var is set) — NOT `~/CLAUDE.md`. Honoring CLAUDE_CONFIG_DIR
+      // env var is set) - NOT `~/CLAUDE.md`. Honoring CLAUDE_CONFIG_DIR
       // here also fixes a pre-existing bug where we wrote to `~/CLAUDE.md`.
       claudeMdPath: join(configDir, "CLAUDE.md"),
       settingsPath: join(configDir, "settings.json"),
@@ -55,14 +55,14 @@ function resolvePaths(global: boolean, projectDir: string, homeDir: string): Set
     claudeMdPath: join(projectDir, "CLAUDE.md"),
     settingsPath: join(projectDir, ".claude", "settings.json"),
     // Skills are always user-scoped, so they always live under the config
-    // dir — even when settings and CLAUDE.md are project-local.
+    // dir - even when settings and CLAUDE.md are project-local.
     skillsDir,
     global: false,
   };
 }
 
 // ---------------------------------------------------------------------------
-// .mcp.json — MCP server registration
+// .mcp.json - MCP server registration
 // ---------------------------------------------------------------------------
 
 function writeMcpConfig(path: string, thatchBin: string): void {
@@ -71,7 +71,7 @@ function writeMcpConfig(path: string, thatchBin: string): void {
     try {
       config = JSON.parse(readFileSync(path, "utf8"));
     } catch {
-      // Corrupt or empty — start fresh.
+      // Corrupt or empty - start fresh.
     }
   }
   if (!config.mcpServers) config.mcpServers = {};
@@ -87,11 +87,11 @@ function writeMcpConfig(path: string, thatchBin: string): void {
 }
 
 // ---------------------------------------------------------------------------
-// CLAUDE.md — append thatch instructions (idempotent)
+// CLAUDE.md - append thatch instructions (idempotent)
 // ---------------------------------------------------------------------------
 
 const THATCH_MARKER = "# Persistence\n\nThatch provides persistent memory across Claude Code sessions.";
-const THATCH_END_MARKER = '"Forget X" — `memory_recall` to find it, then `memory_forget`.';
+const THATCH_END_MARKER = '"Forget X" - `memory_recall` to find it, then `memory_forget`.';
 const CURSOR_MARKER = "# Persistence\n\nThatch provides persistent memory across Cursor sessions.";
 const CURSOR_END_MARKER = THATCH_END_MARKER;
 
@@ -119,7 +119,7 @@ function appendBlock(
           return;
         }
       }
-      // Marker found but block boundaries didn't parse — leave it alone.
+      // Marker found but block boundaries didn't parse - leave it alone.
       return;
     }
     // Append to existing file.
@@ -140,7 +140,7 @@ function appendCursorInstructions(path: string): void {
 }
 
 // ---------------------------------------------------------------------------
-// settings.json — hook installation
+// settings.json - hook installation
 // ---------------------------------------------------------------------------
 
 interface HookEntry {
@@ -163,14 +163,14 @@ function writeHooks(path: string, thatchBin: string): void {
     try {
       settings = JSON.parse(readFileSync(path, "utf8"));
     } catch {
-      // Corrupt — start fresh.
+      // Corrupt - start fresh.
     }
   }
   if (!settings.hooks) settings.hooks = {};
 
   const sessionStartCmd = `${thatchBin} reminder`;
   // PostToolBatch silently buffers tool interactions to the file-backed queue
-  // (see src/extract-queue.ts). No stdout — the next model call must not block
+  // (see src/extract-queue.ts). No stdout - the next model call must not block
   // on a payload that should be invisible to the agent until UserPromptSubmit.
   const bufferCmd = `${thatchBin} buffer-batch`;
   // UserPromptSubmit peeks the queue. With buffered interactions, it prints
@@ -209,7 +209,7 @@ function replaceThatchHooks(
 }
 
 // ---------------------------------------------------------------------------
-// Skills — install to $CLAUDE_CONFIG_DIR/skills/ (or ~/.claude/skills/ by default)
+// Skills - install to $CLAUDE_CONFIG_DIR/skills/ (or ~/.claude/skills/ by default)
 // ---------------------------------------------------------------------------
 
 function installClaudeSkills(skillsDir: string): SkillFile[] {
@@ -233,7 +233,7 @@ export interface SetupResult {
 /**
  * Installs thatch into Claude Code. Writes MCP config, appends instructions to
  * CLAUDE.md, installs SessionStart + PostToolBatch + UserPromptSubmit hooks,
- * and installs skill files. All operations are idempotent — re-running setup
+ * and installs skill files. All operations are idempotent - re-running setup
  * updates content that has drifted without clobbering unrelated configuration.
  *
  * Honors `CLAUDE_CONFIG_DIR` for all user-scoped paths (settings, CLAUDE.md,
@@ -276,7 +276,7 @@ export function setupClaudeCode(
 }
 
 // ---------------------------------------------------------------------------
-// Cursor setup — .cursor/mcp.json, AGENTS.md, .cursor/hooks.json, skills
+// Cursor setup - .cursor/mcp.json, AGENTS.md, .cursor/hooks.json, skills
 // ---------------------------------------------------------------------------
 
 /**
@@ -303,7 +303,7 @@ function resolveCursorPaths(global: boolean, projectDir: string, homeDir: string
 
   if (global) {
     return {
-      // Cursor's global MCP config is a simple file — no equivalent of
+      // Cursor's global MCP config is a simple file - no equivalent of
       // `claude mcp add --scope user`. Writing ~/.cursor/mcp.json is enough.
       mcpConfigPath: join(configDir, "mcp.json"),
       agentsMdPath: join(configDir, "AGENTS.md"),
@@ -340,7 +340,7 @@ function writeCursorHooks(path: string, thatchBin: string): void {
     try {
       config = JSON.parse(readFileSync(path, "utf8"));
     } catch {
-      // Corrupt — start fresh.
+      // Corrupt - start fresh.
     }
   }
   if (!config.version) config.version = 1;
@@ -351,7 +351,7 @@ function writeCursorHooks(path: string, thatchBin: string): void {
   // Code style) and Cursor would not parse it.
   const sessionStartCmd = `${thatchBin} reminder --json`;
   // postToolUse fires per-tool (Cursor has no PostToolBatch equivalent).
-  // Silent — no stdout — so the agent loop is not delayed.
+  // Silent - no stdout - so the agent loop is not delayed.
   const bufferCmd = `${thatchBin} buffer-tool`;
   // beforeSubmitPrompt is Cursor's UserPromptSubmit equivalent. Drains the
   // queue and prints the extraction nudge as JSON additional_context.
@@ -422,7 +422,7 @@ export function setupCursor(
 }
 
 // ---------------------------------------------------------------------------
-// Setup detection — check whether setup was completed for the current host
+// Setup detection - check whether setup was completed for the current host
 // ---------------------------------------------------------------------------
 
 export type HostKind = "claude" | "cursor";
@@ -449,7 +449,7 @@ function checkInstructionsFile(path: string, startMarker: string, endMarker: str
  * CLAUDE_PROJECT_DIR for Claude Code) and checks whether `thatch setup` was
  * run for that host. Checks local instructions (in the project dir) first,
  * then global (in the config dir). Returns null if the host cannot be
- * determined (neither env var is set — e.g. manual `thatch mcp` invocation).
+ * determined (neither env var is set - e.g. manual `thatch mcp` invocation).
  */
 export function checkSetup(projectDir: string, homeDir?: string): SetupStatus | null {
   const home = homeDir ?? process.env.HOME ?? "/tmp";

package/src/sideband.ts

@@ -66,7 +66,7 @@ export class SidebandServer {
     try {
       unlinkSync(this.#path);
     } catch {
-      // No stale socket — expected on first run.
+      // No stale socket - expected on first run.
     }
 
     this.#server = createServer((socket) => {
@@ -103,7 +103,7 @@ export class SidebandServer {
       this.#handleRequest(line, socket);
     });
     socket.on("error", () => {
-      // Client disconnected abruptly — nothing to do.
+      // Client disconnected abruptly - nothing to do.
     });
   }
 
@@ -155,7 +155,7 @@ export class SidebandServer {
 
 /**
  * Connect to the sideband server and request semantic matches for a prompt.
- * Returns null on any failure (server not running, stale socket, timeout) —
+ * Returns null on any failure (server not running, stale socket, timeout) -
  * callers must treat null as "skip the recall nudge" and fall back gracefully.
  */
 export function sidebandMatch(