@jeffober/thatch 0.1.26 → 0.1.27

package/docs/dev/skills.md

@@ -4,6 +4,13 @@ Thatch installs SKILL.md files that give the agent task-specific workflows. All
 skill content lives in `artifacts/skills/*.md` and is loaded by `src/skills.ts` and installed to a host-specific
 directory. See `mcp-parity.md` for which skills each host gets.
 
+## Naming convention
+
+All plugin skills use the `thatch-` prefix. This brands them as part of the
+thatch plugin and makes them easy to identify in the skills directory. The
+`cleanupStaleSkills` function uses this prefix as its namespace: any
+`thatch-*` directory not in the current install set is deleted on install.
+
 ## Skill file format
 
 Each skill is a single `SKILL.md` with YAML frontmatter:
@@ -21,9 +28,9 @@ description: Extract durable project facts ... Use when ...
 - `description` drives when the agent loads the skill (both opencode and
   Cursor auto-discover skills and use the description for relevance).
 
-## The 21 skills
+## The 23 skills
 
-**Shared (20)** — installed everywhere; no sub-agents required:
+**Shared (22)** — installed everywhere; no sub-agents required:
 
 | Skill | Role |
 |-------|------|
@@ -39,14 +46,16 @@ description: Extract durable project facts ... Use when ...
 | `thatch-review-highlights` | Positive finding detection: notably clever solutions, cleanup done along the way, documentation that helps. Medium-high bar against generic praise. |
 | `thatch-review-synthesizer` | Verify specialist findings against code, dedupe, classify, calibrate severity. Starts the final report with a workflow-change preface, then cross-references findings against prior review comments when a follow-up round register is provided. |
 | `thatch-review-context` | Gather project/feature context (PR descriptions, git archaeology, ticket references, memory) before fan-out. Prevents false positives about intentionally deferred work. Also fetches prior review comments on a connected PR/MR for follow-up-round detection and builds a register with preliminary addressed-check status per comment. |
-| `thatch-workflow-research` | Research code workflows/features affected by a change or planned change. Reads code flows, comments, git history, memories, docs. Produces a guide to the code for reviewers or planners. |
+| `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, skeletons) before proposing changes. The research skill; pair with `thatch-coding-workflow`. |
 | `thatch-review-followup` | Alternate entrypoint for follow-up review rounds. Verifies whether the author's responses and code changes since your last review round adequately addressed your prior findings, offers to reply on resolved items, then optionally re-runs the full structured review. |
 | `thatch-change-walkthrough` | Explain a change to the user as a teaching walkthrough: resolve the delta, research each affected workflow at the merge-base, teach current behavior, then overlay the modifications with file:line citations and analogies. |
 | `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). |
-| `pr-description` | Draft PR descriptions with SYNOPSIS / PURPOSE / DESCRIPTION / WALK-THROUGH / NOTES, project-context research, clarity checks, and bold+italic emphasis for scanning. |
-| `ticket-description` | Draft ticket/issue descriptions with clear sections, project-context research, clarity checks, and bold+italic emphasis for scanning. |
-| `split-overlarge-pr` | Split already-completed work from an overlarge PR into human-reviewable, release-safe PRs targeting main. |
+| `thatch-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-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. |
+| `thatch-review-response` | Author-side review response: triage findings, fix bugs one by one, reply on each thread, post a top-level summary comment. |
 
 **opencode-only (1)** — the coordinator needs sub-agent support:
 
@@ -71,7 +80,7 @@ The six problem-finding review specialists share a framework interpolated via `$
   coordinator or from loading `thatch-review-context`), use it to avoid false
   positives about intentionally deferred work.
 - **Workflow context awareness** — if a workflow guide is provided (from the
-  coordinator or from loading `thatch-workflow-research`), use it to understand
+  coordinator or from loading `thatch-code-archaeology`), use it to understand
   the purpose and evolution of the code, distinguishing intentional behavior
   and long-standing design decisions from new issues.
 - **TODO ($ticket) markers** — recognize `TODO ($TICKET-ID): ...` as legitimate
@@ -86,7 +95,7 @@ The synthesizer reuses the same verification rigor but has its own structure
 ## The two arrays
 
 ```ts
-const SHARED_SKILLS: SkillDef[] = [ /* 20 skills above */ ];
+const SHARED_SKILLS: SkillDef[] = [ /* 21 skills above */ ];
 const OPENCODE_ONLY_SKILLS: SkillDef[] = [ /* code-review coordinator */ ];
 ```
 
@@ -104,8 +113,14 @@ and `--cursor` pass only the shared set.
 - **Drift detection**: `installSkills` only writes when the on-disk content
   differs from the definition. This is how skill improvements ship with new
   versions without users manually deleting files.
+- **Stale cleanup**: before installing, `installSkills` removes stale skill
+  directories. Any `thatch-*` directory not in the current install set is
+  deleted (the `thatch-` prefix is our namespace). Three skills renamed from
+  non-prefixed to `thatch-`-prefixed in v0.1.27 (pr-description, ticket-description,
+  split-overlarge-pr) are also cleaned up through v0.1.35; after that, those
+  names are fair game for third parties and the cleanup stops.
 - **Idempotent**: re-running init or setup overwrites drifted content but leaves
-  unrelated skill files alone.
+  unrelated (non-`thatch-*`) skill files alone.
 
 ## Adding a skill
 
@@ -124,6 +139,11 @@ and `--cursor` pass only the shared set.
   has responded or pushed changes after your initial review. It verifies whether
   your prior findings were adequately addressed, offers to reply on resolved
   items, then optionally hands off to `thatch-code-review` for a fresh round.
+- **Author-side review response**: load `thatch-review-response` when responding
+  to review comments on your own PR. It triages findings, collapses comments
+  sharing a root cause, fixes bugs one by one with the user, drafts per-thread
+  replies, and posts a top-level summary comment. Works on all hosts (no
+  sub-agents required).
 
 The coordinator is the only skill that can't be used without sub-agents; that's
 why it lives in `OPENCODE_ONLY_SKILLS`.

package/docs/plans/README.md

@@ -4,13 +4,16 @@ Numbered plan documents capture design decisions that span multiple sessions.
 Each plan is a snapshot of the reasoning at the time — subsequent plans may
 supersede earlier ones as the project evolves.
 
-## Active plans
+Plans are temporary. When a plan is fully implemented, it **graduates**:
 
-| Plan | Description |
-|------|-------------|
-| [001 — Memory Store](001-memory-store.md) | Initial memory feature: stores, embeddings, tools |
-| [002 — Agent-Driven Pipelines](002-agent-driven-pipelines.md) | Extraction/dedup through the agent; hook wiring specifics; supersedes 001's "no CLI" |
-| [003 — Memory Hygiene](003-memory-hygiene.md) | Write-time collision warning, recall telemetry, session heartbeat, cluster dedup |
+1. The plan file is removed from this folder.
+2. The final architecture is documented in `docs/dev/` — either updated into
+   existing dev docs or captured in a new one.
+3. End-to-end use-case scenarios are added to `docs/qa/use-cases/`.
+
+Once graduated, the dev docs and use-case docs are the permanent record. The
+plan file is no longer needed — git history preserves it if someone needs the
+original design reasoning.
 
 ## Plan format
 

package/docs/plans/intuition-drives.md

@@ -0,0 +1,147 @@
+# Intuition Drives
+
+## Synopsis
+
+A pre-response deliberation layer that runs on the first message of a new
+opencode session: perception classifies the prompt, parallel drive sub-agents
+react from their motivational lenses, and a synthesis pass distills them into a
+directive injected into the main agent's context. opencode-only; requires
+parallel sub-agent dispatch via Task.
+
+## Background
+
+Fnord runs as a CLI escript where every user invocation carries significant
+intent because it requires a full command-line invocation. Its coordinator runs
+an "intuition" step before responding: a perception pass classifies the prompt,
+ten parallel "drives" (curiosity, skepticism, optimization, modularity,
+convention, laziness, empathy, standing, pragmatism, stewardship) each react
+from their lens, and a synthesis pass distills them into a directive injected
+into the conscious agent's context.
+
+In opencode's chat TUI, user messages have far less friction. Running the full
+intuition pipeline on every message would burn tokens on "ok" and "yes." This
+feature is gated to the first message of a new session only.
+
+## Session detection
+
+This feature depends on knowing "is this the first message of a new session."
+The opencode plugin hook surface provides this:
+
+- `session.created` fires ONLY when a brand-new session object is constructed
+  (fresh creation or fork). It does NOT fire when a user resumes or continues an
+  existing conversation (`--continue`/`--session` without `--fork` reuses the
+  existing session ID).
+- `chat.message` fires on every incoming user message but carries no turn
+  number or first-message flag in its input or output.
+
+Detection mechanism:
+1. Track `session.created` events for top-level sessions (no `parentID`) in a
+   `Set<string>`.
+2. First `chat.message` for a session ID in that set = first message. Remove
+   from set, trigger the feature.
+3. Continued/resumed conversations never fire `session.created`, so they are
+   never in the set. Second messages also don't trigger (already removed).
+
+Edge cases:
+- `--fork` fires `session.created` (correct: a fork is a new conversation).
+- Plugin not running when the session was created (e.g., `--continue` of a
+  session from a prior run): no `session.created`, no trigger (correct: it is a
+  continued conversation, not new).
+- Child sessions (sub-agents) fire `session.created` with a `parentID` —
+  filtered out by the `parentID` check.
+
+## What it does
+
+On the first message of a new session, before the main agent responds, a
+deliberation layer runs:
+
+1. **Perception** — classify the prompt (interface, codebase, correction,
+   continuation, meta, ambiguous) and produce a short first-person interpretation.
+2. **Drive reactions** — parallel sub-agents, each arguing from a specific
+   motivational lens. Drives are the same as fnord's: curiosity, skepticism,
+   optimization, modularity, convention, laziness, empathy, standing, pragmatism,
+   stewardship.
+3. **Synthesis** — distill the drive reactions into a single directive injected
+   into the main agent's context.
+
+## Why port it
+
+No existing skill does pre-response deliberation. The drives carry real
+personality and map to Jeff's stance (stewardship = "correctness over comfort";
+skepticism = "no reassurance without verification"). The parallel sub-agent
+dispatch is natural for opencode's Task tool.
+
+## Constraints
+
+- **opencode-only.** Requires parallel sub-agent dispatch via Task. Claude Code
+  agents running skills cannot spawn sub-agents.
+- **First-message-only.** Gated by the session-detection mechanism above.
+  Running on every message would burn tokens on trivial follow-ups.
+- **Prompt injection, not a tool.** The synthesis output is injected as a
+  synthetic text part into the first `chat.message`, like the recall nudge. The
+  main agent sees it as context, not as a tool result.
+- **No pre-response hook exists.** The synthesis must complete inside the
+  `chat.message` hook (before the LLM loop runs) or be injected as a system
+  message via `experimental.chat.system.transform`. The hook fires before the
+  message is persisted and before the LLM loop starts, so a synchronous
+  sub-agent dispatch inside `chat.message` would block the turn. The
+  `experimental.chat.system.transform` hook is a better injection point because
+  it runs on every turn and can append to the system prompt — but it does not
+  have access to the user's message text. A hybrid: compute the synthesis in
+  `chat.message` (which has the prompt text), cache it in a per-session map, and
+  inject it in `experimental.chat.system.transform` on the same turn.
+
+## Open questions
+
+1. **Latency.** Ten parallel sub-agent calls add latency to the first turn. Is
+   the value worth it? Options: reduce to 3-4 drives, run drives with a fast
+   model, or make it opt-in.
+2. **Injection point.** The `chat.message` hook fires before the LLM loop but
+   injecting a synthetic part there adds it to the user message, not the system
+   prompt. `experimental.chat.system.transform` can append to the system prompt
+   but fires on every turn and lacks the user message text. The hybrid
+   (compute-in-chat.message, inject-in-system.transform) requires a per-session
+   cache with one-turn TTL.
+3. **Drive selection.** Fnord runs all 10 drives. A smaller set (stewardship,
+   skepticism, pragmatism, empathy) might capture 80% of the value at 40% of the
+   cost.
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| opencode-only | Requires parallel sub-agent dispatch via Task |
+| First-message-only | Chat TUI has low message friction; running on every message wastes tokens |
+| Detection via session.created + chat.message | session.created fires only on new sessions; chat.message provides the first-message trigger |
+| Parallel drives via Task sub-agents | Matches fnord's architecture; drives are independent and parallelizable |
+| Injection via system.transform with chat.message cache | chat.message has the prompt text; system.transform can append to the system prompt; hybrid avoids blocking the turn |
+
+## Architecture
+
+```
+session.created (top-level, no parentID)
+  → add sessionID to newSessions Set
+
+chat.message (first message for sessionID in newSessions)
+  → remove from newSessions
+  → perception + parallel drives + synthesis → cache in Map<sessionID, directive>
+
+experimental.chat.system.transform
+  → if directive cached: append directive, then clear cache (one-shot)
+
+session.deleted
+  → delete from directive cache, newSessions set
+```
+
+## Dependencies
+
+### Runtime
+
+- Fast model for perception and drive reactions (parallel sub-agents)
+- Task tool for parallel drive dispatch (opencode sub-agent support)
+
+### Built-in
+
+- Plugin hooks: `event` (session.created, session.deleted),
+  `chat.message`, `experimental.chat.system.transform`
+- In-process `Map` for per-session caching (directive, newSessions set)

package/docs/plans/nomenclater.md

@@ -0,0 +1,89 @@
+# Nomenclater
+
+## Synopsis
+
+Assigns a geeky/sci-fi name to the agent at the start of each new opencode
+session. The name is generated by a fast LLM call, cached for the session, and
+injected into the system prompt so the agent knows its name. opencode-only;
+requires plugin hooks. Pure cosmetic, no functional dependency.
+
+## Background
+
+Fnord's Nomenclater (backed by a GenServer name pool) generates whimsical names
+for sub-agents so their actions are distinguishable in logs. Jeff explicitly
+wants this for thatch: "I'd love to have this!" It builds agent identity and
+rapport, complementing the personality instructions in OPENCODE.md.
+
+The name must not change mid-conversation and must not trigger on continued
+or resumed sessions.
+
+## Session detection
+
+Same mechanism as the intuition-drives plan. See that plan for full detail.
+
+`session.created` fires only on brand-new session creation (fresh or fork). It
+does not fire when resuming an existing conversation. Detection: track
+`session.created` for top-level sessions (no `parentID`) in a `Set<string>`,
+generate the name on first `chat.message` for sessions in that set, remove
+from set after generating. Continued/resumed sessions never enter the set.
+
+## What it does
+
+```
+session.created (top-level) → add sessionID to newSessions Set
+
+chat.message (first message for sessionID in newSessions)
+  → remove from newSessions
+  → generate name via fast model → cache in Map<sessionID, name>
+
+experimental.chat.system.transform
+  → if name cached for sessionID: append "Your name for this session is <name>."
+
+session.deleted
+  → delete from name cache, newSessions set
+```
+
+Name generation uses fnord's theme list (Jargon File, Zork, Futurama,
+Discworld, D&D, Klingons, Sandman, etc.) and the same JSON-schema response
+format. One LLM call with a fast model. Themes are shuffled and 3 are selected
+per batch to avoid clustering.
+
+## Constraints
+
+- **opencode-only.** Requires plugin hook injection. The name is generated by a
+  fast LLM call and injected via `experimental.chat.system.transform`.
+- **First-message-only.** Same session-detection mechanism. The name must not
+  change mid-conversation.
+- **No persistent state needed.** The name is generated fresh per session and
+  held in a per-session map for the duration of that session. No DB writes.
+- **Must not trigger on continued sessions.** A resumed conversation keeps
+  whatever name the agent had (or had none, if the feature was added after the
+  session started). The `session.created` gate handles this.
+
+## Open question
+
+1. **Where does the name surface?** System prompt injection means the agent
+   knows its name but the user only sees it if the agent chooses to use it. Is
+   that enough, or should the name appear in the TUI somehow (e.g., a toast on
+   session start)?
+
+## Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| opencode-only | Requires plugin hooks for generation and injection |
+| One name per session, cached in memory | No DB writes; name is ephemeral, tied to session lifecycle |
+| Gated to first message of new sessions | Must not rename mid-conversation or trigger on resumed sessions |
+| Detection via session.created + chat.message | Same mechanism as the intuition-drives plan |
+
+## Dependencies
+
+### Runtime
+
+- Fast model for name generation (one LLM call per new session)
+
+### Built-in
+
+- Plugin hooks: `event` (session.created, session.deleted),
+  `chat.message`, `experimental.chat.system.transform`
+- In-process `Map` for per-session name caching