@jeffober/thatch 0.2.1 → 0.2.2

package/README.md

@@ -194,8 +194,10 @@ Thatch gives your agent:
   auto-joining with `chat.autoRegister: false`).
 - **Slash commands** -- `/thatch/defrag` (consolidate duplicate memories),
   `/thatch/extract` (drain the extraction queue now), `/thatch/hygiene`
-  (tend stale and orphaned memories), and `/thatch/reflect` (persist what
-  the session learned) run on demand the same behaviors the nudges run on
+  (tend stale and orphaned memories), `/thatch/reflect` (persist what
+  the session learned), and `/thatch/refine` (refine a plan under the
+  project type's requirements, classifying the project first) run on
+  demand. The first four mirror the same behaviors the nudges run on
   their own schedule. Plus the opencode-only wrap-ups: `/thatch/compact` and
   `/thatch/exit` run a pre-flight checklist before a compaction or an exit:
   the agent flushes pending fact extraction, finishes promised memory

package/artifacts/skills/thatch-plan-refinement.md

@@ -1,6 +1,6 @@
 ---
 name: thatch-plan-refinement
-description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
+description: Refine a plan for a code change by dispatching a fresh-context reviewer subagent to hunt for gaps, unverified premises, and unexpected side effects, then revising and re-reviewing until consensus. Use when a plan is about to be implemented, when the user asks to refine, stress-test, or double-check a plan, or after a plan revision that incorporated prior findings. This is the generic core loop; when the project type should shape the refinement bar, load thatch-refine instead and it will apply a type delta on top of this loop. Quick mode is one fresh reviewer per round; deep mode adds a specialist lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology).
 ---
 
 You are refining a plan before code exists. A plan written by the same context that researched the problem inherits that context's blind spots. A reviewer with no stake in the plan and no memory of writing it finds what the author cannot. Refinement is the loop: draft, review, revise, repeat until consensus. Each pass tightens the plan; a round with no findings means the plan is done, not that the loop failed.
@@ -75,7 +75,8 @@ One reviewer per round in quick mode; one lens fan-out total in deep mode, then
 
 ## Relationship to other skills
 
-- **`thatch-code-archaeology`** — the research skill for understanding the code; its output is often the plan's input. The archaeology lens is a targeted, plan-scoped re-run of its git-history step, not a replacement for it.
+- **`thatch-refine`** - the type-aware entry point. Different project types need different refinement bars: a team codebase owes coordination and breadcrumbs, a personal project allows cleverness, a shared library owes API hygiene. When the user runs `/thatch/refine` or the project's type should shape the bar, load `thatch-refine` first; it classifies and hands back a thatch-refine-* delta to apply on top of this loop. This skill stays the generic core.
+- **`thatch-code-archaeology`** - the research skill for understanding the code; its output is often the plan's input. The archaeology lens is a targeted, plan-scoped re-run of its git-history step, not a replacement for it.
 - **`thatch-coding-workflow`** — the procedure skill for executing the refined plan. Refinement ends where coding-workflow begins.
 - **`thatch-ticket-description` / `thatch-pr-description`** — if the refined plan feeds a ticket or PR description (or the session iterated on one using this skill), RE-LOAD the appropriate writing skill and draft within its contract. A plan is a working artifact for the session that wrote it; a ticket or PR description is a reader-facing document with its own sections, verbosity budget, and prose rules. Refinement output — findings, accepted risks, review rounds — is SOURCE MATERIAL for those skills, never a substitute for them. This holds the right level of detail for the medium and keeps the writing clear.
 - **`thatch-clear-writing`** — for any other human-facing text produced along the way (reports, comments, docs).

package/artifacts/skills/thatch-refine-infra.md

@@ -0,0 +1,66 @@
+---
+name: thatch-refine-infra
+description: Type-specific requirements for refining a plan that touches infrastructure (CI pipelines, Terraform, Kubernetes manifests, build and deploy configuration). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when a wrong premise can break deploys or pipelines for everyone downstream.
+---
+
+You are refining a plan for an **infra** change: CI pipelines, Terraform,
+Kubernetes manifests, build and deploy configuration. The governing value
+is blast radius: a wrong premise here does not break one feature, it
+breaks every pipeline, environment, or developer downstream of it, often
+silently and often for everyone at once. Load `thatch-plan-refinement`
+for the core loop and apply the deltas below; where they disagree, these
+win.
+
+## What this type owes
+
+- **Near-absolute pattern-following.** Configuration is the worst place
+  for novelty. Copy the established pattern from a sibling pipeline,
+  module, or manifest even when a better one exists; propose the better
+  one as its own change, after this one lands.
+- **Rollback as a first-class deliverable.** Every change names how it
+  backs out, concretely (which command, which revert, which state to
+  re-apply), not "revert the commit if problems arise."
+- **Staged verification.** The plan verifies against a non-production
+  target first (staging environment, a canary job, a dry-run or plan
+  output) and names what a successful verification looks like before
+  production applies it.
+
+## How this changes the loop
+
+- **Deep mode is the default.** Infra changes almost always touch shared
+  persistent state that other consumers read, which is the core skill's
+  first deep-mode trigger.
+- **Premises verify against live state, not memory.** The most dangerous
+  infra premise is "the current setup is X" recalled from memory. Check
+  the actual manifests, the actual pipeline config, the actual running
+  versions, and cite where you checked. Terraform drift and manual
+  console changes make memory especially unreliable here.
+- **Consensus is unchanged**, but the reviewer prompt should emphasize
+  checking the rollback and verification sections explicitly.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) dominates.** The question is "who reads
+  this state that the plan does not know about?" - dependent pipelines,
+  environments sharing the module, developers relying on cache behavior,
+  jobs relying on timing. Enumerate the dependents by reading what
+  actually references the resource, not by recollection.
+- **Safe-to-modify is second.** An infra change landing in untested
+  configuration without a verification step is a finding.
+- **Alternatives and pattern/reuse mostly skip.** The pattern question
+  was answered above: follow it.
+
+## Extra plan sections
+
+- **Rollback plan.** Concrete and executable, as above.
+- **Verification step.** What runs in staging or dry-run first, and what
+  result counts as safe to proceed.
+- **Sequencing.** Infra changes often must land in an order (create
+  before reference, drain before delete). The plan states the order and
+  what breaks if it is violated.
+
+## Docs bar
+
+A one-paragraph change note for the team (what changed, why, how to
+roll back) is the deliverable. Config comments explain constraints the
+next person must not violate.

package/artifacts/skills/thatch-refine-oss-contribution.md

@@ -0,0 +1,68 @@
+---
+name: thatch-refine-oss-contribution
+description: Type-specific requirements for refining a plan for a contribution to an open source repository the user does not maintain. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. The maintainer's design authority and house style govern, and the diff stays minimal.
+---
+
+You are refining a plan for an **oss-contribution**: a change to a
+repository the user does not maintain. The governing value is the
+maintainer's design authority. It is their codebase; the contribution
+that gets merged is the one that fits their intent, not the one that
+would be best by your lights. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Conform to house style, even when it is worse.** A foreign codebase's
+  conventions are not up for improvement in this change. Do not import
+  patterns from other projects; do not refactor what the maintainer
+  wrote.
+- **Minimal diff.** No drive-by refactors, no reformatting of untouched
+  lines, no new dependencies, no new abstractions beyond what the change
+  strictly needs.
+- **The discussion comes first.** Significant design work waits until the
+  approach has a maintainer's nod: check CONTRIBUTING.md, search open
+  and closed issues and PRs for the same idea, and file or comment on
+  the proposal before investing in the implementation. A plan that
+  assumes acceptance is building on an unverified premise.
+
+## How this changes the loop
+
+- **Add a premise class: upstream status.** Every plan premise about the
+  maintainer's intent (is this wanted, is the approach acceptable, is
+  the issue still open) needs evidence: an issue thread, a maintainer
+  comment, a CONTRIBUTING instruction. No evidence means "unknown -
+  ask upstream," and the plan gates on that question, not on a guess.
+- **Consensus adds one test.** Alongside the core skill's consensus
+  criteria, the reviewer answers: "would a maintainer accept this
+  scope?" Scope findings are blockers. A contribution that solves the
+  issue plus three adjacent problems will sit unmerged.
+- **Round cap unchanged.** But a plan blocked on upstream discussion
+  pauses for the user to have that conversation; it does not loop.
+
+## Lens weights
+
+- **Pattern and reuse inverts.** In team code, existing patterns are a
+  strong default; here they are the requirement. A "better" pattern than
+  the house style is a finding against the plan, not for it.
+- **Hidden problems shrinks.** Consumers of internal state are the
+  maintainer's concern. Focus on the change's own footprint and its
+  interaction with in-flight upstream work (search open PRs for overlap).
+- **Alternatives mostly skips.** The maintainer chose the architecture.
+  The plan's job is fitting into it, and where the plan needs a
+  maintainer decision, that is an upstream question, not an alternatives
+  survey.
+
+## Extra plan sections
+
+- **Upstream discussion.** The issue or thread this change responds to,
+  and the maintainer signals (or absence of them) the plan relies on.
+- **House-style conformance.** The specific conventions the change will
+  follow, read from the project's own CONTRIBUTING and recent merged
+  PRs, not assumed.
+
+## Docs bar
+
+Match the project's own documentation conventions for any user-facing
+text (changelog entries, docs pages) and the house code-comment style.
+The writing skills still govern clarity, but the structure and tone
+follow the project's.

package/artifacts/skills/thatch-refine-personal.md

@@ -0,0 +1,61 @@
+---
+name: thatch-refine-personal
+description: Type-specific requirements for refining a plan in a solo personal project with no downstream consumers. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Relaxes coordination requirements and allows cleverness and experimentation, while keeping premise verification honest.
+---
+
+You are refining a plan for a **personal** project: solo code with no
+downstream consumers. The coordination constraints that govern team code
+are relaxed. This is the place to show off cleverness and experiment with
+interesting techniques that would be inconsiderate in a shared codebase.
+Load `thatch-plan-refinement` for the core loop and apply the deltas
+below; where they disagree, these win.
+
+## What this type owes
+
+- **Almost nothing to anyone else.** No consistency obligation to
+  teammates, no reviewer to orient, no downstream API to protect.
+- **Still honest about facts.** Relaxed style does not mean relaxed
+  reality: every factual premise still carries a verified `file:line`
+  citation, and "unverified" is still marked. A plan built on a wrong
+  premise wastes your time in any project.
+
+## How this changes the loop
+
+- **The skip threshold drops.** Most personal-project plans can be tried
+  faster than they can be refined. Skip refinement whenever the change is
+  cheap to build and cheaper to rewrite; run the loop only when the plan
+  touches something expensive to get wrong (persistent state, a
+  hard-to-reverse migration, hours of build effort).
+- **Fewer rounds.** One quiet review round is enough consensus. The cap
+  drops from three rounds to two; a personal plan that has not converged
+  by then should just be built or abandoned.
+- **Degraded review is fine.** If the host cannot dispatch sub-agents, a
+  same-context self-review pass is usually enough. Saying so out loud, as
+  the core skill requires, is still worthwhile but the stakes are lower.
+
+## Lens weights
+
+- **Premise verification is the only load-bearing lens.** The fresh
+  reviewer's core job is checking the plan's factual model of the code.
+- **Pattern and reuse mostly skips.** There is no team to stay consistent
+  with. Flag reuse only when reinventing an existing wheel will genuinely
+  bite future-you.
+- **Alternatives turns exploratory.** The question shifts from "what is
+  safest?" to "what would I learn?" - one alternative worth trying for
+  the technique is a valid result even when the plan's choice is fine.
+- **Hidden problems shrinks to future-self.** The only consumer to
+  enumerate is you, six months from now, with no memory of this code.
+
+## Extra plan sections
+
+None required. Blast radius, migration plans, and reviewer orientation
+sections are skipped unless the change is in the expensive-to-get-wrong
+category that triggered refinement at all.
+
+## Docs bar
+
+- Future-self breadcrumbs only: comment the surprising spots, not the
+  obvious ones.
+- When a plan deliberately uses an experimental technique, record that in
+  one line (in the plan or a comment) so a future session knows the
+  oddity was chosen, not accidental.

package/artifacts/skills/thatch-refine-shared-lib.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-shared-lib
+description: Type-specific requirements for refining a plan that touches a library's API surface, in any repo, including personal ones. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use whenever exported API, published packages, or downstream consumers are involved; API hygiene governs even solo projects.
+---
+
+You are refining a plan for a **shared-lib** change: work that touches an
+API other code consumes and keeps working against. This applies to any
+library with external callers, including a personal one. The governing
+value is API hygiene: you are writing for consumers you cannot see and
+cannot call back. Load `thatch-plan-refinement` for the core loop and
+apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Flexible on input, strict on output.** Accept broad input types and
+  normalize them; return precise, well-defined types and never leak
+  internal representations. Callers write code against your output
+  shapes; widen what you accept, pin down what you emit.
+- **Keep special cases out of the API.** No caller-specific knobs, no
+  one-off escape hatches, no parameters that exist for exactly one
+  consumer. A special case is a design smell: handle it inside the
+  implementation or reject it at the boundary.
+- **Do not foreclose caller options.** Prefer returning data over making
+  decisions callers might want to make differently. Every shortcut the
+  library takes on the caller's behalf is a wall they hit later.
+- **Keep the surface small.** Every export is a permanent maintenance
+  promise. The best API change is often the one that exports nothing new.
+
+## How this changes the loop
+
+- **Deep mode is the default** for anything that adds, changes, or
+  removes an export. The abstraction gets locked in at ship time; after
+  release, changing it costs every consumer. This is the last cheap
+  moment to get the shape right.
+- **Alternatives works harder here.** "No better alternative found" must
+  be argued harder than the core skill's paragraph: enumerate the
+  plausible alternative shapes and say why the plan's shape wins for
+  callers, not just for the implementation.
+- **Backward compatibility findings are blockers by default.** A breaking
+  change without a deprecation path is a blocker, not a should-fix.
+
+## Lens weights
+
+- **Hidden problems reframes entirely.** Every consumer is a stranger;
+  you cannot grep your callers. Enumerate the contract the plan changes
+  and reason about the population of consumers you cannot see, including
+  the ones using the API in ways you never intended.
+- **Pattern and reuse applies to your own API first.** Consistency with
+  the library's existing API conventions is its own requirement: a
+  second method that disagrees with the first in naming or shape is a
+  finding even when both are internally fine.
+
+## Extra plan sections
+
+- **API surface diff.** Exactly what is exported, added, changed, or
+  removed, in a list a reviewer can check one line at a time.
+- **Semver impact and deprecation path.** The version bump this deserves,
+  what is deprecated, and how callers migrate.
+- **External documentation.** The docs and examples this change requires,
+  written for the reader: what the behavior is, when to use it, what it
+  does not do. "I'll document it later" is a finding.
+- **Caller migration notes.** For breaking or behavior-changing exports,
+  the note that goes in the changelog.
+
+## Docs bar
+
+Reader-facing documentation is a plan deliverable, not a follow-up. Draft
+it under the writing skills' contracts: define terms on first use,
+behavior stated precisely enough that a caller needs no source dive.

package/artifacts/skills/thatch-refine-spike.md

@@ -0,0 +1,53 @@
+---
+name: thatch-refine-spike
+description: Type-specific requirements for refining a plan for a throwaway prototype or time-boxed spike. Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Skips almost all of the loop, verifying only the premises the experiment's conclusion depends on.
+---
+
+You are refining a plan for a **spike**: throwaway code whose purpose is
+answering a question, not producing a maintained artifact. Almost all of
+the refinement loop is waste here. Load `thatch-plan-refinement` for the
+core loop, then apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **A stated question.** The plan opens with the question the spike
+  exists to answer, stated concretely enough that "done" is checkable
+  ("can Postgres full-text search handle our query volume?" not "explore
+  search options").
+- **A promotion test.** The plan states what would make this code worth
+  promoting into the real codebase versus rewriting it properly. Most
+  spikes end in a rewrite, and that is a success, not a failure.
+- **A time box.** The plan names its budget: hours or days, not open-
+  ended effort.
+
+## How this changes the loop
+
+- **Skip the loop by default.** No reviewer dispatch, no rounds, no
+  consensus machinery. One focused self-review pass is the whole
+  refinement: check the plan's few load-bearing premises, then build.
+- **Verify only conclusion-bearing premises.** The spike's conclusion is
+  only as good as the premises it depends on. If the experiment claims
+  "this approach is too slow," the benchmark setup and the
+  representativeness of the test data are the premises that matter, and
+  they get the verified-citation treatment. Everything else is
+  throwaway.
+- **Degraded review needs no apology.** The core skill's honest-degradation
+  notice is unnecessary; there is no real review to degrade.
+
+## Lens weights
+
+All specialist lenses skip except one consideration: **is the spike
+actually throwaway?** If the plan quietly assumes the prototype code will
+survive into production, stop and surface that. A spike that is really a
+production change wearing a costume should be refined under the type it
+actually is.
+
+## Extra plan sections
+
+- The question, the promotion test, and the time box above. Nothing else.
+
+## Docs bar
+
+No breadcrumb obligation. One comment or note recording the question and
+the answer is enough. The spike's real output is the answer, and it
+should be written down where the user will find it.

package/artifacts/skills/thatch-refine-team-app.md

@@ -0,0 +1,69 @@
+---
+name: thatch-refine-team-app
+description: Type-specific requirements for refining a plan in a multi-developer team codebase (production app or service shared by a team). Loaded by thatch-refine after classification; assumes the core loop in thatch-plan-refinement. Use when coordination cost, consistency, and reviewer comprehension are the governing constraints.
+---
+
+You are refining a plan for a **team-app** project: production code in a
+repository where multiple developers ship, review, and maintain each
+other's work. The governing value is org velocity through coordination and
+consistency. Code is read far more often than it is written, and most of
+its readers did not write it. Load `thatch-plan-refinement` for the core
+loop and apply the deltas below; where they disagree, these win.
+
+## What this type owes
+
+- **Consistency outranks local optimality.** Following the codebase's
+  existing pattern beats a "better" one that splits the codebase in two.
+  A novel approach must justify the divergence it imposes on every future
+  reader, not just prove it is cleverer.
+- **Implement for the junior reviewer.** The bar is that a developer with
+  no history in this area can review the change and debug it at 2am.
+  Cleverness is allowed only with a justification comment at the point of
+  cleverness, and only when the payoff is real.
+- **Intent is a deliverable.** Docstrings and comments are the breadcrumb
+  trail for the next maintainer. The plan says which comments and
+  docstrings it will write, and *why* is documented, not just *what*.
+
+## How this changes the loop
+
+- **Mode triage stays strict.** The skip threshold does not relax for
+  team code: anything another developer must review earns at least quick
+  mode. Established-pattern changes with no design decisions can still
+  skip, as the core skill already provides.
+- **Deep mode triggers broaden.** Beyond the core skill's triggers, deep
+  mode is warranted when the change alters a contract other teams build
+  on, or lands in an area with a history of review churn.
+- **Consensus is unchanged.** Same rounds, same cap, same escalation to
+  the user.
+
+## Lens weights
+
+- **Hidden problems (pre-mortem) carries the most signal.** In team code
+  the plan's biggest risk is an unenumerated consumer or an implicit
+  contract another team relies on.
+- **Safe-to-modify is second.** A plan that lands in an untested,
+  tangled section without a refactor-first dependency is a finding.
+- **Pattern and reuse tightens.** "Reuse the existing pattern" is the
+  default verdict, not one option among several. A plan that introduces a
+  parallel way to do something the codebase already does needs a strong,
+  evidenced reason.
+- **Alternatives stays a filter.** Two alternatives, one paragraph each,
+  as the core skill says; the judgment criterion is team cost, not
+  personal preference.
+
+## Extra plan sections
+
+- **Blast radius and consumers.** Who reads the state, tables, config, and
+  symbols this change touches, including other teams and services.
+- **Migration and rollback.** How the change ships safely and how it
+  backs out.
+- **Intent breadcrumbs.** The docstrings and comments the implementation
+  will write, and what future-reader question each answers.
+- **Reviewer orientation.** One paragraph a reviewer can read first: what
+  changed, why, and where to look.
+
+## Docs bar
+
+Comments and docstrings are part of the definition of done, and any
+reader-facing text produced along the way (PR description, ticket,
+changelog entry) is drafted under the writing skills' contracts.

package/artifacts/skills/thatch-refine.md

@@ -0,0 +1,84 @@
+---
+name: thatch-refine
+description: Classify the current project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the thatch-refine-* family. Use when the user asks to refine a plan, runs /thatch/refine, or when a plan is about to be implemented and the project type should shape the refinement bar. For a bare "refine this plan" request, load this skill rather than thatch-plan-refinement directly - the router picks the type and applies its delta on top of the core loop.
+---
+
+You are the entry point for project-type-aware plan refinement. The core
+refinement loop (draft, fresh-context reviewer, revise, consensus) is the
+same everywhere; it lives in `thatch-plan-refinement`. What changes by
+project type is the bar: which lenses matter, what the plan must contain,
+how much documentation is owed, and when skipping refinement is honest.
+
+## The types
+
+| Type | Governing value | Skill |
+|------|-----------------|-------|
+| `team-app` | Coordination and consistency promote org velocity | `thatch-refine-team-app` |
+| `personal` | Freedom to experiment; low coordination cost | `thatch-refine-personal` |
+| `shared-lib` | API hygiene; never foreclose caller options | `thatch-refine-shared-lib` |
+| `spike` | Answering a question cheaply, not producing code | `thatch-refine-spike` |
+| `infra` | Blast radius across pipelines and environments | `thatch-refine-infra` |
+| `oss-contribution` | The maintainer's design authority | `thatch-refine-oss-contribution` |
+
+## Classification
+
+Classify on three axes, then pick the type whose requirements this plan
+must satisfy. Classify **the change**, not just the repo: a personal repo
+gaining a published API is a `shared-lib` plan for that change, even if the
+repo is `personal` overall.
+
+**Audience** - who reads and maintains this code.
+
+- Solo: one contributor in git history, no CODEOWNERS, no required reviews.
+- Team: CODEOWNERS, CONTRIBUTING.md, required PR review, multiple regular
+  authors.
+- Public: published package (npm/PyPI/etc. metadata, `publishConfig`), or
+  consumers outside the repo you cannot enumerate.
+
+**Lifecycle** - what this code owes anyone.
+
+- Production: protected main, CI gates, deploy configuration, semver
+  discipline.
+- Experimental: active WIP, churny main, thin or absent tests.
+- Throwaway: a question wearing a repository.
+
+**Surface** - what the change lives in.
+
+- Application: end-user or service code with no downstream importers.
+- Library: exported API that other code imports and keeps working against.
+- Infrastructure: CI, Terraform, k8s manifests, build and deploy config.
+
+Signals to gather (all cheap and read-only): `git log --format="%an" |
+sort -u | head`, presence of CODEOWNERS / CONTRIBUTING.md / required
+review config, package.json `private` and `publishConfig` fields, the
+publishing config of the relevant ecosystem, presence of `.github/workflows`,
+`terraform/` or k8s manifests, and what the package exports. Do not
+over-invest here; the classification should cost a minute, not a research
+pass.
+
+## Procedure
+
+1. If the user named a type explicitly (for example `/thatch/refine
+   shared-lib`), skip classification and use it.
+2. Otherwise gather the signals above and pick the type.
+3. State the classification in one line and why, and let the user override.
+   A wrong classification silently changes the requirements, so the user
+   sees the pick before it takes effect. When the signals conflict or are
+   too thin to pick, ask instead of guessing.
+4. Load `thatch-plan-refinement` (the core loop) and the type's skill.
+5. Run the core loop with the type skill's deltas applied. Where a delta
+   and the core skill disagree, the delta wins; that is its whole job.
+
+If no type fits (the repo serves a niche the table misses), run plain
+`thatch-plan-refinement` and say that the requirements are the generic
+ones.
+
+## Relationship to other skills
+
+- **`thatch-plan-refinement`** - the core loop. Always loaded; the type
+  skills only modify it.
+- **`thatch-coding-workflow`** - the procedure skill for executing the
+  refined plan. Refinement ends where it begins.
+- **`thatch-clear-writing`** and the writing skills - several type skills
+  make reader-facing documentation a plan deliverable. Draft that text
+  under the writing skills' contracts, not this one's.

package/docs/dev/gotchas.md

@@ -286,3 +286,16 @@ instead of throwing "Cannot use a closed database". Two rules keep this intact:
   wrap-up arming write, whose command executes are not drained by the v2
   cleanup). Do not "fix" the guard away by moving it into db.ts: the
   accessor cannot tell a legitimate in-flight caller from a stale writer.
+
+## Command frontmatter descriptions must be quoted YAML scalars
+
+- **A plain-scalar frontmatter value containing a colon followed by a space
+  is invalid YAML, and not every host path rescues it.** `/thatch/hygiene`'s
+  description ("Tend the memory store: stale entries, ...") shipped unquoted;
+  the first parse throws
+  and only opencode's fallback sanitizer recovers it — and a long-lived
+  server was observed dropping the description entirely while a fresh server
+  parsed it fine, which made the bug look like a TUI rendering issue. The
+  renderer quotes every description (`yamlQuote` in src/commands.ts) and a
+  unit test pins the quoted form. Keep it that way for any new frontmatter
+  field whose value is free-form prose.

package/docs/dev/mcp-parity.md

@@ -23,7 +23,7 @@ This document maps the feature parity and documents the remaining gaps.
 | **Session-start reminder** (recall nudge + hygiene heartbeat) | `session.created` event → `client.session.prompt` injects a synthetic message | `SessionStart` hook → `thatch reminder`; stdout becomes context | `sessionStart` hook → `thatch reminder --json`; output is `additional_context` JSON | **Full** |
 | **Compaction context** (re-familiarize after compaction) | `experimental.session.compacting` hook appends context to the compaction output | `PostCompact` hook — side-effects only, **cannot inject context** | No equivalent hook | **Gapped** — see below |
 | **Wrap-up commands** (`/thatch/compact`, `/thatch/exit`) | Command markdown synced to `$XDG_CONFIG_HOME/opencode/command/thatch/` at plugin init; `command.execute.before` arms the session and the next idle resolves the greenlight token into a TUI action (`session.compact` via `executeCommand`, `app.exit` via `publish`) | No equivalent — no plugin host to arm the check or trigger the action | No equivalent | **Gapped** — needs the plugin's SDK client and TUI control routes |
-| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
+| **On-demand actions** (`/thatch/defrag`, `extract`, `hygiene`, `reflect`, `refine`) | Command markdown synced at plugin init; bodies rendered from the shared prompt cores with `thatch_` tool spellings; `extract` is opencode-only (needs session identity via `get_session_info` and the plugin's payload provider) | Command markdown synced by `thatch setup --claude` into `<claudeDir>/commands/thatch/`; same cores with `mcp__thatch__` spellings; `extract` excluded | MCP Prompts (`prompts/list` + `prompts/get`) from the same cores; Cursor surfaces them as slash commands; `extract` excluded | **Full** for the shared actions (same cores, per-host tool spellings); `extract` opencode-only |
 | **Extraction** (buffer tool calls, extract durable facts) | `tool.execute.after` buffers non-meta tool calls in-process (`isMetaToolName` in `src/extraction.ts`: thatch_*, skill, task, agent, subagent — execute calls unwrapping only thatch tools are also excluded); **direct extraction** is the primary path — when the parent session goes idle with pending buffer entries, the plugin creates a child session via the SDK (`client.session.create` with `parentID`) and prompts it to call `get_extraction_payload` (nudge suppressed via the `extracting` set); the `chat.message` nudge path is a **fallback** used when direct extraction throws | `PostToolBatch` → `thatch buffer-batch` (file-backed JSONL queue); `UserPromptSubmit` → `thatch flush-tools` peeks the queue and prints the nudge with session ID + fetch tool name (does not drain — the queue persists until a memory write or `extraction_done`) | `postToolUse` → `thatch buffer-tool` (single-tool, file-backed queue); `beforeSubmitPrompt` → `thatch flush-tools --json` | **Partial** — opencode uses direct extraction (parent idle → child session) as the primary path, with the nudge as fallback; MCP hosts are nudge-only. Both paths use `get_extraction_payload` to fetch the queued interactions as a tool response, keeping the full payload out of the main session's context window. Nudge timing differs: the nudge arrives at the **start** of the next turn in Claude Code/Cursor; opencode's direct extraction fires at **end of turn** (session idle), and the nudge fallback fires at the start of the next turn like MCP |
 | **Extraction feedback** (toast notifications) | `client.tui.showToast` fires when the extraction child goes idle — shows `[thatch] new: N, updated: M, deleted: K` (success) or `extraction complete — nothing to save` (info); best-effort, silently ignored in headless mode | No TUI connection — MCP hosts have no equivalent | No TUI connection | **Gapped** — MCP hosts cannot show toast notifications |
 | **Automatic alerts** (notify on LLM pause / turn end) | Plugin event hook drives the `alerts.ts` state machine: `question.asked`/`permission.asked` → pause alert; `session.status` idle with a real-work round → done alert; unrecovered errors → needs-attention. Delivered via the shared `notify.ts` dispatcher, channel per event from the `alerts` config section | No event stream — only `thatch_notify_user` when the agent chooses | No event stream — only `thatch_notify_user` when the agent chooses | **Gapped** — MCP hosts have no plugin event hook to watch; Claude Code's `Notification`/`Stop` hooks could feed the same classifier later |

package/docs/dev/skills.md

@@ -55,7 +55,14 @@ description: Extract durable project facts ... Use when ...
 | `thatch-code-walkthrough` | Explain a feature, module, or workflow to the user as a teaching walkthrough: identify the code area (optionally from a branch or PR), research how it works, teach it with file:line citations and analogies, list the key files. |
 | `thatch-session-reflection` | End-of-session memory recording (project, user, tools, self). |
 | `thatch-coding-workflow` | Plan and execute code changes with a task-list-driven workflow. Use when implementing features, fixing bugs, or making multi-file changes. |
-| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). |
+| `thatch-plan-refinement` | Refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). The generic core loop. |
+| `thatch-refine` | Classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements. Entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box. |
+| `thatch-refine-infra` | Refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | Refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
 | `thatch-pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
 | `thatch-ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, 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. |

package/docs/user/README.md

@@ -328,6 +328,13 @@ response, walkthrough, and workflow skills that support the review pipeline:
 | `thatch-code-walkthrough` | Explains a feature, module, or workflow to the user as a teaching walkthrough with file:line citations. Also used to draft high-level docs for new or undocumented features. |
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
 
 ### Writing skills
 

package/docs/user/commands.md

@@ -17,6 +17,13 @@ or you invoke it.
   The agent asks before forgetting anything that may still matter.
 - `/thatch/reflect` — run the session-reflection skill to persist what the
   current session learned.
+- `/thatch/refine` — refine a plan for a code change under the current
+  project type's requirements: the agent classifies the project (team,
+  personal, shared library, spike, infrastructure, or open source
+  contribution), confirms the pick, and runs the refinement loop with
+  that type's expectations applied. Text after the command can name the
+  type directly (for example, `/thatch/refine shared-lib`) to skip
+  classification.
 - `/thatch/compact` and `/thatch/exit` — the wrap-up commands. They run a
   pre-flight checklist (flush extraction, finish promised memory writes,
   surface loose ends) before a compaction or an exit, gated by a greenlight
@@ -31,6 +38,7 @@ or you invoke it.
 | `/thatch/extract` | yes | no | no |
 | `/thatch/hygiene` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/reflect` | yes | yes | yes (as an MCP prompt) |
+| `/thatch/refine` | yes | yes | yes (as an MCP prompt) |
 | `/thatch/compact`, `/thatch/exit` | yes | no | no |
 
 Why the gaps: `/thatch/extract` needs the invoking session's ID, which only

package/docs/user/skills.md

@@ -77,6 +77,18 @@ Skills are split into shared (all hosts) and opencode-only:
 | `thatch-coding-workflow` | Plans and executes code changes with a task-list-driven workflow: complexity triage, milestone planning, research before coding, post-coding verification. Pairs with `thatch-code-archaeology` (research first, then plan). |
 | `thatch-plan-refinement` | Refines a plan before it is implemented: a fresh-context reviewer subagent re-checks the plan each round until consensus; deep mode adds specialist lenses (reuse, alternatives, hidden problems, safe-to-modify, intent archaeology). |
 
+### Plan refinement skills
+
+| Skill | Purpose |
+|-------|---------|
+| `thatch-refine` | Classifies the project (audience, lifecycle, surface) and refines a plan under that type's requirements. The entry point for the `thatch-refine-*` family; also the `/thatch/refine` command. |
+| `thatch-refine-team-app` | Team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate. |
+| `thatch-refine-personal` | Solo projects: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest. |
+| `thatch-refine-shared-lib` | Library API surfaces: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable. |
+| `thatch-refine-spike` | Throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on. |
+| `thatch-refine-infra` | CI, Terraform, and k8s changes: blast radius, mandatory rollback plan and staged verification, pattern-following is near-absolute. |
+| `thatch-refine-oss-contribution` | PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work. |
+
 ## Stale skill cleanup
 
 When skills are renamed or removed in a new release, thatch automatically

package/package.json

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

package/src/commands.ts

@@ -100,6 +100,16 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
       description: "Tend the memory store: stale entries, orphans, pending dedup pairs",
       body: hygieneCore(),
     },
+    {
+      name: "refine",
+      description: "Refine a plan under the project type's requirements (classifies the project first)",
+      // A skill trigger, not a nudge behavior: the body points at the
+      // thatch-refine router skill, which classifies the project and loads
+      // the matching type deltas on top of the plan-refinement core loop.
+      body: `Load and follow the thatch-refine skill to refine a plan for the current project.
+
+The user message may name a project type (team-app, personal, shared-lib, spike, infra, oss-contribution); if it does, skip classification and use that type. If no plan is drafted yet in this session, the skill's loop starts with drafting one.`,
+    },
     {
       name: "reflect",
       description: "Persist what this session learned as memories",
@@ -108,10 +118,20 @@ After dispatching, call thatch_extraction_done to acknowledge.`,
   ];
 }
 
+/**
+ * Renders a YAML double-quoted scalar. Plain scalars break on values
+ * containing ": " (invalid YAML - the mapping key would be ambiguous), and
+ * opencode's lenient fallback parser does not rescue every host path, so the
+ * description must always be quoted.
+ */
+function yamlQuote(value: string): string {
+  return JSON.stringify(value);
+}
+
 /** Renders one action as a full command markdown file. */
 export function renderActionCommand(action: ActionDef): string {
   return `---
-description: ${action.description}
+description: ${yamlQuote(action.description)}
 ---
 ${userMessageSection}
 
@@ -121,7 +141,7 @@ ${action.body}`;
 }
 
 const COMPACT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then compact if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then compact if clear")}
 ---
 ${userMessageSection}
 
@@ -138,7 +158,7 @@ ${COMPACT_READY_TOKEN}
 If anything is outstanding, list the items concisely so the user can address them, and do NOT include the token. The session will only be compacted when the token is present.`;
 
 const EXIT_TEMPLATE = `---
-description: Flush thatch persistence, check for loose ends, then exit opencode if clear
+description: ${yamlQuote("Flush thatch persistence, check for loose ends, then exit opencode if clear")}
 ---
 ${userMessageSection}
 

package/src/prompts.ts

@@ -192,6 +192,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 - \`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-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`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.
@@ -506,6 +513,13 @@ workflows. The host auto-discovers them, but reach for them proactively:
 
 - \`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-plan-refinement\` - refine a plan before implementing it: fresh-context reviewer rounds until consensus, with an optional deep-mode lens fan-out (reuse, alternatives, hidden problems, safe-to-modify, archaeology). Use when a plan for a code change is about to be built or the user asks to stress-test a plan.
+- \`thatch-refine\` - classify the project (audience, lifecycle, surface) and refine a plan under that type's requirements: team codebases owe coordination and intent breadcrumbs, personal projects allow cleverness, shared libraries owe API hygiene. Entry point for the thatch-refine-* family; also the /thatch/refine command.
+- \`thatch-refine-team-app\` - refinement deltas for multi-developer team codebases: consistency outranks cleverness, intent breadcrumbs are deliverables, pre-mortem and safe-to-modify lenses dominate.
+- \`thatch-refine-personal\` - refinement deltas for solo projects with no downstream consumers: relaxed coordination, cleverness and experimentation welcome, premise verification stays honest.
+- \`thatch-refine-shared-lib\` - refinement deltas for changes touching a library's API surface: flexible on input, strict on output, keep special cases out of the API, never foreclose caller options, docs are a deliverable.
+- \`thatch-refine-spike\` - refinement deltas for throwaway prototypes: skip the loop, verify only the premises the experiment's conclusion depends on, state the question and the time box.
+- \`thatch-refine-infra\` - refinement deltas for CI, Terraform, and k8s changes: blast radius across pipelines and environments, rollback plan and staged verification are mandatory, pattern-following is near-absolute.
+- \`thatch-refine-oss-contribution\` - refinement deltas for PRs to repos you do not maintain: the maintainer's design authority governs, minimal diff, upstream discussion gates significant design work.
 - \`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.

package/src/runtime.ts

@@ -1480,6 +1480,16 @@ export async function createRuntime(input: {
       // requeue here so they are honestly re-extracted instead of lingering
       // as silent loss.
       extraction.requeueStaleAccepted();
+      // Nudges skip injected prompts. A background-task completion, chat
+      // notification, or watcher notification arrives as a prompt whose
+      // parts are all synthetic - it is not user input, and nudging on it
+      // feeds the pipeline its own exhaust: an extractor sub-agent's
+      // completion would otherwise fire a fresh extraction nudge for the
+      // entries the handling turn itself queued (the circular-nudge
+      // pattern). Real user messages carry at least one non-synthetic
+      // part, and an empty-parts message keeps nudging (unchanged
+      // behavior).
+      if (output.parts.length > 0 && (output.parts as any[]).every((p) => p.synthetic)) return;
       // Task-dispatched sub-agent sessions may have restricted tool lists
       // that exclude the thatch tools, and even where the tools exist the
       // child is driven by its dispatch prompt, so nudges only burn "No

package/src/skills.ts

@@ -71,6 +71,13 @@ function loadSharedSkills(): SkillDef[] {
     "thatch-session-reflection",
     "thatch-coding-workflow",
     "thatch-plan-refinement",
+    "thatch-refine",
+    "thatch-refine-team-app",
+    "thatch-refine-personal",
+    "thatch-refine-shared-lib",
+    "thatch-refine-spike",
+    "thatch-refine-infra",
+    "thatch-refine-oss-contribution",
     "thatch-pr-description",
     "thatch-ticket-description",
     "thatch-split-overlarge-pr",