opencode-thrum-pro 0.1.0

package/assets/skills/researcher-answering-queries/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: researcher-answering-queries
+description: "Use when another agent has asked you a research question, when fielding a research request, or when responding to a query. Loads the lookup-and-respond protocol so cached findings get reused before fresh investigation starts."
+---
+
+# Researcher: Answering Queries
+
+## Reconcile your queue first
+
+Lift this query into a bundle (`thrum queue add --from-message <msg-id>`),
+then `thrum queue start <bundle-id>`; drop/close finished bundles. Full
+lifecycle: `using-the-queue`.
+
+## Lookup order: index → thrum memory → staleness check → respond
+
+**Why:** A query that's already been answered shouldn't trigger a fresh
+investigation. The cached `research_note` entries (tagged `research-<slug>`)
+exist precisely so repeat questions resolve cheaply. Skipping the cache and
+re-investigating duplicates effort, burns context, and introduces drift between
+the cached entry and the new answer.
+
+**How to apply:** When a query lands, work the steps in order:
+
+1. **Index check.** Read `.thrum/context/research.md`. Does any Tracked Topic
+   line look relevant? Note the `research-<slug>` tag handles.
+2. **Content fetch.** For each candidate slug, escalate zoom per the shared
+   3-step read pattern (`memory-read-discipline`): `thrum memory search --tag
+   research-<slug>` returns the matching entry IDs; triage with
+   `thrum memory show <id> --zoom short` before fetching the full body with
+   `thrum memory show <id> --zoom full`.
+3. **Staleness check.** Use the protocol from `researcher-maintaining-memory`:
+   `git diff --name-only <stamp-sha> HEAD` filtered by the entry's cited paths.
+   If empty, the entry stands. If any cited path appears, re-verify (re-read the
+   cited code, refresh the footer with `Verified: <today> @ <new-sha>`) before
+   responding.
+4. **Respond.** With the certainty level from the section below.
+
+If the index has no relevant entry, the query is fresh-investigation territory —
+invoke the `researcher-investigating` skill's discipline instead.
+
+## Structure responses by certainty level
+
+**Why:** A response that conflates "I just verified this against HEAD" with "I'm
+pulling this from a stale cached entry" misleads the requester into trusting
+outdated state. Calibrated certainty lets the requester decide whether to act
+now or ask for re-verification.
+
+**How to apply:** Three response shapes:
+
+- **Verified now.** "<answer>. Verified at HEAD `<sha>`: <evidence>." Use after
+  a fresh investigation or a successful staleness re-verify.
+- **Cached + stamp.** "<answer>. Cached entry `research-<slug>`, Verified
+  `<date>` @ `<stamp-sha>`. Cited paths unchanged in
+  `git diff <stamp-sha>..HEAD`." Use when the staleness check returns empty.
+- **Unknown / partial.** "I don't have a verified answer for X. The closest
+  cached entry is `research-<slug>` (last verified <date>) but it doesn't fully
+  cover the question. Want me to investigate?" Use when no entry covers the
+  question, or the cached entry only partially addresses it.
+
+Don't fudge by saying "Yes" without a level qualifier. The qualifier costs five
+words; the cost of silently propagating stale state is real.
+
+## Point at the slug for follow-up — don't dump the whole entry inline
+
+**Why:** A long cached entry quoted inline burns tokens and clutters the
+requester's context. The slug is the durable handle; the requester can
+`thrum memory search --tag research-<slug>` + `thrum memory show <id>`
+themselves if they want the full body.
+
+**How to apply:** In the response, cite the slug (`research-<slug>`) and a
+one-paragraph summary (or the specific sub-fact the requester asked for). If the
+requester needs more, they fetch via `thrum memory search --tag research-<slug>`
+→ `thrum memory show <id>`. Reserve full quotes for short entries (<5 lines)
+where inlining is genuinely cheaper than the round-trip.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `researcher-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.
+
+## Pattern D self-write — set `agent_status=idle` on response/DONE
+
+When reporting a research finding back to the requester (or closing a DONE on a
+research task), write `agent_status="idle"` to your local identity file. This
+closes the `working→idle` transition opened by the ACK protocol in the sibling
+skill `researcher-investigating`.
+
+```bash
+# Step 1: Report finding back to requester
+thrum send --to @<requester> --stdin <<'EOF'
+Research <task-id>: <finding>. Evidence: <file:line refs>.
+EOF
+
+# Step 2: Mark yourself idle (RPC-preferred; local-write fallback if daemon is unreachable)
+thrum agent set-status idle
+```

package/assets/skills/researcher-investigating/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: researcher-investigating
+description: "Use when investigating, exploring code, working on a research task, when asked to find me X, or to investigate Y. Loads researcher-specific discipline for running an investigation cleanly."
+---
+
+# Researcher: Investigating
+
+## Reconcile your queue first
+
+Lift this query into a bundle (`thrum queue add --from-message <msg-id>`),
+then `thrum queue start <bundle-id>`; drop/close finished bundles. Full
+lifecycle: `using-the-queue`.
+
+## Use Explore sub-agents for breadth-first searches
+
+**Why:** Reading 10 files into your main context to "understand the
+architecture" is the Context Hog trap. Sub-agents partition the search across
+multiple conversations that each report a focused finding back — the
+investigation gets done without polluting your context with raw file contents.
+
+**How to apply:** When the question is "how does X work" or "what calls Y",
+spawn an `Explore` sub-agent with a clear partition: a specific directory, a
+specific symbol, or a specific question. Get a focused report back. For research
+across N > 6 items, invoke `efficient-multi-agent-research` instead of bespoke
+dispatch — it handles partition + parallelization + consolidation.
+
+> **Model tiers:** pass an explicit `model:` on every dispatch — `sonnet`
+> (low effort) mechanical, `sonnet` (medium effort) judgment, Opus only on
+> operator-ask or a skill step that names it. See the
+> `choosing-subagent-models` skill for the full policy.
+
+### Prefer `efficient-multi-agent-research` for multi-part research
+
+When a research or investigation task has independent parts, reach for the
+`efficient-multi-agent-research` skill FIRST — it partitions the work across
+many cheap parallel subagents (sonnet-low gatherers, sonnet-medium synthesizers) instead of
+one expensive serial subagent. It is the preferred research path: cheaper,
+faster, and it keeps each subagent's context tight.
+
+## Verify the actual state — don't answer from recall
+
+**Why:** Reporting from memory of past panes, files, or commits produces
+over-claimed findings. The preamble carries the invariant; this rule carries the
+operational depth — the specific commands to run before trusting any state
+claim.
+
+**How to apply:**
+
+- **Pane state.** Run `tmux capture-pane -p -t <pane>` (or the runtime
+  equivalent) before reporting "the pane shows X" / "the prompt fired".
+- **Code state.** Use the Read tool or `git show HEAD:<path>` before reporting
+  "function Y is at line Z" or "file X handles case W".
+- **Beads state.** Run `bd show <id>` before reporting "task is in_progress" /
+  "issue is closed" — your remembered idea of the state may be stale.
+
+If you can't verify, say so explicitly: "I believe X based on <evidence>; I have
+not verified Y."
+
+## Scope queries before deep-diving — return early when unclear
+
+**Why:** A vague request ("investigate the auth flow") burns hours investigating
+dimensions the requester didn't actually care about. Returning early with a
+clarifying question is faster overall — even if it adds five minutes of
+round-trip latency, it prevents three hours of wrong-direction work.
+
+**How to apply:** Read the dispatch and the linked spec/plan first. If the scope
+is ambiguous (multiple plausible interpretations, contradictory documents, no
+clear acceptance signal), reply with NEEDS_CONTEXT and one specific narrowing
+question. Don't guess. Don't investigate "what they probably meant" in parallel.
+
+## Persist findings via `thrum memory create` with a verification footer
+
+**Why:** A finding sent only as a Thrum message is ephemeral — the coordinator
+may acknowledge and move on, and the next session has to re-investigate.
+Persisting as a `research_note` memory makes findings recoverable across
+sessions and re-readable by other agents.
+
+**How to apply:** After reporting to the requester, write the finding as a
+`research_note` memory with cited file:line refs and a verification footer. Tag
+with a `research-<slug>` handle so other agents can find it later via
+`thrum memory search --tag research-<slug>`:
+
+```bash
+cat > /tmp/research-note-body.md <<EOF
+<prose explanation with cited file:line refs>
+
+Verified: $(date +%Y-%m-%d) @ $(git rev-parse HEAD)
+EOF
+thrum memory create --kind research_note --scope role \
+  --title "<finding prose, ~80 char soft limit>" \
+  --tag research-<slug> \
+  --oneline "<one-line summary>" \
+  --full "@/tmp/research-note-body.md"
+```
+
+`--full` here is multi-line prose — compose via heredoc or a captured
+variable, never double-quoted inline like this; see your role preamble's 🔴
+PROSE INTO A COMMAND rule.
+
+Then add one line to `.thrum/context/research.md` under Tracked Topics (note: `thrum queue` now supersedes free-text Open Questions tracking):
+
+```markdown
+- `research-<slug>` — <one-line description, ≤ 80 chars>
+```
+
+The full index format and staleness-check protocol live in
+`researcher-maintaining-memory`.
+
+## Never implement findings — return them to the requester
+
+**Why:** Your job ends when you have a finding. Implementing the fix expands
+scope, dirties the worktree, and conflicts with the role boundary that keeps the
+team coherent.
+
+**How to apply:** When investigation surfaces a bug:
+
+1. Reproduce + cite the file:line evidence
+2. File a beads issue with title, description, repro steps
+3. Send a one-paragraph summary to the coordinator with the bd ID
+4. Stop. Do not write the fix unless the coordinator explicitly asks.
+
+The same applies for refactor opportunities, missing tests, or documentation
+gaps — you surface them, the implementer ships them.
+
+## Project-specific rules (already loaded)
+
+Read the shared partial at the absolute path:
+`claude-plugin/commands/_project-rules-protocol.md`
+
+If you accumulate a new rule mid-session (the user corrects you), capture it via
+the `researcher-maintaining-memory` skill — it references the
+`memory-write-discipline` common for the canonical `thrum memory create` shape.
+
+## Pattern D self-write — set `agent_status=working` on dispatch ACK
+
+Immediately after sending the dispatch ACK for a research request, write
+`agent_status="working"` to your local identity file. This is the same Pattern D
+self-write used by the implementer's dispatch-ACK protocol (sibling skill
+`implementer-receiving-dispatch`).
+
+```bash
+# Step 1: ACK within 2 minutes of receiving a research dispatch
+thrum reply <MSG_ID> --stdin <<'EOF'
+Received. Starting <scope>. ETA <rough>.
+EOF
+
+# Step 2: Mark yourself working (RPC-preferred; local-write fallback if daemon is unreachable)
+thrum agent set-status working
+```
+
+The companion `set-status idle` call lives in `researcher-answering-queries` for
+the response/DONE side.

package/assets/skills/researcher-maintaining-memory/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: researcher-maintaining-memory
+description: "Use after completing research, when updating research memory, when verifying entries, or when working with the research index. Loads researcher-specific discipline — the index file structure, cite-stamp protocol, staleness check via git diff, namespace conventions. References common memory skills for write/read/maintain basics."
+---
+
+# Researcher memory discipline
+
+You are the researcher. You write research findings, role-rules, and curate the
+project-local research index. Common memory operations (write command shape,
+body conventions, lookup patterns, edit/delete protocol) live in the common
+memory skills — invoke them when you need the basics. THIS skill carries
+researcher-specific extensions only.
+
+## When to invoke the commons
+
+| Situation                                                                         | Skill to invoke           |
+| --------------------------------------------------------------------------------- | ------------------------- |
+| Drafting a new research note or role-rule                                         | `memory-write-discipline` |
+| Loading role-rules at session start, finding a topic, looking up a specific entry | `memory-read-discipline`  |
+| Editing, deleting, or superseding an entry; reviewing history                     | `memory-maintenance`      |
+
+## The research index file
+
+You curate **one hand-written artifact**: `.thrum/context/research.md` — a thin
+index over the topics + open questions in this repo's research landscape.
+
+**Canonical sections (required minimum):**
+
+### Repo Map
+
+Your mental model of code-area boundaries — which packages do what, which files
+are gateways into a subsystem, which conventions live where. This is researcher
+synthesis that does NOT fit a memory-entry shape.
+
+Example:
+
+```text
+- internal/daemon/        — daemon server (RPC handlers, websocket, unix socket)
+- internal/daemon/rpc/    — RPC handler files (one per logical surface)
+- internal/sync/          — Tailscale-based sync across clones
+- internal/memory/        — v0.11 memory substrate (model, projection, embed)
+- ui/packages/web-app/    — React SPA (single page; routing in components/)
+```
+
+### Open Questions
+
+> `thrum queue` now supersedes this free-text list for tracking open investigation threads — keep entries here only for historical context.
+
+Researcher TODOs / things-to-investigate that haven't been resolved into
+findings yet. Each line ≤120 chars; cite a file area or epic if relevant.
+
+Example:
+
+```text
+- Is the embedding adapter wired post-<epic>? (check internal/memory/embed/adapter_ollama.go)
+- thrum-abc monitor reliability follow-up still has 4 child bugs open
+- Open: does --scope role on memory.create auto-infer the role, or does it require explicit value?
+```
+
+**Researcher-extensible sections (optional):** Beyond Repo Map + Open Questions,
+you may add other sections that fit your workflow — e.g., a "Pending
+Verifications" list, a "Cross-Repo Notes" section, a debugging-log scratchpad.
+Frame the file as YOUR working artifact; don't constrain it to a fixed schema.
+
+**What does NOT belong in the index:** A "Tracked Topics" mirror of memory
+entries. The CLI owns enumeration:
+
+```bash
+thrum memory list --kind research_note --scope role     # the live, drift-free topic list
+```
+
+Use this instead of maintaining a parallel index of research notes in the
+markdown file.
+
+## Verification-stamp footer for research notes
+
+Every research note (`kind: research_note`) ends with a Verified-stamp footer:
+
+```text
+Verified: YYYY-MM-DD @ <commit-sha>
+```
+
+The SHA is `git rev-parse HEAD` at verification time. This stamp enables
+structural staleness review (next section).
+
+When authoring a new research note via `thrum memory create`, include the stamp
+at the bottom of `--full` body content. When re-verifying an existing note, edit
+the entry to update the stamp:
+
+```bash
+cat > /tmp/memory-verify-body.md <<EOF
+<verified body with updated 'Verified: ... @ <new-sha>' footer>
+EOF
+thrum memory edit <id> --full "@/tmp/memory-verify-body.md"
+```
+
+## Staleness check via git diff
+
+For research notes that cite specific files, structural staleness review filters
+the cited paths against changes since the last Verified-stamp. Pulling the note
+follows the shared 3-step zoom escalation (`memory-read-discipline`): triage
+short before paying for the full body.
+
+```bash
+# 1/2. Triage — confirm this is the right entry before pulling full content
+thrum memory show <id> --zoom short
+
+# 3. Fetch full body only once confirmed
+thrum memory show <id> --format json --zoom full | jq -r '.body_full' > /tmp/note.txt
+
+# Extract the Verified SHA
+STAMP_SHA=$(grep -oE 'Verified: [0-9]{4}-[0-9]{2}-[0-9]{2} @ ([a-f0-9]+)' /tmp/note.txt | awk '{print $NF}')
+
+# Extract cited paths (rough — depends on how your note cites)
+CITED=$(grep -oE '[a-zA-Z_/-]+\.go|[a-zA-Z_/-]+\.md' /tmp/note.txt | sort -u)
+
+# Diff cited paths since the stamp
+git diff --name-only "$STAMP_SHA" HEAD -- $CITED
+# If any output: paths have changed; re-verify the note before relying on it.
+```
+
+A non-empty diff signals possible staleness. Re-read the note's claims against
+the changed code; either update + re-stamp (the note's claims still hold) or
+amend / supersede the note (the claims have drifted).
+
+## Namespace conventions for research_note entries
+
+When authoring research notes, use `--tag <slug>` where `<slug>` is kebab-case
+keywords describing the topic. The title is free-form prose; the slug-style
+handle lives in tags.
+
+**User captures:** `--tag <slug>` (just the slug; no prefix needed).
+
+**Module installs (forward-compatibility — module tooling is not in v1, but the
+segment is reserved):** `--tag mod-<module-name> --tag <slug>` to avoid
+clobbering user-authored entries with the same slug.
+
+The legacy `research-<slug>` and `research-mod-<module>-<slug>` bd-key
+conventions are retired. Migrated entries carry the original bd-key as title
++ `--tag migrated-from-bd:<bd-key>` as the rollback handle.
+
+## Role-rule writes (researcher-specific)
+
+When the user corrects your behavior mid-session, capture a researcher-rule:
+
+```bash
+cat > /tmp/role-rule-body.md <<'EOF'
+<rule>
+
+Why: <reason>
+How to apply: <when/where>
+EOF
+thrum memory create --kind agent_rule --scope role \
+  --title "<short rule prose>" \
+  --oneline "<rule one-liner>" \
+  --short "@/tmp/role-rule-body.md" \
+  --tag <slug>
+```
+
+`--short`/`--full` carry real prose — compose via heredoc or file, never
+double-quoted inline; see your role preamble's 🔴 PROSE INTO A COMMAND rule.
+
+This is the SAME pattern as coordinator/implementer role-rule writes — see
+`memory-write-discipline` for the canonical shape.
+
+## Removal protocol
+
+To retire a research note:
+
+```bash
+thrum memory delete <id>
+```
+
+(See `memory-maintenance` for hard-purge semantics if needed.) If the deleted
+note had its slug or topic referenced in your `.thrum/context/research.md` Open
+Questions, update that file by hand — the index file is yours to maintain.

package/assets/skills/state-migration/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: state-migration
+description: "Use when your agent-local thrum state is empty AND you have an existing State.md file in your agent directory - this is a ONE-TIME conditional onboarding that fires only on that exact combination. Do NOT use if thrum state already has entries (nothing to migrate) or if you have no State.md (brand-new agent, nothing to migrate). Triggers on: first session after the thrum state redesign lands, `thrum state list` returning empty while State.md exists on disk, being asked to migrate your personal state."
+---
+
+# Migrating personal State.md into `thrum state`
+
+This is a conditional, one-time onboarding — modeled on the philosophy-
+document onboarding pattern. It does nothing if either half of its trigger
+condition is false.
+
+## When this fires
+
+- `thrum state list` returns **empty** for your agent AND
+- a `State.md` file exists in your agent directory (readable via
+  `substrate.read_folder` or a direct file read, per your runtime).
+
+If `thrum state list` already has entries: **stop, nothing to migrate.**
+If no `State.md` exists: **stop, you're a brand-new agent, nothing to
+migrate.**
+
+## What to do
+
+Read your `State.md`. For each of its six canonical sections (Identity,
+Current state, Immediate next actions, Durable / structural facts,
+Personal-relevance memory index, Cold-successor note), write it into the
+`personal_state` kind:
+
+```bash
+thrum state set --kind personal_state --scope self --value '{
+  "identity": "<Identity section content>",
+  "current_state": "<Current state section content>",
+  "next_actions": "<Immediate next actions section content>",
+  "durable_facts": "<Durable / structural facts section content>",
+  "memory_index": "<Personal-relevance memory index section content>",
+  "cold_successor": "<Cold-successor note section content, or omit if empty>"
+}'
+```
+
+Value size is capped at 64KB — this replaces the old 60-line cap; if
+State.md is over cap, trim the same way the old cap's error message
+directed (never trim Durable / structural facts).
+
+After migrating, `State.md` itself is no longer read by anything — leave it
+in place (harmless) or delete it; do not keep updating it, since nothing
+consumes it anymore.
+
+## Do not
+
+- Run this if `thrum state list` already shows a `personal_state` entry —
+  a second run would overwrite (upsert semantics), silently discarding
+  anything written to `thrum state` since the last migration.
+- Bulk-import on behalf of another agent. This is self-driven, scoped to
+  the live agent running the skill.

package/assets/skills/thrum/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: thrum
+description: "Multi-agent coordination via messaging, groups, and shared context. Use when agents need to communicate, delegate work, or coordinate across worktrees."
+allowed-tools: "Bash(thrum:*)"
+version: "0.10.6"
+license: "Apache-2.0"
+---
+
+# Thrum - Git-Backed Multi-Agent Coordination (Messaging, Groups, Shared Context)
+
+Run `thrum prime` for full session context (auto-injected by hooks on
+SessionStart and PreCompact).
+
+## Quick Command Reference
+
+### Messaging
+
+```bash
+thrum send --to @name --body-file msg.md           # Direct message (body from file)
+thrum send --broadcast --body-file msg.md          # Team-wide fanout
+thrum send --to @everyone --body-file msg.md       # Broadcast (legacy keyword; --broadcast preferred)
+thrum reply <msg-id> --body-file reply.md          # Reply (same audience; NO --to — recipient comes from the message)
+thrum inbox                              List messages (auto-marks displayed as read)
+thrum inbox --unread                     Unread only (does not mark as read)
+thrum message search "<term>"            Full-text search — use instead of paging; stale unread sorts last
+thrum sent                               List messages you sent
+thrum sent --unread                      Sent messages with unread recipients
+thrum message read --all                 Mark all messages as read
+thrum wait                               Block until message arrives (30s timeout)
+thrum wait --timeout 120s                Custom timeout (duration)
+```
+
+### Agents
+
+```bash
+thrum quickstart --name <agent-name> --role R --module M --intent "..."   Register + start session
+thrum worktree create <name> --name <agent> --role R --module M    Create worktree + register agent
+                                                                   (then run `thrum tmux launch <name>` to start runtime)
+thrum worktree setup <name> --name <agent> --role R --module M     Alias for worktree create
+thrum whoami                                          Show identity
+thrum team                                            List active agents
+thrum ping @name                                      Check if agent online
+thrum who-has <file>                                  Who's editing a file
+```
+
+### Role Templates
+
+```bash
+thrum roles list                         List templates + matching agents
+thrum roles deploy                       Re-render preambles from templates
+thrum roles deploy --agent foo           Deploy for specific agent
+thrum roles deploy --dry-run             Preview without writing
+```
+
+### Sessions & Context
+
+```bash
+thrum session start                      Start session
+thrum session end                        End session
+thrum session set-intent "..."           Update work description
+thrum context show                       Show saved work context
+thrum context save --file <path>         Save context from file
+thrum overview                           Combined status + team + inbox
+/thrum:update-project                    Guided project state update (narrative + state)
+/thrum:load-context                      Restore work context after compaction
+```
+
+### Tmux Sessions (Recommended)
+
+```bash
+thrum tmux start                     Launch agent session (create+launch+prime+attach)
+thrum tmux status                    Show managed sessions with state
+thrum tmux connect                   Attach to running session (interactive picker)
+thrum tmux restart <name>            Restart session with context snapshot
+thrum tmux kill <name>               Tear down session
+thrum tmux create <session> --name <n> --role <r> --module <m> --cwd <path>   Create + register agent
+thrum tmux quickstart <session> --name <n> --role <r> --module <m> --cwd <path>   Alias for tmux create
+thrum tmux launch <session> [--runtime <r>]   Start runtime in session (REQUIRED after `tmux create`)
+```
+
+### Monitor Jobs
+
+```bash
+thrum monitor add <name> --cmd "..." --on-match "msg"   Add a monitored process
+thrum monitor list                   List all monitor jobs
+thrum monitor show <name>            Show job details and recent matches
+thrum monitor stop <name>            Stop a monitor job
+thrum monitor logs <name>            Tail job output
+thrum monitor restart <name>         Restart a stopped job
+```
+
+### Daemon & Sync
+
+```bash
+thrum daemon start                       Start daemon
+thrum daemon stop                        Stop daemon
+thrum daemon status                      Daemon health
+thrum sync force                         Force immediate sync
+thrum sync status                        Sync state
+```
+
+### Utility
+
+```bash
+thrum init                               Initialize thrum in repo (also starts the daemon)
+thrum prime                              Full session context
+thrum prime --json                       Machine-readable output
+thrum <cmd> --help                       Detailed command usage
+```
+
+## When to Use Thrum
+
+| Thrum                                    | TaskList/SendMessage       | Neither                       |
+| ---------------------------------------- | -------------------------- | ----------------------------- |
+| Cross-worktree messaging                 | Same-session task tracking | Single-agent, no coordination |
+| Persistent messages (survive compaction) | Ephemeral task lists       | Temporary scratch notes       |
+| Background listener pattern              | Inline progress tracking   | Simple linear execution       |
+| Multi-machine sync via git               | Local to conversation      | No persistence needed         |
+
+**Decision test:** "Do messages need to survive session restart or reach agents
+in other worktrees?" YES = Thrum.
+
+**Thrum + TaskList coexist:** Use TaskList for immediate session work. Use Thrum
+for cross-session/cross-worktree coordination messages.
+
+## Message Delivery
+
+### Tmux Sessions (Recommended)
+
+When running in a tmux-managed session, messages are delivered directly to your
+pane via daemon nudge — zero token cost, no background sub-agent needed. See
+[TMUX_SESSIONS.md](resources/TMUX_SESSIONS.md).
+
+### Listener Pattern (Fallback)
+
+When tmux is not available, use the background message listener. It calls
+`thrum wait` (blocking) and returns when messages arrive. Re-arm after
+processing. See [LISTENER_PATTERN.md](resources/LISTENER_PATTERN.md).
+
+### Context Management
+
+- `thrum prime` gathers identity, team, inbox, git context, sync health
+- SessionStart hook auto-runs `thrum prime` on session start
+- PreCompact hook saves state to thrum context + `/tmp` backup before compaction
+- **After compaction:** run `/thrum:load-context` to restore your work context
+- Agent identity persists in `.thrum/identities/`
+
+## Resources
+
+| Resource                                             | Content                                      |
+| ---------------------------------------------------- | -------------------------------------------- |
+| [TMUX_SESSIONS.md](resources/TMUX_SESSIONS.md)       | Tmux-managed session setup and commands      |
+| [BOUNDARIES.md](resources/BOUNDARIES.md)             | Thrum vs TaskList/SendMessage decision guide |
+| [MESSAGING.md](resources/MESSAGING.md)               | Protocol patterns, context management        |
+| [ANTI_PATTERNS.md](resources/ANTI_PATTERNS.md)       | Common mistakes and how to avoid them        |
+| [LISTENER_PATTERN.md](resources/LISTENER_PATTERN.md) | Background message listener template         |
+| [CLI_REFERENCE.md](resources/CLI_REFERENCE.md)       | Complete command syntax reference            |
+| [IDENTITY.md](resources/IDENTITY.md)                 | Agent identity and multi-worktree patterns   |
+| [WORKTREES.md](resources/WORKTREES.md)               | Multi-worktree coordination                  |
+
+Run `thrum <command> --help` for any command's full usage.