@jeffober/thatch 0.1.4 → 0.1.5

package/docs/dev/README.md

@@ -18,7 +18,7 @@ Shared core
   ├── git.ts          → detect repo identity (store name)
   ├── hygiene.ts      → hygiene report (pending dedups, stale, orphaned branches)
   ├── prompts.ts      → system prompt, compaction, reminders, CLAUDE.md instructions
-  └── skills.ts       → SKILL.md content + installer
+  └── skills.ts       → SKILL.md content + installer (shared + opencode-only arrays)
 
 OpenCode plugin path
   ├── index.ts        → plugin entry: wires DB/model/extraction, registers tools + hooks
@@ -48,7 +48,7 @@ bin/thatch             → CLI: stores|list|show|forget|search|mcp|reminder|hygi
 | `embeddings.ts` | Lazy-load the embedding model. Expose `queryEmbed`/`passageEmbed` and the model `name` (stored as an informational tag). `MockEmbeddingModel` for tests. |
 | `extraction.ts` | Buffers non-thatch tool interactions per session and serializes them into the JSON payload the extraction nudge carries. (opencode-only — no MCP equivalent.) |
 | `prompts.ts` | Text constants: opencode system prompt, compaction context, session-start reminder, Claude Code CLAUDE.md instructions, Claude Code hook text. |
-| `skills.ts` | `SKILL.md` content for `thatch-fact-extractor` and `thatch-dedup-classifier`, plus the installer. |
+| `skills.ts` | `SKILL.md` content for all thatch skills, plus the installer. Skills are split into `SHARED_SKILLS` (10 skills: fact-extractor, dedup-classifier, project-primer, 5 review specialists, review synthesizer, session reflection — work on both opencode and Claude Code) and `OPENCODE_ONLY_SKILLS` (1 skill: code-review coordinator — requires sub-agent support, not installed for Claude Code). `installSkills(dir, skills)` defaults to `SHARED_SKILLS`; the opencode plugin passes `[...SHARED_SKILLS, ...OPENCODE_ONLY_SKILLS]`. |
 
 ## Plugin hooks
 
@@ -85,7 +85,10 @@ Two of these hooks were dead for weeks because failures were invisible.
 7. **Skills are plugin-owned files.** Installed to
    `$XDG_CONFIG_HOME/opencode/skills` (opencode) or `~/.claude/skills/`
    (Claude Code) — never into the worktree; drifted content is overwritten
-   on plugin init or re-running `thatch setup`.
+   on plugin init or re-running `thatch setup`. Skills are split into
+   `SHARED_SKILLS` (work on both hosts) and `OPENCODE_ONLY_SKILLS` (require
+   sub-agent support, not installed for Claude Code). The opencode plugin
+   installs both arrays; `thatch setup --claude` installs only shared.
 8. **Tool definitions are the single source of truth.** `tool-defs.ts` defines
    each tool once (name, zod schema, execute function). The opencode plugin
    wraps them in `tool()` with a `thatch_` prefix; the MCP server wraps them

package/docs/user/README.md

@@ -82,13 +82,75 @@ Beyond the tools, thatch hooks into opencode itself:
 
 ## Skills
 
-On startup thatch installs two [skills] into your global opencode config
-(`~/.config/opencode/skills/`, or `$XDG_CONFIG_HOME/opencode/skills`):
+On startup thatch installs [skills] into your global opencode config
+(`~/.config/opencode/skills/`, or `$XDG_CONFIG_HOME/opencode/skills`).
+When using `thatch setup --claude`, skills are installed to `~/.claude/skills/`
+(or `$CLAUDE_CONFIG_DIR/skills/`).
+
+### Memory skills
 
 | Skill | Purpose |
 |-------|---------|
 | `thatch-fact-extractor` | Guides the agent through turning buffered tool interactions into memories. |
 | `thatch-dedup-classifier` | Guides the agent through classifying and resolving duplicate-candidate pairs. |
+| `thatch-project-primer` | Investigates a new project from multiple angles and writes foundational memories. |
+| `thatch-session-reflection` | End-of-session skill for recording what was learned about the project, user, tools, and self. |
+
+### Code review skills
+
+Five specialist review lenses, each a self-contained static-analysis pass:
+
+| Skill | Focus |
+|-------|-------|
+| `thatch-review-pedantic` | Mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. |
+| `thatch-review-acceptance` | Behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. |
+| `thatch-review-state-flow` | Data flow and contracts: module boundaries, implicit state machines, error propagation, separation of concerns. |
+| `thatch-review-no-slop` | AI writing anti-patterns: change narration, fourth wall breaks, em dashes, hedging, filler. |
+| `thatch-review-breadcrumbs` | Comment narrative: do comments form a coherent outline of the code's behavior? |
+| `thatch-review-synthesizer` | Verifies and synthesizes findings from multiple specialists into a single deduplicated, severity-grouped report. |
+
+### opencode-only skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-code-review` | Multi-agent review coordinator. Dispatches parallel sub-agents for triage, decomposition, specialist fan-out, and synthesis. Not available in Claude Code (requires sub-agent support). |
+
+### Host availability
+
+| Skill | opencode | Claude Code |
+|-------|----------|-------------|
+| Memory skills (4) | Yes | Yes |
+| Review specialists (5) | Yes | Yes |
+| Review synthesizer | Yes | Yes |
+| Code review coordinator | Yes | No (requires sub-agents) |
+
+### Using review skills
+
+For a **quick single-lens review**, load any specialist skill directly and
+point it at a branch or commit range:
+
+```
+Load thatch-review-pedantic and review the changes on this branch.
+```
+
+For a **full multi-specialist review on opencode**, load the coordinator:
+
+```
+Load thatch-code-review and review branch feature-x.
+```
+
+The coordinator will triage the change, dispatch parallel sub-agents (one per
+specialist lens), and synthesize a final report.
+
+For a **full review on Claude Code** (or without the coordinator), run each
+specialist in sequence, then synthesize:
+
+```
+1. Load thatch-review-pedantic, review branch feature-x, report findings.
+2. Load thatch-review-acceptance, review the same branch.
+3. ... repeat for state-flow, no-slop, breadcrumbs ...
+4. Load thatch-review-synthesizer, verify and aggregate all findings.
+```
 
 These files are plugin-owned: local edits are overwritten the next time the
 plugin initializes (this is how skill improvements ship with new versions).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jeffober/thatch",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Persistent memory for AI coding agents — local embeddings, SQLite stores, zero config. Works with OpenCode (as a plugin) and Claude Code (as an MCP server).",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -10,7 +10,7 @@ import {
   sessionStartReminder,
 } from "./prompts";
 import { ExtractionPipeline } from "./extraction";
-import { installSkills } from "./skills";
+import { installSkills, SHARED_SKILLS, OPENCODE_ONLY_SKILLS } from "./skills";
 import { hygieneReport } from "./hygiene";
 
 // ---------------------------------------------------------------------------
@@ -34,7 +34,10 @@ export const server: Plugin = async ({ client, worktree }) => {
   // worktree would mutate the user's repo (untracked files in git status).
   // A failed install degrades the nudge workflow but must not kill the plugin.
   try {
-    installSkills(join(configHome, "opencode", "skills"));
+    installSkills(join(configHome, "opencode", "skills"), [
+      ...SHARED_SKILLS,
+      ...OPENCODE_ONLY_SKILLS,
+    ]);
   } catch (err) {
     console.error(`[thatch] skill install failed: ${err}`);
   }

package/src/skills.ts

@@ -7,17 +7,29 @@ export interface SkillFile {
   content: string;
 }
 
+export interface SkillDef {
+  name: string;
+  content: string;
+}
+
 /**
  * Writes thatch skill files into the given skills directory. Called at plugin
- * init — idempotent, and rewrites a skill whose on-disk content has drifted so
- * plugin upgrades propagate. These files are plugin-owned: local edits are
- * overwritten on next init.
+ * init and during `thatch setup --claude` — idempotent, and rewrites a skill
+ * whose on-disk content has drifted so plugin upgrades propagate. These files
+ * are plugin-owned: local edits are overwritten on next init.
+ *
+ * Defaults to SHARED_SKILLS (works on both opencode and Claude Code). Pass
+ * OPENCODE_ONLY_SKILLS (or a combined array) for the opencode plugin path,
+ * which can use sub-agent-based skills that Claude Code cannot run.
  */
-export function installSkills(skillsDir: string): SkillFile[] {
+export function installSkills(
+  skillsDir: string,
+  skills: SkillDef[] = SHARED_SKILLS,
+): SkillFile[] {
   mkdirSync(skillsDir, { recursive: true });
   const written: SkillFile[] = [];
 
-  for (const skill of SKILLS) {
+  for (const skill of skills) {
     const dir = join(skillsDir, skill.name);
     const file = join(dir, "SKILL.md");
 
@@ -38,6 +50,52 @@ export function installSkills(skillsDir: string): SkillFile[] {
   return written;
 }
 
+// ---------------------------------------------------------------------------
+// Shared review framework — interpolated into each specialist skill
+// ---------------------------------------------------------------------------
+
+const REVIEW_COMMON = `
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands. Do NOT execute the code under review.
+
+## Scope gathering
+Before reviewing, identify what to review:
+1. If a git range, branch, or PR was specified, use that target.
+2. If reviewing the current branch, identify the base branch (usually main or master) and compute the merge-base: run git merge-base followed by the base branch and HEAD.
+3. Run git diff --stat on the resolved range to identify changed files.
+4. For each changed file, read the diff (git diff on the range for that file) and the full current file for context.
+5. Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## Runtime model
+Identify the application's runtime model early: Is it a CLI tool (process exits after each invocation)? A long-lived server (state persists across requests)? A library (caller controls lifecycle)? A batch job? This determines which classes of bugs are realistic — for example, "state not cleaned up" is irrelevant in a short-lived process but critical in a server.
+
+## Reachability gate
+For every potential finding, you MUST describe a concrete scenario where a real user triggers the problem through normal usage. "The code allows this" is not sufficient — show how a user actually encounters it given the application's runtime model. If the only trigger requires conditions that cannot occur in actual usage, it is not a finding.
+
+## Intent verification
+Before flagging behavior as a bug, verify intent:
+1. **Trace callers.** Read every caller of the cited code. The behavior may be intentional given how the feature is actually used.
+2. **Check git history.** Use git log, git blame, or git log -S to find commit messages explaining why the code was written this way.
+3. **Check memories.** Use thatch_memory_recall to search for documented design decisions or known limitations related to the code area.
+
+If any of these reveals the behavior is intentional, it is not a finding. If you cannot determine intent after all three steps, you may report it — but note that you could not confirm whether the behavior is intentional.
+
+## Output format
+Produce findings as markdown. For each finding:
+
+### [SEVERITY] [CATEGORY] — file:line
+- **Finding**: what the problem is
+- **Evidence**: exact code quoted from the cited location (copy-paste, do not paraphrase)
+- **Trigger**: concrete normal-usage scenario, or "N/A — mechanical finding"
+- **Reachability**: why this is reachable in real usage, or why it is not
+- **Source of truth**: authoritative source for the claim (producer, caller contract, behavior, guideline, docs)
+- **Producer chain**: producer then transform then consumer, or "N/A — mechanical finding"
+- **Provenance**: branch-introduced or pre-existing
+
+Severities: BLOCKING > HIGH > MEDIUM > LOW.
+If no findings, say so explicitly. Do NOT report issues in files you did not actually read. Do NOT report "likely similar issues exist" without evidence.
+`;
+
 // ---------------------------------------------------------------------------
 // Skill definitions
 // ---------------------------------------------------------------------------
@@ -63,16 +121,44 @@ You will be given a JSON payload with:
 
 ## What to extract
 
-- Project architecture, conventions, patterns discovered through tool use
+**Project architecture and design:**
+- Project purpose and goals
+- Overall design and architecture
+- Applications and components, their locations, and dependencies
+- How apps/components interact and integrate
+- Repo/app layout and organization
+- Domain-specific terminology
+
+**Languages, frameworks, and technologies:**
+- Languages, frameworks, and technologies used
+- Build tools, package managers, runtime environment
+- Deployment or runtime details
+
+**Conventions and patterns:**
+- Coding, style, and testing conventions
+- Naming patterns and organizational structures
+- Code style preferences (formatting, indentation, module structure)
+
+**Gotchas and pitfalls:**
 - Non-obvious gotchas and pitfalls (especially ones that took time to debug)
+- "Always check X before doing Y" type advice
+- "The user prefers Z" type advice
+- Bug shapes: the abstract pattern behind a fix, not the specific bug context
+
+**Useful commands and workflows:**
+- Project-specific commands and command sequences for common tasks
+- Project-specific scripts and internal tools, their purpose, and useful invocations
+- Prompting patterns that succeed or fail with coding tools (e.g., "when using the edit tool, always use referential anchors like 'above the function foo'")
+
+**User preferences and environment:**
 - User preferences, communication style, explicit corrections, pet peeves
 - Shell/environment quirks (tool friction, missing commands, platform issues)
-- Bug shapes: the abstract pattern behind a fix, not the specific bug context
+- Details about the user's expertise and experience level
 
 ## Store assignment
 
 - global store: user preferences, personality traits, communication style, environment quirks
-- Project store: architecture, conventions, patterns, project-specific gotchas
+- Project store: architecture, conventions, patterns, project-specific gotchas, useful commands
 
 ## Writing good memories
 
@@ -186,8 +272,633 @@ You are the Thatch Project Primer. Your job: investigate this project thoroughly
 
 Tell the user what you learned and which memories you wrote. Suggest they run thatch_find_duplicates if the store feels crowded.`;
 
-const SKILLS = [
+// ---------------------------------------------------------------------------
+// Review specialist skills (5) — each a standalone review lens
+// ---------------------------------------------------------------------------
+
+const REVIEW_PEDANTIC = `---
+name: thatch-review-pedantic
+description: Mechanical correctness code review — spelling, naming, doc accuracy, specs, guidelines, stale artifacts. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a pedantic review agent. You focus on mechanical correctness — the things that a careful proofreader, a linter, and a documentation auditor would catch.
+${REVIEW_COMMON}
+## Your focus
+
+You care about:
+- **Spelling and grammar** in comments, docs, error messages, UI strings
+- **Naming consistency** across the changes (e.g. module renamed but references to old name remain in comments, docs, specs, or error messages)
+- **Dead references** (mentions of functions, modules, or files that no longer exist after the changes)
+- **Doc accuracy** (do moduledocs, docstrings, README, and inline comments correctly describe the current behavior, or do they describe the old behavior?)
+- **Code comment accuracy** (do comments describe what the code actually does?)
+- **Project style guidelines** (read AGENTS.md, CLAUDE.md, CONTRIBUTING.md, or equivalent project guidelines and check adherence)
+- **Spec/type annotation completeness** (do new public functions have type annotations? Do changed function signatures have updated specs? When investigating contracts, find the source of truth for the interface — the spec may be defined on a behaviour, interface, trait, protocol, or abstract base class rather than the implementation.)
+- **Formatting consistency** (indentation, blank lines, module attribute ordering)
+- **Stale artifacts** (TODO comments that reference completed work, commented-out code, debug prints left behind)
+
+You do NOT care about:
+- Whether the code is correct (other reviewers handle logic)
+- UX or behavioral concerns
+- Architecture or design decisions
+- Test quality or coverage
+
+## Method
+
+1. Read the project guidelines (AGENTS.md, CLAUDE.md, or equivalent) if they exist.
+2. Use the diff stat from your scope gathering to identify changed files.
+3. For EVERY code-bearing changed file:
+   - Read the diff for that file
+   - Read the full current file for doc/comment accuracy in context
+4. For each changed file, check systematically:
+   - Comments: accurate? stale? describe the code, not the change?
+   - Docs: moduledocs and docstrings match current behavior?
+   - Naming: consistent with project conventions and the rest of the changes?
+   - Specs/types: present for new public functions? Updated for changed signatures? Find the source of truth for each interface before flagging.
+   - Style: follows project guidelines?
+   - Dead references: mentions of old names, removed functions, deleted files?
+5. Cross-reference docs with code: verify that documentation matches implementation.
+
+## Materiality and source of truth
+
+Do not flag a spec, doc, or naming issue until you identify the authoritative source of truth for the claim: the owning behavior, public contract, guideline, docs layer, or user-visible string.
+
+Prefer concrete mismatches over theoretical ones. If the implementation looks odd in isolation but callers, contracts, or owning docs show it is correct, do not report it.
+
+## Category taxonomy
+
+- **STALE**: Docs, comments, or references describing old behavior or referencing removed things
+- **GUIDELINE**: Violations of project style guidelines (cite the guideline and the violation)
+- **SPEC**: Missing or incorrect type annotations/specs on public functions
+- **TYPO**: Spelling or grammar errors in user-visible strings, docs, or comments
+- **ARTIFACT**: Debug prints, commented-out code, TODOs referencing completed work
+
+Do NOT report issues in files you did not actually read.
+`;
+
+const REVIEW_ACCEPTANCE = `---
+name: thatch-review-acceptance
+description: Behavioral and product-level code review — UX coherency, behavioral delta, integration effects, user assumptions. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are an acceptance and product review agent. You evaluate code changes from the perspective of a user and a product designer — not a compiler.
+${REVIEW_COMMON}
+## Your focus
+
+You care about:
+- **Behavioral delta**: What did the code do before? What does it do now? Is the change intentional and complete, or does it leave inconsistencies?
+- **UX coherency**: Will users find this easy to use? Will the interface surprise them? Are error messages helpful? Do success messages lie? Consider the workflow(s) affected by this change. Reason through the steps the user will take, and whether the overall workflow minimizes friction and walks the user through unavoidable complexities.
+- **Integration effects**: How do these changes interact with other features? Could they alter behavior of existing workflows the user relies on?
+- **User assumptions**: How will users misunderstand this interface? What will they try that won't work? What mental model will they build, and will it be correct?
+- **Friction in common cases**: Are the happy paths smooth? Do common operations require unnecessary steps or knowledge of internals?
+
+You do NOT care about:
+- Code style, spelling, formatting, or naming conventions
+- Type specs, dialyzer, or linting concerns
+- Internal data structures, unless they leak into user-visible behavior
+- Test coverage
+
+## Method
+
+### 1. Understand the before-state
+Before reading the new code, establish what existed before:
+- For modified files, use git show with the base commit to read the ORIGINAL version.
+- Understand the original behavior, interface, and user experience.
+
+This is critical. You cannot evaluate a behavioral change if you don't know the original behavior.
+
+### 2. Understand the after-state
+Read the current code. Map the new behavior, interfaces, and user-facing outputs.
+
+### 3. Reason about the delta
+For each significant behavioral change:
+- What was the old behavior? What is the new behavior?
+- Is this change intentional (does it align with the stated design)?
+- Is it complete (are there places where old behavior leaks through)?
+- Does it create inconsistencies with other features or interfaces?
+
+### 4. Walk the user journey
+For each user-facing feature touched by the changes:
+- What does a new user try first? Does it work?
+- What does an experienced user expect? Does it match?
+- When something goes wrong, does the error guide the user to recovery?
+- Are there silent failures (operation "succeeds" but does nothing)?
+
+### 5. Check integration boundaries
+- Do other features depend on the changed behavior?
+- Could the change break workflows that span multiple features?
+- Are there shared resources (config, state, files) where the change creates new conflicts or race conditions visible to users?
+
+### 6. Prove the workflow inputs
+For any finding that depends on bad state, malformed data, or surprising cross-feature behavior, identify:
+- Which user action or entrypoint starts the workflow
+- Which code path produces the relevant state/data
+- Which steps transform it before the failure
+- Why current guards, validation, or surrounding workflow do not prevent it
+
+If the issue only exists when someone manually fabricates invalid state/data outside the normal workflow, it is not a real finding.
+
+## Category taxonomy
+
+- **FRICTION**: Common use case is harder/slower/more confusing than it should be
+- **INCONSISTENCY**: Mismatch with existing behavior, conventions, or user expectations
+- **SILENT_FAILURE**: Operation appears to succeed but doesn't do what user expects
+- **BREAKING**: Previously working workflow is now broken or produces wrong results
+
+Report findings as behavioral observations, not code complaints. Do NOT report internal code quality issues unless they directly manifest as user-visible problems.
+`;
+
+const REVIEW_STATE_FLOW = `---
+name: thatch-review-state-flow
+description: Data flow and contract code review — module boundaries, implicit state machines, error propagation, separation of concerns. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a state and data flow review agent. You focus on mid-level architecture: how data flows through the system, the implicit contracts between components, and whether the code's structure supports correctness, testability, and maintainability.
+${REVIEW_COMMON}
+## Your focus
+
+You care about:
+- **Data flow coherency**: Does data transform correctly as it passes between modules? Are there type mismatches, dropped fields, or shape changes that break downstream consumers?
+- **Implicit state machines**: Many workflows have implicit states (e.g. "project selected then skill loaded then skill validated then skill executed"). Are state transitions guarded? Can you reach an invalid state?
+- **Contracts between modules**: When module A calls module B, what does A assume about B's return value, side effects, and error shapes? Are those assumptions documented or enforced? Could a change to B silently break A?
+- **Separation of concerns**: Does each module own a single responsibility? Do the changes introduce coupling between modules that should be independent?
+- **Testability**: Can each component be tested in isolation? Do the changes introduce dependencies that make testing harder?
+- **Error propagation**: Do errors flow correctly through the call chain? Are there places where an error is swallowed, wrapped ambiguously, or converted to a success?
+
+You do NOT care about:
+- User experience or interface design
+- Spelling, formatting, or style
+- Whether the feature is a good idea
+
+## Method
+
+### 1. Map the change set
+Use the diff stat from your scope gathering to identify which modules are touched. Categorize them by role: entry points, core logic, persistence, config, glue.
+
+### 2. For each module boundary, trace the contract
+Read both sides of every call that crosses a module boundary:
+- What does the caller pass?
+- What does the callee accept? (function head, type annotations, guards)
+- What does the callee return? (read the implementation, not just the type annotation)
+- What does the caller do with the return value?
+- Does the caller handle all possible return shapes?
+
+Do NOT assume contracts match. Read both sides and verify.
+
+### 3. Trace at least two end-to-end paths
+Pick the two most important runtime paths through the changed code:
+- The primary happy path
+- The most important error/failure path
+
+For each, walk through actual function calls, tracking data shape at each step.
+
+### 4. Prove the producer chain
+For every finding about invalid state, missing data, shape mismatches, or cross-module behavior, trace the full causal chain:
+- Who produces the state or value?
+- Which functions transform it?
+- Which consumer or branch fails?
+- Which real entrypoint/workflow exercises that chain?
+
+If you cannot identify a real producer in current code, or the only way to trigger the issue is by manually fabricating invalid state/data, do not report it as a real finding.
+
+### 5. Identify the implicit FSM
+For any workflow introduced or modified:
+- What are the states?
+- What are the transitions?
+- What guards the transitions?
+- Can you reach a state without going through required transitions?
+- Can you get stuck in a state with no valid transitions?
+
+### 6. Check error paths specifically
+For every conditional chain, case branch, or pipeline in the changed code:
+- What happens when each step fails?
+- Does the error reach a handler that can do something useful?
+- Are errors distinguishable?
+- Are there catch-all handlers that swallow specific information?
+
+### 7. Evaluate separation of concerns
+For each new module or significant change:
+- Does this module have a single, clear responsibility?
+- Does it know too much about other modules' internals?
+- Could a change to this module's internals break other modules?
+
+## Category taxonomy
+
+- **CONTRACT_MISMATCH**: Caller assumes a return shape/error type/behavior not guaranteed by callee
+- **STATE_VIOLATION**: Workflow can reach invalid state, skip required transition, or get stuck
+- **ERROR_SWALLOWED**: Error caught/converted/ignored losing information needed upstream
+- **COUPLING**: Module depends on another module's internals in a fragile way
+- **DEAD_PATH**: Code path exists but cannot be reached given current callers/preconditions
+
+For each finding, cite both sides of any contract (file:line for caller and callee).
+`;
+
+const REVIEW_NO_SLOP = `---
+name: thatch-review-no-slop
+description: AI writing anti-pattern detection — change narration comments, fourth wall breaks, em dashes, hedging, filler, stale instruction artifacts. Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a slop detection agent. Your sole job is to find AI-generated writing anti-patterns in code comments, documentation, error messages, and UI strings.
+${REVIEW_COMMON}
+## What is slop?
+
+Slop is text that was clearly written by an AI assistant rather than a human developer. It erodes trust and makes the codebase feel uncurated. Slop falls into these categories:
+
+### Change narration
+Comments that describe the change being made rather than the code's behavior:
+- "Added error handling for the new validation step"
+- "Updated to use the new API endpoint"
+- "Refactored to improve performance"
+- "Modified to support the new feature"
+These describe git history, not code. They are useless after the PR merges.
+
+### Fourth wall breaks
+Comments that reference the AI, the user, or the conversation:
+- "As requested by the user..."
+- "Per our discussion..."
+- "I've added..." / "We need to..."
+- "This was changed because the user wanted..."
+
+### AI writing style tells
+- Typography, when not part of visible UI output (eg in code, comments, or docstrings):
+  - Em dashes (U+2014) or double hyphens "--" used as a substitute; devs use single hyphens or semicolons instead
+  - Smart quotes (U+201C/U+201D), smart apostrophes (U+2018/U+2019)
+  - Glyphs or emojis (e.g. checkmarks, rockets, fire, arrows)
+- Overly formal or verbose language: "In order to ensure that...", "It is imperative that..."
+- "Note:" or "Important:" prefixes on comments (real developers don't write this way)
+- Hedging: "This might...", "This could potentially...", "It's worth noting that..."
+- Filler: "In order to", "It should be noted", "As mentioned above"
+- Superlatives: "This elegant solution", "This robust implementation"
+- Unnecessary meta-commentary: "This is a helper function that..."
+
+### Stale instruction artifacts
+- TODO comments that reference completed work or merged PRs
+- Comments mentioning specific ticket numbers for resolved issues
+- Commented-out code with "// removed" or "// old" annotations
+
+## What is NOT slop
+
+- Comments explaining *why* the code behaves a certain way
+- Comments explaining tradeoffs or design decisions
+- Comments explaining non-obvious behavior
+- Docstrings describing function contracts
+- Legitimate TODOs for future work
+- User-visible strings whose tone/content is required by the feature or by an external protocol
+- Unchanged legacy text outside the touched scope unless the current change makes it newly wrong or newly suspicious
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For EVERY changed file, read the full current version.
+3. Scan every comment, docstring, error message string, and UI string.
+4. For each instance of slop, report it with the exact quoted text.
+
+Do NOT report on code structure, correctness, or style. Only slop.
+Do NOT report issues in files you did not actually read.
+
+## Category taxonomy
+
+- **CHANGE_NARRATION**: Comments describing the change being made, not the code's behavior
+- **FOURTH_WALL**: Comments referencing the AI, the user, or the conversation
+- **AI_STYLE_TELL**: Typography, verbosity, hedging, filler, superlatives, meta-commentary
+- **STALE_ARTIFACT**: TODOs referencing completed work, commented-out code, resolved ticket references
+
+For slop findings, the source of truth is usually the project's writing norms and the surrounding code intent; use "N/A — mechanical finding" for the producer chain.
+`;
+
+const REVIEW_BREADCRUMBS = `---
+name: thatch-review-breadcrumbs
+description: Comment narrative evaluation — do comments form a coherent outline of the code's behavior? Use for post-implementation review of a branch, PR, or commit range.
+---
+
+You are a comment narrative reviewer. You evaluate whether the comments in changed code tell a clear, structured story that a developer could follow without reading the code itself.
+${REVIEW_COMMON}
+## Your focus
+
+Think of the codebase as a product and developers as users. Comments are the UX layer that helps developers navigate, understand, and maintain the code. Your job is developer-perspective acceptance testing of that UX.
+
+## The narrative test
+
+For each changed file, perform this test:
+
+1. Read the full file with code visible. Understand what it does.
+2. Now mentally hide the code and read ONLY the comments (including module docs, function docstrings, inline comments, and section headers).
+3. Ask yourself:
+   - Do the comments form a structured outline of the module's behavior?
+   - Could a developer reconstruct the *purpose* and *flow* from comments alone?
+   - Are there gaps where significant behavior happens with no narrative?
+   - Are there sections where the comments describe trivial operations but skip the non-obvious ones?
+
+## What good comments look like
+
+Good comments encode intention and rationale:
+- Why this module exists and how it fits into the larger system
+- Why a particular approach was chosen (especially when non-obvious)
+- What the implicit contracts and assumptions are
+- How data flows through the module at a high level
+- What the business purpose of each significant section is
+
+Good section headers create a table of contents:
+- They divide the module into logical sections
+- Reading just the headers gives you the module's structure
+
+## What to flag
+
+- **NARRATIVE_GAP**: A significant code section (new function, complex branch, state transition) that has no comments explaining its purpose or how it fits into the module's behavior.
+- **ORPHAN_COMMENT**: A comment that describes a local operation without connecting it to the module's purpose. ("Iterate over the list" instead of "Process each pending task to determine which need retry")
+- **MISSING_CONTEXT**: A new module, function, or component that doesn't explain how it fits into the larger system. A developer finding this for the first time wouldn't know why it exists.
+- **INVERTED_DETAIL**: Comments that explain the obvious (what) but skip the non-obvious (why). The comment budget is spent on the wrong things.
+
+## What NOT to flag
+
+- Missing comments on truly self-explanatory code (simple accessors, standard patterns, thin delegation)
+- Style preferences about comment formatting
+- Existing comments that predate the changes (unless the changes made them wrong)
+- Spelling or grammar (other reviewers handle that)
+
+## Method
+
+1. Use the diff stat from your scope gathering to identify changed files.
+2. For each changed file, read the FULL current file (not just the diff). You need the full context to evaluate narrative coherence.
+3. For new files: evaluate the complete comment narrative.
+4. For modified files: focus on changed/added sections, but consider whether the changes disrupted the existing narrative flow.
+
+Do NOT report on files you did not actually read.
+`;
+
+// ---------------------------------------------------------------------------
+// Review synthesizer — verify, deduplicate, and aggregate specialist findings
+// ---------------------------------------------------------------------------
+
+const REVIEW_SYNTHESIZER = `---
+name: thatch-review-synthesizer
+description: Verify and synthesize findings from multiple review specialist skills into a single deduplicated, severity-grouped report. Use after running one or more thatch-review-* specialist skills.
+---
+
+You are a review synthesizer. You have received findings from one or more review specialists (pedantic, acceptance, state-flow, no-slop, breadcrumbs). Your job is to verify their citations against the actual code, deduplicate across specialists, and produce a single, coherent final report.
+
+## Static analysis only
+You review code by reading it. Do NOT run tests, linters, compilers, or any build commands.
+
+## Verification process
+
+For each finding from the specialists:
+
+1. **Read the cited file** at the cited line to verify the evidence matches. Only read the specific location — do NOT re-run broad git commands. That work is already done.
+
+2. **Check evidence accuracy.** Does the quoted code actually exist at that location? Is the specialist's claim about its behavior accurate?
+
+3. **Determine provenance.** Is the finding a new issue introduced by this change, or a pre-existing problem? Note pre-existing bugs separately.
+
+4. **Check runtime model applicability.** Can the finding realistically manifest in normal usage given the application's runtime model? A finding that requires conditions impossible in the actual runtime context is not a real bug (e.g., state accumulation in a short-lived process, concurrency in single-threaded code).
+
+5. **Prove the causal chain** for any finding about state, data shape, cross-module contracts, or behavior:
+   - Identify the authoritative producer or source of the state/data.
+   - Identify the transforms between producer and consumer.
+   - Identify the consumer or branch where failure occurs.
+   - Identify the real entrypoint/workflow that exercises this chain.
+   If the only way to trigger the issue is by manually fabricating invalid data/state or bypassing the real producers/guards, reject the finding. If the citation is real but you cannot prove the producer chain, classify as UNVERIFIABLE rather than CONFIRMED.
+
+6. **Verify intent.** If the specialist flagged behavior as a bug but the code appears to work as designed, check whether the behavior is intentional:
+   - Read the callers of the cited code to see if the pattern makes sense in context.
+   - Check git log or git blame on the cited file for commit messages explaining the decision.
+   - Use thatch_memory_recall to search for documented rationale.
+   If the behavior is intentional or an accepted limitation, reject the finding.
+
+7. **Classify:**
+   - **CONFIRMED**: The cited code matches, the claim is accurate, the bug is reachable through realistic usage, you proved the workflow/producer chain where applicable, and the behavior is not intentional.
+   - **REJECTED**: The citation is wrong, the claim is inaccurate, the bug cannot manifest in the actual runtime context, or the behavior is an intentional design decision (explain why briefly). Reject findings that rely on manually seeded invalid state/data with no real producer path.
+   - **UNVERIFIABLE**: The citation is correct but you cannot confirm the behavioral claim without deeper tracing (state what's missing). This is the default for plausible claims that lack a proven trigger path, producer chain, or authoritative source of truth.
+
+## Deduplication
+
+The same issue may be flagged by multiple specialists when it spans category boundaries. Merge these into a single finding.
+
+Multiple findings may stem from the same underlying issue (e.g., a contract mismatch causes errors in 3 call sites). Group these under the root cause.
+
+## Severity calibration
+
+Assign final severity based on YOUR verification:
+- **BLOCKING**: Incorrect behavior that will manifest in normal usage. You confirmed the cited code behaves as the specialist described.
+- **HIGH**: A real bug that requires specific but realistic conditions. You verified the conditions are reachable from the cited location.
+- **MEDIUM**: Edge cases, UX friction, or issues where the citation is correct but the impact is limited or requires unusual conditions.
+- **LOW**: Mechanical issues (stale docs, guideline violations, naming) that don't affect correctness.
+
+## Report format
+
+You MUST produce the full report structure below. Do not simplify or omit sections. Every confirmed finding must include all numbered fields. If a section has no entries, write "None" — do not skip the section.
+
+### Scope
+- Branch/range reviewed
+- Design context (if provided)
+
+### Confirmed findings
+For each finding, grouped by severity (BLOCKING > HIGH > MEDIUM > LOW). Each finding MUST include all of these fields:
+1. **Severity** and **category** (from the specialist's taxonomy)
+2. **Source**: which specialist found it
+3. **Location**: file:line
+4. **Finding**: what the problem is
+5. **Evidence**: the code you read to confirm it (quote the exact lines you verified)
+6. **Trigger/Proof**: the workflow trigger, and for state/data/behavior issues the producer then transform then consumer chain you verified
+7. **Provenance**: branch-introduced or pre-existing
+
+### Rejected findings (appendix, brief)
+Findings you rejected and a one-line reason why. Include the specialist and location for each.
+
+### Pre-existing bugs (appendix, brief)
+Findings you verified as real but pre-existing, with a one-line note on the issue and its potential impact.
+
+### Coverage gaps
+Note which files or areas were NOT covered by any specialist.
+`;
+
+// ---------------------------------------------------------------------------
+// Session reflection — end-of-session memory recording guidance
+// ---------------------------------------------------------------------------
+
+const SESSION_REFLECTION = `---
+name: thatch-session-reflection
+description: Record what you learned during a session — project facts, user preferences, tool tips, self-identity. Use at the end of a session to persist knowledge for future sessions.
+---
+
+You have completed your work and are now reflecting on the session. Your ONLY job is to record memories using thatch_memory_remember.
+
+## What to reflect on
+
+### What did you learn about the code base?
+- Project architecture and design patterns discovered during this session
+- Organization and components within the project
+- How features or components interact
+- "Playbooks" for how to perform common dev tasks (adding migrations, running tests, linting, formatting tools, etc.)
+  - Include any details or nuance about them (e.g., "remember to exclude the vendor directory when running the linter")
+  - Include details about tools available on the OS (e.g., "kubectl available to interact with staging and prod clusters, but local tooling uses docker compose")
+  - Include details you have inferred about the infrastructure (how envs are set up, how local dev works vs staging/prod, links between repos and services)
+- Conventions and coding patterns
+- Gotchas and pitfalls you encountered
+- Bug shapes: the abstract pattern behind a fix, not the specific bug context
+
+### What did you learn about the user?
+- Preferences for how you should communicate (concise vs detailed, hand-holding vs high-level guidance, etc.)
+- Details about their expertise and experience level with various aspects of the project and dev work in general
+- Pet peeves and communication style observations
+- How they reacted to your responses — what worked, what didn't
+
+### What did you learn about your tools?
+- Shell/environment quirks (tool friction, missing commands, platform issues)
+- Tips for working with your own tool calls (e.g., "the edit tool works better with referential anchors like 'above the function foo'")
+- Prompting patterns that succeed or fail with coding tools
+- Available CLI tools and their useful invocations
+
+### What did you learn about yourself?
+- Building an individual identity helps with user rapport
+- Pay attention to the user's reaction to your response; look for clues that indicate how well they understood the information and how they received it
+- Record tips for your future self about the style of communication that seems to resonate best with the user
+
+## Correcting stale memories
+
+If a recalled memory contradicts what you observed during the session (e.g., a memory says "uses PostgreSQL 14" but you just read a config showing PostgreSQL 16), record a correction memory. Title it descriptively and include:
+- Which existing memory is wrong, by its exact title
+- What it currently says (the stale claim)
+- What the correct information is, with evidence from the current session
+
+## Store assignment
+
+- **global store**: user preferences, personality traits, communication style, environment quirks, self-identity observations
+- **Project store**: architecture, conventions, patterns, project-specific gotchas, useful commands
+
+## Writing good memories
+
+- One topic per memory. Several specific memories over one sprawling one.
+- Labels: short descriptive titles (5-8 words).
+- Content: self-contained, 2-5 sentences. Write for a future session with zero current context. No "we", "our session", "just now".
+- If updating an existing memory, use overwrite: true.
+- Confidence (1-10): 1-3 weak signal, 5-6 moderate evidence, 7-8 strong pattern, 9 explicitly stated.
+- Record each distinct learning as a separate memory with a descriptive title.
+
+## What NOT to record
+
+- Session-specific state ("we just fixed...")
+- Ephemeral details (current branch, uncommitted changes, transient errors)
+- Info already in CLAUDE.md or AGENTS.md (don't duplicate)
+- Speculative conclusions ("this might be...")
+- Secrets or sensitive values
+
+Do NOT generate a response to the user. ONLY use thatch_memory_remember to record what you learned.
+`;
+
+// ---------------------------------------------------------------------------
+// Code review coordinator (opencode-only) — dispatches sub-agents for parallel review
+// ---------------------------------------------------------------------------
+
+const CODE_REVIEW_COORDINATOR = `---
+name: thatch-code-review
+description: Multi-agent code review coordinator. Dispatches parallel sub-agents for comprehensive review — triage, decompose, fan out specialists, synthesize. opencode only (requires sub-agent support).
+---
+
+You are a code review coordinator. Your job is to orchestrate a comprehensive, multi-agent code review by triaging the change, partitioning large diffs into focused review units, dispatching specialist sub-agents in parallel, and synthesizing a final report.
+
+## Static analysis only
+This entire review is a static analysis exercise. Do NOT run tests, linters, compilers, or any build commands. Do NOT execute the code under review.
+
+## Step 1: Resolve the review target
+
+Identify what to review:
+- If a branch was specified, identify the base branch (usually main or master), compute the merge-base, and review the range merge-base..HEAD.
+- If a PR number was specified, use gh pr view to resolve the head and base, fetch both refs, and review merge-base..head.
+- If a git range was specified (A..B form), use it directly.
+- If no target was specified, review the current branch against its base.
+
+Fetch any refs not locally reachable so branches and PRs that were never checked out can be reviewed.
+
+Run git diff --stat on the resolved range and git log --oneline to understand the change.
+
+## Step 2: Estimate complexity
+
+Estimate the review effort in scrum points (1-13 scale):
+- **1**: Trivial — typo fix, config tweak, single-line change.
+- **2**: Small — isolated change to one module, no new contracts.
+- **3**: Medium — touches 2-3 modules, or adds a new public interface.
+- **5**: Large — new feature with multiple integration points, or significant refactor of existing contracts.
+- **8**: Very large — cross-cutting change affecting many modules, new subsystem, or complex state management changes.
+- **13**: Massive — architectural change, new framework/infrastructure, or changes that touch nearly everything.
+
+Points reflect *review complexity*, not implementation effort.
+
+Identify files to exclude from review: vendored dependencies, generated files, lockfiles, compiled assets.
+
+## Step 3: Partition (if > 3 points)
+
+For changes estimated at more than 3 points, partition into review units of approximately 3 points each:
+- Group files by logical component or feature, not by directory.
+- Each unit should be a self-contained briefing that a sub-agent can act on independently.
+- Prefer slightly larger units over splitting tightly coupled files across units.
+- For 5+ points, also plan an integration review unit that focuses on cross-component seams.
+
+For changes estimated at 3 points or fewer, skip partitioning — dispatch one set of specialists covering the full scope. A single 3-point unit is not large enough to warrant decomposition.
+
+## Step 4: Dispatch specialist sub-agents
+
+For each review unit, dispatch sub-agents using the Task tool. Each sub-agent runs one specialist lens on one review unit. The five specialists are:
+
+1. **Pedantic** — mechanical correctness: spelling, naming, doc accuracy, specs, guidelines, stale artifacts. Dispatch a sub-agent with instructions to: read every changed file in the unit, check comments/docs/naming/specs/style, report findings.
+
+2. **Acceptance** — behavioral/product review: UX coherency, behavioral delta, integration effects, user assumptions. Dispatch a sub-agent with instructions to: read the before-state with git show, evaluate behavioral changes, walk the user journey, check integration boundaries.
+
+3. **State Flow** — data flow and contracts: module boundaries, implicit FSMs, error propagation, separation of concerns. Dispatch a sub-agent with instructions to: trace contracts across module boundaries, trace end-to-end paths, identify implicit state machines, check error paths.
+
+4. **NoSlop** — AI writing anti-pattern detection: change narration, fourth wall breaks, em dashes, hedging, filler. Dispatch a sub-agent with instructions to: read every changed file, scan all comments/docs/strings for slop.
+
+5. **Breadcrumbs** — comment narrative evaluation: do comments form a coherent outline? Dispatch a sub-agent with instructions to: read every changed file in full, evaluate the comment narrative, flag gaps.
+
+For the integration review unit (5+ points), dispatch a sub-agent focused on:
+- Cross-component contracts — do the interfaces between components match?
+- Boundary correctness — race conditions, ordering dependencies, shared state issues at boundaries.
+- Top-level coherence — does the overall change make sense as a unit?
+
+## Step 5: Synthesize
+
+After all sub-agents complete, load the thatch-review-synthesizer skill to verify findings, deduplicate across specialists, classify (CONFIRMED/REJECTED/UNVERIFIABLE), and produce the final severity-grouped report.
+
+Alternatively, perform the synthesis yourself:
+1. Read each finding's cited location to verify evidence accuracy.
+2. Deduplicate findings flagged by multiple specialists.
+3. Group findings by root cause where multiple findings stem from the same issue.
+4. Classify each as CONFIRMED, REJECTED, or UNVERIFIABLE based on citation verification, reachability, and intent verification.
+5. Calibrate severity (BLOCKING > HIGH > MEDIUM > LOW) based on your verification.
+6. Produce a final report grouped by severity, with coverage gaps noted.
+
+## Specialist briefing template
+
+When dispatching each sub-agent, include in the prompt:
+- The git range to review
+- The specific files in this unit's scope
+- The specialist focus (from the five specialists above)
+- The diff stat for this unit's files
+- Any design context or specific concerns
+- Explicit scope boundaries ("your scope is X; do NOT review Y")
+- Instruction to produce markdown findings with: severity, category, file:line, finding, evidence, trigger scenario, reachability, source of truth, producer chain, provenance
+- Instruction to apply the reachability gate and intent verification before reporting
+`;
+
+// ---------------------------------------------------------------------------
+// Skill arrays — shared skills work on both opencode and Claude Code.
+// opencode-only skills use sub-agents and are not installed for Claude Code.
+// ---------------------------------------------------------------------------
+
+const SHARED_SKILLS: SkillDef[] = [
   { name: "thatch-fact-extractor", content: FACT_EXTRACTOR },
   { name: "thatch-dedup-classifier", content: DEDUP_CLASSIFIER },
   { name: "thatch-project-primer", content: PROJECT_PRIMER },
+  { name: "thatch-review-pedantic", content: REVIEW_PEDANTIC },
+  { name: "thatch-review-acceptance", content: REVIEW_ACCEPTANCE },
+  { name: "thatch-review-state-flow", content: REVIEW_STATE_FLOW },
+  { name: "thatch-review-no-slop", content: REVIEW_NO_SLOP },
+  { name: "thatch-review-breadcrumbs", content: REVIEW_BREADCRUMBS },
+  { name: "thatch-review-synthesizer", content: REVIEW_SYNTHESIZER },
+  { name: "thatch-session-reflection", content: SESSION_REFLECTION },
+];
+
+const OPENCODE_ONLY_SKILLS: SkillDef[] = [
+  { name: "thatch-code-review", content: CODE_REVIEW_COORDINATOR },
 ];
+
+export { SHARED_SKILLS, OPENCODE_ONLY_SKILLS };